@open-e2ee/signal-protocol-sdk 13.4.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.
Files changed (171) hide show
  1. package/CHANGELOG.md +423 -0
  2. package/README.md +4 -8
  3. package/SECURITY.md +2 -2
  4. package/TROUBLESHOOTING.md +55 -27
  5. package/dist/client/binary-send.d.ts +28 -0
  6. package/dist/client/binary-send.d.ts.map +1 -0
  7. package/dist/client/binary-send.js +26 -0
  8. package/dist/client/binary-send.js.map +1 -0
  9. package/dist/client/client.d.ts +46 -6
  10. package/dist/client/client.d.ts.map +1 -1
  11. package/dist/client/client.js +181 -66
  12. package/dist/client/client.js.map +1 -1
  13. package/dist/client/content-adapter.d.ts +18 -0
  14. package/dist/client/content-adapter.d.ts.map +1 -1
  15. package/dist/client/content-adapter.js.map +1 -1
  16. package/dist/client/device-set-reconciliation.d.ts +23 -8
  17. package/dist/client/device-set-reconciliation.d.ts.map +1 -1
  18. package/dist/client/device-set-reconciliation.js +25 -11
  19. package/dist/client/device-set-reconciliation.js.map +1 -1
  20. package/dist/client/event-hooks.d.ts +88 -8
  21. package/dist/client/event-hooks.d.ts.map +1 -1
  22. package/dist/client/event-hooks.js +1 -0
  23. package/dist/client/event-hooks.js.map +1 -1
  24. package/dist/client/group-outbox.d.ts +45 -10
  25. package/dist/client/group-outbox.d.ts.map +1 -1
  26. package/dist/client/group-outbox.js +246 -154
  27. package/dist/client/group-outbox.js.map +1 -1
  28. package/dist/client/group-receive-authorization.d.ts +10 -1
  29. package/dist/client/group-receive-authorization.d.ts.map +1 -1
  30. package/dist/client/group-receive-authorization.js.map +1 -1
  31. package/dist/client/hosted-anonymous-delivery.d.ts +18 -1
  32. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
  33. package/dist/client/hosted-anonymous-delivery.js +84 -12
  34. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  35. package/dist/client/hosted-connection.js +1 -1
  36. package/dist/client/hosted-connection.js.map +1 -1
  37. package/dist/client/hosted-group-authority.d.ts +6 -2
  38. package/dist/client/hosted-group-authority.d.ts.map +1 -1
  39. package/dist/client/hosted-group-authority.js +11 -7
  40. package/dist/client/hosted-group-authority.js.map +1 -1
  41. package/dist/client/hosted-groups.d.ts +5 -1
  42. package/dist/client/hosted-groups.d.ts.map +1 -1
  43. package/dist/client/hosted-groups.js +8 -4
  44. package/dist/client/hosted-groups.js.map +1 -1
  45. package/dist/client/hosted-http-error.d.ts +5 -1
  46. package/dist/client/hosted-http-error.d.ts.map +1 -1
  47. package/dist/client/hosted-http-error.js +5 -1
  48. package/dist/client/hosted-http-error.js.map +1 -1
  49. package/dist/client/hosted-mailbox-subscription.d.ts +2 -0
  50. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  51. package/dist/client/hosted-mailbox-subscription.js +5 -5
  52. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  53. package/dist/client/hosted-transport.d.ts +11 -1
  54. package/dist/client/hosted-transport.d.ts.map +1 -1
  55. package/dist/client/hosted-transport.js +75 -30
  56. package/dist/client/hosted-transport.js.map +1 -1
  57. package/dist/client/hosted.d.ts.map +1 -1
  58. package/dist/client/hosted.js +1 -1
  59. package/dist/client/hosted.js.map +1 -1
  60. package/dist/client/index.d.ts +1 -1
  61. package/dist/client/index.d.ts.map +1 -1
  62. package/dist/client/index.js.map +1 -1
  63. package/dist/client/receive-queue.d.ts +5 -2
  64. package/dist/client/receive-queue.d.ts.map +1 -1
  65. package/dist/client/receive-queue.js +55 -18
  66. package/dist/client/receive-queue.js.map +1 -1
  67. package/dist/client/relay-acceptance.d.ts +49 -6
  68. package/dist/client/relay-acceptance.d.ts.map +1 -1
  69. package/dist/client/relay-acceptance.js +49 -3
  70. package/dist/client/relay-acceptance.js.map +1 -1
  71. package/dist/client/relay-protocol.d.ts +37 -7
  72. package/dist/client/relay-protocol.d.ts.map +1 -1
  73. package/dist/client/relay-protocol.js +53 -10
  74. package/dist/client/relay-protocol.js.map +1 -1
  75. package/dist/client/retry-family.d.ts +3 -3
  76. package/dist/client/retry-family.js +1 -1
  77. package/dist/client/retry-family.js.map +1 -1
  78. package/dist/client/retry-request-envelope.d.ts +18 -8
  79. package/dist/client/retry-request-envelope.d.ts.map +1 -1
  80. package/dist/client/retry-request-envelope.js +57 -29
  81. package/dist/client/retry-request-envelope.js.map +1 -1
  82. package/dist/client/retry-request-lifecycle.d.ts +24 -11
  83. package/dist/client/retry-request-lifecycle.d.ts.map +1 -1
  84. package/dist/client/retry-request-lifecycle.js +46 -20
  85. package/dist/client/retry-request-lifecycle.js.map +1 -1
  86. package/dist/client/retry-terminal-recovery.d.ts +11 -8
  87. package/dist/client/retry-terminal-recovery.d.ts.map +1 -1
  88. package/dist/client/retry-terminal-recovery.js +18 -12
  89. package/dist/client/retry-terminal-recovery.js.map +1 -1
  90. package/dist/client/retry.d.ts +8 -7
  91. package/dist/client/retry.d.ts.map +1 -1
  92. package/dist/client/retry.js +30 -22
  93. package/dist/client/retry.js.map +1 -1
  94. package/dist/client/send-deadline.d.ts +308 -0
  95. package/dist/client/send-deadline.d.ts.map +1 -0
  96. package/dist/client/send-deadline.js +914 -0
  97. package/dist/client/send-deadline.js.map +1 -0
  98. package/dist/client/send-intent-driver.d.ts +116 -0
  99. package/dist/client/send-intent-driver.d.ts.map +1 -0
  100. package/dist/client/send-intent-driver.js +373 -0
  101. package/dist/client/send-intent-driver.js.map +1 -0
  102. package/dist/client/signal-service-cipher.d.ts +257 -27
  103. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  104. package/dist/client/signal-service-cipher.js +1274 -283
  105. package/dist/client/signal-service-cipher.js.map +1 -1
  106. package/dist/client/types.d.ts +48 -5
  107. package/dist/client/types.d.ts.map +1 -1
  108. package/dist/client/types.js.map +1 -1
  109. package/dist/index.d.ts +1 -1
  110. package/dist/index.d.ts.map +1 -1
  111. package/dist/index.js.map +1 -1
  112. package/dist/local/store/conformance/cases/metadata.d.ts +3 -2
  113. package/dist/local/store/conformance/cases/metadata.d.ts.map +1 -1
  114. package/dist/local/store/conformance/cases/metadata.js +153 -2
  115. package/dist/local/store/conformance/cases/metadata.js.map +1 -1
  116. package/dist/local/store/key-value/adapter.d.ts +2 -1
  117. package/dist/local/store/key-value/adapter.d.ts.map +1 -1
  118. package/dist/local/store/key-value/adapter.js +9 -0
  119. package/dist/local/store/key-value/adapter.js.map +1 -1
  120. package/dist/local/store/memory/adapter.d.ts +2 -1
  121. package/dist/local/store/memory/adapter.d.ts.map +1 -1
  122. package/dist/local/store/memory/adapter.js +4 -0
  123. package/dist/local/store/memory/adapter.js.map +1 -1
  124. package/dist/local/store/metadata-keys.d.ts +13 -0
  125. package/dist/local/store/metadata-keys.d.ts.map +1 -0
  126. package/dist/local/store/metadata-keys.js +20 -0
  127. package/dist/local/store/metadata-keys.js.map +1 -0
  128. package/dist/local/store/receive-work.d.ts.map +1 -1
  129. package/dist/local/store/receive-work.js +12 -1
  130. package/dist/local/store/receive-work.js.map +1 -1
  131. package/dist/local/store/reliability.d.ts +482 -33
  132. package/dist/local/store/reliability.d.ts.map +1 -1
  133. package/dist/local/store/reliability.js +690 -48
  134. package/dist/local/store/reliability.js.map +1 -1
  135. package/dist/local/store/sqlite/key-storage/index.d.ts +2 -1
  136. package/dist/local/store/sqlite/key-storage/index.d.ts.map +1 -1
  137. package/dist/local/store/sqlite/key-storage/index.js +3 -0
  138. package/dist/local/store/sqlite/key-storage/index.js.map +1 -1
  139. package/dist/local/store/sqlite/key-storage/metadata.d.ts +9 -0
  140. package/dist/local/store/sqlite/key-storage/metadata.d.ts.map +1 -1
  141. package/dist/local/store/sqlite/key-storage/metadata.js +12 -0
  142. package/dist/local/store/sqlite/key-storage/metadata.js.map +1 -1
  143. package/dist/local/store/sqlite/store.d.ts +2 -1
  144. package/dist/local/store/sqlite/store.d.ts.map +1 -1
  145. package/dist/local/store/sqlite/store.js +3 -0
  146. package/dist/local/store/sqlite/store.js.map +1 -1
  147. package/dist/local/store/web/adapter.d.ts +8 -1
  148. package/dist/local/store/web/adapter.d.ts.map +1 -1
  149. package/dist/local/store/web/adapter.js +18 -0
  150. package/dist/local/store/web/adapter.js.map +1 -1
  151. package/dist/remote/relay/request-admission.d.ts +49 -0
  152. package/dist/remote/relay/request-admission.d.ts.map +1 -0
  153. package/dist/remote/relay/request-admission.js +74 -0
  154. package/dist/remote/relay/request-admission.js.map +1 -0
  155. package/dist/types/api.d.ts +77 -0
  156. package/dist/types/api.d.ts.map +1 -1
  157. package/dist/types/errors.d.ts +144 -1
  158. package/dist/types/errors.d.ts.map +1 -1
  159. package/dist/types/errors.js +146 -1
  160. package/dist/types/errors.js.map +1 -1
  161. package/docs/ASSURANCE.md +31 -15
  162. package/docs/DEVIATIONS.md +34 -4
  163. package/docs/ERROR_HANDLING.md +134 -7
  164. package/docs/GETTING_STARTED.md +30 -23
  165. package/docs/PROTOCOL_POLICY.md +31 -20
  166. package/groups/README.md +1 -1
  167. package/hooks/README.md +6 -3
  168. package/local/store/react-native/README.md +9 -10
  169. package/local/store/web/README.md +1 -1
  170. package/package.json +1 -1
  171. package/safety/README.md +48 -11
@@ -84,6 +84,8 @@ holds each member to a production construction site.
84
84
  | `DECRYPTION_FAILED` | Available session state could not decrypt the message. | Let the retry flow recover, or inspect the session state. |
85
85
  | `ENCRYPTION_FAILED` | The SDK could not encrypt the message. | Inspect the session state and `originalError`. |
86
86
  | `INVALID_SEND_TIMESTAMP` | A new send carries a `timestamp`, or a sync to linked devices carries an application time, that is not a safe positive integer, or that is more than 5 minutes ahead of or more than 24 hours behind the SDK clock. The SDK throws `InvalidSendTimestampError` from `@open-e2ee/signal-protocol-sdk/types` and stores or posts nothing for the send. | Send again with a timestamp in the window, or with no timestamp. |
87
+ | `SEND_ACCEPTANCE_UNKNOWN` | The posting deadline of a direct or group send ended, and the Relay acceptance of a device is not known. The SDK throws `SendAcceptanceUnknownError` from `@open-e2ee/signal-protocol-sdk/types`. The message might have arrived. | Tell the user that the message might already have arrived. Do not replay the send. |
88
+ | `SEND_NEVER_ACCEPTED` | The posting deadline of a direct or group send ended, the call raised no refusal (a thrown refusal or a refusal in the receipt of a shared body), and no refused device has a stored refusal code. The SDK throws `SendNeverAcceptedByRelayError` from `@open-e2ee/signal-protocol-sdk/types`. | Tell the user which devices did not get the message. |
87
89
  | `MESSAGE_DUPLICATE` | The session processed this message before. | Discard the duplicate. |
88
90
  | `TOO_MANY_SKIPPED_MESSAGES` | The message exceeded the skipped-key bound. | Reset the affected session. |
89
91
  | `REPLAY_DETECTED` | Envelope and encrypted-content timestamps differ. | Reject the message as a replay. |
@@ -154,12 +156,31 @@ holds each member to a production construction site.
154
156
  ## Relay Protocol Errors
155
157
 
156
158
  The Relay serves a set of Relay protocol versions. This SDK speaks
157
- protocol version 1. Two errors come from that set. Neither is an `EncryptionError`.
159
+ protocol version 2. It does not fall back to version 1. Two errors come from
160
+ that set. Neither is an `EncryptionError`.
158
161
 
159
162
  | Error | Cause | Application response |
160
163
  |---|---|---|
161
- | `HostedRelayUpgradeRequiredError` | The Relay no longer serves version 1. `code` is `UPGRADE_REQUIRED`, `status` is the HTTP status (426), and `retryable` is false. | Ship a newer SDK. The same request fails again, so do not retry it. |
162
- | `PROTOCOL_UNSUPPORTED` | The Relay does not serve version 1. The request fails with status 400, the `code` `PROTOCOL_UNSUPPORTED`, and `retryable` true. | Retry later. The Relay never rolls back below a version that a published SDK sends, so this is a transient fault, not a planned state. |
164
+ | `HostedRelayUpgradeRequiredError` | The Relay no longer serves the version that the client sent. The message names that version. `code` is `UPGRADE_REQUIRED`, `status` is the HTTP status (426), and `retryable` is false. | Ship a newer SDK. The same request fails again, so do not retry it. |
165
+ | `PROTOCOL_UNSUPPORTED` | The Relay does not serve version 2. The request fails with status 400, the `code` `PROTOCOL_UNSUPPORTED`, and `retryable` true. A send keeps the device open until its posting deadline. | Retry later. The Relay never rolls back below a version that a published SDK sends, so this is a transient fault, not a planned state. |
166
+
167
+ Version 2 adds one Relay code, `DELIVERY_ALREADY_ACCEPTED`. The Relay gives it
168
+ with HTTP status 409, `retryable` false and the `details` reason
169
+ `message-id-held`, when it already holds an accepted post under the message
170
+ ID of the post. The Relay stored nothing for this post.
171
+ A Relay gives `RETRY_CONFLICT` for the same case to a version 1 request. The
172
+ SDK reads the two answers in the same way:
173
+
174
+ - A direct post, a sealed direct post, a pre-message and a group shared body
175
+ count the answer as an earlier acceptance, under the rules of
176
+ `RETRY_CONFLICT`. A device whose session the SDK replaced stays unknown.
177
+ The answer has no receipt.
178
+ - A retry request that gets `DELIVERY_ALREADY_ACCEPTED` from a version 2
179
+ Relay reads it as the acceptance of its stored attempt, as it reads
180
+ `RETRY_CONFLICT`. No replacement attempt posts.
181
+
182
+ A send error can carry the code `DELIVERY_ALREADY_ACCEPTED` when the SDK
183
+ cannot count the answer as an acceptance. Handle it as `RETRY_CONFLICT`.
163
184
 
164
185
  The SDK does not retry an HTTP request that `UPGRADE_REQUIRED` refuses. Each
165
186
  Relay route that answers with a JSON body throws
@@ -297,14 +318,118 @@ restart post with `OPERATION_EXPIRED`, the send throws
297
318
  | `acceptedDevices` | The devices that the Relay accepted. They stay accepted |
298
319
  | `unresolvedDevices` | The devices that did not get the message |
299
320
  | `clientMessageId` | The ID of the send |
321
+ | `outcome` | `failed` or `acceptance-unknown`. With `acceptance-unknown`, the message might have arrived. Treat it like `SendAcceptanceUnknownError` |
322
+
323
+ After a recipient-phase end, the outbox keeps the send as terminal with its
324
+ `outcome`, and the SDK does not post it again. A replay with the same
325
+ `clientMessageId` throws the stored-end class of its outcome,
326
+ `SendAcceptanceUnknownError` or the failed-end error below, and posts
327
+ nothing. `expired` gives `acceptance-unknown`, because the Relay can have
328
+ accepted an earlier post. A sync-phase end has no `outcome`. The send keeps
329
+ its result with `syncPending`, and a later `send()` with the same
330
+ `clientMessageId` posts the sync phase again.
331
+
332
+ A direct or group send has a posting deadline, `deadlineAt`. It is the earlier of 24
333
+ hours after the SDK first stores the send and 24 hours after its timestamp. A
334
+ replay or a restart never moves it. At or after `deadlineAt`, the SDK starts
335
+ no Relay request for the send. A request that started before it still counts
336
+ when its answer arrives later. Before `deadlineAt`, a send error that leaves a
337
+ device open has `retryable: true`, and `relayRetryable` keeps the hint of the
338
+ Relay. With a store that implements `listMetadataKeys`, as every built-in
339
+ store does, the SDK replays the send at start and on reconnect until
340
+ `deadlineAt`. It reports the end once through `onSendOutcome`. An internal
341
+ send of the SDK, such as a sender key distribution, never reaches
342
+ `onSendOutcome`. The SDK keeps no content of a sender key distribution at
343
+ rest, so it does not replay one. With the listing method, it ends an open
344
+ distribution at its deadline and reports nothing, and a retry request of the
345
+ receiver recovers a lost distribution, as in Signal. An open sender key
346
+ distribution that an earlier SDK version stored carries no marker, so the SDK
347
+ reports `content-required` for it once for each client run before its
348
+ deadline, and reports its end through `onSendOutcome` once, at its deadline.
349
+ With a custom store that does not implement `listMetadataKeys`, replay with
350
+ the same `clientMessageId` before `deadlineAt`. A call of `send()` with the same `clientMessageId` before
351
+ `deadlineAt` is always safe. A replay posts only devices that the Relay did
352
+ not accept. The send also ends before
353
+ `deadlineAt` when each open device got `OPERATION_EXPIRED` as the last answer
354
+ in the call or has a stored refusal that the SDK cannot recover. That early
355
+ end has `retryable: false` and follows the rule below. A Relay answer
356
+ `UPGRADE_REQUIRED` or `DEVICE_REVOKED` ends the send at once by the same
357
+ rule: with no device of unknown acceptance, the answer is the error of the
358
+ failed end. When another device of the call has an unknown acceptance, the
359
+ send ends as acceptance-unknown instead, because that device can hold the
360
+ post. When the deadline
361
+ ends, the send throws `SendAcceptanceUnknownError` or the failed-end error of
362
+ the rule below. The two deadline classes come from
363
+ `@open-e2ee/signal-protocol-sdk/types`:
300
364
 
301
- The outbox keeps the send as terminal and does not post it again. A call of
302
- `send()` with the same `clientMessageId` starts a new run at 0 restarts.
365
+ | Error | Cause | Application response |
366
+ |---|---|---|
367
+ | `SendAcceptanceUnknownError` | The Relay acceptance of a device is not known. An answer was lost, or it followed an uncertain request | Tell the user that the message might already have arrived. Do not replay the send |
368
+ | `SendNeverAcceptedByRelayError` | The Relay accepted no request for an open device, the call raised no refusal, and no refused device has a stored refusal code. No request started before the deadline, or each answer was a refusal for now, such as `QUOTA_EXCEEDED` | Tell the user which devices did not get the message |
369
+
370
+ When no device has an unknown acceptance, the send ends failed, and one rule
371
+ gives its error:
372
+
373
+ 1. When the call that ends the send raised a refusal, the first such refusal
374
+ is the error. A raised refusal is a thrown refusal or a refusal in the
375
+ receipt of a shared body. A thrown refusal keeps its class. A refusal in a
376
+ receipt is an `Error` with the `code` of that refusal.
377
+ 2. Otherwise, the error is an `Error` with the stored `code` of the first
378
+ refused device that has one, in the order of the destinations.
379
+ 3. Otherwise, the error is `SendNeverAcceptedByRelayError` with code
380
+ `SEND_NEVER_ACCEPTED`.
381
+
382
+ A replay of the ended send raises no refusal, so its error comes from case 2
383
+ or case 3. Each of these errors has `deadlineAt`, `acceptedDevices`,
384
+ `refusedDevices` and `retryable: false`. A replay of the ended send posts
385
+ nothing.
386
+
387
+ A replay or a resend after `SendAcceptanceUnknownError` can add one charged
388
+ unit within 24 hours, when the Relay no longer holds its record of the first
389
+ acceptance. The SDK does not promise that such a retry has no cost.
390
+
391
+ To post an ended send again, call `resendMessage(clientMessageId)`. The
392
+ resend keeps the `clientMessageId`, the timestamp and the content of the
393
+ send. It encrypts the content again for each recipient device that the
394
+ Relay did not accept, and posts each copy under the message ID
395
+ `<clientMessageId>:manual:N`, N from 1. A resend of a group send posts the
396
+ content of its send log entry, so each copy carries the group context of the
397
+ original send, not the current one. It is a new Relay operation, so the
398
+ Relay can charge a resend as a new message. It has its own posting deadline,
399
+ 24 hours after the call, and its end has the same classes as the end of a
400
+ send. `onSendOutcome` reports the end of a resend once, with `manualResend`
401
+ set to N. Only a send younger than 30 days takes a new resend. At or after
402
+ 30 days from the send, `resendMessage` throws `Only a send younger than 30
403
+ days takes a manual resend` and posts nothing. An open resend of an older
404
+ send still posts until its own deadline.
405
+
406
+ The receive queue of a recipient device drops a copy whose sender device,
407
+ timestamp and content match a message that it already processed, for 60
408
+ days. Two different messages of one sender device with the same timestamp
409
+ both deliver. This rule holds in SDK 13.x and ends in the next major SDK
410
+ version, which drops a later message of the same sender with the same
411
+ timestamp. The drop needs the timestamp that the content adapter reads
412
+ from the message. Content with no timestamp, such as raw string or byte
413
+ content, takes no drop key, and a recipient that holds it receives the copy
414
+ again. The recipient records the message with the completion of its
415
+ receive record. When a delivery receipt is due, it records the message right
416
+ after the receipt-due write and again with the completion of the receipt.
417
+ When no receipt is owed, a stop before the completion of the receive record
418
+ runs `onMessageDecrypted` again. When a receipt is owed, only a stop before
419
+ the receipt-due write runs it again. The caller-origin receive path gives
420
+ every decrypted message to the caller, and a caller that keeps its own
421
+ records removes a copy itself. A recipient device on an SDK
422
+ version without that check can show the message twice.
303
423
 
304
424
  The sync phase does not fail the send. The recipient result is stored first.
305
425
  When the sync phase does not complete, or the own device list cannot be read,
306
426
  the result carries `syncPending: true`. Call `send()` again with the same
307
- `clientMessageId` to post the pending copies.
427
+ `clientMessageId` before `deadlineAt` to post the pending copies. At or after
428
+ `deadlineAt`, a replay posts nothing. It returns the stored result with
429
+ `syncPending`, with one exception. When the send has no sync messages, the
430
+ replay reads the own device list again. If that read finds no other own
431
+ device, the replay completes the send and returns the result without
432
+ `syncPending`.
308
433
 
309
434
  The Relay marks each accepted declared post with `deviceSetChecked`. When an
310
435
  accepted post has no mark, the Relay did not compare its device set. The send
@@ -314,7 +439,9 @@ is delivered and its result does not change. The client reports a
314
439
  hook. Its `route` names the post route. A sync copy to another own device is
315
440
  an `identified-direct` post. A sync payload of a method such as
316
441
  `syncReadToLinkedDevices` reports the error once, with no `clientMessageId`.
317
- Report it to the Relay operator.
442
+ Report it to the Relay operator. A device that the SDK counts as accepted from
443
+ a `RETRY_CONFLICT` or `DELIVERY_ALREADY_ACCEPTED` answer has no receipt, so
444
+ the SDK reports no `DEVICE_SET_UNCHECKED` error for it.
318
445
 
319
446
  A relay that does not compare device sets gets no declaration. The Convex
320
447
  relay is one. With it, the SDK reads the device lists as before, and none of
@@ -28,10 +28,10 @@ The [adapter guide](../ADAPTERS.md) lists the supported stores.
28
28
  - Application storage for decrypted messages and attachment bytes.
29
29
 
30
30
  A Sandbox environment uses device-owned identity. `hostedRelaySandboxIdentity`
31
- creates its `getIdentityAssertion` callback. The callback signs each assertion
32
- with a key that it keeps in the device-local store, so the device gets the same
33
- account each time it registers. A device that loses its store loses that
34
- Sandbox account. The helper works only in a Sandbox environment.
31
+ creates its `getIdentityAssertion` callback. The callback keeps a key in the device-local store. It signs each assertion
32
+ with that key. The device gets the same account each time it registers.
33
+
34
+ A device that loses its store loses that Sandbox account. The helper works only in a Sandbox environment.
35
35
 
36
36
  Production supports application-bound and explicitly configured device-owned
37
37
  accounts. For application-bound accounts, `getIdentityAssertion` returns a
@@ -62,6 +62,7 @@ transfer or by a channel that the application owns, then joins the account
62
62
  with `linkHostedRelayDevice()`. That call runs in one process that holds the
63
63
  active device's store and the new device's store. It copies each group master
64
64
  key from the active device and gives the new device its own registration ID.
65
+
65
66
  It refuses a new device's store that already lists a group, with
66
67
  `HostedRelayDeviceLinkError`. See the [device guide](../device/README.md). The
67
68
  default policy requires post-quantum session establishment and Braid
@@ -153,39 +154,37 @@ await signal.send("bob", {
153
154
  A new send accepts a `timestamp` at most 5 minutes ahead of the SDK clock and
154
155
  at most 24 hours behind it. For any other value, `send()` throws
155
156
  `InvalidSendTimestampError` and stores or posts nothing. Omit `timestamp`, and
156
- the SDK uses its clock. From the Relay release that follows v2026.10.25, the
157
- Relay admits a mailbox delivery epoch and a new group fan-out operation in the
158
- same window. Earlier Relay releases admit a new operation only within 5
157
+ the SDK uses its clock.
158
+
159
+ From the Relay release that follows v2026.10.25, the Relay admits a mailbox
160
+ delivery epoch in the same window. It also admits a new group fan-out
161
+ operation in that window. Earlier Relay releases admit a new operation only within 5
159
162
  minutes of its epoch. On an earlier Relay release, a time 5 minutes to 24 hours
160
- old passes the SDK check but gets `OPERATION_EXPIRED`. The SDK check uses the
163
+ old passes the SDK check. The Relay returns `OPERATION_EXPIRED`.
164
+
165
+ The SDK check uses the
161
166
  same bounds, so the SDK refuses an application-supplied time before any post.
162
167
 
163
168
  A hosted client sends a sealed 1:1 message only when you pass
164
169
  `hosted.profileKeys`, and only to a contact whose profile key `contacts` holds.
165
- Each other 1:1 message is identified, so the Relay sees its sender. Until the
166
- client holds the profile key of a contact, its messages to that contact are
167
- identified and carry the profile key of this account.
170
+ The client identifies each other 1:1 message, so the Relay sees its sender.
171
+ Until the client holds a contact's profile key, it identifies messages to that
172
+ contact. Those messages carry the profile key of this account.
168
173
 
169
174
  ## Attachments
170
175
 
171
- Add a remote object store when your app sends encrypted attachments. The
172
- `remoteObjectStore` adapter brokers encrypted byte objects rather than
173
- plaintext files.
176
+ The hosted factory supplies the Relay object store for encrypted
177
+ attachments. Configure the media callbacks below to read local bytes and
178
+ save attachment references and downloaded bytes.
174
179
 
175
180
  <!-- doc-snippet:skip requires-external-context -->
176
181
  ```ts
177
182
  import { createHostedSignalProtocolClient, media } from "@open-e2ee/signal-protocol-sdk";
178
- import { convexR2ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2";
179
- import { api } from "../convex/_generated/api";
180
183
 
181
184
  const signal = await createHostedSignalProtocolClient({
182
185
  hosted: { relayUrl, getIdentityAssertion },
183
186
  adapters: {
184
187
  storage,
185
- remoteObjectStore: convexR2ObjectStore({
186
- convex,
187
- api: api.signalObjectStore,
188
- }),
189
188
  },
190
189
  media: {
191
190
  preparedUploads: appPreparedUploads,
@@ -202,6 +201,12 @@ const signal = await createHostedSignalProtocolClient({
202
201
  });
203
202
  ```
204
203
 
204
+ For an application-owned relay and object broker, use
205
+ `createSignalProtocolClient` with `adapters.remoteObjectStore`. The
206
+ [client composition guide](CLIENT_COMPOSITION.md#attachments) shows the
207
+ Convex R2 adapter with that factory. The hosted factory supplies its own
208
+ Relay object store and does not accept a replacement.
209
+
205
210
  For Amazon S3 or S3-compatible storage, use the framework-neutral adapter with
206
211
  an authenticated application-backend broker:
207
212
 
@@ -480,12 +485,14 @@ await signal.media.cleanup(
480
485
 
481
486
  The default is:
482
487
 
483
- <!-- doc-snippet:illustrative config-object-fragment -->
488
+ <!-- doc-snippet:skip configuration-only -->
484
489
  ```ts
485
- protocol: {
490
+ import type { SignalProtocolConfig } from '@open-e2ee/signal-protocol-sdk';
491
+
492
+ export const protocol: SignalProtocolConfig = {
486
493
  postQuantum: 'required',
487
494
  braid: 'required',
488
- }
495
+ };
489
496
  ```
490
497
 
491
498
  Leave it unset. `'required'` is the only `postQuantum` value. See
@@ -10,12 +10,14 @@ identity, the Ed25519-instead-of-XEdDSA signature scheme, the ML-KEM Braid
10
10
 
11
11
  The public Signal Protocol client policy is:
12
12
 
13
- <!-- doc-snippet:illustrative config-object-fragment -->
13
+ <!-- doc-snippet:skip configuration-only -->
14
14
  ```ts
15
- protocol: {
15
+ import type { SignalProtocolConfig } from '@open-e2ee/signal-protocol-sdk';
16
+
17
+ export const protocol: SignalProtocolConfig = {
16
18
  postQuantum: 'required',
17
19
  braid: 'required',
18
- }
20
+ };
19
21
  ```
20
22
 
21
23
  Both values are the defaults.
@@ -42,7 +44,7 @@ message ratchet are mandatory. `'required'` is the only `postQuantum` value.
42
44
 
43
45
  The SDK has no classical key agreement. Every new session uses PQXDH with
44
46
  ML-KEM-1024. A peer that publishes no post-quantum prekeys fails closed with
45
- `PQXDHRequiredError` (`PQXDH_REQUIRED`), and no session is stored.
47
+ `PQXDHRequiredError` (`PQXDH_REQUIRED`). The SDK stores no session.
46
48
 
47
49
  No setting allows downgrade recovery:
48
50
 
@@ -104,7 +106,7 @@ await createSignalProtocolClient({
104
106
  ```
105
107
 
106
108
  `'required'` is the only `postQuantum` value. Any other value throws
107
- `Unsupported postQuantum policy` when the client is created.
109
+ `Unsupported postQuantum policy` when you create the client.
108
110
 
109
111
  ## Advanced Telemetry
110
112
 
@@ -130,18 +132,24 @@ direct-vs-Braid choice.
130
132
  ## Content Recovery
131
133
 
132
134
  A device that cannot decrypt a message asks the sender for it again with a
133
- retry request. To answer with the content, the sender keeps the plaintext of
134
- each resendable message in its local store. `protocol.contentRecovery`
135
+ retry request. The sender keeps each resendable message's plaintext in its local store.
136
+ It uses that content to answer. `protocol.contentRecovery`
135
137
  decides whether the store may hold that plaintext.
136
138
 
137
- <!-- doc-snippet:illustrative config-object-fragment -->
139
+ <!-- doc-snippet:skip requires-application-membership -->
138
140
  ```ts
139
- protocol: {
140
- contentRecovery: {
141
- mode: 'require-protected',
142
- retentionMs: 14 * 24 * 60 * 60 * 1000,
143
- isCurrentMember: async (groupId, userId) => true,
144
- },
141
+ import type { ContentRecoveryPolicy, SignalProtocolConfig } from '@open-e2ee/signal-protocol-sdk';
142
+
143
+ export function protectedContentRecovery(
144
+ isCurrentMember: NonNullable<ContentRecoveryPolicy['isCurrentMember']>,
145
+ ): SignalProtocolConfig {
146
+ return {
147
+ contentRecovery: {
148
+ mode: 'require-protected',
149
+ retentionMs: 14 * 24 * 60 * 60 * 1000,
150
+ isCurrentMember,
151
+ },
152
+ };
145
153
  }
146
154
  ```
147
155
 
@@ -170,7 +178,7 @@ The modes:
170
178
  - `off` keeps no content.
171
179
 
172
180
  A `none` level never keeps content. When the policy refuses the store, the
173
- client keeps no pairwise message record and no send log entry, and deletes
181
+ client keeps no pairwise message record and no send log entry. It deletes
174
182
  the ones that the store already holds. A retry request for a direct message
175
183
  then resets the session with no content. The client shows the decision in
176
184
  `client.contentRecoveryStatus`, with `reason` when it is off, and logs it
@@ -186,9 +194,10 @@ The client deletes expired content before each send log lookup, at creation,
186
194
  at `stop()`, and before the first resendable group send of each day. An E2EE
187
195
  delivery receipt from a device deletes the send log row of that device, and
188
196
  the last row takes the content with it. A Relay delivery receipt, a read
189
- receipt, and a viewed receipt delete no row. A device also acknowledges a
190
- copy that it could not decrypt, so the Relay receipt does not prove that the
191
- device has the content. `client.getPendingRecipients(clientMessageId)` lists
197
+ receipt, and a viewed receipt delete no row. A device also acknowledges a copy that it could not decrypt. The Relay
198
+ receipt does not prove that the device has the content.
199
+
200
+ `client.getPendingRecipients(clientMessageId)` lists
192
201
  the devices that still have a row. `client.forgetSentContent(clientMessageId)`
193
202
  deletes the content of one group send at once. It does not delete the
194
203
  pairwise message records. A device lifecycle reset clears the send log with
@@ -200,14 +209,16 @@ groups, or set `isCurrentMember` for ad hoc groups. The client checks a
200
209
  managed group against its verified group state and never asks the hook
201
210
  about it. The hook gets the prefixed group ID that `createGroupId` makes.
202
211
  `contentRecoveryStatus.groupMembershipSource` is `managed`, `hook`, or
203
- `none`. A client with no source still keeps content and logs one warning
212
+ `none`.
213
+
214
+ A client with no source still keeps content and logs one warning
204
215
  at creation. With no source for a group, the sender gives no group content
205
216
  again. A direct message resend needs no source.
206
217
 
207
218
  A group send of a `DataMessage` has the content hint `Resendable` when the
208
219
  policy keeps content and the application sets no other hint. The client
209
220
  writes the content and the recipient devices to the send log before it
210
- stores the outgoing intent, so a failed write stops the send. When the
221
+ stores the outgoing intent. A failed write stops the send. When the
211
222
  policy keeps no content, the send goes out as `Default`.
212
223
 
213
224
  A custom store must declare its `protection` as `{ atRest, keyCustody }`.
package/groups/README.md CHANGED
@@ -38,7 +38,7 @@ const groups = new GroupManager({
38
38
  serverSigningPublicKey,
39
39
  aci: localAccountServiceId,
40
40
  pni: localPhoneNumberServiceId,
41
- issueProfileKeyCredential: () => appGroupCredentials.issueProfileKey(),
41
+ issueProfileKeyCredential: (request) => appGroupCredentials.issueProfileKey(request),
42
42
  profileKeyCredentialPublicKey,
43
43
  profileKey: localProfileKey,
44
44
  });
package/hooks/README.md CHANGED
@@ -27,19 +27,22 @@ import {
27
27
  useRelayConnectionState,
28
28
  useRelayLifecycle,
29
29
  useSessionHealth,
30
+ type UseRelayLifecycleOptions,
31
+ type UseRelayConnectionStateOptions,
32
+ type UseSessionHealthOptions,
30
33
  } from "@open-e2ee/signal-protocol-sdk/hooks";
31
34
 
32
- function SignalLifecycle({ signal }) {
35
+ function SignalLifecycle({ signal }: Pick<UseRelayLifecycleOptions, "signal">) {
33
36
  useRelayLifecycle({ signal });
34
37
  return null;
35
38
  }
36
39
 
37
- function OwnConnectionDot({ signal }) {
40
+ function OwnConnectionDot({ signal }: Pick<UseRelayConnectionStateOptions, "signal">) {
38
41
  const { state } = useRelayConnectionState({ signal });
39
42
  return <Dot online={state === "connected"} />;
40
43
  }
41
44
 
42
- function ConversationStatus({ signal, userId }) {
45
+ function ConversationStatus({ signal, userId }: Pick<UseSessionHealthOptions, "signal" | "userId">) {
43
46
  const { health, isLoading } = useSessionHealth({ signal, userId });
44
47
  if (isLoading) return <p>Checking…</p>;
45
48
  return <p>{health?.status === "healthy" ? "Ready" : "Check the session"}</p>;
@@ -1,10 +1,9 @@
1
1
  # React Native SQLite Store
2
2
 
3
3
  `ReactNativeSignalProtocolStore` implements `SignalProtocolLocalStore`
4
- for bare React Native in an SDK-owned SQLCipher database on
5
- [op-sqlite](https://github.com/OP-Engineering/op-sqlite). The database key is
6
- held through the local secret-vault boundary, by default in the
7
- react-native-keychain vault.
4
+ for bare React Native. It uses an SDK-owned SQLCipher database on
5
+ [op-sqlite](https://github.com/OP-Engineering/op-sqlite). The local secret-vault
6
+ boundary holds the database key. The react-native-keychain vault is the default.
8
7
 
9
8
  ## Why it exists
10
9
 
@@ -86,8 +85,8 @@ Options:
86
85
  - `logger`: receives the warning of each open without encryption.
87
86
 
88
87
  A store holds its name until `close()`. In one process, the opens and resets
89
- of a name run one at a time. An open or a reset of a name that an open store
90
- holds fails with `INVALID_STATE`, so two parallel first opens write one key
88
+ of a name run one at a time. An open or reset fails with `INVALID_STATE`
89
+ when an open store holds that name. Two parallel first opens write one key,
91
90
  and the second open fails.
92
91
 
93
92
  Keep application tables in a separate database file. The SDK database holds
@@ -115,8 +114,8 @@ and its key. `resetReactNativeStore()` is the full teardown.
115
114
 
116
115
  ## Convert a plaintext store
117
116
 
118
- An encrypted open with `convertPlaintext: true` converts a database that was
119
- created with `encryptionAtRest: false`:
117
+ If you created a database with `encryptionAtRest: false`, an encrypted open
118
+ with `convertPlaintext: true` converts it:
120
119
 
121
120
  <!-- doc-snippet:skip requires-external-context -->
122
121
 
@@ -176,7 +175,7 @@ therefore the only thing that protects them.
176
175
 
177
176
  Do not back up the database file to a server or sync it between devices. The
178
177
  default vault keeps the key out of device backups. iOS backs up the Library
179
- directory, and Android Auto Backup includes the databases directory unless the
178
+ directory. Android Auto Backup includes the databases directory unless the
180
179
  app excludes it. A file restored from a backup to a new device therefore has no
181
180
  key there, and the open fails with `LOCAL_STORE_KEY_LOST`.
182
181
 
@@ -198,5 +197,5 @@ For replaced-prekey maintenance, pass the open store to
198
197
  `createPreKeyMaintenanceStore(store)`.
199
198
 
200
199
  See the parent [storage guide](../README.md), [adapter guide](../../../ADAPTERS.md),
201
- the [op-sqlite installation guide](https://op-engineering.github.io/op-sqlite/docs/installation),
200
+ the [op-sqlite installation guide](https://op-engineering.github.io/op-sqlite/docs/installation/),
202
201
  and [security model](../../../docs/SECURITY.md).
@@ -71,7 +71,7 @@ Browser applications using this adapter should:
71
71
 
72
72
  The exact controls depend on the host application's deployment and threat
73
73
  model. See the [OWASP XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)
74
- and [MDN Content Security Policy guide](https://developer.mozilla.org/docs/Web/HTTP/CSP).
74
+ and [MDN Content Security Policy guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP).
75
75
 
76
76
  ## Operational status
77
77
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "13.4.0",
3
+ "version": "13.5.1",
4
4
  "description": "Pure TypeScript Signal Protocol SDK for encrypted chat in Expo, React Native, browsers, and Node. Post-quantum by default.",
5
5
  "keywords": [
6
6
  "open-e2ee",
package/safety/README.md CHANGED
@@ -15,23 +15,60 @@ decision.
15
15
  <!-- doc-snippet:skip requires-external-context -->
16
16
  ```ts
17
17
  import { generateCompositeSafetyNumber } from "@open-e2ee/signal-protocol-sdk/safety";
18
+ import type { CompositeIdentityV1 } from "@open-e2ee/signal-protocol-sdk/keys";
18
19
 
19
- const safetyNumber = generateCompositeSafetyNumber(
20
- localCompositeIdentity,
21
- remoteCompositeIdentity,
22
- localUserId,
23
- remoteUserId,
24
- );
20
+ export function compareCompositeIdentities(
21
+ localCompositeIdentity: CompositeIdentityV1,
22
+ remoteCompositeIdentity: CompositeIdentityV1,
23
+ localUserId: string,
24
+ remoteUserId: string,
25
+ scannedQrBytes: Uint8Array,
26
+ ): boolean {
27
+ const safetyNumber = generateCompositeSafetyNumber(
28
+ localCompositeIdentity,
29
+ remoteCompositeIdentity,
30
+ localUserId,
31
+ remoteUserId,
32
+ );
33
+ console.log(safetyNumber.numeric);
34
+ console.log(safetyNumber.emojis);
35
+ return safetyNumber.scannable.compare(scannedQrBytes) === "match";
36
+ }
37
+ ```
38
+
39
+ This helper comparison does not change a client's trust state. For an existing
40
+ client, compare the exact value returned by `verify()` through an authenticated
41
+ channel. Pass its original confirmation token only after that comparison succeeds.
25
42
 
26
- console.log(safetyNumber.numeric);
27
- console.log(safetyNumber.emojis);
43
+ <!-- doc-snippet:skip requires-authenticated-comparison -->
44
+ ```ts
45
+ import type { DefaultSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
46
+
47
+ type ComparisonDisplay = Pick<
48
+ Awaited<ReturnType<DefaultSignalProtocolClient["verify"]>>,
49
+ "numeric" | "fingerprint"
50
+ >;
28
51
 
29
- const comparison = safetyNumber.scannable.compare(scannedQrBytes);
30
- if (comparison === "match") {
31
- await signal.verify(remoteAddress, remoteCompositeIdentity);
52
+ export async function verifyContact(
53
+ signal: DefaultSignalProtocolClient,
54
+ remoteUserId: string,
55
+ compareAuthenticated: (display: ComparisonDisplay) => Promise<boolean>,
56
+ ): Promise<void> {
57
+ const safetyNumber = await signal.verify(remoteUserId);
58
+ const matched = await compareAuthenticated({
59
+ numeric: safetyNumber.numeric,
60
+ fingerprint: safetyNumber.fingerprint,
61
+ });
62
+ if (matched) {
63
+ await signal.confirmSafetyNumber(safetyNumber.confirmation);
64
+ }
32
65
  }
33
66
  ```
34
67
 
68
+ The comparison callback belongs to the application. It must compare the displayed
69
+ numeric code or fingerprint with the same peer through an authenticated channel.
70
+ It must not approve a fresh client value because a separate helper value matched.
71
+
35
72
  Use the composite safety-number API for contact verification in this SDK
36
73
  profile. The single-key helper is a lower-level reference primitive and does
37
74
  not authenticate the complete composite identity.