@open-e2ee/signal-protocol-sdk 14.0.0 → 14.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/CHANGELOG.md +46 -0
  2. package/README.md +9 -8
  3. package/SECURITY.md +2 -2
  4. package/client/README.md +5 -3
  5. package/dist/client/hosted-anonymous-delivery.d.ts +13 -1
  6. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
  7. package/dist/client/hosted-anonymous-delivery.js +48 -5
  8. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  9. package/dist/client/hosted-mailbox-subscription.d.ts +6 -5
  10. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  11. package/dist/client/hosted-mailbox-subscription.js +4 -8
  12. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  13. package/dist/client/hosted-sandbox-identity.d.ts +66 -3
  14. package/dist/client/hosted-sandbox-identity.d.ts.map +1 -1
  15. package/dist/client/hosted-sandbox-identity.js +136 -45
  16. package/dist/client/hosted-sandbox-identity.js.map +1 -1
  17. package/dist/client/hosted-transport.d.ts +12 -0
  18. package/dist/client/hosted-transport.d.ts.map +1 -1
  19. package/dist/client/hosted-transport.js +85 -43
  20. package/dist/client/hosted-transport.js.map +1 -1
  21. package/dist/client/hosted.d.ts +6 -3
  22. package/dist/client/hosted.d.ts.map +1 -1
  23. package/dist/client/hosted.js +6 -3
  24. package/dist/client/hosted.js.map +1 -1
  25. package/dist/client/index.d.ts +1 -1
  26. package/dist/client/index.d.ts.map +1 -1
  27. package/dist/client/index.js +1 -1
  28. package/dist/client/index.js.map +1 -1
  29. package/dist/client/relay-period-close.d.ts +35 -0
  30. package/dist/client/relay-period-close.d.ts.map +1 -0
  31. package/dist/client/relay-period-close.js +63 -0
  32. package/dist/client/relay-period-close.js.map +1 -0
  33. package/dist/client/send-deadline.d.ts +3 -2
  34. package/dist/client/send-deadline.d.ts.map +1 -1
  35. package/dist/client/send-deadline.js +5 -0
  36. package/dist/client/send-deadline.js.map +1 -1
  37. package/dist/index.d.ts +1 -1
  38. package/dist/index.d.ts.map +1 -1
  39. package/dist/index.js +1 -1
  40. package/dist/index.js.map +1 -1
  41. package/dist/remote/relay/request-admission.d.ts +5 -3
  42. package/dist/remote/relay/request-admission.d.ts.map +1 -1
  43. package/dist/remote/relay/request-admission.js +2 -1
  44. package/dist/remote/relay/request-admission.js.map +1 -1
  45. package/dist/remote/relay/types.d.ts +1 -1
  46. package/docs/ASSURANCE.md +8 -8
  47. package/docs/CLIENT_COMPOSITION.md +4 -2
  48. package/docs/DEVIATIONS.md +51 -4
  49. package/docs/GETTING_STARTED.md +5 -2
  50. package/package.json +7 -2
  51. package/remote/relay/README.md +4 -2
@@ -83,7 +83,7 @@ model and what is out of scope.
83
83
  | **SPQR / ML-KEM Braid** | ML-KEM Braid rev. 1 | **Deviation.** Same protocol, same KDF labels, same Reed–Solomon parameters, byte-identical message framing — except `hek = SHA3-256(ek_seed ‖ ek_vector)`, the operand order the specification states, which is the reverse of `libsignal`'s implementation | The normative text was followed over the executable reference | Wire-visible. Headers, ciphertexts, and shared secrets diverge; a braid session cannot complete a single epoch against `libsignal`'s implementation. Also means the KEM is not FIPS 203 in braid mode |
84
84
  | **Triple Ratchet** | `libsignal` `triple_ratchet.rs` | **Faithful.** The PQ secret enters as the HKDF salt at message-key expansion, same label, same order | — | The braiding construction follows the ML-KEM Braid specification |
85
85
  | **Sesame** | Sesame rev. 2 | **Faithful** on deleted devices: a removed device is marked and kept for MAXLATENCY, and its archived sessions still decrypt. **Deviation** on session expiry (§4.2 applies only to unacknowledged sessions) and on device-list currency on the Convex relay only (the sender reads the relay's list at most once per 60 s). The Signal Protocol Relay and the memory relay reject a stale declared device set, as §3.3 requires. **Deviation** on stale-record cleanup timing (§5.1: the cleanup runs after the resume, not after a fetch of the whole mailbox, and the Relay's 30-day TTL cap bounds it). **Extensions:** device transfer, encrypted device names, identity-change gating, a 5-device cap | Product requirements the specification does not address | On the Convex relay, a device linked or removed less than 60 s ago can miss a send or still receive one. A client clock that moves forward against the Relay clock between a removal and the cleanup can lose a message accepted just before the removal. Device transfer copies the identity private key and no ratchet state, so each device starts its own sessions |
86
- | **Device-set reconciliation** | Signal's server `MessageController`; Signal's Desktop client `sendToGroup` | **Deviation** in detail. The answer order, one post for each device of a direct send, a bound on direct sends, no empty sync post, a refusal for each not-found group destination, an acknowledgment marker, and a group body sealed again with the same ciphertext (§5.6) | The Relay takes one destination for each direct body, keeps one record for each account, admits a delivery epoch at most 5 minutes ahead of its clock and at most 24 hours behind it from the release that follows v2026.10.25, and stores each send attempt | A phase that does not match in 10 restarts fails the send with `DeviceSetReconciliationError`. A relay that does not acknowledge the comparison raises `DEVICE_SET_UNCHECKED` |
86
+ | **Device-set reconciliation** | Signal's server `MessageController`; Signal's Desktop client `sendToGroup` | **Deviation** in detail. The answer order, one post for each device of a direct send, a bound on direct sends, no empty sync post, a refusal for each not-found group destination, an acknowledgment marker, a group body sealed again with the same ciphertext, and a post again to the recovered generation of a device whose mailbox generation is retired (§5.6) | The Relay takes one destination for each direct body, keeps one record for each account, admits a delivery epoch at most 5 minutes ahead of its clock and at most 24 hours behind it from the release that follows v2026.10.25, and stores each send attempt | A phase that does not match in 10 restarts fails the send with `DeviceSetReconciliationError`. A relay that does not acknowledge the comparison raises `DEVICE_SET_UNCHECKED` |
87
87
  | **Sealed sender** | `libsignal` `sealed_sender.rs` | **Faithful** on the multi-recipient transport labels, KEM, AES-256-GCM-SIV, binary format, and `0x3FFF` registration-ID mask. **Extension:** sender and server certificates require signed Relay scope and issuer validity under operator-owned Ed25519 roots | Binds anonymous delivery to one Relay deployment and supports explicit issuer rotation and revocation | The transport follows `libsignal`; certificates are not interchangeable with Signal Messenger or another deployment |
88
88
  | **Delivery token** | `libsignal` `profile_key.rs` | **Faithful.** `deriveAccessKey` follows `libsignal`'s `ProfileKey::derive_access_key`, and reproduces `libsignal`'s published known-answer values | — | Not an SDK invention, despite what the module name suggests |
89
89
  | **Sender keys** | `libsignal` `sender_keys.rs` | **Deviation.** Protobuf fields, chain seeds, and HKDF-Extract/Expand match. The SDK uses frame version `0x44`, Ed25519 signatures, and UTF-8 distribution identifiers. | The identity profile selects Ed25519. The frame version marks the correction of the former missing Extract. | Message-key derivation matches the reference. Former SDK state and messages require a reset. Frames still differ from Signal Messenger. |
@@ -98,11 +98,12 @@ model and what is out of scope.
98
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) |
99
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
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) |
101
+ | **Relay socket authentication** | Signal's Android client `OkHttpWebSocketConnection`; `libsignal` `chat.rs`; Signal's server `WebSocketDisconnectionRequestListener` | **Faithful.** The mailbox socket sends its credential once, at the handshake, and stays open until the server closes it or it fails. The Relay closes it with 4401 when the authority must be checked again, as Signal's server does. **Deviation** in detail. The handshake credential is a device token that expires after 15 minutes, and the open socket outlives it. The Relay also closes the socket with 4401 at the start of each UTC month | The Relay keeps its device credential short-lived for HTTP requests, and it counts monthly activity at the handshake | A renewal touches only HTTP requests and the next reconnect. An authority change reaches an open socket only through the 4401 close (§9.1) |
101
102
  | **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 |
102
103
  | **Registration IDs** | `libsignal` `sealed_sender.rs` | **Faithful.** Generated in `[1, 16383]`, strictly inside the 14 bits the wire format reserves | — | — |
103
104
  | **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 |
104
105
  | **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 |
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` |
106
+ | **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. A `PERIOD_CLOSED` refusal gets one repeat of the same post, and a second refusal keeps the device pending (§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` |
106
107
 
107
108
  ---
108
109
 
@@ -908,7 +909,7 @@ it never runs.
908
909
 
909
910
  ### 5.6 Device-set reconciliation differs in detail
910
911
 
911
- Reviewed: 2026-11-01.
912
+ Reviewed: 2026-11-04.
912
913
 
913
914
  The reconciliation of §5.5 follows Signal's server and Signal's Desktop
914
915
  client in its rule: the server compares, the client repairs and posts again,
@@ -932,6 +933,7 @@ Signal's Android client. The following details differ.
932
933
  | D12 | A declared post with no `recipientRegistrationId` skips the registration check | The field is optional on every Relay route | Signal's server compares the registration of each device of a post | A Relay test posts an unnamed registration |
933
934
  | D13 | A declaration that names the sender device gets 400 | The Relay refuses a malformed declaration before it compares | Signal's server answers 409 and names the sender device as an extra device | Relay tests on the direct and the group routes. The SDK does not declare the sender device |
934
935
  | D14 | The identified group route compares the declared device set, with the codes and the order of the direct route | The route serves Relay API customers | Signal has no identified group route | Relay tests. No SDK code calls the route |
936
+ | D15 | When the Relay refuses a device post with `NOT_FOUND`, the SDK reads the device list of the account again. When the list names the device at a different mailbox generation, the SDK handles the refusal as a stale device: it archives the session, starts a new session from the new prekey bundle, and posts again only to the new generation, under the same message ID and epoch. When the list names the same generation, does not name the device, or cannot be read, the device keeps its `NOT_FOUND` refusal. The other devices of the account keep their acceptance | A recovered device keeps its device ID and gets a new registration and a new mailbox generation. The Relay refuses a post to a retired generation with `NOT_FOUND` before the mailbox records the delivery. It admits each destination device separately. The founder ruling "Relay delivery assurance takeover: twelve founder rulings on the stage run, fan-out baseline, SDK remainder, billing handoffs, log retention, CI shape and probes (2026-11-04, founder)" sets this path, with a check that the Relay charges no device twice | Signal's server refuses the whole request with 410 and names the stale devices. Signal's Android and Desktop clients then archive those sessions, encrypt again and send the request again. The Relay accepts the live devices of the same request, so a full resend would post them again | On each route, a post to a retired generation is followed by one post to the recovered generation with the first epoch. The live device and the recovered device each have one charge, and the retired generation has none. A restart and a replay add no charged post. A declared post gets the stale device-set refusal that drives the repair. A `NOT_FOUND` stays a refusal when the list names the same generation, does not name the device, or cannot be read |
935
937
 
936
938
  ### 5.7 Registration IDs of linked devices
937
939
 
@@ -978,7 +980,7 @@ which sends a group key sync to the own devices.
978
980
 
979
981
  ### 5.9 The posting deadline and send progress
980
982
 
981
- Reviewed: 2026-11-01.
983
+ Reviewed: 2026-11-04.
982
984
 
983
985
  Signal's Android client gives a send job a lifespan of one day from its
984
986
  creation, and Signal's Desktop client stops a send job one day after its
@@ -1004,6 +1006,7 @@ A retry request has its own posting deadline, in row P9. The following details d
1004
1006
  | 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
1007
  | 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 |
1006
1008
  | 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 |
1009
+ | P11 | After a `PERIOD_CLOSED` refusal of a device post, the SDK posts the same request one more time, with the same message ID, epoch and bytes. It does not encrypt again. When the Relay refuses the repeat with `PERIOD_CLOSED` too, the device stays pending: the send throws a retryable error with its deadline, the send stays open, and a later replay posts the same operation. On the sealed route the error code is `DELIVERY_FAILED`, because that route gives each code outside its safe codes as `DELIVERY_FAILED` | The Relay refuses a new admission with `PERIOD_CLOSED` when its admission period ended. It refuses after its duplicate check and before it stores the post, and it reads the period again for each request. The founder ruling "Relay delivery assurance takeover: twelve founder rulings on the stage run, fan-out baseline, SDK remainder, billing handoffs, log retention, CI shape and probes (2026-11-04, founder)" sets one automatic repeat of the same operation | Signal's server has no admission period and no `PERIOD_CLOSED` answer | On each route, a `PERIOD_CLOSED` refusal and then an acceptance end the send with one charged operation under one epoch. Two `PERIOD_CLOSED` refusals make two identical posts and keep the send open with no outcome, and a later replay completes the same operation with one charge. The sealed carrier repeats an identical body once and does not repeat a `QUOTA_EXCEEDED` refusal |
1007
1010
 
1008
1011
  ---
1009
1012
 
@@ -1684,6 +1687,50 @@ readable count and no key or value, and that a second open logs nothing.
1684
1687
 
1685
1688
  ---
1686
1689
 
1690
+ ## 9. Relay mailbox socket
1691
+
1692
+ Reviewed: 2026-11-04.
1693
+
1694
+ The hosted transport keeps one mailbox socket to the Relay for each
1695
+ subscription (`client/hosted-mailbox-subscription.ts`). Signal's clients keep
1696
+ one authenticated chat socket to Signal's server. This section states where
1697
+ the two follow the same model and where they differ.
1698
+
1699
+ ### 9.1 The socket outlives its handshake token
1700
+
1701
+ **Faithful.** The socket sends the device token once, in its handshake
1702
+ subprotocol, and the Relay authorizes it there. The socket stays open until
1703
+ the Relay closes it or it fails. A token renewal does not close or reopen it.
1704
+ Signal's Android client sends its credentials only in the handshake request
1705
+ (`OkHttpWebSocketConnection.java:167`), and `libsignal` attaches its
1706
+ authenticated headers to the initial websocket connect (`chat.rs:201-206`).
1707
+ When the authority must be checked again, the Relay closes the socket with
1708
+ 4401 `AUTHORITY_REVALIDATE`, and the subscription reconnects. Signal's server
1709
+ closes the chat socket with 4401 "Reauthentication required" for the same
1710
+ purpose (`WebSocketDisconnectionRequestListener.java:31`).
1711
+
1712
+ **Deviation** in detail. Signal's credential is a long-lived account
1713
+ password. The Relay credential is a device token that expires 15 minutes
1714
+ after it is issued. The open socket outlives the token. The hosted transport
1715
+ renews the token only when an HTTP request or a reconnect needs it. The Relay
1716
+ also closes the socket with 4401 at the start of each UTC month, so that a
1717
+ long-lived socket counts once in the monthly activity of the new month.
1718
+
1719
+ The constraint is that the Relay issues a short-lived device token and checks
1720
+ it on each HTTP request. A device that only receives sends no pull, so the
1721
+ Relay counts its monthly activity at the socket handshake.
1722
+ **Consequence:** a revocation, an account deletion, a security hold, or a
1723
+ recovery change reaches an open socket only through the 4401 close. A Relay
1724
+ that does not send that close keeps serving an open socket after the token
1725
+ expires.
1726
+
1727
+ Guarantee tests assert that one socket stays open across two token renewals
1728
+ while Relay receipts continue on it, that a 4401 close after the renewals
1729
+ reconnects with the current token, and that each presence watch stays on the
1730
+ open socket across a renewal.
1731
+
1732
+ ---
1733
+
1687
1734
  ## Unverified and needs review
1688
1735
 
1689
1736
  This review lists the following items rather than asserts them. It could not
@@ -37,10 +37,13 @@ Production supports application-bound and explicitly configured device-owned
37
37
  accounts. For application-bound accounts, `getIdentityAssertion` returns a
38
38
  short-lived Relay-specific assertion from your backend after it verifies the
39
39
  server session and current application membership.
40
+
40
41
  Device-owned accounts prove possession of a persistent account key. They do
41
42
  not bind to an application login, and provider sign-in cannot recover a lost
42
- account key. The SDK does not supply an identity provider or a relay server
43
- implementation. See [identity and authentication](https://docs.open-e2ee.dev/relay/identity)
43
+ account key. For device-owned accounts, pass
44
+ `hostedRelayDeviceOwnedIdentity(storage)` as `getIdentityAssertion`. The SDK
45
+ does not supply an identity provider or a relay server implementation.
46
+ See [identity and authentication](https://docs.open-e2ee.dev/relay/identity)
44
47
  for Production configuration.
45
48
 
46
49
  For a tested backend path, see the [Better Auth recipe](https://docs.open-e2ee.dev/relay/better-auth)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "14.0.0",
3
+ "version": "14.1.0",
4
4
  "description": "Pure TypeScript Signal Protocol SDK for encrypted chat in Expo, React Native, browsers, and Node. Post-quantum by default.",
5
5
  "keywords": [
6
6
  "open-e2ee",
@@ -422,8 +422,13 @@
422
422
  "xcode": {
423
423
  "uuid": "11.1.1"
424
424
  },
425
+ "@expo/cli": {
426
+ "zod": "^4.6.6"
427
+ },
425
428
  "brace-expansion": "^5.0.12",
426
- "image-size": "file:./vendor/image-size-disabled"
429
+ "glob": "^14.0.2",
430
+ "image-size": "file:./vendor/image-size-disabled",
431
+ "minimatch": "^11.0.1"
427
432
  },
428
433
  "devDependencies": {
429
434
  "@op-engineering/op-sqlite": "^18.2.5",
@@ -31,8 +31,10 @@ const signal = await createHostedSignalProtocolClient({
31
31
  `oe new` writes `relayUrl` to `.env.local` as `OPEN_E2EE_RELAY_URL`, with the
32
32
  public prefix of the framework in a Next.js, Expo, or Vite application. Supply
33
33
  `storage` for this device and `getIdentityAssertion`. In a Sandbox environment,
34
- pass `hostedRelaySandboxIdentity(storage)`. In production, pass the callback of
35
- your identity provider.
34
+ pass `hostedRelaySandboxIdentity(storage)`. In a production project in
35
+ device-owned mode, pass `hostedRelayDeviceOwnedIdentity(storage)`. In a
36
+ production project in application-bound mode, pass a callback that returns an
37
+ assertion from your backend.
36
38
 
37
39
  For advanced integrations, implement the `SignalProtocolRelayServer` client
38
40
  transport against your own backend. That backend must authenticate