@open-e2ee/signal-protocol-sdk 12.0.1 → 13.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 (165) hide show
  1. package/ADAPTERS.md +3 -0
  2. package/ARCHITECTURE.md +4 -4
  3. package/CHANGELOG.md +141 -0
  4. package/README.md +1 -1
  5. package/SECURITY.md +2 -2
  6. package/client/README.md +40 -0
  7. package/device/README.md +40 -4
  8. package/dist/client/client.d.ts +8 -0
  9. package/dist/client/client.d.ts.map +1 -1
  10. package/dist/client/client.js +19 -1
  11. package/dist/client/client.js.map +1 -1
  12. package/dist/client/config.d.ts +6 -2
  13. package/dist/client/config.d.ts.map +1 -1
  14. package/dist/client/config.js.map +1 -1
  15. package/dist/client/event-hooks.d.ts +28 -0
  16. package/dist/client/event-hooks.d.ts.map +1 -1
  17. package/dist/client/event-hooks.js +1 -0
  18. package/dist/client/event-hooks.js.map +1 -1
  19. package/dist/client/group-init-status.d.ts +21 -0
  20. package/dist/client/group-init-status.d.ts.map +1 -0
  21. package/dist/client/group-init-status.js +156 -0
  22. package/dist/client/group-init-status.js.map +1 -0
  23. package/dist/client/hosted-device-link-transport.d.ts +11 -0
  24. package/dist/client/hosted-device-link-transport.d.ts.map +1 -0
  25. package/dist/client/hosted-device-link-transport.js +25 -0
  26. package/dist/client/hosted-device-link-transport.js.map +1 -0
  27. package/dist/client/hosted-device-link.d.ts +97 -0
  28. package/dist/client/hosted-device-link.d.ts.map +1 -0
  29. package/dist/client/hosted-device-link.js +149 -0
  30. package/dist/client/hosted-device-link.js.map +1 -0
  31. package/dist/client/hosted-http-error.d.ts +30 -0
  32. package/dist/client/hosted-http-error.d.ts.map +1 -0
  33. package/dist/client/hosted-http-error.js +34 -0
  34. package/dist/client/hosted-http-error.js.map +1 -0
  35. package/dist/client/hosted-presence.js +1 -1
  36. package/dist/client/hosted-presence.js.map +1 -1
  37. package/dist/client/hosted-profile-keys.js +1 -1
  38. package/dist/client/hosted-profile-keys.js.map +1 -1
  39. package/dist/client/hosted-sandbox-identity.d.ts +3 -3
  40. package/dist/client/hosted-sandbox-identity.js +3 -3
  41. package/dist/client/hosted-transport.d.ts +12 -13
  42. package/dist/client/hosted-transport.d.ts.map +1 -1
  43. package/dist/client/hosted-transport.js +111 -17
  44. package/dist/client/hosted-transport.js.map +1 -1
  45. package/dist/client/hosted.d.ts +57 -8
  46. package/dist/client/hosted.d.ts.map +1 -1
  47. package/dist/client/hosted.js +170 -19
  48. package/dist/client/hosted.js.map +1 -1
  49. package/dist/client/index.d.ts +2 -1
  50. package/dist/client/index.d.ts.map +1 -1
  51. package/dist/client/index.js +1 -1
  52. package/dist/client/index.js.map +1 -1
  53. package/dist/client/receive-queue.d.ts +4 -2
  54. package/dist/client/receive-queue.d.ts.map +1 -1
  55. package/dist/client/receive-queue.js +26 -22
  56. package/dist/client/receive-queue.js.map +1 -1
  57. package/dist/index.d.ts +2 -1
  58. package/dist/index.d.ts.map +1 -1
  59. package/dist/index.js +1 -1
  60. package/dist/index.js.map +1 -1
  61. package/dist/local/store/conformance/cases/ciphertext.d.ts +7 -0
  62. package/dist/local/store/conformance/cases/ciphertext.d.ts.map +1 -0
  63. package/dist/local/store/conformance/cases/ciphertext.js +55 -0
  64. package/dist/local/store/conformance/cases/ciphertext.js.map +1 -0
  65. package/dist/local/store/conformance/cases/durability.d.ts +6 -0
  66. package/dist/local/store/conformance/cases/durability.d.ts.map +1 -0
  67. package/dist/local/store/conformance/cases/durability.js +34 -0
  68. package/dist/local/store/conformance/cases/durability.js.map +1 -0
  69. package/dist/local/store/conformance/cases/identity.d.ts +7 -0
  70. package/dist/local/store/conformance/cases/identity.d.ts.map +1 -0
  71. package/dist/local/store/conformance/cases/identity.js +84 -0
  72. package/dist/local/store/conformance/cases/identity.js.map +1 -0
  73. package/dist/local/store/conformance/cases/metadata.d.ts +7 -0
  74. package/dist/local/store/conformance/cases/metadata.d.ts.map +1 -0
  75. package/dist/local/store/conformance/cases/metadata.js +48 -0
  76. package/dist/local/store/conformance/cases/metadata.js.map +1 -0
  77. package/dist/local/store/conformance/cases/protection.d.ts +7 -0
  78. package/dist/local/store/conformance/cases/protection.d.ts.map +1 -0
  79. package/dist/local/store/conformance/cases/protection.js +14 -0
  80. package/dist/local/store/conformance/cases/protection.js.map +1 -0
  81. package/dist/local/store/conformance/cases/receive-work.d.ts +8 -0
  82. package/dist/local/store/conformance/cases/receive-work.d.ts.map +1 -0
  83. package/dist/local/store/conformance/cases/receive-work.js +152 -0
  84. package/dist/local/store/conformance/cases/receive-work.js.map +1 -0
  85. package/dist/local/store/conformance/cases/sender-key.d.ts +7 -0
  86. package/dist/local/store/conformance/cases/sender-key.d.ts.map +1 -0
  87. package/dist/local/store/conformance/cases/sender-key.js +59 -0
  88. package/dist/local/store/conformance/cases/sender-key.js.map +1 -0
  89. package/dist/local/store/conformance/cases/session-trust.d.ts +7 -0
  90. package/dist/local/store/conformance/cases/session-trust.d.ts.map +1 -0
  91. package/dist/local/store/conformance/cases/session-trust.js +64 -0
  92. package/dist/local/store/conformance/cases/session-trust.js.map +1 -0
  93. package/dist/local/store/conformance/checks.d.ts +15 -0
  94. package/dist/local/store/conformance/checks.d.ts.map +1 -0
  95. package/dist/local/store/conformance/checks.js +67 -0
  96. package/dist/local/store/conformance/checks.js.map +1 -0
  97. package/dist/local/store/conformance/index.d.ts +30 -0
  98. package/dist/local/store/conformance/index.d.ts.map +1 -0
  99. package/dist/local/store/conformance/index.js +29 -0
  100. package/dist/local/store/conformance/index.js.map +1 -0
  101. package/dist/local/store/conformance/records.d.ts +36 -0
  102. package/dist/local/store/conformance/records.d.ts.map +1 -0
  103. package/dist/local/store/conformance/records.js +109 -0
  104. package/dist/local/store/conformance/records.js.map +1 -0
  105. package/dist/local/store/conformance/run.d.ts +24 -0
  106. package/dist/local/store/conformance/run.d.ts.map +1 -0
  107. package/dist/local/store/conformance/run.js +156 -0
  108. package/dist/local/store/conformance/run.js.map +1 -0
  109. package/dist/local/store/conformance/types.d.ts +55 -0
  110. package/dist/local/store/conformance/types.d.ts.map +1 -0
  111. package/dist/local/store/conformance/types.js +6 -0
  112. package/dist/local/store/conformance/types.js.map +1 -0
  113. package/dist/local/store/expo/adapter.d.ts +2 -1
  114. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  115. package/dist/local/store/expo/adapter.js.map +1 -1
  116. package/dist/local/store/node/adapter.d.ts +2 -2
  117. package/dist/local/store/react-native/adapter.d.ts +2 -1
  118. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  119. package/dist/local/store/react-native/adapter.js.map +1 -1
  120. package/dist/local/store/sqlite/convert-plaintext.d.ts +62 -0
  121. package/dist/local/store/sqlite/convert-plaintext.d.ts.map +1 -0
  122. package/dist/local/store/sqlite/convert-plaintext.js +236 -0
  123. package/dist/local/store/sqlite/convert-plaintext.js.map +1 -0
  124. package/dist/local/store/sqlite/encryption.d.ts +21 -0
  125. package/dist/local/store/sqlite/encryption.d.ts.map +1 -1
  126. package/dist/local/store/sqlite/encryption.js.map +1 -1
  127. package/dist/local/store/sqlite/errors.d.ts.map +1 -1
  128. package/dist/local/store/sqlite/errors.js +2 -1
  129. package/dist/local/store/sqlite/errors.js.map +1 -1
  130. package/dist/local/store/sqlite/key-storage/identity-keys.d.ts +3 -1
  131. package/dist/local/store/sqlite/key-storage/identity-keys.d.ts.map +1 -1
  132. package/dist/local/store/sqlite/key-storage/identity-keys.js +3 -1
  133. package/dist/local/store/sqlite/key-storage/identity-keys.js.map +1 -1
  134. package/dist/local/store/sqlite/open-store.d.ts +36 -4
  135. package/dist/local/store/sqlite/open-store.d.ts.map +1 -1
  136. package/dist/local/store/sqlite/open-store.js +326 -21
  137. package/dist/local/store/sqlite/open-store.js.map +1 -1
  138. package/dist/local/store/sqlite/web/worker.d.ts +5 -0
  139. package/dist/local/store/sqlite/web/worker.d.ts.map +1 -1
  140. package/dist/local/store/sqlite/web/worker.js +99 -20
  141. package/dist/local/store/sqlite/web/worker.js.map +1 -1
  142. package/dist/local/store/web-sqlite/adapter.d.ts +3 -2
  143. package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
  144. package/dist/local/store/web-sqlite/adapter.js +12 -2
  145. package/dist/local/store/web-sqlite/adapter.js.map +1 -1
  146. package/dist/remote/relay/types.d.ts +4 -2
  147. package/dist/remote/relay/types.d.ts.map +1 -1
  148. package/dist/types/api.d.ts +20 -4
  149. package/dist/types/api.d.ts.map +1 -1
  150. package/docs/ASSURANCE.md +25 -7
  151. package/docs/DEVIATIONS.md +35 -3
  152. package/docs/ERROR_HANDLING.md +8 -6
  153. package/docs/GETTING_STARTED.md +25 -8
  154. package/docs/INTERFACES.md +3 -1
  155. package/docs/PACKAGE_SURFACE.md +1 -0
  156. package/docs/RECIPES.md +44 -0
  157. package/docs/SECURITY.md +23 -5
  158. package/keys/README.md +3 -1
  159. package/local/store/README.md +92 -12
  160. package/local/store/expo/README.md +63 -6
  161. package/local/store/key-value/README.md +3 -2
  162. package/local/store/node/README.md +68 -6
  163. package/local/store/react-native/README.md +62 -4
  164. package/local/store/web-sqlite/README.md +101 -4
  165. package/package.json +5 -1
@@ -321,18 +321,20 @@ these errors occur.
321
321
 
322
322
  ## Relay Device Errors
323
323
 
324
- The Relay can refuse this device. Two errors name that refusal. Neither is an
325
- `EncryptionError`, and the SDK retries neither one.
324
+ The Relay can refuse this device, and a managed device link can refuse its
325
+ linked store. Three errors name these refusals. None is an `EncryptionError`,
326
+ and the SDK retries none of them.
326
327
 
327
328
  | Error | Cause | Application response |
328
329
  |---|---|---|
329
330
  | [`HostedRelayDeviceRevokedError`](./api/classes/HostedRelayDeviceRevokedError.md) | An account recovery revoked this device. `code` is `DEVICE_REVOKED`, `status` is 403, and `retryable` is false. | Sign the user out of this device. The Relay refuses a registration with the revoked key, so a re-registration fails too. |
330
331
  | [`HostedRelayDeviceUnknownError`](./api/classes/HostedRelayDeviceUnknownError.md) | The Relay has no device for the stored session. `code` is `NOT_FOUND`, `status` is 404, and `retryable` is false. The message is the Relay's own message. | Ask the user to confirm a re-registration of this device. Do not re-register without that confirmation. |
332
+ | [`HostedRelayDeviceLinkError`](./api/classes/HostedRelayDeviceLinkError.md) | `linkHostedRelayDevice` found state in the linked store that the link did not write: a group in the linked group store, or a device-authentication key for this Relay connection with no registration of this link. `code` is `DEVICE_LINK_STORE_NOT_EMPTY`, and `retryable` is false. The link wrote nothing. | Link the device again with a new, empty store. The same store is refused again. |
331
333
 
332
- `createHostedSignalProtocolClient` throws either error when the stored session
333
- cannot get a device token. It does not register a new device in their place. A
334
- running client throws them from its Relay calls. A client call can wrap them
335
- in an `EncryptionError`, as the `originalError`. The mailbox subscription
334
+ `createHostedSignalProtocolClient` throws the first two errors when the stored
335
+ session cannot get a device token. It does not register a new device in their
336
+ place. A running client throws them from its Relay calls. A client call can
337
+ wrap them in an `EncryptionError`, as the `originalError`. The mailbox subscription
336
338
  stops with the reason `device-revoked` or `device-unknown`. See
337
339
  [`RelayConnectionReason`](./api/type-aliases/RelayConnectionReason.md).
338
340
 
@@ -33,10 +33,18 @@ with a key that it keeps in the device-local store, so the device gets the same
33
33
  account each time it registers. A device that loses its store loses that
34
34
  Sandbox account. The helper works only in a Sandbox environment.
35
35
 
36
- In production, the callback belongs to your authentication integration. It
37
- returns a short-lived assertion for the signed-in user from your identity
38
- provider. The SDK does not supply an identity provider or a relay server
39
- implementation.
36
+ Production supports application-bound and explicitly configured device-owned
37
+ accounts. For application-bound accounts, `getIdentityAssertion` returns a
38
+ short-lived Relay-specific assertion from your backend after it verifies the
39
+ server session and current application membership.
40
+ Device-owned accounts prove possession of a persistent account key. They do
41
+ not bind to an application login, and provider sign-in cannot recover a lost
42
+ account key. The SDK does not supply an identity provider or a relay server
43
+ implementation. See [identity and authentication](https://docs.open-e2ee.dev/relay/identity)
44
+ for Production configuration.
45
+
46
+ For a tested backend path, see the [Better Auth recipe](https://docs.open-e2ee.dev/relay/better-auth)
47
+ and the [application callback recipe](./RECIPES.md#application-bound-identity-callback).
40
48
 
41
49
  ## Setup Sequence
42
50
 
@@ -52,9 +60,18 @@ The hosted factory authenticates and registers the current device, then publishe
52
60
  its public prekeys. A linked device gets the account identity by device
53
61
  transfer or by a channel that the application owns, then joins the account
54
62
  with `linkHostedRelayDevice()`. That call runs in one process that holds the
55
- active device's store and the new device's store. See the
56
- [device guide](../device/README.md). The default policy requires post-quantum
57
- session establishment and Braid ratcheting.
63
+ active device's store and the new device's store. It copies each group master
64
+ key from the active device and gives the new device its own registration ID.
65
+ It refuses a new device's store that already lists a group, with
66
+ `HostedRelayDeviceLinkError`. See the [device guide](../device/README.md). The
67
+ default policy requires post-quantum session establishment and Braid
68
+ ratcheting.
69
+
70
+ Omit `hosted.adapter` when linking through the OpenE2EE Signal Protocol Relay.
71
+ The SDK uses the active device's stored session and persists the linked session
72
+ before synchronization. It does not register another account or request another
73
+ provider assertion. An explicit adapter keeps application-owned composition.
74
+ Retry with the same stores to retain the original operation and prekeys.
58
75
 
59
76
  ## Expo Client
60
77
 
@@ -71,7 +88,7 @@ const signal = await createHostedSignalProtocolClient({
71
88
  adapters: { storage },
72
89
  hosted: {
73
90
  relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
74
- // Sandbox only. In production, use your identity provider's callback.
91
+ // Sandbox only. Select the Production identity mode explicitly.
75
92
  getIdentityAssertion: hostedRelaySandboxIdentity(storage),
76
93
  },
77
94
  });
@@ -106,7 +106,9 @@ The application backend must:
106
106
  - allocate linked-device identifiers
107
107
  - apply retention and abuse controls
108
108
  - give an envelope one `id`, and keep that `id` on every redelivery of the
109
- envelope, because the client delivers content at most once by that `id`
109
+ envelope. The client delivers each message to the application hook at least
110
+ once, with that `id` as its `messageId`, and the application deduplicates on
111
+ that `id`
110
112
 
111
113
  A client-supplied user identifier is a routing input, not proof of identity.
112
114
 
@@ -106,6 +106,7 @@ implementations are outside the published SDK.
106
106
  - `@open-e2ee/signal-protocol-sdk/local/store/expo`
107
107
  - `@open-e2ee/signal-protocol-sdk/local/store/key-value`
108
108
  - `@open-e2ee/signal-protocol-sdk/local/store/key-value/realm`
109
+ - `@open-e2ee/signal-protocol-sdk/local/store/conformance`
109
110
  - `@open-e2ee/signal-protocol-sdk/local/store/memory`
110
111
  - `@open-e2ee/signal-protocol-sdk/local/store/node`
111
112
  - `@open-e2ee/signal-protocol-sdk/local/store/react-native`
package/docs/RECIPES.md CHANGED
@@ -15,6 +15,50 @@ and device-local storage. Use a Sandbox environment for development, where
15
15
  `hostedRelaySandboxIdentity(storage)` supplies the callback. The
16
16
  [getting-started guide](./GETTING_STARTED.md) describes these inputs.
17
17
 
18
+ ## Application-bound identity callback
19
+
20
+ Your backend verifies the current application session and member eligibility.
21
+ It signs the Relay-specific ES256 assertion. The browser callback only requests
22
+ that assertion. Keep provider credentials and signing keys on the backend.
23
+
24
+ <!-- doc-snippet:skip requires-external-context -->
25
+ ```ts
26
+ import type { GetIdentityAssertion } from "@open-e2ee/signal-protocol-sdk";
27
+
28
+ const getIdentityAssertion: GetIdentityAssertion = async (request) => {
29
+ const response = await fetch("https://application.example/api/relay-identity", {
30
+ method: "POST",
31
+ credentials: "include",
32
+ headers: { "content-type": "application/json" },
33
+ body: JSON.stringify(request),
34
+ cache: "no-store",
35
+ });
36
+ if (!response.ok) throw new Error("Application authentication is required.");
37
+ const result: unknown = await response.json();
38
+ if (!result || typeof result !== "object" || !("assertion" in result) ||
39
+ typeof result.assertion !== "string") {
40
+ throw new Error("Identity assertion missing.");
41
+ }
42
+ return result.assertion;
43
+ };
44
+
45
+ void getIdentityAssertion;
46
+ ```
47
+
48
+ Replace the example application origin with your authenticated backend.
49
+ Configure its CSRF controls and cookie policy. Do not send a member ID or
50
+ provider token from this callback as proof of membership.
51
+
52
+ The [Better Auth recipe](https://docs.open-e2ee.dev/relay/better-auth) uses a
53
+ real server session with the cookie cache disabled. The
54
+ [backend contract](https://docs.open-e2ee.dev/relay/backend-identity) lists
55
+ other provider paths and their evidence levels. Those paths issue custom-token
56
+ assertions. They are not native provider adapters in this package.
57
+
58
+ Application logout and assertion refusal do not revoke existing device proofs.
59
+ The customer suspension/resume recipe awaits the supported backend and CLI
60
+ surface. Anonymous capabilities retain their separate limits.
61
+
18
62
  ## Production composition with Expo on the Signal Protocol Relay
19
63
 
20
64
  <!-- doc-snippet:skip requires-external-context -->
package/docs/SECURITY.md CHANGED
@@ -28,6 +28,9 @@ compatibility boundary.
28
28
  - The SDK selects SESAME's per-user identity-key model and provisions that tuple
29
29
  unchanged across linked devices. Registration IDs, prekeys, and sessions are
30
30
  device-specific. Generic SESAME still supports both identity-key models.
31
+ - A managed device link gives the linked device a fresh registration ID that
32
+ differs from the active device's ID, and a fresh ID for a held PNI record.
33
+ A device that a 12.0.x release linked keeps the ID that it has.
31
34
  - Trust storage persists the tuple and trust metadata. The SDK derives
32
35
  commitments locally, and a redundant supplied commitment must match before
33
36
  mutation.
@@ -204,6 +207,11 @@ writes over it. Flash storage, backups, and the browser storage can also
204
207
  keep earlier copies. A reader who has an earlier copy and its key can read
205
208
  content that the store deleted. The SDK does not promise erasure.
206
209
 
210
+ A conversion with `convertPlaintext` does not erase the plaintext either.
211
+ After it, the old plaintext file can stay in free disk blocks, backups, and
212
+ file system snapshots. A reader of such a copy needs no key. The SDK cannot
213
+ erase these copies.
214
+
207
215
  The store also keeps receive records: the plaintext of each envelope that
208
216
  the client decrypted on the Relay subscription path, in
209
217
  `receiveIncomingEnvelopes`, or in `processIncomingEnvelope`. A record is
@@ -236,11 +244,21 @@ table shows how the built-in configurations combine them:
236
244
  | Custom store | As declared | As declared | From the declaration | As declared | The SDK cannot check the stored bytes |
237
245
 
238
246
  The client checks only the shape of a `protection` declaration. It cannot
239
- check that the bytes on disk are encrypted or where the key is. A custom store
240
- must commit the ratchet state and the receive record in one transaction. It
241
- must declare `protection` truthfully, and keep the key outside the data store
242
- when it declares `protected`. Do not restore a store from a backup while the
243
- client runs. An earlier ratchet state makes later messages fail to decrypt.
247
+ check that the bytes on disk are encrypted or where the key is. The client does
248
+ not check the class of a store, and managed groups work on a custom store. The
249
+ application that supplies a custom store is responsible for these properties:
250
+
251
+ - `commitSessionTrust` writes the ratchet state and the receive record in one
252
+ transaction. `storeSenderKeyRecord` writes the sender key record and its
253
+ receive effects in one transaction. A failed commit rolls back every write
254
+ in it.
255
+ - The store declares `protection` truthfully. When it declares `protected`,
256
+ the key is outside the data store.
257
+ - The application does not restore a store from a backup while the client
258
+ runs. An earlier ratchet state makes later messages fail to decrypt.
259
+ - The store passes the local store conformance kit from
260
+ `@open-e2ee/signal-protocol-sdk/local/store/conformance`. Give the kit the
261
+ `armWriteFailure` hook, so that the rollback of each atomic commit runs.
244
262
 
245
263
  Group sender key state never leaves the device. A sender key record holds the
246
264
  chain key that every message key on that chain derives from, and the sender's
package/keys/README.md CHANGED
@@ -47,7 +47,9 @@ interface CompositeIdentityV1 {
47
47
 
48
48
  The SDK provisions one tuple per `(userId, identityType)` across linked devices.
49
49
  ACI and PNI are independent identity types. Device registration IDs, prekeys,
50
- and sessions remain device-specific.
50
+ and sessions remain device-specific. A managed device link keeps the tuple and
51
+ writes a fresh registration ID for each identity type that the linked store
52
+ holds.
51
53
 
52
54
  The tuple encodes to exactly 67 bytes:
53
55
 
@@ -184,18 +184,27 @@ environment an adapter must honor its promises in, not the subject of a test.
184
184
  application-supplied `storage` backend. Instead it ships the contract
185
185
  suite the application runs against its own backend. The kit exports
186
186
  `runBackendConformance` and `assertBackendConformance`, which execute
187
- thirteen cases against any `KeyValueStorage`:
188
-
189
- - round-trips
190
- - key listing
191
- - batch removal
192
- - in-order atomic application
193
- - checks evaluated against pre-batch state
194
- - null-guarded creation
195
- - all-or-nothing failure
196
- - exact-userId session removal with in-batch visibility
197
- - one winner between concurrent guarded batches
198
- - durability across reopen
187
+ sixteen cases against any `KeyValueStorage`:
188
+
189
+ - `getItem` returns null for a missing key
190
+ - `setItem` stores, overwrites, and round-trips values
191
+ - `removeItem` deletes a key and tolerates a missing key
192
+ - `getAllKeys` lists exactly the stored keys
193
+ - `removeMany` removes the listed keys and tolerates missing ones
194
+ - `pruneSkippedSenderKeys` uses numeric indexes, exact prefixes, and
195
+ earlier writes in its batch
196
+ - `atomicWrite` applies operations in order
197
+ - `atomicWrite` evaluates checks against the state before the batch
198
+ - `atomicWrite` guards a creation with an `expectedValue` of null
199
+ - a failed check applies none of the batch
200
+ - `removeSessionsForUser` removes only exact userId matches under the
201
+ prefix
202
+ - `removeSessionsForUser` sees earlier writes in its batch
203
+ - `removeSenderKeyHandoffs` removes only keys whose segments match
204
+ under the prefix
205
+ - `removeSenderKeyHandoffs` sees earlier writes in its batch
206
+ - concurrent guarded batches have exactly one winner
207
+ - committed writes survive a reopen
199
208
 
200
209
  A jest gate proves the kit catches a non-atomic backend, a
201
210
  prefix-matching session removal, and an unserialized backend, on every
@@ -247,6 +256,77 @@ The [Expo guide](./expo/README.md) covers the native build and the database key.
247
256
  The [React Native SQLite guide](./react-native/README.md) covers the same for
248
257
  bare React Native.
249
258
 
259
+ ## Conformance kit for a custom store
260
+
261
+ - `runLocalStoreConformance` and `assertLocalStoreConformance` from `@open-e2ee/signal-protocol-sdk/local/store/conformance`
262
+
263
+ An application that implements `SignalProtocolLocalStore` itself runs this
264
+ kit against its store. The kit has no framework or platform dependencies. It
265
+ runs unchanged under jest, Node, a browser, or Hermes, and it loads no
266
+ optional peer. The kit gets a fresh, empty store from `createStore` for each
267
+ case. The other options are hooks for the cases that need them:
268
+
269
+ - `reopen` closes the store and opens the same data again. The two reopen
270
+ cases skip without it.
271
+ - `armWriteFailure` makes the next atomic commit fail after its first write.
272
+ Each atomic commit that the kit arms holds a receive record, so a failure
273
+ on that write works when the store writes it after another record. The
274
+ two rollback cases skip without it.
275
+ - `readRawBytes` returns the bytes that the store keeps. The ciphertext case
276
+ skips without it.
277
+ - `closeStore` releases a store after its case.
278
+
279
+ The kit has these cases:
280
+
281
+ - identity overwrite: a key pair and its registration ID for `'aci'` and
282
+ `'pni'`, and an overwrite of each with a new registration ID. The write of
283
+ one type does not change the other type.
284
+ - identity overwrite after reopen
285
+ - session trust commit: a commit of a session, its contact identity, and its
286
+ receive record, and a refused commit that writes nothing
287
+ - session trust commit rollback
288
+ - sender key receive commit: a sender key record with its receive record,
289
+ the consumed skipped key, and skipped key eviction
290
+ - sender key receive commit rollback
291
+ - metadata compare-and-set: a match, a mismatch, an absent value, and one
292
+ winner among concurrent calls
293
+ - receive record insert and compare-and-set
294
+ - receive record listing: arrival order, then work ID order, an exclusive
295
+ `after` cursor, the default page size, and the filters
296
+ - receive record completion and usage
297
+ - durability after reopen: each kind of write survives a reopen
298
+ - no plaintext at rest: the stored bytes hold no known plaintext. It runs
299
+ only when the store declares a cipher.
300
+ - protection declaration: `store.protection` is a valid declaration
301
+
302
+ `runLocalStoreConformance` reports each case as passed, skipped, or failed,
303
+ and it does not throw. A skipped case is a name with no reason. The result
304
+ also carries the `protection` declaration of the store, or null when the
305
+ declaration case fails. `assertLocalStoreConformance` throws with every
306
+ problem listed. A failed case is a problem. A skipped rollback case is also a
307
+ problem, because a store must prove that its atomic commits roll back. Use
308
+ the assert form in the automated checks of the application.
309
+
310
+ <!-- doc-snippet:skip requires-external-context -->
311
+ ```ts
312
+ import { assertLocalStoreConformance } from '@open-e2ee/signal-protocol-sdk/local/store/conformance';
313
+
314
+ await assertLocalStoreConformance({
315
+ createStore: () => openMyStore({ name: freshName() }),
316
+ reopen: (store) => reopenMyStore(store),
317
+ armWriteFailure: (store) => failNextReceiveRecordWrite(store),
318
+ readRawBytes: (store) => readMyStoreFiles(store),
319
+ closeStore: (store) => closeMyStore(store),
320
+ });
321
+ ```
322
+
323
+ The kit does not cover `SenderKeyHandoffStore`, `MessageRecordStore`, or
324
+ `SendLogStore`. A store that implements those interfaces needs its own
325
+ checks for them. On every change to the source repository, each shipped
326
+ store runs the kit under jest. The key-value store and the React Native
327
+ SQLite store also run it under Hermes. The web stores also run it in a real
328
+ browser.
329
+
250
330
  ## Storage Responsibilities
251
331
 
252
332
  An `SignalProtocolLocalStore` implementation must preserve:
@@ -43,15 +43,18 @@ before it returns the store. A file that a newer SDK wrote does not open
43
43
  Options:
44
44
 
45
45
  - `name`: the database file name in the `expo-sqlite` default directory.
46
- Letters, digits, `.`, `_`, and `-` only. Default:
47
- `open-e2ee-signal-protocol.db`.
46
+ Letters, digits, `.`, `_`, and `-` only, and no `.oe2e-convert` ending.
47
+ Default: `open-e2ee-signal-protocol.db`.
48
48
  - `vault`: the `SignalProtocolLocalSecretVault` that holds the database key.
49
49
  Default: `ExpoSecureStoreSignalProtocolSecretVault`.
50
50
  - `encryptionAtRest`: pass `false` to store the database without encryption.
51
51
  The store then does not use the vault, and it logs a warning at each open. A
52
- database created with one setting does not open with the other. Default:
53
- `true`, and the open fails when the build has no SQLCipher (see
54
- [Web](#web)).
52
+ database created with one setting does not open with the other, except
53
+ through `convertPlaintext`. Default: `true`, and the open fails when the
54
+ build has no SQLCipher (see [Web](#web)).
55
+ - `convertPlaintext`: pass `true` to convert a plaintext database to an
56
+ encrypted one at an encrypted open. See
57
+ [Convert a plaintext store](#convert-a-plaintext-store). Default: `false`.
55
58
  - `logger`: receives the warning of each open without encryption.
56
59
 
57
60
  A store holds its name until `close()`. In one process, the opens and resets
@@ -69,6 +72,7 @@ web implementation. On the web, `expoStore()` and `resetExpoStore()` therefore
69
72
  fail with `SqliteEncryptionUnavailableError` (`KEY_STORAGE_ERROR`). They fail
70
73
  before they use the vault or a database file, also when the app passes its own
71
74
  vault. A native build without the `useSQLCipher` option fails in the same way.
75
+ An open with `convertPlaintext: true` also fails in this way, before any write.
72
76
 
73
77
  For an encrypted store in a browser, use
74
78
  [`./local/store/web-sqlite`](../web-sqlite/README.md). `encryptionAtRest: false`
@@ -83,7 +87,9 @@ the old file. Restore the vault entry, or call `resetExpoStore()`.
83
87
 
84
88
  A file created with `encryptionAtRest: false` fails an open without that
85
89
  option with `SqliteKeyMismatchError` (`KEY_STORAGE_ERROR`), not
86
- `LOCAL_STORE_KEY_LOST`. Open it with the setting that created it.
90
+ `LOCAL_STORE_KEY_LOST`. Open it with the setting that created it, or convert
91
+ it to keep its data in an encrypted store (see
92
+ [Convert a plaintext store](#convert-a-plaintext-store)).
87
93
 
88
94
  `resetExpoStore()` deletes the database file, then writes a new key, then
89
95
  returns the open, empty store. It takes the same options as `expoStore`. Close
@@ -92,6 +98,57 @@ the open store of the name first.
92
98
  `clearAllKeys()` on an open store empties every SDK table and keeps the file
93
99
  and its key. `resetExpoStore()` is the full teardown.
94
100
 
101
+ ## Convert a plaintext store
102
+
103
+ An encrypted open with `convertPlaintext: true` converts a database that was
104
+ created with `encryptionAtRest: false`:
105
+
106
+ <!-- doc-snippet:skip requires-external-context -->
107
+
108
+ ```ts
109
+ import { expoStore } from '@open-e2ee/signal-protocol-sdk/local/store/expo';
110
+
111
+ const store = await expoStore({ convertPlaintext: true });
112
+ ```
113
+
114
+ The store keeps every row and its schema version, then applies the
115
+ migrations of this SDK. The option does nothing on an encrypted database or
116
+ when no file exists. With `encryptionAtRest: false`, the option fails with
117
+ `INVALID_STATE`.
118
+
119
+ The conversion writes a new key to a pending vault slot. It copies the
120
+ database to the encrypted temporary file `<name>.oe2e-convert` in one
121
+ transaction. Then it deletes the plaintext file and copies the temporary file
122
+ back. The delete of the plaintext file is the commit point. The conversion
123
+ needs free disk space for one more copy of the database. It runs inside the
124
+ open, one at a time with the other opens and resets of the name.
125
+
126
+ The conversion refuses, with `INVALID_STATE`, a database that holds an
127
+ application table, a BLOB value, or an integer outside the safe JavaScript
128
+ range. It also refuses a file with no SDK schema. A file from a newer SDK
129
+ fails as at any open. A refusal changes nothing.
130
+
131
+ A crash or an error before the copy commits leaves the plaintext file. The
132
+ next open with the option starts again with a new key. A crash after the
133
+ commit point leaves the encrypted copy. The next encrypted open finishes the
134
+ conversion, with or without the option. While the temporary file exists,
135
+ an open or a reset with `encryptionAtRest: false` fails with `INVALID_STATE`.
136
+
137
+ The open fails with `INVALID_STATE` and names both files when the plaintext
138
+ file and a complete encrypted copy both exist. A crash between the end of the
139
+ copy and the commit point leaves this state. So does an older SDK that opens
140
+ the store after the commit point. Delete the plaintext file and its `-wal`,
141
+ `-shm`, and `-journal` files, then open again. The open then finishes the
142
+ conversion from the copy. An
143
+ encrypted reset also ends any conversion, and it deletes all data.
144
+
145
+ Residual risks:
146
+
147
+ - The disk blocks of the old plaintext file can keep plaintext until the file
148
+ system reuses them. So can device backups. The SDK cannot erase them.
149
+ - An SDK older than this release does not know the temporary file. If it
150
+ opens the store after the commit point, it creates a new empty store.
151
+
95
152
  ## Data protection
96
153
 
97
154
  Every table in this store holds material that must not leave the device.
@@ -144,8 +144,9 @@ list, or open a separate Realm file for the store.
144
144
 
145
145
  The adapter is tested with the conformance kit on realm 20.2.0 in Node,
146
146
  including a reopen of the same Realm file. Manual checks ran the kit in
147
- React Native apps in the iOS 26.2 simulator and in an Android emulator. All
148
- 13 cases passed in each. The SDK does not test the adapter
147
+ React Native apps in the iOS 26.2 simulator and in an Android emulator. Those
148
+ manual runs used an earlier version of the kit with thirteen cases, and all
149
+ thirteen passed in each. The SDK does not test the adapter
149
150
  on a physical device. Run the conformance kit on your target devices with
150
151
  your Realm build before you ship.
151
152
 
@@ -50,13 +50,16 @@ Options:
50
50
  safeStorage vault, or `app-vault`. A vault that declares no custody counts
51
51
  as `same-origin`, and the level is then `co-located`.
52
52
  - `name`: the database file name in `directory`. Letters, digits, `.`, `_`,
53
- and `-` only, and no `.lock`, `-wal`, `-shm`, or `-journal` ending.
54
- Default: `open-e2ee-signal-protocol.db`.
53
+ and `-` only, and no `.lock`, `-wal`, `-shm`, `-journal`, or
54
+ `.oe2e-convert` ending. Default: `open-e2ee-signal-protocol.db`.
55
55
  - `encryptionAtRest`: pass `false` to store the database without encryption.
56
56
  The store then does not use the vault, and it logs a warning at each open. A
57
- database created with one setting does not open with the other. The store
58
- reports `none` protection, so the client keeps no resendable content.
59
- Default: `true`.
57
+ database created with one setting does not open with the other, except
58
+ through `convertPlaintext`. The store reports `none` protection, so the
59
+ client keeps no resendable content. Default: `true`.
60
+ - `convertPlaintext`: pass `true` to convert a plaintext database to an
61
+ encrypted one at an encrypted open. See
62
+ [Convert a plaintext store](#convert-a-plaintext-store). Default: `false`.
60
63
  - `logger`: receives the warning of each open without encryption.
61
64
 
62
65
  Keep application tables in a separate database file. The SDK database holds
@@ -195,9 +198,13 @@ if (key) {
195
198
  }
196
199
  ```
197
200
 
201
+ Finish a conversion before a move. The recipe moves only the main key, so a
202
+ conversion that a move interrupts cannot finish.
203
+
198
204
  A file created with `encryptionAtRest: false` fails an open without that
199
205
  option with `SqliteKeyMismatchError` (`KEY_STORAGE_ERROR`), not
200
- `LOCAL_STORE_KEY_LOST`. Open it with the setting that created it.
206
+ `LOCAL_STORE_KEY_LOST`. Open it with the setting that created it, or convert
207
+ it to keep its data in an encrypted store.
201
208
 
202
209
  `resetNodeStore()` deletes the database file, then writes a new key, then
203
210
  returns the open, empty store. It takes the same options as `nodeStore`. Close
@@ -206,6 +213,61 @@ the open store of the file first.
206
213
  `clearAllKeys()` on an open store empties every SDK table and keeps the file
207
214
  and its key. `resetNodeStore()` is the full teardown.
208
215
 
216
+ ## Convert a plaintext store
217
+
218
+ An encrypted open with `convertPlaintext: true` converts a database that was
219
+ created with `encryptionAtRest: false`:
220
+
221
+ <!-- doc-snippet:skip requires-external-context -->
222
+
223
+ ```ts
224
+ import { nodeStore } from '@open-e2ee/signal-protocol-sdk/local/store/node';
225
+
226
+ const store = await nodeStore({ directory, vault, convertPlaintext: true });
227
+ ```
228
+
229
+ The store keeps every row and its schema version, then applies the
230
+ migrations of this SDK. The option does nothing on an encrypted database or
231
+ when no file exists. With `encryptionAtRest: false`, the option fails with
232
+ `INVALID_STATE`.
233
+
234
+ The conversion writes a new key to a pending vault slot. It copies the
235
+ database to the encrypted temporary file `<name>.oe2e-convert` in one
236
+ transaction. Then it deletes the plaintext file and copies the temporary file
237
+ back. The delete of the plaintext file is the commit point. The conversion
238
+ needs free disk space for one more copy of the database. It runs inside the
239
+ owner lock.
240
+
241
+ The conversion refuses, with `INVALID_STATE`, a database that holds an
242
+ application table, a BLOB value, or an integer outside the safe JavaScript
243
+ range. It also refuses a file with no SDK schema. A file from a newer SDK
244
+ fails as at any open. A refusal changes nothing.
245
+
246
+ A crash or an error before the copy commits leaves the plaintext file. The
247
+ next open with the option starts again with a new key. A crash after the
248
+ commit point leaves the encrypted copy. The next encrypted open finishes the
249
+ conversion, with or without the option. While the temporary file exists,
250
+ an open or a reset with `encryptionAtRest: false` fails with `INVALID_STATE`.
251
+
252
+ The open fails with `INVALID_STATE` and names both files when the plaintext
253
+ file and a complete encrypted copy both exist. A crash between the end of the
254
+ copy and the commit point leaves this state. So does an older SDK that opens
255
+ the store after the commit point. Delete the plaintext file and its `-wal`,
256
+ `-shm`, and `-journal` files, then open again. The open then finishes the
257
+ conversion from the copy. An
258
+ encrypted reset also ends any conversion, and it deletes all data.
259
+
260
+ Residual risks:
261
+
262
+ - The disk blocks of the old plaintext file can keep plaintext until the file
263
+ system reuses them. So can backups and file system snapshots. The SDK cannot
264
+ erase them.
265
+ - A directory move during a conversion is not supported. The open then fails
266
+ with `INVALID_STATE`, because the temporary file has no key at the new path.
267
+ Move the directory back and open it there.
268
+ - An SDK older than this release does not know the temporary file. If it
269
+ opens the store after the commit point, it creates a new empty store.
270
+
209
271
  ## Data protection
210
272
 
211
273
  Every table in this store holds material that must not leave the device.
@@ -70,14 +70,19 @@ Options:
70
70
 
71
71
  - `name`: the database file name in the op-sqlite default location (the
72
72
  Library directory on iOS, the databases directory on Android). Letters,
73
- digits, `.`, `_`, and `-` only. Default: `open-e2ee-signal-protocol.db`.
73
+ digits, `.`, `_`, and `-` only, and no `.oe2e-convert` ending. Default:
74
+ `open-e2ee-signal-protocol.db`.
74
75
  - `vault`: the `SignalProtocolLocalSecretVault` that holds the database key.
75
76
  Default: `ReactNativeKeychainSignalProtocolSecretVault`, which keeps the key
76
77
  on this device only (see the [vault guide](../../vault/README.md)).
77
78
  - `encryptionAtRest`: pass `false` to store the database without encryption.
78
79
  The store then does not use the vault, and it logs a warning at each open. A
79
- database created with one setting does not open with the other. Default:
80
- `true`, and the open fails when op-sqlite is not built with SQLCipher.
80
+ database created with one setting does not open with the other, except
81
+ through `convertPlaintext`. Default: `true`, and the open fails when
82
+ op-sqlite is not built with SQLCipher.
83
+ - `convertPlaintext`: pass `true` to convert a plaintext database to an
84
+ encrypted one at an encrypted open. See
85
+ [Convert a plaintext store](#convert-a-plaintext-store). Default: `false`.
81
86
  - `logger`: receives the warning of each open without encryption.
82
87
 
83
88
  A store holds its name until `close()`. In one process, the opens and resets
@@ -97,7 +102,9 @@ A new key cannot read the old file. Restore the vault entry, or call
97
102
 
98
103
  A file created with `encryptionAtRest: false` fails an open without that
99
104
  option with `SqliteKeyMismatchError` (`KEY_STORAGE_ERROR`), not
100
- `LOCAL_STORE_KEY_LOST`. Open it with the setting that created it.
105
+ `LOCAL_STORE_KEY_LOST`. Open it with the setting that created it, or convert
106
+ it to keep its data in an encrypted store (see
107
+ [Convert a plaintext store](#convert-a-plaintext-store)).
101
108
 
102
109
  `resetReactNativeStore()` deletes the database file, then writes a new
103
110
  key, then returns the open, empty store. It takes the same options as
@@ -106,6 +113,57 @@ key, then returns the open, empty store. It takes the same options as
106
113
  `clearAllKeys()` on an open store empties every SDK table and keeps the file
107
114
  and its key. `resetReactNativeStore()` is the full teardown.
108
115
 
116
+ ## Convert a plaintext store
117
+
118
+ An encrypted open with `convertPlaintext: true` converts a database that was
119
+ created with `encryptionAtRest: false`:
120
+
121
+ <!-- doc-snippet:skip requires-external-context -->
122
+
123
+ ```ts
124
+ import { reactNativeStore } from '@open-e2ee/signal-protocol-sdk/local/store/react-native';
125
+
126
+ const store = await reactNativeStore({ convertPlaintext: true });
127
+ ```
128
+
129
+ The store keeps every row and its schema version, then applies the
130
+ migrations of this SDK. The option does nothing on an encrypted database or
131
+ when no file exists. With `encryptionAtRest: false`, the option fails with
132
+ `INVALID_STATE`.
133
+
134
+ The conversion writes a new key to a pending vault slot. It copies the
135
+ database to the encrypted temporary file `<name>.oe2e-convert` in one
136
+ transaction. Then it deletes the plaintext file and copies the temporary file
137
+ back. The delete of the plaintext file is the commit point. The conversion
138
+ needs free disk space for one more copy of the database. It runs inside the
139
+ open, one at a time with the other opens and resets of the name.
140
+
141
+ The conversion refuses, with `INVALID_STATE`, a database that holds an
142
+ application table, a BLOB value, or an integer outside the safe JavaScript
143
+ range. It also refuses a file with no SDK schema. A file from a newer SDK
144
+ fails as at any open. A refusal changes nothing.
145
+
146
+ A crash or an error before the copy commits leaves the plaintext file. The
147
+ next open with the option starts again with a new key. A crash after the
148
+ commit point leaves the encrypted copy. The next encrypted open finishes the
149
+ conversion, with or without the option. While the temporary file exists,
150
+ an open or a reset with `encryptionAtRest: false` fails with `INVALID_STATE`.
151
+
152
+ The open fails with `INVALID_STATE` and names both files when the plaintext
153
+ file and a complete encrypted copy both exist. A crash between the end of the
154
+ copy and the commit point leaves this state. So does an older SDK that opens
155
+ the store after the commit point. Delete the plaintext file and its `-wal`,
156
+ `-shm`, and `-journal` files, then open again. The open then finishes the
157
+ conversion from the copy. An
158
+ encrypted reset also ends any conversion, and it deletes all data.
159
+
160
+ Residual risks:
161
+
162
+ - The disk blocks of the old plaintext file can keep plaintext until the file
163
+ system reuses them. So can device backups. The SDK cannot erase them.
164
+ - An SDK older than this release does not know the temporary file. If it
165
+ opens the store after the commit point, it creates a new empty store.
166
+
109
167
  ## Data protection
110
168
 
111
169
  Every table in this store holds material that must not leave the device.