@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
@@ -6,32 +6,32 @@ application.
6
6
 
7
7
  ## Documentation hierarchy
8
8
 
9
- - The root [`README.md`](../README.md) introduces the package: what it is, how
10
- it compares to the alternatives, how to install it, one working example, and
11
- the evidence behind its security claims. It links onward rather than
12
- documenting the full surface itself.
9
+ - The root [`README.md`](../README.md) introduces the package. It says what
10
+ the package is, how it compares to the alternatives, and how to install it.
11
+ It also gives one working example and the evidence behind its security
12
+ claims. It links onward rather than documenting the full surface itself.
13
13
  - [`PACKAGE_SURFACE.md`](./PACKAGE_SURFACE.md) is the complete public surface:
14
14
  root exports, every subpath, adapter implementations, and core vocabulary.
15
15
  - [`RECIPES.md`](./RECIPES.md) holds the working shapes for common operations.
16
- - [`ASSURANCE.md`](./ASSURANCE.md) states what is verified, where, and what is
17
- not published.
16
+ - [`ASSURANCE.md`](./ASSURANCE.md) states what the project verifies, where it
17
+ verifies it, and what it does not publish.
18
18
  - A module README explains a meaningful exported domain or integration
19
19
  boundary. It answers what the module does, why it exists, and how to use it.
20
20
  - [`ARCHITECTURE.md`](../ARCHITECTURE.md) describes dependency direction and
21
21
  ownership across modules.
22
22
  - [`ADAPTERS.md`](../ADAPTERS.md) describes platform and backend composition.
23
- - `docs/api/` is generated from the exported TypeScript declarations and
23
+ - A generator builds `docs/api/` from the exported TypeScript declarations and
24
24
  source documentation.
25
25
 
26
26
  A thin leaf module does not need its own README when its parent guide explains
27
- the complete contract. A first-class domain, platform boundary, or external
28
- provider integration does.
27
+ the complete contract. A module that owns a domain, a platform boundary, or an
28
+ external provider integration does.
29
29
 
30
30
  ## README structure
31
31
 
32
32
  Module READMEs should normally include:
33
33
 
34
- 1. A plain-language statement of what the module does.
34
+ 1. What the module does, in plain language.
35
35
  2. Why the module is separate from the client or application layer.
36
36
  3. The canonical package import path.
37
37
  4. A minimal, complete example using public exports.
@@ -47,21 +47,21 @@ directly when that is the real integration shape.
47
47
 
48
48
  Public comments document the code that exists now. Prefer comments that explain:
49
49
 
50
- - invariants and validation rules;
51
- - who owns state or makes a security decision;
52
- - observable side effects and idempotency;
53
- - units, encodings, versioning, and expiry semantics;
54
- - why a boundary exists when the reason is not apparent from its type; and
50
+ - invariants and validation rules.
51
+ - who owns state or makes a security decision.
52
+ - observable side effects and idempotency.
53
+ - units, encodings, versioning, and expiry semantics.
54
+ - why a boundary exists when the reason is not apparent from its type.
55
55
  - failure or retry behavior that a caller must handle.
56
56
 
57
57
  Avoid comments that:
58
58
 
59
- - repeat the implementation line by line;
60
- - describe old file locations, migrations, or application-specific paths;
59
+ - repeat the implementation line by line.
60
+ - describe old file locations, migrations, or application-specific paths.
61
61
  - narrate implementation provenance or point to another project's source
62
- files;
63
- - use compatibility shorthand such as “Signal-style” or “Signal-aligned”;
64
- - expose internal assurance artifacts or their organization; or
62
+ files.
63
+ - use compatibility shorthand such as “Signal-style” or “Signal-aligned”.
64
+ - expose internal assurance artifacts or their organization.
65
65
  - promise behavior that belongs to an application, backend, or platform.
66
66
 
67
67
  Use public standards, RFCs, and project policy documents when an external
@@ -88,13 +88,13 @@ belongs in the public
88
88
 
89
89
  State boundaries directly:
90
90
 
91
- - device-local stores own private keys and session state;
91
+ - device-local stores own private keys and session state.
92
92
  - relays own authenticated device/public-key records and encrypted-envelope
93
- delivery;
93
+ delivery.
94
94
  - object-store brokers own authorization, canonical object identifiers, and
95
- provider keys;
95
+ provider keys.
96
96
  - applications own product policy, account authorization, decrypted message
97
- persistence, and user experience; and
97
+ persistence, and user experience.
98
98
  - generated framework APIs remain application-owned even when an SDK adapter
99
99
  consumes them.
100
100
 
package/docs/E2EE.md CHANGED
@@ -12,26 +12,24 @@ recipient's devices. A relay or server sees ciphertext envelopes and routing
12
12
  metadata, never message contents or long-term private keys.
13
13
 
14
14
  This page explains what that changes about how you build. If you have only ever
15
- built server-authoritative applications, most of the work of adopting E2EE is
16
- absorbing these changes — the cryptography itself is the part the SDK already
17
- did.
15
+ built server-authoritative applications, most of the work of adopting E2EE lies
16
+ in these changes. The cryptography itself is the part the SDK already did.
18
17
 
19
18
  ## Security Guarantees
20
19
 
21
- - **End-to-end encryption** — message contents are encrypted on the sender's
22
- device and decrypted only on recipient devices. Intermediaries handle
23
- ciphertext only.
24
- - **Forward secrecy** — per-message keys are derived from a ratchet and deleted
25
- after use, so compromising current key material does not expose previously
26
- captured ciphertext.
27
- - **Break-in recovery** (post-compromise security) — the Diffie–Hellman ratchet
28
- heals the session after a key compromise, so future messages regain
29
- confidentiality once fresh ratchet keys are exchanged.
30
- - **Post-quantum confidentiality** — PQXDH and the SPQR ratchet mix ML-KEM
31
- (FIPS 203) shared secrets into key agreement and continuous ratcheting,
32
- providing resistance against harvest-now-decrypt-later adversaries.
33
- - **Authentication & integrity** — messages are authenticated (AEAD + MACs) and
34
- identities are verifiable through safety numbers.
20
+ - **End-to-end encryption**. The sender's device encrypts message contents, and
21
+ only recipient devices decrypt them. Intermediaries handle ciphertext only.
22
+ - **Forward secrecy**. A ratchet derives per-message keys and deletes them after
23
+ use. An attacker who holds current key material therefore cannot read
24
+ previously captured ciphertext.
25
+ - **Break-in recovery** (post-compromise security). The Diffie–Hellman ratchet
26
+ heals the session after a key compromise. Future messages regain
27
+ confidentiality once the peers exchange fresh ratchet keys.
28
+ - **Post-quantum confidentiality**. PQXDH and the SPQR ratchet mix ML-KEM
29
+ (FIPS 203) shared secrets into key agreement and continuous ratcheting. This
30
+ resists harvest-now-decrypt-later adversaries.
31
+ - **Authentication & integrity**. AEAD and MACs authenticate every message, and
32
+ safety numbers make identities verifiable.
35
33
 
36
34
  ## What changes about your architecture
37
35
 
@@ -40,61 +38,66 @@ did.
40
38
  In a server-authoritative app, the database holds the truth and the backend
41
39
  reads it to do its job. With E2EE the relay carries sealed envelopes: it can
42
40
  route, store, and meter them, but it cannot read, search, filter, moderate, or
43
- render them. Server-side features that assume plaintext — full-text search,
44
- content previews, server-rendered notifications, analytics over message
45
- content — do not degrade; they stop existing, and their replacements live on
46
- the device. The [architecture overview](../ARCHITECTURE.md) shows exactly which
41
+ render them. Four kinds of server-side feature assume plaintext: full-text
42
+ search, content previews, server-rendered notifications, and analytics over
43
+ message content. They do not degrade. They stop existing, and their
44
+ replacements live on the device.
45
+ The [architecture overview](../ARCHITECTURE.md) shows exactly which
47
46
  responsibilities sit on which side of that line.
48
47
 
49
48
  ### The device becomes the source of truth
50
49
 
51
- Message history, session state, and keys live in device-local storage — that is
52
- why the `storage` adapter is required, not optional. Ratchet state mutates on
53
- every decrypt and must persist atomically; treating local storage as a cache
54
- that can be dropped and refetched corrupts sessions irrecoverably. The
50
+ Message history, session state, and keys live in device-local storage. That is
51
+ why the SDK requires the `storage` adapter, rather than offering it as an
52
+ option. Ratchet state mutates on every decrypt and must persist atomically. An
53
+ application that treats local storage as a cache to drop and refetch corrupts
54
+ sessions irrecoverably. The
55
55
  [integration interfaces](./INTERFACES.md) exist to make that contract explicit.
56
56
 
57
57
  ### Identity becomes a set of device keys
58
58
 
59
- A user is no longer a row with a password hash; a user is a set of devices,
59
+ A user is no longer a row with a password hash. A user is a set of devices,
60
60
  each with its own identity key. Adding a second device is a protocol operation
61
- (linking), not a login. Removing one is revocation, not a session delete. Trust
62
- is established per `(userId, identityType)` and verified with safety numbers —
63
- see [Recipes](./RECIPES.md) for the multi-device and verification flows.
61
+ (linking), not a login. Removing one is revocation, not a session delete. The
62
+ SDK establishes trust per `(userId, identityType)`, and safety numbers verify
63
+ it. See [Recipes](./RECIPES.md) for the multi-device and verification flows.
64
64
 
65
65
  ### Recovery becomes a product decision
66
66
 
67
67
  When the server never has the keys, "forgot password" cannot restore content.
68
- What recovery looks like — device-to-device transfer, an encrypted backup a
69
- user can lose, or accepting history loss — is an application policy with real
70
- security tradeoffs in every direction. The SDK does not silently choose one for
71
- you. The considerations are laid out in the hosted guides at
68
+ Recovery is an application policy with real security tradeoffs in every
69
+ direction. The options are device-to-device transfer, an encrypted backup a
70
+ user can lose, or accepted history loss. The SDK does not silently choose one
71
+ for you. The considerations are laid out in the hosted guides at
72
72
  [docs.open-e2ee.dev](https://docs.open-e2ee.dev).
73
73
 
74
74
  ### Metadata remains visible
75
75
 
76
76
  E2EE protects content, not existence. The relay still observes envelope sizes,
77
- timing, and routing — who is talking to whom, when, and how much. Sealed sender
77
+ timing, and routing: who talks to whom, when, and how much. Sealed sender
78
78
  narrows what the relay learns about senders, with published limits stated
79
79
  plainly in the [security model](./SECURITY.md). Do not describe an E2EE product
80
- as anonymous; the two properties are different, and conflating them is the most
80
+ as anonymous. The two properties are different, and conflating them is the most
81
81
  common overclaim in this space.
82
82
 
83
83
  ### Failure modes are new
84
84
 
85
- Sessions can desynchronize; identity keys change when someone reinstalls;
86
- messages arrive out of order or reference skipped keys; one-time prekeys run
87
- out. These are protocol realities, not bugs, and the SDK surfaces them as
88
- explicit states and errors rather than hiding them — see
85
+ - Sessions can desynchronize.
86
+ - Identity keys change when someone reinstalls.
87
+ - Messages arrive out of order or reference skipped keys.
88
+ - One-time prekeys run out.
89
+
90
+ These are protocol realities, not bugs. The SDK surfaces them as explicit
91
+ states and errors rather than hiding them. See
89
92
  [Error Handling](./ERROR_HANDLING.md) for what each one means and what your
90
93
  application should do about it.
91
94
 
92
95
  ## Verifiability
93
96
 
94
97
  The implementation uses narrow protocol seams, explicit state transitions, and
95
- injectable storage and relay boundaries so security properties can be evaluated
96
- independently. This documentation describes intended behavior; it is not a
97
- third-party security certification.
98
+ injectable storage and relay boundaries, so a reviewer can evaluate its
99
+ security properties independently. This documentation describes intended
100
+ behavior. It is not a third-party security certification.
98
101
 
99
102
  See also [SECURITY.md](./SECURITY.md), [ASSURANCE.md](./ASSURANCE.md), and
100
103
  [ARCHITECTURE.md](../ARCHITECTURE.md).
@@ -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
 
@@ -53,69 +53,16 @@ try {
53
53
  }
54
54
  ```
55
55
 
56
- #### IdentityKeyChangedError
57
-
58
- Thrown when a remote party's identity key has changed. Could indicate:
59
-
60
- - Legitimate: Device reinstall, new device, backup restoration
61
- - Attack: Man-in-the-middle attack
62
-
63
- ```typescript
64
- import { isIdentityKeyChangedError } from '@open-e2ee/signal-protocol-sdk';
65
-
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.
84
-
85
- ```typescript
86
- import { isSessionConflictError } from '@open-e2ee/signal-protocol-sdk';
87
-
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
- ```
98
-
99
- #### RegistrationIdChangedError
56
+ ## Error Codes
100
57
 
101
- Thrown when a remote party's registration ID has changed (app reinstall detected).
58
+ The SDK throws every code below. An error-surface check parses the SDK for the
59
+ construction sites that decide that. It fails the build if a code or a subclass
60
+ survives that nothing produces. A code documented here is therefore one an
61
+ application can branch on. The check runs on every change, with the rest of the
62
+ checks that [ASSURANCE.md](./ASSURANCE.md) describes.
102
63
 
103
- ```typescript
104
- import { isRegistrationIdChangedError } from '@open-e2ee/signal-protocol-sdk';
105
-
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
- ```
117
-
118
- ## Error Codes
64
+ The tables group the codes an application handles most often. They are not the
65
+ whole set: `EncryptionErrorCode` is, and every member of it is reachable.
119
66
 
120
67
  ### Session Errors
121
68
 
@@ -123,7 +70,6 @@ try {
123
70
  | ------------------- | --------------------------------- | ----------------------- |
124
71
  | `SESSION_NOT_FOUND` | No session exists for the address | Establish new session |
125
72
  | `SESSION_CORRUPTED` | Session data is invalid | Delete and re-establish |
126
- | `SESSION_CONFLICT` | Multiple active sessions detected | Use Sesame convergence |
127
73
 
128
74
  ### Message Errors
129
75
 
@@ -133,61 +79,45 @@ try {
133
79
  | `DECRYPTION_FAILED` | Could not decrypt message | Check session state |
134
80
  | `ENCRYPTION_FAILED` | Could not encrypt message | Check session state |
135
81
  | `MESSAGE_DUPLICATE` | Message already processed | Ignore (replay protection) |
136
- | `MESSAGE_TOO_OLD` | Message keys expired | Request retransmission |
137
82
  | `TOO_MANY_SKIPPED_MESSAGES` | DoS protection triggered | Reset session |
138
- | `INVALID_MESSAGE_VERSION` | Protocol version mismatch | Update client |
139
83
 
140
84
  ### Identity & Trust Errors
141
85
 
142
86
  | Code | Description | Recovery |
143
87
  | ------------------------------- | --------------------- | ------------------------ |
144
- | `UNTRUSTED_IDENTITY` | Identity not verified | Verify safety number |
145
- | `IDENTITY_KEY_CHANGED` | Identity key changed | Verify and accept/reject |
88
+ | `UNTRUSTED_IDENTITY` | Identity not verified, including after it changed | Verify safety number |
146
89
  | `SIGNATURE_VERIFICATION_FAILED` | Signature is invalid | Reject message |
147
90
 
148
91
  ### PreKey & Session Establishment Errors
149
92
 
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 |
93
+ | Code | Description | Recovery |
94
+ | ----------------------- | -------------------- | ---------------- |
95
+ | `INVALID_PREKEY_BUNDLE` | Bundle is malformed | Fetch new bundle |
96
+ | `PREKEY_NOT_FOUND` | PreKey not available | Rotate prekeys |
156
97
 
157
98
  ### Ratchet Errors
158
99
 
159
100
  | Code | Description | Recovery |
160
101
  | ---------------- | ----------------- | -------------- |
161
- | `RATCHET_ERROR` | DH ratchet failed | Reset session |
162
102
  | `INVALID_DH_KEY` | DH key is invalid | Reject message |
163
103
 
164
104
  ### Storage Errors
165
105
 
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 |
171
-
172
- ### Cryptographic Errors
173
-
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 |
106
+ | Code | Description | Recovery |
107
+ | ------------------------ | ------------------------- | --------------------- |
108
+ | `KEY_STORAGE_ERROR` | Storage operation failed | Retry or reinitialize |
109
+ | `STORAGE_QUOTA_EXCEEDED` | The store ran out of room | Free space or prune |
179
110
 
180
111
  ## Error Handling Patterns
181
112
 
182
- ### Comprehensive Error Handler
113
+ ### One Handler for Every Error
183
114
 
184
115
  ```typescript
185
116
  import {
186
117
  EncryptionError,
187
118
  EncryptionErrorCode,
188
119
  isUntrustedIdentityError,
189
- isIdentityKeyChangedError,
190
- isSessionConflictError,
120
+ isSealedSenderAuthError,
191
121
  } from '@open-e2ee/signal-protocol-sdk';
192
122
 
193
123
  async function handleEncryptionError(error: unknown): Promise<void> {
@@ -202,13 +132,8 @@ async function handleEncryptionError(error: unknown): Promise<void> {
202
132
  return;
203
133
  }
204
134
 
205
- if (isIdentityKeyChangedError(error)) {
206
- await handleIdentityKeyChanged(error);
207
- return;
208
- }
209
-
210
- if (isSessionConflictError(error)) {
211
- await handleSessionConflict(error);
135
+ if (isSealedSenderAuthError(error)) {
136
+ await reauthorizeSealedSender(error);
212
137
  return;
213
138
  }
214
139
 
@@ -218,19 +143,16 @@ async function handleEncryptionError(error: unknown): Promise<void> {
218
143
  await establishNewSession(error.address);
219
144
  break;
220
145
 
221
- case EncryptionErrorCode.MESSAGE_TOO_OLD:
222
146
  case EncryptionErrorCode.TOO_MANY_SKIPPED_MESSAGES:
223
147
  // Message is unrecoverable, notify user
224
148
  notifyMessageLost(error.context?.operation);
225
149
  break;
226
150
 
227
151
  case EncryptionErrorCode.DECRYPTION_FAILED:
228
- case EncryptionErrorCode.HMAC_VERIFICATION_FAILED:
229
152
  // Possible tampering or corruption
230
153
  logSecurityEvent(error);
231
154
  break;
232
155
 
233
- case EncryptionErrorCode.DATABASE_ERROR:
234
156
  case EncryptionErrorCode.KEY_STORAGE_ERROR:
235
157
  // Storage issue, retry with backoff
236
158
  await retryWithBackoff(() => reinitializeStorage());
@@ -364,14 +286,16 @@ throw new Error('Session error');
364
286
 
365
287
  ```typescript
366
288
  // Identity changes require prominent user warning
367
- if (isIdentityKeyChangedError(error)) {
289
+ if (isUntrustedIdentityError(error)) {
368
290
  // Don't silently accept - show security dialog
369
291
  const accepted = await showSecurityWarningDialog(error);
370
292
  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;
293
+ // acceptIdentityRotation() takes the peer's new composite identity tuple and
294
+ // resets the sessions bound to the retired identity. Read that tuple from the
295
+ // relay rather than from `error.identity`: the error carries whichever tuple
296
+ // failed the trust check, which on the three session-bound throw sites is the
297
+ // pinned one being rejected, not the one the peer now publishes.
298
+ const userId = error.untrustedAddress.userId;
375
299
  const identity = await relay.getIdentityKey(userId);
376
300
  if (identity) {
377
301
  await signal.acceptIdentityRotation(userId, identity);
@@ -11,7 +11,7 @@ not want to learn protocol internals before sending a message.
11
11
  npm install @open-e2ee/signal-protocol-sdk
12
12
  ```
13
13
 
14
- In this monorepo the package is consumed as a workspace package. App consumers
14
+ In this monorepo, consumers use the package as a workspace package. App consumers
15
15
  should also install any runtime dependencies their chosen adapters need, such as
16
16
  Expo or Convex client packages.
17
17
 
@@ -22,7 +22,7 @@ Every client needs:
22
22
  - a stable `userId` from your app,
23
23
  - local `storage` for that user's encrypted protocol state,
24
24
  - usually a `relay` for server sync and encrypted message delivery,
25
- - remote encrypted object storage when sending attachments,
25
+ - an encrypted remote object store when sending attachments,
26
26
  - device registration or provisioning with that relay for each active device.
27
27
 
28
28
  The default security policy requires the package's post-quantum Signal Protocol
@@ -32,7 +32,7 @@ path.
32
32
  This guide uses the current stable API names. The target message-first DX groups
33
33
  local persistence under `deviceStorage.{protocol,messages,files}` and calls the
34
34
  remote encrypted byte adapter `remoteObjectStore`. Current `signal.media.*`
35
- examples are transition-only lower-level APIs; the target public API sends
35
+ examples are transition-only lower-level APIs. The target public API sends
36
36
  message attachments through `signal.messages.send({ attachments })` and advanced
37
37
  helpers, if needed, under a message-scoped API.
38
38
 
@@ -99,12 +99,12 @@ flowchart LR
99
99
  decrypts or stages them.
100
100
  - The relay connects devices, stores public keys, and carries encrypted
101
101
  envelopes.
102
- - Remote object storage carries encrypted attachment/media bytes only.
102
+ - The remote object store carries encrypted attachment/media bytes only.
103
103
 
104
104
  ## Target Message-First API Preview
105
105
 
106
- This is the target DX the package is moving toward. It is shown here so app
107
- developers can understand the intended mental model while the current stable API
106
+ This is the target DX the package moves toward. It appears here so app
107
+ developers can understand the intended mental model. The current stable API
108
108
  still uses `storage`, `remoteObjectStore`, hooks, and transition-only media helpers.
109
109
 
110
110
  <!-- doc-snippet:skip target-message-api-not-yet-shipped -->
@@ -181,9 +181,9 @@ const signal = await createSignalProtocolClient({
181
181
  });
182
182
  ```
183
183
 
184
- Attachments use the same message API. On Expo, pass the picker URI; the Signal
184
+ Attachments use the same message API. On Expo, pass the picker URI. The Signal
185
185
  Protocol client copies or persists the bytes through `deviceStorage.files`
186
- before upload so retry can continue after restart:
186
+ before upload, so retry can continue after restart:
187
187
 
188
188
  ```ts
189
189
  await signal.messages.send({
@@ -224,9 +224,9 @@ current `signal.media.*` examples into lower-level transition or migration docs.
224
224
 
225
225
  ## Current Stable Local Clients
226
226
 
227
- Use the in-memory adapters for local examples and development:
228
- the demo sends while Bob is offline, inspects the relay-visible ciphertext, and
229
- then starts Bob's subscription to show the decrypted plaintext entering the app.
227
+ Use the in-memory adapters for local examples and development. The demo sends
228
+ while Bob is offline, inspects the relay-visible ciphertext, and then starts
229
+ Bob's subscription to show the decrypted plaintext entering the app.
230
230
 
231
231
  <!-- doc-snippet:run getting-started-stable-local-clients expect="bob decrypted: alice: hello" -->
232
232
  ```ts
@@ -304,7 +304,7 @@ bob decrypted: alice: hello
304
304
  ```
305
305
 
306
306
  The in-memory relay lets the example inspect what a server can see. The relay sees
307
- metadata plus encrypted envelope bytes; it does not receive Bob's decrypted
307
+ metadata plus encrypted envelope bytes. It does not receive Bob's decrypted
308
308
  message content. The first message often uses `prekey_bundle` to establish a
309
309
  session, and later messages use `ciphertext`.
310
310
 
@@ -397,7 +397,7 @@ Add a remote object store when your app sends encrypted attachments. The
397
397
  `remoteObjectStore` adapter brokers encrypted byte objects rather than
398
398
  plaintext files.
399
399
  The final public DX should not expose both `signal.media.*` and message
400
- attachment helpers; the planned replacement is message-scoped attachment
400
+ attachment helpers. The planned replacement is message-scoped attachment
401
401
  handling.
402
402
 
403
403
  ```ts
@@ -448,8 +448,7 @@ Keep AWS credentials and AWS SDK clients on that backend. The app should
448
448
  receive only narrowly scoped, short-lived upload, download, and delete
449
449
  operations.
450
450
 
451
- Send bytes when the attachment should be delivered as its own encrypted
452
- message:
451
+ Send bytes when the attachment travels as its own encrypted message:
453
452
 
454
453
  ```ts
455
454
  const controller = new AbortController();
@@ -510,7 +509,7 @@ a generic transient failure.
510
509
 
511
510
  `attachment.transfer` is where production apps plug in their foreground or
512
511
  background transfer adapter. The Signal Protocol client still owns encryption, digest
513
- verification, retries, and pointer metadata; the adapter owns how bytes move
512
+ verification, retries, and pointer metadata. The adapter owns how bytes move
514
513
  over the network.
515
514
 
516
515
  If your object store returns TUS credentials, including `protocol: 'tus'`, the
@@ -520,14 +519,14 @@ useful when the app needs custom chunk sizing or a platform-specific `fetch`.
520
519
 
521
520
  For downloads in JavaScript runtimes, `media.createByteRangeMediaAttachmentTransfer()`
522
521
  provides a reviewed HTTP `Range` adapter. It validates `Content-Range`, forwards
523
- signed download headers from the object store, emits checkpoints, and only resumes
524
- from a non-zero offset when your app provides the partial ciphertext prefix via a
525
- partial-byte store. Native background download code should implement the same
522
+ signed download headers from the object store, and emits checkpoints. It resumes
523
+ from a non-zero offset only when your app provides the partial ciphertext prefix
524
+ through a partial-byte store. Native background download code should implement the same
526
525
  `MediaAttachmentTransfer` interface.
527
526
 
528
527
  For background-safe uploads, use the durable client operation. The current API
529
528
  persists bounded recovery metadata through the existing Signal Protocol storage
530
- adapter; the target message-first API moves that responsibility behind
529
+ adapter. The target message-first API moves that responsibility behind
531
530
  `deviceStorage.messages`. The operation tries the upload when it is due and
532
531
  returns either a completed pointer or a pending job id for later recovery:
533
532
 
@@ -564,8 +563,8 @@ await signal.media.processPending({
564
563
  ```
565
564
 
566
565
  On receive, ask the media planner what work this device should do. Your app
567
- supplies the IDs it has already processed or cached; the Signal Protocol package
568
- returns the safe next step without taking ownership of your app database:
566
+ supplies the IDs it has already processed or cached. The Signal Protocol package
567
+ returns the safe next step, and it does not take ownership of your app database:
569
568
 
570
569
  ```ts
571
570
  const mediaWork = media.planMediaAttachmentProcessing({
@@ -661,8 +660,8 @@ if (opened.cleanup?.deleteRemoteBlob) {
661
660
  }
662
661
  ```
663
662
 
664
- When a message delete or expiration should remove media on this account's linked
665
- devices, plan and sync the deletion after your app applies the local cleanup:
663
+ A message delete or expiration can remove media on this account's linked
664
+ devices. Plan and sync the deletion after your app applies the local cleanup:
666
665
 
667
666
  ```ts
668
667
  const deleteSync = media.planMediaAttachmentDeleteSync({
@@ -675,7 +674,7 @@ await appMediaCache.delete(deleteSync.storageId);
675
674
  await signal.syncMediaAttachmentDeleteToLinkedDevices(deleteSync);
676
675
  ```
677
676
 
678
- When cleanup should be performed by a worker, use the durable client operation:
677
+ When a worker must do the cleanup, use the durable client operation:
679
678
 
680
679
  ```ts
681
680
  await signal.media.cleanup(