@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.
- package/ADAPTERS.md +1 -0
- package/CHANGELOG.md +269 -0
- package/README.md +1 -1
- package/SECURITY.md +2 -2
- package/client/README.md +11 -14
- package/dist/client/client.d.ts +134 -64
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +333 -179
- package/dist/client/client.js.map +1 -1
- package/dist/client/config.d.ts +4 -7
- package/dist/client/config.d.ts.map +1 -1
- package/dist/client/config.js.map +1 -1
- package/dist/client/content-adapter.d.ts +8 -0
- package/dist/client/content-adapter.d.ts.map +1 -1
- package/dist/client/content-adapter.js +4 -0
- package/dist/client/content-adapter.js.map +1 -1
- package/dist/client/event-hooks.d.ts +1 -1
- package/dist/client/group-outbox.d.ts +2 -4
- package/dist/client/group-outbox.d.ts.map +1 -1
- package/dist/client/group-outbox.js +7 -1
- package/dist/client/group-outbox.js.map +1 -1
- package/dist/client/hosted-anonymous-delivery.d.ts +1 -1
- package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
- package/dist/client/hosted-anonymous-delivery.js +5 -14
- package/dist/client/hosted-anonymous-delivery.js.map +1 -1
- package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
- package/dist/client/hosted-mailbox-subscription.js +136 -15
- package/dist/client/hosted-mailbox-subscription.js.map +1 -1
- package/dist/client/hosted-transport.d.ts +2 -2
- package/dist/client/hosted-transport.d.ts.map +1 -1
- package/dist/client/hosted-transport.js +20 -5
- package/dist/client/hosted-transport.js.map +1 -1
- package/dist/client/messages.d.ts.map +1 -1
- package/dist/client/messages.js +12 -2
- package/dist/client/messages.js.map +1 -1
- package/dist/client/relay-acceptance.d.ts +29 -0
- package/dist/client/relay-acceptance.d.ts.map +1 -0
- package/dist/client/relay-acceptance.js +29 -0
- package/dist/client/relay-acceptance.js.map +1 -0
- package/dist/client/relay-subscription.d.ts +43 -1
- package/dist/client/relay-subscription.d.ts.map +1 -1
- package/dist/client/relay-subscription.js +278 -100
- package/dist/client/relay-subscription.js.map +1 -1
- package/dist/client/relay-work.d.ts +7 -6
- package/dist/client/relay-work.d.ts.map +1 -1
- package/dist/client/relay-work.js +34 -9
- package/dist/client/relay-work.js.map +1 -1
- package/dist/client/retry-family.d.ts +119 -0
- package/dist/client/retry-family.d.ts.map +1 -0
- package/dist/client/retry-family.js +170 -0
- package/dist/client/retry-family.js.map +1 -0
- package/dist/client/retry-request-envelope.d.ts +106 -0
- package/dist/client/retry-request-envelope.d.ts.map +1 -0
- package/dist/client/retry-request-envelope.js +245 -0
- package/dist/client/retry-request-envelope.js.map +1 -0
- package/dist/client/retry.d.ts +66 -24
- package/dist/client/retry.d.ts.map +1 -1
- package/dist/client/retry.js +239 -139
- package/dist/client/retry.js.map +1 -1
- package/dist/client/sealed-sender.d.ts +15 -3
- package/dist/client/sealed-sender.d.ts.map +1 -1
- package/dist/client/sealed-sender.js +22 -3
- package/dist/client/sealed-sender.js.map +1 -1
- package/dist/client/signal-service-cipher.d.ts +52 -0
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +185 -15
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/client/state.d.ts +12 -64
- package/dist/client/state.d.ts.map +1 -1
- package/dist/client/state.js +22 -98
- package/dist/client/state.js.map +1 -1
- package/dist/client/types.d.ts +28 -2
- package/dist/client/types.d.ts.map +1 -1
- package/dist/client/types.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/types.d.ts +1 -1
- package/dist/internal/protocol/sealed-sender/types.js +1 -1
- package/dist/local/store/received-content.d.ts +16 -2
- package/dist/local/store/received-content.d.ts.map +1 -1
- package/dist/local/store/received-content.js +18 -3
- package/dist/local/store/received-content.js.map +1 -1
- package/dist/local/store/reliability.d.ts +260 -2
- package/dist/local/store/reliability.d.ts.map +1 -1
- package/dist/local/store/reliability.js +390 -12
- package/dist/local/store/reliability.js.map +1 -1
- package/dist/remote/relay/types.d.ts +31 -31
- package/dist/remote/relay/types.d.ts.map +1 -1
- package/dist/types/api.d.ts +74 -26
- package/dist/types/api.d.ts.map +1 -1
- package/docs/ASSURANCE.md +5 -5
- package/docs/DEVIATIONS.md +4 -5
- package/docs/INTERFACES.md +2 -0
- 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.
|
|
42
|
+
Version `9.5.x`. Public APIs and persisted formats follow semantic versioning.
|
|
43
43
|
|
|
44
44
|
## Install
|
|
45
45
|
|
package/SECURITY.md
CHANGED
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
|
|
190
|
-
|
|
|
191
|
-
| `'
|
|
192
|
-
| `'
|
|
193
|
-
| `'off'`
|
|
194
|
-
|
|
195
|
-
`'auto'`
|
|
196
|
-
|
|
197
|
-
|
|
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'
|
|
205
|
-
|
|
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
|
|
package/dist/client/client.d.ts
CHANGED
|
@@ -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
|
|
201
|
+
* Get retry response state for retry operations
|
|
187
202
|
*/
|
|
188
|
-
private get
|
|
203
|
+
private get retryResponseState();
|
|
189
204
|
/**
|
|
190
|
-
* Get retry callbacks for retry operations. Session changes
|
|
191
|
-
*
|
|
192
|
-
* waits for the recipient's lock only until
|
|
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
|
|
202
|
-
* through its relay work. Each receipt send is relay work of
|
|
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
|
-
*
|
|
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
|
-
*
|
|
876
|
-
*
|
|
877
|
-
*
|
|
878
|
-
*
|
|
879
|
-
*
|
|
880
|
-
*
|
|
881
|
-
*
|
|
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
|
*
|