@open-e2ee/signal-protocol-sdk 12.0.1 → 13.1.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 (165) hide show
  1. package/ADAPTERS.md +3 -0
  2. package/ARCHITECTURE.md +4 -4
  3. package/CHANGELOG.md +141 -0
  4. package/README.md +1 -1
  5. package/SECURITY.md +2 -2
  6. package/client/README.md +40 -0
  7. package/device/README.md +40 -4
  8. package/dist/client/client.d.ts +8 -0
  9. package/dist/client/client.d.ts.map +1 -1
  10. package/dist/client/client.js +19 -1
  11. package/dist/client/client.js.map +1 -1
  12. package/dist/client/config.d.ts +6 -2
  13. package/dist/client/config.d.ts.map +1 -1
  14. package/dist/client/config.js.map +1 -1
  15. package/dist/client/event-hooks.d.ts +28 -0
  16. package/dist/client/event-hooks.d.ts.map +1 -1
  17. package/dist/client/event-hooks.js +1 -0
  18. package/dist/client/event-hooks.js.map +1 -1
  19. package/dist/client/group-init-status.d.ts +21 -0
  20. package/dist/client/group-init-status.d.ts.map +1 -0
  21. package/dist/client/group-init-status.js +156 -0
  22. package/dist/client/group-init-status.js.map +1 -0
  23. package/dist/client/hosted-device-link-transport.d.ts +11 -0
  24. package/dist/client/hosted-device-link-transport.d.ts.map +1 -0
  25. package/dist/client/hosted-device-link-transport.js +25 -0
  26. package/dist/client/hosted-device-link-transport.js.map +1 -0
  27. package/dist/client/hosted-device-link.d.ts +97 -0
  28. package/dist/client/hosted-device-link.d.ts.map +1 -0
  29. package/dist/client/hosted-device-link.js +149 -0
  30. package/dist/client/hosted-device-link.js.map +1 -0
  31. package/dist/client/hosted-http-error.d.ts +30 -0
  32. package/dist/client/hosted-http-error.d.ts.map +1 -0
  33. package/dist/client/hosted-http-error.js +34 -0
  34. package/dist/client/hosted-http-error.js.map +1 -0
  35. package/dist/client/hosted-presence.js +1 -1
  36. package/dist/client/hosted-presence.js.map +1 -1
  37. package/dist/client/hosted-profile-keys.js +1 -1
  38. package/dist/client/hosted-profile-keys.js.map +1 -1
  39. package/dist/client/hosted-sandbox-identity.d.ts +3 -3
  40. package/dist/client/hosted-sandbox-identity.js +3 -3
  41. package/dist/client/hosted-transport.d.ts +12 -13
  42. package/dist/client/hosted-transport.d.ts.map +1 -1
  43. package/dist/client/hosted-transport.js +111 -17
  44. package/dist/client/hosted-transport.js.map +1 -1
  45. package/dist/client/hosted.d.ts +57 -8
  46. package/dist/client/hosted.d.ts.map +1 -1
  47. package/dist/client/hosted.js +170 -19
  48. package/dist/client/hosted.js.map +1 -1
  49. package/dist/client/index.d.ts +2 -1
  50. package/dist/client/index.d.ts.map +1 -1
  51. package/dist/client/index.js +1 -1
  52. package/dist/client/index.js.map +1 -1
  53. package/dist/client/receive-queue.d.ts +4 -2
  54. package/dist/client/receive-queue.d.ts.map +1 -1
  55. package/dist/client/receive-queue.js +26 -22
  56. package/dist/client/receive-queue.js.map +1 -1
  57. package/dist/index.d.ts +2 -1
  58. package/dist/index.d.ts.map +1 -1
  59. package/dist/index.js +1 -1
  60. package/dist/index.js.map +1 -1
  61. package/dist/local/store/conformance/cases/ciphertext.d.ts +7 -0
  62. package/dist/local/store/conformance/cases/ciphertext.d.ts.map +1 -0
  63. package/dist/local/store/conformance/cases/ciphertext.js +55 -0
  64. package/dist/local/store/conformance/cases/ciphertext.js.map +1 -0
  65. package/dist/local/store/conformance/cases/durability.d.ts +6 -0
  66. package/dist/local/store/conformance/cases/durability.d.ts.map +1 -0
  67. package/dist/local/store/conformance/cases/durability.js +34 -0
  68. package/dist/local/store/conformance/cases/durability.js.map +1 -0
  69. package/dist/local/store/conformance/cases/identity.d.ts +7 -0
  70. package/dist/local/store/conformance/cases/identity.d.ts.map +1 -0
  71. package/dist/local/store/conformance/cases/identity.js +84 -0
  72. package/dist/local/store/conformance/cases/identity.js.map +1 -0
  73. package/dist/local/store/conformance/cases/metadata.d.ts +7 -0
  74. package/dist/local/store/conformance/cases/metadata.d.ts.map +1 -0
  75. package/dist/local/store/conformance/cases/metadata.js +48 -0
  76. package/dist/local/store/conformance/cases/metadata.js.map +1 -0
  77. package/dist/local/store/conformance/cases/protection.d.ts +7 -0
  78. package/dist/local/store/conformance/cases/protection.d.ts.map +1 -0
  79. package/dist/local/store/conformance/cases/protection.js +14 -0
  80. package/dist/local/store/conformance/cases/protection.js.map +1 -0
  81. package/dist/local/store/conformance/cases/receive-work.d.ts +8 -0
  82. package/dist/local/store/conformance/cases/receive-work.d.ts.map +1 -0
  83. package/dist/local/store/conformance/cases/receive-work.js +152 -0
  84. package/dist/local/store/conformance/cases/receive-work.js.map +1 -0
  85. package/dist/local/store/conformance/cases/sender-key.d.ts +7 -0
  86. package/dist/local/store/conformance/cases/sender-key.d.ts.map +1 -0
  87. package/dist/local/store/conformance/cases/sender-key.js +59 -0
  88. package/dist/local/store/conformance/cases/sender-key.js.map +1 -0
  89. package/dist/local/store/conformance/cases/session-trust.d.ts +7 -0
  90. package/dist/local/store/conformance/cases/session-trust.d.ts.map +1 -0
  91. package/dist/local/store/conformance/cases/session-trust.js +64 -0
  92. package/dist/local/store/conformance/cases/session-trust.js.map +1 -0
  93. package/dist/local/store/conformance/checks.d.ts +15 -0
  94. package/dist/local/store/conformance/checks.d.ts.map +1 -0
  95. package/dist/local/store/conformance/checks.js +67 -0
  96. package/dist/local/store/conformance/checks.js.map +1 -0
  97. package/dist/local/store/conformance/index.d.ts +30 -0
  98. package/dist/local/store/conformance/index.d.ts.map +1 -0
  99. package/dist/local/store/conformance/index.js +29 -0
  100. package/dist/local/store/conformance/index.js.map +1 -0
  101. package/dist/local/store/conformance/records.d.ts +36 -0
  102. package/dist/local/store/conformance/records.d.ts.map +1 -0
  103. package/dist/local/store/conformance/records.js +109 -0
  104. package/dist/local/store/conformance/records.js.map +1 -0
  105. package/dist/local/store/conformance/run.d.ts +24 -0
  106. package/dist/local/store/conformance/run.d.ts.map +1 -0
  107. package/dist/local/store/conformance/run.js +156 -0
  108. package/dist/local/store/conformance/run.js.map +1 -0
  109. package/dist/local/store/conformance/types.d.ts +55 -0
  110. package/dist/local/store/conformance/types.d.ts.map +1 -0
  111. package/dist/local/store/conformance/types.js +6 -0
  112. package/dist/local/store/conformance/types.js.map +1 -0
  113. package/dist/local/store/expo/adapter.d.ts +2 -1
  114. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  115. package/dist/local/store/expo/adapter.js.map +1 -1
  116. package/dist/local/store/node/adapter.d.ts +2 -2
  117. package/dist/local/store/react-native/adapter.d.ts +2 -1
  118. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  119. package/dist/local/store/react-native/adapter.js.map +1 -1
  120. package/dist/local/store/sqlite/convert-plaintext.d.ts +62 -0
  121. package/dist/local/store/sqlite/convert-plaintext.d.ts.map +1 -0
  122. package/dist/local/store/sqlite/convert-plaintext.js +236 -0
  123. package/dist/local/store/sqlite/convert-plaintext.js.map +1 -0
  124. package/dist/local/store/sqlite/encryption.d.ts +21 -0
  125. package/dist/local/store/sqlite/encryption.d.ts.map +1 -1
  126. package/dist/local/store/sqlite/encryption.js.map +1 -1
  127. package/dist/local/store/sqlite/errors.d.ts.map +1 -1
  128. package/dist/local/store/sqlite/errors.js +2 -1
  129. package/dist/local/store/sqlite/errors.js.map +1 -1
  130. package/dist/local/store/sqlite/key-storage/identity-keys.d.ts +3 -1
  131. package/dist/local/store/sqlite/key-storage/identity-keys.d.ts.map +1 -1
  132. package/dist/local/store/sqlite/key-storage/identity-keys.js +3 -1
  133. package/dist/local/store/sqlite/key-storage/identity-keys.js.map +1 -1
  134. package/dist/local/store/sqlite/open-store.d.ts +36 -4
  135. package/dist/local/store/sqlite/open-store.d.ts.map +1 -1
  136. package/dist/local/store/sqlite/open-store.js +326 -21
  137. package/dist/local/store/sqlite/open-store.js.map +1 -1
  138. package/dist/local/store/sqlite/web/worker.d.ts +5 -0
  139. package/dist/local/store/sqlite/web/worker.d.ts.map +1 -1
  140. package/dist/local/store/sqlite/web/worker.js +99 -20
  141. package/dist/local/store/sqlite/web/worker.js.map +1 -1
  142. package/dist/local/store/web-sqlite/adapter.d.ts +3 -2
  143. package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
  144. package/dist/local/store/web-sqlite/adapter.js +12 -2
  145. package/dist/local/store/web-sqlite/adapter.js.map +1 -1
  146. package/dist/remote/relay/types.d.ts +4 -2
  147. package/dist/remote/relay/types.d.ts.map +1 -1
  148. package/dist/types/api.d.ts +20 -4
  149. package/dist/types/api.d.ts.map +1 -1
  150. package/docs/ASSURANCE.md +25 -7
  151. package/docs/DEVIATIONS.md +35 -3
  152. package/docs/ERROR_HANDLING.md +8 -6
  153. package/docs/GETTING_STARTED.md +25 -8
  154. package/docs/INTERFACES.md +3 -1
  155. package/docs/PACKAGE_SURFACE.md +1 -0
  156. package/docs/RECIPES.md +44 -0
  157. package/docs/SECURITY.md +23 -5
  158. package/keys/README.md +3 -1
  159. package/local/store/README.md +92 -12
  160. package/local/store/expo/README.md +63 -6
  161. package/local/store/key-value/README.md +3 -2
  162. package/local/store/node/README.md +68 -6
  163. package/local/store/react-native/README.md +62 -4
  164. package/local/store/web-sqlite/README.md +101 -4
  165. package/package.json +5 -1
@@ -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,97 @@ 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
+ ## Damaged database file
72
+
73
+ The store does not repair a damaged database file. This includes a file that
74
+ SDK 12.0.0 or earlier damaged when a tab closed inside a commit, or when an
75
+ open used the wrong key state. The open reads only some pages of the file. It
76
+ does not check every page. Thus the result depends on the damaged pages:
77
+
78
+ - When the open cannot read the file header with its key and setting, it
79
+ rejects with `SqliteKeyMismatchError` (`KEY_STORAGE_ERROR`). Its message
80
+ starts with `The sqlite3mc-wasm database exists but cannot be read with this
81
+ key and encryption setting`. The store cannot tell a damaged file from a
82
+ wrong key or from the other `encryptionAtRest` setting.
83
+ - When a read of the open fails with `database disk image is malformed`, the
84
+ open rejects with an `Error` whose message holds that SQLite text.
85
+ - When the open reads no damaged page, the open succeeds. A later call can
86
+ then fail on the damaged data.
87
+
88
+ To recover, delete the file and link the device again:
89
+
90
+ 1. Close the store of the name in every tab and worker of the origin.
91
+ 2. Call `resetWebSqliteStore()` with the same options. The reset deletes the
92
+ file, creates a new key, and returns the open, empty store. The identity
93
+ and the sessions of the device go with the file.
94
+ 3. Put the account identity into the new store, then call
95
+ `linkHostedRelayDevice()` with it. This needs another device that holds the
96
+ account identity. See
97
+ [Link a device](../../../device/README.md#link-a-device).
98
+
99
+ ## Convert a plaintext store
100
+
101
+ An encrypted open with `convertPlaintext: true` converts a database that was
102
+ created with `encryptionAtRest: false`:
103
+
104
+ <!-- doc-snippet:skip requires-external-context -->
105
+
106
+ ```ts
107
+ import { webSqliteStore } from '@open-e2ee/signal-protocol-sdk/local/store/web-sqlite';
108
+
109
+ const store = await webSqliteStore({ convertPlaintext: true });
110
+ ```
111
+
112
+ The store keeps every row and its schema version, then applies the
113
+ migrations of this SDK. The option does nothing on an encrypted database or
114
+ when no database exists. With `encryptionAtRest: false`, the option fails with
115
+ `INVALID_STATE`.
116
+
117
+ A database created with `encryptionAtRest: false` fails an open without the
118
+ option with `SqliteKeyMismatchError` (`KEY_STORAGE_ERROR`). Open it with the
119
+ setting that created it, or convert it to keep its data in an encrypted store.
120
+
121
+ The conversion writes a new key to a pending vault slot. It copies the
122
+ database to the encrypted temporary database `<name>.oe2e-convert` in one
123
+ transaction. Then it deletes the plaintext database and copies the temporary
124
+ database back. The delete of the plaintext database is the commit point. The
125
+ conversion needs storage quota for one more copy of the database.
126
+
127
+ Each database file has its own OPFS directory, `.open-e2ee-sqlite-<name>`.
128
+ When the store removes a database file, it also removes that directory if no
129
+ other file of the store is in it. This applies to the conversion and to a
130
+ reset. So a finished conversion leaves no directory for
131
+ `<name>.oe2e-convert`. If the browser does not remove the directory, the
132
+ directory stays, and the next use of the name uses it again. A check for a
133
+ database that does not exist leaves no directory.
134
+
135
+ The conversion needs the store of the name in no other tab or worker of the
136
+ origin. While another context has it open, the conversion fails at once with
137
+ `INVALID_STATE` and changes nothing. A name longer than 51 characters also
138
+ fails with `INVALID_STATE` before any write.
139
+
140
+ The conversion refuses, with `INVALID_STATE`, a database that holds an
141
+ application table, a BLOB value, or an integer outside the safe JavaScript
142
+ range. It also refuses a database with no SDK schema. A database from a newer
143
+ SDK fails as at any open. A refusal changes nothing.
144
+
145
+ A crash or an error before the copy commits leaves the plaintext database.
146
+ The next open with the option starts again with a new key. A crash after the
147
+ commit point leaves the encrypted copy. The next encrypted open finishes the
148
+ conversion, with or without the option. While the temporary database exists,
149
+ an open or a reset with `encryptionAtRest: false` fails with `INVALID_STATE`.
150
+
151
+ The open fails with `INVALID_STATE` and names both databases when the
152
+ plaintext database and a complete encrypted copy both exist. A crash between
153
+ the end of the copy and the commit point leaves this state. So does an older
154
+ SDK that opens the store after the commit point. The store has no call that
155
+ deletes one database of the pair. An encrypted reset ends the state, and it
156
+ deletes all data.
157
+
158
+ Residual risk: an SDK older than this release does not know the temporary
159
+ database. If it opens the store after the commit point, it creates a new
160
+ empty store.
161
+
67
162
  ## Tabs
68
163
 
69
164
  Each tab opens its own store, and the tabs of an origin share the database.
@@ -83,6 +178,8 @@ transaction. Each tab reads the writes of the other tabs.
83
178
  - `OPFS_FILE_BUSY` means that another tab or worker of the origin still holds
84
179
  the files, for example a tab that is closing. The file is unchanged. Retry
85
180
  the open later.
181
+ The store already retries a transient failure of the origin private file
182
+ system a few times before it rejects with this code.
86
183
 
87
184
  ## Full storage
88
185
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "12.0.1",
3
+ "version": "13.1.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"