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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (583) hide show
  1. package/ADAPTERS.md +4 -4
  2. package/ARCHITECTURE.md +6 -8
  3. package/CHANGELOG.md +1315 -0
  4. package/README.md +1 -1
  5. package/SECURITY.md +2 -2
  6. package/TROUBLESHOOTING.md +1 -1
  7. package/client/README.md +70 -37
  8. package/device/README.md +39 -85
  9. package/dist/client/client.d.ts +334 -63
  10. package/dist/client/client.d.ts.map +1 -1
  11. package/dist/client/client.js +1168 -184
  12. package/dist/client/client.js.map +1 -1
  13. package/dist/client/config.d.ts +40 -32
  14. package/dist/client/config.d.ts.map +1 -1
  15. package/dist/client/config.js +1 -1
  16. package/dist/client/config.js.map +1 -1
  17. package/dist/client/constants.d.ts +42 -8
  18. package/dist/client/constants.d.ts.map +1 -1
  19. package/dist/client/constants.js +48 -3
  20. package/dist/client/constants.js.map +1 -1
  21. package/dist/client/content-adapter.d.ts +80 -0
  22. package/dist/client/content-adapter.d.ts.map +1 -1
  23. package/dist/client/content-adapter.js +225 -12
  24. package/dist/client/content-adapter.js.map +1 -1
  25. package/dist/client/delivery-error.d.ts +150 -0
  26. package/dist/client/delivery-error.d.ts.map +1 -0
  27. package/dist/client/delivery-error.js +226 -0
  28. package/dist/client/delivery-error.js.map +1 -0
  29. package/dist/client/delivery-status.d.ts +32 -6
  30. package/dist/client/delivery-status.d.ts.map +1 -1
  31. package/dist/client/delivery-status.js +61 -13
  32. package/dist/client/delivery-status.js.map +1 -1
  33. package/dist/client/device-set-reconciliation.d.ts +196 -0
  34. package/dist/client/device-set-reconciliation.d.ts.map +1 -0
  35. package/dist/client/device-set-reconciliation.js +282 -0
  36. package/dist/client/device-set-reconciliation.js.map +1 -0
  37. package/dist/client/distribution-records.d.ts +29 -0
  38. package/dist/client/distribution-records.d.ts.map +1 -0
  39. package/dist/client/distribution-records.js +33 -0
  40. package/dist/client/distribution-records.js.map +1 -0
  41. package/dist/client/event-hooks.d.ts +280 -14
  42. package/dist/client/event-hooks.d.ts.map +1 -1
  43. package/dist/client/event-hooks.js +8 -0
  44. package/dist/client/event-hooks.js.map +1 -1
  45. package/dist/client/group-device-set.d.ts +47 -0
  46. package/dist/client/group-device-set.d.ts.map +1 -0
  47. package/dist/client/group-device-set.js +65 -0
  48. package/dist/client/group-device-set.js.map +1 -0
  49. package/dist/client/group-fetcher.d.ts +116 -0
  50. package/dist/client/group-fetcher.d.ts.map +1 -0
  51. package/dist/client/group-fetcher.js +598 -0
  52. package/dist/client/group-fetcher.js.map +1 -0
  53. package/dist/client/group-outbox.d.ts +172 -10
  54. package/dist/client/group-outbox.d.ts.map +1 -1
  55. package/dist/client/group-outbox.js +915 -74
  56. package/dist/client/group-outbox.js.map +1 -1
  57. package/dist/client/group-receive-authorization.d.ts +127 -4
  58. package/dist/client/group-receive-authorization.d.ts.map +1 -1
  59. package/dist/client/group-receive-authorization.js +270 -20
  60. package/dist/client/group-receive-authorization.js.map +1 -1
  61. package/dist/client/group-sealed-sender.d.ts +3 -0
  62. package/dist/client/group-sealed-sender.d.ts.map +1 -1
  63. package/dist/client/group-sealed-sender.js +1 -0
  64. package/dist/client/group-sealed-sender.js.map +1 -1
  65. package/dist/client/group-sender-key-operations.d.ts +14 -3
  66. package/dist/client/group-sender-key-operations.d.ts.map +1 -1
  67. package/dist/client/group-sender-key-operations.js +26 -5
  68. package/dist/client/group-sender-key-operations.js.map +1 -1
  69. package/dist/client/groups.d.ts +5 -5
  70. package/dist/client/groups.d.ts.map +1 -1
  71. package/dist/client/groups.js +5 -4
  72. package/dist/client/groups.js.map +1 -1
  73. package/dist/client/hosted-anonymous-delivery.d.ts +61 -9
  74. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
  75. package/dist/client/hosted-anonymous-delivery.js +242 -48
  76. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  77. package/dist/client/hosted-assertion-id.d.ts +7 -0
  78. package/dist/client/hosted-assertion-id.d.ts.map +1 -0
  79. package/dist/client/hosted-assertion-id.js +51 -0
  80. package/dist/client/hosted-assertion-id.js.map +1 -0
  81. package/dist/client/hosted-mailbox-subscription.d.ts +34 -2
  82. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  83. package/dist/client/hosted-mailbox-subscription.js +87 -17
  84. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  85. package/dist/client/hosted-push.d.ts +22 -4
  86. package/dist/client/hosted-push.d.ts.map +1 -1
  87. package/dist/client/hosted-push.js +75 -22
  88. package/dist/client/hosted-push.js.map +1 -1
  89. package/dist/client/hosted-transport.d.ts +22 -28
  90. package/dist/client/hosted-transport.d.ts.map +1 -1
  91. package/dist/client/hosted-transport.js +115 -55
  92. package/dist/client/hosted-transport.js.map +1 -1
  93. package/dist/client/hosted.d.ts +10 -4
  94. package/dist/client/hosted.d.ts.map +1 -1
  95. package/dist/client/hosted.js +10 -4
  96. package/dist/client/hosted.js.map +1 -1
  97. package/dist/client/index.d.ts +5 -3
  98. package/dist/client/index.d.ts.map +1 -1
  99. package/dist/client/index.js +2 -0
  100. package/dist/client/index.js.map +1 -1
  101. package/dist/client/messages.d.ts +25 -3
  102. package/dist/client/messages.d.ts.map +1 -1
  103. package/dist/client/messages.js +111 -20
  104. package/dist/client/messages.js.map +1 -1
  105. package/dist/client/receive-admission.d.ts +58 -0
  106. package/dist/client/receive-admission.d.ts.map +1 -0
  107. package/dist/client/receive-admission.js +78 -0
  108. package/dist/client/receive-admission.js.map +1 -0
  109. package/dist/client/receive-expiry.d.ts +31 -0
  110. package/dist/client/receive-expiry.d.ts.map +1 -0
  111. package/dist/client/receive-expiry.js +35 -0
  112. package/dist/client/receive-expiry.js.map +1 -0
  113. package/dist/client/receive-hook-bound.d.ts +50 -0
  114. package/dist/client/receive-hook-bound.d.ts.map +1 -0
  115. package/dist/client/receive-hook-bound.js +115 -0
  116. package/dist/client/receive-hook-bound.js.map +1 -0
  117. package/dist/client/receive-queue.d.ts +299 -0
  118. package/dist/client/receive-queue.d.ts.map +1 -0
  119. package/dist/client/receive-queue.js +1420 -0
  120. package/dist/client/receive-queue.js.map +1 -0
  121. package/dist/client/receive-work-seed.d.ts +54 -0
  122. package/dist/client/receive-work-seed.d.ts.map +1 -0
  123. package/dist/client/receive-work-seed.js +116 -0
  124. package/dist/client/receive-work-seed.js.map +1 -0
  125. package/dist/client/recovery-driver.d.ts +25 -0
  126. package/dist/client/recovery-driver.d.ts.map +1 -0
  127. package/dist/client/recovery-driver.js +121 -0
  128. package/dist/client/recovery-driver.js.map +1 -0
  129. package/dist/client/relay-acceptance.d.ts +20 -7
  130. package/dist/client/relay-acceptance.d.ts.map +1 -1
  131. package/dist/client/relay-acceptance.js +30 -12
  132. package/dist/client/relay-acceptance.js.map +1 -1
  133. package/dist/client/relay-device-refusal.d.ts +18 -0
  134. package/dist/client/relay-device-refusal.d.ts.map +1 -1
  135. package/dist/client/relay-device-refusal.js +31 -0
  136. package/dist/client/relay-device-refusal.js.map +1 -1
  137. package/dist/client/relay-sealed-route.d.ts +36 -0
  138. package/dist/client/relay-sealed-route.d.ts.map +1 -0
  139. package/dist/client/relay-sealed-route.js +45 -0
  140. package/dist/client/relay-sealed-route.js.map +1 -0
  141. package/dist/client/relay-subscription.d.ts +56 -13
  142. package/dist/client/relay-subscription.d.ts.map +1 -1
  143. package/dist/client/relay-subscription.js +193 -123
  144. package/dist/client/relay-subscription.js.map +1 -1
  145. package/dist/client/resendable-content.d.ts +98 -0
  146. package/dist/client/resendable-content.d.ts.map +1 -0
  147. package/dist/client/resendable-content.js +136 -0
  148. package/dist/client/resendable-content.js.map +1 -0
  149. package/dist/client/retry-family.d.ts +57 -10
  150. package/dist/client/retry-family.d.ts.map +1 -1
  151. package/dist/client/retry-family.js +54 -12
  152. package/dist/client/retry-family.js.map +1 -1
  153. package/dist/client/retry-request-envelope.d.ts +107 -8
  154. package/dist/client/retry-request-envelope.d.ts.map +1 -1
  155. package/dist/client/retry-request-envelope.js +172 -23
  156. package/dist/client/retry-request-envelope.js.map +1 -1
  157. package/dist/client/retry-request-lifecycle.d.ts +70 -14
  158. package/dist/client/retry-request-lifecycle.d.ts.map +1 -1
  159. package/dist/client/retry-request-lifecycle.js +162 -32
  160. package/dist/client/retry-request-lifecycle.js.map +1 -1
  161. package/dist/client/retry-terminal-recovery.d.ts +100 -0
  162. package/dist/client/retry-terminal-recovery.d.ts.map +1 -0
  163. package/dist/client/retry-terminal-recovery.js +164 -0
  164. package/dist/client/retry-terminal-recovery.js.map +1 -0
  165. package/dist/client/retry-utils.d.ts +27 -0
  166. package/dist/client/retry-utils.d.ts.map +1 -1
  167. package/dist/client/retry-utils.js +46 -0
  168. package/dist/client/retry-utils.js.map +1 -1
  169. package/dist/client/retry.d.ts +100 -12
  170. package/dist/client/retry.d.ts.map +1 -1
  171. package/dist/client/retry.js +619 -116
  172. package/dist/client/retry.js.map +1 -1
  173. package/dist/client/sealed-sender.d.ts +23 -6
  174. package/dist/client/sealed-sender.d.ts.map +1 -1
  175. package/dist/client/sealed-sender.js +30 -6
  176. package/dist/client/sealed-sender.js.map +1 -1
  177. package/dist/client/sessions.d.ts +2 -2
  178. package/dist/client/sessions.js +2 -2
  179. package/dist/client/signal-service-cipher.d.ts +726 -19
  180. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  181. package/dist/client/signal-service-cipher.js +2260 -342
  182. package/dist/client/signal-service-cipher.js.map +1 -1
  183. package/dist/client/state.d.ts +5 -0
  184. package/dist/client/state.d.ts.map +1 -1
  185. package/dist/client/state.js +11 -1
  186. package/dist/client/state.js.map +1 -1
  187. package/dist/client/storage-protection.d.ts +64 -0
  188. package/dist/client/storage-protection.d.ts.map +1 -0
  189. package/dist/client/storage-protection.js +150 -0
  190. package/dist/client/storage-protection.js.map +1 -0
  191. package/dist/client/types.d.ts +149 -15
  192. package/dist/client/types.d.ts.map +1 -1
  193. package/dist/client/types.js +1 -1
  194. package/dist/client/types.js.map +1 -1
  195. package/dist/device/constants.d.ts +0 -5
  196. package/dist/device/constants.d.ts.map +1 -1
  197. package/dist/device/constants.js +0 -5
  198. package/dist/device/constants.js.map +1 -1
  199. package/dist/device/expo/index.d.ts +4 -17
  200. package/dist/device/expo/index.d.ts.map +1 -1
  201. package/dist/device/expo/index.js +4 -23
  202. package/dist/device/expo/index.js.map +1 -1
  203. package/dist/device/index.d.ts +0 -2
  204. package/dist/device/index.d.ts.map +1 -1
  205. package/dist/device/index.js +0 -7
  206. package/dist/device/index.js.map +1 -1
  207. package/dist/device/lifecycle/manager.d.ts +5 -4
  208. package/dist/device/lifecycle/manager.d.ts.map +1 -1
  209. package/dist/device/lifecycle/manager.js +16 -16
  210. package/dist/device/lifecycle/manager.js.map +1 -1
  211. package/dist/device/lifecycle/types.d.ts +2 -2
  212. package/dist/device/lifecycle/types.d.ts.map +1 -1
  213. package/dist/device/react-native/index.d.ts +4 -15
  214. package/dist/device/react-native/index.d.ts.map +1 -1
  215. package/dist/device/react-native/index.js +4 -21
  216. package/dist/device/react-native/index.js.map +1 -1
  217. package/dist/device/types.d.ts +1 -1
  218. package/dist/groups/index.d.ts +1 -1
  219. package/dist/groups/index.d.ts.map +1 -1
  220. package/dist/index.d.ts +8 -6
  221. package/dist/index.d.ts.map +1 -1
  222. package/dist/index.js +2 -1
  223. package/dist/index.js.map +1 -1
  224. package/dist/internal/crypto/ec/x25519-validation.d.ts +0 -1
  225. package/dist/internal/crypto/ec/x25519-validation.d.ts.map +1 -1
  226. package/dist/internal/crypto/ec/x25519-validation.js +0 -1
  227. package/dist/internal/crypto/ec/x25519-validation.js.map +1 -1
  228. package/dist/internal/crypto/validation.d.ts +2 -2
  229. package/dist/internal/groups/index.d.ts +1 -0
  230. package/dist/internal/groups/index.d.ts.map +1 -1
  231. package/dist/internal/groups/index.js +1 -0
  232. package/dist/internal/groups/index.js.map +1 -1
  233. package/dist/internal/groups/manager.d.ts +37 -16
  234. package/dist/internal/groups/manager.d.ts.map +1 -1
  235. package/dist/internal/groups/manager.js +46 -1
  236. package/dist/internal/groups/manager.js.map +1 -1
  237. package/dist/internal/groups/receive-record.d.ts +78 -0
  238. package/dist/internal/groups/receive-record.d.ts.map +1 -0
  239. package/dist/internal/groups/receive-record.js +43 -0
  240. package/dist/internal/groups/receive-record.js.map +1 -0
  241. package/dist/internal/groups/sdk-store.d.ts +27 -3
  242. package/dist/internal/groups/sdk-store.d.ts.map +1 -1
  243. package/dist/internal/groups/sdk-store.js +151 -19
  244. package/dist/internal/groups/sdk-store.js.map +1 -1
  245. package/dist/internal/groups/wire.d.ts +12 -1
  246. package/dist/internal/groups/wire.d.ts.map +1 -1
  247. package/dist/internal/groups/wire.js +36 -0
  248. package/dist/internal/groups/wire.js.map +1 -1
  249. package/dist/internal/manager/index.d.ts +1 -1
  250. package/dist/internal/manager/manager.d.ts +20 -19
  251. package/dist/internal/manager/manager.d.ts.map +1 -1
  252. package/dist/internal/manager/manager.js +56 -39
  253. package/dist/internal/manager/manager.js.map +1 -1
  254. package/dist/internal/protocol/double-ratchet/chains.d.ts +4 -18
  255. package/dist/internal/protocol/double-ratchet/chains.d.ts.map +1 -1
  256. package/dist/internal/protocol/double-ratchet/chains.js +23 -74
  257. package/dist/internal/protocol/double-ratchet/chains.js.map +1 -1
  258. package/dist/internal/protocol/double-ratchet/index.d.ts +1 -1
  259. package/dist/internal/protocol/double-ratchet/index.d.ts.map +1 -1
  260. package/dist/internal/protocol/double-ratchet/index.js +1 -1
  261. package/dist/internal/protocol/double-ratchet/index.js.map +1 -1
  262. package/dist/internal/protocol/double-ratchet/ratchet.d.ts +5 -7
  263. package/dist/internal/protocol/double-ratchet/ratchet.d.ts.map +1 -1
  264. package/dist/internal/protocol/double-ratchet/ratchet.js +4 -6
  265. package/dist/internal/protocol/double-ratchet/ratchet.js.map +1 -1
  266. package/dist/internal/protocol/pqxdh/pqxdh.d.ts.map +1 -1
  267. package/dist/internal/protocol/pqxdh/pqxdh.js +2 -1
  268. package/dist/internal/protocol/pqxdh/pqxdh.js.map +1 -1
  269. package/dist/internal/protocol/sealed-sender/types.d.ts +6 -8
  270. package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
  271. package/dist/internal/protocol/sealed-sender/types.js +8 -9
  272. package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
  273. package/dist/internal/protocol/sender-keys/handoff-ledger.d.ts +110 -0
  274. package/dist/internal/protocol/sender-keys/handoff-ledger.d.ts.map +1 -0
  275. package/dist/internal/protocol/sender-keys/handoff-ledger.js +124 -0
  276. package/dist/internal/protocol/sender-keys/handoff-ledger.js.map +1 -0
  277. package/dist/internal/protocol/sender-keys/manager.d.ts +71 -62
  278. package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
  279. package/dist/internal/protocol/sender-keys/manager.js +228 -175
  280. package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
  281. package/dist/internal/protocol/spqr/index.d.ts +2 -2
  282. package/dist/internal/protocol/spqr/index.d.ts.map +1 -1
  283. package/dist/internal/protocol/spqr/index.js +2 -2
  284. package/dist/internal/protocol/spqr/index.js.map +1 -1
  285. package/dist/internal/protocol/spqr/serialize.d.ts +9 -1
  286. package/dist/internal/protocol/spqr/serialize.d.ts.map +1 -1
  287. package/dist/internal/protocol/spqr/serialize.js +56 -16
  288. package/dist/internal/protocol/spqr/serialize.js.map +1 -1
  289. package/dist/internal/protocol/spqr/spqr.d.ts +1 -14
  290. package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
  291. package/dist/internal/protocol/spqr/spqr.js +54 -42
  292. package/dist/internal/protocol/spqr/spqr.js.map +1 -1
  293. package/dist/internal/protocol/spqr/validate.d.ts +26 -6
  294. package/dist/internal/protocol/spqr/validate.d.ts.map +1 -1
  295. package/dist/internal/protocol/spqr/validate.js +49 -21
  296. package/dist/internal/protocol/spqr/validate.js.map +1 -1
  297. package/dist/internal/sesame/index.d.ts +1 -1
  298. package/dist/internal/sesame/index.d.ts.map +1 -1
  299. package/dist/internal/sesame/index.js.map +1 -1
  300. package/dist/internal/sesame/manager.d.ts +66 -13
  301. package/dist/internal/sesame/manager.d.ts.map +1 -1
  302. package/dist/internal/sesame/manager.js +221 -87
  303. package/dist/internal/sesame/manager.js.map +1 -1
  304. package/dist/internal/sesame/types.d.ts +95 -17
  305. package/dist/internal/sesame/types.d.ts.map +1 -1
  306. package/dist/internal/sesame/types.js +17 -0
  307. package/dist/internal/sesame/types.js.map +1 -1
  308. package/dist/internal/session/builder.d.ts +5 -5
  309. package/dist/internal/session/builder.d.ts.map +1 -1
  310. package/dist/internal/session/builder.js +12 -17
  311. package/dist/internal/session/builder.js.map +1 -1
  312. package/dist/internal/session/cipher.d.ts +13 -11
  313. package/dist/internal/session/cipher.d.ts.map +1 -1
  314. package/dist/internal/session/cipher.js +40 -22
  315. package/dist/internal/session/cipher.js.map +1 -1
  316. package/dist/internal/session/factory.d.ts +5 -5
  317. package/dist/internal/session/factory.d.ts.map +1 -1
  318. package/dist/internal/session/factory.js +4 -4
  319. package/dist/internal/session/factory.js.map +1 -1
  320. package/dist/internal/session/handshake.d.ts +14 -16
  321. package/dist/internal/session/handshake.d.ts.map +1 -1
  322. package/dist/internal/session/handshake.js +18 -75
  323. package/dist/internal/session/handshake.js.map +1 -1
  324. package/dist/internal/session/index.d.ts +1 -1
  325. package/dist/internal/session/index.js +1 -1
  326. package/dist/internal/session/record-locks.d.ts +17 -6
  327. package/dist/internal/session/record-locks.d.ts.map +1 -1
  328. package/dist/internal/session/record-locks.js +43 -7
  329. package/dist/internal/session/record-locks.js.map +1 -1
  330. package/dist/internal/session/session-resolver.d.ts +1 -1
  331. package/dist/internal/session/session-resolver.js +1 -1
  332. package/dist/internal/session/state.d.ts +2 -2
  333. package/dist/internal/session/state.js +1 -1
  334. package/dist/internal/session/types.d.ts +4 -12
  335. package/dist/internal/session/types.d.ts.map +1 -1
  336. package/dist/internal/session/types.js +1 -1
  337. package/dist/keys/generation.d.ts +2 -2
  338. package/dist/keys/generation.js +2 -2
  339. package/dist/keys/types.d.ts +5 -5
  340. package/dist/keys/types.d.ts.map +1 -1
  341. package/dist/keys/types.js +1 -1
  342. package/dist/layers.d.ts +1 -1
  343. package/dist/layers.js +2 -2
  344. package/dist/layers.js.map +1 -1
  345. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  346. package/dist/local/store/expo/adapter.js +12 -8
  347. package/dist/local/store/expo/adapter.js.map +1 -1
  348. package/dist/local/store/key-value/adapter.d.ts +76 -10
  349. package/dist/local/store/key-value/adapter.d.ts.map +1 -1
  350. package/dist/local/store/key-value/adapter.js +367 -61
  351. package/dist/local/store/key-value/adapter.js.map +1 -1
  352. package/dist/local/store/key-value/backend-conformance.d.ts.map +1 -1
  353. package/dist/local/store/key-value/backend-conformance.js +74 -0
  354. package/dist/local/store/key-value/backend-conformance.js.map +1 -1
  355. package/dist/local/store/key-value/batch.d.ts +2 -0
  356. package/dist/local/store/key-value/batch.d.ts.map +1 -1
  357. package/dist/local/store/key-value/batch.js +26 -0
  358. package/dist/local/store/key-value/batch.js.map +1 -1
  359. package/dist/local/store/key-value/receive-work.d.ts +55 -0
  360. package/dist/local/store/key-value/receive-work.d.ts.map +1 -0
  361. package/dist/local/store/key-value/receive-work.js +162 -0
  362. package/dist/local/store/key-value/receive-work.js.map +1 -0
  363. package/dist/local/store/key-value/send-log.d.ts +61 -0
  364. package/dist/local/store/key-value/send-log.d.ts.map +1 -0
  365. package/dist/local/store/key-value/send-log.js +430 -0
  366. package/dist/local/store/key-value/send-log.js.map +1 -0
  367. package/dist/local/store/key-value/sender-key-handoff.d.ts +68 -0
  368. package/dist/local/store/key-value/sender-key-handoff.d.ts.map +1 -0
  369. package/dist/local/store/key-value/sender-key-handoff.js +189 -0
  370. package/dist/local/store/key-value/sender-key-handoff.js.map +1 -0
  371. package/dist/local/store/key-value/storage.d.ts +15 -0
  372. package/dist/local/store/key-value/storage.d.ts.map +1 -1
  373. package/dist/local/store/keyed-index.d.ts +23 -0
  374. package/dist/local/store/keyed-index.d.ts.map +1 -0
  375. package/dist/local/store/keyed-index.js +41 -0
  376. package/dist/local/store/keyed-index.js.map +1 -0
  377. package/dist/local/store/memory/adapter.d.ts +44 -12
  378. package/dist/local/store/memory/adapter.d.ts.map +1 -1
  379. package/dist/local/store/memory/adapter.js +197 -46
  380. package/dist/local/store/memory/adapter.js.map +1 -1
  381. package/dist/local/store/memory/send-log.d.ts +42 -0
  382. package/dist/local/store/memory/send-log.d.ts.map +1 -0
  383. package/dist/local/store/memory/send-log.js +190 -0
  384. package/dist/local/store/memory/send-log.js.map +1 -0
  385. package/dist/local/store/node/adapter.d.ts.map +1 -1
  386. package/dist/local/store/node/adapter.js +8 -6
  387. package/dist/local/store/node/adapter.js.map +1 -1
  388. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  389. package/dist/local/store/react-native/adapter.js +12 -8
  390. package/dist/local/store/react-native/adapter.js.map +1 -1
  391. package/dist/local/store/receive-work.d.ts +87 -0
  392. package/dist/local/store/receive-work.d.ts.map +1 -0
  393. package/dist/local/store/receive-work.js +204 -0
  394. package/dist/local/store/receive-work.js.map +1 -0
  395. package/dist/local/store/received-content.d.ts +3 -3
  396. package/dist/local/store/received-content.d.ts.map +1 -1
  397. package/dist/local/store/received-content.js +2 -11
  398. package/dist/local/store/received-content.js.map +1 -1
  399. package/dist/local/store/reliability.d.ts +317 -18
  400. package/dist/local/store/reliability.d.ts.map +1 -1
  401. package/dist/local/store/reliability.js +371 -46
  402. package/dist/local/store/reliability.js.map +1 -1
  403. package/dist/local/store/send-log-order.d.ts +15 -0
  404. package/dist/local/store/send-log-order.d.ts.map +1 -0
  405. package/dist/local/store/send-log-order.js +24 -0
  406. package/dist/local/store/send-log-order.js.map +1 -0
  407. package/dist/local/store/sender-key-handoff-index.d.ts +38 -0
  408. package/dist/local/store/sender-key-handoff-index.d.ts.map +1 -0
  409. package/dist/local/store/sender-key-handoff-index.js +101 -0
  410. package/dist/local/store/sender-key-handoff-index.js.map +1 -0
  411. package/dist/local/store/sender-key-handoff-table.d.ts +29 -0
  412. package/dist/local/store/sender-key-handoff-table.d.ts.map +1 -0
  413. package/dist/local/store/sender-key-handoff-table.js +97 -0
  414. package/dist/local/store/sender-key-handoff-table.js.map +1 -0
  415. package/dist/local/store/sqlite/encryption.d.ts +8 -1
  416. package/dist/local/store/sqlite/encryption.d.ts.map +1 -1
  417. package/dist/local/store/sqlite/encryption.js +9 -0
  418. package/dist/local/store/sqlite/encryption.js.map +1 -1
  419. package/dist/local/store/sqlite/key-storage/index.d.ts +25 -4
  420. package/dist/local/store/sqlite/key-storage/index.d.ts.map +1 -1
  421. package/dist/local/store/sqlite/key-storage/index.js +68 -7
  422. package/dist/local/store/sqlite/key-storage/index.js.map +1 -1
  423. package/dist/local/store/sqlite/key-storage/message-records.d.ts +16 -4
  424. package/dist/local/store/sqlite/key-storage/message-records.d.ts.map +1 -1
  425. package/dist/local/store/sqlite/key-storage/message-records.js +49 -6
  426. package/dist/local/store/sqlite/key-storage/message-records.js.map +1 -1
  427. package/dist/local/store/sqlite/key-storage/metadata.d.ts +8 -7
  428. package/dist/local/store/sqlite/key-storage/metadata.d.ts.map +1 -1
  429. package/dist/local/store/sqlite/key-storage/metadata.js +17 -15
  430. package/dist/local/store/sqlite/key-storage/metadata.js.map +1 -1
  431. package/dist/local/store/sqlite/key-storage/receive-work.d.ts +27 -0
  432. package/dist/local/store/sqlite/key-storage/receive-work.d.ts.map +1 -0
  433. package/dist/local/store/sqlite/key-storage/receive-work.js +98 -0
  434. package/dist/local/store/sqlite/key-storage/receive-work.js.map +1 -0
  435. package/dist/local/store/sqlite/key-storage/send-log.d.ts +27 -0
  436. package/dist/local/store/sqlite/key-storage/send-log.d.ts.map +1 -0
  437. package/dist/local/store/sqlite/key-storage/send-log.js +178 -0
  438. package/dist/local/store/sqlite/key-storage/send-log.js.map +1 -0
  439. package/dist/local/store/sqlite/key-storage/sender-key-handoff.d.ts +27 -0
  440. package/dist/local/store/sqlite/key-storage/sender-key-handoff.d.ts.map +1 -0
  441. package/dist/local/store/sqlite/key-storage/sender-key-handoff.js +75 -0
  442. package/dist/local/store/sqlite/key-storage/sender-key-handoff.js.map +1 -0
  443. package/dist/local/store/sqlite/key-storage/session-trust.d.ts +2 -2
  444. package/dist/local/store/sqlite/key-storage/session-trust.js +5 -5
  445. package/dist/local/store/sqlite/key-storage/session-trust.js.map +1 -1
  446. package/dist/local/store/sqlite/migrations.d.ts.map +1 -1
  447. package/dist/local/store/sqlite/migrations.js +101 -0
  448. package/dist/local/store/sqlite/migrations.js.map +1 -1
  449. package/dist/local/store/sqlite/models/index.d.ts +2 -1
  450. package/dist/local/store/sqlite/models/index.d.ts.map +1 -1
  451. package/dist/local/store/sqlite/models/index.js +5 -1
  452. package/dist/local/store/sqlite/models/index.js.map +1 -1
  453. package/dist/local/store/sqlite/models/message-record.d.ts +15 -0
  454. package/dist/local/store/sqlite/models/message-record.d.ts.map +1 -1
  455. package/dist/local/store/sqlite/models/message-record.js +24 -0
  456. package/dist/local/store/sqlite/models/message-record.js.map +1 -1
  457. package/dist/local/store/sqlite/models/send-log.d.ts +51 -0
  458. package/dist/local/store/sqlite/models/send-log.d.ts.map +1 -0
  459. package/dist/local/store/sqlite/models/send-log.js +206 -0
  460. package/dist/local/store/sqlite/models/send-log.js.map +1 -0
  461. package/dist/local/store/sqlite/open-store.d.ts +9 -1
  462. package/dist/local/store/sqlite/open-store.d.ts.map +1 -1
  463. package/dist/local/store/sqlite/open-store.js +20 -1
  464. package/dist/local/store/sqlite/open-store.js.map +1 -1
  465. package/dist/local/store/sqlite/schema.d.ts +34 -1
  466. package/dist/local/store/sqlite/schema.d.ts.map +1 -1
  467. package/dist/local/store/sqlite/schema.js +14 -0
  468. package/dist/local/store/sqlite/schema.js.map +1 -1
  469. package/dist/local/store/sqlite/store.d.ts +61 -11
  470. package/dist/local/store/sqlite/store.d.ts.map +1 -1
  471. package/dist/local/store/sqlite/store.js +191 -27
  472. package/dist/local/store/sqlite/store.js.map +1 -1
  473. package/dist/local/store/web/adapter.d.ts +76 -8
  474. package/dist/local/store/web/adapter.d.ts.map +1 -1
  475. package/dist/local/store/web/adapter.js +579 -127
  476. package/dist/local/store/web/adapter.js.map +1 -1
  477. package/dist/local/store/web/receive-work.d.ts +57 -0
  478. package/dist/local/store/web/receive-work.d.ts.map +1 -0
  479. package/dist/local/store/web/receive-work.js +99 -0
  480. package/dist/local/store/web/receive-work.js.map +1 -0
  481. package/dist/local/store/web/send-log.d.ts +92 -0
  482. package/dist/local/store/web/send-log.d.ts.map +1 -0
  483. package/dist/local/store/web/send-log.js +267 -0
  484. package/dist/local/store/web/send-log.js.map +1 -0
  485. package/dist/local/store/web/sender-key-handoff.d.ts +81 -0
  486. package/dist/local/store/web/sender-key-handoff.d.ts.map +1 -0
  487. package/dist/local/store/web/sender-key-handoff.js +156 -0
  488. package/dist/local/store/web/sender-key-handoff.js.map +1 -0
  489. package/dist/local/store/web-sqlite/adapter.d.ts +2 -0
  490. package/dist/local/store/web-sqlite/adapter.d.ts.map +1 -1
  491. package/dist/local/store/web-sqlite/adapter.js +12 -6
  492. package/dist/local/store/web-sqlite/adapter.js.map +1 -1
  493. package/dist/local/vault/custody.d.ts +8 -0
  494. package/dist/local/vault/custody.d.ts.map +1 -0
  495. package/dist/local/vault/custody.js +9 -0
  496. package/dist/local/vault/custody.js.map +1 -0
  497. package/dist/local/vault/electron-safe-storage.d.ts +3 -1
  498. package/dist/local/vault/electron-safe-storage.d.ts.map +1 -1
  499. package/dist/local/vault/electron-safe-storage.js +2 -0
  500. package/dist/local/vault/electron-safe-storage.js.map +1 -1
  501. package/dist/local/vault/expo-secure-store.d.ts +3 -1
  502. package/dist/local/vault/expo-secure-store.d.ts.map +1 -1
  503. package/dist/local/vault/expo-secure-store.js +2 -0
  504. package/dist/local/vault/expo-secure-store.js.map +1 -1
  505. package/dist/local/vault/indexed-db.d.ts +3 -1
  506. package/dist/local/vault/indexed-db.d.ts.map +1 -1
  507. package/dist/local/vault/indexed-db.js +2 -0
  508. package/dist/local/vault/indexed-db.js.map +1 -1
  509. package/dist/local/vault/react-native-keychain.d.ts +3 -1
  510. package/dist/local/vault/react-native-keychain.d.ts.map +1 -1
  511. package/dist/local/vault/react-native-keychain.js +2 -0
  512. package/dist/local/vault/react-native-keychain.js.map +1 -1
  513. package/dist/remote/relay/device-set.d.ts +94 -0
  514. package/dist/remote/relay/device-set.d.ts.map +1 -0
  515. package/dist/remote/relay/device-set.js +156 -0
  516. package/dist/remote/relay/device-set.js.map +1 -0
  517. package/dist/remote/relay/types.d.ts +92 -107
  518. package/dist/remote/relay/types.d.ts.map +1 -1
  519. package/dist/safety/core.d.ts +15 -6
  520. package/dist/safety/core.d.ts.map +1 -1
  521. package/dist/safety/core.js +41 -27
  522. package/dist/safety/core.js.map +1 -1
  523. package/dist/safety/index.d.ts +2 -1
  524. package/dist/safety/index.d.ts.map +1 -1
  525. package/dist/safety/index.js +12 -18
  526. package/dist/safety/index.js.map +1 -1
  527. package/dist/types/api.d.ts +707 -62
  528. package/dist/types/api.d.ts.map +1 -1
  529. package/dist/types/errors.d.ts +14 -33
  530. package/dist/types/errors.d.ts.map +1 -1
  531. package/dist/types/errors.js +14 -24
  532. package/dist/types/errors.js.map +1 -1
  533. package/dist/types/messages.d.ts +2 -2
  534. package/dist/types/messages.js +1 -1
  535. package/dist/types/protocol-config.d.ts +175 -42
  536. package/dist/types/protocol-config.d.ts.map +1 -1
  537. package/dist/types/protocol-config.js +19 -38
  538. package/dist/types/protocol-config.js.map +1 -1
  539. package/dist/types/protocol-constants.d.ts +6 -6
  540. package/dist/types/protocol-constants.js +6 -6
  541. package/dist/types/session.d.ts +7 -7
  542. package/dist/types/session.d.ts.map +1 -1
  543. package/dist/types/session.js +39 -21
  544. package/dist/types/session.js.map +1 -1
  545. package/dist/username/link.d.ts +2 -2
  546. package/dist/username/link.js +2 -2
  547. package/dist/utils/origin-lock.d.ts +45 -0
  548. package/dist/utils/origin-lock.d.ts.map +1 -0
  549. package/dist/utils/origin-lock.js +80 -0
  550. package/dist/utils/origin-lock.js.map +1 -0
  551. package/docs/ASSURANCE.md +6 -6
  552. package/docs/CLIENT_COMPOSITION.md +2 -2
  553. package/docs/DEVIATIONS.md +677 -182
  554. package/docs/E2EE.md +1 -1
  555. package/docs/ERROR_HANDLING.md +165 -2
  556. package/docs/GETTING_STARTED.md +7 -4
  557. package/docs/INTERFACES.md +1 -1
  558. package/docs/PACKAGE_SURFACE.md +6 -5
  559. package/docs/PROTOCOL_POLICY.md +102 -22
  560. package/docs/RECIPES.md +3 -15
  561. package/docs/SECURITY.md +90 -5
  562. package/keys/README.md +3 -3
  563. package/local/store/README.md +78 -14
  564. package/local/store/key-value/README.md +14 -3
  565. package/local/store/node/README.md +8 -3
  566. package/local/store/web/README.md +9 -0
  567. package/local/store/web-sqlite/README.md +14 -2
  568. package/local/vault/README.md +21 -0
  569. package/package.json +1 -6
  570. package/remote/README.md +0 -1
  571. package/remote/relay/README.md +2 -2
  572. package/dist/device/provisioning.d.ts +0 -242
  573. package/dist/device/provisioning.d.ts.map +0 -1
  574. package/dist/device/provisioning.js +0 -421
  575. package/dist/device/provisioning.js.map +0 -1
  576. package/dist/internal/protocol/x3dh/index.d.ts +0 -15
  577. package/dist/internal/protocol/x3dh/index.d.ts.map +0 -1
  578. package/dist/internal/protocol/x3dh/index.js +0 -13
  579. package/dist/internal/protocol/x3dh/index.js.map +0 -1
  580. package/dist/internal/protocol/x3dh/x3dh.d.ts +0 -131
  581. package/dist/internal/protocol/x3dh/x3dh.d.ts.map +0 -1
  582. package/dist/internal/protocol/x3dh/x3dh.js +0 -261
  583. package/dist/internal/protocol/x3dh/x3dh.js.map +0 -1
package/docs/E2EE.md CHANGED
@@ -4,7 +4,7 @@
4
4
  > [Security Model](./SECURITY.md) | [Architecture](../ARCHITECTURE.md)
5
5
 
6
6
  `@open-e2ee/signal-protocol-sdk` provides end-to-end encryption based on the
7
- Signal Protocol: X3DH / PQXDH key agreement and the Double Ratchet, extended
7
+ Signal Protocol: PQXDH key agreement and the Double Ratchet, extended
8
8
  with the Sparse Post-Quantum Ratchet (SPQR / ML-KEM Braid).
9
9
 
10
10
  End-to-end encryption means plaintext exists only on the sender's and
@@ -129,9 +129,9 @@ holds each member to a production construction site.
129
129
  |---|---|---|
130
130
  | `INITIALIZATION_FAILED` | Client or group initialization failed. | Inspect `originalError` and the configuration. |
131
131
  | `SECURE_RANDOM_UNAVAILABLE` | The runtime has no global `crypto.getRandomValues`. The SDK throws `SecureRandomUnavailableError` from `@open-e2ee/signal-protocol-sdk/types`. | On React Native and Expo, install `react-native-get-random-values` 2.x or `react-native-quick-crypto` and load it before the first SDK call. |
132
- | `PQXDH_REQUIRED` | Policy requires PQXDH, but the peer lacks required keys. | Wait for new peer keys or queue the message. |
132
+ | `PQXDH_REQUIRED` | Every new session requires PQXDH, and the peer bundle has no ML-KEM prekey. No classical key agreement exists. | Wait for new peer keys or queue the message. |
133
133
  | `PQXDH_FAILED` | The PQXDH exchange failed. | Abort setup and inspect `originalError`. |
134
- | `TRIPLE_RATCHET_REQUIRED` | Triple Ratchet policy lacks a PQXDH session. | Establish the required PQXDH session first. |
134
+ | `TRIPLE_RATCHET_REQUIRED` | Triple Ratchet applies, but the session has no PQXDH result. | Establish a PQXDH session first. |
135
135
 
136
136
  ### SPQR Errors
137
137
 
@@ -208,6 +208,117 @@ try {
208
208
  }
209
209
  ```
210
210
 
211
+ ### Stale Devices
212
+
213
+ A direct message, a sync copy, a sender-key distribution, a group device
214
+ message, a receipt, and a retry request go to one device. Each of these
215
+ posts names the registration ID of the recipient session. A shared group
216
+ message names the registration of each destination device. The identified
217
+ route and both sealed routes send the registration. A sealed post sends no
218
+ sender identity. A post to a device with no session names none.
219
+
220
+ The Relay compares this value with the current registration of the device.
221
+ A device that was reinstalled with the same device ID has a new
222
+ registration. The Relay then refuses the post:
223
+
224
+ - The identified route and the sealed direct route answer HTTP 410 with
225
+ the code `STALE_DEVICE`. The sealed direct route takes an access key or
226
+ the group endorsement of the one recipient account.
227
+ - The sealed group route refuses only that destination. Its receipt names
228
+ each refused destination with the code `STALE_DEVICE`. The refused count
229
+ alone names no device, so the SDK infers no code from it. A one-device post
230
+ goes on this route only after a fallback from the direct route. See
231
+ [Sealed Route Rejections](#sealed-route-rejections).
232
+
233
+ The SDK handles this refusal for each of these post kinds. It refreshes
234
+ the session of the device once and posts again. A direct message, a sync
235
+ copy, a sender-key distribution, a group device message, and a receipt are
236
+ encrypted again under the new session and get a new transport ID. A retry
237
+ request is not encrypted, so it keeps its envelope: the second post has the
238
+ same transport ID and names the registration of the new session. The
239
+ application does not have to act. A retry request ends with the terminal
240
+ class `missing-sender` only when the Relay has no bundle for the device, or
241
+ when the device refuses the request again after the refresh. When the
242
+ refresh of a receipt or a retry request fails for another reason, the SDK
243
+ keeps the stale session and posts the item again later. A device that a
244
+ shared group message names gets the same repair when the receipt refuses it.
245
+
246
+ The registration field never identifies the sender. A sealed post that
247
+ names an old registration tells the Relay only that some sender still has
248
+ a session from before the reinstall. The post carries no sender identity,
249
+ so it does not tell the Relay which sender that is.
250
+
251
+ ### Sealed Route Rejections
252
+
253
+ A post to one device can use the group endorsement on the sealed direct
254
+ route. The Relay answers a rejection in one of two ways:
255
+
256
+ | Answer | Meaning | SDK behavior |
257
+ |---|---|---|
258
+ | 401 `ANONYMOUS_AUTH_REJECTED` | The direct route does not take the endorsement. The post did not start. | The SDK posts the message once on the sealed group route for that device, and writes one `info` log line with the behavior `GROUP_ROUTE_FALLBACK`. The post stays sealed. |
259
+ | 401 `GROUP_CREDENTIAL_REJECTED` | The Relay rejected the endorsement. | No route fallback. In `required` mode, the send fails with `SEALED_SENDER_AUTH_FAILED` and makes no identified post. In `preferred` mode, the SDK posts identified and calls `onIdentifiedFallback`. |
260
+
261
+ A resend that answers a retry request uses the same authorization as its
262
+ original send. A resend of a group send to a member with no access key is
263
+ sealed with the group endorsement. A resend in `required` mode that has no
264
+ sealed authorization fails with `SEALED_SENDER_REQUIRED` and makes no
265
+ identified post.
266
+
267
+ ### Device Sets
268
+
269
+ A Relay that compares device sets checks each declared post. Each post to an
270
+ account declares the device IDs that the sender holds records for. The Relay
271
+ refuses a declaration that does not match its device list:
272
+
273
+ - HTTP 409 with the code `DEVICE_SET_MISMATCH` names the missing and the extra
274
+ devices of each account.
275
+ - HTTP 410 with the code `STALE_DEVICE` names each declared device whose
276
+ registration changed.
277
+
278
+ The SDK repairs the set and posts again. It removes each extra device record,
279
+ starts a new session with each missing or stale device, and encrypts the
280
+ message again only for those devices. A device that the Relay accepted keeps
281
+ its stored post. The application does not have to act.
282
+
283
+ A send has two phases: the recipient phase, and then the sync phase for the
284
+ own devices. Each phase can restart 10 times. When the Relay refuses the
285
+ declaration of the recipient phase after the 10th restart, or refuses a
286
+ restart post with `OPERATION_EXPIRED`, the send throws
287
+ [`DeviceSetReconciliationError`](./api/classes/DeviceSetReconciliationError.md).
288
+ `isOutgoingMessageError` is true for it. Its fields:
289
+
290
+ | Field | Meaning |
291
+ |---|---|
292
+ | `reason` | `exhausted` after the 10th restart, or `expired` after `OPERATION_EXPIRED` |
293
+ | `phase` | `recipient` or `sync` |
294
+ | `restarts` | The restarts of the phase |
295
+ | `lastRefusal` | The code and the devices of the last refusal. `BUNDLE_NOT_FOUND` is a listed device with no prekey bundle |
296
+ | `acceptedDevices` | The devices that the Relay accepted. They stay accepted |
297
+ | `unresolvedDevices` | The devices that did not get the message |
298
+ | `clientMessageId` | The ID of the send |
299
+
300
+ The outbox keeps the send as terminal and does not post it again. A call of
301
+ `send()` with the same `clientMessageId` starts a new run at 0 restarts.
302
+
303
+ The sync phase does not fail the send. The recipient result is stored first.
304
+ When the sync phase does not complete, or the own device list cannot be read,
305
+ the result carries `syncPending: true`. Call `send()` again with the same
306
+ `clientMessageId` to post the pending copies.
307
+
308
+ The Relay marks each accepted declared post with `deviceSetChecked`. When an
309
+ accepted post has no mark, the Relay did not compare its device set. The send
310
+ is delivered and its result does not change. The client reports a
311
+ [`RelayProtocolError`](./api/classes/RelayProtocolError.md) with the code
312
+ `DEVICE_SET_UNCHECKED` once for the send through the `onRelayProtocolError`
313
+ hook. Its `route` names the post route. A sync copy to another own device is
314
+ an `identified-direct` post. A sync payload of a method such as
315
+ `syncReadToLinkedDevices` reports the error once, with no `clientMessageId`.
316
+ Report it to the Relay operator.
317
+
318
+ A relay that does not compare device sets gets no declaration. The Convex
319
+ relay is one. With it, the SDK reads the device lists as before, and none of
320
+ these errors occur.
321
+
211
322
  ## Relay Device Errors
212
323
 
213
324
  The Relay can refuse this device. Two errors name that refusal. Neither is an
@@ -269,6 +380,58 @@ try {
269
380
  }
270
381
  ```
271
382
 
383
+ ## Group Receive Errors
384
+
385
+ A managed group receive can end in three errors. None of them is an
386
+ `EncryptionError`. Each one tells the caller what to do with the message.
387
+
388
+ | Error | Cause | Keep rule |
389
+ |---|---|---|
390
+ | [`GroupReceiveUnavailableError`](./api/classes/GroupReceiveUnavailableError.md) | The group state is not current. `reason` names the wait, and `retryAfterMs` gives the time to the next try. The client stored the content in a receive record under `messageId`. | Call again later with the same message. The later call decides the stored content with no second decrypt. |
391
+ | [`GroupReceiveRefusedError`](./api/classes/GroupReceiveRefusedError.md) | The client refused the content. `reason` names the refusal, for example `sender-not-member` or `sync-from-other-account`. The client asked for no resend. | Drop the message. A redelivery is dropped as a processed duplicate. |
392
+ | [`GroupResendDeferredError`](./api/classes/GroupResendDeferredError.md) | A resend to a group member waits for the group state. The client neither sent nor refused the resend. | The Relay keeps the retry request. Do not acknowledge it. A later delivery decides again. |
393
+
394
+ The deprecated `decryptGroupMessage` throws the first two errors. It also
395
+ throws `EncryptionError` with `STORAGE_QUOTA_EXCEEDED` when the receive queue
396
+ has no room, and with `MESSAGE_DUPLICATE` for a message that this client
397
+ processed or that gives no content, such as a null message. A decrypt failure
398
+ throws its error with no retry request and no report.
399
+ `decryptEnvelope` throws `GroupReceiveRefusedError` for a group context that
400
+ is malformed or names another group. `processIncomingEnvelope` throws none
401
+ of them. It returns a receive outcome: `pending` for content that waits for
402
+ its group state, and `denied` for refused content. Acknowledge the envelope
403
+ for both. The receive queue keeps pending content on the device and decides
404
+ it when its group updates. Do not acknowledge an envelope whose outcome is
405
+ `refused`: the receive queue had no room, and the client stored nothing.
406
+
407
+ Content from another account that carries a sync message is refused as
408
+ `sync-from-other-account` on the Relay subscription, in
409
+ `receiveIncomingEnvelopes`, in `decryptEnvelope` and `decryptGroupMessage`,
410
+ and in `processIncomingEnvelope` as a `denied` outcome. The raw decrypt
411
+ methods `receive`, `decryptMessage`, and `decryptMessages` return the
412
+ plaintext with no group classification and do not refuse it.
413
+
414
+ The Relay subscription applies the rule itself. It acknowledges an envelope
415
+ after its content is committed, also when the content waits for its group
416
+ or is denied. An envelope that the receive queue refuses for lack of room
417
+ stays unacknowledged. `receiveIncomingEnvelopes` commits each envelope and sends
418
+ no acknowledgment. It reports the committed envelopes in
419
+ `processedMessageIds`, ready for the transport acknowledgment. It reports a
420
+ deferred retry request and an envelope that the receive queue had no room
421
+ for in `failedMessageIds`.
422
+
423
+ <!-- doc-snippet:skip requires-existing-client -->
424
+ ```typescript
425
+ const outcome = await signal.processIncomingEnvelope(envelope, {
426
+ onPersist: (processed) => saveMessage(processed.messageId, processed.plaintext),
427
+ });
428
+ if (outcome.kind === 'refused') {
429
+ keepForLater(envelope);
430
+ } else {
431
+ acknowledge(envelope);
432
+ }
433
+ ```
434
+
272
435
  ## Error Handling Patterns
273
436
 
274
437
  ### One Handler for Every Error
@@ -49,7 +49,10 @@ implementation.
49
49
  5. Start the relay subscription.
50
50
 
51
51
  The hosted factory authenticates and registers the current device, then publishes
52
- its public prekeys. Linked devices use the provisioning flow in the
52
+ its public prekeys. A linked device gets the account identity by device
53
+ transfer or by a channel that the application owns, then joins the account
54
+ with `linkHostedRelayDevice()`. That call runs in one process that holds the
55
+ active device's store and the new device's store. See the
53
56
  [device guide](../device/README.md). The default policy requires post-quantum
54
57
  session establishment and Braid ratcheting.
55
58
 
@@ -458,9 +461,9 @@ protocol: {
458
461
  }
459
462
  ```
460
463
 
461
- Leave it unset unless your product has a specific compatibility decision. See
462
- [Protocol Policy](./PROTOCOL_POLICY.md) for the rare cases where you would set
463
- `postQuantum: 'compatible'` or `braid: 'disabled'`.
464
+ Leave it unset. `'required'` is the only `postQuantum` value. See
465
+ [Protocol Policy](./PROTOCOL_POLICY.md) for the rare case where you would set
466
+ `braid: 'disabled'`.
464
467
 
465
468
  ## Where To Go Next
466
469
 
@@ -83,7 +83,7 @@ selected platform service and host configuration. See the
83
83
 
84
84
  `SignalProtocolRelayServer` represents the authenticated application backend used for
85
85
  device registration, account identity state, public prekeys, encrypted-envelope
86
- delivery, provisioning, key rotation, and encrypted group coordination.
86
+ delivery, key rotation, and encrypted group coordination.
87
87
 
88
88
  <!-- doc-snippet:skip requires-external-context -->
89
89
  ```ts
@@ -86,7 +86,6 @@ implementations are outside the published SDK.
86
86
  - `@open-e2ee/signal-protocol-sdk/device/device-id`
87
87
  - `@open-e2ee/signal-protocol-sdk/device/expo`
88
88
  - `@open-e2ee/signal-protocol-sdk/device/lifecycle`
89
- - `@open-e2ee/signal-protocol-sdk/device/provisioning`
90
89
  - `@open-e2ee/signal-protocol-sdk/device/react-native`
91
90
  - `@open-e2ee/signal-protocol-sdk/encoding`
92
91
  - `@open-e2ee/signal-protocol-sdk/encoding/hex`
@@ -224,13 +223,15 @@ implement the same `MediaAttachmentTransfer` seam.
224
223
  default adapters.
225
224
  - `createSignalProtocolClient()` is the preferred composition helper when app
226
225
  code owns multiple adapters.
227
- - Linked devices must already contain provisioned identity material before
228
- `DefaultSignalProtocolClient.create(..., { deviceId: 2 })`.
226
+ - Linked devices must already contain the account identity before
227
+ `DefaultSignalProtocolClient.create(..., { deviceId: 2 })`. The application
228
+ imports it by device transfer or by a channel that the application owns.
229
229
  - Username-only apps typically run ACI-only. Phone-capable apps can enable both
230
230
  ACI and PNI with `enablePniKeys: true`.
231
231
  - `protocol.postQuantum` and `protocol.braid` are product-facing policy.
232
- Advanced protocol strategy knobs remain available for diagnostics, telemetry,
233
- and protocol-level tuning.
232
+ `'required'` is the only `postQuantum` value, and no classical key agreement
233
+ exists. Advanced protocol strategy knobs remain available for diagnostics,
234
+ telemetry, and protocol-level tuning.
234
235
  - The package is workspace-friendly in this repo and dist-first for packed
235
236
  consumers.
236
237
 
@@ -36,25 +36,15 @@ await createSignalProtocolClient({
36
36
  ```
37
37
 
38
38
  Required mode means post-quantum session establishment and the post-quantum
39
- message ratchet are mandatory. A peer that has no post-quantum material fails
40
- closed.
39
+ message ratchet are mandatory. `'required'` is the only `postQuantum` value.
41
40
 
42
- ## Compatible
41
+ ## No Classical Key Agreement
43
42
 
44
- <!-- doc-snippet:skip requires-external-context -->
45
- ```ts
46
- await createSignalProtocolClient({
47
- identity: { userId },
48
- adapters: { storage, relay },
49
- protocol: { postQuantum: 'compatible', braid: 'required' },
50
- });
51
- ```
43
+ The SDK has no classical key agreement. Every new session uses PQXDH with
44
+ ML-KEM-1024. A peer that publishes no post-quantum prekeys fails closed with
45
+ `PQXDHRequiredError` (`PQXDH_REQUIRED`), and no session is stored.
52
46
 
53
- Compatible mode still uses post-quantum behavior whenever the peer supports it.
54
- It only allows classical compatibility when the peer advertises no
55
- post-quantum material at all.
56
-
57
- Compatible mode does not allow downgrade recovery:
47
+ No setting allows downgrade recovery:
58
48
 
59
49
  - malformed post-quantum metadata fails closed
60
50
  - cryptographic failure after post-quantum selection fails closed
@@ -113,14 +103,15 @@ await createSignalProtocolClient({
113
103
  });
114
104
  ```
115
105
 
116
- There is no public `postQuantum: 'disabled'` mode.
106
+ `'required'` is the only `postQuantum` value. Any other value throws
107
+ `Unsupported postQuantum policy` when the client is created.
117
108
 
118
109
  ## Advanced Telemetry
119
110
 
120
111
  The advanced `protocolStrategy.onProtocolSelected` callback remains available
121
- for diagnostics. It distinguishes post-quantum success from explicit classical
122
- compatibility fallback. Do not set `protocolStrategy.allowClassicalFallback`
123
- when `protocol.postQuantum` is present.
112
+ for diagnostics. It fires once for each session that PQXDH establishes. A peer
113
+ without post-quantum prekeys fails before selection, so the callback does not
114
+ fire for it.
124
115
 
125
116
  The advanced `protocolStrategy.onBraidProgress` callback reports ML-KEM Braid
126
117
  chunk progress after every braid-mode send and receive:
@@ -132,5 +123,94 @@ chunk progress after every braid-mode send and receive:
132
123
 
133
124
  A direct-mode session never raises it.
134
125
 
135
- Do not set `protocolStrategy.sckaMode` when `protocol` is present. Use
136
- `protocol.braid` so the public product policy owns the direct-vs-Braid choice.
126
+ Do not set `protocolStrategy.sckaMode` when `protocol` sets more than
127
+ `contentRecovery`. Use `protocol.braid` so the public product policy owns the
128
+ direct-vs-Braid choice.
129
+
130
+ ## Content Recovery
131
+
132
+ A device that cannot decrypt a message asks the sender for it again with a
133
+ retry request. To answer with the content, the sender keeps the plaintext of
134
+ each resendable message in its local store. `protocol.contentRecovery`
135
+ decides whether the store may hold that plaintext.
136
+
137
+ <!-- doc-snippet:illustrative config-object-fragment -->
138
+ ```ts
139
+ protocol: {
140
+ contentRecovery: {
141
+ mode: 'require-protected',
142
+ retentionMs: 14 * 24 * 60 * 60 * 1000,
143
+ isCurrentMember: async (groupId, userId) => true,
144
+ },
145
+ }
146
+ ```
147
+
148
+ The client reads the `protection` that the local store declares and derives
149
+ a level:
150
+
151
+ | Level | Store protection | Built-in stores |
152
+ | --- | --- | --- |
153
+ | `protected` | Encrypted, with the key in an operating system keychain or a declared application vault | SQLite and key-value stores with a keychain or application vault |
154
+ | `co-located` | Encrypted, with the key in storage that the data shares | `IndexedDbSignalProtocolStore`, and the web SQLite store with the IndexedDB vault |
155
+ | `none` | No encryption or no key | `InMemorySignalProtocolStore`, and a SQLite store with `encryptionAtRest: false` |
156
+
157
+ The `co-located` stores encrypt their data. `IndexedDbSignalProtocolStore`
158
+ encrypts each record and each metadata value with AES-256-GCM. Its key is in
159
+ the same database. The web SQLite store encrypts its whole file. That is weaker
160
+ key custody, not missing encryption. A reader of the origin storage can also
161
+ read the key. Metadata key names stay in clear text in
162
+ `IndexedDbSignalProtocolStore`.
163
+
164
+ The modes:
165
+
166
+ - `require-protected`, the default, keeps content only at the `protected`
167
+ level.
168
+ - `allow-co-located-key` also keeps content at the `co-located` level. Use it
169
+ only after a product review accepts that key custody.
170
+ - `off` keeps no content.
171
+
172
+ A `none` level never keeps content. When the policy refuses the store, the
173
+ client keeps no pairwise message record and no send log entry, and deletes
174
+ the ones that the store already holds. A retry request for a direct message
175
+ then resets the session with no content. The client shows the decision in
176
+ `client.contentRecoveryStatus`, with `reason` when it is off, and logs it
177
+ once at creation.
178
+
179
+ The client keeps content for 14 days from the time that it first stored it.
180
+ A retry does not extend that time. Signal uses the same default:
181
+ `retryRespondMaxAge` on Android and `messageSendLogEntryLifetime` on iOS are
182
+ both 14 days. `retentionMs` sets another value, at most 30 days. A message
183
+ that the Relay delivers after the retention may have no resendable content.
184
+
185
+ The client deletes expired content before each send log lookup, at creation,
186
+ at `stop()`, and before the first resendable group send of each day. An E2EE
187
+ delivery receipt from a device deletes the send log row of that device, and
188
+ the last row takes the content with it. A Relay delivery receipt, a read
189
+ receipt, and a viewed receipt delete no row. A device also acknowledges a
190
+ copy that it could not decrypt, so the Relay receipt does not prove that the
191
+ device has the content. `client.getPendingRecipients(clientMessageId)` lists
192
+ the devices that still have a row. `client.forgetSentContent(clientMessageId)`
193
+ deletes the content of one group send at once. It does not delete the
194
+ pairwise message records. A device lifecycle reset clears the send log with
195
+ the other local crypto state.
196
+
197
+ Before the sender gives group content again, it checks a group membership
198
+ source. Configure `groups` with `resolveAciBytesByUserIds` for managed
199
+ groups, or set `isCurrentMember` for ad hoc groups. The client checks a
200
+ managed group against its verified group state and never asks the hook
201
+ about it. The hook gets the prefixed group ID that `createGroupId` makes.
202
+ `contentRecoveryStatus.groupMembershipSource` is `managed`, `hook`, or
203
+ `none`. A client with no source still keeps content and logs one warning
204
+ at creation. With no source for a group, the sender gives no group content
205
+ again. A direct message resend needs no source.
206
+
207
+ A group send of a `DataMessage` has the content hint `Resendable` when the
208
+ policy keeps content and the application sets no other hint. The client
209
+ writes the content and the recipient devices to the send log before it
210
+ stores the outgoing intent, so a failed write stops the send. When the
211
+ policy keeps no content, the send goes out as `Default`.
212
+
213
+ A custom store must declare its `protection` as `{ atRest, keyCustody }`.
214
+ The client validates the declaration and fails creation on a missing or
215
+ unknown value. A declaration adds no encryption. It must state what the
216
+ store does.
package/docs/RECIPES.md CHANGED
@@ -89,21 +89,9 @@ without post-quantum material fail closed, and PQ sessions use the SDK's
89
89
  ML-KEM Braid SPQR profile. See the [protocol policy](./PROTOCOL_POLICY.md) for
90
90
  supported choices.
91
91
 
92
- <!-- doc-snippet:skip requires-external-context -->
93
- ```ts
94
- await createSignalProtocolClient({
95
- identity: { userId },
96
- adapters: { storage, relay },
97
- protocol: {
98
- postQuantum: "compatible",
99
- braid: "required",
100
- },
101
- });
102
- ```
103
-
104
- `postQuantum: 'compatible'` still uses post-quantum sessions whenever the peer
105
- supports them. It only allows classical compatibility for peers that advertise
106
- no post-quantum material at all.
92
+ `'required'` is the only `postQuantum` value. The SDK has no classical key
93
+ agreement, so a peer that advertises no post-quantum material fails with
94
+ `PQXDH_REQUIRED`.
107
95
 
108
96
  <!-- doc-snippet:skip requires-external-context -->
109
97
  ```ts
package/docs/SECURITY.md CHANGED
@@ -42,7 +42,7 @@ implement XEdDSA and cannot consume or produce XEdDSA identity signatures.
42
42
 
43
43
  ### PQXDH and ML-KEM-1024
44
44
 
45
- - Required post-quantum session establishment is the default.
45
+ - Post-quantum session establishment is mandatory.
46
46
  - PQXDH uses standardized FIPS 203 ML-KEM-1024 behavior.
47
47
  - Public keys and ciphertexts require exactly `0x0A || raw ML-KEM-1024 bytes`.
48
48
  Untagged values, the deployed Kyber1024 `0x08` tag, unknown tags, and wrong
@@ -50,9 +50,8 @@ implement XEdDSA and cannot consume or produce XEdDSA identity signatures.
50
50
  - Prekey signatures cover a domain-separated context. That context contains the
51
51
  locally derived composite identity commitment, algorithm tag, key ID, and
52
52
  complete tagged public key.
53
- - `protocol.postQuantum: 'compatible'` is an explicit opt-in. It permits a
54
- classical session only when a peer advertises no PQ material. Malformed or
55
- failed PQ processing does not trigger fallback.
53
+ - No classical key agreement exists. A peer that advertises no PQ material
54
+ fails with `PQXDH_REQUIRED`. Malformed or failed PQ processing fails closed.
56
55
 
57
56
  The `0x0A` encoding is distinct from Signal Messenger deployments that use
58
57
  round-3 Kyber1024 tagged `0x08`.
@@ -138,6 +137,8 @@ requires stronger timing or erasure assurance.
138
137
 
139
138
  ## Storage Boundary
140
139
 
140
+ Reviewed: 2026-10-20.
141
+
141
142
  Local adapters own identity keys, contact trust metadata, prekeys, session
142
143
  records, retry records, and group state. The package requires:
143
144
 
@@ -146,7 +147,8 @@ records, retry records, and group state. The package requires:
146
147
  - that an adapter reject stale-format writes before it replaces current state.
147
148
  - that an adapter remove or reject stale persisted session records on read.
148
149
  - no authoritative cached identity commitment.
149
- - authenticated encryption for adapters that persist encrypted records.
150
+ - authenticated encryption of records and metadata values in an adapter that
151
+ declares a cipher.
150
152
 
151
153
  Adapter encryption does not compensate for:
152
154
 
@@ -157,6 +159,89 @@ Adapter encryption does not compensate for:
157
159
  Browser IndexedDB and caller-provided React Native storage inherit their host
158
160
  application's security boundary.
159
161
 
162
+ Each local store declares its `protection`: how it encrypts its data at rest
163
+ (`atRest`) and where it keeps the key (`keyCustody`). Client creation fails
164
+ when the store declares no `protection`, an unknown value, or a cipher
165
+ without a key. The client derives a level from the declaration, and
166
+ [Content Recovery](./PROTOCOL_POLICY.md#content-recovery) uses that level to
167
+ decide whether the store may hold resendable content. The built-in stores
168
+ declare:
169
+
170
+ | Store | `atRest` | `keyCustody` | Level |
171
+ | --- | --- | --- | --- |
172
+ | Expo or React Native SQLite store, default vault | `file-cipher` | `os-keychain` | `protected` |
173
+ | Node SQLite store with the Electron safeStorage vault | `file-cipher` | `os-keychain` | `protected` |
174
+ | Web SQLite store, default IndexedDB vault | `file-cipher` | `same-origin` | `co-located` |
175
+ | `IndexedDbSignalProtocolStore` | `record-cipher` | `same-origin` | `co-located` |
176
+ | `KeyValueSignalProtocolStore` | `record-cipher` | The custody of its vault | From the vault |
177
+ | Any SQLite store with `encryptionAtRest: false` | `none` | `none` | `none` |
178
+ | `InMemorySignalProtocolStore` | `none` | `none` | `none` |
179
+
180
+ A SQLite store with another vault, and a key-value store, take the custody
181
+ that the vault declares. A vault that declares no custody counts as
182
+ `same-origin`. An encrypted store with a vault that declares `app-vault` is
183
+ `protected`. That declaration is a claim of the application, and the SDK
184
+ cannot check it.
185
+
186
+ The record-cipher stores encrypt each metadata value as well as each record.
187
+ Metadata values include group master keys, the device authentication key, and
188
+ outbox intents. Metadata key names stay in clear text in these stores. Some
189
+ names hold an identifier: a group ID, a recipient user ID, or a message ID. A
190
+ reader of the storage can see these identifiers and the number of entries, but
191
+ not the values. An encrypted SQLite store keeps the metadata keys and values
192
+ inside its file cipher.
193
+
194
+ A record-cipher store encrypts clear metadata values from an earlier SDK when
195
+ it opens. It writes its migration marker last, so a stop during the migration
196
+ is safe. When the storage is full, the store still opens, keeps those values
197
+ clear, and tries again at the next open. An earlier SDK cannot read the
198
+ encrypted values.
199
+
200
+ Retention and deletion limit how long the store holds content. They do not
201
+ erase it. The SQLite stores do not set `secure_delete`, so a deleted row
202
+ can stay in free pages of the file and in the SQLite journal until SQLite
203
+ writes over it. Flash storage, backups, and the browser storage can also
204
+ keep earlier copies. A reader who has an earlier copy and its key can read
205
+ content that the store deleted. The SDK does not promise erasure.
206
+
207
+ The store also keeps receive records: the plaintext of each envelope that
208
+ the client decrypted on the Relay subscription path, in
209
+ `receiveIncomingEnvelopes`, or in `processIncomingEnvelope`. A record is
210
+ written in the same transaction as the ratchet or sender key state, so a
211
+ crash before the application handles the message does not lose it. The
212
+ content recovery policy does not cover it, so every store keeps it, also a
213
+ store with the level `none`. The client deletes a record after the
214
+ application handles its content and its E2EE delivery receipt is sent. Content
215
+ that waits 30 days runs `onReceiveExpired`, and the client then deletes
216
+ its record. No setting changes the 30 days.
217
+ A record that waits only for its E2EE delivery receipt is deleted 1 day after
218
+ the receipt becomes due, or at its age when that comes first, with no
219
+ receipt, no `onMessageDecrypted` call, and no `onReceiveExpired` report,
220
+ because the application has its content. When the record is a
221
+ resend, its completion still reports `onDeliveryRecovered` through its gate. `maxItems` and `maxBytes` bound how many records the store holds.
222
+
223
+ ### Storage protection audit
224
+
225
+ Encryption, key custody, and content recovery are separate properties. This
226
+ table shows how the built-in configurations combine them:
227
+
228
+ | Configuration | Encryption | Key custody | Content recovery, default `require-protected` | Receive records | Consequence |
229
+ | --- | --- | --- | --- | --- | --- |
230
+ | Expo, React Native, or Node SQLite store with a keychain vault | File cipher | Operating system keychain | Kept at `protected` | File cipher | Full content recovery |
231
+ | Web SQLite store, default IndexedDB vault | File cipher | `same-origin`, co-located | Off unless `allow-co-located-key` | File cipher | Same custody as `IndexedDbSignalProtocolStore`. A switch between them adds no custody strength |
232
+ | `IndexedDbSignalProtocolStore` | Record cipher, AES-256-GCM, on records and metadata values | Key in the same database, co-located | Off unless `allow-co-located-key` | Record cipher | Metadata key names stay in clear text |
233
+ | `KeyValueSignalProtocolStore` | Record cipher, AES-256-GCM, on records and metadata values | The custody of its vault, default `same-origin` | Kept with an `os-keychain` or `app-vault` vault. A `same-origin` vault needs `allow-co-located-key` | Record cipher | Metadata key names stay in clear text |
234
+ | Any SQLite store with `encryptionAtRest: false` | None | None | Off | Clear text on disk | Same exposure as the sessions on that store |
235
+ | `InMemorySignalProtocolStore` | None, process memory only | None | Off | Lost at restart | A message that the client acknowledged but the application did not handle is lost at restart |
236
+ | Custom store | As declared | As declared | From the declaration | As declared | The SDK cannot check the stored bytes |
237
+
238
+ The client checks only the shape of a `protection` declaration. It cannot
239
+ check that the bytes on disk are encrypted or where the key is. A custom store
240
+ must commit the ratchet state and the receive record in one transaction. It
241
+ must declare `protection` truthfully, and keep the key outside the data store
242
+ when it declares `protected`. Do not restore a store from a backup while the
243
+ client runs. An earlier ratchet state makes later messages fail to decrypt.
244
+
160
245
  Group sender key state never leaves the device. A sender key record holds the
161
246
  chain key that every message key on that chain derives from, and the sender's
162
247
  private signature key. Together they are enough to read a sender's group
package/keys/README.md CHANGED
@@ -29,8 +29,8 @@ const signedPreKey = await generateEcSignedPreKey(identity);
29
29
  ```
30
30
 
31
31
  Ordinary application code usually lets `SignalProtocolClient` generate and
32
- persist this material. Direct key APIs serve adapter, provisioning, and
33
- advanced lifecycle integrations.
32
+ persist this material. Direct key APIs serve adapter, device transfer,
33
+ and advanced lifecycle integrations.
34
34
 
35
35
  ## Composite identity
36
36
 
@@ -91,7 +91,7 @@ For ML-KEM-1024, `serialized public key` includes the `0x0A` tag.
91
91
  ## Prekey bundle
92
92
 
93
93
  `PreKeyBundle` carries one composite identity and the device-specific material
94
- needed for X3DH/PQXDH session establishment:
94
+ needed for PQXDH session establishment:
95
95
 
96
96
  - registration ID and device ID.
97
97
  - composite identity tuple.