@open-e2ee/signal-protocol-sdk 0.3.0 → 0.4.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 (77) hide show
  1. package/ADAPTERS.md +7 -0
  2. package/ARCHITECTURE.md +2 -0
  3. package/CHANGELOG.md +33 -0
  4. package/README.md +64 -102
  5. package/SECURITY.md +2 -2
  6. package/TROUBLESHOOTING.md +7 -0
  7. package/blocking/README.md +1 -0
  8. package/client/README.md +10 -0
  9. package/device/README.md +5 -0
  10. package/dist/client/groups.d.ts.map +1 -1
  11. package/dist/client/groups.js +14 -4
  12. package/dist/client/groups.js.map +1 -1
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +3 -4
  15. package/dist/index.js.map +1 -1
  16. package/dist/internal/sesame/types.d.ts +0 -2
  17. package/dist/internal/sesame/types.d.ts.map +1 -1
  18. package/dist/internal/sesame/types.js +0 -2
  19. package/dist/internal/sesame/types.js.map +1 -1
  20. package/dist/media/index.d.ts +0 -1
  21. package/dist/media/index.d.ts.map +1 -1
  22. package/dist/media/index.js +0 -1
  23. package/dist/media/index.js.map +1 -1
  24. package/dist/remote/relay/convex/backend.d.ts +2 -2
  25. package/dist/remote/relay/convex/backend.d.ts.map +1 -1
  26. package/dist/remote/relay/convex/backend.js +1 -1
  27. package/dist/remote/relay/convex/backend.js.map +1 -1
  28. package/dist/remote/relay/convex/component/_generated/component.d.ts +2 -2
  29. package/dist/remote/relay/convex/component/_generated/component.d.ts.map +1 -1
  30. package/dist/remote/relay/convex/component/messages.d.ts +2 -2
  31. package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
  32. package/dist/remote/relay/convex/component/messages.js +1 -1
  33. package/dist/remote/relay/convex/component/messages.js.map +1 -1
  34. package/dist/remote/relay/convex/component/schema.d.ts +2 -2
  35. package/dist/remote/relay/convex/component/schema.js +1 -1
  36. package/dist/remote/relay/convex/component/schema.js.map +1 -1
  37. package/dist/utils/retry.d.ts +2 -1
  38. package/dist/utils/retry.d.ts.map +1 -1
  39. package/dist/utils/retry.js +2 -1
  40. package/dist/utils/retry.js.map +1 -1
  41. package/docs/ASSURANCE.md +11 -5
  42. package/docs/CLIENT_COMPOSITION.md +3 -0
  43. package/docs/DOCUMENTATION_STANDARDS.md +28 -0
  44. package/docs/ERROR_HANDLING.md +91 -60
  45. package/docs/GETTING_STARTED.md +20 -1
  46. package/docs/INTERFACES.md +5 -0
  47. package/docs/PACKAGE_SURFACE.md +1 -0
  48. package/docs/PROTOCOL_POLICY.md +6 -0
  49. package/docs/RECIPES.md +9 -0
  50. package/encoding/README.md +1 -0
  51. package/files/README.md +1 -0
  52. package/groups/README.md +1 -0
  53. package/keys/README.md +2 -0
  54. package/local/store/README.md +2 -0
  55. package/local/store/expo/README.md +2 -0
  56. package/local/store/memory/README.md +2 -0
  57. package/local/store/node/README.md +1 -0
  58. package/local/store/react-native/README.md +2 -0
  59. package/local/store/web/README.md +1 -0
  60. package/local/vault/README.md +1 -0
  61. package/media/README.md +2 -0
  62. package/package.json +4 -2
  63. package/profile/README.md +1 -0
  64. package/remote/README.md +6 -0
  65. package/remote/object-store/README.md +1 -0
  66. package/remote/object-store/convex-r2/README.md +2 -0
  67. package/remote/object-store/s3/README.md +1 -0
  68. package/remote/relay/README.md +2 -0
  69. package/remote/relay/convex/README.md +1 -0
  70. package/remote/relay/convex/component/README.md +9 -0
  71. package/remote/relay/memory/README.md +2 -0
  72. package/safety/README.md +1 -0
  73. package/sealed-sender/README.md +1 -0
  74. package/types/README.md +1 -0
  75. package/username/README.md +1 -0
  76. package/utils/README.md +1 -0
  77. package/zk/README.md +1 -0
package/ADAPTERS.md CHANGED
@@ -67,7 +67,9 @@ functions retain authentication, authorization, and persistence.
67
67
 
68
68
  ### Minimal local client
69
69
 
70
+ <!-- doc-snippet:run adapters-local-client expect="" -->
70
71
  ```ts
72
+ // Real protocol and cryptography; simulated in-memory infrastructure.
71
73
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
72
74
  import { inMemoryStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
73
75
 
@@ -79,6 +81,7 @@ const signal = await createSignalProtocolClient({
79
81
 
80
82
  ### Production client
81
83
 
84
+ <!-- doc-snippet:skip requires-production-adapters -->
82
85
  ```ts
83
86
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
84
87
  import {
@@ -110,7 +113,9 @@ database and SQLCipher bootstrap.
110
113
 
111
114
  ### Local development with a shared relay
112
115
 
116
+ <!-- doc-snippet:run adapters-shared-relay expect="" -->
113
117
  ```ts
118
+ // Real protocol and cryptography; simulated in-memory infrastructure.
114
119
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
115
120
  import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
116
121
  import { inMemoryStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
@@ -160,6 +165,7 @@ Prefer these composition patterns:
160
165
 
161
166
  Use the public interfaces:
162
167
 
168
+ <!-- doc-snippet:skip requires-external-context -->
163
169
  ```ts
164
170
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
165
171
  import type { ISignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/relay";
@@ -169,6 +175,7 @@ import type { ISignalProtocolLocalStore } from "@open-e2ee/signal-protocol-sdk/l
169
175
 
170
176
  Then compose them through `createSignalProtocolClient()`:
171
177
 
178
+ <!-- doc-snippet:skip requires-external-context -->
172
179
  ```ts
173
180
  const signal = await createSignalProtocolClient({
174
181
  identity: { userId },
package/ARCHITECTURE.md CHANGED
@@ -56,6 +56,7 @@ modify the code.
56
56
 
57
57
  The root package is core-only:
58
58
 
59
+ <!-- doc-snippet:skip requires-external-context -->
59
60
  ```ts
60
61
  import {
61
62
  SignalProtocolClient,
@@ -152,6 +153,7 @@ This boundary prevents lower protocol/session layers from depending on the clien
152
153
 
153
154
  Application code should prefer:
154
155
 
156
+ <!-- doc-snippet:skip requires-external-context -->
155
157
  ```ts
156
158
  await createSignalProtocolClient({
157
159
  identity: { userId },
package/CHANGELOG.md CHANGED
@@ -1,5 +1,38 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.4.0
4
+
5
+ - **The README now provides a runnable encrypted round trip and a current demo.**
6
+ The quickstart exercises two SDK clients through the in-memory relay. The new
7
+ recording shows the same two-device and relay flow as the live desktop and
8
+ mobile demo.
9
+
10
+ - **Error-surface checks reject unresolved codes and cover media attachment
11
+ codes.** The analyser now reports forwarded code arguments in CI.
12
+ It also checks every `MediaAttachmentErrorCode` value.
13
+ This release removes `RemoteObjectStoreNotConfigured` because no media
14
+ operation could produce it.
15
+
16
+ - **The retry-request wire surface no longer includes
17
+ `RetryReason.INVALID_MESSAGE`.** No local failure produced it. The incoming
18
+ retry handler did not support it. Malformed ciphertext failures use the supported
19
+ `DECRYPTION_FAILED` recovery path.
20
+
21
+ - **Generated API pages and shipped documentation examples now have source
22
+ gates.** CI regenerates `docs/api` with pinned tool versions. It rejects a
23
+ diff. The snippet runner scans every packaged Markdown file and the internal
24
+ lifecycle docs. It executes every complete example and matches its output.
25
+ For an example that cannot run, it compiles every SDK name against the packed
26
+ package. A renamed or deleted export therefore fails the build in every
27
+ document that names it.
28
+
29
+ An example that previews an unreleased API declares the import paths that do
30
+ not exist yet. The build fails if one of them resolves. Only pseudocode is
31
+ exempt, and the build names each exempt block on its own line.
32
+
33
+ - **The error guide now documents all 33 `EncryptionErrorCode` values.** Its
34
+ session examples also use the current `ProtocolAddress` method signatures.
35
+
3
36
  ## 0.3.0
4
37
 
5
38
  - **Breaking: seven error classes and sixteen `EncryptionErrorCode` members are
package/README.md CHANGED
@@ -5,60 +5,46 @@
5
5
  **End-to-end encrypted messaging for TypeScript apps. Signal Protocol, post-quantum by default, runs in Expo.**
6
6
 
7
7
  [![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-2f6f5e)](https://github.com/open-e2ee/signal-protocol-js/blob/main/LICENSE)
8
- [![Types: TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6)](https://www.typescriptlang.org/)
9
8
  [![npm version](https://img.shields.io/npm/v/@open-e2ee/signal-protocol-sdk)](https://www.npmjs.com/package/@open-e2ee/signal-protocol-sdk)
10
- [![native modules: 0](https://img.shields.io/badge/native_modules-0-2f6f5e)](https://github.com/open-e2ee/signal-protocol-js/blob/main/ARCHITECTURE.md)
9
+ [![native crypto: 0](https://img.shields.io/badge/native_crypto-0-2f6f5e)](./ARCHITECTURE.md)
11
10
  [![npm provenance](https://img.shields.io/badge/npm-provenance-2f6f5e)](https://www.npmjs.com/package/@open-e2ee/signal-protocol-sdk#provenance)
12
11
  [![Checks](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml/badge.svg)](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml)
13
- [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/open-e2ee/signal-protocol-js/badge)](https://scorecard.dev/viewer/?uri=github.com/open-e2ee/signal-protocol-js)
14
- [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14043/badge)](https://www.bestpractices.dev/projects/14043)
15
12
 
16
13
  [Website](https://open-e2ee.dev) ·
17
- [Docs](https://docs.open-e2ee.dev) ·
18
- [Quick Start](#quick-start) ·
19
- [Architecture](https://github.com/open-e2ee/signal-protocol-js/blob/main/ARCHITECTURE.md) ·
20
- [Security Model](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/SECURITY.md) ·
21
- [Protocol Policy](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/PROTOCOL_POLICY.md) ·
22
- [Deviations](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md)
14
+ [Documentation](https://docs.open-e2ee.dev) ·
15
+ [Live demo](https://open-e2ee.dev/#demo) ·
16
+ [API reference](https://docs.open-e2ee.dev/reference/api) ·
17
+ [Security](./SECURITY.md)
23
18
 
24
- ---
19
+ - **One TypeScript package.** Run the same protocol code in Expo, React Native, modern browsers, and Node.
20
+ - **Post-quantum by default.** The default policy requires PQXDH session establishment and the ML-KEM Braid post-quantum ratchet. Required post-quantum operations fail closed.
21
+ - **Messaging primitives included.** Build multi-device messaging, groups, sealed sender, encrypted attachments, and safety-number verification.
22
+ - **Your infrastructure, behind explicit interfaces.** Your application owns device-local storage. The relay is an interface, not a hosted service. The relay never needs message plaintext or device private keys.
23
+ - **AGPLv3, or a commercial license.** Proprietary applications that cannot meet AGPLv3 obligations can use a [commercial license](./COMMERCIAL.md).
25
24
 
26
- - **Pure TypeScript.** No native modules, no prebuild step, no platform binaries to ship.
27
- - **Runs where your app runs.** Expo, React Native, modern browsers, and Node from one package.
28
- - **Post-quantum by default.** PQXDH and ML-KEM session establishment are on without configuration, and fail closed.
29
- - **Real messaging features.** Multi-device, groups, sealed sender, encrypted attachments, safety numbers.
30
- - **Pluggable storage and relay.** Your application owns the required device-local storage. The relay is an interface, not a hosted service.
31
- - **AGPLv3, or a commercial license.** Building something closed-source? See [COMMERCIAL](https://github.com/open-e2ee/signal-protocol-js/blob/main/COMMERCIAL.md).
25
+ The protocol code ships without a native crypto module or platform crypto binary. The Expo SQLCipher store requires a development build and native project configuration.
32
26
 
33
- *Not affiliated with Signal Messenger.* This package implements the public Signal Protocol specifications independently. [NOTICE](https://github.com/open-e2ee/signal-protocol-js/blob/main/NOTICE) carries the full notice. It is **not wire-compatible with Signal Messenger or libsignal**. Messages, identities, and safety numbers do not interoperate, and [DEVIATIONS](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md) documents every deliberate difference.
27
+ Version `0.4.x`. Public APIs and persisted formats can change before `1.0`.
34
28
 
35
- Version `0.3.x`. Public APIs and persisted formats may change before `1.0`.
29
+ OpenE2EE implements a versioned profile of the published Signal Protocol specifications. It is not affiliated with Signal Messenger and is **not wire-compatible with Signal Messenger or libsignal**. Messages, identities, and safety numbers do not interoperate. Read the [full notice](./NOTICE) and [documented deviations](./docs/DEVIATIONS.md).
36
30
 
37
- ## See it run
31
+ ## See an encrypted round trip
38
32
 
39
- [![Linking a second device on the demo page. The scenario runs, then reports what each device can read. The device that was already there holds both messages. The newly linked device holds only the message sent after it existed.](https://raw.githubusercontent.com/open-e2ee/signal-protocol-js/main/docs/assets/demo/second-device.gif)](https://open-e2ee.dev/demo/#add-a-second-device)
33
+ [![Two devices exchange an end-to-end encrypted message through a relay. The relay handles public prekeys and ciphertext. Only the receiving device displays the plaintext.](https://raw.githubusercontent.com/open-e2ee/signal-protocol-js/main/docs/assets/demo/encrypted-round-trip.gif)](https://open-e2ee.dev/#demo)
40
34
 
41
- The demo links a second device to an account over the real QR handshake. That device does not hold the message sent before it existed. No policy withholds the message. The device cannot read it, because the device's keys did not exist when the sender encrypted it.
42
-
43
- The recording comes from [open-e2ee.dev/demo](https://open-e2ee.dev/demo). That page runs this package in the browser against the in-memory store and the in-memory relay. The protocol and the cryptography are real, and the adapters simulate the infrastructure in memory. Every scenario there prints the receiving device's own log, unedited.
35
+ The [live demo](https://open-e2ee.dev/#demo) runs two SDK clients against an in-memory relay. On desktop, type a message and inspect the envelope, ratchets, relay mailbox, and decrypted result. On mobile, the same protocol run replays at reading pace. The protocol and cryptography are real. The example simulates infrastructure in memory. Displayed timings exclude network time.
44
36
 
45
37
  ## Install
46
38
 
47
- ```bash
48
- npm install @open-e2ee/signal-protocol-sdk
49
- ```
50
-
51
- Installing straight from the repository also works. The package compiles itself during install, so TypeScript is the only build requirement:
39
+ Requires Node 18 or later for the local example.
52
40
 
53
41
  ```bash
54
- npm install github:open-e2ee/signal-protocol-js
42
+ npm install @open-e2ee/signal-protocol-sdk
55
43
  ```
56
44
 
57
- Adapters declare their runtime requirements as optional peer dependencies, so install the ones your chosen adapters need (for example `expo-sqlite` and `expo-secure-store`, or `convex`).
45
+ ## Run a local encrypted round trip
58
46
 
59
- ## Quick Start
60
-
61
- Two clients, one process, no account and no server. The relay holds the envelope. Only Bob's device turns it back into text.
47
+ Save this as `quickstart.mjs`, then run `node quickstart.mjs`. It uses development-only in-memory adapters so that you can prove the message flow without a backend project.
62
48
 
63
49
  <!-- doc-snippet:run readme-quick-start expect="alice: hello" -->
64
50
  ```ts
@@ -80,97 +66,73 @@ const bob = await createSignalProtocolClient({
80
66
  adapters: { storage: inMemoryStore(), relay },
81
67
  });
82
68
 
83
- await alice.syncToServer();
84
- await bob.syncToServer();
85
-
86
- // Decrypted content reaches your app here, and nowhere else.
87
- bob.registerHook("onMessageDecrypted", async (message) => {
88
- console.log(`${message.senderId}: ${message.content}`); // alice: hello
69
+ const delivered = new Promise((resolve) => {
70
+ bob.registerHook("onMessageDecrypted", async (message) => {
71
+ console.log(`${message.senderId}: ${message.content}`);
72
+ bob.stopRelaySubscription();
73
+ resolve(undefined);
74
+ });
89
75
  });
90
76
 
91
- await alice.send("bob", "hello"); // the relay now holds ciphertext and metadata
92
- bob.startRelaySubscription(); // delivery and local decryption start here
77
+ await alice.send("bob", "hello");
78
+ bob.startRelaySubscription();
79
+ await delivered;
93
80
  ```
94
81
 
95
- Every identifier above is a real export. [This repository's CI](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml) extracts this exact block from this README and runs it against the packed package on every change. The same sequence runs in the engineering repository's automated checks.
82
+ Expected output:
96
83
 
97
- Next: [inspect what the relay actually stored](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/GETTING_STARTED.md), then compose the [Expo + Convex production client](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/CLIENT_COMPOSITION.md).
98
-
99
- ## How it compares
100
-
101
- Measured on 2026-08-03, these figures come from the GitHub API, the npm registry API, and the published package tarballs. Every alternative is a real project that does a real job. The axes below are the ones this SDK sets out to change, not a general quality ranking.
102
-
103
- | | Expo / React Native | Browser | Maintained | Post-quantum | TypeScript-native | Commercial license |
104
- |---|---|---|---|---|---|---|
105
- | **`@open-e2ee/signal-protocol-sdk`** | Yes | Yes | Yes — `0.3.x`, active | Key agreement yes — PQXDH + ML-KEM, default and fails closed. Signatures no — identities are classical Ed25519 | Yes | Yes |
106
- | [`@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) |
107
- | [`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) |
108
- | [`@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) |
109
- | [`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) |
110
-
111
- `ts-mls` implements [MLS (RFC 9420)](https://www.rfc-editor.org/rfc/rfc9420.html). That is a different protocol with different properties. If MLS suits your product, `ts-mls` is a good library, and this table is not an argument against it. Its post-quantum coverage also reaches further than this SDK's.
112
-
113
- `@signalapp/libsignal-client` is the implementation Signal Messenger itself uses. Its README states that it does not support use outside Signal Messenger. Reach for it first when you ship a desktop or server application on Node.
84
+ ```text
85
+ alice: hello
86
+ ```
114
87
 
115
- The longer version of this table, with a paragraph on each project, is at [open-e2ee.dev/compare](https://open-e2ee.dev/compare).
88
+ The client factory creates or loads each device identity. When given a relay, it also publishes the public prekey bundle. `send()` fetches Bob's bundle and starts the required post-quantum session. It then gives ciphertext plus routing metadata to the relay. Bob's subscription retrieves and decrypts the envelope on his device.
116
89
 
117
- ## Trust and verification
90
+ The in-memory store loses identities, sessions, and ratchet state on restart. The in-memory relay has no authentication, authorization, or durable storage. Do not ship either adapter. Continue with the [hosted Quickstart](https://docs.open-e2ee.dev/start/quickstart), which explains key custody, relay metadata, prekey replenishment, additional devices, and recovery policy.
118
91
 
119
- Cryptography deserves evidence rather than adjectives, so here is what there is and what there is not.
92
+ ## Move to production storage
120
93
 
121
- **Audit status.** Adversarial AI agents review this SDK continuously. No independent firm audits it. Every change passes an adversarial AI review before it merges, and recurring whole-codebase AI audit passes run against the engineering repository. The [assurance summary](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/ASSURANCE.md) states what that covers and what it does not. The SDK has no independent audit and no audit engagement. Read nothing here as a third-party assurance claim.
94
+ Choose the device-local store for your runtime, then supply a relay that authenticates each device and implements your product's access policy.
122
95
 
123
- **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 and the scope boundary. It also states 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 the SDK supports and which fail closed.
96
+ | Runtime | Storage path | Deployment boundary |
97
+ |---|---|---|
98
+ | Expo | [`expoStore`](./local/store/expo/README.md) | Configure SQLCipher before schema access. Requires a development build; it does not run in Expo Go. |
99
+ | Browser | [`indexedDbStore`](./local/store/web/README.md) | IndexedDB persists encrypted records, but same-origin JavaScript can access the records and their key. Review CSP, XSS, dependencies, and service workers. |
100
+ | Bare React Native | [`reactNativeStore`](./local/store/react-native/README.md) | Provide an atomic, durable key-value backend and run the exported backend conformance kit. |
101
+ | Node | [`nodeStore`](./local/store/node/README.md) | Set an explicit private data directory on a trusted local filesystem. |
124
102
 
125
- **Specifications, pinned by revision.** The implementation follows its own versioned profile based on these published specifications:
103
+ The [adapter guide](./ADAPTERS.md) defines every storage, relay, vault, and object-store boundary. The [client composition guide](./docs/CLIENT_COMPOSITION.md) shows an Expo and Convex integration.
126
104
 
127
- | Specification | Revision |
128
- |---|---|
129
- | [X3DH](https://signal.org/docs/specifications/x3dh/) | Revision 1, 2016-11-04 |
130
- | [PQXDH](https://signal.org/docs/specifications/pqxdh/) | Revision 3, 2023-05-24 (last updated 2024-01-23) |
131
- | [Double Ratchet](https://signal.org/docs/specifications/doubleratchet/) | Revision 4, 2025-11-04 |
132
- | [Sesame](https://signal.org/docs/specifications/sesame/) | Revision 2, 2017-04-14 |
133
- | [ML-KEM Braid](https://signal.org/docs/specifications/mlkembraid/) | Revision 1, 2025-02-21 (last updated 2025-09-26) |
134
- | [FIPS 203 (ML-KEM)](https://csrc.nist.gov/pubs/fips/203/final) | Final, 2024-08-13 |
135
- | [RFC 8032 (Ed25519)](https://www.rfc-editor.org/rfc/rfc8032.html) | — |
105
+ ## Security and assurance
136
106
 
137
- **Not wire-compatible, and specific about why.** This SDK cannot exchange messages or identities with Signal Messenger or `libsignal`. 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.
107
+ The [assurance summary](./docs/ASSURANCE.md) states what the automated checks cover and what the public export does not contain. Public CI rebuilds, type-checks, audits, and runs this README example against the packed package.
138
108
 
139
- Identities are a versioned composite of separate X25519 and Ed25519 keys rather than one Curve25519 key. Signatures are therefore ordinary RFC 8032 Ed25519 rather than XEdDSA. ML-KEM-1024 keys and ciphertexts carry the tag `0x0A`, which differs from the round-3 Kyber1024 tag `0x08`. [DEVIATIONS](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md) is the complete account. It names every difference from the specifications and from `libsignal`, with the reason, the cost, and the file that implements it. The [security model](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/SECURITY.md) holds the threat model boundary.
109
+ JavaScript engines do not provide a machine-level constant-time contract or guaranteed zeroization. The [security model](./docs/SECURITY.md) defines the timing, same-process, storage, and metadata boundaries. The [protocol policy](./docs/PROTOCOL_POLICY.md) defines supported modes and fail-closed behavior.
140
110
 
141
- **Dependencies: 6.** The package has six direct production dependencies: `@noble/ciphers`, `@noble/curves`, `@noble/hashes`, `@noble/post-quantum`, `async-lock`, and `unique-names-generator`. They resolve to 6 packages in total. The only transitive edges run between the `@noble` packages, 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.
111
+ Report a suspected vulnerability privately through the process in [SECURITY](./SECURITY.md). Do not open a public issue for it.
142
112
 
143
- **Automated checks.** The published repository is a mechanized export of a private engineering repository, through an allowlist. The automated checks live in that engineering repository, and they must pass before the export runs. The [assurance summary](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/ASSURANCE.md) carries the current run figures and explains what the checks cover, what stays unpublished, and why. Every release regenerates those figures from a real run, and no one hand-edits them. 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.
113
+ ## Why developers choose this SDK
144
114
 
145
- **Constant-time posture, honestly.** JavaScript engines offer no machine-level constant-time contract, and this SDK cannot invent one. Selected paths carry best-effort source-level work:
115
+ The SDK gives TypeScript applications one maintained package for required post-quantum session establishment and ratcheting, multi-device messaging, groups, sealed sender, attachments, and safety numbers. It keeps protocol state on the device and leaves the relay implementation to the application.
146
116
 
147
- - a full scan when it compares equal-length MACs and identity bytes
148
- - fixed work on both decapsulation candidates, then a masked choice between them
149
- - equal-work rejection padding on selected replay and authentication paths
117
+ [Compare maintained alternatives and their limits.](https://open-e2ee.dev/product/#how-it-compares)
150
118
 
151
- These are not timing-equivalence proofs. Secret-influenced remainder and compression arithmetic remains. JIT compilation, allocation, garbage collection, and cache effects stay observable. `secureZeroBytes()` overwrites the exact typed array the caller hands it and nothing more. It does not touch copies, strings, or engine temporaries. The threat model does not cover hostile same-process code or a high-assurance co-resident timing adversary, and it says so.
119
+ ## Documentation
152
120
 
153
- **Reporting a vulnerability.** Email security@open-e2ee.dev rather than opening an issue. Acknowledgment within 72 hours, initial assessment within 7 days. [SECURITY.md](https://github.com/open-e2ee/signal-protocol-js/blob/main/SECURITY.md) carries the full policy.
121
+ - [Getting started](./docs/GETTING_STARTED.md): the integration sequence and mental model.
122
+ - [Package surface](./docs/PACKAGE_SURFACE.md): root exports, subpaths, adapters, and core concepts.
123
+ - [Recipes](./docs/RECIPES.md): messaging, multi-device, attachments, and usernames.
124
+ - [Architecture](./ARCHITECTURE.md) and [adapters](./ADAPTERS.md): layer ownership and composition boundaries.
125
+ - [Integration interfaces](./docs/INTERFACES.md): contracts for custom stores, vaults, relays, and object stores.
126
+ - [Error handling](./docs/ERROR_HANDLING.md) and [troubleshooting](./TROUBLESHOOTING.md).
127
+ - [Deviations](./docs/DEVIATIONS.md): differences from the specifications and libsignal, with reasons and costs.
128
+ - [Hosted API reference](https://docs.open-e2ee.dev/reference/api): exported types and methods.
154
129
 
155
- ## Documentation
130
+ ## Help and contributing
156
131
 
157
- Hosted guides, quickstarts per runtime, and concept docs live at
158
- [docs.open-e2ee.dev](https://docs.open-e2ee.dev). The in-repo references below
159
- carry the same version as the code:
160
-
161
- - [Getting Started](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/GETTING_STARTED.md): installation, mental model, first working client.
162
- - [Package Surface](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/PACKAGE_SURFACE.md): root exports, every subpath, adapter implementations, core concepts.
163
- - [Recipes](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/RECIPES.md): message flow, protocol policy, multi-device, attachments, usernames.
164
- - [Client Composition](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/CLIENT_COMPOSITION.md): production composition with Expo and Convex.
165
- - [Architecture](https://github.com/open-e2ee/signal-protocol-js/blob/main/ARCHITECTURE.md) and [Adapters](https://github.com/open-e2ee/signal-protocol-js/blob/main/ADAPTERS.md): layer model and composition boundaries.
166
- - [Integration Interfaces](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/INTERFACES.md): the interfaces to implement for custom storage, vaults, relays, and object stores.
167
- - [Error Handling](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/ERROR_HANDLING.md) and [Troubleshooting](https://github.com/open-e2ee/signal-protocol-js/blob/main/TROUBLESHOOTING.md).
168
- - [E2EE concepts](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/E2EE.md): what changes about your architecture when the relay cannot read.
169
- - [Deviations](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md): every difference from the Signal Protocol specifications and from `libsignal`, with reasons and costs.
170
- - [API Reference](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/api/README.md): generated from the exported declarations.
132
+ Open a [bug report](https://github.com/open-e2ee/signal-protocol-js/issues/new?template=bug_report.yml) or send [API and documentation feedback](https://github.com/open-e2ee/signal-protocol-js/issues/new?template=api_feedback.yml). Read [CONTRIBUTING](./CONTRIBUTING.md) before you propose code. Use the private process in [SECURITY](./SECURITY.md) for suspected vulnerabilities.
171
133
 
172
134
  ## License and warranty
173
135
 
174
- Licensed under `AGPL-3.0-or-later`. See [LICENSE](https://github.com/open-e2ee/signal-protocol-js/blob/main/LICENSE). A commercial license covers proprietary products that cannot meet AGPLv3 obligations. See [COMMERCIAL](https://github.com/open-e2ee/signal-protocol-js/blob/main/COMMERCIAL.md) or email licensing@open-e2ee.dev.
136
+ Licensed under AGPLv3 (`AGPL-3.0-or-later`). See [LICENSE](./LICENSE). A [commercial license](./COMMERCIAL.md) covers proprietary products that cannot meet AGPLv3 obligations.
175
137
 
176
- The license provides the software **as is**, without warranties or conditions of any kind. To the extent that applicable law permits, copyright holders and contributors are not liable for damages that arise from its use. Your application must evaluate this SDK against its own requirements. It must also secure its own deployment, storage, authentication, authorization, and operations. This summary does not modify the license. Sections 15 and 16 of the GNU Affero General Public License carry the complete "Disclaimer of Warranty" and "Limitation of Liability" text.
138
+ The license provides the software **as is**, without warranties or conditions of any kind. To the extent that applicable law permits, copyright holders and contributors are not liable for damages that arise from its use. Your application must evaluate the SDK against its requirements and secure its deployment, storage, authentication, authorization, and operations. This summary does not modify the license.
package/SECURITY.md CHANGED
@@ -7,8 +7,8 @@ backports.
7
7
 
8
8
  | Version | Supported |
9
9
  | ------- | ------------------ |
10
- | 0.3.x | :white_check_mark: |
11
- | < 0.3.0 | :x: |
10
+ | 0.4.x | :white_check_mark: |
11
+ | < 0.4.0 | :x: |
12
12
 
13
13
  ## Reporting a Vulnerability
14
14
 
@@ -49,6 +49,7 @@ Error occurred?
49
49
 
50
50
  **"Identity key not found - client not initialized"**
51
51
 
52
+ <!-- doc-snippet:illustrative elided-call-arguments -->
52
53
  ```typescript
53
54
  // ❌ Wrong: forgot to initialize
54
55
  const signal = new SignalProtocolClient(); // Don't use constructor directly!
@@ -65,6 +66,7 @@ await signal.encryptMessage(...); // Works!
65
66
 
66
67
  Make sure the prekey bundle is fresh and valid:
67
68
 
69
+ <!-- doc-snippet:skip requires-external-context -->
68
70
  ```typescript
69
71
  // Fetch the latest prekey bundle from server
70
72
  const bundle = await convex.mutation(api.signal.keys.fetchPreKeyBundle, {
@@ -87,6 +89,7 @@ await signal.establishSession(sessionId, bobId, bundle);
87
89
 
88
90
  Session IDs must be in `userId:deviceId` format:
89
91
 
92
+ <!-- doc-snippet:skip requires-external-context -->
90
93
  ```typescript
91
94
  // ❌ Wrong: missing device ID
92
95
  await signal.encryptMessage('bob', 'Hello');
@@ -122,6 +125,7 @@ The protocol handles out-of-order messages automatically via MKSKIPPED. For fail
122
125
 
123
126
  ### Check Client State
124
127
 
128
+ <!-- doc-snippet:skip requires-external-context -->
125
129
  ```typescript
126
130
  // Get encryption statistics
127
131
  const stats = await signal.getStats();
@@ -132,6 +136,7 @@ console.log('OneTime prekeys remaining:', stats.oneTimePreKeysCount);
132
136
 
133
137
  ### Check Session Status
134
138
 
139
+ <!-- doc-snippet:skip requires-external-context -->
135
140
  ```typescript
136
141
  // Check if session exists
137
142
  const hasSession = await signal.hasSession('bob:1');
@@ -140,6 +145,7 @@ console.log('Has session with bob:1:', hasSession);
140
145
 
141
146
  ### Enable Debug Logging
142
147
 
148
+ <!-- doc-snippet:skip requires-external-context -->
143
149
  ```typescript
144
150
  const signal = await SignalProtocolClient.create(userId, {
145
151
  enableDebugLogging: true,
@@ -149,6 +155,7 @@ const signal = await SignalProtocolClient.create(userId, {
149
155
 
150
156
  ### Verify Identity Keys
151
157
 
158
+ <!-- doc-snippet:skip requires-external-context -->
152
159
  ```typescript
153
160
  // Generate the composite safety number from the locally pinned identity.
154
161
  const safetyNumber = await signal.verify(theirUserId);
@@ -11,6 +11,7 @@ second, conflicting source of truth. `SignalProtocolBlockingManager` centralizes
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import {
16
17
  SignalProtocolBlockingManager,
package/client/README.md CHANGED
@@ -15,6 +15,7 @@ Every client needs `storage`. Local use can omit `relay`, and real messaging
15
15
  needs it. `protocol.postQuantum` and `protocol.braid` both default to
16
16
  `'required'`.
17
17
 
18
+ <!-- doc-snippet:skip requires-established-session -->
18
19
  ```ts
19
20
  import { createSignalProtocolClient, ProtocolAddress } from '@open-e2ee/signal-protocol-sdk';
20
21
  import { inMemoryStore } from '@open-e2ee/signal-protocol-sdk/local/store/memory';
@@ -32,6 +33,7 @@ await signal.encryptMessage(bob, 'hello');
32
33
 
33
34
  ### With relay
34
35
 
36
+ <!-- doc-snippet:skip requires-external-context -->
35
37
  ```ts
36
38
  import { createSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
37
39
  import { convexRelay, type ConvexSignalProtocolRelayApi } from '@open-e2ee/signal-protocol-sdk/remote/relay/convex';
@@ -65,6 +67,7 @@ database-binding and SQLCipher bootstrap.
65
67
 
66
68
  Use product/security terms at the client seam:
67
69
 
70
+ <!-- doc-snippet:skip requires-external-context -->
68
71
  ```ts
69
72
  await createSignalProtocolClient({
70
73
  identity: { userId },
@@ -77,6 +80,7 @@ await createSignalProtocolClient({
77
80
  `compatible` only for an explicit product decision to support peers that
78
81
  publish no post-quantum material:
79
82
 
83
+ <!-- doc-snippet:skip requires-external-context -->
80
84
  ```ts
81
85
  await createSignalProtocolClient({
82
86
  identity: { userId },
@@ -87,6 +91,7 @@ await createSignalProtocolClient({
87
91
 
88
92
  Use direct SPQR only as an explicit product-reviewed escape hatch:
89
93
 
94
+ <!-- doc-snippet:skip requires-external-context -->
90
95
  ```ts
91
96
  await createSignalProtocolClient({
92
97
  identity: { userId },
@@ -99,6 +104,7 @@ await createSignalProtocolClient({
99
104
 
100
105
  Use typed device addresses instead of string session ids:
101
106
 
107
+ <!-- doc-snippet:skip requires-external-context -->
102
108
  ```ts
103
109
  import { ProtocolAddress } from '@open-e2ee/signal-protocol-sdk';
104
110
 
@@ -111,6 +117,7 @@ const asString = ProtocolAddress.toString(bob);
111
117
 
112
118
  ### Direct session control
113
119
 
120
+ <!-- doc-snippet:skip requires-external-context -->
114
121
  ```ts
115
122
  const bob = ProtocolAddress.create('bob', 1);
116
123
 
@@ -122,6 +129,7 @@ const plaintext = await signal.decryptMessage(bob, ciphertext);
122
129
 
123
130
  ### Multi-device send
124
131
 
132
+ <!-- doc-snippet:skip requires-external-context -->
125
133
  ```ts
126
134
  const result = await signal.send(recipientUserId, 'hello');
127
135
 
@@ -136,6 +144,7 @@ await appMessages.insertOutgoing({
136
144
 
137
145
  ### Server sync
138
146
 
147
+ <!-- doc-snippet:skip requires-external-context -->
139
148
  ```ts
140
149
  // Publish fresh public prekeys and rotate long-lived prekeys on schedule.
141
150
  await signal.syncToServer();
@@ -148,6 +157,7 @@ await signal.rotateKyberPreKey();
148
157
  Use the dedicated headless entry point from a background task after restoring
149
158
  the same application-owned storage and relay boundaries:
150
159
 
160
+ <!-- doc-snippet:skip requires-external-context -->
151
161
  ```ts
152
162
  import { rotateKeysHeadless } from '@open-e2ee/signal-protocol-sdk/client/headless';
153
163
 
package/device/README.md CHANGED
@@ -26,6 +26,7 @@ The top-level device module currently uses Expo and React Native platform APIs.
26
26
  Install the optional peer dependencies required by the exports you use. The
27
27
  framework-neutral lifecycle core is available from:
28
28
 
29
+ <!-- doc-snippet:skip requires-external-context -->
29
30
  ```ts
30
31
  import {
31
32
  DeviceLifecycleManager,
@@ -40,6 +41,7 @@ placing initialization in its own startup lifecycle.
40
41
 
41
42
  ## Device ID access
42
43
 
44
+ <!-- doc-snippet:skip requires-external-context -->
43
45
  ```ts
44
46
  import {
45
47
  getDeviceId,
@@ -57,6 +59,7 @@ it only after preload or in code that can safely tolerate that fallback.
57
59
 
58
60
  The primary device creates a short-lived provisioning session:
59
61
 
62
+ <!-- doc-snippet:skip requires-external-context -->
60
63
  ```ts
61
64
  import {
62
65
  generateProvisioningQR,
@@ -88,6 +91,7 @@ await provisionDevice(
88
91
  The new device parses the QR data, joins the session, and stores the encrypted
89
92
  provisioning result:
90
93
 
94
+ <!-- doc-snippet:skip requires-external-context -->
91
95
  ```ts
92
96
  import {
93
97
  connectToProvisioningSession,
@@ -132,6 +136,7 @@ group/username state only when the host application enables and supplies them.
132
136
 
133
137
  ## Transfer cryptographic state
134
138
 
139
+ <!-- doc-snippet:skip requires-external-context -->
135
140
  ```ts
136
141
  import {
137
142
  prepareNewDeviceTransfer,
@@ -1 +1 @@
1
- {"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../client/groups.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../client/groups.ts"],"names":[],"mappings":"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"}
@@ -244,7 +244,7 @@ export async function getGroupSenderKeyStats(ctx, groupId, senderId, senderDevic
244
244
  * All group functions follow the same pattern: call manager, log success, throw
245
245
  * EncryptionError on failure. This helper eliminates that boilerplate.
246
246
  */
247
- async function wrapGroupOp(label, logger, op, logData, errorCode = EncryptionErrorCode.INVALID_STATE) {
247
+ async function runGroupOp(label, logger, op, logData, wrapError) {
248
248
  try {
249
249
  const result = await op();
250
250
  logger.debug(label, { category: 'E2EE', data: logData });
@@ -255,9 +255,19 @@ async function wrapGroupOp(label, logger, op, logData, errorCode = EncryptionErr
255
255
  error.name === 'GroupSecurityReactionPendingError') {
256
256
  throw error;
257
257
  }
258
- throw new EncryptionError(label, errorCode, { originalError: error });
258
+ throw wrapError(error);
259
259
  }
260
260
  }
261
+ async function wrapGroupOp(label, logger, op, logData) {
262
+ return runGroupOp(label, logger, op, logData, (error) => new EncryptionError(label, EncryptionErrorCode.INVALID_STATE, {
263
+ originalError: error,
264
+ }));
265
+ }
266
+ async function wrapGroupInitializationOp(label, logger, op, logData) {
267
+ return runGroupOp(label, logger, op, logData, (error) => new EncryptionError(label, EncryptionErrorCode.INITIALIZATION_FAILED, {
268
+ originalError: error,
269
+ }));
270
+ }
261
271
  /**
262
272
  * Create a new group
263
273
  *
@@ -265,7 +275,7 @@ async function wrapGroupOp(label, logger, op, logData, errorCode = EncryptionErr
265
275
  * to the server. The creator is added as an administrator.
266
276
  */
267
277
  export async function createGroup(ctx, manager, creatorAci, creatorProfileKey, members, title, options) {
268
- return wrapGroupOp(`Created group "${title}"`, ctx.logger, () => manager.createGroup(creatorAci, creatorProfileKey, members, title, options), { memberCount: members.length + 1, title }, EncryptionErrorCode.INITIALIZATION_FAILED);
278
+ return wrapGroupInitializationOp(`Created group "${title}"`, ctx.logger, () => manager.createGroup(creatorAci, creatorProfileKey, members, title, options), { memberCount: members.length + 1, title });
269
279
  }
270
280
  /**
271
281
  * Get the decrypted state for a group
@@ -352,6 +362,6 @@ export async function createGroupInviteLink(ctx, manager, groupId, editorAci) {
352
362
  * (if admin approval is required).
353
363
  */
354
364
  export async function joinGroupViaInviteLink(ctx, manager, url, userAci, userProfileKey) {
355
- return wrapGroupOp(`Joined group via invite link`, ctx.logger, () => manager.joinViaInviteLink(url, userAci, userProfileKey), {}, EncryptionErrorCode.INITIALIZATION_FAILED);
365
+ return wrapGroupInitializationOp(`Joined group via invite link`, ctx.logger, () => manager.joinViaInviteLink(url, userAci, userProfileKey), {});
356
366
  }
357
367
  //# sourceMappingURL=groups.js.map