@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.
Files changed (171) hide show
  1. package/ADAPTERS.md +3 -0
  2. package/ARCHITECTURE.md +4 -4
  3. package/CHANGELOG.md +165 -0
  4. package/README.md +1 -1
  5. package/SECURITY.md +2 -2
  6. package/TROUBLESHOOTING.md +7 -7
  7. package/client/README.md +40 -0
  8. package/device/README.md +29 -3
  9. package/dist/client/client.d.ts +8 -0
  10. package/dist/client/client.d.ts.map +1 -1
  11. package/dist/client/client.js +26 -3
  12. package/dist/client/client.js.map +1 -1
  13. package/dist/client/config.d.ts +19 -12
  14. package/dist/client/config.d.ts.map +1 -1
  15. package/dist/client/config.js.map +1 -1
  16. package/dist/client/event-hooks.d.ts +28 -0
  17. package/dist/client/event-hooks.d.ts.map +1 -1
  18. package/dist/client/event-hooks.js +1 -0
  19. package/dist/client/event-hooks.js.map +1 -1
  20. package/dist/client/group-init-status.d.ts +21 -0
  21. package/dist/client/group-init-status.d.ts.map +1 -0
  22. package/dist/client/group-init-status.js +156 -0
  23. package/dist/client/group-init-status.js.map +1 -0
  24. package/dist/client/hosted-device-link.d.ts +97 -0
  25. package/dist/client/hosted-device-link.d.ts.map +1 -0
  26. package/dist/client/hosted-device-link.js +149 -0
  27. package/dist/client/hosted-device-link.js.map +1 -0
  28. package/dist/client/hosted-http-error.d.ts +30 -0
  29. package/dist/client/hosted-http-error.d.ts.map +1 -0
  30. package/dist/client/hosted-http-error.js +34 -0
  31. package/dist/client/hosted-http-error.js.map +1 -0
  32. package/dist/client/hosted-presence.js +1 -1
  33. package/dist/client/hosted-presence.js.map +1 -1
  34. package/dist/client/hosted-profile-keys.js +1 -1
  35. package/dist/client/hosted-profile-keys.js.map +1 -1
  36. package/dist/client/hosted-sandbox-identity.d.ts +3 -3
  37. package/dist/client/hosted-sandbox-identity.js +3 -3
  38. package/dist/client/hosted-transport.d.ts +0 -11
  39. package/dist/client/hosted-transport.d.ts.map +1 -1
  40. package/dist/client/hosted-transport.js +1 -15
  41. package/dist/client/hosted-transport.js.map +1 -1
  42. package/dist/client/hosted.d.ts +53 -7
  43. package/dist/client/hosted.d.ts.map +1 -1
  44. package/dist/client/hosted.js +158 -17
  45. package/dist/client/hosted.js.map +1 -1
  46. package/dist/client/index.d.ts +2 -1
  47. package/dist/client/index.d.ts.map +1 -1
  48. package/dist/client/index.js +1 -1
  49. package/dist/client/index.js.map +1 -1
  50. package/dist/client/receive-queue.d.ts +4 -2
  51. package/dist/client/receive-queue.d.ts.map +1 -1
  52. package/dist/client/receive-queue.js +26 -22
  53. package/dist/client/receive-queue.js.map +1 -1
  54. package/dist/index.d.ts +2 -1
  55. package/dist/index.d.ts.map +1 -1
  56. package/dist/index.js +1 -1
  57. package/dist/index.js.map +1 -1
  58. package/dist/internal/manager/manager.d.ts +6 -1
  59. package/dist/internal/manager/manager.d.ts.map +1 -1
  60. package/dist/internal/manager/manager.js +8 -2
  61. package/dist/internal/manager/manager.js.map +1 -1
  62. package/dist/internal/session/cipher.d.ts +2 -2
  63. package/dist/internal/session/cipher.js +1 -1
  64. package/dist/internal/session/types.d.ts +1 -1
  65. package/dist/local/store/conformance/cases/ciphertext.d.ts +7 -0
  66. package/dist/local/store/conformance/cases/ciphertext.d.ts.map +1 -0
  67. package/dist/local/store/conformance/cases/ciphertext.js +55 -0
  68. package/dist/local/store/conformance/cases/ciphertext.js.map +1 -0
  69. package/dist/local/store/conformance/cases/durability.d.ts +6 -0
  70. package/dist/local/store/conformance/cases/durability.d.ts.map +1 -0
  71. package/dist/local/store/conformance/cases/durability.js +34 -0
  72. package/dist/local/store/conformance/cases/durability.js.map +1 -0
  73. package/dist/local/store/conformance/cases/identity.d.ts +7 -0
  74. package/dist/local/store/conformance/cases/identity.d.ts.map +1 -0
  75. package/dist/local/store/conformance/cases/identity.js +84 -0
  76. package/dist/local/store/conformance/cases/identity.js.map +1 -0
  77. package/dist/local/store/conformance/cases/metadata.d.ts +7 -0
  78. package/dist/local/store/conformance/cases/metadata.d.ts.map +1 -0
  79. package/dist/local/store/conformance/cases/metadata.js +48 -0
  80. package/dist/local/store/conformance/cases/metadata.js.map +1 -0
  81. package/dist/local/store/conformance/cases/protection.d.ts +7 -0
  82. package/dist/local/store/conformance/cases/protection.d.ts.map +1 -0
  83. package/dist/local/store/conformance/cases/protection.js +14 -0
  84. package/dist/local/store/conformance/cases/protection.js.map +1 -0
  85. package/dist/local/store/conformance/cases/receive-work.d.ts +8 -0
  86. package/dist/local/store/conformance/cases/receive-work.d.ts.map +1 -0
  87. package/dist/local/store/conformance/cases/receive-work.js +152 -0
  88. package/dist/local/store/conformance/cases/receive-work.js.map +1 -0
  89. package/dist/local/store/conformance/cases/sender-key.d.ts +7 -0
  90. package/dist/local/store/conformance/cases/sender-key.d.ts.map +1 -0
  91. package/dist/local/store/conformance/cases/sender-key.js +59 -0
  92. package/dist/local/store/conformance/cases/sender-key.js.map +1 -0
  93. package/dist/local/store/conformance/cases/session-trust.d.ts +7 -0
  94. package/dist/local/store/conformance/cases/session-trust.d.ts.map +1 -0
  95. package/dist/local/store/conformance/cases/session-trust.js +64 -0
  96. package/dist/local/store/conformance/cases/session-trust.js.map +1 -0
  97. package/dist/local/store/conformance/checks.d.ts +15 -0
  98. package/dist/local/store/conformance/checks.d.ts.map +1 -0
  99. package/dist/local/store/conformance/checks.js +67 -0
  100. package/dist/local/store/conformance/checks.js.map +1 -0
  101. package/dist/local/store/conformance/index.d.ts +30 -0
  102. package/dist/local/store/conformance/index.d.ts.map +1 -0
  103. package/dist/local/store/conformance/index.js +29 -0
  104. package/dist/local/store/conformance/index.js.map +1 -0
  105. package/dist/local/store/conformance/records.d.ts +36 -0
  106. package/dist/local/store/conformance/records.d.ts.map +1 -0
  107. package/dist/local/store/conformance/records.js +109 -0
  108. package/dist/local/store/conformance/records.js.map +1 -0
  109. package/dist/local/store/conformance/run.d.ts +24 -0
  110. package/dist/local/store/conformance/run.d.ts.map +1 -0
  111. package/dist/local/store/conformance/run.js +156 -0
  112. package/dist/local/store/conformance/run.js.map +1 -0
  113. package/dist/local/store/conformance/types.d.ts +55 -0
  114. package/dist/local/store/conformance/types.d.ts.map +1 -0
  115. package/dist/local/store/conformance/types.js +6 -0
  116. package/dist/local/store/conformance/types.js.map +1 -0
  117. package/dist/local/store/expo/adapter.d.ts +2 -1
  118. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  119. package/dist/local/store/expo/adapter.js.map +1 -1
  120. package/dist/local/store/node/adapter.d.ts +2 -2
  121. package/dist/local/store/react-native/adapter.d.ts +2 -1
  122. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  123. package/dist/local/store/react-native/adapter.js.map +1 -1
  124. package/dist/local/store/sqlite/convert-plaintext.d.ts +62 -0
  125. package/dist/local/store/sqlite/convert-plaintext.d.ts.map +1 -0
  126. package/dist/local/store/sqlite/convert-plaintext.js +236 -0
  127. package/dist/local/store/sqlite/convert-plaintext.js.map +1 -0
  128. package/dist/local/store/sqlite/driver.d.ts +9 -0
  129. package/dist/local/store/sqlite/driver.d.ts.map +1 -1
  130. package/dist/local/store/sqlite/encryption.d.ts +21 -0
  131. package/dist/local/store/sqlite/encryption.d.ts.map +1 -1
  132. package/dist/local/store/sqlite/encryption.js.map +1 -1
  133. package/dist/local/store/sqlite/errors.d.ts.map +1 -1
  134. package/dist/local/store/sqlite/errors.js +2 -1
  135. package/dist/local/store/sqlite/errors.js.map +1 -1
  136. package/dist/local/store/sqlite/key-storage/identity-keys.d.ts +3 -1
  137. package/dist/local/store/sqlite/key-storage/identity-keys.d.ts.map +1 -1
  138. package/dist/local/store/sqlite/key-storage/identity-keys.js +3 -1
  139. package/dist/local/store/sqlite/key-storage/identity-keys.js.map +1 -1
  140. package/dist/local/store/sqlite/open-store.d.ts +36 -4
  141. package/dist/local/store/sqlite/open-store.d.ts.map +1 -1
  142. package/dist/local/store/sqlite/open-store.js +326 -21
  143. package/dist/local/store/sqlite/open-store.js.map +1 -1
  144. package/dist/local/store/sqlite/web/sqlite3mc/sqlite3.mjs +2 -1
  145. package/dist/local/store/sqlite/web/worker.d.ts +13 -0
  146. package/dist/local/store/sqlite/web/worker.d.ts.map +1 -1
  147. package/dist/local/store/sqlite/web/worker.js +163 -22
  148. package/dist/local/store/sqlite/web/worker.js.map +1 -1
  149. package/dist/local/store/web-sqlite/adapter.d.ts +3 -2
  150. package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
  151. package/dist/local/store/web-sqlite/adapter.js +12 -2
  152. package/dist/local/store/web-sqlite/adapter.js.map +1 -1
  153. package/dist/remote/relay/types.d.ts +4 -2
  154. package/dist/remote/relay/types.d.ts.map +1 -1
  155. package/dist/types/api.d.ts +20 -4
  156. package/dist/types/api.d.ts.map +1 -1
  157. package/docs/ASSURANCE.md +25 -7
  158. package/docs/DEVIATIONS.md +35 -3
  159. package/docs/ERROR_HANDLING.md +8 -6
  160. package/docs/GETTING_STARTED.md +15 -8
  161. package/docs/INTERFACES.md +3 -1
  162. package/docs/PACKAGE_SURFACE.md +1 -0
  163. package/docs/SECURITY.md +23 -5
  164. package/keys/README.md +3 -1
  165. package/local/store/README.md +92 -12
  166. package/local/store/expo/README.md +63 -6
  167. package/local/store/key-value/README.md +3 -2
  168. package/local/store/node/README.md +68 -6
  169. package/local/store/react-native/README.md +62 -4
  170. package/local/store/web-sqlite/README.md +73 -4
  171. 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. Default:
47
- `open-e2ee-signal-protocol.db`.
46
+ Letters, digits, `.`, `_`, and `-` only, and no `.oe2e-convert` ending.
47
+ Default: `open-e2ee-signal-protocol.db`.
48
48
  - `vault`: the `SignalProtocolLocalSecretVault` that holds the database key.
49
49
  Default: `ExpoSecureStoreSignalProtocolSecretVault`.
50
50
  - `encryptionAtRest`: pass `false` to store the database without encryption.
51
51
  The store then does not use the vault, and it logs a warning at each open. A
52
- database created with one setting does not open with the other. Default:
53
- `true`, and the open fails when the build has no SQLCipher (see
54
- [Web](#web)).
52
+ database created with one setting does not open with the other, except
53
+ through `convertPlaintext`. Default: `true`, and the open fails when the
54
+ build has no SQLCipher (see [Web](#web)).
55
+ - `convertPlaintext`: pass `true` to convert a plaintext database to an
56
+ encrypted one at an encrypted open. See
57
+ [Convert a plaintext store](#convert-a-plaintext-store). Default: `false`.
55
58
  - `logger`: receives the warning of each open without encryption.
56
59
 
57
60
  A store holds its name until `close()`. In one process, the opens and resets
@@ -69,6 +72,7 @@ web implementation. On the web, `expoStore()` and `resetExpoStore()` therefore
69
72
  fail with `SqliteEncryptionUnavailableError` (`KEY_STORAGE_ERROR`). They fail
70
73
  before they use the vault or a database file, also when the app passes its own
71
74
  vault. A native build without the `useSQLCipher` option fails in the same way.
75
+ An open with `convertPlaintext: true` also fails in this way, before any write.
72
76
 
73
77
  For an encrypted store in a browser, use
74
78
  [`./local/store/web-sqlite`](../web-sqlite/README.md). `encryptionAtRest: false`
@@ -83,7 +87,9 @@ the old file. Restore the vault entry, or call `resetExpoStore()`.
83
87
 
84
88
  A file created with `encryptionAtRest: false` fails an open without that
85
89
  option with `SqliteKeyMismatchError` (`KEY_STORAGE_ERROR`), not
86
- `LOCAL_STORE_KEY_LOST`. Open it with the setting that created it.
90
+ `LOCAL_STORE_KEY_LOST`. Open it with the setting that created it, or convert
91
+ it to keep its data in an encrypted store (see
92
+ [Convert a plaintext store](#convert-a-plaintext-store)).
87
93
 
88
94
  `resetExpoStore()` deletes the database file, then writes a new key, then
89
95
  returns the open, empty store. It takes the same options as `expoStore`. Close
@@ -92,6 +98,57 @@ the open store of the name first.
92
98
  `clearAllKeys()` on an open store empties every SDK table and keeps the file
93
99
  and its key. `resetExpoStore()` is the full teardown.
94
100
 
101
+ ## Convert a plaintext store
102
+
103
+ An encrypted open with `convertPlaintext: true` converts a database that was
104
+ created with `encryptionAtRest: false`:
105
+
106
+ <!-- doc-snippet:skip requires-external-context -->
107
+
108
+ ```ts
109
+ import { expoStore } from '@open-e2ee/signal-protocol-sdk/local/store/expo';
110
+
111
+ const store = await expoStore({ convertPlaintext: true });
112
+ ```
113
+
114
+ The store keeps every row and its schema version, then applies the
115
+ migrations of this SDK. The option does nothing on an encrypted database or
116
+ when no file exists. With `encryptionAtRest: false`, the option fails with
117
+ `INVALID_STATE`.
118
+
119
+ The conversion writes a new key to a pending vault slot. It copies the
120
+ database to the encrypted temporary file `<name>.oe2e-convert` in one
121
+ transaction. Then it deletes the plaintext file and copies the temporary file
122
+ back. The delete of the plaintext file is the commit point. The conversion
123
+ needs free disk space for one more copy of the database. It runs inside the
124
+ open, one at a time with the other opens and resets of the name.
125
+
126
+ The conversion refuses, with `INVALID_STATE`, a database that holds an
127
+ application table, a BLOB value, or an integer outside the safe JavaScript
128
+ range. It also refuses a file with no SDK schema. A file from a newer SDK
129
+ fails as at any open. A refusal changes nothing.
130
+
131
+ A crash or an error before the copy commits leaves the plaintext file. The
132
+ next open with the option starts again with a new key. A crash after the
133
+ commit point leaves the encrypted copy. The next encrypted open finishes the
134
+ conversion, with or without the option. While the temporary file exists,
135
+ an open or a reset with `encryptionAtRest: false` fails with `INVALID_STATE`.
136
+
137
+ The open fails with `INVALID_STATE` and names both files when the plaintext
138
+ file and a complete encrypted copy both exist. A crash between the end of the
139
+ copy and the commit point leaves this state. So does an older SDK that opens
140
+ the store after the commit point. Delete the plaintext file and its `-wal`,
141
+ `-shm`, and `-journal` files, then open again. The open then finishes the
142
+ conversion from the copy. An
143
+ encrypted reset also ends any conversion, and it deletes all data.
144
+
145
+ Residual risks:
146
+
147
+ - The disk blocks of the old plaintext file can keep plaintext until the file
148
+ system reuses them. So can device backups. The SDK cannot erase them.
149
+ - An SDK older than this release does not know the temporary file. If it
150
+ opens the store after the commit point, it creates a new empty store.
151
+
95
152
  ## Data protection
96
153
 
97
154
  Every table in this store holds material that must not leave the device.
@@ -144,8 +144,9 @@ list, or open a separate Realm file for the store.
144
144
 
145
145
  The adapter is tested with the conformance kit on realm 20.2.0 in Node,
146
146
  including a reopen of the same Realm file. Manual checks ran the kit in
147
- React Native apps in the iOS 26.2 simulator and in an Android emulator. All
148
- 13 cases passed in each. The SDK does not test the adapter
147
+ React Native apps in the iOS 26.2 simulator and in an Android emulator. Those
148
+ manual runs used an earlier version of the kit with thirteen cases, and all
149
+ thirteen passed in each. The SDK does not test the adapter
149
150
  on a physical device. Run the conformance kit on your target devices with
150
151
  your Realm build before you ship.
151
152
 
@@ -50,13 +50,16 @@ Options:
50
50
  safeStorage vault, or `app-vault`. A vault that declares no custody counts
51
51
  as `same-origin`, and the level is then `co-located`.
52
52
  - `name`: the database file name in `directory`. Letters, digits, `.`, `_`,
53
- and `-` only, and no `.lock`, `-wal`, `-shm`, or `-journal` ending.
54
- Default: `open-e2ee-signal-protocol.db`.
53
+ and `-` only, and no `.lock`, `-wal`, `-shm`, `-journal`, or
54
+ `.oe2e-convert` ending. Default: `open-e2ee-signal-protocol.db`.
55
55
  - `encryptionAtRest`: pass `false` to store the database without encryption.
56
56
  The store then does not use the vault, and it logs a warning at each open. A
57
- database created with one setting does not open with the other. The store
58
- reports `none` protection, so the client keeps no resendable content.
59
- Default: `true`.
57
+ database created with one setting does not open with the other, except
58
+ through `convertPlaintext`. The store reports `none` protection, so the
59
+ client keeps no resendable content. Default: `true`.
60
+ - `convertPlaintext`: pass `true` to convert a plaintext database to an
61
+ encrypted one at an encrypted open. See
62
+ [Convert a plaintext store](#convert-a-plaintext-store). Default: `false`.
60
63
  - `logger`: receives the warning of each open without encryption.
61
64
 
62
65
  Keep application tables in a separate database file. The SDK database holds
@@ -195,9 +198,13 @@ if (key) {
195
198
  }
196
199
  ```
197
200
 
201
+ Finish a conversion before a move. The recipe moves only the main key, so a
202
+ conversion that a move interrupts cannot finish.
203
+
198
204
  A file created with `encryptionAtRest: false` fails an open without that
199
205
  option with `SqliteKeyMismatchError` (`KEY_STORAGE_ERROR`), not
200
- `LOCAL_STORE_KEY_LOST`. Open it with the setting that created it.
206
+ `LOCAL_STORE_KEY_LOST`. Open it with the setting that created it, or convert
207
+ it to keep its data in an encrypted store.
201
208
 
202
209
  `resetNodeStore()` deletes the database file, then writes a new key, then
203
210
  returns the open, empty store. It takes the same options as `nodeStore`. Close
@@ -206,6 +213,61 @@ the open store of the file first.
206
213
  `clearAllKeys()` on an open store empties every SDK table and keeps the file
207
214
  and its key. `resetNodeStore()` is the full teardown.
208
215
 
216
+ ## Convert a plaintext store
217
+
218
+ An encrypted open with `convertPlaintext: true` converts a database that was
219
+ created with `encryptionAtRest: false`:
220
+
221
+ <!-- doc-snippet:skip requires-external-context -->
222
+
223
+ ```ts
224
+ import { nodeStore } from '@open-e2ee/signal-protocol-sdk/local/store/node';
225
+
226
+ const store = await nodeStore({ directory, vault, convertPlaintext: true });
227
+ ```
228
+
229
+ The store keeps every row and its schema version, then applies the
230
+ migrations of this SDK. The option does nothing on an encrypted database or
231
+ when no file exists. With `encryptionAtRest: false`, the option fails with
232
+ `INVALID_STATE`.
233
+
234
+ The conversion writes a new key to a pending vault slot. It copies the
235
+ database to the encrypted temporary file `<name>.oe2e-convert` in one
236
+ transaction. Then it deletes the plaintext file and copies the temporary file
237
+ back. The delete of the plaintext file is the commit point. The conversion
238
+ needs free disk space for one more copy of the database. It runs inside the
239
+ owner lock.
240
+
241
+ The conversion refuses, with `INVALID_STATE`, a database that holds an
242
+ application table, a BLOB value, or an integer outside the safe JavaScript
243
+ range. It also refuses a file with no SDK schema. A file from a newer SDK
244
+ fails as at any open. A refusal changes nothing.
245
+
246
+ A crash or an error before the copy commits leaves the plaintext file. The
247
+ next open with the option starts again with a new key. A crash after the
248
+ commit point leaves the encrypted copy. The next encrypted open finishes the
249
+ conversion, with or without the option. While the temporary file exists,
250
+ an open or a reset with `encryptionAtRest: false` fails with `INVALID_STATE`.
251
+
252
+ The open fails with `INVALID_STATE` and names both files when the plaintext
253
+ file and a complete encrypted copy both exist. A crash between the end of the
254
+ copy and the commit point leaves this state. So does an older SDK that opens
255
+ the store after the commit point. Delete the plaintext file and its `-wal`,
256
+ `-shm`, and `-journal` files, then open again. The open then finishes the
257
+ conversion from the copy. An
258
+ encrypted reset also ends any conversion, and it deletes all data.
259
+
260
+ Residual risks:
261
+
262
+ - The disk blocks of the old plaintext file can keep plaintext until the file
263
+ system reuses them. So can backups and file system snapshots. The SDK cannot
264
+ erase them.
265
+ - A directory move during a conversion is not supported. The open then fails
266
+ with `INVALID_STATE`, because the temporary file has no key at the new path.
267
+ Move the directory back and open it there.
268
+ - An SDK older than this release does not know the temporary file. If it
269
+ opens the store after the commit point, it creates a new empty store.
270
+
209
271
  ## Data protection
210
272
 
211
273
  Every table in this store holds material that must not leave the device.
@@ -70,14 +70,19 @@ Options:
70
70
 
71
71
  - `name`: the database file name in the op-sqlite default location (the
72
72
  Library directory on iOS, the databases directory on Android). Letters,
73
- digits, `.`, `_`, and `-` only. Default: `open-e2ee-signal-protocol.db`.
73
+ digits, `.`, `_`, and `-` only, and no `.oe2e-convert` ending. Default:
74
+ `open-e2ee-signal-protocol.db`.
74
75
  - `vault`: the `SignalProtocolLocalSecretVault` that holds the database key.
75
76
  Default: `ReactNativeKeychainSignalProtocolSecretVault`, which keeps the key
76
77
  on this device only (see the [vault guide](../../vault/README.md)).
77
78
  - `encryptionAtRest`: pass `false` to store the database without encryption.
78
79
  The store then does not use the vault, and it logs a warning at each open. A
79
- database created with one setting does not open with the other. Default:
80
- `true`, and the open fails when op-sqlite is not built with SQLCipher.
80
+ database created with one setting does not open with the other, except
81
+ through `convertPlaintext`. Default: `true`, and the open fails when
82
+ op-sqlite is not built with SQLCipher.
83
+ - `convertPlaintext`: pass `true` to convert a plaintext database to an
84
+ encrypted one at an encrypted open. See
85
+ [Convert a plaintext store](#convert-a-plaintext-store). Default: `false`.
81
86
  - `logger`: receives the warning of each open without encryption.
82
87
 
83
88
  A store holds its name until `close()`. In one process, the opens and resets
@@ -97,7 +102,9 @@ A new key cannot read the old file. Restore the vault entry, or call
97
102
 
98
103
  A file created with `encryptionAtRest: false` fails an open without that
99
104
  option with `SqliteKeyMismatchError` (`KEY_STORAGE_ERROR`), not
100
- `LOCAL_STORE_KEY_LOST`. Open it with the setting that created it.
105
+ `LOCAL_STORE_KEY_LOST`. Open it with the setting that created it, or convert
106
+ it to keep its data in an encrypted store (see
107
+ [Convert a plaintext store](#convert-a-plaintext-store)).
101
108
 
102
109
  `resetReactNativeStore()` deletes the database file, then writes a new
103
110
  key, then returns the open, empty store. It takes the same options as
@@ -106,6 +113,57 @@ key, then returns the open, empty store. It takes the same options as
106
113
  `clearAllKeys()` on an open store empties every SDK table and keeps the file
107
114
  and its key. `resetReactNativeStore()` is the full teardown.
108
115
 
116
+ ## Convert a plaintext store
117
+
118
+ An encrypted open with `convertPlaintext: true` converts a database that was
119
+ created with `encryptionAtRest: false`:
120
+
121
+ <!-- doc-snippet:skip requires-external-context -->
122
+
123
+ ```ts
124
+ import { reactNativeStore } from '@open-e2ee/signal-protocol-sdk/local/store/react-native';
125
+
126
+ const store = await reactNativeStore({ convertPlaintext: true });
127
+ ```
128
+
129
+ The store keeps every row and its schema version, then applies the
130
+ migrations of this SDK. The option does nothing on an encrypted database or
131
+ when no file exists. With `encryptionAtRest: false`, the option fails with
132
+ `INVALID_STATE`.
133
+
134
+ The conversion writes a new key to a pending vault slot. It copies the
135
+ database to the encrypted temporary file `<name>.oe2e-convert` in one
136
+ transaction. Then it deletes the plaintext file and copies the temporary file
137
+ back. The delete of the plaintext file is the commit point. The conversion
138
+ needs free disk space for one more copy of the database. It runs inside the
139
+ open, one at a time with the other opens and resets of the name.
140
+
141
+ The conversion refuses, with `INVALID_STATE`, a database that holds an
142
+ application table, a BLOB value, or an integer outside the safe JavaScript
143
+ range. It also refuses a file with no SDK schema. A file from a newer SDK
144
+ fails as at any open. A refusal changes nothing.
145
+
146
+ A crash or an error before the copy commits leaves the plaintext file. The
147
+ next open with the option starts again with a new key. A crash after the
148
+ commit point leaves the encrypted copy. The next encrypted open finishes the
149
+ conversion, with or without the option. While the temporary file exists,
150
+ an open or a reset with `encryptionAtRest: false` fails with `INVALID_STATE`.
151
+
152
+ The open fails with `INVALID_STATE` and names both files when the plaintext
153
+ file and a complete encrypted copy both exist. A crash between the end of the
154
+ copy and the commit point leaves this state. So does an older SDK that opens
155
+ the store after the commit point. Delete the plaintext file and its `-wal`,
156
+ `-shm`, and `-journal` files, then open again. The open then finishes the
157
+ conversion from the copy. An
158
+ encrypted reset also ends any conversion, and it deletes all data.
159
+
160
+ Residual risks:
161
+
162
+ - The disk blocks of the old plaintext file can keep plaintext until the file
163
+ system reuses them. So can device backups. The SDK cannot erase them.
164
+ - An SDK older than this release does not know the temporary file. If it
165
+ opens the store after the commit point, it creates a new empty store.
166
+
109
167
  ## Data protection
110
168
 
111
169
  Every table in this store holds material that must not leave the device.
@@ -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 `-`. It also names the vault slot of the key.
44
- Default: `open-e2ee-signal-protocol.db`.
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. Default:
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": "12.0.0",
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"