@open-e2ee/signal-protocol-sdk 13.5.1 → 14.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 +329 -0
- package/README.md +2 -2
- package/SECURITY.md +2 -2
- package/device/README.md +4 -3
- package/dist/client/client.d.ts +20 -55
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +133 -165
- package/dist/client/client.js.map +1 -1
- package/dist/client/content-adapter.d.ts +35 -6
- package/dist/client/content-adapter.d.ts.map +1 -1
- package/dist/client/content-adapter.js +28 -0
- package/dist/client/content-adapter.js.map +1 -1
- package/dist/client/event-hooks.d.ts +22 -11
- package/dist/client/event-hooks.d.ts.map +1 -1
- package/dist/client/event-hooks.js.map +1 -1
- package/dist/client/group-fetcher.d.ts.map +1 -1
- package/dist/client/group-fetcher.js +43 -0
- package/dist/client/group-fetcher.js.map +1 -1
- package/dist/client/group-key-sync.d.ts +65 -0
- package/dist/client/group-key-sync.d.ts.map +1 -0
- package/dist/client/group-key-sync.js +286 -0
- package/dist/client/group-key-sync.js.map +1 -0
- package/dist/client/group-outbox.d.ts +20 -6
- package/dist/client/group-outbox.d.ts.map +1 -1
- package/dist/client/group-outbox.js +153 -80
- package/dist/client/group-outbox.js.map +1 -1
- package/dist/client/group-receive-authorization.d.ts +16 -9
- package/dist/client/group-receive-authorization.d.ts.map +1 -1
- package/dist/client/group-receive-authorization.js +25 -16
- package/dist/client/group-receive-authorization.js.map +1 -1
- package/dist/client/hosted.d.ts +7 -7
- package/dist/client/hosted.js +7 -7
- 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 +3 -4
- package/dist/client/receive-queue.d.ts.map +1 -1
- package/dist/client/receive-queue.js +24 -32
- package/dist/client/receive-queue.js.map +1 -1
- package/dist/client/relay-subscription.d.ts.map +1 -1
- package/dist/client/relay-subscription.js +4 -9
- package/dist/client/relay-subscription.js.map +1 -1
- package/dist/client/retry-request-envelope.d.ts +4 -2
- package/dist/client/retry-request-envelope.d.ts.map +1 -1
- package/dist/client/retry-request-envelope.js +6 -4
- package/dist/client/retry-request-envelope.js.map +1 -1
- package/dist/client/retry-request-lifecycle.d.ts +7 -8
- package/dist/client/retry-request-lifecycle.d.ts.map +1 -1
- package/dist/client/retry-request-lifecycle.js +10 -7
- package/dist/client/retry-request-lifecycle.js.map +1 -1
- package/dist/client/retry-terminal-recovery.d.ts +14 -15
- package/dist/client/retry-terminal-recovery.d.ts.map +1 -1
- package/dist/client/retry-terminal-recovery.js +16 -17
- package/dist/client/retry-terminal-recovery.js.map +1 -1
- package/dist/client/retry-utils.d.ts +22 -0
- package/dist/client/retry-utils.d.ts.map +1 -1
- package/dist/client/retry-utils.js +30 -0
- package/dist/client/retry-utils.js.map +1 -1
- package/dist/client/send-deadline.js +1 -1
- package/dist/client/send-deadline.js.map +1 -1
- package/dist/client/send-timestamp.d.ts +71 -14
- package/dist/client/send-timestamp.d.ts.map +1 -1
- package/dist/client/send-timestamp.js +87 -19
- package/dist/client/send-timestamp.js.map +1 -1
- package/dist/client/signal-service-cipher.d.ts +125 -13
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +413 -102
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/client/types.d.ts +21 -16
- 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/internal/groups/key-sync-ledger.d.ts +65 -0
- package/dist/internal/groups/key-sync-ledger.d.ts.map +1 -0
- package/dist/internal/groups/key-sync-ledger.js +104 -0
- package/dist/internal/groups/key-sync-ledger.js.map +1 -0
- package/dist/internal/groups/receive-record.d.ts +4 -1
- package/dist/internal/groups/receive-record.d.ts.map +1 -1
- package/dist/internal/groups/receive-record.js.map +1 -1
- package/dist/internal/session/cipher.d.ts.map +1 -1
- package/dist/internal/session/cipher.js +14 -0
- package/dist/internal/session/cipher.js.map +1 -1
- package/dist/local/store/conformance/cases/durability.d.ts.map +1 -1
- package/dist/local/store/conformance/cases/durability.js +6 -0
- package/dist/local/store/conformance/cases/durability.js.map +1 -1
- package/dist/local/store/conformance/records.d.ts.map +1 -1
- package/dist/local/store/conformance/records.js +3 -0
- package/dist/local/store/conformance/records.js.map +1 -1
- package/dist/local/store/expo/adapter.js +2 -2
- package/dist/local/store/expo/adapter.js.map +1 -1
- package/dist/local/store/key-value/adapter.d.ts +6 -5
- package/dist/local/store/key-value/adapter.d.ts.map +1 -1
- package/dist/local/store/key-value/adapter.js +21 -19
- package/dist/local/store/key-value/adapter.js.map +1 -1
- package/dist/local/store/key-value/receive-work.d.ts +0 -5
- package/dist/local/store/key-value/receive-work.d.ts.map +1 -1
- package/dist/local/store/key-value/receive-work.js +0 -16
- package/dist/local/store/key-value/receive-work.js.map +1 -1
- package/dist/local/store/node/adapter.js +2 -2
- package/dist/local/store/node/adapter.js.map +1 -1
- package/dist/local/store/react-native/adapter.js +2 -2
- package/dist/local/store/react-native/adapter.js.map +1 -1
- package/dist/local/store/receive-work.d.ts +32 -32
- package/dist/local/store/receive-work.d.ts.map +1 -1
- package/dist/local/store/receive-work.js +112 -65
- package/dist/local/store/receive-work.js.map +1 -1
- package/dist/local/store/received-content.d.ts +0 -5
- package/dist/local/store/received-content.d.ts.map +1 -1
- package/dist/local/store/received-content.js +0 -17
- package/dist/local/store/received-content.js.map +1 -1
- package/dist/local/store/reliability.d.ts +191 -53
- package/dist/local/store/reliability.d.ts.map +1 -1
- package/dist/local/store/reliability.js +517 -37
- package/dist/local/store/reliability.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/metadata.d.ts +1 -8
- package/dist/local/store/sqlite/key-storage/metadata.d.ts.map +1 -1
- package/dist/local/store/sqlite/key-storage/metadata.js +1 -18
- package/dist/local/store/sqlite/key-storage/metadata.js.map +1 -1
- package/dist/local/store/sqlite/migrations.d.ts.map +1 -1
- package/dist/local/store/sqlite/migrations.js +8 -0
- package/dist/local/store/sqlite/migrations.js.map +1 -1
- package/dist/local/store/sqlite/store.d.ts +5 -5
- package/dist/local/store/sqlite/store.d.ts.map +1 -1
- package/dist/local/store/sqlite/store.js +29 -9
- package/dist/local/store/sqlite/store.js.map +1 -1
- package/dist/local/store/web/adapter.d.ts +11 -10
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +69 -51
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/local/store/web-sqlite/adapter.js +2 -2
- package/dist/local/store/web-sqlite/adapter.js.map +1 -1
- package/dist/types/api.d.ts +50 -71
- package/dist/types/api.d.ts.map +1 -1
- package/dist/types/errors.d.ts +52 -18
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/errors.js +58 -17
- package/dist/types/errors.js.map +1 -1
- package/docs/ASSURANCE.md +5 -5
- package/docs/DEVIATIONS.md +126 -9
- package/docs/ERROR_HANDLING.md +38 -23
- package/docs/GETTING_STARTED.md +17 -0
- package/local/store/README.md +32 -8
- package/package.json +1 -1
package/docs/DEVIATIONS.md
CHANGED
|
@@ -91,15 +91,17 @@ model and what is out of scope.
|
|
|
91
91
|
| **Cross-tab locks** | Signal's Desktop and Android clients | **Faithful** in a browser: a group send and each session write take a Web Lock named by the store identity, so the tabs and workers of one origin run them one at a time. **Deviation** elsewhere: the lock orders one store object in one process | Signal runs one process for each device. Only the browser stores have a store identity, and Web Locks in Node order one process only | Two processes, or two store objects, that share one database need exclusive access from the application (§7.6) |
|
|
92
92
|
| **Group send route** | Signal's server, multi-recipient send | **Faithful** in the SDK: each group send goes to the anonymous group route with a group send token. The Relay still serves an identified group route that no SDK release calls | The Relay removes the identified route forward only | Until the removal, a client that posts to the identified route sends under its account credential, with no device-set check when the post declares none (§7.7) |
|
|
93
93
|
| **Groups** | Signal Private Group System | **Independent design.** Real zkgroup primitives underneath; profile-key credential issuance blinds the ACI-bound profile-key attribute, the server validates every change against zero-knowledge presentations and signs the accepted result, and clients verify those signatures | Ships a validating group server with an enforcement contract (S1–S14) specified in-tree | Not wire-compatible with the Signal Private Group System; credentials are not interchangeable. The issuer sees the authenticated ACI and redemption window, but not the raw profile key |
|
|
94
|
+
| **Group content with no group context** | Signal's client routing of group content | **Faithful** for content that no transport binds to a group: it takes no group decision, and direct content stays direct. **Deviation** for managed groups: content that the sender key of a managed group decrypted, content that came beside its sender key distribution, and a sent transcript to it are denied as `legacy-no-context` when they carry no group context. **Deviation** for ad hoc groups: content that the sender key of an ad hoc group decrypted, or that came beside its distribution, takes no group decision and is delivered in that ad hoc group. Upstream routes content with no group context to the direct conversation of the sender | The SDK binds that content to its group by the transport. A direct delivery would show content of the group in a direct conversation. Managed group content carries its context since SDK 12.0.0 | Content of a managed group from an SDK 11 sender is not delivered. Ad hoc group content with no group context arrives in its ad hoc group, not in a direct conversation (§7.8) |
|
|
94
95
|
| **Receive order** | Signal's Android client | **Faithful.** The receive queue (`client/receive-queue.ts`) holds back the later records of one conversation, as Android queues its message jobs: group content per group, a sent transcript per destination, and other content per sender account. The commit order stays per sender device | — | A record that waits for its group state holds back the later content of its group from every sender until a fetch of its group or `syncGroup` completes, or until the record expires after 30 days. Direct chats and other groups make progress. A record in hook backoff holds back its conversation until its hook succeeds, it reaches the hook attempt cap of 10, or it expires. Before the queue restores a record, it keys the record by its stored group or by its sender account. A missing sender key does not hold the queue: that content goes to the retry request handler |
|
|
95
96
|
| **Receive hook attempt cap** | Signal's Desktop client | **Deviation.** After 10 failed `onMessageDecrypted` attempts, a record no longer holds back its conversation, as on Desktop. Desktop deletes the record at startup. The SDK keeps it, offers it to the hook once at each start, shows the count in `PendingReceive.hookAttempts`, and removes it at `discardPendingReceive` | The hook is application code. A drop loses content whose ratchet step is spent, and an application update can repair the hook | A hook that ends the process on the record ends it once at each start, until the record expires or the application discards it (§8.2) |
|
|
96
97
|
| **Receive hook bound** | Signal's Desktop client | **Deviation** in detail. Each application hook that a receive pass awaits has a bound, `receiveHookTimeoutMs`, 2 minutes by default. Desktop bounds its receive dispatch at 2 minutes and its long-running tasks at 30 minutes | A founder ruling sets the bound at 2 minutes. The SDK cannot tell a slow hook from a hung one | A timeout of `onMessageDecrypted` counts as one failed attempt. A timeout of another hook is logged, and the pass continues. A settle after the bound writes nothing (§8.4) |
|
|
97
98
|
| **Delivery receipt lifespan** | Signal's Android client | **Faithful.** A stored receipt is sent only within 1 day after it becomes owed, as Android's receipt job lives for 1 day. The receipt is durable across a restart, as on Android | — | A receipt that cannot go out within 1 day is not sent, and no hook reports it (§8.3) |
|
|
98
99
|
| **Receive admission bounds** | Signal's Desktop client | **Extension.** Before a decrypt, the receive queue checks `maxItems`, `maxBytes`, and the group share `blockedGroupShare`. The defaults are provisional. Desktop decrypts each envelope as it arrives and bounds stored content only by age and attempts | The SDK shares a storage budget with the application in a browser and on mobile | A refused envelope is not acknowledged. It stays at the Relay and expires there with no local hook. The messages behind it still arrive (§8.5) |
|
|
100
|
+
| **Legacy received content** | Signal's job migration of a retired format | **Faithful** for unreadable rows: the open deletes them and logs a count. **Deviation** for readable rows: the open deletes each readable SDK 11 row too, and counts it in a separate field. Signal converts each readable pending item to the new format | A founder ruling deletes the readable rows. The constraint is Relay retention: the Relay keeps an undelivered envelope for at most 30 days in production, and a readable row is in a store that SDK 12.0.0 or later never opened | Where the constraint holds, the content of such a row never reaches the application. A device that received the content on SDK 11 inside the last 30 days is not covered: 13.x would complete that row on redelivery, and the sweep does not restore it. The count line holds no key and no value (§8.6) |
|
|
99
101
|
| **zkgroup / zkcredential** | `libsignal` `zkgroup`, `zkcredential`, `poksho` | **Faithful** port of the Ristretto255 KVAC and Sigma-protocol system, verified against `libsignal`'s known-answer vectors. **Deviation:** server parameter derivation is structured as four labeled derivations rather than one seeded derivation | Server keys are the deploying operator's own trust root (each deployment generates its own seed), not Signal Messenger's | The zero-knowledge properties are real. Credentials are not interchangeable with Signal Messenger's |
|
|
100
102
|
| **Registration IDs** | `libsignal` `sealed_sender.rs` | **Faithful.** Generated in `[1, 16383]`, strictly inside the 14 bits the wire format reserves | — | — |
|
|
101
103
|
| **Linked-device registration IDs** | Signal's device linking | **Faithful** for a new link: the linked device gets its own fresh registration ID. **Deviation:** a device that a 12.0.x release linked keeps the ID of its active device, and a link that a 12.0.x release began keeps its stored ID (§5.7) | A changed ID on a live device fails its next prekey sync. A fresh ID on a link already begun can reserve a second device | Two devices of one account can share a registration ID. The sender-key handoff ledger keys each row by the device, so they stay apart |
|
|
102
|
-
| **Linked-device group keys** | Signal's device linking | **Deviation.** The link copies each group master key from the active device's group store in the calling process. A group record that a release before 12.0.0 wrote, and that the active device has not read since, is not copied (§5.8) | The SDK has no storage service, and no master key
|
|
104
|
+
| **Linked-device group keys** | Signal's device linking | **Deviation.** The link copies each group master key from the active device's group store in the calling process. A group record that a release before 12.0.0 wrote, and that the active device has not read since, is not copied (§5.8) | The SDK has no storage service, and the link sends no master key through the Relay | The process that links the device must hold the active device's store. Such an unread group initializes from its first group message |
|
|
103
105
|
| **Posting deadline and send progress** | Signal's Android client `IndividualSendJob`; Signal's Desktop client `conversationJobQueue` | **Faithful** on a window of 1 day and on progress at the deadline: an accepted device stays accepted. **Deviation** in detail. The deadline also ends 24 hours after the send timestamp, has no message-expiry term, and never moves on a restart. A lost Relay answer is acceptance-unknown, not failed. An automatic retry posts the stored bytes and epoch. With a store that lists its metadata keys, the SDK replays open sends at start and on reconnect, as the Signal job runners do, and reports each end once through `onSendOutcome`. On a custom store without the listing method, the application replays (§5.9) | The Relay admits an epoch at most 24 hours behind its clock, keeps a fingerprint of each operation, and charges each accepted operation. Custom stores stay supported, so the listing method is optional | A direct send posts nothing at or after its deadline. When the acceptance of a device is not known, the send throws `SendAcceptanceUnknownError`, and a replay or a resend after it can add one charged unit. When the plaintext of an open send is gone, `onSendOutcome` reports `content-required` |
|
|
104
106
|
|
|
105
107
|
---
|
|
@@ -906,7 +908,7 @@ it never runs.
|
|
|
906
908
|
|
|
907
909
|
### 5.6 Device-set reconciliation differs in detail
|
|
908
910
|
|
|
909
|
-
Reviewed: 2026-
|
|
911
|
+
Reviewed: 2026-11-01.
|
|
910
912
|
|
|
911
913
|
The reconciliation of §5.5 follows Signal's server and Signal's Desktop
|
|
912
914
|
client in its rule: the server compares, the client repairs and posts again,
|
|
@@ -919,7 +921,7 @@ Signal's Android client. The following details differ.
|
|
|
919
921
|
| D1 | A stale registration is reported after missing and extra devices on every route, also for a direct post to one account | One answer order for every route | Signal's server reports stale devices first on its route for one account | Relay tests assert the order on each route |
|
|
920
922
|
| D2 | A direct send is one post for each device, and each post carries the full declaration of the account | The direct Relay route takes one destination for each body. A replay works for each device | One Signal request carries every device of the account. Here a race can accept some posts and refuse others | A restart posts the stored bytes to each accepted device, and each device gets the message once. A partly accepted pass posts every device again, and an accepted device replays |
|
|
921
923
|
| D3 | A group comparison reads the record of each account, up to 1,000, when the Relay accepts the post | The Relay keeps one record for each account | Signal's server reads accounts from one store in one process | Relay tests, and a cost measurement |
|
|
922
|
-
| D4 | The operation time is fixed. `OPERATION_EXPIRED` ends the reconciliation as acceptance-unknown. A new send refuses an application timestamp outside the delivery window with `InvalidSendTimestampError`. A manual resend carries its own stored operation time (row P8) | From the Relay release that follows v2026.10.25, the Relay admits a mailbox delivery epoch and a new group fan-out operation at most 5 minutes ahead of its clock and at most 24 hours behind it. Earlier Relay releases admit a new operation only within 5 minutes of its epoch. On an earlier Relay release, a time 5 minutes to 24 hours old passes the SDK check but gets `OPERATION_EXPIRED`. The SDK check uses the same bounds, so the SDK refuses an application-supplied time before any post | Signal has no admission window | A restart post that gets `OPERATION_EXPIRED` ends the phase as expired, and a recipient-phase end stores the outcome `acceptance-unknown`. A new send with a timestamp outside the window throws `InvalidSendTimestampError`, and stores and posts nothing |
|
|
924
|
+
| D4 | The operation time is fixed. `OPERATION_EXPIRED` ends the reconciliation as acceptance-unknown. A new send refuses an application timestamp outside the delivery window with `InvalidSendTimestampError`. Each send timestamp is unique per sender device: a new send refuses a timestamp that a different send of the device used, with the reason `already_used`, and a timestamp from the SDK clock moves to the next free millisecond. A manual resend and a retry answer keep the original timestamp and reserve none. A manual resend carries its own stored operation time (row P8) | From the Relay release that follows v2026.10.25, the Relay admits a mailbox delivery epoch and a new group fan-out operation at most 5 minutes ahead of its clock and at most 24 hours behind it. Earlier Relay releases admit a new operation only within 5 minutes of its epoch. On an earlier Relay release, a time 5 minutes to 24 hours old passes the SDK check but gets `OPERATION_EXPIRED`. The SDK check uses the same bounds, so the SDK refuses an application-supplied time before any post | Signal has no admission window | A restart post that gets `OPERATION_EXPIRED` ends the phase as expired, and a recipient-phase end stores the outcome `acceptance-unknown`. A new send with a timestamp outside the window, or with the timestamp of a different send of the device, throws `InvalidSendTimestampError`, and stores and posts nothing |
|
|
923
925
|
| D5 | No fallback to one post for each recipient after the bound | The same bound covers every path | Signal's Desktop client falls back because its one-to-one path has no bound. Under the bound, a fallback only moves the churn | The 11th refusal of a phase ends the send with `DeviceSetReconciliationError` |
|
|
924
926
|
| D6 | A direct send also stops at 10 restarts | One bound for every send | Signal's Desktop client has no bound on missing or extra devices for a one-to-one send | The restart bound test of the direct send |
|
|
925
927
|
| D7 | No empty sync post. A `needsSync` mark on the recipient receipt and one read of the own list replace it | A Relay post needs at least one destination | Signal's server accepts an empty sync list, and Signal's Android client addresses its own device | A new own device repairs the sync phase and the recipient post is not sent again. The own list is read only on `needsSync` with no own record, and a failed read leaves the sync phase pending |
|
|
@@ -948,7 +950,7 @@ device has its own registration ID. Two cases keep an ID.
|
|
|
948
950
|
|
|
949
951
|
### 5.8 Group keys of linked devices
|
|
950
952
|
|
|
951
|
-
Reviewed: 2026-
|
|
953
|
+
Reviewed: 2026-11-01.
|
|
952
954
|
|
|
953
955
|
A managed device link copies the master key of each group that the active
|
|
954
956
|
device's group store lists into the linked device's group store. The copy runs
|
|
@@ -956,14 +958,27 @@ in the process that calls the link. A later client on the linked device fetches
|
|
|
956
958
|
each copied group with no application step. In Signal, a linked device restores
|
|
957
959
|
its groups from the storage service.
|
|
958
960
|
|
|
961
|
+
After the link, each own device sends the key of each group that its group
|
|
962
|
+
store lists, whose record is verified, and whose stored state lists the
|
|
963
|
+
account as a member, to each other own device until the ledger marks the
|
|
964
|
+
pair, in an end-to-end encrypted `GroupKeySync`. The ledger marks an own
|
|
965
|
+
device when the Relay accepts a copy for that device's registration, and it
|
|
966
|
+
marks the own device that sent this device the key. Three events send a key:
|
|
967
|
+
the device creates or joins a group, the device accepts a group invitation,
|
|
968
|
+
and the device sees an own device for the first time. Each start also sends
|
|
969
|
+
the key again for each pair of a group and an own device that the ledger does
|
|
970
|
+
not mark. So a group that a device creates or joins after the
|
|
971
|
+
link reaches the other own devices with no group traffic. This follows Signal,
|
|
972
|
+
which sends a group key sync to the own devices.
|
|
973
|
+
|
|
959
974
|
| ID | Deviation | Constraint | Why Signal's form does not fit | Guarantee test |
|
|
960
975
|
|---|---|---|---|---|
|
|
961
|
-
| G1 | The link copies group master keys in the calling process |
|
|
976
|
+
| G1 | The link copies group master keys in the calling process | The link sends no master key through the Relay, and the adapter gets no private key | The SDK has no storage service | Each listed group arrives on the linked device with the master key of the active device and initializes with no application step. A link stopped at any write of the copy and restarted, also in a new browser tab, ends with the group set of the active device. A Relay refusal removes each copied group |
|
|
962
977
|
| G2 | A group record that a release before 12.0.0 wrote, and that the active device has not read since, is not copied | The group store lists only migrated records. The link has no other source of the group IDs | Signal restores each group from the storage service | Such a group initializes on the linked device from its first group message. Read each group once on the active device before the link to copy it |
|
|
963
978
|
|
|
964
979
|
### 5.9 The posting deadline and send progress
|
|
965
980
|
|
|
966
|
-
Reviewed: 2026-
|
|
981
|
+
Reviewed: 2026-11-01.
|
|
967
982
|
|
|
968
983
|
Signal's Android client gives a send job a lifespan of one day from its
|
|
969
984
|
creation, and Signal's Desktop client stops a send job one day after its
|
|
@@ -986,8 +1001,8 @@ A retry request has its own posting deadline, in row P9. The following details d
|
|
|
986
1001
|
| P5 | An automatic retry posts the stored bytes and the stored epoch, also for a retry resend | The Relay keeps a fingerprint of each operation and answers `RETRY_CONFLICT` to other bytes under one ID. A fresh epoch makes a new charged operation | Signal encrypts the content again for each attempt | A replay after a restart posts the same bytes under the same ID and the first epoch, and a repair keeps that epoch. A stored retry resend that gets `OPERATION_EXPIRED` keeps its stored epoch and bytes, posts nothing more under its ID and encrypts nothing again |
|
|
987
1002
|
| P6 | The SDK stores the progress of each destination device, for recipients and sync copies. Before each request, it marks the device as posted and counts the request. At the end, a device counts as refused only when its stored answer is a refusal or a pending answer and its `uncertain` flag is unset. A request with no answer, an uncertain answer, or a send that SDK 13.3 stored sets the flag for good. A replay skips a refused device, and counts it toward an end at once, only when no recovery in the call can change the refusal or its repair already ran | The Relay can store a post whose answer the SDK does not get, and a later post under the same ID can add one charged unit. The Relay gives a refusal or a pending answer before it stores the post | Signal has no charged operation, so it does not keep a durable mark of each request | A replay after a restart posts only the devices with no stored acceptance. A replay ends at once, and posts nothing, when each open device has a stored refusal that the SDK cannot recover, and throws an `Error` with the stored code of the first refused device that has one, in the order of the destinations. A stored `STALE_DEVICE` refusal with no spent repair gets a new post. A crash after a request, or a send that SDK 13.3 stored, ends with `SendAcceptanceUnknownError` when the replay gets `OPERATION_EXPIRED` |
|
|
988
1003
|
| P7 | A repair of a stale device keeps the operation and its epoch. A `RETRY_CONFLICT` answer to the repaired post makes the device unknown, not accepted. The repair writes its mark to the stored progress, and the same call reads that mark | The repaired post has new bytes under the kept ID. The Relay answers `RETRY_CONFLICT` when it holds other bytes for that ID, so the SDK cannot tell which bytes it holds | Signal encrypts the content again for each attempt | A `RETRY_CONFLICT` answer to a repaired post throws a retryable `RETRY_CONFLICT` error, and the device is stored unknown with the `uncertain` flag. The answer never counts as an earlier acceptance, in the same call or on a replay |
|
|
989
|
-
| P8 | A manual resend with `resendMessage` after a send end is a new operation. It has a fresh stored operation time, the message ID `<clientMessageId>:manual:N` and its own posting deadline 24 hours after its creation. Its content keeps the original timestamp, and the receive queue of a recipient drops a copy with the same sender
|
|
990
|
-
| P9 | A retry request has a posting deadline 24 hours after the first failure of its message, and no post starts at or after it. A request whose post is due then ends as `posting-deadline`. After its posting deadline, a request whose post the Relay accepted posts nothing more and waits for its content until its 14-day deadline. `OPERATION_EXPIRED` before the posting deadline ends the request as `posting-deadline` with acceptance unknown. Each `posting-deadline` end resets the session, emits one `onRetryTerminal` event and posts no replacement attempt | The Relay admits an epoch at most 24 hours behind its clock. Its `OPERATION_EXPIRED` also answers an accepted operation that left its retained period, so it does not prove that the Relay holds nothing. The founder ruling "DA1 F3 OPERATION_EXPIRED before the posting deadline: end as acceptance-unknown now, resend on proof after DA1-Q3 (2026-10-28, founder)" sets this end. The version 2 code `DELIVERY_ALREADY_ACCEPTED` proves that the Relay holds the attempt, so a retry request reads it as `RETRY_CONFLICT` and posts no replacement | Signal's server refuses a send only for a wrong device set, before it stores anything, so a Signal client repairs and sends again at once. Signal's Android client gives its retry receipt job a lifespan of one day | A stored attempt that gets `OPERATION_EXPIRED` before the posting deadline posts no attempt 2, ends as `posting-deadline`, resets the session and emits one `onRetryTerminal` event. A fresh attempt and a stale-session repeat end the same way. No retry request posts at or after its first failure plus 24 hours, also after a restart. A request whose post the Relay accepted posts nothing after its posting deadline and ends as `
|
|
1004
|
+
| P8 | A manual resend with `resendMessage` after a send end is a new operation. It has a fresh stored operation time, the message ID `<clientMessageId>:manual:N` and its own posting deadline 24 hours after its creation. Its content keeps the original timestamp, and the receive queue of a recipient drops a copy with the same sender and the same original timestamp. The drop needs the timestamp that the content adapter reads from the message, so raw string or byte content takes no drop key and a recipient that holds it receives the copy again. A resend of a group send posts the content of its send log entry, so each copy carries the group context of the original send, not the current one. The recipient records the message with the completion of its receive record. When a delivery receipt is due, it records the message right after the receipt-due write and again with the completion of the receipt. The record expires after 60 days. The caller-origin receive path gives every decrypted message to the caller, and a caller that keeps its own records removes a copy itself. Only a send younger than 30 days takes a new manual resend. The Relay can charge the resend as a new message, and the message might already have arrived | The Relay admits an operation time at most 24 hours behind its clock and charges each accepted operation. The founder ruling "DA1 F4 manual resend identity: a fresh operation epoch with the original timestamp in the content (2026-10-28, founder)" sets this identity. The SDK encrypts the content again for each device, as the retry-request resend does | Signal's clients resend the stored message with its original timestamp in a new job, and the receivers drop a copy by sender and timestamp alone. The SDK uses the same key. The key has no conversation, so a sent transcript from a second own device with the same timestamp drops with no hook, also when the two transcripts name two conversations. A Signal client drops a duplicate transcript by the same key, so that drop is upstream-equal behavior and not a deviation. Signal's server keeps no operation time and charges no send | A resend posts under a fresh operation time and the manual message ID, with the original timestamp in the content. The Relay admits it after the original ended at its deadline. The entry stores its operation time, and a stored send without manual entries reads as an empty list. A recipient that holds the original drops the resend copy, and a recipient that never got the original receives it once. A later message of the same sender with the same timestamp drops, from any device of the sender. Two own devices send transcripts with one timestamp to two conversations, and the second transcript drops with no hook. When no receipt is owed, a stop before the completion of the receive record runs `onMessageDecrypted` again. When a receipt is owed, only a stop before the receipt-due write runs it again. A new resend at or after 30 days from the send throws and posts nothing |
|
|
1005
|
+
| P9 | A retry request has a posting deadline 24 hours after the first failure of its message, and no post starts at or after it. A request whose post is due then ends as `posting-deadline`. After its posting deadline, a request whose post the Relay accepted posts nothing more and waits for its content until its 14-day deadline. At that deadline, a retry request whose latest attempt the Relay answered or holds ends as `request-expired` and resets no session. A retry request whose latest attempt the Relay did not accept ends as `posting-deadline`. `OPERATION_EXPIRED` before the posting deadline ends the request as `posting-deadline` with acceptance unknown. Each `posting-deadline` end resets the session, emits one `onRetryTerminal` event and posts no replacement attempt. At client start, the SDK moves each stored retry request record to the current key prefix, and rewrites a stored `expired-content` end as `request-expired` with its time, its emitted flag and its recovery. The reader also reads a stored `expired-content` end as `request-expired`, until the next major SDK version and for at least 60 days after the publish day of 14.0.0 | The Relay admits an epoch at most 24 hours behind its clock. Its `OPERATION_EXPIRED` also answers an accepted operation that left its retained period, so it does not prove that the Relay holds nothing. The founder ruling "DA1 F3 OPERATION_EXPIRED before the posting deadline: end as acceptance-unknown now, resend on proof after DA1-Q3 (2026-10-28, founder)" sets this end. The version 2 code `DELIVERY_ALREADY_ACCEPTED` proves that the Relay holds the attempt, so a retry request reads it as `RETRY_CONFLICT` and posts no replacement | Signal's server refuses a send only for a wrong device set, before it stores anything, so a Signal client repairs and sends again at once. Signal's Android client gives its retry receipt job a lifespan of one day | A stored attempt that gets `OPERATION_EXPIRED` before the posting deadline posts no attempt 2, ends as `posting-deadline`, resets the session and emits one `onRetryTerminal` event. A fresh attempt and a stale-session repeat end the same way. No retry request posts at or after its first failure plus 24 hours, also after a restart. A request whose post the Relay accepted posts nothing after its posting deadline, ends as `request-expired` at its deadline and resets no session. A request whose posts all failed, and that no pass ended at its posting deadline, ends as `posting-deadline` at its deadline and resets the session. The class `request-expired` is not the delivery error cause `request-ended`. A stored `expired-content` end moves to the current prefix as `request-expired`, with its time, its emitted flag and its recovery kept. A stored `expired-content` record that the move has not reached reads as `request-expired`. A retry request that SDK 13.3 stored derives the posting deadline from its first failure, at most its deadline. A stored `posting-deadline` record reads back, and an unknown terminal class or a posting deadline that is not a number still reads as corrupt |
|
|
991
1006
|
| P10 | With a store that implements `listMetadataKeys`, as every built-in store does, the SDK replays each open send at start and when the Relay connection returns, ends each send at its posting deadline, and reports each end once through `onSendOutcome`. An internal send of the SDK, such as a sender key distribution, never reaches `onSendOutcome`. The SDK keeps no content of a sender key distribution at rest, so it does not replay one: with the listing method, it ends an open distribution at its deadline and reports nothing, and a retry request of the receiver recovers a lost distribution, as in Signal. An open sender key distribution that an earlier SDK version stored carries no marker, so the SDK reports `content-required` for it once for each client run before its deadline, and reports its end through `onSendOutcome` once, at its deadline. When the stored plaintext of an open send is gone or does not match the send, the SDK reports `content-required` once for each client run, and the send stays open until its deadline. On a custom store without the optional listing method, the SDK does not replay open sends by itself, and the application replays with the same `clientMessageId` | The founder ruling "Managed-group receive follows Signal's complete workflow (DA13-L correction)" keeps custom stores supported through a documented contract and conformance tests, so the store contract does not require the listing method. The SDK keeps the plaintext of a send only when the store and the content recovery policy keep resendable content | Signal's clients keep each pending send as a job, with its content, in their own database, and run the job queue at start and when the network returns. The SDK runs on a store that the application provides, and that store can keep no content | An open send replays at start under its stored epoch and bytes, and again when the Relay connection returns. A send past its deadline at start ends with the class that its stored progress gives, posts nothing, and reports once, also across a restart before the report. A send whose plaintext is gone or does not match its digest reports `content-required` once for each client run. A store without the method starts no driver, logs one line, and still reports the end of an application send, and the conformance suite skips its listing cases on that store |
|
|
992
1007
|
|
|
993
1008
|
---
|
|
@@ -1460,11 +1475,67 @@ and it checks no device set when the post declares none. The constraint is
|
|
|
1460
1475
|
that the Relay removes a served route forward only. The SDK does not depend on
|
|
1461
1476
|
the route, so its removal changes no SDK behavior.
|
|
1462
1477
|
|
|
1478
|
+
### 7.8 Group content with no group context
|
|
1479
|
+
|
|
1480
|
+
Reviewed: 2026-11-02.
|
|
1481
|
+
|
|
1482
|
+
A Signal client routes each received message by the group context in its
|
|
1483
|
+
content. Content with no group context goes to the direct conversation of the
|
|
1484
|
+
sender, also when a sender key decrypted it. With a context, the client
|
|
1485
|
+
updates the group first, and drops the message only when a member check fails.
|
|
1486
|
+
|
|
1487
|
+
**Faithful** for content that no transport binds to a group.
|
|
1488
|
+
`classifyGroupContent` (`client/group-receive-authorization.ts:145-172`)
|
|
1489
|
+
returns null for content with no group context, unless the transport binds
|
|
1490
|
+
the content to a managed group. Content that no transport binds to a group
|
|
1491
|
+
takes no group decision, and direct content stays in the direct
|
|
1492
|
+
conversation of its sender.
|
|
1493
|
+
|
|
1494
|
+
**Deviation for ad hoc groups.** `classifyGroupContent` also returns null
|
|
1495
|
+
for ad hoc group content with no group context
|
|
1496
|
+
(`client/group-receive-authorization.ts:155-164`). That is content that the
|
|
1497
|
+
sender key of an ad hoc group decrypted, or that came beside its
|
|
1498
|
+
distribution. The client authorizes such content with the transport group
|
|
1499
|
+
as its group (`client/signal-service-cipher.ts:2359-2368`). The delivered
|
|
1500
|
+
envelope has that ad hoc group as its `conversationId` and has
|
|
1501
|
+
`isGroup: true` (`client/signal-service-cipher.ts:2402-2407` and `:2425`).
|
|
1502
|
+
Upstream routes content with no group context to the direct conversation of
|
|
1503
|
+
the sender, also when a sender key decrypted it.
|
|
1504
|
+
|
|
1505
|
+
The constraint is that the SDK binds content to its group by the transport.
|
|
1506
|
+
**Consequence:** ad hoc group content with no group context arrives in its
|
|
1507
|
+
ad hoc group, not in the direct conversation of its sender.
|
|
1508
|
+
|
|
1509
|
+
**Deviation for managed groups.** The transport binds content to a group
|
|
1510
|
+
before the content names one. Content that a sender key decrypted, and
|
|
1511
|
+
content that came beside a sender key distribution, is content of that
|
|
1512
|
+
group. A sent transcript is
|
|
1513
|
+
content of its destination. When that group is a managed group and the
|
|
1514
|
+
content carries no group context, the evaluator denies the content with the
|
|
1515
|
+
reason `legacy-no-context` (`client/group-receive-authorization.ts:264`),
|
|
1516
|
+
also when the client has state of the group. A blocked group gives the
|
|
1517
|
+
reason `blocked` first. The client does not deliver the content as direct
|
|
1518
|
+
content. `processIncomingEnvelope` gives a `denied` outcome and
|
|
1519
|
+
runs `onDecryptionError`. A client with no `groups` config refuses such
|
|
1520
|
+
content with a `GroupReceiveRefusedError` of reason `configuration`
|
|
1521
|
+
(`client/signal-service-cipher.ts:2370`).
|
|
1522
|
+
|
|
1523
|
+
The constraint is that the SDK binds sender-key content and content beside a
|
|
1524
|
+
distribution to its group by the transport. A direct delivery of that content
|
|
1525
|
+
would show content of the group in a direct conversation. Managed group
|
|
1526
|
+
content carries its group context since SDK 12.0.0. **Consequence:** content
|
|
1527
|
+
of a managed group from an SDK 11 sender is not delivered.
|
|
1528
|
+
|
|
1529
|
+
Guarantee tests assert that group content with no group context is denied as
|
|
1530
|
+
`legacy-no-context` also when local group state exists, that a blocked group
|
|
1531
|
+
with such content still reports `blocked`, and that ad hoc content with no
|
|
1532
|
+
group context and no group transport arrives as direct content.
|
|
1533
|
+
|
|
1463
1534
|
---
|
|
1464
1535
|
|
|
1465
1536
|
## 8. Receive queue
|
|
1466
1537
|
|
|
1467
|
-
Reviewed: 2026-
|
|
1538
|
+
Reviewed: 2026-11-02.
|
|
1468
1539
|
|
|
1469
1540
|
The receive queue keeps each decrypted receive in the local store until the
|
|
1470
1541
|
application hook accepts it and the receipt goes out (`client/receive-queue.ts`).
|
|
@@ -1565,6 +1636,52 @@ each pass the check and overshoot a bound.
|
|
|
1565
1636
|
Guarantee tests assert the global item and byte bounds, the group item and
|
|
1566
1637
|
byte shares, the progress of direct and other-group messages beside a full
|
|
1567
1638
|
group, and an HTTP pull past a full page of refused envelopes.
|
|
1639
|
+
### 8.6 The open sweep deletes legacy received content
|
|
1640
|
+
|
|
1641
|
+
A Signal client that retires a job format keeps a converter for it. The
|
|
1642
|
+
converter turns each readable pending item into a job of the new format, and
|
|
1643
|
+
fails each unreadable item with a log line.
|
|
1644
|
+
|
|
1645
|
+
**Faithful** for unreadable rows. At each open, each durable store deletes
|
|
1646
|
+
every SDK 11 received-content row and every converted receive record that
|
|
1647
|
+
waits for its envelope (`local/store/receive-work.ts:326`). The store logs
|
|
1648
|
+
one line with the code `LEGACY_RECEIVED_CONTENT_DELETED` and two counts:
|
|
1649
|
+
`count`, the deleted rows and records, and `readable`, the deleted rows that
|
|
1650
|
+
parse. The line holds no key and no value. An open that finds nothing logs
|
|
1651
|
+
nothing.
|
|
1652
|
+
|
|
1653
|
+
**Deviation.** The sweep also deletes each readable SDK 11 row, and counts it
|
|
1654
|
+
in `readable`. It does not convert the row. The founder ruling "Bundled major
|
|
1655
|
+
deletes readable SDK 11 received-content rows too, with a separate count
|
|
1656
|
+
(2026-10-30, founder)" sets this deletion. The constraint is Relay
|
|
1657
|
+
retention.
|
|
1658
|
+
|
|
1659
|
+
The sweep relies on this constraint. The Relay keeps an undelivered envelope
|
|
1660
|
+
for at most its retention period, 30 days in production. The SDK states
|
|
1661
|
+
this bound as `RELIABILITY_RECORD_TTL_MS` (`local/store/reliability.ts:21`
|
|
1662
|
+
and `:33-35`). The first open of SDK 12.0.0 through 13.x converted each
|
|
1663
|
+
readable row. So a readable SDK 11 row is in a store that SDK 12.0.0 or
|
|
1664
|
+
later never opened.
|
|
1665
|
+
|
|
1666
|
+
On 13.x, a converted row completes when the Relay delivers its envelope
|
|
1667
|
+
again. Otherwise it expires in one `onReceiveExpired` call with no sender.
|
|
1668
|
+
Where the constraint holds, the Relay no longer has the envelope. So a
|
|
1669
|
+
conversion as upstream does it would restore nothing.
|
|
1670
|
+
|
|
1671
|
+
The constraint does not cover a device that received the content on SDK 11
|
|
1672
|
+
inside the last 30 days. For that device, 13.x would convert the row and
|
|
1673
|
+
complete it when the Relay delivers the envelope again. This release
|
|
1674
|
+
deletes the row at first open instead, and the sweep does not restore it.
|
|
1675
|
+
|
|
1676
|
+
**Consequence:** where the constraint holds, the content of such a row never
|
|
1677
|
+
reaches the application, as on SDK 13.x. For a device inside the 30 days,
|
|
1678
|
+
the sweep deletes a row that 13.x would complete.
|
|
1679
|
+
|
|
1680
|
+
Guarantee tests assert that each durable store deletes every legacy row at
|
|
1681
|
+
first open and logs the count once, that a stored record that waits for its
|
|
1682
|
+
envelope is removed and counted, that the log line carries the count and the
|
|
1683
|
+
readable count and no key or value, and that a second open logs nothing.
|
|
1684
|
+
|
|
1568
1685
|
---
|
|
1569
1686
|
|
|
1570
1687
|
## Unverified and needs review
|
package/docs/ERROR_HANDLING.md
CHANGED
|
@@ -83,13 +83,14 @@ holds each member to a production construction site.
|
|
|
83
83
|
| `INVALID_CIPHERTEXT` | The ciphertext format is invalid. | Reject the message. |
|
|
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
|
-
| `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. |
|
|
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. A new send also gets it for a `timestamp` that a different send of the device used. The SDK's own sends, the profile key offer and the sender key distribution, reserve from the same index of the device, so an application that passes `timestamp: Date.now()` can get `already_used` when it did not use the value again itself. The SDK throws `InvalidSendTimestampError` from `@open-e2ee/signal-protocol-sdk/types` and stores or posts nothing for the send. The `reason` is `not_safe_positive_integer`, `too_far_ahead`, `too_old` or `already_used`. `earliest` and `latest` give the window, and are absent for `already_used`. | Omit `timestamp`, so that the SDK picks a free value. On `already_used`, send again with no timestamp. Otherwise send again with a timestamp in the window that no other send used. |
|
|
87
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
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. |
|
|
89
89
|
| `MESSAGE_DUPLICATE` | The session processed this message before. | Discard the duplicate. |
|
|
90
90
|
| `TOO_MANY_SKIPPED_MESSAGES` | The message exceeded the skipped-key bound. | Reset the affected session. |
|
|
91
91
|
| `REPLAY_DETECTED` | Envelope and encrypted-content timestamps differ. | Reject the message as a replay. |
|
|
92
92
|
| `SENDER_KEY_EXPIRED` | The sender key exceeded its rotation period. | Rotate and redistribute the sender key. |
|
|
93
|
+
| `GROUP_MASTER_KEY_MISSING` | A client with a `groups` config has no master key for a managed group in its group store, and a new send, an attachment send, or a manual resend of content with no logged group context goes to that group. Receivers deny managed group content with no group context, so the SDK stores and posts nothing for the send, and an attachment send uploads nothing. A manual resend of logged content that carries a group context keeps that context and does not throw. A replay that must build a sent transcript for an own device skips that transcript, keeps its posts, and logs one warning with this code. | Store the group master key through the link or sync path, then send again. |
|
|
93
94
|
|
|
94
95
|
### Identity and Trust Errors
|
|
95
96
|
|
|
@@ -403,16 +404,14 @@ set to N. Only a send younger than 30 days takes a new resend. At or after
|
|
|
403
404
|
days takes a manual resend` and posts nothing. An open resend of an older
|
|
404
405
|
send still posts until its own deadline.
|
|
405
406
|
|
|
406
|
-
The receive queue of a recipient device drops a copy whose sender
|
|
407
|
-
timestamp
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
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
|
|
407
|
+
The receive queue of a recipient device drops a copy whose sender and
|
|
408
|
+
timestamp match a message that it already processed, for 60 days. A later
|
|
409
|
+
message of the same sender with the same timestamp drops too, with any body
|
|
410
|
+
and from any device of the sender. The drop needs the timestamp that the
|
|
411
|
+
content adapter reads from the message. Content with no timestamp, such as
|
|
412
|
+
raw string or byte content, takes no drop key, and a recipient that holds
|
|
413
|
+
it receives the copy again. The recipient records the message with the
|
|
414
|
+
completion of its receive record. When a delivery receipt is due, it records the message right
|
|
416
415
|
after the receipt-due write and again with the completion of the receipt.
|
|
417
416
|
When no receipt is owed, a stop before the completion of the receive record
|
|
418
417
|
runs `onMessageDecrypted` again. When a receipt is owed, only a stop before
|
|
@@ -512,20 +511,16 @@ try {
|
|
|
512
511
|
|
|
513
512
|
## Group Receive Errors
|
|
514
513
|
|
|
515
|
-
|
|
516
|
-
`EncryptionError`. Each one tells the caller what to do
|
|
514
|
+
Three error classes describe a managed group receive that gives no content.
|
|
515
|
+
None of them is an `EncryptionError`. Each one tells the caller what to do
|
|
516
|
+
with the message.
|
|
517
517
|
|
|
518
518
|
| Error | Cause | Keep rule |
|
|
519
519
|
|---|---|---|
|
|
520
|
-
| [`GroupReceiveUnavailableError`](./api/classes/GroupReceiveUnavailableError.md) | The group state is not current. `reason` names the wait, and `retryAfterMs` gives the time to the next try. The client stored the content in a receive record under `messageId`. |
|
|
520
|
+
| [`GroupReceiveUnavailableError`](./api/classes/GroupReceiveUnavailableError.md) | The group state is not current. `reason` names the wait, and `retryAfterMs` gives the time to the next try. The client stored the content in a receive record under `messageId`. | No client method throws it. `processIncomingEnvelope` gives a `pending` outcome for it. Acknowledge the envelope. The receive queue decides the stored content when the group updates, with no second decrypt. |
|
|
521
521
|
| [`GroupReceiveRefusedError`](./api/classes/GroupReceiveRefusedError.md) | The client refused the content. `reason` names the refusal, for example `sender-not-member` or `sync-from-other-account`. The client asked for no resend. | Drop the message. A redelivery is dropped as a processed duplicate. |
|
|
522
522
|
| [`GroupResendDeferredError`](./api/classes/GroupResendDeferredError.md) | A resend to a group member waits for the group state. The client neither sent nor refused the resend. | The Relay keeps the retry request. Do not acknowledge it. A later delivery decides again. |
|
|
523
523
|
|
|
524
|
-
The deprecated `decryptGroupMessage` throws the first two errors. It also
|
|
525
|
-
throws `EncryptionError` with `STORAGE_QUOTA_EXCEEDED` when the receive queue
|
|
526
|
-
has no room, and with `MESSAGE_DUPLICATE` for a message that this client
|
|
527
|
-
processed or that gives no content, such as a null message. A decrypt failure
|
|
528
|
-
throws its error with no retry request and no report.
|
|
529
524
|
`decryptEnvelope` throws `GroupReceiveRefusedError` for a group context that
|
|
530
525
|
is malformed or names another group. `processIncomingEnvelope` throws none
|
|
531
526
|
of them. It returns a receive outcome: `pending` for content that waits for
|
|
@@ -536,10 +531,30 @@ it when its group updates. Do not acknowledge an envelope whose outcome is
|
|
|
536
531
|
|
|
537
532
|
Content from another account that carries a sync message is refused as
|
|
538
533
|
`sync-from-other-account` on the Relay subscription, in
|
|
539
|
-
`receiveIncomingEnvelopes`, in `decryptEnvelope
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
534
|
+
`receiveIncomingEnvelopes`, in `decryptEnvelope`, and in
|
|
535
|
+
`processIncomingEnvelope` as a `denied` outcome. The raw decrypt methods
|
|
536
|
+
`receive`, `decryptMessage`, and `decryptMessages` return the plaintext with
|
|
537
|
+
no group classification and do not refuse it.
|
|
538
|
+
|
|
539
|
+
A `GroupKeySync` from an own device carries the master key of a managed
|
|
540
|
+
group. `processIncomingEnvelope`, the Relay subscription, and the receive
|
|
541
|
+
queue consume it and never give it to the application.
|
|
542
|
+
`processIncomingEnvelope` gives the outcome `null-message` for it, so
|
|
543
|
+
acknowledge the envelope. `decryptEnvelope` and the raw decrypt methods
|
|
544
|
+
`receive`, `decryptMessage`, and `decryptMessages` return it unapplied,
|
|
545
|
+
master key included. A sender device reinstalled with the same device ID
|
|
546
|
+
between the arrival and the consumption of its `GroupKeySync` is marked in
|
|
547
|
+
the key sync ledger with the new registration, so that install gets the key
|
|
548
|
+
from another own device or from group traffic. A device without
|
|
549
|
+
`config.groups` drops the sync, the
|
|
550
|
+
sender does not send it again, and that device gets the key only from group
|
|
551
|
+
traffic. A sync whose key is not a 32-byte master key with a non-negative
|
|
552
|
+
revision, which a custom content adapter can give, is consumed and writes
|
|
553
|
+
nothing. A `GroupKeySync` from another account is refused as
|
|
554
|
+
`sync-from-other-account` before the client writes a group record or a master
|
|
555
|
+
key. An own device on an older SDK version does not know this sync. It gives
|
|
556
|
+
the raw group key sync, with the master key, to `onMessageDecrypted`. So
|
|
557
|
+
upgrade every own device of one account in one release.
|
|
543
558
|
|
|
544
559
|
The Relay subscription applies the rule itself. It acknowledges an envelope
|
|
545
560
|
after its content is committed, also when the content waits for its group
|
package/docs/GETTING_STARTED.md
CHANGED
|
@@ -165,6 +165,23 @@ old passes the SDK check. The Relay returns `OPERATION_EXPIRED`.
|
|
|
165
165
|
The SDK check uses the
|
|
166
166
|
same bounds, so the SDK refuses an application-supplied time before any post.
|
|
167
167
|
|
|
168
|
+
Each send timestamp is unique per sender device. A new send with a `timestamp`
|
|
169
|
+
that a different send of the device used throws `InvalidSendTimestampError`
|
|
170
|
+
with the reason `already_used`. It stores or posts nothing.
|
|
171
|
+
|
|
172
|
+
When a different
|
|
173
|
+
send used the value that the SDK reads from its clock, the SDK moves to the
|
|
174
|
+
next free millisecond. The SDK's own sends, the profile key offer and the
|
|
175
|
+
sender key distribution, reserve from the same index of the device. So a
|
|
176
|
+
`timestamp: Date.now()` can get `already_used` when your app did not use the
|
|
177
|
+
value again. Omit `timestamp`, or send again with no `timestamp` on
|
|
178
|
+
`already_used`. Read the timestamp of the send in `SendResult.clientTimestamp`.
|
|
179
|
+
|
|
180
|
+
After the SDK stores a send, a retry with the same `clientMessageId` keeps
|
|
181
|
+
the original timestamp. A send that failed before the SDK stored it gets a new
|
|
182
|
+
timestamp on retry. A manual resend and a retry answer keep the original
|
|
183
|
+
timestamp.
|
|
184
|
+
|
|
168
185
|
A hosted client sends a sealed 1:1 message only when you pass
|
|
169
186
|
`hosted.profileKeys`, and only to a contact whose profile key `contacts` holds.
|
|
170
187
|
The client identifies each other 1:1 message, so the Relay sees its sender.
|
package/local/store/README.md
CHANGED
|
@@ -301,7 +301,8 @@ The kit has these cases:
|
|
|
301
301
|
- receive record listing: arrival order, then work ID order, an exclusive
|
|
302
302
|
`after` cursor, the default page size, and the filters
|
|
303
303
|
- receive record completion and usage
|
|
304
|
-
- durability after reopen: each kind of write survives a reopen
|
|
304
|
+
- durability after reopen: each kind of write survives a reopen, including a
|
|
305
|
+
metadata value in the shape of the group key sync ledger
|
|
305
306
|
- no plaintext at rest: the stored bytes hold no known plaintext. It runs
|
|
306
307
|
only when the store declares a cipher.
|
|
307
308
|
- protection declaration: `store.protection` is a valid declaration
|
|
@@ -348,6 +349,13 @@ An `SignalProtocolLocalStore` implementation must preserve:
|
|
|
348
349
|
encryption at rest and the custody of its key. Client creation fails
|
|
349
350
|
without one, and [Content Recovery](../../docs/PROTOCOL_POLICY.md#content-recovery)
|
|
350
351
|
reads it
|
|
352
|
+
- each metadata value across a close and a reopen, with an atomic
|
|
353
|
+
`compareAndSetMetadata` for one key. The group key sync ledger keeps, for
|
|
354
|
+
each group, the own devices whose `GroupKeySync` copy the relay accepted
|
|
355
|
+
and the own device that sent this device the key, under the metadata key
|
|
356
|
+
prefix `open-e2ee:group-key-sync:v1:`. A store that
|
|
357
|
+
loses a value causes one more `GroupKeySync` for each own device that the
|
|
358
|
+
value marked
|
|
351
359
|
|
|
352
360
|
## Session Record Shape
|
|
353
361
|
|
|
@@ -409,7 +417,7 @@ with `assertBackendConformance`.
|
|
|
409
417
|
|
|
410
418
|
## Design Notes
|
|
411
419
|
|
|
412
|
-
Reviewed: 2026-
|
|
420
|
+
Reviewed: 2026-11-02.
|
|
413
421
|
|
|
414
422
|
Receive records use the same encryption and transaction boundary as protocol state.
|
|
415
423
|
|
|
@@ -463,12 +471,28 @@ hash of the group ID, not the group ID. A SQLite store with
|
|
|
463
471
|
`encryptionAtRest: false` and the in-memory store keep the records without
|
|
464
472
|
encryption.
|
|
465
473
|
|
|
466
|
-
At
|
|
467
|
-
|
|
468
|
-
conversion marker
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
474
|
+
At each open, each durable store deletes every SDK 11 received-content row
|
|
475
|
+
and every converted receive record that waits for its envelope. It also
|
|
476
|
+
deletes the conversion marker of SDK 13.x. When the open deletes a row or a
|
|
477
|
+
record, the store logs one line with the code
|
|
478
|
+
`LEGACY_RECEIVED_CONTENT_DELETED` and two counts: `count`, the deleted rows and
|
|
479
|
+
records, and `readable`, the deleted rows that parsed. The line holds no key
|
|
480
|
+
and no value. No marker records the sweep. An interrupted sweep deletes the
|
|
481
|
+
rest at the next open, and an open that finds nothing logs nothing.
|
|
482
|
+
|
|
483
|
+
A readable SDK 11 row is in a store that SDK 12.0.0 or later never opened.
|
|
484
|
+
The first open of SDK 12.0.0 through 13.x converted each readable row to a
|
|
485
|
+
receive record that waits for its envelope, and deleted the row. The sweep
|
|
486
|
+
deletes each readable row and counts it in `readable`. The sweep relies on
|
|
487
|
+
the Relay retention constraint. The Relay keeps an undelivered envelope for
|
|
488
|
+
at most its retention period, 30 days in production. Where the constraint
|
|
489
|
+
holds, no SDK version gives the content of such a row to the application.
|
|
490
|
+
|
|
491
|
+
The constraint does not cover a device that received the content on SDK 11
|
|
492
|
+
inside the last 30 days. For that device, 13.x would convert the row and
|
|
493
|
+
complete it when the Relay delivers the envelope again. This release deletes
|
|
494
|
+
the row at first open instead, and the sweep does not restore it. The
|
|
495
|
+
in-memory store keeps no data across a restart and has no sweep.
|
|
472
496
|
|
|
473
497
|
The IndexedDB web store and the key-value store also encrypt each metadata
|
|
474
498
|
value with their store key. Their metadata key names stay in clear text. Some
|
package/package.json
CHANGED