@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
@@ -93,12 +93,110 @@ function resolveMaxSenderKeyAge(configured, logger) {
93
93
  }
94
94
  return configured;
95
95
  }
96
+ /**
97
+ * Classify a sender key against the age bound. Only a locally created key
98
+ * expires: a received key has no private signature key, and it stays usable
99
+ * for delayed messages.
100
+ *
101
+ * A locally created key always records when it was created, at creation and
102
+ * again at every rotation. One that does not is damaged or predates the
103
+ * field, so its age cannot be established. Establishing the age is the single
104
+ * thing this bound exists for. Skipping the check would exempt the only keys
105
+ * whose life is genuinely unbounded. Such a key counts as expired instead.
106
+ * The caller answers that by rotating, which costs a redistribution and
107
+ * restores a key whose age is known.
108
+ *
109
+ * @returns Null when the key is within the bound.
110
+ */
111
+ function ownSenderKeyExpiry(state, maxSenderKeyAge) {
112
+ if (!state.signatureKey)
113
+ return null;
114
+ if (!Number.isFinite(state.createdAt) || state.createdAt <= 0) {
115
+ return { kind: 'no-creation-time' };
116
+ }
117
+ const ageMs = Date.now() - state.createdAt;
118
+ return ageMs > maxSenderKeyAge ? { kind: 'aged', ageMs } : null;
119
+ }
96
120
  /** Reject sender-key state or a distribution in an unsupported format. */
97
121
  export function assertSenderKeyVersion(state) {
98
122
  if (state.senderKeyVersion !== SENDER_KEY_FORMAT) {
99
123
  throw new Error('Unsupported sender-key format. Reset group sender-key state and redistribute keys.');
100
124
  }
101
125
  }
126
+ /**
127
+ * A sender key state with only the fields of `SenderKeyState`. A state that
128
+ * an earlier SDK version wrote can carry a retired field. The manager keeps
129
+ * only the current fields of each state that it loads, so no code path reads
130
+ * a retired field and the next write of the state omits it. The mapped type
131
+ * makes the compiler require each field of `SenderKeyState` here.
132
+ */
133
+ function withoutRetiredFields(state) {
134
+ const current = {
135
+ senderKeyId: state.senderKeyId,
136
+ senderKeyVersion: state.senderKeyVersion,
137
+ chainId: state.chainId,
138
+ generation: state.generation,
139
+ chainKey: state.chainKey,
140
+ signatureKey: state.signatureKey,
141
+ publicSignatureKey: state.publicSignatureKey,
142
+ chainIndex: state.chainIndex,
143
+ createdAt: state.createdAt,
144
+ };
145
+ return current;
146
+ }
147
+ /** The distribution of a sender key state at its current chain index. */
148
+ function currentDistribution(state) {
149
+ assertSenderKeyVersion(state);
150
+ return {
151
+ senderKeyVersion: SENDER_KEY_FORMAT,
152
+ senderKeyId: state.senderKeyId,
153
+ chainId: state.chainId,
154
+ generation: state.generation,
155
+ chainIndex: state.chainIndex,
156
+ chainKey: state.chainKey,
157
+ publicSignatureKey: state.publicSignatureKey,
158
+ };
159
+ }
160
+ /**
161
+ * Resolve the group a framed SenderKeyMessage belongs to.
162
+ *
163
+ * A group envelope names no group. It carries the sender's identity and an
164
+ * opaque distribution identifier inside the frame. The receiver maps that
165
+ * identifier back to a group through its own sender key store. The store is
166
+ * the only thing that knows the association, which is why the relay cannot
167
+ * learn it.
168
+ *
169
+ * Parsing here reads unauthenticated bytes: the signature is not checked
170
+ * until `decryptGroupMessage`. That is safe because the only thing taken
171
+ * from them is an identifier used as a lookup key. A forged identifier
172
+ * either matches no record, or matches one. Matching one is not an
173
+ * escalation. The caller's own state already binds that identifier to a
174
+ * public signature key, and the subsequent verification rejects the forgery
175
+ * against it.
176
+ *
177
+ * @param store - The sender key store of the receiving device
178
+ * @param framedMessage - Framed SenderKeyMessage bytes from the envelope
179
+ * @param senderId - Sender user identifier, from the envelope
180
+ * @param senderDeviceId - Sender device identifier, from the envelope
181
+ * @returns The group identifier, or null if no sender key matches
182
+ */
183
+ export async function resolveGroupForFramedMessage(store, framedMessage, senderId, senderDeviceId) {
184
+ let senderKeyId;
185
+ try {
186
+ const { protobufBytes } = parseSenderKeyMessage(framedMessage);
187
+ const decoded = decodeSenderKeyMessage(protobufBytes);
188
+ if (!decoded.distributionUuid)
189
+ return null;
190
+ senderKeyId = utf8Decode(decoded.distributionUuid);
191
+ }
192
+ catch {
193
+ // Not a well-formed frame, so it names no distribution and no group.
194
+ return null;
195
+ }
196
+ if (!senderKeyId)
197
+ return null;
198
+ return store.resolveGroupForSenderKeyId(senderKeyId, senderId, senderDeviceId);
199
+ }
102
200
  export class SenderKeyManager {
103
201
  storage;
104
202
  /** Resolved configuration values */
@@ -106,21 +204,6 @@ export class SenderKeyManager {
106
204
  maxChainAdvance;
107
205
  maxSkippedKeys;
108
206
  maxSenderKeyAge;
109
- /**
110
- * In-memory cache of previous sender key states for rotation transitions.
111
- *
112
- * Keep up to MAX_SENDER_KEY_STATES per sender to decrypt in-flight
113
- * messages encrypted with a previous key during the rotation window.
114
- *
115
- * This cache is backed by persistent storage via storeSenderKeyRecord/
116
- * getSenderKeyRecord (when available). On cache miss, previous states
117
- * are loaded from storage.
118
- *
119
- * Key format: JSON tuple [groupId, userId, deviceId].
120
- * Value: Array of previous states (most recent first), capped at MAX_SENDER_KEY_STATES - 1
121
- * (the current state is in storage, previous states are here)
122
- */
123
- previousStates = new Map();
124
207
  logger;
125
208
  constructor(storage, config, logger = defaultSignalProtocolLogger) {
126
209
  this.storage = storage;
@@ -131,10 +214,6 @@ export class SenderKeyManager {
131
214
  this.maxSkippedKeys = config?.maxSkippedKeys ?? SENDER_KEYS_DEFAULTS.maxSkippedKeys;
132
215
  this.maxSenderKeyAge = resolveMaxSenderKeyAge(config?.maxSenderKeyAge, this.logger);
133
216
  }
134
- /** Encode each cache address component separately, including delimiters in names. */
135
- stateKey(groupId, userId, deviceId) {
136
- return JSON.stringify([groupId, userId, deviceId]);
137
- }
138
217
  /**
139
218
  * Convert decrypted bytes into a lossless string representation.
140
219
  *
@@ -169,37 +248,24 @@ export class SenderKeyManager {
169
248
  * Per Sender Keys spec Section 5.1 - "Implementations MUST store sender key
170
249
  * state persistently." This persists the full record atomically.
171
250
  */
172
- async persistSenderKeyRecord(groupId, userId, deviceId, currentState, previousStatesList) {
251
+ async persistSenderKeyRecord(groupId, userId, deviceId, currentState, previousStatesList, options) {
173
252
  const allStates = [currentState, ...previousStatesList];
174
- await this.storage.storeSenderKeyRecord(groupId, userId, deviceId, allStates);
253
+ await this.storage.storeSenderKeyRecord(groupId, userId, deviceId, allStates, undefined, options);
175
254
  }
176
255
  /**
177
- * Load previous states from storage, populating the in-memory cache.
178
- *
179
- * Called on cache miss when trying to decrypt with previous states.
180
- * Uses getSenderKeyRecord if available, otherwise returns empty array.
256
+ * Load the previous states of a sender from the stored record, most recent
257
+ * first. The manager keeps no copy: each call reads the store, so a
258
+ * rotation or a receive that another tab or manager wrote is kept.
181
259
  */
182
260
  async loadPreviousStates(groupId, userId, deviceId) {
183
- const key = this.stateKey(groupId, userId, deviceId);
184
- // Check cache first
185
- const cached = this.previousStates.get(key);
186
- if (cached !== undefined) {
187
- return cached;
188
- }
189
- // Load from persistent storage
190
- const record = await this.storage.getSenderKeyRecord(groupId, userId, deviceId);
261
+ const record = await this.loadSenderKeyRecord(groupId, userId, deviceId);
191
262
  if (record && record.length > 1) {
192
263
  // First element is current state (already in storage via getSenderKey),
193
264
  // remaining elements are previous states.
194
265
  // Cap at MAX_SENDER_KEY_STATES - 1 defensively (storage may have stale extras).
195
- const prev = record.slice(1, MAX_SENDER_KEY_STATES);
196
- this.previousStates.set(key, prev);
197
- return prev;
198
- }
199
- // No previous states available
200
- const empty = [];
201
- this.previousStates.set(key, empty);
202
- return empty;
266
+ return record.slice(1, MAX_SENDER_KEY_STATES);
267
+ }
268
+ return [];
203
269
  }
204
270
  /**
205
271
  * Create new sender key for group
@@ -229,9 +295,12 @@ export class SenderKeyManager {
229
295
  chainIndex: 0,
230
296
  createdAt: now,
231
297
  };
232
- // Store sender key (with empty previous states for a new key)
233
- await this.persistSenderKeyRecord(groupId, userId, deviceId, state, []);
234
- this.previousStates.set(this.stateKey(groupId, userId, deviceId), []);
298
+ // Store sender key (with empty previous states for a new key). The new
299
+ // senderKeyId replaces the old key, so the same write deletes the
300
+ // handoff rows of the group.
301
+ await this.persistSenderKeyRecord(groupId, userId, deviceId, state, [], {
302
+ deleteSenderKeyHandoffs: true,
303
+ });
235
304
  // Create distribution message (to send to other members)
236
305
  const distributionMessage = {
237
306
  senderKeyVersion: SENDER_KEY_FORMAT,
@@ -252,10 +321,22 @@ export class SenderKeyManager {
252
321
  * Process received sender key distribution message
253
322
  * Store sender key for another member
254
323
  *
255
- * Validates against existing state per spec Section 3.4 -
256
- * - Rejects if generation < existing (stale distribution)
257
- * - Rejects if generation == existing AND chainIndex <= existing (replay)
258
- * - Accepts if generation > existing (key rotation)
324
+ * The receiver matches a key by its identity, the senderKeyId, as
325
+ * Signal's published implementation matches a state by its chain ID and
326
+ * signing key. A sender that creates a key again starts at generation 1
327
+ * with a new senderKeyId, so the generation does not order two different
328
+ * keys.
329
+ * - The same key as the current state: the generation rules of spec
330
+ * Section 3.4 apply. A lower generation changes nothing. The same
331
+ * generation changes nothing at any chainIndex, because the existing
332
+ * state can be ahead through decryption. A higher generation replaces
333
+ * the current state in place, and the previous states do not change.
334
+ * - The key of a previous state: a late copy changes nothing, and the
335
+ * state stays in its place.
336
+ * - Another key: it becomes the current state, and the existing state
337
+ * moves to the front of the previous states, so a message in flight
338
+ * under it still decrypts. When the record already holds
339
+ * MAX_SENDER_KEY_STATES states, the oldest state goes.
259
340
  *
260
341
  * @param groupId - Group identifier
261
342
  * @param senderId - Sender user identifier
@@ -265,8 +346,20 @@ export class SenderKeyManager {
265
346
  async processSenderKeyDistribution(groupId, senderId, senderDeviceId, message) {
266
347
  assertSenderKeyVersion(message);
267
348
  // Validate against existing state (Specification Section 3.4)
268
- const existing = await this.storage.getSenderKey(groupId, senderId, senderDeviceId);
269
- if (existing !== null) {
349
+ const existing = await this.loadSenderKey(groupId, senderId, senderDeviceId);
350
+ const sameKey = existing !== null && existing.senderKeyId === message.senderKeyId;
351
+ const previous = existing !== null ? await this.loadPreviousStates(groupId, senderId, senderDeviceId) : [];
352
+ if (existing !== null && !sameKey) {
353
+ assertSenderKeyVersion(existing);
354
+ if (previous.some((state) => state.senderKeyId === message.senderKeyId)) {
355
+ this.logger.debug('Rejected late distribution of a previous sender key', {
356
+ category: 'E2EE',
357
+ data: { senderKeyId: message.senderKeyId },
358
+ });
359
+ return;
360
+ }
361
+ }
362
+ else if (existing !== null) {
270
363
  assertSenderKeyVersion(existing);
271
364
  // Reject if generation is lower (stale distribution)
272
365
  if (message.generation < existing.generation) {
@@ -323,18 +416,32 @@ export class SenderKeyManager {
323
416
  chainIndex: message.chainIndex ?? 0,
324
417
  createdAt: Date.now(), // Received keys track when we got them (not checked for expiration)
325
418
  };
326
- // Build the candidate archive without changing the committed cache.
327
- const key = this.stateKey(groupId, senderId, senderDeviceId);
328
- const prev = existing !== null
329
- ? [existing, ...(await this.loadPreviousStates(groupId, senderId, senderDeviceId))].slice(0, MAX_SENDER_KEY_STATES - 1)
330
- : [];
419
+ // Build the archive from the stored record. A later generation of the
420
+ // same key replaces the current state in place, so the record never
421
+ // holds two states with one senderKeyId.
422
+ const prev = existing === null
423
+ ? []
424
+ : sameKey
425
+ ? previous
426
+ : [existing, ...previous].slice(0, MAX_SENDER_KEY_STATES - 1);
331
427
  await this.persistSenderKeyRecord(groupId, senderId, senderDeviceId, state, prev);
332
- this.previousStates.set(key, prev);
333
428
  this.logger.debug('Stored sender key', {
334
429
  category: 'E2EE',
335
430
  data: { senderKeyId: message.senderKeyId, senderId, senderDeviceId },
336
431
  });
337
432
  }
433
+ /**
434
+ * Report whether the local sender key of a group is past the age bound,
435
+ * by the same rule that makes {@link encryptGroupMessage} refuse it with
436
+ * `SENDER_KEY_EXPIRED`. A send reads it before it distributes a pending
437
+ * key, so it rotates instead of distributing a key that it cannot use.
438
+ *
439
+ * @returns False when there is no sender key for the group.
440
+ */
441
+ async isOwnSenderKeyExpired(groupId, userId, deviceId) {
442
+ const state = await this.loadSenderKey(groupId, userId, deviceId);
443
+ return state !== null && ownSenderKeyExpiry(state, this.maxSenderKeyAge) !== null;
444
+ }
338
445
  /**
339
446
  * Encrypt message for group using sender key
340
447
  * Returns ciphertext + signature (O(1) encryption)
@@ -347,38 +454,27 @@ export class SenderKeyManager {
347
454
  */
348
455
  async encryptGroupMessage(groupId, userId, deviceId, plaintextBytes) {
349
456
  // Get sender key state
350
- const state = await this.storage.getSenderKey(groupId, userId, deviceId);
457
+ const state = await this.loadSenderKey(groupId, userId, deviceId);
351
458
  if (!state) {
352
459
  throw new Error('SENDER_KEY_NOT_FOUND: No sender key for this group');
353
460
  }
354
461
  assertSenderKeyVersion(state);
355
- // Received keys have no private signature key, so time-based expiration
356
- // applies only to locally created encryption keys.
357
- if (state.signatureKey) {
358
- // A locally created key always records when it was created, at creation
359
- // and again at every rotation. One that does not is damaged or predates
360
- // the field, so its age cannot be established. Establishing the age is
361
- // the single thing this bound exists for. Skipping the check would
362
- // exempt the only keys whose life is genuinely unbounded. Treat such a
363
- // key as expired instead. The caller answers that by rotating, which
364
- // costs a redistribution and restores a key whose age is known.
365
- if (!Number.isFinite(state.createdAt) || state.createdAt <= 0) {
366
- throw new EncryptionError('Sender key has no usable creation time, so its age cannot be checked. Auto-rotation required.', EncryptionErrorCode.SENDER_KEY_EXPIRED, {
367
- senderKeyId: state.senderKeyId,
368
- groupId,
369
- createdAt: state.createdAt,
370
- maxAgeMs: this.maxSenderKeyAge,
371
- });
372
- }
373
- const age = Date.now() - state.createdAt;
374
- if (age > this.maxSenderKeyAge) {
375
- throw new EncryptionError(`Sender key expired after ${Math.floor(age / (24 * 60 * 60 * 1000))} days (max: ${Math.floor(this.maxSenderKeyAge / (24 * 60 * 60 * 1000))} days). Auto-rotation required.`, EncryptionErrorCode.SENDER_KEY_EXPIRED, {
376
- senderKeyId: state.senderKeyId,
377
- groupId,
378
- ageMs: age,
379
- maxAgeMs: this.maxSenderKeyAge,
380
- });
381
- }
462
+ const expiry = ownSenderKeyExpiry(state, this.maxSenderKeyAge);
463
+ if (expiry?.kind === 'no-creation-time') {
464
+ throw new EncryptionError('Sender key has no usable creation time, so its age cannot be checked. Auto-rotation required.', EncryptionErrorCode.SENDER_KEY_EXPIRED, {
465
+ senderKeyId: state.senderKeyId,
466
+ groupId,
467
+ createdAt: state.createdAt,
468
+ maxAgeMs: this.maxSenderKeyAge,
469
+ });
470
+ }
471
+ if (expiry?.kind === 'aged') {
472
+ throw new EncryptionError(`Sender key expired after ${Math.floor(expiry.ageMs / (24 * 60 * 60 * 1000))} days (max: ${Math.floor(this.maxSenderKeyAge / (24 * 60 * 60 * 1000))} days). Auto-rotation required.`, EncryptionErrorCode.SENDER_KEY_EXPIRED, {
473
+ senderKeyId: state.senderKeyId,
474
+ groupId,
475
+ ageMs: expiry.ageMs,
476
+ maxAgeMs: this.maxSenderKeyAge,
477
+ });
382
478
  }
383
479
  // L6: Check for chain index overflow before encrypting
384
480
  // Sender keys use uint32 in protobuf, so max is 2^32-1 (0xffffffff).
@@ -445,21 +541,8 @@ export class SenderKeyManager {
445
541
  * @returns Decrypted plaintext
446
542
  */
447
543
  /**
448
- * Resolve the group a framed SenderKeyMessage belongs to.
449
- *
450
- * A group envelope names no group. It carries the sender's identity and an
451
- * opaque distribution identifier inside the frame. The receiver maps that
452
- * identifier back to a group through its own sender key store. The store is
453
- * the only thing that knows the association, which is why the relay cannot
454
- * learn it.
455
- *
456
- * Parsing here reads unauthenticated bytes: the signature is not checked
457
- * until `decryptGroupMessage`. That is safe because the only thing taken
458
- * from them is an identifier used as a lookup key. A forged identifier
459
- * either matches no record, or matches one. Matching one is not an
460
- * escalation. The caller's own state already binds that identifier to a
461
- * public signature key, and the subsequent verification rejects the forgery
462
- * against it.
544
+ * Resolve the group a framed SenderKeyMessage belongs to, from the store
545
+ * of this manager, as `resolveGroupForFramedMessage` tells.
463
546
  *
464
547
  * @param framedMessage - Framed SenderKeyMessage bytes from the envelope
465
548
  * @param senderId - Sender user identifier, from the envelope
@@ -467,23 +550,9 @@ export class SenderKeyManager {
467
550
  * @returns The group identifier, or null if no sender key matches
468
551
  */
469
552
  async resolveGroupForFramedMessage(framedMessage, senderId, senderDeviceId) {
470
- let senderKeyId;
471
- try {
472
- const { protobufBytes } = parseSenderKeyMessage(framedMessage);
473
- const decoded = decodeSenderKeyMessage(protobufBytes);
474
- if (!decoded.distributionUuid)
475
- return null;
476
- senderKeyId = utf8Decode(decoded.distributionUuid);
477
- }
478
- catch {
479
- // Not a well-formed frame, so it names no distribution and no group.
480
- return null;
481
- }
482
- if (!senderKeyId)
483
- return null;
484
- return this.storage.resolveGroupForSenderKeyId(senderKeyId, senderId, senderDeviceId);
553
+ return resolveGroupForFramedMessage(this.storage, framedMessage, senderId, senderDeviceId);
485
554
  }
486
- async decryptGroupMessage(groupId, senderId, senderDeviceId, framedMessage, receiveId) {
555
+ async decryptGroupMessage(groupId, senderId, senderDeviceId, framedMessage, receiveWork) {
487
556
  // Parse framed SenderKeyMessage: [version_byte(1)] [protobuf(N)] [signature(64)]
488
557
  const { protobufBytes, signature } = parseSenderKeyMessage(framedMessage);
489
558
  const decoded = decodeSenderKeyMessage(protobufBytes);
@@ -498,7 +567,7 @@ export class SenderKeyManager {
498
567
  signature: crypto.bytesToBase64(signature),
499
568
  };
500
569
  // Get sender's key
501
- const state = await this.storage.getSenderKey(groupId, senderId, senderDeviceId);
570
+ const state = await this.loadSenderKey(groupId, senderId, senderDeviceId);
502
571
  if (!state) {
503
572
  throw new Error(`SENDER_KEY_NOT_FOUND: No sender key for ${senderId}.${senderDeviceId}`);
504
573
  }
@@ -506,7 +575,7 @@ export class SenderKeyManager {
506
575
  // M11: If current state does not match, try previous states (rotation window)
507
576
  // This allows decryption of in-flight messages encrypted with a previous key.
508
577
  if (state.senderKeyId !== message.senderKeyId) {
509
- const prevResult = await this.tryDecryptWithPreviousState(groupId, senderId, senderDeviceId, message, receiveId);
578
+ const prevResult = await this.tryDecryptWithPreviousState(groupId, senderId, senderDeviceId, message, receiveWork);
510
579
  if (prevResult !== null) {
511
580
  return prevResult;
512
581
  }
@@ -557,7 +626,7 @@ export class SenderKeyManager {
557
626
  }
558
627
  else if (message.chainIndex < state.chainIndex) {
559
628
  // Old message - try skipped keys (Spec Section 4.1)
560
- return await this.decryptWithSkippedKey(groupId, senderId, senderDeviceId, message, receiveId);
629
+ return await this.decryptWithSkippedKey(groupId, senderId, senderDeviceId, message, receiveWork);
561
630
  }
562
631
  // Derive message key from chain key (Signal Protocol KDF_CK pattern)
563
632
  // Two-step derivation:
@@ -582,9 +651,7 @@ export class SenderKeyManager {
582
651
  const previous = await this.loadPreviousStates(groupId, senderId, senderDeviceId);
583
652
  await this.storage.storeSenderKeyRecord(groupId, senderId, senderDeviceId, [state, ...previous], {
584
653
  skippedKeys,
585
- content: receiveId
586
- ? { id: receiveId, plaintext, receivedAt: Date.now(), groupId }
587
- : undefined,
654
+ work: receiveWork?.({ plaintext, groupId }),
588
655
  });
589
656
  this.logger.debug('Decrypted message with sender key', {
590
657
  category: 'E2EE',
@@ -602,7 +669,7 @@ export class SenderKeyManager {
602
669
  * @returns Decrypted plaintext
603
670
  * @throws Error if skipped key not found or decryption fails
604
671
  */
605
- async decryptWithSkippedKey(groupId, senderId, senderDeviceId, message, receiveId) {
672
+ async decryptWithSkippedKey(groupId, senderId, senderDeviceId, message, receiveWork) {
606
673
  const skippedKey = await this.storage.getSkippedSenderKey(groupId, senderId, senderDeviceId, message.senderKeyId, message.chainIndex);
607
674
  if (!skippedKey) {
608
675
  // If chainIndex < state.chainIndex
@@ -621,13 +688,11 @@ export class SenderKeyManager {
621
688
  crypto.secureZeroBytes(skippedIv);
622
689
  }
623
690
  const plaintext = this.encodeLosslessPlaintext(plaintextBytes);
624
- const states = await this.storage.getSenderKeyRecord(groupId, senderId, senderDeviceId);
691
+ const states = await this.loadSenderKeyRecord(groupId, senderId, senderDeviceId);
625
692
  if (!states?.length)
626
693
  throw new Error('Missing sender-key record during receive');
627
694
  await this.storage.storeSenderKeyRecord(groupId, senderId, senderDeviceId, states, {
628
- content: receiveId
629
- ? { id: receiveId, plaintext, receivedAt: Date.now(), groupId }
630
- : undefined,
695
+ work: receiveWork?.({ plaintext, groupId }),
631
696
  consumedSkippedKey: {
632
697
  senderKeyId: message.senderKeyId,
633
698
  chainIndex: message.chainIndex,
@@ -657,8 +722,8 @@ export class SenderKeyManager {
657
722
  * @param message - Encrypted message to try decrypting
658
723
  * @returns Decrypted plaintext, or null if no matching state found
659
724
  */
660
- async tryDecryptWithPreviousState(groupId, senderId, senderDeviceId, message, receiveId) {
661
- // Load previous states from storage (populates cache on miss)
725
+ async tryDecryptWithPreviousState(groupId, senderId, senderDeviceId, message, receiveWork) {
726
+ // Load previous states from the stored record
662
727
  const prevStates = (await this.loadPreviousStates(groupId, senderId, senderDeviceId)).map((state) => ({ ...state }));
663
728
  if (prevStates.length === 0) {
664
729
  return null;
@@ -711,7 +776,7 @@ export class SenderKeyManager {
711
776
  }
712
777
  else if (message.chainIndex < prevState.chainIndex) {
713
778
  // Old message in previous state - try skipped keys
714
- return await this.decryptWithSkippedKey(groupId, senderId, senderDeviceId, message, receiveId);
779
+ return await this.decryptWithSkippedKey(groupId, senderId, senderDeviceId, message, receiveWork);
715
780
  }
716
781
  // Derive message key and decrypt (AES-256-CBC, authenticity from Ed25519 signature)
717
782
  const { cipherKey, iv } = await this.deriveMessageKey(prevState.chainKey);
@@ -728,17 +793,13 @@ export class SenderKeyManager {
728
793
  prevState.chainKey = this.advanceChainKey(prevState.chainKey);
729
794
  prevState.chainIndex++;
730
795
  // Persist updated previous states to storage
731
- const currentState = await this.storage.getSenderKey(groupId, senderId, senderDeviceId);
796
+ const currentState = await this.loadSenderKey(groupId, senderId, senderDeviceId);
732
797
  if (!currentState)
733
798
  throw new Error('Missing sender-key record during receive');
734
- const key = this.stateKey(groupId, senderId, senderDeviceId);
735
799
  await this.storage.storeSenderKeyRecord(groupId, senderId, senderDeviceId, [currentState, ...prevStates], {
736
800
  skippedKeys,
737
- content: receiveId
738
- ? { id: receiveId, plaintext, receivedAt: Date.now(), groupId }
739
- : undefined,
801
+ work: receiveWork?.({ plaintext, groupId }),
740
802
  });
741
- this.previousStates.set(key, prevStates);
742
803
  this.logger.debug('Decrypted message with previous sender key state', {
743
804
  category: 'E2EE',
744
805
  data: {
@@ -759,9 +820,9 @@ export class SenderKeyManager {
759
820
  * @param deviceId - Device identifier
760
821
  * @returns New sender key ID and distribution message
761
822
  */
762
- async rotateSenderKey(groupId, userId, deviceId, options) {
823
+ async rotateSenderKey(groupId, userId, deviceId) {
763
824
  // Get old sender key state
764
- const oldState = await this.storage.getSenderKey(groupId, userId, deviceId);
825
+ const oldState = await this.loadSenderKey(groupId, userId, deviceId);
765
826
  if (oldState)
766
827
  assertSenderKeyVersion(oldState);
767
828
  const senderKeyId = await crypto.generateUuidV4();
@@ -780,15 +841,16 @@ export class SenderKeyManager {
780
841
  publicSignatureKey: signatureKeyPair.publicKey, // Already Base64-encoded PublicKey
781
842
  chainIndex: 0,
782
843
  createdAt: Date.now(),
783
- ...(options?.distributionPending && { distributionPending: true }),
784
844
  };
785
- // Build the candidate archive without changing the committed cache.
786
- const key = this.stateKey(groupId, userId, deviceId);
845
+ // Build the archive from the stored record.
787
846
  const prev = oldState
788
847
  ? [oldState, ...(await this.loadPreviousStates(groupId, userId, deviceId))].slice(0, MAX_SENDER_KEY_STATES - 1)
789
848
  : [];
790
- await this.persistSenderKeyRecord(groupId, userId, deviceId, newState, prev);
791
- this.previousStates.set(key, prev);
849
+ // The same write deletes the handoff rows of the group, so the next send
850
+ // gives the new key to every listed device.
851
+ await this.persistSenderKeyRecord(groupId, userId, deviceId, newState, prev, {
852
+ deleteSenderKeyHandoffs: true,
853
+ });
792
854
  // Create distribution message
793
855
  const distributionMessage = {
794
856
  senderKeyVersion: SENDER_KEY_FORMAT,
@@ -806,48 +868,29 @@ export class SenderKeyManager {
806
868
  return { senderKeyId, distributionMessage };
807
869
  }
808
870
  /**
809
- * Reconstruct the current distribution after an interrupted automatic
810
- * rotation. The current chain index and key let a receiver begin at the
811
- * first ciphertext that can still be sent.
871
+ * The distribution of the current sender key at its current chain index,
872
+ * or null when the device has no sender key for the group. A receiver that
873
+ * installs it decrypts the later group messages of the sender, but no
874
+ * earlier one.
812
875
  */
813
- async getPendingSenderKeyDistribution(groupId, userId, deviceId) {
814
- const state = await this.storage.getSenderKey(groupId, userId, deviceId);
815
- if (!state?.distributionPending)
816
- return null;
817
- assertSenderKeyVersion(state);
818
- return {
819
- senderKeyVersion: SENDER_KEY_FORMAT,
820
- senderKeyId: state.senderKeyId,
821
- chainId: state.chainId,
822
- generation: state.generation,
823
- chainIndex: state.chainIndex,
824
- chainKey: state.chainKey,
825
- publicSignatureKey: state.publicSignatureKey,
826
- };
827
- }
828
- /**
829
- * Clear a pending automatic distribution only for the generation whose
830
- * prepared messages have reached the Relay. A later rotation wins.
831
- */
832
- async confirmSenderKeyDistributionSent(groupId, userId, deviceId, senderKeyId) {
833
- const state = await this.storage.getSenderKey(groupId, userId, deviceId);
834
- if (!state?.distributionPending || state.senderKeyId !== senderKeyId)
835
- return;
836
- delete state.distributionPending;
837
- await this.storage.storeSenderKey(groupId, userId, deviceId, state);
876
+ async getCurrentSenderKeyDistribution(groupId, userId, deviceId) {
877
+ const state = await this.loadSenderKey(groupId, userId, deviceId);
878
+ return state ? currentDistribution(state) : null;
838
879
  }
839
880
  /**
840
881
  * Delete sender key (when leaving group or revoking device)
841
882
  *
883
+ * The delete of an own sender key, which holds a private signature key,
884
+ * also deletes the handoff rows of the group in the same write. The delete
885
+ * of a received key keeps them.
886
+ *
842
887
  * @param groupId - Group identifier
843
888
  * @param userId - User identifier
844
889
  * @param deviceId - Device identifier
845
890
  */
846
891
  async deleteSenderKey(groupId, userId, deviceId) {
847
- await this.storage.deleteSenderKey(groupId, userId, deviceId);
848
- // M11: Also clear previous states
849
- const key = this.stateKey(groupId, userId, deviceId);
850
- this.previousStates.delete(key);
892
+ const state = await this.loadSenderKey(groupId, userId, deviceId);
893
+ await this.storage.deleteSenderKey(groupId, userId, deviceId, state?.signatureKey ? { deleteSenderKeyHandoffs: true } : undefined);
851
894
  this.logger.debug('Deleted sender key', {
852
895
  category: 'E2EE',
853
896
  data: { userId, deviceId, groupId },
@@ -864,7 +907,7 @@ export class SenderKeyManager {
864
907
  * @returns Stats including chain position, generation, and skipped keys count
865
908
  */
866
909
  async getStats(groupId, senderId, senderDeviceId) {
867
- const state = await this.storage.getSenderKey(groupId, senderId, senderDeviceId);
910
+ const state = await this.loadSenderKey(groupId, senderId, senderDeviceId);
868
911
  if (!state) {
869
912
  return { chainIndex: 0, generation: 0, skippedKeysCount: 0 };
870
913
  }
@@ -878,6 +921,16 @@ export class SenderKeyManager {
878
921
  // ==========================================================================
879
922
  // Private Helper Methods
880
923
  // ==========================================================================
924
+ /** Load the current sender key state, with no retired fields. */
925
+ async loadSenderKey(groupId, userId, deviceId) {
926
+ const state = await this.storage.getSenderKey(groupId, userId, deviceId);
927
+ return state ? withoutRetiredFields(state) : null;
928
+ }
929
+ /** Load every stored sender key state, with no retired fields. */
930
+ async loadSenderKeyRecord(groupId, userId, deviceId) {
931
+ const record = await this.storage.getSenderKeyRecord(groupId, userId, deviceId);
932
+ return record ? record.map(withoutRetiredFields) : null;
933
+ }
881
934
  /**
882
935
  * Derive a message key from the Sender Keys chain key.
883
936
  *