@open-e2ee/signal-protocol-sdk 12.0.1 → 13.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ADAPTERS.md +3 -0
- package/ARCHITECTURE.md +4 -4
- package/CHANGELOG.md +132 -0
- package/README.md +1 -1
- package/SECURITY.md +2 -2
- package/client/README.md +40 -0
- package/device/README.md +29 -3
- package/dist/client/client.d.ts +8 -0
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +19 -1
- package/dist/client/client.js.map +1 -1
- package/dist/client/event-hooks.d.ts +28 -0
- package/dist/client/event-hooks.d.ts.map +1 -1
- package/dist/client/event-hooks.js +1 -0
- package/dist/client/event-hooks.js.map +1 -1
- package/dist/client/group-init-status.d.ts +21 -0
- package/dist/client/group-init-status.d.ts.map +1 -0
- package/dist/client/group-init-status.js +156 -0
- package/dist/client/group-init-status.js.map +1 -0
- package/dist/client/hosted-device-link.d.ts +97 -0
- package/dist/client/hosted-device-link.d.ts.map +1 -0
- package/dist/client/hosted-device-link.js +149 -0
- package/dist/client/hosted-device-link.js.map +1 -0
- package/dist/client/hosted-http-error.d.ts +30 -0
- package/dist/client/hosted-http-error.d.ts.map +1 -0
- package/dist/client/hosted-http-error.js +34 -0
- package/dist/client/hosted-http-error.js.map +1 -0
- package/dist/client/hosted-presence.js +1 -1
- package/dist/client/hosted-presence.js.map +1 -1
- package/dist/client/hosted-profile-keys.js +1 -1
- package/dist/client/hosted-profile-keys.js.map +1 -1
- package/dist/client/hosted-sandbox-identity.d.ts +3 -3
- package/dist/client/hosted-sandbox-identity.js +3 -3
- package/dist/client/hosted-transport.d.ts +0 -11
- package/dist/client/hosted-transport.d.ts.map +1 -1
- package/dist/client/hosted-transport.js +1 -15
- package/dist/client/hosted-transport.js.map +1 -1
- package/dist/client/hosted.d.ts +53 -7
- package/dist/client/hosted.d.ts.map +1 -1
- package/dist/client/hosted.js +158 -17
- package/dist/client/hosted.js.map +1 -1
- package/dist/client/index.d.ts +2 -1
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +1 -1
- package/dist/client/index.js.map +1 -1
- package/dist/client/receive-queue.d.ts +4 -2
- package/dist/client/receive-queue.d.ts.map +1 -1
- package/dist/client/receive-queue.js +26 -22
- package/dist/client/receive-queue.js.map +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/local/store/conformance/cases/ciphertext.d.ts +7 -0
- package/dist/local/store/conformance/cases/ciphertext.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/ciphertext.js +55 -0
- package/dist/local/store/conformance/cases/ciphertext.js.map +1 -0
- package/dist/local/store/conformance/cases/durability.d.ts +6 -0
- package/dist/local/store/conformance/cases/durability.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/durability.js +34 -0
- package/dist/local/store/conformance/cases/durability.js.map +1 -0
- package/dist/local/store/conformance/cases/identity.d.ts +7 -0
- package/dist/local/store/conformance/cases/identity.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/identity.js +84 -0
- package/dist/local/store/conformance/cases/identity.js.map +1 -0
- package/dist/local/store/conformance/cases/metadata.d.ts +7 -0
- package/dist/local/store/conformance/cases/metadata.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/metadata.js +48 -0
- package/dist/local/store/conformance/cases/metadata.js.map +1 -0
- package/dist/local/store/conformance/cases/protection.d.ts +7 -0
- package/dist/local/store/conformance/cases/protection.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/protection.js +14 -0
- package/dist/local/store/conformance/cases/protection.js.map +1 -0
- package/dist/local/store/conformance/cases/receive-work.d.ts +8 -0
- package/dist/local/store/conformance/cases/receive-work.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/receive-work.js +152 -0
- package/dist/local/store/conformance/cases/receive-work.js.map +1 -0
- package/dist/local/store/conformance/cases/sender-key.d.ts +7 -0
- package/dist/local/store/conformance/cases/sender-key.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/sender-key.js +59 -0
- package/dist/local/store/conformance/cases/sender-key.js.map +1 -0
- package/dist/local/store/conformance/cases/session-trust.d.ts +7 -0
- package/dist/local/store/conformance/cases/session-trust.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/session-trust.js +64 -0
- package/dist/local/store/conformance/cases/session-trust.js.map +1 -0
- package/dist/local/store/conformance/checks.d.ts +15 -0
- package/dist/local/store/conformance/checks.d.ts.map +1 -0
- package/dist/local/store/conformance/checks.js +67 -0
- package/dist/local/store/conformance/checks.js.map +1 -0
- package/dist/local/store/conformance/index.d.ts +30 -0
- package/dist/local/store/conformance/index.d.ts.map +1 -0
- package/dist/local/store/conformance/index.js +29 -0
- package/dist/local/store/conformance/index.js.map +1 -0
- package/dist/local/store/conformance/records.d.ts +36 -0
- package/dist/local/store/conformance/records.d.ts.map +1 -0
- package/dist/local/store/conformance/records.js +109 -0
- package/dist/local/store/conformance/records.js.map +1 -0
- package/dist/local/store/conformance/run.d.ts +24 -0
- package/dist/local/store/conformance/run.d.ts.map +1 -0
- package/dist/local/store/conformance/run.js +156 -0
- package/dist/local/store/conformance/run.js.map +1 -0
- package/dist/local/store/conformance/types.d.ts +55 -0
- package/dist/local/store/conformance/types.d.ts.map +1 -0
- package/dist/local/store/conformance/types.js +6 -0
- package/dist/local/store/conformance/types.js.map +1 -0
- package/dist/local/store/expo/adapter.d.ts +2 -1
- package/dist/local/store/expo/adapter.d.ts.map +1 -1
- package/dist/local/store/expo/adapter.js.map +1 -1
- package/dist/local/store/node/adapter.d.ts +2 -2
- package/dist/local/store/react-native/adapter.d.ts +2 -1
- package/dist/local/store/react-native/adapter.d.ts.map +1 -1
- package/dist/local/store/react-native/adapter.js.map +1 -1
- package/dist/local/store/sqlite/convert-plaintext.d.ts +62 -0
- package/dist/local/store/sqlite/convert-plaintext.d.ts.map +1 -0
- package/dist/local/store/sqlite/convert-plaintext.js +236 -0
- package/dist/local/store/sqlite/convert-plaintext.js.map +1 -0
- package/dist/local/store/sqlite/encryption.d.ts +21 -0
- package/dist/local/store/sqlite/encryption.d.ts.map +1 -1
- package/dist/local/store/sqlite/encryption.js.map +1 -1
- package/dist/local/store/sqlite/errors.d.ts.map +1 -1
- package/dist/local/store/sqlite/errors.js +2 -1
- package/dist/local/store/sqlite/errors.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/identity-keys.d.ts +3 -1
- package/dist/local/store/sqlite/key-storage/identity-keys.d.ts.map +1 -1
- package/dist/local/store/sqlite/key-storage/identity-keys.js +3 -1
- package/dist/local/store/sqlite/key-storage/identity-keys.js.map +1 -1
- package/dist/local/store/sqlite/open-store.d.ts +36 -4
- package/dist/local/store/sqlite/open-store.d.ts.map +1 -1
- package/dist/local/store/sqlite/open-store.js +326 -21
- package/dist/local/store/sqlite/open-store.js.map +1 -1
- package/dist/local/store/sqlite/web/worker.d.ts +5 -0
- package/dist/local/store/sqlite/web/worker.d.ts.map +1 -1
- package/dist/local/store/sqlite/web/worker.js +99 -20
- package/dist/local/store/sqlite/web/worker.js.map +1 -1
- package/dist/local/store/web-sqlite/adapter.d.ts +3 -2
- package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
- package/dist/local/store/web-sqlite/adapter.js +12 -2
- package/dist/local/store/web-sqlite/adapter.js.map +1 -1
- package/dist/remote/relay/types.d.ts +4 -2
- package/dist/remote/relay/types.d.ts.map +1 -1
- package/dist/types/api.d.ts +20 -4
- package/dist/types/api.d.ts.map +1 -1
- package/docs/ASSURANCE.md +25 -7
- package/docs/DEVIATIONS.md +35 -3
- package/docs/ERROR_HANDLING.md +8 -6
- package/docs/GETTING_STARTED.md +15 -8
- package/docs/INTERFACES.md +3 -1
- package/docs/PACKAGE_SURFACE.md +1 -0
- package/docs/SECURITY.md +23 -5
- package/keys/README.md +3 -1
- package/local/store/README.md +92 -12
- package/local/store/expo/README.md +63 -6
- package/local/store/key-value/README.md +3 -2
- package/local/store/node/README.md +68 -6
- package/local/store/react-native/README.md +62 -4
- package/local/store/web-sqlite/README.md +73 -4
- package/package.json +5 -1
package/docs/ERROR_HANDLING.md
CHANGED
|
@@ -321,18 +321,20 @@ these errors occur.
|
|
|
321
321
|
|
|
322
322
|
## Relay Device Errors
|
|
323
323
|
|
|
324
|
-
The Relay can refuse this device
|
|
325
|
-
|
|
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
|
|
333
|
-
cannot get a device token. It does not register a new device in their
|
|
334
|
-
running client throws them from its Relay calls. A client call can
|
|
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
|
|
package/docs/GETTING_STARTED.md
CHANGED
|
@@ -33,10 +33,14 @@ 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
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
36
|
+
Production supports application-bound and explicitly configured device-owned
|
|
37
|
+
accounts. For application-bound accounts, `getIdentityAssertion` returns a
|
|
38
|
+
short-lived assertion for the signed-in user from your identity provider.
|
|
39
|
+
Device-owned accounts prove possession of a persistent account key. They do
|
|
40
|
+
not bind to an application login, and provider sign-in cannot recover a lost
|
|
41
|
+
account key. The SDK does not supply an identity provider or a relay server
|
|
42
|
+
implementation. See [identity and authentication](https://docs.open-e2ee.dev/relay/identity)
|
|
43
|
+
for Production configuration.
|
|
40
44
|
|
|
41
45
|
## Setup Sequence
|
|
42
46
|
|
|
@@ -52,9 +56,12 @@ The hosted factory authenticates and registers the current device, then publishe
|
|
|
52
56
|
its public prekeys. A linked device gets the account identity by device
|
|
53
57
|
transfer or by a channel that the application owns, then joins the account
|
|
54
58
|
with `linkHostedRelayDevice()`. That call runs in one process that holds the
|
|
55
|
-
active device's store and the new device's store.
|
|
56
|
-
|
|
57
|
-
|
|
59
|
+
active device's store and the new device's store. It copies each group master
|
|
60
|
+
key from the active device and gives the new device its own registration ID.
|
|
61
|
+
It refuses a new device's store that already lists a group, with
|
|
62
|
+
`HostedRelayDeviceLinkError`. See the [device guide](../device/README.md). The
|
|
63
|
+
default policy requires post-quantum session establishment and Braid
|
|
64
|
+
ratcheting.
|
|
58
65
|
|
|
59
66
|
## Expo Client
|
|
60
67
|
|
|
@@ -71,7 +78,7 @@ const signal = await createHostedSignalProtocolClient({
|
|
|
71
78
|
adapters: { storage },
|
|
72
79
|
hosted: {
|
|
73
80
|
relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
|
|
74
|
-
// Sandbox only.
|
|
81
|
+
// Sandbox only. Select the Production identity mode explicitly.
|
|
75
82
|
getIdentityAssertion: hostedRelaySandboxIdentity(storage),
|
|
76
83
|
},
|
|
77
84
|
});
|
package/docs/INTERFACES.md
CHANGED
|
@@ -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
|
|
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
|
|
package/docs/PACKAGE_SURFACE.md
CHANGED
|
@@ -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/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.
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
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
|
|
package/local/store/README.md
CHANGED
|
@@ -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
|
-
|
|
188
|
-
|
|
189
|
-
-
|
|
190
|
-
-
|
|
191
|
-
-
|
|
192
|
-
-
|
|
193
|
-
-
|
|
194
|
-
-
|
|
195
|
-
|
|
196
|
-
-
|
|
197
|
-
-
|
|
198
|
-
-
|
|
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.
|
|
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
|
|
53
|
-
`true`, and the open fails when the
|
|
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.
|
|
148
|
-
|
|
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`,
|
|
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
|
|
58
|
-
reports `none` protection, so the
|
|
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:
|
|
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
|
|
80
|
-
`true`, and the open fails when
|
|
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.
|