@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.
- package/CHANGELOG.md +117 -0
- package/README.md +1 -1
- package/SECURITY.md +2 -2
- package/client/README.md +14 -0
- package/dist/client/client.d.ts +9 -0
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +32 -0
- package/dist/client/client.js.map +1 -1
- package/dist/client/event-hooks.d.ts +36 -0
- package/dist/client/event-hooks.d.ts.map +1 -1
- package/dist/client/event-hooks.js +1 -0
- package/dist/client/event-hooks.js.map +1 -1
- package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
- package/dist/client/hosted-anonymous-delivery.js +3 -0
- package/dist/client/hosted-anonymous-delivery.js.map +1 -1
- package/dist/client/hosted-device-standing.d.ts +52 -0
- package/dist/client/hosted-device-standing.d.ts.map +1 -0
- package/dist/client/hosted-device-standing.js +74 -0
- package/dist/client/hosted-device-standing.js.map +1 -0
- package/dist/client/hosted-group-authority.d.ts.map +1 -1
- package/dist/client/hosted-group-authority.js +18 -4
- package/dist/client/hosted-group-authority.js.map +1 -1
- package/dist/client/hosted-groups.d.ts.map +1 -1
- package/dist/client/hosted-groups.js +5 -1
- package/dist/client/hosted-groups.js.map +1 -1
- package/dist/client/hosted-mailbox-subscription.d.ts +16 -2
- package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
- package/dist/client/hosted-mailbox-subscription.js +243 -42
- package/dist/client/hosted-mailbox-subscription.js.map +1 -1
- package/dist/client/hosted-transport.d.ts.map +1 -1
- package/dist/client/hosted-transport.js +56 -8
- package/dist/client/hosted-transport.js.map +1 -1
- package/dist/client/hosted.d.ts +13 -1
- package/dist/client/hosted.d.ts.map +1 -1
- package/dist/client/hosted.js +113 -41
- package/dist/client/hosted.js.map +1 -1
- package/dist/client/index.d.ts +2 -2
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +1 -1
- package/dist/client/index.js.map +1 -1
- package/dist/client/messages.d.ts.map +1 -1
- package/dist/client/messages.js +10 -0
- package/dist/client/messages.js.map +1 -1
- package/dist/client/one-time-prekey-refill.d.ts +7 -0
- package/dist/client/one-time-prekey-refill.d.ts.map +1 -1
- package/dist/client/one-time-prekey-refill.js +5 -1
- package/dist/client/one-time-prekey-refill.js.map +1 -1
- package/dist/client/relay-acceptance.d.ts +17 -0
- package/dist/client/relay-acceptance.d.ts.map +1 -1
- package/dist/client/relay-acceptance.js +37 -0
- package/dist/client/relay-acceptance.js.map +1 -1
- package/dist/client/relay-protocol.d.ts +41 -0
- package/dist/client/relay-protocol.d.ts.map +1 -0
- package/dist/client/relay-protocol.js +60 -0
- package/dist/client/relay-protocol.js.map +1 -0
- package/dist/client/relay-subscription.d.ts.map +1 -1
- package/dist/client/relay-subscription.js +30 -30
- package/dist/client/relay-subscription.js.map +1 -1
- package/dist/client/retry-family.d.ts +11 -9
- package/dist/client/retry-family.d.ts.map +1 -1
- package/dist/client/retry-family.js +5 -5
- package/dist/client/retry-family.js.map +1 -1
- package/dist/client/retry-request-envelope.d.ts +40 -12
- package/dist/client/retry-request-envelope.d.ts.map +1 -1
- package/dist/client/retry-request-envelope.js +142 -54
- package/dist/client/retry-request-envelope.js.map +1 -1
- package/dist/client/retry-request-lifecycle.d.ts +101 -0
- package/dist/client/retry-request-lifecycle.d.ts.map +1 -0
- package/dist/client/retry-request-lifecycle.js +307 -0
- package/dist/client/retry-request-lifecycle.js.map +1 -0
- package/dist/client/retry.d.ts +6 -6
- package/dist/client/retry.d.ts.map +1 -1
- package/dist/client/retry.js +83 -38
- package/dist/client/retry.js.map +1 -1
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +5 -1
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/client/types.d.ts.map +1 -1
- package/dist/client/types.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/local/store/reliability.d.ts +106 -8
- package/dist/local/store/reliability.d.ts.map +1 -1
- package/dist/local/store/reliability.js +165 -16
- package/dist/local/store/reliability.js.map +1 -1
- package/dist/remote/relay/types.d.ts +19 -5
- package/dist/remote/relay/types.d.ts.map +1 -1
- package/dist/utils/retry.d.ts +3 -0
- package/dist/utils/retry.d.ts.map +1 -1
- package/dist/utils/retry.js +13 -0
- package/dist/utils/retry.js.map +1 -1
- package/docs/ASSURANCE.md +5 -5
- package/docs/ERROR_HANDLING.md +119 -0
- package/package.json +1 -1
package/docs/ERROR_HANDLING.md
CHANGED
|
@@ -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