@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.
- package/CHANGELOG.md +423 -0
- package/README.md +4 -8
- package/SECURITY.md +2 -2
- package/TROUBLESHOOTING.md +55 -27
- package/dist/client/binary-send.d.ts +28 -0
- package/dist/client/binary-send.d.ts.map +1 -0
- package/dist/client/binary-send.js +26 -0
- package/dist/client/binary-send.js.map +1 -0
- package/dist/client/client.d.ts +46 -6
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +181 -66
- package/dist/client/client.js.map +1 -1
- package/dist/client/content-adapter.d.ts +18 -0
- package/dist/client/content-adapter.d.ts.map +1 -1
- package/dist/client/content-adapter.js.map +1 -1
- package/dist/client/device-set-reconciliation.d.ts +23 -8
- package/dist/client/device-set-reconciliation.d.ts.map +1 -1
- package/dist/client/device-set-reconciliation.js +25 -11
- package/dist/client/device-set-reconciliation.js.map +1 -1
- package/dist/client/event-hooks.d.ts +88 -8
- 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/group-outbox.d.ts +45 -10
- package/dist/client/group-outbox.d.ts.map +1 -1
- package/dist/client/group-outbox.js +246 -154
- package/dist/client/group-outbox.js.map +1 -1
- package/dist/client/group-receive-authorization.d.ts +10 -1
- package/dist/client/group-receive-authorization.d.ts.map +1 -1
- package/dist/client/group-receive-authorization.js.map +1 -1
- package/dist/client/hosted-anonymous-delivery.d.ts +18 -1
- package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
- package/dist/client/hosted-anonymous-delivery.js +84 -12
- package/dist/client/hosted-anonymous-delivery.js.map +1 -1
- package/dist/client/hosted-connection.js +1 -1
- package/dist/client/hosted-connection.js.map +1 -1
- package/dist/client/hosted-group-authority.d.ts +6 -2
- package/dist/client/hosted-group-authority.d.ts.map +1 -1
- package/dist/client/hosted-group-authority.js +11 -7
- package/dist/client/hosted-group-authority.js.map +1 -1
- package/dist/client/hosted-groups.d.ts +5 -1
- package/dist/client/hosted-groups.d.ts.map +1 -1
- package/dist/client/hosted-groups.js +8 -4
- package/dist/client/hosted-groups.js.map +1 -1
- package/dist/client/hosted-http-error.d.ts +5 -1
- package/dist/client/hosted-http-error.d.ts.map +1 -1
- package/dist/client/hosted-http-error.js +5 -1
- package/dist/client/hosted-http-error.js.map +1 -1
- package/dist/client/hosted-mailbox-subscription.d.ts +2 -0
- package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
- package/dist/client/hosted-mailbox-subscription.js +5 -5
- package/dist/client/hosted-mailbox-subscription.js.map +1 -1
- package/dist/client/hosted-transport.d.ts +11 -1
- package/dist/client/hosted-transport.d.ts.map +1 -1
- package/dist/client/hosted-transport.js +75 -30
- package/dist/client/hosted-transport.js.map +1 -1
- package/dist/client/hosted.d.ts.map +1 -1
- package/dist/client/hosted.js +1 -1
- package/dist/client/hosted.js.map +1 -1
- package/dist/client/index.d.ts +1 -1
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js.map +1 -1
- package/dist/client/receive-queue.d.ts +5 -2
- package/dist/client/receive-queue.d.ts.map +1 -1
- package/dist/client/receive-queue.js +55 -18
- package/dist/client/receive-queue.js.map +1 -1
- package/dist/client/relay-acceptance.d.ts +49 -6
- package/dist/client/relay-acceptance.d.ts.map +1 -1
- package/dist/client/relay-acceptance.js +49 -3
- package/dist/client/relay-acceptance.js.map +1 -1
- package/dist/client/relay-protocol.d.ts +37 -7
- package/dist/client/relay-protocol.d.ts.map +1 -1
- package/dist/client/relay-protocol.js +53 -10
- package/dist/client/relay-protocol.js.map +1 -1
- package/dist/client/retry-family.d.ts +3 -3
- package/dist/client/retry-family.js +1 -1
- package/dist/client/retry-family.js.map +1 -1
- package/dist/client/retry-request-envelope.d.ts +18 -8
- package/dist/client/retry-request-envelope.d.ts.map +1 -1
- package/dist/client/retry-request-envelope.js +57 -29
- package/dist/client/retry-request-envelope.js.map +1 -1
- package/dist/client/retry-request-lifecycle.d.ts +24 -11
- package/dist/client/retry-request-lifecycle.d.ts.map +1 -1
- package/dist/client/retry-request-lifecycle.js +46 -20
- package/dist/client/retry-request-lifecycle.js.map +1 -1
- package/dist/client/retry-terminal-recovery.d.ts +11 -8
- package/dist/client/retry-terminal-recovery.d.ts.map +1 -1
- package/dist/client/retry-terminal-recovery.js +18 -12
- package/dist/client/retry-terminal-recovery.js.map +1 -1
- package/dist/client/retry.d.ts +8 -7
- package/dist/client/retry.d.ts.map +1 -1
- package/dist/client/retry.js +30 -22
- package/dist/client/retry.js.map +1 -1
- package/dist/client/send-deadline.d.ts +308 -0
- package/dist/client/send-deadline.d.ts.map +1 -0
- package/dist/client/send-deadline.js +914 -0
- package/dist/client/send-deadline.js.map +1 -0
- package/dist/client/send-intent-driver.d.ts +116 -0
- package/dist/client/send-intent-driver.d.ts.map +1 -0
- package/dist/client/send-intent-driver.js +373 -0
- package/dist/client/send-intent-driver.js.map +1 -0
- package/dist/client/signal-service-cipher.d.ts +257 -27
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +1274 -283
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/client/types.d.ts +48 -5
- package/dist/client/types.d.ts.map +1 -1
- package/dist/client/types.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/local/store/conformance/cases/metadata.d.ts +3 -2
- package/dist/local/store/conformance/cases/metadata.d.ts.map +1 -1
- package/dist/local/store/conformance/cases/metadata.js +153 -2
- package/dist/local/store/conformance/cases/metadata.js.map +1 -1
- package/dist/local/store/key-value/adapter.d.ts +2 -1
- package/dist/local/store/key-value/adapter.d.ts.map +1 -1
- package/dist/local/store/key-value/adapter.js +9 -0
- package/dist/local/store/key-value/adapter.js.map +1 -1
- package/dist/local/store/memory/adapter.d.ts +2 -1
- package/dist/local/store/memory/adapter.d.ts.map +1 -1
- package/dist/local/store/memory/adapter.js +4 -0
- package/dist/local/store/memory/adapter.js.map +1 -1
- package/dist/local/store/metadata-keys.d.ts +13 -0
- package/dist/local/store/metadata-keys.d.ts.map +1 -0
- package/dist/local/store/metadata-keys.js +20 -0
- package/dist/local/store/metadata-keys.js.map +1 -0
- package/dist/local/store/receive-work.d.ts.map +1 -1
- package/dist/local/store/receive-work.js +12 -1
- package/dist/local/store/receive-work.js.map +1 -1
- package/dist/local/store/reliability.d.ts +482 -33
- package/dist/local/store/reliability.d.ts.map +1 -1
- package/dist/local/store/reliability.js +690 -48
- package/dist/local/store/reliability.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/index.d.ts +2 -1
- package/dist/local/store/sqlite/key-storage/index.d.ts.map +1 -1
- package/dist/local/store/sqlite/key-storage/index.js +3 -0
- package/dist/local/store/sqlite/key-storage/index.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/metadata.d.ts +9 -0
- package/dist/local/store/sqlite/key-storage/metadata.d.ts.map +1 -1
- package/dist/local/store/sqlite/key-storage/metadata.js +12 -0
- package/dist/local/store/sqlite/key-storage/metadata.js.map +1 -1
- package/dist/local/store/sqlite/store.d.ts +2 -1
- package/dist/local/store/sqlite/store.d.ts.map +1 -1
- package/dist/local/store/sqlite/store.js +3 -0
- package/dist/local/store/sqlite/store.js.map +1 -1
- package/dist/local/store/web/adapter.d.ts +8 -1
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +18 -0
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/remote/relay/request-admission.d.ts +49 -0
- package/dist/remote/relay/request-admission.d.ts.map +1 -0
- package/dist/remote/relay/request-admission.js +74 -0
- package/dist/remote/relay/request-admission.js.map +1 -0
- package/dist/types/api.d.ts +77 -0
- package/dist/types/api.d.ts.map +1 -1
- package/dist/types/errors.d.ts +144 -1
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/errors.js +146 -1
- package/dist/types/errors.js.map +1 -1
- package/docs/ASSURANCE.md +31 -15
- package/docs/DEVIATIONS.md +34 -4
- package/docs/ERROR_HANDLING.md +134 -7
- package/docs/GETTING_STARTED.md +30 -23
- package/docs/PROTOCOL_POLICY.md +31 -20
- package/groups/README.md +1 -1
- package/hooks/README.md +6 -3
- package/local/store/react-native/README.md +9 -10
- package/local/store/web/README.md +1 -1
- package/package.json +1 -1
- package/safety/README.md +48 -11
package/docs/ERROR_HANDLING.md
CHANGED
|
@@ -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
|
|
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
|
|
162
|
-
| `PROTOCOL_UNSUPPORTED` | The Relay does not serve version
|
|
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
|
-
|
|
302
|
-
|
|
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
|
package/docs/GETTING_STARTED.md
CHANGED
|
@@ -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
|
|
33
|
-
|
|
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.
|
|
157
|
-
|
|
158
|
-
|
|
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
|
|
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
|
-
|
|
166
|
-
client holds
|
|
167
|
-
|
|
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
|
-
|
|
172
|
-
|
|
173
|
-
|
|
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:
|
|
488
|
+
<!-- doc-snippet:skip configuration-only -->
|
|
484
489
|
```ts
|
|
485
|
-
|
|
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
|
package/docs/PROTOCOL_POLICY.md
CHANGED
|
@@ -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:
|
|
13
|
+
<!-- doc-snippet:skip configuration-only -->
|
|
14
14
|
```ts
|
|
15
|
-
|
|
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`)
|
|
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
|
|
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.
|
|
134
|
-
|
|
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:
|
|
139
|
+
<!-- doc-snippet:skip requires-application-membership -->
|
|
138
140
|
```ts
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
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
|
|
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
|
-
|
|
191
|
-
|
|
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`.
|
|
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
|
|
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
|
|
5
|
-
[op-sqlite](https://github.com/OP-Engineering/op-sqlite). The
|
|
6
|
-
|
|
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
|
|
90
|
-
|
|
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
|
-
|
|
119
|
-
|
|
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
|
|
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
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
|
-
|
|
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
|
-
|
|
27
|
-
|
|
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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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.
|