@open-e2ee/signal-protocol-sdk 10.1.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 (595) hide show
  1. package/ADAPTERS.md +4 -4
  2. package/ARCHITECTURE.md +6 -8
  3. package/CHANGELOG.md +1413 -0
  4. package/README.md +1 -1
  5. package/SECURITY.md +2 -2
  6. package/TROUBLESHOOTING.md +1 -1
  7. package/client/README.md +84 -37
  8. package/device/README.md +39 -85
  9. package/dist/client/client.d.ts +342 -62
  10. package/dist/client/client.d.ts.map +1 -1
  11. package/dist/client/client.js +1195 -179
  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 +308 -6
  42. package/dist/client/event-hooks.d.ts.map +1 -1
  43. package/dist/client/event-hooks.js +9 -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-device-standing.d.ts +52 -0
  82. package/dist/client/hosted-device-standing.d.ts.map +1 -0
  83. package/dist/client/hosted-device-standing.js +74 -0
  84. package/dist/client/hosted-device-standing.js.map +1 -0
  85. package/dist/client/hosted-mailbox-subscription.d.ts +48 -3
  86. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  87. package/dist/client/hosted-mailbox-subscription.js +288 -74
  88. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  89. package/dist/client/hosted-push.d.ts +22 -4
  90. package/dist/client/hosted-push.d.ts.map +1 -1
  91. package/dist/client/hosted-push.js +75 -22
  92. package/dist/client/hosted-push.js.map +1 -1
  93. package/dist/client/hosted-transport.d.ts +22 -28
  94. package/dist/client/hosted-transport.d.ts.map +1 -1
  95. package/dist/client/hosted-transport.js +167 -69
  96. package/dist/client/hosted-transport.js.map +1 -1
  97. package/dist/client/hosted.d.ts +22 -5
  98. package/dist/client/hosted.d.ts.map +1 -1
  99. package/dist/client/hosted.js +122 -45
  100. package/dist/client/hosted.js.map +1 -1
  101. package/dist/client/index.d.ts +6 -4
  102. package/dist/client/index.d.ts.map +1 -1
  103. package/dist/client/index.js +3 -1
  104. package/dist/client/index.js.map +1 -1
  105. package/dist/client/messages.d.ts +25 -3
  106. package/dist/client/messages.d.ts.map +1 -1
  107. package/dist/client/messages.js +118 -17
  108. package/dist/client/messages.js.map +1 -1
  109. package/dist/client/one-time-prekey-refill.d.ts +7 -0
  110. package/dist/client/one-time-prekey-refill.d.ts.map +1 -1
  111. package/dist/client/one-time-prekey-refill.js +5 -1
  112. package/dist/client/one-time-prekey-refill.js.map +1 -1
  113. package/dist/client/receive-admission.d.ts +58 -0
  114. package/dist/client/receive-admission.d.ts.map +1 -0
  115. package/dist/client/receive-admission.js +78 -0
  116. package/dist/client/receive-admission.js.map +1 -0
  117. package/dist/client/receive-expiry.d.ts +31 -0
  118. package/dist/client/receive-expiry.d.ts.map +1 -0
  119. package/dist/client/receive-expiry.js +35 -0
  120. package/dist/client/receive-expiry.js.map +1 -0
  121. package/dist/client/receive-hook-bound.d.ts +50 -0
  122. package/dist/client/receive-hook-bound.d.ts.map +1 -0
  123. package/dist/client/receive-hook-bound.js +115 -0
  124. package/dist/client/receive-hook-bound.js.map +1 -0
  125. package/dist/client/receive-queue.d.ts +299 -0
  126. package/dist/client/receive-queue.d.ts.map +1 -0
  127. package/dist/client/receive-queue.js +1420 -0
  128. package/dist/client/receive-queue.js.map +1 -0
  129. package/dist/client/receive-work-seed.d.ts +54 -0
  130. package/dist/client/receive-work-seed.d.ts.map +1 -0
  131. package/dist/client/receive-work-seed.js +116 -0
  132. package/dist/client/receive-work-seed.js.map +1 -0
  133. package/dist/client/recovery-driver.d.ts +25 -0
  134. package/dist/client/recovery-driver.d.ts.map +1 -0
  135. package/dist/client/recovery-driver.js +121 -0
  136. package/dist/client/recovery-driver.js.map +1 -0
  137. package/dist/client/relay-acceptance.d.ts +30 -0
  138. package/dist/client/relay-acceptance.d.ts.map +1 -1
  139. package/dist/client/relay-acceptance.js +55 -0
  140. package/dist/client/relay-acceptance.js.map +1 -1
  141. package/dist/client/relay-device-refusal.d.ts +18 -0
  142. package/dist/client/relay-device-refusal.d.ts.map +1 -1
  143. package/dist/client/relay-device-refusal.js +31 -0
  144. package/dist/client/relay-device-refusal.js.map +1 -1
  145. package/dist/client/relay-sealed-route.d.ts +36 -0
  146. package/dist/client/relay-sealed-route.d.ts.map +1 -0
  147. package/dist/client/relay-sealed-route.js +45 -0
  148. package/dist/client/relay-sealed-route.js.map +1 -0
  149. package/dist/client/relay-subscription.d.ts +56 -13
  150. package/dist/client/relay-subscription.d.ts.map +1 -1
  151. package/dist/client/relay-subscription.js +220 -150
  152. package/dist/client/relay-subscription.js.map +1 -1
  153. package/dist/client/resendable-content.d.ts +98 -0
  154. package/dist/client/resendable-content.d.ts.map +1 -0
  155. package/dist/client/resendable-content.js +136 -0
  156. package/dist/client/resendable-content.js.map +1 -0
  157. package/dist/client/retry-family.d.ts +68 -19
  158. package/dist/client/retry-family.d.ts.map +1 -1
  159. package/dist/client/retry-family.js +59 -17
  160. package/dist/client/retry-family.js.map +1 -1
  161. package/dist/client/retry-request-envelope.d.ts +145 -18
  162. package/dist/client/retry-request-envelope.d.ts.map +1 -1
  163. package/dist/client/retry-request-envelope.js +301 -64
  164. package/dist/client/retry-request-envelope.js.map +1 -1
  165. package/dist/client/retry-request-lifecycle.d.ts +157 -0
  166. package/dist/client/retry-request-lifecycle.d.ts.map +1 -0
  167. package/dist/client/retry-request-lifecycle.js +437 -0
  168. package/dist/client/retry-request-lifecycle.js.map +1 -0
  169. package/dist/client/retry-terminal-recovery.d.ts +100 -0
  170. package/dist/client/retry-terminal-recovery.d.ts.map +1 -0
  171. package/dist/client/retry-terminal-recovery.js +164 -0
  172. package/dist/client/retry-terminal-recovery.js.map +1 -0
  173. package/dist/client/retry-utils.d.ts +27 -0
  174. package/dist/client/retry-utils.d.ts.map +1 -1
  175. package/dist/client/retry-utils.js +46 -0
  176. package/dist/client/retry-utils.js.map +1 -1
  177. package/dist/client/retry.d.ts +106 -18
  178. package/dist/client/retry.d.ts.map +1 -1
  179. package/dist/client/retry.js +687 -139
  180. package/dist/client/retry.js.map +1 -1
  181. package/dist/client/sealed-sender.d.ts +23 -6
  182. package/dist/client/sealed-sender.d.ts.map +1 -1
  183. package/dist/client/sealed-sender.js +30 -6
  184. package/dist/client/sealed-sender.js.map +1 -1
  185. package/dist/client/sessions.d.ts +2 -2
  186. package/dist/client/sessions.js +2 -2
  187. package/dist/client/signal-service-cipher.d.ts +726 -19
  188. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  189. package/dist/client/signal-service-cipher.js +2265 -343
  190. package/dist/client/signal-service-cipher.js.map +1 -1
  191. package/dist/client/state.d.ts +5 -0
  192. package/dist/client/state.d.ts.map +1 -1
  193. package/dist/client/state.js +11 -1
  194. package/dist/client/state.js.map +1 -1
  195. package/dist/client/storage-protection.d.ts +64 -0
  196. package/dist/client/storage-protection.d.ts.map +1 -0
  197. package/dist/client/storage-protection.js +150 -0
  198. package/dist/client/storage-protection.js.map +1 -0
  199. package/dist/client/types.d.ts +149 -15
  200. package/dist/client/types.d.ts.map +1 -1
  201. package/dist/client/types.js +1 -1
  202. package/dist/client/types.js.map +1 -1
  203. package/dist/device/constants.d.ts +0 -5
  204. package/dist/device/constants.d.ts.map +1 -1
  205. package/dist/device/constants.js +0 -5
  206. package/dist/device/constants.js.map +1 -1
  207. package/dist/device/expo/index.d.ts +4 -17
  208. package/dist/device/expo/index.d.ts.map +1 -1
  209. package/dist/device/expo/index.js +4 -23
  210. package/dist/device/expo/index.js.map +1 -1
  211. package/dist/device/index.d.ts +0 -2
  212. package/dist/device/index.d.ts.map +1 -1
  213. package/dist/device/index.js +0 -7
  214. package/dist/device/index.js.map +1 -1
  215. package/dist/device/lifecycle/manager.d.ts +5 -4
  216. package/dist/device/lifecycle/manager.d.ts.map +1 -1
  217. package/dist/device/lifecycle/manager.js +16 -16
  218. package/dist/device/lifecycle/manager.js.map +1 -1
  219. package/dist/device/lifecycle/types.d.ts +2 -2
  220. package/dist/device/lifecycle/types.d.ts.map +1 -1
  221. package/dist/device/react-native/index.d.ts +4 -15
  222. package/dist/device/react-native/index.d.ts.map +1 -1
  223. package/dist/device/react-native/index.js +4 -21
  224. package/dist/device/react-native/index.js.map +1 -1
  225. package/dist/device/types.d.ts +1 -1
  226. package/dist/groups/index.d.ts +1 -1
  227. package/dist/groups/index.d.ts.map +1 -1
  228. package/dist/index.d.ts +8 -6
  229. package/dist/index.d.ts.map +1 -1
  230. package/dist/index.js +2 -1
  231. package/dist/index.js.map +1 -1
  232. package/dist/internal/crypto/ec/x25519-validation.d.ts +0 -1
  233. package/dist/internal/crypto/ec/x25519-validation.d.ts.map +1 -1
  234. package/dist/internal/crypto/ec/x25519-validation.js +0 -1
  235. package/dist/internal/crypto/ec/x25519-validation.js.map +1 -1
  236. package/dist/internal/crypto/validation.d.ts +2 -2
  237. package/dist/internal/groups/index.d.ts +1 -0
  238. package/dist/internal/groups/index.d.ts.map +1 -1
  239. package/dist/internal/groups/index.js +1 -0
  240. package/dist/internal/groups/index.js.map +1 -1
  241. package/dist/internal/groups/manager.d.ts +37 -16
  242. package/dist/internal/groups/manager.d.ts.map +1 -1
  243. package/dist/internal/groups/manager.js +46 -1
  244. package/dist/internal/groups/manager.js.map +1 -1
  245. package/dist/internal/groups/receive-record.d.ts +78 -0
  246. package/dist/internal/groups/receive-record.d.ts.map +1 -0
  247. package/dist/internal/groups/receive-record.js +43 -0
  248. package/dist/internal/groups/receive-record.js.map +1 -0
  249. package/dist/internal/groups/sdk-store.d.ts +27 -3
  250. package/dist/internal/groups/sdk-store.d.ts.map +1 -1
  251. package/dist/internal/groups/sdk-store.js +151 -19
  252. package/dist/internal/groups/sdk-store.js.map +1 -1
  253. package/dist/internal/groups/wire.d.ts +12 -1
  254. package/dist/internal/groups/wire.d.ts.map +1 -1
  255. package/dist/internal/groups/wire.js +36 -0
  256. package/dist/internal/groups/wire.js.map +1 -1
  257. package/dist/internal/manager/index.d.ts +1 -1
  258. package/dist/internal/manager/manager.d.ts +20 -19
  259. package/dist/internal/manager/manager.d.ts.map +1 -1
  260. package/dist/internal/manager/manager.js +56 -39
  261. package/dist/internal/manager/manager.js.map +1 -1
  262. package/dist/internal/protocol/double-ratchet/chains.d.ts +4 -18
  263. package/dist/internal/protocol/double-ratchet/chains.d.ts.map +1 -1
  264. package/dist/internal/protocol/double-ratchet/chains.js +23 -74
  265. package/dist/internal/protocol/double-ratchet/chains.js.map +1 -1
  266. package/dist/internal/protocol/double-ratchet/index.d.ts +1 -1
  267. package/dist/internal/protocol/double-ratchet/index.d.ts.map +1 -1
  268. package/dist/internal/protocol/double-ratchet/index.js +1 -1
  269. package/dist/internal/protocol/double-ratchet/index.js.map +1 -1
  270. package/dist/internal/protocol/double-ratchet/ratchet.d.ts +5 -7
  271. package/dist/internal/protocol/double-ratchet/ratchet.d.ts.map +1 -1
  272. package/dist/internal/protocol/double-ratchet/ratchet.js +4 -6
  273. package/dist/internal/protocol/double-ratchet/ratchet.js.map +1 -1
  274. package/dist/internal/protocol/pqxdh/pqxdh.d.ts.map +1 -1
  275. package/dist/internal/protocol/pqxdh/pqxdh.js +2 -1
  276. package/dist/internal/protocol/pqxdh/pqxdh.js.map +1 -1
  277. package/dist/internal/protocol/sealed-sender/types.d.ts +6 -8
  278. package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
  279. package/dist/internal/protocol/sealed-sender/types.js +8 -9
  280. package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
  281. package/dist/internal/protocol/sender-keys/handoff-ledger.d.ts +110 -0
  282. package/dist/internal/protocol/sender-keys/handoff-ledger.d.ts.map +1 -0
  283. package/dist/internal/protocol/sender-keys/handoff-ledger.js +124 -0
  284. package/dist/internal/protocol/sender-keys/handoff-ledger.js.map +1 -0
  285. package/dist/internal/protocol/sender-keys/manager.d.ts +71 -62
  286. package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
  287. package/dist/internal/protocol/sender-keys/manager.js +228 -175
  288. package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
  289. package/dist/internal/protocol/spqr/index.d.ts +2 -2
  290. package/dist/internal/protocol/spqr/index.d.ts.map +1 -1
  291. package/dist/internal/protocol/spqr/index.js +2 -2
  292. package/dist/internal/protocol/spqr/index.js.map +1 -1
  293. package/dist/internal/protocol/spqr/serialize.d.ts +9 -1
  294. package/dist/internal/protocol/spqr/serialize.d.ts.map +1 -1
  295. package/dist/internal/protocol/spqr/serialize.js +56 -16
  296. package/dist/internal/protocol/spqr/serialize.js.map +1 -1
  297. package/dist/internal/protocol/spqr/spqr.d.ts +1 -14
  298. package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
  299. package/dist/internal/protocol/spqr/spqr.js +54 -42
  300. package/dist/internal/protocol/spqr/spqr.js.map +1 -1
  301. package/dist/internal/protocol/spqr/validate.d.ts +26 -6
  302. package/dist/internal/protocol/spqr/validate.d.ts.map +1 -1
  303. package/dist/internal/protocol/spqr/validate.js +49 -21
  304. package/dist/internal/protocol/spqr/validate.js.map +1 -1
  305. package/dist/internal/sesame/index.d.ts +1 -1
  306. package/dist/internal/sesame/index.d.ts.map +1 -1
  307. package/dist/internal/sesame/index.js.map +1 -1
  308. package/dist/internal/sesame/manager.d.ts +66 -13
  309. package/dist/internal/sesame/manager.d.ts.map +1 -1
  310. package/dist/internal/sesame/manager.js +221 -87
  311. package/dist/internal/sesame/manager.js.map +1 -1
  312. package/dist/internal/sesame/types.d.ts +95 -17
  313. package/dist/internal/sesame/types.d.ts.map +1 -1
  314. package/dist/internal/sesame/types.js +17 -0
  315. package/dist/internal/sesame/types.js.map +1 -1
  316. package/dist/internal/session/builder.d.ts +5 -5
  317. package/dist/internal/session/builder.d.ts.map +1 -1
  318. package/dist/internal/session/builder.js +12 -17
  319. package/dist/internal/session/builder.js.map +1 -1
  320. package/dist/internal/session/cipher.d.ts +13 -11
  321. package/dist/internal/session/cipher.d.ts.map +1 -1
  322. package/dist/internal/session/cipher.js +40 -22
  323. package/dist/internal/session/cipher.js.map +1 -1
  324. package/dist/internal/session/factory.d.ts +5 -5
  325. package/dist/internal/session/factory.d.ts.map +1 -1
  326. package/dist/internal/session/factory.js +4 -4
  327. package/dist/internal/session/factory.js.map +1 -1
  328. package/dist/internal/session/handshake.d.ts +14 -16
  329. package/dist/internal/session/handshake.d.ts.map +1 -1
  330. package/dist/internal/session/handshake.js +18 -75
  331. package/dist/internal/session/handshake.js.map +1 -1
  332. package/dist/internal/session/index.d.ts +1 -1
  333. package/dist/internal/session/index.js +1 -1
  334. package/dist/internal/session/record-locks.d.ts +17 -6
  335. package/dist/internal/session/record-locks.d.ts.map +1 -1
  336. package/dist/internal/session/record-locks.js +43 -7
  337. package/dist/internal/session/record-locks.js.map +1 -1
  338. package/dist/internal/session/session-resolver.d.ts +1 -1
  339. package/dist/internal/session/session-resolver.js +1 -1
  340. package/dist/internal/session/state.d.ts +2 -2
  341. package/dist/internal/session/state.js +1 -1
  342. package/dist/internal/session/types.d.ts +4 -12
  343. package/dist/internal/session/types.d.ts.map +1 -1
  344. package/dist/internal/session/types.js +1 -1
  345. package/dist/keys/generation.d.ts +2 -2
  346. package/dist/keys/generation.js +2 -2
  347. package/dist/keys/types.d.ts +5 -5
  348. package/dist/keys/types.d.ts.map +1 -1
  349. package/dist/keys/types.js +1 -1
  350. package/dist/layers.d.ts +1 -1
  351. package/dist/layers.js +2 -2
  352. package/dist/layers.js.map +1 -1
  353. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  354. package/dist/local/store/expo/adapter.js +12 -8
  355. package/dist/local/store/expo/adapter.js.map +1 -1
  356. package/dist/local/store/key-value/adapter.d.ts +76 -10
  357. package/dist/local/store/key-value/adapter.d.ts.map +1 -1
  358. package/dist/local/store/key-value/adapter.js +367 -61
  359. package/dist/local/store/key-value/adapter.js.map +1 -1
  360. package/dist/local/store/key-value/backend-conformance.d.ts.map +1 -1
  361. package/dist/local/store/key-value/backend-conformance.js +74 -0
  362. package/dist/local/store/key-value/backend-conformance.js.map +1 -1
  363. package/dist/local/store/key-value/batch.d.ts +2 -0
  364. package/dist/local/store/key-value/batch.d.ts.map +1 -1
  365. package/dist/local/store/key-value/batch.js +26 -0
  366. package/dist/local/store/key-value/batch.js.map +1 -1
  367. package/dist/local/store/key-value/receive-work.d.ts +55 -0
  368. package/dist/local/store/key-value/receive-work.d.ts.map +1 -0
  369. package/dist/local/store/key-value/receive-work.js +162 -0
  370. package/dist/local/store/key-value/receive-work.js.map +1 -0
  371. package/dist/local/store/key-value/send-log.d.ts +61 -0
  372. package/dist/local/store/key-value/send-log.d.ts.map +1 -0
  373. package/dist/local/store/key-value/send-log.js +430 -0
  374. package/dist/local/store/key-value/send-log.js.map +1 -0
  375. package/dist/local/store/key-value/sender-key-handoff.d.ts +68 -0
  376. package/dist/local/store/key-value/sender-key-handoff.d.ts.map +1 -0
  377. package/dist/local/store/key-value/sender-key-handoff.js +189 -0
  378. package/dist/local/store/key-value/sender-key-handoff.js.map +1 -0
  379. package/dist/local/store/key-value/storage.d.ts +15 -0
  380. package/dist/local/store/key-value/storage.d.ts.map +1 -1
  381. package/dist/local/store/keyed-index.d.ts +23 -0
  382. package/dist/local/store/keyed-index.d.ts.map +1 -0
  383. package/dist/local/store/keyed-index.js +41 -0
  384. package/dist/local/store/keyed-index.js.map +1 -0
  385. package/dist/local/store/memory/adapter.d.ts +44 -12
  386. package/dist/local/store/memory/adapter.d.ts.map +1 -1
  387. package/dist/local/store/memory/adapter.js +197 -46
  388. package/dist/local/store/memory/adapter.js.map +1 -1
  389. package/dist/local/store/memory/send-log.d.ts +42 -0
  390. package/dist/local/store/memory/send-log.d.ts.map +1 -0
  391. package/dist/local/store/memory/send-log.js +190 -0
  392. package/dist/local/store/memory/send-log.js.map +1 -0
  393. package/dist/local/store/node/adapter.d.ts.map +1 -1
  394. package/dist/local/store/node/adapter.js +8 -6
  395. package/dist/local/store/node/adapter.js.map +1 -1
  396. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  397. package/dist/local/store/react-native/adapter.js +12 -8
  398. package/dist/local/store/react-native/adapter.js.map +1 -1
  399. package/dist/local/store/receive-work.d.ts +87 -0
  400. package/dist/local/store/receive-work.d.ts.map +1 -0
  401. package/dist/local/store/receive-work.js +204 -0
  402. package/dist/local/store/receive-work.js.map +1 -0
  403. package/dist/local/store/received-content.d.ts +3 -3
  404. package/dist/local/store/received-content.d.ts.map +1 -1
  405. package/dist/local/store/received-content.js +2 -11
  406. package/dist/local/store/received-content.js.map +1 -1
  407. package/dist/local/store/reliability.d.ts +411 -14
  408. package/dist/local/store/reliability.d.ts.map +1 -1
  409. package/dist/local/store/reliability.js +532 -58
  410. package/dist/local/store/reliability.js.map +1 -1
  411. package/dist/local/store/send-log-order.d.ts +15 -0
  412. package/dist/local/store/send-log-order.d.ts.map +1 -0
  413. package/dist/local/store/send-log-order.js +24 -0
  414. package/dist/local/store/send-log-order.js.map +1 -0
  415. package/dist/local/store/sender-key-handoff-index.d.ts +38 -0
  416. package/dist/local/store/sender-key-handoff-index.d.ts.map +1 -0
  417. package/dist/local/store/sender-key-handoff-index.js +101 -0
  418. package/dist/local/store/sender-key-handoff-index.js.map +1 -0
  419. package/dist/local/store/sender-key-handoff-table.d.ts +29 -0
  420. package/dist/local/store/sender-key-handoff-table.d.ts.map +1 -0
  421. package/dist/local/store/sender-key-handoff-table.js +97 -0
  422. package/dist/local/store/sender-key-handoff-table.js.map +1 -0
  423. package/dist/local/store/sqlite/encryption.d.ts +8 -1
  424. package/dist/local/store/sqlite/encryption.d.ts.map +1 -1
  425. package/dist/local/store/sqlite/encryption.js +9 -0
  426. package/dist/local/store/sqlite/encryption.js.map +1 -1
  427. package/dist/local/store/sqlite/key-storage/index.d.ts +25 -4
  428. package/dist/local/store/sqlite/key-storage/index.d.ts.map +1 -1
  429. package/dist/local/store/sqlite/key-storage/index.js +68 -7
  430. package/dist/local/store/sqlite/key-storage/index.js.map +1 -1
  431. package/dist/local/store/sqlite/key-storage/message-records.d.ts +16 -4
  432. package/dist/local/store/sqlite/key-storage/message-records.d.ts.map +1 -1
  433. package/dist/local/store/sqlite/key-storage/message-records.js +49 -6
  434. package/dist/local/store/sqlite/key-storage/message-records.js.map +1 -1
  435. package/dist/local/store/sqlite/key-storage/metadata.d.ts +8 -7
  436. package/dist/local/store/sqlite/key-storage/metadata.d.ts.map +1 -1
  437. package/dist/local/store/sqlite/key-storage/metadata.js +17 -15
  438. package/dist/local/store/sqlite/key-storage/metadata.js.map +1 -1
  439. package/dist/local/store/sqlite/key-storage/receive-work.d.ts +27 -0
  440. package/dist/local/store/sqlite/key-storage/receive-work.d.ts.map +1 -0
  441. package/dist/local/store/sqlite/key-storage/receive-work.js +98 -0
  442. package/dist/local/store/sqlite/key-storage/receive-work.js.map +1 -0
  443. package/dist/local/store/sqlite/key-storage/send-log.d.ts +27 -0
  444. package/dist/local/store/sqlite/key-storage/send-log.d.ts.map +1 -0
  445. package/dist/local/store/sqlite/key-storage/send-log.js +178 -0
  446. package/dist/local/store/sqlite/key-storage/send-log.js.map +1 -0
  447. package/dist/local/store/sqlite/key-storage/sender-key-handoff.d.ts +27 -0
  448. package/dist/local/store/sqlite/key-storage/sender-key-handoff.d.ts.map +1 -0
  449. package/dist/local/store/sqlite/key-storage/sender-key-handoff.js +75 -0
  450. package/dist/local/store/sqlite/key-storage/sender-key-handoff.js.map +1 -0
  451. package/dist/local/store/sqlite/key-storage/session-trust.d.ts +2 -2
  452. package/dist/local/store/sqlite/key-storage/session-trust.js +5 -5
  453. package/dist/local/store/sqlite/key-storage/session-trust.js.map +1 -1
  454. package/dist/local/store/sqlite/migrations.d.ts.map +1 -1
  455. package/dist/local/store/sqlite/migrations.js +101 -0
  456. package/dist/local/store/sqlite/migrations.js.map +1 -1
  457. package/dist/local/store/sqlite/models/index.d.ts +2 -1
  458. package/dist/local/store/sqlite/models/index.d.ts.map +1 -1
  459. package/dist/local/store/sqlite/models/index.js +5 -1
  460. package/dist/local/store/sqlite/models/index.js.map +1 -1
  461. package/dist/local/store/sqlite/models/message-record.d.ts +15 -0
  462. package/dist/local/store/sqlite/models/message-record.d.ts.map +1 -1
  463. package/dist/local/store/sqlite/models/message-record.js +24 -0
  464. package/dist/local/store/sqlite/models/message-record.js.map +1 -1
  465. package/dist/local/store/sqlite/models/send-log.d.ts +51 -0
  466. package/dist/local/store/sqlite/models/send-log.d.ts.map +1 -0
  467. package/dist/local/store/sqlite/models/send-log.js +206 -0
  468. package/dist/local/store/sqlite/models/send-log.js.map +1 -0
  469. package/dist/local/store/sqlite/open-store.d.ts +9 -1
  470. package/dist/local/store/sqlite/open-store.d.ts.map +1 -1
  471. package/dist/local/store/sqlite/open-store.js +20 -1
  472. package/dist/local/store/sqlite/open-store.js.map +1 -1
  473. package/dist/local/store/sqlite/schema.d.ts +34 -1
  474. package/dist/local/store/sqlite/schema.d.ts.map +1 -1
  475. package/dist/local/store/sqlite/schema.js +14 -0
  476. package/dist/local/store/sqlite/schema.js.map +1 -1
  477. package/dist/local/store/sqlite/store.d.ts +61 -11
  478. package/dist/local/store/sqlite/store.d.ts.map +1 -1
  479. package/dist/local/store/sqlite/store.js +191 -27
  480. package/dist/local/store/sqlite/store.js.map +1 -1
  481. package/dist/local/store/web/adapter.d.ts +76 -8
  482. package/dist/local/store/web/adapter.d.ts.map +1 -1
  483. package/dist/local/store/web/adapter.js +579 -127
  484. package/dist/local/store/web/adapter.js.map +1 -1
  485. package/dist/local/store/web/receive-work.d.ts +57 -0
  486. package/dist/local/store/web/receive-work.d.ts.map +1 -0
  487. package/dist/local/store/web/receive-work.js +99 -0
  488. package/dist/local/store/web/receive-work.js.map +1 -0
  489. package/dist/local/store/web/send-log.d.ts +92 -0
  490. package/dist/local/store/web/send-log.d.ts.map +1 -0
  491. package/dist/local/store/web/send-log.js +267 -0
  492. package/dist/local/store/web/send-log.js.map +1 -0
  493. package/dist/local/store/web/sender-key-handoff.d.ts +81 -0
  494. package/dist/local/store/web/sender-key-handoff.d.ts.map +1 -0
  495. package/dist/local/store/web/sender-key-handoff.js +156 -0
  496. package/dist/local/store/web/sender-key-handoff.js.map +1 -0
  497. package/dist/local/store/web-sqlite/adapter.d.ts +2 -0
  498. package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
  499. package/dist/local/store/web-sqlite/adapter.js +12 -6
  500. package/dist/local/store/web-sqlite/adapter.js.map +1 -1
  501. package/dist/local/vault/custody.d.ts +8 -0
  502. package/dist/local/vault/custody.d.ts.map +1 -0
  503. package/dist/local/vault/custody.js +9 -0
  504. package/dist/local/vault/custody.js.map +1 -0
  505. package/dist/local/vault/electron-safe-storage.d.ts +3 -1
  506. package/dist/local/vault/electron-safe-storage.d.ts.map +1 -1
  507. package/dist/local/vault/electron-safe-storage.js +2 -0
  508. package/dist/local/vault/electron-safe-storage.js.map +1 -1
  509. package/dist/local/vault/expo-secure-store.d.ts +3 -1
  510. package/dist/local/vault/expo-secure-store.d.ts.map +1 -1
  511. package/dist/local/vault/expo-secure-store.js +2 -0
  512. package/dist/local/vault/expo-secure-store.js.map +1 -1
  513. package/dist/local/vault/indexed-db.d.ts +3 -1
  514. package/dist/local/vault/indexed-db.d.ts.map +1 -1
  515. package/dist/local/vault/indexed-db.js +2 -0
  516. package/dist/local/vault/indexed-db.js.map +1 -1
  517. package/dist/local/vault/react-native-keychain.d.ts +3 -1
  518. package/dist/local/vault/react-native-keychain.d.ts.map +1 -1
  519. package/dist/local/vault/react-native-keychain.js +2 -0
  520. package/dist/local/vault/react-native-keychain.js.map +1 -1
  521. package/dist/remote/relay/device-set.d.ts +94 -0
  522. package/dist/remote/relay/device-set.d.ts.map +1 -0
  523. package/dist/remote/relay/device-set.js +156 -0
  524. package/dist/remote/relay/device-set.js.map +1 -0
  525. package/dist/remote/relay/types.d.ts +104 -110
  526. package/dist/remote/relay/types.d.ts.map +1 -1
  527. package/dist/safety/core.d.ts +15 -6
  528. package/dist/safety/core.d.ts.map +1 -1
  529. package/dist/safety/core.js +41 -27
  530. package/dist/safety/core.js.map +1 -1
  531. package/dist/safety/index.d.ts +2 -1
  532. package/dist/safety/index.d.ts.map +1 -1
  533. package/dist/safety/index.js +12 -18
  534. package/dist/safety/index.js.map +1 -1
  535. package/dist/types/api.d.ts +707 -62
  536. package/dist/types/api.d.ts.map +1 -1
  537. package/dist/types/errors.d.ts +14 -33
  538. package/dist/types/errors.d.ts.map +1 -1
  539. package/dist/types/errors.js +14 -24
  540. package/dist/types/errors.js.map +1 -1
  541. package/dist/types/messages.d.ts +2 -2
  542. package/dist/types/messages.js +1 -1
  543. package/dist/types/protocol-config.d.ts +175 -42
  544. package/dist/types/protocol-config.d.ts.map +1 -1
  545. package/dist/types/protocol-config.js +19 -38
  546. package/dist/types/protocol-config.js.map +1 -1
  547. package/dist/types/protocol-constants.d.ts +6 -6
  548. package/dist/types/protocol-constants.js +6 -6
  549. package/dist/types/session.d.ts +7 -7
  550. package/dist/types/session.d.ts.map +1 -1
  551. package/dist/types/session.js +39 -21
  552. package/dist/types/session.js.map +1 -1
  553. package/dist/username/link.d.ts +2 -2
  554. package/dist/username/link.js +2 -2
  555. package/dist/utils/origin-lock.d.ts +45 -0
  556. package/dist/utils/origin-lock.d.ts.map +1 -0
  557. package/dist/utils/origin-lock.js +80 -0
  558. package/dist/utils/origin-lock.js.map +1 -0
  559. package/dist/utils/retry.d.ts +2 -0
  560. package/dist/utils/retry.d.ts.map +1 -1
  561. package/dist/utils/retry.js +7 -0
  562. package/dist/utils/retry.js.map +1 -1
  563. package/docs/ASSURANCE.md +6 -6
  564. package/docs/CLIENT_COMPOSITION.md +2 -2
  565. package/docs/DEVIATIONS.md +677 -182
  566. package/docs/E2EE.md +1 -1
  567. package/docs/ERROR_HANDLING.md +235 -2
  568. package/docs/GETTING_STARTED.md +7 -4
  569. package/docs/INTERFACES.md +1 -1
  570. package/docs/PACKAGE_SURFACE.md +6 -5
  571. package/docs/PROTOCOL_POLICY.md +102 -22
  572. package/docs/RECIPES.md +3 -15
  573. package/docs/SECURITY.md +90 -5
  574. package/keys/README.md +3 -3
  575. package/local/store/README.md +78 -14
  576. package/local/store/key-value/README.md +14 -3
  577. package/local/store/node/README.md +8 -3
  578. package/local/store/web/README.md +9 -0
  579. package/local/store/web-sqlite/README.md +14 -2
  580. package/local/vault/README.md +21 -0
  581. package/package.json +1 -6
  582. package/remote/README.md +0 -1
  583. package/remote/relay/README.md +2 -2
  584. package/dist/device/provisioning.d.ts +0 -242
  585. package/dist/device/provisioning.d.ts.map +0 -1
  586. package/dist/device/provisioning.js +0 -421
  587. package/dist/device/provisioning.js.map +0 -1
  588. package/dist/internal/protocol/x3dh/index.d.ts +0 -15
  589. package/dist/internal/protocol/x3dh/index.d.ts.map +0 -1
  590. package/dist/internal/protocol/x3dh/index.js +0 -13
  591. package/dist/internal/protocol/x3dh/index.js.map +0 -1
  592. package/dist/internal/protocol/x3dh/x3dh.d.ts +0 -131
  593. package/dist/internal/protocol/x3dh/x3dh.d.ts.map +0 -1
  594. package/dist/internal/protocol/x3dh/x3dh.js +0 -261
  595. package/dist/internal/protocol/x3dh/x3dh.js.map +0 -1
@@ -8,6 +8,8 @@ import type { TrustDirection, IdentityKeyChange } from './trust.js';
8
8
  import type { UserRecord, DeviceRecord } from '../internal/sesame/types.js';
9
9
  import type { SenderKeyState } from '../internal/protocol/sender-keys/manager.js';
10
10
  import type { Logger } from '../logger.js';
11
+ import type { ContentHint } from './messages.js';
12
+ import type { ContentRecoveryStatus } from './protocol-config.js';
11
13
  import type { RelayConnectionState, Unsubscribe } from '../remote/relay/types.js';
12
14
  export {};
13
15
  export type { IdentityType };
@@ -53,22 +55,154 @@ export interface SessionTrustCommit {
53
55
  signedPreKeyId: number;
54
56
  baseKeyBytes: Uint8Array;
55
57
  };
56
- receivedContent?: ReceivedContent;
58
+ /**
59
+ * The receive record of the decrypted message. The store writes it in the
60
+ * same transaction as the session state, so the ratchet step and the
61
+ * record roll back together.
62
+ */
63
+ receiveWork?: ReceiveWorkRecord;
64
+ /**
65
+ * The device whose sender-key handoffs this commit invalidates. The store
66
+ * deletes the rows of that device in every group in the same transaction.
67
+ * The session layer sets it for an inbound PreKey session and for an
68
+ * outbound bundle session that archives a current session.
69
+ */
70
+ senderKeyHandoffInvalidation?: SenderKeyHandoffDevice;
57
71
  }
58
72
  export interface RetainedKyberPreKey {
59
73
  preKey: KyberPreKey;
60
74
  instanceId: string;
61
75
  }
62
- /** Recoverable plaintext, encrypted at rest with the device-local store. */
76
+ /**
77
+ * The legacy row of recoverable plaintext that SDK 11 stored. A store that
78
+ * opens such a row converts it to a receive record with
79
+ * `awaitingEnvelope: true`. No store writes this shape any more.
80
+ */
63
81
  export interface ReceivedContent {
64
82
  id: string;
65
83
  plaintext: string;
66
84
  receivedAt: number;
67
85
  groupId?: string;
68
86
  }
87
+ /**
88
+ * The stage of one receive record.
89
+ *
90
+ * - `decrypted`: the ratchet step and the plaintext are committed, and the
91
+ * application has not got the content yet.
92
+ * - `receipt-due`: the application got the content, and a delivery receipt
93
+ * is owed. The record holds no plaintext.
94
+ * - `awaiting-completion`: the helper returned the content, and the
95
+ * application has not called `completeReceive` yet.
96
+ */
97
+ export type ReceiveWorkStage = 'decrypted' | 'receipt-due' | 'awaiting-completion';
98
+ /**
99
+ * One received message that the device decrypted and has not finished.
100
+ * The record is protocol state: the store keeps it with the same protection
101
+ * as its sessions.
102
+ */
103
+ export interface ReceiveWorkRecord {
104
+ /** The delivered fingerprint of the envelope. */
105
+ workId: string;
106
+ /** Increases by one on each write. A write names the revision that it replaces. */
107
+ revision: number;
108
+ stage: ReceiveWorkStage;
109
+ /** `relay` for a Relay delivery, `caller` for an envelope that the application passed. */
110
+ origin: 'relay' | 'caller';
111
+ /** The local arrival order. */
112
+ arrivalSeq: number;
113
+ /**
114
+ * The time of the first durable local admission. No later write changes
115
+ * it. It is the expiry base and the fallback receipt timestamp.
116
+ */
117
+ receivedAt: number;
118
+ /** The record is not processed before this time. */
119
+ dueAt: number;
120
+ /** The UTF-8 size of the record. */
121
+ sizeBytes: number;
122
+ /** The decrypted content. Absent in `receipt-due`. */
123
+ plaintext?: string;
124
+ /** The message ID that the application sees. Absent on a converted legacy row. */
125
+ messageId?: string;
126
+ envelopeId?: string;
127
+ senderUserId?: string;
128
+ senderDeviceId?: number;
129
+ messageType?: 'prekey_bundle' | 'ciphertext' | 'sender_key';
130
+ serverTimestamp?: number;
131
+ arrivedSealed?: boolean;
132
+ /**
133
+ * The timestamp of the sender.
134
+ *
135
+ * - `decrypted`: the timestamp of the Relay envelope. The restore of the
136
+ * record checks that the content carries the same timestamp. A caller
137
+ * envelope has none.
138
+ * - `receipt-due`: the timestamp of the content, which the delivery
139
+ * receipt names. Without it, the receipt names `receivedAt`.
140
+ */
141
+ senderTimestamp?: number;
142
+ /**
143
+ * The raw group of the content. A sender-key record sets it at commit.
144
+ * A record that waits for its group sets it when it blocks, or when it
145
+ * waits behind an earlier record of its group.
146
+ */
147
+ groupId?: string;
148
+ /** The record waits for an update of the state of `groupId`. */
149
+ blockedOn?: 'group-update';
150
+ /** The acknowledgment of the envelope, written in the commit. */
151
+ ackIntent?: {
152
+ at: number;
153
+ hasReceiptJoin: boolean;
154
+ };
155
+ /** The join decision of the Relay: true when the Relay sends the receipt. */
156
+ relayOwnsReceipt?: boolean;
157
+ /**
158
+ * The number of `onMessageDecrypted` attempts that started for the
159
+ * content. The count is written before each attempt, so an attempt that
160
+ * ends the process counts. After 10, the record no longer holds back the
161
+ * later records of its conversation. Absent before the first attempt.
162
+ */
163
+ hookAttempts?: number;
164
+ /** The failed envelope that this record resends. */
165
+ failedEnvelopeId?: string;
166
+ /** A converted legacy row. The next delivery of its envelope gives the sender fields. */
167
+ awaitingEnvelope?: true;
168
+ }
169
+ /**
170
+ * Builds the receive record of decrypted content. The decrypt calls it in
171
+ * its commit, with the plaintext and, for a sender-key message, the raw
172
+ * group.
173
+ */
174
+ export type ReceiveWorkSeed = (content: {
175
+ plaintext: string;
176
+ groupId?: string;
177
+ }) => ReceiveWorkRecord;
178
+ /** A query of the receive records, in arrival order. */
179
+ export interface ReceiveWorkQuery {
180
+ stage?: ReceiveWorkStage;
181
+ /** Only records with `dueAt` at or before this time. */
182
+ dueBy?: number;
183
+ /**
184
+ * Only records after this position in arrival order: an `arrivalSeq`
185
+ * above it, or an equal `arrivalSeq` with a `workId` above it. Pass the
186
+ * last record of the page before.
187
+ */
188
+ after?: Pick<ReceiveWorkRecord, 'arrivalSeq' | 'workId'>;
189
+ /** The most records to return. */
190
+ limit?: number;
191
+ }
192
+ /** The number and the total size of receive records. */
193
+ export interface ReceiveWorkUsage {
194
+ items: number;
195
+ bytes: number;
196
+ }
197
+ /** One metadata write in the atomic completion of a receive record. Null deletes. */
198
+ export interface ReceiveWorkMetadataWrite {
199
+ key: string;
200
+ value: string | null;
201
+ }
69
202
  /** Effects committed atomically with the sender-key record after successful decryption. */
70
203
  export interface SenderKeyReceiveCommit {
71
- content?: ReceivedContent;
204
+ /** The receive record of the decrypted message. */
205
+ work?: ReceiveWorkRecord;
72
206
  consumedSkippedKey?: {
73
207
  senderKeyId: string;
74
208
  chainIndex: number;
@@ -116,6 +250,15 @@ export interface SignalProtocolClient {
116
250
  * This is the client-scoped logger used throughout the Signal Protocol runtime.
117
251
  */
118
252
  readonly logger: Required<Logger>;
253
+ /**
254
+ * Whether this client keeps resendable content to answer retry requests.
255
+ *
256
+ * The client decides at creation, from the `protection` that the local
257
+ * store declares and from `protocol.contentRecovery`. When `enabled` is
258
+ * false, `reason` says why, and the client deletes any resendable content
259
+ * that the store already holds.
260
+ */
261
+ readonly contentRecoveryStatus: ContentRecoveryStatus;
119
262
  /**
120
263
  * Register an event hook for Signal Protocol events
121
264
  *
@@ -249,6 +392,32 @@ export interface SignalProtocolClient {
249
392
  * ```
250
393
  */
251
394
  send(recipientId: string, content: import('../client/types.js').DataMessageInput | string | Uint8Array, options?: import('../client/types.js').SendOptions): Promise<import('../client/types.js').SendResult>;
395
+ /**
396
+ * Delete the resendable content of one group send.
397
+ *
398
+ * The client keeps the content of a resendable group send to answer a
399
+ * retry request, until each recipient device confirms it with an E2EE
400
+ * delivery receipt or the retention ends. Call this method when the
401
+ * application deletes the message, so a later retry request gets no
402
+ * content. The method does not delete pairwise message records.
403
+ *
404
+ * @param clientMessageId - The `clientMessageId` of the send
405
+ * @returns True when the client held content for the send
406
+ */
407
+ forgetSentContent(clientMessageId: string): Promise<boolean>;
408
+ /**
409
+ * The recipient devices of a resendable group send that have not
410
+ * confirmed it with an E2EE delivery receipt.
411
+ *
412
+ * A device leaves the list when its E2EE delivery receipt arrives. A Relay
413
+ * delivery receipt does not remove it, because a device also acknowledges
414
+ * a copy that it could not decrypt. The list is empty after the retention
415
+ * ends, after `forgetSentContent`, and for a send that the client did not
416
+ * log.
417
+ *
418
+ * @param clientMessageId - The `clientMessageId` of the send
419
+ */
420
+ getPendingRecipients(clientMessageId: string): Promise<SendLogDevice[]>;
252
421
  /**
253
422
  * Encrypt and upload an attachment without sending a standalone message.
254
423
  *
@@ -289,71 +458,194 @@ export interface SignalProtocolClient {
289
458
  /**
290
459
  * Process an incoming encrypted message envelope.
291
460
  *
292
- * Unified entry point for both foreground (relay) and background (HTTP) message processing.
293
- * Handles decryption and automatically sends SESAME retry requests on retryable failures.
294
- *
295
- * This method:
296
- * 1. Decodes base64 ciphertext
297
- * 2. Decrypts message using Double Ratchet
298
- * 3. On retryable error: sends retry request via relay or options callback
299
- * 4. Re-throws error for caller to handle
300
- *
301
- * A `retry_request` envelope holds no plaintext. This method rejects it
302
- * before decryption and sends no retry request. Give it to
461
+ * The receive helper for an application that pulls envelopes itself. It
462
+ * decrypts the envelope and commits its content as a receive record with
463
+ * the ratchet step, then decides the group of the content. Handles
464
+ * decryption and automatically sends SESAME retry requests on retryable
465
+ * failures. The content stays recoverable until the application calls
466
+ * `completeReceive`, or until `onPersist` resolves.
467
+ *
468
+ * The outcome tells the caller what to do with the envelope:
469
+ *
470
+ * - `processed`: give the content to the application, then acknowledge
471
+ * the envelope. A redelivery of the envelope before `completeReceive`
472
+ * returns the same outcome again with no second decrypt. A second
473
+ * `completeReceive` is a no-op.
474
+ * - `pending`: the content is stored and the client resumes it, for
475
+ * example when its group state must update first. Acknowledge the
476
+ * envelope. When the group updates, the client decides the content
477
+ * again, and `listPendingReceives({ ready: true })` then lists it.
478
+ * - `duplicate`: this client processed the envelope, or the application
479
+ * already has the content of the failed envelope of a retry request.
480
+ * The client acknowledged the envelope.
481
+ * - `null-message`: the envelope carries no content. The client consumes
482
+ * a null message when the content adapter reports `nullMessage: true`,
483
+ * and a custom adapter must report it for its own null encoding. The
484
+ * client acknowledged it. A null message for a failed envelope marks
485
+ * that envelope processed, so a redelivery of it is dropped, but a
486
+ * content resend for it that comes later still gives its content.
487
+ * - `denied`: the client refused the content. The ratchet step is spent,
488
+ * so no resend can repair it. `onDecryptionError` ran, except for a
489
+ * group that the user blocked (reason `blocked`), which has no report.
490
+ * The client acknowledged the envelope. Content from another account that carries
491
+ * a sync message is denied in any envelope.
492
+ * - `refused`: the receive queue has no room. Nothing is decrypted or
493
+ * stored. Do not acknowledge the envelope. Give it again later.
494
+ *
495
+ * The stored receives count toward `protocol.receiveQueue` and expire
496
+ * after 30 days, with `onReceiveExpired`.
497
+ *
498
+ * A group message that fails with a retryable error gets a retry request
499
+ * and is acknowledged, as a pairwise message is. A message with the
500
+ * Implicit content hint gets no request and is acknowledged.
501
+ *
502
+ * A retry request follows the sealed sender delivery mode. With a relay
503
+ * and the access key of the sender, the client posts it sealed. Otherwise
504
+ * the client posts it identified only when the mode permits it. In
505
+ * `'required'` mode a retry request that cannot be sealed is not posted:
506
+ * it stays pending until its deadline. The `sendRetryRequest` callback
507
+ * gets an identified envelope, so the client calls it only when the mode
508
+ * permits identified delivery.
509
+ *
510
+ * A `retry_request` envelope holds no plaintext. This method rejects it,
511
+ * identified or sealed, and sends no retry request. Give it to
303
512
  * `receiveIncomingEnvelopes`, which handles it.
304
513
  *
305
514
  * A failed envelope that this client asked a resend for, and each resend
306
- * or null message for it, gives plaintext at most once on both receive
307
- * paths. When this client processed the envelope, or the application
308
- * already has that content, this method acknowledges the envelope and
309
- * throws MESSAGE_DUPLICATE with no decrypt.
310
- *
311
- * A null message carries no content. The client consumes a null message
312
- * when the content adapter reports `nullMessage: true`, and a custom
313
- * adapter must report it for its own null encoding. This method never
314
- * returns a null message. It marks the null message processed,
315
- * acknowledges it and throws MESSAGE_DUPLICATE. A null message for a
316
- * failed envelope marks that envelope processed, so a redelivery of it
317
- * is dropped, but a content resend for it that comes later still gives
318
- * its plaintext.
515
+ * or null message for it, gives content at most once on both receive
516
+ * paths.
517
+ *
518
+ * A resend that brings only the sender key of a failed group message
519
+ * gives no content. It does not mark the failed envelope processed, so a
520
+ * redelivery of that envelope decrypts with the key. A resend that brings
521
+ * the content beside the key gives that content and marks the failed
522
+ * envelope processed.
319
523
  *
320
524
  * A resend or null message that fails to decrypt, or whose seal fails to
321
525
  * open, asks again for its failed envelope under the same retry ID. When
322
526
  * the processed record of the failed envelope fails to store after a
323
527
  * decrypt, the client writes a warning with the behavior
324
528
  * RETRY_FULFILL_WRITE_FAILED, as on every receive path, and this method
325
- * returns the plaintext. A redelivery of the failed envelope or of
529
+ * still returns the outcome. A redelivery of the failed envelope or of
326
530
  * another family member can then give the content again. When a
327
531
  * processed record of a null message or of its failed envelope fails to
328
532
  * store, the client writes a warning with the behavior
329
533
  * RETRY_NULL_WRITE_FAILED, as on every receive path, and this method
330
- * still throws MESSAGE_DUPLICATE. A redelivery of the failed envelope
331
- * can then give the content.
534
+ * still returns `null-message`. A redelivery of the failed envelope can
535
+ * then give the content.
536
+ *
537
+ * This method never throws `GroupResendDeferredError`, because it
538
+ * rejects a retry request.
539
+ * `receiveIncomingEnvelopes` reports a deferred retry request in
540
+ * `failedMessageIds`, so the Relay keeps the request.
332
541
  *
333
542
  * @param envelope - The encrypted message envelope
334
- * @param options - Transport callbacks for background (no relay) scenarios
335
- * @returns Decrypted plaintext
543
+ * @param options - Transport callbacks for background (no relay)
544
+ * scenarios, and `onPersist`
545
+ * @returns The receive outcome
336
546
  * @throws EncryptionError after sending retry request if decryption fails
337
- * @throws EncryptionError INVALID_CIPHERTEXT for a `retry_request` envelope
338
- * @throws EncryptionError MESSAGE_DUPLICATE when this client processed the
339
- * envelope, or the application already has the content of the failed
340
- * envelope of a retry request, or the envelope is a null message
547
+ * @throws EncryptionError INVALID_CIPHERTEXT for a `retry_request` envelope,
548
+ * identified or sealed
341
549
  *
342
550
  * @example
343
551
  * ```typescript
344
- * // Foreground (relay available)
345
- * const plaintext = await signal.processIncomingEnvelope(envelope);
346
- *
347
- * // Background (the client has no relay)
348
- * const plaintext = await signal.processIncomingEnvelope(envelope, {
552
+ * const outcome = await signal.processIncomingEnvelope(envelope, {
553
+ * // Background (the client has no relay)
349
554
  * sendRetryRequest: async (envelope) => {
350
555
  * // Post the retry_request envelope like any other envelope.
351
556
  * await backgroundRelay.send(envelope);
352
- * }
557
+ * },
558
+ * // The client completes the receive when the content is stored.
559
+ * onPersist: (processed) => db.saveMessage(processed.messageId, processed.plaintext),
353
560
  * });
561
+ * if (outcome.kind !== 'refused') await backgroundRelay.acknowledge(envelope.id);
354
562
  * ```
355
563
  */
356
- processIncomingEnvelope(envelope: import('../client/types.js').IncomingEnvelope, options?: import('../client/types.js').ProcessEnvelopeOptions): Promise<string>;
564
+ processIncomingEnvelope(envelope: import('../client/types.js').IncomingEnvelope, options?: import('../client/types.js').ProcessEnvelopeOptions): Promise<import('../client/types.js').ReceiveOutcome>;
565
+ /**
566
+ * Complete a helper receive: delete its receive record and mark its
567
+ * envelope processed. Call it after the application stored the content
568
+ * of a `processed` outcome. An unknown or completed message ID is a no-op.
569
+ *
570
+ * @param messageId - The `messageId` of the `processed` outcome
571
+ */
572
+ completeReceive(messageId: string): Promise<void>;
573
+ /**
574
+ * List the stored receives in arrival order, one page at a time. A receive
575
+ * whose content the application has, and whose receipt waits, is not
576
+ * listed.
577
+ *
578
+ * @param query - `ready` lists only the helper receives whose content
579
+ * waits for `completeReceive`. `after` is the `next` value of the page
580
+ * before. `limit` is the page size, 100 by default.
581
+ * @returns The page, and `next` when a later page can follow
582
+ * @throws Error when `after` is not a `next` value or `limit` is not a
583
+ * positive integer
584
+ */
585
+ listPendingReceives(query?: {
586
+ ready?: boolean;
587
+ after?: string;
588
+ limit?: number;
589
+ }): Promise<{
590
+ items: import('../client/types.js').PendingReceive[];
591
+ next?: string;
592
+ }>;
593
+ /**
594
+ * Remove one stored receive that the application gives up on, such as a
595
+ * receive whose `onMessageDecrypted` hook fails at each start. The client
596
+ * deletes the receive and marks its envelope processed, so a redelivery
597
+ * of the envelope is a duplicate. The call sends no receipt, calls no
598
+ * hook, and runs no `onReceiveExpired`. A hook call that already started
599
+ * for the receive still runs, and no receipt follows it.
600
+ *
601
+ * @param messageId - The `messageId` of a receive that
602
+ * `listPendingReceives` lists
603
+ * @returns The removed receive, or null when the client removed nothing:
604
+ * no listed receive has the ID, or another path wrote the receive during
605
+ * the call and again after one read
606
+ */
607
+ discardPendingReceive(messageId: string): Promise<import('../client/types.js').PendingReceive | null>;
608
+ /**
609
+ * Run one pass of the receive queue now, and stop between records at the
610
+ * deadline. A host that wakes for a push calls it after it acknowledged
611
+ * the pulled envelopes.
612
+ *
613
+ * @param options - `deadlineMs` bounds the pass. With no deadline, the
614
+ * pass runs until each record is handled.
615
+ * @returns The receives that the pass handled, and the receives that
616
+ * still wait
617
+ */
618
+ processPendingReceives(options?: {
619
+ deadlineMs?: number;
620
+ }): Promise<{
621
+ processed: number;
622
+ remaining: number;
623
+ }>;
624
+ /**
625
+ * Decrypt one envelope with no receive record.
626
+ *
627
+ * The decrypt installs a sender key distribution that the content
628
+ * carries, and checks that a managed group context binds to the group of
629
+ * the transport. It stores no content, decides no group state, and sends
630
+ * no receipt.
631
+ *
632
+ * Warning: the decrypt spends the ratchet step. When the application
633
+ * loses the returned plaintext, no later decrypt of the envelope gives it
634
+ * again. Use `processIncomingEnvelope`, which keeps the content until the
635
+ * application completes the receive.
636
+ *
637
+ * @param envelope - The encrypted message envelope
638
+ * @returns The plaintext as its sender gave it, and the group context of
639
+ * managed-group content
640
+ * @throws EncryptionError when the decrypt fails, and INVALID_CIPHERTEXT
641
+ * for a `retry_request` envelope, identified or sealed
642
+ * @throws GroupReceiveRefusedError when the group context is malformed or
643
+ * names another group than the transport
644
+ */
645
+ decryptEnvelope(envelope: import('../client/types.js').IncomingEnvelope): Promise<{
646
+ plaintext: string;
647
+ groupContext?: import('../client/content-adapter.js').GroupContentContext;
648
+ }>;
357
649
  /**
358
650
  * Encrypt file blob with two-layer encryption
359
651
  * Returns encrypted blob and encrypted key
@@ -441,11 +733,24 @@ export interface SignalProtocolClient {
441
733
  /**
442
734
  * Decrypt a group message from a sender
443
735
  *
736
+ * The message passes the group decision of `processIncomingEnvelope`.
737
+ * Content whose group state must update first stays stored, and a later
738
+ * call with the same message decides it with no second decrypt.
739
+ *
740
+ * @deprecated Use `processIncomingEnvelope`, which returns a receive
741
+ * outcome and keeps the content until the application completes the
742
+ * receive. This method completes the receive before it returns, so a
743
+ * plaintext that the application loses is gone.
744
+ *
444
745
  * @param groupId - Group identifier
445
746
  * @param senderId - Sender's user ID
446
747
  * @param senderDeviceId - Sender's device ID
447
748
  * @param framedMessage - Framed SenderKeyMessage bytes
448
749
  * @returns Decrypted plaintext
750
+ * @throws GroupReceiveUnavailableError when the group state of the content
751
+ * is not current. Its `messageId` names the stored receive. Call again
752
+ * later with the same message.
753
+ * @throws GroupReceiveRefusedError when the client refuses the content
449
754
  */
450
755
  decryptGroupMessage(groupId: string, senderId: string, senderDeviceId: number, framedMessage: Uint8Array): Promise<string>;
451
756
  /**
@@ -643,8 +948,10 @@ export interface SignalProtocolManager {
643
948
  *
644
949
  * @param remoteAddress - Remote party's protocol address (userId:deviceId)
645
950
  * @param ciphertext - Message to decrypt
951
+ * @param receiveWork - When set, the decrypt commits the receive record
952
+ * that it builds in the same transaction as the session state
646
953
  */
647
- decrypt(remoteAddress: ProtocolAddress, ciphertext: Ciphertext): Promise<string>;
954
+ decrypt(remoteAddress: ProtocolAddress, ciphertext: Ciphertext, receiveWork?: ReceiveWorkSeed): Promise<string>;
648
955
  /**
649
956
  * Get the session record for a remote address.
650
957
  *
@@ -958,7 +1265,8 @@ export interface SessionStore {
958
1265
  */
959
1266
  getSessionRecord(address: ProtocolAddress): Promise<SessionRecord | null>;
960
1267
  /**
961
- * Delete session record.
1268
+ * Delete session record. The same write deletes the sender-key handoff
1269
+ * rows of the device in every group.
962
1270
  *
963
1271
  * @param address - Protocol address
964
1272
  */
@@ -971,6 +1279,9 @@ export interface SessionStore {
971
1279
  * - Registration ID changes (app reinstall detected)
972
1280
  * - Manual session reset
973
1281
  *
1282
+ * The same write deletes the sender-key handoff rows of the device in every
1283
+ * group.
1284
+ *
974
1285
  * @param address - Protocol address
975
1286
  * @param newSession - Optional new session to set as current
976
1287
  */
@@ -1023,10 +1334,14 @@ export interface SesameStore {
1023
1334
  getDeviceRecord(userId: string, deviceId: number): Promise<DeviceRecord | null>;
1024
1335
  /**
1025
1336
  * Store device record.
1337
+ *
1338
+ * @param options - With `senderKeyHandoffInvalidation`, the same write
1339
+ * deletes the sender-key handoff rows of that device in every group
1026
1340
  */
1027
- setDeviceRecord(userId: string, deviceId: number, record: DeviceRecord): Promise<void>;
1341
+ setDeviceRecord(userId: string, deviceId: number, record: DeviceRecord, options?: SetDeviceRecordOptions): Promise<void>;
1028
1342
  /**
1029
- * Delete device record.
1343
+ * Delete device record. The same write deletes the sender-key handoff rows
1344
+ * of the device in every group.
1030
1345
  */
1031
1346
  deleteDeviceRecord(userId: string, deviceId: number): Promise<void>;
1032
1347
  /**
@@ -1040,7 +1355,10 @@ export interface SesameStore {
1040
1355
  */
1041
1356
  setDeviceSession(userId: string, deviceId: number, session: SessionRecord): Promise<void>;
1042
1357
  /**
1043
- * Delete stale device records (orphaned sessions older than MAXLATENCY).
1358
+ * Delete the stale device records with their sessions. A record is stale
1359
+ * when it has no session and is older than `maxLatency`, or when it is
1360
+ * marked removed and its removal is older than `maxLatency`
1361
+ * (`isExpiredRemovedDevice`). A user record with no device left goes too.
1044
1362
  */
1045
1363
  deleteStaleRecords(maxLatency: number): Promise<number>;
1046
1364
  /**
@@ -1052,10 +1370,82 @@ export interface SesameStore {
1052
1370
  */
1053
1371
  getAllUserIds(): Promise<string[]>;
1054
1372
  /**
1055
- * Get all device IDs for a specific user.
1373
+ * Get all device IDs for a specific user. The list includes the devices
1374
+ * whose record is marked removed. A caller that sends to the devices skips
1375
+ * them with `isRemovedDevice`.
1056
1376
  */
1057
1377
  getSesameDeviceIds(userId: string): Promise<number[]>;
1058
1378
  }
1379
+ /** One device whose recorded sender-key handoffs an event invalidates. */
1380
+ export interface SenderKeyHandoffDevice {
1381
+ userId: string;
1382
+ deviceId: number;
1383
+ }
1384
+ /**
1385
+ * The Relay accepted a distribution of the local device's own sender key for
1386
+ * this recipient device. A row records a handoff. It is never proof that the
1387
+ * recipient installed the key.
1388
+ */
1389
+ export interface SenderKeyHandoffRecord {
1390
+ groupId: string;
1391
+ senderKeyId: string;
1392
+ generation: number;
1393
+ recipientUserId: string;
1394
+ recipientDeviceId: number;
1395
+ /** The registration ID of the recipient's current session when the Relay accepted the post. */
1396
+ recipientRegistrationId: number;
1397
+ acceptedAt: number;
1398
+ }
1399
+ /**
1400
+ * The sender-key handoff ledger of the local device.
1401
+ *
1402
+ * A group send gives the current own sender key to each listed device that
1403
+ * has no row for the current key. The store keeps the rows and deletes them.
1404
+ * It never decides which device needs the key. Rows have no expiry. A row
1405
+ * leaves the store only through an invalidation, a write that replaces or
1406
+ * deletes the own key, a reset of the store, or the sweep at client start.
1407
+ */
1408
+ export interface SenderKeyHandoffStore {
1409
+ /**
1410
+ * Insert or replace the row keyed by group, sender key ID, generation,
1411
+ * recipient user, recipient device, and recipient registration ID.
1412
+ */
1413
+ recordSenderKeyHandoff(record: SenderKeyHandoffRecord): Promise<void>;
1414
+ /** The rows of one group at one generation. */
1415
+ listSenderKeyHandoffs(groupId: string, generation: number): Promise<SenderKeyHandoffRecord[]>;
1416
+ /**
1417
+ * Delete the rows of one device in one group.
1418
+ *
1419
+ * @returns True when at least one row was deleted
1420
+ */
1421
+ invalidateSenderKeyHandoff(groupId: string, device: SenderKeyHandoffDevice): Promise<boolean>;
1422
+ /**
1423
+ * Delete the rows of every device of one account in every group, as an
1424
+ * identity rotation of the account does.
1425
+ *
1426
+ * @returns True when at least one row was deleted
1427
+ */
1428
+ invalidateAccountSenderKeyHandoffs(userId: string): Promise<boolean>;
1429
+ /** The distinct group IDs that hold rows. For the sweep only. */
1430
+ listSenderKeyHandoffGroupIds(): Promise<string[]>;
1431
+ /**
1432
+ * Delete the rows of a group whose sender key ID differs from the given one.
1433
+ * Null deletes every row of the group.
1434
+ *
1435
+ * @returns The number of deleted rows
1436
+ */
1437
+ retainSenderKeyHandoffs(groupId: string, senderKeyId: string | null): Promise<number>;
1438
+ }
1439
+ /** Options for the own-key writes that replace or remove the key. */
1440
+ export interface SenderKeyRecordWriteOptions {
1441
+ /** Delete every sender-key handoff row of the group in the same write. */
1442
+ deleteSenderKeyHandoffs?: true;
1443
+ }
1444
+ /** Options for a device-record write that replaces the current session. */
1445
+ export interface SetDeviceRecordOptions {
1446
+ /** Delete the sender-key handoff rows of this device in every group in the same write. */
1447
+ senderKeyHandoffInvalidation?: SenderKeyHandoffDevice;
1448
+ }
1059
1449
  /**
1060
1450
  * Sender Key store interface for group messaging.
1061
1451
  *
@@ -1073,8 +1463,12 @@ export interface SenderKeyStore {
1073
1463
  getSenderKey(groupId: string, userId: string, deviceId: number): Promise<SenderKeyState | null>;
1074
1464
  /**
1075
1465
  * Delete sender key for a group member device.
1466
+ *
1467
+ * @param options - With `deleteSenderKeyHandoffs`, the same write deletes
1468
+ * every sender-key handoff row of the group. The manager sets it when it
1469
+ * deletes the local device's own key.
1076
1470
  */
1077
- deleteSenderKey(groupId: string, userId: string, deviceId: number): Promise<void>;
1471
+ deleteSenderKey(groupId: string, userId: string, deviceId: number, options?: SenderKeyRecordWriteOptions): Promise<void>;
1078
1472
  /**
1079
1473
  * Resolve the group a sender key belongs to, given only the identifier that
1080
1474
  * travels on the wire.
@@ -1101,8 +1495,9 @@ export interface SenderKeyStore {
1101
1495
  */
1102
1496
  getAllSenderKeysForGroup(groupId: string): Promise<SenderKeyState[]>;
1103
1497
  /**
1104
- * Delete all sender keys and skipped sender message keys for a group (when the caller deletes
1105
- * the group). Returns the number of sender keys deleted.
1498
+ * Delete all sender keys, skipped sender message keys, and sender-key
1499
+ * handoff rows for a group (when the caller deletes the group), in one
1500
+ * write. Returns the number of sender keys deleted.
1106
1501
  */
1107
1502
  deleteAllSenderKeysForGroup(groupId: string): Promise<number>;
1108
1503
  /**
@@ -1120,8 +1515,12 @@ export interface SenderKeyStore {
1120
1515
  * @param userId - User identifier
1121
1516
  * @param deviceId - Device identifier
1122
1517
  * @param states - Array of states (current first, then previous, capped at MAX_SENDER_KEY_STATES)
1518
+ * @param receive - The receive effects to commit with the record
1519
+ * @param options - With `deleteSenderKeyHandoffs`, the same write deletes
1520
+ * every sender-key handoff row of the group. The manager sets it when it
1521
+ * writes a new own key.
1123
1522
  */
1124
- storeSenderKeyRecord(groupId: string, userId: string, deviceId: number, states: SenderKeyState[], receive?: SenderKeyReceiveCommit): Promise<void>;
1523
+ storeSenderKeyRecord(groupId: string, userId: string, deviceId: number, states: SenderKeyState[], receive?: SenderKeyReceiveCommit, options?: SenderKeyRecordWriteOptions): Promise<void>;
1125
1524
  /**
1126
1525
  * Retrieve all sender key states (current + previous) for a group member device.
1127
1526
  *
@@ -1211,7 +1610,11 @@ export interface SkippedSenderMessageKey {
1211
1610
  export interface ProtocolStore extends IdentityKeyStore, EcOneTimePreKeyStore, EcSignedPreKeyStore, KyberLastResortPreKeyStore, KemPreKeyStore, SessionStore {
1212
1611
  /** Atomically pin/match trust, store the session, and consume referenced one-time prekeys. */
1213
1612
  commitSessionTrust(commit: SessionTrustCommit): Promise<void>;
1214
- /** Atomically rotate one per-user identity tuple and delete every bound device session. */
1613
+ /**
1614
+ * Atomically rotate one per-user identity tuple and delete every bound
1615
+ * device session. The same write deletes the sender-key handoff rows of
1616
+ * every device of the account.
1617
+ */
1215
1618
  acceptContactIdentityRotationAndDeleteSessions(address: ProtocolAddress, identity: CompositeIdentityV1, identityType?: IdentityType, suppliedCommitment?: Uint8Array): Promise<ContactIdentityRecord>;
1216
1619
  }
1217
1620
  /**
@@ -1226,10 +1629,51 @@ export interface ProtocolStore extends IdentityKeyStore, EcOneTimePreKeyStore, E
1226
1629
  * This is the interface that local store adapters should implement.
1227
1630
  *
1228
1631
  */
1229
- export interface SignalProtocolLocalStore extends ProtocolStore, SesameStore, SenderKeyStore, MessageRecordStore {
1230
- getReceivedContent(id: string): Promise<ReceivedContent | null>;
1231
- deleteReceivedContent(id: string): Promise<void>;
1232
- deleteExpiredReceivedContent(before: number): Promise<number>;
1632
+ export interface SignalProtocolLocalStore extends ProtocolStore, SesameStore, SenderKeyStore, SenderKeyHandoffStore, MessageRecordStore, SendLogStore {
1633
+ /**
1634
+ * How this store protects its data at rest, and where its key is kept.
1635
+ */
1636
+ readonly protection: LocalStoreProtection;
1637
+ /**
1638
+ * The name of the stored data, the same in every tab, worker, and thread
1639
+ * of the origin that opens that data. When it is set and
1640
+ * `navigator.locks.request` exists, the client takes its session locks and
1641
+ * group-send locks as Web Locks under this name, so those contexts do not
1642
+ * change one session or one sender key at the same time. Without it, the
1643
+ * locks order the clients of one store object in one JavaScript context
1644
+ * only. The web SQLite store and the IndexedDB store give their database
1645
+ * names.
1646
+ */
1647
+ readonly storeIdentity?: string;
1648
+ /** Get one receive record, or null. */
1649
+ getReceiveWork(workId: string): Promise<ReceiveWorkRecord | null>;
1650
+ /**
1651
+ * Write one receive record. With `expectedRevision` null, the write
1652
+ * inserts and fails when a record exists. Otherwise it replaces the record
1653
+ * with that revision. Return false without writing on a mismatch.
1654
+ */
1655
+ putReceiveWork(record: ReceiveWorkRecord, expectedRevision: number | null): Promise<boolean>;
1656
+ /**
1657
+ * List receive records in ascending `(arrivalSeq, workId)` order. The
1658
+ * order compares `workId` values by UTF-16 code unit. With `after`, a
1659
+ * record passes when its `arrivalSeq` is above the cursor `arrivalSeq`,
1660
+ * or equal to it with a `workId` above the cursor `workId`. Return at
1661
+ * most `limit` records, 100 when not set.
1662
+ */
1663
+ listReceiveWork(query?: ReceiveWorkQuery): Promise<ReceiveWorkRecord[]>;
1664
+ /**
1665
+ * Count receive records. With `groupId`, count only the records of that
1666
+ * group that wait for a group update.
1667
+ */
1668
+ receiveWorkUsage(query?: {
1669
+ groupId?: string;
1670
+ }): Promise<ReceiveWorkUsage>;
1671
+ /**
1672
+ * Delete one receive record and apply the metadata writes in one atomic
1673
+ * write. Return false without writing when the stored revision is not
1674
+ * `expectedRevision`.
1675
+ */
1676
+ completeReceiveWork(workId: string, expectedRevision: number, metadata?: readonly ReceiveWorkMetadataWrite[]): Promise<boolean>;
1233
1677
  /**
1234
1678
  * Clear all encryption keys (use with caution!).
1235
1679
  *
@@ -1310,6 +1754,11 @@ export interface SignalProtocolLocalStore extends ProtocolStore, SesameStore, Se
1310
1754
  * It is not a second general-purpose Signal Protocol data store.
1311
1755
  */
1312
1756
  export interface SignalProtocolLocalSecretVault {
1757
+ /**
1758
+ * Where this vault keeps its secrets. A vault that does not declare it
1759
+ * counts as `same-origin`.
1760
+ */
1761
+ readonly custody?: SecretVaultCustody;
1313
1762
  /**
1314
1763
  * Read a named secret from local secure storage.
1315
1764
  */
@@ -1342,7 +1791,11 @@ export interface SignalProtocolLocalSecretVault {
1342
1791
  * > session."
1343
1792
  *
1344
1793
  * The client timestamp assigned before encryption indexes a message.
1345
- * Retry count enforces SESAME's bounded-resend requirement.
1794
+ *
1795
+ * The client keeps a record only when `protocol.contentRecovery` keeps
1796
+ * content, and only for the content retention: 14 days from `createdAt` by
1797
+ * default, at most 30. The record holds no retry count. The client answers
1798
+ * at most `MAX_RETRY_RESPONSES_PER_MESSAGE` retry requests for one message.
1346
1799
  */
1347
1800
  export interface MessageRecord {
1348
1801
  /** Device address (userId:deviceId format) for the recipient device */
@@ -1359,7 +1812,10 @@ export interface MessageRecord {
1359
1812
  recipientDeviceId: number;
1360
1813
  /** Original plaintext message (stored for resending) */
1361
1814
  plaintext: string;
1362
- /** Timestamp when the store created the record */
1815
+ /**
1816
+ * The store clock when the store first wrote the record. Retention reads
1817
+ * this value, so the message timestamp never changes retention.
1818
+ */
1363
1819
  createdAt: number;
1364
1820
  /**
1365
1821
  * Sender's ratchet key (DHs.publicKey) at send time, for retry session matching.
@@ -1379,7 +1835,12 @@ export interface MessageRecord {
1379
1835
  * primary lookup method is getMessageRecord(sessionId, timestamp).
1380
1836
  */
1381
1837
  export interface MessageRecordStore {
1382
- /** Store a message record after encryption */
1838
+ /**
1839
+ * Store a message record after encryption. A record with the same
1840
+ * `sessionId` and `timestamp` is replaced. The store sets `createdAt` from
1841
+ * its clock on the first write and keeps that value on a replace, so the
1842
+ * value in `record` is not stored and a resend does not extend retention.
1843
+ */
1383
1844
  storeMessageRecord(record: MessageRecord): Promise<void>;
1384
1845
  /**
1385
1846
  * Get a message record by session and timestamp (PRIMARY lookup method).
@@ -1390,7 +1851,9 @@ export interface MessageRecordStore {
1390
1851
  /**
1391
1852
  * Delete a message record by session and timestamp.
1392
1853
  *
1393
- * Called when processing delivery receipts to clean up confirmed messages.
1854
+ * The client calls it after an E2EE delivery receipt from the recipient
1855
+ * device, for an expired record at a retry request, and for a record that
1856
+ * it must not resend: a null message, or a sender key distribution alone.
1394
1857
  */
1395
1858
  deleteMessageRecord(sessionId: string, timestamp: number): Promise<void>;
1396
1859
  /** Delete all expired message records older than maxAgeMs */
@@ -1399,6 +1862,188 @@ export interface MessageRecordStore {
1399
1862
  clearAllMessageRecords(): Promise<number>;
1400
1863
  /** Delete all message records for a session */
1401
1864
  deleteMessageRecordsForSession(sessionId: string): Promise<number>;
1865
+ /**
1866
+ * Rewrite the plaintext of each record. `rewrite` returns the plaintext to
1867
+ * keep: the same string leaves the record as it is, another string
1868
+ * replaces the plaintext, and null deletes the record. A replaced record
1869
+ * keeps its `createdAt` and every other field. A record that another
1870
+ * write replaces between the read and the rewrite stays as that write
1871
+ * left it.
1872
+ *
1873
+ * @returns The number of records replaced or deleted
1874
+ */
1875
+ rewriteMessageRecords(rewrite: (record: MessageRecord) => string | null): Promise<number>;
1876
+ }
1877
+ /**
1878
+ * One device that a logged message was sent to. The device can request the
1879
+ * content again with a retry request.
1880
+ */
1881
+ export interface SendLogDevice {
1882
+ userId: string;
1883
+ deviceId: number;
1884
+ }
1885
+ /**
1886
+ * The content of one group send, kept for a resend to a device that could
1887
+ * not decrypt it. `clientMessageId` identifies the send. It is the Relay
1888
+ * operation ID of the group post.
1889
+ */
1890
+ export interface SendLogPayload {
1891
+ clientMessageId: string;
1892
+ groupId: string;
1893
+ /** The client timestamp of the send, which a retry request names. */
1894
+ clientTimestamp: number;
1895
+ contentHint: ContentHint;
1896
+ /** The plaintext content of the send. */
1897
+ plaintext: Uint8Array;
1898
+ /**
1899
+ * The store clock when the store wrote the entry. Retention reads this
1900
+ * value, so an application-supplied timestamp never changes retention.
1901
+ */
1902
+ createdAt: number;
1903
+ /**
1904
+ * True after the send finished. A payload with no remaining recipient is
1905
+ * deleted only after the send finished, so a send in progress can still
1906
+ * add recipients.
1907
+ */
1908
+ sendComplete: boolean;
1909
+ }
1910
+ /** The content of a new send log entry. The store sets the other fields. */
1911
+ export type NewSendLogPayload = Omit<SendLogPayload, 'createdAt' | 'sendComplete'>;
1912
+ /**
1913
+ * One device that has not confirmed a logged send. The row authorizes a
1914
+ * resend to this exact device.
1915
+ */
1916
+ export interface SendLogRecipient extends SendLogDevice {
1917
+ clientMessageId: string;
1918
+ /** The client timestamp of the send. A copy of the payload value, for lookup. */
1919
+ clientTimestamp: number;
1920
+ /** The number of resends to this device. It survives a restart. */
1921
+ responses: number;
1922
+ }
1923
+ /** A logged payload and the row of one recipient device. */
1924
+ export interface SendLogEntry {
1925
+ payload: SendLogPayload;
1926
+ recipient: SendLogRecipient;
1927
+ }
1928
+ /** The state of a resend job. Only a `pending` job runs. */
1929
+ export type SendLogResendJobState = 'pending' | 'posted' | 'abandoned';
1930
+ /**
1931
+ * A persisted resend of logged content to one requesting device. A job
1932
+ * holds no plaintext. It names the logged entry.
1933
+ */
1934
+ export interface SendLogResendJob {
1935
+ jobId: string;
1936
+ clientMessageId: string;
1937
+ requesterUserId: string;
1938
+ requesterDeviceId: number;
1939
+ /** The retry attempt ID of the request. */
1940
+ retryId: string;
1941
+ /** The Relay envelope ID of the retry request. */
1942
+ requestEnvelopeId: string;
1943
+ /**
1944
+ * The envelope that the requester could not decrypt. Only the job whose
1945
+ * resend answers the request attempt has it: when written, the job of
1946
+ * the first logged entry that the request names, and at the post, the
1947
+ * job of the first entry that the answer admits. Another job has none,
1948
+ * and its resend posts under a new ID.
1949
+ */
1950
+ failedEnvelopeId?: string;
1951
+ /** The store clock when the job was first written. */
1952
+ createdAt: number;
1953
+ attempts: number;
1954
+ state: SendLogResendJobState;
1955
+ }
1956
+ /**
1957
+ * Storage of resendable group content.
1958
+ *
1959
+ * The send log keeps the plaintext of each resendable group send with a row
1960
+ * for each recipient device, until that device confirms the message or the
1961
+ * entry expires. A recipient device that cannot decrypt the message asks
1962
+ * for it again, and only a device with a row gets the content.
1963
+ */
1964
+ export interface SendLogStore {
1965
+ /**
1966
+ * Store a send log entry and its recipient rows in one transaction. An
1967
+ * entry with the same `clientMessageId` is replaced with its rows.
1968
+ */
1969
+ storeSendLogEntry(payload: NewSendLogPayload, recipients: readonly SendLogDevice[]): Promise<void>;
1970
+ /**
1971
+ * Add recipient rows to an entry. An existing row is kept unchanged. With
1972
+ * no entry, nothing is written.
1973
+ */
1974
+ appendSendLogRecipients(clientMessageId: string, recipients: readonly SendLogDevice[]): Promise<void>;
1975
+ /**
1976
+ * Mark the send finished. When no recipient row remains, the payload is
1977
+ * deleted.
1978
+ */
1979
+ markSendLogComplete(clientMessageId: string): Promise<void>;
1980
+ /** The entry of one send for one device, or null when the device has no row. */
1981
+ getSendLogEntry(clientMessageId: string, recipient: SendLogDevice): Promise<SendLogEntry | null>;
1982
+ /** Every entry for one device at one client timestamp, ordered by `clientMessageId`. */
1983
+ findSendLogEntries(recipient: SendLogDevice, clientTimestamp: number): Promise<SendLogEntry[]>;
1984
+ /** The remaining recipient rows of one send, ordered by user and device. */
1985
+ getSendLogRecipients(clientMessageId: string): Promise<SendLogRecipient[]>;
1986
+ /**
1987
+ * Delete the row of one device. When no row remains and the send is
1988
+ * finished, the payload is deleted. Returns true when a row was deleted.
1989
+ */
1990
+ deleteSendLogRecipient(clientMessageId: string, recipient: SendLogDevice): Promise<boolean>;
1991
+ /**
1992
+ * Delete the rows of one device at each of the client timestamps, with the
1993
+ * same payload rule as `deleteSendLogRecipient`. Returns the number of
1994
+ * deleted rows.
1995
+ */
1996
+ deleteSendLogRecipientsByTimestamp(recipient: SendLogDevice, clientTimestamps: readonly number[]): Promise<number>;
1997
+ /**
1998
+ * Add one to the resend count of a row. Returns the new count, or null
1999
+ * when the device has no row.
2000
+ */
2001
+ incrementSendLogResendCount(clientMessageId: string, recipient: SendLogDevice): Promise<number | null>;
2002
+ /** Delete one entry and its rows. Returns true when an entry was deleted. */
2003
+ deleteSendLogEntry(clientMessageId: string): Promise<boolean>;
2004
+ /**
2005
+ * Delete each entry, and each resend job, that the store wrote more than
2006
+ * `maxAgeMs` ago. Returns the number of deleted entries.
2007
+ */
2008
+ deleteExpiredSendLog(maxAgeMs: number): Promise<number>;
2009
+ /** Delete every entry and resend job. Returns the number of deleted entries. */
2010
+ clearSendLog(): Promise<number>;
2011
+ /**
2012
+ * Store a resend job. A job with the same `jobId` is replaced. The store
2013
+ * sets `createdAt` from its clock on the first write and keeps that value
2014
+ * on a replace, so the value in `job` is not stored.
2015
+ */
2016
+ storeResendJob(job: SendLogResendJob): Promise<void>;
2017
+ /** One resend job, or null. */
2018
+ getResendJob(jobId: string): Promise<SendLogResendJob | null>;
2019
+ /** Every `pending` resend job, ordered by `createdAt`, then `jobId`. */
2020
+ getPendingResendJobs(): Promise<SendLogResendJob[]>;
2021
+ /** Set the final state of a resend job. With no job, nothing is written. */
2022
+ completeResendJob(jobId: string, state: Exclude<SendLogResendJobState, 'pending'>): Promise<void>;
2023
+ }
2024
+ /**
2025
+ * How a local store encrypts its data at rest.
2026
+ *
2027
+ * - `file-cipher`: the database file is encrypted, as with SQLCipher.
2028
+ * - `record-cipher`: each stored value is encrypted.
2029
+ * - `none`: the data is stored in the clear.
2030
+ */
2031
+ export type LocalStoreAtRest = 'file-cipher' | 'record-cipher' | 'none';
2032
+ /**
2033
+ * Where the key of a secret vault is kept.
2034
+ *
2035
+ * - `os-keychain`: the operating system keychain or keystore.
2036
+ * - `app-vault`: a vault that the application controls and declares.
2037
+ * - `same-origin`: storage that the data shares, such as the same browser
2038
+ * origin.
2039
+ */
2040
+ export type SecretVaultCustody = 'os-keychain' | 'app-vault' | 'same-origin';
2041
+ /** Where the key of a local store is kept. `none` means there is no key. */
2042
+ export type LocalStoreKeyCustody = SecretVaultCustody | 'none';
2043
+ /** The protection of the data in a local store. */
2044
+ export interface LocalStoreProtection {
2045
+ readonly atRest: LocalStoreAtRest;
2046
+ readonly keyCustody: LocalStoreKeyCustody;
1402
2047
  }
1403
2048
  export type { GroupStateStore, GroupServer, GroupSnapshot, GroupChangeLogEntry, } from '../internal/groups/manager.js';
1404
2049
  //# sourceMappingURL=api.d.ts.map