@open-e2ee/signal-protocol-sdk 9.3.0 → 9.5.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 (92) hide show
  1. package/ADAPTERS.md +1 -0
  2. package/CHANGELOG.md +269 -0
  3. package/README.md +1 -1
  4. package/SECURITY.md +2 -2
  5. package/client/README.md +11 -14
  6. package/dist/client/client.d.ts +134 -64
  7. package/dist/client/client.d.ts.map +1 -1
  8. package/dist/client/client.js +333 -179
  9. package/dist/client/client.js.map +1 -1
  10. package/dist/client/config.d.ts +4 -7
  11. package/dist/client/config.d.ts.map +1 -1
  12. package/dist/client/config.js.map +1 -1
  13. package/dist/client/content-adapter.d.ts +8 -0
  14. package/dist/client/content-adapter.d.ts.map +1 -1
  15. package/dist/client/content-adapter.js +4 -0
  16. package/dist/client/content-adapter.js.map +1 -1
  17. package/dist/client/event-hooks.d.ts +1 -1
  18. package/dist/client/group-outbox.d.ts +2 -4
  19. package/dist/client/group-outbox.d.ts.map +1 -1
  20. package/dist/client/group-outbox.js +7 -1
  21. package/dist/client/group-outbox.js.map +1 -1
  22. package/dist/client/hosted-anonymous-delivery.d.ts +1 -1
  23. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
  24. package/dist/client/hosted-anonymous-delivery.js +5 -14
  25. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  26. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  27. package/dist/client/hosted-mailbox-subscription.js +136 -15
  28. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  29. package/dist/client/hosted-transport.d.ts +2 -2
  30. package/dist/client/hosted-transport.d.ts.map +1 -1
  31. package/dist/client/hosted-transport.js +20 -5
  32. package/dist/client/hosted-transport.js.map +1 -1
  33. package/dist/client/messages.d.ts.map +1 -1
  34. package/dist/client/messages.js +12 -2
  35. package/dist/client/messages.js.map +1 -1
  36. package/dist/client/relay-acceptance.d.ts +29 -0
  37. package/dist/client/relay-acceptance.d.ts.map +1 -0
  38. package/dist/client/relay-acceptance.js +29 -0
  39. package/dist/client/relay-acceptance.js.map +1 -0
  40. package/dist/client/relay-subscription.d.ts +43 -1
  41. package/dist/client/relay-subscription.d.ts.map +1 -1
  42. package/dist/client/relay-subscription.js +278 -100
  43. package/dist/client/relay-subscription.js.map +1 -1
  44. package/dist/client/relay-work.d.ts +7 -6
  45. package/dist/client/relay-work.d.ts.map +1 -1
  46. package/dist/client/relay-work.js +34 -9
  47. package/dist/client/relay-work.js.map +1 -1
  48. package/dist/client/retry-family.d.ts +119 -0
  49. package/dist/client/retry-family.d.ts.map +1 -0
  50. package/dist/client/retry-family.js +170 -0
  51. package/dist/client/retry-family.js.map +1 -0
  52. package/dist/client/retry-request-envelope.d.ts +106 -0
  53. package/dist/client/retry-request-envelope.d.ts.map +1 -0
  54. package/dist/client/retry-request-envelope.js +245 -0
  55. package/dist/client/retry-request-envelope.js.map +1 -0
  56. package/dist/client/retry.d.ts +66 -24
  57. package/dist/client/retry.d.ts.map +1 -1
  58. package/dist/client/retry.js +239 -139
  59. package/dist/client/retry.js.map +1 -1
  60. package/dist/client/sealed-sender.d.ts +15 -3
  61. package/dist/client/sealed-sender.d.ts.map +1 -1
  62. package/dist/client/sealed-sender.js +22 -3
  63. package/dist/client/sealed-sender.js.map +1 -1
  64. package/dist/client/signal-service-cipher.d.ts +52 -0
  65. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  66. package/dist/client/signal-service-cipher.js +185 -15
  67. package/dist/client/signal-service-cipher.js.map +1 -1
  68. package/dist/client/state.d.ts +12 -64
  69. package/dist/client/state.d.ts.map +1 -1
  70. package/dist/client/state.js +22 -98
  71. package/dist/client/state.js.map +1 -1
  72. package/dist/client/types.d.ts +28 -2
  73. package/dist/client/types.d.ts.map +1 -1
  74. package/dist/client/types.js.map +1 -1
  75. package/dist/internal/protocol/sealed-sender/types.d.ts +1 -1
  76. package/dist/internal/protocol/sealed-sender/types.js +1 -1
  77. package/dist/local/store/received-content.d.ts +16 -2
  78. package/dist/local/store/received-content.d.ts.map +1 -1
  79. package/dist/local/store/received-content.js +18 -3
  80. package/dist/local/store/received-content.js.map +1 -1
  81. package/dist/local/store/reliability.d.ts +260 -2
  82. package/dist/local/store/reliability.d.ts.map +1 -1
  83. package/dist/local/store/reliability.js +390 -12
  84. package/dist/local/store/reliability.js.map +1 -1
  85. package/dist/remote/relay/types.d.ts +31 -31
  86. package/dist/remote/relay/types.d.ts.map +1 -1
  87. package/dist/types/api.d.ts +74 -26
  88. package/dist/types/api.d.ts.map +1 -1
  89. package/docs/ASSURANCE.md +5 -5
  90. package/docs/DEVIATIONS.md +4 -5
  91. package/docs/INTERFACES.md +2 -0
  92. package/package.json +1 -1
package/ADAPTERS.md CHANGED
@@ -168,6 +168,7 @@ See the [client guide](./client/README.md#with-relay).
168
168
  - Device registration, unlink, and stale cleanup must stay consistent across active identity types.
169
169
  - Provisioning slot assignment is server-owned, not client-owned.
170
170
  - Public-key reads and writes must enforce correct account ownership rules.
171
+ - An envelope gets one `id`, and that `id` stays the same on every redelivery. A relay that assigns its own ids delivers the SDK id as `clientMessageId`. See [docs/INTERFACES.md](./docs/INTERFACES.md).
171
172
 
172
173
  ### Storage implementations
173
174
 
package/CHANGELOG.md CHANGED
@@ -1,5 +1,274 @@
1
1
  # Changelog
2
2
 
3
+ ## 9.5.0
4
+
5
+ - **Breaking: a retry request is now a mailbox envelope.** Before, a
6
+ recipient that could not decrypt a message sent the retry request on a
7
+ separate relay channel, and the Signal Protocol Relay had no such
8
+ channel, so a hosted client could not ask for a resend. Now the
9
+ recipient sends an identified `retry_request` envelope to the sender
10
+ device through `send()`, on every relay. The receiving client takes the
11
+ requester from the envelope sender, never from the payload. It resends
12
+ only to the device that asked, and it keeps the request when the resend
13
+ fails, so the next pull tries again. It acknowledges a malformed retry
14
+ request and drops it. `SignalProtocolRelayServer` no longer has a
15
+ separate retry-request channel, and `DefaultSignalProtocolClient` no
16
+ longer starts a retry subscription. A custom relay must carry
17
+ `messageType: 'retry_request'` like any other envelope. Each request,
18
+ resend and null message carries its retry family ID in its
19
+ `clientMessageId`. The sender reads the request attempt from it, and the
20
+ requester finds the failed envelope of a resend or a null message by
21
+ it. So a relay that assigns its own envelope IDs must deliver the
22
+ `clientMessageId` with the envelope on every delivery path, as the
23
+ in-memory relay and the Convex subscription and poll do. The client
24
+ keeps the delivered envelope ID for its processed record and its
25
+ acknowledgment. The client drops a request that carries a retry ID
26
+ under another ID.
27
+ `ProcessEnvelopeOptions.sendRetryRequest` now receives that envelope. The
28
+ Convex component no longer has a retry-request table, its cron or its
29
+ three functions, so deploy the new component.
30
+ - **Fixed: a client asks the sender of a sealed message for a resend.**
31
+ Before, when a sealed message failed to decrypt inside the seal, the
32
+ client used the sender of the outer envelope. For a hosted anonymous
33
+ envelope that sender is empty, so the client could not ask for a resend
34
+ and the message failed again at each pull. Now the client asks the
35
+ sender device that it finds inside the seal. When the seal itself fails
36
+ to open, the message names no sender. For a resend or a null message,
37
+ the retry request record names the device that the request went to, so
38
+ the client asks that device for the next attempt, on each receive path.
39
+ It marks the message processed and acknowledges it only after that
40
+ request posts. For any other message, the client sends no retry request
41
+ and writes a log line. A foreground delivery acknowledges that message,
42
+ and a background pull keeps it, as for any other message that fails to
43
+ decrypt.
44
+ - **Fixed: a sealed message keeps its content hint.** Before, a sealed
45
+ message carried the default content hint inside the seal, and the
46
+ receiver did not read it. A sealed IMPLICIT message, such as the null
47
+ message of a retry reset, that failed to decrypt then caused a retry
48
+ request. Now the sender seals the content hint of the message, and the
49
+ receiver puts it on the unsealed envelope. A sealed IMPLICIT message
50
+ that fails to decrypt causes no retry request.
51
+ - **Fixed: `processIncomingEnvelope()` sends one retry request for each
52
+ failed envelope.** Before, when `markDelivered` failed, the next
53
+ processing of the same envelope sent a second retry request. Now the
54
+ client stores the encrypted retry request under the failed envelope ID,
55
+ as on the relay subscription path. A later processing of the same
56
+ envelope posts the stored request again, so the relay sees one
57
+ operation. Each post counts toward the retry rate limit. The record holds
58
+ a fingerprint of the envelope as the Relay delivered it, the same on
59
+ every receive path. The fingerprint covers the envelope ID, the sender,
60
+ the message type and the ciphertext, but not the timestamps, so a push
61
+ without a server timestamp and a pull with one match. When the relay
62
+ gives the same envelope ID with changed content, the client sends no
63
+ retry request, keeps the envelope unacknowledged and writes a log line.
64
+ - **Fixed: one failed message gets one resend.** Before, each retry request
65
+ had its own ID, so two requests for one failed message gave two resends,
66
+ and the requester decrypted both. Now the requester keeps one retry
67
+ request record for each failed envelope. The record holds a random retry
68
+ ID, and that ID names the request family on the wire: the request is
69
+ `<retry ID>:retry-request`, the resend is `<retry ID>:resend`, and the
70
+ null message of a retry reset is `<retry ID>:null`. Each attempt from 2
71
+ adds `:<n>`, for example `<retry ID>:retry-request:2`. The failed
72
+ envelope ID travels only in the request payload, in the new
73
+ `failedEnvelopeId` and `retryId` fields. When the Relay refuses the
74
+ stored request as expired, or when a resend or a null message fails to
75
+ decrypt, the requester encrypts the next request attempt under the same
76
+ retry ID, on each receive path. A second delivery of the same failed
77
+ resend starts no new request attempt. The resend and the null message
78
+ carry the attempt number of the request that they answer, so the answer
79
+ to `<retry ID>:retry-request:2` is `<retry ID>:resend:2`. The sender
80
+ encrypts one resend for each request attempt and stores it, so a second
81
+ delivery of the same request attempt posts the stored resend again. A
82
+ retry request ciphertext is at most 2,048 characters, and a failed
83
+ envelope ID is at most 128 characters.
84
+ - **Fixed: a resend of an older message reaches the Signal Protocol
85
+ Relay.** Before, a resend posted the original message time as its
86
+ operation epoch. The Relay refuses an epoch older than 5 minutes, so it
87
+ refused the resend of an older message. Now the resend keeps the original
88
+ timestamp in the envelope, and posts the epoch of its stored attempt. A
89
+ new encryption after the admission window posts a fresh epoch under the
90
+ same attempt ID. `Envelope.operationEpochMilliseconds` and a new last
91
+ parameter of `sendMultiRecipientUnidentified()` carry that epoch to the
92
+ relay.
93
+ - **Fixed: a failed resend repeats the same post.** Before, each attempt
94
+ encrypted the message again. A second attempt under the same client
95
+ message ID then carried other bytes, and the Relay refused it as a retry
96
+ conflict. Now each resend attempt stores its encrypted bytes and its
97
+ epoch, and a second delivery of the same request attempt posts them
98
+ again. A later request attempt gets a new encryption under the ID of
99
+ that request attempt, for example `<retry ID>:resend:2`. When the Relay
100
+ refuses the stored bytes as expired, the client encrypts again with a
101
+ fresh epoch under the same ID. A retry conflict to a resend post means
102
+ that the Relay holds an earlier encryption under that ID, so the attempt
103
+ is complete. When the Relay admits the new bytes after the requester
104
+ processed the earlier encryption, the requester drops them. The null
105
+ message of a retry reset has its own IDs. The client keeps the records
106
+ for 30 days, so a later delivery of the same request attempt posts them
107
+ again.
108
+ - **Fixed: the application gets each message at most once, unless a local
109
+ store write fails after the application got the message.** The Relay
110
+ frees a message ID after the acknowledgment, so a second resend attempt
111
+ can arrive after the first. The client processes one resend or the failed
112
+ envelope itself for each failed envelope. When a resend decrypts, the
113
+ client marks the failed envelope as processed, and it acknowledges a
114
+ later delivery of the failed envelope and drops it. When the failed
115
+ envelope decrypts on a later delivery, the client drops each resend for
116
+ it. It acknowledges each dropped envelope and does not decrypt it. This
117
+ applies to the relay subscription, to `receiveIncomingEnvelopes()` and to
118
+ `processIncomingEnvelope()`, which throws `MESSAGE_DUPLICATE` for a
119
+ dropped envelope. Two attempts that arrive at the same time are processed
120
+ one after the other. A resend or a null message that fails to decrypt
121
+ while the retry rate limit refuses its request stays unacknowledged, so a
122
+ later delivery asks again. When the client cannot store that a resend or
123
+ the failed envelope decrypted, it writes a warning with the behavior
124
+ `RETRY_FULFILL_WRITE_FAILED` on each receive path, and continues as for
125
+ any decrypted envelope: the relay subscription acknowledges it,
126
+ `receiveIncomingEnvelopes()` returns its ID as processed, and
127
+ `processIncomingEnvelope()` returns the plaintext. A redelivery of the
128
+ failed envelope or of a resend may then give the message again. The
129
+ client stores that the application got the content as the `fulfilled`
130
+ flag of the processed record of the failed envelope, in one write.
131
+ `getProcessedEnvelope()` returns the flag, and `storeProcessedEnvelope()`
132
+ takes it as a new last parameter.
133
+ - **Fixed: the application never gets a null message.** Before, a
134
+ decrypted null message of a retry reset reached `onMessageDecrypted` as
135
+ the content `{"nullMessage":{}}`, and `processIncomingEnvelope()`
136
+ returned it. Now the client consumes a null message when the content
137
+ adapter reports `nullMessage: true`, and a custom adapter must report it
138
+ for its own null encoding. The client marks the null message processed
139
+ and acknowledges it on each receive path, and
140
+ `processIncomingEnvelope()` throws `MESSAGE_DUPLICATE` for it. A null
141
+ message answers a retry request when the sender has no plaintext. It
142
+ marks its failed envelope processed, so the client drops a redelivery of
143
+ that envelope, but it does not mark the content as delivered. A content
144
+ resend for the same failed envelope that arrives later, of any attempt,
145
+ is decrypted and given to the application once. When the client cannot
146
+ store the processed record of a null message or of its failed envelope,
147
+ it writes a warning with the behavior `RETRY_NULL_WRITE_FAILED` and
148
+ still consumes the null message, so `processIncomingEnvelope()` still
149
+ throws `MESSAGE_DUPLICATE`. A redelivery of the failed envelope may then
150
+ give the message.
151
+ - **Breaking: a content adapter must decide the null message.**
152
+ `InspectedSignalProtocolContent.nullMessage` is now a required
153
+ `boolean`. A custom content adapter must set it on every inspect result,
154
+ and report `nullMessage: true` for its own null encoding. The default
155
+ adapter sets it.
156
+ - **Fixed: the hosted transport takes envelope IDs from the Relay.**
157
+ Before, the hosted transport spread the decoded wire JSON over the
158
+ envelope, so a sender could set `id` or `clientMessageId` in the wire
159
+ and replace the Relay message ID. Now the transport keeps only the wire
160
+ fields that a sender encodes: the ciphertext, the content hint, the
161
+ message type, the timestamp and the version. The envelope ID and the
162
+ `clientMessageId` both come from the Relay message ID, on the pull,
163
+ subscription and ephemeral paths.
164
+ - **Fixed: a late resend attempt is still dropped.** A sender now refuses
165
+ a retry request for a message sent more than 30 days ago. The Relay can
166
+ keep the last resend post for 30 more days, so the requester keeps its
167
+ retry records for 60 days.
168
+ - **Fixed: a processed envelope ID with new content is acknowledged.**
169
+ Before, when the relay gave a processed envelope ID with changed bytes,
170
+ the client threw on each pull and never acknowledged the envelope. The
171
+ Relay can reuse an ID after it forgets a row. Now the client
172
+ acknowledges the envelope, drops it and writes a debug log line.
173
+ `hasProcessedEnvelope()` no longer takes a fingerprint, and the new
174
+ `getProcessedEnvelope()` returns the stored record.
175
+ - **Breaking: `runPeriodicCleanup()` is removed.** It cleaned only a
176
+ retry deduplication map that the client no longer fills, so it did
177
+ nothing. Remove each call to it.
178
+
179
+ ## 9.4.0
180
+
181
+ - **Breaking: `deliveryReceipts` defaults to `'auto'`.** Before, the default
182
+ was `'always'`. Now a client that does not set `deliveryReceipts` uses
183
+ `'auto'`, which sends the same receipts as `'always'`.
184
+ - **Fixed: steady traffic no longer holds back a delivery receipt.** Before,
185
+ each new message from a sender restarted the 3 s batch timer of that
186
+ sender, so messages that came less than 3 s apart held every receipt back
187
+ until the traffic stopped. Now a receipt batch is sent 3 s after its last
188
+ message or 30 s after its first message, whichever comes first, or at 100
189
+ messages.
190
+ - **Fixed: `stop()` sends the batched delivery receipts.** Before, `stop()`
191
+ dropped the receipts that waited in a batch, and `stopRelaySubscription()`
192
+ sent each batch but left it in place, so its timer sent the same receipt a
193
+ second time. Now both send each waiting batch once before the relay
194
+ subscription closes. `stop()` waits for delivery receipt sends, including
195
+ their app hooks, such as `onMessageEncrypted`, until one deadline 5 s
196
+ after it starts. It waits for each receipt send that is in progress when
197
+ it starts, except a send that an earlier `stop()` stopped, and for the
198
+ sends that it starts. A delivery that finishes during the wait batches its
199
+ receipt. At the end of each wait, `stop()` sends the batches that wait and
200
+ waits for those sends until the same deadline. It does this again while
201
+ the deadline is not past. `stop()` holds the receipt batches from its
202
+ first flush until it clears its tracking state. During the hold,
203
+ `stopRelaySubscription()` does not send them, and `stop()` drops a receipt
204
+ batched after its last flush. At the deadline it stops each receipt send
205
+ that is left: a send that waits in an app hook stops, and that receipt is
206
+ not sent. A send that is in its relay call at the deadline is waited for,
207
+ and that receipt can still be sent. A hook of a delivery receipt send that
208
+ awaits `stop()` holds `stop()` until the deadline. `stop()` does not wait
209
+ for read and viewed receipt sends. A call to `startRelaySubscription()` or
210
+ `startRetryRequestSubscription()` while `stop()` runs is refused and
211
+ logged; start again after `stop()` resolves. A `stop()` call that overlaps
212
+ a running `stop()` waits for it and settles as it settles.
213
+ `stop()` clears the retry timer of a failed delivery, read, or viewed
214
+ receipt send that started before `stop()` stops its relay work.
215
+ - **Changed: `deliveryReceipts: 'auto'` sends a receipt for each message that
216
+ asks for one.** Before, `'auto'` sent a receipt only for a message that
217
+ arrived through sealed sender, so the sender of an identified message got no
218
+ receipt and kept its copy of that message for 14 days. Now `'auto'` sends
219
+ the same receipts as `'always'`.
220
+ - **Fixed: a resent message keeps its retry copy.** Before, a resend that
221
+ answered a retry request deleted the sender's copy of the message, so a
222
+ second retry request for that message found no copy and the message could
223
+ not be sent again. Now the resend replaces the copy with the copy of the new
224
+ encryption. Only a delivery receipt from that recipient device, or the 14-day
225
+ limit, deletes it.
226
+ - **Added: `SendResult` carries `duplicate` and `expiresAt`.** `client.send()`
227
+ now returns what the relay reported for the device posts of the send.
228
+ `duplicate` is true only when the relay had already accepted every device
229
+ post, so the send stored no new copy. This is the case when the application
230
+ calls `send()` again with the `clientMessageId` of a send whose posts the
231
+ relay accepted but whose result did not arrive. `expiresAt` is the earliest
232
+ time at which the relay drops the copy of a device post that the device has
233
+ not acknowledged. A group send also counts its shared sealed post. For a
234
+ group send over a group token, the shared post reports that the relay had
235
+ already accepted its fan-out, not that each destination stored a copy. Each
236
+ field is present only when every post reported it, so both are absent on a
237
+ relay that does not report them. The sync copies to this account's other
238
+ devices do not count. The sender key pre-messages of a group send do not
239
+ count. `send()` still resolves only after every device post, the sync
240
+ copies, and the outbox record complete. A send that the outbox had already
241
+ completed returns the result that it stored.
242
+ - **Fixed: a hosted client accepts an ephemeral message only after it handled
243
+ it.** Before, the client did not give the relay the promise of its work for
244
+ an envelope, so the hosted transport did not wait for it. The client
245
+ accepted each ephemeral message before it decrypted it, even when the work
246
+ then failed, and sent an extra acknowledgment for each ephemeral message
247
+ that it handled. A durable message whose work failed stayed in the mailbox
248
+ until the next reconnect, and the notification batch of a burst ended before
249
+ its work. Now the hosted transport waits for the work of each envelope. It
250
+ accepts an ephemeral message after its work succeeds, and acknowledges a
251
+ burst in one socket frame after its work. A durable message whose work fails
252
+ stays in the mailbox, and the hosted transport gives it again on the next
253
+ recovery pull or socket replay. The transport continues with the next
254
+ message at once, whatever its sender, so it does not keep the order across a
255
+ failed message. It holds back no message. While a failed message remains,
256
+ the client pulls again after a random wait from half to one and a half of
257
+ the failed-work wait, which starts at 2 s and doubles to 64 s. A failed
258
+ message remains until its work succeeds or a recovery page shows it gone. A
259
+ page shows it gone when the page is not full and does not hold the message.
260
+ The client must also have started to pull the page more than 5 s after the
261
+ first failure of the message. Then the message expired or was acknowledged
262
+ elsewhere. A full recovery page whose batch acknowledged a message pulls the
263
+ next page after a random wait from 1 s to 3 s. A full page that acknowledged
264
+ nothing pulls again only while a failed message remains, after the
265
+ failed-work wait. The failed-work wait starts again at 2 s after a recovery
266
+ pull that leaves no failed message, and when a new socket opens. A socket
267
+ open while a failed message remains schedules one failed-work pull; the
268
+ replay can make that pull empty. The `onEnvelope` callback of
269
+ `SignalProtocolRelayServer.subscribe` returns `void | Promise<void>`, so a
270
+ custom relay can also wait for the work of each envelope.
271
+
3
272
  ## 9.3.0
4
273
 
5
274
  - **Fixed: a hosted client with `hosted.profileKeys` now sends sealed 1:1
package/README.md CHANGED
@@ -39,7 +39,7 @@ The relay never needs message plaintext or device private keys.
39
39
 
40
40
  The OpenE2EE Signal Protocol SDK implements a versioned profile of the published Signal Protocol specifications. It is not affiliated with Signal Messenger and is **not wire-compatible with Signal Messenger or libsignal**. Messages, identities, and safety numbers do not interoperate. See the [notice](./NOTICE) and [documented deviations](./docs/DEVIATIONS.md).
41
41
 
42
- Version `9.3.x`. Public APIs and persisted formats follow semantic versioning.
42
+ Version `9.5.x`. Public APIs and persisted formats follow semantic versioning.
43
43
 
44
44
  ## Install
45
45
 
package/SECURITY.md CHANGED
@@ -7,8 +7,8 @@ backports.
7
7
 
8
8
  | Version | Supported |
9
9
  | ------- | ------------------ |
10
- | 9.3.x | :white_check_mark: |
11
- | < 9.3.0 | :x: |
10
+ | 9.5.x | :white_check_mark: |
11
+ | < 9.5.0 | :x: |
12
12
 
13
13
  ## Reporting a Vulnerability
14
14
 
package/client/README.md CHANGED
@@ -186,24 +186,21 @@ After the `onMessageDecrypted` handler resolves for a message that asks for a
186
186
  receipt, the client sends an end-to-end encrypted delivery receipt to each
187
187
  device of the sender. The `deliveryReceipts` option selects the messages:
188
188
 
189
- | Value | Receipt |
190
- | -------------------- | ---------------------------------------------------------- |
191
- | `'always'` (default) | For each message that asks for one |
192
- | `'auto'` | Only for a message that arrived through sealed sender |
193
- | `'off'` | None |
194
-
195
- `'auto'` is for a relay that reports the delivery of an identified message to
196
- its sender itself. The Signal Protocol Relay does not do that yet, so with
197
- `'auto'` the sender of an identified message gets no receipt.
198
- `DecryptedEnvelope.arrivedSealed` tells whether a message arrived through
199
- sealed sender. Read receipts are not affected.
189
+ | Value | Receipt |
190
+ | ------------------ | -------------------------------------------------------- |
191
+ | `'auto'` (default) | The same receipts as `'always'` |
192
+ | `'always'` | For each message that asks for one, sealed or identified |
193
+ | `'off'` | None |
194
+
195
+ `'auto'` sends the same receipts as `'always'`.
196
+ `DecryptedEnvelope.arrivedSealed` tells whether a message arrived through sealed
197
+ sender. Read receipts are not affected.
200
198
 
201
199
  The sender keeps a copy of each message that it sends, plaintext included, so
202
200
  that it can send the message again when the recipient asks for a retry. A
203
201
  delivery receipt deletes that copy. A message that gets no receipt, with
204
- `'off'` or with `'auto'` for an identified message, keeps its copy on the
205
- sender device until the copy is 14 days old. Only client creation and `stop()`
206
- delete such old copies.
202
+ `'off'`, keeps its copy on the sender device until the copy is 14 days old.
203
+ Only client creation and `stop()` delete such old copies.
207
204
 
208
205
  ### Hosted presence
209
206
 
@@ -130,7 +130,6 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
130
130
  */
131
131
  subscribeRelayConnectionState(listener: (state: RelayConnectionState) => void): Unsubscribe;
132
132
  private relayUnsubscribe?;
133
- private retryUnsubscribe?;
134
133
  /**
135
134
  * Cached sender certificate for sealed sender.
136
135
  * Lazily fetched and refreshed one hour before its signed expiration.
@@ -142,6 +141,22 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
142
141
  * @see SignalProtocolClientState for state details
143
142
  */
144
143
  private readonly state;
144
+ /**
145
+ * The delivery receipt sends in progress, from a batch timer, the batch
146
+ * bound, stopRelaySubscription(), or stop(): the relay work item of each
147
+ * send, and the promise that settles when the send finishes. While stop()
148
+ * holds the batches, only stop() starts a send. stop() waits until its
149
+ * receipt deadline for the sends that are in progress when it starts,
150
+ * except a send that an earlier stop() stopped, and for the sends that it
151
+ * starts. It does not stop them before then.
152
+ */
153
+ private readonly deliveryReceiptSends;
154
+ /**
155
+ * The stop() in progress. It is set before a step of stop() runs, so a
156
+ * stop() call that overlaps it, also from a step, waits for it, and a
157
+ * subscription start is refused.
158
+ */
159
+ private stopping?;
145
160
  /**
146
161
  * Get retry rate limiting state for retry operations
147
162
  */
@@ -183,13 +198,14 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
183
198
  */
184
199
  private get retryConfig();
185
200
  /**
186
- * Get retry dedup state for retry operations
201
+ * Get retry response state for retry operations
187
202
  */
188
- private get retryDedupState();
203
+ private get retryResponseState();
189
204
  /**
190
- * Get retry callbacks for retry operations. Session changes and resends use
191
- * the given context, so their hooks run through its relay work. A resend
192
- * waits for the recipient's lock only until stop() stops the work.
205
+ * Get retry callbacks for retry operations. Session changes use the given
206
+ * context, so their hooks run through its relay work. A resend goes only to
207
+ * the device that asked, and waits for the recipient's lock only until the
208
+ * stop signal aborts.
193
209
  */
194
210
  private retryCallbacks;
195
211
  /**
@@ -198,10 +214,30 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
198
214
  private get relaySubscriptionState();
199
215
  /**
200
216
  * Get relay subscription callbacks (delegate back to DefaultSignalProtocolClient methods).
201
- * Receipts and typing indicators use the given context, so their hooks run
202
- * through its relay work. Each receipt send is relay work of its own.
217
+ * Receipts, typing indicators and retry requests use the given context, so
218
+ * their hooks run through its relay work. Each receipt send is relay work of
219
+ * its own. A retry request runs in the current work, so a stop of that work
220
+ * reaches the receive route, and the route keeps the request envelope.
203
221
  */
204
222
  private relaySubscriptionCallbacks;
223
+ /**
224
+ * Send one delivery receipt batch as relay work of its own. The context
225
+ * carries the stop signal of the tracker, which also aborts at a stop
226
+ * after the work ends, so a retry timer of the send sees that stop. The
227
+ * send is in deliveryReceiptSends while it runs.
228
+ */
229
+ private sendDeliveryReceiptAsRelayWork;
230
+ /**
231
+ * Start the send of every batched delivery receipt, once each. The batches
232
+ * leave the accumulator, so no batch timer sends them again. The returned
233
+ * promises settle when the sends finish. They never reject.
234
+ */
235
+ private flushPendingDeliveryReceipts;
236
+ /**
237
+ * Wait for the receipt sends that stop() waits for, with their app hooks,
238
+ * for no more than the given time.
239
+ */
240
+ private waitForStopReceiptSends;
205
241
  /** Client context whose hooks call the app through the given relay work. */
206
242
  private relayWorkContext;
207
243
  /**
@@ -465,12 +501,54 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
465
501
  * 3. On retryable error: sends retry request via relay or options callback
466
502
  * 4. Re-throws error for caller to handle
467
503
  *
504
+ * A `retry_request` envelope holds no plaintext. This method rejects it
505
+ * before decryption and sends no retry request. Give it to
506
+ * `receiveIncomingEnvelopes`, which handles it.
507
+ *
508
+ * A failed envelope that this client asked a resend for, and each resend
509
+ * or null message for it, gives plaintext at most once on both receive
510
+ * paths. When this client processed the envelope, or the application
511
+ * already has that content, this method acknowledges the envelope and
512
+ * throws MESSAGE_DUPLICATE with no decrypt.
513
+ *
514
+ * A null message carries no content. The client consumes a null message
515
+ * when the content adapter reports `nullMessage: true`, and a custom
516
+ * adapter must report it for its own null encoding. This method never
517
+ * returns a null message. It marks the null message processed,
518
+ * acknowledges it and throws MESSAGE_DUPLICATE. A null message for a
519
+ * failed envelope marks that envelope processed, so a redelivery of it
520
+ * is dropped, but a content resend for it that comes later still gives
521
+ * its plaintext.
522
+ *
523
+ * A resend or null message that fails to decrypt, or whose seal fails to
524
+ * open, asks again for its failed envelope under the same retry ID. When
525
+ * the processed record of the failed envelope fails to store after a
526
+ * decrypt, the client writes a warning with the behavior
527
+ * RETRY_FULFILL_WRITE_FAILED, as on every receive path, and this method
528
+ * returns the plaintext. A redelivery of the failed envelope or of
529
+ * another family member can then give the content again. When a
530
+ * processed record of a null message or of its failed envelope fails to
531
+ * store, the client writes a warning with the behavior
532
+ * RETRY_NULL_WRITE_FAILED, as on every receive path, and this method
533
+ * still throws MESSAGE_DUPLICATE. A redelivery of the failed envelope
534
+ * can then give the content.
535
+ *
468
536
  * @param envelope - The encrypted message envelope
469
537
  * @param options - Transport callbacks for background (no relay) scenarios
470
538
  * @returns Decrypted plaintext
471
539
  * @throws EncryptionError after sending retry request if decryption fails
540
+ * @throws EncryptionError INVALID_CIPHERTEXT for a `retry_request` envelope
541
+ * @throws EncryptionError MESSAGE_DUPLICATE when this client processed the
542
+ * envelope, the application already has the content of the failed
543
+ * envelope of a retry request, or the envelope is a null message
472
544
  */
473
545
  processIncomingEnvelope(envelope: IncomingEnvelope, options?: ProcessEnvelopeOptions): Promise<string>;
546
+ /**
547
+ * Decrypt one envelope that is not a `retry_request`, under its retry family
548
+ * lock. The fingerprint is that of the delivered envelope, also for the
549
+ * inner envelope of a seal.
550
+ */
551
+ private decryptIncomingEnvelope;
474
552
  /**
475
553
  * Process multiple incoming encrypted message envelopes.
476
554
  *
@@ -511,7 +589,10 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
511
589
  /**
512
590
  * Receive a pulled batch through the subscription content handler.
513
591
  * The application must register onMessageDecrypted before calling this method.
514
- * Successful IDs are ready for transport acknowledgment.
592
+ * Processed IDs are ready for transport acknowledgment. They include
593
+ * each envelope that the client drops as a duplicate, and each null
594
+ * message that the content adapter reports, which the client consumes
595
+ * and never gives to onMessageDecrypted.
515
596
  */
516
597
  receiveIncomingEnvelopes(envelopes: IncomingEnvelope[]): Promise<{
517
598
  processedMessageIds: string[];
@@ -525,6 +606,8 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
525
606
  *
526
607
  * @param envelope - The failed message envelope
527
608
  * @param error - The decryption error
609
+ * @param family - The retry family of the delivered envelope
610
+ * @param fingerprint - The fingerprint of the delivered envelope
528
611
  * @param options - Optional transport callbacks (for background without relay)
529
612
  */
530
613
  private sendRetryRequestInternal;
@@ -708,6 +791,8 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
708
791
  *
709
792
  * Callers can run this manually after registering hooks via registerHook().
710
793
  * Called automatically by create() when relay + hook configured.
794
+ * A call while stop() runs is refused and logged; start again after stop()
795
+ * resolves.
711
796
  *
712
797
  * @see SignalProtocolClient.startRelaySubscription
713
798
  */
@@ -724,38 +809,6 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
724
809
  * @see SignalProtocolClient.stopRelaySubscription
725
810
  */
726
811
  stopRelaySubscription(): void;
727
- /**
728
- * Start listening for retry requests from recipients (SESAME spec §6.2)
729
- *
730
- * When a recipient cannot decrypt a message, they send a retry request.
731
- * This method subscribes to incoming retry requests and processes them
732
- * by resending the original message with a new session.
733
- *
734
- * Automatically started if relay.subscribeRetryRequests is available.
735
- * Call this manually if you need to restart the subscription.
736
- */
737
- startRetryRequestSubscription(): void;
738
- /**
739
- * Handle a retry request and resend the original message
740
- *
741
- * Per SESAME spec §4.1 (Resending Process):
742
- * 1. Look up MessageRecord by sequence number
743
- * 2. Validate retry limits and message TTL
744
- * 3. Check session state:
745
- * - If NO active session OR active session IS orphaned (matches MessageRecord.sessionStateId):
746
- * → Fetch prekey bundle and create new session
747
- * - If DIFFERENT active session exists:
748
- * → Use it directly (no prekey fetch, prevents rate limit issues)
749
- * 4. Re-encrypt and send the original message
750
- *
751
- * This prevents infinite retry loops where each retry creates a new session
752
- * with different header keys.
753
- *
754
- * The request runs as relay work, so its hooks run through that work.
755
- *
756
- * @param retryRequest - The retry request from the recipient
757
- */
758
- private handleRetryRequestAndResend;
759
812
  /**
760
813
  * Send delivery receipt to original sender (all devices)
761
814
  *
@@ -850,10 +903,19 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
850
903
  * Delegates to MessageOps.sendTypingIndicator for implementation.
851
904
  */
852
905
  sendTypingIndicator(recipientUserId: string, recipientDeviceId: number, conversationId: string, action: TypingAction, groupId?: string): Promise<void>;
906
+ /**
907
+ * Client context of a receipt send outside relay work, such as a read
908
+ * receipt that the app sends. It carries the stop signal of the tracker,
909
+ * so the next stop() clears the retry timer of the send. stop() does not
910
+ * wait for the send.
911
+ */
912
+ private receiptContext;
853
913
  /**
854
914
  * Internal method to send receipt (delivery or read)
855
915
  *
856
- * Delegates to MessageOps.sendReceipt for implementation.
916
+ * Delegates to MessageOps.sendReceipt for implementation. The context
917
+ * carries the stop signal of the tracker, so the next stop() clears the
918
+ * retry timer of the send.
857
919
  */
858
920
  private sendReceipt;
859
921
  /**
@@ -872,13 +934,34 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
872
934
  * Stop the Signal Protocol client and clean up resources
873
935
  *
874
936
  * Call this when the user logs out or the app shuts down.
875
- * Unsubscribes from relay server, waits for the SDK work of the
876
- * deliveries, retry requests, and receipt sends in progress, and cleans up
877
- * any pending operations.
878
- *
879
- * It does not wait for app hooks, so a hook can await stop(). When a hook
880
- * returns after stop(), the SDK drops the work after the hook and writes
881
- * nothing more. The relay delivers the envelope again after the next start.
937
+ * It starts the send of each batched delivery receipt, once each, and
938
+ * unsubscribes from the relay server. Then it waits for delivery receipt
939
+ * sends, with their app hooks, until one receipt deadline 5 s after stop()
940
+ * starts. It waits for each receipt send that is in progress when stop()
941
+ * starts, except a send that an earlier stop() stopped, and for the sends
942
+ * that it starts. A delivery that finishes during the wait batches its
943
+ * receipt. At the end of each wait, stop() sends the batches that wait and
944
+ * waits for those sends until the same deadline. It does this again while
945
+ * the deadline is not past. stop() holds the receipt batches from its
946
+ * first flush until it clears its tracking state. During the hold,
947
+ * stopRelaySubscription() does not send them, and stop() drops a receipt
948
+ * batched after its last flush. At the deadline it stops each receipt
949
+ * send that is left: a send that waits in an app hook stops, and that
950
+ * receipt is not sent. A send that is in its relay call at the deadline
951
+ * is waited for, and that receipt can still be sent. It also
952
+ * waits for the SDK work of the deliveries and retry requests in progress.
953
+ * Then it cleans up any pending operations.
954
+ *
955
+ * Apart from the receipt wait, it does not wait for app hooks, so a hook
956
+ * can await stop(). A hook of a delivery receipt send that awaits stop()
957
+ * holds stop() until the receipt deadline. stop() does not wait for read
958
+ * and viewed receipt sends. When a hook returns after stop(), the SDK drops
959
+ * the work after the hook and writes nothing more. The relay delivers the
960
+ * envelope again after the next start.
961
+ *
962
+ * A call to startRelaySubscription() while stop() runs is refused and
963
+ * logged; start again after stop() resolves. A stop() call that overlaps a
964
+ * running stop() waits for it and settles as it settles.
882
965
  *
883
966
  * @example
884
967
  * ```typescript
@@ -887,6 +970,8 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
887
970
  * ```
888
971
  */
889
972
  stop(): Promise<void>;
973
+ /** The steps of one stop(). A stop() call that overlaps it waits for it. */
974
+ private stopOnce;
890
975
  /**
891
976
  * Receive and decrypt message from another device (multi-device support)
892
977
  *
@@ -913,21 +998,6 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
913
998
  * @returns Number of sessions cleaned up
914
999
  */
915
1000
  cleanupExpiredSesameSessions(): Promise<number>;
916
- /**
917
- * Run periodic cleanup of internal tracking state.
918
- *
919
- * Safe to call frequently - internally throttled to avoid overhead.
920
- * Recommended call sites:
921
- * - App foreground transition
922
- * - After successful message batch processing
923
- * - Periodically during long sessions
924
- *
925
- * Cleans up:
926
- * - Expired retry dedup entries (recentRetryRequests)
927
- *
928
- * @returns Number of entries cleaned up
929
- */
930
- runPeriodicCleanup(): number;
931
1001
  /**
932
1002
  * Rotate the device's prekeys in one publication.
933
1003
  *