@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.
- package/ADAPTERS.md +3 -0
- package/ARCHITECTURE.md +4 -4
- package/CHANGELOG.md +141 -0
- package/README.md +1 -1
- package/SECURITY.md +2 -2
- package/client/README.md +40 -0
- package/device/README.md +40 -4
- package/dist/client/client.d.ts +8 -0
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +19 -1
- package/dist/client/client.js.map +1 -1
- package/dist/client/config.d.ts +6 -2
- package/dist/client/config.d.ts.map +1 -1
- package/dist/client/config.js.map +1 -1
- package/dist/client/event-hooks.d.ts +28 -0
- package/dist/client/event-hooks.d.ts.map +1 -1
- package/dist/client/event-hooks.js +1 -0
- package/dist/client/event-hooks.js.map +1 -1
- package/dist/client/group-init-status.d.ts +21 -0
- package/dist/client/group-init-status.d.ts.map +1 -0
- package/dist/client/group-init-status.js +156 -0
- package/dist/client/group-init-status.js.map +1 -0
- package/dist/client/hosted-device-link-transport.d.ts +11 -0
- package/dist/client/hosted-device-link-transport.d.ts.map +1 -0
- package/dist/client/hosted-device-link-transport.js +25 -0
- package/dist/client/hosted-device-link-transport.js.map +1 -0
- package/dist/client/hosted-device-link.d.ts +97 -0
- package/dist/client/hosted-device-link.d.ts.map +1 -0
- package/dist/client/hosted-device-link.js +149 -0
- package/dist/client/hosted-device-link.js.map +1 -0
- package/dist/client/hosted-http-error.d.ts +30 -0
- package/dist/client/hosted-http-error.d.ts.map +1 -0
- package/dist/client/hosted-http-error.js +34 -0
- package/dist/client/hosted-http-error.js.map +1 -0
- package/dist/client/hosted-presence.js +1 -1
- package/dist/client/hosted-presence.js.map +1 -1
- package/dist/client/hosted-profile-keys.js +1 -1
- package/dist/client/hosted-profile-keys.js.map +1 -1
- package/dist/client/hosted-sandbox-identity.d.ts +3 -3
- package/dist/client/hosted-sandbox-identity.js +3 -3
- package/dist/client/hosted-transport.d.ts +12 -13
- package/dist/client/hosted-transport.d.ts.map +1 -1
- package/dist/client/hosted-transport.js +111 -17
- package/dist/client/hosted-transport.js.map +1 -1
- package/dist/client/hosted.d.ts +57 -8
- package/dist/client/hosted.d.ts.map +1 -1
- package/dist/client/hosted.js +170 -19
- package/dist/client/hosted.js.map +1 -1
- package/dist/client/index.d.ts +2 -1
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +1 -1
- package/dist/client/index.js.map +1 -1
- package/dist/client/receive-queue.d.ts +4 -2
- package/dist/client/receive-queue.d.ts.map +1 -1
- package/dist/client/receive-queue.js +26 -22
- package/dist/client/receive-queue.js.map +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/local/store/conformance/cases/ciphertext.d.ts +7 -0
- package/dist/local/store/conformance/cases/ciphertext.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/ciphertext.js +55 -0
- package/dist/local/store/conformance/cases/ciphertext.js.map +1 -0
- package/dist/local/store/conformance/cases/durability.d.ts +6 -0
- package/dist/local/store/conformance/cases/durability.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/durability.js +34 -0
- package/dist/local/store/conformance/cases/durability.js.map +1 -0
- package/dist/local/store/conformance/cases/identity.d.ts +7 -0
- package/dist/local/store/conformance/cases/identity.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/identity.js +84 -0
- package/dist/local/store/conformance/cases/identity.js.map +1 -0
- package/dist/local/store/conformance/cases/metadata.d.ts +7 -0
- package/dist/local/store/conformance/cases/metadata.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/metadata.js +48 -0
- package/dist/local/store/conformance/cases/metadata.js.map +1 -0
- package/dist/local/store/conformance/cases/protection.d.ts +7 -0
- package/dist/local/store/conformance/cases/protection.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/protection.js +14 -0
- package/dist/local/store/conformance/cases/protection.js.map +1 -0
- package/dist/local/store/conformance/cases/receive-work.d.ts +8 -0
- package/dist/local/store/conformance/cases/receive-work.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/receive-work.js +152 -0
- package/dist/local/store/conformance/cases/receive-work.js.map +1 -0
- package/dist/local/store/conformance/cases/sender-key.d.ts +7 -0
- package/dist/local/store/conformance/cases/sender-key.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/sender-key.js +59 -0
- package/dist/local/store/conformance/cases/sender-key.js.map +1 -0
- package/dist/local/store/conformance/cases/session-trust.d.ts +7 -0
- package/dist/local/store/conformance/cases/session-trust.d.ts.map +1 -0
- package/dist/local/store/conformance/cases/session-trust.js +64 -0
- package/dist/local/store/conformance/cases/session-trust.js.map +1 -0
- package/dist/local/store/conformance/checks.d.ts +15 -0
- package/dist/local/store/conformance/checks.d.ts.map +1 -0
- package/dist/local/store/conformance/checks.js +67 -0
- package/dist/local/store/conformance/checks.js.map +1 -0
- package/dist/local/store/conformance/index.d.ts +30 -0
- package/dist/local/store/conformance/index.d.ts.map +1 -0
- package/dist/local/store/conformance/index.js +29 -0
- package/dist/local/store/conformance/index.js.map +1 -0
- package/dist/local/store/conformance/records.d.ts +36 -0
- package/dist/local/store/conformance/records.d.ts.map +1 -0
- package/dist/local/store/conformance/records.js +109 -0
- package/dist/local/store/conformance/records.js.map +1 -0
- package/dist/local/store/conformance/run.d.ts +24 -0
- package/dist/local/store/conformance/run.d.ts.map +1 -0
- package/dist/local/store/conformance/run.js +156 -0
- package/dist/local/store/conformance/run.js.map +1 -0
- package/dist/local/store/conformance/types.d.ts +55 -0
- package/dist/local/store/conformance/types.d.ts.map +1 -0
- package/dist/local/store/conformance/types.js +6 -0
- package/dist/local/store/conformance/types.js.map +1 -0
- package/dist/local/store/expo/adapter.d.ts +2 -1
- package/dist/local/store/expo/adapter.d.ts.map +1 -1
- package/dist/local/store/expo/adapter.js.map +1 -1
- package/dist/local/store/node/adapter.d.ts +2 -2
- package/dist/local/store/react-native/adapter.d.ts +2 -1
- package/dist/local/store/react-native/adapter.d.ts.map +1 -1
- package/dist/local/store/react-native/adapter.js.map +1 -1
- package/dist/local/store/sqlite/convert-plaintext.d.ts +62 -0
- package/dist/local/store/sqlite/convert-plaintext.d.ts.map +1 -0
- package/dist/local/store/sqlite/convert-plaintext.js +236 -0
- package/dist/local/store/sqlite/convert-plaintext.js.map +1 -0
- package/dist/local/store/sqlite/encryption.d.ts +21 -0
- package/dist/local/store/sqlite/encryption.d.ts.map +1 -1
- package/dist/local/store/sqlite/encryption.js.map +1 -1
- package/dist/local/store/sqlite/errors.d.ts.map +1 -1
- package/dist/local/store/sqlite/errors.js +2 -1
- package/dist/local/store/sqlite/errors.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/identity-keys.d.ts +3 -1
- package/dist/local/store/sqlite/key-storage/identity-keys.d.ts.map +1 -1
- package/dist/local/store/sqlite/key-storage/identity-keys.js +3 -1
- package/dist/local/store/sqlite/key-storage/identity-keys.js.map +1 -1
- package/dist/local/store/sqlite/open-store.d.ts +36 -4
- package/dist/local/store/sqlite/open-store.d.ts.map +1 -1
- package/dist/local/store/sqlite/open-store.js +326 -21
- package/dist/local/store/sqlite/open-store.js.map +1 -1
- package/dist/local/store/sqlite/web/worker.d.ts +5 -0
- package/dist/local/store/sqlite/web/worker.d.ts.map +1 -1
- package/dist/local/store/sqlite/web/worker.js +99 -20
- package/dist/local/store/sqlite/web/worker.js.map +1 -1
- package/dist/local/store/web-sqlite/adapter.d.ts +3 -2
- package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
- package/dist/local/store/web-sqlite/adapter.js +12 -2
- package/dist/local/store/web-sqlite/adapter.js.map +1 -1
- package/dist/remote/relay/types.d.ts +4 -2
- package/dist/remote/relay/types.d.ts.map +1 -1
- package/dist/types/api.d.ts +20 -4
- package/dist/types/api.d.ts.map +1 -1
- package/docs/ASSURANCE.md +25 -7
- package/docs/DEVIATIONS.md +35 -3
- package/docs/ERROR_HANDLING.md +8 -6
- package/docs/GETTING_STARTED.md +25 -8
- package/docs/INTERFACES.md +3 -1
- package/docs/PACKAGE_SURFACE.md +1 -0
- package/docs/RECIPES.md +44 -0
- package/docs/SECURITY.md +23 -5
- package/keys/README.md +3 -1
- package/local/store/README.md +92 -12
- package/local/store/expo/README.md +63 -6
- package/local/store/key-value/README.md +3 -2
- package/local/store/node/README.md +68 -6
- package/local/store/react-native/README.md +62 -4
- package/local/store/web-sqlite/README.md +101 -4
- 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
|
|
44
|
-
|
|
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
|
|
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": "
|
|
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"
|