@open-e2ee/signal-protocol-sdk 8.2.0 → 9.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ADAPTERS.md +15 -31
- package/ARCHITECTURE.md +5 -7
- package/CHANGELOG.md +128 -0
- package/README.md +52 -49
- package/SECURITY.md +2 -2
- package/client/README.md +11 -0
- package/dist/client/client.d.ts +21 -14
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +93 -78
- package/dist/client/client.js.map +1 -1
- package/dist/client/config.d.ts +10 -17
- package/dist/client/config.d.ts.map +1 -1
- package/dist/client/config.js.map +1 -1
- package/dist/client/event-hooks.js +27 -0
- package/dist/client/event-hooks.js.map +1 -1
- package/dist/client/group-receive-authorization.d.ts +5 -0
- package/dist/client/group-receive-authorization.d.ts.map +1 -0
- package/dist/client/group-receive-authorization.js +32 -0
- package/dist/client/group-receive-authorization.js.map +1 -0
- package/dist/client/group-sender-key-operations.d.ts +15 -0
- package/dist/client/group-sender-key-operations.d.ts.map +1 -0
- package/dist/client/group-sender-key-operations.js +31 -0
- package/dist/client/group-sender-key-operations.js.map +1 -0
- package/dist/client/groups.d.ts +3 -1
- package/dist/client/groups.d.ts.map +1 -1
- package/dist/client/groups.js +5 -2
- package/dist/client/groups.js.map +1 -1
- package/dist/client/hosted-sandbox-identity.d.ts +32 -0
- package/dist/client/hosted-sandbox-identity.d.ts.map +1 -0
- package/dist/client/hosted-sandbox-identity.js +157 -0
- package/dist/client/hosted-sandbox-identity.js.map +1 -0
- package/dist/client/hosted.d.ts +12 -2
- package/dist/client/hosted.d.ts.map +1 -1
- package/dist/client/hosted.js +12 -2
- package/dist/client/hosted.js.map +1 -1
- package/dist/client/index.d.ts +1 -1
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +1 -1
- package/dist/client/index.js.map +1 -1
- package/dist/client/relay-subscription.d.ts +2 -0
- package/dist/client/relay-subscription.d.ts.map +1 -1
- package/dist/client/relay-subscription.js +3 -1
- package/dist/client/relay-subscription.js.map +1 -1
- package/dist/client/sender-key-distribution.d.ts.map +1 -1
- package/dist/client/sender-key-distribution.js +4 -1
- package/dist/client/sender-key-distribution.js.map +1 -1
- package/dist/client/signal-service-cipher.d.ts +4 -2
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +61 -51
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/client/types.d.ts +0 -3
- package/dist/client/types.d.ts.map +1 -1
- package/dist/client/types.js.map +1 -1
- package/dist/index.d.ts +28 -22
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +9 -18
- package/dist/index.js.map +1 -1
- package/dist/internal/crypto/pq/kyber.d.ts +1 -1
- package/dist/internal/crypto/pq/kyber.js +1 -1
- package/dist/internal/encoding/proto/sender-key-message.d.ts +2 -2
- package/dist/internal/encoding/proto/sender-key-message.d.ts.map +1 -1
- package/dist/internal/encoding/proto/sender-key-message.js +5 -2
- package/dist/internal/encoding/proto/sender-key-message.js.map +1 -1
- package/dist/internal/groups/manager.d.ts.map +1 -1
- package/dist/internal/groups/manager.js +5 -2
- package/dist/internal/groups/manager.js.map +1 -1
- package/dist/internal/groups/wire.d.ts +0 -2
- package/dist/internal/groups/wire.d.ts.map +1 -1
- package/dist/internal/groups/wire.js +0 -6
- package/dist/internal/groups/wire.js.map +1 -1
- package/dist/internal/manager/manager.d.ts.map +1 -1
- package/dist/internal/manager/manager.js +0 -1
- package/dist/internal/manager/manager.js.map +1 -1
- package/dist/internal/protocol/double-ratchet/ratchet.d.ts +0 -17
- package/dist/internal/protocol/double-ratchet/ratchet.d.ts.map +1 -1
- package/dist/internal/protocol/double-ratchet/ratchet.js +0 -4
- package/dist/internal/protocol/double-ratchet/ratchet.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/certificate.d.ts +2 -32
- package/dist/internal/protocol/sealed-sender/certificate.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/certificate.js +4 -85
- package/dist/internal/protocol/sealed-sender/certificate.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/index.d.ts +2 -2
- package/dist/internal/protocol/sealed-sender/index.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/index.js +2 -6
- package/dist/internal/protocol/sealed-sender/index.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/proto/index.d.ts +0 -19
- package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/proto/index.js +1 -48
- package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
- package/dist/internal/protocol/sender-keys/manager.d.ts +9 -13
- package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
- package/dist/internal/protocol/sender-keys/manager.js +90 -95
- package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.d.ts +0 -2
- package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js +4 -12
- package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts +1 -0
- package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/spqr.d.ts +1 -1
- package/dist/internal/protocol/spqr/spqr.js +1 -1
- package/dist/internal/protocol/x3dh/x3dh.d.ts.map +1 -1
- package/dist/internal/protocol/x3dh/x3dh.js +1 -1
- package/dist/internal/protocol/x3dh/x3dh.js.map +1 -1
- package/dist/internal/protocol/zk/credentials/credentials.d.ts +3 -54
- package/dist/internal/protocol/zk/credentials/credentials.d.ts.map +1 -1
- package/dist/internal/protocol/zk/credentials/credentials.js +4 -91
- package/dist/internal/protocol/zk/credentials/credentials.js.map +1 -1
- package/dist/internal/protocol/zk/credentials/endorsements.d.ts +3 -64
- package/dist/internal/protocol/zk/credentials/endorsements.d.ts.map +1 -1
- package/dist/internal/protocol/zk/credentials/endorsements.js +4 -134
- package/dist/internal/protocol/zk/credentials/endorsements.js.map +1 -1
- package/dist/internal/protocol/zk/credentials/index.d.ts +3 -3
- package/dist/internal/protocol/zk/credentials/index.d.ts.map +1 -1
- package/dist/internal/protocol/zk/credentials/index.js +3 -3
- package/dist/internal/protocol/zk/credentials/index.js.map +1 -1
- package/dist/internal/protocol/zk/credentials/issuance.d.ts +3 -26
- package/dist/internal/protocol/zk/credentials/issuance.d.ts.map +1 -1
- package/dist/internal/protocol/zk/credentials/issuance.js +3 -80
- package/dist/internal/protocol/zk/credentials/issuance.js.map +1 -1
- package/dist/internal/protocol/zk/credentials/presentation.d.ts +4 -73
- package/dist/internal/protocol/zk/credentials/presentation.d.ts.map +1 -1
- package/dist/internal/protocol/zk/credentials/presentation.js +4 -152
- package/dist/internal/protocol/zk/credentials/presentation.js.map +1 -1
- package/dist/internal/protocol/zk/groups/auth-credential.d.ts +1 -61
- package/dist/internal/protocol/zk/groups/auth-credential.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/auth-credential.js +2 -196
- package/dist/internal/protocol/zk/groups/auth-credential.js.map +1 -1
- package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts +1 -86
- package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/group-send-endorsement.js +1 -152
- package/dist/internal/protocol/zk/groups/group-send-endorsement.js.map +1 -1
- package/dist/internal/protocol/zk/groups/index.d.ts +4 -4
- package/dist/internal/protocol/zk/groups/index.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/index.js +4 -4
- package/dist/internal/protocol/zk/groups/index.js.map +1 -1
- package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts +2 -57
- package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/profile-key-credential.js +2 -174
- package/dist/internal/protocol/zk/groups/profile-key-credential.js.map +1 -1
- package/dist/internal/protocol/zk/groups/server-params.d.ts +8 -72
- package/dist/internal/protocol/zk/groups/server-params.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/server-params.js +8 -108
- package/dist/internal/protocol/zk/groups/server-params.js.map +1 -1
- package/dist/internal/protocol/zk/proofs/sign.d.ts +1 -2
- package/dist/internal/protocol/zk/proofs/sign.d.ts.map +1 -1
- package/dist/internal/protocol/zk/proofs/sign.js +2 -11
- package/dist/internal/protocol/zk/proofs/sign.js.map +1 -1
- package/dist/internal/session/ratchet.d.ts.map +1 -1
- package/dist/internal/session/ratchet.js +0 -2
- package/dist/internal/session/ratchet.js.map +1 -1
- package/dist/local/store/key-value/adapter.d.ts +3 -3
- package/dist/local/store/key-value/adapter.d.ts.map +1 -1
- package/dist/local/store/key-value/adapter.js +30 -15
- package/dist/local/store/key-value/adapter.js.map +1 -1
- package/dist/local/store/key-value/backend-conformance.d.ts.map +1 -1
- package/dist/local/store/key-value/backend-conformance.js +25 -0
- package/dist/local/store/key-value/backend-conformance.js.map +1 -1
- package/dist/local/store/key-value/batch.d.ts +3 -1
- package/dist/local/store/key-value/batch.d.ts.map +1 -1
- package/dist/local/store/key-value/batch.js +9 -1
- package/dist/local/store/key-value/batch.js.map +1 -1
- package/dist/local/store/key-value/storage.d.ts +6 -0
- package/dist/local/store/key-value/storage.d.ts.map +1 -1
- package/dist/local/store/key-value/transactional-backend.d.ts +1 -1
- package/dist/local/store/key-value/transactional-backend.js +1 -1
- package/dist/local/store/memory/adapter.d.ts +3 -3
- package/dist/local/store/memory/adapter.d.ts.map +1 -1
- package/dist/local/store/memory/adapter.js +43 -18
- package/dist/local/store/memory/adapter.js.map +1 -1
- package/dist/local/store/sqlite/errors.d.ts +6 -0
- package/dist/local/store/sqlite/errors.d.ts.map +1 -1
- package/dist/local/store/sqlite/errors.js +6 -6
- package/dist/local/store/sqlite/errors.js.map +1 -1
- package/dist/local/store/sqlite/migrations.d.ts.map +1 -1
- package/dist/local/store/sqlite/migrations.js +18 -0
- package/dist/local/store/sqlite/migrations.js.map +1 -1
- package/dist/local/store/sqlite/models/skipped-sender-key.d.ts +3 -3
- package/dist/local/store/sqlite/models/skipped-sender-key.d.ts.map +1 -1
- package/dist/local/store/sqlite/models/skipped-sender-key.js +13 -17
- package/dist/local/store/sqlite/models/skipped-sender-key.js.map +1 -1
- package/dist/local/store/sqlite/store.d.ts +3 -3
- package/dist/local/store/sqlite/store.d.ts.map +1 -1
- package/dist/local/store/sqlite/store.js +17 -9
- package/dist/local/store/sqlite/store.js.map +1 -1
- package/dist/local/store/web/adapter.d.ts +3 -3
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +59 -20
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/profile/contact-state.d.ts +0 -3
- package/dist/profile/contact-state.d.ts.map +1 -1
- package/dist/profile/contact-state.js +1 -32
- package/dist/profile/contact-state.js.map +1 -1
- package/dist/profile/index.d.ts +2 -1
- package/dist/profile/index.d.ts.map +1 -1
- package/dist/profile/index.js +2 -1
- package/dist/profile/index.js.map +1 -1
- package/dist/profile/unidentified-access.d.ts +12 -0
- package/dist/profile/unidentified-access.d.ts.map +1 -0
- package/dist/profile/unidentified-access.js +42 -0
- package/dist/profile/unidentified-access.js.map +1 -0
- package/dist/remote/relay/index.d.ts +4 -7
- package/dist/remote/relay/index.d.ts.map +1 -1
- package/dist/remote/relay/index.js +5 -7
- package/dist/remote/relay/index.js.map +1 -1
- package/dist/remote/relay/types.d.ts +3 -3
- package/dist/types/api.d.ts +29 -8
- package/dist/types/api.d.ts.map +1 -1
- package/dist/types/errors.d.ts +6 -0
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/errors.js +6 -6
- package/dist/types/errors.js.map +1 -1
- package/dist/versions.d.ts +3 -3
- package/dist/versions.js +3 -3
- package/dist/zk/credentials.d.ts +2 -2
- package/dist/zk/credentials.js +2 -2
- package/dist/zk/groups.d.ts +3 -3
- package/dist/zk/groups.d.ts.map +1 -1
- package/dist/zk/groups.js +3 -3
- package/dist/zk/groups.js.map +1 -1
- package/docs/ASSURANCE.md +12 -14
- package/docs/CLIENT_COMPOSITION.md +11 -3
- package/docs/DEVIATIONS.md +24 -25
- package/docs/GETTING_STARTED.md +61 -323
- package/docs/INTERFACES.md +7 -7
- package/docs/PACKAGE_SURFACE.md +14 -16
- package/docs/RECIPES.md +7 -112
- package/groups/README.md +9 -1
- package/local/store/README.md +26 -6
- package/package.json +2 -31
- package/remote/README.md +14 -78
- package/remote/object-store/convex-r2/README.md +17 -49
- package/remote/relay/README.md +24 -18
- package/zk/README.md +6 -7
- package/dist/client/dual-store.d.ts +0 -70
- package/dist/client/dual-store.d.ts.map +0 -1
- package/dist/client/dual-store.js +0 -123
- package/dist/client/dual-store.js.map +0 -1
- package/dist/client/multi-device.d.ts +0 -74
- package/dist/client/multi-device.d.ts.map +0 -1
- package/dist/client/multi-device.js +0 -105
- package/dist/client/multi-device.js.map +0 -1
- package/dist/groups/server.d.ts +0 -10
- package/dist/groups/server.d.ts.map +0 -1
- package/dist/groups/server.js +0 -6
- package/dist/groups/server.js.map +0 -1
- package/dist/internal/encoding/index.d.ts +0 -2
- package/dist/internal/encoding/index.d.ts.map +0 -1
- package/dist/internal/encoding/index.js +0 -2
- package/dist/internal/encoding/index.js.map +0 -1
- package/dist/internal/groups/server-engine.d.ts +0 -118
- package/dist/internal/groups/server-engine.d.ts.map +0 -1
- package/dist/internal/groups/server-engine.js +0 -1268
- package/dist/internal/groups/server-engine.js.map +0 -1
- package/dist/internal/protocol/index.d.ts +0 -24
- package/dist/internal/protocol/index.d.ts.map +0 -1
- package/dist/internal/protocol/index.js +0 -9
- package/dist/internal/protocol/index.js.map +0 -1
- package/dist/internal/protocol/sealed-sender/trust-root.d.ts +0 -56
- package/dist/internal/protocol/sealed-sender/trust-root.d.ts.map +0 -1
- package/dist/internal/protocol/sealed-sender/trust-root.js +0 -90
- package/dist/internal/protocol/sealed-sender/trust-root.js.map +0 -1
- package/dist/internal/protocol/triple-ratchet/index.d.ts +0 -21
- package/dist/internal/protocol/triple-ratchet/index.d.ts.map +0 -1
- package/dist/internal/protocol/triple-ratchet/index.js +0 -19
- package/dist/internal/protocol/triple-ratchet/index.js.map +0 -1
- package/dist/internal/protocol/triple-ratchet/ratchet.d.ts +0 -233
- package/dist/internal/protocol/triple-ratchet/ratchet.d.ts.map +0 -1
- package/dist/internal/protocol/triple-ratchet/ratchet.js +0 -254
- package/dist/internal/protocol/triple-ratchet/ratchet.js.map +0 -1
- package/dist/internal/protocol/zk/proofs/index.d.ts +0 -13
- package/dist/internal/protocol/zk/proofs/index.d.ts.map +0 -1
- package/dist/internal/protocol/zk/proofs/index.js +0 -7
- package/dist/internal/protocol/zk/proofs/index.js.map +0 -1
- package/dist/local/store/sqlite/index.d.ts +0 -20
- package/dist/local/store/sqlite/index.d.ts.map +0 -1
- package/dist/local/store/sqlite/index.js +0 -18
- package/dist/local/store/sqlite/index.js.map +0 -1
- package/dist/remote/object-store/convex-r2/server/index.d.ts +0 -2
- package/dist/remote/object-store/convex-r2/server/index.d.ts.map +0 -1
- package/dist/remote/object-store/convex-r2/server/index.js +0 -2
- package/dist/remote/object-store/convex-r2/server/index.js.map +0 -1
- package/dist/remote/object-store/convex-r2/server.d.ts +0 -129
- package/dist/remote/object-store/convex-r2/server.d.ts.map +0 -1
- package/dist/remote/object-store/convex-r2/server.js +0 -244
- package/dist/remote/object-store/convex-r2/server.js.map +0 -1
- package/dist/remote/relay/memory/adapter.d.ts +0 -252
- package/dist/remote/relay/memory/adapter.d.ts.map +0 -1
- package/dist/remote/relay/memory/adapter.js +0 -1057
- package/dist/remote/relay/memory/adapter.js.map +0 -1
- package/dist/remote/relay/memory/failures.d.ts +0 -58
- package/dist/remote/relay/memory/failures.d.ts.map +0 -1
- package/dist/remote/relay/memory/failures.js +0 -124
- package/dist/remote/relay/memory/failures.js.map +0 -1
- package/dist/remote/relay/memory/group-server.d.ts +0 -13
- package/dist/remote/relay/memory/group-server.d.ts.map +0 -1
- package/dist/remote/relay/memory/group-server.js +0 -19
- package/dist/remote/relay/memory/group-server.js.map +0 -1
- package/dist/remote/relay/memory/index.d.ts +0 -11
- package/dist/remote/relay/memory/index.d.ts.map +0 -1
- package/dist/remote/relay/memory/index.js +0 -7
- package/dist/remote/relay/memory/index.js.map +0 -1
- package/examples/browser/README.md +0 -35
- package/examples/browser/index.html +0 -27
- package/examples/browser/src/exchange.ts +0 -69
- package/examples/browser/src/main.ts +0 -63
- package/examples/browser/src/style.css +0 -9
- package/examples/browser/src/worker.ts +0 -10
- package/examples/browser/vite.config.ts +0 -9
- package/remote/relay/memory/README.md +0 -72
- package/scripts/oe-groups.mjs +0 -166
package/docs/DEVIATIONS.md
CHANGED
|
@@ -85,7 +85,7 @@ model and what is out of scope.
|
|
|
85
85
|
| **Sesame** | Sesame rev. 2 | **Deviation** on session expiry (§4.2 applies only to unacknowledged sessions), on deleted devices (hard-removed rather than marked stale), and on device-list currency (the sender reads the relay's list at most once per 60 s instead of the server rejecting a stale send). **Extensions:** QR provisioning, device transfer, encrypted device names, identity-change gating, a 5-device cap | Product requirements the specification does not address | Hard deletion **drops the MAXLATENCY window, so in-flight messages from a just-removed device become permanently undecryptable**. A device linked or removed less than 60 s ago can miss a send or still receive one. Device transfer clones ratchet state, which weakens the forward-secrecy bound |
|
|
86
86
|
| **Sealed sender** | `libsignal` `sealed_sender.rs` | **Faithful** on the multi-recipient transport labels, KEM, AES-256-GCM-SIV, binary format, and `0x3FFF` registration-ID mask. **Extension:** sender and server certificates require signed Relay scope and issuer validity under operator-owned Ed25519 roots | Binds anonymous delivery to one Relay deployment and supports explicit issuer rotation and revocation | The transport follows `libsignal`; certificates are not interchangeable with Signal Messenger or another deployment |
|
|
87
87
|
| **Delivery token** | `libsignal` `profile_key.rs` | **Faithful.** `deriveAccessKey` follows `libsignal`'s `ProfileKey::derive_access_key`, and reproduces `libsignal`'s published known-answer values | — | Not an SDK invention, despite what the module name suggests |
|
|
88
|
-
| **Sender keys** | `libsignal` `sender_keys.rs` | **Deviation.** Protobuf
|
|
88
|
+
| **Sender keys** | `libsignal` `sender_keys.rs` | **Deviation.** Protobuf fields, chain seeds, and HKDF-Extract/Expand match. The SDK uses frame version `0x44`, Ed25519 signatures, and UTF-8 distribution identifiers. | The identity profile selects Ed25519. The frame version marks the correction of the former missing Extract. | Message-key derivation matches the reference. Former SDK state and messages require a reset. Frames still differ from Signal Messenger. |
|
|
89
89
|
| **Groups** | Signal Private Group System | **Independent design.** Real zkgroup primitives underneath; profile-key credential issuance blinds the ACI-bound profile-key attribute, the server validates every change against zero-knowledge presentations and signs the accepted result, and clients verify those signatures | Ships a validating group server with an enforcement contract (S1–S14) specified in-tree | Not wire-compatible with the Signal Private Group System; credentials are not interchangeable. The issuer sees the authenticated ACI and redemption window, but not the raw profile key |
|
|
90
90
|
| **zkgroup / zkcredential** | `libsignal` `zkgroup`, `zkcredential`, `poksho` | **Faithful** port of the Ristretto255 KVAC and Sigma-protocol system, verified against `libsignal`'s known-answer vectors. **Deviation:** server parameter derivation is structured as four labeled derivations rather than one seeded derivation | Server keys are the deploying operator's own trust root (each deployment generates its own seed), not Signal Messenger's | The zero-knowledge properties are real. Credentials are not interchangeable with Signal Messenger's |
|
|
91
91
|
| **Registration IDs** | `libsignal` `sealed_sender.rs` | **Faithful.** Generated in `[1, 16383]`, strictly inside the 14 bits the wire format reserves | — | — |
|
|
@@ -873,13 +873,16 @@ Signal Messenger trust root.
|
|
|
873
873
|
These parts match:
|
|
874
874
|
|
|
875
875
|
- protobuf field numbers and types, against [`wire.proto`][wp] exactly
|
|
876
|
-
- the `[version byte] ‖ protobuf ‖ [64-byte signature]` framing
|
|
877
|
-
`0x33`
|
|
876
|
+
- the `[version byte] ‖ protobuf ‖ [64-byte signature]` framing
|
|
878
877
|
- the `0x01`/`0x02` chain seeds and the `WhisperGroup` info string
|
|
879
878
|
- AES-256-CBC with the derived IV
|
|
880
879
|
- the capacity constants
|
|
881
880
|
|
|
882
|
-
|
|
881
|
+
The following details differ:
|
|
882
|
+
|
|
883
|
+
**The signed frame version is `0x44`**. The format break in §7.2 separates
|
|
884
|
+
corrected message-key derivation from the former SDK derivation. Libsignal uses
|
|
885
|
+
`0x33`.
|
|
883
886
|
|
|
884
887
|
**`distributionUuid` carries a UTF-8 string, not 16 UUID bytes**. The SDK writes
|
|
885
888
|
the 36-character textual form of a random UUIDv4
|
|
@@ -899,31 +902,27 @@ requires an opaque identifier.
|
|
|
899
902
|
**Signatures are Ed25519, not XEdDSA**, per §1.2. `libsignal` also serializes the
|
|
900
903
|
signing key as 33 bytes where the SDK uses 32.
|
|
901
904
|
|
|
902
|
-
### 7.2 Message-key derivation
|
|
903
|
-
|
|
904
|
-
This one is worth stating precisely because the field numbers and labels above
|
|
905
|
-
make the format look compatible.
|
|
905
|
+
### 7.2 Message-key derivation matches the reference
|
|
906
906
|
|
|
907
|
-
|
|
908
|
-
`Hkdf::<Sha256>::new(None, &seed).expand(b"WhisperGroup", 48)`
|
|
909
|
-
([`sender_keys.rs:36-38`][sk]). `Hkdf::new` runs HKDF-**Extract** first, as
|
|
910
|
-
`PRK = HMAC-SHA256(salt = zeros[32], seed)`. Only then does it expand.
|
|
907
|
+
Reviewed: 2026-10-02.
|
|
911
908
|
|
|
912
|
-
The SDK
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
909
|
+
The SDK derives Sender Keys message material with HKDF-SHA256 Extract and
|
|
910
|
+
Expand. Its input is `HMAC-SHA256(chain_key, 0x01)`, its salt is 32 zero bytes,
|
|
911
|
+
and its info string is `WhisperGroup`. The 48-byte output contains a 16-byte
|
|
912
|
+
IV followed by a 32-byte cipher key. This matches
|
|
913
|
+
[`SenderMessageKey::new` in libsignal][sk].
|
|
916
914
|
|
|
917
|
-
The
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
915
|
+
The former implementation omitted Extract. The correction changes derived keys
|
|
916
|
+
and requires a format break. State and encrypted distribution messages now
|
|
917
|
+
require `senderKeyVersion: 'v2'`. Signed group frames require byte `0x44`.
|
|
918
|
+
The SDK rejects old state, unversioned distributions, and old frames.
|
|
919
|
+
Applications must reset group sender-key state and discard queued group sends
|
|
920
|
+
before they redistribute keys with upgraded peers.
|
|
922
921
|
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
922
|
+
For a chain key of 32 repeated `0x42` bytes, the current IV is
|
|
923
|
+
`890d51ea73e564722351dc0d5a09142c`. The former IV was
|
|
924
|
+
`2a56b9eb80b3c1ffebd97221b2175960`. An independent Node/OpenSSL oracle checks
|
|
925
|
+
ciphertext against the current derivation.
|
|
927
926
|
|
|
928
927
|
### 7.3 Groups are an independent design
|
|
929
928
|
|
package/docs/GETTING_STARTED.md
CHANGED
|
@@ -2,8 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
> Navigation: [README](../README.md) | [ARCHITECTURE](../ARCHITECTURE.md) | **Getting Started**
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
5
|
+
Use the OpenE2EE Signal Protocol SDK with the OpenE2EE Signal Protocol Relay
|
|
6
|
+
for authenticated delivery. The SDK owns device-local encryption and protocol
|
|
7
|
+
state. The Relay holds public key material, encrypted envelopes, and routing
|
|
8
|
+
metadata. The relay never needs message plaintext or device private keys.
|
|
7
9
|
|
|
8
10
|
## Install
|
|
9
11
|
|
|
@@ -11,336 +13,77 @@ not want to learn protocol internals before sending a message.
|
|
|
11
13
|
npm install @open-e2ee/signal-protocol-sdk
|
|
12
14
|
```
|
|
13
15
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
Expo packages.
|
|
16
|
+
Install the runtime dependencies that your device-local store requires.
|
|
17
|
+
The [adapter guide](../ADAPTERS.md) lists the supported stores.
|
|
17
18
|
|
|
18
19
|
## What You Need
|
|
19
20
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
21
|
+
- A Relay project and its environment connection URL. In the application
|
|
22
|
+
directory, `oe new` creates the project and its Sandbox environment, and it
|
|
23
|
+
writes the connection URL to `.env.local` as `OPEN_E2EE_RELAY_URL`. In a
|
|
24
|
+
Next.js, Expo, or Vite application, the name has the public prefix of the
|
|
25
|
+
framework, for example `EXPO_PUBLIC_OPEN_E2EE_RELAY_URL`.
|
|
26
|
+
- A `getIdentityAssertion` callback that returns a short-lived signed assertion.
|
|
27
|
+
- Device-local storage for private keys, sessions, and delivery state.
|
|
28
|
+
- Application storage for decrypted messages and attachment bytes.
|
|
29
|
+
|
|
30
|
+
A Sandbox environment uses device-owned identity. `hostedRelaySandboxIdentity`
|
|
31
|
+
creates its `getIdentityAssertion` callback. The callback signs each assertion
|
|
32
|
+
with a key that it keeps in the device-local store, so the device gets the same
|
|
33
|
+
account each time it registers. A device that loses its store loses that
|
|
34
|
+
Sandbox account. The helper works only in a Sandbox environment.
|
|
35
|
+
|
|
36
|
+
In production, the callback belongs to your authentication integration. It
|
|
37
|
+
returns a short-lived assertion for the signed-in user from your identity
|
|
38
|
+
provider. The SDK does not supply an identity provider or a relay server
|
|
39
|
+
implementation.
|
|
38
40
|
|
|
39
41
|
## Setup Sequence
|
|
40
42
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
4.
|
|
47
|
-
5.
|
|
48
|
-
6. Register receive hooks and start relay subscription delivery.
|
|
49
|
-
|
|
50
|
-
## Mental Model
|
|
51
|
-
|
|
52
|
-
```mermaid
|
|
53
|
-
flowchart LR
|
|
54
|
-
subgraph ThisDevice["This device"]
|
|
55
|
-
App["Your app"]
|
|
56
|
-
Client["Signal Protocol client"]
|
|
57
|
-
ProtocolStorage["Protocol storage"]
|
|
58
|
-
MessageState["App message state"]
|
|
59
|
-
LocalFiles["Local files/cache"]
|
|
60
|
-
App --> Client
|
|
61
|
-
Client <--> ProtocolStorage
|
|
62
|
-
App <--> MessageState
|
|
63
|
-
App <--> LocalFiles
|
|
64
|
-
end
|
|
65
|
-
|
|
66
|
-
Relay["Relay server"]
|
|
67
|
-
ObjectStorage["Remote object storage"]
|
|
68
|
-
|
|
69
|
-
subgraph RecipientPhone["Recipient phone"]
|
|
70
|
-
PhoneClient["Signal Protocol client"]
|
|
71
|
-
PhoneStorage["Device storage"]
|
|
72
|
-
PhoneClient <--> PhoneStorage
|
|
73
|
-
end
|
|
74
|
-
|
|
75
|
-
subgraph RecipientLaptop["Recipient laptop"]
|
|
76
|
-
LaptopClient["Signal Protocol client"]
|
|
77
|
-
LaptopStorage["Device storage"]
|
|
78
|
-
LaptopClient <--> LaptopStorage
|
|
79
|
-
end
|
|
80
|
-
|
|
81
|
-
subgraph LinkedDevice["Your linked device"]
|
|
82
|
-
LinkedClient["Signal Protocol client"]
|
|
83
|
-
LinkedStorage["Device storage"]
|
|
84
|
-
LinkedClient <--> LinkedStorage
|
|
85
|
-
end
|
|
86
|
-
|
|
87
|
-
Client <--> Relay
|
|
88
|
-
Client --> ObjectStorage
|
|
89
|
-
Relay <--> PhoneClient
|
|
90
|
-
Relay <--> LaptopClient
|
|
91
|
-
Relay <--> LinkedClient
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
- Each device owns its own app runtime, Signal Protocol client, protocol storage, message
|
|
95
|
-
state, and local file/cache storage.
|
|
96
|
-
- The current `adapters.storage` API maps to the protocol facet of the target
|
|
97
|
-
`deviceStorage` model.
|
|
98
|
-
- Your app owns decrypted message rows and local files after the Signal Protocol client
|
|
99
|
-
decrypts or stages them.
|
|
100
|
-
- The relay connects devices, stores public keys, and carries encrypted
|
|
101
|
-
envelopes.
|
|
102
|
-
- The remote object store carries encrypted attachment/media bytes only.
|
|
103
|
-
|
|
104
|
-
You can operate these server-side interfaces through a shipped or custom
|
|
105
|
-
adapter. You can instead use [OpenE2EE Signal Protocol 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
|
-
|
|
111
|
-
## Target Message-First API Preview
|
|
112
|
-
|
|
113
|
-
This is the target DX the package moves toward. It appears here so app
|
|
114
|
-
developers can understand the intended mental model. The current stable API
|
|
115
|
-
still uses `storage`, `remoteObjectStore`, hooks, and transition-only media helpers.
|
|
116
|
-
|
|
117
|
-
<!-- doc-snippet:planned target-message-api unshipped="@open-e2ee/signal-protocol-sdk/device/storage/memory" -->
|
|
118
|
-
```ts
|
|
119
|
-
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
120
|
-
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
121
|
-
import { createInMemoryDeviceStorage } from "@open-e2ee/signal-protocol-sdk/device/storage/memory";
|
|
122
|
-
import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
|
|
123
|
-
|
|
124
|
-
const relay = inMemoryRelay();
|
|
125
|
-
|
|
126
|
-
const alice = await createSignalProtocolClient({
|
|
127
|
-
identity: { userId: "alice", deviceId: 1 },
|
|
128
|
-
adapters: {
|
|
129
|
-
deviceStorage: createInMemoryDeviceStorage(),
|
|
130
|
-
relay,
|
|
131
|
-
},
|
|
132
|
-
});
|
|
133
|
-
|
|
134
|
-
const bob = await createSignalProtocolClient({
|
|
135
|
-
identity: { userId: "bob", deviceId: 1 },
|
|
136
|
-
adapters: {
|
|
137
|
-
deviceStorage: createInMemoryDeviceStorage(),
|
|
138
|
-
relay,
|
|
139
|
-
},
|
|
140
|
-
});
|
|
43
|
+
1. Run `oe new` to create the Relay project and its Sandbox environment.
|
|
44
|
+
2. Open the device-local store for the device.
|
|
45
|
+
3. Create the client with `createHostedSignalProtocolClient()`. In a Sandbox
|
|
46
|
+
environment, pass `hostedRelaySandboxIdentity(storage)` as
|
|
47
|
+
`hosted.getIdentityAssertion`.
|
|
48
|
+
4. Register a receive handler that persists decrypted messages.
|
|
49
|
+
5. Start the relay subscription.
|
|
141
50
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
console.log("bob decrypted:", message.text);
|
|
147
|
-
resolve();
|
|
148
|
-
},
|
|
149
|
-
);
|
|
150
|
-
});
|
|
51
|
+
The hosted factory authenticates and registers the current device, then publishes
|
|
52
|
+
its public prekeys. Linked devices use the provisioning flow in the
|
|
53
|
+
[device guide](../device/README.md). The default policy requires post-quantum
|
|
54
|
+
session establishment and Braid ratcheting.
|
|
151
55
|
|
|
152
|
-
|
|
153
|
-
console.log("alice plaintext input:", plaintext);
|
|
154
|
-
|
|
155
|
-
const sent = await alice.messages.send({
|
|
156
|
-
conversationId: "dm:alice_bob",
|
|
157
|
-
to: "bob",
|
|
158
|
-
text: plaintext,
|
|
159
|
-
});
|
|
160
|
-
|
|
161
|
-
console.log("relay-visible encrypted envelope:", {
|
|
162
|
-
envelopeId: sent.envelopeId,
|
|
163
|
-
ciphertextLength: sent.ciphertextLength,
|
|
164
|
-
});
|
|
165
|
-
|
|
166
|
-
await delivered;
|
|
167
|
-
```
|
|
168
|
-
|
|
169
|
-
The production shape uses the same message API with platform adapters:
|
|
170
|
-
|
|
171
|
-
<!-- doc-snippet:planned target-message-api-platform-adapters unshipped="@open-e2ee/signal-protocol-sdk/device/storage/expo" -->
|
|
172
|
-
```ts
|
|
173
|
-
import { createHostedSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
174
|
-
import { createExpoDeviceStorage } from "@open-e2ee/signal-protocol-sdk/device/storage/expo";
|
|
175
|
-
|
|
176
|
-
const signal = await createHostedSignalProtocolClient({
|
|
177
|
-
adapters: {
|
|
178
|
-
deviceStorage: createExpoDeviceStorage({ database, files }),
|
|
179
|
-
},
|
|
180
|
-
hosted: {
|
|
181
|
-
relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
|
|
182
|
-
getIdentityAssertion,
|
|
183
|
-
},
|
|
184
|
-
});
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
Attachments use the same message API. On Expo, pass the picker URI. The Signal
|
|
188
|
-
Protocol client copies or persists the bytes through `deviceStorage.files`
|
|
189
|
-
before upload, so retry can continue after restart:
|
|
56
|
+
## Expo Client
|
|
190
57
|
|
|
191
58
|
<!-- doc-snippet:skip requires-external-context -->
|
|
192
59
|
```ts
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
attachments: [
|
|
198
|
-
{
|
|
199
|
-
source: pickedPhoto.uri,
|
|
200
|
-
contentType: pickedPhoto.contentType,
|
|
201
|
-
fileName: pickedPhoto.fileName,
|
|
202
|
-
size: pickedPhoto.fileSize,
|
|
203
|
-
},
|
|
204
|
-
],
|
|
205
|
-
});
|
|
206
|
-
```
|
|
207
|
-
|
|
208
|
-
On the web, pass the browser file object:
|
|
209
|
-
|
|
210
|
-
<!-- doc-snippet:skip requires-external-context -->
|
|
211
|
-
```ts
|
|
212
|
-
await signal.messages.send({
|
|
213
|
-
conversationId,
|
|
214
|
-
to: "bob",
|
|
215
|
-
text: "photo from the browser",
|
|
216
|
-
attachments: [
|
|
217
|
-
{
|
|
218
|
-
source: file,
|
|
219
|
-
contentType: file.type,
|
|
220
|
-
fileName: file.name,
|
|
221
|
-
size: file.size,
|
|
222
|
-
},
|
|
223
|
-
],
|
|
224
|
-
});
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
Once this API lands, this guide should teach the target path first and move the
|
|
228
|
-
current `signal.media.*` examples into lower-level transition or migration docs.
|
|
229
|
-
|
|
230
|
-
## Current Stable Local Clients
|
|
231
|
-
|
|
232
|
-
Use the in-memory adapters for local examples and development. The demo sends
|
|
233
|
-
while Bob is offline, inspects the relay-visible ciphertext, and then starts
|
|
234
|
-
Bob's subscription to show the decrypted plaintext entering the app.
|
|
235
|
-
|
|
236
|
-
<!-- doc-snippet:run getting-started-stable-local-clients expect="bob decrypted: alice: hello" -->
|
|
237
|
-
```ts
|
|
238
|
-
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
239
|
-
import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
240
|
-
import { inMemoryStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
|
|
241
|
-
import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
|
|
242
|
-
|
|
243
|
-
const relay = inMemoryRelay();
|
|
244
|
-
|
|
245
|
-
// The relay knows which devices exist, but it does not get plaintext.
|
|
246
|
-
await relay.registerDevice("alice", {
|
|
247
|
-
encryptedDeviceName: new ArrayBuffer(0),
|
|
248
|
-
});
|
|
249
|
-
await relay.registerDevice("bob", { encryptedDeviceName: new ArrayBuffer(0) });
|
|
250
|
-
|
|
251
|
-
// Each client represents one device. Its protocol storage is local to that device.
|
|
252
|
-
const alice = await createSignalProtocolClient({
|
|
253
|
-
identity: { userId: "alice" },
|
|
254
|
-
adapters: { storage: inMemoryStore(), relay },
|
|
255
|
-
});
|
|
256
|
-
|
|
257
|
-
const bob = await createSignalProtocolClient({
|
|
258
|
-
identity: { userId: "bob" },
|
|
259
|
-
adapters: { storage: inMemoryStore(), relay },
|
|
260
|
-
});
|
|
261
|
-
|
|
262
|
-
await alice.syncToServer();
|
|
263
|
-
await bob.syncToServer();
|
|
264
|
-
|
|
265
|
-
// Send while Bob is offline so we can inspect what the relay stores.
|
|
266
|
-
const sent = await alice.send("bob", "hello");
|
|
267
|
-
console.log("alice sent:", sent.messageId);
|
|
268
|
-
|
|
269
|
-
// The relay-visible envelope contains metadata plus ciphertext, not plaintext.
|
|
270
|
-
const [queuedEnvelope] = relay.getPendingMessages("bob", 1);
|
|
271
|
-
const ciphertextLength =
|
|
272
|
-
typeof queuedEnvelope.ciphertext === "string"
|
|
273
|
-
? queuedEnvelope.ciphertext.length
|
|
274
|
-
: queuedEnvelope.ciphertext.byteLength;
|
|
275
|
-
const ciphertextPreview =
|
|
276
|
-
typeof queuedEnvelope.ciphertext === "string"
|
|
277
|
-
? `${queuedEnvelope.ciphertext.slice(0, 32)}...`
|
|
278
|
-
: `${queuedEnvelope.ciphertext.byteLength} encrypted bytes`;
|
|
279
|
-
|
|
280
|
-
console.log("relay sees encrypted envelope:", {
|
|
281
|
-
messageType: queuedEnvelope.messageType,
|
|
282
|
-
ciphertextLength,
|
|
283
|
-
ciphertextPreview,
|
|
284
|
-
});
|
|
285
|
-
|
|
286
|
-
const decrypted = new Promise<void>((resolve) => {
|
|
287
|
-
// Plaintext enters your app only after Bob's Signal Protocol client decrypts it.
|
|
288
|
-
bob.registerHook("onMessageDecrypted", async (message) => {
|
|
289
|
-
console.log("bob decrypted:", `${message.senderId}: ${message.content}`);
|
|
290
|
-
resolve();
|
|
291
|
-
});
|
|
292
|
-
});
|
|
293
|
-
|
|
294
|
-
// Starting the subscription delivers Bob's queued encrypted envelope.
|
|
295
|
-
bob.startRelaySubscription();
|
|
296
|
-
await decrypted;
|
|
297
|
-
```
|
|
298
|
-
|
|
299
|
-
Example output:
|
|
300
|
-
|
|
301
|
-
```text
|
|
302
|
-
alice sent: msg-1
|
|
303
|
-
relay sees encrypted envelope: {
|
|
304
|
-
messageType: 'prekey_bundle',
|
|
305
|
-
ciphertextLength: 3464,
|
|
306
|
-
ciphertextPreview: '<base64 ciphertext preview>...'
|
|
307
|
-
}
|
|
308
|
-
bob decrypted: alice: hello
|
|
309
|
-
```
|
|
310
|
-
|
|
311
|
-
The in-memory relay lets the example inspect what a server can see. The relay sees
|
|
312
|
-
metadata plus encrypted envelope bytes. It does not receive Bob's decrypted
|
|
313
|
-
message content. The first message often uses `prekey_bundle` to establish a
|
|
314
|
-
session, and later messages use `ciphertext`.
|
|
315
|
-
|
|
316
|
-
## Production Client
|
|
317
|
-
|
|
318
|
-
Use the protocol storage adapter for your runtime and connect to the OpenE2EE
|
|
319
|
-
Signal Protocol Relay. For an Expo app, that is Expo local storage and the
|
|
320
|
-
hosted client:
|
|
321
|
-
|
|
322
|
-
<!-- doc-snippet:skip requires-external-context -->
|
|
323
|
-
```ts
|
|
324
|
-
import { createHostedSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
60
|
+
import {
|
|
61
|
+
createHostedSignalProtocolClient,
|
|
62
|
+
hostedRelaySandboxIdentity,
|
|
63
|
+
} from "@open-e2ee/signal-protocol-sdk";
|
|
325
64
|
import { expoStore } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
|
|
326
65
|
|
|
66
|
+
const storage = await expoStore();
|
|
327
67
|
const signal = await createHostedSignalProtocolClient({
|
|
328
|
-
adapters: {
|
|
329
|
-
// Expo storage owns this device's private keys and session state.
|
|
330
|
-
storage: await expoStore(),
|
|
331
|
-
},
|
|
68
|
+
adapters: { storage },
|
|
332
69
|
hosted: {
|
|
333
|
-
// The environment-scoped connection URL from the OpenE2EE console.
|
|
334
70
|
relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
|
|
335
|
-
//
|
|
336
|
-
getIdentityAssertion,
|
|
71
|
+
// Sandbox only. In production, use your identity provider's callback.
|
|
72
|
+
getIdentityAssertion: hostedRelaySandboxIdentity(storage),
|
|
337
73
|
},
|
|
338
74
|
});
|
|
339
75
|
```
|
|
340
76
|
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
77
|
+
Complete the [Expo database setup](../local/store/expo/README.md) before creating
|
|
78
|
+
the client. Use a Sandbox connection URL during development. Keep each
|
|
79
|
+
account's device-local state separate.
|
|
80
|
+
|
|
81
|
+
## Custom Transport
|
|
82
|
+
|
|
83
|
+
Advanced integrations can use `createSignalProtocolClient()` with an
|
|
84
|
+
application-owned `SignalProtocolRelayServer` client transport. That transport
|
|
85
|
+
connects to an authenticated backend. The [interface guide](./INTERFACES.md)
|
|
86
|
+
defines the contract. The published SDK contains no relay server implementation.
|
|
344
87
|
|
|
345
88
|
## Receive Messages
|
|
346
89
|
|
|
@@ -392,21 +135,17 @@ await signal.send("bob", {
|
|
|
392
135
|
Add a remote object store when your app sends encrypted attachments. The
|
|
393
136
|
`remoteObjectStore` adapter brokers encrypted byte objects rather than
|
|
394
137
|
plaintext files.
|
|
395
|
-
The final public DX should not expose both `signal.media.*` and message
|
|
396
|
-
attachment helpers. The planned replacement is message-scoped attachment
|
|
397
|
-
handling.
|
|
398
138
|
|
|
399
139
|
<!-- doc-snippet:skip requires-external-context -->
|
|
400
140
|
```ts
|
|
401
|
-
import { media } from "@open-e2ee/signal-protocol-sdk";
|
|
141
|
+
import { createHostedSignalProtocolClient, media } from "@open-e2ee/signal-protocol-sdk";
|
|
402
142
|
import { convexR2ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2";
|
|
403
143
|
import { api } from "../convex/_generated/api";
|
|
404
144
|
|
|
405
|
-
const signal = await
|
|
406
|
-
|
|
145
|
+
const signal = await createHostedSignalProtocolClient({
|
|
146
|
+
hosted: { relayUrl, getIdentityAssertion },
|
|
407
147
|
adapters: {
|
|
408
148
|
storage,
|
|
409
|
-
relay,
|
|
410
149
|
remoteObjectStore: convexR2ObjectStore({
|
|
411
150
|
convex,
|
|
412
151
|
api: api.signalObjectStore,
|
|
@@ -528,8 +267,7 @@ through a partial-byte store. Native background download code should implement t
|
|
|
528
267
|
|
|
529
268
|
For background-safe uploads, use the durable client operation. The current API
|
|
530
269
|
persists bounded recovery metadata through the existing Signal Protocol storage
|
|
531
|
-
adapter. The
|
|
532
|
-
`deviceStorage.messages`. The operation tries the upload when it is due and
|
|
270
|
+
adapter. The operation tries the upload when it is due and
|
|
533
271
|
returns either a completed pointer or a pending job id for later recovery:
|
|
534
272
|
|
|
535
273
|
<!-- doc-snippet:skip requires-external-context -->
|
|
@@ -722,6 +460,6 @@ Leave it unset unless your product has a specific compatibility decision. See
|
|
|
722
460
|
|
|
723
461
|
- [Client Composition](./CLIENT_COMPOSITION.md): app setup and adapter shape.
|
|
724
462
|
- [Protocol Policy](./PROTOCOL_POLICY.md): security policy choices.
|
|
725
|
-
- [Adapters](../ADAPTERS.md):
|
|
726
|
-
stores
|
|
463
|
+
- [Adapters](../ADAPTERS.md): device-local storage, client transports, and remote
|
|
464
|
+
object stores.
|
|
727
465
|
- [API Reference](./api/README.md): generated TypeScript API docs.
|
package/docs/INTERFACES.md
CHANGED
|
@@ -88,14 +88,15 @@ delivery, provisioning, key rotation, and encrypted group coordination.
|
|
|
88
88
|
<!-- doc-snippet:skip requires-external-context -->
|
|
89
89
|
```ts
|
|
90
90
|
import type { SignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/relay";
|
|
91
|
-
import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
|
|
92
91
|
|
|
93
|
-
//
|
|
94
|
-
|
|
95
|
-
// application backend that implements this interface.
|
|
96
|
-
const relay: SignalProtocolRelayServer = inMemoryRelay();
|
|
92
|
+
// An application-owned client transport to an authenticated backend.
|
|
93
|
+
const relay: SignalProtocolRelayServer = appRelayTransport;
|
|
97
94
|
```
|
|
98
95
|
|
|
96
|
+
The hosted factory configures the OpenE2EE Signal Protocol Relay transport.
|
|
97
|
+
Custom transports remain an advanced integration point. The published package
|
|
98
|
+
contains the client contract, without a relay server implementation.
|
|
99
|
+
|
|
99
100
|
The application backend must:
|
|
100
101
|
|
|
101
102
|
- authenticate every caller
|
|
@@ -202,8 +203,7 @@ update, unless the specific API says so.
|
|
|
202
203
|
- Implement the public interface when infrastructure requirements differ.
|
|
203
204
|
- Import provider and platform adapters from explicit package subpaths so
|
|
204
205
|
unrelated dependencies stay out of client bundles.
|
|
205
|
-
- Keep authentication and product authorization in the application backend
|
|
206
|
-
even when an SDK helper supplies generic broker mechanics.
|
|
206
|
+
- Keep authentication and product authorization in the application backend.
|
|
207
207
|
|
|
208
208
|
See [client composition](./CLIENT_COMPOSITION.md) for the complete client
|
|
209
209
|
configuration shape and [documentation standards](./DOCUMENTATION_STANDARDS.md)
|
package/docs/PACKAGE_SURFACE.md
CHANGED
|
@@ -11,7 +11,8 @@ It also defines the vocabulary the rest of the documentation assumes.
|
|
|
11
11
|
|
|
12
12
|
## Core model
|
|
13
13
|
|
|
14
|
-
- `
|
|
14
|
+
- `createHostedSignalProtocolClient()` connects to the OpenE2EE Signal Protocol Relay.
|
|
15
|
+
- `createSignalProtocolClient()` composes an application-owned client transport.
|
|
15
16
|
- `DefaultSignalProtocolClient` is the class the factory returns. `SignalProtocolClient` is its interface.
|
|
16
17
|
- Every client requires `storage`, which owns local encryption state for one
|
|
17
18
|
user/device.
|
|
@@ -33,12 +34,12 @@ package. They do not imply that one client spans multiple protocols.
|
|
|
33
34
|
|
|
34
35
|
For a production app, the normal startup shape is:
|
|
35
36
|
|
|
36
|
-
1.
|
|
37
|
-
2.
|
|
38
|
-
3.
|
|
39
|
-
4.
|
|
40
|
-
|
|
41
|
-
|
|
37
|
+
1. Configure a Relay project and identity provider in the OpenE2EE console.
|
|
38
|
+
2. Open device-local storage for the signed-in user.
|
|
39
|
+
3. Create the client with `createHostedSignalProtocolClient()`.
|
|
40
|
+
4. Register receive hooks and start relay subscription delivery.
|
|
41
|
+
|
|
42
|
+
The hosted factory registers the device and publishes its public prekeys.
|
|
42
43
|
|
|
43
44
|
## Root package
|
|
44
45
|
|
|
@@ -48,6 +49,7 @@ Use the root package for core portable APIs:
|
|
|
48
49
|
```ts
|
|
49
50
|
import {
|
|
50
51
|
SignalProtocolClient,
|
|
52
|
+
createHostedSignalProtocolClient,
|
|
51
53
|
createSignalProtocolClient,
|
|
52
54
|
ProtocolAddress,
|
|
53
55
|
BraidPolicy,
|
|
@@ -61,14 +63,16 @@ import {
|
|
|
61
63
|
The root package intentionally does not re-export platform-bound adapters like
|
|
62
64
|
Expo storage or the Convex R2 object store.
|
|
63
65
|
|
|
66
|
+
The published package contains client APIs and transport contracts. Relay
|
|
67
|
+
servers, group authorization engines, credential issuers, and server signing
|
|
68
|
+
implementations are outside the published SDK.
|
|
69
|
+
|
|
64
70
|
## Integration subpaths
|
|
65
71
|
|
|
66
72
|
- `@open-e2ee/signal-protocol-sdk/remote/relay`
|
|
67
|
-
- `@open-e2ee/signal-protocol-sdk/remote/relay/memory`
|
|
68
73
|
- `@open-e2ee/signal-protocol-sdk/remote/relay/types`
|
|
69
74
|
- `@open-e2ee/signal-protocol-sdk/remote/object-store`
|
|
70
75
|
- `@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2`
|
|
71
|
-
- `@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2/server`
|
|
72
76
|
- `@open-e2ee/signal-protocol-sdk/remote/object-store/s3`
|
|
73
77
|
- `@open-e2ee/signal-protocol-sdk/client`
|
|
74
78
|
- `@open-e2ee/signal-protocol-sdk/client/config`
|
|
@@ -88,7 +92,6 @@ Expo storage or the Convex R2 object store.
|
|
|
88
92
|
- `@open-e2ee/signal-protocol-sdk/encoding/hex`
|
|
89
93
|
- `@open-e2ee/signal-protocol-sdk/files`
|
|
90
94
|
- `@open-e2ee/signal-protocol-sdk/groups`
|
|
91
|
-
- `@open-e2ee/signal-protocol-sdk/groups/server`
|
|
92
95
|
- `@open-e2ee/signal-protocol-sdk/hooks`
|
|
93
96
|
- `@open-e2ee/signal-protocol-sdk/keys`
|
|
94
97
|
- `@open-e2ee/signal-protocol-sdk/keys/generation`
|
|
@@ -125,7 +128,6 @@ Expo storage or the Convex R2 object store.
|
|
|
125
128
|
|
|
126
129
|
### Development adapters
|
|
127
130
|
|
|
128
|
-
- `@open-e2ee/signal-protocol-sdk/remote/relay/memory`
|
|
129
131
|
- `@open-e2ee/signal-protocol-sdk/local/store/memory`
|
|
130
132
|
|
|
131
133
|
`internal/**` is implementation-only and not part of the supported external API.
|
|
@@ -149,7 +151,6 @@ Expo storage or the Convex R2 object store.
|
|
|
149
151
|
|
|
150
152
|
- `createHostedSignalProtocolClient()` from the package root for the OpenE2EE
|
|
151
153
|
Signal Protocol Relay
|
|
152
|
-
- `InMemorySignalProtocolRelayServer` / `inMemoryRelay()` for local development
|
|
153
154
|
- custom implementations via `SignalProtocolRelayServer`
|
|
154
155
|
|
|
155
156
|
### Storage implementations
|
|
@@ -188,9 +189,6 @@ Expo storage or the Convex R2 object store.
|
|
|
188
189
|
- `ConvexR2ObjectStore` via
|
|
189
190
|
`@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2`
|
|
190
191
|
- `convexR2ObjectStore()` for Cloudflare R2 composition
|
|
191
|
-
- `defineConvexR2ObjectStore()` via the server-only
|
|
192
|
-
`@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2/server` entry
|
|
193
|
-
point
|
|
194
192
|
- `S3ObjectStore` via `@open-e2ee/signal-protocol-sdk/remote/object-store/s3`
|
|
195
193
|
- `s3ObjectStore()` for brokered Amazon S3 or S3-compatible storage
|
|
196
194
|
- custom implementations via `SignalProtocolRemoteObjectStore`
|
|
@@ -199,7 +197,7 @@ Expo storage or the Convex R2 object store.
|
|
|
199
197
|
functions that wrap `@convex-dev/r2`. It is not the Convex component itself.
|
|
200
198
|
The application continues to own component installation, mounting,
|
|
201
199
|
configuration, authentication, authorization, persistence, credentials, and
|
|
202
|
-
the R2 bucket
|
|
200
|
+
the R2 bucket and broker implementation.
|
|
203
201
|
Both concrete adapters keep provider credentials in the application backend.
|
|
204
202
|
|
|
205
203
|
The remote object store is a normal integration point for encrypted
|