@open-e2ee/signal-protocol-sdk 13.5.0 → 13.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 13.5.1
4
+
5
+ ### Fixed
6
+
7
+ - Correct code examples and local links in ten SDK 13.5 guides.
8
+
3
9
  ## 13.5.0
4
10
 
5
11
  ### Added
package/README.md CHANGED
@@ -16,14 +16,10 @@ The default policy requires post-quantum session establishment and ratcheting. T
16
16
  [![npm provenance](https://img.shields.io/badge/npm-provenance-2f6f5e)](https://www.npmjs.com/package/@open-e2ee/signal-protocol-sdk#provenance)
17
17
  [![Checks](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml/badge.svg)](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml)
18
18
 
19
- [Documentation](https://docs.open-e2ee.dev) · [API reference](https://docs.open-e2ee.dev/reference/api) · [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay) · [Security](./SECURITY.md)
19
+ [Documentation](https://docs.open-e2ee.dev) · [API reference](https://docs.open-e2ee.dev/reference/api) · [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay/) · [Security](./SECURITY.md)
20
20
 
21
21
  ## See an encrypted round trip
22
22
 
23
- Press play for device setup, session establishment, encrypted delivery, and decryption on each device.
24
-
25
- https://github.com/user-attachments/assets/d8002bc3-c037-41b6-8f48-4008f2d49e6c
26
-
27
23
  The [visual demo](https://open-e2ee.dev/#demo) shows the envelope, ratchets, relay mailbox, and decrypted result. On desktop, type a message and inspect each step. On mobile, a recorded protocol run replays at reading pace. Displayed timings exclude network time.
28
24
 
29
25
  The demonstrations use real protocol code and cryptography. Application integration requires device-local storage and authenticated delivery.
@@ -33,7 +29,7 @@ The demonstrations use real protocol code and cryptography. Application integrat
33
29
  - **Session establishment and ratcheting.** PQXDH establishes sessions. The ML-KEM Braid ratchet adds post-quantum key updates. Required post-quantum operations fail closed.
34
30
  - **Chat features.** Multi-device messaging, groups, sealed sender, encrypted attachments, and safety-number verification use the same package.
35
31
  - **Device-local state.** Storage adapters keep identities, sessions, and message state on the device.
36
- - **Hosted delivery.** Connect to [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay) with the hosted client factory. Advanced integrations can supply a custom transport. A hosted client sends a sealed 1:1 message only with `hosted.profileKeys`, and only to a contact whose profile key it holds.
32
+ - **Hosted delivery.** Connect to [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay/) with the hosted client factory. Advanced integrations can supply a custom transport. A hosted client sends a sealed 1:1 message only with `hosted.profileKeys`. It must also hold the contact's profile key.
37
33
 
38
34
  The relay never needs message plaintext or device private keys.
39
35
 
@@ -105,7 +101,7 @@ See [client composition](./docs/CLIENT_COMPOSITION.md) for platform setup.
105
101
 
106
102
  ## Use your app’s storage and relay
107
103
 
108
- Choose the device-local store for your runtime. Then supply a relay that authenticates each device and implements your product's access policy, or use [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay) as the managed delivery path. The SDK does not require the managed service. [Review Relay plans and exact meter definitions.](https://open-e2ee.dev/relay/pricing)
104
+ Choose the device-local store for your runtime. Then supply a relay that authenticates each device and implements your product's access policy, or use [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay/) as the managed delivery path. The SDK does not require the managed service. [Review Relay plans and exact meter definitions.](https://open-e2ee.dev/pricing/#relay-plans)
109
105
 
110
106
  | Runtime | Storage path | Deployment boundary |
111
107
  |---|---|---|
@@ -59,15 +59,22 @@ with `--force` or `--legacy-peer-deps`.
59
59
 
60
60
  **"Identity key not found - client not initialized"**
61
61
 
62
- <!-- doc-snippet:illustrative elided-call-arguments -->
62
+ <!-- doc-snippet:skip requires-application-storage -->
63
63
  ```typescript
64
- // ❌ Wrong: forgot to initialize
65
- const signal = new DefaultSignalProtocolClient(); // Don't use constructor directly!
66
- await signal.encryptMessage(...); // Error!
64
+ import { DefaultSignalProtocolClient, type SignalProtocolClientConfig } from '@open-e2ee/signal-protocol-sdk';
67
65
 
68
- // ✅ Correct: use factory method
69
- const signal = await DefaultSignalProtocolClient.create(userId, { storage });
70
- await signal.encryptMessage(...); // Works!
66
+ // Compile-only negative example. This function is never called.
67
+ function compileOnlyRejectsDirectConstruction(): void {
68
+ // @ts-expect-error Initialize the client through its asynchronous factory.
69
+ new DefaultSignalProtocolClient();
70
+ }
71
+
72
+ export function initializeSignal(
73
+ userId: string,
74
+ storage: SignalProtocolClientConfig['storage'],
75
+ ): Promise<DefaultSignalProtocolClient> {
76
+ return DefaultSignalProtocolClient.create(userId, { storage });
77
+ }
71
78
  ```
72
79
 
73
80
  ### Session Establishment
@@ -78,31 +85,44 @@ Make sure the prekey bundle is fresh and valid:
78
85
 
79
86
  <!-- doc-snippet:skip requires-external-context -->
80
87
  ```typescript
81
- // Fetch the latest prekey bundle through the relay adapter
82
- const bundle = await relay.fetchPreKeyBundle(bobId, 1, undefined, 'aci');
83
-
84
- // Verify bundle has required fields
85
- if (!bundle.identityKey || !bundle.signedPreKey) {
86
- throw new Error('Invalid prekey bundle');
88
+ import { ProtocolAddress, type DefaultSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
89
+ import type { SignalProtocolRelayServer } from '@open-e2ee/signal-protocol-sdk/remote/relay';
90
+
91
+ export async function establishBobSession(
92
+ signal: DefaultSignalProtocolClient,
93
+ relay: SignalProtocolRelayServer,
94
+ bobId: string,
95
+ ): Promise<void> {
96
+ const address = ProtocolAddress.create(bobId, 1);
97
+ const bundle = await relay.fetchPreKeyBundle(bobId, 1, undefined, 'aci');
98
+ if (!bundle || !bundle.identity || !bundle.ecSignedPreKey) {
99
+ throw new Error('Invalid prekey bundle');
100
+ }
101
+ await signal.establishSession(address, bundle);
87
102
  }
88
-
89
- await signal.establishSession(sessionId, bobId, bundle);
90
103
  ```
91
104
 
92
- ### Session ID Format
105
+ ### Device Address Format
93
106
 
94
107
  **"No session with address"**
95
108
 
96
- Session IDs must be in `userId:deviceId` format:
109
+ The serialized address form is `userId:deviceId`. Direct client methods take a
110
+ `ProtocolAddress` object. Create it with `ProtocolAddress.create(userId, deviceId)`.
97
111
 
98
112
  <!-- doc-snippet:skip requires-external-context -->
99
113
  ```typescript
100
- // ❌ Wrong: missing device ID
101
- await signal.encryptMessage('bob', 'Hello');
114
+ import { ProtocolAddress, type DefaultSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
102
115
 
103
- // ✅ Correct: include device ID
104
- await signal.encryptMessage('bob:1', 'Hello'); // Primary device
105
- await signal.encryptMessage('bob:2', 'Hello'); // Secondary device
116
+ // Compile-only negative example. This function is never called.
117
+ async function compileOnlyRejectsSerializedAddress(signal: DefaultSignalProtocolClient): Promise<void> {
118
+ // @ts-expect-error encryptMessage requires a ProtocolAddress object.
119
+ await signal.encryptMessage('bob', 'Hello');
120
+ }
121
+
122
+ export async function encryptToBobDevices(signal: DefaultSignalProtocolClient): Promise<void> {
123
+ await signal.encryptMessage(ProtocolAddress.create('bob', 1), 'Hello');
124
+ await signal.encryptMessage(ProtocolAddress.create('bob', 2), 'Hello');
125
+ }
106
126
  ```
107
127
 
108
128
  ### Out-of-Order Messages
@@ -144,19 +164,27 @@ console.log('OneTime prekeys remaining:', stats.oneTimePreKeysCount);
144
164
 
145
165
  <!-- doc-snippet:skip requires-external-context -->
146
166
  ```typescript
147
- // Check if session exists
148
- const hasSession = await signal.hasSession('bob:1');
149
- console.log('Has session with bob:1:', hasSession);
167
+ import { ProtocolAddress, type DefaultSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
168
+
169
+ export async function checkBobSession(signal: DefaultSignalProtocolClient): Promise<void> {
170
+ const address = ProtocolAddress.create('bob', 1);
171
+ const hasSession = await signal.hasSession(address);
172
+ console.log('Has session with bob:1:', hasSession);
173
+ }
150
174
  ```
151
175
 
152
176
  ### Enable Debug Logging
153
177
 
154
178
  <!-- doc-snippet:skip requires-external-context -->
155
179
  ```typescript
156
- const signal = await DefaultSignalProtocolClient.create(userId, {
180
+ import { DefaultSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
181
+ import { inMemoryStore } from '@open-e2ee/signal-protocol-sdk/local/store/memory';
182
+
183
+ const signal = await DefaultSignalProtocolClient.create('alice', {
184
+ storage: inMemoryStore(),
157
185
  enableDebugLogging: true,
158
186
  });
159
- // Now all crypto operations will log to console
187
+ // The in-memory adapter is for this local example. Select a protected platform store in an application.
160
188
  ```
161
189
 
162
190
  ### Verify Identity Keys
package/docs/ASSURANCE.md CHANGED
@@ -10,7 +10,7 @@ The public repository contains SDK client source, documentation, and build check
10
10
 
11
11
  You can inspect the client implementation and run the public checks. Relay server implementations and the internal runtime examples remain private. You cannot reproduce the private results from this repository alone.
12
12
 
13
- Private testing also exists in other open-source projects. [SQLite publishes some checks and keeps TH3 private](https://www.sqlite.org/testing.html). [Convex documents a private testing framework](https://github.com/get-convex/convex-backend#readme). Those projects do not review or endorse this SDK.
13
+ Private testing also exists in other open-source projects. [SQLite publishes some checks and keeps TH3 private](https://www.sqlite.org/testing.html). [Convex documents a private testing framework](https://github.com/convex/convex-backend/blob/main/README.md). Those projects do not review or endorse this SDK.
14
14
 
15
15
  ## Reported engineering results
16
16
 
@@ -38,12 +38,14 @@ Release tooling generates this table from a completed run. It refuses results fr
38
38
  - **Generated inputs:** check protocol and encoding properties across randomized inputs.
39
39
  - **Messaging flows:** exercise device fanout, groups, device linking, device transfer, PNI-to-ACI changes, and relay delivery.
40
40
  - **Storage contracts:** check persistence, concurrency, interruption, recovery, and storage pressure at adapter boundaries.
41
- - **Runtime behavior:** run the browser storage contracts in Chromium, Firefox, and WebKit. Run each public flow on the Hermes V1 command-line engine that React Native 0.86 uses, with only the globals of a bare React Native app. A committed list records each flow step that fails on that engine and its error. The job fails when a result differs from that list. Run release builds of the Expo example and the bare React Native example on an Android emulator. Both use Hermes V1. The Expo build uses Expo SDK 57 and React Native 0.86, and the bare build uses React Native 0.87.1.
41
+ - **Runtime behavior:** run the browser storage contracts in Chromium, Firefox, and WebKit. Run each public flow on the Hermes V1 command-line engine that React Native 0.86 uses. Use only the globals of a bare React Native app. A committed list records each flow step that fails on that engine and its error. The job fails when a result differs from that list.
42
+
43
+ Run release builds of the Expo example and the bare React Native example on an Android emulator. Both use Hermes V1. The Expo build uses Expo SDK 57 and React Native 0.86. The bare build uses React Native 0.87.1.
42
44
  - **Public API:** check exported types, import paths, documented calls, and expected example output against the packed package.
43
45
  - **React Native hosts:** add the packed package to React Native and Expo projects without an override of peer conflicts. The projects cover React Native 0.83 through 0.87 and the Expo SDK 55 through 57 lines. Build the Expo example's Hermes bundle on Expo SDK 55 and 57.
44
46
  - **Errors:** check construction sites for exported error classes and codes. Reject unresolved code forwarding.
45
47
 
46
- The browser storage job also runs 2,000 open, write, read, and close cycles of the IndexedDB store, and a soak of the web SQLite store. Each checks for upward memory and latency drift.
48
+ The browser storage job also runs 2,000 open, write, read, and close cycles of the IndexedDB store. It also runs a soak of the web SQLite store. Each checks for upward memory and latency drift.
47
49
 
48
50
  In Chromium, the browser storage job also builds an app with the Vite version of the browser example and the packed package. The entry module of the app completes an exchange in each direction with a top-level await. The job fails when the exchange does not finish in 30 seconds, or when a chunk of the build imports the entry chunk. A default automated check also fails when the SDK loads a module with a dynamic import and that module imports another module. Other bundlers are not checked.
49
51
 
@@ -51,7 +53,9 @@ A storage contract check does not prove a full encrypted exchange. Internal brow
51
53
 
52
54
  ## SQLite store checks
53
55
 
54
- Four package entries keep device-local state in a SQLite database: `./local/store/node`, `./local/store/expo`, `./local/store/react-native`, and `./local/store/web-sqlite`. A Tauri app uses `./local/store/web-sqlite`. Each row gives one runtime claim and the check that proves it. Rows that do not name public CI run in the project's engineering CI. A check runs on each change to the main branch and on each pull request that is ready for review, unless its row says otherwise. On a pull request, a job on macOS or Windows runs only when a maintainer requests it. Without that request, a pull request runs the Node store job only on Linux with Node 22, and the default automated checks run its tests on Linux with Node 26.
56
+ Four package entries keep device-local state in a SQLite database: `./local/store/node`, `./local/store/expo`, `./local/store/react-native`, and `./local/store/web-sqlite`. A Tauri app uses `./local/store/web-sqlite`. Each row gives one runtime claim and the check that proves it. Rows that do not name public CI run in the project's engineering CI. A check runs on each change to the main branch and on each pull request that is ready for review, unless its row says otherwise.
57
+
58
+ On a pull request, a job on macOS or Windows runs only when a maintainer requests it. Without that request, the Node store job uses only Linux and Node 22 on a pull request. The default automated checks run its tests on Linux with Node 26.
55
59
 
56
60
  ### Node and the Electron main process: `./local/store/node`
57
61
 
@@ -74,7 +78,11 @@ Four package entries keep device-local state in a SQLite database: `./local/stor
74
78
  | On Linux, with a running Secret portal and the default Chromium features, the store passes the shared storage contract. `safeStorage` does not use the key of the portal. | Electron store job: Linux, Electron 44 | Electron with `--password-store=gnome-libsecret`, and xdg-desktop-portal with the GNOME keyring as the back end of its Secret portal. |
75
79
  | On Linux, the vault refuses the key of the Secret portal, which `safeStorage` uses with the Chromium feature `SecretPortalKeyProviderUseForEncryption`. The store does not open, and no key reaches the disk. | Electron store job: Linux, Electron 44 | Electron with that feature and a Secret portal, with the GNOME keyring as the back end of the portal. The test checks that the ciphertext starts with `v12`. Run 36528132421 also refused the key with KWallet 6 (`kwallet6`, Ubuntu 26.04) as the back end of the portal. No job runs that case again. |
76
80
 
77
- No CI job signs the app with a Developer ID. On 2026-09-29, a manual check on macOS 15.7.2 arm64 with Xcode 26.3 built the packaged app twice from the main branch, as version 1.0.0 and version 1.0.1. The build used the SDK 8.1.0 package and Electron 44.4.5. Electron Forge signed each build with a Developer ID identity and the hardened runtime, and notarized and stapled it. For each build, `spctl -a -vv` reported `accepted` and `source=Notarized Developer ID`. A check script wrote a value with version 1.0.0 in the main process and in a utility process. Then it copied version 1.0.1 over the app, and the relaunches read each value back. The securityd log had no Keychain prompt for a launch. When the check copied an ad-hoc signed copy of version 1.0.1 over version 1.0.0, securityd logged a Keychain prompt for each read, and the check stopped the app. The access list of the Keychain item of the key holds the designated requirement of the app, which names the bundle identifier and the Developer ID team, not a code hash.
81
+ No CI job signs the app with a Developer ID. On 2026-09-29, a manual check built the packaged app twice from the main branch. The check used macOS 15.7.2 arm64 with Xcode 26.3 for both builds. It built version 1.0.0 and version 1.0.1 of the app. The build used the SDK 8.1.0 package and Electron 44.4.5.
82
+
83
+ Electron Forge signed each build with a Developer ID identity and the hardened runtime, and notarized and stapled it. For each build, `spctl -a -vv` reported `accepted` and `source=Notarized Developer ID`. A check script wrote a value with version 1.0.0 in the main process and in a utility process. Then it copied version 1.0.1 over the app, and the relaunches read each value back. The securityd log had no Keychain prompt for a launch.
84
+
85
+ The check replaced version 1.0.0 with an ad-hoc signed copy of version 1.0.1 of the app. Then securityd logged a Keychain prompt for each read. The check stopped the app. The access list of the key's Keychain item holds the app's designated requirement. That requirement names the bundle identifier and the Developer ID team. It does not name a code hash.
78
86
 
79
87
  ### Expo: `./local/store/expo`
80
88
 
@@ -87,7 +95,7 @@ No CI job signs the app with a Developer ID. On 2026-09-29, a manual check on ma
87
95
  | The Expo example, which imports this entry, bundles with the Hermes compiler that React Native pins. | Engineering CI | The Android bundle of the Expo example with the packed package, on Expo SDK 55 and Expo SDK 57. |
88
96
  | In an Expo web build, an encrypted open and a reset fail with `SqliteEncryptionUnavailableError` (`KEY_STORAGE_ERROR`) before they use the vault. With `encryptionAtRest: false`, the store opens and keeps its data across a page load. | Browser storage job: Chromium on Linux | An `expo export --platform web` of an Expo SDK 57 app that installs the packed package, loaded in Chromium. The page reads no `PRAGMA cipher_version` row, and Expo SecureStore reports that it is not available. The check does not open a store with `./local/store/web-sqlite` in the Expo web build. |
89
97
 
90
- The Hermes flow job does not load a SQLite store. Its flows use the memory and key-value stores. The Android emulator job is the only CI job that runs the Expo store on Hermes. No check runs the conversion on iOS, so it is unverified there.
98
+ The Hermes flow job does not load a SQLite store. Its flows use the memory and key-value stores. The Android emulator job is the only CI job that runs the Expo store on Hermes. No check runs the conversion on iOS, so no check verifies it there.
91
99
 
92
100
  ### Bare React Native: `./local/store/react-native`
93
101
 
@@ -103,7 +111,9 @@ The Hermes flow job does not load a SQLite store. Its flows use the memory and k
103
111
  | A release build of the bare React Native example converts a plaintext database with SQLCipher on Android. The rows and the schema version stay, the file has no SQLite header, and the vault holds one key that opens it. | Android emulator job | The release APK of the row above. Each run must log the number of rows and the schema version that the conversion kept. The same trigger rules apply. |
104
112
  | The bare React Native example, which imports this entry, bundles with the Hermes compiler that React Native pins. | Engineering CI | The Android release bundle of the bare React Native example with the packed package. |
105
113
 
106
- The Android emulator job is the only CI job that runs this store on Hermes with the native op-sqlite module. No CI job runs it on iOS. No check runs the conversion on iOS, so it is unverified there. On 2026-09-28, a manual check of a development build of the SDK before 8.0.0 ran the bare React Native example in the iOS 26.2 simulator with Xcode 26.3. Each of four launches logged a SQLCipher version, a database header that is not the SQLite header, and the wrong-key failure. Each launch after the first resumed the stored identity.
114
+ The Android emulator job is the only CI job that runs this store on Hermes with the native op-sqlite module. No CI job runs it on iOS. No check runs the conversion on iOS, so no check verifies it there.
115
+
116
+ On 2026-09-28, a manual check ran the bare React Native example. It used a development build from before the SDK's 8.0.0 release. The check used Xcode 26.3 and the iOS 26.2 simulator. Each of four launches logged a SQLCipher version, a database header that is not the SQLite header, and the wrong-key failure. Each launch after the first resumed the stored identity.
107
117
 
108
118
  On 2026-09-29, a manual check with Xcode 26.3 ran the release build of the example four times in the iOS 26.2 simulator. The check used the SDK 8.1.0 package built from the main branch. Each launch passed the same checks. A temporary native log in the app read the storage attributes. The example does not include this log:
109
119
 
@@ -127,7 +137,11 @@ The simulator does not enforce Data Protection. These results do not show the pr
127
137
  | Over a long run, the store holds latency, memory, and file size flat. A closed store leaves no worker, no lock of the store, and no IndexedDB connection. Two tabs that write in turn each read the last write of the other. | Browser storage job: Chromium on Linux | 150 open, write, read, and close cycles, one session of 2,000 churn operations over 250 sessions, and 100 writes that two tabs make in turn. The check counts the workers, locks, IndexedDB connections, and OPFS entries that the cycles leave. It times each cycle and each two-tab read next to a control that does the same platform work with no store state, and compares the early and late thirds of that ratio. It compares the medians of the early and late thirds of the churn, and fits a slope to the page heap of the cycles. It reads the page heap, the IndexedDB connections, and the heap and Wasm memory of the store's worker, through the DevTools protocol. Firefox and WebKit have no such protocol in the test runner, and no CI job runs this check in them. |
128
138
  | A worker without OPFS synchronous access handles fails with `OPFS_UNAVAILABLE` before it loads the engine. | Browser storage job: Chromium, Firefox, and WebKit on Linux | WebKit on Linux (WebKitGTK) has no OPFS synchronous access handles, so there WebKit runs only these checks and the checks that need no OPFS. |
129
139
 
130
- The WebKit store job runs Playwright's WebKit on macOS, where WebKit has OPFS synchronous access handles. Playwright's WebKit is not Safari, so the same job then runs the same checks in the Safari of the macOS runner through `safaridriver`, and records the Safari version. A WebDriver runner runs the Playwright checks unchanged. It counts the workers of a page from inside the page, and it reports the uncaught errors of a page only after the page loads. Each browser context is a Safari WebDriver session, so the check for an ephemeral context that refuses OPFS access handles skips when that session has them. It runs only on a change to the web SQLite store, the SQLite core, the storage contract, the key vault, the job, or a dependency. On a pull request, it runs only when a maintainer requests it. In the browser storage job for Chromium and Firefox and in the WebKit store job, a check that skips for want of OPFS fails.
140
+ The WebKit store job runs Playwright's WebKit on macOS, where WebKit has OPFS synchronous access handles. Playwright's WebKit is not Safari. The same job then runs the same checks in the macOS runner's Safari through `safaridriver`. It records the Safari version. A WebDriver runner runs the Playwright checks unchanged.
141
+
142
+ It counts the workers of a page from inside the page, and it reports the uncaught errors of a page only after the page loads. Each browser context is a Safari WebDriver session. The check for an ephemeral context that refuses OPFS access handles skips when that session has them.
143
+
144
+ Only changes to the web SQLite store, the SQLite core, the storage contract, the key vault, the job, or a dependency trigger the job. On a pull request, it runs only when a maintainer requests it. In the browser storage job for Chromium and Firefox and in the WebKit store job, a check that skips for want of OPFS fails.
131
145
 
132
146
  The internal code-generation check runs an encrypted exchange with the memory store. It does not load a SQLite store.
133
147
 
@@ -139,7 +153,9 @@ The internal code-generation check runs an encrypted exchange with the memory st
139
153
  | In a Tauri 2.12.0 app on Linux, the first open fails with `OPFS_UNAVAILABLE`, because WebKitGTK has no OPFS synchronous access handles. No other step of the check runs. | Tauri example job: Linux x64, WebKitGTK 2.52.6 | The same app under Xvfb. The job fails when the first open succeeds or fails with a different code. |
140
154
  | In a Tauri 2.12.0 app on Android, the store opens in the Android WebView with the default IndexedDB vault. Every step of the Windows check passes, including the relaunch in a new process. | Tauri example job: Android API 36 x86_64 emulator, Android WebView 133.0.6943.137 | A debug APK of the same app, installed on the emulator and launched twice. The app writes its report to its data directory, and the job reads the report with `adb`. The job fails unless every step passes. On a pull request, the Android leg runs only when a maintainer requests it. |
141
155
 
142
- A Tauri 2 app uses `./local/store/web-sqlite` in its webview, with no Tauri-specific SDK code. The [web SQLite store guide](../local/store/web-sqlite/README.md#tauri) gives the Tauri setup. On 2026-09-28, a manual check of a development build of the SDK before 8.0.0, in a Tauri 2.12.0 app, passed in WKWebView on macOS 15.7.2 and in the iOS 18.0 simulator. The check covered a two-device exchange, a close and reopen, an app relaunch, a relaunch after the app was killed with both stores open, and the store locks.
156
+ A Tauri 2 app uses `./local/store/web-sqlite` in its webview, with no Tauri-specific SDK code. The [web SQLite store guide](../local/store/web-sqlite/README.md#tauri) gives the Tauri setup.
157
+
158
+ On 2026-09-28, a manual check used a development build of the SDK before 8.0.0 in a Tauri 2.12.0 app. It passed in WKWebView on macOS 15.7.2 and in the iOS 18.0 simulator. The check covered a two-device exchange, a close and reopen, an app relaunch, and the store locks. It also covered the next relaunch after an app kill with both stores open.
143
159
 
144
160
  On 2026-09-29, a manual check ran a debug build of the Tauri example with Tauri 2.12.0 in its shell. The app installed SDK 8.1.0, packed from the same commit as the example. On macOS 15.7.2 and in the iOS 17.5 simulator, every step of the first launch and of the relaunch passed. On macOS, two windows of the app shared one store. The second window opened the store that the first window held, and each window read the writes of the other. A reset in the second window failed with `INVALID_STATE`.
145
161
 
@@ -152,7 +168,7 @@ No CI job checks these items:
152
168
  - **A full origin quota in Firefox, WebKit, and Safari.** In these browsers, the quota check injects `QuotaExceededError` in the worker. No check fills a real origin quota there.
153
169
  - **Tauri on macOS and iOS.** No CI job runs the Tauri example on macOS or iOS. The manual checks ran a debug build on macOS 15.7.2 and in the iOS 17.5 and 18.0 simulators. No check ran the store in a Tauri app on a physical iOS device.
154
170
  - **A Tauri store that WebKit removes.** A check cleared all website data of the webview with a Tauri call. No check saw WebKit remove the data under storage pressure or after a period without use. No check removed the IndexedDB vault of a Tauri app while its database file stayed.
155
- - **A Tauri release build, and Tauri on physical Android devices.** The Tauri example job runs a debug build with no bundle on Windows and Linux, and a debug APK on an Android API 36 emulator. No check ran the store in a release build, in an installed desktop app, on another Android API level, or on a physical Android device.
171
+ - **A Tauri release build, and Tauri on physical Android devices.** The Tauri example job runs debug builds. On Windows and Linux, they have no bundle. On an Android API 36 emulator, the job runs a debug APK. No check ran the store in a release build or an installed desktop app. No check ran it on another Android API level or a physical Android device.
156
172
  - **The React Native store on iOS and on physical devices.** No CI job opens `./local/store/react-native` on iOS. The manual checks used only the iOS simulator. No check ran the store on a physical Android or iOS device.
157
173
  - **iOS devices.** No CI job runs on iOS. The manual checks used only the iOS simulator.
158
174
  - **iOS Data Protection.** The simulator does not keep a file protection class. So no check recorded the class of the React Native store files. No check observed a file class or the keychain class enforced on a locked device.
@@ -28,10 +28,10 @@ The [adapter guide](../ADAPTERS.md) lists the supported stores.
28
28
  - Application storage for decrypted messages and attachment bytes.
29
29
 
30
30
  A Sandbox environment uses device-owned identity. `hostedRelaySandboxIdentity`
31
- creates its `getIdentityAssertion` callback. The callback signs each assertion
32
- with a key that it keeps in the device-local store, so the device gets the same
33
- account each time it registers. A device that loses its store loses that
34
- Sandbox account. The helper works only in a Sandbox environment.
31
+ creates its `getIdentityAssertion` callback. The callback keeps a key in the device-local store. It signs each assertion
32
+ with that key. The device gets the same account each time it registers.
33
+
34
+ A device that loses its store loses that Sandbox account. The helper works only in a Sandbox environment.
35
35
 
36
36
  Production supports application-bound and explicitly configured device-owned
37
37
  accounts. For application-bound accounts, `getIdentityAssertion` returns a
@@ -62,6 +62,7 @@ transfer or by a channel that the application owns, then joins the account
62
62
  with `linkHostedRelayDevice()`. That call runs in one process that holds the
63
63
  active device's store and the new device's store. It copies each group master
64
64
  key from the active device and gives the new device its own registration ID.
65
+
65
66
  It refuses a new device's store that already lists a group, with
66
67
  `HostedRelayDeviceLinkError`. See the [device guide](../device/README.md). The
67
68
  default policy requires post-quantum session establishment and Braid
@@ -153,39 +154,37 @@ await signal.send("bob", {
153
154
  A new send accepts a `timestamp` at most 5 minutes ahead of the SDK clock and
154
155
  at most 24 hours behind it. For any other value, `send()` throws
155
156
  `InvalidSendTimestampError` and stores or posts nothing. Omit `timestamp`, and
156
- the SDK uses its clock. From the Relay release that follows v2026.10.25, the
157
- Relay admits a mailbox delivery epoch and a new group fan-out operation in the
158
- same window. Earlier Relay releases admit a new operation only within 5
157
+ the SDK uses its clock.
158
+
159
+ From the Relay release that follows v2026.10.25, the Relay admits a mailbox
160
+ delivery epoch in the same window. It also admits a new group fan-out
161
+ operation in that window. Earlier Relay releases admit a new operation only within 5
159
162
  minutes of its epoch. On an earlier Relay release, a time 5 minutes to 24 hours
160
- old passes the SDK check but gets `OPERATION_EXPIRED`. The SDK check uses the
163
+ old passes the SDK check. The Relay returns `OPERATION_EXPIRED`.
164
+
165
+ The SDK check uses the
161
166
  same bounds, so the SDK refuses an application-supplied time before any post.
162
167
 
163
168
  A hosted client sends a sealed 1:1 message only when you pass
164
169
  `hosted.profileKeys`, and only to a contact whose profile key `contacts` holds.
165
- Each other 1:1 message is identified, so the Relay sees its sender. Until the
166
- client holds the profile key of a contact, its messages to that contact are
167
- identified and carry the profile key of this account.
170
+ The client identifies each other 1:1 message, so the Relay sees its sender.
171
+ Until the client holds a contact's profile key, it identifies messages to that
172
+ contact. Those messages carry the profile key of this account.
168
173
 
169
174
  ## Attachments
170
175
 
171
- Add a remote object store when your app sends encrypted attachments. The
172
- `remoteObjectStore` adapter brokers encrypted byte objects rather than
173
- plaintext files.
176
+ The hosted factory supplies the Relay object store for encrypted
177
+ attachments. Configure the media callbacks below to read local bytes and
178
+ save attachment references and downloaded bytes.
174
179
 
175
180
  <!-- doc-snippet:skip requires-external-context -->
176
181
  ```ts
177
182
  import { createHostedSignalProtocolClient, media } from "@open-e2ee/signal-protocol-sdk";
178
- import { convexR2ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2";
179
- import { api } from "../convex/_generated/api";
180
183
 
181
184
  const signal = await createHostedSignalProtocolClient({
182
185
  hosted: { relayUrl, getIdentityAssertion },
183
186
  adapters: {
184
187
  storage,
185
- remoteObjectStore: convexR2ObjectStore({
186
- convex,
187
- api: api.signalObjectStore,
188
- }),
189
188
  },
190
189
  media: {
191
190
  preparedUploads: appPreparedUploads,
@@ -202,6 +201,12 @@ const signal = await createHostedSignalProtocolClient({
202
201
  });
203
202
  ```
204
203
 
204
+ For an application-owned relay and object broker, use
205
+ `createSignalProtocolClient` with `adapters.remoteObjectStore`. The
206
+ [client composition guide](CLIENT_COMPOSITION.md#attachments) shows the
207
+ Convex R2 adapter with that factory. The hosted factory supplies its own
208
+ Relay object store and does not accept a replacement.
209
+
205
210
  For Amazon S3 or S3-compatible storage, use the framework-neutral adapter with
206
211
  an authenticated application-backend broker:
207
212
 
@@ -480,12 +485,14 @@ await signal.media.cleanup(
480
485
 
481
486
  The default is:
482
487
 
483
- <!-- doc-snippet:illustrative config-object-fragment -->
488
+ <!-- doc-snippet:skip configuration-only -->
484
489
  ```ts
485
- protocol: {
490
+ import type { SignalProtocolConfig } from '@open-e2ee/signal-protocol-sdk';
491
+
492
+ export const protocol: SignalProtocolConfig = {
486
493
  postQuantum: 'required',
487
494
  braid: 'required',
488
- }
495
+ };
489
496
  ```
490
497
 
491
498
  Leave it unset. `'required'` is the only `postQuantum` value. See
@@ -10,12 +10,14 @@ identity, the Ed25519-instead-of-XEdDSA signature scheme, the ML-KEM Braid
10
10
 
11
11
  The public Signal Protocol client policy is:
12
12
 
13
- <!-- doc-snippet:illustrative config-object-fragment -->
13
+ <!-- doc-snippet:skip configuration-only -->
14
14
  ```ts
15
- protocol: {
15
+ import type { SignalProtocolConfig } from '@open-e2ee/signal-protocol-sdk';
16
+
17
+ export const protocol: SignalProtocolConfig = {
16
18
  postQuantum: 'required',
17
19
  braid: 'required',
18
- }
20
+ };
19
21
  ```
20
22
 
21
23
  Both values are the defaults.
@@ -42,7 +44,7 @@ message ratchet are mandatory. `'required'` is the only `postQuantum` value.
42
44
 
43
45
  The SDK has no classical key agreement. Every new session uses PQXDH with
44
46
  ML-KEM-1024. A peer that publishes no post-quantum prekeys fails closed with
45
- `PQXDHRequiredError` (`PQXDH_REQUIRED`), and no session is stored.
47
+ `PQXDHRequiredError` (`PQXDH_REQUIRED`). The SDK stores no session.
46
48
 
47
49
  No setting allows downgrade recovery:
48
50
 
@@ -104,7 +106,7 @@ await createSignalProtocolClient({
104
106
  ```
105
107
 
106
108
  `'required'` is the only `postQuantum` value. Any other value throws
107
- `Unsupported postQuantum policy` when the client is created.
109
+ `Unsupported postQuantum policy` when you create the client.
108
110
 
109
111
  ## Advanced Telemetry
110
112
 
@@ -130,18 +132,24 @@ direct-vs-Braid choice.
130
132
  ## Content Recovery
131
133
 
132
134
  A device that cannot decrypt a message asks the sender for it again with a
133
- retry request. To answer with the content, the sender keeps the plaintext of
134
- each resendable message in its local store. `protocol.contentRecovery`
135
+ retry request. The sender keeps each resendable message's plaintext in its local store.
136
+ It uses that content to answer. `protocol.contentRecovery`
135
137
  decides whether the store may hold that plaintext.
136
138
 
137
- <!-- doc-snippet:illustrative config-object-fragment -->
139
+ <!-- doc-snippet:skip requires-application-membership -->
138
140
  ```ts
139
- protocol: {
140
- contentRecovery: {
141
- mode: 'require-protected',
142
- retentionMs: 14 * 24 * 60 * 60 * 1000,
143
- isCurrentMember: async (groupId, userId) => true,
144
- },
141
+ import type { ContentRecoveryPolicy, SignalProtocolConfig } from '@open-e2ee/signal-protocol-sdk';
142
+
143
+ export function protectedContentRecovery(
144
+ isCurrentMember: NonNullable<ContentRecoveryPolicy['isCurrentMember']>,
145
+ ): SignalProtocolConfig {
146
+ return {
147
+ contentRecovery: {
148
+ mode: 'require-protected',
149
+ retentionMs: 14 * 24 * 60 * 60 * 1000,
150
+ isCurrentMember,
151
+ },
152
+ };
145
153
  }
146
154
  ```
147
155
 
@@ -170,7 +178,7 @@ The modes:
170
178
  - `off` keeps no content.
171
179
 
172
180
  A `none` level never keeps content. When the policy refuses the store, the
173
- client keeps no pairwise message record and no send log entry, and deletes
181
+ client keeps no pairwise message record and no send log entry. It deletes
174
182
  the ones that the store already holds. A retry request for a direct message
175
183
  then resets the session with no content. The client shows the decision in
176
184
  `client.contentRecoveryStatus`, with `reason` when it is off, and logs it
@@ -186,9 +194,10 @@ The client deletes expired content before each send log lookup, at creation,
186
194
  at `stop()`, and before the first resendable group send of each day. An E2EE
187
195
  delivery receipt from a device deletes the send log row of that device, and
188
196
  the last row takes the content with it. A Relay delivery receipt, a read
189
- receipt, and a viewed receipt delete no row. A device also acknowledges a
190
- copy that it could not decrypt, so the Relay receipt does not prove that the
191
- device has the content. `client.getPendingRecipients(clientMessageId)` lists
197
+ receipt, and a viewed receipt delete no row. A device also acknowledges a copy that it could not decrypt. The Relay
198
+ receipt does not prove that the device has the content.
199
+
200
+ `client.getPendingRecipients(clientMessageId)` lists
192
201
  the devices that still have a row. `client.forgetSentContent(clientMessageId)`
193
202
  deletes the content of one group send at once. It does not delete the
194
203
  pairwise message records. A device lifecycle reset clears the send log with
@@ -200,14 +209,16 @@ groups, or set `isCurrentMember` for ad hoc groups. The client checks a
200
209
  managed group against its verified group state and never asks the hook
201
210
  about it. The hook gets the prefixed group ID that `createGroupId` makes.
202
211
  `contentRecoveryStatus.groupMembershipSource` is `managed`, `hook`, or
203
- `none`. A client with no source still keeps content and logs one warning
212
+ `none`.
213
+
214
+ A client with no source still keeps content and logs one warning
204
215
  at creation. With no source for a group, the sender gives no group content
205
216
  again. A direct message resend needs no source.
206
217
 
207
218
  A group send of a `DataMessage` has the content hint `Resendable` when the
208
219
  policy keeps content and the application sets no other hint. The client
209
220
  writes the content and the recipient devices to the send log before it
210
- stores the outgoing intent, so a failed write stops the send. When the
221
+ stores the outgoing intent. A failed write stops the send. When the
211
222
  policy keeps no content, the send goes out as `Default`.
212
223
 
213
224
  A custom store must declare its `protection` as `{ atRest, keyCustody }`.
package/groups/README.md CHANGED
@@ -38,7 +38,7 @@ const groups = new GroupManager({
38
38
  serverSigningPublicKey,
39
39
  aci: localAccountServiceId,
40
40
  pni: localPhoneNumberServiceId,
41
- issueProfileKeyCredential: () => appGroupCredentials.issueProfileKey(),
41
+ issueProfileKeyCredential: (request) => appGroupCredentials.issueProfileKey(request),
42
42
  profileKeyCredentialPublicKey,
43
43
  profileKey: localProfileKey,
44
44
  });
package/hooks/README.md CHANGED
@@ -27,19 +27,22 @@ import {
27
27
  useRelayConnectionState,
28
28
  useRelayLifecycle,
29
29
  useSessionHealth,
30
+ type UseRelayLifecycleOptions,
31
+ type UseRelayConnectionStateOptions,
32
+ type UseSessionHealthOptions,
30
33
  } from "@open-e2ee/signal-protocol-sdk/hooks";
31
34
 
32
- function SignalLifecycle({ signal }) {
35
+ function SignalLifecycle({ signal }: Pick<UseRelayLifecycleOptions, "signal">) {
33
36
  useRelayLifecycle({ signal });
34
37
  return null;
35
38
  }
36
39
 
37
- function OwnConnectionDot({ signal }) {
40
+ function OwnConnectionDot({ signal }: Pick<UseRelayConnectionStateOptions, "signal">) {
38
41
  const { state } = useRelayConnectionState({ signal });
39
42
  return <Dot online={state === "connected"} />;
40
43
  }
41
44
 
42
- function ConversationStatus({ signal, userId }) {
45
+ function ConversationStatus({ signal, userId }: Pick<UseSessionHealthOptions, "signal" | "userId">) {
43
46
  const { health, isLoading } = useSessionHealth({ signal, userId });
44
47
  if (isLoading) return <p>Checking…</p>;
45
48
  return <p>{health?.status === "healthy" ? "Ready" : "Check the session"}</p>;
@@ -1,10 +1,9 @@
1
1
  # React Native SQLite Store
2
2
 
3
3
  `ReactNativeSignalProtocolStore` implements `SignalProtocolLocalStore`
4
- for bare React Native in an SDK-owned SQLCipher database on
5
- [op-sqlite](https://github.com/OP-Engineering/op-sqlite). The database key is
6
- held through the local secret-vault boundary, by default in the
7
- react-native-keychain vault.
4
+ for bare React Native. It uses an SDK-owned SQLCipher database on
5
+ [op-sqlite](https://github.com/OP-Engineering/op-sqlite). The local secret-vault
6
+ boundary holds the database key. The react-native-keychain vault is the default.
8
7
 
9
8
  ## Why it exists
10
9
 
@@ -86,8 +85,8 @@ Options:
86
85
  - `logger`: receives the warning of each open without encryption.
87
86
 
88
87
  A store holds its name until `close()`. In one process, the opens and resets
89
- of a name run one at a time. An open or a reset of a name that an open store
90
- holds fails with `INVALID_STATE`, so two parallel first opens write one key
88
+ of a name run one at a time. An open or reset fails with `INVALID_STATE`
89
+ when an open store holds that name. Two parallel first opens write one key,
91
90
  and the second open fails.
92
91
 
93
92
  Keep application tables in a separate database file. The SDK database holds
@@ -115,8 +114,8 @@ and its key. `resetReactNativeStore()` is the full teardown.
115
114
 
116
115
  ## Convert a plaintext store
117
116
 
118
- An encrypted open with `convertPlaintext: true` converts a database that was
119
- created with `encryptionAtRest: false`:
117
+ If you created a database with `encryptionAtRest: false`, an encrypted open
118
+ with `convertPlaintext: true` converts it:
120
119
 
121
120
  <!-- doc-snippet:skip requires-external-context -->
122
121
 
@@ -176,7 +175,7 @@ therefore the only thing that protects them.
176
175
 
177
176
  Do not back up the database file to a server or sync it between devices. The
178
177
  default vault keeps the key out of device backups. iOS backs up the Library
179
- directory, and Android Auto Backup includes the databases directory unless the
178
+ directory. Android Auto Backup includes the databases directory unless the
180
179
  app excludes it. A file restored from a backup to a new device therefore has no
181
180
  key there, and the open fails with `LOCAL_STORE_KEY_LOST`.
182
181
 
@@ -198,5 +197,5 @@ For replaced-prekey maintenance, pass the open store to
198
197
  `createPreKeyMaintenanceStore(store)`.
199
198
 
200
199
  See the parent [storage guide](../README.md), [adapter guide](../../../ADAPTERS.md),
201
- the [op-sqlite installation guide](https://op-engineering.github.io/op-sqlite/docs/installation),
200
+ the [op-sqlite installation guide](https://op-engineering.github.io/op-sqlite/docs/installation/),
202
201
  and [security model](../../../docs/SECURITY.md).
@@ -71,7 +71,7 @@ Browser applications using this adapter should:
71
71
 
72
72
  The exact controls depend on the host application's deployment and threat
73
73
  model. See the [OWASP XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)
74
- and [MDN Content Security Policy guide](https://developer.mozilla.org/docs/Web/HTTP/CSP).
74
+ and [MDN Content Security Policy guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP).
75
75
 
76
76
  ## Operational status
77
77
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "13.5.0",
3
+ "version": "13.5.1",
4
4
  "description": "Pure TypeScript Signal Protocol SDK for encrypted chat in Expo, React Native, browsers, and Node. Post-quantum by default.",
5
5
  "keywords": [
6
6
  "open-e2ee",
package/safety/README.md CHANGED
@@ -15,23 +15,60 @@ decision.
15
15
  <!-- doc-snippet:skip requires-external-context -->
16
16
  ```ts
17
17
  import { generateCompositeSafetyNumber } from "@open-e2ee/signal-protocol-sdk/safety";
18
+ import type { CompositeIdentityV1 } from "@open-e2ee/signal-protocol-sdk/keys";
18
19
 
19
- const safetyNumber = generateCompositeSafetyNumber(
20
- localCompositeIdentity,
21
- remoteCompositeIdentity,
22
- localUserId,
23
- remoteUserId,
24
- );
20
+ export function compareCompositeIdentities(
21
+ localCompositeIdentity: CompositeIdentityV1,
22
+ remoteCompositeIdentity: CompositeIdentityV1,
23
+ localUserId: string,
24
+ remoteUserId: string,
25
+ scannedQrBytes: Uint8Array,
26
+ ): boolean {
27
+ const safetyNumber = generateCompositeSafetyNumber(
28
+ localCompositeIdentity,
29
+ remoteCompositeIdentity,
30
+ localUserId,
31
+ remoteUserId,
32
+ );
33
+ console.log(safetyNumber.numeric);
34
+ console.log(safetyNumber.emojis);
35
+ return safetyNumber.scannable.compare(scannedQrBytes) === "match";
36
+ }
37
+ ```
38
+
39
+ This helper comparison does not change a client's trust state. For an existing
40
+ client, compare the exact value returned by `verify()` through an authenticated
41
+ channel. Pass its original confirmation token only after that comparison succeeds.
25
42
 
26
- console.log(safetyNumber.numeric);
27
- console.log(safetyNumber.emojis);
43
+ <!-- doc-snippet:skip requires-authenticated-comparison -->
44
+ ```ts
45
+ import type { DefaultSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
46
+
47
+ type ComparisonDisplay = Pick<
48
+ Awaited<ReturnType<DefaultSignalProtocolClient["verify"]>>,
49
+ "numeric" | "fingerprint"
50
+ >;
28
51
 
29
- const comparison = safetyNumber.scannable.compare(scannedQrBytes);
30
- if (comparison === "match") {
31
- await signal.verify(remoteAddress, remoteCompositeIdentity);
52
+ export async function verifyContact(
53
+ signal: DefaultSignalProtocolClient,
54
+ remoteUserId: string,
55
+ compareAuthenticated: (display: ComparisonDisplay) => Promise<boolean>,
56
+ ): Promise<void> {
57
+ const safetyNumber = await signal.verify(remoteUserId);
58
+ const matched = await compareAuthenticated({
59
+ numeric: safetyNumber.numeric,
60
+ fingerprint: safetyNumber.fingerprint,
61
+ });
62
+ if (matched) {
63
+ await signal.confirmSafetyNumber(safetyNumber.confirmation);
64
+ }
32
65
  }
33
66
  ```
34
67
 
68
+ The comparison callback belongs to the application. It must compare the displayed
69
+ numeric code or fingerprint with the same peer through an authenticated channel.
70
+ It must not approve a fresh client value because a separate helper value matched.
71
+
35
72
  Use the composite safety-number API for contact verification in this SDK
36
73
  profile. The single-key helper is a lower-level reference primitive and does
37
74
  not authenticate the complete composite identity.