@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.
Files changed (199) hide show
  1. package/ADAPTERS.md +2 -2
  2. package/CHANGELOG.md +188 -0
  3. package/README.md +4 -4
  4. package/SECURITY.md +2 -2
  5. package/device/README.md +16 -7
  6. package/dist/client/client.d.ts +4 -2
  7. package/dist/client/client.d.ts.map +1 -1
  8. package/dist/client/client.js +25 -19
  9. package/dist/client/client.js.map +1 -1
  10. package/dist/client/group-outbox.d.ts +31 -1
  11. package/dist/client/group-outbox.d.ts.map +1 -1
  12. package/dist/client/group-outbox.js +67 -58
  13. package/dist/client/group-outbox.js.map +1 -1
  14. package/dist/client/hosted-anonymous-delivery.d.ts +9 -1
  15. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
  16. package/dist/client/hosted-anonymous-delivery.js +61 -22
  17. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  18. package/dist/client/hosted-transport.d.ts +16 -0
  19. package/dist/client/hosted-transport.d.ts.map +1 -1
  20. package/dist/client/hosted-transport.js +93 -19
  21. package/dist/client/hosted-transport.js.map +1 -1
  22. package/dist/client/key-rotation.d.ts.map +1 -1
  23. package/dist/client/key-rotation.js +2 -4
  24. package/dist/client/key-rotation.js.map +1 -1
  25. package/dist/client/prekeys.d.ts.map +1 -1
  26. package/dist/client/prekeys.js +1 -1
  27. package/dist/client/prekeys.js.map +1 -1
  28. package/dist/client/relay-device-refusal.d.ts +32 -0
  29. package/dist/client/relay-device-refusal.d.ts.map +1 -0
  30. package/dist/client/relay-device-refusal.js +36 -0
  31. package/dist/client/relay-device-refusal.js.map +1 -0
  32. package/dist/client/relay-work.d.ts +26 -0
  33. package/dist/client/relay-work.d.ts.map +1 -1
  34. package/dist/client/relay-work.js +37 -0
  35. package/dist/client/relay-work.js.map +1 -1
  36. package/dist/client/sealed-sender.d.ts.map +1 -1
  37. package/dist/client/sealed-sender.js +12 -17
  38. package/dist/client/sealed-sender.js.map +1 -1
  39. package/dist/client/sessions.d.ts.map +1 -1
  40. package/dist/client/sessions.js +2 -4
  41. package/dist/client/sessions.js.map +1 -1
  42. package/dist/client/signal-service-cipher.d.ts +90 -4
  43. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  44. package/dist/client/signal-service-cipher.js +425 -136
  45. package/dist/client/signal-service-cipher.js.map +1 -1
  46. package/dist/client/types.d.ts +7 -0
  47. package/dist/client/types.d.ts.map +1 -1
  48. package/dist/client/types.js.map +1 -1
  49. package/dist/internal/manager/manager.d.ts +8 -7
  50. package/dist/internal/manager/manager.d.ts.map +1 -1
  51. package/dist/internal/manager/manager.js +34 -36
  52. package/dist/internal/manager/manager.js.map +1 -1
  53. package/dist/internal/protocol/spqr/index.d.ts +1 -1
  54. package/dist/internal/protocol/spqr/index.d.ts.map +1 -1
  55. package/dist/internal/protocol/spqr/index.js +2 -2
  56. package/dist/internal/protocol/spqr/index.js.map +1 -1
  57. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
  58. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js +1 -3
  59. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js.map +1 -1
  60. package/dist/internal/protocol/spqr/serialize.d.ts.map +1 -1
  61. package/dist/internal/protocol/spqr/serialize.js +1 -4
  62. package/dist/internal/protocol/spqr/serialize.js.map +1 -1
  63. package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
  64. package/dist/internal/protocol/spqr/spqr.js +1 -2
  65. package/dist/internal/protocol/spqr/spqr.js.map +1 -1
  66. package/dist/internal/protocol/zk/credentials/attributes.d.ts.map +1 -1
  67. package/dist/internal/protocol/zk/credentials/attributes.js +2 -1
  68. package/dist/internal/protocol/zk/credentials/attributes.js.map +1 -1
  69. package/dist/internal/protocol/zk/credentials/credentials.d.ts.map +1 -1
  70. package/dist/internal/protocol/zk/credentials/credentials.js +8 -6
  71. package/dist/internal/protocol/zk/credentials/credentials.js.map +1 -1
  72. package/dist/internal/protocol/zk/credentials/presentation.d.ts.map +1 -1
  73. package/dist/internal/protocol/zk/credentials/presentation.js +19 -13
  74. package/dist/internal/protocol/zk/credentials/presentation.js.map +1 -1
  75. package/dist/internal/protocol/zk/groups/lizard.d.ts +8 -0
  76. package/dist/internal/protocol/zk/groups/lizard.d.ts.map +1 -1
  77. package/dist/internal/protocol/zk/groups/lizard.js +18 -5
  78. package/dist/internal/protocol/zk/groups/lizard.js.map +1 -1
  79. package/dist/internal/protocol/zk/groups/profile-key-commitment.d.ts.map +1 -1
  80. package/dist/internal/protocol/zk/groups/profile-key-commitment.js +7 -6
  81. package/dist/internal/protocol/zk/groups/profile-key-commitment.js.map +1 -1
  82. package/dist/internal/protocol/zk/groups/profile-key-encryption.d.ts.map +1 -1
  83. package/dist/internal/protocol/zk/groups/profile-key-encryption.js +3 -2
  84. package/dist/internal/protocol/zk/groups/profile-key-encryption.js.map +1 -1
  85. package/dist/internal/protocol/zk/groups/uid-encryption.d.ts.map +1 -1
  86. package/dist/internal/protocol/zk/groups/uid-encryption.js +3 -2
  87. package/dist/internal/protocol/zk/groups/uid-encryption.js.map +1 -1
  88. package/dist/internal/protocol/zk/proofs/point-multiplication.d.ts +53 -0
  89. package/dist/internal/protocol/zk/proofs/point-multiplication.d.ts.map +1 -0
  90. package/dist/internal/protocol/zk/proofs/point-multiplication.js +164 -0
  91. package/dist/internal/protocol/zk/proofs/point-multiplication.js.map +1 -0
  92. package/dist/internal/protocol/zk/proofs/sho.d.ts +1 -0
  93. package/dist/internal/protocol/zk/proofs/sho.d.ts.map +1 -1
  94. package/dist/internal/protocol/zk/proofs/sho.js.map +1 -1
  95. package/dist/internal/protocol/zk/proofs/statement.d.ts.map +1 -1
  96. package/dist/internal/protocol/zk/proofs/statement.js +11 -11
  97. package/dist/internal/protocol/zk/proofs/statement.js.map +1 -1
  98. package/dist/internal/sesame/device-registry.d.ts +24 -4
  99. package/dist/internal/sesame/device-registry.d.ts.map +1 -1
  100. package/dist/internal/sesame/device-registry.js +55 -28
  101. package/dist/internal/sesame/device-registry.js.map +1 -1
  102. package/dist/internal/sesame/manager.d.ts +79 -11
  103. package/dist/internal/sesame/manager.d.ts.map +1 -1
  104. package/dist/internal/sesame/manager.js +381 -280
  105. package/dist/internal/sesame/manager.js.map +1 -1
  106. package/dist/internal/session/cipher.d.ts +0 -5
  107. package/dist/internal/session/cipher.d.ts.map +1 -1
  108. package/dist/internal/session/cipher.js +3 -9
  109. package/dist/internal/session/cipher.js.map +1 -1
  110. package/dist/internal/session/record-locks.d.ts +46 -0
  111. package/dist/internal/session/record-locks.d.ts.map +1 -0
  112. package/dist/internal/session/record-locks.js +72 -0
  113. package/dist/internal/session/record-locks.js.map +1 -0
  114. package/dist/local/store/expo/adapter.d.ts +8 -2
  115. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  116. package/dist/local/store/expo/adapter.js +24 -3
  117. package/dist/local/store/expo/adapter.js.map +1 -1
  118. package/dist/local/store/expo/driver.d.ts +7 -0
  119. package/dist/local/store/expo/driver.d.ts.map +1 -1
  120. package/dist/local/store/expo/driver.js +16 -0
  121. package/dist/local/store/expo/driver.js.map +1 -1
  122. package/dist/local/store/index.d.ts +2 -2
  123. package/dist/local/store/index.js +2 -2
  124. package/dist/local/store/key-value/adapter.d.ts.map +1 -1
  125. package/dist/local/store/key-value/adapter.js +61 -38
  126. package/dist/local/store/key-value/adapter.js.map +1 -1
  127. package/dist/local/store/memory/adapter.d.ts +10 -0
  128. package/dist/local/store/memory/adapter.d.ts.map +1 -1
  129. package/dist/local/store/memory/adapter.js +79 -55
  130. package/dist/local/store/memory/adapter.js.map +1 -1
  131. package/dist/local/store/reliability.d.ts +16 -0
  132. package/dist/local/store/reliability.d.ts.map +1 -1
  133. package/dist/local/store/reliability.js +58 -28
  134. package/dist/local/store/reliability.js.map +1 -1
  135. package/dist/local/store/sqlite/store.d.ts.map +1 -1
  136. package/dist/local/store/sqlite/store.js +36 -14
  137. package/dist/local/store/sqlite/store.js.map +1 -1
  138. package/dist/local/store/sqlite/web/driver.d.ts.map +1 -1
  139. package/dist/local/store/sqlite/web/driver.js +3 -1
  140. package/dist/local/store/sqlite/web/driver.js.map +1 -1
  141. package/dist/local/store/sqlite/web/protocol.d.ts +1 -1
  142. package/dist/local/store/sqlite/web/protocol.d.ts.map +1 -1
  143. package/dist/local/store/sqlite/web/worker.d.ts +7 -4
  144. package/dist/local/store/sqlite/web/worker.d.ts.map +1 -1
  145. package/dist/local/store/sqlite/web/worker.js +48 -18
  146. package/dist/local/store/sqlite/web/worker.js.map +1 -1
  147. package/dist/local/store/web/adapter.d.ts.map +1 -1
  148. package/dist/local/store/web/adapter.js +63 -53
  149. package/dist/local/store/web/adapter.js.map +1 -1
  150. package/dist/local/store/web-sqlite/adapter.d.ts +3 -0
  151. package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
  152. package/dist/local/store/web-sqlite/adapter.js +3 -0
  153. package/dist/local/store/web-sqlite/adapter.js.map +1 -1
  154. package/dist/local/vault/electron-safe-storage.d.ts.map +1 -1
  155. package/dist/local/vault/electron-safe-storage.js +15 -2
  156. package/dist/local/vault/electron-safe-storage.js.map +1 -1
  157. package/dist/profile/index.d.ts +2 -1
  158. package/dist/profile/index.d.ts.map +1 -1
  159. package/dist/profile/index.js +2 -1
  160. package/dist/profile/index.js.map +1 -1
  161. package/dist/profile/own-profile-key.d.ts +42 -0
  162. package/dist/profile/own-profile-key.d.ts.map +1 -0
  163. package/dist/profile/own-profile-key.js +64 -0
  164. package/dist/profile/own-profile-key.js.map +1 -0
  165. package/dist/profile/profile-key.d.ts +1 -34
  166. package/dist/profile/profile-key.d.ts.map +1 -1
  167. package/dist/profile/profile-key.js +3 -63
  168. package/dist/profile/profile-key.js.map +1 -1
  169. package/dist/profile/update-service.js +1 -1
  170. package/dist/profile/update-service.js.map +1 -1
  171. package/dist/remote/relay/memory/adapter.d.ts.map +1 -1
  172. package/dist/remote/relay/memory/adapter.js +3 -4
  173. package/dist/remote/relay/memory/adapter.js.map +1 -1
  174. package/dist/username/link.d.ts.map +1 -1
  175. package/dist/username/link.js +1 -5
  176. package/dist/username/link.js.map +1 -1
  177. package/dist/utils/bounded-fan-out.d.ts +99 -0
  178. package/dist/utils/bounded-fan-out.d.ts.map +1 -0
  179. package/dist/utils/bounded-fan-out.js +180 -0
  180. package/dist/utils/bounded-fan-out.js.map +1 -0
  181. package/dist/utils/keyed-lock.d.ts +16 -0
  182. package/dist/utils/keyed-lock.d.ts.map +1 -0
  183. package/dist/utils/keyed-lock.js +39 -0
  184. package/dist/utils/keyed-lock.js.map +1 -0
  185. package/docs/ASSURANCE.md +68 -24
  186. package/docs/DEVIATIONS.md +21 -2
  187. package/docs/ERROR_HANDLING.md +1 -1
  188. package/docs/PACKAGE_SURFACE.md +3 -1
  189. package/examples/browser/index.html +1 -1
  190. package/hooks/README.md +11 -2
  191. package/local/store/README.md +41 -21
  192. package/local/store/expo/README.md +18 -5
  193. package/local/store/key-value/README.md +5 -3
  194. package/local/store/node/README.md +2 -1
  195. package/local/store/web/README.md +5 -0
  196. package/local/store/web-sqlite/README.md +36 -8
  197. package/local/vault/README.md +21 -2
  198. package/package.json +1 -1
  199. package/remote/object-store/convex-r2/README.md +10 -0
@@ -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
- This store keeps the same state in an SDK-owned SQLite database in the origin
39
- private file system. SQLite3 Multiple Ciphers encrypts the whole file in a Wasm
40
- worker, and the database key lives in a secret vault, by default IndexedDB in
41
- the same origin. The page's Content Security Policy must allow
42
- `'wasm-unsafe-eval'`. A context without the origin private file system gets
43
- `OPFS_UNAVAILABLE`. The [web SQLite store guide](./web-sqlite/README.md) covers
44
- the policy, the tabs, and the security boundary. This store is experimental:
45
- one item on its graduation checklist below is open.
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` (experimental, with one item open):
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
- - [ ] Soak evidence. No soak gate runs against this store.
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 IndexedDB
309
- web adapter and the key-value adapter completed theirs. The web SQLite store
310
- has one item open.
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
- for example on the web, where `expo-sqlite` has no SQLCipher. The store then
52
- does not use the vault, and it logs a warning at each open. A database
53
- created with one setting does not open with the other. Default: `true`, and
54
- the open fails when the build has no SQLCipher.
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. The SDK does not test it on a
136
- device. Run the conformance kit on your target devices with your Realm build
137
- before you ship.
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. The binding uses Node-API,
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
- WKWebView on macOS and iOS. A manual check ran it with Tauri 2.12 on macOS
144
- 15.7 and in the iOS 18.0 simulator. No CI job runs it in Tauri. It needs no
145
- Tauri headers (`app.security.headers`) and no capability, because the store
146
- makes no IPC call.
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
- - **Linux.** WebKitGTK 2.54 has no OPFS synchronous access handles. On it,
179
- the expected result of the open is a rejection with `OPFS_UNAVAILABLE`. See
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
- - **Windows and Android.** WebView2 and the Android WebView are not yet
182
- tested.
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).
@@ -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. The vault
120
- file does not change;
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "8.0.0",
3
+ "version": "8.2.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",
@@ -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 -->