@open-e2ee/signal-protocol-sdk 0.3.0 → 1.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 (273) hide show
  1. package/ADAPTERS.md +7 -0
  2. package/ARCHITECTURE.md +2 -0
  3. package/CHANGELOG.md +96 -5
  4. package/README.md +67 -102
  5. package/SECURITY.md +2 -2
  6. package/THIRD_PARTY_NOTICES.md +1 -1
  7. package/TROUBLESHOOTING.md +7 -0
  8. package/blocking/README.md +1 -0
  9. package/client/README.md +10 -0
  10. package/device/README.md +12 -5
  11. package/dist/client/client.d.ts +3 -2
  12. package/dist/client/client.d.ts.map +1 -1
  13. package/dist/client/client.js +58 -25
  14. package/dist/client/client.js.map +1 -1
  15. package/dist/client/config.d.ts +46 -7
  16. package/dist/client/config.d.ts.map +1 -1
  17. package/dist/client/config.js +2 -2
  18. package/dist/client/config.js.map +1 -1
  19. package/dist/client/group-outbox.d.ts +38 -0
  20. package/dist/client/group-outbox.d.ts.map +1 -0
  21. package/dist/client/group-outbox.js +221 -0
  22. package/dist/client/group-outbox.js.map +1 -0
  23. package/dist/client/group-sealed-sender.d.ts +28 -0
  24. package/dist/client/group-sealed-sender.d.ts.map +1 -0
  25. package/dist/client/group-sealed-sender.js +74 -0
  26. package/dist/client/group-sealed-sender.js.map +1 -0
  27. package/dist/client/groups.d.ts.map +1 -1
  28. package/dist/client/groups.js +14 -4
  29. package/dist/client/groups.js.map +1 -1
  30. package/dist/client/hosted-push.d.ts +77 -0
  31. package/dist/client/hosted-push.d.ts.map +1 -0
  32. package/dist/client/hosted-push.js +90 -0
  33. package/dist/client/hosted-push.js.map +1 -0
  34. package/dist/client/hosted.d.ts +207 -0
  35. package/dist/client/hosted.d.ts.map +1 -0
  36. package/dist/client/hosted.js +505 -0
  37. package/dist/client/hosted.js.map +1 -0
  38. package/dist/client/index.d.ts +4 -2
  39. package/dist/client/index.d.ts.map +1 -1
  40. package/dist/client/index.js +2 -0
  41. package/dist/client/index.js.map +1 -1
  42. package/dist/client/relay-subscription.d.ts.map +1 -1
  43. package/dist/client/relay-subscription.js +34 -7
  44. package/dist/client/relay-subscription.js.map +1 -1
  45. package/dist/client/{sealed-sender-ops.d.ts → sealed-sender.d.ts} +39 -22
  46. package/dist/client/sealed-sender.d.ts.map +1 -0
  47. package/dist/client/sealed-sender.js +296 -0
  48. package/dist/client/sealed-sender.js.map +1 -0
  49. package/dist/client/signal-service-cipher.d.ts +23 -26
  50. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  51. package/dist/client/signal-service-cipher.js +465 -706
  52. package/dist/client/signal-service-cipher.js.map +1 -1
  53. package/dist/client/types.d.ts +18 -3
  54. package/dist/client/types.d.ts.map +1 -1
  55. package/dist/client/types.js +6 -0
  56. package/dist/client/types.js.map +1 -1
  57. package/dist/device/index.d.ts +2 -2
  58. package/dist/device/index.d.ts.map +1 -1
  59. package/dist/device/index.js +1 -1
  60. package/dist/device/index.js.map +1 -1
  61. package/dist/device/transfer.d.ts +7 -43
  62. package/dist/device/transfer.d.ts.map +1 -1
  63. package/dist/device/transfer.js +31 -150
  64. package/dist/device/transfer.js.map +1 -1
  65. package/dist/device/types.d.ts +6 -47
  66. package/dist/device/types.d.ts.map +1 -1
  67. package/dist/device/types.js +1 -1
  68. package/dist/device/types.js.map +1 -1
  69. package/dist/index.d.ts +5 -4
  70. package/dist/index.d.ts.map +1 -1
  71. package/dist/index.js +5 -5
  72. package/dist/index.js.map +1 -1
  73. package/dist/internal/encoding/proto/pq-ratchet-serialize.js +1 -1
  74. package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
  75. package/dist/internal/encoding/proto/primitives.js +1 -1
  76. package/dist/internal/encoding/proto/primitives.js.map +1 -1
  77. package/dist/internal/groups/manager.d.ts +3 -3
  78. package/dist/internal/groups/manager.d.ts.map +1 -1
  79. package/dist/internal/groups/manager.js +5 -4
  80. package/dist/internal/groups/manager.js.map +1 -1
  81. package/dist/internal/protocol/sealed-sender/certificate.d.ts +10 -4
  82. package/dist/internal/protocol/sealed-sender/certificate.d.ts.map +1 -1
  83. package/dist/internal/protocol/sealed-sender/certificate.js +64 -7
  84. package/dist/internal/protocol/sealed-sender/certificate.js.map +1 -1
  85. package/dist/internal/protocol/sealed-sender/decryption.d.ts +34 -47
  86. package/dist/internal/protocol/sealed-sender/decryption.d.ts.map +1 -1
  87. package/dist/internal/protocol/sealed-sender/decryption.js +95 -182
  88. package/dist/internal/protocol/sealed-sender/decryption.js.map +1 -1
  89. package/dist/internal/protocol/sealed-sender/encryption.d.ts +49 -64
  90. package/dist/internal/protocol/sealed-sender/encryption.d.ts.map +1 -1
  91. package/dist/internal/protocol/sealed-sender/encryption.js +120 -123
  92. package/dist/internal/protocol/sealed-sender/encryption.js.map +1 -1
  93. package/dist/internal/protocol/sealed-sender/index.d.ts +5 -7
  94. package/dist/internal/protocol/sealed-sender/index.d.ts.map +1 -1
  95. package/dist/internal/protocol/sealed-sender/index.js +4 -12
  96. package/dist/internal/protocol/sealed-sender/index.js.map +1 -1
  97. package/dist/internal/protocol/sealed-sender/{v2-helpers.d.ts → multi-recipient-crypto.d.ts} +1 -1
  98. package/dist/internal/protocol/sealed-sender/multi-recipient-crypto.d.ts.map +1 -0
  99. package/dist/internal/protocol/sealed-sender/{v2-helpers.js → multi-recipient-crypto.js} +1 -1
  100. package/dist/internal/protocol/sealed-sender/multi-recipient-crypto.js.map +1 -0
  101. package/dist/internal/protocol/sealed-sender/{v2-binary.d.ts → multi-recipient-message.d.ts} +3 -2
  102. package/dist/internal/protocol/sealed-sender/multi-recipient-message.d.ts.map +1 -0
  103. package/dist/internal/protocol/sealed-sender/{v2-binary.js → multi-recipient-message.js} +16 -8
  104. package/dist/internal/protocol/sealed-sender/multi-recipient-message.js.map +1 -0
  105. package/dist/internal/protocol/sealed-sender/proto/index.d.ts +3 -0
  106. package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
  107. package/dist/internal/protocol/sealed-sender/proto/index.js +25 -2
  108. package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
  109. package/dist/internal/protocol/sealed-sender/trust-root.d.ts +11 -1
  110. package/dist/internal/protocol/sealed-sender/trust-root.d.ts.map +1 -1
  111. package/dist/internal/protocol/sealed-sender/trust-root.js +13 -1
  112. package/dist/internal/protocol/sealed-sender/trust-root.js.map +1 -1
  113. package/dist/internal/protocol/sealed-sender/types.d.ts +20 -135
  114. package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
  115. package/dist/internal/protocol/sealed-sender/types.js +15 -6
  116. package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
  117. package/dist/internal/protocol/sender-keys/manager.d.ts +22 -1
  118. package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
  119. package/dist/internal/protocol/sender-keys/manager.js +39 -4
  120. package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
  121. package/dist/internal/protocol/spqr/braid-serialize.js +1 -1
  122. package/dist/internal/protocol/spqr/braid-serialize.js.map +1 -1
  123. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js +4 -4
  124. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js.map +1 -1
  125. package/dist/internal/protocol/zk/groups/index.d.ts +1 -1
  126. package/dist/internal/protocol/zk/groups/index.d.ts.map +1 -1
  127. package/dist/internal/protocol/zk/groups/index.js +1 -1
  128. package/dist/internal/protocol/zk/groups/index.js.map +1 -1
  129. package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts +37 -12
  130. package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts.map +1 -1
  131. package/dist/internal/protocol/zk/groups/profile-key-credential.js +104 -31
  132. package/dist/internal/protocol/zk/groups/profile-key-credential.js.map +1 -1
  133. package/dist/internal/sesame/types.d.ts +0 -2
  134. package/dist/internal/sesame/types.d.ts.map +1 -1
  135. package/dist/internal/sesame/types.js +0 -2
  136. package/dist/internal/sesame/types.js.map +1 -1
  137. package/dist/local/store/expo/adapter.d.ts +1 -0
  138. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  139. package/dist/local/store/expo/adapter.js +3 -0
  140. package/dist/local/store/expo/adapter.js.map +1 -1
  141. package/dist/local/store/expo/key-storage.d.ts +1 -0
  142. package/dist/local/store/expo/key-storage.d.ts.map +1 -1
  143. package/dist/local/store/expo/key-storage.js +4 -0
  144. package/dist/local/store/expo/key-storage.js.map +1 -1
  145. package/dist/local/store/memory/adapter.d.ts +1 -0
  146. package/dist/local/store/memory/adapter.d.ts.map +1 -1
  147. package/dist/local/store/memory/adapter.js +4 -0
  148. package/dist/local/store/memory/adapter.js.map +1 -1
  149. package/dist/local/store/node/adapter.d.ts +1 -0
  150. package/dist/local/store/node/adapter.d.ts.map +1 -1
  151. package/dist/local/store/node/adapter.js +3 -0
  152. package/dist/local/store/node/adapter.js.map +1 -1
  153. package/dist/local/store/node/database.d.ts +1 -0
  154. package/dist/local/store/node/database.d.ts.map +1 -1
  155. package/dist/local/store/node/database.js +5 -0
  156. package/dist/local/store/node/database.js.map +1 -1
  157. package/dist/local/store/react-native/adapter.d.ts +1 -0
  158. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  159. package/dist/local/store/react-native/adapter.js +4 -0
  160. package/dist/local/store/react-native/adapter.js.map +1 -1
  161. package/dist/local/store/react-native/reference-backend.js +1 -1
  162. package/dist/local/store/react-native/reference-backend.js.map +1 -1
  163. package/dist/local/store/reliability.d.ts +63 -0
  164. package/dist/local/store/reliability.d.ts.map +1 -0
  165. package/dist/local/store/reliability.js +219 -0
  166. package/dist/local/store/reliability.js.map +1 -0
  167. package/dist/local/store/web/adapter.d.ts +1 -0
  168. package/dist/local/store/web/adapter.d.ts.map +1 -1
  169. package/dist/local/store/web/adapter.js +5 -0
  170. package/dist/local/store/web/adapter.js.map +1 -1
  171. package/dist/media/index.d.ts +0 -1
  172. package/dist/media/index.d.ts.map +1 -1
  173. package/dist/media/index.js +0 -1
  174. package/dist/media/index.js.map +1 -1
  175. package/dist/remote/relay/convex/backend.d.ts +6 -16
  176. package/dist/remote/relay/convex/backend.d.ts.map +1 -1
  177. package/dist/remote/relay/convex/backend.js +12 -21
  178. package/dist/remote/relay/convex/backend.js.map +1 -1
  179. package/dist/remote/relay/convex/component/_generated/component.d.ts +9 -16
  180. package/dist/remote/relay/convex/component/_generated/component.d.ts.map +1 -1
  181. package/dist/remote/relay/convex/component/certificates.d.ts.map +1 -1
  182. package/dist/remote/relay/convex/component/certificates.js +14 -5
  183. package/dist/remote/relay/convex/component/certificates.js.map +1 -1
  184. package/dist/remote/relay/convex/component/messages.d.ts +2 -15
  185. package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
  186. package/dist/remote/relay/convex/component/messages.js +14 -48
  187. package/dist/remote/relay/convex/component/messages.js.map +1 -1
  188. package/dist/remote/relay/convex/component/schema.d.ts +5 -3
  189. package/dist/remote/relay/convex/component/schema.js +2 -1
  190. package/dist/remote/relay/convex/component/schema.js.map +1 -1
  191. package/dist/remote/relay/convex/component/zkAuth.d.ts +7 -1
  192. package/dist/remote/relay/convex/component/zkAuth.d.ts.map +1 -1
  193. package/dist/remote/relay/convex/component/zkAuth.js +29 -14
  194. package/dist/remote/relay/convex/component/zkAuth.js.map +1 -1
  195. package/dist/remote/relay/convex/relay.d.ts +2 -5
  196. package/dist/remote/relay/convex/relay.d.ts.map +1 -1
  197. package/dist/remote/relay/convex/relay.js +17 -47
  198. package/dist/remote/relay/convex/relay.js.map +1 -1
  199. package/dist/remote/relay/memory/adapter.d.ts +4 -10
  200. package/dist/remote/relay/memory/adapter.d.ts.map +1 -1
  201. package/dist/remote/relay/memory/adapter.js +31 -34
  202. package/dist/remote/relay/memory/adapter.js.map +1 -1
  203. package/dist/remote/relay/types.d.ts +6 -19
  204. package/dist/remote/relay/types.d.ts.map +1 -1
  205. package/dist/types/api.d.ts +2 -0
  206. package/dist/types/api.d.ts.map +1 -1
  207. package/dist/types/errors.d.ts +3 -1
  208. package/dist/types/errors.d.ts.map +1 -1
  209. package/dist/types/errors.js +4 -2
  210. package/dist/types/errors.js.map +1 -1
  211. package/dist/types/protocol-config.d.ts +1 -1
  212. package/dist/username/link.d.ts.map +1 -1
  213. package/dist/username/link.js +1 -1
  214. package/dist/username/link.js.map +1 -1
  215. package/dist/utils/retry.d.ts +2 -1
  216. package/dist/utils/retry.d.ts.map +1 -1
  217. package/dist/utils/retry.js +2 -1
  218. package/dist/utils/retry.js.map +1 -1
  219. package/docs/ASSURANCE.md +16 -10
  220. package/docs/CLIENT_COMPOSITION.md +3 -0
  221. package/docs/DEVIATIONS.md +32 -61
  222. package/docs/DOCUMENTATION_STANDARDS.md +28 -0
  223. package/docs/ERROR_HANDLING.md +91 -60
  224. package/docs/GETTING_STARTED.md +27 -1
  225. package/docs/INTERFACES.md +5 -0
  226. package/docs/PACKAGE_SURFACE.md +1 -0
  227. package/docs/PROTOCOL_POLICY.md +6 -0
  228. package/docs/RECIPES.md +9 -0
  229. package/docs/SECURITY.md +6 -0
  230. package/encoding/README.md +1 -0
  231. package/files/README.md +1 -0
  232. package/groups/README.md +1 -0
  233. package/keys/README.md +2 -0
  234. package/local/store/README.md +2 -0
  235. package/local/store/expo/README.md +2 -0
  236. package/local/store/memory/README.md +2 -0
  237. package/local/store/node/README.md +1 -0
  238. package/local/store/react-native/README.md +2 -0
  239. package/local/store/web/README.md +1 -0
  240. package/local/vault/README.md +1 -0
  241. package/media/README.md +2 -0
  242. package/package.json +4 -2
  243. package/profile/README.md +1 -0
  244. package/remote/README.md +6 -0
  245. package/remote/object-store/README.md +1 -0
  246. package/remote/object-store/convex-r2/README.md +2 -0
  247. package/remote/object-store/s3/README.md +1 -0
  248. package/remote/relay/README.md +2 -0
  249. package/remote/relay/convex/README.md +1 -0
  250. package/remote/relay/convex/component/README.md +29 -14
  251. package/remote/relay/memory/README.md +2 -0
  252. package/safety/README.md +1 -0
  253. package/scripts/oe-groups.mjs +5 -1
  254. package/sealed-sender/README.md +1 -0
  255. package/types/README.md +1 -0
  256. package/username/README.md +1 -0
  257. package/utils/README.md +1 -0
  258. package/zk/README.md +1 -0
  259. package/dist/client/sealed-sender-ops.d.ts.map +0 -1
  260. package/dist/client/sealed-sender-ops.js +0 -203
  261. package/dist/client/sealed-sender-ops.js.map +0 -1
  262. package/dist/internal/protocol/sealed-sender/decryption-v2.d.ts +0 -46
  263. package/dist/internal/protocol/sealed-sender/decryption-v2.d.ts.map +0 -1
  264. package/dist/internal/protocol/sealed-sender/decryption-v2.js +0 -198
  265. package/dist/internal/protocol/sealed-sender/decryption-v2.js.map +0 -1
  266. package/dist/internal/protocol/sealed-sender/encryption-v2.d.ts +0 -56
  267. package/dist/internal/protocol/sealed-sender/encryption-v2.d.ts.map +0 -1
  268. package/dist/internal/protocol/sealed-sender/encryption-v2.js +0 -163
  269. package/dist/internal/protocol/sealed-sender/encryption-v2.js.map +0 -1
  270. package/dist/internal/protocol/sealed-sender/v2-binary.d.ts.map +0 -1
  271. package/dist/internal/protocol/sealed-sender/v2-binary.js.map +0 -1
  272. package/dist/internal/protocol/sealed-sender/v2-helpers.d.ts.map +0 -1
  273. package/dist/internal/protocol/sealed-sender/v2-helpers.js.map +0 -1
@@ -142,6 +142,7 @@ state, retry message records, and recovery helpers.
142
142
 
143
143
  ## Composition
144
144
 
145
+ <!-- doc-snippet:skip requires-external-context -->
145
146
  ```ts
146
147
  import { SignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
147
148
  import { ExpoSignalProtocolStore } from '@open-e2ee/signal-protocol-sdk/local/store/expo';
@@ -169,6 +170,7 @@ An `ISignalProtocolLocalStore` implementation must preserve:
169
170
 
170
171
  The current persisted session record shape is version `4`:
171
172
 
173
+ <!-- doc-snippet:skip requires-external-context -->
172
174
  ```ts
173
175
  interface SessionRecord {
174
176
  currentSession: SessionState | null;
@@ -18,6 +18,7 @@ Compose the exported table definitions into the application schema, configure
18
18
  the database bindings once during bootstrap, and apply the database key before
19
19
  the first query:
20
20
 
21
+ <!-- doc-snippet:skip requires-external-context -->
21
22
  ```ts
22
23
  import {
23
24
  configureSignalProtocolExpoDbBindings,
@@ -65,6 +66,7 @@ Do not back these tables up to a server or sync them between devices.
65
66
 
66
67
  ## Client usage
67
68
 
69
+ <!-- doc-snippet:skip requires-external-context -->
68
70
  ```ts
69
71
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
70
72
  import { expoStore } from "@open-e2ee/signal-protocol-sdk/local/store/expo";
@@ -14,6 +14,7 @@ security or persistence boundary.
14
14
 
15
15
  ## Usage
16
16
 
17
+ <!-- doc-snippet:run memory-store-client expect="" -->
17
18
  ```ts
18
19
  // Real protocol and cryptography; simulated in-memory infrastructure.
19
20
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
@@ -33,6 +34,7 @@ application discards the adapter. Never use this adapter for production accounts
33
34
  Failure mode is opt-in. A seed and cadence replay the same failing writes, or
34
35
  you can target the next named store operation:
35
36
 
37
+ <!-- doc-snippet:run memory-store-failure-injection expect="" -->
36
38
  ```ts
37
39
  // Real protocol and cryptography; simulated in-memory infrastructure.
38
40
  import {
@@ -20,6 +20,7 @@ boundary while allowing each deployment to choose an explicit data directory.
20
20
 
21
21
  ## Usage
22
22
 
23
+ <!-- doc-snippet:skip requires-external-context -->
23
24
  ```ts
24
25
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
25
26
  import { nodeStore } from "@open-e2ee/signal-protocol-sdk/local/store/node";
@@ -11,6 +11,7 @@ needed for trust, session, and one-time-prekey transitions.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
16
17
  import {
@@ -40,6 +41,7 @@ your application supplies. The package therefore exports a
40
41
  backend-conformance kit. Run it against your backend from your application's
41
42
  own tests:
42
43
 
44
+ <!-- doc-snippet:skip requires-external-context -->
43
45
  ```ts
44
46
  import {
45
47
  assertBackendConformance,
@@ -11,6 +11,7 @@ the browser-origin threat model explicit.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
16
17
  import { indexedDbStore } from "@open-e2ee/signal-protocol-sdk/local/store/web";
@@ -13,6 +13,7 @@ platform keychain.
13
13
 
14
14
  ## Expo usage
15
15
 
16
+ <!-- doc-snippet:skip requires-external-context -->
16
17
  ```ts
17
18
  import { ExpoSecureStoreSignalProtocolSecretVault } from "@open-e2ee/signal-protocol-sdk/local/vault/expo-secure-store";
18
19
 
package/media/README.md CHANGED
@@ -18,6 +18,7 @@ The remote object store never receives the media key or plaintext.
18
18
 
19
19
  ## Upload and send
20
20
 
21
+ <!-- doc-snippet:skip requires-external-context -->
21
22
  ```ts
22
23
  import {
23
24
  createMediaAttachmentMessage,
@@ -43,6 +44,7 @@ await signal.send(
43
44
 
44
45
  ## Receive and open
45
46
 
47
+ <!-- doc-snippet:skip requires-external-context -->
46
48
  ```ts
47
49
  import {
48
50
  parseMediaAttachmentMessage,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "0.3.0",
3
+ "version": "1.0.0",
4
4
  "description": "Signal Protocol E2EE SDK for TypeScript — Expo, React Native, browser, and Node. Post-quantum PQXDH and Double Ratchet.",
5
5
  "keywords": [
6
6
  "open-e2ee",
@@ -353,7 +353,8 @@
353
353
  "build:fix-esm": "node ./scripts/fix-esm-specifiers.mjs ./dist",
354
354
  "clean": "rm -rf dist",
355
355
  "typecheck": "tsc --noEmit -p tsconfig.build.json",
356
- "docs:api": "npx -y -p typedoc@0.28 -p typedoc-plugin-markdown@4 -p typescript@5.8 typedoc && node ./scripts/normalize-api-doc-paths.mjs",
356
+ "docs:api": "npx -y -p typedoc@0.28.20 -p typedoc-plugin-markdown@4.12.0 -p typescript@5.8.3 typedoc && node ./scripts/normalize-api-doc-paths.mjs",
357
+ "docs:api:check": "npm run docs:api && git diff --exit-code -- docs/api && test -z \"$(git ls-files --others --exclude-standard docs/api)\"",
357
358
  "prepare": "npm run build",
358
359
  "prepublishOnly": "npm run build"
359
360
  },
@@ -435,6 +436,7 @@
435
436
  "devDependencies": {
436
437
  "@convex-dev/r2": "^0.10.2",
437
438
  "@convex-dev/rate-limiter": "^0.3.2",
439
+ "@swc/core": "^1.15.43",
438
440
  "@types/async-lock": "^1.4.0",
439
441
  "@types/node": "^22.0.0",
440
442
  "@types/react": "^19.0.0",
package/profile/README.md CHANGED
@@ -12,6 +12,7 @@ encrypted fields and does not receive those keys.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import {
17
18
  decryptProfileName,
package/remote/README.md CHANGED
@@ -29,6 +29,7 @@ replaceable and prevent them from owning private keys or plaintext.
29
29
 
30
30
  ## Composition
31
31
 
32
+ <!-- doc-snippet:skip requires-production-adapters -->
32
33
  ```ts
33
34
  import { SignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
34
35
  import {
@@ -95,6 +96,7 @@ application installs, mounts, and configures `@convex-dev/r2`, owns the R2
95
96
  bucket and credentials, and exposes authenticated app-owned functions for
96
97
  create, download, completion, and deletion.
97
98
 
99
+ <!-- doc-snippet:skip requires-external-context -->
98
100
  ```ts
99
101
  import { SignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
100
102
  import { convexR2ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2";
@@ -118,6 +120,7 @@ time-sensitive credentials or await provider metadata. The functions
118
120
  The optional server entry point removes repetitive broker plumbing without
119
121
  taking ownership away from the application:
120
122
 
123
+ <!-- doc-snippet:skip requires-external-context -->
121
124
  ```ts
122
125
  // convex/signalObjectStore.ts
123
126
  import { R2 } from "@convex-dev/r2";
@@ -174,6 +177,7 @@ on that backend. The broker follows the same identity contract: it receives a
174
177
  retry-stable `requestId`, reserves the private provider key, and returns the
175
178
  canonical `objectId`.
176
179
 
180
+ <!-- doc-snippet:skip requires-external-context -->
177
181
  ```ts
178
182
  import { s3ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/s3";
179
183
 
@@ -194,7 +198,9 @@ needed to authorize and construct short-lived operations.
194
198
 
195
199
  Use `InMemorySignalProtocolRelayServer` when multiple clients need a shared in-memory relay:
196
200
 
201
+ <!-- doc-snippet:run remote-shared-memory-relay expect="" -->
197
202
  ```ts
203
+ // Real protocol and cryptography; simulated in-memory infrastructure.
198
204
  import { SignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
199
205
  import { InMemorySignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
200
206
  import { InMemorySignalProtocolStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
@@ -18,6 +18,7 @@ retry-stable requestId -> canonical objectId -> private provider key
18
18
 
19
19
  ## Custom broker usage
20
20
 
21
+ <!-- doc-snippet:skip requires-external-context -->
21
22
  ```ts
22
23
  import type {
23
24
  SignalProtocolRemoteObjectStore,
@@ -13,6 +13,7 @@ component ownership into the SDK.
13
13
 
14
14
  ## Client usage
15
15
 
16
+ <!-- doc-snippet:skip requires-external-context -->
16
17
  ```ts
17
18
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
18
19
  import { convexR2ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/convex-r2";
@@ -40,6 +41,7 @@ by `ConvexR2ObjectStoreApi`.
40
41
  The server-only subpath supplies validators and broker mechanics while keeping
41
42
  authorization and persistence in application callbacks:
42
43
 
44
+ <!-- doc-snippet:skip requires-external-context -->
43
45
  ```ts
44
46
  import { R2 } from "@convex-dev/r2";
45
47
  import {
@@ -11,6 +11,7 @@ returned by that backend.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import { s3ObjectStore } from "@open-e2ee/signal-protocol-sdk/remote/object-store/s3";
16
17
 
@@ -13,7 +13,9 @@ plaintext ownership to the backend.
13
13
 
14
14
  ## Local usage
15
15
 
16
+ <!-- doc-snippet:run relay-memory-client expect="" -->
16
17
  ```ts
18
+ // Real protocol and cryptography; simulated in-memory infrastructure.
17
19
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
18
20
  import { inMemoryStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
19
21
  import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
@@ -21,6 +21,7 @@ functions, retention policy, and operational controls.
21
21
  Organize the application functions under one generated module namespace, then
22
22
  pass that namespace directly:
23
23
 
24
+ <!-- doc-snippet:skip requires-external-context -->
24
25
  ```ts
25
26
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
26
27
  import {
@@ -16,6 +16,7 @@ public wrappers.
16
16
 
17
17
  Mount the component in the app's Convex configuration:
18
18
 
19
+ <!-- doc-snippet:skip requires-external-context -->
19
20
  ```ts
20
21
  // convex/convex.config.ts
21
22
  import { defineApp } from 'convex/server';
@@ -89,6 +90,7 @@ O(versions × state size) per group.
89
90
  Create the wrapper once with the mounted component reference and the app's
90
91
  authentication hook:
91
92
 
93
+ <!-- doc-snippet:skip requires-external-context -->
92
94
  ```ts
93
95
  // convex/relayBackend.ts
94
96
  import { components } from './_generated/api';
@@ -113,6 +115,7 @@ export const signalRelay = defineConvexSignalProtocolBackend(
113
115
  The relay reads these functions through `api.signal`, so the modules must live
114
116
  inside that namespace rather than at the top of `convex/`:
115
117
 
118
+ <!-- doc-snippet:skip requires-external-context -->
116
119
  ```ts
117
120
  // convex/signal/groups.ts
118
121
  import { signalRelay } from '../relayBackend';
@@ -127,6 +130,7 @@ export const {
127
130
  } = signalRelay.groups;
128
131
  ```
129
132
 
133
+ <!-- doc-snippet:skip requires-external-context -->
130
134
  ```ts
131
135
  // convex/signal/zkAuth.ts
132
136
  import { signalRelay } from '../relayBackend';
@@ -139,6 +143,7 @@ export const {
139
143
 
140
144
  Mount the remaining relay namespaces alongside those group modules:
141
145
 
146
+ <!-- doc-snippet:skip requires-external-context -->
142
147
  ```ts
143
148
  // convex/signal/messages.ts
144
149
  import { signalRelay } from '../relayBackend';
@@ -147,7 +152,6 @@ export const {
147
152
  getPendingMessages,
148
153
  markDelivered,
149
154
  getActiveDevices,
150
- sendUnidentified,
151
155
  sendMultiRecipientUnidentified,
152
156
  sendRetryRequest,
153
157
  getPendingRetryRequests,
@@ -155,6 +159,7 @@ export const {
155
159
  } = signalRelay.messages;
156
160
  ```
157
161
 
162
+ <!-- doc-snippet:skip requires-external-context -->
158
163
  ```ts
159
164
  // convex/signal/devices.ts
160
165
  import { signalRelay } from '../relayBackend';
@@ -168,6 +173,7 @@ export const {
168
173
  } = signalRelay.devices;
169
174
  ```
170
175
 
176
+ <!-- doc-snippet:skip requires-external-context -->
171
177
  ```ts
172
178
  // convex/signal/keys.ts
173
179
  import { signalRelay } from '../relayBackend';
@@ -185,12 +191,14 @@ export const {
185
191
  } = signalRelay.keys;
186
192
  ```
187
193
 
194
+ <!-- doc-snippet:skip requires-external-context -->
188
195
  ```ts
189
196
  // convex/signal/certificates.ts
190
197
  import { signalRelay } from '../relayBackend';
191
198
  export const { issueSenderCertificate } = signalRelay.certificates;
192
199
  ```
193
200
 
201
+ <!-- doc-snippet:skip requires-external-context -->
194
202
  ```ts
195
203
  // convex/signal/provisioning.ts
196
204
  import { signalRelay } from '../relayBackend';
@@ -223,8 +231,8 @@ issuance also resolves identity. Group wrappers pass client arguments through
223
231
  untouched because group reads and writes authenticate membership solely through
224
232
  the supplied zero-knowledge presentation.
225
233
 
226
- `sendUnidentified` and `sendMultiRecipientUnidentified` are the deliberate
227
- exception: those sealed-sender paths do **not** call `identify`. They authorize
234
+ `sendMultiRecipientUnidentified` is the deliberate exception: this
235
+ sealed-sender path does **not** call `identify`. It authorizes
228
236
  the bearer request with the target's unidentified-access key or verified group
229
237
  send material, which keeps delivery available without an authenticated
230
238
  application session. Rejections carry structured `ConvexError` data. The relay
@@ -321,8 +329,8 @@ Add `--prod` for the default production deployment or
321
329
  - generates a cryptographically random 32-byte seed only when the secret is
322
330
  absent
323
331
  - writes the seed to the selected Convex deployment through stdin
324
- - prints two labelled base64 roots: the serialized group trust root and the
325
- Ed25519 sender-certificate root
332
+ - prints the serialized group trust root, the Ed25519 sender-certificate root,
333
+ and the sender-certificate relay scope as labeled base64 values
326
334
 
327
335
  Pin both in the client build. See
328
336
  [Sender certificate trust root](#sender-certificate-trust-root) for where each
@@ -341,18 +349,21 @@ from the group signing key by distinct KDF labels
341
349
  (`open-e2ee:sealed-sender:root:v1` / `:server:v1`). Clients verify inbound
342
350
  sealed-sender certificates against the matching Ed25519 **root** public key.
343
351
 
344
- `oe-groups trust-root` prints both roots, labelled:
352
+ `oe-groups trust-root` prints both roots, labeled:
345
353
 
346
354
  ```
347
355
  group trust root: <base64>
348
356
  sealed sender trust root: <base64>
357
+ sealed sender relay scope: <base64>
349
358
  ```
350
359
 
351
360
  The two roots go in different places and are not interchangeable. The group
352
361
  trust root goes into the group configuration, and the sealed-sender root into
353
- `sealedSender.trustRoots` in the client build. Pin both at build time. Never
354
- fetch either from a relay at runtime, because a relay that chooses its own
355
- validation root can mint certificates for any sender.
362
+ `sealedSender.trustRoots` in the client build. Put the matching relay scope into
363
+ `sealedSender.relayScopeId`, and configure the operator-owned issuer revocation
364
+ list in `sealedSender.revokedIssuerKeyIds`. Pin these values at build time.
365
+ Never fetch them from a relay at runtime, because a relay that chooses its own
366
+ validation policy can mint certificates for any sender.
356
367
 
357
368
  The component derives both from the same deployment secret, so rotating
358
369
  `OE_GROUPS_SERVER_SECRET` rotates both and strands clients pinned to either
@@ -442,8 +453,12 @@ The component cannot do it while its identity has no device field.
442
453
 
443
454
  ## Profile-key issuance threat model
444
455
 
445
- `issueProfileKeyCredentialMutation` receives the raw 32-byte profile key. The
446
- group server therefore sees the plaintext profile key at issuance time. The
447
- credential proof hides it in later group presentations, but issuance in this
448
- credential layer is not blinded. Blinded issuance is a future credential-layer
449
- candidate and is explicitly outside this component's scope.
456
+ `issueProfileKeyCredentialMutation` receives a 160-byte blinded request bound
457
+ to the authenticated ACI. The group server sees the ACI and redemption window,
458
+ but it does not receive the raw 32-byte profile key or the client's ephemeral
459
+ blinding secret. The client unblinds and verifies the response before it uses
460
+ the credential in a group presentation.
461
+
462
+ `setUnidentifiedAccessKeyMutation` is a separate delivery-authorization seam.
463
+ It receives only the 16-byte access key that the client derives from its
464
+ profile key. Credential issuance does not derive or register that access key.
@@ -14,6 +14,7 @@ authorization or durability boundary.
14
14
 
15
15
  ## Usage
16
16
 
17
+ <!-- doc-snippet:run memory-relay-client expect="" -->
17
18
  ```ts
18
19
  // Real protocol and cryptography; simulated in-memory infrastructure.
19
20
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
@@ -38,6 +39,7 @@ abuse, or deliver durably. Never use it in production.
38
39
  Failure mode is opt-in and seeded. The default `inMemoryRelay()` remains the
39
40
  deterministic happy path:
40
41
 
42
+ <!-- doc-snippet:run memory-relay-failure-injection expect="" -->
41
43
  ```ts
42
44
  // Real protocol and cryptography; simulated in-memory infrastructure.
43
45
  import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
package/safety/README.md CHANGED
@@ -12,6 +12,7 @@ decision.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import { generateCompositeSafetyNumber } from "@open-e2ee/signal-protocol-sdk/safety";
17
18
 
@@ -94,7 +94,7 @@ async function printTrustRoot(args) {
94
94
  const [
95
95
  { generateServerSecretParams, getServerPublicParams },
96
96
  { encodeGroupTrustRoot },
97
- { deriveSealedSenderRootPublicKey },
97
+ { deriveSealedSenderRootPublicKey, deriveSealedSenderScopeId },
98
98
  ] = await Promise.all([
99
99
  // pathToFileURL: dynamic import of a bare absolute path fails on
100
100
  // Windows, where the ESM loader requires a file:// URL.
@@ -136,6 +136,7 @@ async function printTrustRoot(args) {
136
136
  const sealedSenderRoot = await deriveSealedSenderRootPublicKey(
137
137
  secretParams.signingKeyPair.signingKey
138
138
  );
139
+ const sealedSenderScope = await deriveSealedSenderScopeId(sealedSenderRoot);
139
140
 
140
141
  // Two independently pinned roots, printed with labels because they go to
141
142
  // different places in the client build and are not interchangeable.
@@ -145,6 +146,9 @@ async function printTrustRoot(args) {
145
146
  process.stdout.write(
146
147
  `sealed sender trust root: ${Buffer.from(sealedSenderRoot).toString('base64')}\n`
147
148
  );
149
+ process.stdout.write(
150
+ `sealed sender relay scope: ${Buffer.from(sealedSenderScope).toString('base64')}\n`
151
+ );
148
152
  }
149
153
 
150
154
  const [command, ...args] = process.argv.slice(2);
@@ -12,6 +12,7 @@ contract.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import {
17
18
  ACCESS_KEY_BYTES,
package/types/README.md CHANGED
@@ -12,6 +12,7 @@ contracts they validate.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import type {
17
18
  ISignalProtocolLocalStore,
@@ -11,6 +11,7 @@ helps applications avoid treating display text as a stable account identifier.
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import {
16
17
  formatUsername,
package/utils/README.md CHANGED
@@ -11,6 +11,7 @@ internals.
11
11
 
12
12
  ## Retry usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import {
16
17
  isRetryableError,
package/zk/README.md CHANGED
@@ -12,6 +12,7 @@ group secrets and profile keys on the service.
12
12
 
13
13
  ## Usage
14
14
 
15
+ <!-- doc-snippet:skip requires-external-context -->
15
16
  ```ts
16
17
  import {
17
18
  computeProfileKeyVersion,
@@ -1 +0,0 @@
1
- {"version":3,"file":"sealed-sender-ops.d.ts","sourceRoot":"","sources":["../../client/sealed-sender-ops.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAA+B,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAEtE,OAAO,EACL,uBAAuB,EAGxB,MAAM,0CAA0C,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,CAAC;AACV,wBAAsB,WAAW,CAC/B,gBAAgB,EAAE,MAAM,EACxB,uBAAuB,EAAE,MAAM,EAC/B,qBAAqB,EAAE,UAAU,EACjC,uBAAuB,EAAE,UAAU,EACnC,OAAO,EAAE,kBAAkB,EAC3B,eAAe,CAAC,EAAE,OAAO,EACzB,WAAW,CAAC,EAAE,uBAAuB,GACpC,OAAO,CAAC,MAAM,CAAC,CAkCjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,sBAAsB,EAAE,MAAM,EAC9B,wBAAwB,EAAE,UAAU,EACpC,aAAa,EAAE,MAAM,EACrB,iBAAiB,EAAE,MAAM,EACzB,MAAM,EAAE,kBAAkB,EAC1B,cAAc,CAAC,EAAE,OAAO,GACvB,OAAO,CAAC;IACT,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,WAAW,EAAE,uBAAuB,CAAC;CACtC,CAAC,CAgED;AA8ED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,QAAQ,EAC1B,QAAQ,EAAE;IACR,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,WAAW,EAAE,uBAAuB,CAAC;CACtC,GACA,QAAQ,CAQV;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,uBAAuB,GACnC,QAAQ,CAAC,aAAa,CAAC,CAUzB"}