@open-e2ee/signal-protocol-sdk 12.0.0 → 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 +165 -0
- package/README.md +1 -1
- package/SECURITY.md +2 -2
- package/TROUBLESHOOTING.md +7 -7
- 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 +26 -3
- package/dist/client/client.js.map +1 -1
- package/dist/client/config.d.ts +19 -12
- package/dist/client/config.d.ts.map +1 -1
- package/dist/client/config.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/internal/manager/manager.d.ts +6 -1
- package/dist/internal/manager/manager.d.ts.map +1 -1
- package/dist/internal/manager/manager.js +8 -2
- package/dist/internal/manager/manager.js.map +1 -1
- package/dist/internal/session/cipher.d.ts +2 -2
- package/dist/internal/session/cipher.js +1 -1
- package/dist/internal/session/types.d.ts +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/driver.d.ts +9 -0
- package/dist/local/store/sqlite/driver.d.ts.map +1 -1
- 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/sqlite3mc/sqlite3.mjs +2 -1
- package/dist/local/store/sqlite/web/worker.d.ts +13 -0
- package/dist/local/store/sqlite/web/worker.d.ts.map +1 -1
- package/dist/local/store/sqlite/web/worker.js +163 -22
- 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
|
@@ -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.
|
|
@@ -40,14 +40,18 @@ open (`INVALID_STATE`).
|
|
|
40
40
|
Options:
|
|
41
41
|
|
|
42
42
|
- `name`: the database name in OPFS. A letter or digit, then up to 63
|
|
43
|
-
letters, digits, `.`, `_`, and
|
|
44
|
-
|
|
43
|
+
letters, digits, `.`, `_`, and `-`, and no `.oe2e-convert` ending. It also
|
|
44
|
+
names the vault slot of the key. A conversion with `convertPlaintext` needs
|
|
45
|
+
a name of at most 51 characters. Default: `open-e2ee-signal-protocol.db`.
|
|
45
46
|
- `vault`: the `SignalProtocolLocalSecretVault` that holds the database key.
|
|
46
47
|
Default: the SDK's IndexedDB vault in the same origin.
|
|
47
48
|
- `encryptionAtRest`: pass `false` to store the database without encryption.
|
|
48
49
|
The store then does not use the vault, and it logs a warning at each open. A
|
|
49
|
-
database created with one setting does not open with the other
|
|
50
|
-
`true`.
|
|
50
|
+
database created with one setting does not open with the other, except
|
|
51
|
+
through `convertPlaintext`. Default: `true`.
|
|
52
|
+
- `convertPlaintext`: pass `true` to convert a plaintext database to an
|
|
53
|
+
encrypted one at an encrypted open. See
|
|
54
|
+
[Convert a plaintext store](#convert-a-plaintext-store). Default: `false`.
|
|
51
55
|
- `logger`: receives the warning of each open without encryption.
|
|
52
56
|
- `workerUrl` and `wasmUrl`: see [Content Security Policy](#content-security-policy).
|
|
53
57
|
|
|
@@ -64,6 +68,69 @@ key cannot read the old file. Restore the vault entry, or call
|
|
|
64
68
|
`resetWebSqliteStore()`. The reset deletes the file, creates a new key, and
|
|
65
69
|
returns the open, empty store.
|
|
66
70
|
|
|
71
|
+
## Convert a plaintext store
|
|
72
|
+
|
|
73
|
+
An encrypted open with `convertPlaintext: true` converts a database that was
|
|
74
|
+
created with `encryptionAtRest: false`:
|
|
75
|
+
|
|
76
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
import { webSqliteStore } from '@open-e2ee/signal-protocol-sdk/local/store/web-sqlite';
|
|
80
|
+
|
|
81
|
+
const store = await webSqliteStore({ convertPlaintext: true });
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The store keeps every row and its schema version, then applies the
|
|
85
|
+
migrations of this SDK. The option does nothing on an encrypted database or
|
|
86
|
+
when no database exists. With `encryptionAtRest: false`, the option fails with
|
|
87
|
+
`INVALID_STATE`.
|
|
88
|
+
|
|
89
|
+
A database created with `encryptionAtRest: false` fails an open without the
|
|
90
|
+
option with `SqliteKeyMismatchError` (`KEY_STORAGE_ERROR`). Open it with the
|
|
91
|
+
setting that created it, or convert it to keep its data in an encrypted store.
|
|
92
|
+
|
|
93
|
+
The conversion writes a new key to a pending vault slot. It copies the
|
|
94
|
+
database to the encrypted temporary database `<name>.oe2e-convert` in one
|
|
95
|
+
transaction. Then it deletes the plaintext database and copies the temporary
|
|
96
|
+
database back. The delete of the plaintext database is the commit point. The
|
|
97
|
+
conversion needs storage quota for one more copy of the database.
|
|
98
|
+
|
|
99
|
+
Each database file has its own OPFS directory, `.open-e2ee-sqlite-<name>`.
|
|
100
|
+
When the store removes a database file, it also removes that directory if no
|
|
101
|
+
other file of the store is in it. This applies to the conversion and to a
|
|
102
|
+
reset. So a finished conversion leaves no directory for
|
|
103
|
+
`<name>.oe2e-convert`. If the browser does not remove the directory, the
|
|
104
|
+
directory stays, and the next use of the name uses it again. A check for a
|
|
105
|
+
database that does not exist leaves no directory.
|
|
106
|
+
|
|
107
|
+
The conversion needs the store of the name in no other tab or worker of the
|
|
108
|
+
origin. While another context has it open, the conversion fails at once with
|
|
109
|
+
`INVALID_STATE` and changes nothing. A name longer than 51 characters also
|
|
110
|
+
fails with `INVALID_STATE` before any write.
|
|
111
|
+
|
|
112
|
+
The conversion refuses, with `INVALID_STATE`, a database that holds an
|
|
113
|
+
application table, a BLOB value, or an integer outside the safe JavaScript
|
|
114
|
+
range. It also refuses a database with no SDK schema. A database from a newer
|
|
115
|
+
SDK fails as at any open. A refusal changes nothing.
|
|
116
|
+
|
|
117
|
+
A crash or an error before the copy commits leaves the plaintext database.
|
|
118
|
+
The next open with the option starts again with a new key. A crash after the
|
|
119
|
+
commit point leaves the encrypted copy. The next encrypted open finishes the
|
|
120
|
+
conversion, with or without the option. While the temporary database exists,
|
|
121
|
+
an open or a reset with `encryptionAtRest: false` fails with `INVALID_STATE`.
|
|
122
|
+
|
|
123
|
+
The open fails with `INVALID_STATE` and names both databases when the
|
|
124
|
+
plaintext database and a complete encrypted copy both exist. A crash between
|
|
125
|
+
the end of the copy and the commit point leaves this state. So does an older
|
|
126
|
+
SDK that opens the store after the commit point. The store has no call that
|
|
127
|
+
deletes one database of the pair. An encrypted reset ends the state, and it
|
|
128
|
+
deletes all data.
|
|
129
|
+
|
|
130
|
+
Residual risk: an SDK older than this release does not know the temporary
|
|
131
|
+
database. If it opens the store after the commit point, it creates a new
|
|
132
|
+
empty store.
|
|
133
|
+
|
|
67
134
|
## Tabs
|
|
68
135
|
|
|
69
136
|
Each tab opens its own store, and the tabs of an origin share the database.
|
|
@@ -83,6 +150,8 @@ transaction. Each tab reads the writes of the other tabs.
|
|
|
83
150
|
- `OPFS_FILE_BUSY` means that another tab or worker of the origin still holds
|
|
84
151
|
the files, for example a tab that is closing. The file is unchanged. Retry
|
|
85
152
|
the open later.
|
|
153
|
+
The store already retries a transient failure of the origin private file
|
|
154
|
+
system a few times before it rejects with this code.
|
|
86
155
|
|
|
87
156
|
## Full storage
|
|
88
157
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@open-e2ee/signal-protocol-sdk",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "13.0.0",
|
|
4
4
|
"description": "Pure TypeScript Signal Protocol SDK for encrypted chat in Expo, React Native, browsers, and Node. Post-quantum by default.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"open-e2ee",
|
|
@@ -191,6 +191,10 @@
|
|
|
191
191
|
"types": "./dist/local/store/key-value/realm/index.d.ts",
|
|
192
192
|
"default": "./dist/local/store/key-value/realm/index.js"
|
|
193
193
|
},
|
|
194
|
+
"./local/store/conformance": {
|
|
195
|
+
"types": "./dist/local/store/conformance/index.d.ts",
|
|
196
|
+
"default": "./dist/local/store/conformance/index.js"
|
|
197
|
+
},
|
|
194
198
|
"./local/store/memory": {
|
|
195
199
|
"types": "./dist/local/store/memory/index.d.ts",
|
|
196
200
|
"default": "./dist/local/store/memory/index.js"
|