@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.
Files changed (615) hide show
  1. package/ADAPTERS.md +11 -4
  2. package/ARCHITECTURE.md +19 -16
  3. package/CHANGELOG.md +72 -0
  4. package/COMMERCIAL.md +6 -6
  5. package/NOTICE +1 -1
  6. package/README.md +65 -93
  7. package/SECURITY.md +16 -13
  8. package/TROUBLESHOOTING.md +12 -5
  9. package/blocking/README.md +7 -5
  10. package/client/README.md +15 -5
  11. package/device/README.md +13 -8
  12. package/dist/blocking/types.d.ts +2 -2
  13. package/dist/blocking/types.js +2 -2
  14. package/dist/client/client.d.ts +46 -45
  15. package/dist/client/client.d.ts.map +1 -1
  16. package/dist/client/client.js +61 -60
  17. package/dist/client/client.js.map +1 -1
  18. package/dist/client/config.d.ts +32 -32
  19. package/dist/client/constants.d.ts +7 -6
  20. package/dist/client/constants.d.ts.map +1 -1
  21. package/dist/client/constants.js +5 -4
  22. package/dist/client/constants.js.map +1 -1
  23. package/dist/client/dual-store.d.ts +2 -2
  24. package/dist/client/dual-store.js +2 -2
  25. package/dist/client/endorsement-manager.d.ts +14 -14
  26. package/dist/client/endorsement-manager.d.ts.map +1 -1
  27. package/dist/client/endorsement-manager.js +15 -15
  28. package/dist/client/endorsement-manager.js.map +1 -1
  29. package/dist/client/event-hooks.d.ts +16 -16
  30. package/dist/client/event-hooks.d.ts.map +1 -1
  31. package/dist/client/event-hooks.js +1 -1
  32. package/dist/client/event-hooks.js.map +1 -1
  33. package/dist/client/files.js +4 -4
  34. package/dist/client/files.js.map +1 -1
  35. package/dist/client/groups.d.ts.map +1 -1
  36. package/dist/client/groups.js +14 -4
  37. package/dist/client/groups.js.map +1 -1
  38. package/dist/client/headless.d.ts +7 -7
  39. package/dist/client/headless.d.ts.map +1 -1
  40. package/dist/client/headless.js +4 -4
  41. package/dist/client/key-rotation-core.d.ts +19 -17
  42. package/dist/client/key-rotation-core.d.ts.map +1 -1
  43. package/dist/client/key-rotation-core.js +35 -31
  44. package/dist/client/key-rotation-core.js.map +1 -1
  45. package/dist/client/key-rotation.d.ts +8 -8
  46. package/dist/client/key-rotation.js +8 -8
  47. package/dist/client/media.d.ts +1 -1
  48. package/dist/client/messages.d.ts.map +1 -1
  49. package/dist/client/messages.js +13 -11
  50. package/dist/client/messages.js.map +1 -1
  51. package/dist/client/multi-device.d.ts +5 -4
  52. package/dist/client/multi-device.d.ts.map +1 -1
  53. package/dist/client/multi-device.js.map +1 -1
  54. package/dist/client/prekeys.d.ts +7 -7
  55. package/dist/client/prekeys.js +10 -10
  56. package/dist/client/prekeys.js.map +1 -1
  57. package/dist/client/relay-subscription.d.ts +3 -0
  58. package/dist/client/relay-subscription.d.ts.map +1 -1
  59. package/dist/client/relay-subscription.js +7 -4
  60. package/dist/client/relay-subscription.js.map +1 -1
  61. package/dist/client/retry-utils.d.ts +5 -6
  62. package/dist/client/retry-utils.d.ts.map +1 -1
  63. package/dist/client/retry-utils.js +5 -12
  64. package/dist/client/retry-utils.js.map +1 -1
  65. package/dist/client/retry.js +7 -7
  66. package/dist/client/retry.js.map +1 -1
  67. package/dist/client/sealed-sender-ops.d.ts +3 -3
  68. package/dist/client/sealed-sender-ops.js +5 -5
  69. package/dist/client/sealed-sender-ops.js.map +1 -1
  70. package/dist/client/sessions.d.ts +2 -2
  71. package/dist/client/sessions.js +2 -2
  72. package/dist/client/signal-service-cipher.d.ts +9 -9
  73. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  74. package/dist/client/signal-service-cipher.js +41 -40
  75. package/dist/client/signal-service-cipher.js.map +1 -1
  76. package/dist/client/state.d.ts +1 -1
  77. package/dist/client/state.js +1 -1
  78. package/dist/client/types.d.ts +19 -19
  79. package/dist/client/types.d.ts.map +1 -1
  80. package/dist/device/connection.d.ts +1 -1
  81. package/dist/device/connection.js +2 -2
  82. package/dist/device/connection.js.map +1 -1
  83. package/dist/device/constants.d.ts +4 -4
  84. package/dist/device/constants.js +3 -3
  85. package/dist/device/device-id.d.ts +4 -4
  86. package/dist/device/device-id.js +4 -4
  87. package/dist/device/expo-metadata.d.ts +13 -11
  88. package/dist/device/expo-metadata.d.ts.map +1 -1
  89. package/dist/device/expo-metadata.js +13 -11
  90. package/dist/device/expo-metadata.js.map +1 -1
  91. package/dist/device/lifecycle/manager.d.ts +6 -6
  92. package/dist/device/lifecycle/manager.js +7 -7
  93. package/dist/device/lifecycle/types.d.ts +13 -13
  94. package/dist/device/lifecycle/types.d.ts.map +1 -1
  95. package/dist/device/lifecycle/utils.d.ts +2 -2
  96. package/dist/device/lifecycle/utils.js +5 -5
  97. package/dist/device/lifecycle/utils.js.map +1 -1
  98. package/dist/device/provisioning.d.ts +5 -4
  99. package/dist/device/provisioning.d.ts.map +1 -1
  100. package/dist/device/provisioning.js +5 -4
  101. package/dist/device/provisioning.js.map +1 -1
  102. package/dist/device/transfer.d.ts +2 -2
  103. package/dist/device/transfer.js +3 -3
  104. package/dist/device/transfer.js.map +1 -1
  105. package/dist/encoding/index.d.ts +3 -4
  106. package/dist/encoding/index.d.ts.map +1 -1
  107. package/dist/encoding/index.js.map +1 -1
  108. package/dist/files/index.d.ts +1 -1
  109. package/dist/files/index.js +1 -1
  110. package/dist/hooks/use-connection-presence.d.ts +1 -1
  111. package/dist/hooks/use-connection-presence.js +7 -7
  112. package/dist/hooks/use-connection-presence.js.map +1 -1
  113. package/dist/hooks/use-group-membership.d.ts +2 -2
  114. package/dist/hooks/use-group-membership.d.ts.map +1 -1
  115. package/dist/hooks/use-group-membership.js +6 -6
  116. package/dist/hooks/use-group-membership.js.map +1 -1
  117. package/dist/hooks/use-key-rotation.js +3 -3
  118. package/dist/hooks/use-key-rotation.js.map +1 -1
  119. package/dist/hooks/use-single-flight.d.ts +2 -2
  120. package/dist/hooks/use-single-flight.js +1 -1
  121. package/dist/index.d.ts +4 -3
  122. package/dist/index.d.ts.map +1 -1
  123. package/dist/index.js +21 -4
  124. package/dist/index.js.map +1 -1
  125. package/dist/internal/crypto/ec/ed25519.d.ts +6 -6
  126. package/dist/internal/crypto/ec/ed25519.js +6 -6
  127. package/dist/internal/crypto/ec/x25519-validation.d.ts.map +1 -1
  128. package/dist/internal/crypto/ec/x25519-validation.js +4 -2
  129. package/dist/internal/crypto/ec/x25519-validation.js.map +1 -1
  130. package/dist/internal/crypto/index.d.ts +2 -0
  131. package/dist/internal/crypto/index.d.ts.map +1 -1
  132. package/dist/internal/crypto/index.js +2 -0
  133. package/dist/internal/crypto/index.js.map +1 -1
  134. package/dist/internal/crypto/kdf/hkdf.d.ts +9 -8
  135. package/dist/internal/crypto/kdf/hkdf.d.ts.map +1 -1
  136. package/dist/internal/crypto/kdf/hkdf.js +11 -10
  137. package/dist/internal/crypto/kdf/hkdf.js.map +1 -1
  138. package/dist/internal/crypto/key-prefix.d.ts +3 -3
  139. package/dist/internal/crypto/key-prefix.js +3 -3
  140. package/dist/internal/crypto/pq/kyber.d.ts +7 -7
  141. package/dist/internal/crypto/pq/kyber.js +10 -10
  142. package/dist/internal/crypto/pq/kyber.js.map +1 -1
  143. package/dist/internal/crypto/random.d.ts +1 -1
  144. package/dist/internal/crypto/random.js +1 -1
  145. package/dist/internal/crypto/symmetric/aes-gcm-siv.js +1 -1
  146. package/dist/internal/crypto/symmetric/aes.js +4 -4
  147. package/dist/internal/crypto/symmetric/aes.js.map +1 -1
  148. package/dist/internal/crypto/symmetric/mac.d.ts +1 -1
  149. package/dist/internal/crypto/symmetric/mac.js +3 -3
  150. package/dist/internal/crypto/symmetric/padding.js +1 -1
  151. package/dist/internal/crypto/symmetric/padding.js.map +1 -1
  152. package/dist/internal/crypto/symmetric/streaming-aead.d.ts +7 -1
  153. package/dist/internal/crypto/symmetric/streaming-aead.d.ts.map +1 -1
  154. package/dist/internal/crypto/symmetric/streaming-aead.js +10 -4
  155. package/dist/internal/crypto/symmetric/streaming-aead.js.map +1 -1
  156. package/dist/internal/crypto/utils.d.ts +2 -2
  157. package/dist/internal/crypto/utils.d.ts.map +1 -1
  158. package/dist/internal/crypto/utils.js +16 -14
  159. package/dist/internal/crypto/utils.js.map +1 -1
  160. package/dist/internal/crypto/validation.d.ts +4 -4
  161. package/dist/internal/crypto/validation.js +2 -2
  162. package/dist/internal/encoding/proto/envelope.d.ts +1 -1
  163. package/dist/internal/encoding/proto/envelope.js +1 -1
  164. package/dist/internal/encoding/proto/index.d.ts +4 -4
  165. package/dist/internal/encoding/proto/index.js +4 -4
  166. package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts +28 -16
  167. package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts.map +1 -1
  168. package/dist/internal/encoding/proto/pq-ratchet-serialize.js +30 -18
  169. package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
  170. package/dist/internal/encoding/proto/primitives.d.ts +45 -35
  171. package/dist/internal/encoding/proto/primitives.d.ts.map +1 -1
  172. package/dist/internal/encoding/proto/primitives.js +54 -43
  173. package/dist/internal/encoding/proto/primitives.js.map +1 -1
  174. package/dist/internal/encoding/proto/sender-key-message.d.ts +2 -2
  175. package/dist/internal/encoding/proto/sender-key-message.js +2 -2
  176. package/dist/internal/encoding/proto/signal-message.d.ts +13 -13
  177. package/dist/internal/encoding/proto/signal-message.d.ts.map +1 -1
  178. package/dist/internal/encoding/proto/signal-message.js +13 -13
  179. package/dist/internal/encoding/proto/signal-message.js.map +1 -1
  180. package/dist/internal/groups/access-control.d.ts +5 -5
  181. package/dist/internal/groups/access-control.js +6 -6
  182. package/dist/internal/groups/access-control.js.map +1 -1
  183. package/dist/internal/groups/change-actions.d.ts +4 -4
  184. package/dist/internal/groups/change-actions.js +3 -3
  185. package/dist/internal/groups/encrypted-state.js +1 -1
  186. package/dist/internal/groups/encrypted-state.js.map +1 -1
  187. package/dist/internal/groups/group-id.d.ts +1 -1
  188. package/dist/internal/groups/manager.d.ts +24 -23
  189. package/dist/internal/groups/manager.d.ts.map +1 -1
  190. package/dist/internal/groups/manager.js +40 -36
  191. package/dist/internal/groups/manager.js.map +1 -1
  192. package/dist/internal/groups/server-engine.d.ts +29 -21
  193. package/dist/internal/groups/server-engine.d.ts.map +1 -1
  194. package/dist/internal/groups/server-engine.js +55 -50
  195. package/dist/internal/groups/server-engine.js.map +1 -1
  196. package/dist/internal/groups/trust-root.d.ts +2 -2
  197. package/dist/internal/groups/trust-root.js +2 -2
  198. package/dist/internal/groups/types.d.ts +4 -4
  199. package/dist/internal/groups/types.d.ts.map +1 -1
  200. package/dist/internal/groups/wire.d.ts +6 -7
  201. package/dist/internal/groups/wire.d.ts.map +1 -1
  202. package/dist/internal/groups/wire.js +6 -7
  203. package/dist/internal/groups/wire.js.map +1 -1
  204. package/dist/internal/manager/manager.d.ts +14 -12
  205. package/dist/internal/manager/manager.d.ts.map +1 -1
  206. package/dist/internal/manager/manager.js +47 -41
  207. package/dist/internal/manager/manager.js.map +1 -1
  208. package/dist/internal/protocol/double-ratchet/chains.d.ts +8 -6
  209. package/dist/internal/protocol/double-ratchet/chains.d.ts.map +1 -1
  210. package/dist/internal/protocol/double-ratchet/chains.js +10 -8
  211. package/dist/internal/protocol/double-ratchet/chains.js.map +1 -1
  212. package/dist/internal/protocol/double-ratchet/index.d.ts +2 -2
  213. package/dist/internal/protocol/double-ratchet/index.js +2 -2
  214. package/dist/internal/protocol/double-ratchet/ratchet.d.ts +4 -4
  215. package/dist/internal/protocol/double-ratchet/ratchet.js +6 -6
  216. package/dist/internal/protocol/pqxdh/pqxdh.d.ts +21 -18
  217. package/dist/internal/protocol/pqxdh/pqxdh.d.ts.map +1 -1
  218. package/dist/internal/protocol/pqxdh/pqxdh.js +48 -42
  219. package/dist/internal/protocol/pqxdh/pqxdh.js.map +1 -1
  220. package/dist/internal/protocol/sealed-sender/decryption-v2.js +5 -5
  221. package/dist/internal/protocol/sealed-sender/decryption-v2.js.map +1 -1
  222. package/dist/internal/protocol/sealed-sender/decryption.d.ts.map +1 -1
  223. package/dist/internal/protocol/sealed-sender/decryption.js +11 -8
  224. package/dist/internal/protocol/sealed-sender/decryption.js.map +1 -1
  225. package/dist/internal/protocol/sealed-sender/delivery-token.d.ts +2 -2
  226. package/dist/internal/protocol/sealed-sender/delivery-token.js +2 -2
  227. package/dist/internal/protocol/sealed-sender/encryption-v2.js +1 -1
  228. package/dist/internal/protocol/sealed-sender/encryption-v2.js.map +1 -1
  229. package/dist/internal/protocol/sealed-sender/encryption.d.ts +2 -2
  230. package/dist/internal/protocol/sealed-sender/encryption.js +2 -2
  231. package/dist/internal/protocol/sealed-sender/proto/index.d.ts +25 -23
  232. package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
  233. package/dist/internal/protocol/sealed-sender/proto/index.js +32 -30
  234. package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
  235. package/dist/internal/protocol/sealed-sender/trust-root.d.ts +10 -9
  236. package/dist/internal/protocol/sealed-sender/trust-root.d.ts.map +1 -1
  237. package/dist/internal/protocol/sealed-sender/trust-root.js +10 -9
  238. package/dist/internal/protocol/sealed-sender/trust-root.js.map +1 -1
  239. package/dist/internal/protocol/sealed-sender/types.d.ts +13 -14
  240. package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
  241. package/dist/internal/protocol/sealed-sender/types.js +7 -8
  242. package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
  243. package/dist/internal/protocol/sealed-sender/v2-binary.d.ts +1 -1
  244. package/dist/internal/protocol/sealed-sender/v2-binary.js +2 -2
  245. package/dist/internal/protocol/sealed-sender/v2-binary.js.map +1 -1
  246. package/dist/internal/protocol/sender-keys/manager.d.ts +16 -14
  247. package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
  248. package/dist/internal/protocol/sender-keys/manager.js +37 -34
  249. package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
  250. package/dist/internal/protocol/spqr/braid-serialize.d.ts +6 -6
  251. package/dist/internal/protocol/spqr/braid-serialize.js +5 -5
  252. package/dist/internal/protocol/spqr/braid-serialize.js.map +1 -1
  253. package/dist/internal/protocol/spqr/braid.d.ts +3 -3
  254. package/dist/internal/protocol/spqr/braid.js +7 -7
  255. package/dist/internal/protocol/spqr/braid.js.map +1 -1
  256. package/dist/internal/protocol/spqr/index.js +1 -1
  257. package/dist/internal/protocol/spqr/index.js.map +1 -1
  258. package/dist/internal/protocol/spqr/ml-kem-braid/chunk-domain.d.ts +3 -3
  259. package/dist/internal/protocol/spqr/ml-kem-braid/chunk-domain.js +3 -3
  260. package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js +1 -1
  261. package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js.map +1 -1
  262. package/dist/internal/protocol/spqr/ml-kem-braid/kdf.d.ts +1 -1
  263. package/dist/internal/protocol/spqr/ml-kem-braid/kdf.js +1 -1
  264. package/dist/internal/protocol/spqr/ml-kem-braid/kdf.js.map +1 -1
  265. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.d.ts +4 -3
  266. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.d.ts.map +1 -1
  267. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.js +4 -3
  268. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.js.map +1 -1
  269. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/index.js +2 -2
  270. package/dist/internal/protocol/spqr/ml-kem-braid/progress.d.ts +1 -1
  271. package/dist/internal/protocol/spqr/ml-kem-braid/progress.js +1 -1
  272. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts +15 -7
  273. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
  274. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js +15 -7
  275. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js.map +1 -1
  276. package/dist/internal/protocol/spqr/ml-kem-braid/rs/galois/field.js +1 -1
  277. package/dist/internal/protocol/spqr/ml-kem-braid/rs/polynomial.d.ts +3 -3
  278. package/dist/internal/protocol/spqr/ml-kem-braid/rs/polynomial.js +1 -1
  279. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts +7 -7
  280. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js +11 -11
  281. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js.map +1 -1
  282. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.d.ts +1 -1
  283. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js +6 -6
  284. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js.map +1 -1
  285. package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts +2 -2
  286. package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts.map +1 -1
  287. package/dist/internal/protocol/spqr/ml-kem-braid/types.js.map +1 -1
  288. package/dist/internal/protocol/spqr/serialize.d.ts +12 -12
  289. package/dist/internal/protocol/spqr/serialize.js +5 -5
  290. package/dist/internal/protocol/spqr/spqr.d.ts +6 -6
  291. package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
  292. package/dist/internal/protocol/spqr/spqr.js +47 -42
  293. package/dist/internal/protocol/spqr/spqr.js.map +1 -1
  294. package/dist/internal/protocol/spqr/validate.d.ts +1 -1
  295. package/dist/internal/protocol/triple-ratchet/ratchet.d.ts +12 -12
  296. package/dist/internal/protocol/triple-ratchet/ratchet.d.ts.map +1 -1
  297. package/dist/internal/protocol/triple-ratchet/ratchet.js +11 -11
  298. package/dist/internal/protocol/triple-ratchet/ratchet.js.map +1 -1
  299. package/dist/internal/protocol/username/hash.d.ts.map +1 -1
  300. package/dist/internal/protocol/username/hash.js +6 -4
  301. package/dist/internal/protocol/username/hash.js.map +1 -1
  302. package/dist/internal/protocol/version.d.ts +3 -3
  303. package/dist/internal/protocol/version.js +1 -1
  304. package/dist/internal/protocol/x3dh/x3dh.d.ts +16 -16
  305. package/dist/internal/protocol/x3dh/x3dh.d.ts.map +1 -1
  306. package/dist/internal/protocol/x3dh/x3dh.js +15 -15
  307. package/dist/internal/protocol/x3dh/x3dh.js.map +1 -1
  308. package/dist/internal/protocol/zk/credentials/attributes.d.ts +7 -7
  309. package/dist/internal/protocol/zk/credentials/attributes.js +7 -7
  310. package/dist/internal/protocol/zk/credentials/credentials.d.ts +1 -1
  311. package/dist/internal/protocol/zk/credentials/credentials.js +1 -1
  312. package/dist/internal/protocol/zk/credentials/endorsements.d.ts +11 -11
  313. package/dist/internal/protocol/zk/credentials/endorsements.js +14 -14
  314. package/dist/internal/protocol/zk/credentials/issuance.d.ts +5 -1
  315. package/dist/internal/protocol/zk/credentials/issuance.d.ts.map +1 -1
  316. package/dist/internal/protocol/zk/credentials/issuance.js +5 -1
  317. package/dist/internal/protocol/zk/credentials/issuance.js.map +1 -1
  318. package/dist/internal/protocol/zk/credentials/presentation.d.ts +16 -16
  319. package/dist/internal/protocol/zk/credentials/presentation.d.ts.map +1 -1
  320. package/dist/internal/protocol/zk/credentials/presentation.js +18 -18
  321. package/dist/internal/protocol/zk/credentials/presentation.js.map +1 -1
  322. package/dist/internal/protocol/zk/groups/auth-credential.d.ts +22 -16
  323. package/dist/internal/protocol/zk/groups/auth-credential.d.ts.map +1 -1
  324. package/dist/internal/protocol/zk/groups/auth-credential.js +19 -14
  325. package/dist/internal/protocol/zk/groups/auth-credential.js.map +1 -1
  326. package/dist/internal/protocol/zk/groups/client-zk-group-cipher.d.ts +4 -4
  327. package/dist/internal/protocol/zk/groups/client-zk-group-cipher.js +4 -4
  328. package/dist/internal/protocol/zk/groups/group-params.d.ts +2 -2
  329. package/dist/internal/protocol/zk/groups/group-params.js +2 -2
  330. package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts +10 -9
  331. package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts.map +1 -1
  332. package/dist/internal/protocol/zk/groups/group-send-endorsement.js +9 -8
  333. package/dist/internal/protocol/zk/groups/group-send-endorsement.js.map +1 -1
  334. package/dist/internal/protocol/zk/groups/lizard.d.ts +1 -1
  335. package/dist/internal/protocol/zk/groups/lizard.js +4 -4
  336. package/dist/internal/protocol/zk/groups/lizard.js.map +1 -1
  337. package/dist/internal/protocol/zk/groups/profile-key-commitment.d.ts +3 -3
  338. package/dist/internal/protocol/zk/groups/profile-key-commitment.js +3 -3
  339. package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts +11 -11
  340. package/dist/internal/protocol/zk/groups/profile-key-credential.js +7 -7
  341. package/dist/internal/protocol/zk/groups/profile-key-encryption.d.ts +2 -2
  342. package/dist/internal/protocol/zk/groups/profile-key-encryption.js +2 -2
  343. package/dist/internal/protocol/zk/groups/profile-key-struct.d.ts +2 -2
  344. package/dist/internal/protocol/zk/groups/profile-key-struct.js +2 -2
  345. package/dist/internal/protocol/zk/groups/profile-key-version.d.ts +2 -2
  346. package/dist/internal/protocol/zk/groups/profile-key-version.js +2 -2
  347. package/dist/internal/protocol/zk/groups/server-params.d.ts +1 -1
  348. package/dist/internal/protocol/zk/groups/server-params.js +1 -1
  349. package/dist/internal/protocol/zk/groups/uid-encryption.d.ts +4 -4
  350. package/dist/internal/protocol/zk/groups/uid-encryption.js +4 -4
  351. package/dist/internal/protocol/zk/groups/uid-struct.d.ts +2 -2
  352. package/dist/internal/protocol/zk/groups/uid-struct.js +3 -3
  353. package/dist/internal/protocol/zk/groups/uid-struct.js.map +1 -1
  354. package/dist/internal/protocol/zk/proofs/args.d.ts +3 -3
  355. package/dist/internal/protocol/zk/proofs/args.js +3 -3
  356. package/dist/internal/protocol/zk/proofs/sho-sha256.d.ts +3 -3
  357. package/dist/internal/protocol/zk/proofs/sho-sha256.js +3 -3
  358. package/dist/internal/protocol/zk/proofs/sho.d.ts +8 -7
  359. package/dist/internal/protocol/zk/proofs/sho.d.ts.map +1 -1
  360. package/dist/internal/protocol/zk/proofs/sho.js +8 -7
  361. package/dist/internal/protocol/zk/proofs/sho.js.map +1 -1
  362. package/dist/internal/protocol/zk/proofs/statement.d.ts +8 -6
  363. package/dist/internal/protocol/zk/proofs/statement.d.ts.map +1 -1
  364. package/dist/internal/protocol/zk/proofs/statement.js +8 -6
  365. package/dist/internal/protocol/zk/proofs/statement.js.map +1 -1
  366. package/dist/internal/sesame/manager.d.ts +23 -19
  367. package/dist/internal/sesame/manager.d.ts.map +1 -1
  368. package/dist/internal/sesame/manager.js +64 -54
  369. package/dist/internal/sesame/manager.js.map +1 -1
  370. package/dist/internal/sesame/types.d.ts +28 -27
  371. package/dist/internal/sesame/types.d.ts.map +1 -1
  372. package/dist/internal/sesame/types.js +2 -4
  373. package/dist/internal/sesame/types.js.map +1 -1
  374. package/dist/internal/sesame/validation.d.ts +2 -2
  375. package/dist/internal/sesame/validation.js +3 -3
  376. package/dist/internal/sesame/validation.js.map +1 -1
  377. package/dist/internal/session/builder.d.ts +8 -8
  378. package/dist/internal/session/builder.js +22 -22
  379. package/dist/internal/session/builder.js.map +1 -1
  380. package/dist/internal/session/cipher.d.ts +3 -3
  381. package/dist/internal/session/cipher.d.ts.map +1 -1
  382. package/dist/internal/session/cipher.js +51 -40
  383. package/dist/internal/session/cipher.js.map +1 -1
  384. package/dist/internal/session/decryption.js +11 -9
  385. package/dist/internal/session/decryption.js.map +1 -1
  386. package/dist/internal/session/factory.js +1 -1
  387. package/dist/internal/session/factory.js.map +1 -1
  388. package/dist/internal/session/handshake.d.ts +4 -4
  389. package/dist/internal/session/handshake.js +4 -4
  390. package/dist/internal/session/keys.d.ts +3 -4
  391. package/dist/internal/session/keys.d.ts.map +1 -1
  392. package/dist/internal/session/keys.js.map +1 -1
  393. package/dist/internal/session/ratchet.d.ts +8 -8
  394. package/dist/internal/session/ratchet.js +10 -10
  395. package/dist/internal/session/ratchet.js.map +1 -1
  396. package/dist/internal/session/session-resolver.d.ts +6 -6
  397. package/dist/internal/session/session-resolver.js +6 -6
  398. package/dist/internal/session/state.d.ts +12 -12
  399. package/dist/internal/session/state.d.ts.map +1 -1
  400. package/dist/internal/session/state.js +7 -7
  401. package/dist/internal/session/types.d.ts +20 -20
  402. package/dist/internal/session/types.d.ts.map +1 -1
  403. package/dist/internal/session/types.js +3 -3
  404. package/dist/internal/session/validation.d.ts +1 -1
  405. package/dist/internal/session/validation.js +4 -4
  406. package/dist/internal/session/validation.js.map +1 -1
  407. package/dist/keys/branded.d.ts +12 -12
  408. package/dist/keys/branded.js +3 -3
  409. package/dist/keys/generation.d.ts +4 -4
  410. package/dist/keys/generation.js +4 -4
  411. package/dist/keys/identity.d.ts +7 -7
  412. package/dist/keys/identity.d.ts.map +1 -1
  413. package/dist/keys/identity.js +7 -7
  414. package/dist/keys/identity.js.map +1 -1
  415. package/dist/keys/types.d.ts +16 -16
  416. package/dist/keys/types.d.ts.map +1 -1
  417. package/dist/layers.d.ts +1 -1
  418. package/dist/layers.js +1 -1
  419. package/dist/local/store/expo/adapter.d.ts +8 -8
  420. package/dist/local/store/expo/adapter.js +10 -10
  421. package/dist/local/store/expo/adapter.js.map +1 -1
  422. package/dist/local/store/expo/database-key.d.ts +7 -7
  423. package/dist/local/store/expo/database-key.js +7 -7
  424. package/dist/local/store/expo/key-storage.d.ts +1 -1
  425. package/dist/local/store/expo/key-storage.js +4 -4
  426. package/dist/local/store/expo/key-storage.js.map +1 -1
  427. package/dist/local/store/expo/models/kyber-prekey-used.d.ts +6 -6
  428. package/dist/local/store/expo/models/kyber-prekey-used.js +3 -3
  429. package/dist/local/store/expo/models/kyber-prekey.d.ts +1 -1
  430. package/dist/local/store/expo/models/kyber-prekey.js +1 -1
  431. package/dist/local/store/expo/models/message-record.d.ts +2 -2
  432. package/dist/local/store/expo/models/message-record.d.ts.map +1 -1
  433. package/dist/local/store/expo/models/message-record.js +1 -1
  434. package/dist/local/store/expo/models/message-record.js.map +1 -1
  435. package/dist/local/store/expo/models/sender-key.d.ts +11 -10
  436. package/dist/local/store/expo/models/sender-key.d.ts.map +1 -1
  437. package/dist/local/store/expo/models/sender-key.js +11 -10
  438. package/dist/local/store/expo/models/sender-key.js.map +1 -1
  439. package/dist/local/store/expo/schema.d.ts +2 -2
  440. package/dist/local/store/expo/schema.js +2 -2
  441. package/dist/local/store/expo/secure-store-options.d.ts +1 -1
  442. package/dist/local/store/memory/adapter.d.ts +2 -2
  443. package/dist/local/store/memory/adapter.js +12 -12
  444. package/dist/local/store/memory/adapter.js.map +1 -1
  445. package/dist/local/store/node/adapter.d.ts.map +1 -1
  446. package/dist/local/store/node/adapter.js +5 -4
  447. package/dist/local/store/node/adapter.js.map +1 -1
  448. package/dist/local/store/node/database-key.d.ts +8 -8
  449. package/dist/local/store/node/database-key.js +10 -10
  450. package/dist/local/store/node/database-key.js.map +1 -1
  451. package/dist/local/store/node/database.d.ts +5 -5
  452. package/dist/local/store/node/database.js +11 -11
  453. package/dist/local/store/node/database.js.map +1 -1
  454. package/dist/local/store/react-native/adapter.d.ts +6 -6
  455. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  456. package/dist/local/store/react-native/adapter.js +35 -32
  457. package/dist/local/store/react-native/adapter.js.map +1 -1
  458. package/dist/local/store/react-native/backend-conformance.d.ts +11 -10
  459. package/dist/local/store/react-native/backend-conformance.d.ts.map +1 -1
  460. package/dist/local/store/react-native/backend-conformance.js +13 -12
  461. package/dist/local/store/react-native/backend-conformance.js.map +1 -1
  462. package/dist/local/store/react-native/index.d.ts +1 -1
  463. package/dist/local/store/react-native/reference-backend.d.ts +14 -13
  464. package/dist/local/store/react-native/reference-backend.d.ts.map +1 -1
  465. package/dist/local/store/react-native/reference-backend.js +15 -14
  466. package/dist/local/store/react-native/reference-backend.js.map +1 -1
  467. package/dist/local/store/react-native/storage.d.ts +3 -3
  468. package/dist/local/store/web/adapter.d.ts +3 -3
  469. package/dist/local/store/web/adapter.d.ts.map +1 -1
  470. package/dist/local/store/web/adapter.js +30 -31
  471. package/dist/local/store/web/adapter.js.map +1 -1
  472. package/dist/local/store/web/index.d.ts +1 -1
  473. package/dist/local/vault/index.d.ts +2 -2
  474. package/dist/media/index.d.ts +11 -12
  475. package/dist/media/index.d.ts.map +1 -1
  476. package/dist/media/index.js +9 -10
  477. package/dist/media/index.js.map +1 -1
  478. package/dist/profile/contact-state.d.ts +1 -1
  479. package/dist/profile/contact-state.js +1 -1
  480. package/dist/profile/profile-key.d.ts +2 -2
  481. package/dist/profile/profile-key.js +7 -6
  482. package/dist/profile/profile-key.js.map +1 -1
  483. package/dist/remote/object-store/index.d.ts +1 -1
  484. package/dist/remote/object-store/s3/storage.d.ts +1 -1
  485. package/dist/remote/object-store/types.d.ts +4 -4
  486. package/dist/remote/object-store/types.d.ts.map +1 -1
  487. package/dist/remote/relay/convex/backend.d.ts +6 -6
  488. package/dist/remote/relay/convex/backend.d.ts.map +1 -1
  489. package/dist/remote/relay/convex/backend.js +4 -4
  490. package/dist/remote/relay/convex/backend.js.map +1 -1
  491. package/dist/remote/relay/convex/component/_generated/component.d.ts +2 -2
  492. package/dist/remote/relay/convex/component/_generated/component.d.ts.map +1 -1
  493. package/dist/remote/relay/convex/component/accounts.d.ts +15 -13
  494. package/dist/remote/relay/convex/component/accounts.d.ts.map +1 -1
  495. package/dist/remote/relay/convex/component/accounts.js +31 -28
  496. package/dist/remote/relay/convex/component/accounts.js.map +1 -1
  497. package/dist/remote/relay/convex/component/certificates.js +1 -1
  498. package/dist/remote/relay/convex/component/cleanup.js +7 -7
  499. package/dist/remote/relay/convex/component/cleanup.js.map +1 -1
  500. package/dist/remote/relay/convex/component/convex.config.d.ts.map +1 -1
  501. package/dist/remote/relay/convex/component/convex.config.js +10 -8
  502. package/dist/remote/relay/convex/component/convex.config.js.map +1 -1
  503. package/dist/remote/relay/convex/component/devices.d.ts +21 -20
  504. package/dist/remote/relay/convex/component/devices.d.ts.map +1 -1
  505. package/dist/remote/relay/convex/component/devices.js +24 -23
  506. package/dist/remote/relay/convex/component/devices.js.map +1 -1
  507. package/dist/remote/relay/convex/component/groups.js +6 -6
  508. package/dist/remote/relay/convex/component/groups.js.map +1 -1
  509. package/dist/remote/relay/convex/component/messages.d.ts +2 -2
  510. package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
  511. package/dist/remote/relay/convex/component/messages.js +90 -83
  512. package/dist/remote/relay/convex/component/messages.js.map +1 -1
  513. package/dist/remote/relay/convex/component/provisioning.d.ts +3 -3
  514. package/dist/remote/relay/convex/component/provisioning.d.ts.map +1 -1
  515. package/dist/remote/relay/convex/component/provisioning.js +17 -16
  516. package/dist/remote/relay/convex/component/provisioning.js.map +1 -1
  517. package/dist/remote/relay/convex/component/runtime.d.ts.map +1 -1
  518. package/dist/remote/relay/convex/component/runtime.js +4 -2
  519. package/dist/remote/relay/convex/component/runtime.js.map +1 -1
  520. package/dist/remote/relay/convex/component/schema.d.ts +2 -2
  521. package/dist/remote/relay/convex/component/schema.js +26 -25
  522. package/dist/remote/relay/convex/component/schema.js.map +1 -1
  523. package/dist/remote/relay/convex/group-server.d.ts +3 -3
  524. package/dist/remote/relay/convex/group-server.js +3 -3
  525. package/dist/remote/relay/convex/relay.d.ts +3 -3
  526. package/dist/remote/relay/convex/relay.d.ts.map +1 -1
  527. package/dist/remote/relay/convex/relay.js +18 -17
  528. package/dist/remote/relay/convex/relay.js.map +1 -1
  529. package/dist/remote/relay/convex/types.d.ts +7 -7
  530. package/dist/remote/relay/convex/types.js +4 -4
  531. package/dist/remote/relay/memory/adapter.js +9 -9
  532. package/dist/remote/relay/memory/adapter.js.map +1 -1
  533. package/dist/remote/relay/types.d.ts +27 -27
  534. package/dist/remote/relay/types.d.ts.map +1 -1
  535. package/dist/safety/fingerprint.d.ts +7 -6
  536. package/dist/safety/fingerprint.d.ts.map +1 -1
  537. package/dist/safety/fingerprint.js +5 -4
  538. package/dist/safety/fingerprint.js.map +1 -1
  539. package/dist/safety/index.d.ts +6 -5
  540. package/dist/safety/index.d.ts.map +1 -1
  541. package/dist/safety/index.js +7 -6
  542. package/dist/safety/index.js.map +1 -1
  543. package/dist/safety/protobuf.js +2 -2
  544. package/dist/safety/protobuf.js.map +1 -1
  545. package/dist/safety/url.d.ts +5 -5
  546. package/dist/safety/url.js +6 -6
  547. package/dist/types/address.d.ts +2 -2
  548. package/dist/types/address.js +2 -2
  549. package/dist/types/api.d.ts +78 -73
  550. package/dist/types/api.d.ts.map +1 -1
  551. package/dist/types/errors.d.ts +63 -403
  552. package/dist/types/errors.d.ts.map +1 -1
  553. package/dist/types/errors.js +62 -537
  554. package/dist/types/errors.js.map +1 -1
  555. package/dist/types/messages.d.ts +16 -16
  556. package/dist/types/messages.d.ts.map +1 -1
  557. package/dist/types/messages.js +7 -7
  558. package/dist/types/messages.js.map +1 -1
  559. package/dist/types/protocol-config.d.ts +52 -49
  560. package/dist/types/protocol-config.d.ts.map +1 -1
  561. package/dist/types/protocol-config.js +36 -34
  562. package/dist/types/protocol-config.js.map +1 -1
  563. package/dist/types/protocol-constants.d.ts +2 -2
  564. package/dist/types/protocol-constants.js +2 -2
  565. package/dist/types/session.d.ts +62 -61
  566. package/dist/types/session.d.ts.map +1 -1
  567. package/dist/types/session.js +13 -14
  568. package/dist/types/session.js.map +1 -1
  569. package/dist/types/trust.d.ts +8 -8
  570. package/dist/types/trust.js +3 -3
  571. package/dist/utils/retry.d.ts +2 -1
  572. package/dist/utils/retry.d.ts.map +1 -1
  573. package/dist/utils/retry.js +4 -5
  574. package/dist/utils/retry.js.map +1 -1
  575. package/docs/ASSURANCE.md +89 -75
  576. package/docs/CLIENT_COMPOSITION.md +22 -15
  577. package/docs/DEVIATIONS.md +507 -425
  578. package/docs/DOCUMENTATION_STANDARDS.md +52 -24
  579. package/docs/E2EE.md +45 -42
  580. package/docs/ERROR_HANDLING.md +107 -152
  581. package/docs/GETTING_STARTED.md +44 -26
  582. package/docs/INTERFACES.md +32 -18
  583. package/docs/PACKAGE_SURFACE.md +24 -21
  584. package/docs/PROTOCOL_POLICY.md +25 -13
  585. package/docs/RECIPES.md +13 -4
  586. package/docs/SECURITY.md +72 -60
  587. package/encoding/README.md +3 -2
  588. package/files/README.md +2 -1
  589. package/groups/README.md +5 -3
  590. package/hooks/README.md +2 -2
  591. package/keys/README.md +17 -14
  592. package/local/store/README.md +84 -67
  593. package/local/store/expo/README.md +19 -12
  594. package/local/store/memory/README.md +6 -3
  595. package/local/store/node/README.md +9 -6
  596. package/local/store/react-native/README.md +16 -12
  597. package/local/store/web/README.md +32 -26
  598. package/local/vault/README.md +5 -4
  599. package/media/README.md +8 -5
  600. package/package.json +4 -2
  601. package/profile/README.md +8 -7
  602. package/remote/README.md +26 -18
  603. package/remote/object-store/README.md +9 -4
  604. package/remote/object-store/convex-r2/README.md +5 -3
  605. package/remote/object-store/s3/README.md +11 -5
  606. package/remote/relay/README.md +2 -0
  607. package/remote/relay/convex/README.md +6 -5
  608. package/remote/relay/convex/component/README.md +154 -124
  609. package/remote/relay/memory/README.md +8 -5
  610. package/safety/README.md +2 -1
  611. package/sealed-sender/README.md +4 -2
  612. package/types/README.md +2 -1
  613. package/username/README.md +1 -0
  614. package/utils/README.md +5 -4
  615. package/zk/README.md +1 -0
@@ -1,6 +1,6 @@
1
1
  # Error Handling Guide
2
2
 
3
- Comprehensive guide to error handling in the `@open-e2ee/signal-protocol-sdk` library.
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
- All signal protocol errors extend `EncryptionError`:
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(sessionId, plaintext);
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(sessionId, remoteAddress, bundle);
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
- #### IdentityKeyChangedError
57
-
58
- Thrown when a remote party's identity key has changed. Could indicate:
58
+ ## Error Codes
59
59
 
60
- - Legitimate: Device reinstall, new device, backup restoration
61
- - Attack: Man-in-the-middle attack
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
- ```typescript
64
- import { isIdentityKeyChangedError } from '@open-e2ee/signal-protocol-sdk';
66
+ The tables list the complete `EncryptionErrorCode` enum. The error-surface check
67
+ holds each member to a production construction site.
65
68
 
66
- try {
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
- ```typescript
86
- import { isSessionConflictError } from '@open-e2ee/signal-protocol-sdk';
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
- try {
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
- #### RegistrationIdChangedError
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
- Thrown when a remote party's registration ID has changed (app reinstall detected).
91
+ ### Identity and Trust Errors
102
92
 
103
- ```typescript
104
- import { isRegistrationIdChangedError } from '@open-e2ee/signal-protocol-sdk';
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
- try {
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
- ## Error Codes
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
- ### Session Errors
107
+ ### Ratchet Errors
121
108
 
122
- | Code | Description | Recovery |
123
- | ------------------- | --------------------------------- | ----------------------- |
124
- | `SESSION_NOT_FOUND` | No session exists for the address | Establish new session |
125
- | `SESSION_CORRUPTED` | Session data is invalid | Delete and re-establish |
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
- ### Message Errors
114
+ ### Storage Errors
129
115
 
130
- | Code | Description | Recovery |
131
- | --------------------------- | --------------------------- | -------------------------- |
132
- | `INVALID_CIPHERTEXT` | Message format is malformed | Request retransmission |
133
- | `DECRYPTION_FAILED` | Could not decrypt message | Check session state |
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
- ### Ratchet Errors
121
+ ### Initialization and Protocol Policy Errors
158
122
 
159
- | Code | Description | Recovery |
160
- | ---------------- | ----------------- | -------------- |
161
- | `RATCHET_ERROR` | DH ratchet failed | Reset session |
162
- | `INVALID_DH_KEY` | DH key is invalid | Reject message |
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
- ### Storage Errors
130
+ ### SPQR Errors
165
131
 
166
- | Code | Description | Recovery |
167
- | ------------------- | ------------------------- | --------------------- |
168
- | `KEY_STORAGE_ERROR` | Storage operation failed | Retry or reinitialize |
169
- | `DATABASE_ERROR` | Database operation failed | Check DB connection |
170
- | `DATABASE_LOCKED` | Database is inaccessible | Check encryption key |
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
- ### Cryptographic Errors
140
+ ### Sealed Sender and State Errors
173
141
 
174
- | Code | Description | Recovery |
175
- | -------------------------- | ----------------------------- | ---------------- |
176
- | `KYBER_ERROR` | Post-quantum operation failed | Check Kyber keys |
177
- | `KDF_ERROR` | Key derivation failed | Check input keys |
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
- ### Comprehensive Error Handler
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
- isIdentityKeyChangedError,
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 (isIdentityKeyChangedError(error)) {
206
- await handleIdentityKeyChanged(error);
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 sessionId = `${userId}_${deviceId}`;
243
+ const remoteAddress = ProtocolAddress.create(userId, deviceId);
276
244
 
277
245
  try {
278
- const hasSession = await signal.hasSession(sessionId);
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(sessionId, `${userId}_${deviceId}`, bundle);
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(sessionId);
257
+ await signal.deleteSession(remoteAddress);
290
258
  const bundle = await fetchPreKeyBundle(userId, deviceId);
291
- await signal.establishSession(sessionId, `${userId}_${deviceId}`, bundle);
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(sessionId, `${userId}_${deviceId}`, newBundle);
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
- // Good: Use type guards for specialized errors
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
- // Bad: instanceof check without import
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 (isIdentityKeyChangedError(error)) {
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
- // not the bare key carried on the error, and resets the sessions bound to
373
- // the retired identity.
374
- const userId = error.changedAddress.userId;
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