@open-e2ee/signal-protocol-sdk 0.3.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ADAPTERS.md +7 -0
- package/ARCHITECTURE.md +2 -0
- package/CHANGELOG.md +96 -5
- package/README.md +67 -102
- package/SECURITY.md +2 -2
- package/THIRD_PARTY_NOTICES.md +1 -1
- package/TROUBLESHOOTING.md +7 -0
- package/blocking/README.md +1 -0
- package/client/README.md +10 -0
- package/device/README.md +12 -5
- package/dist/client/client.d.ts +3 -2
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +58 -25
- package/dist/client/client.js.map +1 -1
- package/dist/client/config.d.ts +46 -7
- package/dist/client/config.d.ts.map +1 -1
- package/dist/client/config.js +2 -2
- package/dist/client/config.js.map +1 -1
- package/dist/client/group-outbox.d.ts +38 -0
- package/dist/client/group-outbox.d.ts.map +1 -0
- package/dist/client/group-outbox.js +221 -0
- package/dist/client/group-outbox.js.map +1 -0
- package/dist/client/group-sealed-sender.d.ts +28 -0
- package/dist/client/group-sealed-sender.d.ts.map +1 -0
- package/dist/client/group-sealed-sender.js +74 -0
- package/dist/client/group-sealed-sender.js.map +1 -0
- package/dist/client/groups.d.ts.map +1 -1
- package/dist/client/groups.js +14 -4
- package/dist/client/groups.js.map +1 -1
- package/dist/client/hosted-push.d.ts +77 -0
- package/dist/client/hosted-push.d.ts.map +1 -0
- package/dist/client/hosted-push.js +90 -0
- package/dist/client/hosted-push.js.map +1 -0
- package/dist/client/hosted.d.ts +207 -0
- package/dist/client/hosted.d.ts.map +1 -0
- package/dist/client/hosted.js +505 -0
- package/dist/client/hosted.js.map +1 -0
- package/dist/client/index.d.ts +4 -2
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +2 -0
- package/dist/client/index.js.map +1 -1
- package/dist/client/relay-subscription.d.ts.map +1 -1
- package/dist/client/relay-subscription.js +34 -7
- package/dist/client/relay-subscription.js.map +1 -1
- package/dist/client/{sealed-sender-ops.d.ts → sealed-sender.d.ts} +39 -22
- package/dist/client/sealed-sender.d.ts.map +1 -0
- package/dist/client/sealed-sender.js +296 -0
- package/dist/client/sealed-sender.js.map +1 -0
- package/dist/client/signal-service-cipher.d.ts +23 -26
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +465 -706
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/client/types.d.ts +18 -3
- package/dist/client/types.d.ts.map +1 -1
- package/dist/client/types.js +6 -0
- package/dist/client/types.js.map +1 -1
- package/dist/device/index.d.ts +2 -2
- package/dist/device/index.d.ts.map +1 -1
- package/dist/device/index.js +1 -1
- package/dist/device/index.js.map +1 -1
- package/dist/device/transfer.d.ts +7 -43
- package/dist/device/transfer.d.ts.map +1 -1
- package/dist/device/transfer.js +31 -150
- package/dist/device/transfer.js.map +1 -1
- package/dist/device/types.d.ts +6 -47
- package/dist/device/types.d.ts.map +1 -1
- package/dist/device/types.js +1 -1
- package/dist/device/types.js.map +1 -1
- package/dist/index.d.ts +5 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -5
- package/dist/index.js.map +1 -1
- package/dist/internal/encoding/proto/pq-ratchet-serialize.js +1 -1
- package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
- package/dist/internal/encoding/proto/primitives.js +1 -1
- package/dist/internal/encoding/proto/primitives.js.map +1 -1
- package/dist/internal/groups/manager.d.ts +3 -3
- package/dist/internal/groups/manager.d.ts.map +1 -1
- package/dist/internal/groups/manager.js +5 -4
- package/dist/internal/groups/manager.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/certificate.d.ts +10 -4
- package/dist/internal/protocol/sealed-sender/certificate.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/certificate.js +64 -7
- package/dist/internal/protocol/sealed-sender/certificate.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/decryption.d.ts +34 -47
- package/dist/internal/protocol/sealed-sender/decryption.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/decryption.js +95 -182
- package/dist/internal/protocol/sealed-sender/decryption.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/encryption.d.ts +49 -64
- package/dist/internal/protocol/sealed-sender/encryption.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/encryption.js +120 -123
- package/dist/internal/protocol/sealed-sender/encryption.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/index.d.ts +5 -7
- package/dist/internal/protocol/sealed-sender/index.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/index.js +4 -12
- package/dist/internal/protocol/sealed-sender/index.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/{v2-helpers.d.ts → multi-recipient-crypto.d.ts} +1 -1
- package/dist/internal/protocol/sealed-sender/multi-recipient-crypto.d.ts.map +1 -0
- package/dist/internal/protocol/sealed-sender/{v2-helpers.js → multi-recipient-crypto.js} +1 -1
- package/dist/internal/protocol/sealed-sender/multi-recipient-crypto.js.map +1 -0
- package/dist/internal/protocol/sealed-sender/{v2-binary.d.ts → multi-recipient-message.d.ts} +3 -2
- package/dist/internal/protocol/sealed-sender/multi-recipient-message.d.ts.map +1 -0
- package/dist/internal/protocol/sealed-sender/{v2-binary.js → multi-recipient-message.js} +16 -8
- package/dist/internal/protocol/sealed-sender/multi-recipient-message.js.map +1 -0
- package/dist/internal/protocol/sealed-sender/proto/index.d.ts +3 -0
- package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/proto/index.js +25 -2
- package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/trust-root.d.ts +11 -1
- package/dist/internal/protocol/sealed-sender/trust-root.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/trust-root.js +13 -1
- package/dist/internal/protocol/sealed-sender/trust-root.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/types.d.ts +20 -135
- package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/types.js +15 -6
- package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
- package/dist/internal/protocol/sender-keys/manager.d.ts +22 -1
- package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
- package/dist/internal/protocol/sender-keys/manager.js +39 -4
- package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
- package/dist/internal/protocol/spqr/braid-serialize.js +1 -1
- package/dist/internal/protocol/spqr/braid-serialize.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js +4 -4
- package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js.map +1 -1
- package/dist/internal/protocol/zk/groups/index.d.ts +1 -1
- package/dist/internal/protocol/zk/groups/index.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/index.js +1 -1
- package/dist/internal/protocol/zk/groups/index.js.map +1 -1
- package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts +37 -12
- package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/profile-key-credential.js +104 -31
- package/dist/internal/protocol/zk/groups/profile-key-credential.js.map +1 -1
- package/dist/internal/sesame/types.d.ts +0 -2
- package/dist/internal/sesame/types.d.ts.map +1 -1
- package/dist/internal/sesame/types.js +0 -2
- package/dist/internal/sesame/types.js.map +1 -1
- package/dist/local/store/expo/adapter.d.ts +1 -0
- package/dist/local/store/expo/adapter.d.ts.map +1 -1
- package/dist/local/store/expo/adapter.js +3 -0
- package/dist/local/store/expo/adapter.js.map +1 -1
- package/dist/local/store/expo/key-storage.d.ts +1 -0
- package/dist/local/store/expo/key-storage.d.ts.map +1 -1
- package/dist/local/store/expo/key-storage.js +4 -0
- package/dist/local/store/expo/key-storage.js.map +1 -1
- package/dist/local/store/memory/adapter.d.ts +1 -0
- package/dist/local/store/memory/adapter.d.ts.map +1 -1
- package/dist/local/store/memory/adapter.js +4 -0
- package/dist/local/store/memory/adapter.js.map +1 -1
- package/dist/local/store/node/adapter.d.ts +1 -0
- package/dist/local/store/node/adapter.d.ts.map +1 -1
- package/dist/local/store/node/adapter.js +3 -0
- package/dist/local/store/node/adapter.js.map +1 -1
- package/dist/local/store/node/database.d.ts +1 -0
- package/dist/local/store/node/database.d.ts.map +1 -1
- package/dist/local/store/node/database.js +5 -0
- package/dist/local/store/node/database.js.map +1 -1
- package/dist/local/store/react-native/adapter.d.ts +1 -0
- package/dist/local/store/react-native/adapter.d.ts.map +1 -1
- package/dist/local/store/react-native/adapter.js +4 -0
- package/dist/local/store/react-native/adapter.js.map +1 -1
- package/dist/local/store/react-native/reference-backend.js +1 -1
- package/dist/local/store/react-native/reference-backend.js.map +1 -1
- package/dist/local/store/reliability.d.ts +63 -0
- package/dist/local/store/reliability.d.ts.map +1 -0
- package/dist/local/store/reliability.js +219 -0
- package/dist/local/store/reliability.js.map +1 -0
- package/dist/local/store/web/adapter.d.ts +1 -0
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +5 -0
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/media/index.d.ts +0 -1
- package/dist/media/index.d.ts.map +1 -1
- package/dist/media/index.js +0 -1
- package/dist/media/index.js.map +1 -1
- package/dist/remote/relay/convex/backend.d.ts +6 -16
- package/dist/remote/relay/convex/backend.d.ts.map +1 -1
- package/dist/remote/relay/convex/backend.js +12 -21
- package/dist/remote/relay/convex/backend.js.map +1 -1
- package/dist/remote/relay/convex/component/_generated/component.d.ts +9 -16
- package/dist/remote/relay/convex/component/_generated/component.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/certificates.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/certificates.js +14 -5
- package/dist/remote/relay/convex/component/certificates.js.map +1 -1
- package/dist/remote/relay/convex/component/messages.d.ts +2 -15
- package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/messages.js +14 -48
- package/dist/remote/relay/convex/component/messages.js.map +1 -1
- package/dist/remote/relay/convex/component/schema.d.ts +5 -3
- package/dist/remote/relay/convex/component/schema.js +2 -1
- package/dist/remote/relay/convex/component/schema.js.map +1 -1
- package/dist/remote/relay/convex/component/zkAuth.d.ts +7 -1
- package/dist/remote/relay/convex/component/zkAuth.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/zkAuth.js +29 -14
- package/dist/remote/relay/convex/component/zkAuth.js.map +1 -1
- package/dist/remote/relay/convex/relay.d.ts +2 -5
- package/dist/remote/relay/convex/relay.d.ts.map +1 -1
- package/dist/remote/relay/convex/relay.js +17 -47
- package/dist/remote/relay/convex/relay.js.map +1 -1
- package/dist/remote/relay/memory/adapter.d.ts +4 -10
- package/dist/remote/relay/memory/adapter.d.ts.map +1 -1
- package/dist/remote/relay/memory/adapter.js +31 -34
- package/dist/remote/relay/memory/adapter.js.map +1 -1
- package/dist/remote/relay/types.d.ts +6 -19
- package/dist/remote/relay/types.d.ts.map +1 -1
- package/dist/types/api.d.ts +2 -0
- package/dist/types/api.d.ts.map +1 -1
- package/dist/types/errors.d.ts +3 -1
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/errors.js +4 -2
- package/dist/types/errors.js.map +1 -1
- package/dist/types/protocol-config.d.ts +1 -1
- package/dist/username/link.d.ts.map +1 -1
- package/dist/username/link.js +1 -1
- package/dist/username/link.js.map +1 -1
- package/dist/utils/retry.d.ts +2 -1
- package/dist/utils/retry.d.ts.map +1 -1
- package/dist/utils/retry.js +2 -1
- package/dist/utils/retry.js.map +1 -1
- package/docs/ASSURANCE.md +16 -10
- package/docs/CLIENT_COMPOSITION.md +3 -0
- package/docs/DEVIATIONS.md +32 -61
- package/docs/DOCUMENTATION_STANDARDS.md +28 -0
- package/docs/ERROR_HANDLING.md +91 -60
- package/docs/GETTING_STARTED.md +27 -1
- package/docs/INTERFACES.md +5 -0
- package/docs/PACKAGE_SURFACE.md +1 -0
- package/docs/PROTOCOL_POLICY.md +6 -0
- package/docs/RECIPES.md +9 -0
- package/docs/SECURITY.md +6 -0
- package/encoding/README.md +1 -0
- package/files/README.md +1 -0
- package/groups/README.md +1 -0
- package/keys/README.md +2 -0
- package/local/store/README.md +2 -0
- package/local/store/expo/README.md +2 -0
- package/local/store/memory/README.md +2 -0
- package/local/store/node/README.md +1 -0
- package/local/store/react-native/README.md +2 -0
- package/local/store/web/README.md +1 -0
- package/local/vault/README.md +1 -0
- package/media/README.md +2 -0
- package/package.json +4 -2
- package/profile/README.md +1 -0
- package/remote/README.md +6 -0
- package/remote/object-store/README.md +1 -0
- package/remote/object-store/convex-r2/README.md +2 -0
- package/remote/object-store/s3/README.md +1 -0
- package/remote/relay/README.md +2 -0
- package/remote/relay/convex/README.md +1 -0
- package/remote/relay/convex/component/README.md +29 -14
- package/remote/relay/memory/README.md +2 -0
- package/safety/README.md +1 -0
- package/scripts/oe-groups.mjs +5 -1
- package/sealed-sender/README.md +1 -0
- package/types/README.md +1 -0
- package/username/README.md +1 -0
- package/utils/README.md +1 -0
- package/zk/README.md +1 -0
- package/dist/client/sealed-sender-ops.d.ts.map +0 -1
- package/dist/client/sealed-sender-ops.js +0 -203
- package/dist/client/sealed-sender-ops.js.map +0 -1
- package/dist/internal/protocol/sealed-sender/decryption-v2.d.ts +0 -46
- package/dist/internal/protocol/sealed-sender/decryption-v2.d.ts.map +0 -1
- package/dist/internal/protocol/sealed-sender/decryption-v2.js +0 -198
- package/dist/internal/protocol/sealed-sender/decryption-v2.js.map +0 -1
- package/dist/internal/protocol/sealed-sender/encryption-v2.d.ts +0 -56
- package/dist/internal/protocol/sealed-sender/encryption-v2.d.ts.map +0 -1
- package/dist/internal/protocol/sealed-sender/encryption-v2.js +0 -163
- package/dist/internal/protocol/sealed-sender/encryption-v2.js.map +0 -1
- package/dist/internal/protocol/sealed-sender/v2-binary.d.ts.map +0 -1
- package/dist/internal/protocol/sealed-sender/v2-binary.js.map +0 -1
- package/dist/internal/protocol/sealed-sender/v2-helpers.d.ts.map +0 -1
- package/dist/internal/protocol/sealed-sender/v2-helpers.js.map +0 -1
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,96 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.0.0
|
|
4
|
+
|
|
5
|
+
- **Hosted Relay supports data-only push wake hints across Expo, APNs, FCM,
|
|
6
|
+
and Web Push.** The SDK registers one destination for the authenticated
|
|
7
|
+
device and derives no account, device, scope, or generation identifiers from
|
|
8
|
+
application input. A wake starts an authenticated durable-mailbox pull.
|
|
9
|
+
The SDK acknowledges only envelopes that it processes successfully, and the
|
|
10
|
+
same pull remains available when push delivery is unavailable.
|
|
11
|
+
|
|
12
|
+
- **Hosted Relay now supports provider migration, recovery progress, and
|
|
13
|
+
managed device linking.** Migration assertions use the existing purpose-aware
|
|
14
|
+
identity callback with typed source and target roles. Recovery reports typed
|
|
15
|
+
phases while Relay remains the account authority. Managed linking requires a
|
|
16
|
+
provisioned account identity. It also requires distinct active and new
|
|
17
|
+
device-auth keys. It sends no ratchet, sender-key, skipped-key, or outbox
|
|
18
|
+
state.
|
|
19
|
+
|
|
20
|
+
- **Breaking: sends use a durable exact-ciphertext outbox and always return a
|
|
21
|
+
logical-send identifier.** `SendResult.clientMessageId` is required. The SDK
|
|
22
|
+
generates it when `SendOptions.clientMessageId` is absent, exposes it on send
|
|
23
|
+
errors through `isOutgoingMessageError`, and replays the persisted encrypted
|
|
24
|
+
transmission after an unknown Relay result. Receivers retain processed Relay
|
|
25
|
+
envelope identifiers for 30 days and acknowledge duplicates without running
|
|
26
|
+
protocol decryption again. Automatic sender-key rotation also persists its
|
|
27
|
+
pairwise distribution messages before group transport. Custom
|
|
28
|
+
`ISignalProtocolLocalStore` implementations must now implement
|
|
29
|
+
`deleteMetadata` for bounded outbox and deduplication retention.
|
|
30
|
+
|
|
31
|
+
- **Breaking: linked-device backup format 2 transfers account identity only.**
|
|
32
|
+
A linked device generates fresh prekeys and establishes independent sessions.
|
|
33
|
+
The SDK rejects old or extended backup shapes that carry prekeys, ratchet
|
|
34
|
+
sessions, sender-key state, message state, or outbox state.
|
|
35
|
+
|
|
36
|
+
- **Profile-key credential issuance is blinded.** The authenticated issuer
|
|
37
|
+
receives an ACI-bound blinded request, not the raw profile key. The client
|
|
38
|
+
unblinds and verifies the response before it creates a group presentation.
|
|
39
|
+
|
|
40
|
+
- **Breaking: sealed-sender delivery now uses one multi-recipient wire format
|
|
41
|
+
for direct and group sends.** The direct path supports one recipient through
|
|
42
|
+
the same format, and the SDK rejects the retired V1 wire format. Hosted Relay
|
|
43
|
+
adapters no longer implement the V1 send method. `preferred` delivery falls
|
|
44
|
+
back to identified delivery only after an anonymous authorization rejection;
|
|
45
|
+
other anonymous-delivery failures do not change the privacy route.
|
|
46
|
+
|
|
47
|
+
## 0.4.0
|
|
48
|
+
|
|
49
|
+
- **Breaking: sender certificates now bind to Relay scope and issuer
|
|
50
|
+
validity.** The signed sender certificate requires an opaque 16-byte scope.
|
|
51
|
+
The signed server certificate requires its validity interval. Recipients
|
|
52
|
+
reject the old certificate shape. The new hosted bootstrap accepts a
|
|
53
|
+
publishable key and identity assertion callback. It then uses the account,
|
|
54
|
+
device, and scope bindings that Relay returns. Identified delivery does not
|
|
55
|
+
require a sender certificate.
|
|
56
|
+
|
|
57
|
+
- **Hosted Relay bootstrap now registers a complete EC and ML-KEM prekey
|
|
58
|
+
inventory.** The SDK creates and stores signed, last-resort, and one-time
|
|
59
|
+
prekeys before bootstrap. It sends only public material. Exact retries reuse
|
|
60
|
+
the original operation and public registration snapshot, so a restarted
|
|
61
|
+
client cannot publish an old one-time prekey as a new registration.
|
|
62
|
+
|
|
63
|
+
- **The README now provides a runnable encrypted round trip and a current demo.**
|
|
64
|
+
The quickstart exercises two SDK clients through the in-memory relay. The new
|
|
65
|
+
recording shows the same two-device and relay flow as the live desktop and
|
|
66
|
+
mobile demo.
|
|
67
|
+
|
|
68
|
+
- **Error-surface checks reject unresolved codes and cover media attachment
|
|
69
|
+
codes.** The analyser now reports forwarded code arguments in CI.
|
|
70
|
+
It also checks every `MediaAttachmentErrorCode` value.
|
|
71
|
+
This release removes `RemoteObjectStoreNotConfigured` because no media
|
|
72
|
+
operation could produce it.
|
|
73
|
+
|
|
74
|
+
- **The retry-request wire surface no longer includes
|
|
75
|
+
`RetryReason.INVALID_MESSAGE`.** No local failure produced it. The incoming
|
|
76
|
+
retry handler did not support it. Malformed ciphertext failures use the supported
|
|
77
|
+
`DECRYPTION_FAILED` recovery path.
|
|
78
|
+
|
|
79
|
+
- **Generated API pages and shipped documentation examples now have source
|
|
80
|
+
gates.** CI regenerates `docs/api` with pinned tool versions. It rejects a
|
|
81
|
+
diff. The snippet runner scans every packaged Markdown file and the internal
|
|
82
|
+
lifecycle docs. It executes every complete example and matches its output.
|
|
83
|
+
For an example that cannot run, it compiles every SDK name against the packed
|
|
84
|
+
package. A renamed or deleted export therefore fails the build in every
|
|
85
|
+
document that names it.
|
|
86
|
+
|
|
87
|
+
An example that previews an unreleased API declares the import paths that do
|
|
88
|
+
not exist yet. The build fails if one of them resolves. Only pseudocode is
|
|
89
|
+
exempt, and the build names each exempt block on its own line.
|
|
90
|
+
|
|
91
|
+
- **The error guide now documents all 33 `EncryptionErrorCode` values.** Its
|
|
92
|
+
session examples also use the current `ProtocolAddress` method signatures.
|
|
93
|
+
|
|
3
94
|
## 0.3.0
|
|
4
95
|
|
|
5
96
|
- **Breaking: seven error classes and sixteen `EncryptionErrorCode` members are
|
|
@@ -109,7 +200,7 @@
|
|
|
109
200
|
whether the operation produced the epoch secret. Braid mode spreads one
|
|
110
201
|
ML-KEM key agreement across many messages, and until now the chunk counts
|
|
111
202
|
lived entirely inside the state machine, so a host had no way to show or log
|
|
112
|
-
how far a ratchet had
|
|
203
|
+
how far a ratchet had traveled. A direct-mode session never raises the
|
|
113
204
|
callback. The hook is guarded exactly as `onProtocolSelected` is: a consumer
|
|
114
205
|
that throws is logged and the protocol path continues.
|
|
115
206
|
|
|
@@ -176,7 +267,7 @@
|
|
|
176
267
|
install one. An epoch advance for receiving alone installs a zeroed send
|
|
177
268
|
chain key. Pruning writes one over each retired send chain. Deriving from
|
|
178
269
|
either would key a message from a known constant. No production path reached
|
|
179
|
-
that state, so the check is
|
|
270
|
+
that state, so the check is defense in depth.
|
|
180
271
|
|
|
181
272
|
- **The unused SPQR binary header codec is gone.** `serializeSPQRHeaderBinary`
|
|
182
273
|
and `deserializeSPQRHeaderBinary` emitted an unversioned framing. No
|
|
@@ -947,7 +1038,7 @@
|
|
|
947
1038
|
matching the `Type` enum of the reference implementation's
|
|
948
1039
|
`UnidentifiedSenderMessage.Message` (`PREKEY_MESSAGE`, `MESSAGE`,
|
|
949
1040
|
`SENDERKEY_MESSAGE`, `PLAINTEXT_CONTENT`), and `SealOptions.groupId` —
|
|
950
|
-
encrypted, never populated by the send path — is removed in
|
|
1041
|
+
encrypted, never populated by the send path — is removed in favor of
|
|
951
1042
|
`contentType`. This is a wire-format change to sealed sender for both V1 and
|
|
952
1043
|
V2.
|
|
953
1044
|
|
|
@@ -1028,7 +1119,7 @@
|
|
|
1028
1119
|
|
|
1029
1120
|
- **Sealed sender envelope parsing is now canonical and validated.** Both the
|
|
1030
1121
|
V1 and V2 inner-envelope parsers accepted a payload with trailing bytes, an
|
|
1031
|
-
|
|
1122
|
+
unrecognized content-type byte, a truncated varint, or a missing content
|
|
1032
1123
|
hint. Parsing runs after authentication, so none of these was reachable by an
|
|
1033
1124
|
attacker, but two distinct byte strings could parse to identical content and
|
|
1034
1125
|
an unknown content type fell through to a routing default. The parsers now
|
|
@@ -1202,7 +1293,7 @@
|
|
|
1202
1293
|
|
|
1203
1294
|
- **Sealed sender can now be enabled.** `oe-groups trust-root` exports the
|
|
1204
1295
|
Ed25519 sender-certificate root alongside the group trust root, printing both
|
|
1205
|
-
|
|
1296
|
+
labeled (`group trust root:` / `sealed sender trust root:`). Previously only
|
|
1206
1297
|
the group root was printed, so there was no supported way to obtain the value
|
|
1207
1298
|
clients pin in `sealedSender.trustRoots`; inbound sealed-sender validation
|
|
1208
1299
|
stayed disabled and every send fell back to identified delivery, disclosing
|
package/README.md
CHANGED
|
@@ -1,64 +1,53 @@
|
|
|
1
|
-
<img src="https://raw.githubusercontent.com/open-e2ee/design/v0.
|
|
1
|
+
<img src="https://raw.githubusercontent.com/open-e2ee/design/v0.9.1/brand/generated/open-e2ee-mark-adaptive.svg" alt="OpenE2EE" width="72" height="72">
|
|
2
2
|
|
|
3
3
|
# OpenE2EE Signal Protocol SDK
|
|
4
4
|
|
|
5
5
|
**End-to-end encrypted messaging for TypeScript apps. Signal Protocol, post-quantum by default, runs in Expo.**
|
|
6
6
|
|
|
7
7
|
[](https://github.com/open-e2ee/signal-protocol-js/blob/main/LICENSE)
|
|
8
|
-
[](https://www.typescriptlang.org/)
|
|
9
8
|
[](https://www.npmjs.com/package/@open-e2ee/signal-protocol-sdk)
|
|
10
|
-
[](./ARCHITECTURE.md)
|
|
11
10
|
[](https://www.npmjs.com/package/@open-e2ee/signal-protocol-sdk#provenance)
|
|
12
11
|
[](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml)
|
|
13
|
-
[](https://scorecard.dev/viewer/?uri=github.com/open-e2ee/signal-protocol-js)
|
|
14
|
-
[](https://www.bestpractices.dev/projects/14043)
|
|
15
12
|
|
|
16
13
|
[Website](https://open-e2ee.dev) ·
|
|
17
|
-
[
|
|
18
|
-
[
|
|
19
|
-
[
|
|
20
|
-
[
|
|
21
|
-
[
|
|
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
|
+
[OpenE2EE Relay](https://open-e2ee.dev/relay) ·
|
|
17
|
+
[API reference](https://docs.open-e2ee.dev/reference/api) ·
|
|
18
|
+
[Security](./SECURITY.md)
|
|
23
19
|
|
|
24
|
-
|
|
20
|
+
- **One TypeScript package.** Run the same protocol code in Expo, React Native, modern browsers, and Node.
|
|
21
|
+
- **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.
|
|
22
|
+
- **Messaging primitives included.** Build multi-device messaging, groups, sealed sender, encrypted attachments, and safety-number verification.
|
|
23
|
+
- **Explicit infrastructure boundaries.** Your application owns device-local storage. Supply your own relay adapter or use [OpenE2EE Relay](https://open-e2ee.dev/relay) for managed encrypted delivery. The relay never needs message plaintext or device private keys.
|
|
24
|
+
- **AGPLv3, or a commercial license.** Proprietary applications that cannot meet AGPLv3 obligations can use a [commercial license](./COMMERCIAL.md).
|
|
25
25
|
|
|
26
|
-
|
|
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).
|
|
26
|
+
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
27
|
|
|
33
|
-
|
|
28
|
+
Version `1.0.x`. Public APIs and persisted formats follow semantic versioning.
|
|
34
29
|
|
|
35
|
-
|
|
30
|
+
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
31
|
|
|
37
|
-
## See
|
|
32
|
+
## See an encrypted round trip
|
|
38
33
|
|
|
39
|
-
|
|
34
|
+
Press play for the complete four-message run: device setup, session establishment, encrypted relay delivery, and on-device decryption.
|
|
40
35
|
|
|
41
|
-
|
|
36
|
+
https://github.com/user-attachments/assets/d8002bc3-c037-41b6-8f48-4008f2d49e6c
|
|
42
37
|
|
|
43
|
-
The
|
|
38
|
+
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
39
|
|
|
45
40
|
## Install
|
|
46
41
|
|
|
47
|
-
|
|
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:
|
|
42
|
+
Requires Node 18 or later for the local example.
|
|
52
43
|
|
|
53
44
|
```bash
|
|
54
|
-
npm install
|
|
45
|
+
npm install @open-e2ee/signal-protocol-sdk
|
|
55
46
|
```
|
|
56
47
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
## Quick Start
|
|
48
|
+
## Run a local encrypted round trip
|
|
60
49
|
|
|
61
|
-
|
|
50
|
+
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
51
|
|
|
63
52
|
<!-- doc-snippet:run readme-quick-start expect="alice: hello" -->
|
|
64
53
|
```ts
|
|
@@ -80,97 +69,73 @@ const bob = await createSignalProtocolClient({
|
|
|
80
69
|
adapters: { storage: inMemoryStore(), relay },
|
|
81
70
|
});
|
|
82
71
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
72
|
+
const delivered = new Promise((resolve) => {
|
|
73
|
+
bob.registerHook("onMessageDecrypted", async (message) => {
|
|
74
|
+
console.log(`${message.senderId}: ${message.content}`);
|
|
75
|
+
bob.stopRelaySubscription();
|
|
76
|
+
resolve(undefined);
|
|
77
|
+
});
|
|
89
78
|
});
|
|
90
79
|
|
|
91
|
-
await alice.send("bob", "hello");
|
|
92
|
-
bob.startRelaySubscription();
|
|
80
|
+
await alice.send("bob", "hello");
|
|
81
|
+
bob.startRelaySubscription();
|
|
82
|
+
await delivered;
|
|
93
83
|
```
|
|
94
84
|
|
|
95
|
-
|
|
96
|
-
|
|
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).
|
|
85
|
+
Expected output:
|
|
98
86
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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.
|
|
87
|
+
```text
|
|
88
|
+
alice: hello
|
|
89
|
+
```
|
|
114
90
|
|
|
115
|
-
The
|
|
91
|
+
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
92
|
|
|
117
|
-
|
|
93
|
+
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 [documentation quickstart](https://docs.open-e2ee.dev/start/quickstart), which explains key custody, relay metadata, prekey replenishment, additional devices, and recovery policy.
|
|
118
94
|
|
|
119
|
-
|
|
95
|
+
## Move to production storage
|
|
120
96
|
|
|
121
|
-
|
|
97
|
+
Choose the device-local store for your runtime. Then supply a relay that authenticates each device and implements your product's access policy, or use [OpenE2EE Relay](https://open-e2ee.dev/relay) as the managed delivery path. The SDK does not require the managed service. [Review Relay plans and exact meter definitions.](https://open-e2ee.dev/relay/pricing)
|
|
122
98
|
|
|
123
|
-
|
|
99
|
+
| Runtime | Storage path | Deployment boundary |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| Expo | [`expoStore`](./local/store/expo/README.md) | Configure SQLCipher before schema access. Requires a development build; it does not run in Expo Go. |
|
|
102
|
+
| 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. |
|
|
103
|
+
| Bare React Native | [`reactNativeStore`](./local/store/react-native/README.md) | Provide an atomic, durable key-value backend and run the exported backend conformance kit. |
|
|
104
|
+
| Node | [`nodeStore`](./local/store/node/README.md) | Set an explicit private data directory on a trusted local filesystem. |
|
|
124
105
|
|
|
125
|
-
|
|
106
|
+
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
107
|
|
|
127
|
-
|
|
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) | — |
|
|
108
|
+
## Security and assurance
|
|
136
109
|
|
|
137
|
-
|
|
110
|
+
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
111
|
|
|
139
|
-
|
|
112
|
+
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
113
|
|
|
141
|
-
|
|
114
|
+
Report a suspected vulnerability privately through the process in [SECURITY](./SECURITY.md). Do not open a public issue for it.
|
|
142
115
|
|
|
143
|
-
|
|
116
|
+
## Why developers choose this SDK
|
|
144
117
|
|
|
145
|
-
|
|
118
|
+
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. Applications can operate a relay adapter or use OpenE2EE Relay for managed delivery.
|
|
146
119
|
|
|
147
|
-
|
|
148
|
-
- fixed work on both decapsulation candidates, then a masked choice between them
|
|
149
|
-
- equal-work rejection padding on selected replay and authentication paths
|
|
120
|
+
[Compare maintained alternatives and their limits.](https://open-e2ee.dev/product/#how-it-compares)
|
|
150
121
|
|
|
151
|
-
|
|
122
|
+
## Documentation
|
|
152
123
|
|
|
153
|
-
|
|
124
|
+
- [Getting started](./docs/GETTING_STARTED.md): the integration sequence and mental model.
|
|
125
|
+
- [Package surface](./docs/PACKAGE_SURFACE.md): root exports, subpaths, adapters, and core concepts.
|
|
126
|
+
- [Recipes](./docs/RECIPES.md): messaging, multi-device, attachments, and usernames.
|
|
127
|
+
- [Architecture](./ARCHITECTURE.md) and [adapters](./ADAPTERS.md): layer ownership and composition boundaries.
|
|
128
|
+
- [Integration interfaces](./docs/INTERFACES.md): contracts for custom stores, vaults, relays, and object stores.
|
|
129
|
+
- [Error handling](./docs/ERROR_HANDLING.md) and [troubleshooting](./TROUBLESHOOTING.md).
|
|
130
|
+
- [Deviations](./docs/DEVIATIONS.md): differences from the specifications and libsignal, with reasons and costs.
|
|
131
|
+
- [Hosted API reference](https://docs.open-e2ee.dev/reference/api): exported types and methods.
|
|
154
132
|
|
|
155
|
-
##
|
|
133
|
+
## Help and contributing
|
|
156
134
|
|
|
157
|
-
|
|
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.
|
|
135
|
+
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
136
|
|
|
172
137
|
## License and warranty
|
|
173
138
|
|
|
174
|
-
Licensed under `AGPL-3.0-or-later
|
|
139
|
+
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
140
|
|
|
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
|
|
141
|
+
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
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Third-party notices
|
|
2
2
|
|
|
3
3
|
This file records third-party source distributed with or adapted by the
|
|
4
|
-
OpenE2EE SDK. Dependency distributions may contain additional notices.
|
|
4
|
+
OpenE2EE Signal Protocol SDK. Dependency distributions may contain additional notices.
|
|
5
5
|
|
|
6
6
|
## @noble/post-quantum
|
|
7
7
|
|
package/TROUBLESHOOTING.md
CHANGED
|
@@ -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);
|
package/blocking/README.md
CHANGED
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
|
|