@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/docs/ERROR_HANDLING.md
CHANGED
|
@@ -14,13 +14,14 @@ The library uses a structured error system with stable programmatic codes:
|
|
|
14
14
|
|
|
15
15
|
### EncryptionError (Base Class)
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
Every error in the `EncryptionErrorCode` family extends `EncryptionError`:
|
|
18
18
|
|
|
19
|
+
<!-- doc-snippet:skip requires-existing-client-and-session -->
|
|
19
20
|
```typescript
|
|
20
21
|
import { EncryptionError, EncryptionErrorCode } from '@open-e2ee/signal-protocol-sdk';
|
|
21
22
|
|
|
22
23
|
try {
|
|
23
|
-
await signal.encryptMessage(
|
|
24
|
+
await signal.encryptMessage(remoteAddress, plaintext);
|
|
24
25
|
} catch (error) {
|
|
25
26
|
if (error instanceof EncryptionError) {
|
|
26
27
|
console.log('Error code:', error.code);
|
|
@@ -36,11 +37,12 @@ try {
|
|
|
36
37
|
|
|
37
38
|
Thrown when an identity key is not trusted. Requires user intervention (safety number verification).
|
|
38
39
|
|
|
40
|
+
<!-- doc-snippet:skip requires-untrusted-identity-fixture -->
|
|
39
41
|
```typescript
|
|
40
42
|
import { isUntrustedIdentityError } from '@open-e2ee/signal-protocol-sdk';
|
|
41
43
|
|
|
42
44
|
try {
|
|
43
|
-
await signal.establishSession(
|
|
45
|
+
await signal.establishSession(remoteAddress, bundle);
|
|
44
46
|
} catch (error) {
|
|
45
47
|
if (isUntrustedIdentityError(error)) {
|
|
46
48
|
// Show safety number verification UI
|
|
@@ -61,57 +63,92 @@ survives that nothing produces. A code documented here is therefore one an
|
|
|
61
63
|
application can branch on. The check runs on every change, with the rest of the
|
|
62
64
|
checks that [ASSURANCE.md](./ASSURANCE.md) describes.
|
|
63
65
|
|
|
64
|
-
The tables
|
|
65
|
-
|
|
66
|
+
The tables list the complete `EncryptionErrorCode` enum. The error-surface check
|
|
67
|
+
holds each member to a production construction site.
|
|
66
68
|
|
|
67
69
|
### Session Errors
|
|
68
70
|
|
|
69
|
-
| Code
|
|
70
|
-
|
|
71
|
-
| `SESSION_NOT_FOUND` | No session exists for the address | Establish new session
|
|
72
|
-
| `SESSION_CORRUPTED` |
|
|
71
|
+
| Code | Cause | Application response |
|
|
72
|
+
|---|---|---|
|
|
73
|
+
| `SESSION_NOT_FOUND` | No session exists for the address. | Establish a new session. |
|
|
74
|
+
| `SESSION_CORRUPTED` | Stored session data is invalid. | Delete the damaged session, then establish one. |
|
|
75
|
+
| `RECIPIENT_NOT_REGISTERED` | The recipient has no published prekey bundle. | Wait for recipient registration, then retry. |
|
|
76
|
+
| `PREKEY_FETCH_RATE_LIMITED` | The relay refused another prekey fetch. | Wait for the relay limit, then retry. |
|
|
77
|
+
| `SESSION_ESTABLISHMENT_FAILED` | Session setup failed after retries. | Inspect `originalError`, then retry after its cause is fixed. |
|
|
73
78
|
|
|
74
79
|
### Message Errors
|
|
75
80
|
|
|
76
|
-
| Code
|
|
77
|
-
|
|
78
|
-
| `INVALID_CIPHERTEXT`
|
|
79
|
-
| `DECRYPTION_FAILED`
|
|
80
|
-
| `ENCRYPTION_FAILED`
|
|
81
|
-
| `MESSAGE_DUPLICATE`
|
|
82
|
-
| `TOO_MANY_SKIPPED_MESSAGES` |
|
|
81
|
+
| Code | Cause | Application response |
|
|
82
|
+
|---|---|---|
|
|
83
|
+
| `INVALID_CIPHERTEXT` | The ciphertext format is invalid. | Reject the message. |
|
|
84
|
+
| `DECRYPTION_FAILED` | Available session state could not decrypt the message. | Let the retry flow recover, or inspect the session state. |
|
|
85
|
+
| `ENCRYPTION_FAILED` | The SDK could not encrypt the message. | Inspect the session state and `originalError`. |
|
|
86
|
+
| `MESSAGE_DUPLICATE` | The session processed this message before. | Discard the duplicate. |
|
|
87
|
+
| `TOO_MANY_SKIPPED_MESSAGES` | The message exceeded the skipped-key bound. | Reset the affected session. |
|
|
88
|
+
| `REPLAY_DETECTED` | Envelope and encrypted-content timestamps differ. | Reject the message as a replay. |
|
|
89
|
+
| `SENDER_KEY_EXPIRED` | The sender key exceeded its rotation period. | Rotate and redistribute the sender key. |
|
|
83
90
|
|
|
84
|
-
### Identity
|
|
91
|
+
### Identity and Trust Errors
|
|
85
92
|
|
|
86
|
-
| Code
|
|
87
|
-
|
|
88
|
-
| `UNTRUSTED_IDENTITY`
|
|
89
|
-
| `
|
|
93
|
+
| Code | Cause | Application response |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| `UNTRUSTED_IDENTITY` | The peer identity is unverified or changed. | Verify the safety number before acceptance. |
|
|
96
|
+
| `IDENTITY_MISMATCH` | The message identity does not match the expected sender. | Reject the message and inspect the identity state. |
|
|
97
|
+
| `SIGNATURE_VERIFICATION_FAILED` | A signature is invalid. | Reject the signed value. |
|
|
90
98
|
|
|
91
|
-
###
|
|
99
|
+
### Prekey and Session Establishment Errors
|
|
92
100
|
|
|
93
|
-
| Code
|
|
94
|
-
|
|
95
|
-
| `INVALID_PREKEY_BUNDLE` |
|
|
96
|
-
| `PREKEY_NOT_FOUND`
|
|
101
|
+
| Code | Cause | Application response |
|
|
102
|
+
|---|---|---|
|
|
103
|
+
| `INVALID_PREKEY_BUNDLE` | A prekey bundle is malformed or inconsistent. | Reject it and fetch a current bundle. |
|
|
104
|
+
| `PREKEY_NOT_FOUND` | The required prekey is unavailable. | Fetch current peer keys or rotate local keys, as the operation requires. |
|
|
105
|
+
| `PREKEY_ROTATION_REQUIRED` | A local signed or Kyber prekey is too old. | Rotate prekeys before another send. |
|
|
97
106
|
|
|
98
107
|
### Ratchet Errors
|
|
99
108
|
|
|
100
|
-
| Code
|
|
101
|
-
|
|
102
|
-
| `
|
|
109
|
+
| Code | Cause | Application response |
|
|
110
|
+
|---|---|---|
|
|
111
|
+
| `COUNTER_OVERFLOW` | A message counter reached its safe bound. | Rotate the session or ratchet epoch. |
|
|
112
|
+
| `INVALID_DH_KEY` | A DH public key is malformed or invalid. | Reject the key and its message. |
|
|
103
113
|
|
|
104
114
|
### Storage Errors
|
|
105
115
|
|
|
106
|
-
| Code
|
|
107
|
-
|
|
108
|
-
| `KEY_STORAGE_ERROR`
|
|
109
|
-
| `STORAGE_QUOTA_EXCEEDED` | The
|
|
116
|
+
| Code | Cause | Application response |
|
|
117
|
+
|---|---|---|
|
|
118
|
+
| `KEY_STORAGE_ERROR` | A key-storage operation failed. | Inspect `originalError`, then retry or reinitialize storage. |
|
|
119
|
+
| `STORAGE_QUOTA_EXCEEDED` | The storage origin ran out of space. | Free storage space, then retry the rejected write. |
|
|
120
|
+
|
|
121
|
+
### Initialization and Protocol Policy Errors
|
|
122
|
+
|
|
123
|
+
| Code | Cause | Application response |
|
|
124
|
+
|---|---|---|
|
|
125
|
+
| `INITIALIZATION_FAILED` | Client or group initialization failed. | Inspect `originalError` and the configuration. |
|
|
126
|
+
| `PQXDH_REQUIRED` | Policy requires PQXDH, but the peer lacks required keys. | Wait for new peer keys or queue the message. |
|
|
127
|
+
| `PQXDH_FAILED` | The PQXDH exchange failed. | Abort setup and inspect `originalError`. |
|
|
128
|
+
| `TRIPLE_RATCHET_REQUIRED` | Triple Ratchet policy lacks a PQXDH session. | Establish the required PQXDH session first. |
|
|
129
|
+
|
|
130
|
+
### SPQR Errors
|
|
131
|
+
|
|
132
|
+
| Code | Cause | Application response |
|
|
133
|
+
|---|---|---|
|
|
134
|
+
| `SPQR_EPOCH_OUT_OF_RANGE` | The requested epoch is too old or not established. | Reject the message and synchronize session state. |
|
|
135
|
+
| `SPQR_MESSAGE_JUMP_TOO_LARGE` | The message jump exceeds the configured bound. | Reject the message. |
|
|
136
|
+
| `SPQR_COUNTER_OVERFLOW` | The SPQR message counter reached its bound. | Rotate the SPQR epoch. |
|
|
137
|
+
| `SPQR_INVALID_CIPHERTEXT` | An SPQR ML-KEM ciphertext has an invalid form. | Reject the message. |
|
|
138
|
+
| `SPQR_VERSION_MISMATCH` | Peer and local SPQR version ranges do not overlap. | Update the peer or the required protocol policy. |
|
|
139
|
+
|
|
140
|
+
### Sealed Sender and State Errors
|
|
141
|
+
|
|
142
|
+
| Code | Cause | Application response |
|
|
143
|
+
|---|---|---|
|
|
144
|
+
| `SEALED_SENDER_AUTH_FAILED` | The relay rejected sealed-sender authorization. | Reauthorize or use identified delivery when policy permits it. |
|
|
145
|
+
| `INVALID_STATE` | The requested operation is invalid for current state. | Correct the call order or synchronize state. |
|
|
110
146
|
|
|
111
147
|
## Error Handling Patterns
|
|
112
148
|
|
|
113
149
|
### One Handler for Every Error
|
|
114
150
|
|
|
151
|
+
<!-- doc-snippet:skip application-handler-fragment -->
|
|
115
152
|
```typescript
|
|
116
153
|
import {
|
|
117
154
|
EncryptionError,
|
|
@@ -170,6 +207,7 @@ async function handleEncryptionError(error: unknown): Promise<void> {
|
|
|
170
207
|
|
|
171
208
|
The library provides a built-in retry utility:
|
|
172
209
|
|
|
210
|
+
<!-- doc-snippet:skip requires-existing-client -->
|
|
173
211
|
```typescript
|
|
174
212
|
import { withRetry } from '@open-e2ee/signal-protocol-sdk/utils/retry';
|
|
175
213
|
|
|
@@ -188,35 +226,43 @@ await withRetry(
|
|
|
188
226
|
|
|
189
227
|
### Session Recovery Pattern
|
|
190
228
|
|
|
229
|
+
<!-- doc-snippet:skip application-session-recovery-fragment -->
|
|
191
230
|
```typescript
|
|
231
|
+
import {
|
|
232
|
+
EncryptionError,
|
|
233
|
+
EncryptionErrorCode,
|
|
234
|
+
ProtocolAddress,
|
|
235
|
+
type SignalProtocolClient,
|
|
236
|
+
} from '@open-e2ee/signal-protocol-sdk';
|
|
237
|
+
|
|
192
238
|
async function ensureSession(
|
|
193
239
|
signal: SignalProtocolClient,
|
|
194
240
|
userId: string,
|
|
195
241
|
deviceId: number
|
|
196
242
|
): Promise<void> {
|
|
197
|
-
const
|
|
243
|
+
const remoteAddress = ProtocolAddress.create(userId, deviceId);
|
|
198
244
|
|
|
199
245
|
try {
|
|
200
|
-
const hasSession = await signal.hasSession(
|
|
246
|
+
const hasSession = await signal.hasSession(remoteAddress);
|
|
201
247
|
if (!hasSession) {
|
|
202
248
|
// Fetch prekey bundle and establish session
|
|
203
249
|
const bundle = await fetchPreKeyBundle(userId, deviceId);
|
|
204
|
-
await signal.establishSession(
|
|
250
|
+
await signal.establishSession(remoteAddress, bundle);
|
|
205
251
|
}
|
|
206
252
|
} catch (error) {
|
|
207
253
|
if (error instanceof EncryptionError) {
|
|
208
254
|
switch (error.code) {
|
|
209
255
|
case EncryptionErrorCode.SESSION_CORRUPTED:
|
|
210
256
|
// Delete corrupted session and retry
|
|
211
|
-
await signal.deleteSession(
|
|
257
|
+
await signal.deleteSession(remoteAddress);
|
|
212
258
|
const bundle = await fetchPreKeyBundle(userId, deviceId);
|
|
213
|
-
await signal.establishSession(
|
|
259
|
+
await signal.establishSession(remoteAddress, bundle);
|
|
214
260
|
break;
|
|
215
261
|
|
|
216
262
|
case EncryptionErrorCode.INVALID_PREKEY_BUNDLE:
|
|
217
263
|
// Bundle was invalid, try fetching again
|
|
218
264
|
const newBundle = await fetchPreKeyBundle(userId, deviceId);
|
|
219
|
-
await signal.establishSession(
|
|
265
|
+
await signal.establishSession(remoteAddress, newBundle);
|
|
220
266
|
break;
|
|
221
267
|
|
|
222
268
|
default:
|
|
@@ -233,6 +279,7 @@ async function ensureSession(
|
|
|
233
279
|
|
|
234
280
|
The library includes structured logging for errors:
|
|
235
281
|
|
|
282
|
+
<!-- doc-snippet:skip requires-platform-adapters -->
|
|
236
283
|
```typescript
|
|
237
284
|
import { SignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
|
|
238
285
|
|
|
@@ -256,20 +303,19 @@ void signal;
|
|
|
256
303
|
|
|
257
304
|
### 1. Always Use Type Guards
|
|
258
305
|
|
|
306
|
+
<!-- doc-snippet:skip type-guard-comparison-fragment -->
|
|
259
307
|
```typescript
|
|
260
|
-
//
|
|
308
|
+
// Prefer the exported guard so narrowing stays behind one public function.
|
|
261
309
|
if (isUntrustedIdentityError(error)) {
|
|
262
310
|
// Handle untrusted identity
|
|
263
311
|
}
|
|
264
312
|
|
|
265
|
-
//
|
|
266
|
-
if (error instanceof UntrustedIdentityError) {
|
|
267
|
-
// This might fail if bundled differently
|
|
268
|
-
}
|
|
313
|
+
// Current guards delegate to instanceof. Bundle one copy of the SDK.
|
|
269
314
|
```
|
|
270
315
|
|
|
271
316
|
### 2. Preserve Error Context
|
|
272
317
|
|
|
318
|
+
<!-- doc-snippet:skip error-wrapping-comparison-fragment -->
|
|
273
319
|
```typescript
|
|
274
320
|
// Good: Wrap errors with context
|
|
275
321
|
throw new EncryptionError('Failed to establish session', EncryptionErrorCode.SESSION_NOT_FOUND, {
|
|
@@ -284,6 +330,7 @@ throw new Error('Session error');
|
|
|
284
330
|
|
|
285
331
|
### 3. Handle Security-Critical Errors Prominently
|
|
286
332
|
|
|
333
|
+
<!-- doc-snippet:skip requires-identity-change-fixture -->
|
|
287
334
|
```typescript
|
|
288
335
|
// Identity changes require prominent user warning
|
|
289
336
|
if (isUntrustedIdentityError(error)) {
|
|
@@ -304,22 +351,6 @@ if (isUntrustedIdentityError(error)) {
|
|
|
304
351
|
}
|
|
305
352
|
```
|
|
306
353
|
|
|
307
|
-
### 4. Clean Up on Errors
|
|
308
|
-
|
|
309
|
-
```typescript
|
|
310
|
-
let session = null;
|
|
311
|
-
try {
|
|
312
|
-
session = await signal.establishSession(sessionId, remoteAddress, bundle);
|
|
313
|
-
// Use session...
|
|
314
|
-
} catch (error) {
|
|
315
|
-
// Clean up partial state
|
|
316
|
-
if (session) {
|
|
317
|
-
await signal.deleteSession(sessionId);
|
|
318
|
-
}
|
|
319
|
-
throw error;
|
|
320
|
-
}
|
|
321
|
-
```
|
|
322
|
-
|
|
323
354
|
## See Also
|
|
324
355
|
|
|
325
356
|
- [SECURITY.md](./SECURITY.md) - Security guidelines
|
package/docs/GETTING_STARTED.md
CHANGED
|
@@ -101,13 +101,20 @@ flowchart LR
|
|
|
101
101
|
envelopes.
|
|
102
102
|
- The remote object store carries encrypted attachment/media bytes only.
|
|
103
103
|
|
|
104
|
+
You can operate these server-side interfaces through a shipped or custom
|
|
105
|
+
adapter. You can instead use [OpenE2EE Relay](https://open-e2ee.dev/relay) for
|
|
106
|
+
managed encrypted delivery, private encrypted attachment storage, push wakes,
|
|
107
|
+
and lifecycle controls. The SDK does not require the managed service. The
|
|
108
|
+
[Relay pricing page](https://open-e2ee.dev/relay/pricing) defines its exact
|
|
109
|
+
meters and limits.
|
|
110
|
+
|
|
104
111
|
## Target Message-First API Preview
|
|
105
112
|
|
|
106
113
|
This is the target DX the package moves toward. It appears here so app
|
|
107
114
|
developers can understand the intended mental model. The current stable API
|
|
108
115
|
still uses `storage`, `remoteObjectStore`, hooks, and transition-only media helpers.
|
|
109
116
|
|
|
110
|
-
<!-- doc-snippet:
|
|
117
|
+
<!-- doc-snippet:planned target-message-api unshipped="@open-e2ee/signal-protocol-sdk/device/storage/memory" -->
|
|
111
118
|
```ts
|
|
112
119
|
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
113
120
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
@@ -161,6 +168,7 @@ await delivered;
|
|
|
161
168
|
|
|
162
169
|
The production shape uses the same message API with platform adapters:
|
|
163
170
|
|
|
171
|
+
<!-- doc-snippet:planned target-message-api-platform-adapters unshipped="@open-e2ee/signal-protocol-sdk/device/storage/expo" -->
|
|
164
172
|
```ts
|
|
165
173
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
166
174
|
import { createExpoDeviceStorage } from "@open-e2ee/signal-protocol-sdk/device/storage/expo";
|
|
@@ -185,6 +193,7 @@ Attachments use the same message API. On Expo, pass the picker URI. The Signal
|
|
|
185
193
|
Protocol client copies or persists the bytes through `deviceStorage.files`
|
|
186
194
|
before upload, so retry can continue after restart:
|
|
187
195
|
|
|
196
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
188
197
|
```ts
|
|
189
198
|
await signal.messages.send({
|
|
190
199
|
conversationId: "dm:alice_bob",
|
|
@@ -203,6 +212,7 @@ await signal.messages.send({
|
|
|
203
212
|
|
|
204
213
|
On the web, pass the browser file object:
|
|
205
214
|
|
|
215
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
206
216
|
```ts
|
|
207
217
|
await signal.messages.send({
|
|
208
218
|
conversationId,
|
|
@@ -314,6 +324,7 @@ Use the protocol storage adapter for your runtime and the relay adapter for your
|
|
|
314
324
|
backend. For the Signal Protocol stack, that is Expo local storage and a Convex
|
|
315
325
|
relay:
|
|
316
326
|
|
|
327
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
317
328
|
```ts
|
|
318
329
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
319
330
|
import { expoStore } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
|
|
@@ -353,6 +364,7 @@ provisioning belong to the application bootstrap.
|
|
|
353
364
|
|
|
354
365
|
Register a receive hook before starting the relay subscription:
|
|
355
366
|
|
|
367
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
356
368
|
```ts
|
|
357
369
|
signal.registerHook("onMessageDecrypted", async (message) => {
|
|
358
370
|
// Decrypted content belongs in your app database, not in the relay.
|
|
@@ -377,12 +389,14 @@ and hands the app a `DecryptedEnvelope`.
|
|
|
377
389
|
|
|
378
390
|
Send by recipient user ID for normal one-to-one and multi-device delivery:
|
|
379
391
|
|
|
392
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
380
393
|
```ts
|
|
381
394
|
await signal.send("bob", "hello");
|
|
382
395
|
```
|
|
383
396
|
|
|
384
397
|
For structured app messages, pass an object:
|
|
385
398
|
|
|
399
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
386
400
|
```ts
|
|
387
401
|
await signal.send("bob", {
|
|
388
402
|
body: "hello",
|
|
@@ -400,6 +414,7 @@ The final public DX should not expose both `signal.media.*` and message
|
|
|
400
414
|
attachment helpers. The planned replacement is message-scoped attachment
|
|
401
415
|
handling.
|
|
402
416
|
|
|
417
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
403
418
|
```ts
|
|
404
419
|
import { media } from "@open-e2ee/signal-protocol-sdk";
|
|
405
420
|
import { convexR2ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2";
|
|
@@ -431,6 +446,7 @@ const signal = await createSignalProtocolClient({
|
|
|
431
446
|
For Amazon S3 or S3-compatible storage, use the framework-neutral adapter with
|
|
432
447
|
an authenticated application-backend broker:
|
|
433
448
|
|
|
449
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
434
450
|
```ts
|
|
435
451
|
import { s3ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/s3";
|
|
436
452
|
|
|
@@ -450,6 +466,7 @@ operations.
|
|
|
450
466
|
|
|
451
467
|
Send bytes when the attachment travels as its own encrypted message:
|
|
452
468
|
|
|
469
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
453
470
|
```ts
|
|
454
471
|
const controller = new AbortController();
|
|
455
472
|
|
|
@@ -481,6 +498,7 @@ await signal.send("bob", photoBytes, {
|
|
|
481
498
|
Upload first when your app message format embeds the attachment pointer inside a
|
|
482
499
|
larger payload:
|
|
483
500
|
|
|
501
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
484
502
|
```ts
|
|
485
503
|
const attachment = await signal.uploadAttachment(photoBytes, {
|
|
486
504
|
mimeType: "image/jpeg",
|
|
@@ -530,6 +548,7 @@ adapter. The target message-first API moves that responsibility behind
|
|
|
530
548
|
`deviceStorage.messages`. The operation tries the upload when it is due and
|
|
531
549
|
returns either a completed pointer or a pending job id for later recovery:
|
|
532
550
|
|
|
551
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
533
552
|
```ts
|
|
534
553
|
const upload = await signal.media.upload(
|
|
535
554
|
{
|
|
@@ -554,6 +573,7 @@ if (upload.status === "completed") {
|
|
|
554
573
|
Run pending durable media work on app startup, foreground resume, or from a
|
|
555
574
|
background task:
|
|
556
575
|
|
|
576
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
557
577
|
```ts
|
|
558
578
|
await signal.media.processPending({
|
|
559
579
|
limit: 10,
|
|
@@ -566,6 +586,7 @@ On receive, ask the media planner what work this device should do. Your app
|
|
|
566
586
|
supplies the IDs it has already processed or cached. The Signal Protocol package
|
|
567
587
|
returns the safe next step, and it does not take ownership of your app database:
|
|
568
588
|
|
|
589
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
569
590
|
```ts
|
|
570
591
|
const mediaWork = media.planMediaAttachmentProcessing({
|
|
571
592
|
attachment,
|
|
@@ -609,6 +630,7 @@ If the planner says this device needs media bytes, pass the decrypted attachment
|
|
|
609
630
|
pointer back to the client. The client downloads encrypted blob bytes, verifies
|
|
610
631
|
the digest, authenticates the stream, and returns plaintext bytes:
|
|
611
632
|
|
|
633
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
612
634
|
```ts
|
|
613
635
|
if (mediaWork.shouldDownload) {
|
|
614
636
|
const downloaded = await signal.downloadAttachment(attachment, {
|
|
@@ -640,6 +662,7 @@ if (mediaWork.shouldDownload) {
|
|
|
640
662
|
If the attachment is view-once, plan the local cleanup and linked-device sync
|
|
641
663
|
after the user opens it:
|
|
642
664
|
|
|
665
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
643
666
|
```ts
|
|
644
667
|
const opened = media.planMediaAttachmentOpen({
|
|
645
668
|
attachment,
|
|
@@ -663,6 +686,7 @@ if (opened.cleanup?.deleteRemoteBlob) {
|
|
|
663
686
|
A message delete or expiration can remove media on this account's linked
|
|
664
687
|
devices. Plan and sync the deletion after your app applies the local cleanup:
|
|
665
688
|
|
|
689
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
666
690
|
```ts
|
|
667
691
|
const deleteSync = media.planMediaAttachmentDeleteSync({
|
|
668
692
|
attachment,
|
|
@@ -676,6 +700,7 @@ await signal.syncMediaAttachmentDeleteToLinkedDevices(deleteSync);
|
|
|
676
700
|
|
|
677
701
|
When a worker must do the cleanup, use the durable client operation:
|
|
678
702
|
|
|
703
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
679
704
|
```ts
|
|
680
705
|
await signal.media.cleanup(
|
|
681
706
|
{
|
|
@@ -697,6 +722,7 @@ await signal.media.cleanup(
|
|
|
697
722
|
|
|
698
723
|
The default is:
|
|
699
724
|
|
|
725
|
+
<!-- doc-snippet:illustrative config-object-fragment -->
|
|
700
726
|
```ts
|
|
701
727
|
protocol: {
|
|
702
728
|
postQuantum: 'required',
|
package/docs/INTERFACES.md
CHANGED
|
@@ -31,6 +31,7 @@ requirements described below.
|
|
|
31
31
|
`ISignalProtocolLocalStore` persists the current device's identities, prekeys, sessions,
|
|
32
32
|
sender keys, contact trust, retry records, and operational metadata.
|
|
33
33
|
|
|
34
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
34
35
|
```ts
|
|
35
36
|
import type { ISignalProtocolLocalStore } from "@open-e2ee/signal-protocol-sdk/local/store";
|
|
36
37
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
@@ -62,6 +63,7 @@ and their status.
|
|
|
62
63
|
secrets that must live outside the main local store, such as a database
|
|
63
64
|
encryption key.
|
|
64
65
|
|
|
66
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
65
67
|
```ts
|
|
66
68
|
import type { ISignalProtocolLocalSecretVault } from "@open-e2ee/signal-protocol-sdk";
|
|
67
69
|
|
|
@@ -83,6 +85,7 @@ selected platform service and host configuration. See the
|
|
|
83
85
|
device registration, account identity state, public prekeys, encrypted-envelope
|
|
84
86
|
delivery, provisioning, key rotation, and encrypted group coordination.
|
|
85
87
|
|
|
88
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
86
89
|
```ts
|
|
87
90
|
import type { ISignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/relay";
|
|
88
91
|
import {
|
|
@@ -120,6 +123,7 @@ See the [relay guide](../remote/relay/README.md).
|
|
|
120
123
|
`SignalProtocolRemoteObjectStore` supplies short-lived upload and download operations
|
|
121
124
|
for already encrypted objects. It is provider-neutral and optional.
|
|
122
125
|
|
|
126
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
123
127
|
```ts
|
|
124
128
|
import type {
|
|
125
129
|
SignalProtocolRemoteObjectStore,
|
|
@@ -155,6 +159,7 @@ See the [remote object-store guide](../remote/object-store/README.md).
|
|
|
155
159
|
Application content remains outside the infrastructure adapters. Configure
|
|
156
160
|
media lifecycle callbacks and client hooks at the client boundary:
|
|
157
161
|
|
|
162
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
158
163
|
```ts
|
|
159
164
|
const client = await createSignalProtocolClient({
|
|
160
165
|
identity: { userId },
|
package/docs/PACKAGE_SURFACE.md
CHANGED
package/docs/PROTOCOL_POLICY.md
CHANGED
|
@@ -10,6 +10,7 @@ identity, the Ed25519-instead-of-XEdDSA signature scheme, the ML-KEM Braid
|
|
|
10
10
|
|
|
11
11
|
The public Signal Protocol client policy is:
|
|
12
12
|
|
|
13
|
+
<!-- doc-snippet:illustrative config-object-fragment -->
|
|
13
14
|
```ts
|
|
14
15
|
protocol: {
|
|
15
16
|
postQuantum: 'required',
|
|
@@ -25,6 +26,7 @@ the current app.
|
|
|
25
26
|
|
|
26
27
|
## Required
|
|
27
28
|
|
|
29
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
28
30
|
```ts
|
|
29
31
|
await createSignalProtocolClient({
|
|
30
32
|
identity: { userId },
|
|
@@ -39,6 +41,7 @@ closed.
|
|
|
39
41
|
|
|
40
42
|
## Compatible
|
|
41
43
|
|
|
44
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
42
45
|
```ts
|
|
43
46
|
await createSignalProtocolClient({
|
|
44
47
|
identity: { userId },
|
|
@@ -61,6 +64,7 @@ Compatible mode does not allow downgrade recovery:
|
|
|
61
64
|
|
|
62
65
|
## Braid Policy
|
|
63
66
|
|
|
67
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
64
68
|
```ts
|
|
65
69
|
await createSignalProtocolClient({
|
|
66
70
|
identity: { userId },
|
|
@@ -78,6 +82,7 @@ not stock FIPS 203.
|
|
|
78
82
|
|
|
79
83
|
See [Deviations §4.1](./DEVIATIONS.md#41-the-hek-operand-order-diverges).
|
|
80
84
|
|
|
85
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
81
86
|
```ts
|
|
82
87
|
await createSignalProtocolClient({
|
|
83
88
|
identity: { userId },
|
|
@@ -94,6 +99,7 @@ product-reviewed constraints, not downgrade recovery.
|
|
|
94
99
|
|
|
95
100
|
Use string literals directly or the exported constant object:
|
|
96
101
|
|
|
102
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
97
103
|
```ts
|
|
98
104
|
import { BraidPolicy, PostQuantumPolicy, createSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
|
|
99
105
|
|
package/docs/RECIPES.md
CHANGED
|
@@ -95,6 +95,7 @@ through the `onMessageDecrypted` hook.
|
|
|
95
95
|
|
|
96
96
|
## Production composition with Convex + Expo
|
|
97
97
|
|
|
98
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
98
99
|
```ts
|
|
99
100
|
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
100
101
|
import {
|
|
@@ -159,6 +160,7 @@ const bob = await createSignalProtocolClient({
|
|
|
159
160
|
|
|
160
161
|
## App message flow
|
|
161
162
|
|
|
163
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
162
164
|
```ts
|
|
163
165
|
const signal = await createSignalProtocolClient({
|
|
164
166
|
identity: { userId },
|
|
@@ -189,6 +191,7 @@ message storage through hooks.
|
|
|
189
191
|
|
|
190
192
|
## Protocol policy
|
|
191
193
|
|
|
194
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
192
195
|
```ts
|
|
193
196
|
await createSignalProtocolClient({
|
|
194
197
|
identity: { userId },
|
|
@@ -205,6 +208,7 @@ without post-quantum material fail closed, and PQ sessions use the SDK's
|
|
|
205
208
|
ML-KEM Braid SPQR profile. See the [protocol policy](./PROTOCOL_POLICY.md) for
|
|
206
209
|
supported choices.
|
|
207
210
|
|
|
211
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
208
212
|
```ts
|
|
209
213
|
await createSignalProtocolClient({
|
|
210
214
|
identity: { userId },
|
|
@@ -220,6 +224,7 @@ await createSignalProtocolClient({
|
|
|
220
224
|
supports them. It only allows classical compatibility for peers that advertise
|
|
221
225
|
no post-quantum material at all.
|
|
222
226
|
|
|
227
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
223
228
|
```ts
|
|
224
229
|
await createSignalProtocolClient({
|
|
225
230
|
identity: { userId },
|
|
@@ -237,6 +242,7 @@ PQXDH strictness.
|
|
|
237
242
|
|
|
238
243
|
## Multi-device send
|
|
239
244
|
|
|
245
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
240
246
|
```ts
|
|
241
247
|
const result = await signal.send(recipientUserId, "hello");
|
|
242
248
|
await appMessages.insertOutgoing({
|
|
@@ -250,6 +256,7 @@ await appMessages.insertOutgoing({
|
|
|
250
256
|
|
|
251
257
|
## Direct device session
|
|
252
258
|
|
|
259
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
253
260
|
```ts
|
|
254
261
|
import { ProtocolAddress } from "@open-e2ee/signal-protocol-sdk";
|
|
255
262
|
|
|
@@ -260,6 +267,7 @@ await signal.encryptMessage(bob, "linked-device hello");
|
|
|
260
267
|
|
|
261
268
|
## Username and ZK helpers
|
|
262
269
|
|
|
270
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
263
271
|
```ts
|
|
264
272
|
import {
|
|
265
273
|
hashUsername,
|
|
@@ -274,6 +282,7 @@ const version = computeProfileKeyVersion(profileKeyBytes, userIdBytes);
|
|
|
274
282
|
|
|
275
283
|
## Encrypted attachments
|
|
276
284
|
|
|
285
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
277
286
|
```ts
|
|
278
287
|
import { media } from "@open-e2ee/signal-protocol-sdk";
|
|
279
288
|
|
package/docs/SECURITY.md
CHANGED
|
@@ -64,6 +64,12 @@ round-3 Kyber1024 tagged `0x08`.
|
|
|
64
64
|
using ML-KEM-768 and bounded Reed-Solomon decoding.
|
|
65
65
|
- HEK follows the ML-KEM Braid specification:
|
|
66
66
|
`SHA3-256(ek_seed || ek_vector)`.
|
|
67
|
+
- FIPS 203 serializes the encapsulation key vector-first, and the braid HEK
|
|
68
|
+
order is seed-first. Braid mode therefore runs ML-KEM-768 with a modified
|
|
69
|
+
encapsulation-key commitment, and the SDK makes no FIPS 203 conformance claim
|
|
70
|
+
for that path.
|
|
71
|
+
- The modification reaches only the braid path. Direct ML-KEM-768 SCKA uses
|
|
72
|
+
stock ML-KEM-768, and PQXDH uses standardized FIPS 203 ML-KEM-1024 behavior.
|
|
67
73
|
- The SDK applies `KDF_OK` once when raw ML-KEM output enters the epoch
|
|
68
74
|
boundary. Braid output is already an epoch secret and is not derived a second
|
|
69
75
|
time.
|
package/encoding/README.md
CHANGED
package/files/README.md
CHANGED
package/groups/README.md
CHANGED
package/keys/README.md
CHANGED
|
@@ -13,6 +13,7 @@ prevents storage and relay adapters from inventing incompatible key shapes.
|
|
|
13
13
|
|
|
14
14
|
## Usage
|
|
15
15
|
|
|
16
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
16
17
|
```ts
|
|
17
18
|
import {
|
|
18
19
|
createCompositeIdentityV1,
|
|
@@ -35,6 +36,7 @@ advanced lifecycle integrations.
|
|
|
35
36
|
|
|
36
37
|
`CompositeIdentityV1` is the canonical public trust object:
|
|
37
38
|
|
|
39
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
38
40
|
```ts
|
|
39
41
|
interface CompositeIdentityV1 {
|
|
40
42
|
readonly version: 1;
|