@open-e2ee/signal-protocol-sdk 0.3.0 → 0.4.0
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/ADAPTERS.md +7 -0
- package/ARCHITECTURE.md +2 -0
- package/CHANGELOG.md +33 -0
- package/README.md +64 -102
- package/SECURITY.md +2 -2
- package/TROUBLESHOOTING.md +7 -0
- package/blocking/README.md +1 -0
- package/client/README.md +10 -0
- package/device/README.md +5 -0
- package/dist/client/groups.d.ts.map +1 -1
- package/dist/client/groups.js +14 -4
- package/dist/client/groups.js.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -4
- package/dist/index.js.map +1 -1
- package/dist/internal/sesame/types.d.ts +0 -2
- package/dist/internal/sesame/types.d.ts.map +1 -1
- package/dist/internal/sesame/types.js +0 -2
- package/dist/internal/sesame/types.js.map +1 -1
- package/dist/media/index.d.ts +0 -1
- package/dist/media/index.d.ts.map +1 -1
- package/dist/media/index.js +0 -1
- package/dist/media/index.js.map +1 -1
- package/dist/remote/relay/convex/backend.d.ts +2 -2
- package/dist/remote/relay/convex/backend.d.ts.map +1 -1
- package/dist/remote/relay/convex/backend.js +1 -1
- package/dist/remote/relay/convex/backend.js.map +1 -1
- package/dist/remote/relay/convex/component/_generated/component.d.ts +2 -2
- package/dist/remote/relay/convex/component/_generated/component.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/messages.d.ts +2 -2
- package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/messages.js +1 -1
- package/dist/remote/relay/convex/component/messages.js.map +1 -1
- package/dist/remote/relay/convex/component/schema.d.ts +2 -2
- package/dist/remote/relay/convex/component/schema.js +1 -1
- package/dist/remote/relay/convex/component/schema.js.map +1 -1
- package/dist/utils/retry.d.ts +2 -1
- package/dist/utils/retry.d.ts.map +1 -1
- package/dist/utils/retry.js +2 -1
- package/dist/utils/retry.js.map +1 -1
- package/docs/ASSURANCE.md +11 -5
- package/docs/CLIENT_COMPOSITION.md +3 -0
- package/docs/DOCUMENTATION_STANDARDS.md +28 -0
- package/docs/ERROR_HANDLING.md +91 -60
- package/docs/GETTING_STARTED.md +20 -1
- package/docs/INTERFACES.md +5 -0
- package/docs/PACKAGE_SURFACE.md +1 -0
- package/docs/PROTOCOL_POLICY.md +6 -0
- package/docs/RECIPES.md +9 -0
- package/encoding/README.md +1 -0
- package/files/README.md +1 -0
- package/groups/README.md +1 -0
- package/keys/README.md +2 -0
- package/local/store/README.md +2 -0
- package/local/store/expo/README.md +2 -0
- package/local/store/memory/README.md +2 -0
- package/local/store/node/README.md +1 -0
- package/local/store/react-native/README.md +2 -0
- package/local/store/web/README.md +1 -0
- package/local/vault/README.md +1 -0
- package/media/README.md +2 -0
- package/package.json +4 -2
- package/profile/README.md +1 -0
- package/remote/README.md +6 -0
- package/remote/object-store/README.md +1 -0
- package/remote/object-store/convex-r2/README.md +2 -0
- package/remote/object-store/s3/README.md +1 -0
- package/remote/relay/README.md +2 -0
- package/remote/relay/convex/README.md +1 -0
- package/remote/relay/convex/component/README.md +9 -0
- package/remote/relay/memory/README.md +2 -0
- package/safety/README.md +1 -0
- package/sealed-sender/README.md +1 -0
- package/types/README.md +1 -0
- package/username/README.md +1 -0
- package/utils/README.md +1 -0
- package/zk/README.md +1 -0
package/docs/ERROR_HANDLING.md
CHANGED
|
@@ -14,13 +14,14 @@ The library uses a structured error system with stable programmatic codes:
|
|
|
14
14
|
|
|
15
15
|
### EncryptionError (Base Class)
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
Every error in the `EncryptionErrorCode` family extends `EncryptionError`:
|
|
18
18
|
|
|
19
|
+
<!-- doc-snippet:skip requires-existing-client-and-session -->
|
|
19
20
|
```typescript
|
|
20
21
|
import { EncryptionError, EncryptionErrorCode } from '@open-e2ee/signal-protocol-sdk';
|
|
21
22
|
|
|
22
23
|
try {
|
|
23
|
-
await signal.encryptMessage(
|
|
24
|
+
await signal.encryptMessage(remoteAddress, plaintext);
|
|
24
25
|
} catch (error) {
|
|
25
26
|
if (error instanceof EncryptionError) {
|
|
26
27
|
console.log('Error code:', error.code);
|
|
@@ -36,11 +37,12 @@ try {
|
|
|
36
37
|
|
|
37
38
|
Thrown when an identity key is not trusted. Requires user intervention (safety number verification).
|
|
38
39
|
|
|
40
|
+
<!-- doc-snippet:skip requires-untrusted-identity-fixture -->
|
|
39
41
|
```typescript
|
|
40
42
|
import { isUntrustedIdentityError } from '@open-e2ee/signal-protocol-sdk';
|
|
41
43
|
|
|
42
44
|
try {
|
|
43
|
-
await signal.establishSession(
|
|
45
|
+
await signal.establishSession(remoteAddress, bundle);
|
|
44
46
|
} catch (error) {
|
|
45
47
|
if (isUntrustedIdentityError(error)) {
|
|
46
48
|
// Show safety number verification UI
|
|
@@ -61,57 +63,92 @@ survives that nothing produces. A code documented here is therefore one an
|
|
|
61
63
|
application can branch on. The check runs on every change, with the rest of the
|
|
62
64
|
checks that [ASSURANCE.md](./ASSURANCE.md) describes.
|
|
63
65
|
|
|
64
|
-
The tables
|
|
65
|
-
|
|
66
|
+
The tables list the complete `EncryptionErrorCode` enum. The error-surface check
|
|
67
|
+
holds each member to a production construction site.
|
|
66
68
|
|
|
67
69
|
### Session Errors
|
|
68
70
|
|
|
69
|
-
| Code
|
|
70
|
-
|
|
71
|
-
| `SESSION_NOT_FOUND` | No session exists for the address | Establish new session
|
|
72
|
-
| `SESSION_CORRUPTED` |
|
|
71
|
+
| Code | Cause | Application response |
|
|
72
|
+
|---|---|---|
|
|
73
|
+
| `SESSION_NOT_FOUND` | No session exists for the address. | Establish a new session. |
|
|
74
|
+
| `SESSION_CORRUPTED` | Stored session data is invalid. | Delete the damaged session, then establish one. |
|
|
75
|
+
| `RECIPIENT_NOT_REGISTERED` | The recipient has no published prekey bundle. | Wait for recipient registration, then retry. |
|
|
76
|
+
| `PREKEY_FETCH_RATE_LIMITED` | The relay refused another prekey fetch. | Wait for the relay limit, then retry. |
|
|
77
|
+
| `SESSION_ESTABLISHMENT_FAILED` | Session setup failed after retries. | Inspect `originalError`, then retry after its cause is fixed. |
|
|
73
78
|
|
|
74
79
|
### Message Errors
|
|
75
80
|
|
|
76
|
-
| Code
|
|
77
|
-
|
|
78
|
-
| `INVALID_CIPHERTEXT`
|
|
79
|
-
| `DECRYPTION_FAILED`
|
|
80
|
-
| `ENCRYPTION_FAILED`
|
|
81
|
-
| `MESSAGE_DUPLICATE`
|
|
82
|
-
| `TOO_MANY_SKIPPED_MESSAGES` |
|
|
81
|
+
| Code | Cause | Application response |
|
|
82
|
+
|---|---|---|
|
|
83
|
+
| `INVALID_CIPHERTEXT` | The ciphertext format is invalid. | Reject the message. |
|
|
84
|
+
| `DECRYPTION_FAILED` | Available session state could not decrypt the message. | Let the retry flow recover, or inspect the session state. |
|
|
85
|
+
| `ENCRYPTION_FAILED` | The SDK could not encrypt the message. | Inspect the session state and `originalError`. |
|
|
86
|
+
| `MESSAGE_DUPLICATE` | The session processed this message before. | Discard the duplicate. |
|
|
87
|
+
| `TOO_MANY_SKIPPED_MESSAGES` | The message exceeded the skipped-key bound. | Reset the affected session. |
|
|
88
|
+
| `REPLAY_DETECTED` | Envelope and encrypted-content timestamps differ. | Reject the message as a replay. |
|
|
89
|
+
| `SENDER_KEY_EXPIRED` | The sender key exceeded its rotation period. | Rotate and redistribute the sender key. |
|
|
83
90
|
|
|
84
|
-
### Identity
|
|
91
|
+
### Identity and Trust Errors
|
|
85
92
|
|
|
86
|
-
| Code
|
|
87
|
-
|
|
88
|
-
| `UNTRUSTED_IDENTITY`
|
|
89
|
-
| `
|
|
93
|
+
| Code | Cause | Application response |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| `UNTRUSTED_IDENTITY` | The peer identity is unverified or changed. | Verify the safety number before acceptance. |
|
|
96
|
+
| `IDENTITY_MISMATCH` | The message identity does not match the expected sender. | Reject the message and inspect the identity state. |
|
|
97
|
+
| `SIGNATURE_VERIFICATION_FAILED` | A signature is invalid. | Reject the signed value. |
|
|
90
98
|
|
|
91
|
-
###
|
|
99
|
+
### Prekey and Session Establishment Errors
|
|
92
100
|
|
|
93
|
-
| Code
|
|
94
|
-
|
|
95
|
-
| `INVALID_PREKEY_BUNDLE` |
|
|
96
|
-
| `PREKEY_NOT_FOUND`
|
|
101
|
+
| Code | Cause | Application response |
|
|
102
|
+
|---|---|---|
|
|
103
|
+
| `INVALID_PREKEY_BUNDLE` | A prekey bundle is malformed or inconsistent. | Reject it and fetch a current bundle. |
|
|
104
|
+
| `PREKEY_NOT_FOUND` | The required prekey is unavailable. | Fetch current peer keys or rotate local keys, as the operation requires. |
|
|
105
|
+
| `PREKEY_ROTATION_REQUIRED` | A local signed or Kyber prekey is too old. | Rotate prekeys before another send. |
|
|
97
106
|
|
|
98
107
|
### Ratchet Errors
|
|
99
108
|
|
|
100
|
-
| Code
|
|
101
|
-
|
|
102
|
-
| `
|
|
109
|
+
| Code | Cause | Application response |
|
|
110
|
+
|---|---|---|
|
|
111
|
+
| `COUNTER_OVERFLOW` | A message counter reached its safe bound. | Rotate the session or ratchet epoch. |
|
|
112
|
+
| `INVALID_DH_KEY` | A DH public key is malformed or invalid. | Reject the key and its message. |
|
|
103
113
|
|
|
104
114
|
### Storage Errors
|
|
105
115
|
|
|
106
|
-
| Code
|
|
107
|
-
|
|
108
|
-
| `KEY_STORAGE_ERROR`
|
|
109
|
-
| `STORAGE_QUOTA_EXCEEDED` | The
|
|
116
|
+
| Code | Cause | Application response |
|
|
117
|
+
|---|---|---|
|
|
118
|
+
| `KEY_STORAGE_ERROR` | A key-storage operation failed. | Inspect `originalError`, then retry or reinitialize storage. |
|
|
119
|
+
| `STORAGE_QUOTA_EXCEEDED` | The storage origin ran out of space. | Free storage space, then retry the rejected write. |
|
|
120
|
+
|
|
121
|
+
### Initialization and Protocol Policy Errors
|
|
122
|
+
|
|
123
|
+
| Code | Cause | Application response |
|
|
124
|
+
|---|---|---|
|
|
125
|
+
| `INITIALIZATION_FAILED` | Client or group initialization failed. | Inspect `originalError` and the configuration. |
|
|
126
|
+
| `PQXDH_REQUIRED` | Policy requires PQXDH, but the peer lacks required keys. | Wait for new peer keys or queue the message. |
|
|
127
|
+
| `PQXDH_FAILED` | The PQXDH exchange failed. | Abort setup and inspect `originalError`. |
|
|
128
|
+
| `TRIPLE_RATCHET_REQUIRED` | Triple Ratchet policy lacks a PQXDH session. | Establish the required PQXDH session first. |
|
|
129
|
+
|
|
130
|
+
### SPQR Errors
|
|
131
|
+
|
|
132
|
+
| Code | Cause | Application response |
|
|
133
|
+
|---|---|---|
|
|
134
|
+
| `SPQR_EPOCH_OUT_OF_RANGE` | The requested epoch is too old or not established. | Reject the message and synchronize session state. |
|
|
135
|
+
| `SPQR_MESSAGE_JUMP_TOO_LARGE` | The message jump exceeds the configured bound. | Reject the message. |
|
|
136
|
+
| `SPQR_COUNTER_OVERFLOW` | The SPQR message counter reached its bound. | Rotate the SPQR epoch. |
|
|
137
|
+
| `SPQR_INVALID_CIPHERTEXT` | An SPQR ML-KEM ciphertext has an invalid form. | Reject the message. |
|
|
138
|
+
| `SPQR_VERSION_MISMATCH` | Peer and local SPQR version ranges do not overlap. | Update the peer or the required protocol policy. |
|
|
139
|
+
|
|
140
|
+
### Sealed Sender and State Errors
|
|
141
|
+
|
|
142
|
+
| Code | Cause | Application response |
|
|
143
|
+
|---|---|---|
|
|
144
|
+
| `SEALED_SENDER_AUTH_FAILED` | The relay rejected sealed-sender authorization. | Reauthorize or use identified delivery when policy permits it. |
|
|
145
|
+
| `INVALID_STATE` | The requested operation is invalid for current state. | Correct the call order or synchronize state. |
|
|
110
146
|
|
|
111
147
|
## Error Handling Patterns
|
|
112
148
|
|
|
113
149
|
### One Handler for Every Error
|
|
114
150
|
|
|
151
|
+
<!-- doc-snippet:skip application-handler-fragment -->
|
|
115
152
|
```typescript
|
|
116
153
|
import {
|
|
117
154
|
EncryptionError,
|
|
@@ -170,6 +207,7 @@ async function handleEncryptionError(error: unknown): Promise<void> {
|
|
|
170
207
|
|
|
171
208
|
The library provides a built-in retry utility:
|
|
172
209
|
|
|
210
|
+
<!-- doc-snippet:skip requires-existing-client -->
|
|
173
211
|
```typescript
|
|
174
212
|
import { withRetry } from '@open-e2ee/signal-protocol-sdk/utils/retry';
|
|
175
213
|
|
|
@@ -188,35 +226,43 @@ await withRetry(
|
|
|
188
226
|
|
|
189
227
|
### Session Recovery Pattern
|
|
190
228
|
|
|
229
|
+
<!-- doc-snippet:skip application-session-recovery-fragment -->
|
|
191
230
|
```typescript
|
|
231
|
+
import {
|
|
232
|
+
EncryptionError,
|
|
233
|
+
EncryptionErrorCode,
|
|
234
|
+
ProtocolAddress,
|
|
235
|
+
type SignalProtocolClient,
|
|
236
|
+
} from '@open-e2ee/signal-protocol-sdk';
|
|
237
|
+
|
|
192
238
|
async function ensureSession(
|
|
193
239
|
signal: SignalProtocolClient,
|
|
194
240
|
userId: string,
|
|
195
241
|
deviceId: number
|
|
196
242
|
): Promise<void> {
|
|
197
|
-
const
|
|
243
|
+
const remoteAddress = ProtocolAddress.create(userId, deviceId);
|
|
198
244
|
|
|
199
245
|
try {
|
|
200
|
-
const hasSession = await signal.hasSession(
|
|
246
|
+
const hasSession = await signal.hasSession(remoteAddress);
|
|
201
247
|
if (!hasSession) {
|
|
202
248
|
// Fetch prekey bundle and establish session
|
|
203
249
|
const bundle = await fetchPreKeyBundle(userId, deviceId);
|
|
204
|
-
await signal.establishSession(
|
|
250
|
+
await signal.establishSession(remoteAddress, bundle);
|
|
205
251
|
}
|
|
206
252
|
} catch (error) {
|
|
207
253
|
if (error instanceof EncryptionError) {
|
|
208
254
|
switch (error.code) {
|
|
209
255
|
case EncryptionErrorCode.SESSION_CORRUPTED:
|
|
210
256
|
// Delete corrupted session and retry
|
|
211
|
-
await signal.deleteSession(
|
|
257
|
+
await signal.deleteSession(remoteAddress);
|
|
212
258
|
const bundle = await fetchPreKeyBundle(userId, deviceId);
|
|
213
|
-
await signal.establishSession(
|
|
259
|
+
await signal.establishSession(remoteAddress, bundle);
|
|
214
260
|
break;
|
|
215
261
|
|
|
216
262
|
case EncryptionErrorCode.INVALID_PREKEY_BUNDLE:
|
|
217
263
|
// Bundle was invalid, try fetching again
|
|
218
264
|
const newBundle = await fetchPreKeyBundle(userId, deviceId);
|
|
219
|
-
await signal.establishSession(
|
|
265
|
+
await signal.establishSession(remoteAddress, newBundle);
|
|
220
266
|
break;
|
|
221
267
|
|
|
222
268
|
default:
|
|
@@ -233,6 +279,7 @@ async function ensureSession(
|
|
|
233
279
|
|
|
234
280
|
The library includes structured logging for errors:
|
|
235
281
|
|
|
282
|
+
<!-- doc-snippet:skip requires-platform-adapters -->
|
|
236
283
|
```typescript
|
|
237
284
|
import { SignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
|
|
238
285
|
|
|
@@ -256,20 +303,19 @@ void signal;
|
|
|
256
303
|
|
|
257
304
|
### 1. Always Use Type Guards
|
|
258
305
|
|
|
306
|
+
<!-- doc-snippet:skip type-guard-comparison-fragment -->
|
|
259
307
|
```typescript
|
|
260
|
-
//
|
|
308
|
+
// Prefer the exported guard so narrowing stays behind one public function.
|
|
261
309
|
if (isUntrustedIdentityError(error)) {
|
|
262
310
|
// Handle untrusted identity
|
|
263
311
|
}
|
|
264
312
|
|
|
265
|
-
//
|
|
266
|
-
if (error instanceof UntrustedIdentityError) {
|
|
267
|
-
// This might fail if bundled differently
|
|
268
|
-
}
|
|
313
|
+
// Current guards delegate to instanceof. Bundle one copy of the SDK.
|
|
269
314
|
```
|
|
270
315
|
|
|
271
316
|
### 2. Preserve Error Context
|
|
272
317
|
|
|
318
|
+
<!-- doc-snippet:skip error-wrapping-comparison-fragment -->
|
|
273
319
|
```typescript
|
|
274
320
|
// Good: Wrap errors with context
|
|
275
321
|
throw new EncryptionError('Failed to establish session', EncryptionErrorCode.SESSION_NOT_FOUND, {
|
|
@@ -284,6 +330,7 @@ throw new Error('Session error');
|
|
|
284
330
|
|
|
285
331
|
### 3. Handle Security-Critical Errors Prominently
|
|
286
332
|
|
|
333
|
+
<!-- doc-snippet:skip requires-identity-change-fixture -->
|
|
287
334
|
```typescript
|
|
288
335
|
// Identity changes require prominent user warning
|
|
289
336
|
if (isUntrustedIdentityError(error)) {
|
|
@@ -304,22 +351,6 @@ if (isUntrustedIdentityError(error)) {
|
|
|
304
351
|
}
|
|
305
352
|
```
|
|
306
353
|
|
|
307
|
-
### 4. Clean Up on Errors
|
|
308
|
-
|
|
309
|
-
```typescript
|
|
310
|
-
let session = null;
|
|
311
|
-
try {
|
|
312
|
-
session = await signal.establishSession(sessionId, remoteAddress, bundle);
|
|
313
|
-
// Use session...
|
|
314
|
-
} catch (error) {
|
|
315
|
-
// Clean up partial state
|
|
316
|
-
if (session) {
|
|
317
|
-
await signal.deleteSession(sessionId);
|
|
318
|
-
}
|
|
319
|
-
throw error;
|
|
320
|
-
}
|
|
321
|
-
```
|
|
322
|
-
|
|
323
354
|
## See Also
|
|
324
355
|
|
|
325
356
|
- [SECURITY.md](./SECURITY.md) - Security guidelines
|
package/docs/GETTING_STARTED.md
CHANGED
|
@@ -107,7 +107,7 @@ This is the target DX the package moves toward. It appears here so app
|
|
|
107
107
|
developers can understand the intended mental model. The current stable API
|
|
108
108
|
still uses `storage`, `remoteObjectStore`, hooks, and transition-only media helpers.
|
|
109
109
|
|
|
110
|
-
<!-- doc-snippet:
|
|
110
|
+
<!-- doc-snippet:planned target-message-api unshipped="@open-e2ee/signal-protocol-sdk/device/storage/memory" -->
|
|
111
111
|
```ts
|
|
112
112
|
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
113
113
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
@@ -161,6 +161,7 @@ await delivered;
|
|
|
161
161
|
|
|
162
162
|
The production shape uses the same message API with platform adapters:
|
|
163
163
|
|
|
164
|
+
<!-- doc-snippet:planned target-message-api-platform-adapters unshipped="@open-e2ee/signal-protocol-sdk/device/storage/expo" -->
|
|
164
165
|
```ts
|
|
165
166
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
166
167
|
import { createExpoDeviceStorage } from "@open-e2ee/signal-protocol-sdk/device/storage/expo";
|
|
@@ -185,6 +186,7 @@ Attachments use the same message API. On Expo, pass the picker URI. The Signal
|
|
|
185
186
|
Protocol client copies or persists the bytes through `deviceStorage.files`
|
|
186
187
|
before upload, so retry can continue after restart:
|
|
187
188
|
|
|
189
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
188
190
|
```ts
|
|
189
191
|
await signal.messages.send({
|
|
190
192
|
conversationId: "dm:alice_bob",
|
|
@@ -203,6 +205,7 @@ await signal.messages.send({
|
|
|
203
205
|
|
|
204
206
|
On the web, pass the browser file object:
|
|
205
207
|
|
|
208
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
206
209
|
```ts
|
|
207
210
|
await signal.messages.send({
|
|
208
211
|
conversationId,
|
|
@@ -314,6 +317,7 @@ Use the protocol storage adapter for your runtime and the relay adapter for your
|
|
|
314
317
|
backend. For the Signal Protocol stack, that is Expo local storage and a Convex
|
|
315
318
|
relay:
|
|
316
319
|
|
|
320
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
317
321
|
```ts
|
|
318
322
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
319
323
|
import { expoStore } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
|
|
@@ -353,6 +357,7 @@ provisioning belong to the application bootstrap.
|
|
|
353
357
|
|
|
354
358
|
Register a receive hook before starting the relay subscription:
|
|
355
359
|
|
|
360
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
356
361
|
```ts
|
|
357
362
|
signal.registerHook("onMessageDecrypted", async (message) => {
|
|
358
363
|
// Decrypted content belongs in your app database, not in the relay.
|
|
@@ -377,12 +382,14 @@ and hands the app a `DecryptedEnvelope`.
|
|
|
377
382
|
|
|
378
383
|
Send by recipient user ID for normal one-to-one and multi-device delivery:
|
|
379
384
|
|
|
385
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
380
386
|
```ts
|
|
381
387
|
await signal.send("bob", "hello");
|
|
382
388
|
```
|
|
383
389
|
|
|
384
390
|
For structured app messages, pass an object:
|
|
385
391
|
|
|
392
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
386
393
|
```ts
|
|
387
394
|
await signal.send("bob", {
|
|
388
395
|
body: "hello",
|
|
@@ -400,6 +407,7 @@ The final public DX should not expose both `signal.media.*` and message
|
|
|
400
407
|
attachment helpers. The planned replacement is message-scoped attachment
|
|
401
408
|
handling.
|
|
402
409
|
|
|
410
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
403
411
|
```ts
|
|
404
412
|
import { media } from "@open-e2ee/signal-protocol-sdk";
|
|
405
413
|
import { convexR2ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2";
|
|
@@ -431,6 +439,7 @@ const signal = await createSignalProtocolClient({
|
|
|
431
439
|
For Amazon S3 or S3-compatible storage, use the framework-neutral adapter with
|
|
432
440
|
an authenticated application-backend broker:
|
|
433
441
|
|
|
442
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
434
443
|
```ts
|
|
435
444
|
import { s3ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/s3";
|
|
436
445
|
|
|
@@ -450,6 +459,7 @@ operations.
|
|
|
450
459
|
|
|
451
460
|
Send bytes when the attachment travels as its own encrypted message:
|
|
452
461
|
|
|
462
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
453
463
|
```ts
|
|
454
464
|
const controller = new AbortController();
|
|
455
465
|
|
|
@@ -481,6 +491,7 @@ await signal.send("bob", photoBytes, {
|
|
|
481
491
|
Upload first when your app message format embeds the attachment pointer inside a
|
|
482
492
|
larger payload:
|
|
483
493
|
|
|
494
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
484
495
|
```ts
|
|
485
496
|
const attachment = await signal.uploadAttachment(photoBytes, {
|
|
486
497
|
mimeType: "image/jpeg",
|
|
@@ -530,6 +541,7 @@ adapter. The target message-first API moves that responsibility behind
|
|
|
530
541
|
`deviceStorage.messages`. The operation tries the upload when it is due and
|
|
531
542
|
returns either a completed pointer or a pending job id for later recovery:
|
|
532
543
|
|
|
544
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
533
545
|
```ts
|
|
534
546
|
const upload = await signal.media.upload(
|
|
535
547
|
{
|
|
@@ -554,6 +566,7 @@ if (upload.status === "completed") {
|
|
|
554
566
|
Run pending durable media work on app startup, foreground resume, or from a
|
|
555
567
|
background task:
|
|
556
568
|
|
|
569
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
557
570
|
```ts
|
|
558
571
|
await signal.media.processPending({
|
|
559
572
|
limit: 10,
|
|
@@ -566,6 +579,7 @@ On receive, ask the media planner what work this device should do. Your app
|
|
|
566
579
|
supplies the IDs it has already processed or cached. The Signal Protocol package
|
|
567
580
|
returns the safe next step, and it does not take ownership of your app database:
|
|
568
581
|
|
|
582
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
569
583
|
```ts
|
|
570
584
|
const mediaWork = media.planMediaAttachmentProcessing({
|
|
571
585
|
attachment,
|
|
@@ -609,6 +623,7 @@ If the planner says this device needs media bytes, pass the decrypted attachment
|
|
|
609
623
|
pointer back to the client. The client downloads encrypted blob bytes, verifies
|
|
610
624
|
the digest, authenticates the stream, and returns plaintext bytes:
|
|
611
625
|
|
|
626
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
612
627
|
```ts
|
|
613
628
|
if (mediaWork.shouldDownload) {
|
|
614
629
|
const downloaded = await signal.downloadAttachment(attachment, {
|
|
@@ -640,6 +655,7 @@ if (mediaWork.shouldDownload) {
|
|
|
640
655
|
If the attachment is view-once, plan the local cleanup and linked-device sync
|
|
641
656
|
after the user opens it:
|
|
642
657
|
|
|
658
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
643
659
|
```ts
|
|
644
660
|
const opened = media.planMediaAttachmentOpen({
|
|
645
661
|
attachment,
|
|
@@ -663,6 +679,7 @@ if (opened.cleanup?.deleteRemoteBlob) {
|
|
|
663
679
|
A message delete or expiration can remove media on this account's linked
|
|
664
680
|
devices. Plan and sync the deletion after your app applies the local cleanup:
|
|
665
681
|
|
|
682
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
666
683
|
```ts
|
|
667
684
|
const deleteSync = media.planMediaAttachmentDeleteSync({
|
|
668
685
|
attachment,
|
|
@@ -676,6 +693,7 @@ await signal.syncMediaAttachmentDeleteToLinkedDevices(deleteSync);
|
|
|
676
693
|
|
|
677
694
|
When a worker must do the cleanup, use the durable client operation:
|
|
678
695
|
|
|
696
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
679
697
|
```ts
|
|
680
698
|
await signal.media.cleanup(
|
|
681
699
|
{
|
|
@@ -697,6 +715,7 @@ await signal.media.cleanup(
|
|
|
697
715
|
|
|
698
716
|
The default is:
|
|
699
717
|
|
|
718
|
+
<!-- doc-snippet:illustrative config-object-fragment -->
|
|
700
719
|
```ts
|
|
701
720
|
protocol: {
|
|
702
721
|
postQuantum: 'required',
|
package/docs/INTERFACES.md
CHANGED
|
@@ -31,6 +31,7 @@ requirements described below.
|
|
|
31
31
|
`ISignalProtocolLocalStore` persists the current device's identities, prekeys, sessions,
|
|
32
32
|
sender keys, contact trust, retry records, and operational metadata.
|
|
33
33
|
|
|
34
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
34
35
|
```ts
|
|
35
36
|
import type { ISignalProtocolLocalStore } from "@open-e2ee/signal-protocol-sdk/local/store";
|
|
36
37
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
@@ -62,6 +63,7 @@ and their status.
|
|
|
62
63
|
secrets that must live outside the main local store, such as a database
|
|
63
64
|
encryption key.
|
|
64
65
|
|
|
66
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
65
67
|
```ts
|
|
66
68
|
import type { ISignalProtocolLocalSecretVault } from "@open-e2ee/signal-protocol-sdk";
|
|
67
69
|
|
|
@@ -83,6 +85,7 @@ selected platform service and host configuration. See the
|
|
|
83
85
|
device registration, account identity state, public prekeys, encrypted-envelope
|
|
84
86
|
delivery, provisioning, key rotation, and encrypted group coordination.
|
|
85
87
|
|
|
88
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
86
89
|
```ts
|
|
87
90
|
import type { ISignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/relay";
|
|
88
91
|
import {
|
|
@@ -120,6 +123,7 @@ See the [relay guide](../remote/relay/README.md).
|
|
|
120
123
|
`SignalProtocolRemoteObjectStore` supplies short-lived upload and download operations
|
|
121
124
|
for already encrypted objects. It is provider-neutral and optional.
|
|
122
125
|
|
|
126
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
123
127
|
```ts
|
|
124
128
|
import type {
|
|
125
129
|
SignalProtocolRemoteObjectStore,
|
|
@@ -155,6 +159,7 @@ See the [remote object-store guide](../remote/object-store/README.md).
|
|
|
155
159
|
Application content remains outside the infrastructure adapters. Configure
|
|
156
160
|
media lifecycle callbacks and client hooks at the client boundary:
|
|
157
161
|
|
|
162
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
158
163
|
```ts
|
|
159
164
|
const client = await createSignalProtocolClient({
|
|
160
165
|
identity: { userId },
|
package/docs/PACKAGE_SURFACE.md
CHANGED
package/docs/PROTOCOL_POLICY.md
CHANGED
|
@@ -10,6 +10,7 @@ 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
14
|
```ts
|
|
14
15
|
protocol: {
|
|
15
16
|
postQuantum: 'required',
|
|
@@ -25,6 +26,7 @@ the current app.
|
|
|
25
26
|
|
|
26
27
|
## Required
|
|
27
28
|
|
|
29
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
28
30
|
```ts
|
|
29
31
|
await createSignalProtocolClient({
|
|
30
32
|
identity: { userId },
|
|
@@ -39,6 +41,7 @@ closed.
|
|
|
39
41
|
|
|
40
42
|
## Compatible
|
|
41
43
|
|
|
44
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
42
45
|
```ts
|
|
43
46
|
await createSignalProtocolClient({
|
|
44
47
|
identity: { userId },
|
|
@@ -61,6 +64,7 @@ Compatible mode does not allow downgrade recovery:
|
|
|
61
64
|
|
|
62
65
|
## Braid Policy
|
|
63
66
|
|
|
67
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
64
68
|
```ts
|
|
65
69
|
await createSignalProtocolClient({
|
|
66
70
|
identity: { userId },
|
|
@@ -78,6 +82,7 @@ not stock FIPS 203.
|
|
|
78
82
|
|
|
79
83
|
See [Deviations §4.1](./DEVIATIONS.md#41-the-hek-operand-order-diverges).
|
|
80
84
|
|
|
85
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
81
86
|
```ts
|
|
82
87
|
await createSignalProtocolClient({
|
|
83
88
|
identity: { userId },
|
|
@@ -94,6 +99,7 @@ product-reviewed constraints, not downgrade recovery.
|
|
|
94
99
|
|
|
95
100
|
Use string literals directly or the exported constant object:
|
|
96
101
|
|
|
102
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
97
103
|
```ts
|
|
98
104
|
import { BraidPolicy, PostQuantumPolicy, createSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
|
|
99
105
|
|
package/docs/RECIPES.md
CHANGED
|
@@ -95,6 +95,7 @@ through the `onMessageDecrypted` hook.
|
|
|
95
95
|
|
|
96
96
|
## Production composition with Convex + Expo
|
|
97
97
|
|
|
98
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
98
99
|
```ts
|
|
99
100
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
100
101
|
import {
|
|
@@ -159,6 +160,7 @@ const bob = await createSignalProtocolClient({
|
|
|
159
160
|
|
|
160
161
|
## App message flow
|
|
161
162
|
|
|
163
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
162
164
|
```ts
|
|
163
165
|
const signal = await createSignalProtocolClient({
|
|
164
166
|
identity: { userId },
|
|
@@ -189,6 +191,7 @@ message storage through hooks.
|
|
|
189
191
|
|
|
190
192
|
## Protocol policy
|
|
191
193
|
|
|
194
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
192
195
|
```ts
|
|
193
196
|
await createSignalProtocolClient({
|
|
194
197
|
identity: { userId },
|
|
@@ -205,6 +208,7 @@ without post-quantum material fail closed, and PQ sessions use the SDK's
|
|
|
205
208
|
ML-KEM Braid SPQR profile. See the [protocol policy](./PROTOCOL_POLICY.md) for
|
|
206
209
|
supported choices.
|
|
207
210
|
|
|
211
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
208
212
|
```ts
|
|
209
213
|
await createSignalProtocolClient({
|
|
210
214
|
identity: { userId },
|
|
@@ -220,6 +224,7 @@ await createSignalProtocolClient({
|
|
|
220
224
|
supports them. It only allows classical compatibility for peers that advertise
|
|
221
225
|
no post-quantum material at all.
|
|
222
226
|
|
|
227
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
223
228
|
```ts
|
|
224
229
|
await createSignalProtocolClient({
|
|
225
230
|
identity: { userId },
|
|
@@ -237,6 +242,7 @@ PQXDH strictness.
|
|
|
237
242
|
|
|
238
243
|
## Multi-device send
|
|
239
244
|
|
|
245
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
240
246
|
```ts
|
|
241
247
|
const result = await signal.send(recipientUserId, "hello");
|
|
242
248
|
await appMessages.insertOutgoing({
|
|
@@ -250,6 +256,7 @@ await appMessages.insertOutgoing({
|
|
|
250
256
|
|
|
251
257
|
## Direct device session
|
|
252
258
|
|
|
259
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
253
260
|
```ts
|
|
254
261
|
import { ProtocolAddress } from "@open-e2ee/signal-protocol-sdk";
|
|
255
262
|
|
|
@@ -260,6 +267,7 @@ await signal.encryptMessage(bob, "linked-device hello");
|
|
|
260
267
|
|
|
261
268
|
## Username and ZK helpers
|
|
262
269
|
|
|
270
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
263
271
|
```ts
|
|
264
272
|
import {
|
|
265
273
|
hashUsername,
|
|
@@ -274,6 +282,7 @@ const version = computeProfileKeyVersion(profileKeyBytes, userIdBytes);
|
|
|
274
282
|
|
|
275
283
|
## Encrypted attachments
|
|
276
284
|
|
|
285
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
277
286
|
```ts
|
|
278
287
|
import { media } from "@open-e2ee/signal-protocol-sdk";
|
|
279
288
|
|
package/encoding/README.md
CHANGED
package/files/README.md
CHANGED
package/groups/README.md
CHANGED
package/keys/README.md
CHANGED
|
@@ -13,6 +13,7 @@ prevents storage and relay adapters from inventing incompatible key shapes.
|
|
|
13
13
|
|
|
14
14
|
## Usage
|
|
15
15
|
|
|
16
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
16
17
|
```ts
|
|
17
18
|
import {
|
|
18
19
|
createCompositeIdentityV1,
|
|
@@ -35,6 +36,7 @@ advanced lifecycle integrations.
|
|
|
35
36
|
|
|
36
37
|
`CompositeIdentityV1` is the canonical public trust object:
|
|
37
38
|
|
|
39
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
38
40
|
```ts
|
|
39
41
|
interface CompositeIdentityV1 {
|
|
40
42
|
readonly version: 1;
|
package/local/store/README.md
CHANGED
|
@@ -142,6 +142,7 @@ state, retry message records, and recovery helpers.
|
|
|
142
142
|
|
|
143
143
|
## Composition
|
|
144
144
|
|
|
145
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
145
146
|
```ts
|
|
146
147
|
import { SignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
|
|
147
148
|
import { ExpoSignalProtocolStore } from '@open-e2ee/signal-protocol-sdk/local/store/expo';
|
|
@@ -169,6 +170,7 @@ An `ISignalProtocolLocalStore` implementation must preserve:
|
|
|
169
170
|
|
|
170
171
|
The current persisted session record shape is version `4`:
|
|
171
172
|
|
|
173
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
172
174
|
```ts
|
|
173
175
|
interface SessionRecord {
|
|
174
176
|
currentSession: SessionState | null;
|
|
@@ -18,6 +18,7 @@ Compose the exported table definitions into the application schema, configure
|
|
|
18
18
|
the database bindings once during bootstrap, and apply the database key before
|
|
19
19
|
the first query:
|
|
20
20
|
|
|
21
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
21
22
|
```ts
|
|
22
23
|
import {
|
|
23
24
|
configureSignalProtocolExpoDbBindings,
|
|
@@ -65,6 +66,7 @@ Do not back these tables up to a server or sync them between devices.
|
|
|
65
66
|
|
|
66
67
|
## Client usage
|
|
67
68
|
|
|
69
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
68
70
|
```ts
|
|
69
71
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
70
72
|
import { expoStore } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
|