@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
@@ -1,16 +1,22 @@
1
1
  # Convex Signal Protocol component
2
2
 
3
- This installable Convex component owns the complete relay backend: account and
4
- device registration, identity and prekey storage, message queues, sealed-sender
5
- delivery, retry requests, provisioning, sender certificates, canonical
6
- encrypted group state, anonymous group authorization, credential issuance, and
7
- group-send endorsements. The app owns only its
8
- authentication-to-protocol-identity mapping and thin public wrappers.
3
+ This installable Convex component owns the complete relay backend:
4
+
5
+ - account and device registration
6
+ - identity and prekey storage
7
+ - message queues, sealed-sender delivery, and retry requests
8
+ - provisioning and sender certificates
9
+ - canonical encrypted group state and anonymous group authorization
10
+ - credential issuance and group-send endorsements
11
+
12
+ The app owns only its authentication-to-protocol-identity mapping and thin
13
+ public wrappers.
9
14
 
10
15
  ## Install the component
11
16
 
12
17
  Mount the component in the app's Convex configuration:
13
18
 
19
+ <!-- doc-snippet:skip requires-external-context -->
14
20
  ```ts
15
21
  // convex/convex.config.ts
16
22
  import { defineApp } from 'convex/server';
@@ -26,11 +32,11 @@ app.use(signalProtocol, {
26
32
  export default app;
27
33
  ```
28
34
 
29
- The `env` forwarding is load-bearing: Convex components are isolated from the
30
- app's environment variables, so without it the component cannot see the
31
- deployment's `OE_GROUPS_SERVER_SECRET` and every group, credential-issuance,
32
- and sender-certificate call fails at runtime. The messaging, device, key, and
33
- provisioning namespaces work without the secret.
35
+ The `env` forwarding is load-bearing. Convex isolates each component from the
36
+ app's environment variables. Without the forwarding, the component cannot see
37
+ the deployment's `OE_GROUPS_SERVER_SECRET`, and every group,
38
+ credential-issuance, and sender-certificate call fails at runtime. The
39
+ messaging, device, key, and provisioning namespaces work without the secret.
34
40
 
35
41
  The component owns these isolated tables. They do not appear in the app schema
36
42
  and need no package-specific prefixes:
@@ -49,14 +55,13 @@ and need no package-specific prefixes:
49
55
  - `groups`, `groupChanges`, and `groupSnapshots`: canonical encrypted group
50
56
  state, immutable signed changes, and per-version signed snapshots.
51
57
 
52
- The component derives **no** membership map from group state. Group reads and
53
- writes are authorized entirely by zero-knowledge presentations, so `groups`,
54
- `groupChanges`, and `groupSnapshots` never name an account, and there is no
55
- `getGroupMembers` endpoint anywhere in the relay surface. Membership is
56
- local-first: each client resolves fan-out recipients from its own decrypted
57
- group state and passes their user IDs with the send
58
- (`SendOptions.groupMemberUserIds`); the relay expands users to devices via
59
- `getActiveDevices`.
58
+ The component derives **no** membership map from group state. Zero-knowledge
59
+ presentations authorize every group read and write. Therefore `groups`,
60
+ `groupChanges`, and `groupSnapshots` never name an account, and the relay
61
+ surface has no `getGroupMembers` endpoint. Membership is local-first. Each
62
+ client resolves fan-out recipients from its own decrypted group state and
63
+ passes their user IDs with the send (`SendOptions.groupMemberUserIds`). The
64
+ relay expands users to devices through `getActiveDevices`.
60
65
 
61
66
  See [Group metadata privacy](#group-metadata-privacy) for what the relay can
62
67
  still infer from delivery traffic. The absence of a membership endpoint is not
@@ -65,15 +70,19 @@ by itself a metadata-privacy guarantee.
65
70
  The mounted `@convex-dev/rate-limiter` child component separately owns its
66
71
  isolated `rateLimits` table.
67
72
 
68
- The tables store the latest canonical encrypted state, the exact accepted and
69
- signed action bytes, and every historical encrypted snapshot with its cached
70
- S14 baseline signature. They never store the group master key, group secret
71
- parameters, plaintext group attributes, or the server secret.
73
+ The tables store:
74
+
75
+ - the latest canonical encrypted state
76
+ - the exact accepted and signed action bytes
77
+ - every historical encrypted snapshot with its cached S14 baseline signature
78
+
79
+ They never store the group master key, group secret parameters, plaintext group
80
+ attributes, or the server secret.
72
81
 
73
82
  Storage grows with one full encrypted snapshot per accepted version and is
74
83
  never pruned. Old snapshots are load-bearing: `getGroupChanges` serves signed
75
84
  history from them, so deleting rows breaks catch-up for clients behind that
76
- version. A snapshot-compaction protocol is future work; budget storage as
85
+ version. A snapshot-compaction protocol is future work. Budget storage as
77
86
  O(versions × state size) per group.
78
87
 
79
88
  ## Mount the public wrappers
@@ -81,6 +90,7 @@ O(versions × state size) per group.
81
90
  Create the wrapper once with the mounted component reference and the app's
82
91
  authentication hook:
83
92
 
93
+ <!-- doc-snippet:skip requires-external-context -->
84
94
  ```ts
85
95
  // convex/relayBackend.ts
86
96
  import { components } from './_generated/api';
@@ -105,6 +115,7 @@ export const signalRelay = defineConvexSignalProtocolBackend(
105
115
  The relay reads these functions through `api.signal`, so the modules must live
106
116
  inside that namespace rather than at the top of `convex/`:
107
117
 
118
+ <!-- doc-snippet:skip requires-external-context -->
108
119
  ```ts
109
120
  // convex/signal/groups.ts
110
121
  import { signalRelay } from '../relayBackend';
@@ -119,6 +130,7 @@ export const {
119
130
  } = signalRelay.groups;
120
131
  ```
121
132
 
133
+ <!-- doc-snippet:skip requires-external-context -->
122
134
  ```ts
123
135
  // convex/signal/zkAuth.ts
124
136
  import { signalRelay } from '../relayBackend';
@@ -131,6 +143,7 @@ export const {
131
143
 
132
144
  Mount the remaining relay namespaces alongside those group modules:
133
145
 
146
+ <!-- doc-snippet:skip requires-external-context -->
134
147
  ```ts
135
148
  // convex/signal/messages.ts
136
149
  import { signalRelay } from '../relayBackend';
@@ -147,6 +160,7 @@ export const {
147
160
  } = signalRelay.messages;
148
161
  ```
149
162
 
163
+ <!-- doc-snippet:skip requires-external-context -->
150
164
  ```ts
151
165
  // convex/signal/devices.ts
152
166
  import { signalRelay } from '../relayBackend';
@@ -160,6 +174,7 @@ export const {
160
174
  } = signalRelay.devices;
161
175
  ```
162
176
 
177
+ <!-- doc-snippet:skip requires-external-context -->
163
178
  ```ts
164
179
  // convex/signal/keys.ts
165
180
  import { signalRelay } from '../relayBackend';
@@ -177,12 +192,14 @@ export const {
177
192
  } = signalRelay.keys;
178
193
  ```
179
194
 
195
+ <!-- doc-snippet:skip requires-external-context -->
180
196
  ```ts
181
197
  // convex/signal/certificates.ts
182
198
  import { signalRelay } from '../relayBackend';
183
199
  export const { issueSenderCertificate } = signalRelay.certificates;
184
200
  ```
185
201
 
202
+ <!-- doc-snippet:skip requires-external-context -->
186
203
  ```ts
187
204
  // convex/signal/provisioning.ts
188
205
  import { signalRelay } from '../relayBackend';
@@ -198,13 +215,15 @@ export const {
198
215
  } = signalRelay.provisioning;
199
216
  ```
200
217
 
201
- `messages` owns identified and sealed delivery, multi-recipient fan-out, retry
202
- queues, and message/device lookup reads. `devices` owns registration, removal,
203
- connection state, and presence. `keys` owns identity provisioning and
204
- compare-and-swap rotation, prekey upload, atomic one-time-key consumption, and
205
- key metadata. `certificates` issues sender certificates for registered
206
- account/device identities. `provisioning` owns the linked-device session state
207
- machine through acknowledgment or rollback.
218
+ - `messages` owns identified and sealed delivery, multi-recipient fan-out,
219
+ retry queues, and message/device lookup reads.
220
+ - `devices` owns registration, removal, connection state, and presence.
221
+ - `keys` owns identity provisioning and compare-and-swap rotation, prekey
222
+ upload, atomic one-time-key consumption, and key metadata.
223
+ - `certificates` issues sender certificates for registered account/device
224
+ identities.
225
+ - `provisioning` owns the linked-device session state machine through
226
+ acknowledgment or rollback.
208
227
 
209
228
  The account-scoped wrappers resolve the caller identity on the server and
210
229
  inject the application `userId`, raw ACI, and optional PNI bytes into the
@@ -216,28 +235,28 @@ the supplied zero-knowledge presentation.
216
235
  `sendUnidentified` and `sendMultiRecipientUnidentified` are the deliberate
217
236
  exception: those sealed-sender paths do **not** call `identify`. They authorize
218
237
  the bearer request with the target's unidentified-access key or verified group
219
- send material, preserving delivery without an authenticated application
220
- session. Rejections are structured `ConvexError` data, and the relay adapter
221
- decides whether to fall back to identified delivery by reading
222
- `data.code === 'UNAUTHORIZED'` — not by matching on the message text. A
223
- deployment that wraps or re-throws component rejections must preserve `code`,
224
- or a sealed send that should have retried on the identified path will surface
225
- as a hard failure instead.
226
-
227
- A recipient's unidentified-access key is registered as a side effect of the
228
- zero-knowledge profile-key credential flow
229
- (`issueProfileKeyCredentialMutation`). Until a recipient has completed that
230
- flow, access-key-authorized sealed sends to them are rejected and the client
231
- falls back to identified delivery — messages still arrive, but without sender
238
+ send material, which keeps delivery available without an authenticated
239
+ application session. Rejections carry structured `ConvexError` data. The relay
240
+ adapter reads `data.code === 'UNAUTHORIZED'` to decide the fallback to
241
+ identified delivery, and never matches on the message text. A deployment that
242
+ wraps or re-throws component rejections must preserve `code`. If it drops
243
+ `code`, a sealed send that must retry on the identified path surfaces as a hard
244
+ failure instead.
245
+
246
+ The zero-knowledge profile-key credential flow
247
+ (`issueProfileKeyCredentialMutation`) registers a recipient's
248
+ unidentified-access key as a side effect. Until a recipient completes that flow,
249
+ the component rejects access-key-authorized sealed sends to them, and the client
250
+ falls back to identified delivery. Messages still arrive, but without sender
232
251
  anonymity. Deployments that want sealed sender for 1:1 messaging must drive
233
252
  the profile-key credential flow during account setup, not lazily.
234
253
 
235
254
  `identify` must return the authenticated account's real ACI, and its real PNI
236
255
  or **no PNI at all**, plus the application-owned `userId` used for relay
237
256
  routing. Never substitute a shared placeholder value for accounts without a
238
- PNI: credentials are matched by ACI-or-PNI alias, so a constant PNI issued to
239
- every account would let any authenticated user act on any PNI-addressed pending
240
- membership. An absent PNI must be absent.
257
+ PNI. The credential layer matches by ACI-or-PNI alias. A constant PNI issued to
258
+ every account would therefore let any authenticated user act on any
259
+ PNI-addressed pending membership. An absent PNI must be absent.
241
260
 
242
261
  ## Retention and rate limiting
243
262
 
@@ -247,11 +266,11 @@ minute, and stale KEM prekeys daily. Cleanup mutations delete bounded batches
247
266
  and schedule immediate continuations until the indexed range is empty.
248
267
 
249
268
  Completing a provisioning session grants the acknowledgment its own full
250
- session TTL. A link that is never acknowledged within that window is rolled
251
- back by the cron: the device it created is deleted together with all of its
252
- key material, queued messages, and heartbeats. Teardown matches the device's
253
- `linkedAt` stamp recorded at completion, so a device legitimately
254
- re-registered into a freed slot is never reaped by a stale session.
269
+ session TTL. The cron rolls back a link that nobody acknowledges within that
270
+ window. It deletes the device the link created, together with all of its key
271
+ material, queued messages, and heartbeats. Teardown matches the device's
272
+ `linkedAt` stamp recorded at completion. A stale session therefore never reaps
273
+ a device that a legitimate re-registration put into the freed slot.
255
274
 
256
275
  Prekey-bundle fetches use the mounted `@convex-dev/rate-limiter` child
257
276
  component. Each authenticated fetcher/target-account pair receives ten fetches
@@ -264,35 +283,35 @@ This version drops two shapes from the `messages` table: the optional
264
283
  `groupId` field, and `plaintext_content` from the `messageType` union.
265
284
 
266
285
  Convex validates every existing document against the new schema **during the
267
- push**, before any of your code runs. A stored row carrying a `groupId`, or
268
- one whose `messageType` is `plaintext_content`, therefore fails the deploy —
269
- and no migration mutation can fix it, because the deploy that would ship the
270
- mutation is the deploy that fails. The order has to be: clear first, deploy
271
- second.
286
+ push**, before any of your code runs. A stored row carrying a `groupId`, or one
287
+ whose `messageType` is `plaintext_content`, therefore fails the deploy. No
288
+ migration mutation can fix it, because the deploy that would ship the mutation
289
+ is the deploy that fails. The order has to be: clear first, deploy second.
272
290
 
273
291
  Messages are transient by design. The table has a seven-day TTL and an hourly
274
- cleanup cron, and undelivered messages are re-requested by clients through the
275
- retry path, so clearing it is a normal operation rather than data loss.
292
+ cleanup cron. Clients re-request undelivered messages through the retry path,
293
+ so clearing the table is a normal operation rather than data loss.
276
294
 
277
- Check whether the deployment has anything to clear — still on the previous
278
- version, since the table lives inside the component rather than the app:
295
+ Check whether the deployment has anything to clear. Run the check while the
296
+ deployment is still on the previous version, because the table lives inside the
297
+ component rather than the app:
279
298
 
280
299
  ```sh
281
300
  npx convex data messages --component signalProtocol
282
301
  ```
283
302
 
284
303
  Add `--prod` or `--deployment <name-or-reference>` to target a deployment other
285
- than your dev one. A deployment that has never relayed a group message and
286
- never had a caller pass `plaintext_content` has no affected rows and needs no
287
- action — no send path in this SDK ever produced the latter.
304
+ than your dev one. A deployment that never relayed a group message, and never
305
+ had a caller pass `plaintext_content`, has no affected rows and needs no
306
+ action. No send path in this SDK ever produced the latter.
288
307
 
289
308
  If there are rows, either wait or clear:
290
309
 
291
- - **Wait.** Stop sending, and the hourly cleanup cron drains the table as the
310
+ - **Wait**. Stop sending, and the hourly cleanup cron drains the table as the
292
311
  seven-day retention window expires. No manual step, but it takes a week.
293
- - **Clear.** In the Convex dashboard, select the `signalProtocol` component,
294
- open the `messages` table, and clear it. Undelivered messages are lost;
295
- clients re-request them over the retry path.
312
+ - **Clear**. In the Convex dashboard, select the `signalProtocol` component,
313
+ open the `messages` table, and clear it. Undelivered messages are lost.
314
+ Clients re-request them over the retry path.
296
315
 
297
316
  Deploy once the table is empty.
298
317
 
@@ -305,11 +324,16 @@ npx oe-groups trust-root
305
324
  ```
306
325
 
307
326
  Add `--prod` for the default production deployment or
308
- `--deployment <name-or-reference>` for another deployment. The command checks
309
- `OE_GROUPS_SERVER_SECRET`, generates a cryptographically random 32-byte seed
310
- only when it is absent, writes it to the selected Convex deployment through
311
- stdin, and prints two labelled base64 roots — the serialized group trust root
312
- and the Ed25519 sender-certificate root. Pin both in the client build; see
327
+ `--deployment <name-or-reference>` for another deployment. The command:
328
+
329
+ - checks `OE_GROUPS_SERVER_SECRET`
330
+ - generates a cryptographically random 32-byte seed only when the secret is
331
+ absent
332
+ - writes the seed to the selected Convex deployment through stdin
333
+ - prints two labelled base64 roots: the serialized group trust root and the
334
+ Ed25519 sender-certificate root
335
+
336
+ Pin both in the client build. See
313
337
  [Sender certificate trust root](#sender-certificate-trust-root) for where each
314
338
  one goes. Never fetch and trust either at runtime.
315
339
 
@@ -333,53 +357,56 @@ group trust root: <base64>
333
357
  sealed sender trust root: <base64>
334
358
  ```
335
359
 
336
- They are pinned in different places and are not interchangeable — the group
360
+ The two roots go in different places and are not interchangeable. The group
337
361
  trust root goes into the group configuration, and the sealed-sender root into
338
- `sealedSender.trustRoots` in the client build. Pin both at build time; never
339
- fetch either from a relay at runtime, since a relay that chooses the root it is
340
- validated against can mint certificates for any sender.
362
+ `sealedSender.trustRoots` in the client build. Pin both at build time. Never
363
+ fetch either from a relay at runtime, because a relay that chooses its own
364
+ validation root can mint certificates for any sender.
341
365
 
342
- Both are derived from the same deployment secret, so rotating
366
+ The component derives both from the same deployment secret, so rotating
343
367
  `OE_GROUPS_SERVER_SECRET` rotates both and strands clients pinned to either
344
368
  previous value.
345
369
 
346
- With `trustRoots` left empty, inbound sealed-sender validation stays disabled
347
- and sends fall back to identified delivery — messages still arrive, but the
348
- sender is disclosed to the relay.
370
+ With `trustRoots` left empty, inbound sealed-sender validation stays disabled,
371
+ and sends fall back to identified delivery. Messages still arrive, but they
372
+ disclose the sender to the relay.
349
373
 
350
374
  ## Group metadata privacy
351
375
 
352
- The relay cannot read message contents, cannot derive membership from group
353
- state, and no longer sees a group identifier on the two channels that used to
354
- carry one.
376
+ The relay cannot read message contents and cannot derive membership from group
377
+ state. It also no longer sees a group identifier on the two channels that used
378
+ to carry one.
355
379
 
356
- **Closed: the distribution identifier in the frame.** The identified send path
380
+ **Closed: the distribution identifier in the frame**. The identified send path
357
381
  stores the framed `SenderKeyMessage` as its `ciphertext`, and that frame's
358
382
  `distributionUuid` is **not** encrypted. It used to embed
359
- `groupId:senderUserId:senderDeviceId:timestamp`, so the group and the sender's
360
- device were readable straight out of the ciphertext column — and, worse than a
361
- column, off every message in flight to any relay on the path. Sealed sender did
362
- not help: it hides the frame from the relay but not from the rest of the path,
363
- and it is disabled until the trust root is exported (see above), so group
364
- traffic takes the identified path anyway. Distribution identifiers are now
365
- opaque random UUIDs carrying no group, sender, device, or clock, as the
366
- reference implementation uses, as the sender-keys specification now requires.
367
-
368
- **Closed: the `groupId` column.** Every `messages` row used to store a plaintext
383
+ `groupId:senderUserId:senderDeviceId:timestamp`. The group and the sender's
384
+ device were therefore readable straight out of the ciphertext column. Worse
385
+ than a column, they were readable off every message in flight to any relay on
386
+ the path.
387
+
388
+ Sealed sender did not help. It hides the frame from the relay, but not from the
389
+ rest of the path. The component also keeps sealed sender disabled until you
390
+ export the trust root (see above), so group traffic takes the identified path
391
+ anyway. Distribution identifiers are now opaque random UUIDs carrying no group,
392
+ sender, device, or clock, as the reference implementation uses, as the
393
+ sender-keys specification now requires.
394
+
395
+ **Closed: the `groupId` column**. Every `messages` row used to store a plaintext
369
396
  `groupId` next to `targetUserId` for the seven-day retention window. The column
370
- is gone. What replaces it is a `sender_key` message type, which tells the
371
- receiver to decrypt the payload as a framed `SenderKeyMessage` and nothing more:
372
- the receiver reads the opaque distribution identifier out of the frame and
373
- resolves the group against its own sender key store. No group identifier
397
+ is gone, and a `sender_key` message type replaces it. The type tells the
398
+ receiver to decrypt the payload as a framed `SenderKeyMessage` and nothing
399
+ more. The receiver reads the opaque distribution identifier out of the frame
400
+ and resolves the group against its own sender key store. No group identifier
374
401
  travels on an envelope, sealed or not.
375
402
 
376
- **Open: the group partition itself.** Removing the identifier removed the
403
+ **Open: the group partition itself**. Removing the identifier removed the
377
404
  group's *name*, not the ability to group rows. Be precise about what is left,
378
405
  because the difference matters and it is easy to overstate:
379
406
 
380
- - The frame's `distributionUuid` is unencrypted and is stored verbatim inside
381
- `messages.ciphertext` — the paragraph above says as much. It is opaque, but
382
- it is stable for the life of a sender key, and nothing rotates keys on a
407
+ - The frame leaves `distributionUuid` unencrypted, and the row stores it
408
+ verbatim inside `messages.ciphertext`. The paragraph above says as much. It
409
+ is opaque, but stable for the life of a sender key. Nothing rotates keys on a
383
410
  timer. Grouping rows by it recovers the recipient set for a sender's group
384
411
  traffic.
385
412
  - Sender keys encrypt once and fan out, so every recipient row of one send
@@ -388,17 +415,18 @@ because the difference matters and it is easy to overstate:
388
415
  - The fan-out stamps one `timestamp` across every recipient row, and passes
389
416
  through one `clientMessageId` when the application supplies one.
390
417
  - `sendMultiRecipientUnidentified` hands the relay the roster explicitly, in
391
- one call — the sealed-sender path names the recipient set outright.
418
+ one call. The sealed-sender path names the recipient set outright.
392
419
 
393
420
  So the relay cannot learn *which* group, or its name, membership list, or
394
- attributes — but it can still partition delivery pairs into unlabeled groups,
395
- and any one of those channels suffices. That is a real improvement on a
396
- plaintext `groupId`, which handed over a stable, meaningful, cross-send label;
397
- it is not anonymity of the partition. The `sender_key` type is also a
398
- single-column filter isolating group traffic from pairwise traffic, which the
399
- old design did not offer — group messages used to hide among `ciphertext` rows.
400
-
401
- **Still visible.** Delivery metadata itself: who sent to whom, when, and how
421
+ attributes. It can still partition delivery pairs into unlabeled groups, and
422
+ any one of those channels suffices. That is a real improvement on a plaintext
423
+ `groupId`, which handed over a stable, meaningful, cross-send label. It is not
424
+ anonymity of the partition. The `sender_key` type is also a single-column
425
+ filter that isolates group traffic from pairwise traffic. The old design did
426
+ not offer that filter, because group messages used to hide among `ciphertext`
427
+ rows.
428
+
429
+ **Still visible**. Delivery metadata itself: who sent to whom, when, and how
402
430
  much. Every relay sees this. Sealed sender removes the sender from the
403
431
  identified half of it.
404
432
 
@@ -406,18 +434,20 @@ identified half of it.
406
434
 
407
435
  `identify` maps an authenticated session to an account (`userId`), with no
408
436
  device. Every account-scoped endpoint therefore authorizes at account
409
- granularity, and the `deviceId` arguments are routing selectors chosen by the
410
- caller rather than authenticated claims. Concretely, any session for an account
411
- can read and delete **any** of that account's device queues
412
- (`getPendingMessages`, `markDelivered`), send as any of its device IDs
413
- (`send.senderDeviceId`), and upload or rotate key material for any of its
414
- devices (`keys`).
415
-
416
- This is the intended model — a compromised session already holds the account —
417
- but it means the component provides no isolation *between* an account's own
418
- devices. Deployments that need device isolation must issue device-scoped
419
- sessions and enforce the binding in their own `identify` wrapper; the component
420
- cannot do it while its identity has no device field.
437
+ granularity, and the caller chooses each `deviceId` argument as a route
438
+ selector rather than an authenticated claim. Concretely, any session for an
439
+ account can:
440
+
441
+ - read and delete **any** of that account's device queues
442
+ (`getPendingMessages`, `markDelivered`)
443
+ - send as any of its device IDs (`send.senderDeviceId`)
444
+ - upload or rotate key material for any of its devices (`keys`)
445
+
446
+ This is the intended model, because a compromised session already holds the
447
+ account. It does mean that the component provides no isolation *between* an
448
+ account's own devices. Deployments that need device isolation must issue
449
+ device-scoped sessions and enforce the binding in their own `identify` wrapper.
450
+ The component cannot do it while its identity has no device field.
421
451
 
422
452
  ## Profile-key issuance threat model
423
453
 
@@ -3,7 +3,8 @@
3
3
  `InMemorySignalProtocolRelayServer` implements `ISignalProtocolRelayServer` in memory for examples
4
4
  and local application development.
5
5
 
6
- Real protocol and cryptography; simulated in-memory infrastructure.
6
+ The protocol and cryptography are real. The adapter simulates the
7
+ infrastructure in memory.
7
8
 
8
9
  ## Why it exists
9
10
 
@@ -13,6 +14,7 @@ authorization or durability boundary.
13
14
 
14
15
  ## Usage
15
16
 
17
+ <!-- doc-snippet:run memory-relay-client expect="" -->
16
18
  ```ts
17
19
  // Real protocol and cryptography; simulated in-memory infrastructure.
18
20
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
@@ -29,14 +31,15 @@ await client.syncToServer();
29
31
  ```
30
32
 
31
33
  All registered devices, public keys, mailboxes, and provisioning state disappear
32
- with the adapter. It performs no real account authentication, rate limiting,
33
- abuse prevention, or durable delivery and must not be used in production.
34
+ with the adapter. It does not authenticate accounts, limit rates, prevent
35
+ abuse, or deliver durably. Never use it in production.
34
36
 
35
37
  ## Deterministic failure and recovery exercises
36
38
 
37
39
  Failure mode is opt-in and seeded. The default `inMemoryRelay()` remains the
38
40
  deterministic happy path:
39
41
 
42
+ <!-- doc-snippet:run memory-relay-failure-injection expect="" -->
40
43
  ```ts
41
44
  // Real protocol and cryptography; simulated in-memory infrastructure.
42
45
  import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
@@ -61,8 +64,8 @@ relay.failures.reconnect("bob", 1);
61
64
  a scenario without rebuilding clients. Authorization rejection raises
62
65
  `SealedSenderAuthError`, allowing the client's documented identified-delivery
63
66
  fallback. One-time-prekey exhaustion withholds both EC and KEM one-time keys but
64
- keeps the KEM last-resort key, so strict-PQ examples exercise the intended
65
- post-quantum recovery path rather than a silent classical downgrade. Failure
67
+ keeps the KEM last-resort key. Strict-PQ examples therefore exercise the
68
+ intended post-quantum recovery path rather than a silent classical downgrade. Failure
66
69
  selection uses the configured seed and delivery count, never `Math.random()` or
67
70
  wall-clock time.
68
71
 
package/safety/README.md CHANGED
@@ -12,6 +12,7 @@ decision.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import { generateCompositeSafetyNumber } from "@open-e2ee/signal-protocol-sdk/safety";
17
18
 
@@ -35,7 +36,7 @@ Use the composite safety-number API for contact verification in this SDK
35
36
  profile. The single-key helper is a lower-level reference primitive and does
36
37
  not authenticate the complete composite identity.
37
38
 
38
- The SDK creates comparison data; the application owns QR rendering, scanning,
39
+ The SDK creates comparison data. The application owns QR rendering, scanning,
39
40
  the verification user experience, and storage of the user's trust decision.
40
41
 
41
42
  See the [keys guide](../keys/README.md) and
@@ -6,11 +6,13 @@ that support authenticated sender-anonymous envelope delivery.
6
6
  ## Why it exists
7
7
 
8
8
  A relay may need to authorize delivery without learning sender identity from
9
- the outer request. The access key is derived from profile-key material and can
10
- be presented through the relay's sealed-sender authorization contract.
9
+ the outer request. The module derives the access key from profile-key material.
10
+ A sender can present it through the relay's sealed-sender authorization
11
+ contract.
11
12
 
12
13
  ## Usage
13
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
14
16
  ```ts
15
17
  import {
16
18
  ACCESS_KEY_BYTES,
package/types/README.md CHANGED
@@ -12,6 +12,7 @@ contracts they validate.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import type {
17
18
  ISignalProtocolLocalStore,
@@ -25,7 +26,7 @@ const address = ProtocolAddress.create("bob", 1);
25
26
  const encodedKey = asBase64(valueFromValidatedStorage);
26
27
  ```
27
28
 
28
- TypeScript brands document validated representation; they do not validate at
29
+ TypeScript brands document validated representation. They do not validate at
29
30
  runtime by themselves. Use the provided validators or validate at the
30
31
  untrusted boundary before applying a brand.
31
32
 
@@ -11,6 +11,7 @@ helps applications avoid treating display text as a stable account identifier.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import {
16
17
  formatUsername,
package/utils/README.md CHANGED
@@ -11,6 +11,7 @@ internals.
11
11
 
12
12
  ## Retry usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import {
16
17
  isRetryableError,
@@ -26,11 +27,11 @@ const bundle = await withRetry(
26
27
  );
27
28
  ```
28
29
 
29
- `withRetry()` uses bounded exponential backoff with optional jitter. Known
30
- protocol and identity failures are not retried; transient network, timeout,
31
- database-lock, and concurrency failures are.
30
+ `withRetry()` uses bounded exponential backoff with optional jitter. It does not
31
+ retry known protocol and identity failures. It does retry transient network,
32
+ timeout, database-lock, and concurrency failures.
32
33
 
33
- Retrying is only safe when the operation is read-only or idempotent. The caller
34
+ Retry only a read-only or idempotent operation. The caller
34
35
  must not wrap an arbitrary mutation without an idempotency contract.
35
36
 
36
37
  See the [error-handling guide](../docs/ERROR_HANDLING.md) and
package/zk/README.md CHANGED
@@ -12,6 +12,7 @@ group secrets and profile keys on the service.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import {
17
18
  computeProfileKeyVersion,