@open-e2ee/signal-protocol-sdk 0.1.0-alpha.9 → 0.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 +12 -12
- package/ARCHITECTURE.md +3 -3
- package/CHANGELOG.md +374 -0
- package/README.md +25 -15
- package/SECURITY.md +1 -1
- package/client/README.md +2 -2
- package/device/README.md +3 -1
- package/dist/client/client.d.ts +6 -6
- package/dist/client/client.js +6 -6
- package/dist/client/compose.d.ts +2 -2
- package/dist/client/index.d.ts +2 -2
- package/dist/device/expo-metadata.d.ts +26 -0
- package/dist/device/expo-metadata.d.ts.map +1 -0
- package/dist/device/expo-metadata.js +33 -0
- package/dist/device/expo-metadata.js.map +1 -0
- package/dist/device/index.d.ts +1 -1
- package/dist/device/index.d.ts.map +1 -1
- package/dist/device/index.js +5 -1
- package/dist/device/index.js.map +1 -1
- package/dist/device/provisioning.d.ts +4 -12
- package/dist/device/provisioning.d.ts.map +1 -1
- package/dist/device/provisioning.js +4 -21
- package/dist/device/provisioning.js.map +1 -1
- package/dist/index.d.ts +5 -5
- package/dist/index.js +5 -5
- package/dist/internal/crypto/symmetric/aes.d.ts.map +1 -1
- package/dist/internal/crypto/symmetric/aes.js +27 -30
- package/dist/internal/crypto/symmetric/aes.js.map +1 -1
- package/dist/internal/encoding/proto/primitives.d.ts +261 -6
- package/dist/internal/encoding/proto/primitives.d.ts.map +1 -1
- package/dist/internal/encoding/proto/primitives.js +468 -6
- package/dist/internal/encoding/proto/primitives.js.map +1 -1
- package/dist/internal/encoding/proto/sender-key-message.d.ts +4 -3
- package/dist/internal/encoding/proto/sender-key-message.d.ts.map +1 -1
- package/dist/internal/encoding/proto/sender-key-message.js +97 -76
- package/dist/internal/encoding/proto/sender-key-message.js.map +1 -1
- package/dist/internal/encoding/proto/signal-message.d.ts +7 -2
- package/dist/internal/encoding/proto/signal-message.d.ts.map +1 -1
- package/dist/internal/encoding/proto/signal-message.js +194 -110
- package/dist/internal/encoding/proto/signal-message.js.map +1 -1
- package/dist/internal/manager/manager.d.ts +2 -2
- package/dist/internal/protocol/sealed-sender/proto/index.d.ts +50 -4
- package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/proto/index.js +273 -151
- package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts +7 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js +334 -151
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js.map +1 -1
- package/dist/layers.d.ts +2 -2
- package/dist/layers.d.ts.map +1 -1
- package/dist/layers.js +2 -2
- package/dist/layers.js.map +1 -1
- package/dist/local/store/index.d.ts +3 -3
- package/dist/local/store/index.d.ts.map +1 -1
- package/dist/local/store/index.js +4 -4
- package/dist/local/store/index.js.map +1 -1
- package/dist/local/store/{mock → memory}/adapter.d.ts +10 -10
- package/dist/local/store/memory/adapter.d.ts.map +1 -0
- package/dist/local/store/{mock → memory}/adapter.js +5 -5
- package/dist/local/store/memory/adapter.js.map +1 -0
- package/dist/local/store/{mock → memory}/failures.d.ts +6 -6
- package/dist/local/store/memory/failures.d.ts.map +1 -0
- package/dist/local/store/{mock → memory}/failures.js +6 -6
- package/dist/local/store/memory/failures.js.map +1 -0
- package/dist/local/store/memory/index.d.ts +11 -0
- package/dist/local/store/memory/index.d.ts.map +1 -0
- package/dist/local/store/memory/index.js +7 -0
- package/dist/local/store/memory/index.js.map +1 -0
- package/dist/local/store/react-native/adapter.d.ts.map +1 -1
- package/dist/local/store/react-native/adapter.js +69 -1
- package/dist/local/store/react-native/adapter.js.map +1 -1
- package/dist/local/store/react-native/backend-conformance.d.ts +66 -0
- package/dist/local/store/react-native/backend-conformance.d.ts.map +1 -0
- package/dist/local/store/react-native/backend-conformance.js +326 -0
- package/dist/local/store/react-native/backend-conformance.js.map +1 -0
- package/dist/local/store/react-native/index.d.ts +9 -4
- package/dist/local/store/react-native/index.d.ts.map +1 -1
- package/dist/local/store/react-native/index.js +2 -0
- package/dist/local/store/react-native/index.js.map +1 -1
- package/dist/local/store/react-native/reference-backend.d.ts +42 -0
- package/dist/local/store/react-native/reference-backend.d.ts.map +1 -0
- package/dist/local/store/react-native/reference-backend.js +177 -0
- package/dist/local/store/react-native/reference-backend.js.map +1 -0
- package/dist/local/store/react-native/storage.d.ts +9 -0
- package/dist/local/store/react-native/storage.d.ts.map +1 -1
- package/dist/local/store/web/adapter.d.ts +11 -1
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +196 -33
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/local/store/web/index.d.ts +3 -2
- package/dist/local/store/web/index.d.ts.map +1 -1
- package/dist/local/store/web/index.js.map +1 -1
- package/dist/local/vault/index.d.ts +5 -1
- package/dist/local/vault/index.d.ts.map +1 -1
- package/dist/local/vault/index.js +1 -1
- package/dist/local/vault/index.js.map +1 -1
- package/dist/remote/relay/convex/component/certificates.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/certificates.js +26 -31
- package/dist/remote/relay/convex/component/certificates.js.map +1 -1
- package/dist/remote/relay/index.d.ts +1 -1
- package/dist/remote/relay/index.d.ts.map +1 -1
- package/dist/remote/relay/index.js +2 -2
- package/dist/remote/relay/index.js.map +1 -1
- package/dist/remote/relay/{mock → memory}/adapter.d.ts +17 -17
- package/dist/remote/relay/memory/adapter.d.ts.map +1 -0
- package/dist/remote/relay/{mock → memory}/adapter.js +17 -17
- package/dist/remote/relay/memory/adapter.js.map +1 -0
- package/dist/remote/relay/{mock → memory}/failures.d.ts +5 -5
- package/dist/remote/relay/memory/failures.d.ts.map +1 -0
- package/dist/remote/relay/{mock → memory}/failures.js +1 -1
- package/dist/remote/relay/memory/failures.js.map +1 -0
- package/dist/remote/relay/{mock → memory}/group-server.d.ts +1 -1
- package/dist/remote/relay/memory/group-server.d.ts.map +1 -0
- package/dist/remote/relay/{mock → memory}/group-server.js +1 -1
- package/dist/remote/relay/memory/group-server.js.map +1 -0
- package/dist/remote/relay/memory/index.d.ts +11 -0
- package/dist/remote/relay/memory/index.d.ts.map +1 -0
- package/dist/remote/relay/memory/index.js +7 -0
- package/dist/remote/relay/memory/index.js.map +1 -0
- package/dist/types/errors.d.ts +33 -0
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/errors.js +36 -0
- package/dist/types/errors.js.map +1 -1
- package/docs/ASSURANCE.md +49 -14
- package/docs/CLIENT_COMPOSITION.md +3 -3
- package/docs/GETTING_STARTED.md +11 -11
- package/docs/PACKAGE_SURFACE.md +10 -8
- package/docs/RECIPES.md +12 -12
- package/local/store/README.md +95 -8
- package/local/store/{mock → memory}/README.md +8 -8
- package/local/store/react-native/README.md +34 -2
- package/local/store/web/README.md +30 -3
- package/package.json +13 -10
- package/remote/README.md +7 -7
- package/remote/relay/README.md +5 -5
- package/remote/relay/{mock → memory}/README.md +8 -8
- package/dist/local/store/mock/adapter.d.ts.map +0 -1
- package/dist/local/store/mock/adapter.js.map +0 -1
- package/dist/local/store/mock/failures.d.ts.map +0 -1
- package/dist/local/store/mock/failures.js.map +0 -1
- package/dist/local/store/mock/index.d.ts +0 -11
- package/dist/local/store/mock/index.d.ts.map +0 -1
- package/dist/local/store/mock/index.js +0 -7
- package/dist/local/store/mock/index.js.map +0 -1
- package/dist/remote/relay/mock/adapter.d.ts.map +0 -1
- package/dist/remote/relay/mock/adapter.js.map +0 -1
- package/dist/remote/relay/mock/failures.d.ts.map +0 -1
- package/dist/remote/relay/mock/failures.js.map +0 -1
- package/dist/remote/relay/mock/group-server.d.ts.map +0 -1
- package/dist/remote/relay/mock/group-server.js.map +0 -1
- package/dist/remote/relay/mock/index.d.ts +0 -11
- package/dist/remote/relay/mock/index.d.ts.map +0 -1
- package/dist/remote/relay/mock/index.js +0 -7
- package/dist/remote/relay/mock/index.js.map +0 -1
package/ADAPTERS.md
CHANGED
|
@@ -18,7 +18,7 @@ The relay interface handles server-owned Signal Protocol state:
|
|
|
18
18
|
Use:
|
|
19
19
|
|
|
20
20
|
- `ConvexSignalProtocolRelayServer` from `@open-e2ee/signal-protocol-sdk/remote/relay/convex`
|
|
21
|
-
- `
|
|
21
|
+
- `InMemorySignalProtocolRelayServer` from `@open-e2ee/signal-protocol-sdk/remote/relay/memory`
|
|
22
22
|
- or a custom implementation
|
|
23
23
|
|
|
24
24
|
### Storage: `ISignalProtocolLocalStore`
|
|
@@ -35,10 +35,10 @@ Use:
|
|
|
35
35
|
|
|
36
36
|
- `ExpoSignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/expo`
|
|
37
37
|
- Expo integration helpers like `getKeyStorage`, `getDatabaseKeyManager`, `clearDatabaseKeyCache`, and `createPreKeyMaintenanceStore` from `@open-e2ee/signal-protocol-sdk/local/store/expo`
|
|
38
|
-
- `IndexedDbSignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/web`
|
|
39
|
-
- `ReactNativeSignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/react-native` (
|
|
38
|
+
- `IndexedDbSignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/web`
|
|
39
|
+
- `ReactNativeSignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/react-native` (use `await ReactNativeSignalProtocolStore.create({ storage })` with a caller-provided key-value backend, verified with the exported backend-conformance kit)
|
|
40
40
|
- `NodeSignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/node`
|
|
41
|
-
- `
|
|
41
|
+
- `InMemorySignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/memory`
|
|
42
42
|
- or a custom implementation
|
|
43
43
|
|
|
44
44
|
### Remote object storage: `SignalProtocolRemoteObjectStore`
|
|
@@ -69,11 +69,11 @@ functions retain authentication, authorization, and persistence.
|
|
|
69
69
|
|
|
70
70
|
```ts
|
|
71
71
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
72
|
-
import {
|
|
72
|
+
import { inMemoryStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
|
|
73
73
|
|
|
74
74
|
const signal = await createSignalProtocolClient({
|
|
75
75
|
identity: { userId: "alice" },
|
|
76
|
-
adapters: { storage:
|
|
76
|
+
adapters: { storage: inMemoryStore() },
|
|
77
77
|
});
|
|
78
78
|
```
|
|
79
79
|
|
|
@@ -112,19 +112,19 @@ database and SQLCipher bootstrap.
|
|
|
112
112
|
|
|
113
113
|
```ts
|
|
114
114
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
115
|
-
import {
|
|
116
|
-
import {
|
|
115
|
+
import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
|
|
116
|
+
import { inMemoryStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
|
|
117
117
|
|
|
118
|
-
const relay =
|
|
118
|
+
const relay = inMemoryRelay();
|
|
119
119
|
|
|
120
120
|
const alice = await createSignalProtocolClient({
|
|
121
121
|
identity: { userId: "alice" },
|
|
122
|
-
adapters: { storage:
|
|
122
|
+
adapters: { storage: inMemoryStore(), relay },
|
|
123
123
|
});
|
|
124
124
|
|
|
125
125
|
const bob = await createSignalProtocolClient({
|
|
126
126
|
identity: { userId: "bob" },
|
|
127
|
-
adapters: { storage:
|
|
127
|
+
adapters: { storage: inMemoryStore(), relay },
|
|
128
128
|
});
|
|
129
129
|
```
|
|
130
130
|
|
|
@@ -182,7 +182,7 @@ const signal = await createSignalProtocolClient({
|
|
|
182
182
|
|
|
183
183
|
## Verifiable adapter design
|
|
184
184
|
|
|
185
|
-
|
|
185
|
+
In-memory relay and storage adapters provide deterministic behavior for
|
|
186
186
|
development environments. Production adapters remain dependency-injected so
|
|
187
187
|
applications can evaluate storage, delivery, and failure behavior without
|
|
188
188
|
reaching into client internals.
|
package/ARCHITECTURE.md
CHANGED
|
@@ -40,7 +40,7 @@ compatibility shim when a boundary is wrong.
|
|
|
40
40
|
| Public feature surfaces | [blocking/](./blocking/), [groups/](./groups/), [media/](./media/), [profile/](./profile/), [sealed-sender/](./sealed-sender/), [username/](./username/), [zk/](./zk/) | App-facing helpers that compose protocol, media, or account-state behavior without joining the inward dependency hierarchy |
|
|
41
41
|
| Public utility surfaces | [encoding/](./encoding/), [files/](./files/), [hooks/](./hooks/), [utils/](./utils/), `logger.ts`, `server-clock.ts`, `versions.ts` | Stable helpers, React hooks, logging, clock estimation, version metadata, and file/encoding utilities |
|
|
42
42
|
| Local adapters | [local/](./local/) | Local protocol stores and secret vault integrations |
|
|
43
|
-
| Remote adapters | [remote/](./remote/) | Relay and object-store ports plus Convex,
|
|
43
|
+
| Remote adapters | [remote/](./remote/) | Relay and object-store ports plus Convex, in-memory, R2, and S3 adapters |
|
|
44
44
|
| Device features | [device/](./device/) | Device IDs, provisioning, linked-device lifecycle and transfer |
|
|
45
45
|
|
|
46
46
|
## Documentation Ownership
|
|
@@ -71,9 +71,9 @@ import {
|
|
|
71
71
|
Platform and backend integrations are explicit subpaths such as:
|
|
72
72
|
|
|
73
73
|
- `@open-e2ee/signal-protocol-sdk/local/store/expo`
|
|
74
|
-
- `@open-e2ee/signal-protocol-sdk/local/store/
|
|
74
|
+
- `@open-e2ee/signal-protocol-sdk/local/store/memory`
|
|
75
75
|
- `@open-e2ee/signal-protocol-sdk/remote/relay/convex`
|
|
76
|
-
- `@open-e2ee/signal-protocol-sdk/remote/relay/
|
|
76
|
+
- `@open-e2ee/signal-protocol-sdk/remote/relay/memory`
|
|
77
77
|
- `@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2`
|
|
78
78
|
- `@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2/server`
|
|
79
79
|
- `@open-e2ee/signal-protocol-sdk/remote/object-store/s3`
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,379 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
- **First non-prerelease release.** Identical in code to `0.1.0-alpha.14`;
|
|
6
|
+
the version graduates the `0.1.0-alpha` series. The alpha label is retired
|
|
7
|
+
because the condition it described no longer holds: every shipped store
|
|
8
|
+
adapter now carries the full `ISignalProtocolLocalStore` contract with its
|
|
9
|
+
graduation checklist running as continuous CI gates — the storage contract
|
|
10
|
+
suites in real Chromium, Firefox, and WebKit, the backend-conformance kit
|
|
11
|
+
on Hermes, and the interruption, storage-pressure, multi-tab, and soak
|
|
12
|
+
suites. The `0.x` caveat stands: public APIs and persisted formats may
|
|
13
|
+
change before `1.0`.
|
|
14
|
+
|
|
15
|
+
## 0.1.0-alpha.14
|
|
16
|
+
|
|
17
|
+
- **`ReactNativeSignalProtocolStore` is no longer experimental.** Every gate
|
|
18
|
+
on its graduation checklist now runs continuously. A new
|
|
19
|
+
backend-conformance kit — `runBackendConformance` and
|
|
20
|
+
`assertBackendConformance`, exported from the package — executes thirteen
|
|
21
|
+
cases against any `ReactNativeKeyValueStorage` implementation: round-trips,
|
|
22
|
+
key listing, batch removal, in-order atomic application, checks evaluated
|
|
23
|
+
against pre-batch state, null-guarded creation, all-or-nothing failure,
|
|
24
|
+
exact-userId session removal with in-batch visibility, a single winner
|
|
25
|
+
between concurrent guarded batches, and durability across reopen. Negative
|
|
26
|
+
tests prove the kit catches a non-atomic backend, a prefix-matching
|
|
27
|
+
session removal, and an unserialized backend. A new
|
|
28
|
+
`createReferenceReactNativeBackend` — the executable specification of the
|
|
29
|
+
backend contract — passes the kit on the Hermes engine React Native ships
|
|
30
|
+
with, in a new CI gate that runs the bundled kit on the sha256-pinned
|
|
31
|
+
Hermes CLI and requires an explicit pass sentinel, because Hermes exits 0
|
|
32
|
+
on an unhandled async rejection. Interruption and storage-pressure jest
|
|
33
|
+
suites drive the adapter over the reference backend: a simulated process
|
|
34
|
+
kill before commit leaves every atomic security write all-or-nothing and
|
|
35
|
+
a retry after reopen lands it whole, and quota exhaustion is exercised
|
|
36
|
+
through every write path.
|
|
37
|
+
|
|
38
|
+
- **Quota exhaustion in the React Native store now surfaces as a typed
|
|
39
|
+
error.** The backend contract gains a documented quota signal: a backend
|
|
40
|
+
rejects the failing write with an error named `QuotaExceededError` and
|
|
41
|
+
commits nothing. The adapter maps that signal to the public
|
|
42
|
+
`StorageQuotaExceededError` (code `STORAGE_QUOTA_EXCEEDED`) at the same
|
|
43
|
+
adapter-boundary seam the browser store uses, so both stores report
|
|
44
|
+
storage pressure identically.
|
|
45
|
+
|
|
46
|
+
## 0.1.0-alpha.13
|
|
47
|
+
|
|
48
|
+
- **`IndexedDbSignalProtocolStore` is no longer experimental.** Every gate
|
|
49
|
+
on its graduation checklist now runs continuously: the storage contract
|
|
50
|
+
suites in real Chromium, Firefox, and WebKit; the multi-tab
|
|
51
|
+
compare-and-set suite; the interruption suite; the storage-pressure
|
|
52
|
+
suite; and a new soak gate. The soak drives 2,000 full
|
|
53
|
+
construct/initialize/write/read/close cycles through the adapter in one
|
|
54
|
+
real Chromium page, samples renderer memory — including ArrayBuffer
|
|
55
|
+
backing stores, which plain JS-heap readings miss — after forced
|
|
56
|
+
garbage collection, and fails if the late-run median of memory or
|
|
57
|
+
per-cycle latency grows beyond a small tolerance over the early-run
|
|
58
|
+
median. Injecting a per-cycle leak into the adapter turns both
|
|
59
|
+
detectors red. `npm run soak:web-store` runs longer sessions on demand.
|
|
60
|
+
The React Native adapter remains experimental; its checklist is
|
|
61
|
+
unchanged.
|
|
62
|
+
|
|
63
|
+
- **Quota exhaustion in the browser store now surfaces as a typed error.**
|
|
64
|
+
A write that exhausts the origin's storage quota rejects with the new
|
|
65
|
+
public `StorageQuotaExceededError` (code `STORAGE_QUOTA_EXCEEDED`)
|
|
66
|
+
instead of the raw engine `QuotaExceededError`. The mapping lives at the
|
|
67
|
+
adapter boundary — one seam covering every store method, matched by
|
|
68
|
+
error name so it holds across engines — and because every write commits
|
|
69
|
+
in one atomic transaction, the typed error always means the write did
|
|
70
|
+
not persist, never a partial record. A jest suite drives quota-shaped
|
|
71
|
+
backend failures through every write path, and a new Chromium
|
|
72
|
+
storage-pressure spec in the real-browser gate clamps the origin's
|
|
73
|
+
quota, exhausts it against the real engine, and asserts the typed
|
|
74
|
+
rejection, intact prior state, and a clean retry once space frees.
|
|
75
|
+
|
|
76
|
+
- The real-browser gate now includes an interruption suite: a Playwright
|
|
77
|
+
spec destroys a real tab while a write is in flight — an atomic
|
|
78
|
+
session/trust commit, an identity rotation, a fresh-database bootstrap,
|
|
79
|
+
and a prekey batch — then reopens the store from a fresh tab and asserts
|
|
80
|
+
it is readable and each atomic security commit landed all-or-nothing,
|
|
81
|
+
never partially. The kills are sampled at several points inside each
|
|
82
|
+
write, in all three engines, and a deterministic structural test backs
|
|
83
|
+
them: each atomic security commit must open exactly one readwrite
|
|
84
|
+
transaction, which is what makes every kill land all-or-nothing. Tearing
|
|
85
|
+
either commit into two transactions turns the structural test red on
|
|
86
|
+
every run.
|
|
87
|
+
|
|
88
|
+
- **Two tabs no longer race the IndexedDB store into silent data loss.** Two
|
|
89
|
+
cross-connection races existed in the browser adapter. First, the database
|
|
90
|
+
encryption key bootstrap read then wrote in separate transactions, so two
|
|
91
|
+
tabs initializing a fresh database concurrently could each generate a
|
|
92
|
+
different key — records written by the losing tab then failed authenticated
|
|
93
|
+
decryption everywhere else. Second, first-contact trust pinning checked
|
|
94
|
+
then wrote in separate transactions, so two tabs pinning different
|
|
95
|
+
identities were both told `NEW_IDENTITY` while one pin silently replaced
|
|
96
|
+
the other. Both paths now create through IndexedDB's `add()`, which refuses
|
|
97
|
+
to overwrite: the bootstrap loser adopts the winner's key, and a
|
|
98
|
+
first-contact loser re-evaluates its candidate against the pin that won.
|
|
99
|
+
Rotation, verification, and the atomic session/trust commit already
|
|
100
|
+
performed their compare-and-set inside a single transaction and are
|
|
101
|
+
unchanged.
|
|
102
|
+
|
|
103
|
+
- The real-browser gate now includes a multi-tab compare-and-set suite: a
|
|
104
|
+
Playwright spec drives two tabs — two live IndexedDB connections on one
|
|
105
|
+
origin — through concurrent key bootstrap, first-contact pinning,
|
|
106
|
+
rotations, verification-versus-rotation, and one-time-prekey consumption,
|
|
107
|
+
in all three engines. The two races above are what this suite caught, and
|
|
108
|
+
reverting either fix turns it red.
|
|
109
|
+
|
|
110
|
+
- **Reading sessions or group sender keys no longer fails on Firefox and
|
|
111
|
+
WebKit.** `getSessionsForUser` and `getAllSenderKeysForGroup` in the
|
|
112
|
+
IndexedDB store decrypted each row inside the cursor loop. An IndexedDB
|
|
113
|
+
transaction deactivates the moment the event loop turns to anything that is
|
|
114
|
+
not one of its own requests, so awaiting Web Crypto mid-iteration let the
|
|
115
|
+
transaction commit and the next cursor advance threw
|
|
116
|
+
`TransactionInactiveError`. Chromium's laxer transaction lifetime and the
|
|
117
|
+
fake-indexeddb test double both tolerated the pattern, which is how it went
|
|
118
|
+
unseen. Both methods now collect the encrypted rows inside the transaction
|
|
119
|
+
and decrypt after it completes, the pattern the prekey reads already used.
|
|
120
|
+
No key agreement, payload, or wire byte changed.
|
|
121
|
+
|
|
122
|
+
- **`IndexedDbSignalProtocolStore.close()`.** The store held its database
|
|
123
|
+
connection open for the life of the page, and an open connection blocks
|
|
124
|
+
deletion and version upgrades of the database from anywhere else — so an
|
|
125
|
+
application signing out or clearing local state had no supported way to
|
|
126
|
+
release it. `close()` closes the connection and drops the in-memory
|
|
127
|
+
database key; call `initialize()` again before any other operation.
|
|
128
|
+
|
|
129
|
+
- The storage contract suites now also run against
|
|
130
|
+
`IndexedDbSignalProtocolStore` inside real Chromium, Firefox, and WebKit
|
|
131
|
+
pages on every change to the source repository. The suites are the same
|
|
132
|
+
modules the jest gate runs; the Firefox and WebKit failures above are what
|
|
133
|
+
the gate caught on its first run.
|
|
134
|
+
|
|
135
|
+
## 0.1.0-alpha.12
|
|
136
|
+
|
|
137
|
+
- **AES-GCM without additional data no longer fails in the browser.** Every
|
|
138
|
+
AES-GCM call built its Web Crypto parameters with `additionalData` always
|
|
139
|
+
present, holding `undefined` when the caller passed no AAD. Node converts
|
|
140
|
+
those parameters through WebIDL, where a member set to `undefined` is
|
|
141
|
+
absent, and accepts them. Chrome parses them by hand: a present
|
|
142
|
+
`additionalData` key must be a BufferSource whatever its value, so the same
|
|
143
|
+
call throws `AeadParams: additionalData: Not a BufferSource`. Device
|
|
144
|
+
provisioning and device transfer pass no AAD at all, so both worked under
|
|
145
|
+
Node and were unusable in a browser. The parameters are now built in one
|
|
146
|
+
place, which omits the member when there is nothing to put in it. No key
|
|
147
|
+
agreement, payload, or wire byte changed.
|
|
148
|
+
|
|
149
|
+
## 0.1.0-alpha.11
|
|
150
|
+
|
|
151
|
+
- **BREAKING: device provisioning no longer requires React Native, and
|
|
152
|
+
`getDeviceMetadata` moved to its own subpath.** `device/provisioning`
|
|
153
|
+
statically imported `react-native` and `expo-constants` at module scope.
|
|
154
|
+
Both are optional peer dependencies, so the package's own contract says a
|
|
155
|
+
consumer may have neither — but a static import of an absent package throws
|
|
156
|
+
`ERR_MODULE_NOT_FOUND` before the module runs, which made the entire
|
|
157
|
+
device-linking surface unimportable in Node and in the browser. The two
|
|
158
|
+
imports existed for three fields of one function. Provisioning itself is a
|
|
159
|
+
protocol and already takes the device's description as a
|
|
160
|
+
`LocalDeviceMetadata` parameter, so it is now platform-free, and
|
|
161
|
+
`getDeviceMetadata` lives at
|
|
162
|
+
`@open-e2ee/signal-protocol-sdk/device/expo-metadata`. It is no longer
|
|
163
|
+
re-exported from the `device` barrel. Callers off Expo build the four
|
|
164
|
+
fields themselves; callers on Expo change one import path. No key
|
|
165
|
+
agreement, payload, or wire byte changed.
|
|
166
|
+
|
|
167
|
+
- **`local/vault` no longer drags Expo SecureStore in behind the
|
|
168
|
+
interface.** The barrel re-exported
|
|
169
|
+
`ExpoSecureStoreSignalProtocolSecretVault`, so importing the vault
|
|
170
|
+
*contract* failed without `expo-secure-store` installed. The barrel now
|
|
171
|
+
exports only `ISignalProtocolLocalSecretVault`; the implementation keeps
|
|
172
|
+
its own subpath, `local/vault/expo-secure-store`, which is where every
|
|
173
|
+
caller in this repository already imported it from.
|
|
174
|
+
|
|
175
|
+
- **New check: `node ./scripts/smoke-import-surface.mjs`, wired into CI.**
|
|
176
|
+
Packs the package, installs it into a consumer outside the repository whose
|
|
177
|
+
`node_modules` has every optional peer removed, and imports all 59
|
|
178
|
+
published export subpaths. Entry points that are genuinely bound to a
|
|
179
|
+
platform are listed explicitly, and the list is verified in both
|
|
180
|
+
directions, so an exemption that stops being true fails the check rather
|
|
181
|
+
than lingering. Nothing caught the two defects above: the checks that name
|
|
182
|
+
every subpath resolve types without ever loading a module, and the checks
|
|
183
|
+
that load modules run from inside the repository, where the optional peers
|
|
184
|
+
are installed as devDependencies and Node's resolver finds them.
|
|
185
|
+
|
|
186
|
+
- **Bundling the sealed-sender codec no longer pulls React Native in with
|
|
187
|
+
it.** The codec imported two base64 helpers from the `internal/crypto`
|
|
188
|
+
barrel, and that barrel also exports `generateRandomBytes`, whose
|
|
189
|
+
third-choice runtime fallback is a dynamic `import('expo-crypto')`. The
|
|
190
|
+
fallback is correct — it is how the SDK finds a secure random source on
|
|
191
|
+
Expo, behind two other sources and a `try`/`catch` — but a bundler
|
|
192
|
+
resolves what it can reach without asking whether the branch will run, and
|
|
193
|
+
`expo-crypto` reaches `react-native`, whose entry point is Flow rather than
|
|
194
|
+
TypeScript. Anything bundling the codec for a server or a browser was
|
|
195
|
+
therefore parsing a mobile UI framework, and any bundler without a Flow
|
|
196
|
+
loader stopped there. The helpers now come from `internal/crypto/utils`,
|
|
197
|
+
which imports nothing but types, so the reachable graph ends where the
|
|
198
|
+
encoding does. No encoder, decoder, or byte changed.
|
|
199
|
+
|
|
200
|
+
## 0.1.0-alpha.10
|
|
201
|
+
|
|
202
|
+
- **BREAKING: the quickstart adapters are named for what they are —
|
|
203
|
+
in memory, not mocks.** Nothing in either adapter is a test double: the
|
|
204
|
+
protocol and the cryptography are real, and only the infrastructure is
|
|
205
|
+
simulated. The name said otherwise, and readers discounted the quick
|
|
206
|
+
start because of it. The `mock` subpaths are gone rather than aliased —
|
|
207
|
+
this is a pre-1.0 alpha with no customers, so a compatibility layer would
|
|
208
|
+
only preserve the wrong word. Update imports and identifiers:
|
|
209
|
+
|
|
210
|
+
| Before | After |
|
|
211
|
+
|---|---|
|
|
212
|
+
| `@open-e2ee/signal-protocol-sdk/local/store/mock` | `@open-e2ee/signal-protocol-sdk/local/store/memory` |
|
|
213
|
+
| `@open-e2ee/signal-protocol-sdk/remote/relay/mock` | `@open-e2ee/signal-protocol-sdk/remote/relay/memory` |
|
|
214
|
+
| `mockStore()` | `inMemoryStore()` |
|
|
215
|
+
| `mockRelay()` | `inMemoryRelay()` |
|
|
216
|
+
| `MockSignalProtocolStore` | `InMemorySignalProtocolStore` |
|
|
217
|
+
| `MockSignalProtocolStoreOptions` | `InMemorySignalProtocolStoreOptions` |
|
|
218
|
+
| `MockSignalProtocolRelayServer` | `InMemorySignalProtocolRelayServer` |
|
|
219
|
+
| `MockSignalProtocolRelayServerOptions` | `InMemorySignalProtocolRelayServerOptions` |
|
|
220
|
+
| `MockStoreFailureController` | `StoreFailureController` |
|
|
221
|
+
| `MockStoreFailureOptions` | `StoreFailureOptions` |
|
|
222
|
+
| `MockRelayFailureController` | `RelayFailureController` |
|
|
223
|
+
| `MockRelayFailureOptions` | `RelayFailureOptions` |
|
|
224
|
+
| `MockStorageWriteError` | `InjectedStorageWriteError` |
|
|
225
|
+
|
|
226
|
+
The failure controllers moved with the adapters and kept their behavior.
|
|
227
|
+
They were never test doubles either — they are deterministic, seeded
|
|
228
|
+
failure injection for the documented recovery exercises — so they lost
|
|
229
|
+
the `Mock` prefix instead of the subpath.
|
|
230
|
+
No runtime behavior changed: the storage-failure error message drops the
|
|
231
|
+
word "mock" and `InjectedStorageWriteError` reports the new class name,
|
|
232
|
+
and nothing else on the wire, in storage, or in the failure semantics
|
|
233
|
+
moved. The doc-snippet runner that executes every shipped snippet is now
|
|
234
|
+
`scripts/run-doc-snippets.mjs` with a `doc-snippet:` marker, because the
|
|
235
|
+
snippets it runs were never mock snippets.
|
|
236
|
+
|
|
237
|
+
- **`protobufjs` is no longer a dependency of the published package**, and
|
|
238
|
+
the eval gate that proves it is now part of CI. The relay's sealed-sender
|
|
239
|
+
certificate issuer was the last module importing it, through
|
|
240
|
+
`protobufjs/minimal`'s `Writer` — which generates no code, so it was never
|
|
241
|
+
what made the SDK throw `EvalError` under a strict Content-Security-Policy,
|
|
242
|
+
but it did pull `protobufjs` and `long` into every install to write four
|
|
243
|
+
fields. Issuance now goes through the same hand-written sealed-sender codec
|
|
244
|
+
that validates the certificates it produces, so the field numbers an
|
|
245
|
+
Ed25519 signature is computed over are described in one module instead of
|
|
246
|
+
two that had to agree. The package declares six direct production
|
|
247
|
+
dependencies and resolves to six packages in total; `protobufjs` remains a
|
|
248
|
+
development dependency, where the wire tests use it as an independent
|
|
249
|
+
oracle. The bytes are unchanged, which is the whole of the risk here — a
|
|
250
|
+
certificate is a signature over exactly these bytes, and any shift would
|
|
251
|
+
have invalidated every one already issued. Golden vectors captured from the
|
|
252
|
+
old writer before the rewrite pin the issued bytes for four shapes,
|
|
253
|
+
including a multi-byte UUID and an expiry above 2^53, and each is
|
|
254
|
+
re-validated through the certificate chain with real keys.
|
|
255
|
+
|
|
256
|
+
- **A varint that cannot fit a `uint32` is refused at the encoder instead of
|
|
257
|
+
written wrong.** `encodeVarint` stops at five bytes, so it truncated
|
|
258
|
+
anything above 4294967295 — 2^32 came out as `80 00`, which the 64-bit
|
|
259
|
+
decoder then correctly rejected as non-canonical — and it wrote `NaN` as 0
|
|
260
|
+
and `1.5` as 1. All three now throw a named error at the point the mistake
|
|
261
|
+
is made. Callers that need the wider range already have `encodeVarint64`.
|
|
262
|
+
Nothing in this package encoded a value in the refused range.
|
|
263
|
+
|
|
264
|
+
One decode-side strictness note that belongs with the wire work above and
|
|
265
|
+
was not recorded when it landed: an unknown field encoded as a group (wire
|
|
266
|
+
types 3 and 4) is rejected rather than skipped, where `protobufjs` skipped
|
|
267
|
+
it. Groups are deprecated, no schema here uses them, and skipping one
|
|
268
|
+
correctly means matching its end tag — a parser state this format has no
|
|
269
|
+
reason to carry.
|
|
270
|
+
|
|
271
|
+
- **The sealed-sender wire codec is hand-written, and no signed certificate
|
|
272
|
+
region is re-encoded on the way through.** Its five message types and the
|
|
273
|
+
`UnidentifiedSenderMessage.Type` enum were assembled at runtime by
|
|
274
|
+
`protobufjs` reflection, which compiles its encoders with `new Function` —
|
|
275
|
+
the construct a `script-src 'self'` policy blocks — and they are now static
|
|
276
|
+
encoders and decoders over the shared wire primitives. Every byte is
|
|
277
|
+
unchanged, which carries more weight here than anywhere else in the wire
|
|
278
|
+
work: a server certificate's signature is computed over its serialized
|
|
279
|
+
inner bytes and a sender certificate's over its own, so a shift in field
|
|
280
|
+
order, in a nested length prefix, or in whether an explicitly-set zero
|
|
281
|
+
reaches the wire would invalidate every certificate already issued. The
|
|
282
|
+
decoders hand signed regions back as the raw bytes they arrived as, never
|
|
283
|
+
as a re-encoded structure. The 19 committed golden vectors pin all of it in
|
|
284
|
+
both directions. Two decode paths do change, both for messages that were
|
|
285
|
+
already malformed or came from a peer this version does not know: an inner
|
|
286
|
+
message whose `type` names no declared arm — including an absent field,
|
|
287
|
+
which reads as 0 — now decodes to the value that arrived, where reflection
|
|
288
|
+
substituted the enum's first arm and so reported a `PREKEY_MESSAGE` the
|
|
289
|
+
sender never wrote, and callers that route on the value must narrow it with
|
|
290
|
+
`isSealedSenderContentType`; and a message with no `senderCertificate`
|
|
291
|
+
decodes to empty wrapper fields, which certificate validation rejects,
|
|
292
|
+
instead of raising `TypeError` from a null dereference. A third shift is
|
|
293
|
+
smaller still: string fields decode through `TextDecoder`, which maps
|
|
294
|
+
invalid UTF-8 to U+FFFD replacement characters where reflection produced
|
|
295
|
+
other strings — for one shape, an empty string the required-field check
|
|
296
|
+
then rejected. A certificate whose `senderUuid` is not valid UTF-8
|
|
297
|
+
therefore now decodes instead of failing that check; such bytes can only
|
|
298
|
+
exist under a trusted issuer's signature, and every issuer this SDK has
|
|
299
|
+
shipped writes valid UTF-8.
|
|
300
|
+
|
|
301
|
+
- **The SPQR wire and ratchet-state serializer no longer builds its schema
|
|
302
|
+
at runtime**, so the post-quantum ratchet works under a `script-src 'self'`
|
|
303
|
+
policy. The ML-KEM Braid codec described its eight messages to
|
|
304
|
+
`protobufjs` reflection, which compiles each encoder with `new Function` —
|
|
305
|
+
the one construct a strict Content-Security-Policy forbids, and the reason
|
|
306
|
+
the SDK threw `EvalError` in a hardened browser, an extension service
|
|
307
|
+
worker, or anywhere else code generation is off. The eight messages now
|
|
308
|
+
have hand-written encoders and decoders over the wire primitives, and the
|
|
309
|
+
module imports nothing from `protobufjs`. Every exported function keeps
|
|
310
|
+
its name and signature, and the presence rules that decide what reaches
|
|
311
|
+
the wire are unchanged: an explicitly-set zero is still written, an absent
|
|
312
|
+
field still decodes to its typed zero rather than `undefined`, and the
|
|
313
|
+
`V1Msg` `inner_msg` oneof still emits exactly one arm. That matters more
|
|
314
|
+
than usual here, because the encoder, decoder, and authenticator messages
|
|
315
|
+
are *persisted* ratchet state — an install that upgrades has to decode the
|
|
316
|
+
bytes it wrote before it upgraded. Byte identity is pinned by 49 golden
|
|
317
|
+
vectors covering each message, each oneof arm, empty and maximal repeated
|
|
318
|
+
fields, and epochs at 0, 1, 2^32, 2^53−1, 2^53+1, and 2^64−1.
|
|
319
|
+
|
|
320
|
+
Three behaviors moved, each away from silent corruption. A persisted
|
|
321
|
+
decoder chunk that carries an index but no data used to yield a map entry
|
|
322
|
+
holding `undefined`, which surfaced later as a confusing failure inside
|
|
323
|
+
Reed–Solomon reconstruction; it is now rejected where it is read, naming
|
|
324
|
+
the chunk — nothing in this package has ever written that shape, so it can
|
|
325
|
+
only come from corrupt state. Encoding state that violates its declared
|
|
326
|
+
types — a field that is not the `Uint8Array` it claims, a size that is
|
|
327
|
+
negative or above 4294967295 — now throws a named error where the old
|
|
328
|
+
encoder silently wrapped the value and wrote wrong bytes. And
|
|
329
|
+
`isSerializationReady()` now always returns `true`: with static codecs
|
|
330
|
+
there is no schema to build and no not-ready state to report
|
|
331
|
+
(`initSerialization()` stays as an awaitable no-op for callers that
|
|
332
|
+
sequence on it).
|
|
333
|
+
|
|
334
|
+
- **The Double Ratchet and sender-key message codecs no longer build their
|
|
335
|
+
wire types at runtime.** `SignalProtocolMessage`,
|
|
336
|
+
`PreKeySignalProtocolMessage`, `SenderKeyMessage`, and
|
|
337
|
+
`SenderKeyDistributionMessage` were encoded and decoded through
|
|
338
|
+
`protobufjs` reflection, which compiles each encoder with `new Function` —
|
|
339
|
+
the exact construct a `script-src 'self'` policy blocks. All four are now
|
|
340
|
+
hand-written encoders and `ProtoReader` decode loops over the shared wire
|
|
341
|
+
primitives, and neither module imports `protobufjs`. Nothing on the wire
|
|
342
|
+
moves: the twenty committed golden vectors for these two modules pin every
|
|
343
|
+
byte in both directions, including the behavior that is easiest to lose in
|
|
344
|
+
a rewrite — presence, not value, decides what is written, so a counter of
|
|
345
|
+
0 and a prekey id of 0 stay distinguishable from an absent field, an empty
|
|
346
|
+
bytes field still reaches the wire and is still dropped on decode, and
|
|
347
|
+
unknown fields are still skipped. Decoding is stricter in one respect
|
|
348
|
+
inherited from the primitives: a field whose wire type contradicts its tag
|
|
349
|
+
is now rejected rather than read as its declared type.
|
|
350
|
+
|
|
351
|
+
- **The protobuf wire primitives now cover 64-bit varints and the field
|
|
352
|
+
shapes the message schemas actually use**, which is the groundwork for
|
|
353
|
+
encoding every message here without `protobufjs` — and so without the
|
|
354
|
+
runtime code generation that a `script-src 'self'` policy blocks. The
|
|
355
|
+
varint helpers stopped at 32 bits in five bytes, so the SPQR epoch, a
|
|
356
|
+
uint64, had no representation that survived a round trip; there are now
|
|
357
|
+
bigint encode and decode functions with a ten-byte ceiling, alongside
|
|
358
|
+
helpers for bool, enum, string, fixed64, embedded-message, and repeated
|
|
359
|
+
fields, and a `ProtoReader` cursor that owns the read-tag-dispatch-skip
|
|
360
|
+
loop every decoder repeats. The existing 32-bit functions are untouched
|
|
361
|
+
and byte-compatible. Two contracts are deliberately stricter than
|
|
362
|
+
`protobufjs`: a varint must be canonically encoded, because these bytes
|
|
363
|
+
are signed and MAC'd and a redundant encoding would make the signed byte
|
|
364
|
+
string malleable; and a field whose wire type contradicts its tag is
|
|
365
|
+
rejected rather than misread. Nothing on the wire moves — no encoder has
|
|
366
|
+
ever emitted the forms now refused.
|
|
367
|
+
|
|
368
|
+
- **The public repository's snippet check no longer requires an unpublished
|
|
369
|
+
file.** `0.1.0-alpha.8` removed the internal pricing preview from the
|
|
370
|
+
export, but `run-mock-snippets.mjs` — which ships in both repositories —
|
|
371
|
+
still read it unconditionally, so the public "shipped mock snippets" CI job
|
|
372
|
+
failed with ENOENT from the `0.1.0-alpha.9` push onward. The runner now
|
|
373
|
+
validates that file's snippets only where the file exists, which is the
|
|
374
|
+
boundary the export already draws. `ossf/scorecard-action` also moves to
|
|
375
|
+
v2.4.4 (dependabot, applied here so the export carries it).
|
|
376
|
+
|
|
3
377
|
## 0.1.0-alpha.9
|
|
4
378
|
|
|
5
379
|
- **BREAKING: the multi-recipient content ceiling is the reference's
|
package/README.md
CHANGED
|
@@ -31,7 +31,15 @@
|
|
|
31
31
|
|
|
32
32
|
*Not affiliated with Signal Messenger.* This is an independent implementation of the public Signal Protocol specifications — full notice in [NOTICE](https://github.com/open-e2ee/signal-protocol-js/blob/main/NOTICE). It is **not wire-compatible with Signal Messenger or libsignal**: messages, identities, and safety numbers do not interoperate, and every deliberate difference is documented in [DEVIATIONS](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md).
|
|
33
33
|
|
|
34
|
-
`0.1.
|
|
34
|
+
`0.1.x` — public APIs and persisted formats may change before `1.0`.
|
|
35
|
+
|
|
36
|
+
## See it run
|
|
37
|
+
|
|
38
|
+
[](https://open-e2ee.dev/demo/#add-a-second-device)
|
|
39
|
+
|
|
40
|
+
A second device is linked to an account over the real QR handshake. The message sent before that device existed is not on it — not withheld by a policy, but unreadable because the device's keys did not exist when that message was encrypted.
|
|
41
|
+
|
|
42
|
+
Recorded from [open-e2ee.dev/demo](https://open-e2ee.dev/demo), which runs this package in the browser against the in-memory store and the in-memory relay: real protocol and cryptography, simulated in-memory infrastructure. Every scenario there prints the receiving device's own log, unedited.
|
|
35
43
|
|
|
36
44
|
## Install
|
|
37
45
|
|
|
@@ -51,24 +59,24 @@ Adapters declare their runtime requirements as optional peer dependencies, so in
|
|
|
51
59
|
|
|
52
60
|
Two clients, one process, no account and no server. The relay holds the envelope; only Bob's device turns it back into text.
|
|
53
61
|
|
|
54
|
-
<!--
|
|
62
|
+
<!-- doc-snippet:run readme-quick-start expect="alice: hello" -->
|
|
55
63
|
```ts
|
|
56
64
|
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
57
65
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
58
|
-
import {
|
|
59
|
-
import {
|
|
66
|
+
import { inMemoryStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
|
|
67
|
+
import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
|
|
60
68
|
|
|
61
|
-
const relay =
|
|
69
|
+
const relay = inMemoryRelay();
|
|
62
70
|
await relay.registerDevice("alice", { encryptedDeviceName: new ArrayBuffer(0) });
|
|
63
71
|
await relay.registerDevice("bob", { encryptedDeviceName: new ArrayBuffer(0) });
|
|
64
72
|
|
|
65
73
|
const alice = await createSignalProtocolClient({
|
|
66
74
|
identity: { userId: "alice" },
|
|
67
|
-
adapters: { storage:
|
|
75
|
+
adapters: { storage: inMemoryStore(), relay },
|
|
68
76
|
});
|
|
69
77
|
const bob = await createSignalProtocolClient({
|
|
70
78
|
identity: { userId: "bob" },
|
|
71
|
-
adapters: { storage:
|
|
79
|
+
adapters: { storage: inMemoryStore(), relay },
|
|
72
80
|
});
|
|
73
81
|
|
|
74
82
|
await alice.syncToServer();
|
|
@@ -89,23 +97,25 @@ Next: [inspect what the relay actually stored](https://github.com/open-e2ee/sign
|
|
|
89
97
|
|
|
90
98
|
## How it compares
|
|
91
99
|
|
|
92
|
-
Measured from the GitHub
|
|
100
|
+
Measured from the GitHub API, the npm registry API, and the published package tarballs on 2026-08-03. Every alternative is a real project doing a real job; the axes below are the ones this SDK was built to change, not a general quality ranking.
|
|
93
101
|
|
|
94
102
|
| | Expo / React Native | Browser | Maintained | Post-quantum | TypeScript-native | Commercial license |
|
|
95
103
|
|---|---|---|---|---|---|---|
|
|
96
|
-
| **`@open-e2ee/signal-protocol-sdk`** | Yes | Yes
|
|
97
|
-
| [`@signalapp/libsignal-client`](https://github.com/signalapp/libsignal) | No —
|
|
104
|
+
| **`@open-e2ee/signal-protocol-sdk`** | Yes | Yes | Yes — `0.1.x`, active | Key agreement yes — PQXDH + ML-KEM, default and fails closed. Signatures no — identities are classical Ed25519 | Yes | Yes |
|
|
105
|
+
| [`@signalapp/libsignal-client`](https://github.com/signalapp/libsignal) | No — Node native addon; the 0.99.3 tarball ships binaries for macOS, Linux, and Windows only | No | Yes — very active; repo push 2026-07-31 | Key agreement yes | No — Rust core with TypeScript bindings | No (AGPL-3.0 only) |
|
|
98
106
|
| [`libsignal-protocol-javascript`](https://github.com/signalapp/libsignal-protocol-javascript) | No | Yes | No — archived, last push 2021-08-04 | No | No — JavaScript | No (GPL-3.0) |
|
|
99
107
|
| [`@privacyresearch/libsignal-protocol-typescript`](https://github.com/privacyresearchgroup/libsignal-protocol-typescript) | No documented React Native path | Yes | No — last npm publish 2023-05-06, last repo push 2023-07-18 | No | Yes | No (GPL-3.0) |
|
|
100
|
-
| [`ts-mls`](https://github.com/LukaJCB/ts-mls) |
|
|
108
|
+
| [`ts-mls`](https://github.com/LukaJCB/ts-mls) | Not stated — browsers, Node, and serverless are the documented targets | Yes | Yes — very active; repo push 2026-08-03 | Key agreement and signatures — ML-KEM and ML-DSA-87 ciphersuites | Yes | Not needed (MIT) |
|
|
109
|
+
|
|
110
|
+
`ts-mls` implements [MLS (RFC 9420)](https://www.rfc-editor.org/rfc/rfc9420.html), a different protocol with different properties — if MLS suits your product, it is a good library and this table is not an argument against it, and its post-quantum coverage reaches further than this SDK's. `@signalapp/libsignal-client` is the implementation Signal Messenger itself uses; its README states that use outside Signal Messenger is unsupported. If you are shipping a desktop or server application on Node, reach for it first.
|
|
101
111
|
|
|
102
|
-
|
|
112
|
+
The longer version of this table, with a paragraph on each project, is at [open-e2ee.dev/compare](https://open-e2ee.dev/compare).
|
|
103
113
|
|
|
104
114
|
## Trust and verification
|
|
105
115
|
|
|
106
116
|
Cryptography deserves evidence rather than adjectives, so here is what there is and what there is not.
|
|
107
117
|
|
|
108
|
-
**Audit status.**
|
|
118
|
+
**Audit status.** Reviewed continuously by adversarial AI agents; not audited by any independent firm. Every change passes an adversarial AI review before it merges, and recurring whole-codebase AI audit passes run against the engineering repository. What that covers — and what it does not — is stated in the [assurance summary](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/ASSURANCE.md). No independent firm has audited the SDK, and none is engaged. Nothing here should be read as a third-party assurance claim.
|
|
109
119
|
|
|
110
120
|
**Security model and protocol policy.** The [security model](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/SECURITY.md) states the threat model, what is in and out of scope, the storage boundary, and the resource limits. The [protocol policy](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/PROTOCOL_POLICY.md) states which protocol modes are supported and which fail closed.
|
|
111
121
|
|
|
@@ -123,13 +133,13 @@ Cryptography deserves evidence rather than adjectives, so here is what there is
|
|
|
123
133
|
|
|
124
134
|
**Not wire-compatible, and specific about why.** This SDK cannot exchange messages with Signal Messenger or `libsignal`, cannot exchange identities with them, and its safety numbers will never match the ones a Signal Messenger client displays for the same two users. The cryptographic core is the same; the wire profile is deliberately its own. Identities are a versioned composite of separate X25519 and Ed25519 keys rather than one Curve25519 key, so signatures are ordinary RFC 8032 Ed25519 rather than XEdDSA; ML-KEM-1024 keys and ciphertexts are tagged `0x0A`, distinct from the round-3 Kyber1024 `0x08` tag. [DEVIATIONS](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md) is the complete account — every difference from the specifications and from `libsignal`, with the reason, the cost, and the file that implements it. The threat model boundary is in the [security model](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/SECURITY.md).
|
|
125
135
|
|
|
126
|
-
**Dependencies:
|
|
136
|
+
**Dependencies: 6.** Six direct production dependencies — `@noble/ciphers`, `@noble/curves`, `@noble/hashes`, `@noble/post-quantum`, `async-lock`, `unique-names-generator` — resolving to 6 packages in total: the only transitive edges are the `@noble` packages depending on one another, so the resolved tree adds nothing the list above does not already name. Everything else in the tree is a development or optional peer dependency.
|
|
127
137
|
|
|
128
138
|
**Automated checks.** The published repository is a mechanized export of a private engineering repository, filtered by an allowlist; the automated checks live there and have to pass before an export is cut. The [assurance summary](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/ASSURANCE.md) carries the current run figures — regenerated from a real run as part of every release, never hand-edited — and explains what the checks cover, what is not published, and why. The published repository runs its own build, typecheck, and production dependency audit in [CI](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml) on every change.
|
|
129
139
|
|
|
130
140
|
**Constant-time posture, honestly.** JavaScript engines offer no machine-level constant-time contract, and this SDK cannot invent one. What exists is best-effort source-level work on selected paths: full-scan comparison for equal-length MACs and identity bytes, fixed-work derivation of both decapsulation candidates before masked selection, and equal-work rejection padding on selected replay and authentication paths. These are not timing-equivalence proofs. Secret-influenced remainder and compression arithmetic remains, and JIT compilation, allocation, garbage collection, and cache effects stay observable. `secureZeroBytes()` overwrites the exact typed array it is handed and nothing more — not copies, not strings, not engine temporaries. The threat model does not cover hostile same-process code or a high-assurance co-resident timing adversary, and it says so.
|
|
131
141
|
|
|
132
|
-
**Reporting a vulnerability.** Email security@open-e2ee.dev rather than opening an issue. Acknowledgment within
|
|
142
|
+
**Reporting a vulnerability.** Email security@open-e2ee.dev rather than opening an issue. Acknowledgment within 72 hours, initial assessment within 7 days; the full policy is in [SECURITY.md](https://github.com/open-e2ee/signal-protocol-js/blob/main/SECURITY.md).
|
|
133
143
|
|
|
134
144
|
## Documentation
|
|
135
145
|
|
package/SECURITY.md
CHANGED
|
@@ -36,7 +36,7 @@ own policies.
|
|
|
36
36
|
|
|
37
37
|
### What to Expect
|
|
38
38
|
|
|
39
|
-
- **Acknowledgment**: Within
|
|
39
|
+
- **Acknowledgment**: Within 72 hours of your report
|
|
40
40
|
- **Initial Assessment**: Within 7 days
|
|
41
41
|
- **Resolution Timeline**: Depends on severity
|
|
42
42
|
- Critical: 24-72 hours
|
package/client/README.md
CHANGED
|
@@ -17,12 +17,12 @@ messaging. `protocol.postQuantum` and `protocol.braid` both default to
|
|
|
17
17
|
|
|
18
18
|
```ts
|
|
19
19
|
import { createSignalProtocolClient, ProtocolAddress } from '@open-e2ee/signal-protocol-sdk';
|
|
20
|
-
import {
|
|
20
|
+
import { inMemoryStore } from '@open-e2ee/signal-protocol-sdk/local/store/memory';
|
|
21
21
|
|
|
22
22
|
const signal = await createSignalProtocolClient({
|
|
23
23
|
// A local-only client still needs storage for this device's key/session state.
|
|
24
24
|
identity: { userId: 'alice' },
|
|
25
|
-
adapters: { storage:
|
|
25
|
+
adapters: { storage: inMemoryStore() },
|
|
26
26
|
});
|
|
27
27
|
|
|
28
28
|
// ProtocolAddress is for direct device-level APIs.
|
package/device/README.md
CHANGED
|
@@ -91,10 +91,12 @@ provisioning result:
|
|
|
91
91
|
```ts
|
|
92
92
|
import {
|
|
93
93
|
connectToProvisioningSession,
|
|
94
|
-
getDeviceMetadata,
|
|
95
94
|
parseProvisioningQR,
|
|
96
95
|
receiveProvisioningMessage,
|
|
97
96
|
} from "@open-e2ee/signal-protocol-sdk/device/provisioning";
|
|
97
|
+
// Reads `react-native` and `expo-constants`, so it is imported separately from
|
|
98
|
+
// the protocol itself. Off Expo, build the same four fields by hand.
|
|
99
|
+
import { getDeviceMetadata } from "@open-e2ee/signal-protocol-sdk/device/expo-metadata";
|
|
98
100
|
|
|
99
101
|
const {
|
|
100
102
|
sessionId,
|