@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.
Files changed (77) hide show
  1. package/ADAPTERS.md +7 -0
  2. package/ARCHITECTURE.md +2 -0
  3. package/CHANGELOG.md +33 -0
  4. package/README.md +64 -102
  5. package/SECURITY.md +2 -2
  6. package/TROUBLESHOOTING.md +7 -0
  7. package/blocking/README.md +1 -0
  8. package/client/README.md +10 -0
  9. package/device/README.md +5 -0
  10. package/dist/client/groups.d.ts.map +1 -1
  11. package/dist/client/groups.js +14 -4
  12. package/dist/client/groups.js.map +1 -1
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +3 -4
  15. package/dist/index.js.map +1 -1
  16. package/dist/internal/sesame/types.d.ts +0 -2
  17. package/dist/internal/sesame/types.d.ts.map +1 -1
  18. package/dist/internal/sesame/types.js +0 -2
  19. package/dist/internal/sesame/types.js.map +1 -1
  20. package/dist/media/index.d.ts +0 -1
  21. package/dist/media/index.d.ts.map +1 -1
  22. package/dist/media/index.js +0 -1
  23. package/dist/media/index.js.map +1 -1
  24. package/dist/remote/relay/convex/backend.d.ts +2 -2
  25. package/dist/remote/relay/convex/backend.d.ts.map +1 -1
  26. package/dist/remote/relay/convex/backend.js +1 -1
  27. package/dist/remote/relay/convex/backend.js.map +1 -1
  28. package/dist/remote/relay/convex/component/_generated/component.d.ts +2 -2
  29. package/dist/remote/relay/convex/component/_generated/component.d.ts.map +1 -1
  30. package/dist/remote/relay/convex/component/messages.d.ts +2 -2
  31. package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
  32. package/dist/remote/relay/convex/component/messages.js +1 -1
  33. package/dist/remote/relay/convex/component/messages.js.map +1 -1
  34. package/dist/remote/relay/convex/component/schema.d.ts +2 -2
  35. package/dist/remote/relay/convex/component/schema.js +1 -1
  36. package/dist/remote/relay/convex/component/schema.js.map +1 -1
  37. package/dist/utils/retry.d.ts +2 -1
  38. package/dist/utils/retry.d.ts.map +1 -1
  39. package/dist/utils/retry.js +2 -1
  40. package/dist/utils/retry.js.map +1 -1
  41. package/docs/ASSURANCE.md +11 -5
  42. package/docs/CLIENT_COMPOSITION.md +3 -0
  43. package/docs/DOCUMENTATION_STANDARDS.md +28 -0
  44. package/docs/ERROR_HANDLING.md +91 -60
  45. package/docs/GETTING_STARTED.md +20 -1
  46. package/docs/INTERFACES.md +5 -0
  47. package/docs/PACKAGE_SURFACE.md +1 -0
  48. package/docs/PROTOCOL_POLICY.md +6 -0
  49. package/docs/RECIPES.md +9 -0
  50. package/encoding/README.md +1 -0
  51. package/files/README.md +1 -0
  52. package/groups/README.md +1 -0
  53. package/keys/README.md +2 -0
  54. package/local/store/README.md +2 -0
  55. package/local/store/expo/README.md +2 -0
  56. package/local/store/memory/README.md +2 -0
  57. package/local/store/node/README.md +1 -0
  58. package/local/store/react-native/README.md +2 -0
  59. package/local/store/web/README.md +1 -0
  60. package/local/vault/README.md +1 -0
  61. package/media/README.md +2 -0
  62. package/package.json +4 -2
  63. package/profile/README.md +1 -0
  64. package/remote/README.md +6 -0
  65. package/remote/object-store/README.md +1 -0
  66. package/remote/object-store/convex-r2/README.md +2 -0
  67. package/remote/object-store/s3/README.md +1 -0
  68. package/remote/relay/README.md +2 -0
  69. package/remote/relay/convex/README.md +1 -0
  70. package/remote/relay/convex/component/README.md +9 -0
  71. package/remote/relay/memory/README.md +2 -0
  72. package/safety/README.md +1 -0
  73. package/sealed-sender/README.md +1 -0
  74. package/types/README.md +1 -0
  75. package/username/README.md +1 -0
  76. package/utils/README.md +1 -0
  77. package/zk/README.md +1 -0
@@ -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
- All signal protocol errors extend `EncryptionError`:
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(sessionId, plaintext);
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(sessionId, remoteAddress, bundle);
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 group the codes an application handles most often. They are not the
65
- whole set: `EncryptionErrorCode` is, and every member of it is reachable.
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 | Description | Recovery |
70
- | ------------------- | --------------------------------- | ----------------------- |
71
- | `SESSION_NOT_FOUND` | No session exists for the address | Establish new session |
72
- | `SESSION_CORRUPTED` | Session data is invalid | Delete and re-establish |
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 | Description | Recovery |
77
- | --------------------------- | --------------------------- | -------------------------- |
78
- | `INVALID_CIPHERTEXT` | Message format is malformed | Request retransmission |
79
- | `DECRYPTION_FAILED` | Could not decrypt message | Check session state |
80
- | `ENCRYPTION_FAILED` | Could not encrypt message | Check session state |
81
- | `MESSAGE_DUPLICATE` | Message already processed | Ignore (replay protection) |
82
- | `TOO_MANY_SKIPPED_MESSAGES` | DoS protection triggered | Reset session |
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 & Trust Errors
91
+ ### Identity and Trust Errors
85
92
 
86
- | Code | Description | Recovery |
87
- | ------------------------------- | --------------------- | ------------------------ |
88
- | `UNTRUSTED_IDENTITY` | Identity not verified, including after it changed | Verify safety number |
89
- | `SIGNATURE_VERIFICATION_FAILED` | Signature is invalid | Reject message |
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
- ### PreKey & Session Establishment Errors
99
+ ### Prekey and Session Establishment Errors
92
100
 
93
- | Code | Description | Recovery |
94
- | ----------------------- | -------------------- | ---------------- |
95
- | `INVALID_PREKEY_BUNDLE` | Bundle is malformed | Fetch new bundle |
96
- | `PREKEY_NOT_FOUND` | PreKey not available | Rotate prekeys |
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 | Description | Recovery |
101
- | ---------------- | ----------------- | -------------- |
102
- | `INVALID_DH_KEY` | DH key is invalid | Reject message |
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 | Description | Recovery |
107
- | ------------------------ | ------------------------- | --------------------- |
108
- | `KEY_STORAGE_ERROR` | Storage operation failed | Retry or reinitialize |
109
- | `STORAGE_QUOTA_EXCEEDED` | The store ran out of room | Free space or prune |
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 sessionId = `${userId}_${deviceId}`;
243
+ const remoteAddress = ProtocolAddress.create(userId, deviceId);
198
244
 
199
245
  try {
200
- const hasSession = await signal.hasSession(sessionId);
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(sessionId, `${userId}_${deviceId}`, bundle);
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(sessionId);
257
+ await signal.deleteSession(remoteAddress);
212
258
  const bundle = await fetchPreKeyBundle(userId, deviceId);
213
- await signal.establishSession(sessionId, `${userId}_${deviceId}`, bundle);
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(sessionId, `${userId}_${deviceId}`, newBundle);
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
- // Good: Use type guards for specialized errors
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
- // Bad: instanceof check without import
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
@@ -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:skip target-message-api-not-yet-shipped -->
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',
@@ -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 },
@@ -44,6 +44,7 @@ For a production app, the normal startup shape is:
44
44
 
45
45
  Use the root package for core portable APIs:
46
46
 
47
+ <!-- doc-snippet:skip requires-external-context -->
47
48
  ```ts
48
49
  import {
49
50
  SignalProtocolClient,
@@ -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
 
@@ -11,6 +11,7 @@ modules or silently mixing standard and URL-safe Base64.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import {
16
17
  bytesToBase64,
package/files/README.md CHANGED
@@ -11,6 +11,7 @@ decryption key plus integrity metadata inside an end-to-end encrypted message.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import {
16
17
  streamingDecrypt,
package/groups/README.md CHANGED
@@ -13,6 +13,7 @@ and sender-key rotation.
13
13
 
14
14
  ## Usage
15
15
 
16
+ <!-- doc-snippet:skip requires-external-context -->
16
17
  ```ts
17
18
  import {
18
19
  GroupManager,
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;
@@ -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";