@open-e2ee/signal-protocol-sdk 0.2.3 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (615) hide show
  1. package/ADAPTERS.md +11 -4
  2. package/ARCHITECTURE.md +19 -16
  3. package/CHANGELOG.md +72 -0
  4. package/COMMERCIAL.md +6 -6
  5. package/NOTICE +1 -1
  6. package/README.md +65 -93
  7. package/SECURITY.md +16 -13
  8. package/TROUBLESHOOTING.md +12 -5
  9. package/blocking/README.md +7 -5
  10. package/client/README.md +15 -5
  11. package/device/README.md +13 -8
  12. package/dist/blocking/types.d.ts +2 -2
  13. package/dist/blocking/types.js +2 -2
  14. package/dist/client/client.d.ts +46 -45
  15. package/dist/client/client.d.ts.map +1 -1
  16. package/dist/client/client.js +61 -60
  17. package/dist/client/client.js.map +1 -1
  18. package/dist/client/config.d.ts +32 -32
  19. package/dist/client/constants.d.ts +7 -6
  20. package/dist/client/constants.d.ts.map +1 -1
  21. package/dist/client/constants.js +5 -4
  22. package/dist/client/constants.js.map +1 -1
  23. package/dist/client/dual-store.d.ts +2 -2
  24. package/dist/client/dual-store.js +2 -2
  25. package/dist/client/endorsement-manager.d.ts +14 -14
  26. package/dist/client/endorsement-manager.d.ts.map +1 -1
  27. package/dist/client/endorsement-manager.js +15 -15
  28. package/dist/client/endorsement-manager.js.map +1 -1
  29. package/dist/client/event-hooks.d.ts +16 -16
  30. package/dist/client/event-hooks.d.ts.map +1 -1
  31. package/dist/client/event-hooks.js +1 -1
  32. package/dist/client/event-hooks.js.map +1 -1
  33. package/dist/client/files.js +4 -4
  34. package/dist/client/files.js.map +1 -1
  35. package/dist/client/groups.d.ts.map +1 -1
  36. package/dist/client/groups.js +14 -4
  37. package/dist/client/groups.js.map +1 -1
  38. package/dist/client/headless.d.ts +7 -7
  39. package/dist/client/headless.d.ts.map +1 -1
  40. package/dist/client/headless.js +4 -4
  41. package/dist/client/key-rotation-core.d.ts +19 -17
  42. package/dist/client/key-rotation-core.d.ts.map +1 -1
  43. package/dist/client/key-rotation-core.js +35 -31
  44. package/dist/client/key-rotation-core.js.map +1 -1
  45. package/dist/client/key-rotation.d.ts +8 -8
  46. package/dist/client/key-rotation.js +8 -8
  47. package/dist/client/media.d.ts +1 -1
  48. package/dist/client/messages.d.ts.map +1 -1
  49. package/dist/client/messages.js +13 -11
  50. package/dist/client/messages.js.map +1 -1
  51. package/dist/client/multi-device.d.ts +5 -4
  52. package/dist/client/multi-device.d.ts.map +1 -1
  53. package/dist/client/multi-device.js.map +1 -1
  54. package/dist/client/prekeys.d.ts +7 -7
  55. package/dist/client/prekeys.js +10 -10
  56. package/dist/client/prekeys.js.map +1 -1
  57. package/dist/client/relay-subscription.d.ts +3 -0
  58. package/dist/client/relay-subscription.d.ts.map +1 -1
  59. package/dist/client/relay-subscription.js +7 -4
  60. package/dist/client/relay-subscription.js.map +1 -1
  61. package/dist/client/retry-utils.d.ts +5 -6
  62. package/dist/client/retry-utils.d.ts.map +1 -1
  63. package/dist/client/retry-utils.js +5 -12
  64. package/dist/client/retry-utils.js.map +1 -1
  65. package/dist/client/retry.js +7 -7
  66. package/dist/client/retry.js.map +1 -1
  67. package/dist/client/sealed-sender-ops.d.ts +3 -3
  68. package/dist/client/sealed-sender-ops.js +5 -5
  69. package/dist/client/sealed-sender-ops.js.map +1 -1
  70. package/dist/client/sessions.d.ts +2 -2
  71. package/dist/client/sessions.js +2 -2
  72. package/dist/client/signal-service-cipher.d.ts +9 -9
  73. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  74. package/dist/client/signal-service-cipher.js +41 -40
  75. package/dist/client/signal-service-cipher.js.map +1 -1
  76. package/dist/client/state.d.ts +1 -1
  77. package/dist/client/state.js +1 -1
  78. package/dist/client/types.d.ts +19 -19
  79. package/dist/client/types.d.ts.map +1 -1
  80. package/dist/device/connection.d.ts +1 -1
  81. package/dist/device/connection.js +2 -2
  82. package/dist/device/connection.js.map +1 -1
  83. package/dist/device/constants.d.ts +4 -4
  84. package/dist/device/constants.js +3 -3
  85. package/dist/device/device-id.d.ts +4 -4
  86. package/dist/device/device-id.js +4 -4
  87. package/dist/device/expo-metadata.d.ts +13 -11
  88. package/dist/device/expo-metadata.d.ts.map +1 -1
  89. package/dist/device/expo-metadata.js +13 -11
  90. package/dist/device/expo-metadata.js.map +1 -1
  91. package/dist/device/lifecycle/manager.d.ts +6 -6
  92. package/dist/device/lifecycle/manager.js +7 -7
  93. package/dist/device/lifecycle/types.d.ts +13 -13
  94. package/dist/device/lifecycle/types.d.ts.map +1 -1
  95. package/dist/device/lifecycle/utils.d.ts +2 -2
  96. package/dist/device/lifecycle/utils.js +5 -5
  97. package/dist/device/lifecycle/utils.js.map +1 -1
  98. package/dist/device/provisioning.d.ts +5 -4
  99. package/dist/device/provisioning.d.ts.map +1 -1
  100. package/dist/device/provisioning.js +5 -4
  101. package/dist/device/provisioning.js.map +1 -1
  102. package/dist/device/transfer.d.ts +2 -2
  103. package/dist/device/transfer.js +3 -3
  104. package/dist/device/transfer.js.map +1 -1
  105. package/dist/encoding/index.d.ts +3 -4
  106. package/dist/encoding/index.d.ts.map +1 -1
  107. package/dist/encoding/index.js.map +1 -1
  108. package/dist/files/index.d.ts +1 -1
  109. package/dist/files/index.js +1 -1
  110. package/dist/hooks/use-connection-presence.d.ts +1 -1
  111. package/dist/hooks/use-connection-presence.js +7 -7
  112. package/dist/hooks/use-connection-presence.js.map +1 -1
  113. package/dist/hooks/use-group-membership.d.ts +2 -2
  114. package/dist/hooks/use-group-membership.d.ts.map +1 -1
  115. package/dist/hooks/use-group-membership.js +6 -6
  116. package/dist/hooks/use-group-membership.js.map +1 -1
  117. package/dist/hooks/use-key-rotation.js +3 -3
  118. package/dist/hooks/use-key-rotation.js.map +1 -1
  119. package/dist/hooks/use-single-flight.d.ts +2 -2
  120. package/dist/hooks/use-single-flight.js +1 -1
  121. package/dist/index.d.ts +4 -3
  122. package/dist/index.d.ts.map +1 -1
  123. package/dist/index.js +21 -4
  124. package/dist/index.js.map +1 -1
  125. package/dist/internal/crypto/ec/ed25519.d.ts +6 -6
  126. package/dist/internal/crypto/ec/ed25519.js +6 -6
  127. package/dist/internal/crypto/ec/x25519-validation.d.ts.map +1 -1
  128. package/dist/internal/crypto/ec/x25519-validation.js +4 -2
  129. package/dist/internal/crypto/ec/x25519-validation.js.map +1 -1
  130. package/dist/internal/crypto/index.d.ts +2 -0
  131. package/dist/internal/crypto/index.d.ts.map +1 -1
  132. package/dist/internal/crypto/index.js +2 -0
  133. package/dist/internal/crypto/index.js.map +1 -1
  134. package/dist/internal/crypto/kdf/hkdf.d.ts +9 -8
  135. package/dist/internal/crypto/kdf/hkdf.d.ts.map +1 -1
  136. package/dist/internal/crypto/kdf/hkdf.js +11 -10
  137. package/dist/internal/crypto/kdf/hkdf.js.map +1 -1
  138. package/dist/internal/crypto/key-prefix.d.ts +3 -3
  139. package/dist/internal/crypto/key-prefix.js +3 -3
  140. package/dist/internal/crypto/pq/kyber.d.ts +7 -7
  141. package/dist/internal/crypto/pq/kyber.js +10 -10
  142. package/dist/internal/crypto/pq/kyber.js.map +1 -1
  143. package/dist/internal/crypto/random.d.ts +1 -1
  144. package/dist/internal/crypto/random.js +1 -1
  145. package/dist/internal/crypto/symmetric/aes-gcm-siv.js +1 -1
  146. package/dist/internal/crypto/symmetric/aes.js +4 -4
  147. package/dist/internal/crypto/symmetric/aes.js.map +1 -1
  148. package/dist/internal/crypto/symmetric/mac.d.ts +1 -1
  149. package/dist/internal/crypto/symmetric/mac.js +3 -3
  150. package/dist/internal/crypto/symmetric/padding.js +1 -1
  151. package/dist/internal/crypto/symmetric/padding.js.map +1 -1
  152. package/dist/internal/crypto/symmetric/streaming-aead.d.ts +7 -1
  153. package/dist/internal/crypto/symmetric/streaming-aead.d.ts.map +1 -1
  154. package/dist/internal/crypto/symmetric/streaming-aead.js +10 -4
  155. package/dist/internal/crypto/symmetric/streaming-aead.js.map +1 -1
  156. package/dist/internal/crypto/utils.d.ts +2 -2
  157. package/dist/internal/crypto/utils.d.ts.map +1 -1
  158. package/dist/internal/crypto/utils.js +16 -14
  159. package/dist/internal/crypto/utils.js.map +1 -1
  160. package/dist/internal/crypto/validation.d.ts +4 -4
  161. package/dist/internal/crypto/validation.js +2 -2
  162. package/dist/internal/encoding/proto/envelope.d.ts +1 -1
  163. package/dist/internal/encoding/proto/envelope.js +1 -1
  164. package/dist/internal/encoding/proto/index.d.ts +4 -4
  165. package/dist/internal/encoding/proto/index.js +4 -4
  166. package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts +28 -16
  167. package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts.map +1 -1
  168. package/dist/internal/encoding/proto/pq-ratchet-serialize.js +30 -18
  169. package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
  170. package/dist/internal/encoding/proto/primitives.d.ts +45 -35
  171. package/dist/internal/encoding/proto/primitives.d.ts.map +1 -1
  172. package/dist/internal/encoding/proto/primitives.js +54 -43
  173. package/dist/internal/encoding/proto/primitives.js.map +1 -1
  174. package/dist/internal/encoding/proto/sender-key-message.d.ts +2 -2
  175. package/dist/internal/encoding/proto/sender-key-message.js +2 -2
  176. package/dist/internal/encoding/proto/signal-message.d.ts +13 -13
  177. package/dist/internal/encoding/proto/signal-message.d.ts.map +1 -1
  178. package/dist/internal/encoding/proto/signal-message.js +13 -13
  179. package/dist/internal/encoding/proto/signal-message.js.map +1 -1
  180. package/dist/internal/groups/access-control.d.ts +5 -5
  181. package/dist/internal/groups/access-control.js +6 -6
  182. package/dist/internal/groups/access-control.js.map +1 -1
  183. package/dist/internal/groups/change-actions.d.ts +4 -4
  184. package/dist/internal/groups/change-actions.js +3 -3
  185. package/dist/internal/groups/encrypted-state.js +1 -1
  186. package/dist/internal/groups/encrypted-state.js.map +1 -1
  187. package/dist/internal/groups/group-id.d.ts +1 -1
  188. package/dist/internal/groups/manager.d.ts +24 -23
  189. package/dist/internal/groups/manager.d.ts.map +1 -1
  190. package/dist/internal/groups/manager.js +40 -36
  191. package/dist/internal/groups/manager.js.map +1 -1
  192. package/dist/internal/groups/server-engine.d.ts +29 -21
  193. package/dist/internal/groups/server-engine.d.ts.map +1 -1
  194. package/dist/internal/groups/server-engine.js +55 -50
  195. package/dist/internal/groups/server-engine.js.map +1 -1
  196. package/dist/internal/groups/trust-root.d.ts +2 -2
  197. package/dist/internal/groups/trust-root.js +2 -2
  198. package/dist/internal/groups/types.d.ts +4 -4
  199. package/dist/internal/groups/types.d.ts.map +1 -1
  200. package/dist/internal/groups/wire.d.ts +6 -7
  201. package/dist/internal/groups/wire.d.ts.map +1 -1
  202. package/dist/internal/groups/wire.js +6 -7
  203. package/dist/internal/groups/wire.js.map +1 -1
  204. package/dist/internal/manager/manager.d.ts +14 -12
  205. package/dist/internal/manager/manager.d.ts.map +1 -1
  206. package/dist/internal/manager/manager.js +47 -41
  207. package/dist/internal/manager/manager.js.map +1 -1
  208. package/dist/internal/protocol/double-ratchet/chains.d.ts +8 -6
  209. package/dist/internal/protocol/double-ratchet/chains.d.ts.map +1 -1
  210. package/dist/internal/protocol/double-ratchet/chains.js +10 -8
  211. package/dist/internal/protocol/double-ratchet/chains.js.map +1 -1
  212. package/dist/internal/protocol/double-ratchet/index.d.ts +2 -2
  213. package/dist/internal/protocol/double-ratchet/index.js +2 -2
  214. package/dist/internal/protocol/double-ratchet/ratchet.d.ts +4 -4
  215. package/dist/internal/protocol/double-ratchet/ratchet.js +6 -6
  216. package/dist/internal/protocol/pqxdh/pqxdh.d.ts +21 -18
  217. package/dist/internal/protocol/pqxdh/pqxdh.d.ts.map +1 -1
  218. package/dist/internal/protocol/pqxdh/pqxdh.js +48 -42
  219. package/dist/internal/protocol/pqxdh/pqxdh.js.map +1 -1
  220. package/dist/internal/protocol/sealed-sender/decryption-v2.js +5 -5
  221. package/dist/internal/protocol/sealed-sender/decryption-v2.js.map +1 -1
  222. package/dist/internal/protocol/sealed-sender/decryption.d.ts.map +1 -1
  223. package/dist/internal/protocol/sealed-sender/decryption.js +11 -8
  224. package/dist/internal/protocol/sealed-sender/decryption.js.map +1 -1
  225. package/dist/internal/protocol/sealed-sender/delivery-token.d.ts +2 -2
  226. package/dist/internal/protocol/sealed-sender/delivery-token.js +2 -2
  227. package/dist/internal/protocol/sealed-sender/encryption-v2.js +1 -1
  228. package/dist/internal/protocol/sealed-sender/encryption-v2.js.map +1 -1
  229. package/dist/internal/protocol/sealed-sender/encryption.d.ts +2 -2
  230. package/dist/internal/protocol/sealed-sender/encryption.js +2 -2
  231. package/dist/internal/protocol/sealed-sender/proto/index.d.ts +25 -23
  232. package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
  233. package/dist/internal/protocol/sealed-sender/proto/index.js +32 -30
  234. package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
  235. package/dist/internal/protocol/sealed-sender/trust-root.d.ts +10 -9
  236. package/dist/internal/protocol/sealed-sender/trust-root.d.ts.map +1 -1
  237. package/dist/internal/protocol/sealed-sender/trust-root.js +10 -9
  238. package/dist/internal/protocol/sealed-sender/trust-root.js.map +1 -1
  239. package/dist/internal/protocol/sealed-sender/types.d.ts +13 -14
  240. package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
  241. package/dist/internal/protocol/sealed-sender/types.js +7 -8
  242. package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
  243. package/dist/internal/protocol/sealed-sender/v2-binary.d.ts +1 -1
  244. package/dist/internal/protocol/sealed-sender/v2-binary.js +2 -2
  245. package/dist/internal/protocol/sealed-sender/v2-binary.js.map +1 -1
  246. package/dist/internal/protocol/sender-keys/manager.d.ts +16 -14
  247. package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
  248. package/dist/internal/protocol/sender-keys/manager.js +37 -34
  249. package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
  250. package/dist/internal/protocol/spqr/braid-serialize.d.ts +6 -6
  251. package/dist/internal/protocol/spqr/braid-serialize.js +5 -5
  252. package/dist/internal/protocol/spqr/braid-serialize.js.map +1 -1
  253. package/dist/internal/protocol/spqr/braid.d.ts +3 -3
  254. package/dist/internal/protocol/spqr/braid.js +7 -7
  255. package/dist/internal/protocol/spqr/braid.js.map +1 -1
  256. package/dist/internal/protocol/spqr/index.js +1 -1
  257. package/dist/internal/protocol/spqr/index.js.map +1 -1
  258. package/dist/internal/protocol/spqr/ml-kem-braid/chunk-domain.d.ts +3 -3
  259. package/dist/internal/protocol/spqr/ml-kem-braid/chunk-domain.js +3 -3
  260. package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js +1 -1
  261. package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js.map +1 -1
  262. package/dist/internal/protocol/spqr/ml-kem-braid/kdf.d.ts +1 -1
  263. package/dist/internal/protocol/spqr/ml-kem-braid/kdf.js +1 -1
  264. package/dist/internal/protocol/spqr/ml-kem-braid/kdf.js.map +1 -1
  265. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.d.ts +4 -3
  266. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.d.ts.map +1 -1
  267. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.js +4 -3
  268. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.js.map +1 -1
  269. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/index.js +2 -2
  270. package/dist/internal/protocol/spqr/ml-kem-braid/progress.d.ts +1 -1
  271. package/dist/internal/protocol/spqr/ml-kem-braid/progress.js +1 -1
  272. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts +15 -7
  273. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
  274. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js +15 -7
  275. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js.map +1 -1
  276. package/dist/internal/protocol/spqr/ml-kem-braid/rs/galois/field.js +1 -1
  277. package/dist/internal/protocol/spqr/ml-kem-braid/rs/polynomial.d.ts +3 -3
  278. package/dist/internal/protocol/spqr/ml-kem-braid/rs/polynomial.js +1 -1
  279. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts +7 -7
  280. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js +11 -11
  281. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js.map +1 -1
  282. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.d.ts +1 -1
  283. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js +6 -6
  284. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js.map +1 -1
  285. package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts +2 -2
  286. package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts.map +1 -1
  287. package/dist/internal/protocol/spqr/ml-kem-braid/types.js.map +1 -1
  288. package/dist/internal/protocol/spqr/serialize.d.ts +12 -12
  289. package/dist/internal/protocol/spqr/serialize.js +5 -5
  290. package/dist/internal/protocol/spqr/spqr.d.ts +6 -6
  291. package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
  292. package/dist/internal/protocol/spqr/spqr.js +47 -42
  293. package/dist/internal/protocol/spqr/spqr.js.map +1 -1
  294. package/dist/internal/protocol/spqr/validate.d.ts +1 -1
  295. package/dist/internal/protocol/triple-ratchet/ratchet.d.ts +12 -12
  296. package/dist/internal/protocol/triple-ratchet/ratchet.d.ts.map +1 -1
  297. package/dist/internal/protocol/triple-ratchet/ratchet.js +11 -11
  298. package/dist/internal/protocol/triple-ratchet/ratchet.js.map +1 -1
  299. package/dist/internal/protocol/username/hash.d.ts.map +1 -1
  300. package/dist/internal/protocol/username/hash.js +6 -4
  301. package/dist/internal/protocol/username/hash.js.map +1 -1
  302. package/dist/internal/protocol/version.d.ts +3 -3
  303. package/dist/internal/protocol/version.js +1 -1
  304. package/dist/internal/protocol/x3dh/x3dh.d.ts +16 -16
  305. package/dist/internal/protocol/x3dh/x3dh.d.ts.map +1 -1
  306. package/dist/internal/protocol/x3dh/x3dh.js +15 -15
  307. package/dist/internal/protocol/x3dh/x3dh.js.map +1 -1
  308. package/dist/internal/protocol/zk/credentials/attributes.d.ts +7 -7
  309. package/dist/internal/protocol/zk/credentials/attributes.js +7 -7
  310. package/dist/internal/protocol/zk/credentials/credentials.d.ts +1 -1
  311. package/dist/internal/protocol/zk/credentials/credentials.js +1 -1
  312. package/dist/internal/protocol/zk/credentials/endorsements.d.ts +11 -11
  313. package/dist/internal/protocol/zk/credentials/endorsements.js +14 -14
  314. package/dist/internal/protocol/zk/credentials/issuance.d.ts +5 -1
  315. package/dist/internal/protocol/zk/credentials/issuance.d.ts.map +1 -1
  316. package/dist/internal/protocol/zk/credentials/issuance.js +5 -1
  317. package/dist/internal/protocol/zk/credentials/issuance.js.map +1 -1
  318. package/dist/internal/protocol/zk/credentials/presentation.d.ts +16 -16
  319. package/dist/internal/protocol/zk/credentials/presentation.d.ts.map +1 -1
  320. package/dist/internal/protocol/zk/credentials/presentation.js +18 -18
  321. package/dist/internal/protocol/zk/credentials/presentation.js.map +1 -1
  322. package/dist/internal/protocol/zk/groups/auth-credential.d.ts +22 -16
  323. package/dist/internal/protocol/zk/groups/auth-credential.d.ts.map +1 -1
  324. package/dist/internal/protocol/zk/groups/auth-credential.js +19 -14
  325. package/dist/internal/protocol/zk/groups/auth-credential.js.map +1 -1
  326. package/dist/internal/protocol/zk/groups/client-zk-group-cipher.d.ts +4 -4
  327. package/dist/internal/protocol/zk/groups/client-zk-group-cipher.js +4 -4
  328. package/dist/internal/protocol/zk/groups/group-params.d.ts +2 -2
  329. package/dist/internal/protocol/zk/groups/group-params.js +2 -2
  330. package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts +10 -9
  331. package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts.map +1 -1
  332. package/dist/internal/protocol/zk/groups/group-send-endorsement.js +9 -8
  333. package/dist/internal/protocol/zk/groups/group-send-endorsement.js.map +1 -1
  334. package/dist/internal/protocol/zk/groups/lizard.d.ts +1 -1
  335. package/dist/internal/protocol/zk/groups/lizard.js +4 -4
  336. package/dist/internal/protocol/zk/groups/lizard.js.map +1 -1
  337. package/dist/internal/protocol/zk/groups/profile-key-commitment.d.ts +3 -3
  338. package/dist/internal/protocol/zk/groups/profile-key-commitment.js +3 -3
  339. package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts +11 -11
  340. package/dist/internal/protocol/zk/groups/profile-key-credential.js +7 -7
  341. package/dist/internal/protocol/zk/groups/profile-key-encryption.d.ts +2 -2
  342. package/dist/internal/protocol/zk/groups/profile-key-encryption.js +2 -2
  343. package/dist/internal/protocol/zk/groups/profile-key-struct.d.ts +2 -2
  344. package/dist/internal/protocol/zk/groups/profile-key-struct.js +2 -2
  345. package/dist/internal/protocol/zk/groups/profile-key-version.d.ts +2 -2
  346. package/dist/internal/protocol/zk/groups/profile-key-version.js +2 -2
  347. package/dist/internal/protocol/zk/groups/server-params.d.ts +1 -1
  348. package/dist/internal/protocol/zk/groups/server-params.js +1 -1
  349. package/dist/internal/protocol/zk/groups/uid-encryption.d.ts +4 -4
  350. package/dist/internal/protocol/zk/groups/uid-encryption.js +4 -4
  351. package/dist/internal/protocol/zk/groups/uid-struct.d.ts +2 -2
  352. package/dist/internal/protocol/zk/groups/uid-struct.js +3 -3
  353. package/dist/internal/protocol/zk/groups/uid-struct.js.map +1 -1
  354. package/dist/internal/protocol/zk/proofs/args.d.ts +3 -3
  355. package/dist/internal/protocol/zk/proofs/args.js +3 -3
  356. package/dist/internal/protocol/zk/proofs/sho-sha256.d.ts +3 -3
  357. package/dist/internal/protocol/zk/proofs/sho-sha256.js +3 -3
  358. package/dist/internal/protocol/zk/proofs/sho.d.ts +8 -7
  359. package/dist/internal/protocol/zk/proofs/sho.d.ts.map +1 -1
  360. package/dist/internal/protocol/zk/proofs/sho.js +8 -7
  361. package/dist/internal/protocol/zk/proofs/sho.js.map +1 -1
  362. package/dist/internal/protocol/zk/proofs/statement.d.ts +8 -6
  363. package/dist/internal/protocol/zk/proofs/statement.d.ts.map +1 -1
  364. package/dist/internal/protocol/zk/proofs/statement.js +8 -6
  365. package/dist/internal/protocol/zk/proofs/statement.js.map +1 -1
  366. package/dist/internal/sesame/manager.d.ts +23 -19
  367. package/dist/internal/sesame/manager.d.ts.map +1 -1
  368. package/dist/internal/sesame/manager.js +64 -54
  369. package/dist/internal/sesame/manager.js.map +1 -1
  370. package/dist/internal/sesame/types.d.ts +28 -27
  371. package/dist/internal/sesame/types.d.ts.map +1 -1
  372. package/dist/internal/sesame/types.js +2 -4
  373. package/dist/internal/sesame/types.js.map +1 -1
  374. package/dist/internal/sesame/validation.d.ts +2 -2
  375. package/dist/internal/sesame/validation.js +3 -3
  376. package/dist/internal/sesame/validation.js.map +1 -1
  377. package/dist/internal/session/builder.d.ts +8 -8
  378. package/dist/internal/session/builder.js +22 -22
  379. package/dist/internal/session/builder.js.map +1 -1
  380. package/dist/internal/session/cipher.d.ts +3 -3
  381. package/dist/internal/session/cipher.d.ts.map +1 -1
  382. package/dist/internal/session/cipher.js +51 -40
  383. package/dist/internal/session/cipher.js.map +1 -1
  384. package/dist/internal/session/decryption.js +11 -9
  385. package/dist/internal/session/decryption.js.map +1 -1
  386. package/dist/internal/session/factory.js +1 -1
  387. package/dist/internal/session/factory.js.map +1 -1
  388. package/dist/internal/session/handshake.d.ts +4 -4
  389. package/dist/internal/session/handshake.js +4 -4
  390. package/dist/internal/session/keys.d.ts +3 -4
  391. package/dist/internal/session/keys.d.ts.map +1 -1
  392. package/dist/internal/session/keys.js.map +1 -1
  393. package/dist/internal/session/ratchet.d.ts +8 -8
  394. package/dist/internal/session/ratchet.js +10 -10
  395. package/dist/internal/session/ratchet.js.map +1 -1
  396. package/dist/internal/session/session-resolver.d.ts +6 -6
  397. package/dist/internal/session/session-resolver.js +6 -6
  398. package/dist/internal/session/state.d.ts +12 -12
  399. package/dist/internal/session/state.d.ts.map +1 -1
  400. package/dist/internal/session/state.js +7 -7
  401. package/dist/internal/session/types.d.ts +20 -20
  402. package/dist/internal/session/types.d.ts.map +1 -1
  403. package/dist/internal/session/types.js +3 -3
  404. package/dist/internal/session/validation.d.ts +1 -1
  405. package/dist/internal/session/validation.js +4 -4
  406. package/dist/internal/session/validation.js.map +1 -1
  407. package/dist/keys/branded.d.ts +12 -12
  408. package/dist/keys/branded.js +3 -3
  409. package/dist/keys/generation.d.ts +4 -4
  410. package/dist/keys/generation.js +4 -4
  411. package/dist/keys/identity.d.ts +7 -7
  412. package/dist/keys/identity.d.ts.map +1 -1
  413. package/dist/keys/identity.js +7 -7
  414. package/dist/keys/identity.js.map +1 -1
  415. package/dist/keys/types.d.ts +16 -16
  416. package/dist/keys/types.d.ts.map +1 -1
  417. package/dist/layers.d.ts +1 -1
  418. package/dist/layers.js +1 -1
  419. package/dist/local/store/expo/adapter.d.ts +8 -8
  420. package/dist/local/store/expo/adapter.js +10 -10
  421. package/dist/local/store/expo/adapter.js.map +1 -1
  422. package/dist/local/store/expo/database-key.d.ts +7 -7
  423. package/dist/local/store/expo/database-key.js +7 -7
  424. package/dist/local/store/expo/key-storage.d.ts +1 -1
  425. package/dist/local/store/expo/key-storage.js +4 -4
  426. package/dist/local/store/expo/key-storage.js.map +1 -1
  427. package/dist/local/store/expo/models/kyber-prekey-used.d.ts +6 -6
  428. package/dist/local/store/expo/models/kyber-prekey-used.js +3 -3
  429. package/dist/local/store/expo/models/kyber-prekey.d.ts +1 -1
  430. package/dist/local/store/expo/models/kyber-prekey.js +1 -1
  431. package/dist/local/store/expo/models/message-record.d.ts +2 -2
  432. package/dist/local/store/expo/models/message-record.d.ts.map +1 -1
  433. package/dist/local/store/expo/models/message-record.js +1 -1
  434. package/dist/local/store/expo/models/message-record.js.map +1 -1
  435. package/dist/local/store/expo/models/sender-key.d.ts +11 -10
  436. package/dist/local/store/expo/models/sender-key.d.ts.map +1 -1
  437. package/dist/local/store/expo/models/sender-key.js +11 -10
  438. package/dist/local/store/expo/models/sender-key.js.map +1 -1
  439. package/dist/local/store/expo/schema.d.ts +2 -2
  440. package/dist/local/store/expo/schema.js +2 -2
  441. package/dist/local/store/expo/secure-store-options.d.ts +1 -1
  442. package/dist/local/store/memory/adapter.d.ts +2 -2
  443. package/dist/local/store/memory/adapter.js +12 -12
  444. package/dist/local/store/memory/adapter.js.map +1 -1
  445. package/dist/local/store/node/adapter.d.ts.map +1 -1
  446. package/dist/local/store/node/adapter.js +5 -4
  447. package/dist/local/store/node/adapter.js.map +1 -1
  448. package/dist/local/store/node/database-key.d.ts +8 -8
  449. package/dist/local/store/node/database-key.js +10 -10
  450. package/dist/local/store/node/database-key.js.map +1 -1
  451. package/dist/local/store/node/database.d.ts +5 -5
  452. package/dist/local/store/node/database.js +11 -11
  453. package/dist/local/store/node/database.js.map +1 -1
  454. package/dist/local/store/react-native/adapter.d.ts +6 -6
  455. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  456. package/dist/local/store/react-native/adapter.js +35 -32
  457. package/dist/local/store/react-native/adapter.js.map +1 -1
  458. package/dist/local/store/react-native/backend-conformance.d.ts +11 -10
  459. package/dist/local/store/react-native/backend-conformance.d.ts.map +1 -1
  460. package/dist/local/store/react-native/backend-conformance.js +13 -12
  461. package/dist/local/store/react-native/backend-conformance.js.map +1 -1
  462. package/dist/local/store/react-native/index.d.ts +1 -1
  463. package/dist/local/store/react-native/reference-backend.d.ts +14 -13
  464. package/dist/local/store/react-native/reference-backend.d.ts.map +1 -1
  465. package/dist/local/store/react-native/reference-backend.js +15 -14
  466. package/dist/local/store/react-native/reference-backend.js.map +1 -1
  467. package/dist/local/store/react-native/storage.d.ts +3 -3
  468. package/dist/local/store/web/adapter.d.ts +3 -3
  469. package/dist/local/store/web/adapter.d.ts.map +1 -1
  470. package/dist/local/store/web/adapter.js +30 -31
  471. package/dist/local/store/web/adapter.js.map +1 -1
  472. package/dist/local/store/web/index.d.ts +1 -1
  473. package/dist/local/vault/index.d.ts +2 -2
  474. package/dist/media/index.d.ts +11 -12
  475. package/dist/media/index.d.ts.map +1 -1
  476. package/dist/media/index.js +9 -10
  477. package/dist/media/index.js.map +1 -1
  478. package/dist/profile/contact-state.d.ts +1 -1
  479. package/dist/profile/contact-state.js +1 -1
  480. package/dist/profile/profile-key.d.ts +2 -2
  481. package/dist/profile/profile-key.js +7 -6
  482. package/dist/profile/profile-key.js.map +1 -1
  483. package/dist/remote/object-store/index.d.ts +1 -1
  484. package/dist/remote/object-store/s3/storage.d.ts +1 -1
  485. package/dist/remote/object-store/types.d.ts +4 -4
  486. package/dist/remote/object-store/types.d.ts.map +1 -1
  487. package/dist/remote/relay/convex/backend.d.ts +6 -6
  488. package/dist/remote/relay/convex/backend.d.ts.map +1 -1
  489. package/dist/remote/relay/convex/backend.js +4 -4
  490. package/dist/remote/relay/convex/backend.js.map +1 -1
  491. package/dist/remote/relay/convex/component/_generated/component.d.ts +2 -2
  492. package/dist/remote/relay/convex/component/_generated/component.d.ts.map +1 -1
  493. package/dist/remote/relay/convex/component/accounts.d.ts +15 -13
  494. package/dist/remote/relay/convex/component/accounts.d.ts.map +1 -1
  495. package/dist/remote/relay/convex/component/accounts.js +31 -28
  496. package/dist/remote/relay/convex/component/accounts.js.map +1 -1
  497. package/dist/remote/relay/convex/component/certificates.js +1 -1
  498. package/dist/remote/relay/convex/component/cleanup.js +7 -7
  499. package/dist/remote/relay/convex/component/cleanup.js.map +1 -1
  500. package/dist/remote/relay/convex/component/convex.config.d.ts.map +1 -1
  501. package/dist/remote/relay/convex/component/convex.config.js +10 -8
  502. package/dist/remote/relay/convex/component/convex.config.js.map +1 -1
  503. package/dist/remote/relay/convex/component/devices.d.ts +21 -20
  504. package/dist/remote/relay/convex/component/devices.d.ts.map +1 -1
  505. package/dist/remote/relay/convex/component/devices.js +24 -23
  506. package/dist/remote/relay/convex/component/devices.js.map +1 -1
  507. package/dist/remote/relay/convex/component/groups.js +6 -6
  508. package/dist/remote/relay/convex/component/groups.js.map +1 -1
  509. package/dist/remote/relay/convex/component/messages.d.ts +2 -2
  510. package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
  511. package/dist/remote/relay/convex/component/messages.js +90 -83
  512. package/dist/remote/relay/convex/component/messages.js.map +1 -1
  513. package/dist/remote/relay/convex/component/provisioning.d.ts +3 -3
  514. package/dist/remote/relay/convex/component/provisioning.d.ts.map +1 -1
  515. package/dist/remote/relay/convex/component/provisioning.js +17 -16
  516. package/dist/remote/relay/convex/component/provisioning.js.map +1 -1
  517. package/dist/remote/relay/convex/component/runtime.d.ts.map +1 -1
  518. package/dist/remote/relay/convex/component/runtime.js +4 -2
  519. package/dist/remote/relay/convex/component/runtime.js.map +1 -1
  520. package/dist/remote/relay/convex/component/schema.d.ts +2 -2
  521. package/dist/remote/relay/convex/component/schema.js +26 -25
  522. package/dist/remote/relay/convex/component/schema.js.map +1 -1
  523. package/dist/remote/relay/convex/group-server.d.ts +3 -3
  524. package/dist/remote/relay/convex/group-server.js +3 -3
  525. package/dist/remote/relay/convex/relay.d.ts +3 -3
  526. package/dist/remote/relay/convex/relay.d.ts.map +1 -1
  527. package/dist/remote/relay/convex/relay.js +18 -17
  528. package/dist/remote/relay/convex/relay.js.map +1 -1
  529. package/dist/remote/relay/convex/types.d.ts +7 -7
  530. package/dist/remote/relay/convex/types.js +4 -4
  531. package/dist/remote/relay/memory/adapter.js +9 -9
  532. package/dist/remote/relay/memory/adapter.js.map +1 -1
  533. package/dist/remote/relay/types.d.ts +27 -27
  534. package/dist/remote/relay/types.d.ts.map +1 -1
  535. package/dist/safety/fingerprint.d.ts +7 -6
  536. package/dist/safety/fingerprint.d.ts.map +1 -1
  537. package/dist/safety/fingerprint.js +5 -4
  538. package/dist/safety/fingerprint.js.map +1 -1
  539. package/dist/safety/index.d.ts +6 -5
  540. package/dist/safety/index.d.ts.map +1 -1
  541. package/dist/safety/index.js +7 -6
  542. package/dist/safety/index.js.map +1 -1
  543. package/dist/safety/protobuf.js +2 -2
  544. package/dist/safety/protobuf.js.map +1 -1
  545. package/dist/safety/url.d.ts +5 -5
  546. package/dist/safety/url.js +6 -6
  547. package/dist/types/address.d.ts +2 -2
  548. package/dist/types/address.js +2 -2
  549. package/dist/types/api.d.ts +78 -73
  550. package/dist/types/api.d.ts.map +1 -1
  551. package/dist/types/errors.d.ts +63 -403
  552. package/dist/types/errors.d.ts.map +1 -1
  553. package/dist/types/errors.js +62 -537
  554. package/dist/types/errors.js.map +1 -1
  555. package/dist/types/messages.d.ts +16 -16
  556. package/dist/types/messages.d.ts.map +1 -1
  557. package/dist/types/messages.js +7 -7
  558. package/dist/types/messages.js.map +1 -1
  559. package/dist/types/protocol-config.d.ts +52 -49
  560. package/dist/types/protocol-config.d.ts.map +1 -1
  561. package/dist/types/protocol-config.js +36 -34
  562. package/dist/types/protocol-config.js.map +1 -1
  563. package/dist/types/protocol-constants.d.ts +2 -2
  564. package/dist/types/protocol-constants.js +2 -2
  565. package/dist/types/session.d.ts +62 -61
  566. package/dist/types/session.d.ts.map +1 -1
  567. package/dist/types/session.js +13 -14
  568. package/dist/types/session.js.map +1 -1
  569. package/dist/types/trust.d.ts +8 -8
  570. package/dist/types/trust.js +3 -3
  571. package/dist/utils/retry.d.ts +2 -1
  572. package/dist/utils/retry.d.ts.map +1 -1
  573. package/dist/utils/retry.js +4 -5
  574. package/dist/utils/retry.js.map +1 -1
  575. package/docs/ASSURANCE.md +89 -75
  576. package/docs/CLIENT_COMPOSITION.md +22 -15
  577. package/docs/DEVIATIONS.md +507 -425
  578. package/docs/DOCUMENTATION_STANDARDS.md +52 -24
  579. package/docs/E2EE.md +45 -42
  580. package/docs/ERROR_HANDLING.md +107 -152
  581. package/docs/GETTING_STARTED.md +44 -26
  582. package/docs/INTERFACES.md +32 -18
  583. package/docs/PACKAGE_SURFACE.md +24 -21
  584. package/docs/PROTOCOL_POLICY.md +25 -13
  585. package/docs/RECIPES.md +13 -4
  586. package/docs/SECURITY.md +72 -60
  587. package/encoding/README.md +3 -2
  588. package/files/README.md +2 -1
  589. package/groups/README.md +5 -3
  590. package/hooks/README.md +2 -2
  591. package/keys/README.md +17 -14
  592. package/local/store/README.md +84 -67
  593. package/local/store/expo/README.md +19 -12
  594. package/local/store/memory/README.md +6 -3
  595. package/local/store/node/README.md +9 -6
  596. package/local/store/react-native/README.md +16 -12
  597. package/local/store/web/README.md +32 -26
  598. package/local/vault/README.md +5 -4
  599. package/media/README.md +8 -5
  600. package/package.json +4 -2
  601. package/profile/README.md +8 -7
  602. package/remote/README.md +26 -18
  603. package/remote/object-store/README.md +9 -4
  604. package/remote/object-store/convex-r2/README.md +5 -3
  605. package/remote/object-store/s3/README.md +11 -5
  606. package/remote/relay/README.md +2 -0
  607. package/remote/relay/convex/README.md +6 -5
  608. package/remote/relay/convex/component/README.md +154 -124
  609. package/remote/relay/memory/README.md +8 -5
  610. package/safety/README.md +2 -1
  611. package/sealed-sender/README.md +4 -2
  612. package/types/README.md +2 -1
  613. package/username/README.md +1 -0
  614. package/utils/README.md +5 -4
  615. package/zk/README.md +1 -0
package/docs/RECIPES.md CHANGED
@@ -5,7 +5,7 @@
5
5
  > [Client Composition](./CLIENT_COMPOSITION.md) |
6
6
  > [Protocol Policy](./PROTOCOL_POLICY.md)
7
7
 
8
- Working shapes for the operations applications perform most often. Each example
8
+ Working shapes for the tasks applications do most often. Each example
9
9
  uses public exports only.
10
10
 
11
11
  ## Two local clients
@@ -90,11 +90,12 @@ bob decrypted: alice: hello
90
90
 
91
91
  The first message usually uses a `prekey_bundle` envelope because it establishes
92
92
  the session. Later messages on the same session use `ciphertext`. In both cases
93
- the relay sees encrypted envelope bytes; decrypted content is only surfaced to
94
- Bob through the `onMessageDecrypted` hook.
93
+ the relay sees encrypted envelope bytes. Bob receives decrypted content only
94
+ through the `onMessageDecrypted` hook.
95
95
 
96
96
  ## Production composition with Convex + Expo
97
97
 
98
+ <!-- doc-snippet:skip requires-external-context -->
98
99
  ```ts
99
100
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
100
101
  import {
@@ -159,6 +160,7 @@ const bob = await createSignalProtocolClient({
159
160
 
160
161
  ## App message flow
161
162
 
163
+ <!-- doc-snippet:skip requires-external-context -->
162
164
  ```ts
163
165
  const signal = await createSignalProtocolClient({
164
166
  identity: { userId },
@@ -189,6 +191,7 @@ message storage through hooks.
189
191
 
190
192
  ## Protocol policy
191
193
 
194
+ <!-- doc-snippet:skip requires-external-context -->
192
195
  ```ts
193
196
  await createSignalProtocolClient({
194
197
  identity: { userId },
@@ -205,6 +208,7 @@ without post-quantum material fail closed, and PQ sessions use the SDK's
205
208
  ML-KEM Braid SPQR profile. See the [protocol policy](./PROTOCOL_POLICY.md) for
206
209
  supported choices.
207
210
 
211
+ <!-- doc-snippet:skip requires-external-context -->
208
212
  ```ts
209
213
  await createSignalProtocolClient({
210
214
  identity: { userId },
@@ -220,6 +224,7 @@ await createSignalProtocolClient({
220
224
  supports them. It only allows classical compatibility for peers that advertise
221
225
  no post-quantum material at all.
222
226
 
227
+ <!-- doc-snippet:skip requires-external-context -->
223
228
  ```ts
224
229
  await createSignalProtocolClient({
225
230
  identity: { userId },
@@ -237,6 +242,7 @@ PQXDH strictness.
237
242
 
238
243
  ## Multi-device send
239
244
 
245
+ <!-- doc-snippet:skip requires-external-context -->
240
246
  ```ts
241
247
  const result = await signal.send(recipientUserId, "hello");
242
248
  await appMessages.insertOutgoing({
@@ -250,6 +256,7 @@ await appMessages.insertOutgoing({
250
256
 
251
257
  ## Direct device session
252
258
 
259
+ <!-- doc-snippet:skip requires-external-context -->
253
260
  ```ts
254
261
  import { ProtocolAddress } from "@open-e2ee/signal-protocol-sdk";
255
262
 
@@ -260,6 +267,7 @@ await signal.encryptMessage(bob, "linked-device hello");
260
267
 
261
268
  ## Username and ZK helpers
262
269
 
270
+ <!-- doc-snippet:skip requires-external-context -->
263
271
  ```ts
264
272
  import {
265
273
  hashUsername,
@@ -274,6 +282,7 @@ const version = computeProfileKeyVersion(profileKeyBytes, userIdBytes);
274
282
 
275
283
  ## Encrypted attachments
276
284
 
285
+ <!-- doc-snippet:skip requires-external-context -->
277
286
  ```ts
278
287
  import { media } from "@open-e2ee/signal-protocol-sdk";
279
288
 
@@ -389,5 +398,5 @@ await signal.media.cleanup(
389
398
  ```
390
399
 
391
400
  See the [encrypted media guide](../media/README.md) and
392
- [remote object storage](../remote/README.md) for the transfer and object-store
401
+ [remote object store](../remote/README.md) for the transfer and object-store
393
402
  contracts these examples compose.
package/docs/SECURITY.md CHANGED
@@ -28,15 +28,16 @@ compatibility boundary.
28
28
  - The SDK selects SESAME's per-user identity-key model and provisions that tuple
29
29
  unchanged across linked devices. Registration IDs, prekeys, and sessions are
30
30
  device-specific. Generic SESAME still supports both identity-key models.
31
- - Trust storage persists the tuple and trust metadata. Commitments are derived
32
- locally and a redundant supplied commitment must match before mutation.
31
+ - Trust storage persists the tuple and trust metadata. The SDK derives
32
+ commitments locally, and a redundant supplied commitment must match before
33
+ mutation.
33
34
  - First contact is `UNVERIFIED_TOFU`, not authenticated identity.
34
35
  - Replacing either component of a pinned tuple fails closed until rotation is
35
36
  explicitly accepted. A retired tuple cannot silently regain trust.
36
37
  - Authenticated safety-number comparison covers both peers' complete composite
37
38
  tuples and only promotes the exact current tuple to `VERIFIED`.
38
39
 
39
- The Ed25519 component performs ordinary RFC 8032 signatures. It does not
40
+ The Ed25519 component creates ordinary RFC 8032 signatures. It does not
40
41
  implement XEdDSA and cannot consume or produce XEdDSA identity signatures.
41
42
 
42
43
  ### PQXDH and ML-KEM-1024
@@ -46,9 +47,9 @@ implement XEdDSA and cannot consume or produce XEdDSA identity signatures.
46
47
  - Public keys and ciphertexts require exactly `0x0A || raw ML-KEM-1024 bytes`.
47
48
  Untagged values, the deployed Kyber1024 `0x08` tag, unknown tags, and wrong
48
49
  lengths fail before secret derivation or state commit.
49
- - Prekey signatures cover a domain-separated context containing the locally
50
- derived composite identity commitment, algorithm tag, key ID, and complete
51
- tagged public key.
50
+ - Prekey signatures cover a domain-separated context. That context contains the
51
+ locally derived composite identity commitment, algorithm tag, key ID, and
52
+ complete tagged public key.
52
53
  - `protocol.postQuantum: 'compatible'` is an explicit opt-in. It permits a
53
54
  classical session only when a peer advertises no PQ material. Malformed or
54
55
  failed PQ processing does not trigger fallback.
@@ -63,19 +64,20 @@ round-3 Kyber1024 tagged `0x08`.
63
64
  using ML-KEM-768 and bounded Reed-Solomon decoding.
64
65
  - HEK follows the ML-KEM Braid specification:
65
66
  `SHA3-256(ek_seed || ek_vector)`.
66
- - `KDF_OK` is applied once when raw ML-KEM output enters the epoch boundary.
67
- Braid output is already an epoch secret and is not derived a second time.
68
- - Malformed epoch secrets, roots, chain state, chunks, indexes, and wire values
69
- are validated before live-state commit.
67
+ - The SDK applies `KDF_OK` once when raw ML-KEM output enters the epoch
68
+ boundary. Braid output is already an epoch secret and is not derived a second
69
+ time.
70
+ - The SDK rejects malformed epoch secrets, roots, chain state, chunks, indexes,
71
+ and wire values before it commits live state.
70
72
  - Direct ML-KEM-768 SCKA remains an explicit SDK mode for product-reviewed
71
- constraints; it is not the default.
73
+ constraints. It is not the default.
72
74
 
73
75
  ## Forward and Post-Compromise Security
74
76
 
75
77
  The Double Ratchet derives a new message key for each chain step and advances
76
- chain state after successful use. Skipped receive keys are bounded and removed
77
- when consumed or expired. Fresh DH ratchet inputs provide break-in recovery once
78
- an uncompromised ratchet step is completed. SPQR adds periodic post-quantum
78
+ chain state after successful use. The SDK bounds skipped receive keys, and
79
+ removes each one after use or expiry. Fresh DH ratchet inputs provide break-in
80
+ recovery once an uncompromised ratchet step completes. SPQR adds post-quantum
79
81
  epoch material to the Triple Ratchet hybrid derivation.
80
82
 
81
83
  These properties depend on authenticated session establishment, uncompromised
@@ -86,7 +88,7 @@ source.
86
88
 
87
89
  Best-effort typed-array overwrites reduce the lifetime of some owned temporary
88
90
  buffers. They do not make old secrets physically unrecoverable from JavaScript
89
- memory; copies, strings, engine internals, CPU registers, and garbage-collected
91
+ memory. Copies, strings, engine internals, CPU registers, and garbage-collected
90
92
  heap pages remain outside the SDK's control.
91
93
 
92
94
  ## JavaScript Timing Boundary
@@ -95,10 +97,10 @@ Browser, Node, and Expo/React Native JavaScript engines provide no machine-level
95
97
  constant-time contract. The implementation uses best-effort source patterns on
96
98
  selected paths:
97
99
 
98
- - full-scan comparison for equal-length MACs and identity bytes;
99
- - fixed-work derivation of both decapsulation candidates before masked
100
- selection;
101
- - equal-work rejection padding on selected replay and authentication paths;
100
+ - full-scan comparison for equal-length MACs and identity bytes.
101
+ - fixed work on both decapsulation candidates, then a masked choice between
102
+ them.
103
+ - equal-work rejection padding on selected replay and authentication paths.
102
104
  - fixed-work rejection handling on selected authentication paths.
103
105
 
104
106
  These patterns do not prove timing equivalence. Secret-influenced remainder and
@@ -112,41 +114,50 @@ high-assurance co-resident timing adversary.
112
114
  `secureZeroBytes()` and related cleanup calls overwrite only the exact mutable
113
115
  typed array owned by the caller. They cannot guarantee erasure of:
114
116
 
115
- - earlier or implicit copies;
116
- - immutable Base64 or UTF-8 strings;
117
- - engine temporaries, registers, JIT artifacts, or garbage-collected pages;
117
+ - earlier or implicit copies.
118
+ - immutable Base64 or UTF-8 strings.
119
+ - engine temporaries, registers, JIT artifacts, or garbage-collected pages.
118
120
  - persisted copies held by an adapter or operating system.
119
121
 
120
- Applications should keep long-lived private material in the strongest
121
- platform-backed storage available, minimize plaintext/key lifetimes, avoid
122
- logging secrets, and treat a compromised JavaScript runtime as a key
123
- compromise. A qualified native/WASM/Rust/Swift backend is roadmap work when
124
- stronger timing or erasure assurance is required.
122
+ Applications should:
123
+
124
+ - keep long-lived private material in the strongest platform-backed storage
125
+ available.
126
+ - minimize plaintext/key lifetimes.
127
+ - avoid logging secrets.
128
+ - treat a compromised JavaScript runtime as a key compromise.
129
+
130
+ A qualified native/WASM/Rust/Swift backend is roadmap work when a deployment
131
+ requires stronger timing or erasure assurance.
125
132
 
126
133
  ## Storage Boundary
127
134
 
128
135
  Local adapters own identity keys, contact trust metadata, prekeys, session
129
136
  records, retry records, and group state. The package requires:
130
137
 
131
- - atomic composite-identity writes and explicit rotation acceptance;
132
- - current session-record format version 4;
133
- - rejection of stale-format writes before replacing current state;
134
- - removal or rejection of stale persisted session records on read;
135
- - no authoritative cached identity commitment;
138
+ - atomic composite-identity writes and explicit rotation acceptance.
139
+ - current session-record format version 4.
140
+ - that an adapter reject stale-format writes before it replaces current state.
141
+ - that an adapter remove or reject stale persisted session records on read.
142
+ - no authoritative cached identity commitment.
136
143
  - authenticated encryption for adapters that persist encrypted records.
137
144
 
138
- Adapter encryption does not compensate for XSS, malicious dependencies,
139
- compromised application code, a stolen unlocked device, or an attacker who also
140
- obtains the adapter encryption key. Browser IndexedDB and caller-provided React
141
- Native storage inherit their host application's security boundary.
145
+ Adapter encryption does not compensate for:
146
+
147
+ - XSS, malicious dependencies, or compromised application code.
148
+ - a stolen unlocked device.
149
+ - an attacker who also holds the adapter encryption key.
150
+
151
+ Browser IndexedDB and caller-provided React Native storage inherit their host
152
+ application's security boundary.
142
153
 
143
154
  Group sender key state never leaves the device. A sender key record holds the
144
- chain key every message key on that chain derives from and the sender's private
145
- signature key; together they are enough to read a sender's group messages and to
146
- forge new ones, so no adapter transmits them and no relay contract accepts them.
147
- The same rule covers the message keys held for out-of-order group messages.
148
- Local adapters bound that skipped-key store so a peer cannot grow it without
149
- limit by skipping ever further ahead.
155
+ chain key that every message key on that chain derives from, and the sender's
156
+ private signature key. Together they are enough to read a sender's group
157
+ messages and to forge new ones. No adapter transmits them, and no relay
158
+ contract accepts them. The same rule covers the message keys held for
159
+ out-of-order group messages. Local adapters bound that skipped-key store so a
160
+ peer cannot grow it without limit by skipping ever further ahead.
150
161
 
151
162
  Relay and remote object-store adapters receive public key material, routing
152
163
  metadata, and opaque ciphertext required by their contracts. TLS,
@@ -154,11 +165,12 @@ authorization, abuse controls, atomic prekey consumption, and access logging
154
165
  remain deployment responsibilities. The relay is not an identity trust anchor.
155
166
 
156
167
  Remote object-store upload requests use a retry identifier, not a storage key.
157
- Applications must scope that identifier to the authenticated principal and own
158
- the durable mapping from it to a canonical object identifier and a private
159
- provider key. Applications must also enforce object access, upload size, and
160
- encrypted-object content type on the backend. Presigned URLs are short-lived
161
- bearer credentials and must not be logged or exposed beyond the authorized
168
+ Applications must scope that identifier to the authenticated principal. They
169
+ must also own the durable mapping from it to a canonical object identifier and
170
+ a private provider key. Applications must also enforce object access, upload
171
+ size, and encrypted-object content type on the backend. Presigned URLs are
172
+ short-lived
173
+ bearer credentials. Never log one, and never expose one beyond the authorized
162
174
  operation.
163
175
 
164
176
  ## Resource and DoS Controls
@@ -170,7 +182,7 @@ chunk indexes, shard counts, and allocation before decoding. Retry processing
170
182
  limits attempts and requires an existing sent-message record unless a narrowly
171
183
  scoped lifecycle path explicitly bypasses message validation.
172
184
 
173
- These controls reduce amplification and unbounded allocation; they do not
185
+ These controls reduce amplification and unbounded allocation. They do not
174
186
  replace application-level request size limits, rate limiting, authentication,
175
187
  or transport abuse prevention.
176
188
 
@@ -178,25 +190,25 @@ or transport abuse prevention.
178
190
 
179
191
  In scope:
180
192
 
181
- - passive network observation;
182
- - active message tampering, replay, reordering, duplication, and truncation;
183
- - malicious or stale relay responses within the adapter contract;
184
- - identity component substitution after trust is pinned;
193
+ - passive network observation.
194
+ - active message tampering, replay, reordering, duplication, and truncation.
195
+ - malicious or stale relay responses within the adapter contract.
196
+ - identity component substitution after the SDK pins trust.
185
197
  - malformed prekeys, KEM keys/ciphertexts, protocol messages, restored state,
186
- Braid traces, and Reed-Solomon chunks;
187
- - loss and out-of-order delivery within configured protocol bounds;
198
+ Braid traces, and Reed-Solomon chunks.
199
+ - loss and out-of-order delivery within configured protocol bounds.
188
200
  - later compromise followed by an uncompromised ratchet recovery step.
189
201
 
190
202
  Out of scope or only partially mitigated:
191
203
 
192
- - compromised endpoints, JavaScript engines, dependencies, or build pipeline;
193
- - hostile same-process code and high-assurance local timing attackers;
194
- - guaranteed secret erasure from managed memory;
195
- - hardware, physical, speculative-execution, and microarchitectural attacks;
204
+ - compromised endpoints, JavaScript engines, dependencies, or build pipeline.
205
+ - hostile same-process code and high-assurance local timing attackers.
206
+ - guaranteed secret erasure from managed memory.
207
+ - hardware, physical, speculative-execution, and microarchitectural attacks.
196
208
  - traffic-analysis resistance beyond the metadata/padding behavior explicitly
197
- implemented;
209
+ implemented.
198
210
  - Signal Messenger interoperability outside the exact
199
- alignments stated in this security model;
211
+ alignments stated in this security model.
200
212
  - recovery of authenticity on unauthenticated first contact without an
201
213
  authenticated safety-number or configured trust mechanism.
202
214
 
@@ -11,6 +11,7 @@ modules or silently mixing standard and URL-safe Base64.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import {
16
17
  bytesToBase64,
@@ -26,7 +27,7 @@ const urlToken = bytesToUrlSafeBase64(bytes);
26
27
  const roundTrip = hexToBytes(bytesToHex(bytes));
27
28
  ```
28
29
 
29
- Treat encoded cryptographic values as opaque. Encoding changes representation;
30
- it does not encrypt, authenticate, or validate the meaning of the bytes.
30
+ Treat encoded cryptographic values as opaque. Encoding changes representation. It
31
+ does not encrypt, authenticate, or validate the meaning of the bytes.
31
32
 
32
33
  See the [API reference](../docs/api/namespaces/encoding/README.md).
package/files/README.md CHANGED
@@ -5,12 +5,13 @@ files and attachments.
5
5
 
6
6
  ## Why it exists
7
7
 
8
- Large payloads should not be embedded directly in Signal Protocol messages.
8
+ Do not embed large payloads directly in Signal Protocol messages.
9
9
  The application encrypts bytes locally, uploads only ciphertext, and sends the
10
10
  decryption key plus integrity metadata inside an end-to-end encrypted message.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import {
16
17
  streamingDecrypt,
package/groups/README.md CHANGED
@@ -13,6 +13,7 @@ and sender-key rotation.
13
13
 
14
14
  ## Usage
15
15
 
16
+ <!-- doc-snippet:skip requires-external-context -->
16
17
  ```ts
17
18
  import {
18
19
  GroupManager,
@@ -42,11 +43,12 @@ The server must enforce authenticated access and version sequencing without
42
43
  receiving plaintext group attributes or group master keys. Membership removal
43
44
  must also invalidate or rotate group messaging state through the callbacks
44
45
  required by `GroupManagerOptions`. Every `getGroup()` response must include a
45
- baseline signature over the group ID, version, and exact encrypted-state bytes;
46
- the client verifies it before installing a first or post-revocation baseline.
46
+ baseline signature over the group ID, version, and exact encrypted-state bytes.
47
+ The client verifies that signature before installing a first or post-revocation
48
+ baseline.
47
49
 
48
50
  Deployments whose server does not yet sign group changes must opt in explicitly
49
- with `allowUnauthenticatedGroupHistory: true`; the SDK emits a security warning
51
+ with `allowUnauthenticatedGroupHistory: true`. The SDK emits a security warning
50
52
  because that mode has no authenticated group history.
51
53
 
52
54
  See the [API reference](../docs/api/README.md) and
package/hooks/README.md CHANGED
@@ -7,8 +7,8 @@ and single-flight helpers.
7
7
  ## Why it exists
8
8
 
9
9
  The core SDK is framework-neutral. React hooks live on a separate package
10
- subpath so non-React consumers do not load React and UI code can subscribe to
11
- SDK state without duplicating effect cleanup.
10
+ subpath. Non-React consumers therefore do not load React, and UI code can
11
+ subscribe to SDK state without duplicating effect cleanup.
12
12
 
13
13
  ## Usage
14
14
 
package/keys/README.md CHANGED
@@ -13,6 +13,7 @@ prevents storage and relay adapters from inventing incompatible key shapes.
13
13
 
14
14
  ## Usage
15
15
 
16
+ <!-- doc-snippet:skip requires-external-context -->
16
17
  ```ts
17
18
  import {
18
19
  createCompositeIdentityV1,
@@ -28,13 +29,14 @@ const signedPreKey = await generateEcSignedPreKey(identity);
28
29
  ```
29
30
 
30
31
  Ordinary application code usually lets `SignalProtocolClient` generate and
31
- persist this material. Direct key APIs are intended for adapter, provisioning,
32
- and advanced lifecycle integrations.
32
+ persist this material. Direct key APIs serve adapter, provisioning, and
33
+ advanced lifecycle integrations.
33
34
 
34
35
  ## Composite identity
35
36
 
36
37
  `CompositeIdentityV1` is the canonical public trust object:
37
38
 
39
+ <!-- doc-snippet:skip requires-external-context -->
38
40
  ```ts
39
41
  interface CompositeIdentityV1 {
40
42
  readonly version: 1;
@@ -47,7 +49,7 @@ The SDK provisions one tuple per `(userId, identityType)` across linked devices.
47
49
  ACI and PNI are independent identity types. Device registration IDs, prekeys,
48
50
  and sessions remain device-specific.
49
51
 
50
- The tuple is encoded as exactly 67 bytes:
52
+ The tuple encodes to exactly 67 bytes:
51
53
 
52
54
  ```text
53
55
  0x01 || 0x01 || X25519 public key || 0x02 || Ed25519 public key
@@ -72,7 +74,7 @@ not make this profile interoperable with XEdDSA identity signatures.
72
74
  ML-KEM-1024 public keys use the mandatory `0x0A || raw` representation: one tag
73
75
  byte plus 1,568 raw bytes. The corresponding serialized ciphertext has the same
74
76
  1,569-byte size. A value with the deployed round-3 Kyber1024 `0x08` tag is a
75
- different profile and is rejected.
77
+ different profile, and the SDK rejects it.
76
78
 
77
79
  Prekey signatures cover a domain-separated context, not only the raw key:
78
80
 
@@ -91,11 +93,12 @@ For ML-KEM-1024, `serialized public key` includes the `0x0A` tag.
91
93
  `PreKeyBundle` carries one composite identity and the device-specific material
92
94
  needed for X3DH/PQXDH session establishment:
93
95
 
94
- - registration ID and device ID;
95
- - composite identity tuple;
96
- - required signed EC prekey;
97
- - optional EC one-time prekey; and
98
- - either a one-time or last-resort signed ML-KEM-1024 prekey when PQXDH is used.
96
+ - registration ID and device ID.
97
+ - composite identity tuple.
98
+ - required signed EC prekey.
99
+ - optional EC one-time prekey.
100
+ - either a one-time or last-resort signed ML-KEM-1024 prekey when the session
101
+ uses PQXDH.
99
102
 
100
103
  Relay and storage adapters carry the same canonical tuple. Consumers must reject
101
104
  an identity mismatch before consuming a one-time prekey or committing a session.
@@ -103,11 +106,11 @@ an identity mismatch before consuming a one-time prekey or committing a session.
103
106
  ## Secret ownership
104
107
 
105
108
  Private keys are Base64 strings in the current public types and therefore cannot
106
- be reliably erased by the SDK. Temporary mutable byte arrays owned by generation
107
- or crypto functions are overwritten after use where practical, but JavaScript
108
- does not guarantee physical zeroization, freedom from copies, or hard
109
- constant-time execution. Long-lived keys should be held by the strongest
110
- platform-backed storage available to the application.
109
+ be reliably erased by the SDK. Generation and crypto functions overwrite their
110
+ temporary mutable byte arrays after use, where practical. JavaScript still does
111
+ not guarantee physical zeroization, freedom from copies, or hard constant-time
112
+ execution. The strongest platform-backed storage available to the application
113
+ should hold long-lived keys.
111
114
 
112
115
  ## Module boundaries
113
116