@open-e2ee/signal-protocol-sdk 11.0.0 → 12.0.1

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 (590) hide show
  1. package/ADAPTERS.md +4 -4
  2. package/ARCHITECTURE.md +6 -8
  3. package/CHANGELOG.md +1348 -0
  4. package/README.md +1 -1
  5. package/SECURITY.md +2 -2
  6. package/TROUBLESHOOTING.md +8 -8
  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 +1175 -186
  12. package/dist/client/client.js.map +1 -1
  13. package/dist/client/config.d.ts +57 -42
  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 +26 -20
  251. package/dist/internal/manager/manager.d.ts.map +1 -1
  252. package/dist/internal/manager/manager.js +64 -41
  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 +15 -13
  313. package/dist/internal/session/cipher.d.ts.map +1 -1
  314. package/dist/internal/session/cipher.js +41 -23
  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 +5 -13
  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/driver.d.ts +9 -0
  416. package/dist/local/store/sqlite/driver.d.ts.map +1 -1
  417. package/dist/local/store/sqlite/encryption.d.ts +8 -1
  418. package/dist/local/store/sqlite/encryption.d.ts.map +1 -1
  419. package/dist/local/store/sqlite/encryption.js +9 -0
  420. package/dist/local/store/sqlite/encryption.js.map +1 -1
  421. package/dist/local/store/sqlite/key-storage/index.d.ts +25 -4
  422. package/dist/local/store/sqlite/key-storage/index.d.ts.map +1 -1
  423. package/dist/local/store/sqlite/key-storage/index.js +68 -7
  424. package/dist/local/store/sqlite/key-storage/index.js.map +1 -1
  425. package/dist/local/store/sqlite/key-storage/message-records.d.ts +16 -4
  426. package/dist/local/store/sqlite/key-storage/message-records.d.ts.map +1 -1
  427. package/dist/local/store/sqlite/key-storage/message-records.js +49 -6
  428. package/dist/local/store/sqlite/key-storage/message-records.js.map +1 -1
  429. package/dist/local/store/sqlite/key-storage/metadata.d.ts +8 -7
  430. package/dist/local/store/sqlite/key-storage/metadata.d.ts.map +1 -1
  431. package/dist/local/store/sqlite/key-storage/metadata.js +17 -15
  432. package/dist/local/store/sqlite/key-storage/metadata.js.map +1 -1
  433. package/dist/local/store/sqlite/key-storage/receive-work.d.ts +27 -0
  434. package/dist/local/store/sqlite/key-storage/receive-work.d.ts.map +1 -0
  435. package/dist/local/store/sqlite/key-storage/receive-work.js +98 -0
  436. package/dist/local/store/sqlite/key-storage/receive-work.js.map +1 -0
  437. package/dist/local/store/sqlite/key-storage/send-log.d.ts +27 -0
  438. package/dist/local/store/sqlite/key-storage/send-log.d.ts.map +1 -0
  439. package/dist/local/store/sqlite/key-storage/send-log.js +178 -0
  440. package/dist/local/store/sqlite/key-storage/send-log.js.map +1 -0
  441. package/dist/local/store/sqlite/key-storage/sender-key-handoff.d.ts +27 -0
  442. package/dist/local/store/sqlite/key-storage/sender-key-handoff.d.ts.map +1 -0
  443. package/dist/local/store/sqlite/key-storage/sender-key-handoff.js +75 -0
  444. package/dist/local/store/sqlite/key-storage/sender-key-handoff.js.map +1 -0
  445. package/dist/local/store/sqlite/key-storage/session-trust.d.ts +2 -2
  446. package/dist/local/store/sqlite/key-storage/session-trust.js +5 -5
  447. package/dist/local/store/sqlite/key-storage/session-trust.js.map +1 -1
  448. package/dist/local/store/sqlite/migrations.d.ts.map +1 -1
  449. package/dist/local/store/sqlite/migrations.js +101 -0
  450. package/dist/local/store/sqlite/migrations.js.map +1 -1
  451. package/dist/local/store/sqlite/models/index.d.ts +2 -1
  452. package/dist/local/store/sqlite/models/index.d.ts.map +1 -1
  453. package/dist/local/store/sqlite/models/index.js +5 -1
  454. package/dist/local/store/sqlite/models/index.js.map +1 -1
  455. package/dist/local/store/sqlite/models/message-record.d.ts +15 -0
  456. package/dist/local/store/sqlite/models/message-record.d.ts.map +1 -1
  457. package/dist/local/store/sqlite/models/message-record.js +24 -0
  458. package/dist/local/store/sqlite/models/message-record.js.map +1 -1
  459. package/dist/local/store/sqlite/models/send-log.d.ts +51 -0
  460. package/dist/local/store/sqlite/models/send-log.d.ts.map +1 -0
  461. package/dist/local/store/sqlite/models/send-log.js +206 -0
  462. package/dist/local/store/sqlite/models/send-log.js.map +1 -0
  463. package/dist/local/store/sqlite/open-store.d.ts +9 -1
  464. package/dist/local/store/sqlite/open-store.d.ts.map +1 -1
  465. package/dist/local/store/sqlite/open-store.js +20 -1
  466. package/dist/local/store/sqlite/open-store.js.map +1 -1
  467. package/dist/local/store/sqlite/schema.d.ts +34 -1
  468. package/dist/local/store/sqlite/schema.d.ts.map +1 -1
  469. package/dist/local/store/sqlite/schema.js +14 -0
  470. package/dist/local/store/sqlite/schema.js.map +1 -1
  471. package/dist/local/store/sqlite/store.d.ts +61 -11
  472. package/dist/local/store/sqlite/store.d.ts.map +1 -1
  473. package/dist/local/store/sqlite/store.js +191 -27
  474. package/dist/local/store/sqlite/store.js.map +1 -1
  475. package/dist/local/store/sqlite/web/sqlite3mc/sqlite3.mjs +2 -1
  476. package/dist/local/store/sqlite/web/worker.d.ts +8 -0
  477. package/dist/local/store/sqlite/web/worker.d.ts.map +1 -1
  478. package/dist/local/store/sqlite/web/worker.js +64 -2
  479. package/dist/local/store/sqlite/web/worker.js.map +1 -1
  480. package/dist/local/store/web/adapter.d.ts +76 -8
  481. package/dist/local/store/web/adapter.d.ts.map +1 -1
  482. package/dist/local/store/web/adapter.js +579 -127
  483. package/dist/local/store/web/adapter.js.map +1 -1
  484. package/dist/local/store/web/receive-work.d.ts +57 -0
  485. package/dist/local/store/web/receive-work.d.ts.map +1 -0
  486. package/dist/local/store/web/receive-work.js +99 -0
  487. package/dist/local/store/web/receive-work.js.map +1 -0
  488. package/dist/local/store/web/send-log.d.ts +92 -0
  489. package/dist/local/store/web/send-log.d.ts.map +1 -0
  490. package/dist/local/store/web/send-log.js +267 -0
  491. package/dist/local/store/web/send-log.js.map +1 -0
  492. package/dist/local/store/web/sender-key-handoff.d.ts +81 -0
  493. package/dist/local/store/web/sender-key-handoff.d.ts.map +1 -0
  494. package/dist/local/store/web/sender-key-handoff.js +156 -0
  495. package/dist/local/store/web/sender-key-handoff.js.map +1 -0
  496. package/dist/local/store/web-sqlite/adapter.d.ts +2 -0
  497. package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
  498. package/dist/local/store/web-sqlite/adapter.js +12 -6
  499. package/dist/local/store/web-sqlite/adapter.js.map +1 -1
  500. package/dist/local/vault/custody.d.ts +8 -0
  501. package/dist/local/vault/custody.d.ts.map +1 -0
  502. package/dist/local/vault/custody.js +9 -0
  503. package/dist/local/vault/custody.js.map +1 -0
  504. package/dist/local/vault/electron-safe-storage.d.ts +3 -1
  505. package/dist/local/vault/electron-safe-storage.d.ts.map +1 -1
  506. package/dist/local/vault/electron-safe-storage.js +2 -0
  507. package/dist/local/vault/electron-safe-storage.js.map +1 -1
  508. package/dist/local/vault/expo-secure-store.d.ts +3 -1
  509. package/dist/local/vault/expo-secure-store.d.ts.map +1 -1
  510. package/dist/local/vault/expo-secure-store.js +2 -0
  511. package/dist/local/vault/expo-secure-store.js.map +1 -1
  512. package/dist/local/vault/indexed-db.d.ts +3 -1
  513. package/dist/local/vault/indexed-db.d.ts.map +1 -1
  514. package/dist/local/vault/indexed-db.js +2 -0
  515. package/dist/local/vault/indexed-db.js.map +1 -1
  516. package/dist/local/vault/react-native-keychain.d.ts +3 -1
  517. package/dist/local/vault/react-native-keychain.d.ts.map +1 -1
  518. package/dist/local/vault/react-native-keychain.js +2 -0
  519. package/dist/local/vault/react-native-keychain.js.map +1 -1
  520. package/dist/remote/relay/device-set.d.ts +94 -0
  521. package/dist/remote/relay/device-set.d.ts.map +1 -0
  522. package/dist/remote/relay/device-set.js +156 -0
  523. package/dist/remote/relay/device-set.js.map +1 -0
  524. package/dist/remote/relay/types.d.ts +92 -107
  525. package/dist/remote/relay/types.d.ts.map +1 -1
  526. package/dist/safety/core.d.ts +15 -6
  527. package/dist/safety/core.d.ts.map +1 -1
  528. package/dist/safety/core.js +41 -27
  529. package/dist/safety/core.js.map +1 -1
  530. package/dist/safety/index.d.ts +2 -1
  531. package/dist/safety/index.d.ts.map +1 -1
  532. package/dist/safety/index.js +12 -18
  533. package/dist/safety/index.js.map +1 -1
  534. package/dist/types/api.d.ts +707 -62
  535. package/dist/types/api.d.ts.map +1 -1
  536. package/dist/types/errors.d.ts +14 -33
  537. package/dist/types/errors.d.ts.map +1 -1
  538. package/dist/types/errors.js +14 -24
  539. package/dist/types/errors.js.map +1 -1
  540. package/dist/types/messages.d.ts +2 -2
  541. package/dist/types/messages.js +1 -1
  542. package/dist/types/protocol-config.d.ts +175 -42
  543. package/dist/types/protocol-config.d.ts.map +1 -1
  544. package/dist/types/protocol-config.js +19 -38
  545. package/dist/types/protocol-config.js.map +1 -1
  546. package/dist/types/protocol-constants.d.ts +6 -6
  547. package/dist/types/protocol-constants.js +6 -6
  548. package/dist/types/session.d.ts +7 -7
  549. package/dist/types/session.d.ts.map +1 -1
  550. package/dist/types/session.js +39 -21
  551. package/dist/types/session.js.map +1 -1
  552. package/dist/username/link.d.ts +2 -2
  553. package/dist/username/link.js +2 -2
  554. package/dist/utils/origin-lock.d.ts +45 -0
  555. package/dist/utils/origin-lock.d.ts.map +1 -0
  556. package/dist/utils/origin-lock.js +80 -0
  557. package/dist/utils/origin-lock.js.map +1 -0
  558. package/docs/ASSURANCE.md +6 -6
  559. package/docs/CLIENT_COMPOSITION.md +2 -2
  560. package/docs/DEVIATIONS.md +677 -182
  561. package/docs/E2EE.md +1 -1
  562. package/docs/ERROR_HANDLING.md +165 -2
  563. package/docs/GETTING_STARTED.md +7 -4
  564. package/docs/INTERFACES.md +1 -1
  565. package/docs/PACKAGE_SURFACE.md +6 -5
  566. package/docs/PROTOCOL_POLICY.md +102 -22
  567. package/docs/RECIPES.md +3 -15
  568. package/docs/SECURITY.md +90 -5
  569. package/keys/README.md +3 -3
  570. package/local/store/README.md +78 -14
  571. package/local/store/key-value/README.md +14 -3
  572. package/local/store/node/README.md +8 -3
  573. package/local/store/web/README.md +9 -0
  574. package/local/store/web-sqlite/README.md +14 -2
  575. package/local/vault/README.md +21 -0
  576. package/package.json +1 -6
  577. package/remote/README.md +0 -1
  578. package/remote/relay/README.md +2 -2
  579. package/dist/device/provisioning.d.ts +0 -242
  580. package/dist/device/provisioning.d.ts.map +0 -1
  581. package/dist/device/provisioning.js +0 -421
  582. package/dist/device/provisioning.js.map +0 -1
  583. package/dist/internal/protocol/x3dh/index.d.ts +0 -15
  584. package/dist/internal/protocol/x3dh/index.d.ts.map +0 -1
  585. package/dist/internal/protocol/x3dh/index.js +0 -13
  586. package/dist/internal/protocol/x3dh/index.js.map +0 -1
  587. package/dist/internal/protocol/x3dh/x3dh.d.ts +0 -131
  588. package/dist/internal/protocol/x3dh/x3dh.d.ts.map +0 -1
  589. package/dist/internal/protocol/x3dh/x3dh.js +0 -261
  590. package/dist/internal/protocol/x3dh/x3dh.js.map +0 -1
package/README.md CHANGED
@@ -39,7 +39,7 @@ The relay never needs message plaintext or device private keys.
39
39
 
40
40
  The OpenE2EE Signal Protocol SDK implements a versioned profile of the published Signal Protocol specifications. It is not affiliated with Signal Messenger and is **not wire-compatible with Signal Messenger or libsignal**. Messages, identities, and safety numbers do not interoperate. See the [notice](./NOTICE) and [documented deviations](./docs/DEVIATIONS.md).
41
41
 
42
- Version `11.0.x`. Public APIs and persisted formats follow semantic versioning.
42
+ Version `12.0.x`. Public APIs and persisted formats follow semantic versioning.
43
43
 
44
44
  ## Install
45
45
 
package/SECURITY.md CHANGED
@@ -7,8 +7,8 @@ backports.
7
7
 
8
8
  | Version | Supported |
9
9
  | -------- | ------------------ |
10
- | 11.0.x | :white_check_mark: |
11
- | < 11.0.0 | :x: |
10
+ | 12.0.x | :white_check_mark: |
11
+ | < 12.0.0 | :x: |
12
12
 
13
13
  ## Reporting a Vulnerability
14
14
 
@@ -110,7 +110,7 @@ await signal.encryptMessage('bob:2', 'Hello'); // Secondary device
110
110
  The protocol handles out-of-order messages automatically via MKSKIPPED. For failures:
111
111
 
112
112
  1. Check that both parties established sessions
113
- 2. Verify message counters are not too far apart (maxSkip limit: 1000)
113
+ 2. Verify message counters are not too far apart (default `maxSkip` limit: 25000)
114
114
  3. Check that no sender or transport duplicates messages
115
115
  4. Check that skipped keys did not expire (7-day default)
116
116
 
@@ -118,12 +118,12 @@ The protocol handles out-of-order messages automatically via MKSKIPPED. For fail
118
118
 
119
119
  **"Failed to decrypt" or "MAC verification failed"**
120
120
 
121
- | Symptom | Cause | Solution |
122
- | ----------- | ----------------------- | ------------------------------------------------ |
123
- | MAC failed | Data corrupted | Check network, verify no modification in transit |
124
- | Wrong key | Session mismatch | Verify sessionId matches sender |
125
- | Key expired | Message > 7 days old | Cannot recover; re-send message |
126
- | Counter gap | > 1000 messages skipped | Increase `maxSkip` or re-establish session |
121
+ | Symptom | Cause | Solution |
122
+ | ----------- | ------------------------ | ------------------------------------------------ |
123
+ | MAC failed | Data corrupted | Check network, verify no modification in transit |
124
+ | Wrong key | Session mismatch | Verify sessionId matches sender |
125
+ | Key expired | Message > 7 days old | Cannot recover; re-send message |
126
+ | Counter gap | > 25000 messages skipped | Increase `maxSkip` or re-establish session |
127
127
 
128
128
  ---
129
129
 
@@ -178,7 +178,7 @@ await signal.confirmSafetyNumber(safetyNumber.confirmation);
178
178
  | ------------------------- | ------------------- |
179
179
  | Key generation | `internal/crypto/` |
180
180
  | Key types, bundles | `keys/` |
181
- | Key exchange (X3DH/PQXDH) | `internal/protocol/` |
181
+ | Key exchange (PQXDH) | `internal/protocol/` |
182
182
  | Ratchet state | `internal/protocol/` |
183
183
  | Session state | `internal/session/` |
184
184
  | Multi-device | `internal/sesame/` |
package/client/README.md CHANGED
@@ -93,18 +93,10 @@ await createSignalProtocolClient({
93
93
  });
94
94
  ```
95
95
 
96
- `postQuantum: 'required'` and `braid: 'required'` are the defaults. Use
97
- `compatible` only for an explicit product decision to support peers that
98
- publish no post-quantum material:
99
-
100
- <!-- doc-snippet:skip requires-external-context -->
101
- ```ts
102
- await createSignalProtocolClient({
103
- identity: { userId },
104
- adapters: { storage, relay },
105
- protocol: { postQuantum: 'compatible', braid: 'required' },
106
- });
107
- ```
96
+ `postQuantum: 'required'` and `braid: 'required'` are the defaults.
97
+ `'required'` is the only `postQuantum` value. The SDK has no classical key
98
+ agreement, so a session with a peer that publishes no ML-KEM prekeys fails
99
+ with `PQXDHRequiredError` (`PQXDH_REQUIRED`).
108
100
 
109
101
  Use direct SPQR only as an explicit product-reviewed escape hatch:
110
102
 
@@ -173,26 +165,57 @@ const rotation = await signal.rotatePreKeys();
173
165
 
174
166
  Register `onMessageDecrypted` before calling `pullHostedRelayAfterWake()`.
175
167
  The handler must persist application content before it resolves. Use the message
176
- ID for idempotent application writes. A rejected handler leaves the envelope
177
- unacknowledged.
178
-
179
- The hosted pull uses the same content handler as the foreground subscription.
180
- It installs pairwise sender-key distributions only for members of the verified
181
- local group. It handles receipts and typing separately from application messages.
182
- Successful content receipts permit acknowledgment retries without decryption.
183
-
184
- The device-local store commits recoverable content with the ratchet update or
185
- skipped-key consumption. A restart can resume the application write from that
186
- encrypted record without sender retransmission. The SDK deletes the content
187
- after a successful processing receipt. Retry cleanup removes abandoned records
188
- after the existing thirty-day retry horizon.
189
-
190
- The application handler can run again if its write succeeds but the processing
191
- receipt fails. Use the message ID to prevent duplicate application records.
192
- Recovery rejects changes to the envelope identity or ciphertext.
193
-
194
- `processIncomingEnvelopes()` remains a lower-level decryption API. It returns
195
- plaintext to its caller. It does not run the application handler.
168
+ ID for idempotent application writes.
169
+
170
+ The hosted pull uses the same receive path as the foreground subscription. The
171
+ client decrypts each envelope and commits its content as a receive record with
172
+ the ratchet update or skipped-key consumption. It acknowledges the envelope only
173
+ after that commit. The receive queue then decides the group of the content,
174
+ gives the content to the handler, sends the E2EE delivery receipt, and deletes
175
+ the record. The E2EE receipt is the only proof that the application processed
176
+ the content. A Relay delivery receipt marks only the handoff to the device.
177
+ Content that waits for its group state stays on the device. A waiting record
178
+ holds back the later content of its conversation only. Group content waits by
179
+ its group, a sent transcript by its destination, and other content by its
180
+ sender account. A restart resumes the record with no sender retransmission. A
181
+ rejected handler runs again after a backoff. After 10 attempts, the record no
182
+ longer holds back the later content of its conversation. Each start then gives
183
+ it to the handler once, in the start pass or when `onMessageDecrypted` is
184
+ registered. After that, only `processPendingReceives` runs it again before the
185
+ next start. A pass that ends before the retry, at a deadline or at a failed
186
+ page read, leaves the retry to the next pass. That retry runs after the other
187
+ content of the pass, so a hook call that ends the process on it does not stop
188
+ the later content of its conversation. `listPendingReceives` gives the
189
+ `hookAttempts` of each record. `discardPendingReceive` removes a record that
190
+ the application cannot process, with no receipt, no handler call, and no
191
+ expiry report.
192
+
193
+ A receive pass waits for each hook for at most
194
+ `protocol.receiveQueue.receiveHookTimeoutMs`, 2 minutes by default. A timeout
195
+ of `onMessageDecrypted` counts as one failed attempt. A handler that settles
196
+ after the bound writes nothing. Content that waits
197
+ 30 days on the device runs `onReceiveExpired`, and the client deletes its
198
+ record. The 30 days are fixed. Before the hook, the
199
+ client reads the record again. Content that the client completed before that
200
+ read, such as at the redelivery of its envelope, gets no expiry report. A
201
+ record that waits only for its E2EE delivery receipt completes 1 day after the
202
+ receipt becomes due, with no receipt and no expiry report.
203
+
204
+ At a receive queue bound, the client decrypts nothing more and does not
205
+ acknowledge the envelope, so the Relay keeps it. A refused envelope expires at
206
+ the Relay at the TTL of the Relay project, and no local hook reports that
207
+ expiry. While the mailbox of the device is full, the Relay refuses a new message
208
+ to it with `MAILBOX_FULL` to its sender. Refused envelopes do not stop the
209
+ messages behind them, on the socket or on an HTTP pull.
210
+ The client handles receipts and typing separately from application messages.
211
+
212
+ The handler can run again if its write succeeds but the record does not
213
+ complete. Use the message ID to prevent duplicate application records.
214
+
215
+ `processIncomingEnvelopes()` is the receive helper for an application that pulls
216
+ envelopes itself. It returns a receive outcome for each envelope and does not run
217
+ the application handler. A `processed` receive keeps its content until the
218
+ application calls `completeReceive()`.
196
219
 
197
220
  ### Delivery receipts
198
221
 
@@ -210,8 +233,10 @@ With `'auto'` on the Signal Protocol Relay, the client sends no end-to-end
210
233
  receipt for an identified message that the Relay acknowledgment lists as
211
234
  receipted. On any other relay, `'auto'` sends the same receipts as `'always'`.
212
235
  `DecryptedEnvelope.arrivedSealed` tells whether a message arrived through sealed
213
- sender. The client seals a receipt when it holds the access key of the sender,
214
- and sends it identified otherwise. Read receipts are not affected.
236
+ sender. The client seals a receipt when it holds the access key of the sender.
237
+ Otherwise it sends the receipt identified only when the `deliveryMode` of
238
+ `sealedSender` permits it, and `'required'` sends no identified receipt. A
239
+ retry request follows the same rule. Read receipts are not affected.
215
240
 
216
241
  The sender gets each receipt through the `onDelivered` hook, once for each
217
242
  source and recipient device:
@@ -223,8 +248,16 @@ source and recipient device:
223
248
 
224
249
  The status of a device only moves forward. `sources` holds each source that the
225
250
  device has given so far, so an `'e2ee'` event after a `'relay'` event carries
226
- both. A second receipt of the same source changes nothing. A receipt for a send
227
- that has not resolved yet comes after the send resolves.
251
+ both. A receipt for a send that has not resolved yet comes after the send
252
+ resolves.
253
+
254
+ The hook runs at least once for each source. The client marks a source
255
+ announced only after the hook returns. A hook that throws, a `stop()` during the
256
+ hook, or a crash leaves the source unannounced. An error from the hook fails the
257
+ receipt, so the relay delivers it again, and the hook runs again with the next
258
+ receipt for the message. A second receipt of the same source after the hook
259
+ returned changes nothing. Make the hook idempotent for one `clientMessageId`,
260
+ `recipientDeviceId`, and `source`.
228
261
 
229
262
  The sender keeps a copy of each message that it sends, plaintext included, so
230
263
  that it can send the message again when the recipient asks for a retry. An
@@ -308,7 +341,7 @@ const result = await rotateKeysHeadless(relay, userId, deviceId, { storage });
308
341
 
309
342
  - device `1` is the primary device
310
343
  - linked devices use device IDs `2-5`
311
- - provision linked-device identity material into the provided storage before `DefaultSignalProtocolClient.create(..., { deviceId: 2 })`
344
+ - put the account identity into the linked device's storage by device transfer or by a channel that the application owns before `DefaultSignalProtocolClient.create(..., { deviceId: 2 })`
312
345
 
313
346
  ## Notes
314
347
 
package/device/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Device Lifecycle, Linking, and Transfer
2
2
 
3
3
  The device module contains the platform-bound workflows for device identity,
4
- registration, QR-based account linking, device-name encryption, and encrypted
5
- device-to-device state transfer.
4
+ registration, device-name encryption, and encrypted device-to-device state
5
+ transfer.
6
6
 
7
7
  ## Why it exists
8
8
 
@@ -10,13 +10,17 @@ Signal Protocol sessions address individual devices. The application therefore
10
10
  needs a lifecycle that coordinates a locally persisted device ID with the
11
11
  authenticated backend's device registry.
12
12
 
13
- The two onboarding operations are deliberately separate:
13
+ A linked device needs the account identity before it joins the account. Two
14
+ separate operations do that work:
14
15
 
15
- - **Provisioning** adds a linked device. It transfers account identity material
16
- and optional account metadata, but not existing sessions or message history.
17
- - **Transfer** sends the same identity-only provisioning bundle over an
18
- application-owned encrypted device-to-device channel. The receiving device
19
- generates fresh prekeys and sessions after import.
16
+ - **Transfer** sends an identity-only bundle over an application-owned
17
+ encrypted device-to-device channel. The receiving device generates fresh
18
+ prekeys and sessions after import. The application can also put the account
19
+ identity into the new device's store by a channel that it owns.
20
+ - **The managed device link** is `linkHostedRelayDevice()` from the package
21
+ root. It joins a store that already holds the account identity to the Relay
22
+ account. It runs in one process that holds the active device's store and the
23
+ new device's store. It sends no private key to the Relay.
20
24
 
21
25
  The primary device uses ID `1`. The backend allocates linked device IDs from
22
26
  `2` through `5`. A client must not choose its own linked-device ID.
@@ -92,82 +96,31 @@ it only after preload or in code that can safely tolerate that fallback.
92
96
 
93
97
  ## Link a device
94
98
 
95
- The primary device creates a short-lived provisioning session:
99
+ Put the account identity into the new device's store first, by device transfer
100
+ or by a channel that the application owns. Then join the new device to the
101
+ Relay account:
96
102
 
97
103
  <!-- doc-snippet:skip requires-external-context -->
98
104
  ```ts
99
- import {
100
- generateProvisioningQR,
101
- provisionDevice,
102
- } from "@open-e2ee/signal-protocol-sdk/device/provisioning";
103
-
104
- const {
105
- sessionId,
106
- qrCodeUrl,
107
- ephemeralKeyPair,
108
- } = await generateProvisioningQR(relay, userId);
109
-
110
- await appQr.show(qrCodeUrl);
111
-
112
- const { newDeviceEphemeralPublicKey } =
113
- await appProvisioning.waitForLinkedDevice(sessionId);
114
-
115
- await provisionDevice(
116
- relay,
117
- appProfile,
118
- sessionId,
119
- ephemeralKeyPair.privateKey,
120
- newDeviceEphemeralPublicKey,
121
- userId,
122
- { identityStore, groupStateStore },
123
- );
124
- ```
105
+ import { linkHostedRelayDevice } from "@open-e2ee/signal-protocol-sdk";
125
106
 
126
- The new device parses the QR data, joins the session, and then receives,
127
- decrypts, and stores the provisioning message:
128
-
129
- <!-- doc-snippet:skip requires-external-context -->
130
- ```ts
131
- import {
132
- connectToProvisioningSession,
133
- parseProvisioningQR,
134
- receiveProvisioningMessage,
135
- } from "@open-e2ee/signal-protocol-sdk/device/provisioning";
136
- // Reads the local platform, so it is imported separately from the protocol
137
- // itself. Use `./device/react-native` off Expo, or build the fields by hand.
138
- import { getDeviceMetadata } from "@open-e2ee/signal-protocol-sdk/device/expo";
139
-
140
- const {
141
- sessionId,
142
- primaryEphemeralPublicKey,
143
- } = parseProvisioningQR(scannedQrCode);
144
-
145
- const deviceMetadata = getDeviceMetadata("Alice's tablet");
146
- const linkedKeys = await connectToProvisioningSession(
147
- relay,
148
- sessionId,
149
- deviceMetadata,
150
- );
151
-
152
- const provisioning = await receiveProvisioningMessage(
153
- relay,
154
- sessionId,
155
- linkedKeys.privateKey,
156
- primaryEphemeralPublicKey,
157
- {
158
- identityStore,
159
- localStateStore,
160
- groupStateStore,
161
- usernameStateStore,
162
- deviceMetadata,
163
- },
164
- );
165
-
166
- console.log(provisioning.deviceId);
107
+ const client = await linkHostedRelayDevice({
108
+ adapters: { storage: linkedStorage },
109
+ activeDeviceStorage,
110
+ hosted: { relayUrl, adapter: managedLinkAdapter },
111
+ });
167
112
  ```
168
113
 
169
- Provisioning requires an ACI identity. It includes PNI identity and
170
- group/username state only when the host application enables and supplies them.
114
+ `activeDeviceStorage` is the store of a device that is already signed in. Its
115
+ account identity must match the identity in `linkedStorage`. The call reads
116
+ the device-authentication private key from each store and signs the link
117
+ challenge in the calling process. Thus that process must hold the active
118
+ device's store, private keys included. The adapter's `linkDevice()` gets a
119
+ challenge signer for each device and no private key.
120
+
121
+ The link copies no protocol state and no group state. Sessions start fresh.
122
+ For each group, the application brings the group master key to the new device,
123
+ and the new device then calls `syncGroup()`.
171
124
 
172
125
  ## Transfer cryptographic state
173
126
 
@@ -198,16 +151,17 @@ durably restores the backup.
198
151
 
199
152
  ## Security boundaries
200
153
 
201
- - Provisioning sessions expire after five minutes.
202
- - Ephemeral ECDH keys derive the provisioning/transfer encryption keys.
154
+ - Ephemeral ECDH keys derive the transfer encryption keys.
203
155
  - The SDK encrypts identity material before it reaches a relay or transport.
204
- - Linked-device bundles never contain signed prekeys, one-time prekeys,
205
- ratchet sessions, sender-key state, message state, or retry outbox state.
206
- - The QR channel authenticates the session only to the extent that the
156
+ - Transfer bundles never contain signed prekeys, one-time prekeys, ratchet
157
+ sessions, sender-key state, message state, or retry outbox state.
158
+ - The transfer QR code authenticates the channel only to the extent that the
207
159
  application protects what the user scans or shares.
160
+ - The managed device link sends no private key to the Relay. The process that
161
+ calls it must hold the active device's store.
208
162
  - The SDK encrypts device names for backend storage.
209
- - Backend authentication must bind registration, provisioning, unlink, and
210
- removal to the owning account.
163
+ - Backend authentication must bind registration, unlink, and removal to the
164
+ owning account.
211
165
  - Account reset must clear the device-ID cache, platform secret storage, and
212
166
  protocol store as one product-level lifecycle.
213
167