@open-e2ee/signal-protocol-sdk 10.1.0 → 12.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ADAPTERS.md +4 -4
- package/ARCHITECTURE.md +6 -8
- package/CHANGELOG.md +1413 -0
- package/README.md +1 -1
- package/SECURITY.md +2 -2
- package/TROUBLESHOOTING.md +1 -1
- package/client/README.md +84 -37
- package/device/README.md +39 -85
- package/dist/client/client.d.ts +342 -62
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +1195 -179
- package/dist/client/client.js.map +1 -1
- package/dist/client/config.d.ts +40 -32
- package/dist/client/config.d.ts.map +1 -1
- package/dist/client/config.js +1 -1
- package/dist/client/config.js.map +1 -1
- package/dist/client/constants.d.ts +42 -8
- package/dist/client/constants.d.ts.map +1 -1
- package/dist/client/constants.js +48 -3
- package/dist/client/constants.js.map +1 -1
- package/dist/client/content-adapter.d.ts +80 -0
- package/dist/client/content-adapter.d.ts.map +1 -1
- package/dist/client/content-adapter.js +225 -12
- package/dist/client/content-adapter.js.map +1 -1
- package/dist/client/delivery-error.d.ts +150 -0
- package/dist/client/delivery-error.d.ts.map +1 -0
- package/dist/client/delivery-error.js +226 -0
- package/dist/client/delivery-error.js.map +1 -0
- package/dist/client/delivery-status.d.ts +32 -6
- package/dist/client/delivery-status.d.ts.map +1 -1
- package/dist/client/delivery-status.js +61 -13
- package/dist/client/delivery-status.js.map +1 -1
- package/dist/client/device-set-reconciliation.d.ts +196 -0
- package/dist/client/device-set-reconciliation.d.ts.map +1 -0
- package/dist/client/device-set-reconciliation.js +282 -0
- package/dist/client/device-set-reconciliation.js.map +1 -0
- package/dist/client/distribution-records.d.ts +29 -0
- package/dist/client/distribution-records.d.ts.map +1 -0
- package/dist/client/distribution-records.js +33 -0
- package/dist/client/distribution-records.js.map +1 -0
- package/dist/client/event-hooks.d.ts +308 -6
- package/dist/client/event-hooks.d.ts.map +1 -1
- package/dist/client/event-hooks.js +9 -0
- package/dist/client/event-hooks.js.map +1 -1
- package/dist/client/group-device-set.d.ts +47 -0
- package/dist/client/group-device-set.d.ts.map +1 -0
- package/dist/client/group-device-set.js +65 -0
- package/dist/client/group-device-set.js.map +1 -0
- package/dist/client/group-fetcher.d.ts +116 -0
- package/dist/client/group-fetcher.d.ts.map +1 -0
- package/dist/client/group-fetcher.js +598 -0
- package/dist/client/group-fetcher.js.map +1 -0
- package/dist/client/group-outbox.d.ts +172 -10
- package/dist/client/group-outbox.d.ts.map +1 -1
- package/dist/client/group-outbox.js +915 -74
- package/dist/client/group-outbox.js.map +1 -1
- package/dist/client/group-receive-authorization.d.ts +127 -4
- package/dist/client/group-receive-authorization.d.ts.map +1 -1
- package/dist/client/group-receive-authorization.js +270 -20
- package/dist/client/group-receive-authorization.js.map +1 -1
- package/dist/client/group-sealed-sender.d.ts +3 -0
- package/dist/client/group-sealed-sender.d.ts.map +1 -1
- package/dist/client/group-sealed-sender.js +1 -0
- package/dist/client/group-sealed-sender.js.map +1 -1
- package/dist/client/group-sender-key-operations.d.ts +14 -3
- package/dist/client/group-sender-key-operations.d.ts.map +1 -1
- package/dist/client/group-sender-key-operations.js +26 -5
- package/dist/client/group-sender-key-operations.js.map +1 -1
- package/dist/client/groups.d.ts +5 -5
- package/dist/client/groups.d.ts.map +1 -1
- package/dist/client/groups.js +5 -4
- package/dist/client/groups.js.map +1 -1
- package/dist/client/hosted-anonymous-delivery.d.ts +61 -9
- package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
- package/dist/client/hosted-anonymous-delivery.js +242 -48
- package/dist/client/hosted-anonymous-delivery.js.map +1 -1
- package/dist/client/hosted-assertion-id.d.ts +7 -0
- package/dist/client/hosted-assertion-id.d.ts.map +1 -0
- package/dist/client/hosted-assertion-id.js +51 -0
- package/dist/client/hosted-assertion-id.js.map +1 -0
- package/dist/client/hosted-device-standing.d.ts +52 -0
- package/dist/client/hosted-device-standing.d.ts.map +1 -0
- package/dist/client/hosted-device-standing.js +74 -0
- package/dist/client/hosted-device-standing.js.map +1 -0
- package/dist/client/hosted-mailbox-subscription.d.ts +48 -3
- package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
- package/dist/client/hosted-mailbox-subscription.js +288 -74
- package/dist/client/hosted-mailbox-subscription.js.map +1 -1
- package/dist/client/hosted-push.d.ts +22 -4
- package/dist/client/hosted-push.d.ts.map +1 -1
- package/dist/client/hosted-push.js +75 -22
- package/dist/client/hosted-push.js.map +1 -1
- package/dist/client/hosted-transport.d.ts +22 -28
- package/dist/client/hosted-transport.d.ts.map +1 -1
- package/dist/client/hosted-transport.js +167 -69
- package/dist/client/hosted-transport.js.map +1 -1
- package/dist/client/hosted.d.ts +22 -5
- package/dist/client/hosted.d.ts.map +1 -1
- package/dist/client/hosted.js +122 -45
- package/dist/client/hosted.js.map +1 -1
- package/dist/client/index.d.ts +6 -4
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +3 -1
- package/dist/client/index.js.map +1 -1
- package/dist/client/messages.d.ts +25 -3
- package/dist/client/messages.d.ts.map +1 -1
- package/dist/client/messages.js +118 -17
- package/dist/client/messages.js.map +1 -1
- package/dist/client/one-time-prekey-refill.d.ts +7 -0
- package/dist/client/one-time-prekey-refill.d.ts.map +1 -1
- package/dist/client/one-time-prekey-refill.js +5 -1
- package/dist/client/one-time-prekey-refill.js.map +1 -1
- package/dist/client/receive-admission.d.ts +58 -0
- package/dist/client/receive-admission.d.ts.map +1 -0
- package/dist/client/receive-admission.js +78 -0
- package/dist/client/receive-admission.js.map +1 -0
- package/dist/client/receive-expiry.d.ts +31 -0
- package/dist/client/receive-expiry.d.ts.map +1 -0
- package/dist/client/receive-expiry.js +35 -0
- package/dist/client/receive-expiry.js.map +1 -0
- package/dist/client/receive-hook-bound.d.ts +50 -0
- package/dist/client/receive-hook-bound.d.ts.map +1 -0
- package/dist/client/receive-hook-bound.js +115 -0
- package/dist/client/receive-hook-bound.js.map +1 -0
- package/dist/client/receive-queue.d.ts +299 -0
- package/dist/client/receive-queue.d.ts.map +1 -0
- package/dist/client/receive-queue.js +1420 -0
- package/dist/client/receive-queue.js.map +1 -0
- package/dist/client/receive-work-seed.d.ts +54 -0
- package/dist/client/receive-work-seed.d.ts.map +1 -0
- package/dist/client/receive-work-seed.js +116 -0
- package/dist/client/receive-work-seed.js.map +1 -0
- package/dist/client/recovery-driver.d.ts +25 -0
- package/dist/client/recovery-driver.d.ts.map +1 -0
- package/dist/client/recovery-driver.js +121 -0
- package/dist/client/recovery-driver.js.map +1 -0
- package/dist/client/relay-acceptance.d.ts +30 -0
- package/dist/client/relay-acceptance.d.ts.map +1 -1
- package/dist/client/relay-acceptance.js +55 -0
- package/dist/client/relay-acceptance.js.map +1 -1
- package/dist/client/relay-device-refusal.d.ts +18 -0
- package/dist/client/relay-device-refusal.d.ts.map +1 -1
- package/dist/client/relay-device-refusal.js +31 -0
- package/dist/client/relay-device-refusal.js.map +1 -1
- package/dist/client/relay-sealed-route.d.ts +36 -0
- package/dist/client/relay-sealed-route.d.ts.map +1 -0
- package/dist/client/relay-sealed-route.js +45 -0
- package/dist/client/relay-sealed-route.js.map +1 -0
- package/dist/client/relay-subscription.d.ts +56 -13
- package/dist/client/relay-subscription.d.ts.map +1 -1
- package/dist/client/relay-subscription.js +220 -150
- package/dist/client/relay-subscription.js.map +1 -1
- package/dist/client/resendable-content.d.ts +98 -0
- package/dist/client/resendable-content.d.ts.map +1 -0
- package/dist/client/resendable-content.js +136 -0
- package/dist/client/resendable-content.js.map +1 -0
- package/dist/client/retry-family.d.ts +68 -19
- package/dist/client/retry-family.d.ts.map +1 -1
- package/dist/client/retry-family.js +59 -17
- package/dist/client/retry-family.js.map +1 -1
- package/dist/client/retry-request-envelope.d.ts +145 -18
- package/dist/client/retry-request-envelope.d.ts.map +1 -1
- package/dist/client/retry-request-envelope.js +301 -64
- package/dist/client/retry-request-envelope.js.map +1 -1
- package/dist/client/retry-request-lifecycle.d.ts +157 -0
- package/dist/client/retry-request-lifecycle.d.ts.map +1 -0
- package/dist/client/retry-request-lifecycle.js +437 -0
- package/dist/client/retry-request-lifecycle.js.map +1 -0
- package/dist/client/retry-terminal-recovery.d.ts +100 -0
- package/dist/client/retry-terminal-recovery.d.ts.map +1 -0
- package/dist/client/retry-terminal-recovery.js +164 -0
- package/dist/client/retry-terminal-recovery.js.map +1 -0
- package/dist/client/retry-utils.d.ts +27 -0
- package/dist/client/retry-utils.d.ts.map +1 -1
- package/dist/client/retry-utils.js +46 -0
- package/dist/client/retry-utils.js.map +1 -1
- package/dist/client/retry.d.ts +106 -18
- package/dist/client/retry.d.ts.map +1 -1
- package/dist/client/retry.js +687 -139
- package/dist/client/retry.js.map +1 -1
- package/dist/client/sealed-sender.d.ts +23 -6
- package/dist/client/sealed-sender.d.ts.map +1 -1
- package/dist/client/sealed-sender.js +30 -6
- package/dist/client/sealed-sender.js.map +1 -1
- package/dist/client/sessions.d.ts +2 -2
- package/dist/client/sessions.js +2 -2
- package/dist/client/signal-service-cipher.d.ts +726 -19
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +2265 -343
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/client/state.d.ts +5 -0
- package/dist/client/state.d.ts.map +1 -1
- package/dist/client/state.js +11 -1
- package/dist/client/state.js.map +1 -1
- package/dist/client/storage-protection.d.ts +64 -0
- package/dist/client/storage-protection.d.ts.map +1 -0
- package/dist/client/storage-protection.js +150 -0
- package/dist/client/storage-protection.js.map +1 -0
- package/dist/client/types.d.ts +149 -15
- package/dist/client/types.d.ts.map +1 -1
- package/dist/client/types.js +1 -1
- package/dist/client/types.js.map +1 -1
- package/dist/device/constants.d.ts +0 -5
- package/dist/device/constants.d.ts.map +1 -1
- package/dist/device/constants.js +0 -5
- package/dist/device/constants.js.map +1 -1
- package/dist/device/expo/index.d.ts +4 -17
- package/dist/device/expo/index.d.ts.map +1 -1
- package/dist/device/expo/index.js +4 -23
- package/dist/device/expo/index.js.map +1 -1
- package/dist/device/index.d.ts +0 -2
- package/dist/device/index.d.ts.map +1 -1
- package/dist/device/index.js +0 -7
- package/dist/device/index.js.map +1 -1
- package/dist/device/lifecycle/manager.d.ts +5 -4
- package/dist/device/lifecycle/manager.d.ts.map +1 -1
- package/dist/device/lifecycle/manager.js +16 -16
- package/dist/device/lifecycle/manager.js.map +1 -1
- package/dist/device/lifecycle/types.d.ts +2 -2
- package/dist/device/lifecycle/types.d.ts.map +1 -1
- package/dist/device/react-native/index.d.ts +4 -15
- package/dist/device/react-native/index.d.ts.map +1 -1
- package/dist/device/react-native/index.js +4 -21
- package/dist/device/react-native/index.js.map +1 -1
- package/dist/device/types.d.ts +1 -1
- package/dist/groups/index.d.ts +1 -1
- package/dist/groups/index.d.ts.map +1 -1
- package/dist/index.d.ts +8 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/internal/crypto/ec/x25519-validation.d.ts +0 -1
- package/dist/internal/crypto/ec/x25519-validation.d.ts.map +1 -1
- package/dist/internal/crypto/ec/x25519-validation.js +0 -1
- package/dist/internal/crypto/ec/x25519-validation.js.map +1 -1
- package/dist/internal/crypto/validation.d.ts +2 -2
- package/dist/internal/groups/index.d.ts +1 -0
- package/dist/internal/groups/index.d.ts.map +1 -1
- package/dist/internal/groups/index.js +1 -0
- package/dist/internal/groups/index.js.map +1 -1
- package/dist/internal/groups/manager.d.ts +37 -16
- package/dist/internal/groups/manager.d.ts.map +1 -1
- package/dist/internal/groups/manager.js +46 -1
- package/dist/internal/groups/manager.js.map +1 -1
- package/dist/internal/groups/receive-record.d.ts +78 -0
- package/dist/internal/groups/receive-record.d.ts.map +1 -0
- package/dist/internal/groups/receive-record.js +43 -0
- package/dist/internal/groups/receive-record.js.map +1 -0
- package/dist/internal/groups/sdk-store.d.ts +27 -3
- package/dist/internal/groups/sdk-store.d.ts.map +1 -1
- package/dist/internal/groups/sdk-store.js +151 -19
- package/dist/internal/groups/sdk-store.js.map +1 -1
- package/dist/internal/groups/wire.d.ts +12 -1
- package/dist/internal/groups/wire.d.ts.map +1 -1
- package/dist/internal/groups/wire.js +36 -0
- package/dist/internal/groups/wire.js.map +1 -1
- package/dist/internal/manager/index.d.ts +1 -1
- package/dist/internal/manager/manager.d.ts +20 -19
- package/dist/internal/manager/manager.d.ts.map +1 -1
- package/dist/internal/manager/manager.js +56 -39
- package/dist/internal/manager/manager.js.map +1 -1
- package/dist/internal/protocol/double-ratchet/chains.d.ts +4 -18
- package/dist/internal/protocol/double-ratchet/chains.d.ts.map +1 -1
- package/dist/internal/protocol/double-ratchet/chains.js +23 -74
- package/dist/internal/protocol/double-ratchet/chains.js.map +1 -1
- package/dist/internal/protocol/double-ratchet/index.d.ts +1 -1
- package/dist/internal/protocol/double-ratchet/index.d.ts.map +1 -1
- package/dist/internal/protocol/double-ratchet/index.js +1 -1
- package/dist/internal/protocol/double-ratchet/index.js.map +1 -1
- package/dist/internal/protocol/double-ratchet/ratchet.d.ts +5 -7
- package/dist/internal/protocol/double-ratchet/ratchet.d.ts.map +1 -1
- package/dist/internal/protocol/double-ratchet/ratchet.js +4 -6
- package/dist/internal/protocol/double-ratchet/ratchet.js.map +1 -1
- package/dist/internal/protocol/pqxdh/pqxdh.d.ts.map +1 -1
- package/dist/internal/protocol/pqxdh/pqxdh.js +2 -1
- package/dist/internal/protocol/pqxdh/pqxdh.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/types.d.ts +6 -8
- package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/types.js +8 -9
- package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
- package/dist/internal/protocol/sender-keys/handoff-ledger.d.ts +110 -0
- package/dist/internal/protocol/sender-keys/handoff-ledger.d.ts.map +1 -0
- package/dist/internal/protocol/sender-keys/handoff-ledger.js +124 -0
- package/dist/internal/protocol/sender-keys/handoff-ledger.js.map +1 -0
- package/dist/internal/protocol/sender-keys/manager.d.ts +71 -62
- package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
- package/dist/internal/protocol/sender-keys/manager.js +228 -175
- package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
- package/dist/internal/protocol/spqr/index.d.ts +2 -2
- package/dist/internal/protocol/spqr/index.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/index.js +2 -2
- package/dist/internal/protocol/spqr/index.js.map +1 -1
- package/dist/internal/protocol/spqr/serialize.d.ts +9 -1
- package/dist/internal/protocol/spqr/serialize.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/serialize.js +56 -16
- package/dist/internal/protocol/spqr/serialize.js.map +1 -1
- package/dist/internal/protocol/spqr/spqr.d.ts +1 -14
- package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/spqr.js +54 -42
- package/dist/internal/protocol/spqr/spqr.js.map +1 -1
- package/dist/internal/protocol/spqr/validate.d.ts +26 -6
- package/dist/internal/protocol/spqr/validate.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/validate.js +49 -21
- package/dist/internal/protocol/spqr/validate.js.map +1 -1
- package/dist/internal/sesame/index.d.ts +1 -1
- package/dist/internal/sesame/index.d.ts.map +1 -1
- package/dist/internal/sesame/index.js.map +1 -1
- package/dist/internal/sesame/manager.d.ts +66 -13
- package/dist/internal/sesame/manager.d.ts.map +1 -1
- package/dist/internal/sesame/manager.js +221 -87
- package/dist/internal/sesame/manager.js.map +1 -1
- package/dist/internal/sesame/types.d.ts +95 -17
- package/dist/internal/sesame/types.d.ts.map +1 -1
- package/dist/internal/sesame/types.js +17 -0
- package/dist/internal/sesame/types.js.map +1 -1
- package/dist/internal/session/builder.d.ts +5 -5
- package/dist/internal/session/builder.d.ts.map +1 -1
- package/dist/internal/session/builder.js +12 -17
- package/dist/internal/session/builder.js.map +1 -1
- package/dist/internal/session/cipher.d.ts +13 -11
- package/dist/internal/session/cipher.d.ts.map +1 -1
- package/dist/internal/session/cipher.js +40 -22
- package/dist/internal/session/cipher.js.map +1 -1
- package/dist/internal/session/factory.d.ts +5 -5
- package/dist/internal/session/factory.d.ts.map +1 -1
- package/dist/internal/session/factory.js +4 -4
- package/dist/internal/session/factory.js.map +1 -1
- package/dist/internal/session/handshake.d.ts +14 -16
- package/dist/internal/session/handshake.d.ts.map +1 -1
- package/dist/internal/session/handshake.js +18 -75
- package/dist/internal/session/handshake.js.map +1 -1
- package/dist/internal/session/index.d.ts +1 -1
- package/dist/internal/session/index.js +1 -1
- package/dist/internal/session/record-locks.d.ts +17 -6
- package/dist/internal/session/record-locks.d.ts.map +1 -1
- package/dist/internal/session/record-locks.js +43 -7
- package/dist/internal/session/record-locks.js.map +1 -1
- package/dist/internal/session/session-resolver.d.ts +1 -1
- package/dist/internal/session/session-resolver.js +1 -1
- package/dist/internal/session/state.d.ts +2 -2
- package/dist/internal/session/state.js +1 -1
- package/dist/internal/session/types.d.ts +4 -12
- package/dist/internal/session/types.d.ts.map +1 -1
- package/dist/internal/session/types.js +1 -1
- package/dist/keys/generation.d.ts +2 -2
- package/dist/keys/generation.js +2 -2
- package/dist/keys/types.d.ts +5 -5
- package/dist/keys/types.d.ts.map +1 -1
- package/dist/keys/types.js +1 -1
- package/dist/layers.d.ts +1 -1
- package/dist/layers.js +2 -2
- package/dist/layers.js.map +1 -1
- package/dist/local/store/expo/adapter.d.ts.map +1 -1
- package/dist/local/store/expo/adapter.js +12 -8
- package/dist/local/store/expo/adapter.js.map +1 -1
- package/dist/local/store/key-value/adapter.d.ts +76 -10
- package/dist/local/store/key-value/adapter.d.ts.map +1 -1
- package/dist/local/store/key-value/adapter.js +367 -61
- 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 +74 -0
- package/dist/local/store/key-value/backend-conformance.js.map +1 -1
- package/dist/local/store/key-value/batch.d.ts +2 -0
- package/dist/local/store/key-value/batch.d.ts.map +1 -1
- package/dist/local/store/key-value/batch.js +26 -0
- package/dist/local/store/key-value/batch.js.map +1 -1
- package/dist/local/store/key-value/receive-work.d.ts +55 -0
- package/dist/local/store/key-value/receive-work.d.ts.map +1 -0
- package/dist/local/store/key-value/receive-work.js +162 -0
- package/dist/local/store/key-value/receive-work.js.map +1 -0
- package/dist/local/store/key-value/send-log.d.ts +61 -0
- package/dist/local/store/key-value/send-log.d.ts.map +1 -0
- package/dist/local/store/key-value/send-log.js +430 -0
- package/dist/local/store/key-value/send-log.js.map +1 -0
- package/dist/local/store/key-value/sender-key-handoff.d.ts +68 -0
- package/dist/local/store/key-value/sender-key-handoff.d.ts.map +1 -0
- package/dist/local/store/key-value/sender-key-handoff.js +189 -0
- package/dist/local/store/key-value/sender-key-handoff.js.map +1 -0
- package/dist/local/store/key-value/storage.d.ts +15 -0
- package/dist/local/store/key-value/storage.d.ts.map +1 -1
- package/dist/local/store/keyed-index.d.ts +23 -0
- package/dist/local/store/keyed-index.d.ts.map +1 -0
- package/dist/local/store/keyed-index.js +41 -0
- package/dist/local/store/keyed-index.js.map +1 -0
- package/dist/local/store/memory/adapter.d.ts +44 -12
- package/dist/local/store/memory/adapter.d.ts.map +1 -1
- package/dist/local/store/memory/adapter.js +197 -46
- package/dist/local/store/memory/adapter.js.map +1 -1
- package/dist/local/store/memory/send-log.d.ts +42 -0
- package/dist/local/store/memory/send-log.d.ts.map +1 -0
- package/dist/local/store/memory/send-log.js +190 -0
- package/dist/local/store/memory/send-log.js.map +1 -0
- package/dist/local/store/node/adapter.d.ts.map +1 -1
- package/dist/local/store/node/adapter.js +8 -6
- package/dist/local/store/node/adapter.js.map +1 -1
- package/dist/local/store/react-native/adapter.d.ts.map +1 -1
- package/dist/local/store/react-native/adapter.js +12 -8
- package/dist/local/store/react-native/adapter.js.map +1 -1
- package/dist/local/store/receive-work.d.ts +87 -0
- package/dist/local/store/receive-work.d.ts.map +1 -0
- package/dist/local/store/receive-work.js +204 -0
- package/dist/local/store/receive-work.js.map +1 -0
- package/dist/local/store/received-content.d.ts +3 -3
- package/dist/local/store/received-content.d.ts.map +1 -1
- package/dist/local/store/received-content.js +2 -11
- package/dist/local/store/received-content.js.map +1 -1
- package/dist/local/store/reliability.d.ts +411 -14
- package/dist/local/store/reliability.d.ts.map +1 -1
- package/dist/local/store/reliability.js +532 -58
- package/dist/local/store/reliability.js.map +1 -1
- package/dist/local/store/send-log-order.d.ts +15 -0
- package/dist/local/store/send-log-order.d.ts.map +1 -0
- package/dist/local/store/send-log-order.js +24 -0
- package/dist/local/store/send-log-order.js.map +1 -0
- package/dist/local/store/sender-key-handoff-index.d.ts +38 -0
- package/dist/local/store/sender-key-handoff-index.d.ts.map +1 -0
- package/dist/local/store/sender-key-handoff-index.js +101 -0
- package/dist/local/store/sender-key-handoff-index.js.map +1 -0
- package/dist/local/store/sender-key-handoff-table.d.ts +29 -0
- package/dist/local/store/sender-key-handoff-table.d.ts.map +1 -0
- package/dist/local/store/sender-key-handoff-table.js +97 -0
- package/dist/local/store/sender-key-handoff-table.js.map +1 -0
- package/dist/local/store/sqlite/encryption.d.ts +8 -1
- package/dist/local/store/sqlite/encryption.d.ts.map +1 -1
- package/dist/local/store/sqlite/encryption.js +9 -0
- package/dist/local/store/sqlite/encryption.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/index.d.ts +25 -4
- package/dist/local/store/sqlite/key-storage/index.d.ts.map +1 -1
- package/dist/local/store/sqlite/key-storage/index.js +68 -7
- package/dist/local/store/sqlite/key-storage/index.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/message-records.d.ts +16 -4
- package/dist/local/store/sqlite/key-storage/message-records.d.ts.map +1 -1
- package/dist/local/store/sqlite/key-storage/message-records.js +49 -6
- package/dist/local/store/sqlite/key-storage/message-records.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/metadata.d.ts +8 -7
- package/dist/local/store/sqlite/key-storage/metadata.d.ts.map +1 -1
- package/dist/local/store/sqlite/key-storage/metadata.js +17 -15
- package/dist/local/store/sqlite/key-storage/metadata.js.map +1 -1
- package/dist/local/store/sqlite/key-storage/receive-work.d.ts +27 -0
- package/dist/local/store/sqlite/key-storage/receive-work.d.ts.map +1 -0
- package/dist/local/store/sqlite/key-storage/receive-work.js +98 -0
- package/dist/local/store/sqlite/key-storage/receive-work.js.map +1 -0
- package/dist/local/store/sqlite/key-storage/send-log.d.ts +27 -0
- package/dist/local/store/sqlite/key-storage/send-log.d.ts.map +1 -0
- package/dist/local/store/sqlite/key-storage/send-log.js +178 -0
- package/dist/local/store/sqlite/key-storage/send-log.js.map +1 -0
- package/dist/local/store/sqlite/key-storage/sender-key-handoff.d.ts +27 -0
- package/dist/local/store/sqlite/key-storage/sender-key-handoff.d.ts.map +1 -0
- package/dist/local/store/sqlite/key-storage/sender-key-handoff.js +75 -0
- package/dist/local/store/sqlite/key-storage/sender-key-handoff.js.map +1 -0
- package/dist/local/store/sqlite/key-storage/session-trust.d.ts +2 -2
- package/dist/local/store/sqlite/key-storage/session-trust.js +5 -5
- package/dist/local/store/sqlite/key-storage/session-trust.js.map +1 -1
- package/dist/local/store/sqlite/migrations.d.ts.map +1 -1
- package/dist/local/store/sqlite/migrations.js +101 -0
- package/dist/local/store/sqlite/migrations.js.map +1 -1
- package/dist/local/store/sqlite/models/index.d.ts +2 -1
- package/dist/local/store/sqlite/models/index.d.ts.map +1 -1
- package/dist/local/store/sqlite/models/index.js +5 -1
- package/dist/local/store/sqlite/models/index.js.map +1 -1
- package/dist/local/store/sqlite/models/message-record.d.ts +15 -0
- package/dist/local/store/sqlite/models/message-record.d.ts.map +1 -1
- package/dist/local/store/sqlite/models/message-record.js +24 -0
- package/dist/local/store/sqlite/models/message-record.js.map +1 -1
- package/dist/local/store/sqlite/models/send-log.d.ts +51 -0
- package/dist/local/store/sqlite/models/send-log.d.ts.map +1 -0
- package/dist/local/store/sqlite/models/send-log.js +206 -0
- package/dist/local/store/sqlite/models/send-log.js.map +1 -0
- package/dist/local/store/sqlite/open-store.d.ts +9 -1
- package/dist/local/store/sqlite/open-store.d.ts.map +1 -1
- package/dist/local/store/sqlite/open-store.js +20 -1
- package/dist/local/store/sqlite/open-store.js.map +1 -1
- package/dist/local/store/sqlite/schema.d.ts +34 -1
- package/dist/local/store/sqlite/schema.d.ts.map +1 -1
- package/dist/local/store/sqlite/schema.js +14 -0
- package/dist/local/store/sqlite/schema.js.map +1 -1
- package/dist/local/store/sqlite/store.d.ts +61 -11
- package/dist/local/store/sqlite/store.d.ts.map +1 -1
- package/dist/local/store/sqlite/store.js +191 -27
- package/dist/local/store/sqlite/store.js.map +1 -1
- package/dist/local/store/web/adapter.d.ts +76 -8
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +579 -127
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/local/store/web/receive-work.d.ts +57 -0
- package/dist/local/store/web/receive-work.d.ts.map +1 -0
- package/dist/local/store/web/receive-work.js +99 -0
- package/dist/local/store/web/receive-work.js.map +1 -0
- package/dist/local/store/web/send-log.d.ts +92 -0
- package/dist/local/store/web/send-log.d.ts.map +1 -0
- package/dist/local/store/web/send-log.js +267 -0
- package/dist/local/store/web/send-log.js.map +1 -0
- package/dist/local/store/web/sender-key-handoff.d.ts +81 -0
- package/dist/local/store/web/sender-key-handoff.d.ts.map +1 -0
- package/dist/local/store/web/sender-key-handoff.js +156 -0
- package/dist/local/store/web/sender-key-handoff.js.map +1 -0
- package/dist/local/store/web-sqlite/adapter.d.ts +2 -0
- package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
- package/dist/local/store/web-sqlite/adapter.js +12 -6
- package/dist/local/store/web-sqlite/adapter.js.map +1 -1
- package/dist/local/vault/custody.d.ts +8 -0
- package/dist/local/vault/custody.d.ts.map +1 -0
- package/dist/local/vault/custody.js +9 -0
- package/dist/local/vault/custody.js.map +1 -0
- package/dist/local/vault/electron-safe-storage.d.ts +3 -1
- package/dist/local/vault/electron-safe-storage.d.ts.map +1 -1
- package/dist/local/vault/electron-safe-storage.js +2 -0
- package/dist/local/vault/electron-safe-storage.js.map +1 -1
- package/dist/local/vault/expo-secure-store.d.ts +3 -1
- package/dist/local/vault/expo-secure-store.d.ts.map +1 -1
- package/dist/local/vault/expo-secure-store.js +2 -0
- package/dist/local/vault/expo-secure-store.js.map +1 -1
- package/dist/local/vault/indexed-db.d.ts +3 -1
- package/dist/local/vault/indexed-db.d.ts.map +1 -1
- package/dist/local/vault/indexed-db.js +2 -0
- package/dist/local/vault/indexed-db.js.map +1 -1
- package/dist/local/vault/react-native-keychain.d.ts +3 -1
- package/dist/local/vault/react-native-keychain.d.ts.map +1 -1
- package/dist/local/vault/react-native-keychain.js +2 -0
- package/dist/local/vault/react-native-keychain.js.map +1 -1
- package/dist/remote/relay/device-set.d.ts +94 -0
- package/dist/remote/relay/device-set.d.ts.map +1 -0
- package/dist/remote/relay/device-set.js +156 -0
- package/dist/remote/relay/device-set.js.map +1 -0
- package/dist/remote/relay/types.d.ts +104 -110
- package/dist/remote/relay/types.d.ts.map +1 -1
- package/dist/safety/core.d.ts +15 -6
- package/dist/safety/core.d.ts.map +1 -1
- package/dist/safety/core.js +41 -27
- package/dist/safety/core.js.map +1 -1
- package/dist/safety/index.d.ts +2 -1
- package/dist/safety/index.d.ts.map +1 -1
- package/dist/safety/index.js +12 -18
- package/dist/safety/index.js.map +1 -1
- package/dist/types/api.d.ts +707 -62
- package/dist/types/api.d.ts.map +1 -1
- package/dist/types/errors.d.ts +14 -33
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/errors.js +14 -24
- package/dist/types/errors.js.map +1 -1
- package/dist/types/messages.d.ts +2 -2
- package/dist/types/messages.js +1 -1
- package/dist/types/protocol-config.d.ts +175 -42
- package/dist/types/protocol-config.d.ts.map +1 -1
- package/dist/types/protocol-config.js +19 -38
- package/dist/types/protocol-config.js.map +1 -1
- package/dist/types/protocol-constants.d.ts +6 -6
- package/dist/types/protocol-constants.js +6 -6
- package/dist/types/session.d.ts +7 -7
- package/dist/types/session.d.ts.map +1 -1
- package/dist/types/session.js +39 -21
- package/dist/types/session.js.map +1 -1
- package/dist/username/link.d.ts +2 -2
- package/dist/username/link.js +2 -2
- package/dist/utils/origin-lock.d.ts +45 -0
- package/dist/utils/origin-lock.d.ts.map +1 -0
- package/dist/utils/origin-lock.js +80 -0
- package/dist/utils/origin-lock.js.map +1 -0
- package/dist/utils/retry.d.ts +2 -0
- package/dist/utils/retry.d.ts.map +1 -1
- package/dist/utils/retry.js +7 -0
- package/dist/utils/retry.js.map +1 -1
- package/docs/ASSURANCE.md +6 -6
- package/docs/CLIENT_COMPOSITION.md +2 -2
- package/docs/DEVIATIONS.md +677 -182
- package/docs/E2EE.md +1 -1
- package/docs/ERROR_HANDLING.md +235 -2
- package/docs/GETTING_STARTED.md +7 -4
- package/docs/INTERFACES.md +1 -1
- package/docs/PACKAGE_SURFACE.md +6 -5
- package/docs/PROTOCOL_POLICY.md +102 -22
- package/docs/RECIPES.md +3 -15
- package/docs/SECURITY.md +90 -5
- package/keys/README.md +3 -3
- package/local/store/README.md +78 -14
- package/local/store/key-value/README.md +14 -3
- package/local/store/node/README.md +8 -3
- package/local/store/web/README.md +9 -0
- package/local/store/web-sqlite/README.md +14 -2
- package/local/vault/README.md +21 -0
- package/package.json +1 -6
- package/remote/README.md +0 -1
- package/remote/relay/README.md +2 -2
- package/dist/device/provisioning.d.ts +0 -242
- package/dist/device/provisioning.d.ts.map +0 -1
- package/dist/device/provisioning.js +0 -421
- package/dist/device/provisioning.js.map +0 -1
- package/dist/internal/protocol/x3dh/index.d.ts +0 -15
- package/dist/internal/protocol/x3dh/index.d.ts.map +0 -1
- package/dist/internal/protocol/x3dh/index.js +0 -13
- package/dist/internal/protocol/x3dh/index.js.map +0 -1
- package/dist/internal/protocol/x3dh/x3dh.d.ts +0 -131
- package/dist/internal/protocol/x3dh/x3dh.d.ts.map +0 -1
- package/dist/internal/protocol/x3dh/x3dh.js +0 -261
- package/dist/internal/protocol/x3dh/x3dh.js.map +0 -1
package/docs/DEVIATIONS.md
CHANGED
|
@@ -73,20 +73,29 @@ model and what is out of scope.
|
|
|
73
73
|
|---|---|---|---|---|
|
|
74
74
|
| **Identity keys** | X3DH §2.2; `libsignal` `identity_key.rs` | **Deviation.** A 67-byte composite of separate X25519 and Ed25519 keys replaces the single 33-byte Curve25519 identity key | Avoids XEdDSA, a non-standard signature scheme with no vetted JavaScript implementation; standard Ed25519 is independently verifiable | Two keys to store and rotate; larger identity; **no wire compatibility for any identity-bearing material** |
|
|
75
75
|
| **Prekey signatures** | X3DH §2.2, §4.5 | **Deviation.** RFC 8032 Ed25519 over a domain-separated context binding the identity commitment, algorithm tag, and key ID — not XEdDSA over the bare key | Defeats cross-algorithm and cross-key-ID substitution that a bare-key signature does not cover | Strictly stronger binding; signatures are unverifiable by Signal Messenger clients and vice versa |
|
|
76
|
-
| **Safety numbers** | `libsignal` `fingerprint.rs` | **Deviation.** Iteration
|
|
77
|
-
| **
|
|
76
|
+
| **Safety numbers** | `libsignal` `fingerprint.rs` | **Deviation.** Iteration, digit encoding, and the order of the two halves are byte-identical, but the input is a composite-identity commitment under an SDK domain string, and the QR version is `4` | Follows from the composite identity; a single-key fingerprint cannot authenticate both components | **Safety numbers are not comparable to Signal Messenger's.** The low-level single-key path equals `libsignal`'s version 2 fingerprint |
|
|
77
|
+
| **PQXDH** | PQXDH rev. 3; X3DH rev. 1 for the shared DH steps | **Faithful** on DH order, the `0xFF`×32 prefix, zero-salt HKDF, KEM-secret position, and PQXDH §2.2's info-string construction. **Deviation:** ML-KEM-1024 (FIPS 203) replaces round-3 Kyber1024 | Standardized ML-KEM preferred over round-3 Kyber. The info string names it, and names this application rather than `libsignal`'s, as §2.1 and §2.2 require. PQXDH is required: no classical X3DH session exists | Wire-incompatible with `libsignal` by construction, and the label now says so. The info string is part of the derivation, so any peer that names a different one derives a different `SK` and cannot complete the handshake |
|
|
78
78
|
| **Associated data** | X3DH §3.3 | **Deviation.** `AD` is a domain-separated HMAC input over SHA-256 commitments to both composite identities, not `IK_A ‖ IK_B` | Binds the Ed25519 component, which a raw-key `AD` would leave uncovered | Stronger binding; wire-incompatible |
|
|
79
79
|
| **Double Ratchet** | Double Ratchet rev. 4 | **Faithful** on `WhisperRatchet`, `WhisperMessageKeys`, the `0x01`/`0x02` seeds, the 80-byte split, AES-256-CBC, the `0x44` version byte, and 8-byte MAC truncation | — | The ratchet core follows the Double Ratchet specification |
|
|
80
80
|
| **Message wire format** | `libsignal` `wire.proto` | **Faithful** field numbers 1–8. **Extension:** fields at 100+ carry identity type and ML-KEM one-time prekey material. **Deviation:** address binding uses variable-length UTF-8 user IDs and 4-byte device IDs instead of 17-byte ServiceIds and 1-byte device IDs | The SDK binds application-defined identifiers, not Signal Messenger ACIs | Wire-incompatible; a Signal Messenger client would silently ignore the added fields |
|
|
81
|
-
| **Skipped keys and archiving** | Double Ratchet §2.6; `libsignal` `consts.rs` | **Deviation.** The 2000-key cap
|
|
81
|
+
| **Skipped keys and archiving** | Double Ratchet §2.6, §8.4; `libsignal` `consts.rs` | **Deviation.** The 2000-key cap applies to each receiver chain, as in `libsignal`, and a full chain evicts its lowest index. Skipped keys also expire after 7 days, which `libsignal` does not do. Session records serialize as JSON, not protobuf | Double Ratchet §8.4 recommends the deletion of skipped keys after one week. A held key decrypts its message for as long as it stays, so the expiry bounds what a compromised device state exposes | The worst case is 5 receiver chains of 2000 keys each, in the current session and in each of up to 40 archived sessions. **A message more than 7 days out of order is undecryptable** where `libsignal` decrypts it |
|
|
82
82
|
| **Padding** | — | **Extension.** ISO 7816-4 bit padding to 160-byte buckets inside the library | Length hiding by default rather than left to the application | `libsignal` does not pad at this layer; Signal Messenger's apps do. PKCS#7 then adds a block, so ciphertext lands 16 bytes past each boundary |
|
|
83
83
|
| **SPQR / ML-KEM Braid** | ML-KEM Braid rev. 1 | **Deviation.** Same protocol, same KDF labels, same Reed–Solomon parameters, byte-identical message framing — except `hek = SHA3-256(ek_seed ‖ ek_vector)`, the operand order the specification states, which is the reverse of `libsignal`'s implementation | The normative text was followed over the executable reference | Wire-visible. Headers, ciphertexts, and shared secrets diverge; a braid session cannot complete a single epoch against `libsignal`'s implementation. Also means the KEM is not FIPS 203 in braid mode |
|
|
84
84
|
| **Triple Ratchet** | `libsignal` `triple_ratchet.rs` | **Faithful.** The PQ secret enters as the HKDF salt at message-key expansion, same label, same order | — | The braiding construction follows the ML-KEM Braid specification |
|
|
85
|
-
| **Sesame** | Sesame rev. 2 | **Deviation** on session expiry (§4.2 applies only to unacknowledged sessions)
|
|
85
|
+
| **Sesame** | Sesame rev. 2 | **Faithful** on deleted devices: a removed device is marked and kept for MAXLATENCY, and its archived sessions still decrypt. **Deviation** on session expiry (§4.2 applies only to unacknowledged sessions) and on device-list currency on the Convex relay only (the sender reads the relay's list at most once per 60 s). The Signal Protocol Relay and the memory relay reject a stale declared device set, as §3.3 requires. **Deviation** on stale-record cleanup timing (§5.1: the cleanup runs after the resume, not after a fetch of the whole mailbox, and the Relay's 30-day TTL cap bounds it). **Extensions:** device transfer, encrypted device names, identity-change gating, a 5-device cap | Product requirements the specification does not address | On the Convex relay, a device linked or removed less than 60 s ago can miss a send or still receive one. A client clock that moves forward against the Relay clock between a removal and the cleanup can lose a message accepted just before the removal. Device transfer copies the identity private key and no ratchet state, so each device starts its own sessions |
|
|
86
|
+
| **Device-set reconciliation** | Signal's server `MessageController`; Signal's Desktop client `sendToGroup` | **Deviation** in detail. The answer order, one post for each device of a direct send, a bound on direct sends, no empty sync post, a refusal for each not-found group destination, an acknowledgment marker, and a group body sealed again with the same ciphertext (§5.6) | The Relay takes one destination for each direct body, keeps one record for each account, admits an operation for 5 minutes, and stores each send attempt | A phase that does not match in 10 restarts fails the send with `DeviceSetReconciliationError`. A relay that does not acknowledge the comparison raises `DEVICE_SET_UNCHECKED` |
|
|
86
87
|
| **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
88
|
| **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
89
|
| **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. |
|
|
90
|
+
| **Sender-key distribution tracking** | Signal's Android client `SenderKeySharedTable`; Signal's Desktop client `sendToGroup` | **Deviation** in detail. The same events delete rows. A session or key write deletes them in the same write. The row match adds the key ID and compares the registration ID, as Signal's Desktop client does. A replay keeps its group ciphertext | The Relay refuses a second operation under one message ID. The SQLite, IndexedDB, and key-value stores keep the rows in durable storage, and the memory store keeps them in memory by design | A device that a replay adds gets the content only for a `Resendable` send |
|
|
91
|
+
| **Cross-tab locks** | Signal's Desktop and Android clients | **Faithful** in a browser: a group send and each session write take a Web Lock named by the store identity, so the tabs and workers of one origin run them one at a time. **Deviation** elsewhere: the lock orders one store object in one process | Signal runs one process for each device. Only the browser stores have a store identity, and Web Locks in Node order one process only | Two processes, or two store objects, that share one database need exclusive access from the application (§7.6) |
|
|
92
|
+
| **Group send route** | Signal's server, multi-recipient send | **Faithful** in the SDK: each group send goes to the anonymous group route with a group send token. The Relay still serves an identified group route that no SDK release calls | The Relay removes the identified route forward only | Until the removal, a client that posts to the identified route sends under its account credential, with no device-set check when the post declares none (§7.7) |
|
|
89
93
|
| **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 |
|
|
94
|
+
| **Receive order** | Signal's Android client | **Faithful.** The receive queue (`client/receive-queue.ts`) holds back the later records of one conversation, as Android queues its message jobs: group content per group, a sent transcript per destination, and other content per sender account. The commit order stays per sender device | — | A record that waits for its group state holds back the later content of its group from every sender until a fetch of its group or `syncGroup` completes, or until the record expires after 30 days. Direct chats and other groups make progress. A record in hook backoff holds back its conversation until its hook succeeds, it reaches the hook attempt cap of 10, or it expires. Before the queue restores a record, it keys the record by its stored group or by its sender account. A missing sender key does not hold the queue: that content goes to the retry request handler |
|
|
95
|
+
| **Receive hook attempt cap** | Signal's Desktop client | **Deviation.** After 10 failed `onMessageDecrypted` attempts, a record no longer holds back its conversation, as on Desktop. Desktop deletes the record at startup. The SDK keeps it, offers it to the hook once at each start, shows the count in `PendingReceive.hookAttempts`, and removes it at `discardPendingReceive` | The hook is application code. A drop loses content whose ratchet step is spent, and an application update can repair the hook | A hook that ends the process on the record ends it once at each start, until the record expires or the application discards it (§8.2) |
|
|
96
|
+
| **Receive hook bound** | Signal's Desktop client | **Deviation** in detail. Each application hook that a receive pass awaits has a bound, `receiveHookTimeoutMs`, 2 minutes by default. Desktop bounds its receive dispatch at 2 minutes and its long-running tasks at 30 minutes | A founder ruling sets the bound at 2 minutes. The SDK cannot tell a slow hook from a hung one | A timeout of `onMessageDecrypted` counts as one failed attempt. A timeout of another hook is logged, and the pass continues. A settle after the bound writes nothing (§8.4) |
|
|
97
|
+
| **Delivery receipt lifespan** | Signal's Android client | **Faithful.** A stored receipt is sent only within 1 day after it becomes owed, as Android's receipt job lives for 1 day. The receipt is durable across a restart, as on Android | — | A receipt that cannot go out within 1 day is not sent, and no hook reports it (§8.3) |
|
|
98
|
+
| **Receive admission bounds** | Signal's Desktop client | **Extension.** Before a decrypt, the receive queue checks `maxItems`, `maxBytes`, and the group share `blockedGroupShare`. The defaults are provisional. Desktop decrypts each envelope as it arrives and bounds stored content only by age and attempts | The SDK shares a storage budget with the application in a browser and on mobile | A refused envelope is not acknowledged. It stays at the Relay and expires there with no local hook. The messages behind it still arrive (§8.5) |
|
|
90
99
|
| **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
100
|
| **Registration IDs** | `libsignal` `sealed_sender.rs` | **Faithful.** Generated in `[1, 16383]`, strictly inside the 14 bits the wire format reserves | — | — |
|
|
92
101
|
|
|
@@ -193,47 +202,48 @@ the safety number Signal Messenger shows for the same two users. A user cannot
|
|
|
193
202
|
verify a contact by reading a number out of one application and comparing it
|
|
194
203
|
against the other.
|
|
195
204
|
|
|
196
|
-
|
|
205
|
+
Two independent reasons, either of which is sufficient.
|
|
197
206
|
|
|
198
207
|
**The SDK computes the user-facing number over a composite commitment.**
|
|
199
208
|
The `client.verify()` method uses `generateCompositeSafetyNumber`
|
|
200
|
-
(`client/sessions.ts:
|
|
209
|
+
(`client/sessions.ts:374`, `:436`). Its per-party hash iterates over
|
|
201
210
|
`UTF8("signal-protocol-js composite safety number v1") ‖ type-tagged user ID ‖
|
|
202
|
-
SHA-256 identity commitment` (`safety/core.ts:
|
|
211
|
+
SHA-256 identity commitment` (`safety/core.ts:52-54`, `:249-262`). None of that
|
|
203
212
|
input exists in `libsignal`'s construction ([`fingerprint.rs:161-192`][fp]).
|
|
204
213
|
|
|
205
214
|
**The identity material differs.** Even the raw input is a 67-byte two-key tuple
|
|
206
215
|
rather than a 33-byte `0x05 ‖ X25519` key.
|
|
207
216
|
|
|
208
|
-
**
|
|
209
|
-
|
|
210
|
-
`
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
are
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
`localeCompare` is also locale-sensitive. Two devices with different default
|
|
218
|
-
locales can in principle disagree on how to order the same pair of user IDs.
|
|
217
|
+
**The order of the two halves is faithful.** The party whose 30-digit display
|
|
218
|
+
string is lower by unsigned byte comparison comes first
|
|
219
|
+
(`safety/core.ts:186-226`), as in `libsignal` ([`fingerprint.rs:32-40`][fp]).
|
|
220
|
+
The SDK does not compare user identifiers, so neither the locale nor the
|
|
221
|
+
UTF-16 code-unit order can change the result. When the two display strings
|
|
222
|
+
are equal, the 60 digits do not depend on the order, and the full hash bytes
|
|
223
|
+
choose the first fingerprint, so both parties still produce the same hex and
|
|
224
|
+
emoji. The SDK's low-level single-key path is therefore byte-identical to
|
|
225
|
+
`libsignal`'s version 2 fingerprint (`safety/core.ts:43`).
|
|
219
226
|
|
|
220
227
|
Other parts *are* faithful. The iteration is byte-for-byte `libsignal`'s: 5200
|
|
221
228
|
iterations of SHA-512 over `0x0000 ‖ key ‖ id`, then `hash ‖ key`
|
|
222
|
-
(`safety/core.ts:
|
|
229
|
+
(`safety/core.ts:146-152` vs [`fingerprint.rs:170-189`][fp]). So is the digit
|
|
223
230
|
encoding (six 5-byte big-endian chunks mod 100000, 30 digits per party). So is
|
|
224
231
|
the scannable-fingerprint protobuf layout (`safety/protobuf.ts:94-109`). The
|
|
225
232
|
cross-verification swap and constant-time comparison match as well.
|
|
226
233
|
|
|
227
|
-
The QR format version is the SDK's own: `
|
|
228
|
-
(`safety/core.ts:
|
|
229
|
-
`VersionMismatch` for anything else. A distinct version in the same
|
|
230
|
-
namespace is the correct fail-closed choice. A Signal Messenger client
|
|
231
|
-
the code rather than misreading it.
|
|
234
|
+
The QR format version is the SDK's own: `4` for the composite path
|
|
235
|
+
(`safety/core.ts:45-50`), where `libsignal` knows only versions 1 and 2 and
|
|
236
|
+
returns `VersionMismatch` for anything else. A distinct version in the same
|
|
237
|
+
protobuf namespace is the correct fail-closed choice. A Signal Messenger client
|
|
238
|
+
rejects the code rather than misreading it. An earlier SDK ordered the two
|
|
239
|
+
halves by user ID under version `3`. A version `3` code reports
|
|
240
|
+
`version_mismatch` (`safety/fingerprint.ts:313-316`), so two parties never
|
|
241
|
+
compare numbers that two different order rules made.
|
|
232
242
|
|
|
233
|
-
The SDK also offers an emoji fingerprint (`safety/core.ts:
|
|
243
|
+
The SDK also offers an emoji fingerprint (`safety/core.ts:321-435`) and
|
|
234
244
|
verification deep links (`safety/url.ts`). Both are extensions with no
|
|
235
|
-
`libsignal` counterpart. The emoji form derives from
|
|
236
|
-
only. It therefore encodes roughly half of what the 60-digit number encodes.
|
|
245
|
+
`libsignal` counterpart. The emoji form derives from the fingerprint that comes
|
|
246
|
+
first only. It therefore encodes roughly half of what the 60-digit number encodes.
|
|
237
247
|
Do not present it to users as an equal-strength alternative.
|
|
238
248
|
|
|
239
249
|
### 1.4 Registration ID range
|
|
@@ -288,11 +298,10 @@ tagged `0x0A` rather than `0x08` (`internal/crypto/pq/kyber.ts:79`). That much i
|
|
|
288
298
|
deliberate. The SDK prefers the standardized algorithm over the round-3 draft,
|
|
289
299
|
and a single unambiguous tag over a legacy fallback.
|
|
290
300
|
|
|
291
|
-
The info
|
|
301
|
+
The info string is the SDK's own (`types/protocol-config.ts:624-638`):
|
|
292
302
|
|
|
293
303
|
```text
|
|
294
|
-
OpenE2EE_X25519_SHA-256_ML-KEM-1024
|
|
295
|
-
OpenE2EE (X3DH)
|
|
304
|
+
OpenE2EE_X25519_SHA-256_ML-KEM-1024
|
|
296
305
|
```
|
|
297
306
|
|
|
298
307
|
The SDK sets both implementer-chosen parameters to name itself and the KEM it
|
|
@@ -364,28 +373,30 @@ conditions (`internal/session/cipher.ts:1519-1527`).
|
|
|
364
373
|
Two differences at the boundary between key agreement and the ratchet:
|
|
365
374
|
|
|
366
375
|
**Alice reuses her key-agreement ephemeral as her first ratchet key**
|
|
367
|
-
(`internal/session/builder.ts:
|
|
376
|
+
(`internal/session/builder.ts:158-170`). By contrast, `libsignal` generates a
|
|
368
377
|
fresh sending ratchet key, distinct from the handshake ephemeral
|
|
369
378
|
([`ratchet.rs:77-81`][rat]). In `libsignal` the prekey message's base key and the
|
|
370
379
|
first message's ratchet key therefore differ. Here they are the same value. No
|
|
371
380
|
concrete attack follows, but the reuse weakens key separation and it is
|
|
372
381
|
wire-visible.
|
|
373
382
|
|
|
374
|
-
**Bob initializes without a sending chain** (`internal/session/builder.ts:
|
|
383
|
+
**Bob initializes without a sending chain** (`internal/session/builder.ts:318-356`),
|
|
375
384
|
deriving chains on the first DH ratchet, where `libsignal` seeds a sending chain
|
|
376
385
|
immediately ([`ratchet.rs:137-172`][rat]). A side effect is that bytes 32–64 of
|
|
377
386
|
the 96-byte derivation, the initial chain key, never produce a message key on
|
|
378
387
|
either side. The SDK keeps the 96-byte split for shape compatibility, but only
|
|
379
388
|
the root key and the SPQR key are load-bearing.
|
|
380
389
|
|
|
381
|
-
### 2.5
|
|
390
|
+
### 2.5 PQXDH is required
|
|
382
391
|
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
[
|
|
392
|
+
Every new session uses PQXDH. The SDK has no classical X3DH key agreement and
|
|
393
|
+
no setting that enables one. A peer bundle without an ML-KEM prekey fails with
|
|
394
|
+
`PQXDH_REQUIRED`, and any PQXDH failure raises rather than downgrading
|
|
395
|
+
(`internal/session/handshake.ts:156-408`). This matches `libsignal`, which
|
|
396
|
+
removed X3DH and rejects pre-Kyber prekey messages
|
|
397
|
+
([`session.rs:105-112`][sess]). A stored classical session continues as a
|
|
398
|
+
Double Ratchet session. [Protocol Policy](./PROTOCOL_POLICY.md) documents the
|
|
399
|
+
policy.
|
|
389
400
|
|
|
390
401
|
---
|
|
391
402
|
|
|
@@ -439,36 +450,36 @@ The SDK is also stricter than `libsignal` on decode. It requires fields that
|
|
|
439
450
|
lengths (`internal/encoding/proto/signal-message.ts:332-340`, `:488-505`). This
|
|
440
451
|
is safer, and it is one more reason the formats cannot meet.
|
|
441
452
|
|
|
442
|
-
### 3.3 Skipped-key retention
|
|
453
|
+
### 3.3 Skipped-key retention adds a 7-day expiry to libsignal's limits
|
|
443
454
|
|
|
444
|
-
The constants match: `MAX_MESSAGE_KEYS = 2000
|
|
445
|
-
(`internal/protocol/double-ratchet/ratchet.ts:194-
|
|
446
|
-
[`consts.rs:8-
|
|
447
|
-
|
|
455
|
+
The constants match: `MAX_MESSAGE_KEYS = 2000`, `MAX_FORWARD_JUMPS = 25000`, and
|
|
456
|
+
`MAX_RECEIVER_CHAINS = 5` (`internal/protocol/double-ratchet/ratchet.ts:194-207`
|
|
457
|
+
vs [`consts.rs:8-10`][consts]). The SDK applies the caps as `libsignal` does,
|
|
458
|
+
and it adds one limit that `libsignal` does not have.
|
|
448
459
|
|
|
449
|
-
**The cap is
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
evicts
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
one.
|
|
460
|
+
**The cap is per chain.** `libsignal` applies 2000 to the key vector of each
|
|
461
|
+
chain ([`double_ratchet.rs:346-361`][dr]). The SDK does the same
|
|
462
|
+
(`internal/protocol/double-ratchet/chains.ts:425-447`). A store to one chain
|
|
463
|
+
never evicts a key of another chain. The worst case is 5 receiver chains of
|
|
464
|
+
2000 keys each, in the current session and in each of up to 40 archived
|
|
465
|
+
sessions (`types/session.ts:800`).
|
|
456
466
|
|
|
457
|
-
**
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
467
|
+
**A full chain evicts its lowest index.** `libsignal` inserts each key at the
|
|
468
|
+
front and drops the last entry, which is the oldest insertion. The keys of one
|
|
469
|
+
chain are stored in index order, so the two rules drop the same key. The SDK
|
|
470
|
+
does not read the clock to choose the key.
|
|
461
471
|
|
|
462
472
|
**Skipped keys expire after 7 days**
|
|
463
|
-
(`internal/protocol/double-ratchet/ratchet.ts:
|
|
464
|
-
time-based expiry for message keys
|
|
473
|
+
(`internal/protocol/double-ratchet/ratchet.ts:180`). `libsignal` has no
|
|
474
|
+
time-based expiry for message keys. Double Ratchet §8.4 recommends this policy:
|
|
475
|
+
a held skipped key decrypts its message for as long as it stays, so a
|
|
476
|
+
compromise of the device state exposes each message whose key is held. The
|
|
477
|
+
expiry bounds that window.
|
|
465
478
|
|
|
466
|
-
|
|
467
|
-
this SDK
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
while older-chain messages are still in flight. The bounds are defensible as
|
|
471
|
-
storage hygiene. The consequence should not be a surprise.
|
|
479
|
+
The consequence: **a message more than 7 days out of order is undecryptable in
|
|
480
|
+
this SDK, and `libsignal` decrypts it.** This occurs when the recipient is
|
|
481
|
+
offline for more than a week, or when the message stays in transit for more
|
|
482
|
+
than a week.
|
|
472
483
|
|
|
473
484
|
Two related extensions go with this. A `processedChains` map rejects messages
|
|
474
485
|
that bear a ratchet key from a retired chain
|
|
@@ -479,22 +490,29 @@ where `libsignal` uses `usize::MAX`.
|
|
|
479
490
|
|
|
480
491
|
### 3.4 Session archiving and serialization
|
|
481
492
|
|
|
482
|
-
The cap matches: 40 archived states, [`consts.rs:11`][consts]. The
|
|
483
|
-
|
|
484
|
-
([`session.rs:
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
493
|
+
The cap matches: 40 archived states, [`consts.rs:11`][consts]. The eviction
|
|
494
|
+
order matches: `libsignal` drops the oldest insertion from its ordered list
|
|
495
|
+
([`session.rs:814-826`][st]), and the SDK drops the oldest insertion from its
|
|
496
|
+
archive (`types/session.ts:844-879`). The structure differs. The SDK keeps a
|
|
497
|
+
map keyed by base key. Archiving a session whose base key is already archived
|
|
498
|
+
moves that entry to the newest end rather than adding a second one, so the
|
|
499
|
+
effective history can be shorter than 40.
|
|
500
|
+
|
|
501
|
+
The archive clears the unacknowledged prekey state, as `libsignal` does
|
|
502
|
+
([`session.rs:814-826`][st] calls `clear_unacknowledged_pre_key_message`,
|
|
503
|
+
[`session.rs:566-589`][st]). `SessionRecord.archiveCurrent` and
|
|
504
|
+
`promoteSession` archive a copy of the session without the pending flag, the
|
|
505
|
+
prekey identifiers, and the KEM ciphertexts (`types/session.ts:824-834`). A
|
|
506
|
+
promoted session sends a SignalMessage, not a PreKeyMessage.
|
|
507
|
+
|
|
508
|
+
**Session records serialize as JSON, not protobuf**
|
|
509
|
+
(`local/store/session-codec.ts:10-24`). The constraint is that no Signal client
|
|
510
|
+
reads or writes an SDK store, so the stored format has no interoperability
|
|
511
|
+
requirement. The SDK session also has fields that the `libsignal` record has no
|
|
512
|
+
place for, such as the KEM one-time prekey ciphertext next to the Kyber
|
|
513
|
+
ciphertext (`types/session.ts:255-256`). One consequence is worth naming. Key
|
|
514
|
+
material sits in immutable JavaScript strings that nothing can zero, where
|
|
515
|
+
`libsignal` can zero its byte vectors.
|
|
498
516
|
|
|
499
517
|
### 3.5 Padding
|
|
500
518
|
|
|
@@ -519,8 +537,8 @@ sits 16 bytes past each boundary rather than on it.
|
|
|
519
537
|
## 4. SPQR and the ML-KEM Braid
|
|
520
538
|
|
|
521
539
|
This is the same protocol as the SparsePostQuantumRatchet v1 protocol, implemented
|
|
522
|
-
independently and pinned against commit `
|
|
523
|
-
`SparsePostQuantumRatchet v1.
|
|
540
|
+
independently and pinned against commit `06959b4`, which upstream tags
|
|
541
|
+
`SparsePostQuantumRatchet v1.6.0`. The fidelity is high and specific:
|
|
524
542
|
|
|
525
543
|
- **KDF labels are byte-identical**, including the double space in
|
|
526
544
|
`"Signal PQ Ratchet V1 Chain Start"` (`internal/crypto/kdf/hkdf.ts:353-368`).
|
|
@@ -537,18 +555,46 @@ independently and pinned against commit `fd32048`, which upstream tags
|
|
|
537
555
|
- **ML-KEM-768 with the same incremental split** (32-byte seed, 1152-byte vector,
|
|
538
556
|
960/128-byte ciphertext parts).
|
|
539
557
|
|
|
540
|
-
|
|
541
|
-
change upstream. Decoding a chain epoch direction now rejects a `next` chain key
|
|
542
|
-
whose length is neither zero nor 32 bytes. The internal next-key assertion checks
|
|
543
|
-
that same exact length rather than mere non-emptiness.
|
|
558
|
+
Two delta reviews moved the pin forward from `f2589fef`.
|
|
544
559
|
|
|
545
|
-
The
|
|
546
|
-
|
|
547
|
-
bytes
|
|
548
|
-
|
|
549
|
-
reject. The rest of
|
|
560
|
+
The step to `fd32048` found one behavioral change upstream. Decoding a chain
|
|
561
|
+
epoch direction now rejects a `next` chain key whose length is neither zero nor
|
|
562
|
+
32 bytes. The internal next-key assertion checks that same exact length rather
|
|
563
|
+
than mere non-emptiness. Two upstream error strings now name the value they
|
|
564
|
+
reject. The rest of that delta is proof-assistant annotation and loop rewriting,
|
|
550
565
|
which leaves behavior unchanged.
|
|
551
566
|
|
|
567
|
+
The SDK refuses the same key at a different point. The internal SPQR state
|
|
568
|
+
loader requires every chain key, root key, and skipped-message key to be
|
|
569
|
+
canonical base64 for exactly 32 bytes (`internal/protocol/spqr/serialize.ts:44-72`).
|
|
570
|
+
The production session load does not run that loader, and it does not check the
|
|
571
|
+
chain-key length. A stored wrong-length chain key fails at its first chain step,
|
|
572
|
+
because the chain KDF refuses a key that is not 32 bytes
|
|
573
|
+
(`internal/crypto/kdf/hkdf.ts:438-445`). Upstream refuses the key when it loads
|
|
574
|
+
the state. The SDK has no state in which the key is absent.
|
|
575
|
+
|
|
576
|
+
The step to `06959b4` has two commits that change behavior. `cb8a727` ("Improve
|
|
577
|
+
handling of higher-than-1 SPQR versions") moves preamble parsing into
|
|
578
|
+
`src/lib.rs` (`msg_preamble`) and moves the epoch-0 index-0 case into
|
|
579
|
+
`Chain::recv_key` (`src/chain.rs:417-419`). `a395789` ("Disallow unsupported
|
|
580
|
+
versions from turning off PQ ratcheting") makes an unknown version after
|
|
581
|
+
negotiation a `VersionMismatch` error. It also removes `displaydoc`, moves
|
|
582
|
+
`curve25519-dalek` to the dev-dependencies, and adds one lint attribute to
|
|
583
|
+
`polynomial.rs`. The changed files are `src/lib.rs`, `src/chain.rs`,
|
|
584
|
+
`src/v1/chunked/states.rs`, `src/v1/chunked/states/serialize.rs`,
|
|
585
|
+
`src/encoding/polynomial.rs`, `Cargo.toml`, `Cargo.lock`, and one upstream
|
|
586
|
+
test module. `Version::MAX` stays `V1` (`src/lib.rs:239`). No KDF label,
|
|
587
|
+
framing byte, or Reed–Solomon parameter changes.
|
|
588
|
+
|
|
589
|
+
The SDK behavior does not change. Upstream now returns an epoch-0 key for a
|
|
590
|
+
higher-version message before negotiation, and it refuses an unknown version
|
|
591
|
+
after negotiation. The SDK refuses a version byte other than 1 before
|
|
592
|
+
negotiation and ignores it after negotiation. Neither path occurs between v1
|
|
593
|
+
peers. The SDK fixes the braid version at 1
|
|
594
|
+
(`internal/protocol/spqr/ml-kem-braid/serialize.ts:270-272`,
|
|
595
|
+
`internal/protocol/spqr/spqr.ts:597`) and maps a version byte other than 1 to
|
|
596
|
+
`v0` (`internal/protocol/version.ts:254`, `:183-197`).
|
|
597
|
+
|
|
552
598
|
### 4.1 The `hek` operand order diverges
|
|
553
599
|
|
|
554
600
|
One divergence breaks interoperability completely. The SDK computes
|
|
@@ -607,10 +653,19 @@ analogue.
|
|
|
607
653
|
where `libsignal` uses an 11-variant `oneof` over nested structures. Serialized SPQR
|
|
608
654
|
state is not portable in either direction.
|
|
609
655
|
|
|
610
|
-
**
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
656
|
+
**Faithful.** The SPQR chain trims the held skipped keys of one epoch by
|
|
657
|
+
message index, as `libsignal`'s chain collects its key history. When an epoch
|
|
658
|
+
holds `max_ooo × 11/10 + 1` keys or more, 2201 by default, a receive drops each
|
|
659
|
+
key of that epoch whose index is below the receive counter minus `max_ooo`
|
|
660
|
+
(`internal/protocol/spqr/validate.ts:63-123`, called at
|
|
661
|
+
`internal/protocol/spqr/spqr.ts:1331`, vs `src/chain.rs:84-88` and `:146` at
|
|
662
|
+
`06959b4`). A jump past every held key clears the held keys of the epoch first
|
|
663
|
+
(`internal/protocol/spqr/spqr.ts:1273`, `:1320-1324` vs `src/chain.rs:266-270`). The
|
|
664
|
+
trim reads no clock. The horizon is equivalent: `libsignal` trims before it
|
|
665
|
+
steps its counter to the received index and so keeps one key that its refusal
|
|
666
|
+
rule (`src/chain.rs:192-194`) already refuses, and the SDK trims after the step
|
|
667
|
+
and keeps exactly the keys that the same rule accepts, so both decrypt the same
|
|
668
|
+
messages.
|
|
614
669
|
|
|
615
670
|
**Deviation.** The varint decoder is the stricter of the two. It rejects any
|
|
616
671
|
value above `uint64` (`internal/encoding/proto/pq-ratchet-serialize.ts:163-186`).
|
|
@@ -676,22 +731,68 @@ These parts are faithful:
|
|
|
676
731
|
The per-user identity model is one of the two models the specification permits
|
|
677
732
|
(§3.1).
|
|
678
733
|
|
|
679
|
-
### 5.1 The SDK
|
|
734
|
+
### 5.1 The SDK marks a removed device and keeps it for MAXLATENCY
|
|
680
735
|
|
|
681
736
|
§3.1 and §3.3 require an implementation to mark a removed device's record stale
|
|
682
737
|
and keep it for MAXLATENCY. Messages already in flight from that device then
|
|
683
|
-
still decrypt. The SDK
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
738
|
+
still decrypt. The SDK does this. A removal sets `removedAt` on the device
|
|
739
|
+
record, archives its current session, and keeps the record
|
|
740
|
+
(`internal/sesame/manager.ts:417-447`). A message that the device sent before
|
|
741
|
+
its removal therefore still decrypts against the archived session. Signal's
|
|
742
|
+
Android client also archives the session of a device that the server no longer
|
|
743
|
+
lists, in `SignalServiceMessageSender`. A send marks a device record in the
|
|
744
|
+
same way on two triggers:
|
|
745
|
+
|
|
746
|
+
- The relay no longer lists the device for the recipient (§5.5).
|
|
747
|
+
- On a relay that compares device sets, the send holds no message for the
|
|
748
|
+
account of the device, and the relay has no prekey bundle for the device
|
|
749
|
+
(`NOT_FOUND`). The Signal Protocol Relay gives that answer for an unregistered
|
|
750
|
+
device, and for a registered device that has no uploaded prekeys. The relay
|
|
751
|
+
can still list such a device.
|
|
752
|
+
|
|
753
|
+
A removed device gets no fan-out. One predicate, `isRemovedDevice`
|
|
754
|
+
(`internal/sesame/types.ts:347-355`), states the rule, and each device
|
|
755
|
+
enumeration of the send paths applies it. When the device list names the
|
|
756
|
+
device again, the marker clears, and the device returns to fan-out with no
|
|
757
|
+
current session. Its archived sessions stay
|
|
758
|
+
(`internal/sesame/manager.ts:449-483`).
|
|
759
|
+
|
|
760
|
+
The stale-record cleanup deletes a removed record when its removal is older
|
|
761
|
+
than `maxLatency`, 30 days by default (`internal/sesame/types.ts:357-369`,
|
|
762
|
+
`internal/sesame/manager.ts:2251-2261`). The receive queue runs the cleanup
|
|
763
|
+
once in each client run, after it resumes its stored receives. Nothing orders
|
|
764
|
+
the cleanup after a fetch of the whole mailbox, which §3.1 recommends.
|
|
765
|
+
|
|
766
|
+
The constraint is the message lifetime at the relay. The Signal Protocol Relay
|
|
767
|
+
caps the durable TTL of a message at 30 days (`MAX_DURABLE_TTL_SECONDS` in the
|
|
768
|
+
Relay mailbox contract). It enforces the cap when it parses a project and on
|
|
769
|
+
each request. The SDK fixes `maxLatency` at the same 30 days
|
|
770
|
+
(`internal/sesame/types.ts:114`), and no public client option sets it. The
|
|
771
|
+
removal clause is strict: the cleanup deletes the record only when
|
|
772
|
+
`now - removedAt > maxLatency`. A message that the Relay accepted before the
|
|
773
|
+
removal is therefore gone from the Relay before `maxLatency` passes after the
|
|
774
|
+
removal, and the record outlives it. The §3.1 guarantee for messages in flight
|
|
775
|
+
thus holds without a fetch of the whole mailbox. The Convex relay keeps a
|
|
776
|
+
message for 7 days (`remote/relay/convex/component/messages.ts:18`), so the
|
|
777
|
+
bound holds there too.
|
|
778
|
+
|
|
779
|
+
Two caveats limit the bound:
|
|
780
|
+
|
|
781
|
+
- **Clock skew.** The client measures the window on its own clock, and the
|
|
782
|
+
Relay measures the TTL on its clock. A fixed offset between the two clocks
|
|
783
|
+
cancels. If the client clock moves forward by e against the Relay clock
|
|
784
|
+
between the removal and the cleanup, the record goes e early. A message that
|
|
785
|
+
the Relay accepted up to e before the removal can then fail to decrypt.
|
|
786
|
+
- **Memory relay.** The in-process memory relay keeps a message with no TTL,
|
|
787
|
+
so the bound does not hold there. A message from a removed device that waits
|
|
788
|
+
there for longer than `maxLatency` after the removal can fail to decrypt.
|
|
789
|
+
|
|
790
|
+
Guarantee tests pin the default `maxLatency` at exactly 30 days, and assert
|
|
791
|
+
that no public client options type carries a `maxLatency` option.
|
|
792
|
+
|
|
793
|
+
The SDK also uses the word `stale` for a different concept: a device *list*
|
|
794
|
+
that needs refetching (`internal/sesame/types.ts:512-518`). The specification
|
|
795
|
+
uses the word for a deleted user or device, which the SDK calls removed.
|
|
695
796
|
|
|
696
797
|
### 5.2 Session expiry applies only to unacknowledged sessions
|
|
697
798
|
|
|
@@ -715,29 +816,18 @@ permits device IDs up to 127. The cap is a
|
|
|
715
816
|
product decision. A source comment credits it to the Signal Protocol, which is
|
|
716
817
|
inaccurate.
|
|
717
818
|
|
|
718
|
-
### 5.4 Extensions:
|
|
819
|
+
### 5.4 Extensions: transfer, device names
|
|
719
820
|
|
|
720
821
|
Sesame rev. 2 holds none of these. It says nothing about how a device comes to
|
|
721
822
|
exist, takes a name, or migrates.
|
|
722
823
|
|
|
723
|
-
**
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
**Device transfer** (`device/transfer.ts`). Clones the identity private key and
|
|
731
|
-
live ratchet state to a new device. This is useful, and it **breaks the invariant
|
|
732
|
-
that Sesame rests on**: one device record, one device, its own sessions. After a
|
|
733
|
-
transfer, two physical devices hold the same identity private key and the same
|
|
734
|
-
ratchet state for every peer.
|
|
735
|
-
|
|
736
|
-
A peer message that one device decrypts desynchronizes the other. The duplicated
|
|
737
|
-
ratchet state also weakens the
|
|
738
|
-
forward-secrecy guarantee that keeps the compromise of one endpoint within that
|
|
739
|
-
endpoint. Restore deliberately drops archived sessions, which discards the
|
|
740
|
-
convergence state that §3.4 needs.
|
|
824
|
+
**Device transfer** (`device/transfer.ts`). Copies the account identity key
|
|
825
|
+
pair, private key included, to a new device. The bundle holds no prekeys,
|
|
826
|
+
ratchet sessions, sender-key state, message state, or outbox state, and restore
|
|
827
|
+
rejects a bundle that holds one. The new device generates its own prekeys and
|
|
828
|
+
starts its own sessions, so each device keeps its own sessions as Sesame
|
|
829
|
+
requires. After a transfer, two physical devices hold the same identity private
|
|
830
|
+
key. That is the per-user identity model that the SDK selects.
|
|
741
831
|
|
|
742
832
|
**Encrypted device names** (`device/device-name-crypto.ts`). A three-field
|
|
743
833
|
protobuf carries a synthetic IV that HMAC derives, with AES-256-CTR. That is the
|
|
@@ -746,7 +836,7 @@ counterpart.
|
|
|
746
836
|
|
|
747
837
|
**Identity-change gating.** The SDK TOFU-pins an unseen identity. A changed
|
|
748
838
|
identity sets `pendingVerification` and blocks sending until the application
|
|
749
|
-
accepts the rotation (`internal/sesame/manager.ts:
|
|
839
|
+
accepts the rotation (`internal/sesame/manager.ts:702-706`, `:1843`). Sesame
|
|
750
840
|
rev. 2 has no such concept. This is a genuine improvement.
|
|
751
841
|
|
|
752
842
|
**Not implemented:** proof of possession. Registration does not make the device
|
|
@@ -754,49 +844,90 @@ sign a server-issued nonce with its identity private key. Registration therefore
|
|
|
754
844
|
trusts the relay more than §6.3 assumes. A deployment that needs proof of
|
|
755
845
|
possession must add it at the application layer.
|
|
756
846
|
|
|
757
|
-
### 5.5 The
|
|
847
|
+
### 5.5 The relay compares the declared device set
|
|
848
|
+
|
|
849
|
+
Reviewed: 2026-10-18.
|
|
758
850
|
|
|
759
851
|
§3.3 steps 3 and 4 make the server the check. The server accepts a send only
|
|
760
852
|
when the sender's list of device IDs is current, and otherwise rejects it with
|
|
761
|
-
the old and new device IDs.
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
853
|
+
the old and new device IDs.
|
|
854
|
+
|
|
855
|
+
The Signal Protocol Relay and the memory relay make this check. Each post to
|
|
856
|
+
an account declares the device IDs that the sender holds records for. The
|
|
857
|
+
relay compares the declaration with its device list and with the registration
|
|
858
|
+
of each device:
|
|
859
|
+
|
|
860
|
+
- When a device is missing or extra, it refuses the post with
|
|
861
|
+
`DEVICE_SET_MISMATCH` (409), and names the missing and the extra devices.
|
|
862
|
+
- When the registration of a device changed, it refuses the post with
|
|
863
|
+
`STALE_DEVICE` (410), and names those devices.
|
|
864
|
+
|
|
865
|
+
The SDK then removes each extra device record, starts a new session with each
|
|
866
|
+
missing or stale device, and encrypts the message again only for those
|
|
867
|
+
devices. It posts again with the repaired declaration. §5.6 lists the details
|
|
868
|
+
that differ from Signal.
|
|
869
|
+
|
|
870
|
+
On these relays, a send to a recipient with a session reads no device list. A
|
|
871
|
+
recipient with no session gets one list read to start the sessions. A group
|
|
872
|
+
send declares the devices of the records that it holds, and reads the list of
|
|
873
|
+
a member only when it holds no record for that member. The SDK reads the own
|
|
874
|
+
device list only when a recipient receipt sets `needsSync` and the sender
|
|
875
|
+
holds no record of another own device. One exception holds in a live send and
|
|
876
|
+
in a replay. A repair that leaves an account with no device record reads the
|
|
877
|
+
list of that account once.
|
|
878
|
+
|
|
879
|
+
The Convex relay does not compare device sets. With it, the SDK declares
|
|
880
|
+
nothing. It reads the recipient's device list (`getActiveDevices`) before a
|
|
881
|
+
direct send or a sender key distribution, when the last read for that
|
|
882
|
+
recipient is more than 60 s old (`RECIPIENT_DEVICE_LIST_FRESH_MILLISECONDS` in
|
|
769
883
|
`client/signal-service-cipher.ts`). It makes a session for each listed device
|
|
770
|
-
that has none,
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
**Consequence on the Signal Protocol Relay.** A device linked less than 60 s
|
|
786
|
-
before a send can miss that send. A device linked 60 s to 300 s before a send
|
|
787
|
-
receives it when the read in that send succeeds. A removed device receives no
|
|
788
|
-
message, because the Relay refuses the device's mailbox before the list shows
|
|
789
|
-
the removal. The 300 s maximum limits only how long a client posts first on a
|
|
790
|
-
list that no read confirmed.
|
|
791
|
-
|
|
792
|
-
**Consequence on the Convex and memory relays.** A device linked less than
|
|
793
|
-
60 s before a send can miss that send, and a device removed less than 60 s
|
|
794
|
-
before a send can still receive it.
|
|
884
|
+
that has none, marks each local device record that the relay does not list as
|
|
885
|
+
removed, and clears the mark of a removed record that the list names again
|
|
886
|
+
(§5.1). The time of the last read is kept in memory only, so a restarted client
|
|
887
|
+
reads the list on its first send to each recipient. Each send also reads the
|
|
888
|
+
own device list before it posts.
|
|
889
|
+
|
|
890
|
+
**Consequence on the Signal Protocol Relay and the memory relay.** A device
|
|
891
|
+
that is linked or removed before the relay accepts a post changes the answer
|
|
892
|
+
to that post. A linked device gets the message, and a removed device does not.
|
|
893
|
+
A phase of a send that does not match in 10 restarts fails the send with
|
|
894
|
+
`DeviceSetReconciliationError`.
|
|
895
|
+
|
|
896
|
+
**Consequence on the Convex relay.** A device linked less than 60 s before a
|
|
897
|
+
send can miss that send, and a device removed less than 60 s before a send can
|
|
898
|
+
still receive it.
|
|
795
899
|
|
|
796
900
|
The SESAME stale-device-list retry loop (`StaleDeviceListError`) stays in
|
|
797
901
|
`internal/sesame/manager.ts`, but no caller supplies a device-list version, so
|
|
798
902
|
it never runs.
|
|
799
903
|
|
|
904
|
+
### 5.6 Device-set reconciliation differs in detail
|
|
905
|
+
|
|
906
|
+
Reviewed: 2026-10-18.
|
|
907
|
+
|
|
908
|
+
The reconciliation of §5.5 follows Signal's server and Signal's Desktop
|
|
909
|
+
client in its rule: the server compares, the client repairs and posts again,
|
|
910
|
+
and a bound stops the loop. The bound of 10 restarts in each phase equals the
|
|
911
|
+
bound of Signal's Desktop client. It is stricter than the 4 attempts of
|
|
912
|
+
Signal's Android client. The following details differ.
|
|
913
|
+
|
|
914
|
+
| ID | Deviation | Constraint | Why Signal's form does not fit | Guarantee test |
|
|
915
|
+
|---|---|---|---|---|
|
|
916
|
+
| D1 | A stale registration is reported after missing and extra devices on every route, also for a direct post to one account | One answer order for every route | Signal's server reports stale devices first on its route for one account | Relay tests assert the order on each route |
|
|
917
|
+
| D2 | A direct send is one post for each device, and each post carries the full declaration of the account | The direct Relay route takes one destination for each body. A replay works for each device | One Signal request carries every device of the account. Here a race can accept some posts and refuse others | A restart posts the stored bytes to each accepted device, and each device gets the message once. A partly accepted pass posts every device again, and an accepted device replays |
|
|
918
|
+
| D3 | A group comparison reads the record of each account, up to 1,000, when the Relay accepts the post | The Relay keeps one record for each account | Signal's server reads accounts from one store in one process | Relay tests, and a cost measurement |
|
|
919
|
+
| D4 | The operation time is fixed. `OPERATION_EXPIRED` ends the reconciliation | The Relay admits an operation for 5 minutes | Signal has no admission window | A restart post that gets `OPERATION_EXPIRED` ends the phase as expired |
|
|
920
|
+
| D5 | No fallback to one post for each recipient after the bound | The same bound covers every path | Signal's Desktop client falls back because its one-to-one path has no bound. Under the bound, a fallback only moves the churn | The 11th refusal of a phase ends the send with `DeviceSetReconciliationError` |
|
|
921
|
+
| D6 | A direct send also stops at 10 restarts | One bound for every send | Signal's Desktop client has no bound on missing or extra devices for a one-to-one send | The restart bound test of the direct send |
|
|
922
|
+
| D7 | No empty sync post. A `needsSync` mark on the recipient receipt and one read of the own list replace it | A Relay post needs at least one destination | Signal's server accepts an empty sync list, and Signal's Android client addresses its own device | A new own device repairs the sync phase and the recipient post is not sent again. The own list is read only on `needsSync` with no own record, and a failed read leaves the sync phase pending |
|
|
923
|
+
| D8 | A group post settles a not-found account as a refusal of each of its destinations, and the Relay accepts the rest | `NOT_FOUND` is a fan-out result code. A refusal of the whole post would use a restart | This is equivalent to the group-send-token path of Signal's server, which sends to the accounts it resolves and returns the others. Only the form differs: a refusal code for each destination | A removed account settles as refused and the send adds nothing. A lost response resumes as a duplicate with no not-found account |
|
|
924
|
+
| D9 | The receipt of a declared post carries a `deviceSetChecked` mark | The identified Relay route passes unknown keys, and a deployment lane can lag the SDK | Signal ships its client and server together | A receipt without the mark raises `DEVICE_SET_UNCHECKED` through `onRelayProtocolError` |
|
|
925
|
+
| D10 | The SDK seals a group body again only before the Relay accepts it, and only after a definite refusal | The Relay keeps a fingerprint of each operation and answers `RETRY_CONFLICT` to a second body under the same ID | Signal stores nothing on the server for a send attempt | A refused body is replaced in one write. A crash before the post of the replaced body posts it on resume |
|
|
926
|
+
| D11 | A group restart keeps the group ciphertext, seals the shared body again, and replaces it in one write. It does not encrypt the content again | One group pass posts the same ciphertext in the shared body and in the device posts. A new ciphertext would change a device post that the Relay already accepted, and its replay would get `RETRY_CONFLICT` | Signal's Desktop client encrypts again for each attempt | The group ciphertext is byte-equal before and after the replacement, the accepted device post replays to its stored receipt, and the new body names the repaired destinations |
|
|
927
|
+
| D12 | A declared post with no `recipientRegistrationId` skips the registration check | The field is optional on every Relay route | Signal's server compares the registration of each device of a post | A Relay test posts an unnamed registration |
|
|
928
|
+
| D13 | A declaration that names the sender device gets 400 | The Relay refuses a malformed declaration before it compares | Signal's server answers 409 and names the sender device as an extra device | Relay tests on the direct and the group routes. The SDK does not declare the sender device |
|
|
929
|
+
| D14 | The identified group route compares the declared device set, with the codes and the order of the direct route | The route serves Relay API customers | Signal has no identified group route | Relay tests. No SDK code calls the route |
|
|
930
|
+
|
|
800
931
|
---
|
|
801
932
|
|
|
802
933
|
## 6. Sealed sender
|
|
@@ -818,26 +949,42 @@ The base trust-root loop also matches. It does not short-circuit and therefore
|
|
|
818
949
|
does not reveal which root validated. Required signed scope and issuer-validity
|
|
819
950
|
checks extend the upstream certificate semantics.
|
|
820
951
|
|
|
821
|
-
**`PLAINTEXT_CONTENT` (8)
|
|
822
|
-
`libsignal` uses
|
|
823
|
-
to encrypt one under ([`sealed_sender.rs:2055-2075`][ss]).
|
|
824
|
-
|
|
825
|
-
`
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
952
|
+
**`PLAINTEXT_CONTENT` (8) carries a sealed retry request, with an SDK payload.**
|
|
953
|
+
`libsignal` uses the type to carry a serialized `DecryptionErrorMessage` when
|
|
954
|
+
no session exists to encrypt one under ([`sealed_sender.rs:2055-2075`][ss]).
|
|
955
|
+
This SDK uses the same type for its own retry request (Sesame §4.1,
|
|
956
|
+
`client/retry-request-envelope.ts`). The sealed content is the small JSON
|
|
957
|
+
payload that the identified `retry_request` envelope carries, not a
|
|
958
|
+
`DecryptionErrorMessage`. The wire value matches. The payload does not.
|
|
959
|
+
|
|
960
|
+
A retry request follows the sealed sender delivery mode, as a delivery
|
|
961
|
+
receipt does. When the requester holds the access key of the target, it seals
|
|
962
|
+
the request, and the Relay does not see the requester. A group send
|
|
963
|
+
endorsement never seals a retry request. Without an access key, or when the
|
|
964
|
+
Relay refuses the access key, the request goes identified only in
|
|
965
|
+
`'preferred'` mode. In `'required'` mode the request never goes identified.
|
|
966
|
+
It stays pending, and the scheduler posts it again until its deadline. In
|
|
967
|
+
`'disabled'` mode it is always identified. An identified retry request shows
|
|
968
|
+
the Relay which device could not decrypt a message from which sender, so it
|
|
969
|
+
does not have the privacy of a sealed request.
|
|
970
|
+
|
|
971
|
+
The receive path accepts the type only for this route. The cipher unseals the
|
|
972
|
+
envelope, and a content type of 8 goes to the retry request handler, never to
|
|
973
|
+
a ratchet decrypt. The seal authenticates the requester: the authentication
|
|
974
|
+
tag binds the sealing key to the identity key of the sender certificate, and
|
|
975
|
+
the certificate must validate against the trust roots. `envelopeTypeForContent`
|
|
976
|
+
maps 8 to `retry_request`, so a new member without a route still fails loudly.
|
|
977
|
+
|
|
978
|
+
Note the cost when you debug interop. A `libsignal` peer that sends
|
|
979
|
+
`PLAINTEXT_CONTENT` with a `DecryptionErrorMessage` reaches the retry request
|
|
980
|
+
handler, which drops it as a malformed retry request. A shipped `11.0.x`
|
|
981
|
+
release of this SDK rejects the type at the parse. That receiver drops a
|
|
982
|
+
sealed retry request from a newer client, and the requester ends the request
|
|
983
|
+
as expired content. The parsers throw a single generic error for every
|
|
984
|
+
malformed envelope, `Sealed sender verification failed`, which is the same
|
|
985
|
+
string a MAC mismatch produces. The uniformity is deliberate, and the parse
|
|
986
|
+
runs after authentication, so nothing here is an oracle. Watch for one
|
|
987
|
+
pattern: sealed messages from one peer stack fail with that error while
|
|
841
988
|
messages from this SDK succeed. Check the leading content-type byte before you
|
|
842
989
|
treat that as a cryptographic failure.
|
|
843
990
|
|
|
@@ -904,7 +1051,7 @@ signing key as 33 bytes where the SDK uses 32.
|
|
|
904
1051
|
|
|
905
1052
|
### 7.2 Message-key derivation matches the reference
|
|
906
1053
|
|
|
907
|
-
Reviewed: 2026-10-
|
|
1054
|
+
Reviewed: 2026-10-11.
|
|
908
1055
|
|
|
909
1056
|
The SDK derives Sender Keys message material with HKDF-SHA256 Extract and
|
|
910
1057
|
Expand. Its input is `HMAC-SHA256(chain_key, 0x01)`, its salt is 32 zero bytes,
|
|
@@ -1008,6 +1155,354 @@ Credential serialization is also ad hoc and carries no version byte, where
|
|
|
1008
1155
|
`libsignal` uses a leading version byte. That is a forward-compatibility gap
|
|
1009
1156
|
rather than a security one.
|
|
1010
1157
|
|
|
1158
|
+
### 7.5 Sender-key distribution tracking
|
|
1159
|
+
|
|
1160
|
+
Reviewed: 2026-10-20.
|
|
1161
|
+
|
|
1162
|
+
`libsignal` creates and processes sender-key distribution messages. It does
|
|
1163
|
+
not record which devices hold a key. The Signal apps do that work.
|
|
1164
|
+
Signal-Android keeps a shared-with set for each distribution
|
|
1165
|
+
(`SenderKeySharedTable`). Signal-Desktop keeps the member devices with
|
|
1166
|
+
each sender key. The SDK keeps a handoff
|
|
1167
|
+
ledger for the same role. A row records that the Relay accepted a distribution
|
|
1168
|
+
of the own key for one device of another member. A send gives the key to each
|
|
1169
|
+
listed device with no matching row, and to each device with no session.
|
|
1170
|
+
|
|
1171
|
+
These parts follow Signal-Android:
|
|
1172
|
+
|
|
1173
|
+
- An inbound PreKey session deletes the rows of that device in every group.
|
|
1174
|
+
The SDK deletes them in the same write as the session. Signal-Android uses a
|
|
1175
|
+
separate write.
|
|
1176
|
+
- A session archive deletes the rows of that device in every group.
|
|
1177
|
+
- An identity change deletes the rows of the account.
|
|
1178
|
+
- A retry request for a group message deletes the rows of that device in that
|
|
1179
|
+
group only.
|
|
1180
|
+
- The session reset after an expired retry request deletes the rows of each
|
|
1181
|
+
device of the account in every group, as `AutomaticSessionResetJob` does.
|
|
1182
|
+
It does so for a group message and for a pairwise message. It archives the
|
|
1183
|
+
session with the device that sent the failed envelope only.
|
|
1184
|
+
- A rotation deletes the rows of the group. The SDK deletes them in the same
|
|
1185
|
+
write as the key.
|
|
1186
|
+
- Own devices get the sent transcript and no distribution.
|
|
1187
|
+
- When the Relay refuses a sync copy because the registration of the own
|
|
1188
|
+
device changed, the SDK starts a new session and posts the transcript
|
|
1189
|
+
again. Signal-Android tries a send up to 4 times. The SDK repairs each
|
|
1190
|
+
refused copy once, as it does each other refused post. A second refusal
|
|
1191
|
+
archives the session and drops the copy.
|
|
1192
|
+
|
|
1193
|
+
The following details differ:
|
|
1194
|
+
|
|
1195
|
+
**1. The row match includes the key ID and the registration ID**.
|
|
1196
|
+
Signal-Android keys a row by distribution and device. The registration-ID
|
|
1197
|
+
match is faithful to Signal-Desktop, which compares the registration IDs of
|
|
1198
|
+
the member devices. The key-ID match is an addition. A delete and then a
|
|
1199
|
+
create of the own key start again at generation 1, so the SDK also matches the
|
|
1200
|
+
key ID. A custom store can write the key and delete the rows in two writes,
|
|
1201
|
+
and a crash between them leaves a row. With the key ID in the match, that row
|
|
1202
|
+
never stops a device from getting the current key. A peer that holds the
|
|
1203
|
+
earlier key installs the new key, because the receiver matches a sender key by
|
|
1204
|
+
its ID and not by its generation.
|
|
1205
|
+
|
|
1206
|
+
**2. A new session from a prekey bundle deletes rows**. Signal-Android
|
|
1207
|
+
replaces a session only after an archive. In the SDK, the commit of a new
|
|
1208
|
+
session from a bundle archives the current session itself, so the same commit
|
|
1209
|
+
deletes the rows of the device.
|
|
1210
|
+
|
|
1211
|
+
**3. The SDK reads the own device list only on `needsSync`**. Signal learns
|
|
1212
|
+
of new and removed own devices from the 409 device-set mismatch answer of the
|
|
1213
|
+
server to a sync post, and it posts to the recipients first. The SDK keeps
|
|
1214
|
+
this order on the Signal Protocol Relay and the memory relay. The recipient
|
|
1215
|
+
phase posts first. Then the sync phase declares the own devices that the
|
|
1216
|
+
sender holds records for, and the relay compares them (§5.5). When a
|
|
1217
|
+
recipient receipt sets `needsSync` and the sender holds no record of another
|
|
1218
|
+
own device, the SDK reads the own list once (§5.6, D7). A failed read does
|
|
1219
|
+
not fail the send. The result carries `syncPending`, and a call to `send()`
|
|
1220
|
+
with the same `clientMessageId` reads the list again. The Convex relay does
|
|
1221
|
+
not compare device sets, so each send with it reads the own list before it
|
|
1222
|
+
posts. A failed read there stops the recipient post and fails the send or the
|
|
1223
|
+
sync API call.
|
|
1224
|
+
|
|
1225
|
+
**4. A replay keeps the stored group ciphertext**. Signal encrypts again for
|
|
1226
|
+
the devices of each attempt. The Relay refuses a second operation under the
|
|
1227
|
+
same message ID, so the replay of a stored group send keeps its ciphertext. A
|
|
1228
|
+
device that the replay adds cannot decrypt it. That device gets the content
|
|
1229
|
+
only through its retry request and the resend of a `Resendable` send.
|
|
1230
|
+
|
|
1231
|
+
**5. A sweep at start deletes the rows of a replaced key**. Signal has no
|
|
1232
|
+
sweep. The match already ignores these rows, so the sweep only frees storage.
|
|
1233
|
+
|
|
1234
|
+
**6. The Relay names each refused group destination**. Signal's server
|
|
1235
|
+
names each stale device in a 410 answer. The Relay refuses a declared group
|
|
1236
|
+
post with `DEVICE_SET_MISMATCH` or `STALE_DEVICE` before it accepts the post,
|
|
1237
|
+
and the SDK repairs as §5.5 says. The receipt of an accepted post carries a
|
|
1238
|
+
`refusals` list with a code for each refused destination. A `NOT_FOUND`
|
|
1239
|
+
refusal settles a removed account (§5.6, D8). The SDK does not infer a stale
|
|
1240
|
+
device from the count of refused destinations.
|
|
1241
|
+
|
|
1242
|
+
**7. Only a logged `Resendable` send can answer a retry request with its
|
|
1243
|
+
content** (2026-10-15). Signal-Android logs sends in its message send log
|
|
1244
|
+
through `MessageSendLogTables.insertIfPossible`. That method stores the
|
|
1245
|
+
content of a send only when the `retryReceipts` remote config is on, the send
|
|
1246
|
+
result is a success, and the result carries its content. For a group send, it
|
|
1247
|
+
stores one entry for the recipients whose result meets the last two
|
|
1248
|
+
conditions, and it stores no entry when no result does. The method does not
|
|
1249
|
+
read the content hint. A group send calls it only when its send operation
|
|
1250
|
+
returns true from `shouldIncludeInMessageLog`: a resendable data message or a
|
|
1251
|
+
story, and never a typing or call message (`GroupSendUtil`). A retry
|
|
1252
|
+
request for a group message with a log entry gets that content again. A
|
|
1253
|
+
request with no entry gets the sender-key distribution alone
|
|
1254
|
+
(`MessageContentProcessor`). Signal-Android keeps its own message
|
|
1255
|
+
database, so each resendable data message that it sends can have an
|
|
1256
|
+
entry. A data message sent through `sendUnresendableDataMessage`, such as
|
|
1257
|
+
a profile-key or group-call update, has none.
|
|
1258
|
+
|
|
1259
|
+
The constraint is that the SDK does not own the message store of the
|
|
1260
|
+
application. The SDK keeps a send log entry only for a group send whose
|
|
1261
|
+
content hint is `Resendable`. The SDK sets the hint by default from the
|
|
1262
|
+
content and the recovery policy. A group send of a `DataMessage` is
|
|
1263
|
+
`Resendable` when content recovery is on, and `Default` when it is off. A
|
|
1264
|
+
string or bytes send has no hint. The application can set another hint for a
|
|
1265
|
+
send. When it sets `Resendable` and the SDK cannot answer, because recovery
|
|
1266
|
+
is off or the content is a string or bytes, the send goes out as `Default`.
|
|
1267
|
+
So a retry request for another send finds no entry. The SDK then answers with the current
|
|
1268
|
+
distribution alone, as Signal-Android does for a missing entry. The device
|
|
1269
|
+
gets the key for later messages, but it does not get that message. Item 4
|
|
1270
|
+
makes this outcome more frequent, because a device that a replay adds can
|
|
1271
|
+
decrypt the send only through its retry request.
|
|
1272
|
+
|
|
1273
|
+
Two guarantee tests assert the two outcomes. For a send that is not `Resendable`, the send log has no entry, and
|
|
1274
|
+
the answer carries the current distribution and no message. For a
|
|
1275
|
+
`Resendable` send, the answer carries the message and the distribution.
|
|
1276
|
+
|
|
1277
|
+
**8. A receipt or a retry request keeps the stale session until the new
|
|
1278
|
+
session commits** (2026-10-16). Signal-Android archives the session of each
|
|
1279
|
+
stale device first (`SignalServiceMessageSender.handleStaleDevices`).
|
|
1280
|
+
The next pass of the send loop then fetches a bundle and starts a new
|
|
1281
|
+
session. Signal-Desktop also archives each stale session first, and then
|
|
1282
|
+
fetches the keys of the device (`handleMismatchedDevicesError`).
|
|
1283
|
+
When the fetch fails, an application job sends again later, and that send
|
|
1284
|
+
starts the session.
|
|
1285
|
+
|
|
1286
|
+
The constraint is that a receipt or a retry request has no application job
|
|
1287
|
+
that retries it. If the SDK archived first and the fetch failed, the item
|
|
1288
|
+
would have no session, and a lost session drops the item. So when the Relay
|
|
1289
|
+
refuses a receipt or a retry request as a stale device, the SDK fetches the
|
|
1290
|
+
bundle first. The session start then archives the stale session in the same
|
|
1291
|
+
record write that stores the new one. A failure before that write keeps the
|
|
1292
|
+
stale session, so the next post is refused again and refreshes again. A
|
|
1293
|
+
failure after that write, in the SESAME registration, leaves the new session,
|
|
1294
|
+
and the next post uses it. The `onSessionArchived` hook runs after the
|
|
1295
|
+
session start succeeds. The refresh of a send keeps the order of Signal: it
|
|
1296
|
+
archives the stale session first.
|
|
1297
|
+
|
|
1298
|
+
A guarantee test asserts the order. The
|
|
1299
|
+
first session start fails, the stale session stays, and the hook does not
|
|
1300
|
+
run. The retry refreshes the session, the hook runs once for the device, and
|
|
1301
|
+
the device decrypts the receipt.
|
|
1302
|
+
|
|
1303
|
+
**9. A late copy of a previous sender key changes nothing** (2026-10-16).
|
|
1304
|
+
Signal's published implementation keeps up to 5 sender-key states for each
|
|
1305
|
+
sender. When a distribution matches a kept state, [`add_sender_key_state`][sk]
|
|
1306
|
+
removes that state and puts it at the front of the record, so it becomes the
|
|
1307
|
+
current state again. The SDK also keeps up to 5 states and matches a
|
|
1308
|
+
distribution by its key ID. A distribution of the current key follows the
|
|
1309
|
+
generation rules of the SDK: a lower or the same generation changes nothing,
|
|
1310
|
+
and a higher generation replaces the current state in place. A distribution
|
|
1311
|
+
of a kept previous key changes nothing, and that state stays in its place.
|
|
1312
|
+
A distribution of another key becomes the current state, the earlier current
|
|
1313
|
+
state moves to the front of the previous states, and when the record already
|
|
1314
|
+
holds 5 states, the oldest state goes.
|
|
1315
|
+
So a replay of an installed distribution changes nothing only while its key
|
|
1316
|
+
is the current state or a kept previous state. When the key is neither, the
|
|
1317
|
+
replay installs it again as the current state, and when the record already
|
|
1318
|
+
holds 5 states, the oldest state goes.
|
|
1319
|
+
|
|
1320
|
+
The constraint is that the current state is the newest key that the sender
|
|
1321
|
+
installed. The receiver matches the current state first, so a late copy of
|
|
1322
|
+
an earlier key must not displace it. The cost is in the order of eviction.
|
|
1323
|
+
When the record holds K5, K4, K3, K2, and K1, with K5 current, a late copy of
|
|
1324
|
+
K1 and then K6 leave K6, K5, K4, K3, and K2 in the SDK. Signal keeps K1 and
|
|
1325
|
+
evicts K2. A message in flight under K1 then fails in the SDK.
|
|
1326
|
+
|
|
1327
|
+
A guarantee test asserts the rule. The receiver holds the replaced key as a
|
|
1328
|
+
previous state, and a late copy of its distribution arrives. The record keeps
|
|
1329
|
+
the new key current and the replaced key previous, and a message under the
|
|
1330
|
+
new key decrypts.
|
|
1331
|
+
|
|
1332
|
+
### 7.6 Group sends and session writes take a lock across tabs
|
|
1333
|
+
|
|
1334
|
+
Reviewed: 2026-10-20.
|
|
1335
|
+
|
|
1336
|
+
Signal runs one process for each device. Signal's Desktop client exits a
|
|
1337
|
+
second instance and runs the sender-key jobs of one address one at a time.
|
|
1338
|
+
Signal's Android client takes its session lock around each group encrypt.
|
|
1339
|
+
`libsignal`'s `group_encrypt` loads the sender-key record and stores it with
|
|
1340
|
+
no lock of its own, so the caller supplies the exclusion.
|
|
1341
|
+
|
|
1342
|
+
A browser application can open several tabs on one store. When
|
|
1343
|
+
`navigator.locks.request` exists and the store sets `storeIdentity`, the SDK
|
|
1344
|
+
takes a Web Lock for each group send and for each session write. A group send
|
|
1345
|
+
takes `open-e2ee:group-send:<store identity>:<lock key>`
|
|
1346
|
+
(`client/group-sender-key-operations.ts:41-57`). The session lock, the user
|
|
1347
|
+
lock, and the device-list sync lock take
|
|
1348
|
+
`open-e2ee:session:<store identity>:<lock key>`
|
|
1349
|
+
(`internal/session/record-locks.ts:60-142`). The IndexedDB store and the web
|
|
1350
|
+
SQLite store set `storeIdentity` to their database names. The tabs, workers,
|
|
1351
|
+
and clients of one origin that share the store then run one operation of each
|
|
1352
|
+
lock key at a time. Inside the group send lock, the sender-key manager reads
|
|
1353
|
+
its state from the store again, so a rotation keeps the states that another
|
|
1354
|
+
tab wrote. The session lock and the device-list sync lock keep their 5 s wait
|
|
1355
|
+
timeout, so a lock-order fault or a hung holder shows as an error and not as a
|
|
1356
|
+
receive or send that never ends. On the Web Lock path the wait rejects with
|
|
1357
|
+
`ORIGIN_LOCK_TIMEOUT_MESSAGE` (`utils/origin-lock.ts:18`). On the in-process
|
|
1358
|
+
path it rejects with the timeout message of the in-process lock. A Web Lock
|
|
1359
|
+
queue has no bound on the number of waiting requests.
|
|
1360
|
+
|
|
1361
|
+
**Deviation.** Where `navigator.locks.request` does not exist, or the store
|
|
1362
|
+
sets no identity, `originLockScope` gives no scope
|
|
1363
|
+
(`utils/origin-lock.ts:25-32`), and each lock is an in-process lock keyed by
|
|
1364
|
+
the store object. The constraint is that a Web Lock name needs a name for the
|
|
1365
|
+
data that every tab gives alike, and such a runtime has no shared lock or no
|
|
1366
|
+
such name.
|
|
1367
|
+
The Node SQLite, key-value, and memory stores set no identity, and React
|
|
1368
|
+
Native has no `navigator.locks`. Node has `navigator.locks`, but its locks
|
|
1369
|
+
order one process only. Two processes, or two store objects, that share one
|
|
1370
|
+
database are then not ordered. The application must give one of them
|
|
1371
|
+
exclusive access, as Signal's Desktop client does with its single-instance
|
|
1372
|
+
lock.
|
|
1373
|
+
|
|
1374
|
+
Guarantee tests assert both paths. Two browser tests open two tabs on one
|
|
1375
|
+
IndexedDB store. In the first, both tabs send to one group at the same time:
|
|
1376
|
+
the two ciphertexts carry distinct iterations, and the receiver decrypts each
|
|
1377
|
+
message. In the second, both tabs encrypt on one direct session at the same
|
|
1378
|
+
time: the two ciphertexts carry distinct counters, and the receiver decrypts
|
|
1379
|
+
each message. Unit tests assert the lock names, the order of two store
|
|
1380
|
+
objects with one identity, the in-process fallback with no Web Locks and with
|
|
1381
|
+
no identity, the 5 s session lock timeout and its message on each path, the
|
|
1382
|
+
stop of a wait, and two sender-key managers that rotate in turn and keep both
|
|
1383
|
+
states in the archive.
|
|
1384
|
+
|
|
1385
|
+
### 7.7 The SDK posts group sends to the anonymous route only
|
|
1386
|
+
|
|
1387
|
+
Reviewed: 2026-10-18.
|
|
1388
|
+
|
|
1389
|
+
Signal's server accepts a multi-recipient send only with an access key or a
|
|
1390
|
+
group send token, and it checks the device set of each recipient. The SDK
|
|
1391
|
+
posts each group send with a group send token to the anonymous group route of
|
|
1392
|
+
the Signal Protocol Relay (`client/hosted-anonymous-delivery.ts:269`, `:520`).
|
|
1393
|
+
No SDK release posts to the identified group route.
|
|
1394
|
+
|
|
1395
|
+
**Deviation in the Relay.** The Relay still serves the identified group
|
|
1396
|
+
route. It accepts a group post under the account credential of the sender,
|
|
1397
|
+
and it checks no device set when the post declares none. The constraint is
|
|
1398
|
+
that the Relay removes a served route forward only. The SDK does not depend on
|
|
1399
|
+
the route, so its removal changes no SDK behavior.
|
|
1400
|
+
|
|
1401
|
+
---
|
|
1402
|
+
|
|
1403
|
+
## 8. Receive queue
|
|
1404
|
+
|
|
1405
|
+
Reviewed: 2026-10-20.
|
|
1406
|
+
|
|
1407
|
+
The receive queue keeps each decrypted receive in the local store until the
|
|
1408
|
+
application hook accepts it and the receipt goes out (`client/receive-queue.ts`).
|
|
1409
|
+
Signal's Android client keeps the same work in its message jobs, and Signal's
|
|
1410
|
+
Desktop client keeps it in its table of unprocessed envelopes. This section
|
|
1411
|
+
states where the queue follows them and where it differs.
|
|
1412
|
+
|
|
1413
|
+
### 8.1 The queue holds back one conversation
|
|
1414
|
+
|
|
1415
|
+
**Faithful.** A record that waits holds back the later records of its
|
|
1416
|
+
conversation only (`client/receive-queue.ts:379-402`). Group content keys by
|
|
1417
|
+
its group, a sent transcript keys by its destination, and other content keys
|
|
1418
|
+
by its sender account, as Signal's Android client names its message job
|
|
1419
|
+
queues. A record that
|
|
1420
|
+
has not decrypted yet keys by its sender account, because its conversation is
|
|
1421
|
+
not known. The commit order stays per sender device, because the ratchet of
|
|
1422
|
+
one device must step in order.
|
|
1423
|
+
|
|
1424
|
+
Guarantee tests assert a record that fails before its restore and holds back
|
|
1425
|
+
only its sender account, a group record that holds back its group from every
|
|
1426
|
+
sender, pairwise content of a blocked group, and a second sender in a blocked
|
|
1427
|
+
group whose direct message delivers.
|
|
1428
|
+
|
|
1429
|
+
### 8.2 A failed hook has an attempt cap, and the record stays
|
|
1430
|
+
|
|
1431
|
+
**Deviation.** After `RECEIVE_HOOK_ATTEMPT_CAP`, 10 failed
|
|
1432
|
+
`onMessageDecrypted` attempts (`client/receive-queue.ts:285`), a record no
|
|
1433
|
+
longer holds back its conversation. Signal's Desktop client has the same cap.
|
|
1434
|
+
Desktop deletes such a record at startup and loses the message. The SDK keeps
|
|
1435
|
+
it.
|
|
1436
|
+
Each client start offers it to the hook once. After that offer, only
|
|
1437
|
+
`processPendingReceives` runs it again before the next start.
|
|
1438
|
+
`discardPendingReceive` removes it with no receipt, no hook call, and no
|
|
1439
|
+
expiry report. `PendingReceive` shows `hookAttempts`.
|
|
1440
|
+
|
|
1441
|
+
The constraint is that the hook is application code. The SDK cannot tell a
|
|
1442
|
+
lasting failure from a passing one. A drop loses content whose ratchet step is
|
|
1443
|
+
spent, and an application update can repair the hook. **Consequence:** a hook
|
|
1444
|
+
that ends the process on the record ends it once at each start, until the
|
|
1445
|
+
record expires or the application discards it.
|
|
1446
|
+
|
|
1447
|
+
Guarantee tests assert the offer once at start and not again at the hook
|
|
1448
|
+
registration, no second offer before the next start, and a discard with no
|
|
1449
|
+
receipt, no hook call, and no expiry report.
|
|
1450
|
+
|
|
1451
|
+
### 8.3 A delivery receipt lives for 1 day
|
|
1452
|
+
|
|
1453
|
+
**Faithful.** A stored receipt is sent only within `RECEIPT_LIFESPAN_MS`, 1
|
|
1454
|
+
day, after the receipt becomes owed (`client/receive-queue.ts:292`). Signal's
|
|
1455
|
+
Android client gives its receipt job the same lifespan, and it creates the
|
|
1456
|
+
job when the receipt becomes owed. The record keeps the receipt across a
|
|
1457
|
+
restart, as Android stores its job. At the end of the lifespan the record
|
|
1458
|
+
completes with no receipt and no report.
|
|
1459
|
+
|
|
1460
|
+
Guarantee tests assert a receipt 1 ms before the end of the lifespan, no
|
|
1461
|
+
receipt at the end, the recovery report of a resend record at the end, and
|
|
1462
|
+
the stop of the receipt retries of a running client.
|
|
1463
|
+
|
|
1464
|
+
### 8.4 Each awaited hook has a bound
|
|
1465
|
+
|
|
1466
|
+
**Deviation** in detail. A receive pass waits for each application hook for
|
|
1467
|
+
at most `receiveHookTimeoutMs`, 2 minutes by default
|
|
1468
|
+
(`client/receive-hook-bound.ts:36`). The value must be a positive integer no
|
|
1469
|
+
longer than the longest timer delay (`client/storage-protection.ts:169-179`).
|
|
1470
|
+
Signal's Desktop client bounds its receive dispatch at 2 minutes and its
|
|
1471
|
+
long-running tasks at 30 minutes.
|
|
1472
|
+
|
|
1473
|
+
The constraint is a founder ruling that sets the bound at 2 minutes. The SDK
|
|
1474
|
+
cannot tell a slow hook from a hung one, and one hung hook would otherwise
|
|
1475
|
+
stop all receive. **Consequence:** a timeout of `onMessageDecrypted` counts as
|
|
1476
|
+
one failed attempt, with the normal backoff and the attempt cap. A timeout of
|
|
1477
|
+
another hook is logged, and the pass continues. A settle after the bound
|
|
1478
|
+
writes nothing. A hook that needs longer than the bound fails each attempt.
|
|
1479
|
+
|
|
1480
|
+
Guarantee tests assert the 2-minute default, the refusal of an invalid bound,
|
|
1481
|
+
a hung `onMessageDecrypted` hook that counts one attempt for each pass, a
|
|
1482
|
+
late settle that writes nothing, and one timeout test for each other awaited
|
|
1483
|
+
hook.
|
|
1484
|
+
|
|
1485
|
+
### 8.5 Admission bounds before a decrypt
|
|
1486
|
+
|
|
1487
|
+
**Extension.** Before a decrypt, the receive queue checks `maxItems`,
|
|
1488
|
+
`maxBytes`, and the group share `blockedGroupShare`
|
|
1489
|
+
(`client/receive-admission.ts:67-96`). The defaults are 3000 items, 750 MiB,
|
|
1490
|
+
and 0.25. They are provisional until a measurement of real receive queues
|
|
1491
|
+
replaces them (`client/constants.ts:36-43`). Signal's Desktop client decrypts
|
|
1492
|
+
each envelope as it arrives and bounds stored content only by age and attempts.
|
|
1493
|
+
|
|
1494
|
+
The constraint is that the SDK shares a storage budget with the application
|
|
1495
|
+
in a browser and on mobile. **Consequence:** a refused envelope is not
|
|
1496
|
+
acknowledged. It stays at the Relay and expires there with no local hook. On
|
|
1497
|
+
the WebSocket path, other conversations progress. An HTTP pull sends the Relay
|
|
1498
|
+
cursor of the page before it, so a full page of refused envelopes does not stop
|
|
1499
|
+
the pages behind it. A page without a Relay cursor clears the stored cursor,
|
|
1500
|
+
and the next pull starts at the head. Two processes that share one store can
|
|
1501
|
+
each pass the check and overshoot a bound.
|
|
1502
|
+
|
|
1503
|
+
Guarantee tests assert the global item and byte bounds, the group item and
|
|
1504
|
+
byte shares, the progress of direct and other-group messages beside a full
|
|
1505
|
+
group, and an HTTP pull past a full page of refused envelopes.
|
|
1011
1506
|
---
|
|
1012
1507
|
|
|
1013
1508
|
## Unverified and needs review
|