@open-e2ee/signal-protocol-sdk 14.1.0 → 14.2.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 (408) hide show
  1. package/ADAPTERS.md +5 -5
  2. package/ARCHITECTURE.md +1 -1
  3. package/CHANGELOG.md +415 -0
  4. package/README.md +19 -14
  5. package/SECURITY.md +2 -2
  6. package/TROUBLESHOOTING.md +1 -1
  7. package/client/README.md +32 -21
  8. package/device/README.md +5 -5
  9. package/dist/client/client.d.ts +44 -34
  10. package/dist/client/client.d.ts.map +1 -1
  11. package/dist/client/client.js +221 -146
  12. package/dist/client/client.js.map +1 -1
  13. package/dist/client/compose.d.ts +7 -5
  14. package/dist/client/compose.d.ts.map +1 -1
  15. package/dist/client/compose.js +7 -2
  16. package/dist/client/compose.js.map +1 -1
  17. package/dist/client/config.d.ts +23 -14
  18. package/dist/client/config.d.ts.map +1 -1
  19. package/dist/client/config.js.map +1 -1
  20. package/dist/client/content-adapter.d.ts +9 -0
  21. package/dist/client/content-adapter.d.ts.map +1 -1
  22. package/dist/client/content-adapter.js +6 -0
  23. package/dist/client/content-adapter.js.map +1 -1
  24. package/dist/client/delivery-status.d.ts +2 -2
  25. package/dist/client/delivery-status.d.ts.map +1 -1
  26. package/dist/client/delivery-status.js +10 -4
  27. package/dist/client/delivery-status.js.map +1 -1
  28. package/dist/client/device-set-reconciliation.d.ts +24 -16
  29. package/dist/client/device-set-reconciliation.d.ts.map +1 -1
  30. package/dist/client/device-set-reconciliation.js +17 -14
  31. package/dist/client/device-set-reconciliation.js.map +1 -1
  32. package/dist/client/event-hooks.d.ts +22 -7
  33. package/dist/client/event-hooks.d.ts.map +1 -1
  34. package/dist/client/event-hooks.js +35 -5
  35. package/dist/client/event-hooks.js.map +1 -1
  36. package/dist/client/group-device-set.d.ts +1 -1
  37. package/dist/client/group-device-set.d.ts.map +1 -1
  38. package/dist/client/group-key-sync.js +1 -1
  39. package/dist/client/group-key-sync.js.map +1 -1
  40. package/dist/client/group-outbox.d.ts +7 -7
  41. package/dist/client/group-outbox.d.ts.map +1 -1
  42. package/dist/client/group-outbox.js +24 -24
  43. package/dist/client/group-outbox.js.map +1 -1
  44. package/dist/client/group-sealed-sender.d.ts +1 -1
  45. package/dist/client/group-sealed-sender.d.ts.map +1 -1
  46. package/dist/client/group-sender-key-operations.js +1 -1
  47. package/dist/client/group-sender-key-operations.js.map +1 -1
  48. package/dist/client/headless.d.ts +6 -6
  49. package/dist/client/headless.d.ts.map +1 -1
  50. package/dist/client/headless.js +7 -7
  51. package/dist/client/headless.js.map +1 -1
  52. package/dist/client/hosted-anonymous-delivery.d.ts +6 -6
  53. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
  54. package/dist/client/hosted-anonymous-delivery.js +17 -17
  55. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  56. package/dist/client/hosted-assertion-id.d.ts +1 -1
  57. package/dist/client/hosted-assertion-id.d.ts.map +1 -1
  58. package/dist/client/hosted-assertion-id.js +1 -1
  59. package/dist/client/hosted-assertion-id.js.map +1 -1
  60. package/dist/client/hosted-connection.d.ts +5 -5
  61. package/dist/client/hosted-connection.d.ts.map +1 -1
  62. package/dist/client/hosted-connection.js +32 -32
  63. package/dist/client/hosted-connection.js.map +1 -1
  64. package/dist/client/hosted-device-link-transport.d.ts +2 -2
  65. package/dist/client/hosted-device-link-transport.d.ts.map +1 -1
  66. package/dist/client/hosted-device-link-transport.js +1 -1
  67. package/dist/client/hosted-device-link-transport.js.map +1 -1
  68. package/dist/client/hosted-device-link.d.ts +5 -1
  69. package/dist/client/hosted-device-link.d.ts.map +1 -1
  70. package/dist/client/hosted-device-link.js +7 -4
  71. package/dist/client/hosted-device-link.js.map +1 -1
  72. package/dist/client/hosted-device-standing.d.ts +13 -5
  73. package/dist/client/hosted-device-standing.d.ts.map +1 -1
  74. package/dist/client/hosted-device-standing.js +11 -6
  75. package/dist/client/hosted-device-standing.js.map +1 -1
  76. package/dist/client/hosted-group-authority.d.ts +2 -2
  77. package/dist/client/hosted-group-authority.d.ts.map +1 -1
  78. package/dist/client/hosted-group-authority.js +8 -8
  79. package/dist/client/hosted-group-authority.js.map +1 -1
  80. package/dist/client/hosted-groups.d.ts +4 -4
  81. package/dist/client/hosted-groups.d.ts.map +1 -1
  82. package/dist/client/hosted-groups.js +8 -8
  83. package/dist/client/hosted-groups.js.map +1 -1
  84. package/dist/client/hosted-http-error.d.ts +8 -4
  85. package/dist/client/hosted-http-error.d.ts.map +1 -1
  86. package/dist/client/hosted-http-error.js +7 -4
  87. package/dist/client/hosted-http-error.js.map +1 -1
  88. package/dist/client/hosted-mailbox-subscription.d.ts +10 -10
  89. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  90. package/dist/client/hosted-mailbox-subscription.js +17 -17
  91. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  92. package/dist/client/hosted-prekey-publication.d.ts +9 -9
  93. package/dist/client/hosted-prekey-publication.d.ts.map +1 -1
  94. package/dist/client/hosted-prekey-publication.js.map +1 -1
  95. package/dist/client/hosted-presence-frames.d.ts +62 -38
  96. package/dist/client/hosted-presence-frames.d.ts.map +1 -1
  97. package/dist/client/hosted-presence-frames.js +4 -2
  98. package/dist/client/hosted-presence-frames.js.map +1 -1
  99. package/dist/client/hosted-presence.d.ts +22 -14
  100. package/dist/client/hosted-presence.d.ts.map +1 -1
  101. package/dist/client/hosted-presence.js +26 -17
  102. package/dist/client/hosted-presence.js.map +1 -1
  103. package/dist/client/hosted-profile-keys.d.ts +3 -1
  104. package/dist/client/hosted-profile-keys.d.ts.map +1 -1
  105. package/dist/client/hosted-profile-keys.js +19 -15
  106. package/dist/client/hosted-profile-keys.js.map +1 -1
  107. package/dist/client/hosted-push.d.ts +38 -16
  108. package/dist/client/hosted-push.d.ts.map +1 -1
  109. package/dist/client/hosted-push.js +11 -5
  110. package/dist/client/hosted-push.js.map +1 -1
  111. package/dist/client/hosted-resume-error.d.ts +21 -9
  112. package/dist/client/hosted-resume-error.d.ts.map +1 -1
  113. package/dist/client/hosted-resume-error.js +4 -1
  114. package/dist/client/hosted-resume-error.js.map +1 -1
  115. package/dist/client/hosted-resume.d.ts +3 -3
  116. package/dist/client/hosted-resume.d.ts.map +1 -1
  117. package/dist/client/hosted-resume.js +12 -12
  118. package/dist/client/hosted-resume.js.map +1 -1
  119. package/dist/client/hosted-sandbox-identity.d.ts +32 -18
  120. package/dist/client/hosted-sandbox-identity.d.ts.map +1 -1
  121. package/dist/client/hosted-sandbox-identity.js +46 -27
  122. package/dist/client/hosted-sandbox-identity.js.map +1 -1
  123. package/dist/client/hosted-store-records.d.ts +46 -0
  124. package/dist/client/hosted-store-records.d.ts.map +1 -0
  125. package/dist/client/hosted-store-records.js +32 -0
  126. package/dist/client/hosted-store-records.js.map +1 -0
  127. package/dist/client/hosted-transport.d.ts +41 -33
  128. package/dist/client/hosted-transport.d.ts.map +1 -1
  129. package/dist/client/hosted-transport.js +146 -101
  130. package/dist/client/hosted-transport.js.map +1 -1
  131. package/dist/client/hosted-trust.d.ts +1 -1
  132. package/dist/client/hosted-trust.d.ts.map +1 -1
  133. package/dist/client/hosted-trust.js +1 -1
  134. package/dist/client/hosted-trust.js.map +1 -1
  135. package/dist/client/hosted.d.ts +140 -74
  136. package/dist/client/hosted.d.ts.map +1 -1
  137. package/dist/client/hosted.js +102 -60
  138. package/dist/client/hosted.js.map +1 -1
  139. package/dist/client/index.d.ts +4 -4
  140. package/dist/client/index.d.ts.map +1 -1
  141. package/dist/client/index.js +4 -4
  142. package/dist/client/index.js.map +1 -1
  143. package/dist/client/key-rotation-core.d.ts +4 -4
  144. package/dist/client/key-rotation-core.d.ts.map +1 -1
  145. package/dist/client/key-rotation-core.js +8 -8
  146. package/dist/client/key-rotation-core.js.map +1 -1
  147. package/dist/client/key-rotation.js +2 -2
  148. package/dist/client/key-rotation.js.map +1 -1
  149. package/dist/client/messages.d.ts +3 -3
  150. package/dist/client/messages.d.ts.map +1 -1
  151. package/dist/client/messages.js +18 -18
  152. package/dist/client/messages.js.map +1 -1
  153. package/dist/client/one-time-prekey-refill.d.ts +1 -1
  154. package/dist/client/one-time-prekey-refill.d.ts.map +1 -1
  155. package/dist/client/prekeys.js +17 -17
  156. package/dist/client/prekeys.js.map +1 -1
  157. package/dist/client/receive-queue.d.ts +4 -4
  158. package/dist/client/receive-queue.d.ts.map +1 -1
  159. package/dist/client/receive-queue.js +29 -29
  160. package/dist/client/receive-queue.js.map +1 -1
  161. package/dist/client/receive-work-seed.d.ts +6 -2
  162. package/dist/client/receive-work-seed.d.ts.map +1 -1
  163. package/dist/client/receive-work-seed.js.map +1 -1
  164. package/dist/client/recovery-driver.js +7 -7
  165. package/dist/client/recovery-driver.js.map +1 -1
  166. package/dist/client/retry-request-envelope.d.ts +3 -3
  167. package/dist/client/retry-request-envelope.d.ts.map +1 -1
  168. package/dist/client/retry-request-envelope.js +10 -10
  169. package/dist/client/retry-request-envelope.js.map +1 -1
  170. package/dist/client/retry-request-lifecycle.d.ts +1 -1
  171. package/dist/client/retry-request-lifecycle.d.ts.map +1 -1
  172. package/dist/client/retry-request-lifecycle.js +8 -8
  173. package/dist/client/retry-request-lifecycle.js.map +1 -1
  174. package/dist/client/retry-terminal-recovery.js +2 -2
  175. package/dist/client/retry-terminal-recovery.js.map +1 -1
  176. package/dist/client/retry.js +13 -13
  177. package/dist/client/retry.js.map +1 -1
  178. package/dist/client/sealed-sender.d.ts +13 -4
  179. package/dist/client/sealed-sender.d.ts.map +1 -1
  180. package/dist/client/sealed-sender.js +27 -15
  181. package/dist/client/sealed-sender.js.map +1 -1
  182. package/dist/client/send-deadline.d.ts +7 -7
  183. package/dist/client/send-deadline.d.ts.map +1 -1
  184. package/dist/client/send-deadline.js +37 -24
  185. package/dist/client/send-deadline.js.map +1 -1
  186. package/dist/client/send-intent-driver.js +9 -9
  187. package/dist/client/send-intent-driver.js.map +1 -1
  188. package/dist/client/sessions.js +11 -11
  189. package/dist/client/sessions.js.map +1 -1
  190. package/dist/client/{relay-acceptance.d.ts → signal-relay-acceptance.d.ts} +9 -9
  191. package/dist/client/signal-relay-acceptance.d.ts.map +1 -0
  192. package/dist/client/{relay-acceptance.js → signal-relay-acceptance.js} +7 -7
  193. package/dist/client/signal-relay-acceptance.js.map +1 -0
  194. package/dist/client/{relay-device-refusal.d.ts → signal-relay-device-refusal.d.ts} +7 -7
  195. package/dist/client/signal-relay-device-refusal.d.ts.map +1 -0
  196. package/dist/client/{relay-device-refusal.js → signal-relay-device-refusal.js} +9 -9
  197. package/dist/client/signal-relay-device-refusal.js.map +1 -0
  198. package/dist/client/{relay-lifecycle.d.ts → signal-relay-lifecycle.d.ts} +21 -11
  199. package/dist/client/signal-relay-lifecycle.d.ts.map +1 -0
  200. package/dist/client/{relay-lifecycle.js → signal-relay-lifecycle.js} +19 -9
  201. package/dist/client/signal-relay-lifecycle.js.map +1 -0
  202. package/dist/client/{relay-period-close.d.ts → signal-relay-period-close.d.ts} +1 -1
  203. package/dist/client/signal-relay-period-close.d.ts.map +1 -0
  204. package/dist/client/{relay-period-close.js → signal-relay-period-close.js} +1 -1
  205. package/dist/client/signal-relay-period-close.js.map +1 -0
  206. package/dist/client/{relay-protocol.d.ts → signal-relay-protocol.d.ts} +12 -8
  207. package/dist/client/signal-relay-protocol.d.ts.map +1 -0
  208. package/dist/client/{relay-protocol.js → signal-relay-protocol.js} +13 -10
  209. package/dist/client/signal-relay-protocol.js.map +1 -0
  210. package/dist/client/{relay-receipt-intake.d.ts → signal-relay-receipt-intake.d.ts} +12 -12
  211. package/dist/client/signal-relay-receipt-intake.d.ts.map +1 -0
  212. package/dist/client/{relay-receipt-intake.js → signal-relay-receipt-intake.js} +9 -9
  213. package/dist/client/signal-relay-receipt-intake.js.map +1 -0
  214. package/dist/client/{relay-receipt-join.d.ts → signal-relay-receipt-join.d.ts} +8 -8
  215. package/dist/client/signal-relay-receipt-join.d.ts.map +1 -0
  216. package/dist/client/{relay-receipt-join.js → signal-relay-receipt-join.js} +11 -11
  217. package/dist/client/signal-relay-receipt-join.js.map +1 -0
  218. package/dist/client/{relay-request-deadline.d.ts → signal-relay-request-deadline.d.ts} +3 -3
  219. package/dist/client/signal-relay-request-deadline.d.ts.map +1 -0
  220. package/dist/client/{relay-request-deadline.js → signal-relay-request-deadline.js} +4 -4
  221. package/dist/client/signal-relay-request-deadline.js.map +1 -0
  222. package/dist/client/{relay-sealed-route.d.ts → signal-relay-sealed-route.d.ts} +1 -1
  223. package/dist/client/signal-relay-sealed-route.d.ts.map +1 -0
  224. package/dist/client/{relay-sealed-route.js → signal-relay-sealed-route.js} +1 -1
  225. package/dist/client/signal-relay-sealed-route.js.map +1 -0
  226. package/dist/client/{relay-subscription.d.ts → signal-relay-subscription.d.ts} +12 -12
  227. package/dist/client/signal-relay-subscription.d.ts.map +1 -0
  228. package/dist/client/{relay-subscription.js → signal-relay-subscription.js} +23 -23
  229. package/dist/client/signal-relay-subscription.js.map +1 -0
  230. package/dist/client/{relay-work.d.ts → signal-relay-work.d.ts} +7 -7
  231. package/dist/client/signal-relay-work.d.ts.map +1 -0
  232. package/dist/client/{relay-work.js → signal-relay-work.js} +13 -13
  233. package/dist/client/signal-relay-work.js.map +1 -0
  234. package/dist/client/signal-service-cipher.d.ts +11 -9
  235. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  236. package/dist/client/signal-service-cipher.js +103 -98
  237. package/dist/client/signal-service-cipher.js.map +1 -1
  238. package/dist/client/state.d.ts +4 -4
  239. package/dist/client/state.d.ts.map +1 -1
  240. package/dist/client/state.js +3 -3
  241. package/dist/client/state.js.map +1 -1
  242. package/dist/client/types.d.ts +13 -4
  243. package/dist/client/types.d.ts.map +1 -1
  244. package/dist/client/types.js.map +1 -1
  245. package/dist/device/connection.d.ts +10 -4
  246. package/dist/device/connection.d.ts.map +1 -1
  247. package/dist/device/connection.js +8 -3
  248. package/dist/device/connection.js.map +1 -1
  249. package/dist/device/index.d.ts +2 -2
  250. package/dist/device/index.d.ts.map +1 -1
  251. package/dist/device/index.js +1 -1
  252. package/dist/device/index.js.map +1 -1
  253. package/dist/device/types.d.ts +3 -1
  254. package/dist/device/types.d.ts.map +1 -1
  255. package/dist/hooks/index.d.ts +2 -2
  256. package/dist/hooks/index.d.ts.map +1 -1
  257. package/dist/hooks/index.js +2 -2
  258. package/dist/hooks/index.js.map +1 -1
  259. package/dist/hooks/use-signal-relay-connection-state.d.ts +40 -0
  260. package/dist/hooks/use-signal-relay-connection-state.d.ts.map +1 -0
  261. package/dist/hooks/use-signal-relay-connection-state.js +45 -0
  262. package/dist/hooks/use-signal-relay-connection-state.js.map +1 -0
  263. package/dist/hooks/use-signal-relay-lifecycle.d.ts +43 -0
  264. package/dist/hooks/use-signal-relay-lifecycle.d.ts.map +1 -0
  265. package/dist/hooks/use-signal-relay-lifecycle.js +38 -0
  266. package/dist/hooks/use-signal-relay-lifecycle.js.map +1 -0
  267. package/dist/index.d.ts +18 -12
  268. package/dist/index.d.ts.map +1 -1
  269. package/dist/index.js +5 -5
  270. package/dist/index.js.map +1 -1
  271. package/dist/internal/groups/authority-certificate.d.ts +7 -1
  272. package/dist/internal/groups/authority-certificate.d.ts.map +1 -1
  273. package/dist/internal/groups/authority-certificate.js +29 -6
  274. package/dist/internal/groups/authority-certificate.js.map +1 -1
  275. package/dist/internal/protocol/sealed-sender/certificate.js +2 -2
  276. package/dist/internal/protocol/sealed-sender/certificate.js.map +1 -1
  277. package/dist/internal/protocol/sealed-sender/proto/index.d.ts +1 -1
  278. package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
  279. package/dist/internal/protocol/sealed-sender/proto/index.js +5 -5
  280. package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
  281. package/dist/internal/sesame/device-registry.d.ts +13 -13
  282. package/dist/internal/sesame/device-registry.d.ts.map +1 -1
  283. package/dist/internal/sesame/device-registry.js +20 -20
  284. package/dist/internal/sesame/device-registry.js.map +1 -1
  285. package/dist/local/store/receive-work.d.ts +29 -0
  286. package/dist/local/store/receive-work.d.ts.map +1 -1
  287. package/dist/local/store/receive-work.js +58 -1
  288. package/dist/local/store/receive-work.js.map +1 -1
  289. package/dist/local/store/received-content.d.ts +1 -1
  290. package/dist/local/store/received-content.d.ts.map +1 -1
  291. package/dist/local/store/reliability.d.ts +11 -3
  292. package/dist/local/store/reliability.d.ts.map +1 -1
  293. package/dist/local/store/reliability.js +4 -0
  294. package/dist/local/store/reliability.js.map +1 -1
  295. package/dist/local/store/sqlite/key-storage/index.d.ts +3 -9
  296. package/dist/local/store/sqlite/key-storage/index.d.ts.map +1 -1
  297. package/dist/local/store/sqlite/key-storage/index.js.map +1 -1
  298. package/dist/local/store/sqlite/key-storage/signed-prekeys.d.ts +1 -7
  299. package/dist/local/store/sqlite/key-storage/signed-prekeys.d.ts.map +1 -1
  300. package/dist/local/store/sqlite/key-storage/signed-prekeys.js.map +1 -1
  301. package/dist/local/store/sqlite/models/kyber-prekey.d.ts +4 -9
  302. package/dist/local/store/sqlite/models/kyber-prekey.d.ts.map +1 -1
  303. package/dist/local/store/sqlite/models/kyber-prekey.js +4 -1
  304. package/dist/local/store/sqlite/models/kyber-prekey.js.map +1 -1
  305. package/dist/local/store/sqlite/store.d.ts.map +1 -1
  306. package/dist/local/store/sqlite/store.js +1 -2
  307. package/dist/local/store/sqlite/store.js.map +1 -1
  308. package/dist/remote/signal-relay/connection-state.d.ts +16 -0
  309. package/dist/remote/signal-relay/connection-state.d.ts.map +1 -0
  310. package/dist/remote/{relay → signal-relay}/connection-state.js +1 -1
  311. package/dist/remote/signal-relay/connection-state.js.map +1 -0
  312. package/dist/remote/{relay → signal-relay}/device-set.d.ts +3 -3
  313. package/dist/remote/signal-relay/device-set.d.ts.map +1 -0
  314. package/dist/remote/{relay → signal-relay}/device-set.js +7 -7
  315. package/dist/remote/signal-relay/device-set.js.map +1 -0
  316. package/dist/remote/{relay → signal-relay}/index.d.ts +3 -3
  317. package/dist/remote/signal-relay/index.d.ts.map +1 -0
  318. package/dist/remote/{relay → signal-relay}/index.js +2 -2
  319. package/dist/remote/signal-relay/index.js.map +1 -0
  320. package/dist/remote/{relay → signal-relay}/request-admission.d.ts +2 -2
  321. package/dist/remote/signal-relay/request-admission.d.ts.map +1 -0
  322. package/dist/remote/{relay → signal-relay}/request-admission.js +5 -5
  323. package/dist/remote/signal-relay/request-admission.js.map +1 -0
  324. package/dist/remote/{relay → signal-relay}/types.d.ts +29 -11
  325. package/dist/remote/signal-relay/types.d.ts.map +1 -0
  326. package/dist/remote/{relay → signal-relay}/types.js +1 -1
  327. package/dist/remote/signal-relay/types.js.map +1 -0
  328. package/dist/safety/core.d.ts +1 -1
  329. package/dist/safety/core.js +1 -1
  330. package/dist/types/api.d.ts +43 -20
  331. package/dist/types/api.d.ts.map +1 -1
  332. package/dist/types/errors.d.ts +55 -7
  333. package/dist/types/errors.d.ts.map +1 -1
  334. package/dist/types/errors.js +61 -8
  335. package/dist/types/errors.js.map +1 -1
  336. package/dist/types/renamed-member.d.ts +41 -0
  337. package/dist/types/renamed-member.d.ts.map +1 -0
  338. package/dist/types/renamed-member.js +73 -0
  339. package/dist/types/renamed-member.js.map +1 -0
  340. package/dist/utils/bounded-fan-out.d.ts +2 -2
  341. package/dist/utils/bounded-fan-out.d.ts.map +1 -1
  342. package/dist/utils/bounded-fan-out.js +2 -2
  343. package/dist/utils/bounded-fan-out.js.map +1 -1
  344. package/dist/utils/retry.d.ts +3 -3
  345. package/dist/utils/retry.d.ts.map +1 -1
  346. package/dist/utils/retry.js +4 -3
  347. package/dist/utils/retry.js.map +1 -1
  348. package/docs/ASSURANCE.md +5 -5
  349. package/docs/CLIENT_COMPOSITION.md +10 -8
  350. package/docs/DEVIATIONS.md +10 -7
  351. package/docs/ERROR_HANDLING.md +24 -24
  352. package/docs/GETTING_STARTED.md +22 -16
  353. package/docs/INTERFACES.md +5 -5
  354. package/docs/PACKAGE_SURFACE.md +14 -4
  355. package/docs/PROTOCOL_POLICY.md +4 -4
  356. package/docs/RECIPES.md +274 -15
  357. package/hooks/README.md +11 -11
  358. package/local/store/expo/README.md +1 -1
  359. package/local/store/key-value/README.md +2 -2
  360. package/local/store/node/README.md +1 -1
  361. package/local/store/react-native/README.md +1 -1
  362. package/local/store/web/README.md +1 -1
  363. package/local/store/web-sqlite/README.md +2 -2
  364. package/package.json +16 -6
  365. package/remote/README.md +4 -4
  366. package/remote/object-store/convex-r2/README.md +1 -1
  367. package/remote/{relay → signal-relay}/README.md +14 -6
  368. package/dist/client/relay-acceptance.d.ts.map +0 -1
  369. package/dist/client/relay-acceptance.js.map +0 -1
  370. package/dist/client/relay-device-refusal.d.ts.map +0 -1
  371. package/dist/client/relay-device-refusal.js.map +0 -1
  372. package/dist/client/relay-lifecycle.d.ts.map +0 -1
  373. package/dist/client/relay-lifecycle.js.map +0 -1
  374. package/dist/client/relay-period-close.d.ts.map +0 -1
  375. package/dist/client/relay-period-close.js.map +0 -1
  376. package/dist/client/relay-protocol.d.ts.map +0 -1
  377. package/dist/client/relay-protocol.js.map +0 -1
  378. package/dist/client/relay-receipt-intake.d.ts.map +0 -1
  379. package/dist/client/relay-receipt-intake.js.map +0 -1
  380. package/dist/client/relay-receipt-join.d.ts.map +0 -1
  381. package/dist/client/relay-receipt-join.js.map +0 -1
  382. package/dist/client/relay-request-deadline.d.ts.map +0 -1
  383. package/dist/client/relay-request-deadline.js.map +0 -1
  384. package/dist/client/relay-sealed-route.d.ts.map +0 -1
  385. package/dist/client/relay-sealed-route.js.map +0 -1
  386. package/dist/client/relay-subscription.d.ts.map +0 -1
  387. package/dist/client/relay-subscription.js.map +0 -1
  388. package/dist/client/relay-work.d.ts.map +0 -1
  389. package/dist/client/relay-work.js.map +0 -1
  390. package/dist/hooks/use-relay-connection-state.d.ts +0 -32
  391. package/dist/hooks/use-relay-connection-state.d.ts.map +0 -1
  392. package/dist/hooks/use-relay-connection-state.js +0 -31
  393. package/dist/hooks/use-relay-connection-state.js.map +0 -1
  394. package/dist/hooks/use-relay-lifecycle.d.ts +0 -36
  395. package/dist/hooks/use-relay-lifecycle.d.ts.map +0 -1
  396. package/dist/hooks/use-relay-lifecycle.js +0 -35
  397. package/dist/hooks/use-relay-lifecycle.js.map +0 -1
  398. package/dist/remote/relay/connection-state.d.ts +0 -16
  399. package/dist/remote/relay/connection-state.d.ts.map +0 -1
  400. package/dist/remote/relay/connection-state.js.map +0 -1
  401. package/dist/remote/relay/device-set.d.ts.map +0 -1
  402. package/dist/remote/relay/device-set.js.map +0 -1
  403. package/dist/remote/relay/index.d.ts.map +0 -1
  404. package/dist/remote/relay/index.js.map +0 -1
  405. package/dist/remote/relay/request-admission.d.ts.map +0 -1
  406. package/dist/remote/relay/request-admission.js.map +0 -1
  407. package/dist/remote/relay/types.d.ts.map +0 -1
  408. package/dist/remote/relay/types.js.map +0 -1
@@ -20,14 +20,17 @@ The [adapter guide](../ADAPTERS.md) lists the supported stores.
20
20
 
21
21
  - A Relay project and its environment connection URL. In the application
22
22
  directory, `oe new` creates the project and its Sandbox environment, and it
23
- writes the connection URL to `.env.local` as `OPEN_E2EE_RELAY_URL`. In a
24
- Next.js, Expo, or Vite application, the name has the public prefix of the
25
- framework, for example `EXPO_PUBLIC_OPEN_E2EE_RELAY_URL`.
23
+ writes the connection URL to `.env.local` as `OPEN_E2EE_SIGNAL_RELAY_URL`. In
24
+ a Next.js, Expo, or Vite application, the name has the public prefix of the
25
+ framework, for example `EXPO_PUBLIC_OPEN_E2EE_SIGNAL_RELAY_URL`. An `oe`
26
+ release before 5.0.0 wrote the earlier name, such as
27
+ `EXPO_PUBLIC_OPEN_E2EE_RELAY_URL`. The examples read the new name first and
28
+ the earlier name second.
26
29
  - A `getIdentityAssertion` callback that returns a short-lived signed assertion.
27
30
  - Device-local storage for private keys, sessions, and delivery state.
28
31
  - Application storage for decrypted messages and attachment bytes.
29
32
 
30
- A Sandbox environment uses device-owned identity. `hostedRelaySandboxIdentity`
33
+ A Sandbox environment uses device-owned identity. `hostedSignalProtocolRelaySandboxIdentity`
31
34
  creates its `getIdentityAssertion` callback. The callback keeps a key in the device-local store. It signs each assertion
32
35
  with that key. The device gets the same account each time it registers.
33
36
 
@@ -36,17 +39,20 @@ A device that loses its store loses that Sandbox account. The helper works only
36
39
  Production supports application-bound and explicitly configured device-owned
37
40
  accounts. For application-bound accounts, `getIdentityAssertion` returns a
38
41
  short-lived Relay-specific assertion from your backend after it verifies the
39
- server session and current application membership.
42
+ server session and current application membership. With a
43
+ [native Clerk or Firebase profile](./RECIPES.md#native-provider-profiles),
44
+ `getIdentityAssertion` returns the provider token instead, and no backend
45
+ assertion is needed.
40
46
 
41
47
  Device-owned accounts prove possession of a persistent account key. They do
42
48
  not bind to an application login, and provider sign-in cannot recover a lost
43
49
  account key. For device-owned accounts, pass
44
- `hostedRelayDeviceOwnedIdentity(storage)` as `getIdentityAssertion`. The SDK
50
+ `hostedSignalProtocolRelayDeviceOwnedIdentity(storage)` as `getIdentityAssertion`. The SDK
45
51
  does not supply an identity provider or a relay server implementation.
46
- See [identity and authentication](https://docs.open-e2ee.dev/relay/identity)
52
+ See [identity and authentication](https://docs.open-e2ee.dev/signal-relay/identity)
47
53
  for Production configuration.
48
54
 
49
- For a tested backend path, see the [Better Auth recipe](https://docs.open-e2ee.dev/relay/better-auth)
55
+ For a tested backend path, see the [Better Auth recipe](https://docs.open-e2ee.dev/signal-relay/better-auth)
50
56
  and the [application callback recipe](./RECIPES.md#application-bound-identity-callback).
51
57
 
52
58
  ## Setup Sequence
@@ -54,7 +60,7 @@ and the [application callback recipe](./RECIPES.md#application-bound-identity-ca
54
60
  1. Run `oe new` to create the Relay project and its Sandbox environment.
55
61
  2. Open the device-local store for the device.
56
62
  3. Create the client with `createHostedSignalProtocolClient()`. In a Sandbox
57
- environment, pass `hostedRelaySandboxIdentity(storage)` as
63
+ environment, pass `hostedSignalProtocolRelaySandboxIdentity(storage)` as
58
64
  `hosted.getIdentityAssertion`.
59
65
  4. Register a receive handler that persists decrypted messages.
60
66
  5. Start the relay subscription.
@@ -62,12 +68,12 @@ and the [application callback recipe](./RECIPES.md#application-bound-identity-ca
62
68
  The hosted factory authenticates and registers the current device, then publishes
63
69
  its public prekeys. A linked device gets the account identity by device
64
70
  transfer or by a channel that the application owns, then joins the account
65
- with `linkHostedRelayDevice()`. That call runs in one process that holds the
71
+ with `linkHostedSignalProtocolRelayDevice()`. That call runs in one process that holds the
66
72
  active device's store and the new device's store. It copies each group master
67
73
  key from the active device and gives the new device its own registration ID.
68
74
 
69
75
  It refuses a new device's store that already lists a group, with
70
- `HostedRelayDeviceLinkError`. See the [device guide](../device/README.md). The
76
+ `HostedSignalProtocolRelayDeviceLinkError`. See the [device guide](../device/README.md). The
71
77
  default policy requires post-quantum session establishment and Braid
72
78
  ratcheting.
73
79
 
@@ -83,7 +89,7 @@ Retry with the same stores to retain the original operation and prekeys.
83
89
  ```ts
84
90
  import {
85
91
  createHostedSignalProtocolClient,
86
- hostedRelaySandboxIdentity,
92
+ hostedSignalProtocolRelaySandboxIdentity,
87
93
  } from "@open-e2ee/signal-protocol-sdk";
88
94
  import { expoStore } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
89
95
 
@@ -91,9 +97,9 @@ const storage = await expoStore();
91
97
  const signal = await createHostedSignalProtocolClient({
92
98
  adapters: { storage },
93
99
  hosted: {
94
- relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
100
+ signalProtocolRelayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_SIGNAL_RELAY_URL ?? process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
95
101
  // Sandbox only. Select the Production identity mode explicitly.
96
- getIdentityAssertion: hostedRelaySandboxIdentity(storage),
102
+ getIdentityAssertion: hostedSignalProtocolRelaySandboxIdentity(storage),
97
103
  },
98
104
  });
99
105
  ```
@@ -128,7 +134,7 @@ signal.registerHook("onMessageDecrypted", async (message) => {
128
134
  });
129
135
 
130
136
  // Subscribing starts encrypted envelope delivery and local decryption.
131
- signal.startRelaySubscription();
137
+ signal.startSignalProtocolRelaySubscription();
132
138
  ```
133
139
 
134
140
  The package does not own your product database or UI state. It decrypts messages
@@ -202,7 +208,7 @@ save attachment references and downloaded bytes.
202
208
  import { createHostedSignalProtocolClient, media } from "@open-e2ee/signal-protocol-sdk";
203
209
 
204
210
  const signal = await createHostedSignalProtocolClient({
205
- hosted: { relayUrl, getIdentityAssertion },
211
+ hosted: { signalProtocolRelayUrl, getIdentityAssertion },
206
212
  adapters: {
207
213
  storage,
208
214
  },
@@ -40,7 +40,7 @@ const storage: SignalProtocolLocalStore = appProtocolStore;
40
40
 
41
41
  const client = await createSignalProtocolClient({
42
42
  identity: { userId },
43
- adapters: { storage, relay },
43
+ adapters: { storage, signalProtocolRelay },
44
44
  });
45
45
  ```
46
46
 
@@ -87,10 +87,10 @@ delivery, key rotation, and encrypted group coordination.
87
87
 
88
88
  <!-- doc-snippet:skip requires-external-context -->
89
89
  ```ts
90
- import type { SignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/relay";
90
+ import type { SignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/signal-relay";
91
91
 
92
92
  // An application-owned client transport to an authenticated backend.
93
- const relay: SignalProtocolRelayServer = appRelayTransport;
93
+ const signalProtocolRelay: SignalProtocolRelayServer = appSignalProtocolRelayTransport;
94
94
  ```
95
95
 
96
96
  The hosted factory configures the OpenE2EE Signal Protocol Relay transport.
@@ -128,7 +128,7 @@ The server remains responsible for atomic one-time-key consumption.
128
128
 
129
129
  The relay stores public protocol material, ciphertext, and required routing
130
130
  metadata. It must not require device private keys or decrypted message content.
131
- See the [relay guide](../remote/relay/README.md).
131
+ See the [relay guide](../remote/signal-relay/README.md).
132
132
 
133
133
  ## `SignalProtocolRemoteObjectStore`
134
134
 
@@ -175,7 +175,7 @@ media lifecycle callbacks and client hooks at the client boundary:
175
175
  ```ts
176
176
  const client = await createSignalProtocolClient({
177
177
  identity: { userId },
178
- adapters: { storage, relay, remoteObjectStore },
178
+ adapters: { storage, signalProtocolRelay, remoteObjectStore },
179
179
  media: {
180
180
  preparedUploads: appPreparedUploads,
181
181
  maxPreparedUploadBytes: appUploadBudgetBytes,
@@ -70,8 +70,8 @@ implementations are outside the published SDK.
70
70
 
71
71
  ## Integration subpaths
72
72
 
73
- - `@open-e2ee/signal-protocol-sdk/remote/relay`
74
- - `@open-e2ee/signal-protocol-sdk/remote/relay/types`
73
+ - `@open-e2ee/signal-protocol-sdk/remote/signal-relay`
74
+ - `@open-e2ee/signal-protocol-sdk/remote/signal-relay/types`
75
75
  - `@open-e2ee/signal-protocol-sdk/remote/object-store`
76
76
  - `@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2`
77
77
  - `@open-e2ee/signal-protocol-sdk/remote/object-store/s3`
@@ -131,6 +131,16 @@ implementations are outside the published SDK.
131
131
 
132
132
  - `@open-e2ee/signal-protocol-sdk/local/store/memory`
133
133
 
134
+ ### Deprecated subpaths
135
+
136
+ Each deprecated subpath loads the same module as its replacement. SDK 15.0.0
137
+ removes the deprecated subpaths.
138
+
139
+ | Deprecated subpath | Replacement |
140
+ | --- | --- |
141
+ | `@open-e2ee/signal-protocol-sdk/remote/relay` | `@open-e2ee/signal-protocol-sdk/remote/signal-relay` |
142
+ | `@open-e2ee/signal-protocol-sdk/remote/relay/types` | `@open-e2ee/signal-protocol-sdk/remote/signal-relay/types` |
143
+
134
144
  `internal/**` is implementation-only and not part of the supported external API.
135
145
 
136
146
  ## Basic concepts
@@ -260,7 +270,7 @@ implement the same `MediaAttachmentTransfer` seam.
260
270
 
261
271
  ## Resume an existing hosted device
262
272
 
263
- Use `resumeHostedSignalProtocolClient({ adapters: { storage }, hosted: { relayUrl } })`
273
+ Use `resumeHostedSignalProtocolClient({ adapters: { storage }, hosted: { signalProtocolRelayUrl } })`
264
274
  when the application must preserve the device already held by its open store.
265
275
  The SDK refuses missing, unreadable or changed required identity state. It never
266
276
  falls back to registration, recovery or device linking. The default
@@ -272,7 +282,7 @@ the application configures receive hooks, still run. This API does not promise a
272
282
  store or prove that the store contains every historical message/key.
273
283
 
274
284
  The application owns the store and must not use it concurrently. A
275
- `HostedRelayResumeError` with `cleanupPending` retains a client that has not
285
+ `HostedSignalProtocolRelayResumeError` with `cleanupPending` retains a client that has not
276
286
  completed `stop()`. Keep that error and call `retryCleanup()` only when cleanup is
277
287
  selected. This retries the held stop, never resume or registration, and never
278
288
  closes the application store. Preserve unresolved application operation state.
@@ -32,7 +32,7 @@ the current app.
32
32
  ```ts
33
33
  await createSignalProtocolClient({
34
34
  identity: { userId },
35
- adapters: { storage, relay },
35
+ adapters: { storage, signalProtocolRelay },
36
36
  protocol: { postQuantum: 'required', braid: 'required' },
37
37
  });
38
38
  ```
@@ -60,7 +60,7 @@ No setting allows downgrade recovery:
60
60
  ```ts
61
61
  await createSignalProtocolClient({
62
62
  identity: { userId },
63
- adapters: { storage, relay },
63
+ adapters: { storage, signalProtocolRelay },
64
64
  protocol: { postQuantum: 'required', braid: 'required' },
65
65
  });
66
66
  ```
@@ -78,7 +78,7 @@ See [Deviations §4.1](./DEVIATIONS.md#41-the-hek-operand-order-diverges).
78
78
  ```ts
79
79
  await createSignalProtocolClient({
80
80
  identity: { userId },
81
- adapters: { storage, relay },
81
+ adapters: { storage, signalProtocolRelay },
82
82
  protocol: { postQuantum: 'required', braid: 'disabled' },
83
83
  });
84
84
  ```
@@ -97,7 +97,7 @@ import { BraidPolicy, PostQuantumPolicy, createSignalProtocolClient } from '@ope
97
97
 
98
98
  await createSignalProtocolClient({
99
99
  identity: { userId },
100
- adapters: { storage, relay },
100
+ adapters: { storage, signalProtocolRelay },
101
101
  protocol: {
102
102
  postQuantum: PostQuantumPolicy.Required,
103
103
  braid: BraidPolicy.Required,
package/docs/RECIPES.md CHANGED
@@ -10,9 +10,10 @@ uses public exports only.
10
10
 
11
11
  ## Hosted Client Setup
12
12
 
13
- The recipes require a configured Relay project, an identity-assertion callback,
14
- and device-local storage. Use a Sandbox environment for development, where
15
- `hostedRelaySandboxIdentity(storage)` supplies the callback. The
13
+ The recipes require a configured OpenE2EE Signal Protocol Relay project, an
14
+ identity-assertion callback, and device-local storage. Use a Sandbox
15
+ environment for development, where
16
+ `hostedSignalProtocolRelaySandboxIdentity(storage)` supplies the callback. The
16
17
  [getting-started guide](./GETTING_STARTED.md) describes these inputs.
17
18
 
18
19
  ## Application-bound identity callback
@@ -26,7 +27,7 @@ that assertion. Keep provider credentials and signing keys on the backend.
26
27
  import type { GetIdentityAssertion } from "@open-e2ee/signal-protocol-sdk";
27
28
 
28
29
  const getIdentityAssertion: GetIdentityAssertion = async (request) => {
29
- const response = await fetch("https://application.example/api/relay-identity", {
30
+ const response = await fetch("https://application.example/api/signal-relay-identity", {
30
31
  method: "POST",
31
32
  credentials: "include",
32
33
  headers: { "content-type": "application/json" },
@@ -49,17 +50,275 @@ Replace the example application origin with your authenticated backend.
49
50
  Configure its CSRF controls and cookie policy. Do not send a member ID or
50
51
  provider token from this callback as proof of membership.
51
52
 
52
- The [Better Auth recipe](https://docs.open-e2ee.dev/relay/better-auth) uses a
53
+ The browser callback above uses cookies. Native apps (React Native and Expo)
54
+ use the bearer-credential callback in
55
+ [native apps](https://docs.open-e2ee.dev/signal-relay/custom-token#native-apps-react-native-and-expo).
56
+
57
+ The [Better Auth recipe](https://docs.open-e2ee.dev/signal-relay/better-auth) uses a
53
58
  real server session with the cookie cache disabled. The
54
- [backend contract](https://docs.open-e2ee.dev/relay/backend-identity) lists
55
- other provider paths and their evidence levels. Those paths issue custom-token
56
- assertions. They are not native provider adapters in this package.
59
+ [backend contract](https://docs.open-e2ee.dev/signal-relay/backend-identity) lists
60
+ other provider paths and their evidence levels. Those backend paths issue
61
+ custom-token assertions. The [native provider profiles](#native-provider-profiles)
62
+ use the provider token instead.
57
63
 
58
64
  Application logout and assertion refusal do not revoke existing device proofs.
59
65
  To stop identified access on existing devices, follow the
60
- [suspension procedure](https://docs.open-e2ee.dev/relay/backend-identity#suspend-an-identified-account).
66
+ [suspension procedure](https://docs.open-e2ee.dev/signal-relay/backend-identity#suspend-an-identified-account).
61
67
  Anonymous capabilities retain their separate limits.
62
68
 
69
+ ## Native provider profiles
70
+
71
+ A native provider profile lets the OpenE2EE Signal Protocol Relay verify the
72
+ token of the identity provider itself. The browser callback returns that
73
+ token. No application backend signs a Relay-specific assertion.
74
+
75
+ The Signal Protocol Relay accepts Clerk and Firebase sign-in as native
76
+ identity providers in Sandbox and Production. Select Clerk or Firebase as the
77
+ identity source of the environment in the Console before the first device
78
+ registers. The recipes below give the callback and the Relay verifier contract
79
+ for each profile.
80
+
81
+ Relay applies these checks to both providers:
82
+
83
+ - The token is a JWT signed with RS256. Its header has a `kid`. It has no
84
+ `crit`, `jku`, `jwk`, `x5c`, or `x5u` parameter.
85
+ - The `iss` claim matches the configured issuer. The `sub` claim is the user
86
+ ID of the provider. The issuer and the subject together select one Relay
87
+ account.
88
+ - The `iat` and `exp` claims are integers. The token is not expired, and its
89
+ `nbf` claim, when present, is not in the future.
90
+ - Relay records an identifier for each accepted token. With a `jti` claim,
91
+ the identifier is that claim, and the same token in a second SDK operation
92
+ fails with `ASSERTION_REPLAY`. Without `jti`, Relay derives the identifier
93
+ from the token, the purpose, and the SDK operation.
94
+
95
+ The SDK calls the callback to register a device, to recover the account, and
96
+ to advance an identity migration. Each callback in these recipes asks the
97
+ provider for a new token on each call. It refuses a migration request, because
98
+ one provider session cannot serve as both the source and the target of a
99
+ migration.
100
+
101
+ ### Clerk session token callback
102
+
103
+ The profile names the issuer of the Clerk instance and its authorized
104
+ parties. Relay checks these claims of the Clerk session token:
105
+
106
+ | Claim | Relay rule |
107
+ |---|---|
108
+ | `iss` | The public HTTPS origin of the Clerk instance, with no path or port. |
109
+ | `azp` | One of the 1 to 16 configured authorized parties. A profile accepts a token without `azp` only when it also requires an audience. |
110
+ | `aud` | Absent, unless the profile sets an audience. Then it must match. |
111
+ | `sid`, `v`, `nbf` | Required. `v` is `2`. The `sts` claim, when present, is `active`. |
112
+ | `jti` | Optional. |
113
+ | `exp` | At most 10 minutes after `iat`. |
114
+
115
+ Return the session token itself. A token from a JWT template without the
116
+ session claims fails verification.
117
+
118
+ <!-- doc-snippet:run recipes-clerk-identity-callback expect="clerk register=clerk-session-token migration=This callback does not serve identity migration." -->
119
+ ```ts
120
+ // Real protocol and cryptography; simulated in-memory infrastructure.
121
+ import type {
122
+ GetIdentityAssertion,
123
+ IdentityAssertionRequest,
124
+ } from "@open-e2ee/signal-protocol-sdk";
125
+
126
+ // The part of a loaded Clerk instance that the callback reads.
127
+ interface ClerkSessionSource {
128
+ readonly session?: {
129
+ readonly user: { readonly id: string } | null;
130
+ getToken(options: { skipCache: boolean }): Promise<string | null>;
131
+ } | null;
132
+ }
133
+
134
+ function clerkIdentityAssertion(
135
+ clerk: ClerkSessionSource,
136
+ userId: string,
137
+ ): GetIdentityAssertion {
138
+ return async (request: IdentityAssertionRequest) => {
139
+ if (request.migration || request.purpose === "refresh") {
140
+ throw new Error("This callback does not serve identity migration.");
141
+ }
142
+ const session = clerk.session;
143
+ if (!session || session.user?.id !== userId) {
144
+ throw new Error("Sign in as the user of this device store.");
145
+ }
146
+ // Relay refuses an expired or reused token, so ask for a new one.
147
+ const token = await session.getToken({ skipCache: true });
148
+ if (clerk.session?.user?.id !== userId) {
149
+ throw new Error("The signed-in user changed.");
150
+ }
151
+ if (!token) throw new Error("Clerk returned no session token.");
152
+ return token;
153
+ };
154
+ }
155
+
156
+ // In-memory stand-in for a signed-in Clerk instance.
157
+ const clerk: ClerkSessionSource = {
158
+ session: {
159
+ user: { id: "user_example" },
160
+ getToken: async ({ skipCache }) => (skipCache ? "clerk-session-token" : null),
161
+ },
162
+ };
163
+ const getIdentityAssertion = clerkIdentityAssertion(clerk, "user_example");
164
+ const context = { environment: "sandbox", publishableKey: "example" } as const;
165
+ const token = await getIdentityAssertion({ ...context, purpose: "register" });
166
+ const migration = await getIdentityAssertion({
167
+ ...context,
168
+ purpose: "refresh",
169
+ migration: { action: "prepare", providerRole: "target" },
170
+ }).catch((error: Error) => error.message);
171
+ console.log(`clerk register=${token} migration=${migration}`);
172
+ ```
173
+
174
+ Pass the Clerk instance after it loads, and the user ID of the device store.
175
+ For recovery, Relay reads the factor verification ages in the `fva` claim.
176
+ By default, recovery needs a first-factor verification in the last 5 minutes.
177
+ A profile that requires step-up needs a second-factor verification in the
178
+ last 5 minutes. Otherwise, Relay refuses recovery with `AUTHORITY_DENIED`. Ask
179
+ the user to verify again before you start recovery.
180
+
181
+ ### Firebase ID token callback
182
+
183
+ The profile names the Firebase project. Relay checks these claims of the
184
+ Firebase ID token:
185
+
186
+ | Claim | Relay rule |
187
+ |---|---|
188
+ | `iss` | `https://securetoken.google.com/<project id>` |
189
+ | `aud` | The project ID. |
190
+ | `auth_time` | An integer sign-in time, not later than `iat`. |
191
+ | `firebase.sign_in_provider` | Required. |
192
+ | `firebase.tenant` | Absent. Relay refuses a tenant token. |
193
+ | `exp` | At most 1 hour after `iat`. |
194
+
195
+ Relay accepts project-level tokens only. Sign users in to the project itself,
196
+ not to a tenant.
197
+
198
+ <!-- doc-snippet:run recipes-firebase-identity-callback expect="firebase register=firebase-id-token migration=This callback does not serve identity migration." -->
199
+ ```ts
200
+ // Real protocol and cryptography; simulated in-memory infrastructure.
201
+ import type {
202
+ GetIdentityAssertion,
203
+ IdentityAssertionRequest,
204
+ } from "@open-e2ee/signal-protocol-sdk";
205
+
206
+ // The part of a Firebase Auth instance that the callback reads.
207
+ interface FirebaseUserSource {
208
+ readonly currentUser: {
209
+ readonly uid: string;
210
+ getIdToken(forceRefresh?: boolean): Promise<string>;
211
+ } | null;
212
+ }
213
+
214
+ function firebaseIdentityAssertion(
215
+ auth: FirebaseUserSource,
216
+ uid: string,
217
+ ): GetIdentityAssertion {
218
+ return async (request: IdentityAssertionRequest) => {
219
+ if (request.migration || request.purpose === "refresh") {
220
+ throw new Error("This callback does not serve identity migration.");
221
+ }
222
+ const user = auth.currentUser;
223
+ if (!user || user.uid !== uid) {
224
+ throw new Error("Sign in as the user of this device store.");
225
+ }
226
+ // Relay refuses an expired or reused token, so ask for a new one.
227
+ const token = await user.getIdToken(true);
228
+ if (auth.currentUser?.uid !== uid) {
229
+ throw new Error("The signed-in user changed.");
230
+ }
231
+ return token;
232
+ };
233
+ }
234
+
235
+ // In-memory stand-in for a signed-in Firebase Auth instance.
236
+ const auth: FirebaseUserSource = {
237
+ currentUser: {
238
+ uid: "uid-example",
239
+ getIdToken: async (forceRefresh) =>
240
+ forceRefresh ? "firebase-id-token" : "cached-id-token",
241
+ },
242
+ };
243
+ const getIdentityAssertion = firebaseIdentityAssertion(auth, "uid-example");
244
+ const context = { environment: "sandbox", publishableKey: "example" } as const;
245
+ const token = await getIdentityAssertion({ ...context, purpose: "register" });
246
+ const migration = await getIdentityAssertion({
247
+ ...context,
248
+ purpose: "refresh",
249
+ migration: { action: "prepare", providerRole: "target" },
250
+ }).catch((error: Error) => error.message);
251
+ console.log(`firebase register=${token} migration=${migration}`);
252
+ ```
253
+
254
+ Pass the Auth instance and the user ID of the device store. For recovery,
255
+ Relay reads the sign-in time in `auth_time`. By default, recovery needs a
256
+ sign-in in the last 5 minutes. A profile that requires step-up also needs the
257
+ `firebase.sign_in_second_factor` claim. Otherwise, Relay refuses recovery
258
+ with `AUTHORITY_DENIED`. Ask the user to sign in again before you start
259
+ recovery.
260
+
261
+ ### Native provider lifecycle
262
+
263
+ Open one device store for each provider user, and stop the client at sign-out:
264
+
265
+ <!-- doc-snippet:skip requires-external-context -->
266
+ ```ts
267
+ import { createHostedSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
268
+ import { webSqliteStore } from "@open-e2ee/signal-protocol-sdk/local/store/web-sqlite";
269
+
270
+ // An application-chosen name for this provider user, within the store name rules.
271
+ const storage = await webSqliteStore({ name: storeName });
272
+ const signal = await createHostedSignalProtocolClient({
273
+ adapters: { storage },
274
+ hosted: {
275
+ signalProtocolRelayUrl,
276
+ getIdentityAssertion: firebaseIdentityAssertion(auth, uid),
277
+ },
278
+ });
279
+
280
+ // At provider sign-out, stop the client before another user signs in.
281
+ await signal.stop();
282
+ ```
283
+
284
+ These rules apply to Clerk and Firebase profiles:
285
+
286
+ - **Token refresh.** A registered device resumes its session with its device
287
+ key. The SDK does not call the callback for a resume. A provider token
288
+ refresh or expiry does not change a registered device.
289
+ - **Sign-out.** Provider sign-out does not revoke the device. The store
290
+ resumes its account without the callback. A shared store would give the
291
+ next user the account of the previous user. To stop access on existing
292
+ devices, follow the
293
+ [suspension procedure](https://docs.open-e2ee.dev/signal-relay/backend-identity#suspend-an-identified-account).
294
+ - **Reinstall or lost store.** A new store registers a new device of the same
295
+ account. It has a new Signal identity key, no earlier sessions, and no
296
+ message history. Peers must verify and accept the new key. The earlier
297
+ devices stay active with the old key. Until the earlier devices are removed,
298
+ or until recovery, peers cannot send to all devices of the account. A peer
299
+ that accepted the new key gets `UNTRUSTED_IDENTITY` when it sends to an
300
+ earlier device. A peer that has not accepted it cannot decrypt messages from
301
+ the new device. To keep the account identity, use device linking. Each
302
+ registration reserves one of the five device IDs of the account for good.
303
+ See [Signal Protocol Relay device errors](./ERROR_HANDLING.md#signal-protocol-relay-device-errors).
304
+ - **Device linking.** To keep the account identity on a new device, move the
305
+ identity from an existing device and call `linkHostedSignalProtocolRelayDevice`. Your
306
+ application owns that transfer.
307
+ - **Recovery.** Create the client with `assertionPurpose: "recover"` when no
308
+ device of the account remains. Recovery revokes all earlier devices of the
309
+ account and returns device ID 1. The device ID reservation applies to
310
+ registrations, so recovery starts again at device 1. Recovery does not
311
+ restore message plaintext or sessions. Your application decides when to
312
+ start it. Recovery needs a recent provider sign-in. Sign the user in again
313
+ before you start recovery. Relay refuses a sign-in older than the recovery
314
+ window with HTTP 401 `AUTHORITY_DENIED`. See
315
+ [device lifecycle and recovery](https://docs.open-e2ee.dev/signal-relay/device-lifecycle-and-recovery).
316
+ - **Provider change.** A different provider, Clerk instance, or Firebase
317
+ project gives a different issuer or subject. Relay treats it as a different
318
+ account. An environment keeps its identity profile after its first
319
+ registration. To use another provider, start a new project. See
320
+ [in-use environments](https://docs.open-e2ee.dev/signal-relay/identity#in-use-environments).
321
+
63
322
  ## Production composition with Expo on the Signal Protocol Relay
64
323
 
65
324
  <!-- doc-snippet:skip requires-external-context -->
@@ -74,8 +333,8 @@ const signal = await createHostedSignalProtocolClient({
74
333
  },
75
334
  hosted: {
76
335
  // The environment-scoped connection URL from the OpenE2EE console.
77
- relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
78
- // Returns a short-lived signed assertion for the signed-in user.
336
+ signalProtocolRelayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_SIGNAL_RELAY_URL ?? process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
337
+ // The native app callback: https://docs.open-e2ee.dev/signal-relay/custom-token#native-apps-react-native-and-expo
79
338
  getIdentityAssertion,
80
339
  },
81
340
  });
@@ -90,7 +349,7 @@ must complete the [database setup](../local/store/expo/README.md) first.
90
349
  ```ts
91
350
  const signal = await createSignalProtocolClient({
92
351
  identity: { userId },
93
- adapters: { storage, relay },
352
+ adapters: { storage, signalProtocolRelay },
94
353
  });
95
354
 
96
355
  // Upload public prekeys before other devices need to message this device.
@@ -107,7 +366,7 @@ signal.registerHook("onMessageDecrypted", async (message) => {
107
366
  });
108
367
 
109
368
  // Subscribing starts encrypted envelope delivery and local decryption.
110
- signal.startRelaySubscription();
369
+ signal.startSignalProtocolRelaySubscription();
111
370
 
112
371
  await signal.send(recipientUserId, "hello");
113
372
  ```
@@ -121,7 +380,7 @@ message storage through hooks.
121
380
  ```ts
122
381
  await createSignalProtocolClient({
123
382
  identity: { userId },
124
- adapters: { storage, relay },
383
+ adapters: { storage, signalProtocolRelay },
125
384
  protocol: {
126
385
  postQuantum: "required",
127
386
  braid: "required",
@@ -142,7 +401,7 @@ agreement, so a peer that advertises no post-quantum material fails with
142
401
  ```ts
143
402
  await createSignalProtocolClient({
144
403
  identity: { userId },
145
- adapters: { storage, relay },
404
+ adapters: { storage, signalProtocolRelay },
146
405
  protocol: {
147
406
  postQuantum: "required",
148
407
  braid: "disabled",
package/hooks/README.md CHANGED
@@ -24,21 +24,21 @@ npm install react react-native
24
24
 
25
25
  ```tsx
26
26
  import {
27
- useRelayConnectionState,
28
- useRelayLifecycle,
27
+ useSignalProtocolRelayConnectionState,
28
+ useSignalProtocolRelayLifecycle,
29
29
  useSessionHealth,
30
- type UseRelayLifecycleOptions,
31
- type UseRelayConnectionStateOptions,
30
+ type UseSignalProtocolRelayLifecycleOptions,
31
+ type UseSignalProtocolRelayConnectionStateOptions,
32
32
  type UseSessionHealthOptions,
33
33
  } from "@open-e2ee/signal-protocol-sdk/hooks";
34
34
 
35
- function SignalLifecycle({ signal }: Pick<UseRelayLifecycleOptions, "signal">) {
36
- useRelayLifecycle({ signal });
35
+ function SignalLifecycle({ signal }: Pick<UseSignalProtocolRelayLifecycleOptions, "signal">) {
36
+ useSignalProtocolRelayLifecycle({ signal });
37
37
  return null;
38
38
  }
39
39
 
40
- function OwnConnectionDot({ signal }: Pick<UseRelayConnectionStateOptions, "signal">) {
41
- const { state } = useRelayConnectionState({ signal });
40
+ function OwnConnectionDot({ signal }: Pick<UseSignalProtocolRelayConnectionStateOptions, "signal">) {
41
+ const { state } = useSignalProtocolRelayConnectionState({ signal });
42
42
  return <Dot online={state === "connected"} />;
43
43
  }
44
44
 
@@ -51,7 +51,7 @@ function ConversationStatus({ signal, userId }: Pick<UseSessionHealthOptions, "s
51
51
 
52
52
  ## Relay connection state
53
53
 
54
- `useRelayConnectionState({ signal })` returns the `RelayConnectionState` of
54
+ `useSignalProtocolRelayConnectionState({ signal })` returns the `SignalProtocolRelayConnectionState` of
55
55
  the relay subscription on this device. The component renders again on each
56
56
  transition, and the hook unsubscribes when the component unmounts. The state
57
57
  is `stopped`, `connecting`, `connected`, or `reconnecting`. A `reason` tells
@@ -60,7 +60,7 @@ is not presence and does not tell you about other users.
60
60
 
61
61
  ## Relay lifecycle
62
62
 
63
- `useRelayLifecycle({ signal })` stops the relay subscription when a React
63
+ `useSignalProtocolRelayLifecycle({ signal })` stops the relay subscription when a React
64
64
  Native app goes to the background and starts it again when the app becomes
65
65
  active. The stop closes the socket with code 1000, so the Relay records a
66
66
  client close. The Relay replays retained messages when the app becomes active.
@@ -69,7 +69,7 @@ a hidden desktop tab keeps its socket open by itself.
69
69
 
70
70
  Set `keepOpenInBackground: true` to keep the socket open in the background,
71
71
  for example while an Android foreground service runs. Outside React, call
72
- `bindRelayLifecycle(signal, AppState)` from
72
+ `bindSignalProtocolRelayLifecycle(signal, AppState)` from
73
73
  `@open-e2ee/signal-protocol-sdk/client`.
74
74
 
75
75
  Do not call these hooks outside React components or custom hooks. Event callbacks from
@@ -171,7 +171,7 @@ import { expoStore } from '@open-e2ee/signal-protocol-sdk/local/store/expo';
171
171
 
172
172
  const client = await createSignalProtocolClient({
173
173
  identity: { userId },
174
- adapters: { storage: await expoStore(), relay },
174
+ adapters: { storage: await expoStore(), signalProtocolRelay },
175
175
  });
176
176
  ```
177
177
 
@@ -21,7 +21,7 @@ The store gets random bytes from the global `crypto.getRandomValues`. Install
21
21
  it at app startup before the first SDK call. Without a global source, the SDK
22
22
  throws `SecureRandomUnavailableError`. The store needs no `crypto.subtle`
23
23
  polyfill. AES-256-GCM uses Web Crypto when `crypto.subtle` exists and the
24
- bundled Noble implementation otherwise. The [README](../../../README.md#use-your-apps-storage-and-relay)
24
+ bundled Noble implementation otherwise. The [README](../../../README.md#use-your-apps-storage-and-message-delivery)
25
25
  lists the supported React Native versions.
26
26
 
27
27
  The store also needs a `SignalProtocolLocalSecretVault` backed by the platform
@@ -47,7 +47,7 @@ const storage = await keyValueStore({ storage: keyValueStorage, vault });
47
47
 
48
48
  const client = await createSignalProtocolClient({
49
49
  identity: { userId },
50
- adapters: { storage, relay },
50
+ adapters: { storage, signalProtocolRelay },
51
51
  });
52
52
  ```
53
53