@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 +6 -0
- package/README.md +3 -7
- package/TROUBLESHOOTING.md +55 -27
- package/docs/ASSURANCE.md +26 -10
- package/docs/GETTING_STARTED.md +30 -23
- package/docs/PROTOCOL_POLICY.md +31 -20
- package/groups/README.md +1 -1
- package/hooks/README.md +6 -3
- package/local/store/react-native/README.md +9 -10
- package/local/store/web/README.md +1 -1
- package/package.json +1 -1
- package/safety/README.md +48 -11
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -16,14 +16,10 @@ The default policy requires post-quantum session establishment and ratcheting. T
|
|
|
16
16
|
[](https://www.npmjs.com/package/@open-e2ee/signal-protocol-sdk#provenance)
|
|
17
17
|
[](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
|
|
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
|
|
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
|
|---|---|---|
|
package/TROUBLESHOOTING.md
CHANGED
|
@@ -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:
|
|
62
|
+
<!-- doc-snippet:skip requires-application-storage -->
|
|
63
63
|
```typescript
|
|
64
|
-
|
|
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
|
-
//
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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
|
-
###
|
|
105
|
+
### Device Address Format
|
|
93
106
|
|
|
94
107
|
**"No session with address"**
|
|
95
108
|
|
|
96
|
-
|
|
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
|
-
|
|
101
|
-
await signal.encryptMessage('bob', 'Hello');
|
|
114
|
+
import { ProtocolAddress, type DefaultSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
|
|
102
115
|
|
|
103
|
-
//
|
|
104
|
-
|
|
105
|
-
|
|
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
|
-
|
|
148
|
-
|
|
149
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
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/
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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.
|
package/docs/GETTING_STARTED.md
CHANGED
|
@@ -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
|
|
33
|
-
|
|
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.
|
|
157
|
-
|
|
158
|
-
|
|
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
|
|
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
|
-
|
|
166
|
-
client holds
|
|
167
|
-
|
|
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
|
-
|
|
172
|
-
|
|
173
|
-
|
|
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:
|
|
488
|
+
<!-- doc-snippet:skip configuration-only -->
|
|
484
489
|
```ts
|
|
485
|
-
|
|
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
|
package/docs/PROTOCOL_POLICY.md
CHANGED
|
@@ -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:
|
|
13
|
+
<!-- doc-snippet:skip configuration-only -->
|
|
14
14
|
```ts
|
|
15
|
-
|
|
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`)
|
|
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
|
|
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.
|
|
134
|
-
|
|
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:
|
|
139
|
+
<!-- doc-snippet:skip requires-application-membership -->
|
|
138
140
|
```ts
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
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
|
|
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
|
-
|
|
191
|
-
|
|
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`.
|
|
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
|
|
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
|
|
5
|
-
[op-sqlite](https://github.com/OP-Engineering/op-sqlite). The
|
|
6
|
-
|
|
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
|
|
90
|
-
|
|
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
|
-
|
|
119
|
-
|
|
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
|
|
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
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
|
-
|
|
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
|
-
|
|
27
|
-
|
|
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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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.
|