@open-e2ee/signal-protocol-sdk 14.1.0 → 14.2.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 +5 -5
- package/ARCHITECTURE.md +1 -1
- package/CHANGELOG.md +415 -0
- package/README.md +19 -14
- package/SECURITY.md +2 -2
- package/TROUBLESHOOTING.md +1 -1
- package/client/README.md +32 -21
- package/device/README.md +5 -5
- package/dist/client/client.d.ts +44 -34
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +221 -146
- package/dist/client/client.js.map +1 -1
- package/dist/client/compose.d.ts +7 -5
- package/dist/client/compose.d.ts.map +1 -1
- package/dist/client/compose.js +7 -2
- package/dist/client/compose.js.map +1 -1
- package/dist/client/config.d.ts +23 -14
- package/dist/client/config.d.ts.map +1 -1
- package/dist/client/config.js.map +1 -1
- package/dist/client/content-adapter.d.ts +9 -0
- package/dist/client/content-adapter.d.ts.map +1 -1
- package/dist/client/content-adapter.js +6 -0
- package/dist/client/content-adapter.js.map +1 -1
- package/dist/client/delivery-status.d.ts +2 -2
- package/dist/client/delivery-status.d.ts.map +1 -1
- package/dist/client/delivery-status.js +10 -4
- package/dist/client/delivery-status.js.map +1 -1
- package/dist/client/device-set-reconciliation.d.ts +24 -16
- package/dist/client/device-set-reconciliation.d.ts.map +1 -1
- package/dist/client/device-set-reconciliation.js +17 -14
- package/dist/client/device-set-reconciliation.js.map +1 -1
- package/dist/client/event-hooks.d.ts +22 -7
- package/dist/client/event-hooks.d.ts.map +1 -1
- package/dist/client/event-hooks.js +35 -5
- package/dist/client/event-hooks.js.map +1 -1
- package/dist/client/group-device-set.d.ts +1 -1
- package/dist/client/group-device-set.d.ts.map +1 -1
- package/dist/client/group-key-sync.js +1 -1
- package/dist/client/group-key-sync.js.map +1 -1
- package/dist/client/group-outbox.d.ts +7 -7
- package/dist/client/group-outbox.d.ts.map +1 -1
- package/dist/client/group-outbox.js +24 -24
- package/dist/client/group-outbox.js.map +1 -1
- package/dist/client/group-sealed-sender.d.ts +1 -1
- package/dist/client/group-sealed-sender.d.ts.map +1 -1
- package/dist/client/group-sender-key-operations.js +1 -1
- package/dist/client/group-sender-key-operations.js.map +1 -1
- package/dist/client/headless.d.ts +6 -6
- package/dist/client/headless.d.ts.map +1 -1
- package/dist/client/headless.js +7 -7
- package/dist/client/headless.js.map +1 -1
- package/dist/client/hosted-anonymous-delivery.d.ts +6 -6
- package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
- package/dist/client/hosted-anonymous-delivery.js +17 -17
- package/dist/client/hosted-anonymous-delivery.js.map +1 -1
- package/dist/client/hosted-assertion-id.d.ts +1 -1
- package/dist/client/hosted-assertion-id.d.ts.map +1 -1
- package/dist/client/hosted-assertion-id.js +1 -1
- package/dist/client/hosted-assertion-id.js.map +1 -1
- package/dist/client/hosted-connection.d.ts +5 -5
- package/dist/client/hosted-connection.d.ts.map +1 -1
- package/dist/client/hosted-connection.js +32 -32
- package/dist/client/hosted-connection.js.map +1 -1
- package/dist/client/hosted-device-link-transport.d.ts +2 -2
- package/dist/client/hosted-device-link-transport.d.ts.map +1 -1
- package/dist/client/hosted-device-link-transport.js +1 -1
- package/dist/client/hosted-device-link-transport.js.map +1 -1
- package/dist/client/hosted-device-link.d.ts +5 -1
- package/dist/client/hosted-device-link.d.ts.map +1 -1
- package/dist/client/hosted-device-link.js +7 -4
- package/dist/client/hosted-device-link.js.map +1 -1
- package/dist/client/hosted-device-standing.d.ts +13 -5
- package/dist/client/hosted-device-standing.d.ts.map +1 -1
- package/dist/client/hosted-device-standing.js +11 -6
- package/dist/client/hosted-device-standing.js.map +1 -1
- package/dist/client/hosted-group-authority.d.ts +2 -2
- package/dist/client/hosted-group-authority.d.ts.map +1 -1
- package/dist/client/hosted-group-authority.js +8 -8
- package/dist/client/hosted-group-authority.js.map +1 -1
- package/dist/client/hosted-groups.d.ts +4 -4
- package/dist/client/hosted-groups.d.ts.map +1 -1
- package/dist/client/hosted-groups.js +8 -8
- package/dist/client/hosted-groups.js.map +1 -1
- package/dist/client/hosted-http-error.d.ts +8 -4
- package/dist/client/hosted-http-error.d.ts.map +1 -1
- package/dist/client/hosted-http-error.js +7 -4
- package/dist/client/hosted-http-error.js.map +1 -1
- package/dist/client/hosted-mailbox-subscription.d.ts +10 -10
- package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
- package/dist/client/hosted-mailbox-subscription.js +17 -17
- package/dist/client/hosted-mailbox-subscription.js.map +1 -1
- package/dist/client/hosted-prekey-publication.d.ts +9 -9
- package/dist/client/hosted-prekey-publication.d.ts.map +1 -1
- package/dist/client/hosted-prekey-publication.js.map +1 -1
- package/dist/client/hosted-presence-frames.d.ts +62 -38
- package/dist/client/hosted-presence-frames.d.ts.map +1 -1
- package/dist/client/hosted-presence-frames.js +4 -2
- package/dist/client/hosted-presence-frames.js.map +1 -1
- package/dist/client/hosted-presence.d.ts +22 -14
- package/dist/client/hosted-presence.d.ts.map +1 -1
- package/dist/client/hosted-presence.js +26 -17
- package/dist/client/hosted-presence.js.map +1 -1
- package/dist/client/hosted-profile-keys.d.ts +3 -1
- package/dist/client/hosted-profile-keys.d.ts.map +1 -1
- package/dist/client/hosted-profile-keys.js +19 -15
- package/dist/client/hosted-profile-keys.js.map +1 -1
- package/dist/client/hosted-push.d.ts +38 -16
- package/dist/client/hosted-push.d.ts.map +1 -1
- package/dist/client/hosted-push.js +11 -5
- package/dist/client/hosted-push.js.map +1 -1
- package/dist/client/hosted-resume-error.d.ts +21 -9
- package/dist/client/hosted-resume-error.d.ts.map +1 -1
- package/dist/client/hosted-resume-error.js +4 -1
- package/dist/client/hosted-resume-error.js.map +1 -1
- package/dist/client/hosted-resume.d.ts +3 -3
- package/dist/client/hosted-resume.d.ts.map +1 -1
- package/dist/client/hosted-resume.js +12 -12
- package/dist/client/hosted-resume.js.map +1 -1
- package/dist/client/hosted-sandbox-identity.d.ts +32 -18
- package/dist/client/hosted-sandbox-identity.d.ts.map +1 -1
- package/dist/client/hosted-sandbox-identity.js +46 -27
- package/dist/client/hosted-sandbox-identity.js.map +1 -1
- package/dist/client/hosted-store-records.d.ts +46 -0
- package/dist/client/hosted-store-records.d.ts.map +1 -0
- package/dist/client/hosted-store-records.js +32 -0
- package/dist/client/hosted-store-records.js.map +1 -0
- package/dist/client/hosted-transport.d.ts +41 -33
- package/dist/client/hosted-transport.d.ts.map +1 -1
- package/dist/client/hosted-transport.js +146 -101
- package/dist/client/hosted-transport.js.map +1 -1
- package/dist/client/hosted-trust.d.ts +1 -1
- package/dist/client/hosted-trust.d.ts.map +1 -1
- package/dist/client/hosted-trust.js +1 -1
- package/dist/client/hosted-trust.js.map +1 -1
- package/dist/client/hosted.d.ts +140 -74
- package/dist/client/hosted.d.ts.map +1 -1
- package/dist/client/hosted.js +102 -60
- package/dist/client/hosted.js.map +1 -1
- package/dist/client/index.d.ts +4 -4
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +4 -4
- package/dist/client/index.js.map +1 -1
- package/dist/client/key-rotation-core.d.ts +4 -4
- package/dist/client/key-rotation-core.d.ts.map +1 -1
- package/dist/client/key-rotation-core.js +8 -8
- package/dist/client/key-rotation-core.js.map +1 -1
- package/dist/client/key-rotation.js +2 -2
- package/dist/client/key-rotation.js.map +1 -1
- package/dist/client/messages.d.ts +3 -3
- package/dist/client/messages.d.ts.map +1 -1
- package/dist/client/messages.js +18 -18
- package/dist/client/messages.js.map +1 -1
- package/dist/client/one-time-prekey-refill.d.ts +1 -1
- package/dist/client/one-time-prekey-refill.d.ts.map +1 -1
- package/dist/client/prekeys.js +17 -17
- package/dist/client/prekeys.js.map +1 -1
- package/dist/client/receive-queue.d.ts +4 -4
- package/dist/client/receive-queue.d.ts.map +1 -1
- package/dist/client/receive-queue.js +29 -29
- package/dist/client/receive-queue.js.map +1 -1
- package/dist/client/receive-work-seed.d.ts +6 -2
- package/dist/client/receive-work-seed.d.ts.map +1 -1
- package/dist/client/receive-work-seed.js.map +1 -1
- package/dist/client/recovery-driver.js +7 -7
- package/dist/client/recovery-driver.js.map +1 -1
- package/dist/client/retry-request-envelope.d.ts +3 -3
- package/dist/client/retry-request-envelope.d.ts.map +1 -1
- package/dist/client/retry-request-envelope.js +10 -10
- package/dist/client/retry-request-envelope.js.map +1 -1
- package/dist/client/retry-request-lifecycle.d.ts +1 -1
- package/dist/client/retry-request-lifecycle.d.ts.map +1 -1
- package/dist/client/retry-request-lifecycle.js +8 -8
- package/dist/client/retry-request-lifecycle.js.map +1 -1
- package/dist/client/retry-terminal-recovery.js +2 -2
- package/dist/client/retry-terminal-recovery.js.map +1 -1
- package/dist/client/retry.js +13 -13
- package/dist/client/retry.js.map +1 -1
- package/dist/client/sealed-sender.d.ts +13 -4
- package/dist/client/sealed-sender.d.ts.map +1 -1
- package/dist/client/sealed-sender.js +27 -15
- package/dist/client/sealed-sender.js.map +1 -1
- package/dist/client/send-deadline.d.ts +7 -7
- package/dist/client/send-deadline.d.ts.map +1 -1
- package/dist/client/send-deadline.js +37 -24
- package/dist/client/send-deadline.js.map +1 -1
- package/dist/client/send-intent-driver.js +9 -9
- package/dist/client/send-intent-driver.js.map +1 -1
- package/dist/client/sessions.js +11 -11
- package/dist/client/sessions.js.map +1 -1
- package/dist/client/{relay-acceptance.d.ts → signal-relay-acceptance.d.ts} +9 -9
- package/dist/client/signal-relay-acceptance.d.ts.map +1 -0
- package/dist/client/{relay-acceptance.js → signal-relay-acceptance.js} +7 -7
- package/dist/client/signal-relay-acceptance.js.map +1 -0
- package/dist/client/{relay-device-refusal.d.ts → signal-relay-device-refusal.d.ts} +7 -7
- package/dist/client/signal-relay-device-refusal.d.ts.map +1 -0
- package/dist/client/{relay-device-refusal.js → signal-relay-device-refusal.js} +9 -9
- package/dist/client/signal-relay-device-refusal.js.map +1 -0
- package/dist/client/{relay-lifecycle.d.ts → signal-relay-lifecycle.d.ts} +21 -11
- package/dist/client/signal-relay-lifecycle.d.ts.map +1 -0
- package/dist/client/{relay-lifecycle.js → signal-relay-lifecycle.js} +19 -9
- package/dist/client/signal-relay-lifecycle.js.map +1 -0
- package/dist/client/{relay-period-close.d.ts → signal-relay-period-close.d.ts} +1 -1
- package/dist/client/signal-relay-period-close.d.ts.map +1 -0
- package/dist/client/{relay-period-close.js → signal-relay-period-close.js} +1 -1
- package/dist/client/signal-relay-period-close.js.map +1 -0
- package/dist/client/{relay-protocol.d.ts → signal-relay-protocol.d.ts} +12 -8
- package/dist/client/signal-relay-protocol.d.ts.map +1 -0
- package/dist/client/{relay-protocol.js → signal-relay-protocol.js} +13 -10
- package/dist/client/signal-relay-protocol.js.map +1 -0
- package/dist/client/{relay-receipt-intake.d.ts → signal-relay-receipt-intake.d.ts} +12 -12
- package/dist/client/signal-relay-receipt-intake.d.ts.map +1 -0
- package/dist/client/{relay-receipt-intake.js → signal-relay-receipt-intake.js} +9 -9
- package/dist/client/signal-relay-receipt-intake.js.map +1 -0
- package/dist/client/{relay-receipt-join.d.ts → signal-relay-receipt-join.d.ts} +8 -8
- package/dist/client/signal-relay-receipt-join.d.ts.map +1 -0
- package/dist/client/{relay-receipt-join.js → signal-relay-receipt-join.js} +11 -11
- package/dist/client/signal-relay-receipt-join.js.map +1 -0
- package/dist/client/{relay-request-deadline.d.ts → signal-relay-request-deadline.d.ts} +3 -3
- package/dist/client/signal-relay-request-deadline.d.ts.map +1 -0
- package/dist/client/{relay-request-deadline.js → signal-relay-request-deadline.js} +4 -4
- package/dist/client/signal-relay-request-deadline.js.map +1 -0
- package/dist/client/{relay-sealed-route.d.ts → signal-relay-sealed-route.d.ts} +1 -1
- package/dist/client/signal-relay-sealed-route.d.ts.map +1 -0
- package/dist/client/{relay-sealed-route.js → signal-relay-sealed-route.js} +1 -1
- package/dist/client/signal-relay-sealed-route.js.map +1 -0
- package/dist/client/{relay-subscription.d.ts → signal-relay-subscription.d.ts} +12 -12
- package/dist/client/signal-relay-subscription.d.ts.map +1 -0
- package/dist/client/{relay-subscription.js → signal-relay-subscription.js} +23 -23
- package/dist/client/signal-relay-subscription.js.map +1 -0
- package/dist/client/{relay-work.d.ts → signal-relay-work.d.ts} +7 -7
- package/dist/client/signal-relay-work.d.ts.map +1 -0
- package/dist/client/{relay-work.js → signal-relay-work.js} +13 -13
- package/dist/client/signal-relay-work.js.map +1 -0
- package/dist/client/signal-service-cipher.d.ts +11 -9
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +103 -98
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/client/state.d.ts +4 -4
- package/dist/client/state.d.ts.map +1 -1
- package/dist/client/state.js +3 -3
- package/dist/client/state.js.map +1 -1
- package/dist/client/types.d.ts +13 -4
- package/dist/client/types.d.ts.map +1 -1
- package/dist/client/types.js.map +1 -1
- package/dist/device/connection.d.ts +10 -4
- package/dist/device/connection.d.ts.map +1 -1
- package/dist/device/connection.js +8 -3
- package/dist/device/connection.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/types.d.ts +3 -1
- package/dist/device/types.d.ts.map +1 -1
- package/dist/hooks/index.d.ts +2 -2
- package/dist/hooks/index.d.ts.map +1 -1
- package/dist/hooks/index.js +2 -2
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/use-signal-relay-connection-state.d.ts +40 -0
- package/dist/hooks/use-signal-relay-connection-state.d.ts.map +1 -0
- package/dist/hooks/use-signal-relay-connection-state.js +45 -0
- package/dist/hooks/use-signal-relay-connection-state.js.map +1 -0
- package/dist/hooks/use-signal-relay-lifecycle.d.ts +43 -0
- package/dist/hooks/use-signal-relay-lifecycle.d.ts.map +1 -0
- package/dist/hooks/use-signal-relay-lifecycle.js +38 -0
- package/dist/hooks/use-signal-relay-lifecycle.js.map +1 -0
- package/dist/index.d.ts +18 -12
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -5
- package/dist/index.js.map +1 -1
- package/dist/internal/groups/authority-certificate.d.ts +7 -1
- package/dist/internal/groups/authority-certificate.d.ts.map +1 -1
- package/dist/internal/groups/authority-certificate.js +29 -6
- package/dist/internal/groups/authority-certificate.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/certificate.js +2 -2
- package/dist/internal/protocol/sealed-sender/certificate.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/proto/index.d.ts +1 -1
- package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/proto/index.js +5 -5
- package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
- package/dist/internal/sesame/device-registry.d.ts +13 -13
- package/dist/internal/sesame/device-registry.d.ts.map +1 -1
- package/dist/internal/sesame/device-registry.js +20 -20
- package/dist/internal/sesame/device-registry.js.map +1 -1
- package/dist/local/store/receive-work.d.ts +29 -0
- package/dist/local/store/receive-work.d.ts.map +1 -1
- package/dist/local/store/receive-work.js +58 -1
- package/dist/local/store/receive-work.js.map +1 -1
- package/dist/local/store/received-content.d.ts +1 -1
- package/dist/local/store/received-content.d.ts.map +1 -1
- package/dist/local/store/reliability.d.ts +11 -3
- package/dist/local/store/reliability.d.ts.map +1 -1
- package/dist/local/store/reliability.js +4 -0
- package/dist/local/store/reliability.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/index.d.ts +3 -9
- package/dist/local/store/sqlite/key-storage/index.d.ts.map +1 -1
- package/dist/local/store/sqlite/key-storage/index.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/signed-prekeys.d.ts +1 -7
- package/dist/local/store/sqlite/key-storage/signed-prekeys.d.ts.map +1 -1
- package/dist/local/store/sqlite/key-storage/signed-prekeys.js.map +1 -1
- package/dist/local/store/sqlite/models/kyber-prekey.d.ts +4 -9
- package/dist/local/store/sqlite/models/kyber-prekey.d.ts.map +1 -1
- package/dist/local/store/sqlite/models/kyber-prekey.js +4 -1
- package/dist/local/store/sqlite/models/kyber-prekey.js.map +1 -1
- package/dist/local/store/sqlite/store.d.ts.map +1 -1
- package/dist/local/store/sqlite/store.js +1 -2
- package/dist/local/store/sqlite/store.js.map +1 -1
- package/dist/remote/signal-relay/connection-state.d.ts +16 -0
- package/dist/remote/signal-relay/connection-state.d.ts.map +1 -0
- package/dist/remote/{relay → signal-relay}/connection-state.js +1 -1
- package/dist/remote/signal-relay/connection-state.js.map +1 -0
- package/dist/remote/{relay → signal-relay}/device-set.d.ts +3 -3
- package/dist/remote/signal-relay/device-set.d.ts.map +1 -0
- package/dist/remote/{relay → signal-relay}/device-set.js +7 -7
- package/dist/remote/signal-relay/device-set.js.map +1 -0
- package/dist/remote/{relay → signal-relay}/index.d.ts +3 -3
- package/dist/remote/signal-relay/index.d.ts.map +1 -0
- package/dist/remote/{relay → signal-relay}/index.js +2 -2
- package/dist/remote/signal-relay/index.js.map +1 -0
- package/dist/remote/{relay → signal-relay}/request-admission.d.ts +2 -2
- package/dist/remote/signal-relay/request-admission.d.ts.map +1 -0
- package/dist/remote/{relay → signal-relay}/request-admission.js +5 -5
- package/dist/remote/signal-relay/request-admission.js.map +1 -0
- package/dist/remote/{relay → signal-relay}/types.d.ts +29 -11
- package/dist/remote/signal-relay/types.d.ts.map +1 -0
- package/dist/remote/{relay → signal-relay}/types.js +1 -1
- package/dist/remote/signal-relay/types.js.map +1 -0
- package/dist/safety/core.d.ts +1 -1
- package/dist/safety/core.js +1 -1
- package/dist/types/api.d.ts +43 -20
- package/dist/types/api.d.ts.map +1 -1
- package/dist/types/errors.d.ts +55 -7
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/errors.js +61 -8
- package/dist/types/errors.js.map +1 -1
- package/dist/types/renamed-member.d.ts +41 -0
- package/dist/types/renamed-member.d.ts.map +1 -0
- package/dist/types/renamed-member.js +73 -0
- package/dist/types/renamed-member.js.map +1 -0
- package/dist/utils/bounded-fan-out.d.ts +2 -2
- package/dist/utils/bounded-fan-out.d.ts.map +1 -1
- package/dist/utils/bounded-fan-out.js +2 -2
- package/dist/utils/bounded-fan-out.js.map +1 -1
- package/dist/utils/retry.d.ts +3 -3
- package/dist/utils/retry.d.ts.map +1 -1
- package/dist/utils/retry.js +4 -3
- package/dist/utils/retry.js.map +1 -1
- package/docs/ASSURANCE.md +5 -5
- package/docs/CLIENT_COMPOSITION.md +10 -8
- package/docs/DEVIATIONS.md +10 -7
- package/docs/ERROR_HANDLING.md +24 -24
- package/docs/GETTING_STARTED.md +22 -16
- package/docs/INTERFACES.md +5 -5
- package/docs/PACKAGE_SURFACE.md +14 -4
- package/docs/PROTOCOL_POLICY.md +4 -4
- package/docs/RECIPES.md +274 -15
- package/hooks/README.md +11 -11
- package/local/store/expo/README.md +1 -1
- package/local/store/key-value/README.md +2 -2
- package/local/store/node/README.md +1 -1
- package/local/store/react-native/README.md +1 -1
- package/local/store/web/README.md +1 -1
- package/local/store/web-sqlite/README.md +2 -2
- package/package.json +16 -6
- package/remote/README.md +4 -4
- package/remote/object-store/convex-r2/README.md +1 -1
- package/remote/{relay → signal-relay}/README.md +14 -6
- package/dist/client/relay-acceptance.d.ts.map +0 -1
- package/dist/client/relay-acceptance.js.map +0 -1
- package/dist/client/relay-device-refusal.d.ts.map +0 -1
- package/dist/client/relay-device-refusal.js.map +0 -1
- package/dist/client/relay-lifecycle.d.ts.map +0 -1
- package/dist/client/relay-lifecycle.js.map +0 -1
- package/dist/client/relay-period-close.d.ts.map +0 -1
- package/dist/client/relay-period-close.js.map +0 -1
- package/dist/client/relay-protocol.d.ts.map +0 -1
- package/dist/client/relay-protocol.js.map +0 -1
- package/dist/client/relay-receipt-intake.d.ts.map +0 -1
- package/dist/client/relay-receipt-intake.js.map +0 -1
- package/dist/client/relay-receipt-join.d.ts.map +0 -1
- package/dist/client/relay-receipt-join.js.map +0 -1
- package/dist/client/relay-request-deadline.d.ts.map +0 -1
- package/dist/client/relay-request-deadline.js.map +0 -1
- package/dist/client/relay-sealed-route.d.ts.map +0 -1
- package/dist/client/relay-sealed-route.js.map +0 -1
- package/dist/client/relay-subscription.d.ts.map +0 -1
- package/dist/client/relay-subscription.js.map +0 -1
- package/dist/client/relay-work.d.ts.map +0 -1
- package/dist/client/relay-work.js.map +0 -1
- package/dist/hooks/use-relay-connection-state.d.ts +0 -32
- package/dist/hooks/use-relay-connection-state.d.ts.map +0 -1
- package/dist/hooks/use-relay-connection-state.js +0 -31
- package/dist/hooks/use-relay-connection-state.js.map +0 -1
- package/dist/hooks/use-relay-lifecycle.d.ts +0 -36
- package/dist/hooks/use-relay-lifecycle.d.ts.map +0 -1
- package/dist/hooks/use-relay-lifecycle.js +0 -35
- package/dist/hooks/use-relay-lifecycle.js.map +0 -1
- package/dist/remote/relay/connection-state.d.ts +0 -16
- package/dist/remote/relay/connection-state.d.ts.map +0 -1
- package/dist/remote/relay/connection-state.js.map +0 -1
- package/dist/remote/relay/device-set.d.ts.map +0 -1
- package/dist/remote/relay/device-set.js.map +0 -1
- package/dist/remote/relay/index.d.ts.map +0 -1
- package/dist/remote/relay/index.js.map +0 -1
- package/dist/remote/relay/request-admission.d.ts.map +0 -1
- package/dist/remote/relay/request-admission.js.map +0 -1
- package/dist/remote/relay/types.d.ts.map +0 -1
- package/dist/remote/relay/types.js.map +0 -1
package/docs/GETTING_STARTED.md
CHANGED
|
@@ -20,14 +20,17 @@ The [adapter guide](../ADAPTERS.md) lists the supported stores.
|
|
|
20
20
|
|
|
21
21
|
- A Relay project and its environment connection URL. In the application
|
|
22
22
|
directory, `oe new` creates the project and its Sandbox environment, and it
|
|
23
|
-
writes the connection URL to `.env.local` as `
|
|
24
|
-
Next.js, Expo, or Vite application, the name has the public prefix of the
|
|
25
|
-
framework, for example `
|
|
23
|
+
writes the connection URL to `.env.local` as `OPEN_E2EE_SIGNAL_RELAY_URL`. In
|
|
24
|
+
a Next.js, Expo, or Vite application, the name has the public prefix of the
|
|
25
|
+
framework, for example `EXPO_PUBLIC_OPEN_E2EE_SIGNAL_RELAY_URL`. An `oe`
|
|
26
|
+
release before 5.0.0 wrote the earlier name, such as
|
|
27
|
+
`EXPO_PUBLIC_OPEN_E2EE_RELAY_URL`. The examples read the new name first and
|
|
28
|
+
the earlier name second.
|
|
26
29
|
- A `getIdentityAssertion` callback that returns a short-lived signed assertion.
|
|
27
30
|
- Device-local storage for private keys, sessions, and delivery state.
|
|
28
31
|
- Application storage for decrypted messages and attachment bytes.
|
|
29
32
|
|
|
30
|
-
A Sandbox environment uses device-owned identity. `
|
|
33
|
+
A Sandbox environment uses device-owned identity. `hostedSignalProtocolRelaySandboxIdentity`
|
|
31
34
|
creates its `getIdentityAssertion` callback. The callback keeps a key in the device-local store. It signs each assertion
|
|
32
35
|
with that key. The device gets the same account each time it registers.
|
|
33
36
|
|
|
@@ -36,17 +39,20 @@ A device that loses its store loses that Sandbox account. The helper works only
|
|
|
36
39
|
Production supports application-bound and explicitly configured device-owned
|
|
37
40
|
accounts. For application-bound accounts, `getIdentityAssertion` returns a
|
|
38
41
|
short-lived Relay-specific assertion from your backend after it verifies the
|
|
39
|
-
server session and current application membership.
|
|
42
|
+
server session and current application membership. With a
|
|
43
|
+
[native Clerk or Firebase profile](./RECIPES.md#native-provider-profiles),
|
|
44
|
+
`getIdentityAssertion` returns the provider token instead, and no backend
|
|
45
|
+
assertion is needed.
|
|
40
46
|
|
|
41
47
|
Device-owned accounts prove possession of a persistent account key. They do
|
|
42
48
|
not bind to an application login, and provider sign-in cannot recover a lost
|
|
43
49
|
account key. For device-owned accounts, pass
|
|
44
|
-
`
|
|
50
|
+
`hostedSignalProtocolRelayDeviceOwnedIdentity(storage)` as `getIdentityAssertion`. The SDK
|
|
45
51
|
does not supply an identity provider or a relay server implementation.
|
|
46
|
-
See [identity and authentication](https://docs.open-e2ee.dev/relay/identity)
|
|
52
|
+
See [identity and authentication](https://docs.open-e2ee.dev/signal-relay/identity)
|
|
47
53
|
for Production configuration.
|
|
48
54
|
|
|
49
|
-
For a tested backend path, see the [Better Auth recipe](https://docs.open-e2ee.dev/relay/better-auth)
|
|
55
|
+
For a tested backend path, see the [Better Auth recipe](https://docs.open-e2ee.dev/signal-relay/better-auth)
|
|
50
56
|
and the [application callback recipe](./RECIPES.md#application-bound-identity-callback).
|
|
51
57
|
|
|
52
58
|
## Setup Sequence
|
|
@@ -54,7 +60,7 @@ and the [application callback recipe](./RECIPES.md#application-bound-identity-ca
|
|
|
54
60
|
1. Run `oe new` to create the Relay project and its Sandbox environment.
|
|
55
61
|
2. Open the device-local store for the device.
|
|
56
62
|
3. Create the client with `createHostedSignalProtocolClient()`. In a Sandbox
|
|
57
|
-
environment, pass `
|
|
63
|
+
environment, pass `hostedSignalProtocolRelaySandboxIdentity(storage)` as
|
|
58
64
|
`hosted.getIdentityAssertion`.
|
|
59
65
|
4. Register a receive handler that persists decrypted messages.
|
|
60
66
|
5. Start the relay subscription.
|
|
@@ -62,12 +68,12 @@ and the [application callback recipe](./RECIPES.md#application-bound-identity-ca
|
|
|
62
68
|
The hosted factory authenticates and registers the current device, then publishes
|
|
63
69
|
its public prekeys. A linked device gets the account identity by device
|
|
64
70
|
transfer or by a channel that the application owns, then joins the account
|
|
65
|
-
with `
|
|
71
|
+
with `linkHostedSignalProtocolRelayDevice()`. That call runs in one process that holds the
|
|
66
72
|
active device's store and the new device's store. It copies each group master
|
|
67
73
|
key from the active device and gives the new device its own registration ID.
|
|
68
74
|
|
|
69
75
|
It refuses a new device's store that already lists a group, with
|
|
70
|
-
`
|
|
76
|
+
`HostedSignalProtocolRelayDeviceLinkError`. See the [device guide](../device/README.md). The
|
|
71
77
|
default policy requires post-quantum session establishment and Braid
|
|
72
78
|
ratcheting.
|
|
73
79
|
|
|
@@ -83,7 +89,7 @@ Retry with the same stores to retain the original operation and prekeys.
|
|
|
83
89
|
```ts
|
|
84
90
|
import {
|
|
85
91
|
createHostedSignalProtocolClient,
|
|
86
|
-
|
|
92
|
+
hostedSignalProtocolRelaySandboxIdentity,
|
|
87
93
|
} from "@open-e2ee/signal-protocol-sdk";
|
|
88
94
|
import { expoStore } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
|
|
89
95
|
|
|
@@ -91,9 +97,9 @@ const storage = await expoStore();
|
|
|
91
97
|
const signal = await createHostedSignalProtocolClient({
|
|
92
98
|
adapters: { storage },
|
|
93
99
|
hosted: {
|
|
94
|
-
|
|
100
|
+
signalProtocolRelayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_SIGNAL_RELAY_URL ?? process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
|
|
95
101
|
// Sandbox only. Select the Production identity mode explicitly.
|
|
96
|
-
getIdentityAssertion:
|
|
102
|
+
getIdentityAssertion: hostedSignalProtocolRelaySandboxIdentity(storage),
|
|
97
103
|
},
|
|
98
104
|
});
|
|
99
105
|
```
|
|
@@ -128,7 +134,7 @@ signal.registerHook("onMessageDecrypted", async (message) => {
|
|
|
128
134
|
});
|
|
129
135
|
|
|
130
136
|
// Subscribing starts encrypted envelope delivery and local decryption.
|
|
131
|
-
signal.
|
|
137
|
+
signal.startSignalProtocolRelaySubscription();
|
|
132
138
|
```
|
|
133
139
|
|
|
134
140
|
The package does not own your product database or UI state. It decrypts messages
|
|
@@ -202,7 +208,7 @@ save attachment references and downloaded bytes.
|
|
|
202
208
|
import { createHostedSignalProtocolClient, media } from "@open-e2ee/signal-protocol-sdk";
|
|
203
209
|
|
|
204
210
|
const signal = await createHostedSignalProtocolClient({
|
|
205
|
-
hosted: {
|
|
211
|
+
hosted: { signalProtocolRelayUrl, getIdentityAssertion },
|
|
206
212
|
adapters: {
|
|
207
213
|
storage,
|
|
208
214
|
},
|
package/docs/INTERFACES.md
CHANGED
|
@@ -40,7 +40,7 @@ const storage: SignalProtocolLocalStore = appProtocolStore;
|
|
|
40
40
|
|
|
41
41
|
const client = await createSignalProtocolClient({
|
|
42
42
|
identity: { userId },
|
|
43
|
-
adapters: { storage,
|
|
43
|
+
adapters: { storage, signalProtocolRelay },
|
|
44
44
|
});
|
|
45
45
|
```
|
|
46
46
|
|
|
@@ -87,10 +87,10 @@ delivery, key rotation, and encrypted group coordination.
|
|
|
87
87
|
|
|
88
88
|
<!-- doc-snippet:skip requires-external-context -->
|
|
89
89
|
```ts
|
|
90
|
-
import type { SignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/relay";
|
|
90
|
+
import type { SignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/signal-relay";
|
|
91
91
|
|
|
92
92
|
// An application-owned client transport to an authenticated backend.
|
|
93
|
-
const
|
|
93
|
+
const signalProtocolRelay: SignalProtocolRelayServer = appSignalProtocolRelayTransport;
|
|
94
94
|
```
|
|
95
95
|
|
|
96
96
|
The hosted factory configures the OpenE2EE Signal Protocol Relay transport.
|
|
@@ -128,7 +128,7 @@ The server remains responsible for atomic one-time-key consumption.
|
|
|
128
128
|
|
|
129
129
|
The relay stores public protocol material, ciphertext, and required routing
|
|
130
130
|
metadata. It must not require device private keys or decrypted message content.
|
|
131
|
-
See the [relay guide](../remote/relay/README.md).
|
|
131
|
+
See the [relay guide](../remote/signal-relay/README.md).
|
|
132
132
|
|
|
133
133
|
## `SignalProtocolRemoteObjectStore`
|
|
134
134
|
|
|
@@ -175,7 +175,7 @@ media lifecycle callbacks and client hooks at the client boundary:
|
|
|
175
175
|
```ts
|
|
176
176
|
const client = await createSignalProtocolClient({
|
|
177
177
|
identity: { userId },
|
|
178
|
-
adapters: { storage,
|
|
178
|
+
adapters: { storage, signalProtocolRelay, remoteObjectStore },
|
|
179
179
|
media: {
|
|
180
180
|
preparedUploads: appPreparedUploads,
|
|
181
181
|
maxPreparedUploadBytes: appUploadBudgetBytes,
|
package/docs/PACKAGE_SURFACE.md
CHANGED
|
@@ -70,8 +70,8 @@ implementations are outside the published SDK.
|
|
|
70
70
|
|
|
71
71
|
## Integration subpaths
|
|
72
72
|
|
|
73
|
-
- `@open-e2ee/signal-protocol-sdk/remote/relay`
|
|
74
|
-
- `@open-e2ee/signal-protocol-sdk/remote/relay/types`
|
|
73
|
+
- `@open-e2ee/signal-protocol-sdk/remote/signal-relay`
|
|
74
|
+
- `@open-e2ee/signal-protocol-sdk/remote/signal-relay/types`
|
|
75
75
|
- `@open-e2ee/signal-protocol-sdk/remote/object-store`
|
|
76
76
|
- `@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2`
|
|
77
77
|
- `@open-e2ee/signal-protocol-sdk/remote/object-store/s3`
|
|
@@ -131,6 +131,16 @@ implementations are outside the published SDK.
|
|
|
131
131
|
|
|
132
132
|
- `@open-e2ee/signal-protocol-sdk/local/store/memory`
|
|
133
133
|
|
|
134
|
+
### Deprecated subpaths
|
|
135
|
+
|
|
136
|
+
Each deprecated subpath loads the same module as its replacement. SDK 15.0.0
|
|
137
|
+
removes the deprecated subpaths.
|
|
138
|
+
|
|
139
|
+
| Deprecated subpath | Replacement |
|
|
140
|
+
| --- | --- |
|
|
141
|
+
| `@open-e2ee/signal-protocol-sdk/remote/relay` | `@open-e2ee/signal-protocol-sdk/remote/signal-relay` |
|
|
142
|
+
| `@open-e2ee/signal-protocol-sdk/remote/relay/types` | `@open-e2ee/signal-protocol-sdk/remote/signal-relay/types` |
|
|
143
|
+
|
|
134
144
|
`internal/**` is implementation-only and not part of the supported external API.
|
|
135
145
|
|
|
136
146
|
## Basic concepts
|
|
@@ -260,7 +270,7 @@ implement the same `MediaAttachmentTransfer` seam.
|
|
|
260
270
|
|
|
261
271
|
## Resume an existing hosted device
|
|
262
272
|
|
|
263
|
-
Use `resumeHostedSignalProtocolClient({ adapters: { storage }, hosted: {
|
|
273
|
+
Use `resumeHostedSignalProtocolClient({ adapters: { storage }, hosted: { signalProtocolRelayUrl } })`
|
|
264
274
|
when the application must preserve the device already held by its open store.
|
|
265
275
|
The SDK refuses missing, unreadable or changed required identity state. It never
|
|
266
276
|
falls back to registration, recovery or device linking. The default
|
|
@@ -272,7 +282,7 @@ the application configures receive hooks, still run. This API does not promise a
|
|
|
272
282
|
store or prove that the store contains every historical message/key.
|
|
273
283
|
|
|
274
284
|
The application owns the store and must not use it concurrently. A
|
|
275
|
-
`
|
|
285
|
+
`HostedSignalProtocolRelayResumeError` with `cleanupPending` retains a client that has not
|
|
276
286
|
completed `stop()`. Keep that error and call `retryCleanup()` only when cleanup is
|
|
277
287
|
selected. This retries the held stop, never resume or registration, and never
|
|
278
288
|
closes the application store. Preserve unresolved application operation state.
|
package/docs/PROTOCOL_POLICY.md
CHANGED
|
@@ -32,7 +32,7 @@ the current app.
|
|
|
32
32
|
```ts
|
|
33
33
|
await createSignalProtocolClient({
|
|
34
34
|
identity: { userId },
|
|
35
|
-
adapters: { storage,
|
|
35
|
+
adapters: { storage, signalProtocolRelay },
|
|
36
36
|
protocol: { postQuantum: 'required', braid: 'required' },
|
|
37
37
|
});
|
|
38
38
|
```
|
|
@@ -60,7 +60,7 @@ No setting allows downgrade recovery:
|
|
|
60
60
|
```ts
|
|
61
61
|
await createSignalProtocolClient({
|
|
62
62
|
identity: { userId },
|
|
63
|
-
adapters: { storage,
|
|
63
|
+
adapters: { storage, signalProtocolRelay },
|
|
64
64
|
protocol: { postQuantum: 'required', braid: 'required' },
|
|
65
65
|
});
|
|
66
66
|
```
|
|
@@ -78,7 +78,7 @@ See [Deviations §4.1](./DEVIATIONS.md#41-the-hek-operand-order-diverges).
|
|
|
78
78
|
```ts
|
|
79
79
|
await createSignalProtocolClient({
|
|
80
80
|
identity: { userId },
|
|
81
|
-
adapters: { storage,
|
|
81
|
+
adapters: { storage, signalProtocolRelay },
|
|
82
82
|
protocol: { postQuantum: 'required', braid: 'disabled' },
|
|
83
83
|
});
|
|
84
84
|
```
|
|
@@ -97,7 +97,7 @@ import { BraidPolicy, PostQuantumPolicy, createSignalProtocolClient } from '@ope
|
|
|
97
97
|
|
|
98
98
|
await createSignalProtocolClient({
|
|
99
99
|
identity: { userId },
|
|
100
|
-
adapters: { storage,
|
|
100
|
+
adapters: { storage, signalProtocolRelay },
|
|
101
101
|
protocol: {
|
|
102
102
|
postQuantum: PostQuantumPolicy.Required,
|
|
103
103
|
braid: BraidPolicy.Required,
|
package/docs/RECIPES.md
CHANGED
|
@@ -10,9 +10,10 @@ uses public exports only.
|
|
|
10
10
|
|
|
11
11
|
## Hosted Client Setup
|
|
12
12
|
|
|
13
|
-
The recipes require a configured Relay project, an
|
|
14
|
-
and device-local storage. Use a Sandbox
|
|
15
|
-
|
|
13
|
+
The recipes require a configured OpenE2EE Signal Protocol Relay project, an
|
|
14
|
+
identity-assertion callback, and device-local storage. Use a Sandbox
|
|
15
|
+
environment for development, where
|
|
16
|
+
`hostedSignalProtocolRelaySandboxIdentity(storage)` supplies the callback. The
|
|
16
17
|
[getting-started guide](./GETTING_STARTED.md) describes these inputs.
|
|
17
18
|
|
|
18
19
|
## Application-bound identity callback
|
|
@@ -26,7 +27,7 @@ that assertion. Keep provider credentials and signing keys on the backend.
|
|
|
26
27
|
import type { GetIdentityAssertion } from "@open-e2ee/signal-protocol-sdk";
|
|
27
28
|
|
|
28
29
|
const getIdentityAssertion: GetIdentityAssertion = async (request) => {
|
|
29
|
-
const response = await fetch("https://application.example/api/relay-identity", {
|
|
30
|
+
const response = await fetch("https://application.example/api/signal-relay-identity", {
|
|
30
31
|
method: "POST",
|
|
31
32
|
credentials: "include",
|
|
32
33
|
headers: { "content-type": "application/json" },
|
|
@@ -49,17 +50,275 @@ Replace the example application origin with your authenticated backend.
|
|
|
49
50
|
Configure its CSRF controls and cookie policy. Do not send a member ID or
|
|
50
51
|
provider token from this callback as proof of membership.
|
|
51
52
|
|
|
52
|
-
The
|
|
53
|
+
The browser callback above uses cookies. Native apps (React Native and Expo)
|
|
54
|
+
use the bearer-credential callback in
|
|
55
|
+
[native apps](https://docs.open-e2ee.dev/signal-relay/custom-token#native-apps-react-native-and-expo).
|
|
56
|
+
|
|
57
|
+
The [Better Auth recipe](https://docs.open-e2ee.dev/signal-relay/better-auth) uses a
|
|
53
58
|
real server session with the cookie cache disabled. The
|
|
54
|
-
[backend contract](https://docs.open-e2ee.dev/relay/backend-identity) lists
|
|
55
|
-
other provider paths and their evidence levels. Those paths issue
|
|
56
|
-
assertions.
|
|
59
|
+
[backend contract](https://docs.open-e2ee.dev/signal-relay/backend-identity) lists
|
|
60
|
+
other provider paths and their evidence levels. Those backend paths issue
|
|
61
|
+
custom-token assertions. The [native provider profiles](#native-provider-profiles)
|
|
62
|
+
use the provider token instead.
|
|
57
63
|
|
|
58
64
|
Application logout and assertion refusal do not revoke existing device proofs.
|
|
59
65
|
To stop identified access on existing devices, follow the
|
|
60
|
-
[suspension procedure](https://docs.open-e2ee.dev/relay/backend-identity#suspend-an-identified-account).
|
|
66
|
+
[suspension procedure](https://docs.open-e2ee.dev/signal-relay/backend-identity#suspend-an-identified-account).
|
|
61
67
|
Anonymous capabilities retain their separate limits.
|
|
62
68
|
|
|
69
|
+
## Native provider profiles
|
|
70
|
+
|
|
71
|
+
A native provider profile lets the OpenE2EE Signal Protocol Relay verify the
|
|
72
|
+
token of the identity provider itself. The browser callback returns that
|
|
73
|
+
token. No application backend signs a Relay-specific assertion.
|
|
74
|
+
|
|
75
|
+
The Signal Protocol Relay accepts Clerk and Firebase sign-in as native
|
|
76
|
+
identity providers in Sandbox and Production. Select Clerk or Firebase as the
|
|
77
|
+
identity source of the environment in the Console before the first device
|
|
78
|
+
registers. The recipes below give the callback and the Relay verifier contract
|
|
79
|
+
for each profile.
|
|
80
|
+
|
|
81
|
+
Relay applies these checks to both providers:
|
|
82
|
+
|
|
83
|
+
- The token is a JWT signed with RS256. Its header has a `kid`. It has no
|
|
84
|
+
`crit`, `jku`, `jwk`, `x5c`, or `x5u` parameter.
|
|
85
|
+
- The `iss` claim matches the configured issuer. The `sub` claim is the user
|
|
86
|
+
ID of the provider. The issuer and the subject together select one Relay
|
|
87
|
+
account.
|
|
88
|
+
- The `iat` and `exp` claims are integers. The token is not expired, and its
|
|
89
|
+
`nbf` claim, when present, is not in the future.
|
|
90
|
+
- Relay records an identifier for each accepted token. With a `jti` claim,
|
|
91
|
+
the identifier is that claim, and the same token in a second SDK operation
|
|
92
|
+
fails with `ASSERTION_REPLAY`. Without `jti`, Relay derives the identifier
|
|
93
|
+
from the token, the purpose, and the SDK operation.
|
|
94
|
+
|
|
95
|
+
The SDK calls the callback to register a device, to recover the account, and
|
|
96
|
+
to advance an identity migration. Each callback in these recipes asks the
|
|
97
|
+
provider for a new token on each call. It refuses a migration request, because
|
|
98
|
+
one provider session cannot serve as both the source and the target of a
|
|
99
|
+
migration.
|
|
100
|
+
|
|
101
|
+
### Clerk session token callback
|
|
102
|
+
|
|
103
|
+
The profile names the issuer of the Clerk instance and its authorized
|
|
104
|
+
parties. Relay checks these claims of the Clerk session token:
|
|
105
|
+
|
|
106
|
+
| Claim | Relay rule |
|
|
107
|
+
|---|---|
|
|
108
|
+
| `iss` | The public HTTPS origin of the Clerk instance, with no path or port. |
|
|
109
|
+
| `azp` | One of the 1 to 16 configured authorized parties. A profile accepts a token without `azp` only when it also requires an audience. |
|
|
110
|
+
| `aud` | Absent, unless the profile sets an audience. Then it must match. |
|
|
111
|
+
| `sid`, `v`, `nbf` | Required. `v` is `2`. The `sts` claim, when present, is `active`. |
|
|
112
|
+
| `jti` | Optional. |
|
|
113
|
+
| `exp` | At most 10 minutes after `iat`. |
|
|
114
|
+
|
|
115
|
+
Return the session token itself. A token from a JWT template without the
|
|
116
|
+
session claims fails verification.
|
|
117
|
+
|
|
118
|
+
<!-- doc-snippet:run recipes-clerk-identity-callback expect="clerk register=clerk-session-token migration=This callback does not serve identity migration." -->
|
|
119
|
+
```ts
|
|
120
|
+
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
121
|
+
import type {
|
|
122
|
+
GetIdentityAssertion,
|
|
123
|
+
IdentityAssertionRequest,
|
|
124
|
+
} from "@open-e2ee/signal-protocol-sdk";
|
|
125
|
+
|
|
126
|
+
// The part of a loaded Clerk instance that the callback reads.
|
|
127
|
+
interface ClerkSessionSource {
|
|
128
|
+
readonly session?: {
|
|
129
|
+
readonly user: { readonly id: string } | null;
|
|
130
|
+
getToken(options: { skipCache: boolean }): Promise<string | null>;
|
|
131
|
+
} | null;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
function clerkIdentityAssertion(
|
|
135
|
+
clerk: ClerkSessionSource,
|
|
136
|
+
userId: string,
|
|
137
|
+
): GetIdentityAssertion {
|
|
138
|
+
return async (request: IdentityAssertionRequest) => {
|
|
139
|
+
if (request.migration || request.purpose === "refresh") {
|
|
140
|
+
throw new Error("This callback does not serve identity migration.");
|
|
141
|
+
}
|
|
142
|
+
const session = clerk.session;
|
|
143
|
+
if (!session || session.user?.id !== userId) {
|
|
144
|
+
throw new Error("Sign in as the user of this device store.");
|
|
145
|
+
}
|
|
146
|
+
// Relay refuses an expired or reused token, so ask for a new one.
|
|
147
|
+
const token = await session.getToken({ skipCache: true });
|
|
148
|
+
if (clerk.session?.user?.id !== userId) {
|
|
149
|
+
throw new Error("The signed-in user changed.");
|
|
150
|
+
}
|
|
151
|
+
if (!token) throw new Error("Clerk returned no session token.");
|
|
152
|
+
return token;
|
|
153
|
+
};
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
// In-memory stand-in for a signed-in Clerk instance.
|
|
157
|
+
const clerk: ClerkSessionSource = {
|
|
158
|
+
session: {
|
|
159
|
+
user: { id: "user_example" },
|
|
160
|
+
getToken: async ({ skipCache }) => (skipCache ? "clerk-session-token" : null),
|
|
161
|
+
},
|
|
162
|
+
};
|
|
163
|
+
const getIdentityAssertion = clerkIdentityAssertion(clerk, "user_example");
|
|
164
|
+
const context = { environment: "sandbox", publishableKey: "example" } as const;
|
|
165
|
+
const token = await getIdentityAssertion({ ...context, purpose: "register" });
|
|
166
|
+
const migration = await getIdentityAssertion({
|
|
167
|
+
...context,
|
|
168
|
+
purpose: "refresh",
|
|
169
|
+
migration: { action: "prepare", providerRole: "target" },
|
|
170
|
+
}).catch((error: Error) => error.message);
|
|
171
|
+
console.log(`clerk register=${token} migration=${migration}`);
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Pass the Clerk instance after it loads, and the user ID of the device store.
|
|
175
|
+
For recovery, Relay reads the factor verification ages in the `fva` claim.
|
|
176
|
+
By default, recovery needs a first-factor verification in the last 5 minutes.
|
|
177
|
+
A profile that requires step-up needs a second-factor verification in the
|
|
178
|
+
last 5 minutes. Otherwise, Relay refuses recovery with `AUTHORITY_DENIED`. Ask
|
|
179
|
+
the user to verify again before you start recovery.
|
|
180
|
+
|
|
181
|
+
### Firebase ID token callback
|
|
182
|
+
|
|
183
|
+
The profile names the Firebase project. Relay checks these claims of the
|
|
184
|
+
Firebase ID token:
|
|
185
|
+
|
|
186
|
+
| Claim | Relay rule |
|
|
187
|
+
|---|---|
|
|
188
|
+
| `iss` | `https://securetoken.google.com/<project id>` |
|
|
189
|
+
| `aud` | The project ID. |
|
|
190
|
+
| `auth_time` | An integer sign-in time, not later than `iat`. |
|
|
191
|
+
| `firebase.sign_in_provider` | Required. |
|
|
192
|
+
| `firebase.tenant` | Absent. Relay refuses a tenant token. |
|
|
193
|
+
| `exp` | At most 1 hour after `iat`. |
|
|
194
|
+
|
|
195
|
+
Relay accepts project-level tokens only. Sign users in to the project itself,
|
|
196
|
+
not to a tenant.
|
|
197
|
+
|
|
198
|
+
<!-- doc-snippet:run recipes-firebase-identity-callback expect="firebase register=firebase-id-token migration=This callback does not serve identity migration." -->
|
|
199
|
+
```ts
|
|
200
|
+
// Real protocol and cryptography; simulated in-memory infrastructure.
|
|
201
|
+
import type {
|
|
202
|
+
GetIdentityAssertion,
|
|
203
|
+
IdentityAssertionRequest,
|
|
204
|
+
} from "@open-e2ee/signal-protocol-sdk";
|
|
205
|
+
|
|
206
|
+
// The part of a Firebase Auth instance that the callback reads.
|
|
207
|
+
interface FirebaseUserSource {
|
|
208
|
+
readonly currentUser: {
|
|
209
|
+
readonly uid: string;
|
|
210
|
+
getIdToken(forceRefresh?: boolean): Promise<string>;
|
|
211
|
+
} | null;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
function firebaseIdentityAssertion(
|
|
215
|
+
auth: FirebaseUserSource,
|
|
216
|
+
uid: string,
|
|
217
|
+
): GetIdentityAssertion {
|
|
218
|
+
return async (request: IdentityAssertionRequest) => {
|
|
219
|
+
if (request.migration || request.purpose === "refresh") {
|
|
220
|
+
throw new Error("This callback does not serve identity migration.");
|
|
221
|
+
}
|
|
222
|
+
const user = auth.currentUser;
|
|
223
|
+
if (!user || user.uid !== uid) {
|
|
224
|
+
throw new Error("Sign in as the user of this device store.");
|
|
225
|
+
}
|
|
226
|
+
// Relay refuses an expired or reused token, so ask for a new one.
|
|
227
|
+
const token = await user.getIdToken(true);
|
|
228
|
+
if (auth.currentUser?.uid !== uid) {
|
|
229
|
+
throw new Error("The signed-in user changed.");
|
|
230
|
+
}
|
|
231
|
+
return token;
|
|
232
|
+
};
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
// In-memory stand-in for a signed-in Firebase Auth instance.
|
|
236
|
+
const auth: FirebaseUserSource = {
|
|
237
|
+
currentUser: {
|
|
238
|
+
uid: "uid-example",
|
|
239
|
+
getIdToken: async (forceRefresh) =>
|
|
240
|
+
forceRefresh ? "firebase-id-token" : "cached-id-token",
|
|
241
|
+
},
|
|
242
|
+
};
|
|
243
|
+
const getIdentityAssertion = firebaseIdentityAssertion(auth, "uid-example");
|
|
244
|
+
const context = { environment: "sandbox", publishableKey: "example" } as const;
|
|
245
|
+
const token = await getIdentityAssertion({ ...context, purpose: "register" });
|
|
246
|
+
const migration = await getIdentityAssertion({
|
|
247
|
+
...context,
|
|
248
|
+
purpose: "refresh",
|
|
249
|
+
migration: { action: "prepare", providerRole: "target" },
|
|
250
|
+
}).catch((error: Error) => error.message);
|
|
251
|
+
console.log(`firebase register=${token} migration=${migration}`);
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Pass the Auth instance and the user ID of the device store. For recovery,
|
|
255
|
+
Relay reads the sign-in time in `auth_time`. By default, recovery needs a
|
|
256
|
+
sign-in in the last 5 minutes. A profile that requires step-up also needs the
|
|
257
|
+
`firebase.sign_in_second_factor` claim. Otherwise, Relay refuses recovery
|
|
258
|
+
with `AUTHORITY_DENIED`. Ask the user to sign in again before you start
|
|
259
|
+
recovery.
|
|
260
|
+
|
|
261
|
+
### Native provider lifecycle
|
|
262
|
+
|
|
263
|
+
Open one device store for each provider user, and stop the client at sign-out:
|
|
264
|
+
|
|
265
|
+
<!-- doc-snippet:skip requires-external-context -->
|
|
266
|
+
```ts
|
|
267
|
+
import { createHostedSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
|
|
268
|
+
import { webSqliteStore } from "@open-e2ee/signal-protocol-sdk/local/store/web-sqlite";
|
|
269
|
+
|
|
270
|
+
// An application-chosen name for this provider user, within the store name rules.
|
|
271
|
+
const storage = await webSqliteStore({ name: storeName });
|
|
272
|
+
const signal = await createHostedSignalProtocolClient({
|
|
273
|
+
adapters: { storage },
|
|
274
|
+
hosted: {
|
|
275
|
+
signalProtocolRelayUrl,
|
|
276
|
+
getIdentityAssertion: firebaseIdentityAssertion(auth, uid),
|
|
277
|
+
},
|
|
278
|
+
});
|
|
279
|
+
|
|
280
|
+
// At provider sign-out, stop the client before another user signs in.
|
|
281
|
+
await signal.stop();
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
These rules apply to Clerk and Firebase profiles:
|
|
285
|
+
|
|
286
|
+
- **Token refresh.** A registered device resumes its session with its device
|
|
287
|
+
key. The SDK does not call the callback for a resume. A provider token
|
|
288
|
+
refresh or expiry does not change a registered device.
|
|
289
|
+
- **Sign-out.** Provider sign-out does not revoke the device. The store
|
|
290
|
+
resumes its account without the callback. A shared store would give the
|
|
291
|
+
next user the account of the previous user. To stop access on existing
|
|
292
|
+
devices, follow the
|
|
293
|
+
[suspension procedure](https://docs.open-e2ee.dev/signal-relay/backend-identity#suspend-an-identified-account).
|
|
294
|
+
- **Reinstall or lost store.** A new store registers a new device of the same
|
|
295
|
+
account. It has a new Signal identity key, no earlier sessions, and no
|
|
296
|
+
message history. Peers must verify and accept the new key. The earlier
|
|
297
|
+
devices stay active with the old key. Until the earlier devices are removed,
|
|
298
|
+
or until recovery, peers cannot send to all devices of the account. A peer
|
|
299
|
+
that accepted the new key gets `UNTRUSTED_IDENTITY` when it sends to an
|
|
300
|
+
earlier device. A peer that has not accepted it cannot decrypt messages from
|
|
301
|
+
the new device. To keep the account identity, use device linking. Each
|
|
302
|
+
registration reserves one of the five device IDs of the account for good.
|
|
303
|
+
See [Signal Protocol Relay device errors](./ERROR_HANDLING.md#signal-protocol-relay-device-errors).
|
|
304
|
+
- **Device linking.** To keep the account identity on a new device, move the
|
|
305
|
+
identity from an existing device and call `linkHostedSignalProtocolRelayDevice`. Your
|
|
306
|
+
application owns that transfer.
|
|
307
|
+
- **Recovery.** Create the client with `assertionPurpose: "recover"` when no
|
|
308
|
+
device of the account remains. Recovery revokes all earlier devices of the
|
|
309
|
+
account and returns device ID 1. The device ID reservation applies to
|
|
310
|
+
registrations, so recovery starts again at device 1. Recovery does not
|
|
311
|
+
restore message plaintext or sessions. Your application decides when to
|
|
312
|
+
start it. Recovery needs a recent provider sign-in. Sign the user in again
|
|
313
|
+
before you start recovery. Relay refuses a sign-in older than the recovery
|
|
314
|
+
window with HTTP 401 `AUTHORITY_DENIED`. See
|
|
315
|
+
[device lifecycle and recovery](https://docs.open-e2ee.dev/signal-relay/device-lifecycle-and-recovery).
|
|
316
|
+
- **Provider change.** A different provider, Clerk instance, or Firebase
|
|
317
|
+
project gives a different issuer or subject. Relay treats it as a different
|
|
318
|
+
account. An environment keeps its identity profile after its first
|
|
319
|
+
registration. To use another provider, start a new project. See
|
|
320
|
+
[in-use environments](https://docs.open-e2ee.dev/signal-relay/identity#in-use-environments).
|
|
321
|
+
|
|
63
322
|
## Production composition with Expo on the Signal Protocol Relay
|
|
64
323
|
|
|
65
324
|
<!-- doc-snippet:skip requires-external-context -->
|
|
@@ -74,8 +333,8 @@ const signal = await createHostedSignalProtocolClient({
|
|
|
74
333
|
},
|
|
75
334
|
hosted: {
|
|
76
335
|
// The environment-scoped connection URL from the OpenE2EE console.
|
|
77
|
-
|
|
78
|
-
//
|
|
336
|
+
signalProtocolRelayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_SIGNAL_RELAY_URL ?? process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
|
|
337
|
+
// The native app callback: https://docs.open-e2ee.dev/signal-relay/custom-token#native-apps-react-native-and-expo
|
|
79
338
|
getIdentityAssertion,
|
|
80
339
|
},
|
|
81
340
|
});
|
|
@@ -90,7 +349,7 @@ must complete the [database setup](../local/store/expo/README.md) first.
|
|
|
90
349
|
```ts
|
|
91
350
|
const signal = await createSignalProtocolClient({
|
|
92
351
|
identity: { userId },
|
|
93
|
-
adapters: { storage,
|
|
352
|
+
adapters: { storage, signalProtocolRelay },
|
|
94
353
|
});
|
|
95
354
|
|
|
96
355
|
// Upload public prekeys before other devices need to message this device.
|
|
@@ -107,7 +366,7 @@ signal.registerHook("onMessageDecrypted", async (message) => {
|
|
|
107
366
|
});
|
|
108
367
|
|
|
109
368
|
// Subscribing starts encrypted envelope delivery and local decryption.
|
|
110
|
-
signal.
|
|
369
|
+
signal.startSignalProtocolRelaySubscription();
|
|
111
370
|
|
|
112
371
|
await signal.send(recipientUserId, "hello");
|
|
113
372
|
```
|
|
@@ -121,7 +380,7 @@ message storage through hooks.
|
|
|
121
380
|
```ts
|
|
122
381
|
await createSignalProtocolClient({
|
|
123
382
|
identity: { userId },
|
|
124
|
-
adapters: { storage,
|
|
383
|
+
adapters: { storage, signalProtocolRelay },
|
|
125
384
|
protocol: {
|
|
126
385
|
postQuantum: "required",
|
|
127
386
|
braid: "required",
|
|
@@ -142,7 +401,7 @@ agreement, so a peer that advertises no post-quantum material fails with
|
|
|
142
401
|
```ts
|
|
143
402
|
await createSignalProtocolClient({
|
|
144
403
|
identity: { userId },
|
|
145
|
-
adapters: { storage,
|
|
404
|
+
adapters: { storage, signalProtocolRelay },
|
|
146
405
|
protocol: {
|
|
147
406
|
postQuantum: "required",
|
|
148
407
|
braid: "disabled",
|
package/hooks/README.md
CHANGED
|
@@ -24,21 +24,21 @@ npm install react react-native
|
|
|
24
24
|
|
|
25
25
|
```tsx
|
|
26
26
|
import {
|
|
27
|
-
|
|
28
|
-
|
|
27
|
+
useSignalProtocolRelayConnectionState,
|
|
28
|
+
useSignalProtocolRelayLifecycle,
|
|
29
29
|
useSessionHealth,
|
|
30
|
-
type
|
|
31
|
-
type
|
|
30
|
+
type UseSignalProtocolRelayLifecycleOptions,
|
|
31
|
+
type UseSignalProtocolRelayConnectionStateOptions,
|
|
32
32
|
type UseSessionHealthOptions,
|
|
33
33
|
} from "@open-e2ee/signal-protocol-sdk/hooks";
|
|
34
34
|
|
|
35
|
-
function SignalLifecycle({ signal }: Pick<
|
|
36
|
-
|
|
35
|
+
function SignalLifecycle({ signal }: Pick<UseSignalProtocolRelayLifecycleOptions, "signal">) {
|
|
36
|
+
useSignalProtocolRelayLifecycle({ signal });
|
|
37
37
|
return null;
|
|
38
38
|
}
|
|
39
39
|
|
|
40
|
-
function OwnConnectionDot({ signal }: Pick<
|
|
41
|
-
const { state } =
|
|
40
|
+
function OwnConnectionDot({ signal }: Pick<UseSignalProtocolRelayConnectionStateOptions, "signal">) {
|
|
41
|
+
const { state } = useSignalProtocolRelayConnectionState({ signal });
|
|
42
42
|
return <Dot online={state === "connected"} />;
|
|
43
43
|
}
|
|
44
44
|
|
|
@@ -51,7 +51,7 @@ function ConversationStatus({ signal, userId }: Pick<UseSessionHealthOptions, "s
|
|
|
51
51
|
|
|
52
52
|
## Relay connection state
|
|
53
53
|
|
|
54
|
-
`
|
|
54
|
+
`useSignalProtocolRelayConnectionState({ signal })` returns the `SignalProtocolRelayConnectionState` of
|
|
55
55
|
the relay subscription on this device. The component renders again on each
|
|
56
56
|
transition, and the hook unsubscribes when the component unmounts. The state
|
|
57
57
|
is `stopped`, `connecting`, `connected`, or `reconnecting`. A `reason` tells
|
|
@@ -60,7 +60,7 @@ is not presence and does not tell you about other users.
|
|
|
60
60
|
|
|
61
61
|
## Relay lifecycle
|
|
62
62
|
|
|
63
|
-
`
|
|
63
|
+
`useSignalProtocolRelayLifecycle({ signal })` stops the relay subscription when a React
|
|
64
64
|
Native app goes to the background and starts it again when the app becomes
|
|
65
65
|
active. The stop closes the socket with code 1000, so the Relay records a
|
|
66
66
|
client close. The Relay replays retained messages when the app becomes active.
|
|
@@ -69,7 +69,7 @@ a hidden desktop tab keeps its socket open by itself.
|
|
|
69
69
|
|
|
70
70
|
Set `keepOpenInBackground: true` to keep the socket open in the background,
|
|
71
71
|
for example while an Android foreground service runs. Outside React, call
|
|
72
|
-
`
|
|
72
|
+
`bindSignalProtocolRelayLifecycle(signal, AppState)` from
|
|
73
73
|
`@open-e2ee/signal-protocol-sdk/client`.
|
|
74
74
|
|
|
75
75
|
Do not call these hooks outside React components or custom hooks. Event callbacks from
|
|
@@ -171,7 +171,7 @@ import { expoStore } from '@open-e2ee/signal-protocol-sdk/local/store/expo';
|
|
|
171
171
|
|
|
172
172
|
const client = await createSignalProtocolClient({
|
|
173
173
|
identity: { userId },
|
|
174
|
-
adapters: { storage: await expoStore(),
|
|
174
|
+
adapters: { storage: await expoStore(), signalProtocolRelay },
|
|
175
175
|
});
|
|
176
176
|
```
|
|
177
177
|
|
|
@@ -21,7 +21,7 @@ The store gets random bytes from the global `crypto.getRandomValues`. Install
|
|
|
21
21
|
it at app startup before the first SDK call. Without a global source, the SDK
|
|
22
22
|
throws `SecureRandomUnavailableError`. The store needs no `crypto.subtle`
|
|
23
23
|
polyfill. AES-256-GCM uses Web Crypto when `crypto.subtle` exists and the
|
|
24
|
-
bundled Noble implementation otherwise. The [README](../../../README.md#use-your-apps-storage-and-
|
|
24
|
+
bundled Noble implementation otherwise. The [README](../../../README.md#use-your-apps-storage-and-message-delivery)
|
|
25
25
|
lists the supported React Native versions.
|
|
26
26
|
|
|
27
27
|
The store also needs a `SignalProtocolLocalSecretVault` backed by the platform
|
|
@@ -47,7 +47,7 @@ const storage = await keyValueStore({ storage: keyValueStorage, vault });
|
|
|
47
47
|
|
|
48
48
|
const client = await createSignalProtocolClient({
|
|
49
49
|
identity: { userId },
|
|
50
|
-
adapters: { storage,
|
|
50
|
+
adapters: { storage, signalProtocolRelay },
|
|
51
51
|
});
|
|
52
52
|
```
|
|
53
53
|
|