@open-e2ee/signal-protocol-sdk 11.0.0 → 12.0.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 (583) hide show
  1. package/ADAPTERS.md +4 -4
  2. package/ARCHITECTURE.md +6 -8
  3. package/CHANGELOG.md +1315 -0
  4. package/README.md +1 -1
  5. package/SECURITY.md +2 -2
  6. package/TROUBLESHOOTING.md +1 -1
  7. package/client/README.md +70 -37
  8. package/device/README.md +39 -85
  9. package/dist/client/client.d.ts +334 -63
  10. package/dist/client/client.d.ts.map +1 -1
  11. package/dist/client/client.js +1168 -184
  12. package/dist/client/client.js.map +1 -1
  13. package/dist/client/config.d.ts +40 -32
  14. package/dist/client/config.d.ts.map +1 -1
  15. package/dist/client/config.js +1 -1
  16. package/dist/client/config.js.map +1 -1
  17. package/dist/client/constants.d.ts +42 -8
  18. package/dist/client/constants.d.ts.map +1 -1
  19. package/dist/client/constants.js +48 -3
  20. package/dist/client/constants.js.map +1 -1
  21. package/dist/client/content-adapter.d.ts +80 -0
  22. package/dist/client/content-adapter.d.ts.map +1 -1
  23. package/dist/client/content-adapter.js +225 -12
  24. package/dist/client/content-adapter.js.map +1 -1
  25. package/dist/client/delivery-error.d.ts +150 -0
  26. package/dist/client/delivery-error.d.ts.map +1 -0
  27. package/dist/client/delivery-error.js +226 -0
  28. package/dist/client/delivery-error.js.map +1 -0
  29. package/dist/client/delivery-status.d.ts +32 -6
  30. package/dist/client/delivery-status.d.ts.map +1 -1
  31. package/dist/client/delivery-status.js +61 -13
  32. package/dist/client/delivery-status.js.map +1 -1
  33. package/dist/client/device-set-reconciliation.d.ts +196 -0
  34. package/dist/client/device-set-reconciliation.d.ts.map +1 -0
  35. package/dist/client/device-set-reconciliation.js +282 -0
  36. package/dist/client/device-set-reconciliation.js.map +1 -0
  37. package/dist/client/distribution-records.d.ts +29 -0
  38. package/dist/client/distribution-records.d.ts.map +1 -0
  39. package/dist/client/distribution-records.js +33 -0
  40. package/dist/client/distribution-records.js.map +1 -0
  41. package/dist/client/event-hooks.d.ts +280 -14
  42. package/dist/client/event-hooks.d.ts.map +1 -1
  43. package/dist/client/event-hooks.js +8 -0
  44. package/dist/client/event-hooks.js.map +1 -1
  45. package/dist/client/group-device-set.d.ts +47 -0
  46. package/dist/client/group-device-set.d.ts.map +1 -0
  47. package/dist/client/group-device-set.js +65 -0
  48. package/dist/client/group-device-set.js.map +1 -0
  49. package/dist/client/group-fetcher.d.ts +116 -0
  50. package/dist/client/group-fetcher.d.ts.map +1 -0
  51. package/dist/client/group-fetcher.js +598 -0
  52. package/dist/client/group-fetcher.js.map +1 -0
  53. package/dist/client/group-outbox.d.ts +172 -10
  54. package/dist/client/group-outbox.d.ts.map +1 -1
  55. package/dist/client/group-outbox.js +915 -74
  56. package/dist/client/group-outbox.js.map +1 -1
  57. package/dist/client/group-receive-authorization.d.ts +127 -4
  58. package/dist/client/group-receive-authorization.d.ts.map +1 -1
  59. package/dist/client/group-receive-authorization.js +270 -20
  60. package/dist/client/group-receive-authorization.js.map +1 -1
  61. package/dist/client/group-sealed-sender.d.ts +3 -0
  62. package/dist/client/group-sealed-sender.d.ts.map +1 -1
  63. package/dist/client/group-sealed-sender.js +1 -0
  64. package/dist/client/group-sealed-sender.js.map +1 -1
  65. package/dist/client/group-sender-key-operations.d.ts +14 -3
  66. package/dist/client/group-sender-key-operations.d.ts.map +1 -1
  67. package/dist/client/group-sender-key-operations.js +26 -5
  68. package/dist/client/group-sender-key-operations.js.map +1 -1
  69. package/dist/client/groups.d.ts +5 -5
  70. package/dist/client/groups.d.ts.map +1 -1
  71. package/dist/client/groups.js +5 -4
  72. package/dist/client/groups.js.map +1 -1
  73. package/dist/client/hosted-anonymous-delivery.d.ts +61 -9
  74. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
  75. package/dist/client/hosted-anonymous-delivery.js +242 -48
  76. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  77. package/dist/client/hosted-assertion-id.d.ts +7 -0
  78. package/dist/client/hosted-assertion-id.d.ts.map +1 -0
  79. package/dist/client/hosted-assertion-id.js +51 -0
  80. package/dist/client/hosted-assertion-id.js.map +1 -0
  81. package/dist/client/hosted-mailbox-subscription.d.ts +34 -2
  82. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  83. package/dist/client/hosted-mailbox-subscription.js +87 -17
  84. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  85. package/dist/client/hosted-push.d.ts +22 -4
  86. package/dist/client/hosted-push.d.ts.map +1 -1
  87. package/dist/client/hosted-push.js +75 -22
  88. package/dist/client/hosted-push.js.map +1 -1
  89. package/dist/client/hosted-transport.d.ts +22 -28
  90. package/dist/client/hosted-transport.d.ts.map +1 -1
  91. package/dist/client/hosted-transport.js +115 -55
  92. package/dist/client/hosted-transport.js.map +1 -1
  93. package/dist/client/hosted.d.ts +10 -4
  94. package/dist/client/hosted.d.ts.map +1 -1
  95. package/dist/client/hosted.js +10 -4
  96. package/dist/client/hosted.js.map +1 -1
  97. package/dist/client/index.d.ts +5 -3
  98. package/dist/client/index.d.ts.map +1 -1
  99. package/dist/client/index.js +2 -0
  100. package/dist/client/index.js.map +1 -1
  101. package/dist/client/messages.d.ts +25 -3
  102. package/dist/client/messages.d.ts.map +1 -1
  103. package/dist/client/messages.js +111 -20
  104. package/dist/client/messages.js.map +1 -1
  105. package/dist/client/receive-admission.d.ts +58 -0
  106. package/dist/client/receive-admission.d.ts.map +1 -0
  107. package/dist/client/receive-admission.js +78 -0
  108. package/dist/client/receive-admission.js.map +1 -0
  109. package/dist/client/receive-expiry.d.ts +31 -0
  110. package/dist/client/receive-expiry.d.ts.map +1 -0
  111. package/dist/client/receive-expiry.js +35 -0
  112. package/dist/client/receive-expiry.js.map +1 -0
  113. package/dist/client/receive-hook-bound.d.ts +50 -0
  114. package/dist/client/receive-hook-bound.d.ts.map +1 -0
  115. package/dist/client/receive-hook-bound.js +115 -0
  116. package/dist/client/receive-hook-bound.js.map +1 -0
  117. package/dist/client/receive-queue.d.ts +299 -0
  118. package/dist/client/receive-queue.d.ts.map +1 -0
  119. package/dist/client/receive-queue.js +1420 -0
  120. package/dist/client/receive-queue.js.map +1 -0
  121. package/dist/client/receive-work-seed.d.ts +54 -0
  122. package/dist/client/receive-work-seed.d.ts.map +1 -0
  123. package/dist/client/receive-work-seed.js +116 -0
  124. package/dist/client/receive-work-seed.js.map +1 -0
  125. package/dist/client/recovery-driver.d.ts +25 -0
  126. package/dist/client/recovery-driver.d.ts.map +1 -0
  127. package/dist/client/recovery-driver.js +121 -0
  128. package/dist/client/recovery-driver.js.map +1 -0
  129. package/dist/client/relay-acceptance.d.ts +20 -7
  130. package/dist/client/relay-acceptance.d.ts.map +1 -1
  131. package/dist/client/relay-acceptance.js +30 -12
  132. package/dist/client/relay-acceptance.js.map +1 -1
  133. package/dist/client/relay-device-refusal.d.ts +18 -0
  134. package/dist/client/relay-device-refusal.d.ts.map +1 -1
  135. package/dist/client/relay-device-refusal.js +31 -0
  136. package/dist/client/relay-device-refusal.js.map +1 -1
  137. package/dist/client/relay-sealed-route.d.ts +36 -0
  138. package/dist/client/relay-sealed-route.d.ts.map +1 -0
  139. package/dist/client/relay-sealed-route.js +45 -0
  140. package/dist/client/relay-sealed-route.js.map +1 -0
  141. package/dist/client/relay-subscription.d.ts +56 -13
  142. package/dist/client/relay-subscription.d.ts.map +1 -1
  143. package/dist/client/relay-subscription.js +193 -123
  144. package/dist/client/relay-subscription.js.map +1 -1
  145. package/dist/client/resendable-content.d.ts +98 -0
  146. package/dist/client/resendable-content.d.ts.map +1 -0
  147. package/dist/client/resendable-content.js +136 -0
  148. package/dist/client/resendable-content.js.map +1 -0
  149. package/dist/client/retry-family.d.ts +57 -10
  150. package/dist/client/retry-family.d.ts.map +1 -1
  151. package/dist/client/retry-family.js +54 -12
  152. package/dist/client/retry-family.js.map +1 -1
  153. package/dist/client/retry-request-envelope.d.ts +107 -8
  154. package/dist/client/retry-request-envelope.d.ts.map +1 -1
  155. package/dist/client/retry-request-envelope.js +172 -23
  156. package/dist/client/retry-request-envelope.js.map +1 -1
  157. package/dist/client/retry-request-lifecycle.d.ts +70 -14
  158. package/dist/client/retry-request-lifecycle.d.ts.map +1 -1
  159. package/dist/client/retry-request-lifecycle.js +162 -32
  160. package/dist/client/retry-request-lifecycle.js.map +1 -1
  161. package/dist/client/retry-terminal-recovery.d.ts +100 -0
  162. package/dist/client/retry-terminal-recovery.d.ts.map +1 -0
  163. package/dist/client/retry-terminal-recovery.js +164 -0
  164. package/dist/client/retry-terminal-recovery.js.map +1 -0
  165. package/dist/client/retry-utils.d.ts +27 -0
  166. package/dist/client/retry-utils.d.ts.map +1 -1
  167. package/dist/client/retry-utils.js +46 -0
  168. package/dist/client/retry-utils.js.map +1 -1
  169. package/dist/client/retry.d.ts +100 -12
  170. package/dist/client/retry.d.ts.map +1 -1
  171. package/dist/client/retry.js +619 -116
  172. package/dist/client/retry.js.map +1 -1
  173. package/dist/client/sealed-sender.d.ts +23 -6
  174. package/dist/client/sealed-sender.d.ts.map +1 -1
  175. package/dist/client/sealed-sender.js +30 -6
  176. package/dist/client/sealed-sender.js.map +1 -1
  177. package/dist/client/sessions.d.ts +2 -2
  178. package/dist/client/sessions.js +2 -2
  179. package/dist/client/signal-service-cipher.d.ts +726 -19
  180. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  181. package/dist/client/signal-service-cipher.js +2260 -342
  182. package/dist/client/signal-service-cipher.js.map +1 -1
  183. package/dist/client/state.d.ts +5 -0
  184. package/dist/client/state.d.ts.map +1 -1
  185. package/dist/client/state.js +11 -1
  186. package/dist/client/state.js.map +1 -1
  187. package/dist/client/storage-protection.d.ts +64 -0
  188. package/dist/client/storage-protection.d.ts.map +1 -0
  189. package/dist/client/storage-protection.js +150 -0
  190. package/dist/client/storage-protection.js.map +1 -0
  191. package/dist/client/types.d.ts +149 -15
  192. package/dist/client/types.d.ts.map +1 -1
  193. package/dist/client/types.js +1 -1
  194. package/dist/client/types.js.map +1 -1
  195. package/dist/device/constants.d.ts +0 -5
  196. package/dist/device/constants.d.ts.map +1 -1
  197. package/dist/device/constants.js +0 -5
  198. package/dist/device/constants.js.map +1 -1
  199. package/dist/device/expo/index.d.ts +4 -17
  200. package/dist/device/expo/index.d.ts.map +1 -1
  201. package/dist/device/expo/index.js +4 -23
  202. package/dist/device/expo/index.js.map +1 -1
  203. package/dist/device/index.d.ts +0 -2
  204. package/dist/device/index.d.ts.map +1 -1
  205. package/dist/device/index.js +0 -7
  206. package/dist/device/index.js.map +1 -1
  207. package/dist/device/lifecycle/manager.d.ts +5 -4
  208. package/dist/device/lifecycle/manager.d.ts.map +1 -1
  209. package/dist/device/lifecycle/manager.js +16 -16
  210. package/dist/device/lifecycle/manager.js.map +1 -1
  211. package/dist/device/lifecycle/types.d.ts +2 -2
  212. package/dist/device/lifecycle/types.d.ts.map +1 -1
  213. package/dist/device/react-native/index.d.ts +4 -15
  214. package/dist/device/react-native/index.d.ts.map +1 -1
  215. package/dist/device/react-native/index.js +4 -21
  216. package/dist/device/react-native/index.js.map +1 -1
  217. package/dist/device/types.d.ts +1 -1
  218. package/dist/groups/index.d.ts +1 -1
  219. package/dist/groups/index.d.ts.map +1 -1
  220. package/dist/index.d.ts +8 -6
  221. package/dist/index.d.ts.map +1 -1
  222. package/dist/index.js +2 -1
  223. package/dist/index.js.map +1 -1
  224. package/dist/internal/crypto/ec/x25519-validation.d.ts +0 -1
  225. package/dist/internal/crypto/ec/x25519-validation.d.ts.map +1 -1
  226. package/dist/internal/crypto/ec/x25519-validation.js +0 -1
  227. package/dist/internal/crypto/ec/x25519-validation.js.map +1 -1
  228. package/dist/internal/crypto/validation.d.ts +2 -2
  229. package/dist/internal/groups/index.d.ts +1 -0
  230. package/dist/internal/groups/index.d.ts.map +1 -1
  231. package/dist/internal/groups/index.js +1 -0
  232. package/dist/internal/groups/index.js.map +1 -1
  233. package/dist/internal/groups/manager.d.ts +37 -16
  234. package/dist/internal/groups/manager.d.ts.map +1 -1
  235. package/dist/internal/groups/manager.js +46 -1
  236. package/dist/internal/groups/manager.js.map +1 -1
  237. package/dist/internal/groups/receive-record.d.ts +78 -0
  238. package/dist/internal/groups/receive-record.d.ts.map +1 -0
  239. package/dist/internal/groups/receive-record.js +43 -0
  240. package/dist/internal/groups/receive-record.js.map +1 -0
  241. package/dist/internal/groups/sdk-store.d.ts +27 -3
  242. package/dist/internal/groups/sdk-store.d.ts.map +1 -1
  243. package/dist/internal/groups/sdk-store.js +151 -19
  244. package/dist/internal/groups/sdk-store.js.map +1 -1
  245. package/dist/internal/groups/wire.d.ts +12 -1
  246. package/dist/internal/groups/wire.d.ts.map +1 -1
  247. package/dist/internal/groups/wire.js +36 -0
  248. package/dist/internal/groups/wire.js.map +1 -1
  249. package/dist/internal/manager/index.d.ts +1 -1
  250. package/dist/internal/manager/manager.d.ts +20 -19
  251. package/dist/internal/manager/manager.d.ts.map +1 -1
  252. package/dist/internal/manager/manager.js +56 -39
  253. package/dist/internal/manager/manager.js.map +1 -1
  254. package/dist/internal/protocol/double-ratchet/chains.d.ts +4 -18
  255. package/dist/internal/protocol/double-ratchet/chains.d.ts.map +1 -1
  256. package/dist/internal/protocol/double-ratchet/chains.js +23 -74
  257. package/dist/internal/protocol/double-ratchet/chains.js.map +1 -1
  258. package/dist/internal/protocol/double-ratchet/index.d.ts +1 -1
  259. package/dist/internal/protocol/double-ratchet/index.d.ts.map +1 -1
  260. package/dist/internal/protocol/double-ratchet/index.js +1 -1
  261. package/dist/internal/protocol/double-ratchet/index.js.map +1 -1
  262. package/dist/internal/protocol/double-ratchet/ratchet.d.ts +5 -7
  263. package/dist/internal/protocol/double-ratchet/ratchet.d.ts.map +1 -1
  264. package/dist/internal/protocol/double-ratchet/ratchet.js +4 -6
  265. package/dist/internal/protocol/double-ratchet/ratchet.js.map +1 -1
  266. package/dist/internal/protocol/pqxdh/pqxdh.d.ts.map +1 -1
  267. package/dist/internal/protocol/pqxdh/pqxdh.js +2 -1
  268. package/dist/internal/protocol/pqxdh/pqxdh.js.map +1 -1
  269. package/dist/internal/protocol/sealed-sender/types.d.ts +6 -8
  270. package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
  271. package/dist/internal/protocol/sealed-sender/types.js +8 -9
  272. package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
  273. package/dist/internal/protocol/sender-keys/handoff-ledger.d.ts +110 -0
  274. package/dist/internal/protocol/sender-keys/handoff-ledger.d.ts.map +1 -0
  275. package/dist/internal/protocol/sender-keys/handoff-ledger.js +124 -0
  276. package/dist/internal/protocol/sender-keys/handoff-ledger.js.map +1 -0
  277. package/dist/internal/protocol/sender-keys/manager.d.ts +71 -62
  278. package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
  279. package/dist/internal/protocol/sender-keys/manager.js +228 -175
  280. package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
  281. package/dist/internal/protocol/spqr/index.d.ts +2 -2
  282. package/dist/internal/protocol/spqr/index.d.ts.map +1 -1
  283. package/dist/internal/protocol/spqr/index.js +2 -2
  284. package/dist/internal/protocol/spqr/index.js.map +1 -1
  285. package/dist/internal/protocol/spqr/serialize.d.ts +9 -1
  286. package/dist/internal/protocol/spqr/serialize.d.ts.map +1 -1
  287. package/dist/internal/protocol/spqr/serialize.js +56 -16
  288. package/dist/internal/protocol/spqr/serialize.js.map +1 -1
  289. package/dist/internal/protocol/spqr/spqr.d.ts +1 -14
  290. package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
  291. package/dist/internal/protocol/spqr/spqr.js +54 -42
  292. package/dist/internal/protocol/spqr/spqr.js.map +1 -1
  293. package/dist/internal/protocol/spqr/validate.d.ts +26 -6
  294. package/dist/internal/protocol/spqr/validate.d.ts.map +1 -1
  295. package/dist/internal/protocol/spqr/validate.js +49 -21
  296. package/dist/internal/protocol/spqr/validate.js.map +1 -1
  297. package/dist/internal/sesame/index.d.ts +1 -1
  298. package/dist/internal/sesame/index.d.ts.map +1 -1
  299. package/dist/internal/sesame/index.js.map +1 -1
  300. package/dist/internal/sesame/manager.d.ts +66 -13
  301. package/dist/internal/sesame/manager.d.ts.map +1 -1
  302. package/dist/internal/sesame/manager.js +221 -87
  303. package/dist/internal/sesame/manager.js.map +1 -1
  304. package/dist/internal/sesame/types.d.ts +95 -17
  305. package/dist/internal/sesame/types.d.ts.map +1 -1
  306. package/dist/internal/sesame/types.js +17 -0
  307. package/dist/internal/sesame/types.js.map +1 -1
  308. package/dist/internal/session/builder.d.ts +5 -5
  309. package/dist/internal/session/builder.d.ts.map +1 -1
  310. package/dist/internal/session/builder.js +12 -17
  311. package/dist/internal/session/builder.js.map +1 -1
  312. package/dist/internal/session/cipher.d.ts +13 -11
  313. package/dist/internal/session/cipher.d.ts.map +1 -1
  314. package/dist/internal/session/cipher.js +40 -22
  315. package/dist/internal/session/cipher.js.map +1 -1
  316. package/dist/internal/session/factory.d.ts +5 -5
  317. package/dist/internal/session/factory.d.ts.map +1 -1
  318. package/dist/internal/session/factory.js +4 -4
  319. package/dist/internal/session/factory.js.map +1 -1
  320. package/dist/internal/session/handshake.d.ts +14 -16
  321. package/dist/internal/session/handshake.d.ts.map +1 -1
  322. package/dist/internal/session/handshake.js +18 -75
  323. package/dist/internal/session/handshake.js.map +1 -1
  324. package/dist/internal/session/index.d.ts +1 -1
  325. package/dist/internal/session/index.js +1 -1
  326. package/dist/internal/session/record-locks.d.ts +17 -6
  327. package/dist/internal/session/record-locks.d.ts.map +1 -1
  328. package/dist/internal/session/record-locks.js +43 -7
  329. package/dist/internal/session/record-locks.js.map +1 -1
  330. package/dist/internal/session/session-resolver.d.ts +1 -1
  331. package/dist/internal/session/session-resolver.js +1 -1
  332. package/dist/internal/session/state.d.ts +2 -2
  333. package/dist/internal/session/state.js +1 -1
  334. package/dist/internal/session/types.d.ts +4 -12
  335. package/dist/internal/session/types.d.ts.map +1 -1
  336. package/dist/internal/session/types.js +1 -1
  337. package/dist/keys/generation.d.ts +2 -2
  338. package/dist/keys/generation.js +2 -2
  339. package/dist/keys/types.d.ts +5 -5
  340. package/dist/keys/types.d.ts.map +1 -1
  341. package/dist/keys/types.js +1 -1
  342. package/dist/layers.d.ts +1 -1
  343. package/dist/layers.js +2 -2
  344. package/dist/layers.js.map +1 -1
  345. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  346. package/dist/local/store/expo/adapter.js +12 -8
  347. package/dist/local/store/expo/adapter.js.map +1 -1
  348. package/dist/local/store/key-value/adapter.d.ts +76 -10
  349. package/dist/local/store/key-value/adapter.d.ts.map +1 -1
  350. package/dist/local/store/key-value/adapter.js +367 -61
  351. package/dist/local/store/key-value/adapter.js.map +1 -1
  352. package/dist/local/store/key-value/backend-conformance.d.ts.map +1 -1
  353. package/dist/local/store/key-value/backend-conformance.js +74 -0
  354. package/dist/local/store/key-value/backend-conformance.js.map +1 -1
  355. package/dist/local/store/key-value/batch.d.ts +2 -0
  356. package/dist/local/store/key-value/batch.d.ts.map +1 -1
  357. package/dist/local/store/key-value/batch.js +26 -0
  358. package/dist/local/store/key-value/batch.js.map +1 -1
  359. package/dist/local/store/key-value/receive-work.d.ts +55 -0
  360. package/dist/local/store/key-value/receive-work.d.ts.map +1 -0
  361. package/dist/local/store/key-value/receive-work.js +162 -0
  362. package/dist/local/store/key-value/receive-work.js.map +1 -0
  363. package/dist/local/store/key-value/send-log.d.ts +61 -0
  364. package/dist/local/store/key-value/send-log.d.ts.map +1 -0
  365. package/dist/local/store/key-value/send-log.js +430 -0
  366. package/dist/local/store/key-value/send-log.js.map +1 -0
  367. package/dist/local/store/key-value/sender-key-handoff.d.ts +68 -0
  368. package/dist/local/store/key-value/sender-key-handoff.d.ts.map +1 -0
  369. package/dist/local/store/key-value/sender-key-handoff.js +189 -0
  370. package/dist/local/store/key-value/sender-key-handoff.js.map +1 -0
  371. package/dist/local/store/key-value/storage.d.ts +15 -0
  372. package/dist/local/store/key-value/storage.d.ts.map +1 -1
  373. package/dist/local/store/keyed-index.d.ts +23 -0
  374. package/dist/local/store/keyed-index.d.ts.map +1 -0
  375. package/dist/local/store/keyed-index.js +41 -0
  376. package/dist/local/store/keyed-index.js.map +1 -0
  377. package/dist/local/store/memory/adapter.d.ts +44 -12
  378. package/dist/local/store/memory/adapter.d.ts.map +1 -1
  379. package/dist/local/store/memory/adapter.js +197 -46
  380. package/dist/local/store/memory/adapter.js.map +1 -1
  381. package/dist/local/store/memory/send-log.d.ts +42 -0
  382. package/dist/local/store/memory/send-log.d.ts.map +1 -0
  383. package/dist/local/store/memory/send-log.js +190 -0
  384. package/dist/local/store/memory/send-log.js.map +1 -0
  385. package/dist/local/store/node/adapter.d.ts.map +1 -1
  386. package/dist/local/store/node/adapter.js +8 -6
  387. package/dist/local/store/node/adapter.js.map +1 -1
  388. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  389. package/dist/local/store/react-native/adapter.js +12 -8
  390. package/dist/local/store/react-native/adapter.js.map +1 -1
  391. package/dist/local/store/receive-work.d.ts +87 -0
  392. package/dist/local/store/receive-work.d.ts.map +1 -0
  393. package/dist/local/store/receive-work.js +204 -0
  394. package/dist/local/store/receive-work.js.map +1 -0
  395. package/dist/local/store/received-content.d.ts +3 -3
  396. package/dist/local/store/received-content.d.ts.map +1 -1
  397. package/dist/local/store/received-content.js +2 -11
  398. package/dist/local/store/received-content.js.map +1 -1
  399. package/dist/local/store/reliability.d.ts +317 -18
  400. package/dist/local/store/reliability.d.ts.map +1 -1
  401. package/dist/local/store/reliability.js +371 -46
  402. package/dist/local/store/reliability.js.map +1 -1
  403. package/dist/local/store/send-log-order.d.ts +15 -0
  404. package/dist/local/store/send-log-order.d.ts.map +1 -0
  405. package/dist/local/store/send-log-order.js +24 -0
  406. package/dist/local/store/send-log-order.js.map +1 -0
  407. package/dist/local/store/sender-key-handoff-index.d.ts +38 -0
  408. package/dist/local/store/sender-key-handoff-index.d.ts.map +1 -0
  409. package/dist/local/store/sender-key-handoff-index.js +101 -0
  410. package/dist/local/store/sender-key-handoff-index.js.map +1 -0
  411. package/dist/local/store/sender-key-handoff-table.d.ts +29 -0
  412. package/dist/local/store/sender-key-handoff-table.d.ts.map +1 -0
  413. package/dist/local/store/sender-key-handoff-table.js +97 -0
  414. package/dist/local/store/sender-key-handoff-table.js.map +1 -0
  415. package/dist/local/store/sqlite/encryption.d.ts +8 -1
  416. package/dist/local/store/sqlite/encryption.d.ts.map +1 -1
  417. package/dist/local/store/sqlite/encryption.js +9 -0
  418. package/dist/local/store/sqlite/encryption.js.map +1 -1
  419. package/dist/local/store/sqlite/key-storage/index.d.ts +25 -4
  420. package/dist/local/store/sqlite/key-storage/index.d.ts.map +1 -1
  421. package/dist/local/store/sqlite/key-storage/index.js +68 -7
  422. package/dist/local/store/sqlite/key-storage/index.js.map +1 -1
  423. package/dist/local/store/sqlite/key-storage/message-records.d.ts +16 -4
  424. package/dist/local/store/sqlite/key-storage/message-records.d.ts.map +1 -1
  425. package/dist/local/store/sqlite/key-storage/message-records.js +49 -6
  426. package/dist/local/store/sqlite/key-storage/message-records.js.map +1 -1
  427. package/dist/local/store/sqlite/key-storage/metadata.d.ts +8 -7
  428. package/dist/local/store/sqlite/key-storage/metadata.d.ts.map +1 -1
  429. package/dist/local/store/sqlite/key-storage/metadata.js +17 -15
  430. package/dist/local/store/sqlite/key-storage/metadata.js.map +1 -1
  431. package/dist/local/store/sqlite/key-storage/receive-work.d.ts +27 -0
  432. package/dist/local/store/sqlite/key-storage/receive-work.d.ts.map +1 -0
  433. package/dist/local/store/sqlite/key-storage/receive-work.js +98 -0
  434. package/dist/local/store/sqlite/key-storage/receive-work.js.map +1 -0
  435. package/dist/local/store/sqlite/key-storage/send-log.d.ts +27 -0
  436. package/dist/local/store/sqlite/key-storage/send-log.d.ts.map +1 -0
  437. package/dist/local/store/sqlite/key-storage/send-log.js +178 -0
  438. package/dist/local/store/sqlite/key-storage/send-log.js.map +1 -0
  439. package/dist/local/store/sqlite/key-storage/sender-key-handoff.d.ts +27 -0
  440. package/dist/local/store/sqlite/key-storage/sender-key-handoff.d.ts.map +1 -0
  441. package/dist/local/store/sqlite/key-storage/sender-key-handoff.js +75 -0
  442. package/dist/local/store/sqlite/key-storage/sender-key-handoff.js.map +1 -0
  443. package/dist/local/store/sqlite/key-storage/session-trust.d.ts +2 -2
  444. package/dist/local/store/sqlite/key-storage/session-trust.js +5 -5
  445. package/dist/local/store/sqlite/key-storage/session-trust.js.map +1 -1
  446. package/dist/local/store/sqlite/migrations.d.ts.map +1 -1
  447. package/dist/local/store/sqlite/migrations.js +101 -0
  448. package/dist/local/store/sqlite/migrations.js.map +1 -1
  449. package/dist/local/store/sqlite/models/index.d.ts +2 -1
  450. package/dist/local/store/sqlite/models/index.d.ts.map +1 -1
  451. package/dist/local/store/sqlite/models/index.js +5 -1
  452. package/dist/local/store/sqlite/models/index.js.map +1 -1
  453. package/dist/local/store/sqlite/models/message-record.d.ts +15 -0
  454. package/dist/local/store/sqlite/models/message-record.d.ts.map +1 -1
  455. package/dist/local/store/sqlite/models/message-record.js +24 -0
  456. package/dist/local/store/sqlite/models/message-record.js.map +1 -1
  457. package/dist/local/store/sqlite/models/send-log.d.ts +51 -0
  458. package/dist/local/store/sqlite/models/send-log.d.ts.map +1 -0
  459. package/dist/local/store/sqlite/models/send-log.js +206 -0
  460. package/dist/local/store/sqlite/models/send-log.js.map +1 -0
  461. package/dist/local/store/sqlite/open-store.d.ts +9 -1
  462. package/dist/local/store/sqlite/open-store.d.ts.map +1 -1
  463. package/dist/local/store/sqlite/open-store.js +20 -1
  464. package/dist/local/store/sqlite/open-store.js.map +1 -1
  465. package/dist/local/store/sqlite/schema.d.ts +34 -1
  466. package/dist/local/store/sqlite/schema.d.ts.map +1 -1
  467. package/dist/local/store/sqlite/schema.js +14 -0
  468. package/dist/local/store/sqlite/schema.js.map +1 -1
  469. package/dist/local/store/sqlite/store.d.ts +61 -11
  470. package/dist/local/store/sqlite/store.d.ts.map +1 -1
  471. package/dist/local/store/sqlite/store.js +191 -27
  472. package/dist/local/store/sqlite/store.js.map +1 -1
  473. package/dist/local/store/web/adapter.d.ts +76 -8
  474. package/dist/local/store/web/adapter.d.ts.map +1 -1
  475. package/dist/local/store/web/adapter.js +579 -127
  476. package/dist/local/store/web/adapter.js.map +1 -1
  477. package/dist/local/store/web/receive-work.d.ts +57 -0
  478. package/dist/local/store/web/receive-work.d.ts.map +1 -0
  479. package/dist/local/store/web/receive-work.js +99 -0
  480. package/dist/local/store/web/receive-work.js.map +1 -0
  481. package/dist/local/store/web/send-log.d.ts +92 -0
  482. package/dist/local/store/web/send-log.d.ts.map +1 -0
  483. package/dist/local/store/web/send-log.js +267 -0
  484. package/dist/local/store/web/send-log.js.map +1 -0
  485. package/dist/local/store/web/sender-key-handoff.d.ts +81 -0
  486. package/dist/local/store/web/sender-key-handoff.d.ts.map +1 -0
  487. package/dist/local/store/web/sender-key-handoff.js +156 -0
  488. package/dist/local/store/web/sender-key-handoff.js.map +1 -0
  489. package/dist/local/store/web-sqlite/adapter.d.ts +2 -0
  490. package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
  491. package/dist/local/store/web-sqlite/adapter.js +12 -6
  492. package/dist/local/store/web-sqlite/adapter.js.map +1 -1
  493. package/dist/local/vault/custody.d.ts +8 -0
  494. package/dist/local/vault/custody.d.ts.map +1 -0
  495. package/dist/local/vault/custody.js +9 -0
  496. package/dist/local/vault/custody.js.map +1 -0
  497. package/dist/local/vault/electron-safe-storage.d.ts +3 -1
  498. package/dist/local/vault/electron-safe-storage.d.ts.map +1 -1
  499. package/dist/local/vault/electron-safe-storage.js +2 -0
  500. package/dist/local/vault/electron-safe-storage.js.map +1 -1
  501. package/dist/local/vault/expo-secure-store.d.ts +3 -1
  502. package/dist/local/vault/expo-secure-store.d.ts.map +1 -1
  503. package/dist/local/vault/expo-secure-store.js +2 -0
  504. package/dist/local/vault/expo-secure-store.js.map +1 -1
  505. package/dist/local/vault/indexed-db.d.ts +3 -1
  506. package/dist/local/vault/indexed-db.d.ts.map +1 -1
  507. package/dist/local/vault/indexed-db.js +2 -0
  508. package/dist/local/vault/indexed-db.js.map +1 -1
  509. package/dist/local/vault/react-native-keychain.d.ts +3 -1
  510. package/dist/local/vault/react-native-keychain.d.ts.map +1 -1
  511. package/dist/local/vault/react-native-keychain.js +2 -0
  512. package/dist/local/vault/react-native-keychain.js.map +1 -1
  513. package/dist/remote/relay/device-set.d.ts +94 -0
  514. package/dist/remote/relay/device-set.d.ts.map +1 -0
  515. package/dist/remote/relay/device-set.js +156 -0
  516. package/dist/remote/relay/device-set.js.map +1 -0
  517. package/dist/remote/relay/types.d.ts +92 -107
  518. package/dist/remote/relay/types.d.ts.map +1 -1
  519. package/dist/safety/core.d.ts +15 -6
  520. package/dist/safety/core.d.ts.map +1 -1
  521. package/dist/safety/core.js +41 -27
  522. package/dist/safety/core.js.map +1 -1
  523. package/dist/safety/index.d.ts +2 -1
  524. package/dist/safety/index.d.ts.map +1 -1
  525. package/dist/safety/index.js +12 -18
  526. package/dist/safety/index.js.map +1 -1
  527. package/dist/types/api.d.ts +707 -62
  528. package/dist/types/api.d.ts.map +1 -1
  529. package/dist/types/errors.d.ts +14 -33
  530. package/dist/types/errors.d.ts.map +1 -1
  531. package/dist/types/errors.js +14 -24
  532. package/dist/types/errors.js.map +1 -1
  533. package/dist/types/messages.d.ts +2 -2
  534. package/dist/types/messages.js +1 -1
  535. package/dist/types/protocol-config.d.ts +175 -42
  536. package/dist/types/protocol-config.d.ts.map +1 -1
  537. package/dist/types/protocol-config.js +19 -38
  538. package/dist/types/protocol-config.js.map +1 -1
  539. package/dist/types/protocol-constants.d.ts +6 -6
  540. package/dist/types/protocol-constants.js +6 -6
  541. package/dist/types/session.d.ts +7 -7
  542. package/dist/types/session.d.ts.map +1 -1
  543. package/dist/types/session.js +39 -21
  544. package/dist/types/session.js.map +1 -1
  545. package/dist/username/link.d.ts +2 -2
  546. package/dist/username/link.js +2 -2
  547. package/dist/utils/origin-lock.d.ts +45 -0
  548. package/dist/utils/origin-lock.d.ts.map +1 -0
  549. package/dist/utils/origin-lock.js +80 -0
  550. package/dist/utils/origin-lock.js.map +1 -0
  551. package/docs/ASSURANCE.md +6 -6
  552. package/docs/CLIENT_COMPOSITION.md +2 -2
  553. package/docs/DEVIATIONS.md +677 -182
  554. package/docs/E2EE.md +1 -1
  555. package/docs/ERROR_HANDLING.md +165 -2
  556. package/docs/GETTING_STARTED.md +7 -4
  557. package/docs/INTERFACES.md +1 -1
  558. package/docs/PACKAGE_SURFACE.md +6 -5
  559. package/docs/PROTOCOL_POLICY.md +102 -22
  560. package/docs/RECIPES.md +3 -15
  561. package/docs/SECURITY.md +90 -5
  562. package/keys/README.md +3 -3
  563. package/local/store/README.md +78 -14
  564. package/local/store/key-value/README.md +14 -3
  565. package/local/store/node/README.md +8 -3
  566. package/local/store/web/README.md +9 -0
  567. package/local/store/web-sqlite/README.md +14 -2
  568. package/local/vault/README.md +21 -0
  569. package/package.json +1 -6
  570. package/remote/README.md +0 -1
  571. package/remote/relay/README.md +2 -2
  572. package/dist/device/provisioning.d.ts +0 -242
  573. package/dist/device/provisioning.d.ts.map +0 -1
  574. package/dist/device/provisioning.js +0 -421
  575. package/dist/device/provisioning.js.map +0 -1
  576. package/dist/internal/protocol/x3dh/index.d.ts +0 -15
  577. package/dist/internal/protocol/x3dh/index.d.ts.map +0 -1
  578. package/dist/internal/protocol/x3dh/index.js +0 -13
  579. package/dist/internal/protocol/x3dh/index.js.map +0 -1
  580. package/dist/internal/protocol/x3dh/x3dh.d.ts +0 -131
  581. package/dist/internal/protocol/x3dh/x3dh.d.ts.map +0 -1
  582. package/dist/internal/protocol/x3dh/x3dh.js +0 -261
  583. package/dist/internal/protocol/x3dh/x3dh.js.map +0 -1
@@ -73,20 +73,29 @@ model and what is out of scope.
73
73
  |---|---|---|---|---|
74
74
  | **Identity keys** | X3DH §2.2; `libsignal` `identity_key.rs` | **Deviation.** A 67-byte composite of separate X25519 and Ed25519 keys replaces the single 33-byte Curve25519 identity key | Avoids XEdDSA, a non-standard signature scheme with no vetted JavaScript implementation; standard Ed25519 is independently verifiable | Two keys to store and rotate; larger identity; **no wire compatibility for any identity-bearing material** |
75
75
  | **Prekey signatures** | X3DH §2.2, §4.5 | **Deviation.** RFC 8032 Ed25519 over a domain-separated context binding the identity commitment, algorithm tag, and key ID — not XEdDSA over the bare key | Defeats cross-algorithm and cross-key-ID substitution that a bare-key signature does not cover | Strictly stronger binding; signatures are unverifiable by Signal Messenger clients and vice versa |
76
- | **Safety numbers** | `libsignal` `fingerprint.rs` | **Deviation.** Iteration and digit encoding are byte-identical, but the input is a composite-identity commitment under an SDK domain string, the QR version is `3`, and the two halves are ordered by user ID rather than by digit string | Follows from the composite identity; a single-key fingerprint cannot authenticate both components | **Safety numbers are not comparable to Signal Messenger's.** The ordering rule also differs from `libsignal` even on the single-key path |
77
- | **X3DH / PQXDH** | X3DH rev. 1; PQXDH rev. 3 | **Faithful** on DH order, the `0xFF`×32 prefix, zero-salt HKDF, KEM-secret position, and PQXDH §2.2's info-string construction. **Deviation:** ML-KEM-1024 (FIPS 203) replaces round-3 Kyber1024 | Standardized ML-KEM preferred over round-3 Kyber. The info string names it, and names this application rather than `libsignal`'s, as §2.1 and §2.2 require | Wire-incompatible with `libsignal` by construction, and the label now says so. The info string is part of the derivation, so any peer that names a different one derives a different `SK` and cannot complete the handshake |
76
+ | **Safety numbers** | `libsignal` `fingerprint.rs` | **Deviation.** Iteration, digit encoding, and the order of the two halves are byte-identical, but the input is a composite-identity commitment under an SDK domain string, and the QR version is `4` | Follows from the composite identity; a single-key fingerprint cannot authenticate both components | **Safety numbers are not comparable to Signal Messenger's.** The low-level single-key path equals `libsignal`'s version 2 fingerprint |
77
+ | **PQXDH** | PQXDH rev. 3; X3DH rev. 1 for the shared DH steps | **Faithful** on DH order, the `0xFF`×32 prefix, zero-salt HKDF, KEM-secret position, and PQXDH §2.2's info-string construction. **Deviation:** ML-KEM-1024 (FIPS 203) replaces round-3 Kyber1024 | Standardized ML-KEM preferred over round-3 Kyber. The info string names it, and names this application rather than `libsignal`'s, as §2.1 and §2.2 require. PQXDH is required: no classical X3DH session exists | Wire-incompatible with `libsignal` by construction, and the label now says so. The info string is part of the derivation, so any peer that names a different one derives a different `SK` and cannot complete the handshake |
78
78
  | **Associated data** | X3DH §3.3 | **Deviation.** `AD` is a domain-separated HMAC input over SHA-256 commitments to both composite identities, not `IK_A ‖ IK_B` | Binds the Ed25519 component, which a raw-key `AD` would leave uncovered | Stronger binding; wire-incompatible |
79
79
  | **Double Ratchet** | Double Ratchet rev. 4 | **Faithful** on `WhisperRatchet`, `WhisperMessageKeys`, the `0x01`/`0x02` seeds, the 80-byte split, AES-256-CBC, the `0x44` version byte, and 8-byte MAC truncation | — | The ratchet core follows the Double Ratchet specification |
80
80
  | **Message wire format** | `libsignal` `wire.proto` | **Faithful** field numbers 1–8. **Extension:** fields at 100+ carry identity type and ML-KEM one-time prekey material. **Deviation:** address binding uses variable-length UTF-8 user IDs and 4-byte device IDs instead of 17-byte ServiceIds and 1-byte device IDs | The SDK binds application-defined identifiers, not Signal Messenger ACIs | Wire-incompatible; a Signal Messenger client would silently ignore the added fields |
81
- | **Skipped keys and archiving** | Double Ratchet §2.6; `libsignal` `consts.rs` | **Deviation.** The 2000-key cap is global rather than per-chain, eviction is by wall-clock timestamp, and skipped keys expire after 7 days. Session records serialize as JSON, not protobuf | Simpler storage accounting and bounded growth | **Legitimate messages can become undecryptable** where `libsignal` would still decrypt them: a 5× smaller effective cap, cross-chain eviction, and a hard 7-day limit for offline recipients |
81
+ | **Skipped keys and archiving** | Double Ratchet §2.6, §8.4; `libsignal` `consts.rs` | **Deviation.** The 2000-key cap applies to each receiver chain, as in `libsignal`, and a full chain evicts its lowest index. Skipped keys also expire after 7 days, which `libsignal` does not do. Session records serialize as JSON, not protobuf | Double Ratchet §8.4 recommends the deletion of skipped keys after one week. A held key decrypts its message for as long as it stays, so the expiry bounds what a compromised device state exposes | The worst case is 5 receiver chains of 2000 keys each, in the current session and in each of up to 40 archived sessions. **A message more than 7 days out of order is undecryptable** where `libsignal` decrypts it |
82
82
  | **Padding** | — | **Extension.** ISO 7816-4 bit padding to 160-byte buckets inside the library | Length hiding by default rather than left to the application | `libsignal` does not pad at this layer; Signal Messenger's apps do. PKCS#7 then adds a block, so ciphertext lands 16 bytes past each boundary |
83
83
  | **SPQR / ML-KEM Braid** | ML-KEM Braid rev. 1 | **Deviation.** Same protocol, same KDF labels, same Reed–Solomon parameters, byte-identical message framing — except `hek = SHA3-256(ek_seed ‖ ek_vector)`, the operand order the specification states, which is the reverse of `libsignal`'s implementation | The normative text was followed over the executable reference | Wire-visible. Headers, ciphertexts, and shared secrets diverge; a braid session cannot complete a single epoch against `libsignal`'s implementation. Also means the KEM is not FIPS 203 in braid mode |
84
84
  | **Triple Ratchet** | `libsignal` `triple_ratchet.rs` | **Faithful.** The PQ secret enters as the HKDF salt at message-key expansion, same label, same order | — | The braiding construction follows the ML-KEM Braid specification |
85
- | **Sesame** | Sesame rev. 2 | **Deviation** on session expiry (§4.2 applies only to unacknowledged sessions), on deleted devices (hard-removed rather than marked stale), and on device-list currency (the sender reads the relay's list at most once per 60 s instead of the server rejecting a stale send). **Extensions:** QR provisioning, device transfer, encrypted device names, identity-change gating, a 5-device cap | Product requirements the specification does not address | Hard deletion **drops the MAXLATENCY window, so in-flight messages from a just-removed device become permanently undecryptable**. A device linked or removed less than 60 s ago can miss a send or still receive one. Device transfer clones ratchet state, which weakens the forward-secrecy bound |
85
+ | **Sesame** | Sesame rev. 2 | **Faithful** on deleted devices: a removed device is marked and kept for MAXLATENCY, and its archived sessions still decrypt. **Deviation** on session expiry (§4.2 applies only to unacknowledged sessions) and on device-list currency on the Convex relay only (the sender reads the relay's list at most once per 60 s). The Signal Protocol Relay and the memory relay reject a stale declared device set, as §3.3 requires. **Deviation** on stale-record cleanup timing (§5.1: the cleanup runs after the resume, not after a fetch of the whole mailbox, and the Relay's 30-day TTL cap bounds it). **Extensions:** device transfer, encrypted device names, identity-change gating, a 5-device cap | Product requirements the specification does not address | On the Convex relay, a device linked or removed less than 60 s ago can miss a send or still receive one. A client clock that moves forward against the Relay clock between a removal and the cleanup can lose a message accepted just before the removal. Device transfer copies the identity private key and no ratchet state, so each device starts its own sessions |
86
+ | **Device-set reconciliation** | Signal's server `MessageController`; Signal's Desktop client `sendToGroup` | **Deviation** in detail. The answer order, one post for each device of a direct send, a bound on direct sends, no empty sync post, a refusal for each not-found group destination, an acknowledgment marker, and a group body sealed again with the same ciphertext (§5.6) | The Relay takes one destination for each direct body, keeps one record for each account, admits an operation for 5 minutes, and stores each send attempt | A phase that does not match in 10 restarts fails the send with `DeviceSetReconciliationError`. A relay that does not acknowledge the comparison raises `DEVICE_SET_UNCHECKED` |
86
87
  | **Sealed sender** | `libsignal` `sealed_sender.rs` | **Faithful** on the multi-recipient transport labels, KEM, AES-256-GCM-SIV, binary format, and `0x3FFF` registration-ID mask. **Extension:** sender and server certificates require signed Relay scope and issuer validity under operator-owned Ed25519 roots | Binds anonymous delivery to one Relay deployment and supports explicit issuer rotation and revocation | The transport follows `libsignal`; certificates are not interchangeable with Signal Messenger or another deployment |
87
88
  | **Delivery token** | `libsignal` `profile_key.rs` | **Faithful.** `deriveAccessKey` follows `libsignal`'s `ProfileKey::derive_access_key`, and reproduces `libsignal`'s published known-answer values | — | Not an SDK invention, despite what the module name suggests |
88
89
  | **Sender keys** | `libsignal` `sender_keys.rs` | **Deviation.** Protobuf fields, chain seeds, and HKDF-Extract/Expand match. The SDK uses frame version `0x44`, Ed25519 signatures, and UTF-8 distribution identifiers. | The identity profile selects Ed25519. The frame version marks the correction of the former missing Extract. | Message-key derivation matches the reference. Former SDK state and messages require a reset. Frames still differ from Signal Messenger. |
90
+ | **Sender-key distribution tracking** | Signal's Android client `SenderKeySharedTable`; Signal's Desktop client `sendToGroup` | **Deviation** in detail. The same events delete rows. A session or key write deletes them in the same write. The row match adds the key ID and compares the registration ID, as Signal's Desktop client does. A replay keeps its group ciphertext | The Relay refuses a second operation under one message ID. The SQLite, IndexedDB, and key-value stores keep the rows in durable storage, and the memory store keeps them in memory by design | A device that a replay adds gets the content only for a `Resendable` send |
91
+ | **Cross-tab locks** | Signal's Desktop and Android clients | **Faithful** in a browser: a group send and each session write take a Web Lock named by the store identity, so the tabs and workers of one origin run them one at a time. **Deviation** elsewhere: the lock orders one store object in one process | Signal runs one process for each device. Only the browser stores have a store identity, and Web Locks in Node order one process only | Two processes, or two store objects, that share one database need exclusive access from the application (§7.6) |
92
+ | **Group send route** | Signal's server, multi-recipient send | **Faithful** in the SDK: each group send goes to the anonymous group route with a group send token. The Relay still serves an identified group route that no SDK release calls | The Relay removes the identified route forward only | Until the removal, a client that posts to the identified route sends under its account credential, with no device-set check when the post declares none (§7.7) |
89
93
  | **Groups** | Signal Private Group System | **Independent design.** Real zkgroup primitives underneath; profile-key credential issuance blinds the ACI-bound profile-key attribute, the server validates every change against zero-knowledge presentations and signs the accepted result, and clients verify those signatures | Ships a validating group server with an enforcement contract (S1–S14) specified in-tree | Not wire-compatible with the Signal Private Group System; credentials are not interchangeable. The issuer sees the authenticated ACI and redemption window, but not the raw profile key |
94
+ | **Receive order** | Signal's Android client | **Faithful.** The receive queue (`client/receive-queue.ts`) holds back the later records of one conversation, as Android queues its message jobs: group content per group, a sent transcript per destination, and other content per sender account. The commit order stays per sender device | — | A record that waits for its group state holds back the later content of its group from every sender until a fetch of its group or `syncGroup` completes, or until the record expires after 30 days. Direct chats and other groups make progress. A record in hook backoff holds back its conversation until its hook succeeds, it reaches the hook attempt cap of 10, or it expires. Before the queue restores a record, it keys the record by its stored group or by its sender account. A missing sender key does not hold the queue: that content goes to the retry request handler |
95
+ | **Receive hook attempt cap** | Signal's Desktop client | **Deviation.** After 10 failed `onMessageDecrypted` attempts, a record no longer holds back its conversation, as on Desktop. Desktop deletes the record at startup. The SDK keeps it, offers it to the hook once at each start, shows the count in `PendingReceive.hookAttempts`, and removes it at `discardPendingReceive` | The hook is application code. A drop loses content whose ratchet step is spent, and an application update can repair the hook | A hook that ends the process on the record ends it once at each start, until the record expires or the application discards it (§8.2) |
96
+ | **Receive hook bound** | Signal's Desktop client | **Deviation** in detail. Each application hook that a receive pass awaits has a bound, `receiveHookTimeoutMs`, 2 minutes by default. Desktop bounds its receive dispatch at 2 minutes and its long-running tasks at 30 minutes | A founder ruling sets the bound at 2 minutes. The SDK cannot tell a slow hook from a hung one | A timeout of `onMessageDecrypted` counts as one failed attempt. A timeout of another hook is logged, and the pass continues. A settle after the bound writes nothing (§8.4) |
97
+ | **Delivery receipt lifespan** | Signal's Android client | **Faithful.** A stored receipt is sent only within 1 day after it becomes owed, as Android's receipt job lives for 1 day. The receipt is durable across a restart, as on Android | — | A receipt that cannot go out within 1 day is not sent, and no hook reports it (§8.3) |
98
+ | **Receive admission bounds** | Signal's Desktop client | **Extension.** Before a decrypt, the receive queue checks `maxItems`, `maxBytes`, and the group share `blockedGroupShare`. The defaults are provisional. Desktop decrypts each envelope as it arrives and bounds stored content only by age and attempts | The SDK shares a storage budget with the application in a browser and on mobile | A refused envelope is not acknowledged. It stays at the Relay and expires there with no local hook. The messages behind it still arrive (§8.5) |
90
99
  | **zkgroup / zkcredential** | `libsignal` `zkgroup`, `zkcredential`, `poksho` | **Faithful** port of the Ristretto255 KVAC and Sigma-protocol system, verified against `libsignal`'s known-answer vectors. **Deviation:** server parameter derivation is structured as four labeled derivations rather than one seeded derivation | Server keys are the deploying operator's own trust root (each deployment generates its own seed), not Signal Messenger's | The zero-knowledge properties are real. Credentials are not interchangeable with Signal Messenger's |
91
100
  | **Registration IDs** | `libsignal` `sealed_sender.rs` | **Faithful.** Generated in `[1, 16383]`, strictly inside the 14 bits the wire format reserves | — | — |
92
101
 
@@ -193,47 +202,48 @@ the safety number Signal Messenger shows for the same two users. A user cannot
193
202
  verify a contact by reading a number out of one application and comparing it
194
203
  against the other.
195
204
 
196
- Three independent reasons, any one of which is sufficient.
205
+ Two independent reasons, either of which is sufficient.
197
206
 
198
207
  **The SDK computes the user-facing number over a composite commitment.**
199
208
  The `client.verify()` method uses `generateCompositeSafetyNumber`
200
- (`client/sessions.ts:326`, `:432-433`). Its per-party hash iterates over
209
+ (`client/sessions.ts:374`, `:436`). Its per-party hash iterates over
201
210
  `UTF8("signal-protocol-js composite safety number v1") ‖ type-tagged user ID ‖
202
- SHA-256 identity commitment` (`safety/core.ts:48-50`, `:205-233`). None of that
211
+ SHA-256 identity commitment` (`safety/core.ts:52-54`, `:249-262`). None of that
203
212
  input exists in `libsignal`'s construction ([`fingerprint.rs:161-192`][fp]).
204
213
 
205
214
  **The identity material differs.** Even the raw input is a 67-byte two-key tuple
206
215
  rather than a 33-byte `0x05 ‖ X25519` key.
207
216
 
208
- **A different rule orders the two halves.** This one applies even on the
209
- SDK's low-level single-key path, which is otherwise byte-identical to
210
- `libsignal`. The SDK orders by user identifier,
211
- `localId.localeCompare(remoteId)` (`safety/core.ts:177`). `libsignal` orders by
212
- the encoded digit strings themselves ([`fingerprint.rs:32-40`][fp]). Both rules
213
- are symmetric, so the two parties always agree with each other. They do not
214
- agree with Signal Messenger, and roughly half the time the halves come out in
215
- the opposite order.
216
-
217
- `localeCompare` is also locale-sensitive. Two devices with different default
218
- locales can in principle disagree on how to order the same pair of user IDs.
217
+ **The order of the two halves is faithful.** The party whose 30-digit display
218
+ string is lower by unsigned byte comparison comes first
219
+ (`safety/core.ts:186-226`), as in `libsignal` ([`fingerprint.rs:32-40`][fp]).
220
+ The SDK does not compare user identifiers, so neither the locale nor the
221
+ UTF-16 code-unit order can change the result. When the two display strings
222
+ are equal, the 60 digits do not depend on the order, and the full hash bytes
223
+ choose the first fingerprint, so both parties still produce the same hex and
224
+ emoji. The SDK's low-level single-key path is therefore byte-identical to
225
+ `libsignal`'s version 2 fingerprint (`safety/core.ts:43`).
219
226
 
220
227
  Other parts *are* faithful. The iteration is byte-for-byte `libsignal`'s: 5200
221
228
  iterations of SHA-512 over `0x0000 ‖ key ‖ id`, then `hash ‖ key`
222
- (`safety/core.ts:138-143` vs [`fingerprint.rs:170-189`][fp]). So is the digit
229
+ (`safety/core.ts:146-152` vs [`fingerprint.rs:170-189`][fp]). So is the digit
223
230
  encoding (six 5-byte big-endian chunks mod 100000, 30 digits per party). So is
224
231
  the scannable-fingerprint protobuf layout (`safety/protobuf.ts:94-109`). The
225
232
  cross-verification swap and constant-time comparison match as well.
226
233
 
227
- The QR format version is the SDK's own: `3` for the composite path
228
- (`safety/core.ts:46`), where `libsignal` knows only versions 1 and 2 and returns
229
- `VersionMismatch` for anything else. A distinct version in the same protobuf
230
- namespace is the correct fail-closed choice. A Signal Messenger client rejects
231
- the code rather than misreading it.
234
+ The QR format version is the SDK's own: `4` for the composite path
235
+ (`safety/core.ts:45-50`), where `libsignal` knows only versions 1 and 2 and
236
+ returns `VersionMismatch` for anything else. A distinct version in the same
237
+ protobuf namespace is the correct fail-closed choice. A Signal Messenger client
238
+ rejects the code rather than misreading it. An earlier SDK ordered the two
239
+ halves by user ID under version `3`. A version `3` code reports
240
+ `version_mismatch` (`safety/fingerprint.ts:313-316`), so two parties never
241
+ compare numbers that two different order rules made.
232
242
 
233
- The SDK also offers an emoji fingerprint (`safety/core.ts:308-392`) and
243
+ The SDK also offers an emoji fingerprint (`safety/core.ts:321-435`) and
234
244
  verification deep links (`safety/url.ts`). Both are extensions with no
235
- `libsignal` counterpart. The emoji form derives from one party's fingerprint
236
- only. It therefore encodes roughly half of what the 60-digit number encodes.
245
+ `libsignal` counterpart. The emoji form derives from the fingerprint that comes
246
+ first only. It therefore encodes roughly half of what the 60-digit number encodes.
237
247
  Do not present it to users as an equal-strength alternative.
238
248
 
239
249
  ### 1.4 Registration ID range
@@ -288,11 +298,10 @@ tagged `0x0A` rather than `0x08` (`internal/crypto/pq/kyber.ts:79`). That much i
288
298
  deliberate. The SDK prefers the standardized algorithm over the round-3 draft,
289
299
  and a single unambiguous tag over a legacy fallback.
290
300
 
291
- The info strings are the SDK's own (`types/protocol-config.ts:363-386`):
301
+ The info string is the SDK's own (`types/protocol-config.ts:624-638`):
292
302
 
293
303
  ```text
294
- OpenE2EE_X25519_SHA-256_ML-KEM-1024 (PQXDH)
295
- OpenE2EE (X3DH)
304
+ OpenE2EE_X25519_SHA-256_ML-KEM-1024
296
305
  ```
297
306
 
298
307
  The SDK sets both implementer-chosen parameters to name itself and the KEM it
@@ -364,28 +373,30 @@ conditions (`internal/session/cipher.ts:1519-1527`).
364
373
  Two differences at the boundary between key agreement and the ratchet:
365
374
 
366
375
  **Alice reuses her key-agreement ephemeral as her first ratchet key**
367
- (`internal/session/builder.ts:159-171`). By contrast, `libsignal` generates a
376
+ (`internal/session/builder.ts:158-170`). By contrast, `libsignal` generates a
368
377
  fresh sending ratchet key, distinct from the handshake ephemeral
369
378
  ([`ratchet.rs:77-81`][rat]). In `libsignal` the prekey message's base key and the
370
379
  first message's ratchet key therefore differ. Here they are the same value. No
371
380
  concrete attack follows, but the reuse weakens key separation and it is
372
381
  wire-visible.
373
382
 
374
- **Bob initializes without a sending chain** (`internal/session/builder.ts:326-364`),
383
+ **Bob initializes without a sending chain** (`internal/session/builder.ts:318-356`),
375
384
  deriving chains on the first DH ratchet, where `libsignal` seeds a sending chain
376
385
  immediately ([`ratchet.rs:137-172`][rat]). A side effect is that bytes 32–64 of
377
386
  the 96-byte derivation, the initial chain key, never produce a message key on
378
387
  either side. The SDK keeps the 96-byte split for shape compatibility, but only
379
388
  the root key and the SPQR key are load-bearing.
380
389
 
381
- ### 2.5 The SDK keeps a gated classical fallback
390
+ ### 2.5 PQXDH is required
382
391
 
383
- `libsignal` removed X3DH entirely and rejects pre-Kyber prekey messages
384
- ([`session.rs:105-112`][sess]). The SDK keeps the X3DH path reachable only via an
385
- explicit opt-in. The default is fail-closed, and any PQXDH failure raises rather
386
- than silently downgrading (`internal/session/handshake.ts:167-260`). This is a
387
- downgrade surface that `libsignal` closed.
388
- [Protocol Policy](./PROTOCOL_POLICY.md) documents it.
392
+ Every new session uses PQXDH. The SDK has no classical X3DH key agreement and
393
+ no setting that enables one. A peer bundle without an ML-KEM prekey fails with
394
+ `PQXDH_REQUIRED`, and any PQXDH failure raises rather than downgrading
395
+ (`internal/session/handshake.ts:156-408`). This matches `libsignal`, which
396
+ removed X3DH and rejects pre-Kyber prekey messages
397
+ ([`session.rs:105-112`][sess]). A stored classical session continues as a
398
+ Double Ratchet session. [Protocol Policy](./PROTOCOL_POLICY.md) documents the
399
+ policy.
389
400
 
390
401
  ---
391
402
 
@@ -439,36 +450,36 @@ The SDK is also stricter than `libsignal` on decode. It requires fields that
439
450
  lengths (`internal/encoding/proto/signal-message.ts:332-340`, `:488-505`). This
440
451
  is safer, and it is one more reason the formats cannot meet.
441
452
 
442
- ### 3.3 Skipped-key retention is much tighter than in libsignal
453
+ ### 3.3 Skipped-key retention adds a 7-day expiry to libsignal's limits
443
454
 
444
- The constants match: `MAX_MESSAGE_KEYS = 2000` and `MAX_FORWARD_JUMPS = 25000`
445
- (`internal/protocol/double-ratchet/ratchet.ts:194-227` vs
446
- [`consts.rs:8-9`][consts]). The two implementations apply them differently, and
447
- the difference is user-visible.
455
+ The constants match: `MAX_MESSAGE_KEYS = 2000`, `MAX_FORWARD_JUMPS = 25000`, and
456
+ `MAX_RECEIVER_CHAINS = 5` (`internal/protocol/double-ratchet/ratchet.ts:194-207`
457
+ vs [`consts.rs:8-10`][consts]). The SDK applies the caps as `libsignal` does,
458
+ and it adds one limit that `libsignal` does not have.
448
459
 
449
- **The cap is global, not per-chain.** `libsignal` applies 2000 to each chain's key
450
- vector ([`double_ratchet.rs:349-361`][dr]). Five receiver chains therefore give a
451
- true system capacity of 10,000 skipped keys. The SDK counts across all chains and
452
- evicts when the total reaches 2000
453
- (`internal/protocol/double-ratchet/chains.ts:478-513`). The effective capacity is
454
- 5× smaller, and traffic on a newer chain can evict keys that belong to an older
455
- one.
460
+ **The cap is per chain.** `libsignal` applies 2000 to the key vector of each
461
+ chain ([`double_ratchet.rs:346-361`][dr]). The SDK does the same
462
+ (`internal/protocol/double-ratchet/chains.ts:425-447`). A store to one chain
463
+ never evicts a key of another chain. The worst case is 5 receiver chains of
464
+ 2000 keys each, in the current session and in each of up to 40 archived
465
+ sessions (`types/session.ts:800`).
456
466
 
457
- **Wall-clock timestamps drive eviction.** The SDK scans every chain for the
458
- oldest entry (`internal/protocol/double-ratchet/chains.ts:414-463`). By contrast,
459
- `libsignal` evicts strictly by insertion position. `Date.now()` is not monotonic,
460
- so a clock adjustment makes the eviction order non-deterministic.
467
+ **A full chain evicts its lowest index.** `libsignal` inserts each key at the
468
+ front and drops the last entry, which is the oldest insertion. The keys of one
469
+ chain are stored in index order, so the two rules drop the same key. The SDK
470
+ does not read the clock to choose the key.
461
471
 
462
472
  **Skipped keys expire after 7 days**
463
- (`internal/protocol/double-ratchet/ratchet.ts:197`). `libsignal` has no
464
- time-based expiry for message keys at all.
473
+ (`internal/protocol/double-ratchet/ratchet.ts:180`). `libsignal` has no
474
+ time-based expiry for message keys. Double Ratchet §8.4 recommends this policy:
475
+ a held skipped key decrypts its message for as long as it stays, so a
476
+ compromise of the device state exposes each message whose key is held. The
477
+ expiry bounds that window.
465
478
 
466
- Taken together, these three differences create **message-delivery patterns where
467
- this SDK reports an undecryptable message and `libsignal` decrypts it**. Two
468
- recipients can lose messages that the specification's own limits keep. The first
469
- is offline for more than a week. The second takes heavy traffic on a new chain
470
- while older-chain messages are still in flight. The bounds are defensible as
471
- storage hygiene. The consequence should not be a surprise.
479
+ The consequence: **a message more than 7 days out of order is undecryptable in
480
+ this SDK, and `libsignal` decrypts it.** This occurs when the recipient is
481
+ offline for more than a week, or when the message stays in transit for more
482
+ than a week.
472
483
 
473
484
  Two related extensions go with this. A `processedChains` map rejects messages
474
485
  that bear a ratchet key from a retired chain
@@ -479,22 +490,29 @@ where `libsignal` uses `usize::MAX`.
479
490
 
480
491
  ### 3.4 Session archiving and serialization
481
492
 
482
- The cap matches: 40 archived states, [`consts.rs:11`][consts]. The structure
483
- differs. `libsignal` keeps an ordered list with strict insertion-order eviction
484
- ([`session.rs:787-830`][st]). The SDK keeps a map keyed by base key and trims by
485
- `lastUsedAt` (`types/session.ts:815-847`). Archiving a session whose base key
486
- already exists overwrites rather than appends, so the effective history can be
487
- shorter than 40.
488
-
489
- `libsignal` clears unacknowledged prekey state before archiving a session. The
490
- SDK does not. Retired sessions therefore keep pending prekey references alive in
491
- storage.
492
-
493
- **Session records serialize as JSON, not protobuf** (`types/session.ts:1002-1028`).
494
- The source states this as a simplicity and debuggability choice. Two consequences
495
- are worth naming. No Signal Messenger client can read or write these stored
496
- sessions. Key material also sits in immutable JavaScript strings that nothing can
497
- zero, where `libsignal` can zero its byte vectors.
493
+ The cap matches: 40 archived states, [`consts.rs:11`][consts]. The eviction
494
+ order matches: `libsignal` drops the oldest insertion from its ordered list
495
+ ([`session.rs:814-826`][st]), and the SDK drops the oldest insertion from its
496
+ archive (`types/session.ts:844-879`). The structure differs. The SDK keeps a
497
+ map keyed by base key. Archiving a session whose base key is already archived
498
+ moves that entry to the newest end rather than adding a second one, so the
499
+ effective history can be shorter than 40.
500
+
501
+ The archive clears the unacknowledged prekey state, as `libsignal` does
502
+ ([`session.rs:814-826`][st] calls `clear_unacknowledged_pre_key_message`,
503
+ [`session.rs:566-589`][st]). `SessionRecord.archiveCurrent` and
504
+ `promoteSession` archive a copy of the session without the pending flag, the
505
+ prekey identifiers, and the KEM ciphertexts (`types/session.ts:824-834`). A
506
+ promoted session sends a SignalMessage, not a PreKeyMessage.
507
+
508
+ **Session records serialize as JSON, not protobuf**
509
+ (`local/store/session-codec.ts:10-24`). The constraint is that no Signal client
510
+ reads or writes an SDK store, so the stored format has no interoperability
511
+ requirement. The SDK session also has fields that the `libsignal` record has no
512
+ place for, such as the KEM one-time prekey ciphertext next to the Kyber
513
+ ciphertext (`types/session.ts:255-256`). One consequence is worth naming. Key
514
+ material sits in immutable JavaScript strings that nothing can zero, where
515
+ `libsignal` can zero its byte vectors.
498
516
 
499
517
  ### 3.5 Padding
500
518
 
@@ -519,8 +537,8 @@ sits 16 bytes past each boundary rather than on it.
519
537
  ## 4. SPQR and the ML-KEM Braid
520
538
 
521
539
  This is the same protocol as the SparsePostQuantumRatchet v1 protocol, implemented
522
- independently and pinned against commit `fd32048`, which upstream tags
523
- `SparsePostQuantumRatchet v1.5.3`. The fidelity is high and specific:
540
+ independently and pinned against commit `06959b4`, which upstream tags
541
+ `SparsePostQuantumRatchet v1.6.0`. The fidelity is high and specific:
524
542
 
525
543
  - **KDF labels are byte-identical**, including the double space in
526
544
  `"Signal PQ Ratchet V1 Chain Start"` (`internal/crypto/kdf/hkdf.ts:353-368`).
@@ -537,18 +555,46 @@ independently and pinned against commit `fd32048`, which upstream tags
537
555
  - **ML-KEM-768 with the same incremental split** (32-byte seed, 1152-byte vector,
538
556
  960/128-byte ciphertext parts).
539
557
 
540
- The delta review that moved the pin forward from `f2589fef` found one behavioral
541
- change upstream. Decoding a chain epoch direction now rejects a `next` chain key
542
- whose length is neither zero nor 32 bytes. The internal next-key assertion checks
543
- that same exact length rather than mere non-emptiness.
558
+ Two delta reviews moved the pin forward from `f2589fef`.
544
559
 
545
- The SDK is already at least as strict. Restoring SPQR state requires every chain
546
- key, root key, and skipped-message key to be canonical base64 for exactly 32
547
- bytes (`internal/protocol/spqr/serialize.ts:44-72`). The SDK has no state in
548
- which the key is absent. Two upstream error strings now name the value they
549
- reject. The rest of the delta is proof-assistant annotation and loop rewriting,
560
+ The step to `fd32048` found one behavioral change upstream. Decoding a chain
561
+ epoch direction now rejects a `next` chain key whose length is neither zero nor
562
+ 32 bytes. The internal next-key assertion checks that same exact length rather
563
+ than mere non-emptiness. Two upstream error strings now name the value they
564
+ reject. The rest of that delta is proof-assistant annotation and loop rewriting,
550
565
  which leaves behavior unchanged.
551
566
 
567
+ The SDK refuses the same key at a different point. The internal SPQR state
568
+ loader requires every chain key, root key, and skipped-message key to be
569
+ canonical base64 for exactly 32 bytes (`internal/protocol/spqr/serialize.ts:44-72`).
570
+ The production session load does not run that loader, and it does not check the
571
+ chain-key length. A stored wrong-length chain key fails at its first chain step,
572
+ because the chain KDF refuses a key that is not 32 bytes
573
+ (`internal/crypto/kdf/hkdf.ts:438-445`). Upstream refuses the key when it loads
574
+ the state. The SDK has no state in which the key is absent.
575
+
576
+ The step to `06959b4` has two commits that change behavior. `cb8a727` ("Improve
577
+ handling of higher-than-1 SPQR versions") moves preamble parsing into
578
+ `src/lib.rs` (`msg_preamble`) and moves the epoch-0 index-0 case into
579
+ `Chain::recv_key` (`src/chain.rs:417-419`). `a395789` ("Disallow unsupported
580
+ versions from turning off PQ ratcheting") makes an unknown version after
581
+ negotiation a `VersionMismatch` error. It also removes `displaydoc`, moves
582
+ `curve25519-dalek` to the dev-dependencies, and adds one lint attribute to
583
+ `polynomial.rs`. The changed files are `src/lib.rs`, `src/chain.rs`,
584
+ `src/v1/chunked/states.rs`, `src/v1/chunked/states/serialize.rs`,
585
+ `src/encoding/polynomial.rs`, `Cargo.toml`, `Cargo.lock`, and one upstream
586
+ test module. `Version::MAX` stays `V1` (`src/lib.rs:239`). No KDF label,
587
+ framing byte, or Reed–Solomon parameter changes.
588
+
589
+ The SDK behavior does not change. Upstream now returns an epoch-0 key for a
590
+ higher-version message before negotiation, and it refuses an unknown version
591
+ after negotiation. The SDK refuses a version byte other than 1 before
592
+ negotiation and ignores it after negotiation. Neither path occurs between v1
593
+ peers. The SDK fixes the braid version at 1
594
+ (`internal/protocol/spqr/ml-kem-braid/serialize.ts:270-272`,
595
+ `internal/protocol/spqr/spqr.ts:597`) and maps a version byte other than 1 to
596
+ `v0` (`internal/protocol/version.ts:254`, `:183-197`).
597
+
552
598
  ### 4.1 The `hek` operand order diverges
553
599
 
554
600
  One divergence breaks interoperability completely. The SDK computes
@@ -607,10 +653,19 @@ analogue.
607
653
  where `libsignal` uses an 11-variant `oneof` over nested structures. Serialized SPQR
608
654
  state is not portable in either direction.
609
655
 
610
- **Deviation.** Skipped-key eviction in the SPQR chain triggers at the cap and
611
- evicts by wall-clock timestamp, where `libsignal` triggers at `max_ooo × 11/10 + 1` and
612
- evicts by message index. `libsignal`'s rule is deterministic and index-anchored.
613
- The SDK's rule puts a clock dependency into ratchet state.
656
+ **Faithful.** The SPQR chain trims the held skipped keys of one epoch by
657
+ message index, as `libsignal`'s chain collects its key history. When an epoch
658
+ holds `max_ooo × 11/10 + 1` keys or more, 2201 by default, a receive drops each
659
+ key of that epoch whose index is below the receive counter minus `max_ooo`
660
+ (`internal/protocol/spqr/validate.ts:63-123`, called at
661
+ `internal/protocol/spqr/spqr.ts:1331`, vs `src/chain.rs:84-88` and `:146` at
662
+ `06959b4`). A jump past every held key clears the held keys of the epoch first
663
+ (`internal/protocol/spqr/spqr.ts:1273`, `:1320-1324` vs `src/chain.rs:266-270`). The
664
+ trim reads no clock. The horizon is equivalent: `libsignal` trims before it
665
+ steps its counter to the received index and so keeps one key that its refusal
666
+ rule (`src/chain.rs:192-194`) already refuses, and the SDK trims after the step
667
+ and keeps exactly the keys that the same rule accepts, so both decrypt the same
668
+ messages.
614
669
 
615
670
  **Deviation.** The varint decoder is the stricter of the two. It rejects any
616
671
  value above `uint64` (`internal/encoding/proto/pq-ratchet-serialize.ts:163-186`).
@@ -676,22 +731,68 @@ These parts are faithful:
676
731
  The per-user identity model is one of the two models the specification permits
677
732
  (§3.1).
678
733
 
679
- ### 5.1 The SDK removes deleted devices instead of marking them stale
734
+ ### 5.1 The SDK marks a removed device and keeps it for MAXLATENCY
680
735
 
681
736
  §3.1 and §3.3 require an implementation to mark a removed device's record stale
682
737
  and keep it for MAXLATENCY. Messages already in flight from that device then
683
- still decrypt. The SDK removes the record immediately
684
- (`internal/sesame/manager.ts:2098-2102`). A send also removes, immediately, each
685
- device record that the relay no longer lists for the recipient (§5.5).
686
-
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.
691
-
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.
738
+ still decrypt. The SDK does this. A removal sets `removedAt` on the device
739
+ record, archives its current session, and keeps the record
740
+ (`internal/sesame/manager.ts:417-447`). A message that the device sent before
741
+ its removal therefore still decrypts against the archived session. Signal's
742
+ Android client also archives the session of a device that the server no longer
743
+ lists, in `SignalServiceMessageSender`. A send marks a device record in the
744
+ same way on two triggers:
745
+
746
+ - The relay no longer lists the device for the recipient (§5.5).
747
+ - On a relay that compares device sets, the send holds no message for the
748
+ account of the device, and the relay has no prekey bundle for the device
749
+ (`NOT_FOUND`). The Signal Protocol Relay gives that answer for an unregistered
750
+ device, and for a registered device that has no uploaded prekeys. The relay
751
+ can still list such a device.
752
+
753
+ A removed device gets no fan-out. One predicate, `isRemovedDevice`
754
+ (`internal/sesame/types.ts:347-355`), states the rule, and each device
755
+ enumeration of the send paths applies it. When the device list names the
756
+ device again, the marker clears, and the device returns to fan-out with no
757
+ current session. Its archived sessions stay
758
+ (`internal/sesame/manager.ts:449-483`).
759
+
760
+ The stale-record cleanup deletes a removed record when its removal is older
761
+ than `maxLatency`, 30 days by default (`internal/sesame/types.ts:357-369`,
762
+ `internal/sesame/manager.ts:2251-2261`). The receive queue runs the cleanup
763
+ once in each client run, after it resumes its stored receives. Nothing orders
764
+ the cleanup after a fetch of the whole mailbox, which §3.1 recommends.
765
+
766
+ The constraint is the message lifetime at the relay. The Signal Protocol Relay
767
+ caps the durable TTL of a message at 30 days (`MAX_DURABLE_TTL_SECONDS` in the
768
+ Relay mailbox contract). It enforces the cap when it parses a project and on
769
+ each request. The SDK fixes `maxLatency` at the same 30 days
770
+ (`internal/sesame/types.ts:114`), and no public client option sets it. The
771
+ removal clause is strict: the cleanup deletes the record only when
772
+ `now - removedAt > maxLatency`. A message that the Relay accepted before the
773
+ removal is therefore gone from the Relay before `maxLatency` passes after the
774
+ removal, and the record outlives it. The §3.1 guarantee for messages in flight
775
+ thus holds without a fetch of the whole mailbox. The Convex relay keeps a
776
+ message for 7 days (`remote/relay/convex/component/messages.ts:18`), so the
777
+ bound holds there too.
778
+
779
+ Two caveats limit the bound:
780
+
781
+ - **Clock skew.** The client measures the window on its own clock, and the
782
+ Relay measures the TTL on its clock. A fixed offset between the two clocks
783
+ cancels. If the client clock moves forward by e against the Relay clock
784
+ between the removal and the cleanup, the record goes e early. A message that
785
+ the Relay accepted up to e before the removal can then fail to decrypt.
786
+ - **Memory relay.** The in-process memory relay keeps a message with no TTL,
787
+ so the bound does not hold there. A message from a removed device that waits
788
+ there for longer than `maxLatency` after the removal can fail to decrypt.
789
+
790
+ Guarantee tests pin the default `maxLatency` at exactly 30 days, and assert
791
+ that no public client options type carries a `maxLatency` option.
792
+
793
+ The SDK also uses the word `stale` for a different concept: a device *list*
794
+ that needs refetching (`internal/sesame/types.ts:512-518`). The specification
795
+ uses the word for a deleted user or device, which the SDK calls removed.
695
796
 
696
797
  ### 5.2 Session expiry applies only to unacknowledged sessions
697
798
 
@@ -715,29 +816,18 @@ permits device IDs up to 127. The cap is a
715
816
  product decision. A source comment credits it to the Signal Protocol, which is
716
817
  inaccurate.
717
818
 
718
- ### 5.4 Extensions: provisioning, transfer, device names
819
+ ### 5.4 Extensions: transfer, device names
719
820
 
720
821
  Sesame rev. 2 holds none of these. It says nothing about how a device comes to
721
822
  exist, takes a name, or migrates.
722
823
 
723
- **QR device provisioning** (`device/provisioning.ts`). Ephemeral X25519 ECDH →
724
- HKDF → AES-256-GCM, with a `signalprotocol://link-device` QR scheme, strict prefix
725
- and key validation, a 5-minute TTL, and rollback on both server and local failure.
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.
729
-
730
- **Device transfer** (`device/transfer.ts`). Clones the identity private key and
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.
824
+ **Device transfer** (`device/transfer.ts`). Copies the account identity key
825
+ pair, private key included, to a new device. The bundle holds no prekeys,
826
+ ratchet sessions, sender-key state, message state, or outbox state, and restore
827
+ rejects a bundle that holds one. The new device generates its own prekeys and
828
+ starts its own sessions, so each device keeps its own sessions as Sesame
829
+ requires. After a transfer, two physical devices hold the same identity private
830
+ key. That is the per-user identity model that the SDK selects.
741
831
 
742
832
  **Encrypted device names** (`device/device-name-crypto.ts`). A three-field
743
833
  protobuf carries a synthetic IV that HMAC derives, with AES-256-CTR. That is the
@@ -746,7 +836,7 @@ counterpart.
746
836
 
747
837
  **Identity-change gating.** The SDK TOFU-pins an unseen identity. A changed
748
838
  identity sets `pendingVerification` and blocks sending until the application
749
- accepts the rotation (`internal/sesame/manager.ts:561-566`, `:1682-1714`). Sesame
839
+ accepts the rotation (`internal/sesame/manager.ts:702-706`, `:1843`). Sesame
750
840
  rev. 2 has no such concept. This is a genuine improvement.
751
841
 
752
842
  **Not implemented:** proof of possession. Registration does not make the device
@@ -754,49 +844,90 @@ sign a server-issued nonce with its identity private key. Registration therefore
754
844
  trusts the relay more than §6.3 assumes. A deployment that needs proof of
755
845
  possession must add it at the application layer.
756
846
 
757
- ### 5.5 The sender reads the device list; the server does not reject a stale send
847
+ ### 5.5 The relay compares the declared device set
848
+
849
+ Reviewed: 2026-10-18.
758
850
 
759
851
  §3.3 steps 3 and 4 make the server the check. The server accepts a send only
760
852
  when the sender's list of device IDs is current, and otherwise rejects it with
761
- the old and new device IDs. The Signal Protocol Relay takes one message per
762
- device and has no whole-user device-set check, so it cannot reject a send
763
- that omits a device.
764
-
765
- The SDK therefore reads the recipient's device list from the relay
766
- (`getActiveDevices`) before a direct send or a sender key distribution, when
767
- the last read for that recipient is more than 60 s old
768
- (`RECIPIENT_DEVICE_LIST_FRESH_MILLISECONDS` in
853
+ the old and new device IDs.
854
+
855
+ The Signal Protocol Relay and the memory relay make this check. Each post to
856
+ an account declares the device IDs that the sender holds records for. The
857
+ relay compares the declaration with its device list and with the registration
858
+ of each device:
859
+
860
+ - When a device is missing or extra, it refuses the post with
861
+ `DEVICE_SET_MISMATCH` (409), and names the missing and the extra devices.
862
+ - When the registration of a device changed, it refuses the post with
863
+ `STALE_DEVICE` (410), and names those devices.
864
+
865
+ The SDK then removes each extra device record, starts a new session with each
866
+ missing or stale device, and encrypts the message again only for those
867
+ devices. It posts again with the repaired declaration. §5.6 lists the details
868
+ that differ from Signal.
869
+
870
+ On these relays, a send to a recipient with a session reads no device list. A
871
+ recipient with no session gets one list read to start the sessions. A group
872
+ send declares the devices of the records that it holds, and reads the list of
873
+ a member only when it holds no record for that member. The SDK reads the own
874
+ device list only when a recipient receipt sets `needsSync` and the sender
875
+ holds no record of another own device. One exception holds in a live send and
876
+ in a replay. A repair that leaves an account with no device record reads the
877
+ list of that account once.
878
+
879
+ The Convex relay does not compare device sets. With it, the SDK declares
880
+ nothing. It reads the recipient's device list (`getActiveDevices`) before a
881
+ direct send or a sender key distribution, when the last read for that
882
+ recipient is more than 60 s old (`RECIPIENT_DEVICE_LIST_FRESH_MILLISECONDS` in
769
883
  `client/signal-service-cipher.ts`). It makes a session for each listed device
770
- that has none, and removes each local device record that the relay does not
771
- list. The time of the last read is kept in memory only, so a restarted client
772
- reads the list on its first send to each recipient.
773
-
774
- On the Signal Protocol Relay, a direct send posts first and reads second
775
- when the last successful read for that recipient in this process is at least
776
- 60 s and less than 300 s old
777
- (`RECIPIENT_DEVICE_LIST_MAXIMUM_AGE_MILLISECONDS`). The send posts to the known
778
- devices, and then reads the list. It encrypts the same message for each newly
779
- listed device and posts it in the same send. It drops a device that the Relay
780
- refused and the list no longer shows. The stored intent records that its read
781
- is pending, so a replay after a crash reads the list before it completes. A
782
- sender key distribution, and a send through the Convex or memory relay, reads
783
- first as above.
784
-
785
- **Consequence on the Signal Protocol Relay.** A device linked less than 60 s
786
- before a send can miss that send. A device linked 60 s to 300 s before a send
787
- receives it when the read in that send succeeds. A removed device receives no
788
- message, because the Relay refuses the device's mailbox before the list shows
789
- the removal. The 300 s maximum limits only how long a client posts first on a
790
- list that no read confirmed.
791
-
792
- **Consequence on the Convex and memory relays.** A device linked less than
793
- 60 s before a send can miss that send, and a device removed less than 60 s
794
- before a send can still receive it.
884
+ that has none, marks each local device record that the relay does not list as
885
+ removed, and clears the mark of a removed record that the list names again
886
+ (§5.1). The time of the last read is kept in memory only, so a restarted client
887
+ reads the list on its first send to each recipient. Each send also reads the
888
+ own device list before it posts.
889
+
890
+ **Consequence on the Signal Protocol Relay and the memory relay.** A device
891
+ that is linked or removed before the relay accepts a post changes the answer
892
+ to that post. A linked device gets the message, and a removed device does not.
893
+ A phase of a send that does not match in 10 restarts fails the send with
894
+ `DeviceSetReconciliationError`.
895
+
896
+ **Consequence on the Convex relay.** A device linked less than 60 s before a
897
+ send can miss that send, and a device removed less than 60 s before a send can
898
+ still receive it.
795
899
 
796
900
  The SESAME stale-device-list retry loop (`StaleDeviceListError`) stays in
797
901
  `internal/sesame/manager.ts`, but no caller supplies a device-list version, so
798
902
  it never runs.
799
903
 
904
+ ### 5.6 Device-set reconciliation differs in detail
905
+
906
+ Reviewed: 2026-10-18.
907
+
908
+ The reconciliation of §5.5 follows Signal's server and Signal's Desktop
909
+ client in its rule: the server compares, the client repairs and posts again,
910
+ and a bound stops the loop. The bound of 10 restarts in each phase equals the
911
+ bound of Signal's Desktop client. It is stricter than the 4 attempts of
912
+ Signal's Android client. The following details differ.
913
+
914
+ | ID | Deviation | Constraint | Why Signal's form does not fit | Guarantee test |
915
+ |---|---|---|---|---|
916
+ | D1 | A stale registration is reported after missing and extra devices on every route, also for a direct post to one account | One answer order for every route | Signal's server reports stale devices first on its route for one account | Relay tests assert the order on each route |
917
+ | D2 | A direct send is one post for each device, and each post carries the full declaration of the account | The direct Relay route takes one destination for each body. A replay works for each device | One Signal request carries every device of the account. Here a race can accept some posts and refuse others | A restart posts the stored bytes to each accepted device, and each device gets the message once. A partly accepted pass posts every device again, and an accepted device replays |
918
+ | D3 | A group comparison reads the record of each account, up to 1,000, when the Relay accepts the post | The Relay keeps one record for each account | Signal's server reads accounts from one store in one process | Relay tests, and a cost measurement |
919
+ | D4 | The operation time is fixed. `OPERATION_EXPIRED` ends the reconciliation | The Relay admits an operation for 5 minutes | Signal has no admission window | A restart post that gets `OPERATION_EXPIRED` ends the phase as expired |
920
+ | D5 | No fallback to one post for each recipient after the bound | The same bound covers every path | Signal's Desktop client falls back because its one-to-one path has no bound. Under the bound, a fallback only moves the churn | The 11th refusal of a phase ends the send with `DeviceSetReconciliationError` |
921
+ | D6 | A direct send also stops at 10 restarts | One bound for every send | Signal's Desktop client has no bound on missing or extra devices for a one-to-one send | The restart bound test of the direct send |
922
+ | D7 | No empty sync post. A `needsSync` mark on the recipient receipt and one read of the own list replace it | A Relay post needs at least one destination | Signal's server accepts an empty sync list, and Signal's Android client addresses its own device | A new own device repairs the sync phase and the recipient post is not sent again. The own list is read only on `needsSync` with no own record, and a failed read leaves the sync phase pending |
923
+ | D8 | A group post settles a not-found account as a refusal of each of its destinations, and the Relay accepts the rest | `NOT_FOUND` is a fan-out result code. A refusal of the whole post would use a restart | This is equivalent to the group-send-token path of Signal's server, which sends to the accounts it resolves and returns the others. Only the form differs: a refusal code for each destination | A removed account settles as refused and the send adds nothing. A lost response resumes as a duplicate with no not-found account |
924
+ | D9 | The receipt of a declared post carries a `deviceSetChecked` mark | The identified Relay route passes unknown keys, and a deployment lane can lag the SDK | Signal ships its client and server together | A receipt without the mark raises `DEVICE_SET_UNCHECKED` through `onRelayProtocolError` |
925
+ | D10 | The SDK seals a group body again only before the Relay accepts it, and only after a definite refusal | The Relay keeps a fingerprint of each operation and answers `RETRY_CONFLICT` to a second body under the same ID | Signal stores nothing on the server for a send attempt | A refused body is replaced in one write. A crash before the post of the replaced body posts it on resume |
926
+ | D11 | A group restart keeps the group ciphertext, seals the shared body again, and replaces it in one write. It does not encrypt the content again | One group pass posts the same ciphertext in the shared body and in the device posts. A new ciphertext would change a device post that the Relay already accepted, and its replay would get `RETRY_CONFLICT` | Signal's Desktop client encrypts again for each attempt | The group ciphertext is byte-equal before and after the replacement, the accepted device post replays to its stored receipt, and the new body names the repaired destinations |
927
+ | D12 | A declared post with no `recipientRegistrationId` skips the registration check | The field is optional on every Relay route | Signal's server compares the registration of each device of a post | A Relay test posts an unnamed registration |
928
+ | D13 | A declaration that names the sender device gets 400 | The Relay refuses a malformed declaration before it compares | Signal's server answers 409 and names the sender device as an extra device | Relay tests on the direct and the group routes. The SDK does not declare the sender device |
929
+ | D14 | The identified group route compares the declared device set, with the codes and the order of the direct route | The route serves Relay API customers | Signal has no identified group route | Relay tests. No SDK code calls the route |
930
+
800
931
  ---
801
932
 
802
933
  ## 6. Sealed sender
@@ -818,26 +949,42 @@ The base trust-root loop also matches. It does not short-circuit and therefore
818
949
  does not reveal which root validated. Required signed scope and issuer-validity
819
950
  checks extend the upstream certificate semantics.
820
951
 
821
- **`PLAINTEXT_CONTENT` (8) is a known wire value that this SDK rejects.**
822
- `libsignal` uses it to carry a `DecryptionErrorMessage` when no session exists
823
- to encrypt one under ([`sealed_sender.rs:2055-2075`][ss]). This SDK instead
824
- sends a decryption-error signal as an identified mailbox envelope with
825
- `messageType: 'retry_request'` (Sesame §4.1, `client/retry-request-envelope.ts`).
826
- No send path produces the type, and no decrypt path consumes it. The envelope parse therefore
827
- rejects the value (`internal/protocol/sealed-sender/types.ts`) rather than map it
828
- to an envelope type with no handler.
829
-
830
- The enum keeps the member so the wire values stay a faithful record.
831
- `envelopeTypeForContent` throws on it, so a new member without a route fails
832
- loudly. A peer that sends one gets a clean parse failure, not a payload routed
833
- into the pairwise ratchet.
834
-
835
- Note the cost when you debug interop. The parsers throw a single generic error
836
- for every malformed envelope. A peer implementation that legitimately sends
837
- `PLAINTEXT_CONTENT` therefore fails with `Sealed sender verification failed`,
838
- which is the same string a MAC mismatch produces. The uniformity is deliberate,
839
- and the parse runs after authentication, so nothing here is an oracle. Watch for
840
- one pattern: sealed messages from one peer stack fail with that error while
952
+ **`PLAINTEXT_CONTENT` (8) carries a sealed retry request, with an SDK payload.**
953
+ `libsignal` uses the type to carry a serialized `DecryptionErrorMessage` when
954
+ no session exists to encrypt one under ([`sealed_sender.rs:2055-2075`][ss]).
955
+ This SDK uses the same type for its own retry request (Sesame §4.1,
956
+ `client/retry-request-envelope.ts`). The sealed content is the small JSON
957
+ payload that the identified `retry_request` envelope carries, not a
958
+ `DecryptionErrorMessage`. The wire value matches. The payload does not.
959
+
960
+ A retry request follows the sealed sender delivery mode, as a delivery
961
+ receipt does. When the requester holds the access key of the target, it seals
962
+ the request, and the Relay does not see the requester. A group send
963
+ endorsement never seals a retry request. Without an access key, or when the
964
+ Relay refuses the access key, the request goes identified only in
965
+ `'preferred'` mode. In `'required'` mode the request never goes identified.
966
+ It stays pending, and the scheduler posts it again until its deadline. In
967
+ `'disabled'` mode it is always identified. An identified retry request shows
968
+ the Relay which device could not decrypt a message from which sender, so it
969
+ does not have the privacy of a sealed request.
970
+
971
+ The receive path accepts the type only for this route. The cipher unseals the
972
+ envelope, and a content type of 8 goes to the retry request handler, never to
973
+ a ratchet decrypt. The seal authenticates the requester: the authentication
974
+ tag binds the sealing key to the identity key of the sender certificate, and
975
+ the certificate must validate against the trust roots. `envelopeTypeForContent`
976
+ maps 8 to `retry_request`, so a new member without a route still fails loudly.
977
+
978
+ Note the cost when you debug interop. A `libsignal` peer that sends
979
+ `PLAINTEXT_CONTENT` with a `DecryptionErrorMessage` reaches the retry request
980
+ handler, which drops it as a malformed retry request. A shipped `11.0.x`
981
+ release of this SDK rejects the type at the parse. That receiver drops a
982
+ sealed retry request from a newer client, and the requester ends the request
983
+ as expired content. The parsers throw a single generic error for every
984
+ malformed envelope, `Sealed sender verification failed`, which is the same
985
+ string a MAC mismatch produces. The uniformity is deliberate, and the parse
986
+ runs after authentication, so nothing here is an oracle. Watch for one
987
+ pattern: sealed messages from one peer stack fail with that error while
841
988
  messages from this SDK succeed. Check the leading content-type byte before you
842
989
  treat that as a cryptographic failure.
843
990
 
@@ -904,7 +1051,7 @@ signing key as 33 bytes where the SDK uses 32.
904
1051
 
905
1052
  ### 7.2 Message-key derivation matches the reference
906
1053
 
907
- Reviewed: 2026-10-06.
1054
+ Reviewed: 2026-10-11.
908
1055
 
909
1056
  The SDK derives Sender Keys message material with HKDF-SHA256 Extract and
910
1057
  Expand. Its input is `HMAC-SHA256(chain_key, 0x01)`, its salt is 32 zero bytes,
@@ -1008,6 +1155,354 @@ Credential serialization is also ad hoc and carries no version byte, where
1008
1155
  `libsignal` uses a leading version byte. That is a forward-compatibility gap
1009
1156
  rather than a security one.
1010
1157
 
1158
+ ### 7.5 Sender-key distribution tracking
1159
+
1160
+ Reviewed: 2026-10-20.
1161
+
1162
+ `libsignal` creates and processes sender-key distribution messages. It does
1163
+ not record which devices hold a key. The Signal apps do that work.
1164
+ Signal-Android keeps a shared-with set for each distribution
1165
+ (`SenderKeySharedTable`). Signal-Desktop keeps the member devices with
1166
+ each sender key. The SDK keeps a handoff
1167
+ ledger for the same role. A row records that the Relay accepted a distribution
1168
+ of the own key for one device of another member. A send gives the key to each
1169
+ listed device with no matching row, and to each device with no session.
1170
+
1171
+ These parts follow Signal-Android:
1172
+
1173
+ - An inbound PreKey session deletes the rows of that device in every group.
1174
+ The SDK deletes them in the same write as the session. Signal-Android uses a
1175
+ separate write.
1176
+ - A session archive deletes the rows of that device in every group.
1177
+ - An identity change deletes the rows of the account.
1178
+ - A retry request for a group message deletes the rows of that device in that
1179
+ group only.
1180
+ - The session reset after an expired retry request deletes the rows of each
1181
+ device of the account in every group, as `AutomaticSessionResetJob` does.
1182
+ It does so for a group message and for a pairwise message. It archives the
1183
+ session with the device that sent the failed envelope only.
1184
+ - A rotation deletes the rows of the group. The SDK deletes them in the same
1185
+ write as the key.
1186
+ - Own devices get the sent transcript and no distribution.
1187
+ - When the Relay refuses a sync copy because the registration of the own
1188
+ device changed, the SDK starts a new session and posts the transcript
1189
+ again. Signal-Android tries a send up to 4 times. The SDK repairs each
1190
+ refused copy once, as it does each other refused post. A second refusal
1191
+ archives the session and drops the copy.
1192
+
1193
+ The following details differ:
1194
+
1195
+ **1. The row match includes the key ID and the registration ID**.
1196
+ Signal-Android keys a row by distribution and device. The registration-ID
1197
+ match is faithful to Signal-Desktop, which compares the registration IDs of
1198
+ the member devices. The key-ID match is an addition. A delete and then a
1199
+ create of the own key start again at generation 1, so the SDK also matches the
1200
+ key ID. A custom store can write the key and delete the rows in two writes,
1201
+ and a crash between them leaves a row. With the key ID in the match, that row
1202
+ never stops a device from getting the current key. A peer that holds the
1203
+ earlier key installs the new key, because the receiver matches a sender key by
1204
+ its ID and not by its generation.
1205
+
1206
+ **2. A new session from a prekey bundle deletes rows**. Signal-Android
1207
+ replaces a session only after an archive. In the SDK, the commit of a new
1208
+ session from a bundle archives the current session itself, so the same commit
1209
+ deletes the rows of the device.
1210
+
1211
+ **3. The SDK reads the own device list only on `needsSync`**. Signal learns
1212
+ of new and removed own devices from the 409 device-set mismatch answer of the
1213
+ server to a sync post, and it posts to the recipients first. The SDK keeps
1214
+ this order on the Signal Protocol Relay and the memory relay. The recipient
1215
+ phase posts first. Then the sync phase declares the own devices that the
1216
+ sender holds records for, and the relay compares them (§5.5). When a
1217
+ recipient receipt sets `needsSync` and the sender holds no record of another
1218
+ own device, the SDK reads the own list once (§5.6, D7). A failed read does
1219
+ not fail the send. The result carries `syncPending`, and a call to `send()`
1220
+ with the same `clientMessageId` reads the list again. The Convex relay does
1221
+ not compare device sets, so each send with it reads the own list before it
1222
+ posts. A failed read there stops the recipient post and fails the send or the
1223
+ sync API call.
1224
+
1225
+ **4. A replay keeps the stored group ciphertext**. Signal encrypts again for
1226
+ the devices of each attempt. The Relay refuses a second operation under the
1227
+ same message ID, so the replay of a stored group send keeps its ciphertext. A
1228
+ device that the replay adds cannot decrypt it. That device gets the content
1229
+ only through its retry request and the resend of a `Resendable` send.
1230
+
1231
+ **5. A sweep at start deletes the rows of a replaced key**. Signal has no
1232
+ sweep. The match already ignores these rows, so the sweep only frees storage.
1233
+
1234
+ **6. The Relay names each refused group destination**. Signal's server
1235
+ names each stale device in a 410 answer. The Relay refuses a declared group
1236
+ post with `DEVICE_SET_MISMATCH` or `STALE_DEVICE` before it accepts the post,
1237
+ and the SDK repairs as §5.5 says. The receipt of an accepted post carries a
1238
+ `refusals` list with a code for each refused destination. A `NOT_FOUND`
1239
+ refusal settles a removed account (§5.6, D8). The SDK does not infer a stale
1240
+ device from the count of refused destinations.
1241
+
1242
+ **7. Only a logged `Resendable` send can answer a retry request with its
1243
+ content** (2026-10-15). Signal-Android logs sends in its message send log
1244
+ through `MessageSendLogTables.insertIfPossible`. That method stores the
1245
+ content of a send only when the `retryReceipts` remote config is on, the send
1246
+ result is a success, and the result carries its content. For a group send, it
1247
+ stores one entry for the recipients whose result meets the last two
1248
+ conditions, and it stores no entry when no result does. The method does not
1249
+ read the content hint. A group send calls it only when its send operation
1250
+ returns true from `shouldIncludeInMessageLog`: a resendable data message or a
1251
+ story, and never a typing or call message (`GroupSendUtil`). A retry
1252
+ request for a group message with a log entry gets that content again. A
1253
+ request with no entry gets the sender-key distribution alone
1254
+ (`MessageContentProcessor`). Signal-Android keeps its own message
1255
+ database, so each resendable data message that it sends can have an
1256
+ entry. A data message sent through `sendUnresendableDataMessage`, such as
1257
+ a profile-key or group-call update, has none.
1258
+
1259
+ The constraint is that the SDK does not own the message store of the
1260
+ application. The SDK keeps a send log entry only for a group send whose
1261
+ content hint is `Resendable`. The SDK sets the hint by default from the
1262
+ content and the recovery policy. A group send of a `DataMessage` is
1263
+ `Resendable` when content recovery is on, and `Default` when it is off. A
1264
+ string or bytes send has no hint. The application can set another hint for a
1265
+ send. When it sets `Resendable` and the SDK cannot answer, because recovery
1266
+ is off or the content is a string or bytes, the send goes out as `Default`.
1267
+ So a retry request for another send finds no entry. The SDK then answers with the current
1268
+ distribution alone, as Signal-Android does for a missing entry. The device
1269
+ gets the key for later messages, but it does not get that message. Item 4
1270
+ makes this outcome more frequent, because a device that a replay adds can
1271
+ decrypt the send only through its retry request.
1272
+
1273
+ Two guarantee tests assert the two outcomes. For a send that is not `Resendable`, the send log has no entry, and
1274
+ the answer carries the current distribution and no message. For a
1275
+ `Resendable` send, the answer carries the message and the distribution.
1276
+
1277
+ **8. A receipt or a retry request keeps the stale session until the new
1278
+ session commits** (2026-10-16). Signal-Android archives the session of each
1279
+ stale device first (`SignalServiceMessageSender.handleStaleDevices`).
1280
+ The next pass of the send loop then fetches a bundle and starts a new
1281
+ session. Signal-Desktop also archives each stale session first, and then
1282
+ fetches the keys of the device (`handleMismatchedDevicesError`).
1283
+ When the fetch fails, an application job sends again later, and that send
1284
+ starts the session.
1285
+
1286
+ The constraint is that a receipt or a retry request has no application job
1287
+ that retries it. If the SDK archived first and the fetch failed, the item
1288
+ would have no session, and a lost session drops the item. So when the Relay
1289
+ refuses a receipt or a retry request as a stale device, the SDK fetches the
1290
+ bundle first. The session start then archives the stale session in the same
1291
+ record write that stores the new one. A failure before that write keeps the
1292
+ stale session, so the next post is refused again and refreshes again. A
1293
+ failure after that write, in the SESAME registration, leaves the new session,
1294
+ and the next post uses it. The `onSessionArchived` hook runs after the
1295
+ session start succeeds. The refresh of a send keeps the order of Signal: it
1296
+ archives the stale session first.
1297
+
1298
+ A guarantee test asserts the order. The
1299
+ first session start fails, the stale session stays, and the hook does not
1300
+ run. The retry refreshes the session, the hook runs once for the device, and
1301
+ the device decrypts the receipt.
1302
+
1303
+ **9. A late copy of a previous sender key changes nothing** (2026-10-16).
1304
+ Signal's published implementation keeps up to 5 sender-key states for each
1305
+ sender. When a distribution matches a kept state, [`add_sender_key_state`][sk]
1306
+ removes that state and puts it at the front of the record, so it becomes the
1307
+ current state again. The SDK also keeps up to 5 states and matches a
1308
+ distribution by its key ID. A distribution of the current key follows the
1309
+ generation rules of the SDK: a lower or the same generation changes nothing,
1310
+ and a higher generation replaces the current state in place. A distribution
1311
+ of a kept previous key changes nothing, and that state stays in its place.
1312
+ A distribution of another key becomes the current state, the earlier current
1313
+ state moves to the front of the previous states, and when the record already
1314
+ holds 5 states, the oldest state goes.
1315
+ So a replay of an installed distribution changes nothing only while its key
1316
+ is the current state or a kept previous state. When the key is neither, the
1317
+ replay installs it again as the current state, and when the record already
1318
+ holds 5 states, the oldest state goes.
1319
+
1320
+ The constraint is that the current state is the newest key that the sender
1321
+ installed. The receiver matches the current state first, so a late copy of
1322
+ an earlier key must not displace it. The cost is in the order of eviction.
1323
+ When the record holds K5, K4, K3, K2, and K1, with K5 current, a late copy of
1324
+ K1 and then K6 leave K6, K5, K4, K3, and K2 in the SDK. Signal keeps K1 and
1325
+ evicts K2. A message in flight under K1 then fails in the SDK.
1326
+
1327
+ A guarantee test asserts the rule. The receiver holds the replaced key as a
1328
+ previous state, and a late copy of its distribution arrives. The record keeps
1329
+ the new key current and the replaced key previous, and a message under the
1330
+ new key decrypts.
1331
+
1332
+ ### 7.6 Group sends and session writes take a lock across tabs
1333
+
1334
+ Reviewed: 2026-10-20.
1335
+
1336
+ Signal runs one process for each device. Signal's Desktop client exits a
1337
+ second instance and runs the sender-key jobs of one address one at a time.
1338
+ Signal's Android client takes its session lock around each group encrypt.
1339
+ `libsignal`'s `group_encrypt` loads the sender-key record and stores it with
1340
+ no lock of its own, so the caller supplies the exclusion.
1341
+
1342
+ A browser application can open several tabs on one store. When
1343
+ `navigator.locks.request` exists and the store sets `storeIdentity`, the SDK
1344
+ takes a Web Lock for each group send and for each session write. A group send
1345
+ takes `open-e2ee:group-send:<store identity>:<lock key>`
1346
+ (`client/group-sender-key-operations.ts:41-57`). The session lock, the user
1347
+ lock, and the device-list sync lock take
1348
+ `open-e2ee:session:<store identity>:<lock key>`
1349
+ (`internal/session/record-locks.ts:60-142`). The IndexedDB store and the web
1350
+ SQLite store set `storeIdentity` to their database names. The tabs, workers,
1351
+ and clients of one origin that share the store then run one operation of each
1352
+ lock key at a time. Inside the group send lock, the sender-key manager reads
1353
+ its state from the store again, so a rotation keeps the states that another
1354
+ tab wrote. The session lock and the device-list sync lock keep their 5 s wait
1355
+ timeout, so a lock-order fault or a hung holder shows as an error and not as a
1356
+ receive or send that never ends. On the Web Lock path the wait rejects with
1357
+ `ORIGIN_LOCK_TIMEOUT_MESSAGE` (`utils/origin-lock.ts:18`). On the in-process
1358
+ path it rejects with the timeout message of the in-process lock. A Web Lock
1359
+ queue has no bound on the number of waiting requests.
1360
+
1361
+ **Deviation.** Where `navigator.locks.request` does not exist, or the store
1362
+ sets no identity, `originLockScope` gives no scope
1363
+ (`utils/origin-lock.ts:25-32`), and each lock is an in-process lock keyed by
1364
+ the store object. The constraint is that a Web Lock name needs a name for the
1365
+ data that every tab gives alike, and such a runtime has no shared lock or no
1366
+ such name.
1367
+ The Node SQLite, key-value, and memory stores set no identity, and React
1368
+ Native has no `navigator.locks`. Node has `navigator.locks`, but its locks
1369
+ order one process only. Two processes, or two store objects, that share one
1370
+ database are then not ordered. The application must give one of them
1371
+ exclusive access, as Signal's Desktop client does with its single-instance
1372
+ lock.
1373
+
1374
+ Guarantee tests assert both paths. Two browser tests open two tabs on one
1375
+ IndexedDB store. In the first, both tabs send to one group at the same time:
1376
+ the two ciphertexts carry distinct iterations, and the receiver decrypts each
1377
+ message. In the second, both tabs encrypt on one direct session at the same
1378
+ time: the two ciphertexts carry distinct counters, and the receiver decrypts
1379
+ each message. Unit tests assert the lock names, the order of two store
1380
+ objects with one identity, the in-process fallback with no Web Locks and with
1381
+ no identity, the 5 s session lock timeout and its message on each path, the
1382
+ stop of a wait, and two sender-key managers that rotate in turn and keep both
1383
+ states in the archive.
1384
+
1385
+ ### 7.7 The SDK posts group sends to the anonymous route only
1386
+
1387
+ Reviewed: 2026-10-18.
1388
+
1389
+ Signal's server accepts a multi-recipient send only with an access key or a
1390
+ group send token, and it checks the device set of each recipient. The SDK
1391
+ posts each group send with a group send token to the anonymous group route of
1392
+ the Signal Protocol Relay (`client/hosted-anonymous-delivery.ts:269`, `:520`).
1393
+ No SDK release posts to the identified group route.
1394
+
1395
+ **Deviation in the Relay.** The Relay still serves the identified group
1396
+ route. It accepts a group post under the account credential of the sender,
1397
+ and it checks no device set when the post declares none. The constraint is
1398
+ that the Relay removes a served route forward only. The SDK does not depend on
1399
+ the route, so its removal changes no SDK behavior.
1400
+
1401
+ ---
1402
+
1403
+ ## 8. Receive queue
1404
+
1405
+ Reviewed: 2026-10-20.
1406
+
1407
+ The receive queue keeps each decrypted receive in the local store until the
1408
+ application hook accepts it and the receipt goes out (`client/receive-queue.ts`).
1409
+ Signal's Android client keeps the same work in its message jobs, and Signal's
1410
+ Desktop client keeps it in its table of unprocessed envelopes. This section
1411
+ states where the queue follows them and where it differs.
1412
+
1413
+ ### 8.1 The queue holds back one conversation
1414
+
1415
+ **Faithful.** A record that waits holds back the later records of its
1416
+ conversation only (`client/receive-queue.ts:379-402`). Group content keys by
1417
+ its group, a sent transcript keys by its destination, and other content keys
1418
+ by its sender account, as Signal's Android client names its message job
1419
+ queues. A record that
1420
+ has not decrypted yet keys by its sender account, because its conversation is
1421
+ not known. The commit order stays per sender device, because the ratchet of
1422
+ one device must step in order.
1423
+
1424
+ Guarantee tests assert a record that fails before its restore and holds back
1425
+ only its sender account, a group record that holds back its group from every
1426
+ sender, pairwise content of a blocked group, and a second sender in a blocked
1427
+ group whose direct message delivers.
1428
+
1429
+ ### 8.2 A failed hook has an attempt cap, and the record stays
1430
+
1431
+ **Deviation.** After `RECEIVE_HOOK_ATTEMPT_CAP`, 10 failed
1432
+ `onMessageDecrypted` attempts (`client/receive-queue.ts:285`), a record no
1433
+ longer holds back its conversation. Signal's Desktop client has the same cap.
1434
+ Desktop deletes such a record at startup and loses the message. The SDK keeps
1435
+ it.
1436
+ Each client start offers it to the hook once. After that offer, only
1437
+ `processPendingReceives` runs it again before the next start.
1438
+ `discardPendingReceive` removes it with no receipt, no hook call, and no
1439
+ expiry report. `PendingReceive` shows `hookAttempts`.
1440
+
1441
+ The constraint is that the hook is application code. The SDK cannot tell a
1442
+ lasting failure from a passing one. A drop loses content whose ratchet step is
1443
+ spent, and an application update can repair the hook. **Consequence:** a hook
1444
+ that ends the process on the record ends it once at each start, until the
1445
+ record expires or the application discards it.
1446
+
1447
+ Guarantee tests assert the offer once at start and not again at the hook
1448
+ registration, no second offer before the next start, and a discard with no
1449
+ receipt, no hook call, and no expiry report.
1450
+
1451
+ ### 8.3 A delivery receipt lives for 1 day
1452
+
1453
+ **Faithful.** A stored receipt is sent only within `RECEIPT_LIFESPAN_MS`, 1
1454
+ day, after the receipt becomes owed (`client/receive-queue.ts:292`). Signal's
1455
+ Android client gives its receipt job the same lifespan, and it creates the
1456
+ job when the receipt becomes owed. The record keeps the receipt across a
1457
+ restart, as Android stores its job. At the end of the lifespan the record
1458
+ completes with no receipt and no report.
1459
+
1460
+ Guarantee tests assert a receipt 1 ms before the end of the lifespan, no
1461
+ receipt at the end, the recovery report of a resend record at the end, and
1462
+ the stop of the receipt retries of a running client.
1463
+
1464
+ ### 8.4 Each awaited hook has a bound
1465
+
1466
+ **Deviation** in detail. A receive pass waits for each application hook for
1467
+ at most `receiveHookTimeoutMs`, 2 minutes by default
1468
+ (`client/receive-hook-bound.ts:36`). The value must be a positive integer no
1469
+ longer than the longest timer delay (`client/storage-protection.ts:169-179`).
1470
+ Signal's Desktop client bounds its receive dispatch at 2 minutes and its
1471
+ long-running tasks at 30 minutes.
1472
+
1473
+ The constraint is a founder ruling that sets the bound at 2 minutes. The SDK
1474
+ cannot tell a slow hook from a hung one, and one hung hook would otherwise
1475
+ stop all receive. **Consequence:** a timeout of `onMessageDecrypted` counts as
1476
+ one failed attempt, with the normal backoff and the attempt cap. A timeout of
1477
+ another hook is logged, and the pass continues. A settle after the bound
1478
+ writes nothing. A hook that needs longer than the bound fails each attempt.
1479
+
1480
+ Guarantee tests assert the 2-minute default, the refusal of an invalid bound,
1481
+ a hung `onMessageDecrypted` hook that counts one attempt for each pass, a
1482
+ late settle that writes nothing, and one timeout test for each other awaited
1483
+ hook.
1484
+
1485
+ ### 8.5 Admission bounds before a decrypt
1486
+
1487
+ **Extension.** Before a decrypt, the receive queue checks `maxItems`,
1488
+ `maxBytes`, and the group share `blockedGroupShare`
1489
+ (`client/receive-admission.ts:67-96`). The defaults are 3000 items, 750 MiB,
1490
+ and 0.25. They are provisional until a measurement of real receive queues
1491
+ replaces them (`client/constants.ts:36-43`). Signal's Desktop client decrypts
1492
+ each envelope as it arrives and bounds stored content only by age and attempts.
1493
+
1494
+ The constraint is that the SDK shares a storage budget with the application
1495
+ in a browser and on mobile. **Consequence:** a refused envelope is not
1496
+ acknowledged. It stays at the Relay and expires there with no local hook. On
1497
+ the WebSocket path, other conversations progress. An HTTP pull sends the Relay
1498
+ cursor of the page before it, so a full page of refused envelopes does not stop
1499
+ the pages behind it. A page without a Relay cursor clears the stored cursor,
1500
+ and the next pull starts at the head. Two processes that share one store can
1501
+ each pass the check and overshoot a bound.
1502
+
1503
+ Guarantee tests assert the global item and byte bounds, the group item and
1504
+ byte shares, the progress of direct and other-group messages beside a full
1505
+ group, and an HTTP pull past a full page of refused envelopes.
1011
1506
  ---
1012
1507
 
1013
1508
  ## Unverified and needs review