> 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/integration-api.md).

# App integration API

How an app talks to Encryptor: the four requests, the two events and the SDK connector.

{% 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 %}

Apps normally use the SDK package `@4thtech-sdk/encryptor`; the [SDK reference for the connector](https://wiki.4thtech.io/developers/sdk/encryptor.md) covers each method. This page shows what happens underneath.

## With the SDK

```ts
import { EncryptorExtensionConnector } from '@4thtech-sdk/encryptor';

const encryptor = new EncryptorExtensionConnector();
await encryptor.isInstalled();
await encryptor.getState();
await encryptor.getPublicKey();
await encryptor.computeSharedSecretKey(peerPublicKey);
```

The connector's `getPublicKeyType()` returns `BL_ENCRYPTOR_EC`. In `@4thtech-sdk/ethereum`, the `Encryptor` class wraps it and adds `storePublicKey()`, which writes your public key to the Users contract.

## Requests the extension accepts

The connector calls `chrome.runtime.sendMessage` with the extension ID and `{ action, data }`.

| Action                   | Data            | Reply              |
| ------------------------ | --------------- | ------------------ |
| `getAppVersion`          | none            | `{ version }`      |
| `getEncryptorState`      | none            | `{ state }`        |
| `getPublicKey`           | none            | `{ publicKey }`    |
| `computeSharedSecretKey` | `{ publicKey }` | `{ sharedSecret }` |

Other actions return `{ error: 'Requested action is not allowed.' }`.

```mermaid
sequenceDiagram
    participant App as Your app
    participant SDK as SDK connector
    participant Enc as Encryptor
    App->>SDK: isInstalled
    SDK->>Enc: getAppVersion
    Enc-->>SDK: version
    App->>SDK: computeSharedSecretKey(peer public key)
    SDK->>Enc: computeSharedSecretKey
    Note over Enc: Private key stays inside the extension
    Enc-->>SDK: shared secret
    SDK-->>App: shared secret
```

*Figure: Request flow for an SDK call, with the private key kept in the extension.*

## Events the page receives

The connector listens for `message` events on `window` (same window only) with these actions:

* `emitHeartbeat`: marks Encryptor as installed.
* `emitEncryptorStateChange`: `data.state` is the new state, cached by the connector.

## Version

The 0.0.4 changelog entry lists "Add Encryptor version to custom DOM element". The source at the last commit contains no code that creates a DOM element; use `getAppVersion` instead.

## Security questions

This page lists what the integration API offers. For security questions, see [Security and disclosure](https://wiki.4thtech.io/resources/security.md).
