@open-e2ee/signal-protocol-sdk 0.2.3 → 0.3.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 (601) hide show
  1. package/ADAPTERS.md +4 -4
  2. package/ARCHITECTURE.md +17 -16
  3. package/CHANGELOG.md +39 -0
  4. package/COMMERCIAL.md +6 -6
  5. package/NOTICE +1 -1
  6. package/README.md +44 -34
  7. package/SECURITY.md +16 -13
  8. package/TROUBLESHOOTING.md +5 -5
  9. package/blocking/README.md +6 -5
  10. package/client/README.md +5 -5
  11. package/device/README.md +8 -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/headless.d.ts +7 -7
  36. package/dist/client/headless.d.ts.map +1 -1
  37. package/dist/client/headless.js +4 -4
  38. package/dist/client/key-rotation-core.d.ts +19 -17
  39. package/dist/client/key-rotation-core.d.ts.map +1 -1
  40. package/dist/client/key-rotation-core.js +35 -31
  41. package/dist/client/key-rotation-core.js.map +1 -1
  42. package/dist/client/key-rotation.d.ts +8 -8
  43. package/dist/client/key-rotation.js +8 -8
  44. package/dist/client/media.d.ts +1 -1
  45. package/dist/client/messages.d.ts.map +1 -1
  46. package/dist/client/messages.js +13 -11
  47. package/dist/client/messages.js.map +1 -1
  48. package/dist/client/multi-device.d.ts +5 -4
  49. package/dist/client/multi-device.d.ts.map +1 -1
  50. package/dist/client/multi-device.js.map +1 -1
  51. package/dist/client/prekeys.d.ts +7 -7
  52. package/dist/client/prekeys.js +10 -10
  53. package/dist/client/prekeys.js.map +1 -1
  54. package/dist/client/relay-subscription.d.ts +3 -0
  55. package/dist/client/relay-subscription.d.ts.map +1 -1
  56. package/dist/client/relay-subscription.js +7 -4
  57. package/dist/client/relay-subscription.js.map +1 -1
  58. package/dist/client/retry-utils.d.ts +5 -6
  59. package/dist/client/retry-utils.d.ts.map +1 -1
  60. package/dist/client/retry-utils.js +5 -12
  61. package/dist/client/retry-utils.js.map +1 -1
  62. package/dist/client/retry.js +7 -7
  63. package/dist/client/retry.js.map +1 -1
  64. package/dist/client/sealed-sender-ops.d.ts +3 -3
  65. package/dist/client/sealed-sender-ops.js +5 -5
  66. package/dist/client/sealed-sender-ops.js.map +1 -1
  67. package/dist/client/sessions.d.ts +2 -2
  68. package/dist/client/sessions.js +2 -2
  69. package/dist/client/signal-service-cipher.d.ts +9 -9
  70. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  71. package/dist/client/signal-service-cipher.js +41 -40
  72. package/dist/client/signal-service-cipher.js.map +1 -1
  73. package/dist/client/state.d.ts +1 -1
  74. package/dist/client/state.js +1 -1
  75. package/dist/client/types.d.ts +19 -19
  76. package/dist/client/types.d.ts.map +1 -1
  77. package/dist/device/connection.d.ts +1 -1
  78. package/dist/device/connection.js +2 -2
  79. package/dist/device/connection.js.map +1 -1
  80. package/dist/device/constants.d.ts +4 -4
  81. package/dist/device/constants.js +3 -3
  82. package/dist/device/device-id.d.ts +4 -4
  83. package/dist/device/device-id.js +4 -4
  84. package/dist/device/expo-metadata.d.ts +13 -11
  85. package/dist/device/expo-metadata.d.ts.map +1 -1
  86. package/dist/device/expo-metadata.js +13 -11
  87. package/dist/device/expo-metadata.js.map +1 -1
  88. package/dist/device/lifecycle/manager.d.ts +6 -6
  89. package/dist/device/lifecycle/manager.js +7 -7
  90. package/dist/device/lifecycle/types.d.ts +13 -13
  91. package/dist/device/lifecycle/types.d.ts.map +1 -1
  92. package/dist/device/lifecycle/utils.d.ts +2 -2
  93. package/dist/device/lifecycle/utils.js +5 -5
  94. package/dist/device/lifecycle/utils.js.map +1 -1
  95. package/dist/device/provisioning.d.ts +5 -4
  96. package/dist/device/provisioning.d.ts.map +1 -1
  97. package/dist/device/provisioning.js +5 -4
  98. package/dist/device/provisioning.js.map +1 -1
  99. package/dist/device/transfer.d.ts +2 -2
  100. package/dist/device/transfer.js +3 -3
  101. package/dist/device/transfer.js.map +1 -1
  102. package/dist/encoding/index.d.ts +3 -4
  103. package/dist/encoding/index.d.ts.map +1 -1
  104. package/dist/encoding/index.js.map +1 -1
  105. package/dist/files/index.d.ts +1 -1
  106. package/dist/files/index.js +1 -1
  107. package/dist/hooks/use-connection-presence.d.ts +1 -1
  108. package/dist/hooks/use-connection-presence.js +7 -7
  109. package/dist/hooks/use-connection-presence.js.map +1 -1
  110. package/dist/hooks/use-group-membership.d.ts +2 -2
  111. package/dist/hooks/use-group-membership.d.ts.map +1 -1
  112. package/dist/hooks/use-group-membership.js +6 -6
  113. package/dist/hooks/use-group-membership.js.map +1 -1
  114. package/dist/hooks/use-key-rotation.js +3 -3
  115. package/dist/hooks/use-key-rotation.js.map +1 -1
  116. package/dist/hooks/use-single-flight.d.ts +2 -2
  117. package/dist/hooks/use-single-flight.js +1 -1
  118. package/dist/index.d.ts +4 -3
  119. package/dist/index.d.ts.map +1 -1
  120. package/dist/index.js +22 -4
  121. package/dist/index.js.map +1 -1
  122. package/dist/internal/crypto/ec/ed25519.d.ts +6 -6
  123. package/dist/internal/crypto/ec/ed25519.js +6 -6
  124. package/dist/internal/crypto/ec/x25519-validation.d.ts.map +1 -1
  125. package/dist/internal/crypto/ec/x25519-validation.js +4 -2
  126. package/dist/internal/crypto/ec/x25519-validation.js.map +1 -1
  127. package/dist/internal/crypto/index.d.ts +2 -0
  128. package/dist/internal/crypto/index.d.ts.map +1 -1
  129. package/dist/internal/crypto/index.js +2 -0
  130. package/dist/internal/crypto/index.js.map +1 -1
  131. package/dist/internal/crypto/kdf/hkdf.d.ts +9 -8
  132. package/dist/internal/crypto/kdf/hkdf.d.ts.map +1 -1
  133. package/dist/internal/crypto/kdf/hkdf.js +11 -10
  134. package/dist/internal/crypto/kdf/hkdf.js.map +1 -1
  135. package/dist/internal/crypto/key-prefix.d.ts +3 -3
  136. package/dist/internal/crypto/key-prefix.js +3 -3
  137. package/dist/internal/crypto/pq/kyber.d.ts +7 -7
  138. package/dist/internal/crypto/pq/kyber.js +10 -10
  139. package/dist/internal/crypto/pq/kyber.js.map +1 -1
  140. package/dist/internal/crypto/random.d.ts +1 -1
  141. package/dist/internal/crypto/random.js +1 -1
  142. package/dist/internal/crypto/symmetric/aes-gcm-siv.js +1 -1
  143. package/dist/internal/crypto/symmetric/aes.js +4 -4
  144. package/dist/internal/crypto/symmetric/aes.js.map +1 -1
  145. package/dist/internal/crypto/symmetric/mac.d.ts +1 -1
  146. package/dist/internal/crypto/symmetric/mac.js +3 -3
  147. package/dist/internal/crypto/symmetric/padding.js +1 -1
  148. package/dist/internal/crypto/symmetric/padding.js.map +1 -1
  149. package/dist/internal/crypto/symmetric/streaming-aead.d.ts +7 -1
  150. package/dist/internal/crypto/symmetric/streaming-aead.d.ts.map +1 -1
  151. package/dist/internal/crypto/symmetric/streaming-aead.js +10 -4
  152. package/dist/internal/crypto/symmetric/streaming-aead.js.map +1 -1
  153. package/dist/internal/crypto/utils.d.ts +2 -2
  154. package/dist/internal/crypto/utils.d.ts.map +1 -1
  155. package/dist/internal/crypto/utils.js +16 -14
  156. package/dist/internal/crypto/utils.js.map +1 -1
  157. package/dist/internal/crypto/validation.d.ts +4 -4
  158. package/dist/internal/crypto/validation.js +2 -2
  159. package/dist/internal/encoding/proto/envelope.d.ts +1 -1
  160. package/dist/internal/encoding/proto/envelope.js +1 -1
  161. package/dist/internal/encoding/proto/index.d.ts +4 -4
  162. package/dist/internal/encoding/proto/index.js +4 -4
  163. package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts +28 -16
  164. package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts.map +1 -1
  165. package/dist/internal/encoding/proto/pq-ratchet-serialize.js +30 -18
  166. package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
  167. package/dist/internal/encoding/proto/primitives.d.ts +45 -35
  168. package/dist/internal/encoding/proto/primitives.d.ts.map +1 -1
  169. package/dist/internal/encoding/proto/primitives.js +54 -43
  170. package/dist/internal/encoding/proto/primitives.js.map +1 -1
  171. package/dist/internal/encoding/proto/sender-key-message.d.ts +2 -2
  172. package/dist/internal/encoding/proto/sender-key-message.js +2 -2
  173. package/dist/internal/encoding/proto/signal-message.d.ts +13 -13
  174. package/dist/internal/encoding/proto/signal-message.d.ts.map +1 -1
  175. package/dist/internal/encoding/proto/signal-message.js +13 -13
  176. package/dist/internal/encoding/proto/signal-message.js.map +1 -1
  177. package/dist/internal/groups/access-control.d.ts +5 -5
  178. package/dist/internal/groups/access-control.js +6 -6
  179. package/dist/internal/groups/access-control.js.map +1 -1
  180. package/dist/internal/groups/change-actions.d.ts +4 -4
  181. package/dist/internal/groups/change-actions.js +3 -3
  182. package/dist/internal/groups/encrypted-state.js +1 -1
  183. package/dist/internal/groups/encrypted-state.js.map +1 -1
  184. package/dist/internal/groups/group-id.d.ts +1 -1
  185. package/dist/internal/groups/manager.d.ts +24 -23
  186. package/dist/internal/groups/manager.d.ts.map +1 -1
  187. package/dist/internal/groups/manager.js +40 -36
  188. package/dist/internal/groups/manager.js.map +1 -1
  189. package/dist/internal/groups/server-engine.d.ts +29 -21
  190. package/dist/internal/groups/server-engine.d.ts.map +1 -1
  191. package/dist/internal/groups/server-engine.js +55 -50
  192. package/dist/internal/groups/server-engine.js.map +1 -1
  193. package/dist/internal/groups/trust-root.d.ts +2 -2
  194. package/dist/internal/groups/trust-root.js +2 -2
  195. package/dist/internal/groups/types.d.ts +4 -4
  196. package/dist/internal/groups/types.d.ts.map +1 -1
  197. package/dist/internal/groups/wire.d.ts +6 -7
  198. package/dist/internal/groups/wire.d.ts.map +1 -1
  199. package/dist/internal/groups/wire.js +6 -7
  200. package/dist/internal/groups/wire.js.map +1 -1
  201. package/dist/internal/manager/manager.d.ts +14 -12
  202. package/dist/internal/manager/manager.d.ts.map +1 -1
  203. package/dist/internal/manager/manager.js +47 -41
  204. package/dist/internal/manager/manager.js.map +1 -1
  205. package/dist/internal/protocol/double-ratchet/chains.d.ts +8 -6
  206. package/dist/internal/protocol/double-ratchet/chains.d.ts.map +1 -1
  207. package/dist/internal/protocol/double-ratchet/chains.js +10 -8
  208. package/dist/internal/protocol/double-ratchet/chains.js.map +1 -1
  209. package/dist/internal/protocol/double-ratchet/index.d.ts +2 -2
  210. package/dist/internal/protocol/double-ratchet/index.js +2 -2
  211. package/dist/internal/protocol/double-ratchet/ratchet.d.ts +4 -4
  212. package/dist/internal/protocol/double-ratchet/ratchet.js +6 -6
  213. package/dist/internal/protocol/pqxdh/pqxdh.d.ts +21 -18
  214. package/dist/internal/protocol/pqxdh/pqxdh.d.ts.map +1 -1
  215. package/dist/internal/protocol/pqxdh/pqxdh.js +48 -42
  216. package/dist/internal/protocol/pqxdh/pqxdh.js.map +1 -1
  217. package/dist/internal/protocol/sealed-sender/decryption-v2.js +5 -5
  218. package/dist/internal/protocol/sealed-sender/decryption-v2.js.map +1 -1
  219. package/dist/internal/protocol/sealed-sender/decryption.d.ts.map +1 -1
  220. package/dist/internal/protocol/sealed-sender/decryption.js +11 -8
  221. package/dist/internal/protocol/sealed-sender/decryption.js.map +1 -1
  222. package/dist/internal/protocol/sealed-sender/delivery-token.d.ts +2 -2
  223. package/dist/internal/protocol/sealed-sender/delivery-token.js +2 -2
  224. package/dist/internal/protocol/sealed-sender/encryption-v2.js +1 -1
  225. package/dist/internal/protocol/sealed-sender/encryption-v2.js.map +1 -1
  226. package/dist/internal/protocol/sealed-sender/encryption.d.ts +2 -2
  227. package/dist/internal/protocol/sealed-sender/encryption.js +2 -2
  228. package/dist/internal/protocol/sealed-sender/proto/index.d.ts +25 -23
  229. package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
  230. package/dist/internal/protocol/sealed-sender/proto/index.js +32 -30
  231. package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
  232. package/dist/internal/protocol/sealed-sender/trust-root.d.ts +10 -9
  233. package/dist/internal/protocol/sealed-sender/trust-root.d.ts.map +1 -1
  234. package/dist/internal/protocol/sealed-sender/trust-root.js +10 -9
  235. package/dist/internal/protocol/sealed-sender/trust-root.js.map +1 -1
  236. package/dist/internal/protocol/sealed-sender/types.d.ts +13 -14
  237. package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
  238. package/dist/internal/protocol/sealed-sender/types.js +7 -8
  239. package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
  240. package/dist/internal/protocol/sealed-sender/v2-binary.d.ts +1 -1
  241. package/dist/internal/protocol/sealed-sender/v2-binary.js +2 -2
  242. package/dist/internal/protocol/sealed-sender/v2-binary.js.map +1 -1
  243. package/dist/internal/protocol/sender-keys/manager.d.ts +16 -14
  244. package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
  245. package/dist/internal/protocol/sender-keys/manager.js +37 -34
  246. package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
  247. package/dist/internal/protocol/spqr/braid-serialize.d.ts +6 -6
  248. package/dist/internal/protocol/spqr/braid-serialize.js +5 -5
  249. package/dist/internal/protocol/spqr/braid-serialize.js.map +1 -1
  250. package/dist/internal/protocol/spqr/braid.d.ts +3 -3
  251. package/dist/internal/protocol/spqr/braid.js +7 -7
  252. package/dist/internal/protocol/spqr/braid.js.map +1 -1
  253. package/dist/internal/protocol/spqr/index.js +1 -1
  254. package/dist/internal/protocol/spqr/index.js.map +1 -1
  255. package/dist/internal/protocol/spqr/ml-kem-braid/chunk-domain.d.ts +3 -3
  256. package/dist/internal/protocol/spqr/ml-kem-braid/chunk-domain.js +3 -3
  257. package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js +1 -1
  258. package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js.map +1 -1
  259. package/dist/internal/protocol/spqr/ml-kem-braid/kdf.d.ts +1 -1
  260. package/dist/internal/protocol/spqr/ml-kem-braid/kdf.js +1 -1
  261. package/dist/internal/protocol/spqr/ml-kem-braid/kdf.js.map +1 -1
  262. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.d.ts +4 -3
  263. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.d.ts.map +1 -1
  264. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.js +4 -3
  265. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.js.map +1 -1
  266. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/index.js +2 -2
  267. package/dist/internal/protocol/spqr/ml-kem-braid/progress.d.ts +1 -1
  268. package/dist/internal/protocol/spqr/ml-kem-braid/progress.js +1 -1
  269. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts +15 -7
  270. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
  271. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js +15 -7
  272. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js.map +1 -1
  273. package/dist/internal/protocol/spqr/ml-kem-braid/rs/galois/field.js +1 -1
  274. package/dist/internal/protocol/spqr/ml-kem-braid/rs/polynomial.d.ts +3 -3
  275. package/dist/internal/protocol/spqr/ml-kem-braid/rs/polynomial.js +1 -1
  276. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts +7 -7
  277. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js +11 -11
  278. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js.map +1 -1
  279. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.d.ts +1 -1
  280. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js +6 -6
  281. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js.map +1 -1
  282. package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts +2 -2
  283. package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts.map +1 -1
  284. package/dist/internal/protocol/spqr/ml-kem-braid/types.js.map +1 -1
  285. package/dist/internal/protocol/spqr/serialize.d.ts +12 -12
  286. package/dist/internal/protocol/spqr/serialize.js +5 -5
  287. package/dist/internal/protocol/spqr/spqr.d.ts +6 -6
  288. package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
  289. package/dist/internal/protocol/spqr/spqr.js +47 -42
  290. package/dist/internal/protocol/spqr/spqr.js.map +1 -1
  291. package/dist/internal/protocol/spqr/validate.d.ts +1 -1
  292. package/dist/internal/protocol/triple-ratchet/ratchet.d.ts +12 -12
  293. package/dist/internal/protocol/triple-ratchet/ratchet.d.ts.map +1 -1
  294. package/dist/internal/protocol/triple-ratchet/ratchet.js +11 -11
  295. package/dist/internal/protocol/triple-ratchet/ratchet.js.map +1 -1
  296. package/dist/internal/protocol/username/hash.d.ts.map +1 -1
  297. package/dist/internal/protocol/username/hash.js +6 -4
  298. package/dist/internal/protocol/username/hash.js.map +1 -1
  299. package/dist/internal/protocol/version.d.ts +3 -3
  300. package/dist/internal/protocol/version.js +1 -1
  301. package/dist/internal/protocol/x3dh/x3dh.d.ts +16 -16
  302. package/dist/internal/protocol/x3dh/x3dh.d.ts.map +1 -1
  303. package/dist/internal/protocol/x3dh/x3dh.js +15 -15
  304. package/dist/internal/protocol/x3dh/x3dh.js.map +1 -1
  305. package/dist/internal/protocol/zk/credentials/attributes.d.ts +7 -7
  306. package/dist/internal/protocol/zk/credentials/attributes.js +7 -7
  307. package/dist/internal/protocol/zk/credentials/credentials.d.ts +1 -1
  308. package/dist/internal/protocol/zk/credentials/credentials.js +1 -1
  309. package/dist/internal/protocol/zk/credentials/endorsements.d.ts +11 -11
  310. package/dist/internal/protocol/zk/credentials/endorsements.js +14 -14
  311. package/dist/internal/protocol/zk/credentials/issuance.d.ts +5 -1
  312. package/dist/internal/protocol/zk/credentials/issuance.d.ts.map +1 -1
  313. package/dist/internal/protocol/zk/credentials/issuance.js +5 -1
  314. package/dist/internal/protocol/zk/credentials/issuance.js.map +1 -1
  315. package/dist/internal/protocol/zk/credentials/presentation.d.ts +16 -16
  316. package/dist/internal/protocol/zk/credentials/presentation.d.ts.map +1 -1
  317. package/dist/internal/protocol/zk/credentials/presentation.js +18 -18
  318. package/dist/internal/protocol/zk/credentials/presentation.js.map +1 -1
  319. package/dist/internal/protocol/zk/groups/auth-credential.d.ts +22 -16
  320. package/dist/internal/protocol/zk/groups/auth-credential.d.ts.map +1 -1
  321. package/dist/internal/protocol/zk/groups/auth-credential.js +19 -14
  322. package/dist/internal/protocol/zk/groups/auth-credential.js.map +1 -1
  323. package/dist/internal/protocol/zk/groups/client-zk-group-cipher.d.ts +4 -4
  324. package/dist/internal/protocol/zk/groups/client-zk-group-cipher.js +4 -4
  325. package/dist/internal/protocol/zk/groups/group-params.d.ts +2 -2
  326. package/dist/internal/protocol/zk/groups/group-params.js +2 -2
  327. package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts +10 -9
  328. package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts.map +1 -1
  329. package/dist/internal/protocol/zk/groups/group-send-endorsement.js +9 -8
  330. package/dist/internal/protocol/zk/groups/group-send-endorsement.js.map +1 -1
  331. package/dist/internal/protocol/zk/groups/lizard.d.ts +1 -1
  332. package/dist/internal/protocol/zk/groups/lizard.js +4 -4
  333. package/dist/internal/protocol/zk/groups/lizard.js.map +1 -1
  334. package/dist/internal/protocol/zk/groups/profile-key-commitment.d.ts +3 -3
  335. package/dist/internal/protocol/zk/groups/profile-key-commitment.js +3 -3
  336. package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts +11 -11
  337. package/dist/internal/protocol/zk/groups/profile-key-credential.js +7 -7
  338. package/dist/internal/protocol/zk/groups/profile-key-encryption.d.ts +2 -2
  339. package/dist/internal/protocol/zk/groups/profile-key-encryption.js +2 -2
  340. package/dist/internal/protocol/zk/groups/profile-key-struct.d.ts +2 -2
  341. package/dist/internal/protocol/zk/groups/profile-key-struct.js +2 -2
  342. package/dist/internal/protocol/zk/groups/profile-key-version.d.ts +2 -2
  343. package/dist/internal/protocol/zk/groups/profile-key-version.js +2 -2
  344. package/dist/internal/protocol/zk/groups/server-params.d.ts +1 -1
  345. package/dist/internal/protocol/zk/groups/server-params.js +1 -1
  346. package/dist/internal/protocol/zk/groups/uid-encryption.d.ts +4 -4
  347. package/dist/internal/protocol/zk/groups/uid-encryption.js +4 -4
  348. package/dist/internal/protocol/zk/groups/uid-struct.d.ts +2 -2
  349. package/dist/internal/protocol/zk/groups/uid-struct.js +3 -3
  350. package/dist/internal/protocol/zk/groups/uid-struct.js.map +1 -1
  351. package/dist/internal/protocol/zk/proofs/args.d.ts +3 -3
  352. package/dist/internal/protocol/zk/proofs/args.js +3 -3
  353. package/dist/internal/protocol/zk/proofs/sho-sha256.d.ts +3 -3
  354. package/dist/internal/protocol/zk/proofs/sho-sha256.js +3 -3
  355. package/dist/internal/protocol/zk/proofs/sho.d.ts +8 -7
  356. package/dist/internal/protocol/zk/proofs/sho.d.ts.map +1 -1
  357. package/dist/internal/protocol/zk/proofs/sho.js +8 -7
  358. package/dist/internal/protocol/zk/proofs/sho.js.map +1 -1
  359. package/dist/internal/protocol/zk/proofs/statement.d.ts +8 -6
  360. package/dist/internal/protocol/zk/proofs/statement.d.ts.map +1 -1
  361. package/dist/internal/protocol/zk/proofs/statement.js +8 -6
  362. package/dist/internal/protocol/zk/proofs/statement.js.map +1 -1
  363. package/dist/internal/sesame/manager.d.ts +23 -19
  364. package/dist/internal/sesame/manager.d.ts.map +1 -1
  365. package/dist/internal/sesame/manager.js +64 -54
  366. package/dist/internal/sesame/manager.js.map +1 -1
  367. package/dist/internal/sesame/types.d.ts +28 -25
  368. package/dist/internal/sesame/types.d.ts.map +1 -1
  369. package/dist/internal/sesame/types.js +2 -2
  370. package/dist/internal/sesame/types.js.map +1 -1
  371. package/dist/internal/sesame/validation.d.ts +2 -2
  372. package/dist/internal/sesame/validation.js +3 -3
  373. package/dist/internal/sesame/validation.js.map +1 -1
  374. package/dist/internal/session/builder.d.ts +8 -8
  375. package/dist/internal/session/builder.js +22 -22
  376. package/dist/internal/session/builder.js.map +1 -1
  377. package/dist/internal/session/cipher.d.ts +3 -3
  378. package/dist/internal/session/cipher.d.ts.map +1 -1
  379. package/dist/internal/session/cipher.js +51 -40
  380. package/dist/internal/session/cipher.js.map +1 -1
  381. package/dist/internal/session/decryption.js +11 -9
  382. package/dist/internal/session/decryption.js.map +1 -1
  383. package/dist/internal/session/factory.js +1 -1
  384. package/dist/internal/session/factory.js.map +1 -1
  385. package/dist/internal/session/handshake.d.ts +4 -4
  386. package/dist/internal/session/handshake.js +4 -4
  387. package/dist/internal/session/keys.d.ts +3 -4
  388. package/dist/internal/session/keys.d.ts.map +1 -1
  389. package/dist/internal/session/keys.js.map +1 -1
  390. package/dist/internal/session/ratchet.d.ts +8 -8
  391. package/dist/internal/session/ratchet.js +10 -10
  392. package/dist/internal/session/ratchet.js.map +1 -1
  393. package/dist/internal/session/session-resolver.d.ts +6 -6
  394. package/dist/internal/session/session-resolver.js +6 -6
  395. package/dist/internal/session/state.d.ts +12 -12
  396. package/dist/internal/session/state.d.ts.map +1 -1
  397. package/dist/internal/session/state.js +7 -7
  398. package/dist/internal/session/types.d.ts +20 -20
  399. package/dist/internal/session/types.d.ts.map +1 -1
  400. package/dist/internal/session/types.js +3 -3
  401. package/dist/internal/session/validation.d.ts +1 -1
  402. package/dist/internal/session/validation.js +4 -4
  403. package/dist/internal/session/validation.js.map +1 -1
  404. package/dist/keys/branded.d.ts +12 -12
  405. package/dist/keys/branded.js +3 -3
  406. package/dist/keys/generation.d.ts +4 -4
  407. package/dist/keys/generation.js +4 -4
  408. package/dist/keys/identity.d.ts +7 -7
  409. package/dist/keys/identity.d.ts.map +1 -1
  410. package/dist/keys/identity.js +7 -7
  411. package/dist/keys/identity.js.map +1 -1
  412. package/dist/keys/types.d.ts +16 -16
  413. package/dist/keys/types.d.ts.map +1 -1
  414. package/dist/layers.d.ts +1 -1
  415. package/dist/layers.js +1 -1
  416. package/dist/local/store/expo/adapter.d.ts +8 -8
  417. package/dist/local/store/expo/adapter.js +10 -10
  418. package/dist/local/store/expo/adapter.js.map +1 -1
  419. package/dist/local/store/expo/database-key.d.ts +7 -7
  420. package/dist/local/store/expo/database-key.js +7 -7
  421. package/dist/local/store/expo/key-storage.d.ts +1 -1
  422. package/dist/local/store/expo/key-storage.js +4 -4
  423. package/dist/local/store/expo/key-storage.js.map +1 -1
  424. package/dist/local/store/expo/models/kyber-prekey-used.d.ts +6 -6
  425. package/dist/local/store/expo/models/kyber-prekey-used.js +3 -3
  426. package/dist/local/store/expo/models/kyber-prekey.d.ts +1 -1
  427. package/dist/local/store/expo/models/kyber-prekey.js +1 -1
  428. package/dist/local/store/expo/models/message-record.d.ts +2 -2
  429. package/dist/local/store/expo/models/message-record.d.ts.map +1 -1
  430. package/dist/local/store/expo/models/message-record.js +1 -1
  431. package/dist/local/store/expo/models/message-record.js.map +1 -1
  432. package/dist/local/store/expo/models/sender-key.d.ts +11 -10
  433. package/dist/local/store/expo/models/sender-key.d.ts.map +1 -1
  434. package/dist/local/store/expo/models/sender-key.js +11 -10
  435. package/dist/local/store/expo/models/sender-key.js.map +1 -1
  436. package/dist/local/store/expo/schema.d.ts +2 -2
  437. package/dist/local/store/expo/schema.js +2 -2
  438. package/dist/local/store/expo/secure-store-options.d.ts +1 -1
  439. package/dist/local/store/memory/adapter.d.ts +2 -2
  440. package/dist/local/store/memory/adapter.js +12 -12
  441. package/dist/local/store/memory/adapter.js.map +1 -1
  442. package/dist/local/store/node/adapter.d.ts.map +1 -1
  443. package/dist/local/store/node/adapter.js +5 -4
  444. package/dist/local/store/node/adapter.js.map +1 -1
  445. package/dist/local/store/node/database-key.d.ts +8 -8
  446. package/dist/local/store/node/database-key.js +10 -10
  447. package/dist/local/store/node/database-key.js.map +1 -1
  448. package/dist/local/store/node/database.d.ts +5 -5
  449. package/dist/local/store/node/database.js +11 -11
  450. package/dist/local/store/node/database.js.map +1 -1
  451. package/dist/local/store/react-native/adapter.d.ts +6 -6
  452. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  453. package/dist/local/store/react-native/adapter.js +35 -32
  454. package/dist/local/store/react-native/adapter.js.map +1 -1
  455. package/dist/local/store/react-native/backend-conformance.d.ts +11 -10
  456. package/dist/local/store/react-native/backend-conformance.d.ts.map +1 -1
  457. package/dist/local/store/react-native/backend-conformance.js +13 -12
  458. package/dist/local/store/react-native/backend-conformance.js.map +1 -1
  459. package/dist/local/store/react-native/index.d.ts +1 -1
  460. package/dist/local/store/react-native/reference-backend.d.ts +14 -13
  461. package/dist/local/store/react-native/reference-backend.d.ts.map +1 -1
  462. package/dist/local/store/react-native/reference-backend.js +15 -14
  463. package/dist/local/store/react-native/reference-backend.js.map +1 -1
  464. package/dist/local/store/react-native/storage.d.ts +3 -3
  465. package/dist/local/store/web/adapter.d.ts +3 -3
  466. package/dist/local/store/web/adapter.d.ts.map +1 -1
  467. package/dist/local/store/web/adapter.js +30 -31
  468. package/dist/local/store/web/adapter.js.map +1 -1
  469. package/dist/local/store/web/index.d.ts +1 -1
  470. package/dist/local/vault/index.d.ts +2 -2
  471. package/dist/media/index.d.ts +11 -11
  472. package/dist/media/index.js +9 -9
  473. package/dist/profile/contact-state.d.ts +1 -1
  474. package/dist/profile/contact-state.js +1 -1
  475. package/dist/profile/profile-key.d.ts +2 -2
  476. package/dist/profile/profile-key.js +7 -6
  477. package/dist/profile/profile-key.js.map +1 -1
  478. package/dist/remote/object-store/index.d.ts +1 -1
  479. package/dist/remote/object-store/s3/storage.d.ts +1 -1
  480. package/dist/remote/object-store/types.d.ts +4 -4
  481. package/dist/remote/object-store/types.d.ts.map +1 -1
  482. package/dist/remote/relay/convex/backend.d.ts +4 -4
  483. package/dist/remote/relay/convex/backend.js +3 -3
  484. package/dist/remote/relay/convex/backend.js.map +1 -1
  485. package/dist/remote/relay/convex/component/accounts.d.ts +15 -13
  486. package/dist/remote/relay/convex/component/accounts.d.ts.map +1 -1
  487. package/dist/remote/relay/convex/component/accounts.js +31 -28
  488. package/dist/remote/relay/convex/component/accounts.js.map +1 -1
  489. package/dist/remote/relay/convex/component/certificates.js +1 -1
  490. package/dist/remote/relay/convex/component/cleanup.js +7 -7
  491. package/dist/remote/relay/convex/component/cleanup.js.map +1 -1
  492. package/dist/remote/relay/convex/component/convex.config.d.ts.map +1 -1
  493. package/dist/remote/relay/convex/component/convex.config.js +10 -8
  494. package/dist/remote/relay/convex/component/convex.config.js.map +1 -1
  495. package/dist/remote/relay/convex/component/devices.d.ts +21 -20
  496. package/dist/remote/relay/convex/component/devices.d.ts.map +1 -1
  497. package/dist/remote/relay/convex/component/devices.js +24 -23
  498. package/dist/remote/relay/convex/component/devices.js.map +1 -1
  499. package/dist/remote/relay/convex/component/groups.js +6 -6
  500. package/dist/remote/relay/convex/component/groups.js.map +1 -1
  501. package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
  502. package/dist/remote/relay/convex/component/messages.js +89 -82
  503. package/dist/remote/relay/convex/component/messages.js.map +1 -1
  504. package/dist/remote/relay/convex/component/provisioning.d.ts +3 -3
  505. package/dist/remote/relay/convex/component/provisioning.d.ts.map +1 -1
  506. package/dist/remote/relay/convex/component/provisioning.js +17 -16
  507. package/dist/remote/relay/convex/component/provisioning.js.map +1 -1
  508. package/dist/remote/relay/convex/component/runtime.d.ts.map +1 -1
  509. package/dist/remote/relay/convex/component/runtime.js +4 -2
  510. package/dist/remote/relay/convex/component/runtime.js.map +1 -1
  511. package/dist/remote/relay/convex/component/schema.js +25 -24
  512. package/dist/remote/relay/convex/component/schema.js.map +1 -1
  513. package/dist/remote/relay/convex/group-server.d.ts +3 -3
  514. package/dist/remote/relay/convex/group-server.js +3 -3
  515. package/dist/remote/relay/convex/relay.d.ts +3 -3
  516. package/dist/remote/relay/convex/relay.d.ts.map +1 -1
  517. package/dist/remote/relay/convex/relay.js +18 -17
  518. package/dist/remote/relay/convex/relay.js.map +1 -1
  519. package/dist/remote/relay/convex/types.d.ts +7 -7
  520. package/dist/remote/relay/convex/types.js +4 -4
  521. package/dist/remote/relay/memory/adapter.js +9 -9
  522. package/dist/remote/relay/memory/adapter.js.map +1 -1
  523. package/dist/remote/relay/types.d.ts +27 -27
  524. package/dist/remote/relay/types.d.ts.map +1 -1
  525. package/dist/safety/fingerprint.d.ts +7 -6
  526. package/dist/safety/fingerprint.d.ts.map +1 -1
  527. package/dist/safety/fingerprint.js +5 -4
  528. package/dist/safety/fingerprint.js.map +1 -1
  529. package/dist/safety/index.d.ts +6 -5
  530. package/dist/safety/index.d.ts.map +1 -1
  531. package/dist/safety/index.js +7 -6
  532. package/dist/safety/index.js.map +1 -1
  533. package/dist/safety/protobuf.js +2 -2
  534. package/dist/safety/protobuf.js.map +1 -1
  535. package/dist/safety/url.d.ts +5 -5
  536. package/dist/safety/url.js +6 -6
  537. package/dist/types/address.d.ts +2 -2
  538. package/dist/types/address.js +2 -2
  539. package/dist/types/api.d.ts +78 -73
  540. package/dist/types/api.d.ts.map +1 -1
  541. package/dist/types/errors.d.ts +63 -403
  542. package/dist/types/errors.d.ts.map +1 -1
  543. package/dist/types/errors.js +62 -537
  544. package/dist/types/errors.js.map +1 -1
  545. package/dist/types/messages.d.ts +16 -16
  546. package/dist/types/messages.d.ts.map +1 -1
  547. package/dist/types/messages.js +7 -7
  548. package/dist/types/messages.js.map +1 -1
  549. package/dist/types/protocol-config.d.ts +52 -49
  550. package/dist/types/protocol-config.d.ts.map +1 -1
  551. package/dist/types/protocol-config.js +36 -34
  552. package/dist/types/protocol-config.js.map +1 -1
  553. package/dist/types/protocol-constants.d.ts +2 -2
  554. package/dist/types/protocol-constants.js +2 -2
  555. package/dist/types/session.d.ts +62 -61
  556. package/dist/types/session.d.ts.map +1 -1
  557. package/dist/types/session.js +13 -14
  558. package/dist/types/session.js.map +1 -1
  559. package/dist/types/trust.d.ts +8 -8
  560. package/dist/types/trust.js +3 -3
  561. package/dist/utils/retry.d.ts.map +1 -1
  562. package/dist/utils/retry.js +2 -4
  563. package/dist/utils/retry.js.map +1 -1
  564. package/docs/ASSURANCE.md +82 -74
  565. package/docs/CLIENT_COMPOSITION.md +19 -15
  566. package/docs/DEVIATIONS.md +507 -425
  567. package/docs/DOCUMENTATION_STANDARDS.md +24 -24
  568. package/docs/E2EE.md +45 -42
  569. package/docs/ERROR_HANDLING.md +29 -105
  570. package/docs/GETTING_STARTED.md +24 -25
  571. package/docs/INTERFACES.md +27 -18
  572. package/docs/PACKAGE_SURFACE.md +23 -21
  573. package/docs/PROTOCOL_POLICY.md +19 -13
  574. package/docs/RECIPES.md +4 -4
  575. package/docs/SECURITY.md +72 -60
  576. package/encoding/README.md +2 -2
  577. package/files/README.md +1 -1
  578. package/groups/README.md +4 -3
  579. package/hooks/README.md +2 -2
  580. package/keys/README.md +15 -14
  581. package/local/store/README.md +82 -67
  582. package/local/store/expo/README.md +17 -12
  583. package/local/store/memory/README.md +4 -3
  584. package/local/store/node/README.md +8 -6
  585. package/local/store/react-native/README.md +14 -12
  586. package/local/store/web/README.md +31 -26
  587. package/local/vault/README.md +4 -4
  588. package/media/README.md +6 -5
  589. package/package.json +1 -1
  590. package/profile/README.md +7 -7
  591. package/remote/README.md +20 -18
  592. package/remote/object-store/README.md +8 -4
  593. package/remote/object-store/convex-r2/README.md +3 -3
  594. package/remote/object-store/s3/README.md +10 -5
  595. package/remote/relay/convex/README.md +5 -5
  596. package/remote/relay/convex/component/README.md +145 -124
  597. package/remote/relay/memory/README.md +6 -5
  598. package/safety/README.md +1 -1
  599. package/sealed-sender/README.md +3 -2
  600. package/types/README.md +1 -1
  601. package/utils/README.md +4 -4
@@ -1,29 +1,27 @@
1
1
  /**
2
- * Error type definitions for Signal Protocol
2
+ * Error type definitions for Signal Protocol.
3
3
  *
4
- * Implements a tiered error system aligned with the layered architecture:
4
+ * Every error the SDK throws is an `EncryptionError` carrying an
5
+ * `EncryptionErrorCode`. A subclass exists only where the caller needs typed
6
+ * data off the error to recover. Examples are the peer's address and identity
7
+ * to verify a safety number, and the counter and epoch of a duplicate. Each
8
+ * subclass fixes its own code in its constructor.
5
9
  *
6
10
  * ```
7
- * Layer Error Class Use Case
8
- * ──────────────────────────────────────────────────────
9
- * Layer 1 CryptoError Low-level crypto failures
10
- * Layer 5 SessionError Session operations
11
- * Layer 6 ProtocolError Protocol-level errors
12
- * Client ClientError User-facing errors
13
- * Base EncryptionError Generic encryption errors
14
- * ```
15
- *
16
- * Error Hierarchy:
17
- * ```
18
11
  * Error
19
- * └── EncryptionError (base for all Signal Protocol errors)
20
- * ├── CryptoError (Layer 1)
21
- * ├── SessionError (Layer 5)
22
- * ├── ProtocolError (Layer 6)
23
- * ├── ClientError (User-facing)
24
- * └── Specialized errors (UntrustedIdentityError, etc.)
12
+ * └── EncryptionError code + context, thrown directly for most failures
13
+ * ├── UntrustedIdentityError address + identity, for safety-number verification
14
+ * ├── DuplicatedMessageError counter + epoch of the replayed message
15
+ * ├── SealedSenderAuthError the rejected sealed-sender credential
16
+ * ├── PQXDHRequiredError which post-quantum key the peer is missing
17
+ * └── StorageQuotaExceededError the store that ran out of room
25
18
  * ```
26
19
  *
20
+ * A code or a subclass belongs here only if production code can produce it. An
21
+ * error-surface check in the engineering repository parses for the construction
22
+ * sites that decide that. It fails the build when this module declares
23
+ * something nothing throws. A `switch` arm or a non-retryable set only reads a
24
+ * code. It does not produce one, so it does not keep a code alive.
27
25
  */
28
26
  /**
29
27
  * Base encryption error class.
@@ -78,20 +76,13 @@ export var EncryptionErrorCode;
78
76
  // ===== Session Errors =====
79
77
  /** Session not found for the given address */
80
78
  EncryptionErrorCode["SESSION_NOT_FOUND"] = "SESSION_NOT_FOUND";
81
- /** Session data is corrupted or invalid */
79
+ /** Damaged or invalid session data */
82
80
  EncryptionErrorCode["SESSION_CORRUPTED"] = "SESSION_CORRUPTED";
83
- /**
84
- * Multiple active sessions detected (race condition).
85
- *
86
- * Occurs when both parties try to establish sessions simultaneously.
87
- * Requires session archiving and convergence.
88
- */
89
- EncryptionErrorCode["SESSION_CONFLICT"] = "SESSION_CONFLICT";
90
81
  /**
91
82
  * Recipient has not registered encryption keys.
92
83
  *
93
84
  * The target user has no prekey bundle available on the server.
94
- * They may not have completed encryption setup.
85
+ * Their encryption setup may be incomplete.
95
86
  */
96
87
  EncryptionErrorCode["RECIPIENT_NOT_REGISTERED"] = "RECIPIENT_NOT_REGISTERED";
97
88
  /**
@@ -117,15 +108,9 @@ export var EncryptionErrorCode;
117
108
  /**
118
109
  * Duplicate message detected (replay attack).
119
110
  *
120
- * Message number has already been processed.
111
+ * The session already processed this message number.
121
112
  */
122
113
  EncryptionErrorCode["MESSAGE_DUPLICATE"] = "MESSAGE_DUPLICATE";
123
- /**
124
- * Message arrived too old to decrypt.
125
- *
126
- * Message keys have been deleted due to age or count limits.
127
- */
128
- EncryptionErrorCode["MESSAGE_TOO_OLD"] = "MESSAGE_TOO_OLD";
129
114
  /**
130
115
  * Too many messages skipped (DoS protection).
131
116
  *
@@ -134,7 +119,7 @@ export var EncryptionErrorCode;
134
119
  */
135
120
  EncryptionErrorCode["TOO_MANY_SKIPPED_MESSAGES"] = "TOO_MANY_SKIPPED_MESSAGES";
136
121
  /**
137
- * Replay attack detected: envelope.timestamp doesn't match dataMessage.timestamp.
122
+ * Replay attack detected: envelope.timestamp does not match dataMessage.timestamp.
138
123
  *
139
124
  * After decryption, the envelope timestamp must match the timestamp inside the encrypted
140
125
  * content. A mismatch indicates an attacker may have re-sent old encrypted content
@@ -143,13 +128,7 @@ export var EncryptionErrorCode;
143
128
  */
144
129
  EncryptionErrorCode["REPLAY_DETECTED"] = "REPLAY_DETECTED";
145
130
  /**
146
- * Invalid message version or protocol mismatch.
147
- *
148
- * Message was encrypted with an incompatible protocol version.
149
- */
150
- EncryptionErrorCode["INVALID_MESSAGE_VERSION"] = "INVALID_MESSAGE_VERSION";
151
- /**
152
- * Sender key has expired based on time-based rotation policy.
131
+ * The sender key expired under the time-based rotation policy.
153
132
  *
154
133
  * The default policy rotates sender keys every two weeks.
155
134
  * The caller should auto-rotate the sender key and redistribute to group members.
@@ -159,20 +138,14 @@ export var EncryptionErrorCode;
159
138
  /**
160
139
  * Identity key is not trusted.
161
140
  *
162
- * User has not verified the identity or it has changed without confirmation.
141
+ * The user did not verify the identity, or the identity changed without
142
+ * confirmation.
163
143
  */
164
144
  EncryptionErrorCode["UNTRUSTED_IDENTITY"] = "UNTRUSTED_IDENTITY";
165
- /**
166
- * Identity key changed (possible MITM attack).
167
- *
168
- * Remote party's identity key differs from previously saved value.
169
- * Could be legitimate (reinstall) or an attack.
170
- */
171
- EncryptionErrorCode["IDENTITY_KEY_CHANGED"] = "IDENTITY_KEY_CHANGED";
172
145
  /**
173
146
  * Sender identity mismatch.
174
147
  *
175
- * The sender address in the message doesn't match the expected address.
148
+ * The sender address in the message does not match the expected address.
176
149
  * This indicates a session hijacking attempt where an attacker tries to
177
150
  * inject their messages under a different identity.
178
151
  */
@@ -187,62 +160,35 @@ export var EncryptionErrorCode;
187
160
  /**
188
161
  * PreKey rotation required before sending.
189
162
  *
190
- * Signed prekeys or Kyber prekeys have exceeded the maximum allowed age
191
- * (14 days by default). Message sending is blocked until rotation succeeds
192
- * to maintain forward-secrecy guarantees.
163
+ * Signed prekeys or Kyber prekeys are past the maximum allowed age
164
+ * (14 days by default). The client blocks message sending until rotation
165
+ * succeeds, which maintains the forward-secrecy guarantees.
193
166
  *
194
167
  * @see https://signal.org/docs/specifications/pqxdh/#publishing-keys
195
168
  */
196
169
  EncryptionErrorCode["PREKEY_ROTATION_REQUIRED"] = "PREKEY_ROTATION_REQUIRED";
197
- /**
198
- * Invalid registration ID.
199
- *
200
- * Registration ID is 0 or doesn't match expected format.
201
- */
202
- EncryptionErrorCode["INVALID_REGISTRATION_ID"] = "INVALID_REGISTRATION_ID";
203
- /**
204
- * Registration ID changed (session reset detected).
205
- *
206
- * Remote party's registration ID changed, indicating app reinstall.
207
- * Old sessions should be archived.
208
- */
209
- EncryptionErrorCode["REGISTRATION_ID_CHANGED"] = "REGISTRATION_ID_CHANGED";
210
170
  // ===== Ratchet Errors =====
211
- /**
212
- * DH ratchet error.
213
- *
214
- * Diffie-Hellman key exchange failed or produced invalid output.
215
- */
216
- EncryptionErrorCode["RATCHET_ERROR"] = "RATCHET_ERROR";
217
171
  /**
218
172
  * Message counter overflow.
219
173
  *
220
- * Counter has reached MAX_SAFE_INTEGER - session must be rotated.
174
+ * The counter reached MAX_SAFE_INTEGER, so the caller must rotate the session.
221
175
  * This is a safety check to prevent cryptographic issues from counter wrap-around.
222
176
  */
223
177
  EncryptionErrorCode["COUNTER_OVERFLOW"] = "COUNTER_OVERFLOW";
224
178
  /**
225
179
  * Invalid DH public key.
226
180
  *
227
- * DH public key is malformed or fails validation.
181
+ * A malformed DH public key, or one that fails validation.
228
182
  */
229
183
  EncryptionErrorCode["INVALID_DH_KEY"] = "INVALID_DH_KEY";
230
184
  // ===== Storage Errors =====
231
185
  /** Key storage operation failed */
232
186
  EncryptionErrorCode["KEY_STORAGE_ERROR"] = "KEY_STORAGE_ERROR";
233
- /** Database operation failed */
234
- EncryptionErrorCode["DATABASE_ERROR"] = "DATABASE_ERROR";
235
- /**
236
- * Database is locked or unavailable.
237
- *
238
- * Encrypted database cannot be accessed (wrong password, corruption, etc.)
239
- */
240
- EncryptionErrorCode["DATABASE_LOCKED"] = "DATABASE_LOCKED";
241
187
  /**
242
- * The storage backend rejected a write because the origin's storage
243
- * quota is exhausted.
188
+ * The storage backend rejected a write because the origin ran out of
189
+ * storage quota.
244
190
  *
245
- * The rejected write did not persist: storage adapters commit each
191
+ * The rejected write did not persist. Storage adapters commit each
246
192
  * write in an atomic transaction, so quota exhaustion rolls the whole
247
193
  * transaction back instead of leaving a subset. The application should
248
194
  * free space or request more from the platform, then retry.
@@ -251,25 +197,23 @@ export var EncryptionErrorCode;
251
197
  // ===== Initialization Errors =====
252
198
  /** Signal Protocol initialization failed */
253
199
  EncryptionErrorCode["INITIALIZATION_FAILED"] = "INITIALIZATION_FAILED";
254
- /** Identity key pair generation or loading failed */
255
- EncryptionErrorCode["IDENTITY_KEY_ERROR"] = "IDENTITY_KEY_ERROR";
256
200
  // ===== Protocol Strategy Errors =====
257
201
  /**
258
- * PQXDH (post-quantum key exchange) is required but partner lacks Kyber keys.
202
+ * PQXDH (post-quantum key exchange) applies, but the partner lacks Kyber keys.
259
203
  *
260
- * Thrown when partner doesn't support the required PQXDH handshake.
204
+ * Thrown when partner does not support the required PQXDH handshake.
261
205
  * Application can catch this to notify user or queue message for retry.
262
206
  */
263
207
  EncryptionErrorCode["PQXDH_REQUIRED"] = "PQXDH_REQUIRED";
264
208
  /**
265
209
  * PQXDH key exchange failed during handshake.
266
210
  *
267
- * The post-quantum key exchange encountered an error. The session is aborted
268
- * rather than downgraded to classical X3DH.
211
+ * The post-quantum key exchange encountered an error. The SDK aborts the
212
+ * session instead of a downgrade to classical X3DH.
269
213
  */
270
214
  EncryptionErrorCode["PQXDH_FAILED"] = "PQXDH_FAILED";
271
215
  /**
272
- * Triple Ratchet is required but PQXDH was not used.
216
+ * Triple Ratchet applies, but the session did not use PQXDH.
273
217
  *
274
218
  * Triple Ratchet requires post-quantum material from PQXDH.
275
219
  * Cannot enable Triple Ratchet with classical X3DH handshake.
@@ -290,18 +234,10 @@ export var EncryptionErrorCode;
290
234
  * `SPQR`'s the profile uses `max_jump` of 25,000.
291
235
  */
292
236
  EncryptionErrorCode["SPQR_MESSAGE_JUMP_TOO_LARGE"] = "SPQR_MESSAGE_JUMP_TOO_LARGE";
293
- /**
294
- * Attempted to use a message key that was already consumed.
295
- *
296
- * Indicates replay attack or duplicate message.
297
- *
298
- * Reserved: Reserved for future use when replay detection is implemented.
299
- */
300
- EncryptionErrorCode["SPQR_KEY_ALREADY_USED"] = "SPQR_KEY_ALREADY_USED";
301
237
  /**
302
238
  * SPQR message counter overflow.
303
239
  *
304
- * Counter has reached maximum value - epoch must be rotated.
240
+ * The counter reached its maximum value, so the caller must rotate the epoch.
305
241
  */
306
242
  EncryptionErrorCode["SPQR_COUNTER_OVERFLOW"] = "SPQR_COUNTER_OVERFLOW";
307
243
  /**
@@ -310,15 +246,6 @@ export var EncryptionErrorCode;
310
246
  * Ciphertext has wrong size or format for ML-KEM-1024.
311
247
  */
312
248
  EncryptionErrorCode["SPQR_INVALID_CIPHERTEXT"] = "SPQR_INVALID_CIPHERTEXT";
313
- /**
314
- * SPQR epoch regression detected.
315
- *
316
- * Received message claims an epoch earlier than current - possible replay.
317
- *
318
- * Reserved: Reserved for future use. Currently epoch regression is handled
319
- * via SPQR_EPOCH_OUT_OF_RANGE with oldestEpoch context.
320
- */
321
- EncryptionErrorCode["SPQR_EPOCH_REGRESSION"] = "SPQR_EPOCH_REGRESSION";
322
249
  /**
323
250
  * SPQR version negotiation failed.
324
251
  *
@@ -326,26 +253,17 @@ export var EncryptionErrorCode;
326
253
  * For example, peer only supports V0 but we require V1.
327
254
  */
328
255
  EncryptionErrorCode["SPQR_VERSION_MISMATCH"] = "SPQR_VERSION_MISMATCH";
329
- // ===== Cryptographic Errors =====
330
- /** Post-quantum (Kyber) operation failed */
331
- EncryptionErrorCode["KYBER_ERROR"] = "KYBER_ERROR";
332
- /** Key derivation function failed */
333
- EncryptionErrorCode["KDF_ERROR"] = "KDF_ERROR";
334
- /** HMAC verification failed (message tampering detected) */
335
- EncryptionErrorCode["HMAC_VERIFICATION_FAILED"] = "HMAC_VERIFICATION_FAILED";
336
256
  // ===== Sealed Sender Errors =====
337
257
  /**
338
258
  * Sealed sender authentication failed.
339
259
  *
340
- * The unidentified access key was rejected by the server. This may trigger
260
+ * The server rejected the unidentified access key. This may trigger
341
261
  * fallback to identified sender delivery.
342
262
  */
343
263
  EncryptionErrorCode["SEALED_SENDER_AUTH_FAILED"] = "SEALED_SENDER_AUTH_FAILED";
344
264
  // ===== Generic Errors =====
345
265
  /** Invalid operation or state */
346
266
  EncryptionErrorCode["INVALID_STATE"] = "INVALID_STATE";
347
- /** Unknown or unexpected error */
348
- EncryptionErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
349
267
  })(EncryptionErrorCode || (EncryptionErrorCode = {}));
350
268
  // ===== Specialized Error Classes =====
351
269
  /**
@@ -370,57 +288,12 @@ export class UntrustedIdentityError extends EncryptionError {
370
288
  }
371
289
  }
372
290
  /**
373
- * Error thrown when an identity key has changed.
374
- *
375
- * This could indicate:
376
- * - Legitimate: Device reinstall, new device, backup restoration
377
- * - Attack: Man-in-the-middle attack
378
- *
379
- * Requires prominent user warning and safety number verification.
380
- *
381
- * @example
382
- * ```typescript
383
- * throw new IdentityKeyChangedError(address, oldKey, newKey);
384
- * ```
385
- */
386
- export class IdentityKeyChangedError extends EncryptionError {
387
- changedAddress;
388
- oldIdentityKey;
389
- newIdentityKey;
390
- constructor(address, oldIdentityKey, newIdentityKey) {
391
- super(`Identity key changed for ${address.userId}.${address.deviceId}`, EncryptionErrorCode.IDENTITY_KEY_CHANGED, { address, identityKey: newIdentityKey });
392
- this.name = 'IdentityKeyChangedError';
393
- this.changedAddress = address;
394
- this.oldIdentityKey = oldIdentityKey;
395
- this.newIdentityKey = newIdentityKey;
396
- }
397
- }
398
- /**
399
- * Error thrown when multiple active sessions are detected (race condition).
400
- *
401
- * Occurs when both parties try to establish sessions simultaneously.
402
- * Requires session archiving and convergence using Sesame algorithm.
403
- *
404
- * @example
405
- * ```typescript
406
- * throw new SessionConflictError(address);
407
- * ```
408
- */
409
- export class SessionConflictError extends EncryptionError {
410
- conflictAddress;
411
- constructor(address) {
412
- super(`Session conflict detected for ${address.userId}.${address.deviceId}`, EncryptionErrorCode.SESSION_CONFLICT, { address });
413
- this.name = 'SessionConflictError';
414
- this.conflictAddress = address;
415
- }
416
- }
417
- /**
418
- * Error thrown when a duplicate message is detected (replay attack).
291
+ * Error thrown when the session detects a duplicate message (replay attack).
419
292
  *
420
293
  * This is a security-critical error indicating:
421
294
  * - Network replay (attacker re-sent a captured message)
422
295
  * - Client bug (accidentally decrypting same message twice)
423
- * - Storage corruption (message key index was corrupted)
296
+ * - Storage corruption (a damaged message key index)
424
297
  *
425
298
  * Metadata should support diagnostics without exposing secret material.
426
299
  *
@@ -431,9 +304,9 @@ export class SessionConflictError extends EncryptionError {
431
304
  */
432
305
  export class DuplicatedMessageError extends EncryptionError {
433
306
  duplicatedAddress;
434
- /** Message counter that was duplicated (if known) - matches the reference implementation's proto field name */
307
+ /** The duplicate message counter (if known) - matches the reference implementation's proto field name */
435
308
  counter;
436
- /** Epoch (for Triple Ratchet) where duplicate was detected */
309
+ /** Epoch (for Triple Ratchet) of the duplicate */
437
310
  epoch;
438
311
  /** Fingerprint of the duplicate ciphertext (truncated for logging) */
439
312
  fingerprintPreview;
@@ -459,35 +332,11 @@ export class DuplicatedMessageError extends EncryptionError {
459
332
  export function isDuplicatedMessageError(error) {
460
333
  return error instanceof DuplicatedMessageError;
461
334
  }
462
- /**
463
- * Error thrown when registration ID has changed (session reset).
464
- *
465
- * Indicates the remote party has reinstalled their app.
466
- * Old sessions should be archived and new session established.
467
- *
468
- * @example
469
- * ```typescript
470
- * throw new RegistrationIdChangedError(address, oldId, newId);
471
- * ```
472
- */
473
- export class RegistrationIdChangedError extends EncryptionError {
474
- resetAddress;
475
- oldRegistrationId;
476
- newRegistrationId;
477
- constructor(address, oldRegistrationId, newRegistrationId) {
478
- super(`Registration ID changed for ${address.userId}.${address.deviceId} ` +
479
- `(${oldRegistrationId} → ${newRegistrationId})`, EncryptionErrorCode.REGISTRATION_ID_CHANGED, { address });
480
- this.name = 'RegistrationIdChangedError';
481
- this.resetAddress = address;
482
- this.oldRegistrationId = oldRegistrationId;
483
- this.newRegistrationId = newRegistrationId;
484
- }
485
- }
486
335
  /**
487
336
  * Error thrown when sealed sender (anonymous delivery) authentication fails.
488
337
  *
489
- * The unidentified access key was rejected by the server, either because:
490
- * - The access key doesn't match the recipient's stored key
338
+ * The server rejected the unidentified access key, for one of these reasons:
339
+ * - The access key does not match the recipient's stored key
491
340
  * - The recipient's account was not found
492
341
  * - The recipient disabled unrestricted unidentified access
493
342
  *
@@ -524,7 +373,7 @@ export function isSealedSenderAuthError(error) {
524
373
  return error instanceof SealedSenderAuthError;
525
374
  }
526
375
  /**
527
- * Error thrown when PQXDH is required but partner lacks Kyber keys.
376
+ * Error thrown when PQXDH applies, but the partner lacks Kyber keys.
528
377
  *
529
378
  * This is a recoverable error - applications can:
530
379
  * - Notify user that partner needs to update their app
@@ -532,7 +381,7 @@ export function isSealedSenderAuthError(error) {
532
381
  * - Fall back to classical encryption with user consent
533
382
  *
534
383
  * Recovery metadata:
535
- * - `retryable`: Whether the operation can be retried
384
+ * - `retryable`: Whether the caller can retry the operation
536
385
  * - `suggestedRetryDelay`: Recommended delay before retry (ms)
537
386
  * - `fallbackType`: Category of fallback for analytics
538
387
  *
@@ -563,7 +412,7 @@ export function isSealedSenderAuthError(error) {
563
412
  export class PQXDHRequiredError extends EncryptionError {
564
413
  remoteAddress;
565
414
  reason;
566
- /** Whether the operation can be retried */
415
+ /** Whether the caller can retry the operation */
567
416
  retryable;
568
417
  /** Suggested delay before retry in milliseconds */
569
418
  suggestedRetryDelay;
@@ -583,15 +432,15 @@ export class PQXDHRequiredError extends EncryptionError {
583
432
  // Set recovery metadata with sensible defaults
584
433
  this.fallbackType =
585
434
  opts.fallbackType ?? (reason === 'no_kyber_prekey' ? 'missing_keys' : 'crypto_failure');
586
- this.retryable = opts.retryable ?? reason === 'no_kyber_prekey'; // Missing keys can be retried after partner updates
435
+ this.retryable = opts.retryable ?? reason === 'no_kyber_prekey'; // The caller can retry missing keys after partner updates
587
436
  this.suggestedRetryDelay = opts.suggestedRetryDelay ?? (this.retryable ? 30000 : undefined); // 30s default for retryable
588
437
  }
589
438
  }
590
439
  /**
591
- * Error thrown when the storage backend rejects a write because the
592
- * origin's storage quota is exhausted.
440
+ * Error thrown when the storage backend rejects a write because the origin
441
+ * ran out of storage quota.
593
442
  *
594
- * The rejected write did not persist: storage adapters commit each write
443
+ * The rejected write did not persist. Storage adapters commit each write
595
444
  * in an atomic transaction, so quota exhaustion rolls the whole
596
445
  * transaction back instead of leaving a subset. The application should
597
446
  * free space or request more from the platform, then retry the write.
@@ -613,6 +462,15 @@ export class StorageQuotaExceededError extends EncryptionError {
613
462
  this.name = 'StorageQuotaExceededError';
614
463
  }
615
464
  }
465
+ /**
466
+ * Type guard to check if an error is a StorageQuotaExceededError.
467
+ *
468
+ * @param error - Error to check
469
+ * @returns true if error is StorageQuotaExceededError
470
+ */
471
+ export function isStorageQuotaExceededError(error) {
472
+ return error instanceof StorageQuotaExceededError;
473
+ }
616
474
  /**
617
475
  * Type guard to check if an error is a PQXDHRequiredError.
618
476
  *
@@ -631,339 +489,6 @@ export function isPQXDHRequiredError(error) {
631
489
  export function isUntrustedIdentityError(error) {
632
490
  return error instanceof UntrustedIdentityError;
633
491
  }
634
- /**
635
- * Type guard to check if an error is an IdentityKeyChangedError.
636
- *
637
- * @param error - Error to check
638
- * @returns true if error is IdentityKeyChangedError
639
- */
640
- export function isIdentityKeyChangedError(error) {
641
- return error instanceof IdentityKeyChangedError;
642
- }
643
- /**
644
- * Type guard to check if an error is a SessionConflictError.
645
- *
646
- * @param error - Error to check
647
- * @returns true if error is SessionConflictError
648
- */
649
- export function isSessionConflictError(error) {
650
- return error instanceof SessionConflictError;
651
- }
652
- /**
653
- * Type guard to check if an error is a RegistrationIdChangedError.
654
- *
655
- * @param error - Error to check
656
- * @returns true if error is RegistrationIdChangedError
657
- */
658
- export function isRegistrationIdChangedError(error) {
659
- return error instanceof RegistrationIdChangedError;
660
- }
661
- // ============================================================================
662
- // Tiered Error Classes (Layer-Aligned)
663
- // ============================================================================
664
- /**
665
- * Error codes for cryptographic layer (Layer 1) errors.
666
- *
667
- * These errors occur in low-level cryptographic operations.
668
- */
669
- export var CryptoErrorCode;
670
- (function (CryptoErrorCode) {
671
- /** Random number generation failed */
672
- CryptoErrorCode["RNG_FAILURE"] = "CRYPTO_RNG_FAILURE";
673
- /** ECDH key agreement failed */
674
- CryptoErrorCode["ECDH_FAILURE"] = "CRYPTO_ECDH_FAILURE";
675
- /** Kyber (ML-KEM) operation failed */
676
- CryptoErrorCode["KYBER_FAILURE"] = "CRYPTO_KYBER_FAILURE";
677
- /** Key derivation function failed */
678
- CryptoErrorCode["KDF_FAILURE"] = "CRYPTO_KDF_FAILURE";
679
- /** AES encryption/decryption failed */
680
- CryptoErrorCode["AES_FAILURE"] = "CRYPTO_AES_FAILURE";
681
- /** HMAC computation or verification failed */
682
- CryptoErrorCode["HMAC_FAILURE"] = "CRYPTO_HMAC_FAILURE";
683
- /** Digital signature failed */
684
- CryptoErrorCode["SIGNATURE_FAILURE"] = "CRYPTO_SIGNATURE_FAILURE";
685
- /** Hash computation failed */
686
- CryptoErrorCode["HASH_FAILURE"] = "CRYPTO_HASH_FAILURE";
687
- /** Invalid key format or length */
688
- CryptoErrorCode["INVALID_KEY"] = "CRYPTO_INVALID_KEY";
689
- /** Invalid ciphertext format */
690
- CryptoErrorCode["INVALID_CIPHERTEXT"] = "CRYPTO_INVALID_CIPHERTEXT";
691
- })(CryptoErrorCode || (CryptoErrorCode = {}));
692
- /**
693
- * Cryptographic layer error (Layer 1).
694
- *
695
- * Thrown when low-level cryptographic operations fail.
696
- * These errors are typically unrecoverable and indicate
697
- * fundamental issues with crypto primitives.
698
- *
699
- * @example
700
- * ```typescript
701
- * throw new CryptoError(
702
- * 'ECDH key agreement produced invalid output',
703
- * CryptoErrorCode.ECDH_FAILURE,
704
- * { operation: 'computeSharedSecret' }
705
- * );
706
- * ```
707
- */
708
- export class CryptoError extends EncryptionError {
709
- cryptoCode;
710
- constructor(message, code, context) {
711
- // Map to base EncryptionErrorCode for compatibility
712
- const baseCode = mapCryptoToEncryptionCode(code);
713
- super(message, baseCode, context);
714
- this.name = 'CryptoError';
715
- this.cryptoCode = code;
716
- }
717
- }
718
- /**
719
- * Error codes for session layer (Layer 5) errors.
720
- *
721
- * These errors occur during session operations.
722
- */
723
- export var SessionErrorCode;
724
- (function (SessionErrorCode) {
725
- /** Session not found */
726
- SessionErrorCode["NOT_FOUND"] = "SESSION_NOT_FOUND";
727
- /** Session is corrupted or invalid */
728
- SessionErrorCode["CORRUPTED"] = "SESSION_CORRUPTED";
729
- /** Session has expired */
730
- SessionErrorCode["EXPIRED"] = "SESSION_EXPIRED";
731
- /** Session conflict (race condition) */
732
- SessionErrorCode["CONFLICT"] = "SESSION_CONFLICT";
733
- /** Invalid session state for operation */
734
- SessionErrorCode["INVALID_STATE"] = "SESSION_INVALID_STATE";
735
- /** Session ratchet step failed */
736
- SessionErrorCode["RATCHET_FAILED"] = "SESSION_RATCHET_FAILED";
737
- /** Too many skipped messages */
738
- SessionErrorCode["TOO_MANY_SKIPPED"] = "SESSION_TOO_MANY_SKIPPED";
739
- /** Message key not found (message too old) */
740
- SessionErrorCode["MESSAGE_KEY_NOT_FOUND"] = "SESSION_MESSAGE_KEY_NOT_FOUND";
741
- /** Session establishment failed */
742
- SessionErrorCode["ESTABLISHMENT_FAILED"] = "SESSION_ESTABLISHMENT_FAILED";
743
- })(SessionErrorCode || (SessionErrorCode = {}));
744
- /**
745
- * Session layer error (Layer 5).
746
- *
747
- * Thrown when session operations fail. Includes session ID
748
- * for debugging and potentially recovery.
749
- *
750
- * @example
751
- * ```typescript
752
- * throw new SessionError(
753
- * 'Session not found for decryption',
754
- * SessionErrorCode.NOT_FOUND,
755
- * 'session-123',
756
- * { operation: 'decrypt' }
757
- * );
758
- * ```
759
- */
760
- export class SessionError extends EncryptionError {
761
- sessionCode;
762
- sessionId;
763
- constructor(message, code, sessionId, context) {
764
- // Map to base EncryptionErrorCode for compatibility
765
- const baseCode = mapSessionToEncryptionCode(code);
766
- super(message, baseCode, context);
767
- this.name = 'SessionError';
768
- this.sessionCode = code;
769
- this.sessionId = sessionId;
770
- }
771
- }
772
- /**
773
- * Error codes for protocol layer (Layer 6) errors.
774
- *
775
- * These errors occur at the protocol level (Sesame, message routing).
776
- */
777
- export var ProtocolErrorCode;
778
- (function (ProtocolErrorCode) {
779
- /** Invalid message format */
780
- ProtocolErrorCode["INVALID_MESSAGE"] = "PROTOCOL_INVALID_MESSAGE";
781
- /** Invalid prekey bundle */
782
- ProtocolErrorCode["INVALID_BUNDLE"] = "PROTOCOL_INVALID_BUNDLE";
783
- /** Protocol version mismatch */
784
- ProtocolErrorCode["VERSION_MISMATCH"] = "PROTOCOL_VERSION_MISMATCH";
785
- /** Device not found in device list */
786
- ProtocolErrorCode["DEVICE_NOT_FOUND"] = "PROTOCOL_DEVICE_NOT_FOUND";
787
- /** Stale device list */
788
- ProtocolErrorCode["STALE_DEVICE_LIST"] = "PROTOCOL_STALE_DEVICE_LIST";
789
- /** Retry request required */
790
- ProtocolErrorCode["RETRY_REQUIRED"] = "PROTOCOL_RETRY_REQUIRED";
791
- /** Sender key distribution failed */
792
- ProtocolErrorCode["SENDER_KEY_FAILED"] = "PROTOCOL_SENDER_KEY_FAILED";
793
- })(ProtocolErrorCode || (ProtocolErrorCode = {}));
794
- /**
795
- * Protocol layer error (Layer 6).
796
- *
797
- * Thrown for protocol-level issues like message format errors,
798
- * version mismatches, or multi-device coordination failures.
799
- *
800
- * @example
801
- * ```typescript
802
- * throw new ProtocolError(
803
- * 'Device list is stale, retry required',
804
- * ProtocolErrorCode.STALE_DEVICE_LIST,
805
- * { operation: 'sendGroupMessage', context: { groupId } }
806
- * );
807
- * ```
808
- */
809
- export class ProtocolError extends EncryptionError {
810
- protocolCode;
811
- protocolContext;
812
- constructor(message, code, context) {
813
- // Map to base EncryptionErrorCode for compatibility
814
- const baseCode = mapProtocolToEncryptionCode(code);
815
- super(message, baseCode, context);
816
- this.name = 'ProtocolError';
817
- this.protocolCode = code;
818
- this.protocolContext = context?.protocolContext;
819
- }
820
- }
821
- /**
822
- * Error codes for client-facing errors.
823
- *
824
- * These errors should be displayed to users (with appropriate messaging).
825
- */
826
- export var ClientErrorCode;
827
- (function (ClientErrorCode) {
828
- /** Network error during key exchange */
829
- ClientErrorCode["NETWORK_ERROR"] = "CLIENT_NETWORK_ERROR";
830
- /** User identity verification required */
831
- ClientErrorCode["VERIFICATION_REQUIRED"] = "CLIENT_VERIFICATION_REQUIRED";
832
- /** Recipient not found */
833
- ClientErrorCode["RECIPIENT_NOT_FOUND"] = "CLIENT_RECIPIENT_NOT_FOUND";
834
- /** Message delivery failed */
835
- ClientErrorCode["DELIVERY_FAILED"] = "CLIENT_DELIVERY_FAILED";
836
- /** Encryption unavailable (keys not initialized) */
837
- ClientErrorCode["ENCRYPTION_UNAVAILABLE"] = "CLIENT_ENCRYPTION_UNAVAILABLE";
838
- /** Session needs reset */
839
- ClientErrorCode["SESSION_RESET_NEEDED"] = "CLIENT_SESSION_RESET_NEEDED";
840
- })(ClientErrorCode || (ClientErrorCode = {}));
841
- /**
842
- * Client-facing error.
843
- *
844
- * These errors are intended to be shown to users with
845
- * appropriate messaging. Includes optional user-facing
846
- * message that can be displayed directly in UI.
847
- *
848
- * @example
849
- * ```typescript
850
- * throw new ClientError(
851
- * 'Failed to send encrypted message',
852
- * ClientErrorCode.DELIVERY_FAILED,
853
- * 'Message could not be delivered. Please try again.',
854
- * { operation: 'sendMessage' }
855
- * );
856
- * ```
857
- */
858
- export class ClientError extends EncryptionError {
859
- clientCode;
860
- userFacingMessage;
861
- constructor(message, code, userFacingMessage, context) {
862
- // Map to base EncryptionErrorCode for compatibility
863
- const baseCode = mapClientToEncryptionCode(code);
864
- super(message, baseCode, context);
865
- this.name = 'ClientError';
866
- this.clientCode = code;
867
- this.userFacingMessage = userFacingMessage;
868
- }
869
- }
870
- // ============================================================================
871
- // Error Code Mapping (Record-based with compile-time exhaustiveness)
872
- // ============================================================================
873
- /**
874
- * Map CryptoErrorCode to EncryptionErrorCode.
875
- *
876
- * Using Record type ensures compile-time exhaustiveness - TypeScript will
877
- * error if we add a new CryptoErrorCode without adding a mapping.
878
- */
879
- const cryptoToEncryptionCodeMap = {
880
- [CryptoErrorCode.RNG_FAILURE]: EncryptionErrorCode.ENCRYPTION_FAILED,
881
- [CryptoErrorCode.ECDH_FAILURE]: EncryptionErrorCode.ENCRYPTION_FAILED,
882
- [CryptoErrorCode.KYBER_FAILURE]: EncryptionErrorCode.KYBER_ERROR,
883
- [CryptoErrorCode.KDF_FAILURE]: EncryptionErrorCode.KDF_ERROR,
884
- [CryptoErrorCode.AES_FAILURE]: EncryptionErrorCode.ENCRYPTION_FAILED,
885
- [CryptoErrorCode.HMAC_FAILURE]: EncryptionErrorCode.HMAC_VERIFICATION_FAILED,
886
- [CryptoErrorCode.SIGNATURE_FAILURE]: EncryptionErrorCode.SIGNATURE_VERIFICATION_FAILED,
887
- [CryptoErrorCode.HASH_FAILURE]: EncryptionErrorCode.ENCRYPTION_FAILED,
888
- [CryptoErrorCode.INVALID_KEY]: EncryptionErrorCode.INVALID_DH_KEY,
889
- [CryptoErrorCode.INVALID_CIPHERTEXT]: EncryptionErrorCode.INVALID_CIPHERTEXT,
890
- };
891
- function mapCryptoToEncryptionCode(code) {
892
- return cryptoToEncryptionCodeMap[code];
893
- }
894
- /**
895
- * Map SessionErrorCode to EncryptionErrorCode.
896
- */
897
- const sessionToEncryptionCodeMap = {
898
- [SessionErrorCode.NOT_FOUND]: EncryptionErrorCode.SESSION_NOT_FOUND,
899
- [SessionErrorCode.CORRUPTED]: EncryptionErrorCode.SESSION_CORRUPTED,
900
- [SessionErrorCode.EXPIRED]: EncryptionErrorCode.SESSION_NOT_FOUND, // Treat expired as not found
901
- [SessionErrorCode.CONFLICT]: EncryptionErrorCode.SESSION_CONFLICT,
902
- [SessionErrorCode.INVALID_STATE]: EncryptionErrorCode.INVALID_STATE,
903
- [SessionErrorCode.RATCHET_FAILED]: EncryptionErrorCode.RATCHET_ERROR,
904
- [SessionErrorCode.TOO_MANY_SKIPPED]: EncryptionErrorCode.TOO_MANY_SKIPPED_MESSAGES,
905
- [SessionErrorCode.MESSAGE_KEY_NOT_FOUND]: EncryptionErrorCode.MESSAGE_TOO_OLD,
906
- [SessionErrorCode.ESTABLISHMENT_FAILED]: EncryptionErrorCode.SESSION_NOT_FOUND,
907
- };
908
- function mapSessionToEncryptionCode(code) {
909
- return sessionToEncryptionCodeMap[code];
910
- }
911
- /**
912
- * Map ProtocolErrorCode to EncryptionErrorCode.
913
- */
914
- const protocolToEncryptionCodeMap = {
915
- [ProtocolErrorCode.INVALID_MESSAGE]: EncryptionErrorCode.INVALID_CIPHERTEXT,
916
- [ProtocolErrorCode.INVALID_BUNDLE]: EncryptionErrorCode.INVALID_PREKEY_BUNDLE,
917
- [ProtocolErrorCode.VERSION_MISMATCH]: EncryptionErrorCode.INVALID_MESSAGE_VERSION,
918
- [ProtocolErrorCode.DEVICE_NOT_FOUND]: EncryptionErrorCode.SESSION_NOT_FOUND,
919
- [ProtocolErrorCode.STALE_DEVICE_LIST]: EncryptionErrorCode.INVALID_STATE,
920
- [ProtocolErrorCode.RETRY_REQUIRED]: EncryptionErrorCode.INVALID_STATE,
921
- [ProtocolErrorCode.SENDER_KEY_FAILED]: EncryptionErrorCode.ENCRYPTION_FAILED,
922
- };
923
- function mapProtocolToEncryptionCode(code) {
924
- return protocolToEncryptionCodeMap[code];
925
- }
926
- /**
927
- * Map ClientErrorCode to EncryptionErrorCode.
928
- */
929
- const clientToEncryptionCodeMap = {
930
- [ClientErrorCode.NETWORK_ERROR]: EncryptionErrorCode.UNKNOWN_ERROR,
931
- [ClientErrorCode.VERIFICATION_REQUIRED]: EncryptionErrorCode.UNTRUSTED_IDENTITY,
932
- [ClientErrorCode.RECIPIENT_NOT_FOUND]: EncryptionErrorCode.SESSION_NOT_FOUND,
933
- [ClientErrorCode.DELIVERY_FAILED]: EncryptionErrorCode.ENCRYPTION_FAILED,
934
- [ClientErrorCode.ENCRYPTION_UNAVAILABLE]: EncryptionErrorCode.INITIALIZATION_FAILED,
935
- [ClientErrorCode.SESSION_RESET_NEEDED]: EncryptionErrorCode.SESSION_NOT_FOUND,
936
- };
937
- function mapClientToEncryptionCode(code) {
938
- return clientToEncryptionCodeMap[code];
939
- }
940
- // ============================================================================
941
- // Type Guards for Tiered Errors
942
- // ============================================================================
943
- /**
944
- * Type guard to check if an error is a CryptoError.
945
- */
946
- export function isCryptoError(error) {
947
- return error instanceof CryptoError;
948
- }
949
- /**
950
- * Type guard to check if an error is a SessionError.
951
- */
952
- export function isSessionError(error) {
953
- return error instanceof SessionError;
954
- }
955
- /**
956
- * Type guard to check if an error is a ProtocolError.
957
- */
958
- export function isProtocolError(error) {
959
- return error instanceof ProtocolError;
960
- }
961
- /**
962
- * Type guard to check if an error is a ClientError.
963
- */
964
- export function isClientError(error) {
965
- return error instanceof ClientError;
966
- }
967
492
  /**
968
493
  * Type guard to check if an error is any Signal Protocol error.
969
494
  */