@open-e2ee/signal-protocol-sdk 10.0.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 (96) hide show
  1. package/CHANGELOG.md +117 -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-anonymous-delivery.d.ts.map +1 -1
  14. package/dist/client/hosted-anonymous-delivery.js +3 -0
  15. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  16. package/dist/client/hosted-device-standing.d.ts +52 -0
  17. package/dist/client/hosted-device-standing.d.ts.map +1 -0
  18. package/dist/client/hosted-device-standing.js +74 -0
  19. package/dist/client/hosted-device-standing.js.map +1 -0
  20. package/dist/client/hosted-group-authority.d.ts.map +1 -1
  21. package/dist/client/hosted-group-authority.js +18 -4
  22. package/dist/client/hosted-group-authority.js.map +1 -1
  23. package/dist/client/hosted-groups.d.ts.map +1 -1
  24. package/dist/client/hosted-groups.js +5 -1
  25. package/dist/client/hosted-groups.js.map +1 -1
  26. package/dist/client/hosted-mailbox-subscription.d.ts +16 -2
  27. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  28. package/dist/client/hosted-mailbox-subscription.js +243 -42
  29. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  30. package/dist/client/hosted-transport.d.ts.map +1 -1
  31. package/dist/client/hosted-transport.js +56 -8
  32. package/dist/client/hosted-transport.js.map +1 -1
  33. package/dist/client/hosted.d.ts +13 -1
  34. package/dist/client/hosted.d.ts.map +1 -1
  35. package/dist/client/hosted.js +113 -41
  36. package/dist/client/hosted.js.map +1 -1
  37. package/dist/client/index.d.ts +2 -2
  38. package/dist/client/index.d.ts.map +1 -1
  39. package/dist/client/index.js +1 -1
  40. package/dist/client/index.js.map +1 -1
  41. package/dist/client/messages.d.ts.map +1 -1
  42. package/dist/client/messages.js +10 -0
  43. package/dist/client/messages.js.map +1 -1
  44. package/dist/client/one-time-prekey-refill.d.ts +7 -0
  45. package/dist/client/one-time-prekey-refill.d.ts.map +1 -1
  46. package/dist/client/one-time-prekey-refill.js +5 -1
  47. package/dist/client/one-time-prekey-refill.js.map +1 -1
  48. package/dist/client/relay-acceptance.d.ts +17 -0
  49. package/dist/client/relay-acceptance.d.ts.map +1 -1
  50. package/dist/client/relay-acceptance.js +37 -0
  51. package/dist/client/relay-acceptance.js.map +1 -1
  52. package/dist/client/relay-protocol.d.ts +41 -0
  53. package/dist/client/relay-protocol.d.ts.map +1 -0
  54. package/dist/client/relay-protocol.js +60 -0
  55. package/dist/client/relay-protocol.js.map +1 -0
  56. package/dist/client/relay-subscription.d.ts.map +1 -1
  57. package/dist/client/relay-subscription.js +30 -30
  58. package/dist/client/relay-subscription.js.map +1 -1
  59. package/dist/client/retry-family.d.ts +11 -9
  60. package/dist/client/retry-family.d.ts.map +1 -1
  61. package/dist/client/retry-family.js +5 -5
  62. package/dist/client/retry-family.js.map +1 -1
  63. package/dist/client/retry-request-envelope.d.ts +40 -12
  64. package/dist/client/retry-request-envelope.d.ts.map +1 -1
  65. package/dist/client/retry-request-envelope.js +142 -54
  66. package/dist/client/retry-request-envelope.js.map +1 -1
  67. package/dist/client/retry-request-lifecycle.d.ts +101 -0
  68. package/dist/client/retry-request-lifecycle.d.ts.map +1 -0
  69. package/dist/client/retry-request-lifecycle.js +307 -0
  70. package/dist/client/retry-request-lifecycle.js.map +1 -0
  71. package/dist/client/retry.d.ts +6 -6
  72. package/dist/client/retry.d.ts.map +1 -1
  73. package/dist/client/retry.js +83 -38
  74. package/dist/client/retry.js.map +1 -1
  75. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  76. package/dist/client/signal-service-cipher.js +5 -1
  77. package/dist/client/signal-service-cipher.js.map +1 -1
  78. package/dist/client/types.d.ts.map +1 -1
  79. package/dist/client/types.js.map +1 -1
  80. package/dist/index.d.ts +2 -2
  81. package/dist/index.d.ts.map +1 -1
  82. package/dist/index.js +1 -1
  83. package/dist/index.js.map +1 -1
  84. package/dist/local/store/reliability.d.ts +106 -8
  85. package/dist/local/store/reliability.d.ts.map +1 -1
  86. package/dist/local/store/reliability.js +165 -16
  87. package/dist/local/store/reliability.js.map +1 -1
  88. package/dist/remote/relay/types.d.ts +19 -5
  89. package/dist/remote/relay/types.d.ts.map +1 -1
  90. package/dist/utils/retry.d.ts +3 -0
  91. package/dist/utils/retry.d.ts.map +1 -1
  92. package/dist/utils/retry.js +13 -0
  93. package/dist/utils/retry.js.map +1 -1
  94. package/docs/ASSURANCE.md +5 -5
  95. package/docs/ERROR_HANDLING.md +119 -0
  96. package/package.json +1 -1
@@ -150,6 +150,125 @@ holds each member to a production construction site.
150
150
  | `SEALED_SENDER_AUTH_FAILED` | The relay rejected sealed-sender authorization. | Reauthorize or use identified delivery when policy permits it. |
151
151
  | `INVALID_STATE` | The requested operation is invalid for current state. | Correct the call order or synchronize state. |
152
152
 
153
+ ## Relay Protocol Errors
154
+
155
+ The Relay serves a set of Relay protocol versions. This SDK speaks
156
+ protocol version 1. Two errors come from that set. Neither is an `EncryptionError`.
157
+
158
+ | Error | Cause | Application response |
159
+ |---|---|---|
160
+ | `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. |
161
+ | `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. |
162
+
163
+ The SDK does not retry an HTTP request that `UPGRADE_REQUIRED` refuses. Each
164
+ Relay route that answers with a JSON body throws
165
+ `HostedRelayUpgradeRequiredError`. An attachment download does not read the
166
+ response body, so it reports the 426 as a
167
+ [`MediaAttachmentError`](./api/namespaces/media/classes/MediaAttachmentError.md)
168
+ with the code `download-failed` and the `status` 426.
169
+
170
+ The mailbox subscription stops for the same refusal on its socket, with the
171
+ state `stopped` and the reason `upgrade-required`. It does not reconnect and
172
+ does not pull. For `PROTOCOL_UNSUPPORTED` on its socket, the subscription
173
+ reconnects with its usual backoff. See [`RelayConnectionReason`](./api/type-aliases/RelayConnectionReason.md).
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
+
184
+ A client call can wrap the error in an `EncryptionError`. It is then the
185
+ `originalError`.
186
+
187
+ <!-- doc-snippet:skip requires-existing-client -->
188
+ ```typescript
189
+ import {
190
+ EncryptionError,
191
+ HostedRelayUpgradeRequiredError,
192
+ } from '@open-e2ee/signal-protocol-sdk';
193
+
194
+ function upgradeRequired(error: unknown): boolean {
195
+ return (
196
+ error instanceof HostedRelayUpgradeRequiredError ||
197
+ (error instanceof EncryptionError &&
198
+ error.originalError instanceof HostedRelayUpgradeRequiredError)
199
+ );
200
+ }
201
+
202
+ try {
203
+ await signal.send(remoteUserId, plaintext);
204
+ } catch (error) {
205
+ // Only a newer SDK can send again. Ask the user to update the app.
206
+ if (upgradeRequired(error)) showUpdateRequired();
207
+ else throw error;
208
+ }
209
+ ```
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
+
153
272
  ## Error Handling Patterns
154
273
 
155
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.0.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",