@open-e2ee/signal-protocol-sdk 12.0.1 → 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 (157) hide show
  1. package/ADAPTERS.md +3 -0
  2. package/ARCHITECTURE.md +4 -4
  3. package/CHANGELOG.md +132 -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 +29 -3
  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/event-hooks.d.ts +28 -0
  13. package/dist/client/event-hooks.d.ts.map +1 -1
  14. package/dist/client/event-hooks.js +1 -0
  15. package/dist/client/event-hooks.js.map +1 -1
  16. package/dist/client/group-init-status.d.ts +21 -0
  17. package/dist/client/group-init-status.d.ts.map +1 -0
  18. package/dist/client/group-init-status.js +156 -0
  19. package/dist/client/group-init-status.js.map +1 -0
  20. package/dist/client/hosted-device-link.d.ts +97 -0
  21. package/dist/client/hosted-device-link.d.ts.map +1 -0
  22. package/dist/client/hosted-device-link.js +149 -0
  23. package/dist/client/hosted-device-link.js.map +1 -0
  24. package/dist/client/hosted-http-error.d.ts +30 -0
  25. package/dist/client/hosted-http-error.d.ts.map +1 -0
  26. package/dist/client/hosted-http-error.js +34 -0
  27. package/dist/client/hosted-http-error.js.map +1 -0
  28. package/dist/client/hosted-presence.js +1 -1
  29. package/dist/client/hosted-presence.js.map +1 -1
  30. package/dist/client/hosted-profile-keys.js +1 -1
  31. package/dist/client/hosted-profile-keys.js.map +1 -1
  32. package/dist/client/hosted-sandbox-identity.d.ts +3 -3
  33. package/dist/client/hosted-sandbox-identity.js +3 -3
  34. package/dist/client/hosted-transport.d.ts +0 -11
  35. package/dist/client/hosted-transport.d.ts.map +1 -1
  36. package/dist/client/hosted-transport.js +1 -15
  37. package/dist/client/hosted-transport.js.map +1 -1
  38. package/dist/client/hosted.d.ts +53 -7
  39. package/dist/client/hosted.d.ts.map +1 -1
  40. package/dist/client/hosted.js +158 -17
  41. package/dist/client/hosted.js.map +1 -1
  42. package/dist/client/index.d.ts +2 -1
  43. package/dist/client/index.d.ts.map +1 -1
  44. package/dist/client/index.js +1 -1
  45. package/dist/client/index.js.map +1 -1
  46. package/dist/client/receive-queue.d.ts +4 -2
  47. package/dist/client/receive-queue.d.ts.map +1 -1
  48. package/dist/client/receive-queue.js +26 -22
  49. package/dist/client/receive-queue.js.map +1 -1
  50. package/dist/index.d.ts +2 -1
  51. package/dist/index.d.ts.map +1 -1
  52. package/dist/index.js +1 -1
  53. package/dist/index.js.map +1 -1
  54. package/dist/local/store/conformance/cases/ciphertext.d.ts +7 -0
  55. package/dist/local/store/conformance/cases/ciphertext.d.ts.map +1 -0
  56. package/dist/local/store/conformance/cases/ciphertext.js +55 -0
  57. package/dist/local/store/conformance/cases/ciphertext.js.map +1 -0
  58. package/dist/local/store/conformance/cases/durability.d.ts +6 -0
  59. package/dist/local/store/conformance/cases/durability.d.ts.map +1 -0
  60. package/dist/local/store/conformance/cases/durability.js +34 -0
  61. package/dist/local/store/conformance/cases/durability.js.map +1 -0
  62. package/dist/local/store/conformance/cases/identity.d.ts +7 -0
  63. package/dist/local/store/conformance/cases/identity.d.ts.map +1 -0
  64. package/dist/local/store/conformance/cases/identity.js +84 -0
  65. package/dist/local/store/conformance/cases/identity.js.map +1 -0
  66. package/dist/local/store/conformance/cases/metadata.d.ts +7 -0
  67. package/dist/local/store/conformance/cases/metadata.d.ts.map +1 -0
  68. package/dist/local/store/conformance/cases/metadata.js +48 -0
  69. package/dist/local/store/conformance/cases/metadata.js.map +1 -0
  70. package/dist/local/store/conformance/cases/protection.d.ts +7 -0
  71. package/dist/local/store/conformance/cases/protection.d.ts.map +1 -0
  72. package/dist/local/store/conformance/cases/protection.js +14 -0
  73. package/dist/local/store/conformance/cases/protection.js.map +1 -0
  74. package/dist/local/store/conformance/cases/receive-work.d.ts +8 -0
  75. package/dist/local/store/conformance/cases/receive-work.d.ts.map +1 -0
  76. package/dist/local/store/conformance/cases/receive-work.js +152 -0
  77. package/dist/local/store/conformance/cases/receive-work.js.map +1 -0
  78. package/dist/local/store/conformance/cases/sender-key.d.ts +7 -0
  79. package/dist/local/store/conformance/cases/sender-key.d.ts.map +1 -0
  80. package/dist/local/store/conformance/cases/sender-key.js +59 -0
  81. package/dist/local/store/conformance/cases/sender-key.js.map +1 -0
  82. package/dist/local/store/conformance/cases/session-trust.d.ts +7 -0
  83. package/dist/local/store/conformance/cases/session-trust.d.ts.map +1 -0
  84. package/dist/local/store/conformance/cases/session-trust.js +64 -0
  85. package/dist/local/store/conformance/cases/session-trust.js.map +1 -0
  86. package/dist/local/store/conformance/checks.d.ts +15 -0
  87. package/dist/local/store/conformance/checks.d.ts.map +1 -0
  88. package/dist/local/store/conformance/checks.js +67 -0
  89. package/dist/local/store/conformance/checks.js.map +1 -0
  90. package/dist/local/store/conformance/index.d.ts +30 -0
  91. package/dist/local/store/conformance/index.d.ts.map +1 -0
  92. package/dist/local/store/conformance/index.js +29 -0
  93. package/dist/local/store/conformance/index.js.map +1 -0
  94. package/dist/local/store/conformance/records.d.ts +36 -0
  95. package/dist/local/store/conformance/records.d.ts.map +1 -0
  96. package/dist/local/store/conformance/records.js +109 -0
  97. package/dist/local/store/conformance/records.js.map +1 -0
  98. package/dist/local/store/conformance/run.d.ts +24 -0
  99. package/dist/local/store/conformance/run.d.ts.map +1 -0
  100. package/dist/local/store/conformance/run.js +156 -0
  101. package/dist/local/store/conformance/run.js.map +1 -0
  102. package/dist/local/store/conformance/types.d.ts +55 -0
  103. package/dist/local/store/conformance/types.d.ts.map +1 -0
  104. package/dist/local/store/conformance/types.js +6 -0
  105. package/dist/local/store/conformance/types.js.map +1 -0
  106. package/dist/local/store/expo/adapter.d.ts +2 -1
  107. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  108. package/dist/local/store/expo/adapter.js.map +1 -1
  109. package/dist/local/store/node/adapter.d.ts +2 -2
  110. package/dist/local/store/react-native/adapter.d.ts +2 -1
  111. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  112. package/dist/local/store/react-native/adapter.js.map +1 -1
  113. package/dist/local/store/sqlite/convert-plaintext.d.ts +62 -0
  114. package/dist/local/store/sqlite/convert-plaintext.d.ts.map +1 -0
  115. package/dist/local/store/sqlite/convert-plaintext.js +236 -0
  116. package/dist/local/store/sqlite/convert-plaintext.js.map +1 -0
  117. package/dist/local/store/sqlite/encryption.d.ts +21 -0
  118. package/dist/local/store/sqlite/encryption.d.ts.map +1 -1
  119. package/dist/local/store/sqlite/encryption.js.map +1 -1
  120. package/dist/local/store/sqlite/errors.d.ts.map +1 -1
  121. package/dist/local/store/sqlite/errors.js +2 -1
  122. package/dist/local/store/sqlite/errors.js.map +1 -1
  123. package/dist/local/store/sqlite/key-storage/identity-keys.d.ts +3 -1
  124. package/dist/local/store/sqlite/key-storage/identity-keys.d.ts.map +1 -1
  125. package/dist/local/store/sqlite/key-storage/identity-keys.js +3 -1
  126. package/dist/local/store/sqlite/key-storage/identity-keys.js.map +1 -1
  127. package/dist/local/store/sqlite/open-store.d.ts +36 -4
  128. package/dist/local/store/sqlite/open-store.d.ts.map +1 -1
  129. package/dist/local/store/sqlite/open-store.js +326 -21
  130. package/dist/local/store/sqlite/open-store.js.map +1 -1
  131. package/dist/local/store/sqlite/web/worker.d.ts +5 -0
  132. package/dist/local/store/sqlite/web/worker.d.ts.map +1 -1
  133. package/dist/local/store/sqlite/web/worker.js +99 -20
  134. package/dist/local/store/sqlite/web/worker.js.map +1 -1
  135. package/dist/local/store/web-sqlite/adapter.d.ts +3 -2
  136. package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
  137. package/dist/local/store/web-sqlite/adapter.js +12 -2
  138. package/dist/local/store/web-sqlite/adapter.js.map +1 -1
  139. package/dist/remote/relay/types.d.ts +4 -2
  140. package/dist/remote/relay/types.d.ts.map +1 -1
  141. package/dist/types/api.d.ts +20 -4
  142. package/dist/types/api.d.ts.map +1 -1
  143. package/docs/ASSURANCE.md +25 -7
  144. package/docs/DEVIATIONS.md +35 -3
  145. package/docs/ERROR_HANDLING.md +8 -6
  146. package/docs/GETTING_STARTED.md +15 -8
  147. package/docs/INTERFACES.md +3 -1
  148. package/docs/PACKAGE_SURFACE.md +1 -0
  149. package/docs/SECURITY.md +23 -5
  150. package/keys/README.md +3 -1
  151. package/local/store/README.md +92 -12
  152. package/local/store/expo/README.md +63 -6
  153. package/local/store/key-value/README.md +3 -2
  154. package/local/store/node/README.md +68 -6
  155. package/local/store/react-native/README.md +62 -4
  156. package/local/store/web-sqlite/README.md +73 -4
  157. 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,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.1",
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"