@open-e2ee/signal-protocol-sdk 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (601) hide show
  1. package/ADAPTERS.md +4 -4
  2. package/ARCHITECTURE.md +17 -16
  3. package/CHANGELOG.md +49 -0
  4. package/COMMERCIAL.md +6 -6
  5. package/NOTICE +1 -1
  6. package/README.md +44 -34
  7. package/SECURITY.md +16 -13
  8. package/TROUBLESHOOTING.md +5 -5
  9. package/blocking/README.md +6 -5
  10. package/client/README.md +5 -5
  11. package/device/README.md +8 -8
  12. package/dist/blocking/types.d.ts +2 -2
  13. package/dist/blocking/types.js +2 -2
  14. package/dist/client/client.d.ts +46 -45
  15. package/dist/client/client.d.ts.map +1 -1
  16. package/dist/client/client.js +61 -60
  17. package/dist/client/client.js.map +1 -1
  18. package/dist/client/config.d.ts +32 -32
  19. package/dist/client/constants.d.ts +7 -6
  20. package/dist/client/constants.d.ts.map +1 -1
  21. package/dist/client/constants.js +5 -4
  22. package/dist/client/constants.js.map +1 -1
  23. package/dist/client/dual-store.d.ts +2 -2
  24. package/dist/client/dual-store.js +2 -2
  25. package/dist/client/endorsement-manager.d.ts +14 -14
  26. package/dist/client/endorsement-manager.d.ts.map +1 -1
  27. package/dist/client/endorsement-manager.js +15 -15
  28. package/dist/client/endorsement-manager.js.map +1 -1
  29. package/dist/client/event-hooks.d.ts +16 -16
  30. package/dist/client/event-hooks.d.ts.map +1 -1
  31. package/dist/client/event-hooks.js +1 -1
  32. package/dist/client/event-hooks.js.map +1 -1
  33. package/dist/client/files.js +4 -4
  34. package/dist/client/files.js.map +1 -1
  35. package/dist/client/headless.d.ts +7 -7
  36. package/dist/client/headless.d.ts.map +1 -1
  37. package/dist/client/headless.js +4 -4
  38. package/dist/client/key-rotation-core.d.ts +19 -17
  39. package/dist/client/key-rotation-core.d.ts.map +1 -1
  40. package/dist/client/key-rotation-core.js +35 -31
  41. package/dist/client/key-rotation-core.js.map +1 -1
  42. package/dist/client/key-rotation.d.ts +8 -8
  43. package/dist/client/key-rotation.js +8 -8
  44. package/dist/client/media.d.ts +1 -1
  45. package/dist/client/messages.d.ts.map +1 -1
  46. package/dist/client/messages.js +13 -11
  47. package/dist/client/messages.js.map +1 -1
  48. package/dist/client/multi-device.d.ts +5 -4
  49. package/dist/client/multi-device.d.ts.map +1 -1
  50. package/dist/client/multi-device.js.map +1 -1
  51. package/dist/client/prekeys.d.ts +7 -7
  52. package/dist/client/prekeys.js +10 -10
  53. package/dist/client/prekeys.js.map +1 -1
  54. package/dist/client/relay-subscription.d.ts +3 -0
  55. package/dist/client/relay-subscription.d.ts.map +1 -1
  56. package/dist/client/relay-subscription.js +7 -4
  57. package/dist/client/relay-subscription.js.map +1 -1
  58. package/dist/client/retry-utils.d.ts +5 -6
  59. package/dist/client/retry-utils.d.ts.map +1 -1
  60. package/dist/client/retry-utils.js +5 -12
  61. package/dist/client/retry-utils.js.map +1 -1
  62. package/dist/client/retry.js +7 -7
  63. package/dist/client/retry.js.map +1 -1
  64. package/dist/client/sealed-sender-ops.d.ts +3 -3
  65. package/dist/client/sealed-sender-ops.js +5 -5
  66. package/dist/client/sealed-sender-ops.js.map +1 -1
  67. package/dist/client/sessions.d.ts +2 -2
  68. package/dist/client/sessions.js +2 -2
  69. package/dist/client/signal-service-cipher.d.ts +9 -9
  70. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  71. package/dist/client/signal-service-cipher.js +41 -40
  72. package/dist/client/signal-service-cipher.js.map +1 -1
  73. package/dist/client/state.d.ts +1 -1
  74. package/dist/client/state.js +1 -1
  75. package/dist/client/types.d.ts +19 -19
  76. package/dist/client/types.d.ts.map +1 -1
  77. package/dist/device/connection.d.ts +1 -1
  78. package/dist/device/connection.js +2 -2
  79. package/dist/device/connection.js.map +1 -1
  80. package/dist/device/constants.d.ts +4 -4
  81. package/dist/device/constants.js +3 -3
  82. package/dist/device/device-id.d.ts +4 -4
  83. package/dist/device/device-id.js +4 -4
  84. package/dist/device/expo-metadata.d.ts +13 -11
  85. package/dist/device/expo-metadata.d.ts.map +1 -1
  86. package/dist/device/expo-metadata.js +13 -11
  87. package/dist/device/expo-metadata.js.map +1 -1
  88. package/dist/device/lifecycle/manager.d.ts +6 -6
  89. package/dist/device/lifecycle/manager.js +7 -7
  90. package/dist/device/lifecycle/types.d.ts +13 -13
  91. package/dist/device/lifecycle/types.d.ts.map +1 -1
  92. package/dist/device/lifecycle/utils.d.ts +2 -2
  93. package/dist/device/lifecycle/utils.js +5 -5
  94. package/dist/device/lifecycle/utils.js.map +1 -1
  95. package/dist/device/provisioning.d.ts +5 -4
  96. package/dist/device/provisioning.d.ts.map +1 -1
  97. package/dist/device/provisioning.js +5 -4
  98. package/dist/device/provisioning.js.map +1 -1
  99. package/dist/device/transfer.d.ts +2 -2
  100. package/dist/device/transfer.js +3 -3
  101. package/dist/device/transfer.js.map +1 -1
  102. package/dist/encoding/index.d.ts +3 -4
  103. package/dist/encoding/index.d.ts.map +1 -1
  104. package/dist/encoding/index.js.map +1 -1
  105. package/dist/files/index.d.ts +1 -1
  106. package/dist/files/index.js +1 -1
  107. package/dist/hooks/use-connection-presence.d.ts +1 -1
  108. package/dist/hooks/use-connection-presence.js +7 -7
  109. package/dist/hooks/use-connection-presence.js.map +1 -1
  110. package/dist/hooks/use-group-membership.d.ts +2 -2
  111. package/dist/hooks/use-group-membership.d.ts.map +1 -1
  112. package/dist/hooks/use-group-membership.js +6 -6
  113. package/dist/hooks/use-group-membership.js.map +1 -1
  114. package/dist/hooks/use-key-rotation.js +3 -3
  115. package/dist/hooks/use-key-rotation.js.map +1 -1
  116. package/dist/hooks/use-single-flight.d.ts +2 -2
  117. package/dist/hooks/use-single-flight.js +1 -1
  118. package/dist/index.d.ts +4 -3
  119. package/dist/index.d.ts.map +1 -1
  120. package/dist/index.js +22 -4
  121. package/dist/index.js.map +1 -1
  122. package/dist/internal/crypto/ec/ed25519.d.ts +6 -6
  123. package/dist/internal/crypto/ec/ed25519.js +6 -6
  124. package/dist/internal/crypto/ec/x25519-validation.d.ts.map +1 -1
  125. package/dist/internal/crypto/ec/x25519-validation.js +4 -2
  126. package/dist/internal/crypto/ec/x25519-validation.js.map +1 -1
  127. package/dist/internal/crypto/index.d.ts +2 -0
  128. package/dist/internal/crypto/index.d.ts.map +1 -1
  129. package/dist/internal/crypto/index.js +2 -0
  130. package/dist/internal/crypto/index.js.map +1 -1
  131. package/dist/internal/crypto/kdf/hkdf.d.ts +9 -8
  132. package/dist/internal/crypto/kdf/hkdf.d.ts.map +1 -1
  133. package/dist/internal/crypto/kdf/hkdf.js +11 -10
  134. package/dist/internal/crypto/kdf/hkdf.js.map +1 -1
  135. package/dist/internal/crypto/key-prefix.d.ts +3 -3
  136. package/dist/internal/crypto/key-prefix.js +3 -3
  137. package/dist/internal/crypto/pq/kyber.d.ts +7 -7
  138. package/dist/internal/crypto/pq/kyber.js +10 -10
  139. package/dist/internal/crypto/pq/kyber.js.map +1 -1
  140. package/dist/internal/crypto/random.d.ts +1 -1
  141. package/dist/internal/crypto/random.js +1 -1
  142. package/dist/internal/crypto/symmetric/aes-gcm-siv.js +1 -1
  143. package/dist/internal/crypto/symmetric/aes.js +4 -4
  144. package/dist/internal/crypto/symmetric/aes.js.map +1 -1
  145. package/dist/internal/crypto/symmetric/mac.d.ts +1 -1
  146. package/dist/internal/crypto/symmetric/mac.js +3 -3
  147. package/dist/internal/crypto/symmetric/padding.js +1 -1
  148. package/dist/internal/crypto/symmetric/padding.js.map +1 -1
  149. package/dist/internal/crypto/symmetric/streaming-aead.d.ts +7 -1
  150. package/dist/internal/crypto/symmetric/streaming-aead.d.ts.map +1 -1
  151. package/dist/internal/crypto/symmetric/streaming-aead.js +10 -4
  152. package/dist/internal/crypto/symmetric/streaming-aead.js.map +1 -1
  153. package/dist/internal/crypto/utils.d.ts +2 -2
  154. package/dist/internal/crypto/utils.d.ts.map +1 -1
  155. package/dist/internal/crypto/utils.js +16 -14
  156. package/dist/internal/crypto/utils.js.map +1 -1
  157. package/dist/internal/crypto/validation.d.ts +4 -4
  158. package/dist/internal/crypto/validation.js +2 -2
  159. package/dist/internal/encoding/proto/envelope.d.ts +1 -1
  160. package/dist/internal/encoding/proto/envelope.js +1 -1
  161. package/dist/internal/encoding/proto/index.d.ts +4 -4
  162. package/dist/internal/encoding/proto/index.js +4 -4
  163. package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts +28 -16
  164. package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts.map +1 -1
  165. package/dist/internal/encoding/proto/pq-ratchet-serialize.js +30 -18
  166. package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
  167. package/dist/internal/encoding/proto/primitives.d.ts +45 -35
  168. package/dist/internal/encoding/proto/primitives.d.ts.map +1 -1
  169. package/dist/internal/encoding/proto/primitives.js +54 -43
  170. package/dist/internal/encoding/proto/primitives.js.map +1 -1
  171. package/dist/internal/encoding/proto/sender-key-message.d.ts +2 -2
  172. package/dist/internal/encoding/proto/sender-key-message.js +2 -2
  173. package/dist/internal/encoding/proto/signal-message.d.ts +13 -13
  174. package/dist/internal/encoding/proto/signal-message.d.ts.map +1 -1
  175. package/dist/internal/encoding/proto/signal-message.js +13 -13
  176. package/dist/internal/encoding/proto/signal-message.js.map +1 -1
  177. package/dist/internal/groups/access-control.d.ts +5 -5
  178. package/dist/internal/groups/access-control.js +6 -6
  179. package/dist/internal/groups/access-control.js.map +1 -1
  180. package/dist/internal/groups/change-actions.d.ts +4 -4
  181. package/dist/internal/groups/change-actions.js +3 -3
  182. package/dist/internal/groups/encrypted-state.js +1 -1
  183. package/dist/internal/groups/encrypted-state.js.map +1 -1
  184. package/dist/internal/groups/group-id.d.ts +1 -1
  185. package/dist/internal/groups/manager.d.ts +24 -23
  186. package/dist/internal/groups/manager.d.ts.map +1 -1
  187. package/dist/internal/groups/manager.js +40 -36
  188. package/dist/internal/groups/manager.js.map +1 -1
  189. package/dist/internal/groups/server-engine.d.ts +29 -21
  190. package/dist/internal/groups/server-engine.d.ts.map +1 -1
  191. package/dist/internal/groups/server-engine.js +55 -50
  192. package/dist/internal/groups/server-engine.js.map +1 -1
  193. package/dist/internal/groups/trust-root.d.ts +2 -2
  194. package/dist/internal/groups/trust-root.js +2 -2
  195. package/dist/internal/groups/types.d.ts +4 -4
  196. package/dist/internal/groups/types.d.ts.map +1 -1
  197. package/dist/internal/groups/wire.d.ts +6 -7
  198. package/dist/internal/groups/wire.d.ts.map +1 -1
  199. package/dist/internal/groups/wire.js +6 -7
  200. package/dist/internal/groups/wire.js.map +1 -1
  201. package/dist/internal/manager/manager.d.ts +14 -12
  202. package/dist/internal/manager/manager.d.ts.map +1 -1
  203. package/dist/internal/manager/manager.js +47 -41
  204. package/dist/internal/manager/manager.js.map +1 -1
  205. package/dist/internal/protocol/double-ratchet/chains.d.ts +8 -6
  206. package/dist/internal/protocol/double-ratchet/chains.d.ts.map +1 -1
  207. package/dist/internal/protocol/double-ratchet/chains.js +10 -8
  208. package/dist/internal/protocol/double-ratchet/chains.js.map +1 -1
  209. package/dist/internal/protocol/double-ratchet/index.d.ts +2 -2
  210. package/dist/internal/protocol/double-ratchet/index.js +2 -2
  211. package/dist/internal/protocol/double-ratchet/ratchet.d.ts +4 -4
  212. package/dist/internal/protocol/double-ratchet/ratchet.js +6 -6
  213. package/dist/internal/protocol/pqxdh/pqxdh.d.ts +21 -18
  214. package/dist/internal/protocol/pqxdh/pqxdh.d.ts.map +1 -1
  215. package/dist/internal/protocol/pqxdh/pqxdh.js +48 -42
  216. package/dist/internal/protocol/pqxdh/pqxdh.js.map +1 -1
  217. package/dist/internal/protocol/sealed-sender/decryption-v2.js +5 -5
  218. package/dist/internal/protocol/sealed-sender/decryption-v2.js.map +1 -1
  219. package/dist/internal/protocol/sealed-sender/decryption.d.ts.map +1 -1
  220. package/dist/internal/protocol/sealed-sender/decryption.js +11 -8
  221. package/dist/internal/protocol/sealed-sender/decryption.js.map +1 -1
  222. package/dist/internal/protocol/sealed-sender/delivery-token.d.ts +2 -2
  223. package/dist/internal/protocol/sealed-sender/delivery-token.js +2 -2
  224. package/dist/internal/protocol/sealed-sender/encryption-v2.js +1 -1
  225. package/dist/internal/protocol/sealed-sender/encryption-v2.js.map +1 -1
  226. package/dist/internal/protocol/sealed-sender/encryption.d.ts +2 -2
  227. package/dist/internal/protocol/sealed-sender/encryption.js +2 -2
  228. package/dist/internal/protocol/sealed-sender/proto/index.d.ts +25 -23
  229. package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
  230. package/dist/internal/protocol/sealed-sender/proto/index.js +32 -30
  231. package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
  232. package/dist/internal/protocol/sealed-sender/trust-root.d.ts +10 -9
  233. package/dist/internal/protocol/sealed-sender/trust-root.d.ts.map +1 -1
  234. package/dist/internal/protocol/sealed-sender/trust-root.js +10 -9
  235. package/dist/internal/protocol/sealed-sender/trust-root.js.map +1 -1
  236. package/dist/internal/protocol/sealed-sender/types.d.ts +13 -14
  237. package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
  238. package/dist/internal/protocol/sealed-sender/types.js +7 -8
  239. package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
  240. package/dist/internal/protocol/sealed-sender/v2-binary.d.ts +1 -1
  241. package/dist/internal/protocol/sealed-sender/v2-binary.js +2 -2
  242. package/dist/internal/protocol/sealed-sender/v2-binary.js.map +1 -1
  243. package/dist/internal/protocol/sender-keys/manager.d.ts +16 -14
  244. package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
  245. package/dist/internal/protocol/sender-keys/manager.js +37 -34
  246. package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
  247. package/dist/internal/protocol/spqr/braid-serialize.d.ts +6 -6
  248. package/dist/internal/protocol/spqr/braid-serialize.js +5 -5
  249. package/dist/internal/protocol/spqr/braid-serialize.js.map +1 -1
  250. package/dist/internal/protocol/spqr/braid.d.ts +3 -3
  251. package/dist/internal/protocol/spqr/braid.js +7 -7
  252. package/dist/internal/protocol/spqr/braid.js.map +1 -1
  253. package/dist/internal/protocol/spqr/index.js +1 -1
  254. package/dist/internal/protocol/spqr/index.js.map +1 -1
  255. package/dist/internal/protocol/spqr/ml-kem-braid/chunk-domain.d.ts +3 -3
  256. package/dist/internal/protocol/spqr/ml-kem-braid/chunk-domain.js +3 -3
  257. package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js +1 -1
  258. package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js.map +1 -1
  259. package/dist/internal/protocol/spqr/ml-kem-braid/kdf.d.ts +1 -1
  260. package/dist/internal/protocol/spqr/ml-kem-braid/kdf.js +1 -1
  261. package/dist/internal/protocol/spqr/ml-kem-braid/kdf.js.map +1 -1
  262. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.d.ts +4 -3
  263. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.d.ts.map +1 -1
  264. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.js +4 -3
  265. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.js.map +1 -1
  266. package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/index.js +2 -2
  267. package/dist/internal/protocol/spqr/ml-kem-braid/progress.d.ts +1 -1
  268. package/dist/internal/protocol/spqr/ml-kem-braid/progress.js +1 -1
  269. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts +15 -7
  270. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
  271. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js +15 -7
  272. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js.map +1 -1
  273. package/dist/internal/protocol/spqr/ml-kem-braid/rs/galois/field.js +1 -1
  274. package/dist/internal/protocol/spqr/ml-kem-braid/rs/polynomial.d.ts +3 -3
  275. package/dist/internal/protocol/spqr/ml-kem-braid/rs/polynomial.js +1 -1
  276. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts +7 -7
  277. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js +11 -11
  278. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js.map +1 -1
  279. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.d.ts +1 -1
  280. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js +6 -6
  281. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js.map +1 -1
  282. package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts +2 -2
  283. package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts.map +1 -1
  284. package/dist/internal/protocol/spqr/ml-kem-braid/types.js.map +1 -1
  285. package/dist/internal/protocol/spqr/serialize.d.ts +12 -12
  286. package/dist/internal/protocol/spqr/serialize.js +5 -5
  287. package/dist/internal/protocol/spqr/spqr.d.ts +6 -6
  288. package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
  289. package/dist/internal/protocol/spqr/spqr.js +47 -42
  290. package/dist/internal/protocol/spqr/spqr.js.map +1 -1
  291. package/dist/internal/protocol/spqr/validate.d.ts +1 -1
  292. package/dist/internal/protocol/triple-ratchet/ratchet.d.ts +12 -12
  293. package/dist/internal/protocol/triple-ratchet/ratchet.d.ts.map +1 -1
  294. package/dist/internal/protocol/triple-ratchet/ratchet.js +11 -11
  295. package/dist/internal/protocol/triple-ratchet/ratchet.js.map +1 -1
  296. package/dist/internal/protocol/username/hash.d.ts.map +1 -1
  297. package/dist/internal/protocol/username/hash.js +6 -4
  298. package/dist/internal/protocol/username/hash.js.map +1 -1
  299. package/dist/internal/protocol/version.d.ts +3 -3
  300. package/dist/internal/protocol/version.js +1 -1
  301. package/dist/internal/protocol/x3dh/x3dh.d.ts +16 -16
  302. package/dist/internal/protocol/x3dh/x3dh.d.ts.map +1 -1
  303. package/dist/internal/protocol/x3dh/x3dh.js +15 -15
  304. package/dist/internal/protocol/x3dh/x3dh.js.map +1 -1
  305. package/dist/internal/protocol/zk/credentials/attributes.d.ts +7 -7
  306. package/dist/internal/protocol/zk/credentials/attributes.js +7 -7
  307. package/dist/internal/protocol/zk/credentials/credentials.d.ts +1 -1
  308. package/dist/internal/protocol/zk/credentials/credentials.js +1 -1
  309. package/dist/internal/protocol/zk/credentials/endorsements.d.ts +11 -11
  310. package/dist/internal/protocol/zk/credentials/endorsements.js +14 -14
  311. package/dist/internal/protocol/zk/credentials/issuance.d.ts +5 -1
  312. package/dist/internal/protocol/zk/credentials/issuance.d.ts.map +1 -1
  313. package/dist/internal/protocol/zk/credentials/issuance.js +5 -1
  314. package/dist/internal/protocol/zk/credentials/issuance.js.map +1 -1
  315. package/dist/internal/protocol/zk/credentials/presentation.d.ts +16 -16
  316. package/dist/internal/protocol/zk/credentials/presentation.d.ts.map +1 -1
  317. package/dist/internal/protocol/zk/credentials/presentation.js +18 -18
  318. package/dist/internal/protocol/zk/credentials/presentation.js.map +1 -1
  319. package/dist/internal/protocol/zk/groups/auth-credential.d.ts +22 -16
  320. package/dist/internal/protocol/zk/groups/auth-credential.d.ts.map +1 -1
  321. package/dist/internal/protocol/zk/groups/auth-credential.js +19 -14
  322. package/dist/internal/protocol/zk/groups/auth-credential.js.map +1 -1
  323. package/dist/internal/protocol/zk/groups/client-zk-group-cipher.d.ts +4 -4
  324. package/dist/internal/protocol/zk/groups/client-zk-group-cipher.js +4 -4
  325. package/dist/internal/protocol/zk/groups/group-params.d.ts +2 -2
  326. package/dist/internal/protocol/zk/groups/group-params.js +2 -2
  327. package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts +10 -9
  328. package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts.map +1 -1
  329. package/dist/internal/protocol/zk/groups/group-send-endorsement.js +9 -8
  330. package/dist/internal/protocol/zk/groups/group-send-endorsement.js.map +1 -1
  331. package/dist/internal/protocol/zk/groups/lizard.d.ts +1 -1
  332. package/dist/internal/protocol/zk/groups/lizard.js +4 -4
  333. package/dist/internal/protocol/zk/groups/lizard.js.map +1 -1
  334. package/dist/internal/protocol/zk/groups/profile-key-commitment.d.ts +3 -3
  335. package/dist/internal/protocol/zk/groups/profile-key-commitment.js +3 -3
  336. package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts +11 -11
  337. package/dist/internal/protocol/zk/groups/profile-key-credential.js +7 -7
  338. package/dist/internal/protocol/zk/groups/profile-key-encryption.d.ts +2 -2
  339. package/dist/internal/protocol/zk/groups/profile-key-encryption.js +2 -2
  340. package/dist/internal/protocol/zk/groups/profile-key-struct.d.ts +2 -2
  341. package/dist/internal/protocol/zk/groups/profile-key-struct.js +2 -2
  342. package/dist/internal/protocol/zk/groups/profile-key-version.d.ts +2 -2
  343. package/dist/internal/protocol/zk/groups/profile-key-version.js +2 -2
  344. package/dist/internal/protocol/zk/groups/server-params.d.ts +1 -1
  345. package/dist/internal/protocol/zk/groups/server-params.js +1 -1
  346. package/dist/internal/protocol/zk/groups/uid-encryption.d.ts +4 -4
  347. package/dist/internal/protocol/zk/groups/uid-encryption.js +4 -4
  348. package/dist/internal/protocol/zk/groups/uid-struct.d.ts +2 -2
  349. package/dist/internal/protocol/zk/groups/uid-struct.js +3 -3
  350. package/dist/internal/protocol/zk/groups/uid-struct.js.map +1 -1
  351. package/dist/internal/protocol/zk/proofs/args.d.ts +3 -3
  352. package/dist/internal/protocol/zk/proofs/args.js +3 -3
  353. package/dist/internal/protocol/zk/proofs/sho-sha256.d.ts +3 -3
  354. package/dist/internal/protocol/zk/proofs/sho-sha256.js +3 -3
  355. package/dist/internal/protocol/zk/proofs/sho.d.ts +8 -7
  356. package/dist/internal/protocol/zk/proofs/sho.d.ts.map +1 -1
  357. package/dist/internal/protocol/zk/proofs/sho.js +8 -7
  358. package/dist/internal/protocol/zk/proofs/sho.js.map +1 -1
  359. package/dist/internal/protocol/zk/proofs/statement.d.ts +8 -6
  360. package/dist/internal/protocol/zk/proofs/statement.d.ts.map +1 -1
  361. package/dist/internal/protocol/zk/proofs/statement.js +8 -6
  362. package/dist/internal/protocol/zk/proofs/statement.js.map +1 -1
  363. package/dist/internal/sesame/manager.d.ts +23 -19
  364. package/dist/internal/sesame/manager.d.ts.map +1 -1
  365. package/dist/internal/sesame/manager.js +64 -54
  366. package/dist/internal/sesame/manager.js.map +1 -1
  367. package/dist/internal/sesame/types.d.ts +28 -25
  368. package/dist/internal/sesame/types.d.ts.map +1 -1
  369. package/dist/internal/sesame/types.js +2 -2
  370. package/dist/internal/sesame/types.js.map +1 -1
  371. package/dist/internal/sesame/validation.d.ts +2 -2
  372. package/dist/internal/sesame/validation.js +3 -3
  373. package/dist/internal/sesame/validation.js.map +1 -1
  374. package/dist/internal/session/builder.d.ts +8 -8
  375. package/dist/internal/session/builder.js +22 -22
  376. package/dist/internal/session/builder.js.map +1 -1
  377. package/dist/internal/session/cipher.d.ts +3 -3
  378. package/dist/internal/session/cipher.d.ts.map +1 -1
  379. package/dist/internal/session/cipher.js +51 -40
  380. package/dist/internal/session/cipher.js.map +1 -1
  381. package/dist/internal/session/decryption.js +11 -9
  382. package/dist/internal/session/decryption.js.map +1 -1
  383. package/dist/internal/session/factory.js +1 -1
  384. package/dist/internal/session/factory.js.map +1 -1
  385. package/dist/internal/session/handshake.d.ts +4 -4
  386. package/dist/internal/session/handshake.js +4 -4
  387. package/dist/internal/session/keys.d.ts +3 -4
  388. package/dist/internal/session/keys.d.ts.map +1 -1
  389. package/dist/internal/session/keys.js.map +1 -1
  390. package/dist/internal/session/ratchet.d.ts +8 -8
  391. package/dist/internal/session/ratchet.js +10 -10
  392. package/dist/internal/session/ratchet.js.map +1 -1
  393. package/dist/internal/session/session-resolver.d.ts +6 -6
  394. package/dist/internal/session/session-resolver.js +6 -6
  395. package/dist/internal/session/state.d.ts +12 -12
  396. package/dist/internal/session/state.d.ts.map +1 -1
  397. package/dist/internal/session/state.js +7 -7
  398. package/dist/internal/session/types.d.ts +20 -20
  399. package/dist/internal/session/types.d.ts.map +1 -1
  400. package/dist/internal/session/types.js +3 -3
  401. package/dist/internal/session/validation.d.ts +1 -1
  402. package/dist/internal/session/validation.js +4 -4
  403. package/dist/internal/session/validation.js.map +1 -1
  404. package/dist/keys/branded.d.ts +12 -12
  405. package/dist/keys/branded.js +3 -3
  406. package/dist/keys/generation.d.ts +4 -4
  407. package/dist/keys/generation.js +4 -4
  408. package/dist/keys/identity.d.ts +7 -7
  409. package/dist/keys/identity.d.ts.map +1 -1
  410. package/dist/keys/identity.js +7 -7
  411. package/dist/keys/identity.js.map +1 -1
  412. package/dist/keys/types.d.ts +16 -16
  413. package/dist/keys/types.d.ts.map +1 -1
  414. package/dist/layers.d.ts +1 -1
  415. package/dist/layers.js +1 -1
  416. package/dist/local/store/expo/adapter.d.ts +8 -8
  417. package/dist/local/store/expo/adapter.js +10 -10
  418. package/dist/local/store/expo/adapter.js.map +1 -1
  419. package/dist/local/store/expo/database-key.d.ts +7 -7
  420. package/dist/local/store/expo/database-key.js +7 -7
  421. package/dist/local/store/expo/key-storage.d.ts +1 -1
  422. package/dist/local/store/expo/key-storage.js +4 -4
  423. package/dist/local/store/expo/key-storage.js.map +1 -1
  424. package/dist/local/store/expo/models/kyber-prekey-used.d.ts +6 -6
  425. package/dist/local/store/expo/models/kyber-prekey-used.js +3 -3
  426. package/dist/local/store/expo/models/kyber-prekey.d.ts +1 -1
  427. package/dist/local/store/expo/models/kyber-prekey.js +1 -1
  428. package/dist/local/store/expo/models/message-record.d.ts +2 -2
  429. package/dist/local/store/expo/models/message-record.d.ts.map +1 -1
  430. package/dist/local/store/expo/models/message-record.js +1 -1
  431. package/dist/local/store/expo/models/message-record.js.map +1 -1
  432. package/dist/local/store/expo/models/sender-key.d.ts +11 -10
  433. package/dist/local/store/expo/models/sender-key.d.ts.map +1 -1
  434. package/dist/local/store/expo/models/sender-key.js +11 -10
  435. package/dist/local/store/expo/models/sender-key.js.map +1 -1
  436. package/dist/local/store/expo/schema.d.ts +2 -2
  437. package/dist/local/store/expo/schema.js +2 -2
  438. package/dist/local/store/expo/secure-store-options.d.ts +1 -1
  439. package/dist/local/store/memory/adapter.d.ts +2 -2
  440. package/dist/local/store/memory/adapter.js +12 -12
  441. package/dist/local/store/memory/adapter.js.map +1 -1
  442. package/dist/local/store/node/adapter.d.ts.map +1 -1
  443. package/dist/local/store/node/adapter.js +5 -4
  444. package/dist/local/store/node/adapter.js.map +1 -1
  445. package/dist/local/store/node/database-key.d.ts +8 -8
  446. package/dist/local/store/node/database-key.js +10 -10
  447. package/dist/local/store/node/database-key.js.map +1 -1
  448. package/dist/local/store/node/database.d.ts +5 -5
  449. package/dist/local/store/node/database.js +11 -11
  450. package/dist/local/store/node/database.js.map +1 -1
  451. package/dist/local/store/react-native/adapter.d.ts +6 -6
  452. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  453. package/dist/local/store/react-native/adapter.js +35 -32
  454. package/dist/local/store/react-native/adapter.js.map +1 -1
  455. package/dist/local/store/react-native/backend-conformance.d.ts +11 -10
  456. package/dist/local/store/react-native/backend-conformance.d.ts.map +1 -1
  457. package/dist/local/store/react-native/backend-conformance.js +13 -12
  458. package/dist/local/store/react-native/backend-conformance.js.map +1 -1
  459. package/dist/local/store/react-native/index.d.ts +1 -1
  460. package/dist/local/store/react-native/reference-backend.d.ts +14 -13
  461. package/dist/local/store/react-native/reference-backend.d.ts.map +1 -1
  462. package/dist/local/store/react-native/reference-backend.js +15 -14
  463. package/dist/local/store/react-native/reference-backend.js.map +1 -1
  464. package/dist/local/store/react-native/storage.d.ts +3 -3
  465. package/dist/local/store/web/adapter.d.ts +3 -3
  466. package/dist/local/store/web/adapter.d.ts.map +1 -1
  467. package/dist/local/store/web/adapter.js +30 -31
  468. package/dist/local/store/web/adapter.js.map +1 -1
  469. package/dist/local/store/web/index.d.ts +1 -1
  470. package/dist/local/vault/index.d.ts +2 -2
  471. package/dist/media/index.d.ts +11 -11
  472. package/dist/media/index.js +9 -9
  473. package/dist/profile/contact-state.d.ts +1 -1
  474. package/dist/profile/contact-state.js +1 -1
  475. package/dist/profile/profile-key.d.ts +2 -2
  476. package/dist/profile/profile-key.js +7 -6
  477. package/dist/profile/profile-key.js.map +1 -1
  478. package/dist/remote/object-store/index.d.ts +1 -1
  479. package/dist/remote/object-store/s3/storage.d.ts +1 -1
  480. package/dist/remote/object-store/types.d.ts +4 -4
  481. package/dist/remote/object-store/types.d.ts.map +1 -1
  482. package/dist/remote/relay/convex/backend.d.ts +4 -4
  483. package/dist/remote/relay/convex/backend.js +3 -3
  484. package/dist/remote/relay/convex/backend.js.map +1 -1
  485. package/dist/remote/relay/convex/component/accounts.d.ts +15 -13
  486. package/dist/remote/relay/convex/component/accounts.d.ts.map +1 -1
  487. package/dist/remote/relay/convex/component/accounts.js +31 -28
  488. package/dist/remote/relay/convex/component/accounts.js.map +1 -1
  489. package/dist/remote/relay/convex/component/certificates.js +1 -1
  490. package/dist/remote/relay/convex/component/cleanup.js +7 -7
  491. package/dist/remote/relay/convex/component/cleanup.js.map +1 -1
  492. package/dist/remote/relay/convex/component/convex.config.d.ts.map +1 -1
  493. package/dist/remote/relay/convex/component/convex.config.js +10 -8
  494. package/dist/remote/relay/convex/component/convex.config.js.map +1 -1
  495. package/dist/remote/relay/convex/component/devices.d.ts +21 -20
  496. package/dist/remote/relay/convex/component/devices.d.ts.map +1 -1
  497. package/dist/remote/relay/convex/component/devices.js +24 -23
  498. package/dist/remote/relay/convex/component/devices.js.map +1 -1
  499. package/dist/remote/relay/convex/component/groups.js +6 -6
  500. package/dist/remote/relay/convex/component/groups.js.map +1 -1
  501. package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
  502. package/dist/remote/relay/convex/component/messages.js +89 -82
  503. package/dist/remote/relay/convex/component/messages.js.map +1 -1
  504. package/dist/remote/relay/convex/component/provisioning.d.ts +3 -3
  505. package/dist/remote/relay/convex/component/provisioning.d.ts.map +1 -1
  506. package/dist/remote/relay/convex/component/provisioning.js +17 -16
  507. package/dist/remote/relay/convex/component/provisioning.js.map +1 -1
  508. package/dist/remote/relay/convex/component/runtime.d.ts.map +1 -1
  509. package/dist/remote/relay/convex/component/runtime.js +4 -2
  510. package/dist/remote/relay/convex/component/runtime.js.map +1 -1
  511. package/dist/remote/relay/convex/component/schema.js +25 -24
  512. package/dist/remote/relay/convex/component/schema.js.map +1 -1
  513. package/dist/remote/relay/convex/group-server.d.ts +3 -3
  514. package/dist/remote/relay/convex/group-server.js +3 -3
  515. package/dist/remote/relay/convex/relay.d.ts +3 -3
  516. package/dist/remote/relay/convex/relay.d.ts.map +1 -1
  517. package/dist/remote/relay/convex/relay.js +18 -17
  518. package/dist/remote/relay/convex/relay.js.map +1 -1
  519. package/dist/remote/relay/convex/types.d.ts +7 -7
  520. package/dist/remote/relay/convex/types.js +4 -4
  521. package/dist/remote/relay/memory/adapter.js +9 -9
  522. package/dist/remote/relay/memory/adapter.js.map +1 -1
  523. package/dist/remote/relay/types.d.ts +27 -27
  524. package/dist/remote/relay/types.d.ts.map +1 -1
  525. package/dist/safety/fingerprint.d.ts +7 -6
  526. package/dist/safety/fingerprint.d.ts.map +1 -1
  527. package/dist/safety/fingerprint.js +5 -4
  528. package/dist/safety/fingerprint.js.map +1 -1
  529. package/dist/safety/index.d.ts +6 -5
  530. package/dist/safety/index.d.ts.map +1 -1
  531. package/dist/safety/index.js +7 -6
  532. package/dist/safety/index.js.map +1 -1
  533. package/dist/safety/protobuf.js +2 -2
  534. package/dist/safety/protobuf.js.map +1 -1
  535. package/dist/safety/url.d.ts +5 -5
  536. package/dist/safety/url.js +6 -6
  537. package/dist/types/address.d.ts +2 -2
  538. package/dist/types/address.js +2 -2
  539. package/dist/types/api.d.ts +78 -73
  540. package/dist/types/api.d.ts.map +1 -1
  541. package/dist/types/errors.d.ts +63 -403
  542. package/dist/types/errors.d.ts.map +1 -1
  543. package/dist/types/errors.js +62 -537
  544. package/dist/types/errors.js.map +1 -1
  545. package/dist/types/messages.d.ts +16 -16
  546. package/dist/types/messages.d.ts.map +1 -1
  547. package/dist/types/messages.js +7 -7
  548. package/dist/types/messages.js.map +1 -1
  549. package/dist/types/protocol-config.d.ts +52 -49
  550. package/dist/types/protocol-config.d.ts.map +1 -1
  551. package/dist/types/protocol-config.js +36 -34
  552. package/dist/types/protocol-config.js.map +1 -1
  553. package/dist/types/protocol-constants.d.ts +2 -2
  554. package/dist/types/protocol-constants.js +2 -2
  555. package/dist/types/session.d.ts +62 -61
  556. package/dist/types/session.d.ts.map +1 -1
  557. package/dist/types/session.js +13 -14
  558. package/dist/types/session.js.map +1 -1
  559. package/dist/types/trust.d.ts +8 -8
  560. package/dist/types/trust.js +3 -3
  561. package/dist/utils/retry.d.ts.map +1 -1
  562. package/dist/utils/retry.js +2 -4
  563. package/dist/utils/retry.js.map +1 -1
  564. package/docs/ASSURANCE.md +82 -74
  565. package/docs/CLIENT_COMPOSITION.md +19 -15
  566. package/docs/DEVIATIONS.md +507 -425
  567. package/docs/DOCUMENTATION_STANDARDS.md +24 -24
  568. package/docs/E2EE.md +45 -42
  569. package/docs/ERROR_HANDLING.md +29 -105
  570. package/docs/GETTING_STARTED.md +24 -25
  571. package/docs/INTERFACES.md +27 -18
  572. package/docs/PACKAGE_SURFACE.md +23 -21
  573. package/docs/PROTOCOL_POLICY.md +19 -13
  574. package/docs/RECIPES.md +4 -4
  575. package/docs/SECURITY.md +72 -60
  576. package/encoding/README.md +2 -2
  577. package/files/README.md +1 -1
  578. package/groups/README.md +4 -3
  579. package/hooks/README.md +2 -2
  580. package/keys/README.md +15 -14
  581. package/local/store/README.md +82 -67
  582. package/local/store/expo/README.md +17 -12
  583. package/local/store/memory/README.md +4 -3
  584. package/local/store/node/README.md +8 -6
  585. package/local/store/react-native/README.md +14 -12
  586. package/local/store/web/README.md +31 -26
  587. package/local/vault/README.md +4 -4
  588. package/media/README.md +6 -5
  589. package/package.json +2 -2
  590. package/profile/README.md +7 -7
  591. package/remote/README.md +20 -18
  592. package/remote/object-store/README.md +8 -4
  593. package/remote/object-store/convex-r2/README.md +3 -3
  594. package/remote/object-store/s3/README.md +10 -5
  595. package/remote/relay/convex/README.md +5 -5
  596. package/remote/relay/convex/component/README.md +145 -124
  597. package/remote/relay/memory/README.md +6 -5
  598. package/safety/README.md +1 -1
  599. package/sealed-sender/README.md +3 -2
  600. package/types/README.md +1 -1
  601. package/utils/README.md +4 -4
@@ -7,47 +7,61 @@
7
7
  ## What compatibility means here
8
8
 
9
9
  This SDK implements the same cryptographic core as the published Signal Protocol
10
- specifications — X3DH/PQXDH key agreement, the Double Ratchet, the ML-KEM Braid
11
- post-quantum ratchet, Sesame multi-device session management, sealed sender, and
12
- the Signal Protocol's zero-knowledge group credential system. In many places it is faithful
13
- down to the byte: the same KDF labels, the same chain-key constants, the same
14
- protobuf field numbers, the same iteration counts.
10
+ specifications:
11
+
12
+ - X3DH/PQXDH key agreement
13
+ - the Double Ratchet
14
+ - the ML-KEM Braid post-quantum ratchet
15
+ - Sesame multi-device session management
16
+ - sealed sender
17
+ - the Signal Protocol's zero-knowledge group credential system
18
+
19
+ In many places it is faithful down to the byte. It uses the same KDF labels, the
20
+ same chain-key constants, the same protobuf field numbers, and the same
21
+ iteration counts.
15
22
 
16
23
  It is **not wire-compatible with Signal Messenger or with `libsignal`**, and it
17
- is not intended to be. Messages produced by this SDK cannot be decrypted by a
18
- Signal Messenger client, identities cannot be exchanged, safety numbers computed here
19
- cannot be compared against safety numbers shown in Signal Messenger, and sessions cannot be
20
- migrated in either direction. This is a distinct wire profile —
21
- `IndependentProfileV1` — that shares the Signal Protocol's cryptographic design and
24
+ is not intended to be:
25
+
26
+ - a Signal Messenger client cannot decrypt a message from this SDK
27
+ - the two systems cannot exchange identities
28
+ - a user cannot check a safety number from this SDK against the number Signal
29
+ Messenger shows
30
+ - neither side can migrate a session to the other
31
+
32
+ This is a distinct wire profile,
33
+ `IndependentProfileV1`. It shares the Signal Protocol's cryptographic design and
22
34
  deliberately does not share its encoding.
23
35
 
24
36
  That distinction matters in a specific way. Reading "implements X3DH and the
25
37
  Double Ratchet" reasonably leads someone to expect interoperability. There is
26
- none. Reading "safety numbers compatible with Signal Messenger" would reasonably
27
- lead someone to expect that a user could verify a contact by comparing a number
28
- shown in this SDK against the same contact's number in Signal Messenger. They
29
- cannot; the numbers are computed over different inputs and will never match.
38
+ none. Reading "safety numbers compatible with Signal Messenger" invites a second
39
+ expectation: that a user could verify a contact against the number Signal
40
+ Messenger shows. A user cannot. The two numbers come from different inputs and
41
+ will never match.
30
42
 
31
43
  This document is the complete, honest account of where and why the profile
32
44
  differs. Each entry names the implementing file, the specification section or
33
- `libsignal` source it departs from, the engineering reason, and the cost. Where a
34
- deviation weakens an assurance that a reader of the specification would
35
- reasonably assume, that is stated plainly rather than framed as a feature.
45
+ `libsignal` source it departs from, the engineering reason, and the cost. A
46
+ deviation sometimes weakens an assurance that a reader of the specification
47
+ would reasonably assume. This document says so plainly rather than framing it as
48
+ a feature.
36
49
 
37
50
  Deviations fall into three kinds:
38
51
 
39
- - **Deviation** — does something different from the specification or from
52
+ - **Deviation**: does something different from the specification or from
40
53
  `libsignal`, deliberately.
41
- - **Extension** — adds a mechanism the specification does not describe.
42
- - **Independent design** — shares a name and a goal with a Signal Protocol system, but is
43
- the SDK's own construction rather than a port of the corresponding `libsignal` system.
54
+ - **Extension**: adds a mechanism the specification does not describe.
55
+ - **Independent design**: shares a name and a goal with a Signal Protocol system.
56
+ It is the SDK's own construction rather than a port of the corresponding
57
+ `libsignal` system.
44
58
 
45
- A fourth label, **faithful**, appears in the table where an area follows the
46
- specification closely enough that its presence in this document is only to
47
- delimit what the neighbouring deviations do and do not touch.
59
+ A fourth label, **faithful**, appears in the table for an area that follows the
60
+ specification closely. Such a row is here only to delimit what the neighbouring
61
+ deviations do and do not touch.
48
62
 
49
63
  Companion documents: [Protocol Policy](./PROTOCOL_POLICY.md) states which
50
- protocol modes run and which fail closed; this document states how the profile
64
+ protocol modes run and which fail closed. This document states how the profile
51
65
  differs from the specifications. [Security](./SECURITY.md) states the threat
52
66
  model and what is out of scope.
53
67
 
@@ -84,8 +98,8 @@ model and what is out of scope.
84
98
  ### 1.1 Composite identity replaces the single Curve25519 key
85
99
 
86
100
  `libsignal` represents an identity as one Curve25519 public key serialized as
87
- `0x05 ‖ key` — 33 bytes ([`identity_key.rs:23-49`][ik]). The same private key is
88
- used both for Diffie-Hellman and, via XEdDSA, for signing.
101
+ `0x05 ‖ key`, or 33 bytes ([`identity_key.rs:23-49`][ik]). One private key
102
+ serves both Diffie-Hellman and, via XEdDSA, signing.
89
103
 
90
104
  This SDK stores a versioned tuple of two separate keys
91
105
  (`keys/identity.ts:20-23`, `:66-72`):
@@ -100,12 +114,15 @@ This SDK stores a versioned tuple of two separate keys
100
114
  length (`keys/identity.ts:75-96`).
101
115
 
102
116
  **Why.** XEdDSA ([spec][xeddsa]) lets one Curve25519 key serve both roles by
103
- converting a Montgomery point to an Edwards point at signing time. It is
104
- elegant, and it is also non-standard: no vetted JavaScript implementation exists,
105
- the conversion has sign-bit handling that is easy to get subtly wrong, and the
106
- resulting signatures cannot be checked by any general-purpose Ed25519 verifier.
107
- Carrying an explicit Ed25519 key costs 32 bytes and one more key to manage, and
108
- buys signatures that any RFC 8032 implementation can verify and that auditors can
117
+ converting a Montgomery point to an Edwards point at signing time. It is also
118
+ non-standard:
119
+
120
+ - no vetted JavaScript implementation exists
121
+ - the conversion has sign-bit handling that is easy to get subtly wrong
122
+ - no general-purpose Ed25519 verifier can check the resulting signatures
123
+
124
+ An explicit Ed25519 key costs 32 bytes and one more key to manage. It buys
125
+ signatures that any RFC 8032 implementation can verify, and that auditors can
109
126
  reason about without first reasoning about curve conversion.
110
127
 
111
128
  **Cost.** Two keys to generate, store, rotate, and back up. A larger identity on
@@ -120,16 +137,17 @@ A commitment binds the tuple (`keys/identity.ts:98-100`):
120
137
  SHA-256(UTF8("signal-protocol-js composite identity v1") || CompositeIdentityV1)
121
138
  ```
122
139
 
123
- A commitment received from a relay, cache, or caller is never trusted; it is
124
- recomputed and compared in constant time (`keys/identity.ts:103-111`), and every
125
- producer of stored identity bytes is forced through a decode/re-encode round trip
126
- so that two encodings of the same key cannot forge an identity-change event
127
- (`keys/identity.ts:154-161`). `libsignal` has no commitment concept, because a
128
- single-key format has nothing to bind together.
140
+ The SDK never trusts a commitment that arrives from a relay, cache, or caller.
141
+ It recomputes the commitment and compares it in constant time
142
+ (`keys/identity.ts:103-111`). Every producer of stored identity bytes goes
143
+ through a decode/re-encode round trip (`keys/identity.ts:154-161`). Two
144
+ encodings of the same key therefore cannot forge an identity-change event.
145
+ `libsignal` has no commitment concept, because a single-key format has nothing
146
+ to bind together.
129
147
 
130
148
  **Not ported.** `libsignal`'s ACI↔PNI alternate-identity signature
131
149
  ([`identity_key.rs:61-70`][ik]) has no SDK equivalent. ACI and PNI are fully
132
- independent identities here with independent trust histories; neither certifies
150
+ independent identities here with independent trust histories. Neither certifies
133
151
  the other. An application that wants a user's two identities linked must
134
152
  establish that link itself.
135
153
 
@@ -151,8 +169,8 @@ UTF8("signal-protocol-js prekey signature v1")
151
169
  ML-KEM prekeys must carry their `0x0A` tag inside the signed bytes
152
170
  (`keys/prekey-signature.ts:33-38`).
153
171
 
154
- **Why.** A bare-key signature says only "the identity holder signed these 32
155
- bytes." It does not say which algorithm the key is for, which key ID it occupies,
172
+ **Why.** A bare-key signature says only that the identity holder signed these 32
173
+ bytes. It does not say which algorithm the key is for, which key ID it occupies,
156
174
  or which identity it belongs to. Binding all three defeats cross-algorithm
157
175
  substitution (presenting an X25519 signature as an ML-KEM one) and cross-key-ID
158
176
  substitution. This is strictly stronger than the specification requires.
@@ -166,21 +184,21 @@ messages (§7.2).
166
184
 
167
185
  XEdDSA and VXEdDSA are not implemented, not stubbed, and not claimed anywhere in
168
186
  this codebase. Where the frozen upstream specification snapshots mention them,
169
- that is upstream text; the SDK's own documentation consistently states that
170
- ordinary Ed25519 is used instead.
187
+ that is upstream text. The SDK's own documentation consistently states that it
188
+ uses ordinary Ed25519 instead.
171
189
 
172
190
  ### 1.3 Safety numbers are not comparable to Signal Messenger's
173
191
 
174
- State this without hedging: **a safety number produced by this SDK will never
175
- match the safety number Signal Messenger shows for the same two users.** A user cannot
192
+ State this without hedging. A safety number from this SDK **will never match**
193
+ the safety number Signal Messenger shows for the same two users. A user cannot
176
194
  verify a contact by reading a number out of one application and comparing it
177
195
  against the other.
178
196
 
179
197
  Three independent reasons, any one of which is sufficient.
180
198
 
181
- **The user-facing number is computed over a composite commitment.**
182
- `client.verify()` uses `generateCompositeSafetyNumber`
183
- (`client/sessions.ts:326`, `:432-433`), whose per-party hash iterates over
199
+ **The SDK computes the user-facing number over a composite commitment.**
200
+ The `client.verify()` method uses `generateCompositeSafetyNumber`
201
+ (`client/sessions.ts:326`, `:432-433`). Its per-party hash iterates over
184
202
  `UTF8("signal-protocol-js composite safety number v1") ‖ type-tagged user ID ‖
185
203
  SHA-256 identity commitment` (`safety/core.ts:48-50`, `:205-233`). None of that
186
204
  input exists in `libsignal`'s construction ([`fingerprint.rs:161-192`][fp]).
@@ -188,60 +206,65 @@ input exists in `libsignal`'s construction ([`fingerprint.rs:161-192`][fp]).
188
206
  **The identity material differs.** Even the raw input is a 67-byte two-key tuple
189
207
  rather than a 33-byte `0x05 ‖ X25519` key.
190
208
 
191
- **The two halves are ordered by a different rule.** This one applies even on the
209
+ **A different rule orders the two halves.** This one applies even on the
192
210
  SDK's low-level single-key path, which is otherwise byte-identical to
193
- `libsignal`. The SDK orders by user identifier — `localId.localeCompare(remoteId)`
194
- (`safety/core.ts:177`) — where `libsignal` orders by the encoded digit strings
195
- themselves ([`fingerprint.rs:32-40`][fp]). Both rules are symmetric, so the two
196
- parties always agree with each other; they simply do not agree with Signal Messenger, and
197
- roughly half the time the halves come out in the opposite order. `localeCompare`
198
- is additionally locale-sensitive, so two devices with different default locales
199
- can in principle disagree with each other on the ordering of the same pair of
200
- user IDs.
201
-
202
- What *is* faithful: the iteration is byte-for-byte `libsignal`'s — 5200
211
+ `libsignal`. The SDK orders by user identifier,
212
+ `localId.localeCompare(remoteId)` (`safety/core.ts:177`). `libsignal` orders by
213
+ the encoded digit strings themselves ([`fingerprint.rs:32-40`][fp]). Both rules
214
+ are symmetric, so the two parties always agree with each other. They do not
215
+ agree with Signal Messenger, and roughly half the time the halves come out in
216
+ the opposite order.
217
+
218
+ `localeCompare` is also locale-sensitive. Two devices with different default
219
+ locales can in principle disagree on how to order the same pair of user IDs.
220
+
221
+ Other parts *are* faithful. The iteration is byte-for-byte `libsignal`'s: 5200
203
222
  iterations of SHA-512 over `0x0000 ‖ key ‖ id`, then `hash ‖ key`
204
- (`safety/core.ts:138-143` vs [`fingerprint.rs:170-189`][fp]) — as is the digit
205
- encoding (six 5-byte big-endian chunks mod 100000, 30 digits per party) and the
206
- scannable-fingerprint protobuf layout (`safety/protobuf.ts:94-109`). The
223
+ (`safety/core.ts:138-143` vs [`fingerprint.rs:170-189`][fp]). So is the digit
224
+ encoding (six 5-byte big-endian chunks mod 100000, 30 digits per party). So is
225
+ the scannable-fingerprint protobuf layout (`safety/protobuf.ts:94-109`). The
207
226
  cross-verification swap and constant-time comparison match as well.
208
227
 
209
228
  The QR format version is the SDK's own: `3` for the composite path
210
229
  (`safety/core.ts:46`), where `libsignal` knows only versions 1 and 2 and returns
211
- `VersionMismatch` for anything else. Using a distinct version in the same
212
- protobuf namespace is the correct fail-closed choice — a Signal Messenger client rejects
230
+ `VersionMismatch` for anything else. A distinct version in the same protobuf
231
+ namespace is the correct fail-closed choice. A Signal Messenger client rejects
213
232
  the code rather than misreading it.
214
233
 
215
234
  The SDK also offers an emoji fingerprint (`safety/core.ts:308-392`) and
216
235
  verification deep links (`safety/url.ts`). Both are extensions with no
217
- `libsignal` counterpart. Note that the emoji form is derived from one party's
218
- fingerprint only, so it carries roughly half the information of the 60-digit
219
- number and should not be presented to users as an equal-strength alternative.
236
+ `libsignal` counterpart. The emoji form derives from one party's fingerprint
237
+ only. It therefore encodes roughly half of what the 60-digit number encodes.
238
+ Do not present it to users as an equal-strength alternative.
220
239
 
221
240
  ### 1.4 Registration ID range
222
241
 
223
- Registration IDs are generated in the closed range `[1, 16383]`
242
+ The SDK generates registration IDs in the closed range `[1, 16383]`
224
243
  (`keys/generation.ts:43-46`). The wire format reserves exactly 14 bits, and
225
244
  `libsignal` rejects any ID where `id & 0x3FFF != id`
226
- ([`sealed_sender.rs:1508-1515`][ss]); `libsignal`'s own helper generates `[1, 16380]`.
245
+ ([`sealed_sender.rs:1508-1515`][ss]). Its own helper generates `[1, 16380]`.
227
246
 
228
- The upper bound is load-bearing rather than cosmetic. `16384` is `0x4000` and
229
- does not fit in 14 bits, and the SDK's multi-recipient sealed-sender encoder
230
- masks rather than rejects
247
+ The upper bound is load-bearing rather than cosmetic. The value `16384` is
248
+ `0x4000` and does not fit in 14 bits. The SDK's multi-recipient sealed-sender
249
+ encoder masks rather than rejects
231
250
  (`internal/protocol/sealed-sender/v2-binary.ts:170-171`), so an ID one above
232
- the range would reach the wire as `0`. The generated range is therefore
233
- strictly narrower than `libsignal`'s accepted range, and a test asserts every
251
+ the range would reach the wire as `0`. The generated range is therefore strictly
252
+ narrower than `libsignal`'s accepted range, and a test asserts that every
234
253
  generated ID survives the mask unchanged.
235
254
 
236
255
  ---
237
256
 
238
257
  ## 2. X3DH and PQXDH
239
258
 
240
- The key agreement is the most faithful area in the codebase. The DH computation
241
- order, the 32-byte `0xFF` discontinuity prefix, the zero-filled HKDF salt, the
242
- single-step derivation over the full concatenation, the position of the KEM
243
- shared secret (appended last), and the 96-byte output split all match
244
- `libsignal` exactly.
259
+ The key agreement is the most faithful area in the codebase. These all match
260
+ `libsignal` exactly:
261
+
262
+ - the DH computation order
263
+ - the 32-byte `0xFF` discontinuity prefix
264
+ - the zero-filled HKDF salt
265
+ - the single-step derivation over the full concatenation
266
+ - the KEM shared secret appended last
267
+ - the 96-byte output split
245
268
 
246
269
  - Initiator DH order `DH(IK_A,SPK_B)`, `DH(EK_A,IK_B)`, `DH(EK_A,SPK_B)`,
247
270
  `DH(EK_A,OPK_B)`: `internal/protocol/pqxdh/pqxdh.ts:243-264` vs
@@ -252,18 +275,19 @@ shared secret (appended last), and the 96-byte output split all match
252
275
  `internal/protocol/pqxdh/pqxdh.ts:365-374` vs [`pqxdh.rs:226-230`][pq]. Spec
253
276
  PQXDH §3.3.
254
277
 
255
- Two hardening extensions go beyond the specification at no interop cost: every
256
- remote X25519 point is validated before any DH is computed
257
- (`internal/protocol/pqxdh/pqxdh.ts:219-227`), and prekey bundles are validated
258
- far more strictly than `libsignal` requires
259
- (`internal/session/handshake.ts:107-138`).
278
+ Two hardening extensions go beyond the specification at no interop cost:
279
+
280
+ - the SDK validates every remote X25519 point before it computes any DH
281
+ (`internal/protocol/pqxdh/pqxdh.ts:219-227`)
282
+ - the SDK validates prekey bundles far more strictly than `libsignal` requires
283
+ (`internal/session/handshake.ts:107-138`)
260
284
 
261
285
  ### 2.1 The info strings name this application and this KEM
262
286
 
263
287
  The SDK uses ML-KEM-1024 (FIPS 203) where `libsignal` uses round-3 Kyber1024,
264
288
  tagged `0x0A` rather than `0x08` (`internal/crypto/pq/kyber.ts:79`). That much is
265
- deliberate: the standardized algorithm is preferred over the round-3 draft, and a
266
- single unambiguous tag is preferred over carrying a legacy fallback.
289
+ deliberate. The SDK prefers the standardized algorithm over the round-3 draft,
290
+ and a single unambiguous tag over a legacy fallback.
267
291
 
268
292
  The info strings are the SDK's own (`types/protocol-config.ts:363-386`):
269
293
 
@@ -272,29 +296,28 @@ OpenE2EE_X25519_SHA-256_ML-KEM-1024 (PQXDH)
272
296
  OpenE2EE (X3DH)
273
297
  ```
274
298
 
275
- Both parameters the specifications leave to the implementer are set to what
276
- this SDK is and runs. PQXDH §2.2 defines the info string as `info`, `curve`,
277
- `hash`, and `pqkem` joined by `_`, with each representation implementer-chosen;
278
- §2.1 defines `info` as an application identifier of at least 8 bytes. X3DH §2.1
279
- defines the same `info` parameter, and §3.3 uses it as the HKDF info with
280
- nothing appended.
299
+ The SDK sets both implementer-chosen parameters to name itself and the KEM it
300
+ runs. PQXDH §2.2 defines the info string as `info`, `curve`, `hash`, and `pqkem`
301
+ joined by `_`, with each representation implementer-chosen. PQXDH §2.1 defines
302
+ `info` as an application identifier of at least 8 bytes. X3DH §2.1 defines the
303
+ same `info` parameter, and §3.3 uses it as the HKDF info with nothing appended.
281
304
 
282
- The SDK does not use `libsignal`'s labels — `WhisperText` and
305
+ The SDK does not use `libsignal`'s labels, `WhisperText` and
283
306
  `WhisperText_X25519_SHA-256_CRYSTALS-KYBER-1024` ([`pqxdh.rs:73-74`][pq]).
284
307
  Inheriting them would be wrong on both parameters:
285
308
 
286
309
  1. **`pqkem` would name a KEM the SDK does not run**, violating §2.2. That is
287
- worse than a labelling error: two implementations feeding an identical
288
- label derive *different* shared secrets, because the KEM underneath
289
- differs, with nothing at the KDF layer to signal it. Domain separation is
290
- the one job the info string has.
310
+ worse than a labelling error. Two implementations feeding an identical label
311
+ derive *different* shared secrets. The KEM underneath differs, and nothing at
312
+ the KDF layer signals it. Domain separation is the one job the info string
313
+ has.
291
314
  2. **`info` would name someone else's application.** The specifications ask
292
315
  for an identifier of the application deriving the key. This SDK is not
293
316
  Signal Messenger.
294
317
 
295
318
  Choosing the SDK's own labels is a pre-1.0 format break against sessions
296
- established under `libsignal`'s: they derive a different `SK` and cannot be
297
- continued. Nothing else about the derivation changes.
319
+ established under `libsignal`'s. Those sessions derive a different `SK`, and
320
+ neither side can continue them. Nothing else about the derivation changes.
298
321
 
299
322
  An application that needs `libsignal`'s known-answer vectors can still get them
300
323
  by setting `protocolStrategy.keyExchangeInfoString` to the old label
@@ -319,50 +342,51 @@ HMAC-SHA256(mac_key,
319
342
  ```
320
343
 
321
344
  **Why.** With a two-key identity, an `AD` over the DH key alone would leave the
322
- Ed25519 signing component unbound — the component that authenticates every prekey
323
- the peer will ever publish. Hashing the commitment covers both.
345
+ Ed25519 signing component unbound. That component authenticates every prekey the
346
+ peer will ever publish. Hashing the commitment covers both.
324
347
 
325
348
  **Cost.** This is the single largest wire deviation in the message path. The
326
- truncation to 8 bytes matches `libsignal`'s convention, and the construction is sound
327
- and domain-separated, but a Signal Messenger client and this SDK cannot exchange a single
328
- message.
349
+ truncation to 8 bytes matches `libsignal`'s convention, and the construction is
350
+ sound and domain-separated. Even so, a Signal Messenger client and this SDK
351
+ cannot exchange a single message.
329
352
 
330
- ### 2.3 One-time prekey deletion is deferred
353
+ ### 2.3 The SDK defers one-time prekey deletion
331
354
 
332
355
  PQXDH §3.4 has Bob delete a used one-time prekey after successful decryption. The
333
356
  SDK records a pending deletion (`internal/manager/manager.ts:940-952`) and
334
357
  commits it only once a prekey message decrypts
335
- (`internal/session/cipher.ts:1189-1200`). This is compliant in letter and widens
336
- the window in which the same first ciphertext can be replayed before commit;
337
- duplicate and missing-prekey conditions are refused auto-recovery
338
- (`internal/session/cipher.ts:1519-1527`).
358
+ (`internal/session/cipher.ts:1189-1200`). This is compliant in letter. It also
359
+ widens the window in which an attacker can replay the same first ciphertext
360
+ before commit. The SDK refuses auto-recovery for duplicate and missing-prekey
361
+ conditions (`internal/session/cipher.ts:1519-1527`).
339
362
 
340
363
  ### 2.4 Ratchet initialization details
341
364
 
342
365
  Two differences at the boundary between key agreement and the ratchet:
343
366
 
344
367
  **Alice reuses her key-agreement ephemeral as her first ratchet key**
345
- (`internal/session/builder.ts:159-171`). `libsignal` generates a fresh sending
346
- ratchet key distinct from the handshake ephemeral ([`ratchet.rs:77-81`][rat]), so
347
- the prekey message's base key and the first message's ratchet key differ. Here
348
- they are the same value. No concrete attack follows, but it is a reduction in key
349
- separation and it is wire-visible.
368
+ (`internal/session/builder.ts:159-171`). By contrast, `libsignal` generates a
369
+ fresh sending ratchet key, distinct from the handshake ephemeral
370
+ ([`ratchet.rs:77-81`][rat]). In `libsignal` the prekey message's base key and the
371
+ first message's ratchet key therefore differ. Here they are the same value. No
372
+ concrete attack follows, but the reuse weakens key separation and it is
373
+ wire-visible.
350
374
 
351
375
  **Bob initializes without a sending chain** (`internal/session/builder.ts:326-364`),
352
376
  deriving chains on the first DH ratchet, where `libsignal` seeds a sending chain
353
377
  immediately ([`ratchet.rs:137-172`][rat]). A side effect is that bytes 32–64 of
354
- the 96-byte derivation — the initial chain key — never produce a message key on
355
- either side. The 96-byte split is retained for shape compatibility, but only the
356
- root key and the SPQR key are load-bearing.
378
+ the 96-byte derivation, the initial chain key, never produce a message key on
379
+ either side. The SDK keeps the 96-byte split for shape compatibility, but only
380
+ the root key and the SPQR key are load-bearing.
357
381
 
358
- ### 2.5 Classical fallback is retained but gated
382
+ ### 2.5 The SDK keeps a gated classical fallback
359
383
 
360
- `libsignal` has removed X3DH entirely and rejects pre-Kyber prekey messages
384
+ `libsignal` removed X3DH entirely and rejects pre-Kyber prekey messages
361
385
  ([`session.rs:105-112`][sess]). The SDK keeps the X3DH path reachable only via an
362
- explicit opt-in; the default is fail-closed, and any PQXDH failure raises rather
386
+ explicit opt-in. The default is fail-closed, and any PQXDH failure raises rather
363
387
  than silently downgrading (`internal/session/handshake.ts:167-260`). This is a
364
- downgrade surface that `libsignal` has closed, and it is documented in
365
- [Protocol Policy](./PROTOCOL_POLICY.md).
388
+ downgrade surface that `libsignal` closed.
389
+ [Protocol Policy](./PROTOCOL_POLICY.md) documents it.
366
390
 
367
391
  ---
368
392
 
@@ -370,19 +394,24 @@ downgrade surface that `libsignal` has closed, and it is documented in
370
394
 
371
395
  ### 3.1 The ratchet core is faithful
372
396
 
373
- Byte-for-byte with `libsignal`: the `0x01`/`0x02` chain-key seeds
374
- (`internal/crypto/kdf/hkdf.ts:183-195` vs [`keys.rs:148-149`][rk]), the
375
- `WhisperMessageKeys` expansion to 80 bytes split 32/32/16
376
- (`internal/crypto/kdf/hkdf.ts:215-243` vs [`keys.rs:100-118`][rk]), the
377
- `WhisperRatchet` root-key step producing a 64-byte split
378
- (`internal/crypto/kdf/hkdf.ts:141-161` vs [`keys.rs:199-218`][rk]), the DH ratchet
379
- half-step ordering, `MAX_RECEIVER_CHAINS = 5`, AES-256-CBC with PKCS#7, the
380
- `0x44` version byte, and 8-byte MAC truncation.
397
+ These parts are byte-for-byte with `libsignal`:
398
+
399
+ - the `0x01`/`0x02` chain-key seeds (`internal/crypto/kdf/hkdf.ts:183-195` vs
400
+ [`keys.rs:148-149`][rk])
401
+ - the `WhisperMessageKeys` expansion to 80 bytes split 32/32/16
402
+ (`internal/crypto/kdf/hkdf.ts:215-243` vs [`keys.rs:100-118`][rk])
403
+ - the `WhisperRatchet` root-key step producing a 64-byte split
404
+ (`internal/crypto/kdf/hkdf.ts:141-161` vs [`keys.rs:199-218`][rk])
405
+ - the DH ratchet half-step ordering
406
+ - `MAX_RECEIVER_CHAINS = 5`
407
+ - AES-256-CBC with PKCS#7
408
+ - the `0x44` version byte
409
+ - 8-byte MAC truncation
381
410
 
382
411
  Message framing matches too: `[version byte] ‖ protobuf ‖ [8-byte HMAC]` for
383
412
  messages and `[version byte] ‖ protobuf` for prekey messages
384
413
  (`internal/encoding/proto/envelope.ts:104-168`). What goes *into* the MAC does
385
- not — see §2.2.
414
+ not. See §2.2.
386
415
 
387
416
  Protobuf fields 1–8 match [`wire.proto`][wp] exactly, including `libsignal`'s
388
417
  non-obvious ordering where `registrationId` is field 5 and `signedPreKeyId` is
@@ -394,93 +423,97 @@ field 6.
394
423
  have: `recipientIdentityType` on both message types, and `kemOneTimePreKeyId` /
395
424
  `kemOneTimeCiphertext` on prekey messages
396
425
  (`internal/encoding/proto/signal-message.ts:80`, `:226-228`). High numbering
397
- avoids collision with future upstream fields. A Signal Messenger client would parse the
398
- message and silently ignore them, losing the identity-type binding.
426
+ avoids collision with future upstream fields. A Signal Messenger client parses
427
+ the message and ignores the added fields, which loses the identity-type
428
+ binding.
399
429
 
400
430
  **Deviation.** `libsignal` binds addresses as a 17-byte fixed-width ServiceId plus
401
431
  a 1-byte device ID ([`protocol.rs:246-260`][proto]). The SDK binds a
402
432
  format-version byte, a varint-length-prefixed UTF-8 user ID, and a 4-byte
403
433
  big-endian device ID (`internal/encoding/proto/signal-message.ts:84-92`). The
404
434
  encoding is unambiguous, but it authenticates an application-defined identifier
405
- rather than a Signal Messenger ACI or PNI — which is the correct thing for this SDK to bind
406
- and an incompatible thing to put on the wire.
435
+ rather than a Signal Messenger ACI or PNI. That is the correct thing for this SDK
436
+ to bind, and an incompatible thing to put on the wire.
407
437
 
408
- The SDK is also stricter than `libsignal` on decode, requiring fields that
409
- `libsignal` treats as optional for backward compatibility and enforcing exact
410
- lengths (`internal/encoding/proto/signal-message.ts:332-340`, `:488-505`). Safer,
411
- and one more reason the formats cannot meet.
438
+ The SDK is also stricter than `libsignal` on decode. It requires fields that
439
+ `libsignal` treats as optional for backward compatibility, and it enforces exact
440
+ lengths (`internal/encoding/proto/signal-message.ts:332-340`, `:488-505`). This
441
+ is safer, and it is one more reason the formats cannot meet.
412
442
 
413
- ### 3.3 Skipped-key retention is materially tighter than libsignal's
443
+ ### 3.3 Skipped-key retention is much tighter than in libsignal
414
444
 
415
- The constants match — `MAX_MESSAGE_KEYS = 2000`, `MAX_FORWARD_JUMPS = 25000`
416
- (`internal/protocol/double-ratchet/ratchet.ts:194-227` vs [`consts.rs:8-9`][consts])
417
- — but they are applied differently, and the difference is user-visible.
445
+ The constants match: `MAX_MESSAGE_KEYS = 2000` and `MAX_FORWARD_JUMPS = 25000`
446
+ (`internal/protocol/double-ratchet/ratchet.ts:194-227` vs
447
+ [`consts.rs:8-9`][consts]). The two implementations apply them differently, and
448
+ the difference is user-visible.
418
449
 
419
450
  **The cap is global, not per-chain.** `libsignal` applies 2000 to each chain's key
420
- vector ([`double_ratchet.rs:349-361`][dr]), so with five receiver chains the true
421
- system capacity is 10,000 skipped keys. The SDK counts across all chains and
451
+ vector ([`double_ratchet.rs:349-361`][dr]). Five receiver chains therefore give a
452
+ true system capacity of 10,000 skipped keys. The SDK counts across all chains and
422
453
  evicts when the total reaches 2000
423
454
  (`internal/protocol/double-ratchet/chains.ts:478-513`). The effective capacity is
424
- 5× smaller, and traffic on a newer chain can evict keys belonging to an older one.
455
+ 5× smaller, and traffic on a newer chain can evict keys that belong to an older
456
+ one.
425
457
 
426
- **Eviction is by wall-clock timestamp**, scanning every chain for the oldest
427
- entry (`internal/protocol/double-ratchet/chains.ts:414-463`), where `libsignal`
428
- evicts strictly by insertion position. `Date.now()` is not monotonic, so eviction
429
- order is not deterministic across clock adjustments.
458
+ **Wall-clock timestamps drive eviction.** The SDK scans every chain for the
459
+ oldest entry (`internal/protocol/double-ratchet/chains.ts:414-463`). By contrast,
460
+ `libsignal` evicts strictly by insertion position. `Date.now()` is not monotonic,
461
+ so a clock adjustment makes the eviction order non-deterministic.
430
462
 
431
463
  **Skipped keys expire after 7 days**
432
464
  (`internal/protocol/double-ratchet/ratchet.ts:197`). `libsignal` has no
433
465
  time-based expiry for message keys at all.
434
466
 
435
- Taken together: **there are message-delivery patterns where this SDK reports an
436
- undecryptable message and `libsignal` would have decrypted it.** A recipient
437
- offline for more than a week, or one receiving heavy traffic on a new chain while
438
- older-chain messages are still in flight, can lose messages that the
439
- specification's own limits would have preserved. The bounds are defensible as
440
- storage hygiene; the consequence should not be a surprise.
467
+ Taken together, these three differences create **message-delivery patterns where
468
+ this SDK reports an undecryptable message and `libsignal` decrypts it**. Two
469
+ recipients can lose messages that the specification's own limits keep. The first
470
+ is offline for more than a week. The second takes heavy traffic on a new chain
471
+ while older-chain messages are still in flight. The bounds are defensible as
472
+ storage hygiene. The consequence should not be a surprise.
441
473
 
442
- Two related extensions: a `processedChains` map rejects messages bearing a ratchet
443
- key from an already-retired chain (`internal/protocol/double-ratchet/ratchet.ts:141-153`),
444
- closing a replay gap that `libsignal` handles only via its five-chain window; and
445
- self-sessions get a finite 100,000-message skip limit
446
- (`internal/session/validation.ts:453-461`) where `libsignal` uses `usize::MAX`.
474
+ Two related extensions go with this. A `processedChains` map rejects messages
475
+ that bear a ratchet key from a retired chain
476
+ (`internal/protocol/double-ratchet/ratchet.ts:141-153`), which closes a replay gap
477
+ that `libsignal` handles only through its five-chain window. Self-sessions get a
478
+ finite 100,000-message skip limit (`internal/session/validation.ts:453-461`)
479
+ where `libsignal` uses `usize::MAX`.
447
480
 
448
481
  ### 3.4 Session archiving and serialization
449
482
 
450
- The cap matches (40 archived states, [`consts.rs:11`][consts]), but the structure
483
+ The cap matches: 40 archived states, [`consts.rs:11`][consts]. The structure
451
484
  differs. `libsignal` keeps an ordered list with strict insertion-order eviction
452
- ([`session.rs:787-830`][st]); the SDK keeps a map keyed by base key and trims by
485
+ ([`session.rs:787-830`][st]). The SDK keeps a map keyed by base key and trims by
453
486
  `lastUsedAt` (`types/session.ts:815-847`). Archiving a session whose base key
454
487
  already exists overwrites rather than appends, so the effective history can be
455
488
  shorter than 40.
456
489
 
457
- `libsignal` clears unacknowledged prekey state before archiving a session; the SDK
458
- does not. Retired sessions therefore keep pending prekey references alive in
490
+ `libsignal` clears unacknowledged prekey state before archiving a session. The
491
+ SDK does not. Retired sessions therefore keep pending prekey references alive in
459
492
  storage.
460
493
 
461
494
  **Session records serialize as JSON, not protobuf** (`types/session.ts:1002-1028`).
462
- This is acknowledged in the source as a simplicity and debuggability choice.
463
- Consequences worth naming: stored sessions are not portable to or from any Signal Messenger
464
- client, and key material sits in immutable JavaScript strings that cannot be
465
- zeroed, where `libsignal`'s byte vectors can be.
495
+ The source states this as a simplicity and debuggability choice. Two consequences
496
+ are worth naming. No Signal Messenger client can read or write these stored
497
+ sessions. Key material also sits in immutable JavaScript strings that nothing can
498
+ zero, where `libsignal` can zero its byte vectors.
466
499
 
467
500
  ### 3.5 Padding
468
501
 
469
- **Extension.** Message plaintext is padded to 160-byte buckets with ISO 7816-4 bit
470
- padding — a `0x80` terminator followed by zeros
502
+ **Extension.** The SDK pads message plaintext to 160-byte buckets with ISO 7816-4
503
+ bit padding, which is a `0x80` terminator followed by zeros
471
504
  (`internal/crypto/symmetric/padding.ts:19-60`). Unpadding scans backwards and
472
- rejects malformed padding with a deliberately generic error to avoid a padding
473
- oracle.
505
+ rejects malformed padding with a deliberately generic error, which avoids a
506
+ padding oracle.
474
507
 
475
- `libsignal` does not bucket-pad at this layer; in Signal Messenger, that lives in the client
476
- applications. Doing it in the library means length hiding is on by default rather
477
- than a thing each integrator must remember.
508
+ `libsignal` does not bucket-pad at this layer. In Signal Messenger, that step
509
+ lives in the client applications. Padding in the library turns length hiding on
510
+ by default, instead of leaving it for each integrator to remember.
478
511
 
479
- One imprecision: because the padded plaintext is an exact multiple of 160 and
480
- AES-CBC then applies PKCS#7, a full block is always appended. A 5-byte message
481
- produces 160 padded bytes and 176 ciphertext bytes. Length is still quantized in
482
- 160-byte steps, so the hiding property holds; the ciphertext simply sits 16 bytes
483
- past each boundary rather than on it.
512
+ One imprecision follows. The padded plaintext is an exact multiple of 160, and
513
+ AES-CBC then applies PKCS#7, so every message gets a full extra block. A 5-byte
514
+ message produces 160 padded bytes and 176 ciphertext bytes. Length is still
515
+ quantized in 160-byte steps, so the hiding property holds. The ciphertext simply
516
+ sits 16 bytes past each boundary rather than on it.
484
517
 
485
518
  ---
486
519
 
@@ -496,8 +529,8 @@ independently and pinned against commit `fd32048`, which upstream tags
496
529
  "Signal_PQCKA_V1_MLKEM768"` and the `:ekheader` / `:ciphertext` MAC inputs
497
530
  (`internal/protocol/spqr/ml-kem-braid/kdf.ts:32-92`).
498
531
  - **The Reed–Solomon erasure layer matches**: GF(2^16) with primitive polynomial
499
- `0x1100b`, 32-byte chunks, 16 polynomials, degree bound 35. Reed–Solomon is
500
- present in `libsignal`; it is not an SDK addition.
532
+ `0x1100b`. Chunks are 32 bytes, with 16 polynomials and degree bound 35.
533
+ Reed–Solomon comes from `libsignal`. It is not an SDK addition.
501
534
  - **The production wire framing is byte-compatible**:
502
535
  `VERSION ‖ LEB128(epoch) ‖ LEB128(chain_index) ‖ MSG_TYPE ‖ [LEB128(chunk_index) ‖ CHUNK]`
503
536
  (`internal/encoding/proto/pq-ratchet-serialize.ts`), matching `libsignal`'s
@@ -526,8 +559,8 @@ One divergence breaks interoperability completely. The SDK computes
526
559
  hek = SHA3-256(ek_seed || ek_vector)
527
560
  ```
528
561
 
529
- `libsignal`, via libcrux, builds the encapsulation key as
530
- `t̂ ‖ ρ` before hashing — the reverse order.
562
+ `libsignal`, through libcrux, builds the encapsulation key as `t̂ ‖ ρ` before
563
+ hashing. That is the reverse order.
531
564
 
532
565
  The SDK follows the **normative text of the published ML-KEM Braid
533
566
  specification**, which states seed-first ordering. `libsignal` follows FIPS 203,
@@ -535,21 +568,28 @@ which serializes vector-first. The specification and the reference implementatio
535
568
  disagree, and the SDK chose the specification.
536
569
 
537
570
  The value feeds the Fujisaki–Okamoto transform, so the consequences cascade:
538
- different header bytes, so `libsignal`'s header validation rejects the SDK's output;
539
- different ciphertext; different shared secret; different epoch secret; different
540
- authenticator ratchet. **A braid session between this SDK and Signal Messenger's
541
- implementation cannot complete a single epoch.**
571
+
572
+ - different header bytes, so `libsignal`'s header validation rejects the SDK's
573
+ output
574
+ - a different ciphertext
575
+ - a different shared secret
576
+ - a different epoch secret
577
+ - a different authenticator ratchet
578
+
579
+ **A braid session between this SDK and Signal Messenger's implementation cannot
580
+ complete a single epoch.**
542
581
 
543
582
  Two further consequences a reader should not have to infer:
544
583
 
545
584
  - **In braid mode the KEM is not FIPS 203 ML-KEM-768.** It is ML-KEM-768 with a
546
- modified `hek` derivation. The security argument is unaffected — the hash input
547
- is a permutation of the same material — but a FIPS conformance claim would not
548
- hold for this path. Direct (non-braid) mode uses stock ML-KEM-768.
549
- - The SDK resolves the same spec-versus-code conflict in the *opposite* direction
550
- elsewhere: for `KDF_AUTH`, it follows the `libsignal` Rust reference rather than the
551
- written specification. The two choices are individually defensible and
552
- collectively inconsistent about which artifact is authoritative.
585
+ modified `hek` derivation. The change does not weaken the security argument,
586
+ because the hash input permutes the same material. A FIPS conformance claim
587
+ still does not hold for this path. Direct (non-braid) mode uses stock
588
+ ML-KEM-768.
589
+ - Elsewhere the SDK resolves the same spec-versus-code conflict in the *opposite*
590
+ direction. For `KDF_AUTH` it follows the `libsignal` Rust reference rather than
591
+ the written specification. Each choice is defensible on its own. Together they
592
+ are inconsistent about which artifact is authoritative.
553
593
 
554
594
  The operand order is part of the public compatibility boundary stated in
555
595
  [Protocol Policy](./PROTOCOL_POLICY.md). Changing it later would invalidate every
@@ -559,9 +599,10 @@ braid session persisted under the former ordering.
559
599
 
560
600
  **Extension.** An opt-in direct mode (`protocol.braid: 'disabled'`) uses stock
561
601
  ML-KEM-768 and adds wire message types `0x80`–`0x82`
562
- (`internal/encoding/proto/pq-ratchet-serialize.ts:40-45`). `libsignal`'s parser rejects
563
- anything above `6`, so these are visible only within the SDK; they occupy a byte
564
- range `libsignal` has not claimed. This mode has no Signal Protocol analogue.
602
+ (`internal/encoding/proto/pq-ratchet-serialize.ts:40-45`). `libsignal`'s parser
603
+ rejects anything above `6`, so these types are visible only within the SDK. They
604
+ occupy a byte range `libsignal` has not claimed. This mode has no Signal Protocol
605
+ analogue.
565
606
 
566
607
  **Independent design.** Persisted SPQR state uses a flat message with 20 fields
567
608
  where `libsignal` uses an 11-variant `oneof` over nested structures. Serialized SPQR
@@ -569,8 +610,8 @@ state is not portable in either direction.
569
610
 
570
611
  **Deviation.** Skipped-key eviction in the SPQR chain triggers at the cap and
571
612
  evicts by wall-clock timestamp, where `libsignal` triggers at `max_ooo × 11/10 + 1` and
572
- evicts by message index. `libsignal`'s rule is deterministic and index-anchored; the
573
- SDK's introduces a clock dependency into ratchet state.
613
+ evicts by message index. `libsignal`'s rule is deterministic and index-anchored.
614
+ The SDK's rule puts a clock dependency into ratchet state.
574
615
 
575
616
  **Deviation.** The varint decoder is the stricter of the two. It rejects any
576
617
  value above `uint64` (`internal/encoding/proto/pq-ratchet-serialize.ts:163-186`).
@@ -605,104 +646,113 @@ format, so this entry records the divergence rather than repairing it.
605
646
 
606
647
  ### 4.3 The Triple Ratchet is faithful
607
648
 
608
- The post-quantum secret enters as the HKDF **salt** at message-key expansion, with
609
- the classical message key as IKM and the `WhisperMessageKeys` label
610
- (`internal/session/cipher.ts:453-510`) — the same combination order and the same
611
- label as [`triple_ratchet.rs`][tr]. There is no root-key braiding in either
612
- implementation.
649
+ The post-quantum secret enters as the HKDF **salt** at message-key expansion. The
650
+ classical message key is the IKM, and the label is `WhisperMessageKeys`
651
+ (`internal/session/cipher.ts:453-510`). [`triple_ratchet.rs`][tr] uses the same
652
+ combination order and the same label. Neither implementation braids the root key.
613
653
 
614
- Note that `internal/protocol/triple-ratchet/` contains a second, unused hybrid KDF
615
- using the label `'Signal Triple Ratchet V1'`. It is exported but not called from
616
- the message path, and it is incompatible with what the SDK actually puts on the
617
- wire. It is documented in the PR that accompanied this file as cleanup work.
654
+ `internal/protocol/triple-ratchet/` holds a second, unused hybrid KDF under the
655
+ label `'Signal Triple Ratchet V1'`. The barrel exports it, but the message path
656
+ never calls it, and it does not match what the SDK puts on the wire. The PR that
657
+ accompanied this file records it as cleanup work.
618
658
 
619
659
  ---
620
660
 
621
661
  ## 5. Sesame
622
662
 
623
- Sesame has no reference implementation to compare against — `libsignal` does not
624
- implement it; device and session management lives in the Signal Messenger service and its
625
- clients. Everything below is measured against the pinned specification text
626
- (revision 2) alone.
663
+ Sesame has no reference implementation to compare against. `libsignal` does not
664
+ implement it. Device and session management lives in the Signal Messenger service
665
+ and its clients. This section therefore measures the SDK against the pinned
666
+ specification text (revision 2) alone.
667
+
668
+ These parts are faithful:
669
+
670
+ - the user-record and device-record structure (§3.1)
671
+ - the per-device session fan-out on send, including the sender's own other
672
+ devices (§3.3)
673
+ - the bounded send loop (§3.3, §6.5)
674
+ - discarding all changes transactionally on error (§3.3, §3.4, §6.7)
675
+ - creating a session on receive only from an initiating message (§3.4)
627
676
 
628
- Faithful: the user-record and device-record structure (§3.1), the per-device
629
- session fan-out on send including the sender's own other devices (§3.3), the
630
- bounded send loop (§3.3, §6.5), discard-all-changes-on-error handled
631
- transactionally (§3.3, §3.4, §6.7), and creating a session on receive only from an
632
- initiating message (§3.4). The per-user identity model is one of the two the
633
- specification explicitly permits (§3.1).
677
+ The per-user identity model is one of the two models the specification permits
678
+ (§3.1).
634
679
 
635
- ### 5.1 Deleted devices are removed rather than marked stale
680
+ ### 5.1 The SDK removes deleted devices instead of marking them stale
636
681
 
637
- §3.1 and §3.3 require a removed device's record to be marked stale and retained
638
- for MAXLATENCY, so that messages already in flight from that device still
639
- decrypt. The SDK removes the record immediately
682
+ §3.1 and §3.3 require an implementation to mark a removed device's record stale
683
+ and keep it for MAXLATENCY. Messages already in flight from that device then
684
+ still decrypt. The SDK removes the record immediately
640
685
  (`internal/sesame/manager.ts:2098-2102`).
641
686
 
642
- **Consequence, stated plainly: a message sent by a device that was removed moments
643
- earlier becomes permanently undecryptable.** The specification's staleness window
644
- exists precisely to prevent this. This is the most substantive contradiction of
645
- the Sesame text in the codebase.
687
+ **State the consequence plainly. A message that a device sent moments before its
688
+ removal becomes permanently undecryptable.** The specification's staleness window
689
+ exists to prevent exactly that. No other part of the codebase contradicts the
690
+ Sesame text this directly.
646
691
 
647
- Relatedly, the SDK reuses the word `stale` for a different concept — a device
648
- *list* that needs refetching (`internal/sesame/types.ts:476-483`) — rather than
649
- the specification's meaning of a deleted user or device.
692
+ The SDK also reuses the word `stale` for a different concept: a device *list*
693
+ that needs refetching (`internal/sesame/types.ts:476-483`). The specification uses
694
+ the word for a deleted user or device.
650
695
 
651
696
  ### 5.2 Session expiry applies only to unacknowledged sessions
652
697
 
653
- §4.2 is unconditional: at MAXSEND past its timestamp, a session must no longer be
654
- used for encryption. The SDK applies that bound only to sessions that have never
655
- received a reply (`internal/sesame/types.ts:175-199`). A session that received one
656
- message on its first day remains a valid encryption session indefinitely.
698
+ §4.2 is unconditional. At MAXSEND past its timestamp, a session may no longer
699
+ encrypt. The SDK applies that bound only to sessions that never received a reply
700
+ (`internal/sesame/types.ts:175-199`). A session that received one message on its
701
+ first day stays a valid encryption session indefinitely.
657
702
 
658
- The configuration field is honestly renamed to `maxUnacknowledgedSessionAge` to
659
- reflect this. The gap worth naming is that the §4.2 invariant check
660
- (`internal/sesame/validation.ts:93-101`) is still validated against that renamed
661
- quantity, so it is enforcing the specification's arithmetic over a value that no
703
+ The configuration field carries the honest name `maxUnacknowledgedSessionAge`.
704
+ One gap follows. The §4.2 invariant check
705
+ (`internal/sesame/validation.ts:93-101`) still runs against that renamed
706
+ quantity. It therefore applies the specification's arithmetic to a value that no
662
707
  longer carries the specification's meaning.
663
708
 
664
709
  ### 5.3 Device limit
665
710
 
666
- A hard cap of 5 devices per user (`internal/sesame/types.ts:45-50`, enforced at
667
- `internal/sesame/manager.ts:285-290`). §6.5 recommends *a* limit without fixing
668
- one; `libsignal` permits device IDs up to 127. This is a product decision, and a
669
- source comment attributing it to the Signal Protocol is inaccurate.
711
+ The SDK caps a user at 5 devices (`internal/sesame/types.ts:45-50`).
712
+ The file `internal/sesame/manager.ts:285-290` enforces the cap. The
713
+ specification's §6.5 recommends *a* limit without fixing one, and `libsignal`
714
+ permits device IDs up to 127. The cap is a
715
+ product decision. A source comment credits it to the Signal Protocol, which is
716
+ inaccurate.
670
717
 
671
718
  ### 5.4 Extensions: provisioning, transfer, device names
672
719
 
673
- None of these exist in Sesame rev. 2, which says nothing about how devices come to
674
- exist, are named, or migrate.
720
+ Sesame rev. 2 holds none of these. It says nothing about how a device comes to
721
+ exist, takes a name, or migrates.
675
722
 
676
723
  **QR device provisioning** (`device/provisioning.ts`). Ephemeral X25519 ECDH →
677
724
  HKDF → AES-256-GCM, with a `signalprotocol://link-device` QR scheme, strict prefix
678
725
  and key validation, a 5-minute TTL, and rollback on both server and local failure.
679
- The construction is sound. The property worth naming: the provisioning key is not
680
- bound to the primary device's long-term identity, so the channel is authenticated
681
- only by out-of-band display of the QR code.
726
+ The construction is sound. One property is worth naming. Nothing binds the
727
+ provisioning key to the primary device's long-term identity. The only
728
+ authentication for the channel is the out-of-band display of the QR code.
682
729
 
683
730
  **Device transfer** (`device/transfer.ts`). Clones the identity private key and
684
- live ratchet state to a new device. This is useful and it **violates the
685
- invariant Sesame is built on** — one device record, one device, its own sessions.
686
- After a transfer, two physical devices hold the same identity private key and the
687
- same ratchet state for every peer. Peer messages decrypted by one desynchronize
688
- the other, and duplicating ratchet state weakens the forward-secrecy guarantee
689
- that compromise of one endpoint is bounded to that endpoint. Archived sessions are
690
- deliberately dropped on restore, which also discards the convergence state §3.4
691
- depends on.
731
+ live ratchet state to a new device. This is useful, and it **breaks the invariant
732
+ that Sesame rests on**: one device record, one device, its own sessions. After a
733
+ transfer, two physical devices hold the same identity private key and the same
734
+ ratchet state for every peer.
735
+
736
+ A peer message that one device decrypts desynchronizes the other. The duplicated
737
+ ratchet state also weakens the
738
+ forward-secrecy guarantee that keeps the compromise of one endpoint within that
739
+ endpoint. Restore deliberately drops archived sessions, which discards the
740
+ convergence state that §3.4 needs.
692
741
 
693
742
  **Encrypted device names** (`device/device-name-crypto.ts`). A three-field
694
- protobuf with a synthetic IV derived by HMAC and AES-256-CTR — the standard SIV
695
- pattern, correctly constructed. No specification counterpart.
743
+ protobuf carries a synthetic IV that HMAC derives, with AES-256-CTR. That is the
744
+ standard SIV pattern, correctly constructed. The specification has no
745
+ counterpart.
696
746
 
697
- **Identity-change gating.** Unseen identities are TOFU-pinned; a changed identity
698
- sets `pendingVerification` and blocks sending until the application accepts the
699
- rotation (`internal/sesame/manager.ts:561-566`, `:1682-1714`). Sesame rev. 2 has
700
- no such concept. This is a genuine improvement.
747
+ **Identity-change gating.** The SDK TOFU-pins an unseen identity. A changed
748
+ identity sets `pendingVerification` and blocks sending until the application
749
+ accepts the rotation (`internal/sesame/manager.ts:561-566`, `:1682-1714`). Sesame
750
+ rev. 2 has no such concept. This is a genuine improvement.
701
751
 
702
- **Not implemented:** proof of possession. Device registration does not require the
703
- device to sign a server-issued nonce with the identity private key, so
704
- registration places more trust in the relay than §6.3's discussion assumes. A
705
- deployment that needs this must add it at the application layer.
752
+ **Not implemented:** proof of possession. Registration does not make the device
753
+ sign a server-issued nonce with its identity private key. Registration therefore
754
+ trusts the relay more than §6.3 assumes. A deployment that needs proof of
755
+ possession must add it at the application layer.
706
756
 
707
757
  ---
708
758
 
@@ -710,81 +760,91 @@ deployment that needs this must add it at the application layer.
710
760
 
711
761
  ### 6.1 Version 2 is faithful
712
762
 
713
- All four HKDF labels are byte-identical, the KEM construction and its
714
- direction-swapped IKM orderings match, the authentication tag is the same 16-byte
715
- raw HKDF output, AES-256-GCM-SIV is used with a zero nonce and no AAD as
716
- `libsignal` does, and the multi-recipient binary format — version bytes
717
- `0x22`/`0x23`, varint count, 17-byte ServiceIds, the packed device ID and 14-bit
718
- registration ID, the `0x3FFF` mask — matches ([`sealed_sender.rs:1023-1153`][ss],
719
- `:1306-1360`). Certificate validation order and semantics match as well, including
720
- the non-short-circuiting trust-root loop that avoids revealing which root
721
- validated.
763
+ These parts match `libsignal`:
764
+
765
+ - all four HKDF labels, byte for byte
766
+ - the KEM construction and its direction-swapped IKM orderings
767
+ - the authentication tag, which is the same 16-byte raw HKDF output
768
+ - AES-256-GCM-SIV with a zero nonce and no AAD
769
+ - the multi-recipient binary format ([`sealed_sender.rs:1023-1153`][ss],
770
+ `:1306-1360`): version bytes `0x22`/`0x23`, the varint count, and 17-byte
771
+ ServiceIds
772
+ - the packed device ID with its 14-bit registration ID and `0x3FFF` mask
773
+
774
+ Certificate validation order and semantics match as well. That includes the
775
+ trust-root loop, which does not short-circuit and therefore does not reveal which
776
+ root validated.
722
777
 
723
778
  ### 6.2 Version 1 diverges in three places
724
779
 
725
- **The 96-byte HKDF output is split in a different order.** `libsignal` derives
726
- `(chain_key, cipher_key, mac_key)` ([`sealed_sender.rs:711-746`][ss]); the SDK
727
- derives `(cipher, mac, chain)`
780
+ **The SDK splits the 96-byte HKDF output in a different order.** `libsignal`
781
+ derives `(chain_key, cipher_key, mac_key)` ([`sealed_sender.rs:711-746`][ss]).
782
+ The SDK derives `(cipher, mac, chain)`
728
783
  (`internal/protocol/sealed-sender/encryption.ts:164-166`). The construction is
729
- self-consistent and secure — the keys are independent HKDF output either way — but
730
- every v1 key sits in a different slot than `libsignal`'s. This is an
731
- implementation divergence rather than a design decision, and the SDK's own pinned
732
- specification document records the same order, so the two are at least consistent
733
- with each other.
784
+ self-consistent and secure, because the keys are independent HKDF output either
785
+ way. Every v1 key still sits in a different slot than `libsignal`'s. This is an
786
+ implementation divergence rather than a design decision. The SDK's own pinned
787
+ specification document records the same order, so the two agree with each other.
734
788
 
735
789
  **Public keys in the v1 salt and in certificates omit the `0x05` type byte.**
736
- `libsignal` uses the 33-byte serialized form; the SDK uses raw 32 bytes and
790
+ `libsignal` uses the 33-byte serialized form. The SDK uses raw 32 bytes and
737
791
  enforces that length
738
- (`internal/protocol/sealed-sender/certificate.ts:306-309`). Notably the SDK's own
739
- v2 path *does* apply the `0x05` prefix, so the two sealed-sender versions are
740
- internally inconsistent about this.
792
+ (`internal/protocol/sealed-sender/certificate.ts:306-309`). The SDK's own v2 path
793
+ *does* apply the `0x05` prefix, so the two sealed-sender versions disagree with
794
+ each other.
741
795
 
742
796
  **The inner envelope is a hand-rolled varint format**
743
797
  (`internal/protocol/sealed-sender/encryption.ts:46-86`) rather than the
744
- `UnidentifiedSenderMessage.Message` protobuf. It does carry the message-type
745
- field `libsignal` uses to dispatch between prekey, regular, sender-key, and
746
- plaintext payloads ([`sealed_sender.rs:2055-2075`][ss]), as a leading byte
747
- using `libsignal`'s enum values, so the framing differs but the dispatch does
748
- not. The field is what lets the unseal path restore the real message type
749
- rather than reconstruct the envelope with a fixed one, which is what sealed
750
- group messages need to decrypt as group messages.
798
+ `UnidentifiedSenderMessage.Message` protobuf. It still carries the message-type
799
+ field that `libsignal` dispatches on, which selects between prekey, regular,
800
+ sender-key, and plaintext payloads ([`sealed_sender.rs:2055-2075`][ss]). The
801
+ field is a leading byte holding `libsignal`'s enum values. The framing therefore
802
+ differs while the dispatch does not.
803
+
804
+ That field lets the unseal path restore the real message type. Without it the
805
+ path would rebuild the envelope with a fixed type, and a sealed group message
806
+ would not decrypt as a group message.
751
807
 
752
808
  **`PLAINTEXT_CONTENT` (8) is a known wire value that this SDK rejects.**
753
809
  `libsignal` uses it to carry a `DecryptionErrorMessage` when no session exists
754
- to encrypt one under ([`sealed_sender.rs:2055-2075`][ss]). This SDK delivers
755
- decryption-error signals over a dedicated relay channel instead — the
756
- `retryRequests` table and `sendRetryRequest`, per Sesame §4.1 — so no send path
757
- produces the type and no decrypt path consumes it. It is therefore rejected at
758
- the envelope parse (`internal/protocol/sealed-sender/types.ts`) rather than
759
- mapped to an envelope type with no handler. The enum retains the member so the
760
- wire values stay a faithful record, and `envelopeTypeForContent` throws on it so
761
- that adding a member without a route fails loudly. A peer that sends one gets a
762
- clean parse failure, not a payload routed into the pairwise ratchet.
763
-
764
- Note the cost when debugging interop. The parsers throw a single generic error
765
- for every malformed envelope, so a peer implementation that legitimately sends
766
- `PLAINTEXT_CONTENT` fails with `Sealed sender verification failed` — the same
767
- string a MAC mismatch produces. The uniformity is deliberate and the parse runs
768
- after authentication, so nothing here is an oracle; but if sealed messages from
769
- one particular peer stack fail with that error while messages from this SDK
770
- succeed, check the leading content-type byte before treating it as a
771
- cryptographic failure.
810
+ to encrypt one under ([`sealed_sender.rs:2055-2075`][ss]). This SDK instead
811
+ delivers decryption-error signals over a dedicated relay channel. Sesame §4.1
812
+ defines that channel, and the SDK builds it from the `retryRequests` table and
813
+ `sendRetryRequest`. No send path produces the type, and no decrypt path consumes
814
+ it. The envelope parse therefore
815
+ rejects the value (`internal/protocol/sealed-sender/types.ts`) rather than map it
816
+ to an envelope type with no handler.
817
+
818
+ The enum keeps the member so the wire values stay a faithful record.
819
+ `envelopeTypeForContent` throws on it, so a new member without a route fails
820
+ loudly. A peer that sends one gets a clean parse failure, not a payload routed
821
+ into the pairwise ratchet.
822
+
823
+ Note the cost when you debug interop. The parsers throw a single generic error
824
+ for every malformed envelope. A peer implementation that legitimately sends
825
+ `PLAINTEXT_CONTENT` therefore fails with `Sealed sender verification failed`,
826
+ which is the same string a MAC mismatch produces. The uniformity is deliberate,
827
+ and the parse runs after authentication, so nothing here is an oracle. Watch for
828
+ one pattern: sealed messages from one peer stack fail with that error while
829
+ messages from this SDK succeed. Check the leading content-type byte before you
830
+ treat that as a cryptographic failure.
772
831
 
773
832
  ### 6.3 The delivery token follows `libsignal`, not an SDK invention
774
833
 
775
834
  Despite the module name, `deriveAccessKey`
776
835
  (`internal/protocol/sealed-sender/delivery-token.ts:52-91`) is `libsignal`'s
777
- `ProfileKey::derive_access_key` — AES-256-GCM over 16 zero bytes with a zero
778
- nonce, truncated to 16 bytes — and it reproduces the values `libsignal`
779
- publishes for that derivation. It is a 16-byte value derived from the
780
- recipient's profile key
781
- that proves to the relay that the sender knows that profile key, gating anonymous
782
- delivery to contacts. It never enters the sealed-sender wire format; it is
783
- presented out of band.
784
-
785
- The SDK's own documentation previously described a different, 12-byte HKDF
786
- construction that no code implements. That description is wrong and is corrected
787
- in the PR accompanying this file.
836
+ `ProfileKey::derive_access_key`. It runs AES-256-GCM over 16 zero bytes with a
837
+ zero nonce and truncates to 16 bytes. It reproduces the values `libsignal`
838
+ publishes for that derivation.
839
+
840
+ The 16-byte value comes from the recipient's profile key. It proves to the relay
841
+ that the sender knows that profile key, which gates anonymous delivery to
842
+ contacts. It never enters the sealed-sender wire format. The sender presents it
843
+ out of band.
844
+
845
+ The SDK's own documentation once described a different, 12-byte HKDF
846
+ construction that no code implements. That description is wrong, and the PR that
847
+ accompanies this file corrects it.
788
848
 
789
849
  Certificate signatures use Ed25519 rather than XEdDSA, per §1.2, so SDK
790
850
  certificates cannot validate against a Signal Messenger trust root or vice versa. The
@@ -797,29 +857,33 @@ appropriate for a different trust root but worth noting.
797
857
 
798
858
  ### 7.1 Sender key message format
799
859
 
800
- Protobuf field numbers and types match [`wire.proto`][wp] exactly, the
801
- `[version byte] ‖ protobuf ‖ [64-byte signature]` framing with version `0x33`
802
- matches, the `0x01`/`0x02` chain seeds and the `WhisperGroup` info string match,
803
- AES-256-CBC with the derived IV matches, and the capacity constants match.
860
+ These parts match:
861
+
862
+ - protobuf field numbers and types, against [`wire.proto`][wp] exactly
863
+ - the `[version byte] ‖ protobuf ‖ [64-byte signature]` framing with version
864
+ `0x33`
865
+ - the `0x01`/`0x02` chain seeds and the `WhisperGroup` info string
866
+ - AES-256-CBC with the derived IV
867
+ - the capacity constants
804
868
 
805
869
  Three things do not:
806
870
 
807
- **`distributionUuid` carries a UTF-8 string, not 16 UUID bytes.** The SDK writes
871
+ **`distributionUuid` carries a UTF-8 string, not 16 UUID bytes**. The SDK writes
808
872
  the 36-character textual form of a random UUIDv4
809
- (`internal/protocol/sender-keys/manager.ts:279`, `:932`); `libsignal` writes
810
- exactly the 16 raw bytes and rejects anything else on parse. The value is now
811
- the same *kind* of thing `libsignal` uses — an opaque random identifier
812
- unrelated to the group — but the encoding still differs, so the frames remain
813
- mutually unparseable. Related: `chain_id` is an FNV-1a hash of that string
873
+ (`internal/protocol/sender-keys/manager.ts:279`, `:932`). `libsignal` writes
874
+ exactly the 16 raw bytes and rejects anything else on parse. The value is the
875
+ same *kind* of thing `libsignal` uses, an opaque random identifier with no
876
+ relation to the group. The encoding still differs, so neither side can parse the
877
+ other's frames. One related point: `chain_id` is an FNV-1a hash of that string
814
878
  rather than a random 31-bit value.
815
879
 
816
- Until recently the SDK wrote `groupId:userId:deviceId:timestamp` here, which was
817
- a metadata leak rather than a format deviation: `distributionUuid` sits outside
818
- the ciphertext, so every relay on the path could read the plaintext group and
819
- sender off each message. That is fixed; the sender-keys specification now
820
- requires the identifier to be opaque.
880
+ The SDK once wrote `groupId:userId:deviceId:timestamp` here. That was a metadata
881
+ leak rather than a format deviation, because `distributionUuid` sits outside the
882
+ ciphertext. Every relay on the path could read the plaintext group and sender off
883
+ each message. The current code fixes it, and the sender-keys specification now
884
+ requires an opaque identifier.
821
885
 
822
- **Signatures are Ed25519, not XEdDSA**, per §1.2 — and `libsignal` serializes the
886
+ **Signatures are Ed25519, not XEdDSA**, per §1.2. `libsignal` also serializes the
823
887
  signing key as 33 bytes where the SDK uses 32.
824
888
 
825
889
  ### 7.2 Message-key derivation omits HKDF-Extract
@@ -829,68 +893,74 @@ make the format look compatible.
829
893
 
830
894
  `libsignal` derives sender message keys with
831
895
  `Hkdf::<Sha256>::new(None, &seed).expand(b"WhisperGroup", 48)`
832
- ([`sender_keys.rs:36-38`][sk]). `Hkdf::new` performs HKDF-**Extract** first:
896
+ ([`sender_keys.rs:36-38`][sk]). `Hkdf::new` runs HKDF-**Extract** first, as
833
897
  `PRK = HMAC-SHA256(salt = zeros[32], seed)`. Only then does it expand.
834
898
 
835
899
  The SDK calls `hkdfExpand(seed, info, 48)` directly
836
900
  (`internal/protocol/sender-keys/manager.ts:1062-1066`), where `hkdfExpand`
837
901
  (`internal/crypto/kdf/hkdf.ts:86-116`) is pure RFC 5869 Expand using the seed
838
- itself as the PRK. The extract step is missing.
902
+ itself as the PRK. The SDK never runs the extract step.
839
903
 
840
904
  The derived IV and cipher key therefore differ from `libsignal`'s for the same
841
- chain key. This was confirmed numerically, not merely by inspection: for a chain
905
+ chain key. A numeric check confirms it, rather than inspection alone. For a chain
842
906
  key of 32 repeated `0x42` bytes, the SDK derives IV
843
907
  `2a56b9eb80b3c1ffebd97221b2175960` where `libsignal` derives
844
908
  `890d51ea73e564722351dc0d5a09142c`.
845
909
 
846
- This appears unintentional. It is not a weakness — omitting Extract from a
847
- uniformly random HMAC output is cryptographically fine — but the repository's own
848
- sender-keys note claims equivalence with `libsignal` at this step, and that claim
849
- is incorrect. Flagged for correction.
910
+ This appears unintentional. It is not a weakness, because dropping Extract from a
911
+ uniformly random HMAC output is cryptographically sound. The repository's own
912
+ sender-keys note still claims equivalence with `libsignal` at this step, and that
913
+ claim is incorrect. This entry flags it for correction.
850
914
 
851
915
  ### 7.3 Groups are an independent design
852
916
 
853
917
  The zero-knowledge primitives underneath are real and faithful (§7.4). The group
854
918
  system built on them is not the Signal Private Group System.
855
919
 
856
- What is faithful: role and access-control enum values match `libsignal`'s exactly,
857
- group ID derivation from the master key is correct, the `open-e2ee:group:`
858
- identifier namespace is package-owned, authentication genuinely uses zkgroup
859
- credentials, and member identifiers and profile keys are encrypted with real
860
- `UidCiphertext` and `ProfileKeyCiphertext`.
920
+ These parts are faithful:
921
+
922
+ - role and access-control enum values, which match `libsignal`'s exactly
923
+ - group ID derivation from the master key
924
+ - the `open-e2ee:group:` identifier namespace, which the package owns
925
+ - authentication, which uses real zkgroup credentials
926
+ - member identifiers and profile keys, which the SDK encrypts into real
927
+ `UidCiphertext` and `ProfileKeyCiphertext` values
861
928
 
862
929
  What differs, and it is structural:
863
930
 
864
- **The enforcement contract is this SDK's own.** Like the Signal Private Group
865
- System, the client submits change actions carrying zero-knowledge
866
- presentations, and the **server** validates every action against the group's
867
- access control before signing and persisting the accepted result. The
868
- enforcement rules are the SDK's own specified S1–S14 contract rather than
869
- Signal Messenger's server implementation, and the shipped enforcing server
931
+ **The enforcement contract is this SDK's own**. The client submits change actions
932
+ that carry zero-knowledge presentations, as it does in the Signal Private Group
933
+ System. The **server** then validates every action against the group's access
934
+ control before it signs and persists the accepted result.
935
+
936
+ The enforcement rules are the SDK's own S1–S14 contract rather than Signal
937
+ Messenger's server implementation. The shipped enforcing server
870
938
  (`internal/groups/server-engine.ts`, with an installable Convex component)
871
- implements that contract. Clients verify the
872
- server's signature, group binding, strict version sequence, and pre-state
873
- authorization on every applied change.
939
+ implements that contract. On every applied change, clients verify the server's
940
+ signature, the group binding, the strict version sequence, and the pre-state
941
+ authorization.
874
942
 
875
- **Profile-key credential issuance is not blinded.** The issuance endpoint
943
+ **Profile-key credential issuance is not blinded**. The issuance endpoint
876
944
  receives the raw 32-byte profile key, so the issuing server sees every user's
877
- profile key in plaintext at issuance time. The Signal Private Group System
878
- issues profile-key credentials over a *blinded* commitment, so its server
879
- never learns the key. The blinding primitives exist in this codebase
880
- (`internal/protocol/zk/credentials/issuance.ts`) but are not wired into this
881
- path; §12.1 of the in-tree group specification carries the same caveat.
882
- A deployer must treat the issuance server as learning profile keys — and
883
- therefore profile names and avatars — until blinded issuance ships.
945
+ profile key in plaintext at issuance time. The Signal Private Group System issues
946
+ profile-key credentials over a *blinded* commitment, so its server never learns
947
+ the key. The blinding primitives exist in this codebase
948
+ (`internal/protocol/zk/credentials/issuance.ts`), but nothing wires them into
949
+ this path. Section 12.1 of the in-tree group specification carries the same
950
+ caveat.
951
+
952
+ Until blinded issuance ships, a deployer must assume that the issuance server
953
+ learns profile keys, and therefore profile names and avatars.
884
954
 
885
955
  **Serialization is JSON**, not protobuf, both for group state
886
956
  (`internal/groups/manager.ts:1229-1236`) and for the blob payloads inside the
887
- AES-256-GCM-SIV envelope (`internal/groups/encrypted-state.ts:70-81`). Every
888
- encrypted group title and description is undecryptable by Signal Messenger even with the
957
+ AES-256-GCM-SIV envelope (`internal/groups/encrypted-state.ts:70-81`). Signal
958
+ Messenger cannot decrypt an encrypted group title or description, even with the
889
959
  correct master key.
890
960
 
891
961
  **Invite links** use `https://join.open-e2ee.dev/#` with a 49-byte raw payload
892
962
  (`internal/groups/invite-link.ts:36`, `:78-85`), where `libsignal` uses
893
- `https://signal.group/#` with a protobuf. This is labelled accurately in source as
963
+ `https://signal.group/#` with a protobuf. The source labels this accurately as
894
964
  the package's own format.
895
965
 
896
966
  ### 7.4 The zero-knowledge layer is a faithful port
@@ -899,22 +969,27 @@ Stated directly, because "zk" in a codebase often means something weaker: this i
899
969
  a genuine zero-knowledge credential system, not HMAC tokens, not signatures, not a
900
970
  placeholder.
901
971
 
902
- `internal/protocol/zk/` implements the Sigma protocol over Ristretto255 with
903
- Fiat–Shamir, matching `poksho`'s protocol label
904
- `POKSHO_Ristretto_SHOHMACSHA256` exactly, and the Chase–Perrin–Zaverucha algebraic
905
- MAC credential system matching `zkcredential`'s five domain labels byte for byte.
906
- The Lizard encoding, `UidStruct` derivation, `AuthCredentialWithPni` flow, and
907
- redemption window all match `libsignal`. The strongest evidence is a test that
908
- asserts the 416-byte serialized system parameters against a hex string taken from
909
- `libsignal`'s own Rust test, and passes.
910
-
911
- One deviation: server secret parameters are derived as four separately labelled
912
- key derivations rather than `libsignal`'s single seeded derivation
913
- (`internal/protocol/zk/groups/server-params.ts:43-54`), so the same randomness
914
- would yield different server keys. Independently of that structural difference,
915
- each deployment generates its **own** random 32-byte seed, which is what makes
916
- the trust root the deploying operator's rather than Signal Messenger's.
917
- Credentials are not interchangeable with Signal Messenger's.
972
+ The directory `internal/protocol/zk/` implements the Sigma protocol over
973
+ Ristretto255 with Fiat–Shamir. It matches `poksho`'s protocol label
974
+ `POKSHO_Ristretto_SHOHMACSHA256` exactly. It also implements the
975
+ Chase–Perrin–Zaverucha algebraic MAC credential system, which matches
976
+ `zkcredential`'s five domain labels byte for byte. The Lizard encoding, the
977
+ `UidStruct` derivation, the `AuthCredentialWithPni` flow, and the redemption
978
+ window all match `libsignal`.
979
+
980
+ One test carries the strongest evidence. It asserts the 416-byte serialized
981
+ system parameters against a hex string taken from `libsignal`'s own Rust test,
982
+ and it passes.
983
+
984
+ One deviation remains. The SDK derives server secret parameters through four
985
+ separately labelled key derivations, where `libsignal` uses a single seeded
986
+ derivation (`internal/protocol/zk/groups/server-params.ts:43-54`). The same
987
+ randomness therefore yields different server keys.
988
+
989
+ That structural difference stands on its own. Separately, each deployment
990
+ generates its **own** random 32-byte seed, which puts the trust root with the
991
+ deploying operator rather than with Signal Messenger. No credential is
992
+ interchangeable with a Signal Messenger credential.
918
993
 
919
994
  Credential serialization is also ad hoc and carries no version byte, where
920
995
  `libsignal` uses a leading version byte. That is a forward-compatibility gap
@@ -924,49 +999,56 @@ rather than a security one.
924
999
 
925
1000
  ## Unverified and needs review
926
1001
 
927
- Listed rather than asserted, because these could not be confirmed in source
928
- within this review.
929
-
930
- - **Whether a sealed-sender-wrapped prekey message decrypts end to end.** The
931
- unseal path reconstructs the envelope with a fixed message type
932
- (`client/sealed-sender-ops.ts:263-265`), and an adjacent comment suggests the
933
- Sesame layer re-derives the initiation state from the ciphertext. That path was
934
- not traced and the integration tests were not executed. If Sesame does not
935
- self-detect, first-contact sealed messages would be affected.
936
- - **Whether the session-identity-key check the sealed-sender note requires is
937
- enforced downstream.** The decrypt path compares the certificate's identity key
938
- against the decrypted static key but does not consult the session store. In
939
- `libsignal` the equivalent guarantee arrives later via the identity store.
940
- - **Whether `@noble/post-quantum`'s ML-KEM-1024 is byte-identical to libcrux's.**
941
- The repository claims pinned known-answer-test coverage; those tests were not
942
- executed as part of this review.
943
- - **Lizard encoding correctness against `libsignal`'s vectors.** The forward and
944
- inverse Elligator maps are hand-implemented in TypeScript. Structure and labels
945
- are correct and unit tests exist, but the outputs were not diffed against
946
- `libsignal`'s. A subtle error here would silently corrupt every `UidStruct`.
947
- - **SPQR state-machine transition equivalence.** State names, message types, and
948
- chunk counts match `libsignal`'s; the eleven-state transition table was not diffed
949
- transition by transition.
950
- - **Whether the SPQR decoder enforces a bound on stored points.** `libsignal` caps
951
- stored points per polynomial; no equivalent bound was located in the SDK's
1002
+ This review lists the following items rather than asserts them. It could not
1003
+ confirm any of them in source.
1004
+
1005
+ - **Does a sealed-sender-wrapped prekey message decrypt end to end?** The unseal
1006
+ path rebuilds the envelope with a fixed message type
1007
+ (`client/sealed-sender-ops.ts:263-265`). An adjacent comment suggests that the
1008
+ Sesame layer re-derives the initiation state from the ciphertext. This review
1009
+ traced neither that path nor the integration tests. First-contact sealed
1010
+ messages break if Sesame does not detect the state itself.
1011
+ - **Does anything downstream enforce the session-identity-key check?** The
1012
+ sealed-sender note requires it. The decrypt path compares the certificate's
1013
+ identity key against the decrypted static key. It does not consult the session
1014
+ store. In `libsignal`, the identity store carries the equivalent guarantee
1015
+ later.
1016
+ - **Is `@noble/post-quantum`'s ML-KEM-1024 byte-identical to libcrux's?** The
1017
+ repository claims pinned known-answer-test coverage. This review did not run
1018
+ those tests.
1019
+ - **Does the Lizard encoding match `libsignal`'s vectors?** The forward and
1020
+ inverse Elligator maps are hand-implemented in TypeScript. The structure and
1021
+ the labels are correct, and unit tests exist. This review did not diff the
1022
+ outputs against `libsignal`'s. A subtle error here silently corrupts every
1023
+ `UidStruct`.
1024
+ - **Do the SPQR state-machine transitions match?** State names, message types,
1025
+ and chunk counts match `libsignal`'s. This review did not diff the eleven-state
1026
+ transition table transition by transition.
1027
+ - **Does the SPQR decoder bound the stored points?** `libsignal` caps stored
1028
+ points per polynomial. This review found no equivalent bound in the SDK's
952
1029
  decoder.
953
- - **Whether SPQR state mutations are rolled back when message authentication
954
- fails.** `libsignal` commits the new state only after the MAC and decryption
955
- succeed; the SDK's receive path mutates state during decode, and the caller's
956
- rollback behaviour was not traced.
957
- - **Whether an equivalent of `libsignal`'s `promote_matching_session` exists.**
958
- `libsignal` matches archived sessions on `(version, base key)`; the SDK's map is
959
- keyed on base key alone.
1030
+ - **Does SPQR state roll back on an authentication failure**? By contrast,
1031
+ `libsignal` commits the new state only after the MAC and the decryption
1032
+ succeed. The SDK's receive
1033
+ path mutates state during decode, and this review did not trace the caller's
1034
+ rollback behaviour.
1035
+ - **Does an equivalent of `libsignal`'s `promote_matching_session` exist?**
1036
+ `libsignal` matches archived sessions on `(version, base key)`. The SDK keys
1037
+ its map on the base key alone.
960
1038
 
961
1039
  ---
962
1040
 
963
1041
  ## Reporting an error in this document
964
1042
 
965
- If something here is wrong — a citation that does not say what it is claimed to
966
- say, a deviation that has since been fixed, or a deviation that is missing —
967
- email security@open-e2ee.dev or open an issue. A deviations document that has
968
- drifted from the code is worse than none, because it invites exactly the
969
- assumption it exists to prevent.
1043
+ Email security@open-e2ee.dev or open an issue when something here is wrong. Three
1044
+ cases qualify:
1045
+
1046
+ - a citation that does not say what this document claims it says
1047
+ - a deviation that the code already fixed
1048
+ - a deviation that this document omits
1049
+
1050
+ A deviations document that drifts from the code is worse than no document at
1051
+ all, because it invites exactly the assumption it exists to prevent.
970
1052
 
971
1053
  [ik]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/identity_key.rs
972
1054
  [fp]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/fingerprint.rs