> For the complete documentation index, see [llms.txt](https://wiki.4thtech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.4thtech.io/developers/architecture.md).

# Encryptor for app builders

How the Encryptor extension is built: popup, background service worker, storage and permissions.

{% hint style="info" %}
**Status: Production-ready, stable.** Encryptor is supported; no new features are planned. Last update: 18 Apr 2024 (version 0.1.0).
{% endhint %}

Encryptor is a Manifest V3 Chrome extension built with Vue 3, Vite and TypeScript. Key handling uses the ethers library (v6).

## Parts

| Part                                                      | What it does                                                                                                        |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Popup** (`popup.html`, Vue pages)                       | The UI: Welcome, Create, Seeds, Restore, Unlock, Main, Loading. It asks the background for state and sends commands |
| **Background service worker** (`src/background/index.ts`) | Holds the unlocked key in memory, stores the encrypted key, answers apps, emits events                              |
| **Local storage** (`chrome.storage.local`)                | The encrypted key (`encryptedWallet`)                                                                               |

```mermaid
flowchart LR
    Web["Web app"]
    BG["Background service worker"]
    Pop["Popup UI"]
    LS[("chrome.storage.local: encrypted key")]
    Web -- "integration API requests" --> BG
    BG -- "postMessage events via scripting" --> Web
    Pop -- "runtime messages" --> BG
    BG --- LS
```

*Figure: Data flow between a web app, the background worker, the popup and the stored key.*

## Messages

Popup to background (internal): create, unlock, restore, get key object, lock, get state.

Web page to background (external): only these four actions are accepted. Anything else returns "Requested action is not allowed."

| Action                   | Reply                                                            |
| ------------------------ | ---------------------------------------------------------------- |
| `getAppVersion`          | The extension version                                            |
| `getEncryptorState`      | `not-generated`, `locked` or `unlocked`                          |
| `getPublicKey`           | The public key (nothing while locked)                            |
| `computeSharedSecretKey` | A shared secret for a public key you pass (nothing while locked) |

Background to page (events), posted to the active tab as `window.postMessage`:

* `emitHeartbeat`, once at worker start and every 30 seconds.
* `emitEncryptorStateChange`, with the new state, after create, unlock, restore or lock.

## State logic

The background reports `unlocked` if the key is in memory. Otherwise it reports `locked` if an encrypted key exists, or `not-generated` if there is no stored key.

## Permissions

| Permission  | Where it appears                                                  |
| ----------- | ----------------------------------------------------------------- |
| `storage`   | Saves the encrypted key                                           |
| `scripting` | `chrome.scripting.executeScript` posts events into the active tab |
| `activeTab` | Added in 0.0.6 (11 Apr 2024)                                      |

See [Security notes](https://wiki.4thtech.io/developers/architecture/security.md) and the [integration API](https://wiki.4thtech.io/developers/architecture/integration-api.md).
