@open-e2ee/signal-protocol-sdk 0.2.3 → 0.4.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 +11 -4
- package/ARCHITECTURE.md +19 -16
- package/CHANGELOG.md +72 -0
- package/COMMERCIAL.md +6 -6
- package/NOTICE +1 -1
- package/README.md +65 -93
- package/SECURITY.md +16 -13
- package/TROUBLESHOOTING.md +12 -5
- package/blocking/README.md +7 -5
- package/client/README.md +15 -5
- package/device/README.md +13 -8
- package/dist/blocking/types.d.ts +2 -2
- package/dist/blocking/types.js +2 -2
- package/dist/client/client.d.ts +46 -45
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +61 -60
- package/dist/client/client.js.map +1 -1
- package/dist/client/config.d.ts +32 -32
- package/dist/client/constants.d.ts +7 -6
- package/dist/client/constants.d.ts.map +1 -1
- package/dist/client/constants.js +5 -4
- package/dist/client/constants.js.map +1 -1
- package/dist/client/dual-store.d.ts +2 -2
- package/dist/client/dual-store.js +2 -2
- package/dist/client/endorsement-manager.d.ts +14 -14
- package/dist/client/endorsement-manager.d.ts.map +1 -1
- package/dist/client/endorsement-manager.js +15 -15
- package/dist/client/endorsement-manager.js.map +1 -1
- package/dist/client/event-hooks.d.ts +16 -16
- package/dist/client/event-hooks.d.ts.map +1 -1
- package/dist/client/event-hooks.js +1 -1
- package/dist/client/event-hooks.js.map +1 -1
- package/dist/client/files.js +4 -4
- package/dist/client/files.js.map +1 -1
- package/dist/client/groups.d.ts.map +1 -1
- package/dist/client/groups.js +14 -4
- package/dist/client/groups.js.map +1 -1
- package/dist/client/headless.d.ts +7 -7
- package/dist/client/headless.d.ts.map +1 -1
- package/dist/client/headless.js +4 -4
- package/dist/client/key-rotation-core.d.ts +19 -17
- package/dist/client/key-rotation-core.d.ts.map +1 -1
- package/dist/client/key-rotation-core.js +35 -31
- package/dist/client/key-rotation-core.js.map +1 -1
- package/dist/client/key-rotation.d.ts +8 -8
- package/dist/client/key-rotation.js +8 -8
- package/dist/client/media.d.ts +1 -1
- package/dist/client/messages.d.ts.map +1 -1
- package/dist/client/messages.js +13 -11
- package/dist/client/messages.js.map +1 -1
- package/dist/client/multi-device.d.ts +5 -4
- package/dist/client/multi-device.d.ts.map +1 -1
- package/dist/client/multi-device.js.map +1 -1
- package/dist/client/prekeys.d.ts +7 -7
- package/dist/client/prekeys.js +10 -10
- package/dist/client/prekeys.js.map +1 -1
- package/dist/client/relay-subscription.d.ts +3 -0
- package/dist/client/relay-subscription.d.ts.map +1 -1
- package/dist/client/relay-subscription.js +7 -4
- package/dist/client/relay-subscription.js.map +1 -1
- package/dist/client/retry-utils.d.ts +5 -6
- package/dist/client/retry-utils.d.ts.map +1 -1
- package/dist/client/retry-utils.js +5 -12
- package/dist/client/retry-utils.js.map +1 -1
- package/dist/client/retry.js +7 -7
- package/dist/client/retry.js.map +1 -1
- package/dist/client/sealed-sender-ops.d.ts +3 -3
- package/dist/client/sealed-sender-ops.js +5 -5
- package/dist/client/sealed-sender-ops.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 +9 -9
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +41 -40
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/client/state.d.ts +1 -1
- package/dist/client/state.js +1 -1
- package/dist/client/types.d.ts +19 -19
- package/dist/client/types.d.ts.map +1 -1
- package/dist/device/connection.d.ts +1 -1
- package/dist/device/connection.js +2 -2
- package/dist/device/connection.js.map +1 -1
- package/dist/device/constants.d.ts +4 -4
- package/dist/device/constants.js +3 -3
- package/dist/device/device-id.d.ts +4 -4
- package/dist/device/device-id.js +4 -4
- package/dist/device/expo-metadata.d.ts +13 -11
- package/dist/device/expo-metadata.d.ts.map +1 -1
- package/dist/device/expo-metadata.js +13 -11
- package/dist/device/expo-metadata.js.map +1 -1
- package/dist/device/lifecycle/manager.d.ts +6 -6
- package/dist/device/lifecycle/manager.js +7 -7
- package/dist/device/lifecycle/types.d.ts +13 -13
- package/dist/device/lifecycle/types.d.ts.map +1 -1
- package/dist/device/lifecycle/utils.d.ts +2 -2
- package/dist/device/lifecycle/utils.js +5 -5
- package/dist/device/lifecycle/utils.js.map +1 -1
- package/dist/device/provisioning.d.ts +5 -4
- package/dist/device/provisioning.d.ts.map +1 -1
- package/dist/device/provisioning.js +5 -4
- package/dist/device/provisioning.js.map +1 -1
- package/dist/device/transfer.d.ts +2 -2
- package/dist/device/transfer.js +3 -3
- package/dist/device/transfer.js.map +1 -1
- package/dist/encoding/index.d.ts +3 -4
- package/dist/encoding/index.d.ts.map +1 -1
- package/dist/encoding/index.js.map +1 -1
- package/dist/files/index.d.ts +1 -1
- package/dist/files/index.js +1 -1
- package/dist/hooks/use-connection-presence.d.ts +1 -1
- package/dist/hooks/use-connection-presence.js +7 -7
- package/dist/hooks/use-connection-presence.js.map +1 -1
- package/dist/hooks/use-group-membership.d.ts +2 -2
- package/dist/hooks/use-group-membership.d.ts.map +1 -1
- package/dist/hooks/use-group-membership.js +6 -6
- package/dist/hooks/use-group-membership.js.map +1 -1
- package/dist/hooks/use-key-rotation.js +3 -3
- package/dist/hooks/use-key-rotation.js.map +1 -1
- package/dist/hooks/use-single-flight.d.ts +2 -2
- package/dist/hooks/use-single-flight.js +1 -1
- package/dist/index.d.ts +4 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +21 -4
- package/dist/index.js.map +1 -1
- package/dist/internal/crypto/ec/ed25519.d.ts +6 -6
- package/dist/internal/crypto/ec/ed25519.js +6 -6
- package/dist/internal/crypto/ec/x25519-validation.d.ts.map +1 -1
- package/dist/internal/crypto/ec/x25519-validation.js +4 -2
- package/dist/internal/crypto/ec/x25519-validation.js.map +1 -1
- package/dist/internal/crypto/index.d.ts +2 -0
- package/dist/internal/crypto/index.d.ts.map +1 -1
- package/dist/internal/crypto/index.js +2 -0
- package/dist/internal/crypto/index.js.map +1 -1
- package/dist/internal/crypto/kdf/hkdf.d.ts +9 -8
- package/dist/internal/crypto/kdf/hkdf.d.ts.map +1 -1
- package/dist/internal/crypto/kdf/hkdf.js +11 -10
- package/dist/internal/crypto/kdf/hkdf.js.map +1 -1
- package/dist/internal/crypto/key-prefix.d.ts +3 -3
- package/dist/internal/crypto/key-prefix.js +3 -3
- package/dist/internal/crypto/pq/kyber.d.ts +7 -7
- package/dist/internal/crypto/pq/kyber.js +10 -10
- package/dist/internal/crypto/pq/kyber.js.map +1 -1
- package/dist/internal/crypto/random.d.ts +1 -1
- package/dist/internal/crypto/random.js +1 -1
- package/dist/internal/crypto/symmetric/aes-gcm-siv.js +1 -1
- package/dist/internal/crypto/symmetric/aes.js +4 -4
- package/dist/internal/crypto/symmetric/aes.js.map +1 -1
- package/dist/internal/crypto/symmetric/mac.d.ts +1 -1
- package/dist/internal/crypto/symmetric/mac.js +3 -3
- package/dist/internal/crypto/symmetric/padding.js +1 -1
- package/dist/internal/crypto/symmetric/padding.js.map +1 -1
- package/dist/internal/crypto/symmetric/streaming-aead.d.ts +7 -1
- package/dist/internal/crypto/symmetric/streaming-aead.d.ts.map +1 -1
- package/dist/internal/crypto/symmetric/streaming-aead.js +10 -4
- package/dist/internal/crypto/symmetric/streaming-aead.js.map +1 -1
- package/dist/internal/crypto/utils.d.ts +2 -2
- package/dist/internal/crypto/utils.d.ts.map +1 -1
- package/dist/internal/crypto/utils.js +16 -14
- package/dist/internal/crypto/utils.js.map +1 -1
- package/dist/internal/crypto/validation.d.ts +4 -4
- package/dist/internal/crypto/validation.js +2 -2
- package/dist/internal/encoding/proto/envelope.d.ts +1 -1
- package/dist/internal/encoding/proto/envelope.js +1 -1
- package/dist/internal/encoding/proto/index.d.ts +4 -4
- package/dist/internal/encoding/proto/index.js +4 -4
- package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts +28 -16
- package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts.map +1 -1
- package/dist/internal/encoding/proto/pq-ratchet-serialize.js +30 -18
- package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
- package/dist/internal/encoding/proto/primitives.d.ts +45 -35
- package/dist/internal/encoding/proto/primitives.d.ts.map +1 -1
- package/dist/internal/encoding/proto/primitives.js +54 -43
- package/dist/internal/encoding/proto/primitives.js.map +1 -1
- package/dist/internal/encoding/proto/sender-key-message.d.ts +2 -2
- package/dist/internal/encoding/proto/sender-key-message.js +2 -2
- package/dist/internal/encoding/proto/signal-message.d.ts +13 -13
- package/dist/internal/encoding/proto/signal-message.d.ts.map +1 -1
- package/dist/internal/encoding/proto/signal-message.js +13 -13
- package/dist/internal/encoding/proto/signal-message.js.map +1 -1
- package/dist/internal/groups/access-control.d.ts +5 -5
- package/dist/internal/groups/access-control.js +6 -6
- package/dist/internal/groups/access-control.js.map +1 -1
- package/dist/internal/groups/change-actions.d.ts +4 -4
- package/dist/internal/groups/change-actions.js +3 -3
- package/dist/internal/groups/encrypted-state.js +1 -1
- package/dist/internal/groups/encrypted-state.js.map +1 -1
- package/dist/internal/groups/group-id.d.ts +1 -1
- package/dist/internal/groups/manager.d.ts +24 -23
- package/dist/internal/groups/manager.d.ts.map +1 -1
- package/dist/internal/groups/manager.js +40 -36
- package/dist/internal/groups/manager.js.map +1 -1
- package/dist/internal/groups/server-engine.d.ts +29 -21
- package/dist/internal/groups/server-engine.d.ts.map +1 -1
- package/dist/internal/groups/server-engine.js +55 -50
- package/dist/internal/groups/server-engine.js.map +1 -1
- package/dist/internal/groups/trust-root.d.ts +2 -2
- package/dist/internal/groups/trust-root.js +2 -2
- package/dist/internal/groups/types.d.ts +4 -4
- package/dist/internal/groups/types.d.ts.map +1 -1
- package/dist/internal/groups/wire.d.ts +6 -7
- package/dist/internal/groups/wire.d.ts.map +1 -1
- package/dist/internal/groups/wire.js +6 -7
- package/dist/internal/groups/wire.js.map +1 -1
- package/dist/internal/manager/manager.d.ts +14 -12
- package/dist/internal/manager/manager.d.ts.map +1 -1
- package/dist/internal/manager/manager.js +47 -41
- package/dist/internal/manager/manager.js.map +1 -1
- package/dist/internal/protocol/double-ratchet/chains.d.ts +8 -6
- package/dist/internal/protocol/double-ratchet/chains.d.ts.map +1 -1
- package/dist/internal/protocol/double-ratchet/chains.js +10 -8
- package/dist/internal/protocol/double-ratchet/chains.js.map +1 -1
- package/dist/internal/protocol/double-ratchet/index.d.ts +2 -2
- package/dist/internal/protocol/double-ratchet/index.js +2 -2
- package/dist/internal/protocol/double-ratchet/ratchet.d.ts +4 -4
- package/dist/internal/protocol/double-ratchet/ratchet.js +6 -6
- package/dist/internal/protocol/pqxdh/pqxdh.d.ts +21 -18
- package/dist/internal/protocol/pqxdh/pqxdh.d.ts.map +1 -1
- package/dist/internal/protocol/pqxdh/pqxdh.js +48 -42
- package/dist/internal/protocol/pqxdh/pqxdh.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/decryption-v2.js +5 -5
- package/dist/internal/protocol/sealed-sender/decryption-v2.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/decryption.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/decryption.js +11 -8
- package/dist/internal/protocol/sealed-sender/decryption.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/delivery-token.d.ts +2 -2
- package/dist/internal/protocol/sealed-sender/delivery-token.js +2 -2
- package/dist/internal/protocol/sealed-sender/encryption-v2.js +1 -1
- package/dist/internal/protocol/sealed-sender/encryption-v2.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/encryption.d.ts +2 -2
- package/dist/internal/protocol/sealed-sender/encryption.js +2 -2
- package/dist/internal/protocol/sealed-sender/proto/index.d.ts +25 -23
- package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/proto/index.js +32 -30
- package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/trust-root.d.ts +10 -9
- package/dist/internal/protocol/sealed-sender/trust-root.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/trust-root.js +10 -9
- package/dist/internal/protocol/sealed-sender/trust-root.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/types.d.ts +13 -14
- package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/types.js +7 -8
- package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/v2-binary.d.ts +1 -1
- package/dist/internal/protocol/sealed-sender/v2-binary.js +2 -2
- package/dist/internal/protocol/sealed-sender/v2-binary.js.map +1 -1
- package/dist/internal/protocol/sender-keys/manager.d.ts +16 -14
- package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
- package/dist/internal/protocol/sender-keys/manager.js +37 -34
- package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
- package/dist/internal/protocol/spqr/braid-serialize.d.ts +6 -6
- package/dist/internal/protocol/spqr/braid-serialize.js +5 -5
- package/dist/internal/protocol/spqr/braid-serialize.js.map +1 -1
- package/dist/internal/protocol/spqr/braid.d.ts +3 -3
- package/dist/internal/protocol/spqr/braid.js +7 -7
- package/dist/internal/protocol/spqr/braid.js.map +1 -1
- package/dist/internal/protocol/spqr/index.js +1 -1
- package/dist/internal/protocol/spqr/index.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/chunk-domain.d.ts +3 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/chunk-domain.js +3 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/kdf.d.ts +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/kdf.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/kdf.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.d.ts +4 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.js +4 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/index.js +2 -2
- package/dist/internal/protocol/spqr/ml-kem-braid/progress.d.ts +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/progress.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts +15 -7
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js +15 -7
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/galois/field.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/polynomial.d.ts +3 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/polynomial.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts +7 -7
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js +11 -11
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.d.ts +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js +6 -6
- package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts +2 -2
- package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/types.js.map +1 -1
- package/dist/internal/protocol/spqr/serialize.d.ts +12 -12
- package/dist/internal/protocol/spqr/serialize.js +5 -5
- package/dist/internal/protocol/spqr/spqr.d.ts +6 -6
- package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/spqr.js +47 -42
- package/dist/internal/protocol/spqr/spqr.js.map +1 -1
- package/dist/internal/protocol/spqr/validate.d.ts +1 -1
- package/dist/internal/protocol/triple-ratchet/ratchet.d.ts +12 -12
- package/dist/internal/protocol/triple-ratchet/ratchet.d.ts.map +1 -1
- package/dist/internal/protocol/triple-ratchet/ratchet.js +11 -11
- package/dist/internal/protocol/triple-ratchet/ratchet.js.map +1 -1
- package/dist/internal/protocol/username/hash.d.ts.map +1 -1
- package/dist/internal/protocol/username/hash.js +6 -4
- package/dist/internal/protocol/username/hash.js.map +1 -1
- package/dist/internal/protocol/version.d.ts +3 -3
- package/dist/internal/protocol/version.js +1 -1
- package/dist/internal/protocol/x3dh/x3dh.d.ts +16 -16
- package/dist/internal/protocol/x3dh/x3dh.d.ts.map +1 -1
- package/dist/internal/protocol/x3dh/x3dh.js +15 -15
- package/dist/internal/protocol/x3dh/x3dh.js.map +1 -1
- package/dist/internal/protocol/zk/credentials/attributes.d.ts +7 -7
- package/dist/internal/protocol/zk/credentials/attributes.js +7 -7
- package/dist/internal/protocol/zk/credentials/credentials.d.ts +1 -1
- package/dist/internal/protocol/zk/credentials/credentials.js +1 -1
- package/dist/internal/protocol/zk/credentials/endorsements.d.ts +11 -11
- package/dist/internal/protocol/zk/credentials/endorsements.js +14 -14
- package/dist/internal/protocol/zk/credentials/issuance.d.ts +5 -1
- package/dist/internal/protocol/zk/credentials/issuance.d.ts.map +1 -1
- package/dist/internal/protocol/zk/credentials/issuance.js +5 -1
- package/dist/internal/protocol/zk/credentials/issuance.js.map +1 -1
- package/dist/internal/protocol/zk/credentials/presentation.d.ts +16 -16
- package/dist/internal/protocol/zk/credentials/presentation.d.ts.map +1 -1
- package/dist/internal/protocol/zk/credentials/presentation.js +18 -18
- package/dist/internal/protocol/zk/credentials/presentation.js.map +1 -1
- package/dist/internal/protocol/zk/groups/auth-credential.d.ts +22 -16
- package/dist/internal/protocol/zk/groups/auth-credential.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/auth-credential.js +19 -14
- package/dist/internal/protocol/zk/groups/auth-credential.js.map +1 -1
- package/dist/internal/protocol/zk/groups/client-zk-group-cipher.d.ts +4 -4
- package/dist/internal/protocol/zk/groups/client-zk-group-cipher.js +4 -4
- package/dist/internal/protocol/zk/groups/group-params.d.ts +2 -2
- package/dist/internal/protocol/zk/groups/group-params.js +2 -2
- package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts +10 -9
- package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/group-send-endorsement.js +9 -8
- package/dist/internal/protocol/zk/groups/group-send-endorsement.js.map +1 -1
- package/dist/internal/protocol/zk/groups/lizard.d.ts +1 -1
- package/dist/internal/protocol/zk/groups/lizard.js +4 -4
- package/dist/internal/protocol/zk/groups/lizard.js.map +1 -1
- package/dist/internal/protocol/zk/groups/profile-key-commitment.d.ts +3 -3
- package/dist/internal/protocol/zk/groups/profile-key-commitment.js +3 -3
- package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts +11 -11
- package/dist/internal/protocol/zk/groups/profile-key-credential.js +7 -7
- package/dist/internal/protocol/zk/groups/profile-key-encryption.d.ts +2 -2
- package/dist/internal/protocol/zk/groups/profile-key-encryption.js +2 -2
- package/dist/internal/protocol/zk/groups/profile-key-struct.d.ts +2 -2
- package/dist/internal/protocol/zk/groups/profile-key-struct.js +2 -2
- package/dist/internal/protocol/zk/groups/profile-key-version.d.ts +2 -2
- package/dist/internal/protocol/zk/groups/profile-key-version.js +2 -2
- package/dist/internal/protocol/zk/groups/server-params.d.ts +1 -1
- package/dist/internal/protocol/zk/groups/server-params.js +1 -1
- package/dist/internal/protocol/zk/groups/uid-encryption.d.ts +4 -4
- package/dist/internal/protocol/zk/groups/uid-encryption.js +4 -4
- package/dist/internal/protocol/zk/groups/uid-struct.d.ts +2 -2
- package/dist/internal/protocol/zk/groups/uid-struct.js +3 -3
- package/dist/internal/protocol/zk/groups/uid-struct.js.map +1 -1
- package/dist/internal/protocol/zk/proofs/args.d.ts +3 -3
- package/dist/internal/protocol/zk/proofs/args.js +3 -3
- package/dist/internal/protocol/zk/proofs/sho-sha256.d.ts +3 -3
- package/dist/internal/protocol/zk/proofs/sho-sha256.js +3 -3
- package/dist/internal/protocol/zk/proofs/sho.d.ts +8 -7
- package/dist/internal/protocol/zk/proofs/sho.d.ts.map +1 -1
- package/dist/internal/protocol/zk/proofs/sho.js +8 -7
- package/dist/internal/protocol/zk/proofs/sho.js.map +1 -1
- package/dist/internal/protocol/zk/proofs/statement.d.ts +8 -6
- package/dist/internal/protocol/zk/proofs/statement.d.ts.map +1 -1
- package/dist/internal/protocol/zk/proofs/statement.js +8 -6
- package/dist/internal/protocol/zk/proofs/statement.js.map +1 -1
- package/dist/internal/sesame/manager.d.ts +23 -19
- package/dist/internal/sesame/manager.d.ts.map +1 -1
- package/dist/internal/sesame/manager.js +64 -54
- package/dist/internal/sesame/manager.js.map +1 -1
- package/dist/internal/sesame/types.d.ts +28 -27
- package/dist/internal/sesame/types.d.ts.map +1 -1
- package/dist/internal/sesame/types.js +2 -4
- package/dist/internal/sesame/types.js.map +1 -1
- package/dist/internal/sesame/validation.d.ts +2 -2
- package/dist/internal/sesame/validation.js +3 -3
- package/dist/internal/sesame/validation.js.map +1 -1
- package/dist/internal/session/builder.d.ts +8 -8
- package/dist/internal/session/builder.js +22 -22
- package/dist/internal/session/builder.js.map +1 -1
- package/dist/internal/session/cipher.d.ts +3 -3
- package/dist/internal/session/cipher.d.ts.map +1 -1
- package/dist/internal/session/cipher.js +51 -40
- package/dist/internal/session/cipher.js.map +1 -1
- package/dist/internal/session/decryption.js +11 -9
- package/dist/internal/session/decryption.js.map +1 -1
- package/dist/internal/session/factory.js +1 -1
- package/dist/internal/session/factory.js.map +1 -1
- package/dist/internal/session/handshake.d.ts +4 -4
- package/dist/internal/session/handshake.js +4 -4
- package/dist/internal/session/keys.d.ts +3 -4
- package/dist/internal/session/keys.d.ts.map +1 -1
- package/dist/internal/session/keys.js.map +1 -1
- package/dist/internal/session/ratchet.d.ts +8 -8
- package/dist/internal/session/ratchet.js +10 -10
- package/dist/internal/session/ratchet.js.map +1 -1
- package/dist/internal/session/session-resolver.d.ts +6 -6
- package/dist/internal/session/session-resolver.js +6 -6
- package/dist/internal/session/state.d.ts +12 -12
- package/dist/internal/session/state.d.ts.map +1 -1
- package/dist/internal/session/state.js +7 -7
- package/dist/internal/session/types.d.ts +20 -20
- package/dist/internal/session/types.d.ts.map +1 -1
- package/dist/internal/session/types.js +3 -3
- package/dist/internal/session/validation.d.ts +1 -1
- package/dist/internal/session/validation.js +4 -4
- package/dist/internal/session/validation.js.map +1 -1
- package/dist/keys/branded.d.ts +12 -12
- package/dist/keys/branded.js +3 -3
- package/dist/keys/generation.d.ts +4 -4
- package/dist/keys/generation.js +4 -4
- package/dist/keys/identity.d.ts +7 -7
- package/dist/keys/identity.d.ts.map +1 -1
- package/dist/keys/identity.js +7 -7
- package/dist/keys/identity.js.map +1 -1
- package/dist/keys/types.d.ts +16 -16
- package/dist/keys/types.d.ts.map +1 -1
- package/dist/layers.d.ts +1 -1
- package/dist/layers.js +1 -1
- package/dist/local/store/expo/adapter.d.ts +8 -8
- package/dist/local/store/expo/adapter.js +10 -10
- package/dist/local/store/expo/adapter.js.map +1 -1
- package/dist/local/store/expo/database-key.d.ts +7 -7
- package/dist/local/store/expo/database-key.js +7 -7
- package/dist/local/store/expo/key-storage.d.ts +1 -1
- package/dist/local/store/expo/key-storage.js +4 -4
- package/dist/local/store/expo/key-storage.js.map +1 -1
- package/dist/local/store/expo/models/kyber-prekey-used.d.ts +6 -6
- package/dist/local/store/expo/models/kyber-prekey-used.js +3 -3
- package/dist/local/store/expo/models/kyber-prekey.d.ts +1 -1
- package/dist/local/store/expo/models/kyber-prekey.js +1 -1
- package/dist/local/store/expo/models/message-record.d.ts +2 -2
- package/dist/local/store/expo/models/message-record.d.ts.map +1 -1
- package/dist/local/store/expo/models/message-record.js +1 -1
- package/dist/local/store/expo/models/message-record.js.map +1 -1
- package/dist/local/store/expo/models/sender-key.d.ts +11 -10
- package/dist/local/store/expo/models/sender-key.d.ts.map +1 -1
- package/dist/local/store/expo/models/sender-key.js +11 -10
- package/dist/local/store/expo/models/sender-key.js.map +1 -1
- package/dist/local/store/expo/schema.d.ts +2 -2
- package/dist/local/store/expo/schema.js +2 -2
- package/dist/local/store/expo/secure-store-options.d.ts +1 -1
- package/dist/local/store/memory/adapter.d.ts +2 -2
- package/dist/local/store/memory/adapter.js +12 -12
- package/dist/local/store/memory/adapter.js.map +1 -1
- package/dist/local/store/node/adapter.d.ts.map +1 -1
- package/dist/local/store/node/adapter.js +5 -4
- package/dist/local/store/node/adapter.js.map +1 -1
- package/dist/local/store/node/database-key.d.ts +8 -8
- package/dist/local/store/node/database-key.js +10 -10
- package/dist/local/store/node/database-key.js.map +1 -1
- package/dist/local/store/node/database.d.ts +5 -5
- package/dist/local/store/node/database.js +11 -11
- package/dist/local/store/node/database.js.map +1 -1
- package/dist/local/store/react-native/adapter.d.ts +6 -6
- package/dist/local/store/react-native/adapter.d.ts.map +1 -1
- package/dist/local/store/react-native/adapter.js +35 -32
- package/dist/local/store/react-native/adapter.js.map +1 -1
- package/dist/local/store/react-native/backend-conformance.d.ts +11 -10
- package/dist/local/store/react-native/backend-conformance.d.ts.map +1 -1
- package/dist/local/store/react-native/backend-conformance.js +13 -12
- package/dist/local/store/react-native/backend-conformance.js.map +1 -1
- package/dist/local/store/react-native/index.d.ts +1 -1
- package/dist/local/store/react-native/reference-backend.d.ts +14 -13
- package/dist/local/store/react-native/reference-backend.d.ts.map +1 -1
- package/dist/local/store/react-native/reference-backend.js +15 -14
- package/dist/local/store/react-native/reference-backend.js.map +1 -1
- package/dist/local/store/react-native/storage.d.ts +3 -3
- package/dist/local/store/web/adapter.d.ts +3 -3
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +30 -31
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/local/store/web/index.d.ts +1 -1
- package/dist/local/vault/index.d.ts +2 -2
- package/dist/media/index.d.ts +11 -12
- package/dist/media/index.d.ts.map +1 -1
- package/dist/media/index.js +9 -10
- package/dist/media/index.js.map +1 -1
- package/dist/profile/contact-state.d.ts +1 -1
- package/dist/profile/contact-state.js +1 -1
- package/dist/profile/profile-key.d.ts +2 -2
- package/dist/profile/profile-key.js +7 -6
- package/dist/profile/profile-key.js.map +1 -1
- package/dist/remote/object-store/index.d.ts +1 -1
- package/dist/remote/object-store/s3/storage.d.ts +1 -1
- package/dist/remote/object-store/types.d.ts +4 -4
- package/dist/remote/object-store/types.d.ts.map +1 -1
- package/dist/remote/relay/convex/backend.d.ts +6 -6
- package/dist/remote/relay/convex/backend.d.ts.map +1 -1
- package/dist/remote/relay/convex/backend.js +4 -4
- package/dist/remote/relay/convex/backend.js.map +1 -1
- package/dist/remote/relay/convex/component/_generated/component.d.ts +2 -2
- package/dist/remote/relay/convex/component/_generated/component.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/accounts.d.ts +15 -13
- package/dist/remote/relay/convex/component/accounts.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/accounts.js +31 -28
- package/dist/remote/relay/convex/component/accounts.js.map +1 -1
- package/dist/remote/relay/convex/component/certificates.js +1 -1
- package/dist/remote/relay/convex/component/cleanup.js +7 -7
- package/dist/remote/relay/convex/component/cleanup.js.map +1 -1
- package/dist/remote/relay/convex/component/convex.config.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/convex.config.js +10 -8
- package/dist/remote/relay/convex/component/convex.config.js.map +1 -1
- package/dist/remote/relay/convex/component/devices.d.ts +21 -20
- package/dist/remote/relay/convex/component/devices.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/devices.js +24 -23
- package/dist/remote/relay/convex/component/devices.js.map +1 -1
- package/dist/remote/relay/convex/component/groups.js +6 -6
- package/dist/remote/relay/convex/component/groups.js.map +1 -1
- package/dist/remote/relay/convex/component/messages.d.ts +2 -2
- package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/messages.js +90 -83
- package/dist/remote/relay/convex/component/messages.js.map +1 -1
- package/dist/remote/relay/convex/component/provisioning.d.ts +3 -3
- package/dist/remote/relay/convex/component/provisioning.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/provisioning.js +17 -16
- package/dist/remote/relay/convex/component/provisioning.js.map +1 -1
- package/dist/remote/relay/convex/component/runtime.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/runtime.js +4 -2
- package/dist/remote/relay/convex/component/runtime.js.map +1 -1
- package/dist/remote/relay/convex/component/schema.d.ts +2 -2
- package/dist/remote/relay/convex/component/schema.js +26 -25
- package/dist/remote/relay/convex/component/schema.js.map +1 -1
- package/dist/remote/relay/convex/group-server.d.ts +3 -3
- package/dist/remote/relay/convex/group-server.js +3 -3
- package/dist/remote/relay/convex/relay.d.ts +3 -3
- package/dist/remote/relay/convex/relay.d.ts.map +1 -1
- package/dist/remote/relay/convex/relay.js +18 -17
- package/dist/remote/relay/convex/relay.js.map +1 -1
- package/dist/remote/relay/convex/types.d.ts +7 -7
- package/dist/remote/relay/convex/types.js +4 -4
- package/dist/remote/relay/memory/adapter.js +9 -9
- package/dist/remote/relay/memory/adapter.js.map +1 -1
- package/dist/remote/relay/types.d.ts +27 -27
- package/dist/remote/relay/types.d.ts.map +1 -1
- package/dist/safety/fingerprint.d.ts +7 -6
- package/dist/safety/fingerprint.d.ts.map +1 -1
- package/dist/safety/fingerprint.js +5 -4
- package/dist/safety/fingerprint.js.map +1 -1
- package/dist/safety/index.d.ts +6 -5
- package/dist/safety/index.d.ts.map +1 -1
- package/dist/safety/index.js +7 -6
- package/dist/safety/index.js.map +1 -1
- package/dist/safety/protobuf.js +2 -2
- package/dist/safety/protobuf.js.map +1 -1
- package/dist/safety/url.d.ts +5 -5
- package/dist/safety/url.js +6 -6
- package/dist/types/address.d.ts +2 -2
- package/dist/types/address.js +2 -2
- package/dist/types/api.d.ts +78 -73
- package/dist/types/api.d.ts.map +1 -1
- package/dist/types/errors.d.ts +63 -403
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/errors.js +62 -537
- package/dist/types/errors.js.map +1 -1
- package/dist/types/messages.d.ts +16 -16
- package/dist/types/messages.d.ts.map +1 -1
- package/dist/types/messages.js +7 -7
- package/dist/types/messages.js.map +1 -1
- package/dist/types/protocol-config.d.ts +52 -49
- package/dist/types/protocol-config.d.ts.map +1 -1
- package/dist/types/protocol-config.js +36 -34
- package/dist/types/protocol-config.js.map +1 -1
- package/dist/types/protocol-constants.d.ts +2 -2
- package/dist/types/protocol-constants.js +2 -2
- package/dist/types/session.d.ts +62 -61
- package/dist/types/session.d.ts.map +1 -1
- package/dist/types/session.js +13 -14
- package/dist/types/session.js.map +1 -1
- package/dist/types/trust.d.ts +8 -8
- package/dist/types/trust.js +3 -3
- package/dist/utils/retry.d.ts +2 -1
- package/dist/utils/retry.d.ts.map +1 -1
- package/dist/utils/retry.js +4 -5
- package/dist/utils/retry.js.map +1 -1
- package/docs/ASSURANCE.md +89 -75
- package/docs/CLIENT_COMPOSITION.md +22 -15
- package/docs/DEVIATIONS.md +507 -425
- package/docs/DOCUMENTATION_STANDARDS.md +52 -24
- package/docs/E2EE.md +45 -42
- package/docs/ERROR_HANDLING.md +107 -152
- package/docs/GETTING_STARTED.md +44 -26
- package/docs/INTERFACES.md +32 -18
- package/docs/PACKAGE_SURFACE.md +24 -21
- package/docs/PROTOCOL_POLICY.md +25 -13
- package/docs/RECIPES.md +13 -4
- package/docs/SECURITY.md +72 -60
- package/encoding/README.md +3 -2
- package/files/README.md +2 -1
- package/groups/README.md +5 -3
- package/hooks/README.md +2 -2
- package/keys/README.md +17 -14
- package/local/store/README.md +84 -67
- package/local/store/expo/README.md +19 -12
- package/local/store/memory/README.md +6 -3
- package/local/store/node/README.md +9 -6
- package/local/store/react-native/README.md +16 -12
- package/local/store/web/README.md +32 -26
- package/local/vault/README.md +5 -4
- package/media/README.md +8 -5
- package/package.json +4 -2
- package/profile/README.md +8 -7
- package/remote/README.md +26 -18
- package/remote/object-store/README.md +9 -4
- package/remote/object-store/convex-r2/README.md +5 -3
- package/remote/object-store/s3/README.md +11 -5
- package/remote/relay/README.md +2 -0
- package/remote/relay/convex/README.md +6 -5
- package/remote/relay/convex/component/README.md +154 -124
- package/remote/relay/memory/README.md +8 -5
- package/safety/README.md +2 -1
- package/sealed-sender/README.md +4 -2
- package/types/README.md +2 -1
- package/username/README.md +1 -0
- package/utils/README.md +5 -4
- package/zk/README.md +1 -0
package/docs/ERROR_HANDLING.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Error Handling Guide
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
How to handle the errors that the `@open-e2ee/signal-protocol-sdk` library throws.
|
|
4
4
|
|
|
5
5
|
## Overview
|
|
6
6
|
|
|
@@ -14,13 +14,14 @@ The library uses a structured error system with stable programmatic codes:
|
|
|
14
14
|
|
|
15
15
|
### EncryptionError (Base Class)
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
Every error in the `EncryptionErrorCode` family extends `EncryptionError`:
|
|
18
18
|
|
|
19
|
+
<!-- doc-snippet:skip requires-existing-client-and-session -->
|
|
19
20
|
```typescript
|
|
20
21
|
import { EncryptionError, EncryptionErrorCode } from '@open-e2ee/signal-protocol-sdk';
|
|
21
22
|
|
|
22
23
|
try {
|
|
23
|
-
await signal.encryptMessage(
|
|
24
|
+
await signal.encryptMessage(remoteAddress, plaintext);
|
|
24
25
|
} catch (error) {
|
|
25
26
|
if (error instanceof EncryptionError) {
|
|
26
27
|
console.log('Error code:', error.code);
|
|
@@ -36,11 +37,12 @@ try {
|
|
|
36
37
|
|
|
37
38
|
Thrown when an identity key is not trusted. Requires user intervention (safety number verification).
|
|
38
39
|
|
|
40
|
+
<!-- doc-snippet:skip requires-untrusted-identity-fixture -->
|
|
39
41
|
```typescript
|
|
40
42
|
import { isUntrustedIdentityError } from '@open-e2ee/signal-protocol-sdk';
|
|
41
43
|
|
|
42
44
|
try {
|
|
43
|
-
await signal.establishSession(
|
|
45
|
+
await signal.establishSession(remoteAddress, bundle);
|
|
44
46
|
} catch (error) {
|
|
45
47
|
if (isUntrustedIdentityError(error)) {
|
|
46
48
|
// Show safety number verification UI
|
|
@@ -53,141 +55,106 @@ try {
|
|
|
53
55
|
}
|
|
54
56
|
```
|
|
55
57
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
Thrown when a remote party's identity key has changed. Could indicate:
|
|
58
|
+
## Error Codes
|
|
59
59
|
|
|
60
|
-
-
|
|
61
|
-
|
|
60
|
+
The SDK throws every code below. An error-surface check parses the SDK for the
|
|
61
|
+
construction sites that decide that. It fails the build if a code or a subclass
|
|
62
|
+
survives that nothing produces. A code documented here is therefore one an
|
|
63
|
+
application can branch on. The check runs on every change, with the rest of the
|
|
64
|
+
checks that [ASSURANCE.md](./ASSURANCE.md) describes.
|
|
62
65
|
|
|
63
|
-
|
|
64
|
-
|
|
66
|
+
The tables list the complete `EncryptionErrorCode` enum. The error-surface check
|
|
67
|
+
holds each member to a production construction site.
|
|
65
68
|
|
|
66
|
-
|
|
67
|
-
await signal.decryptMessage(sessionId, ciphertext);
|
|
68
|
-
} catch (error) {
|
|
69
|
-
if (isIdentityKeyChangedError(error)) {
|
|
70
|
-
// Show prominent security warning
|
|
71
|
-
showIdentityChangedWarning({
|
|
72
|
-
userId: error.changedAddress.userId,
|
|
73
|
-
deviceId: error.changedAddress.deviceId,
|
|
74
|
-
oldKey: error.oldIdentityKey,
|
|
75
|
-
newKey: error.newIdentityKey,
|
|
76
|
-
});
|
|
77
|
-
}
|
|
78
|
-
}
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
#### SessionConflictError
|
|
82
|
-
|
|
83
|
-
Thrown when both parties try to establish sessions simultaneously.
|
|
69
|
+
### Session Errors
|
|
84
70
|
|
|
85
|
-
|
|
86
|
-
|
|
71
|
+
| Code | Cause | Application response |
|
|
72
|
+
|---|---|---|
|
|
73
|
+
| `SESSION_NOT_FOUND` | No session exists for the address. | Establish a new session. |
|
|
74
|
+
| `SESSION_CORRUPTED` | Stored session data is invalid. | Delete the damaged session, then establish one. |
|
|
75
|
+
| `RECIPIENT_NOT_REGISTERED` | The recipient has no published prekey bundle. | Wait for recipient registration, then retry. |
|
|
76
|
+
| `PREKEY_FETCH_RATE_LIMITED` | The relay refused another prekey fetch. | Wait for the relay limit, then retry. |
|
|
77
|
+
| `SESSION_ESTABLISHMENT_FAILED` | Session setup failed after retries. | Inspect `originalError`, then retry after its cause is fixed. |
|
|
87
78
|
|
|
88
|
-
|
|
89
|
-
await signal.establishSession(sessionId, remoteAddress, bundle);
|
|
90
|
-
} catch (error) {
|
|
91
|
-
if (isSessionConflictError(error)) {
|
|
92
|
-
// Archive old session and retry with Sesame convergence
|
|
93
|
-
await signal.archiveSession(sessionId);
|
|
94
|
-
await signal.establishSession(sessionId, remoteAddress, bundle);
|
|
95
|
-
}
|
|
96
|
-
}
|
|
97
|
-
```
|
|
79
|
+
### Message Errors
|
|
98
80
|
|
|
99
|
-
|
|
81
|
+
| Code | Cause | Application response |
|
|
82
|
+
|---|---|---|
|
|
83
|
+
| `INVALID_CIPHERTEXT` | The ciphertext format is invalid. | Reject the message. |
|
|
84
|
+
| `DECRYPTION_FAILED` | Available session state could not decrypt the message. | Let the retry flow recover, or inspect the session state. |
|
|
85
|
+
| `ENCRYPTION_FAILED` | The SDK could not encrypt the message. | Inspect the session state and `originalError`. |
|
|
86
|
+
| `MESSAGE_DUPLICATE` | The session processed this message before. | Discard the duplicate. |
|
|
87
|
+
| `TOO_MANY_SKIPPED_MESSAGES` | The message exceeded the skipped-key bound. | Reset the affected session. |
|
|
88
|
+
| `REPLAY_DETECTED` | Envelope and encrypted-content timestamps differ. | Reject the message as a replay. |
|
|
89
|
+
| `SENDER_KEY_EXPIRED` | The sender key exceeded its rotation period. | Rotate and redistribute the sender key. |
|
|
100
90
|
|
|
101
|
-
|
|
91
|
+
### Identity and Trust Errors
|
|
102
92
|
|
|
103
|
-
|
|
104
|
-
|
|
93
|
+
| Code | Cause | Application response |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| `UNTRUSTED_IDENTITY` | The peer identity is unverified or changed. | Verify the safety number before acceptance. |
|
|
96
|
+
| `IDENTITY_MISMATCH` | The message identity does not match the expected sender. | Reject the message and inspect the identity state. |
|
|
97
|
+
| `SIGNATURE_VERIFICATION_FAILED` | A signature is invalid. | Reject the signed value. |
|
|
105
98
|
|
|
106
|
-
|
|
107
|
-
await signal.decryptMessage(sessionId, ciphertext);
|
|
108
|
-
} catch (error) {
|
|
109
|
-
if (isRegistrationIdChangedError(error)) {
|
|
110
|
-
// Archive old session, re-establish new one
|
|
111
|
-
await signal.archiveSession(sessionId);
|
|
112
|
-
// Notify user of reset
|
|
113
|
-
showSessionResetNotification(error.resetAddress.userId);
|
|
114
|
-
}
|
|
115
|
-
}
|
|
116
|
-
```
|
|
99
|
+
### Prekey and Session Establishment Errors
|
|
117
100
|
|
|
118
|
-
|
|
101
|
+
| Code | Cause | Application response |
|
|
102
|
+
|---|---|---|
|
|
103
|
+
| `INVALID_PREKEY_BUNDLE` | A prekey bundle is malformed or inconsistent. | Reject it and fetch a current bundle. |
|
|
104
|
+
| `PREKEY_NOT_FOUND` | The required prekey is unavailable. | Fetch current peer keys or rotate local keys, as the operation requires. |
|
|
105
|
+
| `PREKEY_ROTATION_REQUIRED` | A local signed or Kyber prekey is too old. | Rotate prekeys before another send. |
|
|
119
106
|
|
|
120
|
-
###
|
|
107
|
+
### Ratchet Errors
|
|
121
108
|
|
|
122
|
-
| Code
|
|
123
|
-
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `SESSION_CONFLICT` | Multiple active sessions detected | Use Sesame convergence |
|
|
109
|
+
| Code | Cause | Application response |
|
|
110
|
+
|---|---|---|
|
|
111
|
+
| `COUNTER_OVERFLOW` | A message counter reached its safe bound. | Rotate the session or ratchet epoch. |
|
|
112
|
+
| `INVALID_DH_KEY` | A DH public key is malformed or invalid. | Reject the key and its message. |
|
|
127
113
|
|
|
128
|
-
###
|
|
114
|
+
### Storage Errors
|
|
129
115
|
|
|
130
|
-
| Code
|
|
131
|
-
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `ENCRYPTION_FAILED` | Could not encrypt message | Check session state |
|
|
135
|
-
| `MESSAGE_DUPLICATE` | Message already processed | Ignore (replay protection) |
|
|
136
|
-
| `MESSAGE_TOO_OLD` | Message keys expired | Request retransmission |
|
|
137
|
-
| `TOO_MANY_SKIPPED_MESSAGES` | DoS protection triggered | Reset session |
|
|
138
|
-
| `INVALID_MESSAGE_VERSION` | Protocol version mismatch | Update client |
|
|
139
|
-
|
|
140
|
-
### Identity & Trust Errors
|
|
141
|
-
|
|
142
|
-
| Code | Description | Recovery |
|
|
143
|
-
| ------------------------------- | --------------------- | ------------------------ |
|
|
144
|
-
| `UNTRUSTED_IDENTITY` | Identity not verified | Verify safety number |
|
|
145
|
-
| `IDENTITY_KEY_CHANGED` | Identity key changed | Verify and accept/reject |
|
|
146
|
-
| `SIGNATURE_VERIFICATION_FAILED` | Signature is invalid | Reject message |
|
|
147
|
-
|
|
148
|
-
### PreKey & Session Establishment Errors
|
|
149
|
-
|
|
150
|
-
| Code | Description | Recovery |
|
|
151
|
-
| ------------------------- | ----------------------- | -------------------- |
|
|
152
|
-
| `INVALID_PREKEY_BUNDLE` | Bundle is malformed | Fetch new bundle |
|
|
153
|
-
| `PREKEY_NOT_FOUND` | PreKey not available | Rotate prekeys |
|
|
154
|
-
| `INVALID_REGISTRATION_ID` | Invalid registration ID | Re-register |
|
|
155
|
-
| `REGISTRATION_ID_CHANGED` | App was reinstalled | Re-establish session |
|
|
116
|
+
| Code | Cause | Application response |
|
|
117
|
+
|---|---|---|
|
|
118
|
+
| `KEY_STORAGE_ERROR` | A key-storage operation failed. | Inspect `originalError`, then retry or reinitialize storage. |
|
|
119
|
+
| `STORAGE_QUOTA_EXCEEDED` | The storage origin ran out of space. | Free storage space, then retry the rejected write. |
|
|
156
120
|
|
|
157
|
-
###
|
|
121
|
+
### Initialization and Protocol Policy Errors
|
|
158
122
|
|
|
159
|
-
| Code
|
|
160
|
-
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
123
|
+
| Code | Cause | Application response |
|
|
124
|
+
|---|---|---|
|
|
125
|
+
| `INITIALIZATION_FAILED` | Client or group initialization failed. | Inspect `originalError` and the configuration. |
|
|
126
|
+
| `PQXDH_REQUIRED` | Policy requires PQXDH, but the peer lacks required keys. | Wait for new peer keys or queue the message. |
|
|
127
|
+
| `PQXDH_FAILED` | The PQXDH exchange failed. | Abort setup and inspect `originalError`. |
|
|
128
|
+
| `TRIPLE_RATCHET_REQUIRED` | Triple Ratchet policy lacks a PQXDH session. | Establish the required PQXDH session first. |
|
|
163
129
|
|
|
164
|
-
###
|
|
130
|
+
### SPQR Errors
|
|
165
131
|
|
|
166
|
-
| Code
|
|
167
|
-
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
| `
|
|
132
|
+
| Code | Cause | Application response |
|
|
133
|
+
|---|---|---|
|
|
134
|
+
| `SPQR_EPOCH_OUT_OF_RANGE` | The requested epoch is too old or not established. | Reject the message and synchronize session state. |
|
|
135
|
+
| `SPQR_MESSAGE_JUMP_TOO_LARGE` | The message jump exceeds the configured bound. | Reject the message. |
|
|
136
|
+
| `SPQR_COUNTER_OVERFLOW` | The SPQR message counter reached its bound. | Rotate the SPQR epoch. |
|
|
137
|
+
| `SPQR_INVALID_CIPHERTEXT` | An SPQR ML-KEM ciphertext has an invalid form. | Reject the message. |
|
|
138
|
+
| `SPQR_VERSION_MISMATCH` | Peer and local SPQR version ranges do not overlap. | Update the peer or the required protocol policy. |
|
|
171
139
|
|
|
172
|
-
###
|
|
140
|
+
### Sealed Sender and State Errors
|
|
173
141
|
|
|
174
|
-
| Code
|
|
175
|
-
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
| `HMAC_VERIFICATION_FAILED` | Message tampered | Reject message |
|
|
142
|
+
| Code | Cause | Application response |
|
|
143
|
+
|---|---|---|
|
|
144
|
+
| `SEALED_SENDER_AUTH_FAILED` | The relay rejected sealed-sender authorization. | Reauthorize or use identified delivery when policy permits it. |
|
|
145
|
+
| `INVALID_STATE` | The requested operation is invalid for current state. | Correct the call order or synchronize state. |
|
|
179
146
|
|
|
180
147
|
## Error Handling Patterns
|
|
181
148
|
|
|
182
|
-
###
|
|
149
|
+
### One Handler for Every Error
|
|
183
150
|
|
|
151
|
+
<!-- doc-snippet:skip application-handler-fragment -->
|
|
184
152
|
```typescript
|
|
185
153
|
import {
|
|
186
154
|
EncryptionError,
|
|
187
155
|
EncryptionErrorCode,
|
|
188
156
|
isUntrustedIdentityError,
|
|
189
|
-
|
|
190
|
-
isSessionConflictError,
|
|
157
|
+
isSealedSenderAuthError,
|
|
191
158
|
} from '@open-e2ee/signal-protocol-sdk';
|
|
192
159
|
|
|
193
160
|
async function handleEncryptionError(error: unknown): Promise<void> {
|
|
@@ -202,13 +169,8 @@ async function handleEncryptionError(error: unknown): Promise<void> {
|
|
|
202
169
|
return;
|
|
203
170
|
}
|
|
204
171
|
|
|
205
|
-
if (
|
|
206
|
-
await
|
|
207
|
-
return;
|
|
208
|
-
}
|
|
209
|
-
|
|
210
|
-
if (isSessionConflictError(error)) {
|
|
211
|
-
await handleSessionConflict(error);
|
|
172
|
+
if (isSealedSenderAuthError(error)) {
|
|
173
|
+
await reauthorizeSealedSender(error);
|
|
212
174
|
return;
|
|
213
175
|
}
|
|
214
176
|
|
|
@@ -218,19 +180,16 @@ async function handleEncryptionError(error: unknown): Promise<void> {
|
|
|
218
180
|
await establishNewSession(error.address);
|
|
219
181
|
break;
|
|
220
182
|
|
|
221
|
-
case EncryptionErrorCode.MESSAGE_TOO_OLD:
|
|
222
183
|
case EncryptionErrorCode.TOO_MANY_SKIPPED_MESSAGES:
|
|
223
184
|
// Message is unrecoverable, notify user
|
|
224
185
|
notifyMessageLost(error.context?.operation);
|
|
225
186
|
break;
|
|
226
187
|
|
|
227
188
|
case EncryptionErrorCode.DECRYPTION_FAILED:
|
|
228
|
-
case EncryptionErrorCode.HMAC_VERIFICATION_FAILED:
|
|
229
189
|
// Possible tampering or corruption
|
|
230
190
|
logSecurityEvent(error);
|
|
231
191
|
break;
|
|
232
192
|
|
|
233
|
-
case EncryptionErrorCode.DATABASE_ERROR:
|
|
234
193
|
case EncryptionErrorCode.KEY_STORAGE_ERROR:
|
|
235
194
|
// Storage issue, retry with backoff
|
|
236
195
|
await retryWithBackoff(() => reinitializeStorage());
|
|
@@ -248,6 +207,7 @@ async function handleEncryptionError(error: unknown): Promise<void> {
|
|
|
248
207
|
|
|
249
208
|
The library provides a built-in retry utility:
|
|
250
209
|
|
|
210
|
+
<!-- doc-snippet:skip requires-existing-client -->
|
|
251
211
|
```typescript
|
|
252
212
|
import { withRetry } from '@open-e2ee/signal-protocol-sdk/utils/retry';
|
|
253
213
|
|
|
@@ -266,35 +226,43 @@ await withRetry(
|
|
|
266
226
|
|
|
267
227
|
### Session Recovery Pattern
|
|
268
228
|
|
|
229
|
+
<!-- doc-snippet:skip application-session-recovery-fragment -->
|
|
269
230
|
```typescript
|
|
231
|
+
import {
|
|
232
|
+
EncryptionError,
|
|
233
|
+
EncryptionErrorCode,
|
|
234
|
+
ProtocolAddress,
|
|
235
|
+
type SignalProtocolClient,
|
|
236
|
+
} from '@open-e2ee/signal-protocol-sdk';
|
|
237
|
+
|
|
270
238
|
async function ensureSession(
|
|
271
239
|
signal: SignalProtocolClient,
|
|
272
240
|
userId: string,
|
|
273
241
|
deviceId: number
|
|
274
242
|
): Promise<void> {
|
|
275
|
-
const
|
|
243
|
+
const remoteAddress = ProtocolAddress.create(userId, deviceId);
|
|
276
244
|
|
|
277
245
|
try {
|
|
278
|
-
const hasSession = await signal.hasSession(
|
|
246
|
+
const hasSession = await signal.hasSession(remoteAddress);
|
|
279
247
|
if (!hasSession) {
|
|
280
248
|
// Fetch prekey bundle and establish session
|
|
281
249
|
const bundle = await fetchPreKeyBundle(userId, deviceId);
|
|
282
|
-
await signal.establishSession(
|
|
250
|
+
await signal.establishSession(remoteAddress, bundle);
|
|
283
251
|
}
|
|
284
252
|
} catch (error) {
|
|
285
253
|
if (error instanceof EncryptionError) {
|
|
286
254
|
switch (error.code) {
|
|
287
255
|
case EncryptionErrorCode.SESSION_CORRUPTED:
|
|
288
256
|
// Delete corrupted session and retry
|
|
289
|
-
await signal.deleteSession(
|
|
257
|
+
await signal.deleteSession(remoteAddress);
|
|
290
258
|
const bundle = await fetchPreKeyBundle(userId, deviceId);
|
|
291
|
-
await signal.establishSession(
|
|
259
|
+
await signal.establishSession(remoteAddress, bundle);
|
|
292
260
|
break;
|
|
293
261
|
|
|
294
262
|
case EncryptionErrorCode.INVALID_PREKEY_BUNDLE:
|
|
295
263
|
// Bundle was invalid, try fetching again
|
|
296
264
|
const newBundle = await fetchPreKeyBundle(userId, deviceId);
|
|
297
|
-
await signal.establishSession(
|
|
265
|
+
await signal.establishSession(remoteAddress, newBundle);
|
|
298
266
|
break;
|
|
299
267
|
|
|
300
268
|
default:
|
|
@@ -311,6 +279,7 @@ async function ensureSession(
|
|
|
311
279
|
|
|
312
280
|
The library includes structured logging for errors:
|
|
313
281
|
|
|
282
|
+
<!-- doc-snippet:skip requires-platform-adapters -->
|
|
314
283
|
```typescript
|
|
315
284
|
import { SignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
|
|
316
285
|
|
|
@@ -334,20 +303,19 @@ void signal;
|
|
|
334
303
|
|
|
335
304
|
### 1. Always Use Type Guards
|
|
336
305
|
|
|
306
|
+
<!-- doc-snippet:skip type-guard-comparison-fragment -->
|
|
337
307
|
```typescript
|
|
338
|
-
//
|
|
308
|
+
// Prefer the exported guard so narrowing stays behind one public function.
|
|
339
309
|
if (isUntrustedIdentityError(error)) {
|
|
340
310
|
// Handle untrusted identity
|
|
341
311
|
}
|
|
342
312
|
|
|
343
|
-
//
|
|
344
|
-
if (error instanceof UntrustedIdentityError) {
|
|
345
|
-
// This might fail if bundled differently
|
|
346
|
-
}
|
|
313
|
+
// Current guards delegate to instanceof. Bundle one copy of the SDK.
|
|
347
314
|
```
|
|
348
315
|
|
|
349
316
|
### 2. Preserve Error Context
|
|
350
317
|
|
|
318
|
+
<!-- doc-snippet:skip error-wrapping-comparison-fragment -->
|
|
351
319
|
```typescript
|
|
352
320
|
// Good: Wrap errors with context
|
|
353
321
|
throw new EncryptionError('Failed to establish session', EncryptionErrorCode.SESSION_NOT_FOUND, {
|
|
@@ -362,16 +330,19 @@ throw new Error('Session error');
|
|
|
362
330
|
|
|
363
331
|
### 3. Handle Security-Critical Errors Prominently
|
|
364
332
|
|
|
333
|
+
<!-- doc-snippet:skip requires-identity-change-fixture -->
|
|
365
334
|
```typescript
|
|
366
335
|
// Identity changes require prominent user warning
|
|
367
|
-
if (
|
|
336
|
+
if (isUntrustedIdentityError(error)) {
|
|
368
337
|
// Don't silently accept - show security dialog
|
|
369
338
|
const accepted = await showSecurityWarningDialog(error);
|
|
370
339
|
if (accepted) {
|
|
371
|
-
// acceptIdentityRotation() takes the peer's new composite identity tuple
|
|
372
|
-
//
|
|
373
|
-
// the
|
|
374
|
-
|
|
340
|
+
// acceptIdentityRotation() takes the peer's new composite identity tuple and
|
|
341
|
+
// resets the sessions bound to the retired identity. Read that tuple from the
|
|
342
|
+
// relay rather than from `error.identity`: the error carries whichever tuple
|
|
343
|
+
// failed the trust check, which on the three session-bound throw sites is the
|
|
344
|
+
// pinned one being rejected, not the one the peer now publishes.
|
|
345
|
+
const userId = error.untrustedAddress.userId;
|
|
375
346
|
const identity = await relay.getIdentityKey(userId);
|
|
376
347
|
if (identity) {
|
|
377
348
|
await signal.acceptIdentityRotation(userId, identity);
|
|
@@ -380,22 +351,6 @@ if (isIdentityKeyChangedError(error)) {
|
|
|
380
351
|
}
|
|
381
352
|
```
|
|
382
353
|
|
|
383
|
-
### 4. Clean Up on Errors
|
|
384
|
-
|
|
385
|
-
```typescript
|
|
386
|
-
let session = null;
|
|
387
|
-
try {
|
|
388
|
-
session = await signal.establishSession(sessionId, remoteAddress, bundle);
|
|
389
|
-
// Use session...
|
|
390
|
-
} catch (error) {
|
|
391
|
-
// Clean up partial state
|
|
392
|
-
if (session) {
|
|
393
|
-
await signal.deleteSession(sessionId);
|
|
394
|
-
}
|
|
395
|
-
throw error;
|
|
396
|
-
}
|
|
397
|
-
```
|
|
398
|
-
|
|
399
354
|
## See Also
|
|
400
355
|
|
|
401
356
|
- [SECURITY.md](./SECURITY.md) - Security guidelines
|