@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
@@ -11,7 +11,7 @@ not want to learn protocol internals before sending a message.
11
11
  npm install @open-e2ee/signal-protocol-sdk
12
12
  ```
13
13
 
14
- In this monorepo the package is consumed as a workspace package. App consumers
14
+ In this monorepo, consumers use the package as a workspace package. App consumers
15
15
  should also install any runtime dependencies their chosen adapters need, such as
16
16
  Expo or Convex client packages.
17
17
 
@@ -22,7 +22,7 @@ Every client needs:
22
22
  - a stable `userId` from your app,
23
23
  - local `storage` for that user's encrypted protocol state,
24
24
  - usually a `relay` for server sync and encrypted message delivery,
25
- - remote encrypted object storage when sending attachments,
25
+ - an encrypted remote object store when sending attachments,
26
26
  - device registration or provisioning with that relay for each active device.
27
27
 
28
28
  The default security policy requires the package's post-quantum Signal Protocol
@@ -32,7 +32,7 @@ path.
32
32
  This guide uses the current stable API names. The target message-first DX groups
33
33
  local persistence under `deviceStorage.{protocol,messages,files}` and calls the
34
34
  remote encrypted byte adapter `remoteObjectStore`. Current `signal.media.*`
35
- examples are transition-only lower-level APIs; the target public API sends
35
+ examples are transition-only lower-level APIs. The target public API sends
36
36
  message attachments through `signal.messages.send({ attachments })` and advanced
37
37
  helpers, if needed, under a message-scoped API.
38
38
 
@@ -99,15 +99,15 @@ flowchart LR
99
99
  decrypts or stages them.
100
100
  - The relay connects devices, stores public keys, and carries encrypted
101
101
  envelopes.
102
- - Remote object storage carries encrypted attachment/media bytes only.
102
+ - The remote object store carries encrypted attachment/media bytes only.
103
103
 
104
104
  ## Target Message-First API Preview
105
105
 
106
- This is the target DX the package is moving toward. It is shown here so app
107
- developers can understand the intended mental model while the current stable API
106
+ This is the target DX the package moves toward. It appears here so app
107
+ developers can understand the intended mental model. The current stable API
108
108
  still uses `storage`, `remoteObjectStore`, hooks, and transition-only media helpers.
109
109
 
110
- <!-- doc-snippet:skip target-message-api-not-yet-shipped -->
110
+ <!-- doc-snippet:planned target-message-api unshipped="@open-e2ee/signal-protocol-sdk/device/storage/memory" -->
111
111
  ```ts
112
112
  // Real protocol and cryptography; simulated in-memory infrastructure.
113
113
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
@@ -161,6 +161,7 @@ await delivered;
161
161
 
162
162
  The production shape uses the same message API with platform adapters:
163
163
 
164
+ <!-- doc-snippet:planned target-message-api-platform-adapters unshipped="@open-e2ee/signal-protocol-sdk/device/storage/expo" -->
164
165
  ```ts
165
166
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
166
167
  import { createExpoDeviceStorage } from "@open-e2ee/signal-protocol-sdk/device/storage/expo";
@@ -181,10 +182,11 @@ const signal = await createSignalProtocolClient({
181
182
  });
182
183
  ```
183
184
 
184
- Attachments use the same message API. On Expo, pass the picker URI; the Signal
185
+ Attachments use the same message API. On Expo, pass the picker URI. The Signal
185
186
  Protocol client copies or persists the bytes through `deviceStorage.files`
186
- before upload so retry can continue after restart:
187
+ before upload, so retry can continue after restart:
187
188
 
189
+ <!-- doc-snippet:skip requires-external-context -->
188
190
  ```ts
189
191
  await signal.messages.send({
190
192
  conversationId: "dm:alice_bob",
@@ -203,6 +205,7 @@ await signal.messages.send({
203
205
 
204
206
  On the web, pass the browser file object:
205
207
 
208
+ <!-- doc-snippet:skip requires-external-context -->
206
209
  ```ts
207
210
  await signal.messages.send({
208
211
  conversationId,
@@ -224,9 +227,9 @@ current `signal.media.*` examples into lower-level transition or migration docs.
224
227
 
225
228
  ## Current Stable Local Clients
226
229
 
227
- Use the in-memory adapters for local examples and development:
228
- the demo sends while Bob is offline, inspects the relay-visible ciphertext, and
229
- then starts Bob's subscription to show the decrypted plaintext entering the app.
230
+ Use the in-memory adapters for local examples and development. The demo sends
231
+ while Bob is offline, inspects the relay-visible ciphertext, and then starts
232
+ Bob's subscription to show the decrypted plaintext entering the app.
230
233
 
231
234
  <!-- doc-snippet:run getting-started-stable-local-clients expect="bob decrypted: alice: hello" -->
232
235
  ```ts
@@ -304,7 +307,7 @@ bob decrypted: alice: hello
304
307
  ```
305
308
 
306
309
  The in-memory relay lets the example inspect what a server can see. The relay sees
307
- metadata plus encrypted envelope bytes; it does not receive Bob's decrypted
310
+ metadata plus encrypted envelope bytes. It does not receive Bob's decrypted
308
311
  message content. The first message often uses `prekey_bundle` to establish a
309
312
  session, and later messages use `ciphertext`.
310
313
 
@@ -314,6 +317,7 @@ Use the protocol storage adapter for your runtime and the relay adapter for your
314
317
  backend. For the Signal Protocol stack, that is Expo local storage and a Convex
315
318
  relay:
316
319
 
320
+ <!-- doc-snippet:skip requires-external-context -->
317
321
  ```ts
318
322
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
319
323
  import { expoStore } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
@@ -353,6 +357,7 @@ provisioning belong to the application bootstrap.
353
357
 
354
358
  Register a receive hook before starting the relay subscription:
355
359
 
360
+ <!-- doc-snippet:skip requires-external-context -->
356
361
  ```ts
357
362
  signal.registerHook("onMessageDecrypted", async (message) => {
358
363
  // Decrypted content belongs in your app database, not in the relay.
@@ -377,12 +382,14 @@ and hands the app a `DecryptedEnvelope`.
377
382
 
378
383
  Send by recipient user ID for normal one-to-one and multi-device delivery:
379
384
 
385
+ <!-- doc-snippet:skip requires-external-context -->
380
386
  ```ts
381
387
  await signal.send("bob", "hello");
382
388
  ```
383
389
 
384
390
  For structured app messages, pass an object:
385
391
 
392
+ <!-- doc-snippet:skip requires-external-context -->
386
393
  ```ts
387
394
  await signal.send("bob", {
388
395
  body: "hello",
@@ -397,9 +404,10 @@ Add a remote object store when your app sends encrypted attachments. The
397
404
  `remoteObjectStore` adapter brokers encrypted byte objects rather than
398
405
  plaintext files.
399
406
  The final public DX should not expose both `signal.media.*` and message
400
- attachment helpers; the planned replacement is message-scoped attachment
407
+ attachment helpers. The planned replacement is message-scoped attachment
401
408
  handling.
402
409
 
410
+ <!-- doc-snippet:skip requires-external-context -->
403
411
  ```ts
404
412
  import { media } from "@open-e2ee/signal-protocol-sdk";
405
413
  import { convexR2ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2";
@@ -431,6 +439,7 @@ const signal = await createSignalProtocolClient({
431
439
  For Amazon S3 or S3-compatible storage, use the framework-neutral adapter with
432
440
  an authenticated application-backend broker:
433
441
 
442
+ <!-- doc-snippet:skip requires-external-context -->
434
443
  ```ts
435
444
  import { s3ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/s3";
436
445
 
@@ -448,9 +457,9 @@ Keep AWS credentials and AWS SDK clients on that backend. The app should
448
457
  receive only narrowly scoped, short-lived upload, download, and delete
449
458
  operations.
450
459
 
451
- Send bytes when the attachment should be delivered as its own encrypted
452
- message:
460
+ Send bytes when the attachment travels as its own encrypted message:
453
461
 
462
+ <!-- doc-snippet:skip requires-external-context -->
454
463
  ```ts
455
464
  const controller = new AbortController();
456
465
 
@@ -482,6 +491,7 @@ await signal.send("bob", photoBytes, {
482
491
  Upload first when your app message format embeds the attachment pointer inside a
483
492
  larger payload:
484
493
 
494
+ <!-- doc-snippet:skip requires-external-context -->
485
495
  ```ts
486
496
  const attachment = await signal.uploadAttachment(photoBytes, {
487
497
  mimeType: "image/jpeg",
@@ -510,7 +520,7 @@ a generic transient failure.
510
520
 
511
521
  `attachment.transfer` is where production apps plug in their foreground or
512
522
  background transfer adapter. The Signal Protocol client still owns encryption, digest
513
- verification, retries, and pointer metadata; the adapter owns how bytes move
523
+ verification, retries, and pointer metadata. The adapter owns how bytes move
514
524
  over the network.
515
525
 
516
526
  If your object store returns TUS credentials, including `protocol: 'tus'`, the
@@ -520,17 +530,18 @@ useful when the app needs custom chunk sizing or a platform-specific `fetch`.
520
530
 
521
531
  For downloads in JavaScript runtimes, `media.createByteRangeMediaAttachmentTransfer()`
522
532
  provides a reviewed HTTP `Range` adapter. It validates `Content-Range`, forwards
523
- signed download headers from the object store, emits checkpoints, and only resumes
524
- from a non-zero offset when your app provides the partial ciphertext prefix via a
525
- partial-byte store. Native background download code should implement the same
533
+ signed download headers from the object store, and emits checkpoints. It resumes
534
+ from a non-zero offset only when your app provides the partial ciphertext prefix
535
+ through a partial-byte store. Native background download code should implement the same
526
536
  `MediaAttachmentTransfer` interface.
527
537
 
528
538
  For background-safe uploads, use the durable client operation. The current API
529
539
  persists bounded recovery metadata through the existing Signal Protocol storage
530
- adapter; the target message-first API moves that responsibility behind
540
+ adapter. The target message-first API moves that responsibility behind
531
541
  `deviceStorage.messages`. The operation tries the upload when it is due and
532
542
  returns either a completed pointer or a pending job id for later recovery:
533
543
 
544
+ <!-- doc-snippet:skip requires-external-context -->
534
545
  ```ts
535
546
  const upload = await signal.media.upload(
536
547
  {
@@ -555,6 +566,7 @@ if (upload.status === "completed") {
555
566
  Run pending durable media work on app startup, foreground resume, or from a
556
567
  background task:
557
568
 
569
+ <!-- doc-snippet:skip requires-external-context -->
558
570
  ```ts
559
571
  await signal.media.processPending({
560
572
  limit: 10,
@@ -564,9 +576,10 @@ await signal.media.processPending({
564
576
  ```
565
577
 
566
578
  On receive, ask the media planner what work this device should do. Your app
567
- supplies the IDs it has already processed or cached; the Signal Protocol package
568
- returns the safe next step without taking ownership of your app database:
579
+ supplies the IDs it has already processed or cached. The Signal Protocol package
580
+ returns the safe next step, and it does not take ownership of your app database:
569
581
 
582
+ <!-- doc-snippet:skip requires-external-context -->
570
583
  ```ts
571
584
  const mediaWork = media.planMediaAttachmentProcessing({
572
585
  attachment,
@@ -610,6 +623,7 @@ If the planner says this device needs media bytes, pass the decrypted attachment
610
623
  pointer back to the client. The client downloads encrypted blob bytes, verifies
611
624
  the digest, authenticates the stream, and returns plaintext bytes:
612
625
 
626
+ <!-- doc-snippet:skip requires-external-context -->
613
627
  ```ts
614
628
  if (mediaWork.shouldDownload) {
615
629
  const downloaded = await signal.downloadAttachment(attachment, {
@@ -641,6 +655,7 @@ if (mediaWork.shouldDownload) {
641
655
  If the attachment is view-once, plan the local cleanup and linked-device sync
642
656
  after the user opens it:
643
657
 
658
+ <!-- doc-snippet:skip requires-external-context -->
644
659
  ```ts
645
660
  const opened = media.planMediaAttachmentOpen({
646
661
  attachment,
@@ -661,9 +676,10 @@ if (opened.cleanup?.deleteRemoteBlob) {
661
676
  }
662
677
  ```
663
678
 
664
- When a message delete or expiration should remove media on this account's linked
665
- devices, plan and sync the deletion after your app applies the local cleanup:
679
+ A message delete or expiration can remove media on this account's linked
680
+ devices. Plan and sync the deletion after your app applies the local cleanup:
666
681
 
682
+ <!-- doc-snippet:skip requires-external-context -->
667
683
  ```ts
668
684
  const deleteSync = media.planMediaAttachmentDeleteSync({
669
685
  attachment,
@@ -675,8 +691,9 @@ await appMediaCache.delete(deleteSync.storageId);
675
691
  await signal.syncMediaAttachmentDeleteToLinkedDevices(deleteSync);
676
692
  ```
677
693
 
678
- When cleanup should be performed by a worker, use the durable client operation:
694
+ When a worker must do the cleanup, use the durable client operation:
679
695
 
696
+ <!-- doc-snippet:skip requires-external-context -->
680
697
  ```ts
681
698
  await signal.media.cleanup(
682
699
  {
@@ -698,6 +715,7 @@ await signal.media.cleanup(
698
715
 
699
716
  The default is:
700
717
 
718
+ <!-- doc-snippet:illustrative config-object-fragment -->
701
719
  ```ts
702
720
  protocol: {
703
721
  postQuantum: 'required',
@@ -4,7 +4,7 @@
4
4
  > [Adapters](../ADAPTERS.md)
5
5
 
6
6
  The Signal Protocol SDK keeps platform and backend infrastructure behind
7
- explicit TypeScript interfaces. The client owns protocol coordination; the host
7
+ explicit TypeScript interfaces. The client owns protocol coordination. The host
8
8
  application owns persistence, authentication, authorization, and product
9
9
  policy.
10
10
 
@@ -31,6 +31,7 @@ requirements described below.
31
31
  `ISignalProtocolLocalStore` persists the current device's identities, prekeys, sessions,
32
32
  sender keys, contact trust, retry records, and operational metadata.
33
33
 
34
+ <!-- doc-snippet:skip requires-external-context -->
34
35
  ```ts
35
36
  import type { ISignalProtocolLocalStore } from "@open-e2ee/signal-protocol-sdk/local/store";
36
37
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
@@ -46,15 +47,15 @@ const client = await createSignalProtocolClient({
46
47
  A production implementation must:
47
48
 
48
49
  - preserve compare-and-swap and transaction semantics for trust and session
49
- transitions;
50
- - consume one-time prekeys atomically with the corresponding session commit;
51
- - persist exact device/session ownership metadata;
50
+ transitions.
51
+ - consume one-time prekeys atomically with the corresponding session commit.
52
+ - persist exact device/session ownership metadata.
52
53
  - treat account reset as a coordinated lifecycle across protocol records,
53
- bootstrap secrets, backups, and application state; and
54
+ bootstrap secrets, backups, and application state.
54
55
  - avoid placing decrypted application messages in the protocol store.
55
56
 
56
- Available adapters and their status are documented in the
57
- [local-store guide](../local/store/README.md).
57
+ The [local-store guide](../local/store/README.md) lists the available adapters
58
+ and their status.
58
59
 
59
60
  ## `ISignalProtocolLocalSecretVault`
60
61
 
@@ -62,6 +63,7 @@ Available adapters and their status are documented in the
62
63
  secrets that must live outside the main local store, such as a database
63
64
  encryption key.
64
65
 
66
+ <!-- doc-snippet:skip requires-external-context -->
65
67
  ```ts
66
68
  import type { ISignalProtocolLocalSecretVault } from "@open-e2ee/signal-protocol-sdk";
67
69
 
@@ -83,6 +85,7 @@ selected platform service and host configuration. See the
83
85
  device registration, account identity state, public prekeys, encrypted-envelope
84
86
  delivery, provisioning, key rotation, and encrypted group coordination.
85
87
 
88
+ <!-- doc-snippet:skip requires-external-context -->
86
89
  ```ts
87
90
  import type { ISignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/relay";
88
91
  import {
@@ -100,11 +103,16 @@ const relay: ISignalProtocolRelayServer = convexRelay({
100
103
  });
101
104
  ```
102
105
 
103
- The application backend must authenticate every caller, derive ownership from
104
- trusted server context, authorize reads and writes, atomically consume one-time
105
- prekeys, allocate linked-device identifiers, and apply retention and abuse
106
- controls. Client-supplied user identifiers are routing inputs, not proof of
107
- identity.
106
+ The application backend must:
107
+
108
+ - authenticate every caller
109
+ - derive ownership from trusted server context
110
+ - authorize reads and writes
111
+ - atomically consume one-time prekeys
112
+ - allocate linked-device identifiers
113
+ - apply retention and abuse controls
114
+
115
+ A client-supplied user identifier is a routing input, not proof of identity.
108
116
 
109
117
  The relay stores public protocol material, ciphertext, and required routing
110
118
  metadata. It must not require device private keys or decrypted message content.
@@ -115,6 +123,7 @@ See the [relay guide](../remote/relay/README.md).
115
123
  `SignalProtocolRemoteObjectStore` supplies short-lived upload and download operations
116
124
  for already encrypted objects. It is provider-neutral and optional.
117
125
 
126
+ <!-- doc-snippet:skip requires-external-context -->
118
127
  ```ts
119
128
  import type {
120
129
  SignalProtocolRemoteObjectStore,
@@ -136,16 +145,21 @@ authenticated principal + retry requestId
136
145
  -> private provider key
137
146
  ```
138
147
 
139
- It must keep provider credentials and keys off the client, enforce ciphertext
140
- size and content-type policy, make upload completion idempotent, and authorize
141
- every download and deletion. See the
142
- [remote object-store guide](../remote/object-store/README.md).
148
+ It must:
149
+
150
+ - keep provider credentials and keys off the client
151
+ - enforce ciphertext size and content-type policy
152
+ - make upload completion idempotent
153
+ - authorize every download and deletion
154
+
155
+ See the [remote object-store guide](../remote/object-store/README.md).
143
156
 
144
157
  ## Application callbacks
145
158
 
146
159
  Application content remains outside the infrastructure adapters. Configure
147
160
  media lifecycle callbacks and client hooks at the client boundary:
148
161
 
162
+ <!-- doc-snippet:skip requires-external-context -->
149
163
  ```ts
150
164
  const client = await createSignalProtocolClient({
151
165
  identity: { userId },
@@ -169,8 +183,8 @@ const client = await createSignalProtocolClient({
169
183
  ```
170
184
 
171
185
  Callbacks may update application databases, caches, UI state, and telemetry.
172
- They must not be treated as a transactional extension of a completed protocol
173
- state update unless the specific API says so.
186
+ Never treat them as a transactional extension of a completed protocol state
187
+ update, unless the specific API says so.
174
188
 
175
189
  ## Choosing an integration
176
190
 
@@ -5,28 +5,29 @@
5
5
  > [Security Model](./SECURITY.md) | [API Reference](./api/README.md)
6
6
 
7
7
  This document is the complete public surface of
8
- `@open-e2ee/signal-protocol-sdk`: what the root package exports, every
9
- supported subpath, the adapter implementations that ship with the package, and
10
- the vocabulary the rest of the documentation assumes.
8
+ `@open-e2ee/signal-protocol-sdk`. It lists what the root package exports, every
9
+ supported subpath, and the adapter implementations that ship with the package.
10
+ It also defines the vocabulary the rest of the documentation assumes.
11
11
 
12
12
  ## Core model
13
13
 
14
14
  - `createSignalProtocolClient()` is the recommended app-facing entry point.
15
15
  - `SignalProtocolClient` is the primary class returned by the factory.
16
- - `storage` is required and owns local encryption state for one user/device.
17
- - `relay` is optional for local development, but real messaging apps use it for
16
+ - Every client requires `storage`, which owns local encryption state for one
17
+ user/device.
18
+ - `relay` is optional for local development. Real messaging apps use it for
18
19
  key sync, message delivery, device fanout, and linked-device workflows.
19
- - Secure post-quantum defaults are enabled without extra configuration.
20
- - Identity trust is pinned to one versioned X25519 + Ed25519 composite tuple
21
- per `(userId, identityType)`; first contact remains unverified TOFU.
20
+ - The client enables secure post-quantum defaults without extra configuration.
21
+ - The SDK pins identity trust to one versioned X25519 + Ed25519 composite tuple
22
+ per `(userId, identityType)`. First contact remains unverified TOFU.
22
23
  - The root package is intentionally core-only. Platform and backend adapters
23
24
  live on explicit subpaths.
24
25
 
25
- OpenE2EE is the project and package namespace; it is not the name of a single
26
+ OpenE2EE is the project and package namespace. It is not the name of a single
26
27
  protocol client. The protocol-specific package and client names leave that
27
28
  namespace clear for other E2EE protocol implementations, such as a future
28
29
  [Messaging Layer Security (MLS)](https://www.rfc-editor.org/rfc/rfc9420.html)
29
- package, without implying that one client spans multiple protocols.
30
+ package. They do not imply that one client spans multiple protocols.
30
31
 
31
32
  ## Setup sequence
32
33
 
@@ -43,6 +44,7 @@ For a production app, the normal startup shape is:
43
44
 
44
45
  Use the root package for core portable APIs:
45
46
 
47
+ <!-- doc-snippet:skip requires-external-context -->
46
48
  ```ts
47
49
  import {
48
50
  SignalProtocolClient,
@@ -131,7 +133,7 @@ Expo storage or Convex helpers.
131
133
 
132
134
  - **Client**: one running app instance for one account and one device.
133
135
  - **User ID**: your app's stable account identifier.
134
- - **Device ID**: `1` for the primary device; linked devices use `2-5`.
136
+ - **Device ID**: `1` for the primary device. Linked devices use `2-5`.
135
137
  - **Storage**: local encrypted state needed to keep conversations working across
136
138
  restarts.
137
139
  - **Relay**: server-side public keys, device lists, encrypted envelope delivery,
@@ -169,7 +171,7 @@ Expo storage or Convex helpers.
169
171
  - `InMemorySignalProtocolStore` / `inMemoryStore()` for local development
170
172
  - custom implementations via `ISignalProtocolLocalStore`
171
173
 
172
- ### Remote object storage
174
+ ### Remote object store
173
175
 
174
176
  - `ConvexR2ObjectStore` via
175
177
  `@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2`
@@ -182,13 +184,13 @@ Expo storage or Convex helpers.
182
184
  - custom implementations via `SignalProtocolRemoteObjectStore`
183
185
 
184
186
  `ConvexR2ObjectStore` is a client adapter for authenticated app-owned Convex
185
- functions that wrap `@convex-dev/r2`; it is not the Convex component itself.
187
+ functions that wrap `@convex-dev/r2`. It is not the Convex component itself.
186
188
  The application continues to own component installation, mounting,
187
189
  configuration, authentication, authorization, persistence, credentials, and
188
190
  the R2 bucket. The optional server helper owns only generic broker mechanics.
189
191
  Both concrete adapters keep provider credentials in the application backend.
190
192
 
191
- Remote object storage is a normal first-class integration point for encrypted
193
+ The remote object store is a normal integration point for encrypted
192
194
  attachments and files, not a niche or internal-only adapter. Use
193
195
  `attachment.transfer` when your app has a foreground, background, resumable, or
194
196
  platform-native byte transfer implementation. The Signal Protocol package still
@@ -198,12 +200,13 @@ Object stores can return signed upload headers, and stores that return
198
200
  `protocol: 'tus'` automatically use the built-in resumable TUS transfer helper.
199
201
  You can also pass `media.createTusMediaAttachmentTransfer()` explicitly when
200
202
  your app wants to tune the TUS fetch implementation or chunk size. Download
201
- credentials can also return signed headers. For JavaScript runtimes that need
202
- resumable downloads, `media.createByteRangeMediaAttachmentTransfer()` performs
203
- strict HTTP range requests, validates `Content-Range`, persists checkpoints, and
204
- resumes only when your app provides a partial-byte store for the previous
205
- ciphertext prefix. Native background download integrations should implement the
206
- same `MediaAttachmentTransfer` seam.
203
+ credentials can also return signed headers.
204
+
205
+ For JavaScript runtimes that need resumable downloads, use `media.createByteRangeMediaAttachmentTransfer()`. It
206
+ makes strict HTTP range requests, validates `Content-Range`, and persists
207
+ checkpoints. It resumes only when your app provides a partial-byte store for the
208
+ previous ciphertext prefix. Native background download integrations should
209
+ implement the same `MediaAttachmentTransfer` seam.
207
210
 
208
211
  ## Design notes
209
212
 
@@ -228,7 +231,7 @@ same `MediaAttachmentTransfer` seam.
228
231
  - [Keys and identity](../keys/README.md)
229
232
  - [Local stores](../local/store/README.md)
230
233
  - [Local secret vault](../local/vault/README.md)
231
- - [Remote relay and object storage](../remote/README.md)
234
+ - [Relay and remote object store](../remote/README.md)
232
235
  - [Encrypted media](../media/README.md)
233
236
  - [Encrypted files](../files/README.md)
234
237
  - [Groups](../groups/README.md)
@@ -2,14 +2,15 @@
2
2
 
3
3
  > Navigation: [README](../README.md) | [ARCHITECTURE](../ARCHITECTURE.md) | [Security](./SECURITY.md) | [Getting Started](./GETTING_STARTED.md) | **Protocol Policy** | [Deviations](./DEVIATIONS.md)
4
4
 
5
- This document covers **which protocol modes run** and which fail closed. For
6
- **how the profile differs from the published specifications and from
7
- `libsignal`** — the composite identity, the Ed25519-instead-of-XEdDSA signature
8
- scheme, the ML-KEM Braid `hek` operand order, and the rest — see
9
- [Deviations](./DEVIATIONS.md).
5
+ This document covers **which protocol modes run** and which fail closed.
6
+ [Deviations](./DEVIATIONS.md) covers **how the profile differs from the
7
+ published specifications and from `libsignal`**. That includes the composite
8
+ identity, the Ed25519-instead-of-XEdDSA signature scheme, the ML-KEM Braid
9
+ `hek` operand order, and every other difference.
10
10
 
11
11
  The public Signal Protocol client policy is:
12
12
 
13
+ <!-- doc-snippet:illustrative config-object-fragment -->
13
14
  ```ts
14
15
  protocol: {
15
16
  postQuantum: 'required',
@@ -25,6 +26,7 @@ the current app.
25
26
 
26
27
  ## Required
27
28
 
29
+ <!-- doc-snippet:skip requires-external-context -->
28
30
  ```ts
29
31
  await createSignalProtocolClient({
30
32
  identity: { userId },
@@ -39,6 +41,7 @@ closed.
39
41
 
40
42
  ## Compatible
41
43
 
44
+ <!-- doc-snippet:skip requires-external-context -->
42
45
  ```ts
43
46
  await createSignalProtocolClient({
44
47
  identity: { userId },
@@ -61,6 +64,7 @@ Compatible mode does not allow downgrade recovery:
61
64
 
62
65
  ## Braid Policy
63
66
 
67
+ <!-- doc-snippet:skip requires-external-context -->
64
68
  ```ts
65
69
  await createSignalProtocolClient({
66
70
  identity: { userId },
@@ -70,12 +74,15 @@ await createSignalProtocolClient({
70
74
  ```
71
75
 
72
76
  `braid: 'required'` uses the specification-defined ML-KEM Braid SPQR profile
73
- and is the default. HEK is `SHA3-256(ek_seed || ek_vector)`; that operand order
77
+ and is the default. HEK is `SHA3-256(ek_seed || ek_vector)`. That operand order
74
78
  is part of the public compatibility boundary. It follows the ML-KEM Braid
75
- specification text and is the reverse of `libsignal`'s implementation, which means
76
- braid sessions do not interoperate with `libsignal`'s and the KEM in this mode is not
77
- stock FIPS 203 — see [Deviations §4.1](./DEVIATIONS.md#41-the-hek-operand-order-diverges).
79
+ specification text and reverses `libsignal`'s implementation. Braid sessions
80
+ therefore do not interoperate with `libsignal`'s, and the KEM in this mode is
81
+ not stock FIPS 203.
78
82
 
83
+ See [Deviations §4.1](./DEVIATIONS.md#41-the-hek-operand-order-diverges).
84
+
85
+ <!-- doc-snippet:skip requires-external-context -->
79
86
  ```ts
80
87
  await createSignalProtocolClient({
81
88
  identity: { userId },
@@ -92,6 +99,7 @@ product-reviewed constraints, not downgrade recovery.
92
99
 
93
100
  Use string literals directly or the exported constant object:
94
101
 
102
+ <!-- doc-snippet:skip requires-external-context -->
95
103
  ```ts
96
104
  import { BraidPolicy, PostQuantumPolicy, createSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
97
105
 
@@ -115,10 +123,14 @@ compatibility fallback. Do not set `protocolStrategy.allowClassicalFallback`
115
123
  when `protocol.postQuantum` is present.
116
124
 
117
125
  The advanced `protocolStrategy.onBraidProgress` callback reports ML-KEM Braid
118
- chunk progress after every braid-mode send and receive: the chunks this side has
119
- carried in the current epoch, the chunks the open transfers account for, the
120
- epoch, and whether the operation produced the epoch secret. A direct-mode
121
- session never raises it.
126
+ chunk progress after every braid-mode send and receive:
127
+
128
+ - the chunks this side carried in the current epoch
129
+ - the chunks the open transfers account for
130
+ - the epoch
131
+ - whether the operation produced the epoch secret
132
+
133
+ A direct-mode session never raises it.
122
134
 
123
135
  Do not set `protocolStrategy.sckaMode` when `protocol` is present. Use
124
136
  `protocol.braid` so the public product policy owns the direct-vs-Braid choice.