@open-e2ee/signal-protocol-sdk 13.5.2 → 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 (179) hide show
  1. package/CHANGELOG.md +369 -0
  2. package/README.md +9 -8
  3. package/SECURITY.md +2 -2
  4. package/client/README.md +5 -3
  5. package/device/README.md +4 -3
  6. package/dist/client/client.d.ts +20 -55
  7. package/dist/client/client.d.ts.map +1 -1
  8. package/dist/client/client.js +133 -165
  9. package/dist/client/client.js.map +1 -1
  10. package/dist/client/content-adapter.d.ts +35 -6
  11. package/dist/client/content-adapter.d.ts.map +1 -1
  12. package/dist/client/content-adapter.js +28 -0
  13. package/dist/client/content-adapter.js.map +1 -1
  14. package/dist/client/event-hooks.d.ts +22 -11
  15. package/dist/client/event-hooks.d.ts.map +1 -1
  16. package/dist/client/event-hooks.js.map +1 -1
  17. package/dist/client/group-fetcher.d.ts.map +1 -1
  18. package/dist/client/group-fetcher.js +43 -0
  19. package/dist/client/group-fetcher.js.map +1 -1
  20. package/dist/client/group-key-sync.d.ts +65 -0
  21. package/dist/client/group-key-sync.d.ts.map +1 -0
  22. package/dist/client/group-key-sync.js +286 -0
  23. package/dist/client/group-key-sync.js.map +1 -0
  24. package/dist/client/group-outbox.d.ts +20 -6
  25. package/dist/client/group-outbox.d.ts.map +1 -1
  26. package/dist/client/group-outbox.js +153 -80
  27. package/dist/client/group-outbox.js.map +1 -1
  28. package/dist/client/group-receive-authorization.d.ts +16 -9
  29. package/dist/client/group-receive-authorization.d.ts.map +1 -1
  30. package/dist/client/group-receive-authorization.js +25 -16
  31. package/dist/client/group-receive-authorization.js.map +1 -1
  32. package/dist/client/hosted-anonymous-delivery.d.ts +13 -1
  33. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
  34. package/dist/client/hosted-anonymous-delivery.js +48 -5
  35. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  36. package/dist/client/hosted-mailbox-subscription.d.ts +6 -5
  37. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  38. package/dist/client/hosted-mailbox-subscription.js +4 -8
  39. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  40. package/dist/client/hosted-sandbox-identity.d.ts +66 -3
  41. package/dist/client/hosted-sandbox-identity.d.ts.map +1 -1
  42. package/dist/client/hosted-sandbox-identity.js +136 -45
  43. package/dist/client/hosted-sandbox-identity.js.map +1 -1
  44. package/dist/client/hosted-transport.d.ts +12 -0
  45. package/dist/client/hosted-transport.d.ts.map +1 -1
  46. package/dist/client/hosted-transport.js +85 -43
  47. package/dist/client/hosted-transport.js.map +1 -1
  48. package/dist/client/hosted.d.ts +13 -10
  49. package/dist/client/hosted.d.ts.map +1 -1
  50. package/dist/client/hosted.js +13 -10
  51. package/dist/client/hosted.js.map +1 -1
  52. package/dist/client/index.d.ts +2 -2
  53. package/dist/client/index.d.ts.map +1 -1
  54. package/dist/client/index.js +1 -1
  55. package/dist/client/index.js.map +1 -1
  56. package/dist/client/receive-queue.d.ts +3 -4
  57. package/dist/client/receive-queue.d.ts.map +1 -1
  58. package/dist/client/receive-queue.js +24 -32
  59. package/dist/client/receive-queue.js.map +1 -1
  60. package/dist/client/relay-period-close.d.ts +35 -0
  61. package/dist/client/relay-period-close.d.ts.map +1 -0
  62. package/dist/client/relay-period-close.js +63 -0
  63. package/dist/client/relay-period-close.js.map +1 -0
  64. package/dist/client/relay-subscription.d.ts.map +1 -1
  65. package/dist/client/relay-subscription.js +4 -9
  66. package/dist/client/relay-subscription.js.map +1 -1
  67. package/dist/client/retry-request-envelope.d.ts +4 -2
  68. package/dist/client/retry-request-envelope.d.ts.map +1 -1
  69. package/dist/client/retry-request-envelope.js +6 -4
  70. package/dist/client/retry-request-envelope.js.map +1 -1
  71. package/dist/client/retry-request-lifecycle.d.ts +7 -8
  72. package/dist/client/retry-request-lifecycle.d.ts.map +1 -1
  73. package/dist/client/retry-request-lifecycle.js +10 -7
  74. package/dist/client/retry-request-lifecycle.js.map +1 -1
  75. package/dist/client/retry-terminal-recovery.d.ts +14 -15
  76. package/dist/client/retry-terminal-recovery.d.ts.map +1 -1
  77. package/dist/client/retry-terminal-recovery.js +16 -17
  78. package/dist/client/retry-terminal-recovery.js.map +1 -1
  79. package/dist/client/retry-utils.d.ts +22 -0
  80. package/dist/client/retry-utils.d.ts.map +1 -1
  81. package/dist/client/retry-utils.js +30 -0
  82. package/dist/client/retry-utils.js.map +1 -1
  83. package/dist/client/send-deadline.d.ts +3 -2
  84. package/dist/client/send-deadline.d.ts.map +1 -1
  85. package/dist/client/send-deadline.js +6 -1
  86. package/dist/client/send-deadline.js.map +1 -1
  87. package/dist/client/send-timestamp.d.ts +71 -14
  88. package/dist/client/send-timestamp.d.ts.map +1 -1
  89. package/dist/client/send-timestamp.js +87 -19
  90. package/dist/client/send-timestamp.js.map +1 -1
  91. package/dist/client/signal-service-cipher.d.ts +125 -13
  92. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  93. package/dist/client/signal-service-cipher.js +413 -102
  94. package/dist/client/signal-service-cipher.js.map +1 -1
  95. package/dist/client/types.d.ts +21 -16
  96. package/dist/client/types.d.ts.map +1 -1
  97. package/dist/client/types.js.map +1 -1
  98. package/dist/index.d.ts +2 -2
  99. package/dist/index.d.ts.map +1 -1
  100. package/dist/index.js +1 -1
  101. package/dist/index.js.map +1 -1
  102. package/dist/internal/groups/key-sync-ledger.d.ts +65 -0
  103. package/dist/internal/groups/key-sync-ledger.d.ts.map +1 -0
  104. package/dist/internal/groups/key-sync-ledger.js +104 -0
  105. package/dist/internal/groups/key-sync-ledger.js.map +1 -0
  106. package/dist/internal/groups/receive-record.d.ts +4 -1
  107. package/dist/internal/groups/receive-record.d.ts.map +1 -1
  108. package/dist/internal/groups/receive-record.js.map +1 -1
  109. package/dist/internal/session/cipher.d.ts.map +1 -1
  110. package/dist/internal/session/cipher.js +14 -0
  111. package/dist/internal/session/cipher.js.map +1 -1
  112. package/dist/local/store/conformance/cases/durability.d.ts.map +1 -1
  113. package/dist/local/store/conformance/cases/durability.js +6 -0
  114. package/dist/local/store/conformance/cases/durability.js.map +1 -1
  115. package/dist/local/store/conformance/records.d.ts.map +1 -1
  116. package/dist/local/store/conformance/records.js +3 -0
  117. package/dist/local/store/conformance/records.js.map +1 -1
  118. package/dist/local/store/expo/adapter.js +2 -2
  119. package/dist/local/store/expo/adapter.js.map +1 -1
  120. package/dist/local/store/key-value/adapter.d.ts +6 -5
  121. package/dist/local/store/key-value/adapter.d.ts.map +1 -1
  122. package/dist/local/store/key-value/adapter.js +21 -19
  123. package/dist/local/store/key-value/adapter.js.map +1 -1
  124. package/dist/local/store/key-value/receive-work.d.ts +0 -5
  125. package/dist/local/store/key-value/receive-work.d.ts.map +1 -1
  126. package/dist/local/store/key-value/receive-work.js +0 -16
  127. package/dist/local/store/key-value/receive-work.js.map +1 -1
  128. package/dist/local/store/node/adapter.js +2 -2
  129. package/dist/local/store/node/adapter.js.map +1 -1
  130. package/dist/local/store/react-native/adapter.js +2 -2
  131. package/dist/local/store/react-native/adapter.js.map +1 -1
  132. package/dist/local/store/receive-work.d.ts +32 -32
  133. package/dist/local/store/receive-work.d.ts.map +1 -1
  134. package/dist/local/store/receive-work.js +112 -65
  135. package/dist/local/store/receive-work.js.map +1 -1
  136. package/dist/local/store/received-content.d.ts +0 -5
  137. package/dist/local/store/received-content.d.ts.map +1 -1
  138. package/dist/local/store/received-content.js +0 -17
  139. package/dist/local/store/received-content.js.map +1 -1
  140. package/dist/local/store/reliability.d.ts +191 -53
  141. package/dist/local/store/reliability.d.ts.map +1 -1
  142. package/dist/local/store/reliability.js +517 -37
  143. package/dist/local/store/reliability.js.map +1 -1
  144. package/dist/local/store/sqlite/key-storage/metadata.d.ts +1 -8
  145. package/dist/local/store/sqlite/key-storage/metadata.d.ts.map +1 -1
  146. package/dist/local/store/sqlite/key-storage/metadata.js +1 -18
  147. package/dist/local/store/sqlite/key-storage/metadata.js.map +1 -1
  148. package/dist/local/store/sqlite/migrations.d.ts.map +1 -1
  149. package/dist/local/store/sqlite/migrations.js +8 -0
  150. package/dist/local/store/sqlite/migrations.js.map +1 -1
  151. package/dist/local/store/sqlite/store.d.ts +5 -5
  152. package/dist/local/store/sqlite/store.d.ts.map +1 -1
  153. package/dist/local/store/sqlite/store.js +29 -9
  154. package/dist/local/store/sqlite/store.js.map +1 -1
  155. package/dist/local/store/web/adapter.d.ts +11 -10
  156. package/dist/local/store/web/adapter.d.ts.map +1 -1
  157. package/dist/local/store/web/adapter.js +69 -51
  158. package/dist/local/store/web/adapter.js.map +1 -1
  159. package/dist/local/store/web-sqlite/adapter.js +2 -2
  160. package/dist/local/store/web-sqlite/adapter.js.map +1 -1
  161. package/dist/remote/relay/request-admission.d.ts +5 -3
  162. package/dist/remote/relay/request-admission.d.ts.map +1 -1
  163. package/dist/remote/relay/request-admission.js +2 -1
  164. package/dist/remote/relay/request-admission.js.map +1 -1
  165. package/dist/remote/relay/types.d.ts +1 -1
  166. package/dist/types/api.d.ts +50 -71
  167. package/dist/types/api.d.ts.map +1 -1
  168. package/dist/types/errors.d.ts +52 -18
  169. package/dist/types/errors.d.ts.map +1 -1
  170. package/dist/types/errors.js +58 -17
  171. package/dist/types/errors.js.map +1 -1
  172. package/docs/ASSURANCE.md +8 -8
  173. package/docs/CLIENT_COMPOSITION.md +4 -2
  174. package/docs/DEVIATIONS.md +175 -11
  175. package/docs/ERROR_HANDLING.md +38 -23
  176. package/docs/GETTING_STARTED.md +22 -2
  177. package/local/store/README.md +32 -8
  178. package/package.json +7 -2
  179. package/remote/relay/README.md +4 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,374 @@
1
1
  # Changelog
2
2
 
3
+ ## 14.1.0
4
+
5
+ ### Added
6
+
7
+ - `hostedRelayDeviceOwnedIdentity(storage)`, from the package root and
8
+ `@open-e2ee/signal-protocol-sdk/client`. It returns a `getIdentityAssertion`
9
+ callback for a device-owned account in a Sandbox environment or in a
10
+ Production environment in device-owned identity mode. It signs a
11
+ normal-assurance registration assertion with an Ed25519 key in `storage`.
12
+ It refuses recovery, refresh, provider migration, and recent or step-up
13
+ assurance, and creates no key for a refused request. Its TSDoc documents
14
+ the header and claims of the assertion. It uses the key slot of
15
+ `hostedRelaySandboxIdentity`, so for the same store and publishable key both
16
+ helpers return the same account. `hostedRelaySandboxIdentity` keeps its
17
+ Sandbox-only behavior. A Production project in application-bound mode
18
+ refuses the assertion with `ASSERTION_INVALID`.
19
+
20
+ ### Changed
21
+
22
+ - **The OpenE2EE Signal Protocol Relay mailbox socket stays open across a device
23
+ token renewal.** The Relay authorizes the device token once, at the socket
24
+ handshake, and closes the socket with 4401 `AUTHORITY_REVALIDATE` when the
25
+ authority changes. Before, the hosted transport closed and reopened the socket
26
+ shortly before each token expired, about every 14 minutes. Now it renews the
27
+ token only for an HTTP request or a reconnect, and reconnects only on a Relay
28
+ close or a transport error. The presence watches and the Relay receipt intake
29
+ stay on the one socket. `onConnectionState` and `relayConnectionState` no
30
+ longer emit `reconnecting` for a failed renewal socket, because no renewal
31
+ socket exists. No API changes. See `docs/RELAY_CONNECTION.md`.
32
+
33
+ ### Fixed
34
+
35
+ - **A `PERIOD_CLOSED` refusal gets one repeat.** When the Relay refuses
36
+ a device post with `PERIOD_CLOSED`, the SDK posts the same request once more,
37
+ with the same message ID, epoch and bytes. When the Relay refuses the repeat
38
+ too, the device stays pending: the send throws a retryable error with its
39
+ deadline, and a replay posts the same operation. On the sealed route the
40
+ error code stays `DELIVERY_FAILED`.
41
+ - **A send reaches a recovered device.** When the Relay refuses a
42
+ device post with `NOT_FOUND` because the mailbox generation of the device is
43
+ retired, and the device list names the device at a new generation, the SDK
44
+ archives the session, starts a new session and posts to the new generation
45
+ under the same message ID and epoch. The other devices keep their
46
+ acceptance, and the Relay charges each device once. Before, the device ended
47
+ with a `NOT_FOUND` refusal.
48
+
49
+ ## 14.0.0
50
+
51
+ ### Breaking
52
+
53
+ - **`decryptGroupMessage` is removed from the client.**
54
+ `DefaultSignalProtocolClient` and the `SignalProtocolClient` interface no
55
+ longer have the method, which 12.0.0 deprecated. Use
56
+ `processIncomingEnvelope`. It returns a receive outcome and keeps the
57
+ content until `completeReceive`. Give it the framed message as a
58
+ `sender_key` envelope. The client resolves the group from the frame. See
59
+ step 20.
60
+ - **Managed group content with no group context is denied.** A client with
61
+ a `groups` config denies all such content. The reason is
62
+ `legacy-no-context`, also when the client has state of the group. An
63
+ earlier check can deny the content first, such as `blocked` for a blocked
64
+ group. Before, the client decided such content against its local group
65
+ state. Content from an SDK 11 sender is not delivered. A client with no
66
+ `groups` config refuses such content with a `GroupReceiveRefusedError` of
67
+ reason `configuration`. See step 21.
68
+ - **A send to a managed group with no stored master key throws.** When the
69
+ client has a `groups` config and its group store has no master key for
70
+ the managed group, a new send or a manual resend of content with no
71
+ logged group context throws `EncryptionError` with the new code
72
+ `GROUP_MASTER_KEY_MISSING`, and stores and posts nothing. An attachment
73
+ send also uploads nothing. A manual resend of logged content that
74
+ carries a group context keeps that context and needs no master key. A
75
+ replay that must build a sent transcript for an own device skips that
76
+ transcript, keeps its posts, and logs one warning with the code.
77
+ Before, the client posted content with no group context, which every
78
+ receiver now denies. A send to an ad hoc group does not change.
79
+ See step 21.
80
+ - **The output of `encryptGroupMessage` is denied for a managed group.**
81
+ The primitive adds no group context and checks no master key. Unless the
82
+ plaintext already carries a group context, a `processIncomingEnvelope`
83
+ receiver denies the output for a managed group. A receiver with a `groups`
84
+ config gives the reason `legacy-no-context`, or `blocked` when the group
85
+ is blocked. A receiver with no `groups` config refuses the output with a
86
+ `GroupReceiveRefusedError` of reason `configuration`. The primitive
87
+ remains for a caller that delivers the bytes itself and decrypts them
88
+ with `decryptEnvelope`. See step 21.
89
+ - **`ReceivedContent` is removed.** The type of an SDK 11 received-content
90
+ row, which 13.5.0 deprecated, is no longer exported. Use
91
+ `ReceiveWorkRecord`. See step 22.
92
+ - **`ReceiveWorkRecord.awaitingEnvelope` is removed, and the sender fields
93
+ are required.** Each `ReceiveWorkRecord` now has the required fields
94
+ `messageId`, `senderUserId` and `senderDeviceId`. See step 22.
95
+ - **The legacy received-content conversion is removed, and the SQLite open
96
+ wrapper is renamed.** `LegacyConversionMarker`,
97
+ `LegacyReceivedContentSource`, `convertLegacyReceivedContent`,
98
+ `legacyReceiveWork`, `LEGACY_RECEIVED_CONTENT_UNREADABLE`,
99
+ `receivedContentKey`, `parseReceivedContent`,
100
+ `legacyReceivedContentSource` and `KeyValueReceiveWork.legacySource` are
101
+ no longer exported. No store converts an SDK 11 received-content row.
102
+ `convertSqliteLegacyReceivedContent` is now
103
+ `sweepSqliteLegacyReceivedContent`. It keeps its contract: when the sweep
104
+ fails, it closes the database and throws the error again. See step 22.
105
+ - **Each durable store deletes the legacy received content at open.** At
106
+ each open, the IndexedDB, SQLite and key-value stores delete every SDK 11
107
+ received-content row and every converted record that waits for its
108
+ envelope. The sweep reads each row only to count the readable rows, then
109
+ deletes it. It logs one warning with the code
110
+ `LEGACY_RECEIVED_CONTENT_DELETED` and two fields: `count` holds the
111
+ deleted rows and records, and `readable` holds the deleted rows that
112
+ parse. A readable row is in a store that SDK 12.0.0 or later never opened.
113
+ The sweep relies on the Relay retention constraint. The Relay keeps an
114
+ undelivered envelope for at most its retention period, 30 days in
115
+ production. The constraint does not cover a device that received the
116
+ content on SDK 11 inside the last 30 days. For that device, 13.x would
117
+ convert the row and complete it when the Relay delivers the envelope
118
+ again. This release deletes the row at first open, and the sweep does not
119
+ restore it. An open that finds nothing logs nothing. The memory store
120
+ keeps no data across a restart and has no sweep. See step 22.
121
+ - **`SignalProtocolContentAdapter` has the required method
122
+ `serializeGroupKeySync`.** `ParsedSyncContent.type` has the new member
123
+ `'groupKeySync'`, and `ParsedSyncContent` has the new optional field
124
+ `groupKey`. A custom adapter must implement the method, and its
125
+ `inspectContent` must report the result as a sync of type `'groupKeySync'`
126
+ with its `groupKey`. An adapter that spreads the result of
127
+ `createDefaultSignalProtocolContentAdapter()` into itself gets the default
128
+ method. Code that switches on the sync `type` must handle
129
+ `'groupKeySync'`. See step 23.
130
+ - **The retry terminal class `expired-content` is now `request-expired`.**
131
+ `RetryTerminalClass` no longer holds `expired-content`. A retry request
132
+ whose latest attempt the Relay answered or holds ends as `request-expired`
133
+ when its content did not come before its deadline. The session does not
134
+ reset. A retry request whose latest attempt the Relay did not accept ends
135
+ as `posting-deadline` at its posting deadline or its deadline. The session
136
+ resets. Only a `posting-deadline` end resets the session. The class
137
+ `request-expired` is not the delivery error cause `request-ended`. At
138
+ client start, the SDK moves each stored retry request record to a new key
139
+ prefix, and rewrites a stored `expired-content` end to `request-expired`.
140
+ It keeps the time, the emitted flag and the session reset of the end, so
141
+ a moved end can carry `event.recovery` from an SDK 13.x reset. The reader
142
+ also reads a stored `expired-content` end as `request-expired`. That
143
+ reader is removed only when both conditions are true: the next major SDK
144
+ version ships, and at least 60 days have passed since the publish day of
145
+ 14.0.0. See step 24.
146
+ - **Each send timestamp is unique per sender device.** A new send reserves
147
+ its timestamp in the store before it writes its intent and before it posts
148
+ anything. A new send with a timestamp that a different send of the device
149
+ used throws `InvalidSendTimestampError` with the new reason
150
+ `already_used`, and stores and posts nothing. The SDK's own sends, the
151
+ profile key offer and the sender key distribution, reserve from the same
152
+ index of the device. So an application that passes
153
+ `timestamp: Date.now()` can get `already_used` when it did not use the
154
+ value again itself. Omit `timestamp`, or send again with no `timestamp`
155
+ on `already_used`. When a different send used the timestamp that the SDK
156
+ reads from its clock, the SDK moves to the next free millisecond. A moved
157
+ timestamp more than 5 minutes ahead of the SDK clock throws the error with
158
+ the reason `too_far_ahead`. A reservation with no stored send holds its
159
+ timestamp for 5 minutes, and a new send can then take it. A send that
160
+ spends longer than 5 minutes between its reservation and its stored
161
+ intent, and whose timestamp another send took in the meantime, fails with
162
+ `already_used` instead of posting a duplicate timestamp.
163
+ `InvalidSendTimestampError.earliest` and `latest` are now optional, and
164
+ are absent for `already_used`. `SendResult.clientTimestamp` is now
165
+ required, and every send returns it. After the SDK has stored a send, a
166
+ retry with the same `clientMessageId` keeps the original timestamp and
167
+ reserves nothing. A send that failed before the SDK stored it gets a new
168
+ timestamp on retry. A manual resend, a retry answer and a group resend
169
+ keep the original timestamp and reserve nothing. A sync to linked devices
170
+ and the null message of a session reset reserve no timestamp. See step 25.
171
+ - **A received message is keyed by its sender and timestamp only.** The
172
+ receive queue drops a copy by the key `[senderUserId, timestamp]`. A later
173
+ message of the same sender with the same timestamp drops with no notice
174
+ and runs no `onMessageDecrypted`. This applies to any body and to any
175
+ device of the sender. `ReceivedMessageKey` no longer has the fields
176
+ `contentDigest` and `senderDeviceId`. At the first start on this release,
177
+ the SDK moves the stored received-timestamp records to a new prefix. Two
178
+ old records of one sender and timestamp become one record with the
179
+ earliest receive time. A custom store that checks
180
+ `ReceiveWorkRecord.received` gets a key with the two fields `senderUserId`
181
+ and `timestamp`. A receive record that SDK 13.x stored can still carry
182
+ `senderDeviceId` and `contentDigest` in `received`, and a custom store must
183
+ accept that shape until the next major. A send to the own account posts
184
+ only a sent transcript to each other own device, and posts nothing when
185
+ the account has no other device. See step 26.
186
+ - **The stores refuse SDK 13.x after the first open of this release.** The
187
+ IndexedDB store opens its database at version 12, and the SQLite store
188
+ applies step 7. Neither changes a table. A 13.x tab then fails to open
189
+ the database with `VersionError`, and a 13.x SQLite store refuses the file
190
+ with `INVALID_STATE`. An open IndexedDB connection of this release closes
191
+ when another connection opens a newer version. When an open connection of
192
+ an older tab blocks the open, the store logs one warning with the code
193
+ `INDEXEDDB_OPEN_BLOCKED` and the field `version`, and the open completes
194
+ when that connection closes. The key-value store has no guard.
195
+ See step 27.
196
+
197
+ #### Upgrade steps
198
+
199
+ 20. Replace `decryptGroupMessage` with `processIncomingEnvelope`. A cipher
200
+ primitive that returns plaintext has a `decrypt*` name, such as
201
+ `decryptMessage`, `decryptEnvelope` and `decryptFile`. A receive
202
+ workflow that returns an outcome and keeps the content until
203
+ `completeReceive` has a `process*` name, such as
204
+ `processIncomingEnvelope`. Pass the delivered envelope with its Relay
205
+ `id`. An envelope with no `id` takes no receive lock, and a repeat call
206
+ gives the retained content again until `completeReceive`. A refusal now
207
+ gives a `denied` outcome and runs `onDecryptionError` instead of
208
+ throwing. A retryable decrypt failure sends a retry request and throws.
209
+ Receives that 13.x `decryptGroupMessage` left pending complete through
210
+ `completeReceive` once `listPendingReceives` lists them at
211
+ `awaiting-completion`. A `completeReceive` call before that stage
212
+ deletes nothing. A repeated `processIncomingEnvelope` call with the
213
+ same frame does not find them. It fails with `DECRYPTION_FAILED` and
214
+ sends a retry request. So stop any 13.x re-call loop and use
215
+ `listPendingReceives`.
216
+ 21. Expect a denial for all managed group content with no group context. A
217
+ client with a `groups` config gives the reason `legacy-no-context`. An
218
+ earlier check can deny the content first, such as `blocked` for a
219
+ blocked group. A client with no `groups` config refuses such content
220
+ with a `GroupReceiveRefusedError` of reason `configuration`. Before, the
221
+ client decided such content against local group state. Every sender must
222
+ run SDK 12.0.0 or later. A client with a `groups` config whose group
223
+ store has no master key for a managed group now refuses a new send to
224
+ that group, and a manual resend of content with no logged group
225
+ context. It throws `EncryptionError` with the
226
+ code `GROUP_MASTER_KEY_MISSING`, and stores and posts nothing. An
227
+ attachment send also uploads nothing. Store the group master key through
228
+ the link or sync path, then send again. A manual resend of logged content
229
+ that carries a group context keeps that context. A replay that must build
230
+ a sent transcript for an own device skips that transcript, keeps its
231
+ posts, and logs one warning with the code. The output of
232
+ `encryptGroupMessage` carries no group context unless its plaintext holds
233
+ one. A `processIncomingEnvelope` receiver with a `groups` config denies it
234
+ for a managed group as `legacy-no-context`, or as `blocked` when the group
235
+ is blocked. A receiver with no `groups` config refuses it with a
236
+ `GroupReceiveRefusedError` of reason `configuration`. Send managed group
237
+ content with `send`. A caller that delivers the bytes of
238
+ `encryptGroupMessage` itself decrypts them with `decryptEnvelope`.
239
+ 22. Expect each durable store to delete every SDK 11 received-content row
240
+ at the first open on this release. It also deletes every converted
241
+ record that waits for an envelope, and it logs the count once with the
242
+ code `LEGACY_RECEIVED_CONTENT_DELETED`. It also deletes each readable
243
+ SDK 11 row in a store that SDK 12.0.0 or later never opened, and the
244
+ count line carries that number in the separate field `readable`. The
245
+ sweep relies on the Relay retention constraint. The Relay keeps an
246
+ undelivered envelope for at most its retention period, 30 days in
247
+ production. Where the constraint holds, no SDK version shows the content
248
+ of such a row. The constraint does not cover a device that received the
249
+ content on SDK 11 inside the last 30 days. For that device, 13.x would
250
+ convert the row and complete it when the Relay delivers the envelope
251
+ again. This release deletes the row at first open, and the sweep does not
252
+ restore it. Remove all use of `ReceivedContent`,
253
+ `ReceiveWorkRecord.awaitingEnvelope`, `receivedContentKey` and
254
+ `parseReceivedContent`. A custom store must now set `messageId`,
255
+ `senderUserId` and `senderDeviceId` on each `ReceiveWorkRecord`.
256
+ 23. Upgrade every own device of one account in one release. An own device
257
+ on an older SDK version gives the raw group key sync to
258
+ `onMessageDecrypted`. That sync holds the group master key. A custom
259
+ content adapter must implement `serializeGroupKeySync`, or spread the
260
+ result of `createDefaultSignalProtocolContentAdapter()` into itself.
261
+ Handle `'groupKeySync'` when you switch on `ParsedSyncContent.type`. A
262
+ custom local store must keep each metadata value across a close and a
263
+ reopen. The first start on this release sends one `GroupKeySync` for
264
+ each managed group with a verified record and with stored state that
265
+ lists the account as a member, to each other own device.
266
+ 24. Replace `case 'expired-content':` with `case 'request-expired':` in
267
+ `onRetryTerminal`. A retry request whose latest attempt the Relay
268
+ answered or holds ends as `request-expired` at its deadline and resets no
269
+ session. A retry request whose latest attempt the Relay did not accept
270
+ ends as `posting-deadline` at its posting deadline or its deadline. It
271
+ resets the session. Only `posting-deadline` resets. A record that the
272
+ migration moved can carry `event.recovery` with `request-expired` during
273
+ the reader window. Do not confuse `request-expired` with the delivery
274
+ error cause `request-ended`. The reader window lasts until the next major
275
+ SDK version ships, and for at least 60 days after the publish day of
276
+ 14.0.0. In that window, the SDK reads a stored `expired-content` end as
277
+ `request-expired`.
278
+ 25. Expect a unique send timestamp per device. A new send with a timestamp
279
+ that a different send of the device used throws
280
+ `InvalidSendTimestampError` with the reason `already_used`. The field
281
+ `SendResult.clientTimestamp` is now required. Read the timestamp there
282
+ when the SDK picks it. A retry with the same `clientMessageId`, a manual
283
+ resend and a retry answer keep the original timestamp. The fields
284
+ `InvalidSendTimestampError.earliest` and `latest` are absent for
285
+ `already_used`.
286
+ 26. Expect the SDK to drop a later message of the same sender with the same
287
+ timestamp. This applies to any device of the sender. The rule also
288
+ covers sent transcripts from two own devices in two conversations. A
289
+ custom store that checks `ReceiveWorkRecord.received` gets a key with
290
+ `senderUserId` and `timestamp` only. A note to self arrives at each
291
+ other own device as a sent transcript only.
292
+ 27. Do not go back to SDK 13.x after the first open on this release. A 13.x
293
+ reader throws on a record of this release and does not degrade. A 13.x
294
+ web tab fails to open with `VersionError`. A 14.x open waits for each
295
+ open 13.x tab to close. A 13.x SQLite store refuses the file with
296
+ `INVALID_STATE`. The key-value store has no guard, so stop each 13.x
297
+ process on it before the first 14.x open.
298
+
299
+ ### Added
300
+
301
+ - **Own devices get the key of each managed group.** When a client creates a
302
+ managed group, joins one through an invite link, or accepts a member
303
+ invitation, it sends one `GroupKeySync` with the group master key and the
304
+ revision to each other own device. When the client sees an own device for
305
+ the first time, it sends the key of each group to that device only. Each
306
+ start sends the key of each group to each own device that the key sync
307
+ ledger does not mark for the group. So the first start on this release
308
+ sends one `GroupKeySync` for each group and own device, and a start after
309
+ a complete run sends none. The ledger marks the own devices whose copy
310
+ the Relay accepted and the own device that sent this device the key, so
311
+ a refused or failed send is sent again at the next start. A group sends
312
+ no key while its record is unverified, while it has no stored state, or
313
+ while its stored state does not list the account as a member. The
314
+ receiver accepts a `GroupKeySync` only from its own account. For a group
315
+ with no record, it writes the group record with the source `'sync'`
316
+ before the master key, and schedules a fetch of the group. So an own
317
+ device knows the group with no group traffic. A record that exists keeps
318
+ its source. A `GroupKeySync` from an own device clears the unverified
319
+ origin that a group context set, so the group leaves the per-sender
320
+ `unverified-cap`. A record that already has its master key gets no new
321
+ fetch, and a repeated `GroupKeySync` applies once.
322
+ `processIncomingEnvelope`, the Relay subscription and the receive queue
323
+ consume the content, so the application never gets it from them, and
324
+ `processIncomingEnvelope` gives the outcome `null-message`.
325
+ `decryptEnvelope` and the raw decrypt methods `receive`, `decryptMessage`
326
+ and `decryptMessages` return the sync unapplied, master key included. The
327
+ ledger is one metadata value for each group, under the key prefix
328
+ `open-e2ee:group-key-sync:v1:`. The client deletes the value when it
329
+ removes the group record. See step 23.
330
+
331
+ ### Fixed
332
+
333
+ - **A dying page no longer leaves a rotated pin with sessions.** The
334
+ IndexedDB store now writes the new pin last. If a page stops inside an
335
+ identity rotation transaction, a browser can commit only part of it. The
336
+ store then keeps the old pin. Before, the store could keep the new pin
337
+ together with sessions of the old identity. An encrypt on such a session
338
+ then failed the identity trust check, and the send reported
339
+ `EncryptionError` with code `ENCRYPTION_FAILED` for that device.
340
+ - **A dying page no longer leaves a session with unused prekeys.** The
341
+ IndexedDB store now deletes the one-time prekeys, records the Kyber
342
+ prekey use, and deletes the sender-key handoff rows of the device first.
343
+ It writes the pin, then the receive record, and then the session. If a page
344
+ stops inside a session commit, a browser can commit only part of it.
345
+ Before, the store could keep the receive record of a PreKey message
346
+ without its session while the one-time prekeys of that message stayed.
347
+ It could also keep the session while the one-time prekeys stayed or the
348
+ Kyber prekey use was not recorded. It could also keep the session with
349
+ handoff rows of the device, so a group send could skip the sender key
350
+ for that device. Now a commit that stops before the receive record keeps
351
+ no session. If it already deleted a one-time prekey of the message, a
352
+ redelivery of that PreKey message fails with `EncryptionError` with
353
+ code `PREKEY_NOT_FOUND`, and the client sends a retry request to the
354
+ sender. If it recorded only the Kyber prekey use, the next entry
355
+ applies. A commit that stops between the receive
356
+ record and the session keeps the content, and the client gives it to
357
+ the application.
358
+ - **A PreKey message whose Kyber prekey use the store recorded without its
359
+ session now gets a resend.** A session commit that stops after the Kyber
360
+ prekey use and before the session leaves that state. No released write
361
+ order could leave it, and the order above can. Without this change,
362
+ each redelivery of that PreKey message fails at the session commit
363
+ with `ReusedBaseKeyError`, the client does not acknowledge the envelope
364
+ and sends no retry request, and the message never arrives. Now, when no
365
+ session of the sender device holds the base key of the message, the
366
+ failure is a retryable decryption error. The client sends a retry
367
+ request to the sender and acknowledges the envelope. The sender makes a
368
+ new session from a fresh prekey bundle, with a new base key, and resends.
369
+ `processIncomingEnvelope` sends the request and throws `EncryptionError`
370
+ with code `DECRYPTION_FAILED`.
371
+
3
372
  ## 13.5.2
4
373
 
5
374
  ### Fixed
package/README.md CHANGED
@@ -35,7 +35,7 @@ The relay never needs message plaintext or device private keys.
35
35
 
36
36
  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).
37
37
 
38
- Version `13.5.x`. Public APIs and persisted formats follow semantic versioning.
38
+ Version `14.1.x`. Public APIs and persisted formats follow semantic versioning.
39
39
 
40
40
  ## Install
41
41
 
@@ -54,8 +54,8 @@ environment. It writes the connection URL to `.env.local` as
54
54
  the public prefix of the framework, for example `EXPO_PUBLIC_OPEN_E2EE_RELAY_URL`.
55
55
  The URL is public configuration. It is not a credential.
56
56
 
57
- A Sandbox environment uses device-owned identity. `hostedRelaySandboxIdentity`
58
- signs the identity assertion with a key that it keeps in the device-local store.
57
+ A new Sandbox environment defaults to device-owned identity.
58
+ `hostedRelaySandboxIdentity` signs the identity assertion with a key that it keeps in the device-local store.
59
59
  Use the same store for the client.
60
60
 
61
61
  This example needs that Sandbox environment. It is not an offline script.
@@ -76,11 +76,12 @@ const signal = await createHostedSignalProtocolClient({
76
76
  });
77
77
  ```
78
78
 
79
- `hostedRelaySandboxIdentity` works only in a Sandbox environment. In production,
80
- your identity provider signs the assertion: pass a `getIdentityAssertion`
81
- callback that returns a short-lived assertion for the signed-in user. The
82
- [identity guide](https://docs.open-e2ee.dev/relay/identity) describes the
83
- production setup.
79
+ `hostedRelaySandboxIdentity` works only in a Sandbox environment. A production
80
+ project in device-owned mode uses `hostedRelayDeviceOwnedIdentity(storage)`. A
81
+ production project in application-bound mode needs a `getIdentityAssertion`
82
+ callback that returns a short-lived assertion for the signed-in user from your
83
+ backend. The [identity guide](https://docs.open-e2ee.dev/relay/identity)
84
+ describes the production setup.
84
85
 
85
86
  Register a handler before you start incoming delivery. Persist each message
86
87
  before the handler resolves, and use its ID to make repeated writes idempotent.
package/SECURITY.md CHANGED
@@ -7,8 +7,8 @@ backports.
7
7
 
8
8
  | Version | Supported |
9
9
  | -------- | ------------------ |
10
- | 13.5.x | :white_check_mark: |
11
- | < 13.5.0 | :x: |
10
+ | 14.1.x | :white_check_mark: |
11
+ | < 14.1.0 | :x: |
12
12
 
13
13
  ## Reporting a Vulnerability
14
14
 
package/client/README.md CHANGED
@@ -36,9 +36,11 @@ await signal.encryptMessage(bob, 'hello');
36
36
  Run `oe new` in the application directory. It creates the Relay project and
37
37
  its Sandbox environment, and it writes the connection URL to `.env.local`. In
38
38
  a Sandbox environment, `hostedRelaySandboxIdentity(storage)` supplies
39
- `getIdentityAssertion` from a key in the device-local store. In production,
40
- supply `getIdentityAssertion` from your authentication integration. It returns
41
- a short-lived signed assertion for the signed-in user.
39
+ `getIdentityAssertion` from a key in the device-local store. In a production
40
+ project in device-owned mode, `hostedRelayDeviceOwnedIdentity(storage)`
41
+ supplies it from the same kind of key. In a production project in
42
+ application-bound mode, supply `getIdentityAssertion` from your backend. It
43
+ returns a short-lived signed assertion for the signed-in user.
42
44
 
43
45
  The hosted factory registers the device and publishes its public prekeys.
44
46
  The published SDK contains client code and transport contracts. Relay server
package/device/README.md CHANGED
@@ -130,9 +130,10 @@ device's key. Existing custom-adapter refusal and rollback rules still apply.
130
130
 
131
131
  The link copies the master key of each group that the active device's group
132
132
  store lists into the new device's group store. The copy runs in the calling
133
- process, so no master key crosses the Relay. A client with `groups` on the new
134
- device then fetches each copied group. The application calls no group method
135
- for this. The link copies no protocol state, so sessions start fresh.
133
+ process, so the link sends no master key through the Relay. A client with
134
+ `groups` on the new device then fetches each copied group. The application calls
135
+ no group method for this. The link copies no protocol state, so sessions start
136
+ fresh.
136
137
 
137
138
  A group record that a release before 12.0.0 wrote, and that the active device
138
139
  has not read since, is not listed and is not copied. Read each group once on
@@ -106,6 +106,7 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
106
106
  private groupReceiveEvaluator?;
107
107
  /** The single fetcher that brings each group up to its claimed revision. */
108
108
  private groupFetcher?;
109
+ private groupKeySync?;
109
110
  /** The current membership that a retry resend of group content needs. */
110
111
  private readonly groupMembership;
111
112
  /** The processor of the stored receive records. */
@@ -309,7 +310,7 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
309
310
  private waitForStopReceiptSends;
310
311
  /**
311
312
  * The session reset steps of a retry request that ended as
312
- * `expired-content` or `posting-deadline`. Their session hooks run through
313
+ * `posting-deadline`. Their session hooks run through
313
314
  * the given context, and its stop signal stops their lock waits and relay
314
315
  * requests. There are none without a relay.
315
316
  */
@@ -630,10 +631,11 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
630
631
  * - `duplicate`: this client processed the envelope, or the application
631
632
  * already has the content of the failed envelope of a retry request.
632
633
  * The client acknowledged the envelope.
633
- * - `null-message`: the envelope carries no content. The client consumed
634
- * it and acknowledged it. A null message for a failed envelope marks
635
- * that envelope processed, but a content resend for it that comes later
636
- * still gives its content.
634
+ * - `null-message`: the envelope carries no content for the application.
635
+ * It is a null message, or a `GroupKeySync` from an own device that the
636
+ * client consumed. The client acknowledged it. A null message for a
637
+ * failed envelope marks that envelope processed, but a content resend
638
+ * for it that comes later still gives its content.
637
639
  * - `denied`: the client refused the content. The ratchet step is spent,
638
640
  * and the client acknowledged the envelope. Content from another
639
641
  * account that carries a sync message is denied in any envelope.
@@ -751,9 +753,6 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
751
753
  * Receive one envelope that the application passed. The queue skips its
752
754
  * record while the receive runs, and runs a pass after it.
753
755
  *
754
- * @param direct - The group and the receive record ID of a framed group
755
- * message that `decryptGroupMessage` passed. A decrypt failure then
756
- * throws with no retry request and no report.
757
756
  * @returns The outcome, and the error behind a `pending` or `denied`
758
757
  * outcome
759
758
  */
@@ -771,12 +770,6 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
771
770
  private openForCaller;
772
771
  /** The receive commit of an envelope that the application passed. */
773
772
  private callerReceiveCommit;
774
- /**
775
- * Fill the sender fields of a converted legacy record from the envelope
776
- * that the application passed. The record keeps its age and its arrival
777
- * order, and becomes a helper record.
778
- */
779
- private fillAwaitingRecord;
780
773
  /**
781
774
  * Decrypt one opened envelope under the receive admission, and commit its
782
775
  * receive record with the ratchet step.
@@ -787,7 +780,9 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
787
780
  * the outcome is `denied`. A retryable failure (per SESAME spec §4.1)
788
781
  * sends a retry request, which acknowledges the envelope, and throws. A
789
782
  * failure after the decrypt built the record is a store failure: it
790
- * throws with no request, and the ratchet step rolled back.
783
+ * throws with no request, and the ratchet step rolled back. A refused
784
+ * Kyber prekey use with no session for its base key is retryable, as
785
+ * `isPartialCommitKyberPreKeyUse` tells.
791
786
  *
792
787
  * @returns The committed record, or the outcome when nothing committed
793
788
  */
@@ -1385,6 +1380,16 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
1385
1380
  * use this to encrypt messages. All group members can decrypt
1386
1381
  * the same ciphertext, making it efficient for large groups.
1387
1382
  *
1383
+ * This primitive adds no group context and checks no group master key.
1384
+ * Unless the plaintext carries a group context, a
1385
+ * `processIncomingEnvelope` receiver denies the output for a managed
1386
+ * group. A receiver with a `groups` config gives the reason
1387
+ * `legacy-no-context`, or `blocked` when the group is blocked. A receiver
1388
+ * with no `groups` config refuses the output with a
1389
+ * `GroupReceiveRefusedError` of reason `configuration`. Send managed group
1390
+ * content with `send`. A caller that delivers the bytes itself decrypts
1391
+ * them with `decryptEnvelope`, as a `sender_key` envelope.
1392
+ *
1388
1393
  * @param groupId - Group identifier
1389
1394
  * @param plaintext - Message to encrypt
1390
1395
  * @returns Framed SenderKeyMessage bytes
@@ -1401,46 +1406,6 @@ export declare class DefaultSignalProtocolClient implements SignalProtocolClient
1401
1406
  * ```
1402
1407
  */
1403
1408
  encryptGroupMessage(groupId: string, plaintext: string): Promise<Uint8Array>;
1404
- /**
1405
- * Decrypt a group message from a sender
1406
- *
1407
- * Use this to decrypt messages from other group members.
1408
- * You must process the sender's distribution message first.
1409
- *
1410
- * The message passes the group decision of `processIncomingEnvelope`.
1411
- * Content whose group state must update first stays stored, and a later
1412
- * call with the same message decides it with no second decrypt.
1413
- *
1414
- * @deprecated Use `processIncomingEnvelope`, which returns a receive
1415
- * outcome and keeps the content until the application completes the
1416
- * receive. This method completes the receive before it returns, so a
1417
- * plaintext that the application loses is gone.
1418
- *
1419
- * @param groupId - Group identifier
1420
- * @param senderId - Sender's user ID
1421
- * @param senderDeviceId - Sender's device ID
1422
- * @param framedMessage - Framed SenderKeyMessage bytes
1423
- * @returns Decrypted plaintext
1424
- * @throws GroupReceiveUnavailableError when the group state of the content
1425
- * is not current. Its `messageId` names the stored receive. Call again
1426
- * later with the same message.
1427
- * @throws GroupReceiveRefusedError when the client refuses the content
1428
- * @throws EncryptionError MESSAGE_DUPLICATE for a message that this client
1429
- * processed, or that carries no content, and STORAGE_QUOTA_EXCEEDED when
1430
- * the receive queue has no room
1431
- *
1432
- * @example
1433
- * ```typescript
1434
- * const plaintext = await signal.decryptGroupMessage(
1435
- * 'group-123',
1436
- * senderId,
1437
- * senderDeviceId,
1438
- * encryptedMessage
1439
- * );
1440
- * console.log('Message:', plaintext);
1441
- * ```
1442
- */
1443
- decryptGroupMessage(groupId: string, senderId: string, senderDeviceId: number, framedMessage: Uint8Array): Promise<string>;
1444
1409
  /**
1445
1410
  * Rotate sender key for a group (forward secrecy on membership changes).
1446
1411
  *