@open-e2ee/signal-protocol-sdk 10.1.0 → 11.0.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 (83) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/README.md +1 -1
  3. package/SECURITY.md +2 -2
  4. package/client/README.md +14 -0
  5. package/dist/client/client.d.ts +9 -0
  6. package/dist/client/client.d.ts.map +1 -1
  7. package/dist/client/client.js +32 -0
  8. package/dist/client/client.js.map +1 -1
  9. package/dist/client/event-hooks.d.ts +36 -0
  10. package/dist/client/event-hooks.d.ts.map +1 -1
  11. package/dist/client/event-hooks.js +1 -0
  12. package/dist/client/event-hooks.js.map +1 -1
  13. package/dist/client/hosted-device-standing.d.ts +52 -0
  14. package/dist/client/hosted-device-standing.d.ts.map +1 -0
  15. package/dist/client/hosted-device-standing.js +74 -0
  16. package/dist/client/hosted-device-standing.js.map +1 -0
  17. package/dist/client/hosted-mailbox-subscription.d.ts +14 -1
  18. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  19. package/dist/client/hosted-mailbox-subscription.js +201 -57
  20. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  21. package/dist/client/hosted-transport.d.ts.map +1 -1
  22. package/dist/client/hosted-transport.js +52 -14
  23. package/dist/client/hosted-transport.js.map +1 -1
  24. package/dist/client/hosted.d.ts +12 -1
  25. package/dist/client/hosted.d.ts.map +1 -1
  26. package/dist/client/hosted.js +112 -41
  27. package/dist/client/hosted.js.map +1 -1
  28. package/dist/client/index.d.ts +2 -2
  29. package/dist/client/index.d.ts.map +1 -1
  30. package/dist/client/index.js +1 -1
  31. package/dist/client/index.js.map +1 -1
  32. package/dist/client/messages.d.ts.map +1 -1
  33. package/dist/client/messages.js +10 -0
  34. package/dist/client/messages.js.map +1 -1
  35. package/dist/client/one-time-prekey-refill.d.ts +7 -0
  36. package/dist/client/one-time-prekey-refill.d.ts.map +1 -1
  37. package/dist/client/one-time-prekey-refill.js +5 -1
  38. package/dist/client/one-time-prekey-refill.js.map +1 -1
  39. package/dist/client/relay-acceptance.d.ts +17 -0
  40. package/dist/client/relay-acceptance.d.ts.map +1 -1
  41. package/dist/client/relay-acceptance.js +37 -0
  42. package/dist/client/relay-acceptance.js.map +1 -1
  43. package/dist/client/relay-subscription.d.ts.map +1 -1
  44. package/dist/client/relay-subscription.js +30 -30
  45. package/dist/client/relay-subscription.js.map +1 -1
  46. package/dist/client/retry-family.d.ts +11 -9
  47. package/dist/client/retry-family.d.ts.map +1 -1
  48. package/dist/client/retry-family.js +5 -5
  49. package/dist/client/retry-family.js.map +1 -1
  50. package/dist/client/retry-request-envelope.d.ts +40 -12
  51. package/dist/client/retry-request-envelope.d.ts.map +1 -1
  52. package/dist/client/retry-request-envelope.js +142 -54
  53. package/dist/client/retry-request-envelope.js.map +1 -1
  54. package/dist/client/retry-request-lifecycle.d.ts +101 -0
  55. package/dist/client/retry-request-lifecycle.d.ts.map +1 -0
  56. package/dist/client/retry-request-lifecycle.js +307 -0
  57. package/dist/client/retry-request-lifecycle.js.map +1 -0
  58. package/dist/client/retry.d.ts +6 -6
  59. package/dist/client/retry.d.ts.map +1 -1
  60. package/dist/client/retry.js +83 -38
  61. package/dist/client/retry.js.map +1 -1
  62. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  63. package/dist/client/signal-service-cipher.js +5 -1
  64. package/dist/client/signal-service-cipher.js.map +1 -1
  65. package/dist/client/types.d.ts.map +1 -1
  66. package/dist/client/types.js.map +1 -1
  67. package/dist/index.d.ts +2 -2
  68. package/dist/index.d.ts.map +1 -1
  69. package/dist/index.js +1 -1
  70. package/dist/index.js.map +1 -1
  71. package/dist/local/store/reliability.d.ts +106 -8
  72. package/dist/local/store/reliability.d.ts.map +1 -1
  73. package/dist/local/store/reliability.js +165 -16
  74. package/dist/local/store/reliability.js.map +1 -1
  75. package/dist/remote/relay/types.d.ts +12 -3
  76. package/dist/remote/relay/types.d.ts.map +1 -1
  77. package/dist/utils/retry.d.ts +2 -0
  78. package/dist/utils/retry.d.ts.map +1 -1
  79. package/dist/utils/retry.js +7 -0
  80. package/dist/utils/retry.js.map +1 -1
  81. package/docs/ASSURANCE.md +5 -5
  82. package/docs/ERROR_HANDLING.md +70 -0
  83. package/package.json +1 -1
@@ -172,6 +172,15 @@ state `stopped` and the reason `upgrade-required`. It does not reconnect and
172
172
  does not pull. For `PROTOCOL_UNSUPPORTED` on its socket, the subscription
173
173
  reconnects with its usual backoff. See [`RelayConnectionReason`](./api/type-aliases/RelayConnectionReason.md).
174
174
 
175
+ The subscription also stops when the Relay refuses its socket token request or
176
+ a pull conclusively. The refusal has `retryable` false and the code
177
+ `AUTHORITY_DENIED`, `NOT_FOUND`, or `OPERATION_EXPIRED`. The state is `stopped`
178
+ and the reason is `authority-refused`. A refusal with `retryable` true, for
179
+ example a missing Relay binding, goes to the retry schedule. A `NOT_FOUND` on
180
+ the socket token request is a refusal of this device instead, as
181
+ [Relay Device Errors](#relay-device-errors) describes. See
182
+ [`RelayConnectionState`](./api/interfaces/RelayConnectionState.md).
183
+
175
184
  A client call can wrap the error in an `EncryptionError`. It is then the
176
185
  `originalError`.
177
186
 
@@ -199,6 +208,67 @@ try {
199
208
  }
200
209
  ```
201
210
 
211
+ ## Relay Device Errors
212
+
213
+ The Relay can refuse this device. Two errors name that refusal. Neither is an
214
+ `EncryptionError`, and the SDK retries neither one.
215
+
216
+ | Error | Cause | Application response |
217
+ |---|---|---|
218
+ | [`HostedRelayDeviceRevokedError`](./api/classes/HostedRelayDeviceRevokedError.md) | An account recovery revoked this device. `code` is `DEVICE_REVOKED`, `status` is 403, and `retryable` is false. | Sign the user out of this device. The Relay refuses a registration with the revoked key, so a re-registration fails too. |
219
+ | [`HostedRelayDeviceUnknownError`](./api/classes/HostedRelayDeviceUnknownError.md) | The Relay has no device for the stored session. `code` is `NOT_FOUND`, `status` is 404, and `retryable` is false. The message is the Relay's own message. | Ask the user to confirm a re-registration of this device. Do not re-register without that confirmation. |
220
+
221
+ `createHostedSignalProtocolClient` throws either error when the stored session
222
+ cannot get a device token. It does not register a new device in their place. A
223
+ running client throws them from its Relay calls. A client call can wrap them
224
+ in an `EncryptionError`, as the `originalError`. The mailbox subscription
225
+ stops with the reason `device-revoked` or `device-unknown`. See
226
+ [`RelayConnectionReason`](./api/type-aliases/RelayConnectionReason.md).
227
+
228
+ To re-register, create the client again with `assertionPurpose: 'reregister'`.
229
+ It keeps the stored identity and device key, and it asks for a `register`
230
+ assertion. It throws before any assertion when the store holds no identity or
231
+ no device key. A retry after a failed call sends the same registration again.
232
+
233
+ A re-registration has these effects:
234
+
235
+ - The Relay can give this device a new device ID. The messages queued for the
236
+ old device are lost.
237
+ - Each re-registration reserves a device ID for good. An account has five
238
+ device IDs, so a registration fails when all five are reserved.
239
+ - When the account itself was deleted, the re-registration makes a new account
240
+ address. Contacts of the old address do not reach the new one.
241
+ - A device that a recovery revoked before the Relay recorded revoked keys reads
242
+ as unknown. A re-registration can then restore it. So always ask the user
243
+ first.
244
+
245
+ <!-- doc-snippet:skip requires-existing-client -->
246
+ ```typescript
247
+ import {
248
+ HostedRelayDeviceRevokedError,
249
+ HostedRelayDeviceUnknownError,
250
+ createHostedSignalProtocolClient,
251
+ } from '@open-e2ee/signal-protocol-sdk';
252
+
253
+ try {
254
+ signal = await createHostedSignalProtocolClient(options);
255
+ } catch (error) {
256
+ if (error instanceof HostedRelayDeviceRevokedError) {
257
+ signOutThisDevice();
258
+ } else if (
259
+ error instanceof HostedRelayDeviceUnknownError &&
260
+ (await confirmReregistration())
261
+ ) {
262
+ signal = await createHostedSignalProtocolClient({
263
+ ...options,
264
+ hosted: { ...options.hosted, assertionPurpose: 'reregister' },
265
+ });
266
+ } else {
267
+ throw error;
268
+ }
269
+ }
270
+ ```
271
+
202
272
  ## Error Handling Patterns
203
273
 
204
274
  ### One Handler for Every Error
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "10.1.0",
3
+ "version": "11.0.0",
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",