@open-e2ee/signal-protocol-sdk 8.0.0 → 8.2.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 +2 -2
- package/CHANGELOG.md +188 -0
- package/README.md +4 -4
- package/SECURITY.md +2 -2
- package/device/README.md +16 -7
- package/dist/client/client.d.ts +4 -2
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +25 -19
- package/dist/client/client.js.map +1 -1
- package/dist/client/group-outbox.d.ts +31 -1
- package/dist/client/group-outbox.d.ts.map +1 -1
- package/dist/client/group-outbox.js +67 -58
- package/dist/client/group-outbox.js.map +1 -1
- package/dist/client/hosted-anonymous-delivery.d.ts +9 -1
- package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
- package/dist/client/hosted-anonymous-delivery.js +61 -22
- package/dist/client/hosted-anonymous-delivery.js.map +1 -1
- package/dist/client/hosted-transport.d.ts +16 -0
- package/dist/client/hosted-transport.d.ts.map +1 -1
- package/dist/client/hosted-transport.js +93 -19
- package/dist/client/hosted-transport.js.map +1 -1
- package/dist/client/key-rotation.d.ts.map +1 -1
- package/dist/client/key-rotation.js +2 -4
- package/dist/client/key-rotation.js.map +1 -1
- package/dist/client/prekeys.d.ts.map +1 -1
- package/dist/client/prekeys.js +1 -1
- package/dist/client/prekeys.js.map +1 -1
- package/dist/client/relay-device-refusal.d.ts +32 -0
- package/dist/client/relay-device-refusal.d.ts.map +1 -0
- package/dist/client/relay-device-refusal.js +36 -0
- package/dist/client/relay-device-refusal.js.map +1 -0
- package/dist/client/relay-work.d.ts +26 -0
- package/dist/client/relay-work.d.ts.map +1 -1
- package/dist/client/relay-work.js +37 -0
- package/dist/client/relay-work.js.map +1 -1
- package/dist/client/sealed-sender.d.ts.map +1 -1
- package/dist/client/sealed-sender.js +12 -17
- package/dist/client/sealed-sender.js.map +1 -1
- package/dist/client/sessions.d.ts.map +1 -1
- package/dist/client/sessions.js +2 -4
- package/dist/client/sessions.js.map +1 -1
- package/dist/client/signal-service-cipher.d.ts +90 -4
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +425 -136
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/client/types.d.ts +7 -0
- package/dist/client/types.d.ts.map +1 -1
- package/dist/client/types.js.map +1 -1
- package/dist/internal/manager/manager.d.ts +8 -7
- package/dist/internal/manager/manager.d.ts.map +1 -1
- package/dist/internal/manager/manager.js +34 -36
- package/dist/internal/manager/manager.js.map +1 -1
- package/dist/internal/protocol/spqr/index.d.ts +1 -1
- package/dist/internal/protocol/spqr/index.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/index.js +2 -2
- package/dist/internal/protocol/spqr/index.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js +1 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js.map +1 -1
- package/dist/internal/protocol/spqr/serialize.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/serialize.js +1 -4
- package/dist/internal/protocol/spqr/serialize.js.map +1 -1
- package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/spqr.js +1 -2
- package/dist/internal/protocol/spqr/spqr.js.map +1 -1
- package/dist/internal/protocol/zk/credentials/attributes.d.ts.map +1 -1
- package/dist/internal/protocol/zk/credentials/attributes.js +2 -1
- package/dist/internal/protocol/zk/credentials/attributes.js.map +1 -1
- package/dist/internal/protocol/zk/credentials/credentials.d.ts.map +1 -1
- package/dist/internal/protocol/zk/credentials/credentials.js +8 -6
- package/dist/internal/protocol/zk/credentials/credentials.js.map +1 -1
- package/dist/internal/protocol/zk/credentials/presentation.d.ts.map +1 -1
- package/dist/internal/protocol/zk/credentials/presentation.js +19 -13
- package/dist/internal/protocol/zk/credentials/presentation.js.map +1 -1
- package/dist/internal/protocol/zk/groups/lizard.d.ts +8 -0
- package/dist/internal/protocol/zk/groups/lizard.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/lizard.js +18 -5
- package/dist/internal/protocol/zk/groups/lizard.js.map +1 -1
- package/dist/internal/protocol/zk/groups/profile-key-commitment.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/profile-key-commitment.js +7 -6
- package/dist/internal/protocol/zk/groups/profile-key-commitment.js.map +1 -1
- package/dist/internal/protocol/zk/groups/profile-key-encryption.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/profile-key-encryption.js +3 -2
- package/dist/internal/protocol/zk/groups/profile-key-encryption.js.map +1 -1
- package/dist/internal/protocol/zk/groups/uid-encryption.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/uid-encryption.js +3 -2
- package/dist/internal/protocol/zk/groups/uid-encryption.js.map +1 -1
- package/dist/internal/protocol/zk/proofs/point-multiplication.d.ts +53 -0
- package/dist/internal/protocol/zk/proofs/point-multiplication.d.ts.map +1 -0
- package/dist/internal/protocol/zk/proofs/point-multiplication.js +164 -0
- package/dist/internal/protocol/zk/proofs/point-multiplication.js.map +1 -0
- package/dist/internal/protocol/zk/proofs/sho.d.ts +1 -0
- package/dist/internal/protocol/zk/proofs/sho.d.ts.map +1 -1
- package/dist/internal/protocol/zk/proofs/sho.js.map +1 -1
- package/dist/internal/protocol/zk/proofs/statement.d.ts.map +1 -1
- package/dist/internal/protocol/zk/proofs/statement.js +11 -11
- package/dist/internal/protocol/zk/proofs/statement.js.map +1 -1
- package/dist/internal/sesame/device-registry.d.ts +24 -4
- package/dist/internal/sesame/device-registry.d.ts.map +1 -1
- package/dist/internal/sesame/device-registry.js +55 -28
- package/dist/internal/sesame/device-registry.js.map +1 -1
- package/dist/internal/sesame/manager.d.ts +79 -11
- package/dist/internal/sesame/manager.d.ts.map +1 -1
- package/dist/internal/sesame/manager.js +381 -280
- package/dist/internal/sesame/manager.js.map +1 -1
- package/dist/internal/session/cipher.d.ts +0 -5
- package/dist/internal/session/cipher.d.ts.map +1 -1
- package/dist/internal/session/cipher.js +3 -9
- package/dist/internal/session/cipher.js.map +1 -1
- package/dist/internal/session/record-locks.d.ts +46 -0
- package/dist/internal/session/record-locks.d.ts.map +1 -0
- package/dist/internal/session/record-locks.js +72 -0
- package/dist/internal/session/record-locks.js.map +1 -0
- package/dist/local/store/expo/adapter.d.ts +8 -2
- package/dist/local/store/expo/adapter.d.ts.map +1 -1
- package/dist/local/store/expo/adapter.js +24 -3
- package/dist/local/store/expo/adapter.js.map +1 -1
- package/dist/local/store/expo/driver.d.ts +7 -0
- package/dist/local/store/expo/driver.d.ts.map +1 -1
- package/dist/local/store/expo/driver.js +16 -0
- package/dist/local/store/expo/driver.js.map +1 -1
- package/dist/local/store/index.d.ts +2 -2
- package/dist/local/store/index.js +2 -2
- package/dist/local/store/key-value/adapter.d.ts.map +1 -1
- package/dist/local/store/key-value/adapter.js +61 -38
- package/dist/local/store/key-value/adapter.js.map +1 -1
- package/dist/local/store/memory/adapter.d.ts +10 -0
- package/dist/local/store/memory/adapter.d.ts.map +1 -1
- package/dist/local/store/memory/adapter.js +79 -55
- package/dist/local/store/memory/adapter.js.map +1 -1
- package/dist/local/store/reliability.d.ts +16 -0
- package/dist/local/store/reliability.d.ts.map +1 -1
- package/dist/local/store/reliability.js +58 -28
- package/dist/local/store/reliability.js.map +1 -1
- package/dist/local/store/sqlite/store.d.ts.map +1 -1
- package/dist/local/store/sqlite/store.js +36 -14
- package/dist/local/store/sqlite/store.js.map +1 -1
- package/dist/local/store/sqlite/web/driver.d.ts.map +1 -1
- package/dist/local/store/sqlite/web/driver.js +3 -1
- package/dist/local/store/sqlite/web/driver.js.map +1 -1
- package/dist/local/store/sqlite/web/protocol.d.ts +1 -1
- package/dist/local/store/sqlite/web/protocol.d.ts.map +1 -1
- package/dist/local/store/sqlite/web/worker.d.ts +7 -4
- package/dist/local/store/sqlite/web/worker.d.ts.map +1 -1
- package/dist/local/store/sqlite/web/worker.js +48 -18
- package/dist/local/store/sqlite/web/worker.js.map +1 -1
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +63 -53
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/local/store/web-sqlite/adapter.d.ts +3 -0
- package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
- package/dist/local/store/web-sqlite/adapter.js +3 -0
- package/dist/local/store/web-sqlite/adapter.js.map +1 -1
- package/dist/local/vault/electron-safe-storage.d.ts.map +1 -1
- package/dist/local/vault/electron-safe-storage.js +15 -2
- package/dist/local/vault/electron-safe-storage.js.map +1 -1
- package/dist/profile/index.d.ts +2 -1
- package/dist/profile/index.d.ts.map +1 -1
- package/dist/profile/index.js +2 -1
- package/dist/profile/index.js.map +1 -1
- package/dist/profile/own-profile-key.d.ts +42 -0
- package/dist/profile/own-profile-key.d.ts.map +1 -0
- package/dist/profile/own-profile-key.js +64 -0
- package/dist/profile/own-profile-key.js.map +1 -0
- package/dist/profile/profile-key.d.ts +1 -34
- package/dist/profile/profile-key.d.ts.map +1 -1
- package/dist/profile/profile-key.js +3 -63
- package/dist/profile/profile-key.js.map +1 -1
- package/dist/profile/update-service.js +1 -1
- package/dist/profile/update-service.js.map +1 -1
- package/dist/remote/relay/memory/adapter.d.ts.map +1 -1
- package/dist/remote/relay/memory/adapter.js +3 -4
- package/dist/remote/relay/memory/adapter.js.map +1 -1
- package/dist/username/link.d.ts.map +1 -1
- package/dist/username/link.js +1 -5
- package/dist/username/link.js.map +1 -1
- package/dist/utils/bounded-fan-out.d.ts +99 -0
- package/dist/utils/bounded-fan-out.d.ts.map +1 -0
- package/dist/utils/bounded-fan-out.js +180 -0
- package/dist/utils/bounded-fan-out.js.map +1 -0
- package/dist/utils/keyed-lock.d.ts +16 -0
- package/dist/utils/keyed-lock.d.ts.map +1 -0
- package/dist/utils/keyed-lock.js +39 -0
- package/dist/utils/keyed-lock.js.map +1 -0
- package/docs/ASSURANCE.md +68 -24
- package/docs/DEVIATIONS.md +21 -2
- package/docs/ERROR_HANDLING.md +1 -1
- package/docs/PACKAGE_SURFACE.md +3 -1
- package/examples/browser/index.html +1 -1
- package/hooks/README.md +11 -2
- package/local/store/README.md +41 -21
- package/local/store/expo/README.md +18 -5
- package/local/store/key-value/README.md +5 -3
- package/local/store/node/README.md +2 -1
- package/local/store/web/README.md +5 -0
- package/local/store/web-sqlite/README.md +36 -8
- package/local/vault/README.md +21 -2
- package/package.json +1 -1
- package/remote/object-store/convex-r2/README.md +10 -0
package/local/store/README.md
CHANGED
|
@@ -24,29 +24,31 @@ without coupling the client to a database or platform.
|
|
|
24
24
|
|
|
25
25
|
### Web
|
|
26
26
|
|
|
27
|
-
- `IndexedDbSignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/web`
|
|
28
|
-
|
|
29
|
-
Use this for browser applications. It implements the full core store
|
|
30
|
-
contract, including SESAME records, sender-key state, retry message records,
|
|
31
|
-
and recovery helpers. It graduated from experimental by completing every
|
|
32
|
-
gate on the checklist below. Deployment still requires the origin-security
|
|
33
|
-
review described in the [web adapter guide](./web/README.md).
|
|
34
|
-
|
|
35
27
|
- `webSqliteStore` and `WebSqliteSignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/web-sqlite`
|
|
36
28
|
- `resetWebSqliteStore` and `createPreKeyMaintenanceStore` from the same entry
|
|
37
29
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
the
|
|
42
|
-
|
|
43
|
-
`
|
|
44
|
-
|
|
45
|
-
|
|
30
|
+
Use this for browser applications where the origin private file system
|
|
31
|
+
works. It keeps the full core store state in an SDK-owned SQLite database in
|
|
32
|
+
the origin private file system. SQLite3 Multiple Ciphers encrypts the whole
|
|
33
|
+
file in a Wasm worker, and the database key lives in a secret vault, by
|
|
34
|
+
default IndexedDB in the same origin. The page's Content Security Policy must
|
|
35
|
+
allow `'wasm-unsafe-eval'`. A context without the origin private file system
|
|
36
|
+
gets `OPFS_UNAVAILABLE`. The [web SQLite store guide](./web-sqlite/README.md)
|
|
37
|
+
covers the policy, the tabs, and the security boundary. It graduated from
|
|
38
|
+
experimental by completing every gate on the checklist below.
|
|
46
39
|
|
|
47
40
|
A Tauri 2 app uses this store in its webview. See the
|
|
48
41
|
[Tauri section](./web-sqlite/README.md#tauri).
|
|
49
42
|
|
|
43
|
+
- `IndexedDbSignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/web`
|
|
44
|
+
|
|
45
|
+
Use this where the origin private file system is not available, and
|
|
46
|
+
`webSqliteStore` fails with `OPFS_UNAVAILABLE`. It implements the full core
|
|
47
|
+
store contract, including SESAME records, sender-key state, retry message
|
|
48
|
+
records, and recovery helpers. It graduated from experimental by completing
|
|
49
|
+
every gate on the checklist below. Deployment still requires the
|
|
50
|
+
origin-security review described in the [web adapter guide](./web/README.md).
|
|
51
|
+
|
|
50
52
|
### Bare React Native
|
|
51
53
|
|
|
52
54
|
- `reactNativeStore` and `ReactNativeSignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/react-native`
|
|
@@ -119,7 +121,7 @@ environment an adapter must honor its promises in, not the subject of a test.
|
|
|
119
121
|
source repository, and `npm run soak:web-store` runs longer sessions
|
|
120
122
|
on demand.
|
|
121
123
|
|
|
122
|
-
`WebSqliteSignalProtocolStore` (
|
|
124
|
+
`WebSqliteSignalProtocolStore` (graduated, and the gates keep running):
|
|
123
125
|
|
|
124
126
|
- [x] Storage contract suites pass in real Chromium, Firefox, and WebKit.
|
|
125
127
|
The suites are the same modules the jest gate runs. They run against
|
|
@@ -154,9 +156,27 @@ environment an adapter must honor its promises in, not the subject of a test.
|
|
|
154
156
|
no row of the write, no pinned identity, and the one-time prekey stays.
|
|
155
157
|
The store stays open. After the clamp is removed, the same commit
|
|
156
158
|
succeeds, new writes land, and `PRAGMA integrity_check` returns `ok`.
|
|
159
|
+
A first open under a 1 MB and a 4 MB quota rejects with the same typed
|
|
160
|
+
error, and it writes no database key and no database file. After the
|
|
161
|
+
clamp is removed, the open succeeds. A store with two pool files opens,
|
|
162
|
+
reads, and writes under a 3 MB quota that has no room for a new pool.
|
|
157
163
|
Runs in Chromium on the schedule above. The quota clamp is a DevTools
|
|
158
164
|
protocol call, so Firefox and WebKit do not run it.
|
|
159
|
-
- [
|
|
165
|
+
- [x] Soak evidence: a long run holds latency, memory, and file size flat.
|
|
166
|
+
A soak gate drives the store in real Chromium tabs in three phases:
|
|
167
|
+
150 open/write/read/close cycles in one tab, one session of 2,000
|
|
168
|
+
churn operations over 250 sessions, and 100 writes that two tabs make
|
|
169
|
+
in turn, so that the file moves to the other tab at each write. Each
|
|
170
|
+
write is read back, and `PRAGMA integrity_check` returns `ok` after
|
|
171
|
+
each phase and after each open. A closed store leaves no worker in the
|
|
172
|
+
tab and no lock of the store in the origin. The gate fails if the
|
|
173
|
+
late-run median of latency, of the page heap, or of the worker heap
|
|
174
|
+
grows beyond a small tolerance over the early-run median, if the Wasm
|
|
175
|
+
memory of the worker grows after the first third of the churn, or if
|
|
176
|
+
the database file grows by more than 10% and 64 KiB over the churn.
|
|
177
|
+
Runs in Chromium on each change to the main branch and on each pull
|
|
178
|
+
request that is ready for review. `npm run soak:web-sqlite` also runs
|
|
179
|
+
it in Firefox and WebKit on demand, without the memory checks.
|
|
160
180
|
|
|
161
181
|
`KeyValueSignalProtocolStore` (graduated, and the gates keep running):
|
|
162
182
|
|
|
@@ -305,9 +325,9 @@ The host application must use idempotent writes keyed by message ID.
|
|
|
305
325
|
- `@open-e2ee/signal-protocol-sdk/local/store/react-native` is the same SQLite
|
|
306
326
|
store for bare React Native, on op-sqlite and the react-native-keychain vault.
|
|
307
327
|
- An adapter carries the experimental label until every item on its
|
|
308
|
-
graduation checklist is a named, continuously running CI gate. The
|
|
309
|
-
web adapter and the key-value adapter completed
|
|
310
|
-
|
|
328
|
+
graduation checklist is a named, continuously running CI gate. The web
|
|
329
|
+
SQLite store, the IndexedDB web adapter, and the key-value adapter completed
|
|
330
|
+
theirs.
|
|
311
331
|
- Storage adapters should expose the real package contract instead of app-specific wrappers.
|
|
312
332
|
|
|
313
333
|
## Related Docs
|
|
@@ -47,11 +47,11 @@ Options:
|
|
|
47
47
|
`open-e2ee-signal-protocol.db`.
|
|
48
48
|
- `vault`: the `SignalProtocolLocalSecretVault` that holds the database key.
|
|
49
49
|
Default: `ExpoSecureStoreSignalProtocolSecretVault`.
|
|
50
|
-
- `encryptionAtRest`: pass `false` to store the database without encryption
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
50
|
+
- `encryptionAtRest`: pass `false` to store the database without encryption.
|
|
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)).
|
|
55
55
|
- `logger`: receives the warning of each open without encryption.
|
|
56
56
|
|
|
57
57
|
A store holds its name until `close()`. In one process, the opens and resets
|
|
@@ -62,6 +62,19 @@ and the second open fails.
|
|
|
62
62
|
Keep application tables in a separate database file. The SDK database holds
|
|
63
63
|
only SDK tables.
|
|
64
64
|
|
|
65
|
+
## Web
|
|
66
|
+
|
|
67
|
+
The web build of `expo-sqlite` has no SQLCipher, and Expo SecureStore has no
|
|
68
|
+
web implementation. On the web, `expoStore()` and `resetExpoStore()` therefore
|
|
69
|
+
fail with `SqliteEncryptionUnavailableError` (`KEY_STORAGE_ERROR`). They fail
|
|
70
|
+
before they use the vault or a database file, also when the app passes its own
|
|
71
|
+
vault. A native build without the `useSQLCipher` option fails in the same way.
|
|
72
|
+
|
|
73
|
+
For an encrypted store in a browser, use
|
|
74
|
+
[`./local/store/web-sqlite`](../web-sqlite/README.md). `encryptionAtRest: false`
|
|
75
|
+
opens this store on the web without encryption. Use it only when the app
|
|
76
|
+
accepts protocol state in plaintext in the browser storage of the origin.
|
|
77
|
+
|
|
65
78
|
## Lost key and reset
|
|
66
79
|
|
|
67
80
|
When the database file exists and the vault holds no key for it, `expoStore`
|
|
@@ -132,9 +132,11 @@ Realm file. If you already use a Realm, add `realmKeyValueSchema` to its schema
|
|
|
132
132
|
list, or open a separate Realm file for the store.
|
|
133
133
|
|
|
134
134
|
The adapter is tested with the conformance kit on realm 20.2.0 in Node,
|
|
135
|
-
including a reopen of the same Realm file.
|
|
136
|
-
|
|
137
|
-
|
|
135
|
+
including a reopen of the same Realm file. Manual checks ran the kit in
|
|
136
|
+
React Native apps in the iOS 26.2 simulator and in an Android emulator. All
|
|
137
|
+
13 cases passed in each. The SDK does not test the adapter
|
|
138
|
+
on a physical device. Run the conformance kit on your target devices with
|
|
139
|
+
your Realm build before you ship.
|
|
138
140
|
|
|
139
141
|
### Realm maintenance status
|
|
140
142
|
|
|
@@ -61,7 +61,8 @@ only SDK tables.
|
|
|
61
61
|
|
|
62
62
|
Use a supported Electron major: the Electron team supports the latest three
|
|
63
63
|
stable majors ([release timelines](https://www.electronjs.org/docs/latest/tutorial/electron-timelines)).
|
|
64
|
-
CI tests Electron 44 on Linux, macOS, and Windows
|
|
64
|
+
CI tests the latest major, Electron 44, on Linux, macOS, and Windows, and the
|
|
65
|
+
oldest supported major, Electron 42, on Linux. The binding uses Node-API,
|
|
65
66
|
so its prebuild loads in each supported major without a rebuild.
|
|
66
67
|
|
|
67
68
|
Open the store in the main process, with the vault over Electron's
|
|
@@ -66,6 +66,11 @@ and [MDN Content Security Policy guide](https://developer.mozilla.org/docs/Web/H
|
|
|
66
66
|
|
|
67
67
|
## Operational status
|
|
68
68
|
|
|
69
|
+
In a browser where the origin private file system works, use the
|
|
70
|
+
[web SQLite store](../web-sqlite/README.md). Use this adapter where the origin
|
|
71
|
+
private file system is not available, and `webSqliteStore` fails with
|
|
72
|
+
`OPFS_UNAVAILABLE`.
|
|
73
|
+
|
|
69
74
|
The adapter covers the core store contract, including atomic security commits,
|
|
70
75
|
SESAME state, sender-key state, and retry records. Every gate on its
|
|
71
76
|
graduation checklist in the parent [storage guide](../README.md) runs
|
|
@@ -84,6 +84,14 @@ transaction. Each tab reads the writes of the other tabs.
|
|
|
84
84
|
the files, for example a tab that is closing. The file is unchanged. Retry
|
|
85
85
|
the open later.
|
|
86
86
|
|
|
87
|
+
## Full storage
|
|
88
|
+
|
|
89
|
+
When the origin storage quota is full, the open rejects with
|
|
90
|
+
`StorageQuotaExceededError` (`STORAGE_QUOTA_EXCEEDED`). An open that fails
|
|
91
|
+
this way on a new store writes no key and no database file. A write on an open
|
|
92
|
+
store rejects with the same error. SQLite rolls the write back, and the store
|
|
93
|
+
stays open. Free space, then open again or retry the write.
|
|
94
|
+
|
|
87
95
|
## Content Security Policy
|
|
88
96
|
|
|
89
97
|
The engine compiles WebAssembly in its worker. A Content Security Policy
|
|
@@ -140,10 +148,12 @@ move to the other after an error that is not `OPFS_UNAVAILABLE`.
|
|
|
140
148
|
## Tauri
|
|
141
149
|
|
|
142
150
|
A Tauri 2 app uses this entry in its webview. The entry runs unchanged in
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
151
|
+
WebView2 on Windows, in the Android WebView, and in WKWebView on macOS and iOS.
|
|
152
|
+
A CI job runs it in a Tauri 2.12 app in WebView2 on Windows and in the Android
|
|
153
|
+
WebView on an Android emulator. Manual checks ran it with Tauri 2.12 on
|
|
154
|
+
macOS 15.7 and in the iOS 17.5 and 18.0 simulators. It needs no Tauri headers
|
|
155
|
+
(`app.security.headers`) and no capability, because the store makes no IPC
|
|
156
|
+
call.
|
|
147
157
|
|
|
148
158
|
Put the policy from [Content Security Policy](#content-security-policy) in
|
|
149
159
|
`app.security.csp` of `tauri.conf.json`. When the app uses Tauri IPC, add the
|
|
@@ -175,11 +185,29 @@ IPC sources to `connect-src`:
|
|
|
175
185
|
where the webview keeps its data. Set these values before the first release,
|
|
176
186
|
and never change them. A change moves the data, and the app then cannot find
|
|
177
187
|
its database or its vault.
|
|
178
|
-
- **
|
|
179
|
-
|
|
188
|
+
- **Windows of one app.** Each window of the app is its own JavaScript
|
|
189
|
+
context. The windows of one origin share the database. A reset fails
|
|
190
|
+
with `INVALID_STATE` while any window holds the store. See [Tabs](#tabs).
|
|
191
|
+
- **Website data.** The database and the vault key are website data of the
|
|
192
|
+
webview. In WKWebView, `navigator.storage.persist()` returns `false`, so
|
|
193
|
+
the webview does not promise to keep them. A clear of all website data,
|
|
194
|
+
for example with `clear_all_browsing_data`, removes the database and the
|
|
195
|
+
key together. The next open then creates a new, empty store and reports
|
|
196
|
+
no error. The open fails with `LOCAL_STORE_KEY_LOST` only when the file
|
|
197
|
+
stays and the key goes. See [Lost key and reset](#lost-key-and-reset).
|
|
198
|
+
- **Loss of all data.** The app must find a loss of all website data itself.
|
|
199
|
+
For example, write a marker to the store with `setMetadata`. Keep a record
|
|
200
|
+
in the app data directory, outside the webview data, that the device has a
|
|
201
|
+
store. When the record exists and the marker does not, treat the device as
|
|
202
|
+
a new device. Do not clear the website data of the webview that holds the
|
|
203
|
+
store.
|
|
204
|
+
- **Linux.** WebKitGTK has no OPFS synchronous access handles, so the open
|
|
205
|
+
rejects with `OPFS_UNAVAILABLE`. A CI job checks this refusal in a Tauri
|
|
206
|
+
app with WebKitGTK 2.52. See
|
|
180
207
|
[When OPFS is not available](#when-opfs-is-not-available).
|
|
181
|
-
- **
|
|
182
|
-
|
|
208
|
+
- **Android.** A CI job runs every check in a debug APK in the Android
|
|
209
|
+
WebView 133 on an Android API 36 emulator, and every check passes. The
|
|
210
|
+
origin of the webview is `http://tauri.localhost`.
|
|
183
211
|
- **Key custody.** The default vault keeps the key in IndexedDB in the same
|
|
184
212
|
origin as the database. An app that needs OS keychain custody passes its own
|
|
185
213
|
vault. See [Security boundary](#security-boundary).
|
package/local/vault/README.md
CHANGED
|
@@ -108,6 +108,24 @@ The protection is that of the OS key store
|
|
|
108
108
|
refuses that key: on Linux, it accepts only a ciphertext that starts with
|
|
109
109
|
`v11`, the prefix of a key from a secret service.
|
|
110
110
|
|
|
111
|
+
On Linux, the vault gives these results for the backends of
|
|
112
|
+
`getSelectedStorageBackend()`:
|
|
113
|
+
|
|
114
|
+
| Backend | Secret store | Result |
|
|
115
|
+
|---|---|---|
|
|
116
|
+
| `gnome_libsecret` | GNOME Keyring | The vault works. |
|
|
117
|
+
| `kwallet5` | KWallet 5, and KWallet 6 through its `kwalletd5` name | The vault works. |
|
|
118
|
+
| `kwallet6` | KWallet 6 | The vault works. |
|
|
119
|
+
| `basic_text` | None | The vault refuses the backend. |
|
|
120
|
+
| `gnome_libsecret`, `kwallet5`, or `kwallet6` with no secret service | None: the fixed fallback key, `v10` | The vault refuses the key. |
|
|
121
|
+
| `gnome_libsecret`, `kwallet5`, or `kwallet6`, with the Chromium feature `SecretPortalKeyProviderUseForEncryption` and a Secret portal | The key of the Secret portal, `v12` | The vault refuses the key. |
|
|
122
|
+
|
|
123
|
+
The Secret portal of xdg-desktop-portal gives a key to each app. Outside a
|
|
124
|
+
Flatpak or Snap sandbox, Electron asks for the key as the Chromium app. Each
|
|
125
|
+
Electron app of the user then gets the same key. Electron uses the portal key
|
|
126
|
+
only with the `SecretPortalKeyProviderUseForEncryption` feature, which is off
|
|
127
|
+
by default. Without that feature, a running portal does not change the key.
|
|
128
|
+
|
|
111
129
|
The vault fails with an `EncryptionError` that has the code
|
|
112
130
|
`KEY_STORAGE_ERROR`:
|
|
113
131
|
|
|
@@ -116,8 +134,9 @@ The vault fails with an `EncryptionError` that has the code
|
|
|
116
134
|
- on Linux, when the backend is `basic_text`, which encrypts with a fixed
|
|
117
135
|
password, or `unknown`;
|
|
118
136
|
- on Linux, when a ciphertext does not start with `v11`, for example when no
|
|
119
|
-
secret service answered and `safeStorage` used its fixed key
|
|
120
|
-
file does not
|
|
137
|
+
secret service answered and `safeStorage` used its fixed key, or when
|
|
138
|
+
`safeStorage` used the key of the Secret portal. The vault file does not
|
|
139
|
+
change;
|
|
121
140
|
- when `safeStorage` cannot encrypt or decrypt, for example when the OS key
|
|
122
141
|
is gone or the macOS signature of the app is not valid. The Electron error
|
|
123
142
|
is the `originalError`. It can say that `safeStorage` is temporarily
|
package/package.json
CHANGED
|
@@ -11,6 +11,16 @@ operates inside the application backend. This adapter maps that generated API
|
|
|
11
11
|
to `SignalProtocolRemoteObjectStore` without moving storage policy, provider keys, or
|
|
12
12
|
component ownership into the SDK.
|
|
13
13
|
|
|
14
|
+
## Setup
|
|
15
|
+
|
|
16
|
+
Install the peer `convex` 1.42.1 or later. The server helper loads it to
|
|
17
|
+
define its functions. The client adapter loads no peer. The application
|
|
18
|
+
installs and mounts the `@convex-dev/r2` component in its own backend.
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
npm install convex
|
|
22
|
+
```
|
|
23
|
+
|
|
14
24
|
## Client usage
|
|
15
25
|
|
|
16
26
|
<!-- doc-snippet:skip requires-external-context -->
|