@open-e2ee/signal-protocol-sdk 2.0.2 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (410) hide show
  1. package/ADAPTERS.md +10 -17
  2. package/ARCHITECTURE.md +1 -2
  3. package/CHANGELOG.md +74 -0
  4. package/LICENSE +11 -655
  5. package/LICENSE-APACHE +201 -0
  6. package/LICENSE-MIT +21 -0
  7. package/NOTICE +5 -7
  8. package/README.md +11 -11
  9. package/SECURITY.md +2 -2
  10. package/TROUBLESHOOTING.md +2 -6
  11. package/client/README.md +34 -16
  12. package/device/README.md +1 -1
  13. package/dist/client/client.d.ts +13 -2
  14. package/dist/client/client.d.ts.map +1 -1
  15. package/dist/client/client.js +136 -73
  16. package/dist/client/client.js.map +1 -1
  17. package/dist/client/config.d.ts +14 -18
  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 +2 -0
  21. package/dist/client/content-adapter.d.ts.map +1 -1
  22. package/dist/client/content-adapter.js +4 -0
  23. package/dist/client/content-adapter.js.map +1 -1
  24. package/dist/client/endorsement-manager.d.ts +4 -1
  25. package/dist/client/endorsement-manager.d.ts.map +1 -1
  26. package/dist/client/endorsement-manager.js +14 -6
  27. package/dist/client/endorsement-manager.js.map +1 -1
  28. package/dist/client/group-authority.d.ts +8 -0
  29. package/dist/client/group-authority.d.ts.map +1 -0
  30. package/dist/client/group-authority.js +2 -0
  31. package/dist/client/group-authority.js.map +1 -0
  32. package/dist/client/headless.d.ts +3 -8
  33. package/dist/client/headless.d.ts.map +1 -1
  34. package/dist/client/headless.js +3 -8
  35. package/dist/client/headless.js.map +1 -1
  36. package/dist/client/hosted-anonymous-delivery.d.ts +32 -0
  37. package/dist/client/hosted-anonymous-delivery.d.ts.map +1 -0
  38. package/dist/client/hosted-anonymous-delivery.js +239 -0
  39. package/dist/client/hosted-anonymous-delivery.js.map +1 -0
  40. package/dist/client/hosted-connection.d.ts +1 -1
  41. package/dist/client/hosted-connection.d.ts.map +1 -1
  42. package/dist/client/hosted-connection.js +18 -51
  43. package/dist/client/hosted-connection.js.map +1 -1
  44. package/dist/client/hosted-group-authority.d.ts +11 -0
  45. package/dist/client/hosted-group-authority.d.ts.map +1 -0
  46. package/dist/client/hosted-group-authority.js +96 -0
  47. package/dist/client/hosted-group-authority.js.map +1 -0
  48. package/dist/client/hosted-groups.d.ts +31 -0
  49. package/dist/client/hosted-groups.d.ts.map +1 -0
  50. package/dist/client/hosted-groups.js +217 -0
  51. package/dist/client/hosted-groups.js.map +1 -0
  52. package/dist/client/hosted-mailbox-subscription.d.ts +34 -0
  53. package/dist/client/hosted-mailbox-subscription.d.ts.map +1 -0
  54. package/dist/client/hosted-mailbox-subscription.js +257 -0
  55. package/dist/client/hosted-mailbox-subscription.js.map +1 -0
  56. package/dist/client/hosted-prekey-publication.d.ts +51 -0
  57. package/dist/client/hosted-prekey-publication.d.ts.map +1 -0
  58. package/dist/client/hosted-prekey-publication.js +249 -0
  59. package/dist/client/hosted-prekey-publication.js.map +1 -0
  60. package/dist/client/hosted-push.d.ts +4 -5
  61. package/dist/client/hosted-push.d.ts.map +1 -1
  62. package/dist/client/hosted-push.js +22 -22
  63. package/dist/client/hosted-push.js.map +1 -1
  64. package/dist/client/hosted-transport.d.ts +57 -35
  65. package/dist/client/hosted-transport.d.ts.map +1 -1
  66. package/dist/client/hosted-transport.js +666 -341
  67. package/dist/client/hosted-transport.js.map +1 -1
  68. package/dist/client/hosted-trust.d.ts +29 -0
  69. package/dist/client/hosted-trust.d.ts.map +1 -0
  70. package/dist/client/hosted-trust.js +28 -0
  71. package/dist/client/hosted-trust.js.map +1 -0
  72. package/dist/client/hosted.d.ts +18 -13
  73. package/dist/client/hosted.d.ts.map +1 -1
  74. package/dist/client/hosted.js +78 -34
  75. package/dist/client/hosted.js.map +1 -1
  76. package/dist/client/index.d.ts +14 -14
  77. package/dist/client/index.d.ts.map +1 -1
  78. package/dist/client/index.js +7 -7
  79. package/dist/client/index.js.map +1 -1
  80. package/dist/client/key-rotation-core.d.ts +8 -0
  81. package/dist/client/key-rotation-core.d.ts.map +1 -1
  82. package/dist/client/key-rotation-core.js +12 -1
  83. package/dist/client/key-rotation-core.js.map +1 -1
  84. package/dist/client/key-rotation.d.ts +2 -1
  85. package/dist/client/key-rotation.d.ts.map +1 -1
  86. package/dist/client/key-rotation.js +4 -4
  87. package/dist/client/key-rotation.js.map +1 -1
  88. package/dist/client/media-queue-persistence.d.ts +14 -0
  89. package/dist/client/media-queue-persistence.d.ts.map +1 -0
  90. package/dist/client/media-queue-persistence.js +123 -0
  91. package/dist/client/media-queue-persistence.js.map +1 -0
  92. package/dist/client/media-upload-budget.d.ts +3 -0
  93. package/dist/client/media-upload-budget.d.ts.map +1 -0
  94. package/dist/client/media-upload-budget.js +27 -0
  95. package/dist/client/media-upload-budget.js.map +1 -0
  96. package/dist/client/media.d.ts +51 -15
  97. package/dist/client/media.d.ts.map +1 -1
  98. package/dist/client/media.js +541 -73
  99. package/dist/client/media.js.map +1 -1
  100. package/dist/client/messages.d.ts.map +1 -1
  101. package/dist/client/messages.js +13 -14
  102. package/dist/client/messages.js.map +1 -1
  103. package/dist/client/prekeys.d.ts.map +1 -1
  104. package/dist/client/prekeys.js +131 -43
  105. package/dist/client/prekeys.js.map +1 -1
  106. package/dist/client/relay-subscription.d.ts +4 -0
  107. package/dist/client/relay-subscription.d.ts.map +1 -1
  108. package/dist/client/relay-subscription.js +58 -25
  109. package/dist/client/relay-subscription.js.map +1 -1
  110. package/dist/client/sender-key-distribution.d.ts +8 -0
  111. package/dist/client/sender-key-distribution.d.ts.map +1 -0
  112. package/dist/client/sender-key-distribution.js +59 -0
  113. package/dist/client/sender-key-distribution.js.map +1 -0
  114. package/dist/client/signal-service-cipher.d.ts +7 -3
  115. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  116. package/dist/client/signal-service-cipher.js +41 -16
  117. package/dist/client/signal-service-cipher.js.map +1 -1
  118. package/dist/device/{expo-metadata.d.ts → expo/index.d.ts} +3 -3
  119. package/dist/device/expo/index.d.ts.map +1 -0
  120. package/dist/device/{expo-metadata.js → expo/index.js} +2 -2
  121. package/dist/device/expo/index.js.map +1 -0
  122. package/dist/device/index.js +1 -1
  123. package/dist/device/index.js.map +1 -1
  124. package/dist/device/provisioning.d.ts +1 -1
  125. package/dist/device/provisioning.js +1 -1
  126. package/dist/device/types.d.ts +1 -1
  127. package/dist/groups/server.d.ts +10 -0
  128. package/dist/groups/server.d.ts.map +1 -0
  129. package/dist/groups/server.js +6 -0
  130. package/dist/groups/server.js.map +1 -0
  131. package/dist/hooks/use-connection-presence.d.ts +2 -4
  132. package/dist/hooks/use-connection-presence.d.ts.map +1 -1
  133. package/dist/hooks/use-connection-presence.js +2 -4
  134. package/dist/hooks/use-connection-presence.js.map +1 -1
  135. package/dist/index.d.ts +51 -49
  136. package/dist/index.d.ts.map +1 -1
  137. package/dist/index.js +25 -24
  138. package/dist/index.js.map +1 -1
  139. package/dist/internal/groups/authority-certificate.d.ts +22 -0
  140. package/dist/internal/groups/authority-certificate.d.ts.map +1 -0
  141. package/dist/internal/groups/authority-certificate.js +99 -0
  142. package/dist/internal/groups/authority-certificate.js.map +1 -0
  143. package/dist/internal/groups/error-details.d.ts +9 -0
  144. package/dist/internal/groups/error-details.d.ts.map +1 -0
  145. package/dist/internal/groups/error-details.js +30 -0
  146. package/dist/internal/groups/error-details.js.map +1 -0
  147. package/dist/internal/groups/manager.d.ts +5 -0
  148. package/dist/internal/groups/manager.d.ts.map +1 -1
  149. package/dist/internal/groups/manager.js +3 -0
  150. package/dist/internal/groups/manager.js.map +1 -1
  151. package/dist/internal/groups/server-engine.d.ts +7 -0
  152. package/dist/internal/groups/server-engine.d.ts.map +1 -1
  153. package/dist/internal/groups/server-engine.js +51 -19
  154. package/dist/internal/groups/server-engine.js.map +1 -1
  155. package/dist/internal/groups/wire.d.ts.map +1 -1
  156. package/dist/internal/groups/wire.js +10 -9
  157. package/dist/internal/groups/wire.js.map +1 -1
  158. package/dist/internal/manager/manager.d.ts +1 -1
  159. package/dist/internal/manager/manager.d.ts.map +1 -1
  160. package/dist/internal/manager/manager.js +22 -25
  161. package/dist/internal/manager/manager.js.map +1 -1
  162. package/dist/internal/protocol/sender-keys/manager.d.ts +1 -1
  163. package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
  164. package/dist/internal/protocol/sender-keys/manager.js +27 -14
  165. package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
  166. package/dist/internal/sesame/manager.d.ts +2 -2
  167. package/dist/internal/sesame/manager.d.ts.map +1 -1
  168. package/dist/internal/sesame/manager.js +6 -6
  169. package/dist/internal/sesame/manager.js.map +1 -1
  170. package/dist/internal/sesame/types.d.ts +1 -1
  171. package/dist/internal/sesame/types.d.ts.map +1 -1
  172. package/dist/internal/session/cipher.d.ts +1 -1
  173. package/dist/internal/session/cipher.d.ts.map +1 -1
  174. package/dist/internal/session/cipher.js +31 -28
  175. package/dist/internal/session/cipher.js.map +1 -1
  176. package/dist/layers.d.ts +1 -1
  177. package/dist/layers.d.ts.map +1 -1
  178. package/dist/layers.js +1 -1
  179. package/dist/layers.js.map +1 -1
  180. package/dist/local/store/expo/adapter.d.ts +8 -2
  181. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  182. package/dist/local/store/expo/adapter.js +28 -9
  183. package/dist/local/store/expo/adapter.js.map +1 -1
  184. package/dist/local/store/expo/key-storage.d.ts +7 -1
  185. package/dist/local/store/expo/key-storage.d.ts.map +1 -1
  186. package/dist/local/store/expo/key-storage.js +82 -17
  187. package/dist/local/store/expo/key-storage.js.map +1 -1
  188. package/dist/local/store/expo/models/kyber-prekey-used.d.ts +1 -4
  189. package/dist/local/store/expo/models/kyber-prekey-used.d.ts.map +1 -1
  190. package/dist/local/store/expo/models/kyber-prekey-used.js +23 -9
  191. package/dist/local/store/expo/models/kyber-prekey-used.js.map +1 -1
  192. package/dist/local/store/expo/models/kyber-prekey.d.ts +4 -4
  193. package/dist/local/store/expo/models/kyber-prekey.d.ts.map +1 -1
  194. package/dist/local/store/expo/models/kyber-prekey.js +67 -26
  195. package/dist/local/store/expo/models/kyber-prekey.js.map +1 -1
  196. package/dist/local/store/expo/schema.d.ts +21 -2
  197. package/dist/local/store/expo/schema.d.ts.map +1 -1
  198. package/dist/local/store/expo/schema.js +10 -2
  199. package/dist/local/store/expo/schema.js.map +1 -1
  200. package/dist/local/store/kyber-prekey-lifecycle.d.ts +46 -0
  201. package/dist/local/store/kyber-prekey-lifecycle.d.ts.map +1 -0
  202. package/dist/local/store/kyber-prekey-lifecycle.js +88 -0
  203. package/dist/local/store/kyber-prekey-lifecycle.js.map +1 -0
  204. package/dist/local/store/memory/adapter.d.ts +11 -3
  205. package/dist/local/store/memory/adapter.d.ts.map +1 -1
  206. package/dist/local/store/memory/adapter.js +113 -28
  207. package/dist/local/store/memory/adapter.js.map +1 -1
  208. package/dist/local/store/node/adapter.d.ts +8 -2
  209. package/dist/local/store/node/adapter.d.ts.map +1 -1
  210. package/dist/local/store/node/adapter.js +31 -13
  211. package/dist/local/store/node/adapter.js.map +1 -1
  212. package/dist/local/store/node/database-file-commit.d.ts +8 -0
  213. package/dist/local/store/node/database-file-commit.d.ts.map +1 -0
  214. package/dist/local/store/node/database-file-commit.js +62 -0
  215. package/dist/local/store/node/database-file-commit.js.map +1 -0
  216. package/dist/local/store/node/database-key.d.ts +6 -1
  217. package/dist/local/store/node/database-key.d.ts.map +1 -1
  218. package/dist/local/store/node/database-key.js +79 -44
  219. package/dist/local/store/node/database-key.js.map +1 -1
  220. package/dist/local/store/node/database-lock.d.ts +8 -0
  221. package/dist/local/store/node/database-lock.d.ts.map +1 -0
  222. package/dist/local/store/node/database-lock.js +44 -0
  223. package/dist/local/store/node/database-lock.js.map +1 -0
  224. package/dist/local/store/node/database.d.ts +15 -14
  225. package/dist/local/store/node/database.d.ts.map +1 -1
  226. package/dist/local/store/node/database.js +197 -202
  227. package/dist/local/store/node/database.js.map +1 -1
  228. package/dist/local/store/react-native/adapter.d.ts +8 -2
  229. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  230. package/dist/local/store/react-native/adapter.js +151 -66
  231. package/dist/local/store/react-native/adapter.js.map +1 -1
  232. package/dist/local/store/received-content.d.ts +9 -0
  233. package/dist/local/store/received-content.d.ts.map +1 -0
  234. package/dist/local/store/received-content.js +46 -0
  235. package/dist/local/store/received-content.js.map +1 -0
  236. package/dist/local/store/reliability.d.ts +2 -2
  237. package/dist/local/store/reliability.d.ts.map +1 -1
  238. package/dist/local/store/reliability.js +7 -4
  239. package/dist/local/store/reliability.js.map +1 -1
  240. package/dist/local/store/web/adapter.d.ts +8 -2
  241. package/dist/local/store/web/adapter.d.ts.map +1 -1
  242. package/dist/local/store/web/adapter.js +206 -73
  243. package/dist/local/store/web/adapter.js.map +1 -1
  244. package/dist/media/index.d.ts +71 -61
  245. package/dist/media/index.d.ts.map +1 -1
  246. package/dist/media/index.js +550 -386
  247. package/dist/media/index.js.map +1 -1
  248. package/dist/media/prepared-upload.d.ts +37 -0
  249. package/dist/media/prepared-upload.d.ts.map +1 -0
  250. package/dist/media/prepared-upload.js +46 -0
  251. package/dist/media/prepared-upload.js.map +1 -0
  252. package/dist/remote/object-store/convex-r2/server.d.ts +2 -1
  253. package/dist/remote/object-store/convex-r2/server.d.ts.map +1 -1
  254. package/dist/remote/object-store/convex-r2/server.js +4 -0
  255. package/dist/remote/object-store/convex-r2/server.js.map +1 -1
  256. package/dist/remote/object-store/convex-r2/storage.d.ts.map +1 -1
  257. package/dist/remote/object-store/convex-r2/storage.js +1 -0
  258. package/dist/remote/object-store/convex-r2/storage.js.map +1 -1
  259. package/dist/remote/object-store/index.d.ts +3 -1
  260. package/dist/remote/object-store/index.d.ts.map +1 -1
  261. package/dist/remote/object-store/index.js +1 -1
  262. package/dist/remote/object-store/index.js.map +1 -1
  263. package/dist/remote/object-store/s3/storage.d.ts +3 -1
  264. package/dist/remote/object-store/s3/storage.d.ts.map +1 -1
  265. package/dist/remote/object-store/s3/storage.js +9 -2
  266. package/dist/remote/object-store/s3/storage.js.map +1 -1
  267. package/dist/remote/object-store/types.d.ts +33 -4
  268. package/dist/remote/object-store/types.d.ts.map +1 -1
  269. package/dist/remote/object-store/upload-error.d.ts +23 -0
  270. package/dist/remote/object-store/upload-error.d.ts.map +1 -0
  271. package/dist/remote/object-store/upload-error.js +33 -0
  272. package/dist/remote/object-store/upload-error.js.map +1 -0
  273. package/dist/remote/object-store/validation.d.ts +7 -1
  274. package/dist/remote/object-store/validation.d.ts.map +1 -1
  275. package/dist/remote/object-store/validation.js +39 -25
  276. package/dist/remote/object-store/validation.js.map +1 -1
  277. package/dist/remote/relay/index.d.ts +5 -12
  278. package/dist/remote/relay/index.d.ts.map +1 -1
  279. package/dist/remote/relay/index.js +4 -11
  280. package/dist/remote/relay/index.js.map +1 -1
  281. package/dist/remote/relay/memory/adapter.d.ts +2 -1
  282. package/dist/remote/relay/memory/adapter.d.ts.map +1 -1
  283. package/dist/remote/relay/memory/adapter.js +10 -0
  284. package/dist/remote/relay/memory/adapter.js.map +1 -1
  285. package/dist/remote/relay/types.d.ts +28 -17
  286. package/dist/remote/relay/types.d.ts.map +1 -1
  287. package/dist/types/api.d.ts +36 -1
  288. package/dist/types/api.d.ts.map +1 -1
  289. package/dist/types/session.d.ts +6 -0
  290. package/dist/types/session.d.ts.map +1 -1
  291. package/dist/types/session.js.map +1 -1
  292. package/docs/ASSURANCE.md +7 -7
  293. package/docs/CLIENT_COMPOSITION.md +12 -19
  294. package/docs/DEVIATIONS.md +1 -1
  295. package/docs/DOCUMENTATION_STANDARDS.md +4 -0
  296. package/docs/GETTING_STARTED.md +23 -38
  297. package/docs/INTERFACES.md +22 -13
  298. package/docs/PACKAGE_SURFACE.md +5 -12
  299. package/docs/RECIPES.md +10 -23
  300. package/examples/browser/index.html +2 -2
  301. package/local/store/README.md +16 -1
  302. package/local/store/expo/README.md +23 -19
  303. package/local/store/node/README.md +29 -0
  304. package/media/README.md +94 -0
  305. package/package.json +17 -27
  306. package/remote/README.md +16 -16
  307. package/remote/object-store/README.md +8 -0
  308. package/remote/object-store/s3/README.md +10 -1
  309. package/remote/relay/README.md +3 -2
  310. package/COMMERCIAL.md +0 -56
  311. package/dist/device/expo-metadata.d.ts.map +0 -1
  312. package/dist/device/expo-metadata.js.map +0 -1
  313. package/dist/remote/relay/convex/backend.d.ts +0 -394
  314. package/dist/remote/relay/convex/backend.d.ts.map +0 -1
  315. package/dist/remote/relay/convex/backend.js +0 -678
  316. package/dist/remote/relay/convex/backend.js.map +0 -1
  317. package/dist/remote/relay/convex/component/_generated/api.d.ts +0 -58
  318. package/dist/remote/relay/convex/component/_generated/api.d.ts.map +0 -1
  319. package/dist/remote/relay/convex/component/_generated/api.js +0 -31
  320. package/dist/remote/relay/convex/component/_generated/api.js.map +0 -1
  321. package/dist/remote/relay/convex/component/_generated/component.d.ts +0 -475
  322. package/dist/remote/relay/convex/component/_generated/component.d.ts.map +0 -1
  323. package/dist/remote/relay/convex/component/_generated/component.js +0 -11
  324. package/dist/remote/relay/convex/component/_generated/component.js.map +0 -1
  325. package/dist/remote/relay/convex/component/_generated/dataModel.d.ts +0 -46
  326. package/dist/remote/relay/convex/component/_generated/dataModel.d.ts.map +0 -1
  327. package/dist/remote/relay/convex/component/_generated/dataModel.js +0 -11
  328. package/dist/remote/relay/convex/component/_generated/dataModel.js.map +0 -1
  329. package/dist/remote/relay/convex/component/_generated/server.d.ts +0 -129
  330. package/dist/remote/relay/convex/component/_generated/server.d.ts.map +0 -1
  331. package/dist/remote/relay/convex/component/_generated/server.js +0 -79
  332. package/dist/remote/relay/convex/component/_generated/server.js.map +0 -1
  333. package/dist/remote/relay/convex/component/accounts.d.ts +0 -45
  334. package/dist/remote/relay/convex/component/accounts.d.ts.map +0 -1
  335. package/dist/remote/relay/convex/component/accounts.js +0 -184
  336. package/dist/remote/relay/convex/component/accounts.js.map +0 -1
  337. package/dist/remote/relay/convex/component/certificates.d.ts +0 -10
  338. package/dist/remote/relay/convex/component/certificates.d.ts.map +0 -1
  339. package/dist/remote/relay/convex/component/certificates.js +0 -126
  340. package/dist/remote/relay/convex/component/certificates.js.map +0 -1
  341. package/dist/remote/relay/convex/component/cleanup.d.ts +0 -32
  342. package/dist/remote/relay/convex/component/cleanup.d.ts.map +0 -1
  343. package/dist/remote/relay/convex/component/cleanup.js +0 -146
  344. package/dist/remote/relay/convex/component/cleanup.js.map +0 -1
  345. package/dist/remote/relay/convex/component/convex.config.d.ts +0 -5
  346. package/dist/remote/relay/convex/component/convex.config.d.ts.map +0 -1
  347. package/dist/remote/relay/convex/component/convex.config.js +0 -35
  348. package/dist/remote/relay/convex/component/convex.config.js.map +0 -1
  349. package/dist/remote/relay/convex/component/crons.d.ts +0 -3
  350. package/dist/remote/relay/convex/component/crons.d.ts.map +0 -1
  351. package/dist/remote/relay/convex/component/crons.js +0 -10
  352. package/dist/remote/relay/convex/component/crons.js.map +0 -1
  353. package/dist/remote/relay/convex/component/devices.d.ts +0 -102
  354. package/dist/remote/relay/convex/component/devices.d.ts.map +0 -1
  355. package/dist/remote/relay/convex/component/devices.js +0 -300
  356. package/dist/remote/relay/convex/component/devices.js.map +0 -1
  357. package/dist/remote/relay/convex/component/errors.d.ts +0 -22
  358. package/dist/remote/relay/convex/component/errors.d.ts.map +0 -1
  359. package/dist/remote/relay/convex/component/errors.js +0 -17
  360. package/dist/remote/relay/convex/component/errors.js.map +0 -1
  361. package/dist/remote/relay/convex/component/groups.d.ts +0 -63
  362. package/dist/remote/relay/convex/component/groups.d.ts.map +0 -1
  363. package/dist/remote/relay/convex/component/groups.js +0 -341
  364. package/dist/remote/relay/convex/component/groups.js.map +0 -1
  365. package/dist/remote/relay/convex/component/keys.d.ts +0 -130
  366. package/dist/remote/relay/convex/component/keys.d.ts.map +0 -1
  367. package/dist/remote/relay/convex/component/keys.js +0 -578
  368. package/dist/remote/relay/convex/component/keys.js.map +0 -1
  369. package/dist/remote/relay/convex/component/messages.d.ts +0 -105
  370. package/dist/remote/relay/convex/component/messages.d.ts.map +0 -1
  371. package/dist/remote/relay/convex/component/messages.js +0 -702
  372. package/dist/remote/relay/convex/component/messages.js.map +0 -1
  373. package/dist/remote/relay/convex/component/provisioning.d.ts +0 -92
  374. package/dist/remote/relay/convex/component/provisioning.d.ts.map +0 -1
  375. package/dist/remote/relay/convex/component/provisioning.js +0 -360
  376. package/dist/remote/relay/convex/component/provisioning.js.map +0 -1
  377. package/dist/remote/relay/convex/component/runtime.d.ts +0 -18
  378. package/dist/remote/relay/convex/component/runtime.d.ts.map +0 -1
  379. package/dist/remote/relay/convex/component/runtime.js +0 -144
  380. package/dist/remote/relay/convex/component/runtime.js.map +0 -1
  381. package/dist/remote/relay/convex/component/schema.d.ts +0 -358
  382. package/dist/remote/relay/convex/component/schema.d.ts.map +0 -1
  383. package/dist/remote/relay/convex/component/schema.js +0 -288
  384. package/dist/remote/relay/convex/component/schema.js.map +0 -1
  385. package/dist/remote/relay/convex/component/zkAuth.d.ts +0 -18
  386. package/dist/remote/relay/convex/component/zkAuth.d.ts.map +0 -1
  387. package/dist/remote/relay/convex/component/zkAuth.js +0 -86
  388. package/dist/remote/relay/convex/component/zkAuth.js.map +0 -1
  389. package/dist/remote/relay/convex/constants.d.ts +0 -3
  390. package/dist/remote/relay/convex/constants.d.ts.map +0 -1
  391. package/dist/remote/relay/convex/constants.js +0 -3
  392. package/dist/remote/relay/convex/constants.js.map +0 -1
  393. package/dist/remote/relay/convex/group-server.d.ts +0 -123
  394. package/dist/remote/relay/convex/group-server.d.ts.map +0 -1
  395. package/dist/remote/relay/convex/group-server.js +0 -184
  396. package/dist/remote/relay/convex/group-server.js.map +0 -1
  397. package/dist/remote/relay/convex/index.d.ts +0 -42
  398. package/dist/remote/relay/convex/index.d.ts.map +0 -1
  399. package/dist/remote/relay/convex/index.js +0 -38
  400. package/dist/remote/relay/convex/index.js.map +0 -1
  401. package/dist/remote/relay/convex/relay.d.ts +0 -323
  402. package/dist/remote/relay/convex/relay.d.ts.map +0 -1
  403. package/dist/remote/relay/convex/relay.js +0 -1144
  404. package/dist/remote/relay/convex/relay.js.map +0 -1
  405. package/dist/remote/relay/convex/types.d.ts +0 -24
  406. package/dist/remote/relay/convex/types.d.ts.map +0 -1
  407. package/dist/remote/relay/convex/types.js +0 -14
  408. package/dist/remote/relay/convex/types.js.map +0 -1
  409. package/remote/relay/convex/README.md +0 -61
  410. package/remote/relay/convex/component/README.md +0 -462
@@ -27,33 +27,24 @@ const signal = await createSignalProtocolClient({
27
27
  });
28
28
  ```
29
29
 
30
- ## Expo + Convex Client
30
+ ## Expo client on the Signal Protocol Relay
31
31
 
32
32
  <!-- doc-snippet:skip requires-external-context -->
33
33
  ```ts
34
- import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
34
+ import { createHostedSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
35
35
  import { expoStore } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
36
- import {
37
- convexRelay,
38
- type ConvexSignalProtocolRelayApi,
39
- } from "@open-e2ee/signal-protocol-sdk/remote/relay/convex";
40
- import { api } from "../convex/_generated/api";
41
-
42
- const signalApi = api.signal satisfies ConvexSignalProtocolRelayApi;
43
-
44
- // Convex owns relay-side device lists, public prekeys, and encrypted envelopes.
45
- const relay = convexRelay({
46
- convex,
47
- api: signalApi,
48
- currentUserId: userId,
49
- });
50
36
 
51
- const signal = await createSignalProtocolClient({
52
- identity: { userId, deviceId: 1 },
37
+ // Initialize the application-owned Expo/SQLCipher database bindings first.
38
+ const signal = await createHostedSignalProtocolClient({
53
39
  adapters: {
54
40
  // Expo storage owns this device's private keys and session state.
55
41
  storage: expoStore(),
56
- relay,
42
+ },
43
+ hosted: {
44
+ // The environment-scoped connection URL from the OpenE2EE console.
45
+ relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
46
+ // Returns a short-lived signed assertion for the signed-in user.
47
+ getIdentityAssertion,
57
48
  },
58
49
  logger,
59
50
  });
@@ -78,6 +69,8 @@ const signal = await createSignalProtocolClient({
78
69
  }),
79
70
  },
80
71
  media: {
72
+ preparedUploads: appPreparedUploads,
73
+ maxPreparedUploadBytes: appUploadBudgetBytes,
81
74
  // The existing Signal Protocol storage adapter persists queue metadata.
82
75
  // These callbacks keep app-owned files, plaintext cache, and UI state
83
76
  // outside the protocol package.
@@ -905,7 +905,7 @@ control before it signs and persists the accepted result.
905
905
 
906
906
  The enforcement rules are the SDK's own S1–S14 contract rather than Signal
907
907
  Messenger's server implementation. The shipped enforcing server
908
- (`internal/groups/server-engine.ts`, with an installable Convex component)
908
+ (`internal/groups/server-engine.ts`, which the OpenE2EE Signal Protocol Relay runs)
909
909
  implements that contract. On every applied change, clients verify the server's
910
910
  signature, the group binding, the strict version sequence, and the pre-state
911
911
  authorization.
@@ -77,6 +77,10 @@ substitute for documenting the local behavior.
77
77
  - **Application** or **host application** names the consuming product.
78
78
  - **Relay** names the application backend interface for device state, public
79
79
  prekeys, and encrypted envelopes.
80
+ - **OpenE2EE Signal Protocol Relay** names the hosted relay that OpenE2EE
81
+ operates for this SDK. **Signal Protocol Relay** is the permitted short form
82
+ in error messages and repeated references. Do not write OpenE2EE Relay,
83
+ Managed Relay, or hosted Relay.
80
84
  - **Remote object store** names the brokered ciphertext-storage interface.
81
85
 
82
86
  Do not imply affiliation with Signal Messenger or general compatibility with
@@ -13,7 +13,7 @@ npm install @open-e2ee/signal-protocol-sdk
13
13
 
14
14
  In this monorepo, consumers use the package as a workspace package. App consumers
15
15
  should also install any runtime dependencies their chosen adapters need, such as
16
- Expo or Convex client packages.
16
+ Expo packages.
17
17
 
18
18
  ## What You Need
19
19
 
@@ -102,7 +102,7 @@ flowchart LR
102
102
  - The remote object store carries encrypted attachment/media bytes only.
103
103
 
104
104
  You can operate these server-side interfaces through a shipped or custom
105
- adapter. You can instead use [OpenE2EE Relay](https://open-e2ee.dev/relay) for
105
+ adapter. You can instead use [OpenE2EE Signal Protocol Relay](https://open-e2ee.dev/relay) for
106
106
  managed encrypted delivery, private encrypted attachment storage, push wakes,
107
107
  and lifecycle controls. The SDK does not require the managed service. The
108
108
  [Relay pricing page](https://open-e2ee.dev/relay/pricing) defines its exact
@@ -170,21 +170,16 @@ The production shape uses the same message API with platform adapters:
170
170
 
171
171
  <!-- doc-snippet:planned target-message-api-platform-adapters unshipped="@open-e2ee/signal-protocol-sdk/device/storage/expo" -->
172
172
  ```ts
173
- import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
173
+ import { createHostedSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
174
174
  import { createExpoDeviceStorage } from "@open-e2ee/signal-protocol-sdk/device/storage/expo";
175
- import { convexR2ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2";
176
- import { convexRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/convex";
177
- import { api } from "../convex/_generated/api";
178
175
 
179
- const signal = await createSignalProtocolClient({
180
- identity: { userId, deviceId },
176
+ const signal = await createHostedSignalProtocolClient({
181
177
  adapters: {
182
178
  deviceStorage: createExpoDeviceStorage({ database, files }),
183
- relay: convexRelay({ convex, api, currentUserId: userId }),
184
- remoteObjectStore: convexR2ObjectStore({
185
- convex,
186
- api: api.signalObjectStore,
187
- }),
179
+ },
180
+ hosted: {
181
+ relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
182
+ getIdentityAssertion,
188
183
  },
189
184
  });
190
185
  ```
@@ -320,40 +315,28 @@ session, and later messages use `ciphertext`.
320
315
 
321
316
  ## Production Client
322
317
 
323
- Use the protocol storage adapter for your runtime and the relay adapter for your
324
- backend. For the Signal Protocol stack, that is Expo local storage and a Convex
325
- relay:
318
+ Use the protocol storage adapter for your runtime and connect to the OpenE2EE
319
+ Signal Protocol Relay. For an Expo app, that is Expo local storage and the
320
+ hosted client:
326
321
 
327
322
  <!-- doc-snippet:skip requires-external-context -->
328
323
  ```ts
329
- import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
324
+ import { createHostedSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
330
325
  import { expoStore } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
331
- import {
332
- convexRelay,
333
- type ConvexSignalProtocolRelayApi,
334
- } from "@open-e2ee/signal-protocol-sdk/remote/relay/convex";
335
- import { api } from "../convex/_generated/api";
336
-
337
- const signalApi = api.signal satisfies ConvexSignalProtocolRelayApi;
338
326
 
339
- // The relay handles server-side public keys, devices, and encrypted envelopes.
340
- const relay = convexRelay({
341
- convex,
342
- api: signalApi,
343
- currentUserId: userId,
344
- });
345
-
346
- const signal = await createSignalProtocolClient({
347
- identity: { userId },
327
+ // Initialize the application-owned Expo/SQLCipher database bindings first.
328
+ const signal = await createHostedSignalProtocolClient({
348
329
  adapters: {
349
- // Storage owns this device's private keys and session state.
330
+ // Expo storage owns this device's private keys and session state.
350
331
  storage: expoStore(),
351
- relay,
332
+ },
333
+ hosted: {
334
+ // The environment-scoped connection URL from the OpenE2EE console.
335
+ relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
336
+ // Returns a short-lived signed assertion for the signed-in user.
337
+ getIdentityAssertion,
352
338
  },
353
339
  });
354
-
355
- // Publish this device's public prekeys so other devices can start sessions.
356
- await signal.syncToServer();
357
340
  ```
358
341
 
359
342
  Production bootstrapping must register or provision the current device with the
@@ -431,6 +414,8 @@ const signal = await createSignalProtocolClient({
431
414
  }),
432
415
  },
433
416
  media: {
417
+ preparedUploads: appPreparedUploads,
418
+ maxPreparedUploadBytes: appUploadBudgetBytes,
434
419
  loadLocalAttachment: async ({ localMediaId }) =>
435
420
  appDraftMedia.readBytes(localMediaId),
436
421
  saveUploadedAttachment: async ({ localMediaId, attachment }) =>
@@ -88,19 +88,12 @@ delivery, provisioning, key rotation, and encrypted group coordination.
88
88
  <!-- doc-snippet:skip requires-external-context -->
89
89
  ```ts
90
90
  import type { ISignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/relay";
91
- import {
92
- convexRelay,
93
- type ConvexSignalProtocolRelayApi,
94
- } from "@open-e2ee/signal-protocol-sdk/remote/relay/convex";
95
- import { api } from "../convex/_generated/api";
96
-
97
- const signalApi = api.signal satisfies ConvexSignalProtocolRelayApi;
98
-
99
- const relay: ISignalProtocolRelayServer = convexRelay({
100
- convex,
101
- api: signalApi,
102
- currentUserId: userId,
103
- });
91
+ import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
92
+
93
+ // Development uses the in-memory relay. Production connects to the OpenE2EE
94
+ // Signal Protocol Relay through `createHostedSignalProtocolClient()`, or to an
95
+ // application backend that implements this interface.
96
+ const relay: ISignalProtocolRelayServer = inMemoryRelay();
104
97
  ```
105
98
 
106
99
  The application backend must:
@@ -114,6 +107,20 @@ The application backend must:
114
107
 
115
108
  A client-supplied user identifier is a routing input, not proof of identity.
116
109
 
110
+ Each adapter implements `getPreKeyInventory` for prekey synchronization.
111
+ It returns both reusable-key metadata records and both one-time-key counts.
112
+ These observations do not consume keys, reserve a version, or authorize an upload.
113
+ Callers request new observations after intervening work.
114
+ The Signal Protocol Relay persists a separate public-eligibility snapshot for its published
115
+ prekeys. A publication reads the current public inventory, names its exact
116
+ predecessor revision, persists one pending receipt before the request, and reads
117
+ the accepted inventory before it commits the new receipt. An exact retry can
118
+ recover a lost response. A stale or reordered writer cannot restore material
119
+ that the Relay already issued. Retained private prekeys are not a publication
120
+ inventory.
121
+
122
+ The server remains responsible for atomic one-time-key consumption.
123
+
117
124
  The relay stores public protocol material, ciphertext, and required routing
118
125
  metadata. It must not require device private keys or decrypted message content.
119
126
  See the [relay guide](../remote/relay/README.md).
@@ -165,6 +172,8 @@ const client = await createSignalProtocolClient({
165
172
  identity: { userId },
166
173
  adapters: { storage, relay, remoteObjectStore },
167
174
  media: {
175
+ preparedUploads: appPreparedUploads,
176
+ maxPreparedUploadBytes: appUploadBudgetBytes,
168
177
  loadLocalAttachment: ({ localMediaId }) =>
169
178
  appDrafts.readBytes(localMediaId),
170
179
  saveUploadedAttachment: ({ localMediaId, attachment }) =>
@@ -59,14 +59,11 @@ import {
59
59
  ```
60
60
 
61
61
  The root package intentionally does not re-export platform-bound adapters like
62
- Expo storage or Convex helpers.
62
+ Expo storage or the Convex R2 object store.
63
63
 
64
64
  ## Integration subpaths
65
65
 
66
66
  - `@open-e2ee/signal-protocol-sdk/remote/relay`
67
- - `@open-e2ee/signal-protocol-sdk/remote/relay/convex`
68
- - `@open-e2ee/signal-protocol-sdk/remote/relay/convex/relay`
69
- - `@open-e2ee/signal-protocol-sdk/convex.config`
70
67
  - `@open-e2ee/signal-protocol-sdk/remote/relay/memory`
71
68
  - `@open-e2ee/signal-protocol-sdk/remote/relay/types`
72
69
  - `@open-e2ee/signal-protocol-sdk/remote/object-store`
@@ -83,13 +80,14 @@ Expo storage or Convex helpers.
83
80
  - `@open-e2ee/signal-protocol-sdk/device`
84
81
  - `@open-e2ee/signal-protocol-sdk/device/constants`
85
82
  - `@open-e2ee/signal-protocol-sdk/device/device-id`
86
- - `@open-e2ee/signal-protocol-sdk/device/expo-metadata`
83
+ - `@open-e2ee/signal-protocol-sdk/device/expo`
87
84
  - `@open-e2ee/signal-protocol-sdk/device/lifecycle`
88
85
  - `@open-e2ee/signal-protocol-sdk/device/provisioning`
89
86
  - `@open-e2ee/signal-protocol-sdk/encoding`
90
87
  - `@open-e2ee/signal-protocol-sdk/encoding/hex`
91
88
  - `@open-e2ee/signal-protocol-sdk/files`
92
89
  - `@open-e2ee/signal-protocol-sdk/groups`
90
+ - `@open-e2ee/signal-protocol-sdk/groups/server`
93
91
  - `@open-e2ee/signal-protocol-sdk/hooks`
94
92
  - `@open-e2ee/signal-protocol-sdk/hooks/use-connection-presence`
95
93
  - `@open-e2ee/signal-protocol-sdk/keys`
@@ -146,13 +144,8 @@ Expo storage or Convex helpers.
146
144
 
147
145
  ### Relay implementations
148
146
 
149
- - `ConvexSignalProtocolRelayServer` for Convex-backed apps
150
- - `convexRelay()` for Convex-backed composition
151
- - the installable component from
152
- `@open-e2ee/signal-protocol-sdk/convex.config`, with public handlers from
153
- `defineConvexSignalProtocolBackend()` and the `oe-groups` CLI
154
- (`npx oe-groups trust-root`) for secret initialization and trust-root
155
- export
147
+ - `createHostedSignalProtocolClient()` from the package root for the OpenE2EE
148
+ Signal Protocol Relay
156
149
  - `InMemorySignalProtocolRelayServer` / `inMemoryRelay()` for local development
157
150
  - custom implementations via `ISignalProtocolRelayServer`
158
151
 
package/docs/RECIPES.md CHANGED
@@ -93,39 +93,26 @@ the session. Later messages on the same session use `ciphertext`. In both cases
93
93
  the relay sees encrypted envelope bytes. Bob receives decrypted content only
94
94
  through the `onMessageDecrypted` hook.
95
95
 
96
- ## Production composition with Convex + Expo
96
+ ## Production composition with Expo on the Signal Protocol Relay
97
97
 
98
98
  <!-- doc-snippet:skip requires-external-context -->
99
99
  ```ts
100
- import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
101
- import {
102
- convexRelay,
103
- type ConvexSignalProtocolRelayApi,
104
- } from "@open-e2ee/signal-protocol-sdk/remote/relay/convex";
100
+ import { createHostedSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
105
101
  import { expoStore } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
106
- import { api } from "../convex/_generated/api";
107
-
108
- const signalApi = api.signal satisfies ConvexSignalProtocolRelayApi;
109
-
110
- // The relay handles server-side public keys, devices, and encrypted envelopes.
111
- const relay = convexRelay({
112
- convex,
113
- api: signalApi,
114
- currentUserId: userId,
115
- });
116
102
 
117
103
  // Initialize the application-owned Expo/SQLCipher database bindings first.
118
- const signal = await createSignalProtocolClient({
119
- identity: { userId },
104
+ const signal = await createHostedSignalProtocolClient({
120
105
  adapters: {
121
- // Storage owns this device's private keys and session state.
106
+ // Expo storage owns this device's private keys and session state.
122
107
  storage: expoStore(),
123
- relay,
108
+ },
109
+ hosted: {
110
+ // The environment-scoped connection URL from the OpenE2EE console.
111
+ relayUrl: process.env.EXPO_PUBLIC_OPEN_E2EE_RELAY_URL!,
112
+ // Returns a short-lived signed assertion for the signed-in user.
113
+ getIdentityAssertion,
124
114
  },
125
115
  });
126
-
127
- // Publish this device's public prekeys so other devices can start sessions.
128
- await signal.syncToServer();
129
116
  ```
130
117
 
131
118
  Production bootstrapping must register or provision the current device with the
@@ -19,8 +19,8 @@
19
19
  <p id="status" role="status">Ready</p>
20
20
  <pre id="output" aria-label="Execution output" tabindex="0"></pre>
21
21
  <p>The browser console shows the same results. Ciphertext changes on each run.</p>
22
- <p><a href="https://github.com/open-e2ee/signal-protocol-js/tree/v2.0.2/examples/browser/src/exchange.ts">Read the exchange code</a> · <a href="https://stackblitz.com/fork/github/open-e2ee/signal-protocol-js/tree/v2.0.2/examples/browser">Edit on StackBlitz</a></p>
23
- <p>Continue with <a href="https://docs.open-e2ee.dev/start/browser">browser storage</a>, <a href="https://docs.open-e2ee.dev/start/expo">Expo / Hermes setup</a>, or <a href="https://open-e2ee.dev/relay">OpenE2EE Relay for separate devices</a>.</p>
22
+ <p><a href="https://github.com/open-e2ee/signal-protocol-js/tree/v3.0.0/examples/browser/src/exchange.ts">Read the exchange code</a> · <a href="https://stackblitz.com/fork/github/open-e2ee/signal-protocol-js/tree/v3.0.0/examples/browser">Edit on StackBlitz</a></p>
23
+ <p>Continue with <a href="https://docs.open-e2ee.dev/start/browser">browser storage</a>, <a href="https://docs.open-e2ee.dev/start/expo">Expo / Hermes setup</a>, or <a href="https://open-e2ee.dev/relay">the OpenE2EE Signal Protocol Relay for separate devices</a>.</p>
24
24
  </main>
25
25
  <script type="module" src="/src/main.ts"></script>
26
26
  </body>
@@ -187,7 +187,7 @@ every live session.
187
187
 
188
188
  ## Atomic Security Commits
189
189
 
190
- Contact trust and session creation/advancement share one atomic commit seam.
190
+ Contact trust and session creation/advancement share one atomic commit boundary.
191
191
  Responder one-time-prekey consumption joins that same transaction. Separately,
192
192
  one logical transaction accepts an identity rotation and deletes every bound
193
193
  device session. An adapter must never publish only a subset of either
@@ -205,6 +205,21 @@ identity.
205
205
 
206
206
  ## Design Notes
207
207
 
208
+ Received content uses the same encryption and transaction boundary as protocol state.
209
+
210
+ The `commitSessionTrust` method commits received content, ratchet state, contact trust, and consumed prekeys together.
211
+ The `storeSenderKeyRecord` method commits received content and skipped-key consumption together.
212
+
213
+ An adapter must reject the complete transaction if any write fails.
214
+ `getReceivedContent`, `deleteReceivedContent`, and `deleteExpiredReceivedContent`
215
+ own recovery and cleanup. Generic unencrypted metadata cannot hold this content.
216
+ The Node adapter uses its encrypted security document. Expo uses SQLCipher.
217
+ Web and React Native encrypt each content record with their existing store key.
218
+
219
+ The SDK removes content after durable handling and retains separate bounded
220
+ duplicate evidence. Cleanup uses the existing thirty-day retry horizon.
221
+ The host application must use idempotent writes keyed by message ID.
222
+
208
223
  - The Expo adapter is the primary supported mobile implementation. Deployment
209
224
  still requires review of key custody, backups, and host security.
210
225
  - `@open-e2ee/signal-protocol-sdk/local/store/expo` is also the package home for Expo-specific
@@ -14,29 +14,31 @@ schema and transaction lifecycle.
14
14
 
15
15
  ## Database setup
16
16
 
17
- Compose the exported table definitions into the application schema, configure
17
+ The package ships the authoritative Drizzle table definitions at
18
+ `@open-e2ee/signal-protocol-sdk/local/store/expo/schema`. The host application
19
+ owns migration generation and execution. Generate migrations from the package
20
+ version that the application uses. Apply those migrations before the store
21
+ makes its first query.
22
+
23
+ Compose the exported table definitions into the application schema. Configure
18
24
  the database bindings once during bootstrap, and apply the database key before
19
25
  the first query:
20
26
 
21
27
  <!-- doc-snippet:skip requires-external-context -->
28
+
22
29
  ```ts
23
- import {
24
- configureSignalProtocolExpoDbBindings,
25
- } from "@open-e2ee/signal-protocol-sdk/local/store/expo/db";
26
- import {
27
- getDatabaseKeyManager,
28
- } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
29
- import * as signalSchema from "@open-e2ee/signal-protocol-sdk/local/store/expo/schema";
30
+ import { configureSignalProtocolExpoDbBindings } from '@open-e2ee/signal-protocol-sdk/local/store/expo/db';
31
+ import { getDatabaseKeyManager } from '@open-e2ee/signal-protocol-sdk/local/store/expo';
32
+ import * as signalSchema from '@open-e2ee/signal-protocol-sdk/local/store/expo/schema';
30
33
 
31
34
  const keyManager = getDatabaseKeyManager();
32
35
  await keyManager.initialize();
33
36
  const sqlCipherPassword = await keyManager.getPassword();
34
37
 
35
- const { rawDatabase, drizzleDatabase } =
36
- await appDatabase.openEncryptedSignalProtocolDatabase({
37
- password: sqlCipherPassword,
38
- schema: signalSchema,
39
- });
38
+ const { rawDatabase, drizzleDatabase } = await appDatabase.openEncryptedSignalProtocolDatabase({
39
+ password: sqlCipherPassword,
40
+ schema: signalSchema,
41
+ });
40
42
 
41
43
  configureSignalProtocolExpoDbBindings({
42
44
  getDrizzle: async () => drizzleDatabase,
@@ -52,6 +54,10 @@ bootstrap. It must:
52
54
  - create or migrate the exported tables
53
55
  - return the matching raw and Drizzle handles
54
56
 
57
+ Do not copy the exported table definitions into an application-owned schema.
58
+ Copied definitions can omit key ownership constraints when the package schema
59
+ changes.
60
+
55
61
  SQLCipher requires a development build and is not available in Expo Go.
56
62
 
57
63
  Every table this store exports holds material that must not leave the device.
@@ -67,16 +73,14 @@ Do not back these tables up to a server or sync them between devices.
67
73
  ## Client usage
68
74
 
69
75
  <!-- doc-snippet:skip requires-external-context -->
76
+
70
77
  ```ts
71
- import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
72
- import { expoStore } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
78
+ import { createSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
79
+ import { expoStore } from '@open-e2ee/signal-protocol-sdk/local/store/expo';
73
80
 
74
81
  const client = await createSignalProtocolClient({
75
82
  identity: { userId },
76
- adapters: {
77
- storage: expoStore(),
78
- relay,
79
- },
83
+ adapters: { storage: expoStore(), relay },
80
84
  });
81
85
  ```
82
86
 
@@ -20,6 +20,16 @@ boundary while allowing each deployment to choose an explicit data directory.
20
20
 
21
21
  ## Usage
22
22
 
23
+ Install the Node adapter's native file-lock dependency:
24
+
25
+ ```sh
26
+ npm install fs-native-extensions@1.2.7
27
+ ```
28
+
29
+ The exact version passes the supported-runtime checks on Node.js 22 and 26.
30
+ Dependency upgrades must pass the supported-runtime checks. Other adapters do not load this dependency.
31
+ If the native module or file locking is unavailable, the Node store refuses to open.
32
+
23
33
  <!-- doc-snippet:skip requires-external-context -->
24
34
  ```ts
25
35
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
@@ -41,5 +51,24 @@ account isolation, backups, volume security, process access, and secure account
41
51
  reset. Do not place the store on an eventually consistent or multi-writer
42
52
  network filesystem.
43
53
 
54
+ ## Concurrent access and reset
55
+
56
+ A kernel file lock serializes security-state transactions across processes and
57
+ independent handles. Directory aliases use the same lock inode.
58
+ The lock covers the key check, state read, conditional mutation, and durable write.
59
+ It does not make several SDK calls one transaction.
60
+
61
+ A contender stops after 30 seconds without acquiring the lock. It does not
62
+ remove the lock or continue without exclusion. Process termination releases
63
+ the kernel lock. The next initialization removes interrupted temporary writes.
64
+
65
+ Reset removes stored data but retains the empty `.database.lock` file and its
66
+ directory. It preserves unrelated files. Do not remove the lock file while a process can use the store.
67
+ An interrupted reset blocks access until an explicit reset finishes.
68
+ Handles with the old database key refuse subsequent writes after reset.
69
+
70
+ The application owns a coordinated key rotation across all encrypted records.
71
+ Changing only the key file is not a complete rotation.
72
+
44
73
  See the parent [storage guide](../README.md), [adapter guide](../../../ADAPTERS.md),
45
74
  and [security model](../../../docs/SECURITY.md).
package/media/README.md CHANGED
@@ -16,6 +16,100 @@ objects. Media therefore uses two encryption layers:
16
16
 
17
17
  The remote object store never receives the media key or plaintext.
18
18
 
19
+ ## Durable upload preparation
20
+
21
+ `prepareMediaAttachmentUpload()` covers retries within one invocation.
22
+ A later invocation must not encrypt different bytes under the same `requestId`.
23
+ For restart recovery, use `signal.media.upload()` with `media.preparedUploads` configured.
24
+
25
+ The application implements `MediaAttachmentPreparedUploadStore` beside its local file storage.
26
+ Its atomic `createIfAbsent` operation persists ciphertext and private pointer material together.
27
+ Concurrent callers receive the same durable record.
28
+ The store returns independent copies and retains records until the queue requests deletion.
29
+ It must not evict preparations as disposable cache entries.
30
+
31
+ `withExclusiveAccess` coordinates queue checks and artifact mutations across clients, tabs, and processes that share the store.
32
+ Its callback can use the same store's methods. Process exit must release ownership without a timed lock takeover.
33
+ The SDK holds this access only for local queue and artifact work, not provider calls or application callbacks.
34
+ The application must not mutate queue-owned artifacts outside this coordination boundary.
35
+
36
+ Set `media.maxPreparedUploadBytes` from the application's device-local storage budget. The value must be a positive safe integer.
37
+ There is no SDK default. The queue reserves each upload's exact ciphertext size before loading or encrypting its draft.
38
+ This reservation includes the encoder's header and authentication tags. Pending drafts also hold reservations.
39
+
40
+ Conditional queue writes enforce the total against shared backing state across clients, tabs, and processes.
41
+
42
+ The reservation remains until successful cleanup removes the queued upload.
43
+ Uncertain authorization, pointer callbacks, or artifact deletion do not release capacity.
44
+ If the application lowers its limit, existing uploads can still retry or finish cleanup.
45
+ The queue refuses new work that increases an excessive total. It never evicts an upload to make space.
46
+
47
+ This limit covers ciphertext bytes, not physical disk capacity or encryption memory.
48
+ The application must reserve additional space for private metadata, atomic file commits, and its storage adapter.
49
+ The existing `maxJobs` setting bounds queue entries separately.
50
+ Use one artifact namespace per device-local queue. Independent queues require separate budgets or an application-owned shared storage limit.
51
+
52
+ The queue persists a small preparation fingerprint before remote authorization.
53
+ It saves the canonical object identifier before transfer.
54
+ After a successful transfer response, it persists that progress before broker completion.
55
+ A lost completion response then retries only completion for the same object.
56
+
57
+ After a lost transfer response, `reconcileUpload` can verify the original stored object.
58
+ The SDK checks its object ID, exact length, and SHA-256 against the saved preparation.
59
+ The queue can repeat this check after a client restart without another authorization or transfer.
60
+
61
+ Unknown outcomes and mismatches remain failures. A conditional refusal alone never proves success.
62
+ Metadata-only brokers must omit this capability. The ordinary completion hook does not supply this proof.
63
+
64
+ It persists the completed pointer before the application's `saveUploadedAttachment` callback.
65
+ That callback must be idempotent for the job ID because its result can be lost.
66
+ Local cleanup runs only after the queue records callback completion.
67
+
68
+ After automatic retries stop, a prepared upload keeps its original identity.
69
+ The queue also retains intent after a lost preparation-store reply, before its fingerprint exists.
70
+ Call `signal.media.upload()` with the same input to retry that job explicitly.
71
+ Missing or changed preparation fails without another authorization or new encryption.
72
+ Do not reset the queue to recover uncertain remote work.
73
+
74
+ Broker refusals stop automatic retries without deleting the prepared upload.
75
+ The upload result exposes safe guidance in `failure`.
76
+ `processPending()` reports retained refusals in `uploadFailures`, including after a restart.
77
+ Only an explicit upload call retries a refused preparation.
78
+
79
+ | Failure code | Required action |
80
+ | --- | --- |
81
+ | `upload-expired` | Reconcile the existing upload before explicitly starting another upload. |
82
+ | `upload-clock-skew` | Correct the device clock. Retry when the saved preparation time is valid, without changing its time or identity. |
83
+ | `upload-admission-closed` | Reconcile existing work without moving its admission to another accounting period. |
84
+ | `upload-unavailable` | Check deletion or expiry before explicitly starting another upload. |
85
+ | `upload-identity-conflict` | Restore the original preparation before retrying. |
86
+ | `upload-rejected` | Check connection and permissions without replacing the preparation. |
87
+
88
+ An expired transfer URL remains retryable with the same prepared bytes.
89
+ An uncertain settlement remains retryable even when period-close repair delays it.
90
+ A stale connection does not prove that the prepared upload expired.
91
+ The queue stores only the refusal code, not provider error text.
92
+
93
+ Call `signal.media.abandonUpload(jobId)` to abandon a retained upload explicitly.
94
+ The broker's `abandonUpload` operation uses the original request ID and preparation time without creating another upload.
95
+ Accepted upload usage remains charged. The server retains its refusal and cleanup obligations.
96
+ The SDK records abandonment before the call and removes local artifacts only after confirmation.
97
+ `processPending()` retries uncertain cancellation and local cleanup with the configured delay. Its `abandoned` count reports completed cleanup.
98
+
99
+ A `completed` result returns an existing pointer instead of deleting it.
100
+ The application's pointer callback can save the pointer before its reply is lost.
101
+ Use the existing attachment cleanup operation when the application wants to delete that completed object.
102
+ An unsupported broker leaves the queue retained with actionable guidance.
103
+
104
+ Keep prepared records private on the device, outside queue JSON, logs, and provider payloads.
105
+ The supplied store must survive the failures that the application's recovery contract covers.
106
+ An in-memory test store does not prove disk or device durability.
107
+
108
+ Applications with their own scheduler can persist the result of `prepareMediaAttachmentUploadData()`.
109
+ They then pass that exact preparation to `uploadPreparedMediaAttachment()`.
110
+ The scheduler owns equivalent persistence, callback, and cleanup ordering.
111
+ Broker completion recovery and logical upload expiry remain separate server contracts.
112
+
19
113
  ## Upload and send
20
114
 
21
115
  <!-- doc-snippet:skip requires-external-context -->