@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/ADAPTERS.md CHANGED
@@ -41,7 +41,7 @@ Use:
41
41
  - `InMemorySignalProtocolStore` from `@open-e2ee/signal-protocol-sdk/local/store/memory`
42
42
  - or a custom implementation
43
43
 
44
- ### Remote object storage: `SignalProtocolRemoteObjectStore`
44
+ ### Remote object store: `SignalProtocolRemoteObjectStore`
45
45
 
46
46
  Optional encrypted file upload/download support for two-layer attachment encryption.
47
47
 
@@ -54,10 +54,10 @@ Use:
54
54
  - or a custom implementation
55
55
 
56
56
  Both concrete adapters call an authenticated application-backend broker. The
57
- app runtime receives only narrowly scoped, short-lived operations; provider
57
+ app runtime receives only narrowly scoped, short-lived operations. Provider
58
58
  credentials remain on the backend.
59
59
 
60
- Upload requests carry a retry/idempotency `requestId`; the backend returns the
60
+ Upload requests carry a retry/idempotency `requestId`. The backend returns the
61
61
  canonical `objectId` used in encrypted attachment pointers. Provider keys stay
62
62
  private to the backend. The Convex server helper can supply generic validators,
63
63
  R2 calls, expiry parsing, and metadata verification, while app-owned internal
@@ -67,7 +67,9 @@ functions retain authentication, authorization, and persistence.
67
67
 
68
68
  ### Minimal local client
69
69
 
70
+ <!-- doc-snippet:run adapters-local-client expect="" -->
70
71
  ```ts
72
+ // Real protocol and cryptography; simulated in-memory infrastructure.
71
73
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
72
74
  import { inMemoryStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
73
75
 
@@ -79,6 +81,7 @@ const signal = await createSignalProtocolClient({
79
81
 
80
82
  ### Production client
81
83
 
84
+ <!-- doc-snippet:skip requires-production-adapters -->
82
85
  ```ts
83
86
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
84
87
  import {
@@ -110,7 +113,9 @@ database and SQLCipher bootstrap.
110
113
 
111
114
  ### Local development with a shared relay
112
115
 
116
+ <!-- doc-snippet:run adapters-shared-relay expect="" -->
113
117
  ```ts
118
+ // Real protocol and cryptography; simulated in-memory infrastructure.
114
119
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
115
120
  import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
116
121
  import { inMemoryStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
@@ -142,7 +147,7 @@ const bob = await createSignalProtocolClient({
142
147
  - Protect local key material at rest.
143
148
  - Keep contact identity trust decisions stable and explicit.
144
149
  - Persist linked-device identity state atomically enough that startup verification cannot enter a half-linked state.
145
- - Preserve session record semantics; do not treat sessions as opaque blobs without honoring update and archive behavior.
150
+ - Preserve session record semantics. Do not treat sessions as opaque blobs without honoring update and archive behavior.
146
151
 
147
152
  ## Choosing a Shape
148
153
 
@@ -160,6 +165,7 @@ Prefer these composition patterns:
160
165
 
161
166
  Use the public interfaces:
162
167
 
168
+ <!-- doc-snippet:skip requires-external-context -->
163
169
  ```ts
164
170
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
165
171
  import type { ISignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/relay";
@@ -169,6 +175,7 @@ import type { ISignalProtocolLocalStore } from "@open-e2ee/signal-protocol-sdk/l
169
175
 
170
176
  Then compose them through `createSignalProtocolClient()`:
171
177
 
178
+ <!-- doc-snippet:skip requires-external-context -->
172
179
  ```ts
173
180
  const signal = await createSignalProtocolClient({
174
181
  identity: { userId },
package/ARCHITECTURE.md CHANGED
@@ -6,8 +6,9 @@
6
6
  versioned profile based on selected public Signal Protocol specifications. It
7
7
  owns client-side encryption, local protocol state, prekey lifecycle,
8
8
  multi-device session orchestration, group sender keys, sealed sender,
9
- profile/username helpers, and explicit local/remote adapter seams. Public
10
- security guarantees and protocol policy are documented in
9
+ profile/username helpers, and explicit local/remote adapter seams.
10
+
11
+ For public security guarantees and protocol policy, see
11
12
  [Security](./docs/SECURITY.md) and
12
13
  [Protocol Policy](./docs/PROTOCOL_POLICY.md).
13
14
 
@@ -22,9 +23,9 @@ compatibility shim when a boundary is wrong.
22
23
 
23
24
  - Crypto and protocol internals must be auditable from current code, not historical layout names.
24
25
  - Public APIs should be narrow and explicit. Platform and backend adapters live on subpaths.
25
- - Runtime dependencies point inward toward lower protocol layers. Type-only imports are allowed where they describe ports or public contracts.
26
+ - Runtime dependencies point inward toward lower protocol layers. The rule allows type-only imports where they describe ports or public contracts.
26
27
  - Shared protocol strategy, reference-aligned limits, and HKDF info strings belong in `types/protocol-config.ts`, not in the client layer.
27
- - Session record resolution belongs to `internal/session/session-resolver.ts`; SESAME orchestrates it but does not own the shared active/archive helper.
28
+ - Session record resolution belongs to `internal/session/session-resolver.ts`. SESAME orchestrates it but does not own the shared active/archive helper.
28
29
 
29
30
  ## Package Shape
30
31
 
@@ -55,6 +56,7 @@ modify the code.
55
56
 
56
57
  The root package is core-only:
57
58
 
59
+ <!-- doc-snippet:skip requires-external-context -->
58
60
  ```ts
59
61
  import {
60
62
  SignalProtocolClient,
@@ -96,7 +98,7 @@ The executable layer map lives in [layers.ts](./layers.ts).
96
98
  | 5 | Domain/Keys | `keys/` | Key types and generation |
97
99
  | 6 | Domain/Crypto | `internal/crypto/` | Cryptographic primitives and low-level KDF/encryption helpers |
98
100
 
99
- Runtime imports must point inward, toward equal or higher layer numbers. For example, Layer 3 may import Layer 4, 5, or 6; Layer 4 must not import Layer 3.
101
+ Runtime imports must point inward, toward equal or higher layer numbers. For example, Layer 3 may import Layer 4, 5, or 6. Layer 4 must not import Layer 3.
100
102
 
101
103
  Shared non-layer modules:
102
104
 
@@ -151,6 +153,7 @@ This boundary prevents lower protocol/session layers from depending on the clien
151
153
 
152
154
  Application code should prefer:
153
155
 
156
+ <!-- doc-snippet:skip requires-external-context -->
154
157
  ```ts
155
158
  await createSignalProtocolClient({
156
159
  identity: { userId },
@@ -159,22 +162,22 @@ await createSignalProtocolClient({
159
162
  ```
160
163
 
161
164
  Strict post-quantum sessions and ML-KEM Braid are the defaults, so application
162
- code should leave `protocol` unset unless the product has made an explicit
165
+ code should leave `protocol` unset unless the product made an explicit
163
166
  compatibility decision. Advanced strategy fields remain available for
164
- diagnostics, telemetry, and algorithm tuning, but compatibility fallback is selected
165
- through `protocol.postQuantum: 'compatible'`, and direct SPQR is selected
166
- through `protocol.braid: 'disabled'`.
167
+ diagnostics, telemetry, and algorithm tuning. To choose compatibility fallback,
168
+ set `protocol.postQuantum: 'compatible'`. To choose direct SPQR, set
169
+ `protocol.braid: 'disabled'`.
167
170
 
168
- Two strategy hooks report protocol events. `onProtocolSelected` fires once per
169
- session establishment, from the handshake. `onBraidProgress` fires on every
170
- braid-mode send and receive, from the SPQR seam that holds the braid state; the
171
- manager carries the strategy into `SessionCipher`, which passes it to `spqrSend`
172
- and `spqrRecv`. Both hooks are guarded, so a consumer that throws cannot break
173
- the protocol path.
171
+ Two strategy hooks report protocol events. The hook `onProtocolSelected` fires
172
+ once per session establishment, from the handshake. The hook `onBraidProgress`
173
+ fires on every braid-mode send and receive, from the SPQR seam that holds the
174
+ braid state. The manager carries the strategy into `SessionCipher`, which passes
175
+ it to `spqrSend` and `spqrRecv`. The SDK guards both hooks, so a consumer that
176
+ throws cannot break the protocol path.
174
177
 
175
178
  ## Session Resolution
176
179
 
177
- Session convergence is a SESAME behavior, but active/archive record manipulation is shared session-domain logic.
180
+ Session convergence is a SESAME behavior, but active/archive record manipulation belongs to shared session-domain logic.
178
181
 
179
182
  - Owner: [internal/session/session-resolver.ts](./internal/session/session-resolver.ts)
180
183
  - Consumed by: [internal/session/cipher.ts](./internal/session/cipher.ts) and [internal/sesame/manager.ts](./internal/sesame/manager.ts)
package/CHANGELOG.md CHANGED
@@ -1,5 +1,77 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.4.0
4
+
5
+ - **The README now provides a runnable encrypted round trip and a current demo.**
6
+ The quickstart exercises two SDK clients through the in-memory relay. The new
7
+ recording shows the same two-device and relay flow as the live desktop and
8
+ mobile demo.
9
+
10
+ - **Error-surface checks reject unresolved codes and cover media attachment
11
+ codes.** The analyser now reports forwarded code arguments in CI.
12
+ It also checks every `MediaAttachmentErrorCode` value.
13
+ This release removes `RemoteObjectStoreNotConfigured` because no media
14
+ operation could produce it.
15
+
16
+ - **The retry-request wire surface no longer includes
17
+ `RetryReason.INVALID_MESSAGE`.** No local failure produced it. The incoming
18
+ retry handler did not support it. Malformed ciphertext failures use the supported
19
+ `DECRYPTION_FAILED` recovery path.
20
+
21
+ - **Generated API pages and shipped documentation examples now have source
22
+ gates.** CI regenerates `docs/api` with pinned tool versions. It rejects a
23
+ diff. The snippet runner scans every packaged Markdown file and the internal
24
+ lifecycle docs. It executes every complete example and matches its output.
25
+ For an example that cannot run, it compiles every SDK name against the packed
26
+ package. A renamed or deleted export therefore fails the build in every
27
+ document that names it.
28
+
29
+ An example that previews an unreleased API declares the import paths that do
30
+ not exist yet. The build fails if one of them resolves. Only pseudocode is
31
+ exempt, and the build names each exempt block on its own line.
32
+
33
+ - **The error guide now documents all 33 `EncryptionErrorCode` values.** Its
34
+ session examples also use the current `ProtocolAddress` method signatures.
35
+
36
+ ## 0.3.0
37
+
38
+ - **Breaking: seven error classes and sixteen `EncryptionErrorCode` members are
39
+ removed, because nothing in the library ever threw them.** Each class was
40
+ exported and paired with a type guard, so an application could branch on it —
41
+ but no code path constructed any of them, which made every one of those
42
+ branches dead code that read as handled. Removed, with their `is*` guards:
43
+ `IdentityKeyChangedError`, `SessionConflictError`,
44
+ `RegistrationIdChangedError`, and the four intermediate classes
45
+ `CryptoError`, `SessionError`, `ProtocolError` and `ClientError`. Removed
46
+ codes: `IDENTITY_KEY_CHANGED`, `IDENTITY_KEY_ERROR`, `SESSION_CONFLICT`,
47
+ `REGISTRATION_ID_CHANGED`, `INVALID_REGISTRATION_ID`, `MESSAGE_TOO_OLD`,
48
+ `INVALID_MESSAGE_VERSION`, `RATCHET_ERROR`, `DATABASE_ERROR`,
49
+ `DATABASE_LOCKED`, `KYBER_ERROR`, `KDF_ERROR`, `HMAC_VERIFICATION_FAILED`,
50
+ `SPQR_KEY_ALREADY_USED`, `SPQR_EPOCH_REGRESSION` and `UNKNOWN_ERROR`. The
51
+ enum goes from 49 members to 33.
52
+
53
+ What to use instead: an identity that changed is an identity that is not
54
+ trusted, and the library throws `UntrustedIdentityError` /
55
+ `UNTRUSTED_IDENTITY` for it from five sites on the session and sending
56
+ paths. Code branching on `isIdentityKeyChangedError` or on
57
+ `IDENTITY_KEY_CHANGED` was never reached and should branch on
58
+ `isUntrustedIdentityError` instead. The other removed names have no
59
+ replacement, because there was no event behind them.
60
+
61
+ - **`UntrustedIdentityError` and `isUntrustedIdentityError` are exported from
62
+ the package root.** They were reachable only from
63
+ `@open-e2ee/signal-protocol-sdk/types/errors`, while the error-handling guide
64
+ imported them from the root — so the first thing a reader copied did not
65
+ resolve. `StorageQuotaExceededError` also gains the
66
+ `isStorageQuotaExceededError` guard its five siblings already had.
67
+
68
+ - **Every documented error code is now traceable to a construction site.** A
69
+ check parses the library for the sites that decide whether a class can be
70
+ thrown, and fails the build when an exported error class or a declared code
71
+ survives with none — so the surface cannot drift back. Being named in a
72
+ `switch` counted as use before, which is what hid `IDENTITY_KEY_CHANGED`
73
+ through all nineteen releases that declared it and never threw it.
74
+
3
75
  ## 0.2.3
4
76
 
5
77
  - **`@noble/post-quantum` 0.6.1 → 0.7.0.** Upstream hardening of the
package/COMMERCIAL.md CHANGED
@@ -6,24 +6,24 @@ commercial path; the open-source path is the
6
6
 
7
7
  ## Do you need a commercial license?
8
8
 
9
- You do **not** need one if your application complies with the AGPL — including
9
+ You do **not** need one if your application complies with AGPLv3 — including
10
10
  its network-use provision (section 13): users who interact with your service
11
11
  over a network must be able to obtain the complete corresponding source of your
12
- application under the AGPL.
12
+ application under AGPLv3.
13
13
 
14
14
  You likely **do** need one if any of these describe your product:
15
15
 
16
16
  - Closed-source or proprietary application, mobile or web, that ships or serves
17
17
  this SDK.
18
- - You cannot offer your application's source under AGPL terms — for
18
+ - You cannot offer your application's source under AGPLv3 terms — for
19
19
  contractual, competitive, or policy reasons.
20
20
  - You are embedding the SDK in a product you redistribute to customers who
21
- will not receive AGPL source (OEM).
21
+ will not receive AGPLv3 source (OEM).
22
22
 
23
23
  ## What the commercial license changes
24
24
 
25
25
  - **Grant.** The right to use, modify, and distribute the SDK in a proprietary
26
- product, without the AGPL's source-provision obligations.
26
+ product, without the AGPLv3 source-provision obligations.
27
27
  - **Scope.** Licensed per product, covering `@open-e2ee/signal-protocol-sdk`
28
28
  and its subpath adapters as named in your license record.
29
29
  - **Support.** Any support terms are those stated in your order form; nothing
@@ -51,6 +51,6 @@ Growth and Enterprise start with an email.
51
51
 
52
52
  ## Evaluation
53
53
 
54
- Evaluate under the AGPL first — the full SDK, not a trial build. Nothing about
54
+ Evaluate under AGPLv3 first — the full SDK, not a trial build. Nothing about
55
55
  evaluation, prototyping, or internal proof-of-concept work requires a
56
56
  commercial license before you ship to users.
package/NOTICE CHANGED
@@ -25,5 +25,5 @@ This software is provided as is, without warranty, and is subject to the
25
25
  limitation of liability in the LICENSE file. This notice does not modify the
26
26
  license.
27
27
 
28
- For commercial licensing options that do not require AGPL compliance, contact
28
+ For commercial licensing options that do not require AGPLv3 compliance, contact
29
29
  licensing@open-e2ee.dev.
package/README.md CHANGED
@@ -1,64 +1,50 @@
1
- <img src="https://raw.githubusercontent.com/open-e2ee/design/v0.2.2/brand/generated/open-e2ee-mark-adaptive.svg" alt="OpenE2EE" width="72" height="72">
1
+ <img src="https://raw.githubusercontent.com/open-e2ee/design/v0.8.0/brand/generated/open-e2ee-mark-adaptive.svg" alt="OpenE2EE" width="72" height="72">
2
2
 
3
3
  # OpenE2EE Signal Protocol SDK
4
4
 
5
5
  **End-to-end encrypted messaging for TypeScript apps. Signal Protocol, post-quantum by default, runs in Expo.**
6
6
 
7
7
  [![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-2f6f5e)](https://github.com/open-e2ee/signal-protocol-js/blob/main/LICENSE)
8
- [![Types: TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6)](https://www.typescriptlang.org/)
9
8
  [![npm version](https://img.shields.io/npm/v/@open-e2ee/signal-protocol-sdk)](https://www.npmjs.com/package/@open-e2ee/signal-protocol-sdk)
10
- [![native modules: 0](https://img.shields.io/badge/native_modules-0-2f6f5e)](https://github.com/open-e2ee/signal-protocol-js/blob/main/ARCHITECTURE.md)
9
+ [![native crypto: 0](https://img.shields.io/badge/native_crypto-0-2f6f5e)](./ARCHITECTURE.md)
11
10
  [![npm provenance](https://img.shields.io/badge/npm-provenance-2f6f5e)](https://www.npmjs.com/package/@open-e2ee/signal-protocol-sdk#provenance)
12
11
  [![Checks](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml/badge.svg)](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml)
13
- [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/open-e2ee/signal-protocol-js/badge)](https://scorecard.dev/viewer/?uri=github.com/open-e2ee/signal-protocol-js)
14
- [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14043/badge)](https://www.bestpractices.dev/projects/14043)
15
12
 
16
13
  [Website](https://open-e2ee.dev) ·
17
- [Docs](https://docs.open-e2ee.dev) ·
18
- [Quick Start](#quick-start) ·
19
- [Architecture](https://github.com/open-e2ee/signal-protocol-js/blob/main/ARCHITECTURE.md) ·
20
- [Security Model](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/SECURITY.md) ·
21
- [Protocol Policy](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/PROTOCOL_POLICY.md) ·
22
- [Deviations](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md)
14
+ [Documentation](https://docs.open-e2ee.dev) ·
15
+ [Live demo](https://open-e2ee.dev/#demo) ·
16
+ [API reference](https://docs.open-e2ee.dev/reference/api) ·
17
+ [Security](./SECURITY.md)
23
18
 
24
- ---
19
+ - **One TypeScript package.** Run the same protocol code in Expo, React Native, modern browsers, and Node.
20
+ - **Post-quantum by default.** The default policy requires PQXDH session establishment and the ML-KEM Braid post-quantum ratchet. Required post-quantum operations fail closed.
21
+ - **Messaging primitives included.** Build multi-device messaging, groups, sealed sender, encrypted attachments, and safety-number verification.
22
+ - **Your infrastructure, behind explicit interfaces.** Your application owns device-local storage. The relay is an interface, not a hosted service. The relay never needs message plaintext or device private keys.
23
+ - **AGPLv3, or a commercial license.** Proprietary applications that cannot meet AGPLv3 obligations can use a [commercial license](./COMMERCIAL.md).
25
24
 
26
- - **Pure TypeScript.** No native modules, no prebuild step, no platform binaries to ship.
27
- - **Runs where your app runs.** Expo, React Native, modern browsers, and Node from one package.
28
- - **Post-quantum by default.** PQXDH and ML-KEM session establishment are on without configuration, and fail closed.
29
- - **Real messaging features.** Multi-device, groups, sealed sender, encrypted attachments, safety numbers.
30
- - **Pluggable storage and relay.** Device-local storage is required and yours; the relay is an interface, not a hosted service.
31
- - **AGPL-3.0-or-later, or a commercial license.** Building something closed-source? See [COMMERCIAL](https://github.com/open-e2ee/signal-protocol-js/blob/main/COMMERCIAL.md).
25
+ The protocol code ships without a native crypto module or platform crypto binary. The Expo SQLCipher store requires a development build and native project configuration.
32
26
 
33
- *Not affiliated with Signal Messenger.* This is an independent implementation of the public Signal Protocol specifications — full notice in [NOTICE](https://github.com/open-e2ee/signal-protocol-js/blob/main/NOTICE). It is **not wire-compatible with Signal Messenger or libsignal**: messages, identities, and safety numbers do not interoperate, and every deliberate difference is documented in [DEVIATIONS](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md).
27
+ Version `0.4.x`. Public APIs and persisted formats can change before `1.0`.
34
28
 
35
- `0.1.x` — public APIs and persisted formats may change before `1.0`.
29
+ OpenE2EE implements a versioned profile of the published Signal Protocol specifications. It is not affiliated with Signal Messenger and is **not wire-compatible with Signal Messenger or libsignal**. Messages, identities, and safety numbers do not interoperate. Read the [full notice](./NOTICE) and [documented deviations](./docs/DEVIATIONS.md).
36
30
 
37
- ## See it run
31
+ ## See an encrypted round trip
38
32
 
39
- [![Linking a second device on the demo page: the scenario runs, then reports what each device can read — the device that was already there holds both messages, and the newly linked device holds only the one sent after it existed.](https://raw.githubusercontent.com/open-e2ee/signal-protocol-js/main/docs/assets/demo/second-device.gif)](https://open-e2ee.dev/demo/#add-a-second-device)
33
+ [![Two devices exchange an end-to-end encrypted message through a relay. The relay handles public prekeys and ciphertext. Only the receiving device displays the plaintext.](https://raw.githubusercontent.com/open-e2ee/signal-protocol-js/main/docs/assets/demo/encrypted-round-trip.gif)](https://open-e2ee.dev/#demo)
40
34
 
41
- A second device is linked to an account over the real QR handshake. The message sent before that device existed is not on it — not withheld by a policy, but unreadable because the device's keys did not exist when that message was encrypted.
42
-
43
- Recorded from [open-e2ee.dev/demo](https://open-e2ee.dev/demo), which runs this package in the browser against the in-memory store and the in-memory relay: real protocol and cryptography, simulated in-memory infrastructure. Every scenario there prints the receiving device's own log, unedited.
35
+ The [live demo](https://open-e2ee.dev/#demo) runs two SDK clients against an in-memory relay. On desktop, type a message and inspect the envelope, ratchets, relay mailbox, and decrypted result. On mobile, the same protocol run replays at reading pace. The protocol and cryptography are real. The example simulates infrastructure in memory. Displayed timings exclude network time.
44
36
 
45
37
  ## Install
46
38
 
47
- ```bash
48
- npm install @open-e2ee/signal-protocol-sdk
49
- ```
50
-
51
- Installing straight from the repository also works — the package compiles itself during install, so TypeScript is the only build requirement:
39
+ Requires Node 18 or later for the local example.
52
40
 
53
41
  ```bash
54
- npm install github:open-e2ee/signal-protocol-js
42
+ npm install @open-e2ee/signal-protocol-sdk
55
43
  ```
56
44
 
57
- Adapters declare their runtime requirements as optional peer dependencies, so install the ones your chosen adapters need (for example `expo-sqlite` and `expo-secure-store`, or `convex`).
45
+ ## Run a local encrypted round trip
58
46
 
59
- ## Quick Start
60
-
61
- Two clients, one process, no account and no server. The relay holds the envelope; only Bob's device turns it back into text.
47
+ Save this as `quickstart.mjs`, then run `node quickstart.mjs`. It uses development-only in-memory adapters so that you can prove the message flow without a backend project.
62
48
 
63
49
  <!-- doc-snippet:run readme-quick-start expect="alice: hello" -->
64
50
  ```ts
@@ -80,87 +66,73 @@ const bob = await createSignalProtocolClient({
80
66
  adapters: { storage: inMemoryStore(), relay },
81
67
  });
82
68
 
83
- await alice.syncToServer();
84
- await bob.syncToServer();
85
-
86
- // Decrypted content reaches your app here, and nowhere else.
87
- bob.registerHook("onMessageDecrypted", async (message) => {
88
- console.log(`${message.senderId}: ${message.content}`); // alice: hello
69
+ const delivered = new Promise((resolve) => {
70
+ bob.registerHook("onMessageDecrypted", async (message) => {
71
+ console.log(`${message.senderId}: ${message.content}`);
72
+ bob.stopRelaySubscription();
73
+ resolve(undefined);
74
+ });
89
75
  });
90
76
 
91
- await alice.send("bob", "hello"); // the relay now holds ciphertext and metadata
92
- bob.startRelaySubscription(); // delivery and local decryption start here
77
+ await alice.send("bob", "hello");
78
+ bob.startRelaySubscription();
79
+ await delivered;
93
80
  ```
94
81
 
95
- Every identifier above is a real export. This exact block is extracted from this README and executed against the packed package by [this repository's CI](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml) on every change, and the same sequence runs in the engineering repository's automated checks.
96
-
97
- Next: [inspect what the relay actually stored](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/GETTING_STARTED.md), then compose the [Expo + Convex production client](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/CLIENT_COMPOSITION.md).
82
+ Expected output:
98
83
 
99
- ## How it compares
84
+ ```text
85
+ alice: hello
86
+ ```
100
87
 
101
- Measured from the GitHub API, the npm registry API, and the published package tarballs on 2026-08-03. Every alternative is a real project doing a real job; the axes below are the ones this SDK was built to change, not a general quality ranking.
88
+ The client factory creates or loads each device identity. When given a relay, it also publishes the public prekey bundle. `send()` fetches Bob's bundle and starts the required post-quantum session. It then gives ciphertext plus routing metadata to the relay. Bob's subscription retrieves and decrypts the envelope on his device.
102
89
 
103
- | | Expo / React Native | Browser | Maintained | Post-quantum | TypeScript-native | Commercial license |
104
- |---|---|---|---|---|---|---|
105
- | **`@open-e2ee/signal-protocol-sdk`** | Yes | Yes | Yes — `0.1.x`, active | Key agreement yes — PQXDH + ML-KEM, default and fails closed. Signatures no — identities are classical Ed25519 | Yes | Yes |
106
- | [`@signalapp/libsignal-client`](https://github.com/signalapp/libsignal) | No — Node native addon; the 0.99.3 tarball ships binaries for macOS, Linux, and Windows only | No | Yes — very active; repo push 2026-07-31 | Key agreement yes | No — Rust core with TypeScript bindings | No (AGPL-3.0 only) |
107
- | [`libsignal-protocol-javascript`](https://github.com/signalapp/libsignal-protocol-javascript) | No | Yes | No — archived, last push 2021-08-04 | No | No — JavaScript | No (GPL-3.0) |
108
- | [`@privacyresearch/libsignal-protocol-typescript`](https://github.com/privacyresearchgroup/libsignal-protocol-typescript) | No documented React Native path | Yes | No — last npm publish 2023-05-06, last repo push 2023-07-18 | No | Yes | No (GPL-3.0) |
109
- | [`ts-mls`](https://github.com/LukaJCB/ts-mls) | Not stated — browsers, Node, and serverless are the documented targets | Yes | Yes — very active; repo push 2026-08-03 | Key agreement and signatures — ML-KEM and ML-DSA-87 ciphersuites | Yes | Not needed (MIT) |
90
+ The in-memory store loses identities, sessions, and ratchet state on restart. The in-memory relay has no authentication, authorization, or durable storage. Do not ship either adapter. Continue with the [hosted Quickstart](https://docs.open-e2ee.dev/start/quickstart), which explains key custody, relay metadata, prekey replenishment, additional devices, and recovery policy.
110
91
 
111
- `ts-mls` implements [MLS (RFC 9420)](https://www.rfc-editor.org/rfc/rfc9420.html), a different protocol with different properties — if MLS suits your product, it is a good library and this table is not an argument against it, and its post-quantum coverage reaches further than this SDK's. `@signalapp/libsignal-client` is the implementation Signal Messenger itself uses; its README states that use outside Signal Messenger is unsupported. If you are shipping a desktop or server application on Node, reach for it first.
92
+ ## Move to production storage
112
93
 
113
- The longer version of this table, with a paragraph on each project, is at [open-e2ee.dev/compare](https://open-e2ee.dev/compare).
94
+ Choose the device-local store for your runtime, then supply a relay that authenticates each device and implements your product's access policy.
114
95
 
115
- ## Trust and verification
96
+ | Runtime | Storage path | Deployment boundary |
97
+ |---|---|---|
98
+ | Expo | [`expoStore`](./local/store/expo/README.md) | Configure SQLCipher before schema access. Requires a development build; it does not run in Expo Go. |
99
+ | Browser | [`indexedDbStore`](./local/store/web/README.md) | IndexedDB persists encrypted records, but same-origin JavaScript can access the records and their key. Review CSP, XSS, dependencies, and service workers. |
100
+ | Bare React Native | [`reactNativeStore`](./local/store/react-native/README.md) | Provide an atomic, durable key-value backend and run the exported backend conformance kit. |
101
+ | Node | [`nodeStore`](./local/store/node/README.md) | Set an explicit private data directory on a trusted local filesystem. |
116
102
 
117
- Cryptography deserves evidence rather than adjectives, so here is what there is and what there is not.
103
+ The [adapter guide](./ADAPTERS.md) defines every storage, relay, vault, and object-store boundary. The [client composition guide](./docs/CLIENT_COMPOSITION.md) shows an Expo and Convex integration.
118
104
 
119
- **Audit status.** Reviewed continuously by adversarial AI agents; not audited by any independent firm. Every change passes an adversarial AI review before it merges, and recurring whole-codebase AI audit passes run against the engineering repository. What that covers — and what it does not — is stated in the [assurance summary](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/ASSURANCE.md). No independent firm has audited the SDK, and none is engaged. Nothing here should be read as a third-party assurance claim.
105
+ ## Security and assurance
120
106
 
121
- **Security model and protocol policy.** The [security model](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/SECURITY.md) states the threat model, what is in and out of scope, the storage boundary, and the resource limits. The [protocol policy](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/PROTOCOL_POLICY.md) states which protocol modes are supported and which fail closed.
107
+ The [assurance summary](./docs/ASSURANCE.md) states what the automated checks cover and what the public export does not contain. Public CI rebuilds, type-checks, audits, and runs this README example against the packed package.
122
108
 
123
- **Specifications, pinned by revision.** The implementation follows its own versioned profile based on these published specifications:
109
+ JavaScript engines do not provide a machine-level constant-time contract or guaranteed zeroization. The [security model](./docs/SECURITY.md) defines the timing, same-process, storage, and metadata boundaries. The [protocol policy](./docs/PROTOCOL_POLICY.md) defines supported modes and fail-closed behavior.
124
110
 
125
- | Specification | Revision |
126
- |---|---|
127
- | [X3DH](https://signal.org/docs/specifications/x3dh/) | Revision 1, 2016-11-04 |
128
- | [PQXDH](https://signal.org/docs/specifications/pqxdh/) | Revision 3, 2023-05-24 (last updated 2024-01-23) |
129
- | [Double Ratchet](https://signal.org/docs/specifications/doubleratchet/) | Revision 4, 2025-11-04 |
130
- | [Sesame](https://signal.org/docs/specifications/sesame/) | Revision 2, 2017-04-14 |
131
- | [ML-KEM Braid](https://signal.org/docs/specifications/mlkembraid/) | Revision 1, 2025-02-21 (last updated 2025-09-26) |
132
- | [FIPS 203 (ML-KEM)](https://csrc.nist.gov/pubs/fips/203/final) | Final, 2024-08-13 |
133
- | [RFC 8032 (Ed25519)](https://www.rfc-editor.org/rfc/rfc8032.html) | — |
111
+ Report a suspected vulnerability privately through the process in [SECURITY](./SECURITY.md). Do not open a public issue for it.
134
112
 
135
- **Not wire-compatible, and specific about why.** This SDK cannot exchange messages with Signal Messenger or `libsignal`, cannot exchange identities with them, and its safety numbers will never match the ones a Signal Messenger client displays for the same two users. The cryptographic core is the same; the wire profile is deliberately its own. Identities are a versioned composite of separate X25519 and Ed25519 keys rather than one Curve25519 key, so signatures are ordinary RFC 8032 Ed25519 rather than XEdDSA; ML-KEM-1024 keys and ciphertexts are tagged `0x0A`, distinct from the round-3 Kyber1024 `0x08` tag. [DEVIATIONS](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md) is the complete account — every difference from the specifications and from `libsignal`, with the reason, the cost, and the file that implements it. The threat model boundary is in the [security model](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/SECURITY.md).
113
+ ## Why developers choose this SDK
136
114
 
137
- **Dependencies: 6.** Six direct production dependencies — `@noble/ciphers`, `@noble/curves`, `@noble/hashes`, `@noble/post-quantum`, `async-lock`, `unique-names-generator` — resolving to 6 packages in total: the only transitive edges are the `@noble` packages depending on one another, so the resolved tree adds nothing the list above does not already name. Everything else in the tree is a development or optional peer dependency.
115
+ The SDK gives TypeScript applications one maintained package for required post-quantum session establishment and ratcheting, multi-device messaging, groups, sealed sender, attachments, and safety numbers. It keeps protocol state on the device and leaves the relay implementation to the application.
138
116
 
139
- **Automated checks.** The published repository is a mechanized export of a private engineering repository, filtered by an allowlist; the automated checks live there and have to pass before an export is cut. The [assurance summary](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/ASSURANCE.md) carries the current run figures — regenerated from a real run as part of every release, never hand-edited — and explains what the checks cover, what is not published, and why. The published repository runs its own build, typecheck, and production dependency audit in [CI](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml) on every change.
117
+ [Compare maintained alternatives and their limits.](https://open-e2ee.dev/product/#how-it-compares)
140
118
 
141
- **Constant-time posture, honestly.** JavaScript engines offer no machine-level constant-time contract, and this SDK cannot invent one. What exists is best-effort source-level work on selected paths: full-scan comparison for equal-length MACs and identity bytes, fixed-work derivation of both decapsulation candidates before masked selection, and equal-work rejection padding on selected replay and authentication paths. These are not timing-equivalence proofs. Secret-influenced remainder and compression arithmetic remains, and JIT compilation, allocation, garbage collection, and cache effects stay observable. `secureZeroBytes()` overwrites the exact typed array it is handed and nothing more — not copies, not strings, not engine temporaries. The threat model does not cover hostile same-process code or a high-assurance co-resident timing adversary, and it says so.
119
+ ## Documentation
142
120
 
143
- **Reporting a vulnerability.** Email security@open-e2ee.dev rather than opening an issue. Acknowledgment within 72 hours, initial assessment within 7 days; the full policy is in [SECURITY.md](https://github.com/open-e2ee/signal-protocol-js/blob/main/SECURITY.md).
121
+ - [Getting started](./docs/GETTING_STARTED.md): the integration sequence and mental model.
122
+ - [Package surface](./docs/PACKAGE_SURFACE.md): root exports, subpaths, adapters, and core concepts.
123
+ - [Recipes](./docs/RECIPES.md): messaging, multi-device, attachments, and usernames.
124
+ - [Architecture](./ARCHITECTURE.md) and [adapters](./ADAPTERS.md): layer ownership and composition boundaries.
125
+ - [Integration interfaces](./docs/INTERFACES.md): contracts for custom stores, vaults, relays, and object stores.
126
+ - [Error handling](./docs/ERROR_HANDLING.md) and [troubleshooting](./TROUBLESHOOTING.md).
127
+ - [Deviations](./docs/DEVIATIONS.md): differences from the specifications and libsignal, with reasons and costs.
128
+ - [Hosted API reference](https://docs.open-e2ee.dev/reference/api): exported types and methods.
144
129
 
145
- ## Documentation
130
+ ## Help and contributing
146
131
 
147
- Hosted guides, quickstarts per runtime, and concept docs live at
148
- [docs.open-e2ee.dev](https://docs.open-e2ee.dev). The in-repo references below
149
- are versioned with the code:
150
-
151
- - [Getting Started](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/GETTING_STARTED.md) — installation, mental model, first working client.
152
- - [Package Surface](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/PACKAGE_SURFACE.md) — root exports, every subpath, adapter implementations, core concepts.
153
- - [Recipes](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/RECIPES.md) — message flow, protocol policy, multi-device, attachments, usernames.
154
- - [Client Composition](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/CLIENT_COMPOSITION.md) — production composition with Expo and Convex.
155
- - [Architecture](https://github.com/open-e2ee/signal-protocol-js/blob/main/ARCHITECTURE.md) and [Adapters](https://github.com/open-e2ee/signal-protocol-js/blob/main/ADAPTERS.md) — layer model and composition boundaries.
156
- - [Integration Interfaces](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/INTERFACES.md) — the interfaces to implement for custom storage, vaults, relays, and object stores.
157
- - [Error Handling](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/ERROR_HANDLING.md) and [Troubleshooting](https://github.com/open-e2ee/signal-protocol-js/blob/main/TROUBLESHOOTING.md).
158
- - [E2EE concepts](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/E2EE.md) — what changes about your architecture when the relay cannot read.
159
- - [Deviations](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md) — every difference from the Signal Protocol specifications and from `libsignal`, with reasons and costs.
160
- - [API Reference](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/api/README.md) — generated from the exported declarations.
132
+ Open a [bug report](https://github.com/open-e2ee/signal-protocol-js/issues/new?template=bug_report.yml) or send [API and documentation feedback](https://github.com/open-e2ee/signal-protocol-js/issues/new?template=api_feedback.yml). Read [CONTRIBUTING](./CONTRIBUTING.md) before you propose code. Use the private process in [SECURITY](./SECURITY.md) for suspected vulnerabilities.
161
133
 
162
134
  ## License and warranty
163
135
 
164
- Licensed under `AGPL-3.0-or-later`; see [LICENSE](https://github.com/open-e2ee/signal-protocol-js/blob/main/LICENSE). For proprietary products that cannot meet AGPL obligations, a commercial license is available — see [COMMERCIAL](https://github.com/open-e2ee/signal-protocol-js/blob/main/COMMERCIAL.md) or email licensing@open-e2ee.dev.
136
+ Licensed under AGPLv3 (`AGPL-3.0-or-later`). See [LICENSE](./LICENSE). A [commercial license](./COMMERCIAL.md) covers proprietary products that cannot meet AGPLv3 obligations.
165
137
 
166
- The software is provided **as is**, without warranties or conditions of any kind. To the extent permitted by applicable law, copyright holders and contributors are not liable for damages arising from its use. Applications remain responsible for evaluating this SDK against their own requirements and for securing their deployment, storage, authentication, authorization, and operations. This summary does not modify the license; the complete warranty disclaimer and limitation of liability are in sections 15 and 16 of the GNU Affero General Public License.
138
+ The license provides the software **as is**, without warranties or conditions of any kind. To the extent that applicable law permits, copyright holders and contributors are not liable for damages that arise from its use. Your application must evaluate the SDK against its requirements and secure its deployment, storage, authentication, authorization, and operations. This summary does not modify the license.
package/SECURITY.md CHANGED
@@ -7,8 +7,8 @@ backports.
7
7
 
8
8
  | Version | Supported |
9
9
  | ------- | ------------------ |
10
- | 0.2.x | :white_check_mark: |
11
- | < 0.2.0 | :x: |
10
+ | 0.4.x | :white_check_mark: |
11
+ | < 0.4.0 | :x: |
12
12
 
13
13
  ## Reporting a Vulnerability
14
14
 
@@ -22,7 +22,7 @@ We take security vulnerabilities seriously. If you discover a security issue, pl
22
22
  the repository's [Security tab](https://github.com/open-e2ee/signal-protocol-js/security)
23
23
  - Email: security@open-e2ee.dev
24
24
  3. Include the following information:
25
- - Description of the vulnerability
25
+ - What the vulnerability is
26
26
  - Steps to reproduce
27
27
  - Potential impact
28
28
  - Suggested fix (if any)
@@ -30,13 +30,16 @@ We take security vulnerabilities seriously. If you discover a security issue, pl
30
30
  ### Safe Harbor
31
31
 
32
32
  We will not pursue legal action or law-enforcement referral against
33
- good-faith security research on this codebase. Good faith means: make every
34
- effort to avoid privacy violations and data destruction, use your own accounts
35
- and devices for testing, do not exploit a finding beyond what is needed to
36
- demonstrate it, and give us a reasonable window to remediate before public
37
- disclosure. This applies to research on the SDK itself; testing deployed
38
- third-party applications that use the SDK is governed by those applications'
39
- own policies.
33
+ good-faith security research on this codebase. Good faith means all of the
34
+ following:
35
+
36
+ - Make every effort to avoid privacy violations and data destruction.
37
+ - Use your own accounts and devices for testing.
38
+ - Do not exploit a finding beyond what you need to show it.
39
+ - Give us a reasonable window to remediate before public disclosure.
40
+
41
+ This applies to research on the SDK itself. Those applications' own policies
42
+ govern testing of deployed third-party applications that use the SDK.
40
43
 
41
44
  ### What to Expect
42
45
 
@@ -51,7 +54,7 @@ own policies.
51
54
  ### Disclosure Policy
52
55
 
53
56
  - We follow responsible disclosure practices
54
- - We will credit reporters (unless anonymity is requested)
57
+ - We will credit reporters, unless a reporter requests anonymity
55
58
  - We aim to release patches before public disclosure
56
59
  - Public disclosure occurs after patch is available
57
60
 
@@ -112,7 +115,7 @@ write or that no copies exist.
112
115
  However, JIT compilers may:
113
116
 
114
117
  - Optimize away the zeroing before our check runs
115
- - Copy values to CPU registers that aren't zeroed
118
+ - Copy values to CPU registers that are not zeroed
116
119
  - Leave copies in garbage-collected heap memory
117
120
 
118
121
  **Garbage Collection**: Sensitive data in JavaScript objects may persist in heap memory until GC runs. We cannot force immediate collection or guarantee cleanup timing.
@@ -131,7 +134,7 @@ However, JIT compilers may:
131
134
  Browser/runtime timing attacks are possible. Current source-level mitigations include:
132
135
 
133
136
  - Full-scan equal-length comparison helpers on selected MAC/ciphertext paths
134
- - Fixed-work derivation of both decapsulation candidates before masked selection
137
+ - Fixed work on both decapsulation candidates, then a masked choice between them
135
138
  - Fixed-work rejection handling on selected authentication paths
136
139
 
137
140
  These are not hard constant-time guarantees. Ed25519 signature verification