@open-e2ee/signal-protocol-sdk 14.1.0 → 14.3.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 (401) hide show
  1. package/ADAPTERS.md +5 -5
  2. package/CHANGELOG.md +505 -0
  3. package/README.md +24 -19
  4. package/SECURITY.md +2 -2
  5. package/TROUBLESHOOTING.md +1 -1
  6. package/client/README.md +30 -18
  7. package/device/README.md +6 -5
  8. package/dist/client/client.d.ts +49 -38
  9. package/dist/client/client.d.ts.map +1 -1
  10. package/dist/client/client.js +231 -155
  11. package/dist/client/client.js.map +1 -1
  12. package/dist/client/compose.d.ts +4 -2
  13. package/dist/client/compose.d.ts.map +1 -1
  14. package/dist/client/compose.js +6 -1
  15. package/dist/client/compose.js.map +1 -1
  16. package/dist/client/config.d.ts +15 -6
  17. package/dist/client/config.d.ts.map +1 -1
  18. package/dist/client/config.js.map +1 -1
  19. package/dist/client/content-adapter.d.ts +9 -0
  20. package/dist/client/content-adapter.d.ts.map +1 -1
  21. package/dist/client/content-adapter.js +6 -0
  22. package/dist/client/content-adapter.js.map +1 -1
  23. package/dist/client/delivery-status.d.ts +2 -2
  24. package/dist/client/delivery-status.d.ts.map +1 -1
  25. package/dist/client/delivery-status.js +10 -4
  26. package/dist/client/delivery-status.js.map +1 -1
  27. package/dist/client/device-set-reconciliation.d.ts +23 -15
  28. package/dist/client/device-set-reconciliation.d.ts.map +1 -1
  29. package/dist/client/device-set-reconciliation.js +16 -13
  30. package/dist/client/device-set-reconciliation.js.map +1 -1
  31. package/dist/client/event-hooks.d.ts +15 -5
  32. package/dist/client/event-hooks.d.ts.map +1 -1
  33. package/dist/client/event-hooks.js +39 -4
  34. package/dist/client/event-hooks.js.map +1 -1
  35. package/dist/client/group-device-set.d.ts +1 -1
  36. package/dist/client/group-device-set.d.ts.map +1 -1
  37. package/dist/client/group-key-sync.js +1 -1
  38. package/dist/client/group-key-sync.js.map +1 -1
  39. package/dist/client/group-outbox.d.ts +7 -7
  40. package/dist/client/group-outbox.d.ts.map +1 -1
  41. package/dist/client/group-outbox.js +24 -24
  42. package/dist/client/group-outbox.js.map +1 -1
  43. package/dist/client/group-sealed-sender.d.ts +1 -1
  44. package/dist/client/group-sealed-sender.d.ts.map +1 -1
  45. package/dist/client/group-sender-key-operations.js +1 -1
  46. package/dist/client/group-sender-key-operations.js.map +1 -1
  47. package/dist/client/headless.d.ts +6 -6
  48. package/dist/client/headless.d.ts.map +1 -1
  49. package/dist/client/headless.js +7 -7
  50. package/dist/client/headless.js.map +1 -1
  51. package/dist/client/hosted-anonymous-delivery.d.ts +6 -6
  52. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -1
  53. package/dist/client/hosted-anonymous-delivery.js +17 -17
  54. package/dist/client/hosted-anonymous-delivery.js.map +1 -1
  55. package/dist/client/hosted-assertion-id.d.ts +1 -1
  56. package/dist/client/hosted-assertion-id.d.ts.map +1 -1
  57. package/dist/client/hosted-assertion-id.js +1 -1
  58. package/dist/client/hosted-assertion-id.js.map +1 -1
  59. package/dist/client/hosted-connection.d.ts +5 -5
  60. package/dist/client/hosted-connection.d.ts.map +1 -1
  61. package/dist/client/hosted-connection.js +32 -32
  62. package/dist/client/hosted-connection.js.map +1 -1
  63. package/dist/client/hosted-device-link-transport.d.ts +2 -2
  64. package/dist/client/hosted-device-link-transport.d.ts.map +1 -1
  65. package/dist/client/hosted-device-link-transport.js +1 -1
  66. package/dist/client/hosted-device-link-transport.js.map +1 -1
  67. package/dist/client/hosted-device-link.d.ts +5 -1
  68. package/dist/client/hosted-device-link.d.ts.map +1 -1
  69. package/dist/client/hosted-device-link.js +7 -4
  70. package/dist/client/hosted-device-link.js.map +1 -1
  71. package/dist/client/hosted-device-standing.d.ts +13 -5
  72. package/dist/client/hosted-device-standing.d.ts.map +1 -1
  73. package/dist/client/hosted-device-standing.js +11 -6
  74. package/dist/client/hosted-device-standing.js.map +1 -1
  75. package/dist/client/hosted-group-authority.d.ts +2 -2
  76. package/dist/client/hosted-group-authority.d.ts.map +1 -1
  77. package/dist/client/hosted-group-authority.js +8 -8
  78. package/dist/client/hosted-group-authority.js.map +1 -1
  79. package/dist/client/hosted-groups.d.ts +4 -4
  80. package/dist/client/hosted-groups.d.ts.map +1 -1
  81. package/dist/client/hosted-groups.js +8 -8
  82. package/dist/client/hosted-groups.js.map +1 -1
  83. package/dist/client/hosted-http-error.d.ts +7 -3
  84. package/dist/client/hosted-http-error.d.ts.map +1 -1
  85. package/dist/client/hosted-http-error.js +6 -3
  86. package/dist/client/hosted-http-error.js.map +1 -1
  87. package/dist/client/hosted-mailbox-subscription.d.ts +10 -10
  88. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -1
  89. package/dist/client/hosted-mailbox-subscription.js +17 -17
  90. package/dist/client/hosted-mailbox-subscription.js.map +1 -1
  91. package/dist/client/hosted-prekey-publication.d.ts +9 -9
  92. package/dist/client/hosted-prekey-publication.d.ts.map +1 -1
  93. package/dist/client/hosted-prekey-publication.js.map +1 -1
  94. package/dist/client/hosted-presence-frames.d.ts +62 -38
  95. package/dist/client/hosted-presence-frames.d.ts.map +1 -1
  96. package/dist/client/hosted-presence-frames.js +4 -2
  97. package/dist/client/hosted-presence-frames.js.map +1 -1
  98. package/dist/client/hosted-presence.d.ts +22 -14
  99. package/dist/client/hosted-presence.d.ts.map +1 -1
  100. package/dist/client/hosted-presence.js +26 -17
  101. package/dist/client/hosted-presence.js.map +1 -1
  102. package/dist/client/hosted-profile-keys.d.ts +3 -1
  103. package/dist/client/hosted-profile-keys.d.ts.map +1 -1
  104. package/dist/client/hosted-profile-keys.js +19 -15
  105. package/dist/client/hosted-profile-keys.js.map +1 -1
  106. package/dist/client/hosted-push.d.ts +38 -16
  107. package/dist/client/hosted-push.d.ts.map +1 -1
  108. package/dist/client/hosted-push.js +11 -5
  109. package/dist/client/hosted-push.js.map +1 -1
  110. package/dist/client/hosted-resume-error.d.ts +21 -9
  111. package/dist/client/hosted-resume-error.d.ts.map +1 -1
  112. package/dist/client/hosted-resume-error.js +4 -1
  113. package/dist/client/hosted-resume-error.js.map +1 -1
  114. package/dist/client/hosted-resume.d.ts +3 -3
  115. package/dist/client/hosted-resume.d.ts.map +1 -1
  116. package/dist/client/hosted-resume.js +12 -12
  117. package/dist/client/hosted-resume.js.map +1 -1
  118. package/dist/client/hosted-sandbox-identity.d.ts +32 -18
  119. package/dist/client/hosted-sandbox-identity.d.ts.map +1 -1
  120. package/dist/client/hosted-sandbox-identity.js +46 -27
  121. package/dist/client/hosted-sandbox-identity.js.map +1 -1
  122. package/dist/client/hosted-store-records.d.ts +46 -0
  123. package/dist/client/hosted-store-records.d.ts.map +1 -0
  124. package/dist/client/hosted-store-records.js +32 -0
  125. package/dist/client/hosted-store-records.js.map +1 -0
  126. package/dist/client/hosted-transport.d.ts +41 -33
  127. package/dist/client/hosted-transport.d.ts.map +1 -1
  128. package/dist/client/hosted-transport.js +146 -101
  129. package/dist/client/hosted-transport.js.map +1 -1
  130. package/dist/client/hosted-trust.d.ts +1 -1
  131. package/dist/client/hosted-trust.d.ts.map +1 -1
  132. package/dist/client/hosted-trust.js +1 -1
  133. package/dist/client/hosted-trust.js.map +1 -1
  134. package/dist/client/hosted.d.ts +138 -72
  135. package/dist/client/hosted.d.ts.map +1 -1
  136. package/dist/client/hosted.js +102 -60
  137. package/dist/client/hosted.js.map +1 -1
  138. package/dist/client/index.d.ts +4 -4
  139. package/dist/client/index.d.ts.map +1 -1
  140. package/dist/client/index.js +4 -4
  141. package/dist/client/index.js.map +1 -1
  142. package/dist/client/key-rotation-core.d.ts +4 -4
  143. package/dist/client/key-rotation-core.d.ts.map +1 -1
  144. package/dist/client/key-rotation-core.js +8 -8
  145. package/dist/client/key-rotation-core.js.map +1 -1
  146. package/dist/client/key-rotation.js +2 -2
  147. package/dist/client/key-rotation.js.map +1 -1
  148. package/dist/client/messages.d.ts +3 -3
  149. package/dist/client/messages.d.ts.map +1 -1
  150. package/dist/client/messages.js +18 -18
  151. package/dist/client/messages.js.map +1 -1
  152. package/dist/client/one-time-prekey-refill.d.ts +1 -1
  153. package/dist/client/one-time-prekey-refill.d.ts.map +1 -1
  154. package/dist/client/prekeys.js +17 -17
  155. package/dist/client/prekeys.js.map +1 -1
  156. package/dist/client/receive-queue.d.ts +4 -4
  157. package/dist/client/receive-queue.d.ts.map +1 -1
  158. package/dist/client/receive-queue.js +29 -29
  159. package/dist/client/receive-queue.js.map +1 -1
  160. package/dist/client/receive-work-seed.d.ts +6 -2
  161. package/dist/client/receive-work-seed.d.ts.map +1 -1
  162. package/dist/client/receive-work-seed.js.map +1 -1
  163. package/dist/client/recovery-driver.js +7 -7
  164. package/dist/client/recovery-driver.js.map +1 -1
  165. package/dist/client/retry-request-envelope.d.ts +3 -3
  166. package/dist/client/retry-request-envelope.d.ts.map +1 -1
  167. package/dist/client/retry-request-envelope.js +10 -10
  168. package/dist/client/retry-request-envelope.js.map +1 -1
  169. package/dist/client/retry-request-lifecycle.d.ts +1 -1
  170. package/dist/client/retry-request-lifecycle.d.ts.map +1 -1
  171. package/dist/client/retry-request-lifecycle.js +8 -8
  172. package/dist/client/retry-request-lifecycle.js.map +1 -1
  173. package/dist/client/retry-terminal-recovery.js +2 -2
  174. package/dist/client/retry-terminal-recovery.js.map +1 -1
  175. package/dist/client/retry.js +13 -13
  176. package/dist/client/retry.js.map +1 -1
  177. package/dist/client/sealed-sender.d.ts +13 -4
  178. package/dist/client/sealed-sender.d.ts.map +1 -1
  179. package/dist/client/sealed-sender.js +27 -15
  180. package/dist/client/sealed-sender.js.map +1 -1
  181. package/dist/client/send-deadline.d.ts +6 -6
  182. package/dist/client/send-deadline.d.ts.map +1 -1
  183. package/dist/client/send-deadline.js +37 -23
  184. package/dist/client/send-deadline.js.map +1 -1
  185. package/dist/client/send-intent-driver.js +9 -9
  186. package/dist/client/send-intent-driver.js.map +1 -1
  187. package/dist/client/sessions.js +11 -11
  188. package/dist/client/sessions.js.map +1 -1
  189. package/dist/client/{relay-acceptance.d.ts → signal-relay-acceptance.d.ts} +9 -9
  190. package/dist/client/signal-relay-acceptance.d.ts.map +1 -0
  191. package/dist/client/{relay-acceptance.js → signal-relay-acceptance.js} +7 -7
  192. package/dist/client/signal-relay-acceptance.js.map +1 -0
  193. package/dist/client/{relay-device-refusal.d.ts → signal-relay-device-refusal.d.ts} +7 -7
  194. package/dist/client/signal-relay-device-refusal.d.ts.map +1 -0
  195. package/dist/client/{relay-device-refusal.js → signal-relay-device-refusal.js} +9 -9
  196. package/dist/client/signal-relay-device-refusal.js.map +1 -0
  197. package/dist/client/{relay-lifecycle.d.ts → signal-relay-lifecycle.d.ts} +18 -9
  198. package/dist/client/signal-relay-lifecycle.d.ts.map +1 -0
  199. package/dist/client/{relay-lifecycle.js → signal-relay-lifecycle.js} +16 -7
  200. package/dist/client/signal-relay-lifecycle.js.map +1 -0
  201. package/dist/client/{relay-period-close.d.ts → signal-relay-period-close.d.ts} +1 -1
  202. package/dist/client/signal-relay-period-close.d.ts.map +1 -0
  203. package/dist/client/{relay-period-close.js → signal-relay-period-close.js} +1 -1
  204. package/dist/client/signal-relay-period-close.js.map +1 -0
  205. package/dist/client/{relay-protocol.d.ts → signal-relay-protocol.d.ts} +12 -8
  206. package/dist/client/signal-relay-protocol.d.ts.map +1 -0
  207. package/dist/client/{relay-protocol.js → signal-relay-protocol.js} +13 -10
  208. package/dist/client/signal-relay-protocol.js.map +1 -0
  209. package/dist/client/{relay-receipt-intake.d.ts → signal-relay-receipt-intake.d.ts} +12 -12
  210. package/dist/client/signal-relay-receipt-intake.d.ts.map +1 -0
  211. package/dist/client/{relay-receipt-intake.js → signal-relay-receipt-intake.js} +9 -9
  212. package/dist/client/signal-relay-receipt-intake.js.map +1 -0
  213. package/dist/client/{relay-receipt-join.d.ts → signal-relay-receipt-join.d.ts} +8 -8
  214. package/dist/client/signal-relay-receipt-join.d.ts.map +1 -0
  215. package/dist/client/{relay-receipt-join.js → signal-relay-receipt-join.js} +11 -11
  216. package/dist/client/signal-relay-receipt-join.js.map +1 -0
  217. package/dist/client/{relay-request-deadline.d.ts → signal-relay-request-deadline.d.ts} +3 -3
  218. package/dist/client/signal-relay-request-deadline.d.ts.map +1 -0
  219. package/dist/client/{relay-request-deadline.js → signal-relay-request-deadline.js} +4 -4
  220. package/dist/client/signal-relay-request-deadline.js.map +1 -0
  221. package/dist/client/{relay-sealed-route.d.ts → signal-relay-sealed-route.d.ts} +1 -1
  222. package/dist/client/signal-relay-sealed-route.d.ts.map +1 -0
  223. package/dist/client/{relay-sealed-route.js → signal-relay-sealed-route.js} +1 -1
  224. package/dist/client/signal-relay-sealed-route.js.map +1 -0
  225. package/dist/client/{relay-subscription.d.ts → signal-relay-subscription.d.ts} +12 -12
  226. package/dist/client/signal-relay-subscription.d.ts.map +1 -0
  227. package/dist/client/{relay-subscription.js → signal-relay-subscription.js} +23 -23
  228. package/dist/client/signal-relay-subscription.js.map +1 -0
  229. package/dist/client/{relay-work.d.ts → signal-relay-work.d.ts} +7 -7
  230. package/dist/client/signal-relay-work.d.ts.map +1 -0
  231. package/dist/client/{relay-work.js → signal-relay-work.js} +13 -13
  232. package/dist/client/signal-relay-work.js.map +1 -0
  233. package/dist/client/signal-service-cipher.d.ts +10 -8
  234. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  235. package/dist/client/signal-service-cipher.js +102 -97
  236. package/dist/client/signal-service-cipher.js.map +1 -1
  237. package/dist/client/state.d.ts +4 -4
  238. package/dist/client/state.d.ts.map +1 -1
  239. package/dist/client/state.js +3 -3
  240. package/dist/client/state.js.map +1 -1
  241. package/dist/client/types.d.ts +13 -4
  242. package/dist/client/types.d.ts.map +1 -1
  243. package/dist/client/types.js.map +1 -1
  244. package/dist/device/connection.d.ts +10 -4
  245. package/dist/device/connection.d.ts.map +1 -1
  246. package/dist/device/connection.js +8 -3
  247. package/dist/device/connection.js.map +1 -1
  248. package/dist/device/index.d.ts +2 -2
  249. package/dist/device/index.d.ts.map +1 -1
  250. package/dist/device/index.js +1 -1
  251. package/dist/device/index.js.map +1 -1
  252. package/dist/device/types.d.ts +3 -1
  253. package/dist/device/types.d.ts.map +1 -1
  254. package/dist/hooks/index.d.ts +2 -2
  255. package/dist/hooks/index.d.ts.map +1 -1
  256. package/dist/hooks/index.js +2 -2
  257. package/dist/hooks/index.js.map +1 -1
  258. package/dist/hooks/use-signal-relay-connection-state.d.ts +39 -0
  259. package/dist/hooks/use-signal-relay-connection-state.d.ts.map +1 -0
  260. package/dist/hooks/use-signal-relay-connection-state.js +45 -0
  261. package/dist/hooks/use-signal-relay-connection-state.js.map +1 -0
  262. package/dist/hooks/use-signal-relay-lifecycle.d.ts +43 -0
  263. package/dist/hooks/use-signal-relay-lifecycle.d.ts.map +1 -0
  264. package/dist/hooks/use-signal-relay-lifecycle.js +38 -0
  265. package/dist/hooks/use-signal-relay-lifecycle.js.map +1 -0
  266. package/dist/index.d.ts +16 -9
  267. package/dist/index.d.ts.map +1 -1
  268. package/dist/index.js +6 -5
  269. package/dist/index.js.map +1 -1
  270. package/dist/internal/groups/authority-certificate.d.ts +8 -1
  271. package/dist/internal/groups/authority-certificate.d.ts.map +1 -1
  272. package/dist/internal/groups/authority-certificate.js +29 -6
  273. package/dist/internal/groups/authority-certificate.js.map +1 -1
  274. package/dist/internal/protocol/sealed-sender/certificate.js +2 -2
  275. package/dist/internal/protocol/sealed-sender/certificate.js.map +1 -1
  276. package/dist/internal/protocol/sealed-sender/proto/index.d.ts +1 -1
  277. package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
  278. package/dist/internal/protocol/sealed-sender/proto/index.js +5 -5
  279. package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
  280. package/dist/internal/sesame/device-registry.d.ts +13 -13
  281. package/dist/internal/sesame/device-registry.d.ts.map +1 -1
  282. package/dist/internal/sesame/device-registry.js +20 -20
  283. package/dist/internal/sesame/device-registry.js.map +1 -1
  284. package/dist/local/store/receive-work.d.ts +29 -0
  285. package/dist/local/store/receive-work.d.ts.map +1 -1
  286. package/dist/local/store/receive-work.js +58 -1
  287. package/dist/local/store/receive-work.js.map +1 -1
  288. package/dist/local/store/received-content.d.ts +1 -1
  289. package/dist/local/store/received-content.d.ts.map +1 -1
  290. package/dist/local/store/reliability.d.ts +11 -3
  291. package/dist/local/store/reliability.d.ts.map +1 -1
  292. package/dist/local/store/reliability.js +4 -0
  293. package/dist/local/store/reliability.js.map +1 -1
  294. package/dist/local/store/sqlite/key-storage/index.d.ts +3 -9
  295. package/dist/local/store/sqlite/key-storage/index.d.ts.map +1 -1
  296. package/dist/local/store/sqlite/key-storage/index.js.map +1 -1
  297. package/dist/local/store/sqlite/key-storage/signed-prekeys.d.ts +1 -7
  298. package/dist/local/store/sqlite/key-storage/signed-prekeys.d.ts.map +1 -1
  299. package/dist/local/store/sqlite/key-storage/signed-prekeys.js.map +1 -1
  300. package/dist/local/store/sqlite/models/kyber-prekey.d.ts +4 -9
  301. package/dist/local/store/sqlite/models/kyber-prekey.d.ts.map +1 -1
  302. package/dist/local/store/sqlite/models/kyber-prekey.js +4 -1
  303. package/dist/local/store/sqlite/models/kyber-prekey.js.map +1 -1
  304. package/dist/local/store/sqlite/store.d.ts.map +1 -1
  305. package/dist/local/store/sqlite/store.js +1 -2
  306. package/dist/local/store/sqlite/store.js.map +1 -1
  307. package/dist/remote/signal-relay/connection-state.d.ts +16 -0
  308. package/dist/remote/signal-relay/connection-state.d.ts.map +1 -0
  309. package/dist/remote/{relay → signal-relay}/connection-state.js +1 -1
  310. package/dist/remote/signal-relay/connection-state.js.map +1 -0
  311. package/dist/remote/{relay → signal-relay}/device-set.d.ts +3 -3
  312. package/dist/remote/signal-relay/device-set.d.ts.map +1 -0
  313. package/dist/remote/{relay → signal-relay}/device-set.js +7 -7
  314. package/dist/remote/signal-relay/device-set.js.map +1 -0
  315. package/dist/remote/{relay → signal-relay}/index.d.ts +3 -3
  316. package/dist/remote/signal-relay/index.d.ts.map +1 -0
  317. package/dist/remote/{relay → signal-relay}/index.js +2 -2
  318. package/dist/remote/signal-relay/index.js.map +1 -0
  319. package/dist/remote/{relay → signal-relay}/request-admission.d.ts +2 -2
  320. package/dist/remote/signal-relay/request-admission.d.ts.map +1 -0
  321. package/dist/remote/{relay → signal-relay}/request-admission.js +5 -5
  322. package/dist/remote/signal-relay/request-admission.js.map +1 -0
  323. package/dist/remote/{relay → signal-relay}/types.d.ts +29 -10
  324. package/dist/remote/signal-relay/types.d.ts.map +1 -0
  325. package/dist/remote/{relay → signal-relay}/types.js +1 -1
  326. package/dist/remote/signal-relay/types.js.map +1 -0
  327. package/dist/safety/core.d.ts +1 -1
  328. package/dist/safety/core.js +1 -1
  329. package/dist/types/api.d.ts +38 -15
  330. package/dist/types/api.d.ts.map +1 -1
  331. package/dist/types/errors.d.ts +62 -7
  332. package/dist/types/errors.d.ts.map +1 -1
  333. package/dist/types/errors.js +68 -8
  334. package/dist/types/errors.js.map +1 -1
  335. package/dist/types/renamed-member.d.ts +48 -0
  336. package/dist/types/renamed-member.d.ts.map +1 -0
  337. package/dist/types/renamed-member.js +78 -0
  338. package/dist/types/renamed-member.js.map +1 -0
  339. package/dist/utils/bounded-fan-out.d.ts +2 -2
  340. package/dist/utils/bounded-fan-out.d.ts.map +1 -1
  341. package/dist/utils/bounded-fan-out.js +2 -2
  342. package/dist/utils/bounded-fan-out.js.map +1 -1
  343. package/dist/utils/retry.d.ts +3 -3
  344. package/dist/utils/retry.d.ts.map +1 -1
  345. package/dist/utils/retry.js +4 -3
  346. package/dist/utils/retry.js.map +1 -1
  347. package/docs/ASSURANCE.md +9 -9
  348. package/docs/CLIENT_COMPOSITION.md +7 -5
  349. package/docs/DEVIATIONS.md +8 -5
  350. package/docs/ERROR_HANDLING.md +21 -21
  351. package/docs/GETTING_STARTED.md +22 -15
  352. package/docs/INTERFACES.md +3 -3
  353. package/docs/PACKAGE_SURFACE.md +14 -4
  354. package/docs/RECIPES.md +271 -11
  355. package/hooks/README.md +11 -11
  356. package/local/store/key-value/README.md +1 -1
  357. package/local/store/web-sqlite/README.md +1 -1
  358. package/package.json +16 -6
  359. package/remote/README.md +3 -3
  360. package/remote/{relay → signal-relay}/README.md +15 -6
  361. package/dist/client/relay-acceptance.d.ts.map +0 -1
  362. package/dist/client/relay-acceptance.js.map +0 -1
  363. package/dist/client/relay-device-refusal.d.ts.map +0 -1
  364. package/dist/client/relay-device-refusal.js.map +0 -1
  365. package/dist/client/relay-lifecycle.d.ts.map +0 -1
  366. package/dist/client/relay-lifecycle.js.map +0 -1
  367. package/dist/client/relay-period-close.d.ts.map +0 -1
  368. package/dist/client/relay-period-close.js.map +0 -1
  369. package/dist/client/relay-protocol.d.ts.map +0 -1
  370. package/dist/client/relay-protocol.js.map +0 -1
  371. package/dist/client/relay-receipt-intake.d.ts.map +0 -1
  372. package/dist/client/relay-receipt-intake.js.map +0 -1
  373. package/dist/client/relay-receipt-join.d.ts.map +0 -1
  374. package/dist/client/relay-receipt-join.js.map +0 -1
  375. package/dist/client/relay-request-deadline.d.ts.map +0 -1
  376. package/dist/client/relay-request-deadline.js.map +0 -1
  377. package/dist/client/relay-sealed-route.d.ts.map +0 -1
  378. package/dist/client/relay-sealed-route.js.map +0 -1
  379. package/dist/client/relay-subscription.d.ts.map +0 -1
  380. package/dist/client/relay-subscription.js.map +0 -1
  381. package/dist/client/relay-work.d.ts.map +0 -1
  382. package/dist/client/relay-work.js.map +0 -1
  383. package/dist/hooks/use-relay-connection-state.d.ts +0 -32
  384. package/dist/hooks/use-relay-connection-state.d.ts.map +0 -1
  385. package/dist/hooks/use-relay-connection-state.js +0 -31
  386. package/dist/hooks/use-relay-connection-state.js.map +0 -1
  387. package/dist/hooks/use-relay-lifecycle.d.ts +0 -36
  388. package/dist/hooks/use-relay-lifecycle.d.ts.map +0 -1
  389. package/dist/hooks/use-relay-lifecycle.js +0 -35
  390. package/dist/hooks/use-relay-lifecycle.js.map +0 -1
  391. package/dist/remote/relay/connection-state.d.ts +0 -16
  392. package/dist/remote/relay/connection-state.d.ts.map +0 -1
  393. package/dist/remote/relay/connection-state.js.map +0 -1
  394. package/dist/remote/relay/device-set.d.ts.map +0 -1
  395. package/dist/remote/relay/device-set.js.map +0 -1
  396. package/dist/remote/relay/index.d.ts.map +0 -1
  397. package/dist/remote/relay/index.js.map +0 -1
  398. package/dist/remote/relay/request-admission.d.ts.map +0 -1
  399. package/dist/remote/relay/request-admission.js.map +0 -1
  400. package/dist/remote/relay/types.d.ts.map +0 -1
  401. 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
+ relayUrl: 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
  ```
@@ -201,8 +207,9 @@ save attachment references and downloaded bytes.
201
207
  ```ts
202
208
  import { createHostedSignalProtocolClient, media } from "@open-e2ee/signal-protocol-sdk";
203
209
 
210
+ const signalRelayUrl = process.env.OPEN_E2EE_SIGNAL_RELAY_URL!;
204
211
  const signal = await createHostedSignalProtocolClient({
205
- hosted: { relayUrl, getIdentityAssertion },
212
+ hosted: { relayUrl: signalRelayUrl, getIdentityAssertion },
206
213
  adapters: {
207
214
  storage,
208
215
  },
@@ -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 relay: 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
 
@@ -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: { relayUrl: signalRelayUrl } })`
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.
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,276 @@ 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 signalRelayUrl = process.env.OPEN_E2EE_SIGNAL_RELAY_URL!;
273
+ const signal = await createHostedSignalProtocolClient({
274
+ adapters: { storage },
275
+ hosted: {
276
+ relayUrl: signalRelayUrl,
277
+ getIdentityAssertion: firebaseIdentityAssertion(auth, uid),
278
+ },
279
+ });
280
+
281
+ // At provider sign-out, stop the client before another user signs in.
282
+ await signal.stop();
283
+ ```
284
+
285
+ These rules apply to Clerk and Firebase profiles:
286
+
287
+ - **Token refresh.** A registered device resumes its session with its device
288
+ key. The SDK does not call the callback for a resume. A provider token
289
+ refresh or expiry does not change a registered device.
290
+ - **Sign-out.** Provider sign-out does not revoke the device. The store
291
+ resumes its account without the callback. A shared store would give the
292
+ next user the account of the previous user. To stop access on existing
293
+ devices, follow the
294
+ [suspension procedure](https://docs.open-e2ee.dev/signal-relay/backend-identity#suspend-an-identified-account).
295
+ - **Reinstall or lost store.** A new store registers a new device of the same
296
+ account. It has a new Signal identity key, no earlier sessions, and no
297
+ message history. Peers must verify and accept the new key. The earlier
298
+ devices stay active with the old key. Until the earlier devices are removed,
299
+ or until recovery, peers cannot send to all devices of the account. A peer
300
+ that accepted the new key gets `UNTRUSTED_IDENTITY` when it sends to an
301
+ earlier device. A peer that has not accepted it cannot decrypt messages from
302
+ the new device. To keep the account identity, use device linking. Each
303
+ registration reserves one of the five device IDs of the account for good.
304
+ See [Signal Protocol Relay device errors](./ERROR_HANDLING.md#signal-protocol-relay-device-errors).
305
+ - **Device linking.** To keep the account identity on a new device, move the
306
+ identity from an existing device and call `linkHostedSignalProtocolRelayDevice`. Your
307
+ application owns that transfer.
308
+ - **Recovery.** Create the client with `assertionPurpose: "recover"` when no
309
+ device of the account remains. Recovery revokes all earlier devices of the
310
+ account and returns device ID 1. The device ID reservation applies to
311
+ registrations, so recovery starts again at device 1. Recovery does not
312
+ restore message plaintext or sessions. Your application decides when to
313
+ start it. Recovery needs a recent provider sign-in. Sign the user in again
314
+ before you start recovery. Relay refuses a sign-in older than the recovery
315
+ window with HTTP 401 `AUTHORITY_DENIED`. See
316
+ [device lifecycle and recovery](https://docs.open-e2ee.dev/signal-relay/device-lifecycle-and-recovery).
317
+ - **Provider change.** A different provider, Clerk instance, or Firebase
318
+ project gives a different issuer or subject. Relay treats it as a different
319
+ account. An environment keeps its identity profile after its first
320
+ registration. To use another provider, start a new project. See
321
+ [in-use environments](https://docs.open-e2ee.dev/signal-relay/identity#in-use-environments).
322
+
63
323
  ## Production composition with Expo on the Signal Protocol Relay
64
324
 
65
325
  <!-- doc-snippet:skip requires-external-context -->
@@ -74,8 +334,8 @@ const signal = await createHostedSignalProtocolClient({
74
334
  },
75
335
  hosted: {
76
336
  // 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.
337
+ relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_SIGNAL_RELAY_URL ?? process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
338
+ // The native app callback: https://docs.open-e2ee.dev/signal-relay/custom-token#native-apps-react-native-and-expo
79
339
  getIdentityAssertion,
80
340
  },
81
341
  });
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
@@ -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
@@ -107,7 +107,7 @@ To recover, delete the file and link the device again:
107
107
  file, creates a new key, and returns the open, empty store. The identity
108
108
  and the sessions of the device go with the file.
109
109
  3. Put the account identity into the new store, then call
110
- `linkHostedRelayDevice()` with it. This needs another device that holds the
110
+ `linkHostedSignalProtocolRelayDevice()` with it. This needs another device that holds the
111
111
  account identity. See
112
112
  [Link a device](../../../device/README.md#link-a-device).
113
113
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "14.1.0",
3
+ "version": "14.3.0",
4
4
  "description": "Pure TypeScript Signal Protocol SDK for encrypted chat in Expo, React Native, browsers, and Node. Post-quantum by default.",
5
5
  "keywords": [
6
6
  "open-e2ee",
@@ -23,6 +23,8 @@
23
23
  "messaging",
24
24
  "sealed-sender",
25
25
  "sdk",
26
+ "clerk",
27
+ "firebase",
26
28
  "forward-secrecy"
27
29
  ],
28
30
  "license": "(MIT OR Apache-2.0)",
@@ -55,13 +57,21 @@
55
57
  "types": "./dist/index.d.ts",
56
58
  "default": "./dist/index.js"
57
59
  },
60
+ "./remote/signal-relay": {
61
+ "types": "./dist/remote/signal-relay/index.d.ts",
62
+ "default": "./dist/remote/signal-relay/index.js"
63
+ },
64
+ "./remote/signal-relay/types": {
65
+ "types": "./dist/remote/signal-relay/types.d.ts",
66
+ "default": "./dist/remote/signal-relay/types.js"
67
+ },
58
68
  "./remote/relay": {
59
- "types": "./dist/remote/relay/index.d.ts",
60
- "default": "./dist/remote/relay/index.js"
69
+ "types": "./dist/remote/signal-relay/index.d.ts",
70
+ "default": "./dist/remote/signal-relay/index.js"
61
71
  },
62
72
  "./remote/relay/types": {
63
- "types": "./dist/remote/relay/types.d.ts",
64
- "default": "./dist/remote/relay/types.js"
73
+ "types": "./dist/remote/signal-relay/types.d.ts",
74
+ "default": "./dist/remote/signal-relay/types.js"
65
75
  },
66
76
  "./client": {
67
77
  "types": "./dist/client/index.d.ts",
@@ -329,7 +339,7 @@
329
339
  "remote/object-store/README.md",
330
340
  "remote/object-store/convex-r2/README.md",
331
341
  "remote/object-store/s3/README.md",
332
- "remote/relay/README.md",
342
+ "remote/signal-relay/README.md",
333
343
  "safety/README.md",
334
344
  "sealed-sender/README.md",
335
345
  "types/README.md",
package/remote/README.md CHANGED
@@ -40,7 +40,7 @@ const signal = await createHostedSignalProtocolClient({
40
40
  },
41
41
  hosted: {
42
42
  // The environment-scoped connection URL from the OpenE2EE console.
43
- relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
43
+ relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_SIGNAL_RELAY_URL ?? process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
44
44
  // Returns a short-lived signed assertion for the signed-in user.
45
45
  getIdentityAssertion,
46
46
  },
@@ -149,7 +149,7 @@ needed to authorize and construct short-lived operations.
149
149
  `oe new` writes a Sandbox connection URL to `.env.local`. Pass it to
150
150
  `createHostedSignalProtocolClient()` with the device-local store that your
151
151
  application uses for production. A Sandbox environment uses device-owned
152
- identity, so pass `hostedRelaySandboxIdentity(storage)` as
152
+ identity, so pass `hostedSignalProtocolRelaySandboxIdentity(storage)` as
153
153
  `hosted.getIdentityAssertion`.
154
154
 
155
155
  ## Related Docs
@@ -157,5 +157,5 @@ identity, so pass `hostedRelaySandboxIdentity(storage)` as
157
157
  - [README](../README.md)
158
158
  - [ADAPTERS](../ADAPTERS.md)
159
159
  - [local/store/README.md](../local/store/README.md)
160
- - [Relay Guide](./relay/README.md)
160
+ - [Relay Guide](./signal-relay/README.md)
161
161
  - [Object Store Guide](./object-store/README.md)