@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
package/ADAPTERS.md CHANGED
@@ -67,7 +67,9 @@ functions retain authentication, authorization, and persistence.
67
67
 
68
68
  ### Minimal local client
69
69
 
70
+ <!-- doc-snippet:run adapters-local-client expect="" -->
70
71
  ```ts
72
+ // Real protocol and cryptography; simulated in-memory infrastructure.
71
73
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
72
74
  import { inMemoryStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
73
75
 
@@ -79,6 +81,7 @@ const signal = await createSignalProtocolClient({
79
81
 
80
82
  ### Production client
81
83
 
84
+ <!-- doc-snippet:skip requires-production-adapters -->
82
85
  ```ts
83
86
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
84
87
  import {
@@ -110,7 +113,9 @@ database and SQLCipher bootstrap.
110
113
 
111
114
  ### Local development with a shared relay
112
115
 
116
+ <!-- doc-snippet:run adapters-shared-relay expect="" -->
113
117
  ```ts
118
+ // Real protocol and cryptography; simulated in-memory infrastructure.
114
119
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
115
120
  import { inMemoryRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/memory";
116
121
  import { inMemoryStore } from "@open-e2ee/signal-protocol-sdk/local/store/memory";
@@ -160,6 +165,7 @@ Prefer these composition patterns:
160
165
 
161
166
  Use the public interfaces:
162
167
 
168
+ <!-- doc-snippet:skip requires-external-context -->
163
169
  ```ts
164
170
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
165
171
  import type { ISignalProtocolRelayServer } from "@open-e2ee/signal-protocol-sdk/remote/relay";
@@ -169,6 +175,7 @@ import type { ISignalProtocolLocalStore } from "@open-e2ee/signal-protocol-sdk/l
169
175
 
170
176
  Then compose them through `createSignalProtocolClient()`:
171
177
 
178
+ <!-- doc-snippet:skip requires-external-context -->
172
179
  ```ts
173
180
  const signal = await createSignalProtocolClient({
174
181
  identity: { userId },
package/ARCHITECTURE.md CHANGED
@@ -56,6 +56,7 @@ modify the code.
56
56
 
57
57
  The root package is core-only:
58
58
 
59
+ <!-- doc-snippet:skip requires-external-context -->
59
60
  ```ts
60
61
  import {
61
62
  SignalProtocolClient,
@@ -152,6 +153,7 @@ This boundary prevents lower protocol/session layers from depending on the clien
152
153
 
153
154
  Application code should prefer:
154
155
 
156
+ <!-- doc-snippet:skip requires-external-context -->
155
157
  ```ts
156
158
  await createSignalProtocolClient({
157
159
  identity: { userId },
package/CHANGELOG.md CHANGED
@@ -1,5 +1,96 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.0.0
4
+
5
+ - **Hosted Relay supports data-only push wake hints across Expo, APNs, FCM,
6
+ and Web Push.** The SDK registers one destination for the authenticated
7
+ device and derives no account, device, scope, or generation identifiers from
8
+ application input. A wake starts an authenticated durable-mailbox pull.
9
+ The SDK acknowledges only envelopes that it processes successfully, and the
10
+ same pull remains available when push delivery is unavailable.
11
+
12
+ - **Hosted Relay now supports provider migration, recovery progress, and
13
+ managed device linking.** Migration assertions use the existing purpose-aware
14
+ identity callback with typed source and target roles. Recovery reports typed
15
+ phases while Relay remains the account authority. Managed linking requires a
16
+ provisioned account identity. It also requires distinct active and new
17
+ device-auth keys. It sends no ratchet, sender-key, skipped-key, or outbox
18
+ state.
19
+
20
+ - **Breaking: sends use a durable exact-ciphertext outbox and always return a
21
+ logical-send identifier.** `SendResult.clientMessageId` is required. The SDK
22
+ generates it when `SendOptions.clientMessageId` is absent, exposes it on send
23
+ errors through `isOutgoingMessageError`, and replays the persisted encrypted
24
+ transmission after an unknown Relay result. Receivers retain processed Relay
25
+ envelope identifiers for 30 days and acknowledge duplicates without running
26
+ protocol decryption again. Automatic sender-key rotation also persists its
27
+ pairwise distribution messages before group transport. Custom
28
+ `ISignalProtocolLocalStore` implementations must now implement
29
+ `deleteMetadata` for bounded outbox and deduplication retention.
30
+
31
+ - **Breaking: linked-device backup format 2 transfers account identity only.**
32
+ A linked device generates fresh prekeys and establishes independent sessions.
33
+ The SDK rejects old or extended backup shapes that carry prekeys, ratchet
34
+ sessions, sender-key state, message state, or outbox state.
35
+
36
+ - **Profile-key credential issuance is blinded.** The authenticated issuer
37
+ receives an ACI-bound blinded request, not the raw profile key. The client
38
+ unblinds and verifies the response before it creates a group presentation.
39
+
40
+ - **Breaking: sealed-sender delivery now uses one multi-recipient wire format
41
+ for direct and group sends.** The direct path supports one recipient through
42
+ the same format, and the SDK rejects the retired V1 wire format. Hosted Relay
43
+ adapters no longer implement the V1 send method. `preferred` delivery falls
44
+ back to identified delivery only after an anonymous authorization rejection;
45
+ other anonymous-delivery failures do not change the privacy route.
46
+
47
+ ## 0.4.0
48
+
49
+ - **Breaking: sender certificates now bind to Relay scope and issuer
50
+ validity.** The signed sender certificate requires an opaque 16-byte scope.
51
+ The signed server certificate requires its validity interval. Recipients
52
+ reject the old certificate shape. The new hosted bootstrap accepts a
53
+ publishable key and identity assertion callback. It then uses the account,
54
+ device, and scope bindings that Relay returns. Identified delivery does not
55
+ require a sender certificate.
56
+
57
+ - **Hosted Relay bootstrap now registers a complete EC and ML-KEM prekey
58
+ inventory.** The SDK creates and stores signed, last-resort, and one-time
59
+ prekeys before bootstrap. It sends only public material. Exact retries reuse
60
+ the original operation and public registration snapshot, so a restarted
61
+ client cannot publish an old one-time prekey as a new registration.
62
+
63
+ - **The README now provides a runnable encrypted round trip and a current demo.**
64
+ The quickstart exercises two SDK clients through the in-memory relay. The new
65
+ recording shows the same two-device and relay flow as the live desktop and
66
+ mobile demo.
67
+
68
+ - **Error-surface checks reject unresolved codes and cover media attachment
69
+ codes.** The analyser now reports forwarded code arguments in CI.
70
+ It also checks every `MediaAttachmentErrorCode` value.
71
+ This release removes `RemoteObjectStoreNotConfigured` because no media
72
+ operation could produce it.
73
+
74
+ - **The retry-request wire surface no longer includes
75
+ `RetryReason.INVALID_MESSAGE`.** No local failure produced it. The incoming
76
+ retry handler did not support it. Malformed ciphertext failures use the supported
77
+ `DECRYPTION_FAILED` recovery path.
78
+
79
+ - **Generated API pages and shipped documentation examples now have source
80
+ gates.** CI regenerates `docs/api` with pinned tool versions. It rejects a
81
+ diff. The snippet runner scans every packaged Markdown file and the internal
82
+ lifecycle docs. It executes every complete example and matches its output.
83
+ For an example that cannot run, it compiles every SDK name against the packed
84
+ package. A renamed or deleted export therefore fails the build in every
85
+ document that names it.
86
+
87
+ An example that previews an unreleased API declares the import paths that do
88
+ not exist yet. The build fails if one of them resolves. Only pseudocode is
89
+ exempt, and the build names each exempt block on its own line.
90
+
91
+ - **The error guide now documents all 33 `EncryptionErrorCode` values.** Its
92
+ session examples also use the current `ProtocolAddress` method signatures.
93
+
3
94
  ## 0.3.0
4
95
 
5
96
  - **Breaking: seven error classes and sixteen `EncryptionErrorCode` members are
@@ -109,7 +200,7 @@
109
200
  whether the operation produced the epoch secret. Braid mode spreads one
110
201
  ML-KEM key agreement across many messages, and until now the chunk counts
111
202
  lived entirely inside the state machine, so a host had no way to show or log
112
- how far a ratchet had travelled. A direct-mode session never raises the
203
+ how far a ratchet had traveled. A direct-mode session never raises the
113
204
  callback. The hook is guarded exactly as `onProtocolSelected` is: a consumer
114
205
  that throws is logged and the protocol path continues.
115
206
 
@@ -176,7 +267,7 @@
176
267
  install one. An epoch advance for receiving alone installs a zeroed send
177
268
  chain key. Pruning writes one over each retired send chain. Deriving from
178
269
  either would key a message from a known constant. No production path reached
179
- that state, so the check is defence in depth.
270
+ that state, so the check is defense in depth.
180
271
 
181
272
  - **The unused SPQR binary header codec is gone.** `serializeSPQRHeaderBinary`
182
273
  and `deserializeSPQRHeaderBinary` emitted an unversioned framing. No
@@ -947,7 +1038,7 @@
947
1038
  matching the `Type` enum of the reference implementation's
948
1039
  `UnidentifiedSenderMessage.Message` (`PREKEY_MESSAGE`, `MESSAGE`,
949
1040
  `SENDERKEY_MESSAGE`, `PLAINTEXT_CONTENT`), and `SealOptions.groupId` —
950
- encrypted, never populated by the send path — is removed in favour of
1041
+ encrypted, never populated by the send path — is removed in favor of
951
1042
  `contentType`. This is a wire-format change to sealed sender for both V1 and
952
1043
  V2.
953
1044
 
@@ -1028,7 +1119,7 @@
1028
1119
 
1029
1120
  - **Sealed sender envelope parsing is now canonical and validated.** Both the
1030
1121
  V1 and V2 inner-envelope parsers accepted a payload with trailing bytes, an
1031
- unrecognised content-type byte, a truncated varint, or a missing content
1122
+ unrecognized content-type byte, a truncated varint, or a missing content
1032
1123
  hint. Parsing runs after authentication, so none of these was reachable by an
1033
1124
  attacker, but two distinct byte strings could parse to identical content and
1034
1125
  an unknown content type fell through to a routing default. The parsers now
@@ -1202,7 +1293,7 @@
1202
1293
 
1203
1294
  - **Sealed sender can now be enabled.** `oe-groups trust-root` exports the
1204
1295
  Ed25519 sender-certificate root alongside the group trust root, printing both
1205
- labelled (`group trust root:` / `sealed sender trust root:`). Previously only
1296
+ labeled (`group trust root:` / `sealed sender trust root:`). Previously only
1206
1297
  the group root was printed, so there was no supported way to obtain the value
1207
1298
  clients pin in `sealedSender.trustRoots`; inbound sealed-sender validation
1208
1299
  stayed disabled and every send fell back to identified delivery, disclosing
package/README.md CHANGED
@@ -1,64 +1,53 @@
1
- <img src="https://raw.githubusercontent.com/open-e2ee/design/v0.8.0/brand/generated/open-e2ee-mark-adaptive.svg" alt="OpenE2EE" width="72" height="72">
1
+ <img src="https://raw.githubusercontent.com/open-e2ee/design/v0.9.1/brand/generated/open-e2ee-mark-adaptive.svg" alt="OpenE2EE" width="72" height="72">
2
2
 
3
3
  # OpenE2EE Signal Protocol SDK
4
4
 
5
5
  **End-to-end encrypted messaging for TypeScript apps. Signal Protocol, post-quantum by default, runs in Expo.**
6
6
 
7
7
  [![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-2f6f5e)](https://github.com/open-e2ee/signal-protocol-js/blob/main/LICENSE)
8
- [![Types: TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6)](https://www.typescriptlang.org/)
9
8
  [![npm version](https://img.shields.io/npm/v/@open-e2ee/signal-protocol-sdk)](https://www.npmjs.com/package/@open-e2ee/signal-protocol-sdk)
10
- [![native modules: 0](https://img.shields.io/badge/native_modules-0-2f6f5e)](https://github.com/open-e2ee/signal-protocol-js/blob/main/ARCHITECTURE.md)
9
+ [![native crypto: 0](https://img.shields.io/badge/native_crypto-0-2f6f5e)](./ARCHITECTURE.md)
11
10
  [![npm provenance](https://img.shields.io/badge/npm-provenance-2f6f5e)](https://www.npmjs.com/package/@open-e2ee/signal-protocol-sdk#provenance)
12
11
  [![Checks](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml/badge.svg)](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml)
13
- [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/open-e2ee/signal-protocol-js/badge)](https://scorecard.dev/viewer/?uri=github.com/open-e2ee/signal-protocol-js)
14
- [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14043/badge)](https://www.bestpractices.dev/projects/14043)
15
12
 
16
13
  [Website](https://open-e2ee.dev) ·
17
- [Docs](https://docs.open-e2ee.dev) ·
18
- [Quick Start](#quick-start) ·
19
- [Architecture](https://github.com/open-e2ee/signal-protocol-js/blob/main/ARCHITECTURE.md) ·
20
- [Security Model](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/SECURITY.md) ·
21
- [Protocol Policy](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/PROTOCOL_POLICY.md) ·
22
- [Deviations](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md)
14
+ [Documentation](https://docs.open-e2ee.dev) ·
15
+ [Live demo](https://open-e2ee.dev/#demo) ·
16
+ [OpenE2EE Relay](https://open-e2ee.dev/relay) ·
17
+ [API reference](https://docs.open-e2ee.dev/reference/api) ·
18
+ [Security](./SECURITY.md)
23
19
 
24
- ---
20
+ - **One TypeScript package.** Run the same protocol code in Expo, React Native, modern browsers, and Node.
21
+ - **Post-quantum by default.** The default policy requires PQXDH session establishment and the ML-KEM Braid post-quantum ratchet. Required post-quantum operations fail closed.
22
+ - **Messaging primitives included.** Build multi-device messaging, groups, sealed sender, encrypted attachments, and safety-number verification.
23
+ - **Explicit infrastructure boundaries.** Your application owns device-local storage. Supply your own relay adapter or use [OpenE2EE Relay](https://open-e2ee.dev/relay) for managed encrypted delivery. The relay never needs message plaintext or device private keys.
24
+ - **AGPLv3, or a commercial license.** Proprietary applications that cannot meet AGPLv3 obligations can use a [commercial license](./COMMERCIAL.md).
25
25
 
26
- - **Pure TypeScript.** No native modules, no prebuild step, no platform binaries to ship.
27
- - **Runs where your app runs.** Expo, React Native, modern browsers, and Node from one package.
28
- - **Post-quantum by default.** PQXDH and ML-KEM session establishment are on without configuration, and fail closed.
29
- - **Real messaging features.** Multi-device, groups, sealed sender, encrypted attachments, safety numbers.
30
- - **Pluggable storage and relay.** Your application owns the required device-local storage. The relay is an interface, not a hosted service.
31
- - **AGPLv3, or a commercial license.** Building something closed-source? See [COMMERCIAL](https://github.com/open-e2ee/signal-protocol-js/blob/main/COMMERCIAL.md).
26
+ The protocol code ships without a native crypto module or platform crypto binary. The Expo SQLCipher store requires a development build and native project configuration.
32
27
 
33
- *Not affiliated with Signal Messenger.* This package implements the public Signal Protocol specifications independently. [NOTICE](https://github.com/open-e2ee/signal-protocol-js/blob/main/NOTICE) carries the full notice. It is **not wire-compatible with Signal Messenger or libsignal**. Messages, identities, and safety numbers do not interoperate, and [DEVIATIONS](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md) documents every deliberate difference.
28
+ Version `1.0.x`. Public APIs and persisted formats follow semantic versioning.
34
29
 
35
- Version `0.3.x`. Public APIs and persisted formats may change before `1.0`.
30
+ OpenE2EE implements a versioned profile of the published Signal Protocol specifications. It is not affiliated with Signal Messenger and is **not wire-compatible with Signal Messenger or libsignal**. Messages, identities, and safety numbers do not interoperate. Read the [full notice](./NOTICE) and [documented deviations](./docs/DEVIATIONS.md).
36
31
 
37
- ## See it run
32
+ ## See an encrypted round trip
38
33
 
39
- [![Linking a second device on the demo page. The scenario runs, then reports what each device can read. The device that was already there holds both messages. The newly linked device holds only the message sent after it existed.](https://raw.githubusercontent.com/open-e2ee/signal-protocol-js/main/docs/assets/demo/second-device.gif)](https://open-e2ee.dev/demo/#add-a-second-device)
34
+ Press play for the complete four-message run: device setup, session establishment, encrypted relay delivery, and on-device decryption.
40
35
 
41
- The demo links a second device to an account over the real QR handshake. That device does not hold the message sent before it existed. No policy withholds the message. The device cannot read it, because the device's keys did not exist when the sender encrypted it.
36
+ https://github.com/user-attachments/assets/d8002bc3-c037-41b6-8f48-4008f2d49e6c
42
37
 
43
- The recording comes from [open-e2ee.dev/demo](https://open-e2ee.dev/demo). That page runs this package in the browser against the in-memory store and the in-memory relay. The protocol and the cryptography are real, and the adapters simulate the infrastructure in memory. Every scenario there prints the receiving device's own log, unedited.
38
+ The [live demo](https://open-e2ee.dev/#demo) runs two SDK clients against an in-memory relay. On desktop, type a message and inspect the envelope, ratchets, relay mailbox, and decrypted result. On mobile, the same protocol run replays at reading pace. The protocol and cryptography are real. The example simulates infrastructure in memory. Displayed timings exclude network time.
44
39
 
45
40
  ## Install
46
41
 
47
- ```bash
48
- npm install @open-e2ee/signal-protocol-sdk
49
- ```
50
-
51
- Installing straight from the repository also works. The package compiles itself during install, so TypeScript is the only build requirement:
42
+ Requires Node 18 or later for the local example.
52
43
 
53
44
  ```bash
54
- npm install github:open-e2ee/signal-protocol-js
45
+ npm install @open-e2ee/signal-protocol-sdk
55
46
  ```
56
47
 
57
- Adapters declare their runtime requirements as optional peer dependencies, so install the ones your chosen adapters need (for example `expo-sqlite` and `expo-secure-store`, or `convex`).
58
-
59
- ## Quick Start
48
+ ## Run a local encrypted round trip
60
49
 
61
- Two clients, one process, no account and no server. The relay holds the envelope. Only Bob's device turns it back into text.
50
+ Save this as `quickstart.mjs`, then run `node quickstart.mjs`. It uses development-only in-memory adapters so that you can prove the message flow without a backend project.
62
51
 
63
52
  <!-- doc-snippet:run readme-quick-start expect="alice: hello" -->
64
53
  ```ts
@@ -80,97 +69,73 @@ const bob = await createSignalProtocolClient({
80
69
  adapters: { storage: inMemoryStore(), relay },
81
70
  });
82
71
 
83
- await alice.syncToServer();
84
- await bob.syncToServer();
85
-
86
- // Decrypted content reaches your app here, and nowhere else.
87
- bob.registerHook("onMessageDecrypted", async (message) => {
88
- console.log(`${message.senderId}: ${message.content}`); // alice: hello
72
+ const delivered = new Promise((resolve) => {
73
+ bob.registerHook("onMessageDecrypted", async (message) => {
74
+ console.log(`${message.senderId}: ${message.content}`);
75
+ bob.stopRelaySubscription();
76
+ resolve(undefined);
77
+ });
89
78
  });
90
79
 
91
- await alice.send("bob", "hello"); // the relay now holds ciphertext and metadata
92
- bob.startRelaySubscription(); // delivery and local decryption start here
80
+ await alice.send("bob", "hello");
81
+ bob.startRelaySubscription();
82
+ await delivered;
93
83
  ```
94
84
 
95
- Every identifier above is a real export. [This repository's CI](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml) extracts this exact block from this README and runs it against the packed package on every change. The same sequence runs in the engineering repository's automated checks.
96
-
97
- Next: [inspect what the relay actually stored](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/GETTING_STARTED.md), then compose the [Expo + Convex production client](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/CLIENT_COMPOSITION.md).
85
+ Expected output:
98
86
 
99
- ## How it compares
100
-
101
- Measured on 2026-08-03, these figures come from the GitHub API, the npm registry API, and the published package tarballs. Every alternative is a real project that does a real job. The axes below are the ones this SDK sets out to change, not a general quality ranking.
102
-
103
- | | Expo / React Native | Browser | Maintained | Post-quantum | TypeScript-native | Commercial license |
104
- |---|---|---|---|---|---|---|
105
- | **`@open-e2ee/signal-protocol-sdk`** | Yes | Yes | Yes — `0.3.x`, active | Key agreement yes — PQXDH + ML-KEM, default and fails closed. Signatures no — identities are classical Ed25519 | Yes | Yes |
106
- | [`@signalapp/libsignal-client`](https://github.com/signalapp/libsignal) | No — Node native addon; the 0.99.3 tarball ships binaries for macOS, Linux, and Windows only | No | Yes — very active; repo push 2026-07-31 | Key agreement yes | No — Rust core with TypeScript bindings | No (AGPL-3.0 only) |
107
- | [`libsignal-protocol-javascript`](https://github.com/signalapp/libsignal-protocol-javascript) | No | Yes | No — archived, last push 2021-08-04 | No | No — JavaScript | No (GPL-3.0) |
108
- | [`@privacyresearch/libsignal-protocol-typescript`](https://github.com/privacyresearchgroup/libsignal-protocol-typescript) | No documented React Native path | Yes | No — last npm publish 2023-05-06, last repo push 2023-07-18 | No | Yes | No (GPL-3.0) |
109
- | [`ts-mls`](https://github.com/LukaJCB/ts-mls) | Not stated — browsers, Node, and serverless are the documented targets | Yes | Yes — very active; repo push 2026-08-03 | Key agreement and signatures — ML-KEM and ML-DSA-87 ciphersuites | Yes | Not needed (MIT) |
110
-
111
- `ts-mls` implements [MLS (RFC 9420)](https://www.rfc-editor.org/rfc/rfc9420.html). That is a different protocol with different properties. If MLS suits your product, `ts-mls` is a good library, and this table is not an argument against it. Its post-quantum coverage also reaches further than this SDK's.
112
-
113
- `@signalapp/libsignal-client` is the implementation Signal Messenger itself uses. Its README states that it does not support use outside Signal Messenger. Reach for it first when you ship a desktop or server application on Node.
87
+ ```text
88
+ alice: hello
89
+ ```
114
90
 
115
- The longer version of this table, with a paragraph on each project, is at [open-e2ee.dev/compare](https://open-e2ee.dev/compare).
91
+ The client factory creates or loads each device identity. When given a relay, it also publishes the public prekey bundle. `send()` fetches Bob's bundle and starts the required post-quantum session. It then gives ciphertext plus routing metadata to the relay. Bob's subscription retrieves and decrypts the envelope on his device.
116
92
 
117
- ## Trust and verification
93
+ The in-memory store loses identities, sessions, and ratchet state on restart. The in-memory relay has no authentication, authorization, or durable storage. Do not ship either adapter. Continue with the [documentation quickstart](https://docs.open-e2ee.dev/start/quickstart), which explains key custody, relay metadata, prekey replenishment, additional devices, and recovery policy.
118
94
 
119
- Cryptography deserves evidence rather than adjectives, so here is what there is and what there is not.
95
+ ## Move to production storage
120
96
 
121
- **Audit status.** Adversarial AI agents review this SDK continuously. No independent firm audits it. Every change passes an adversarial AI review before it merges, and recurring whole-codebase AI audit passes run against the engineering repository. The [assurance summary](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/ASSURANCE.md) states what that covers and what it does not. The SDK has no independent audit and no audit engagement. Read nothing here as a third-party assurance claim.
97
+ Choose the device-local store for your runtime. Then supply a relay that authenticates each device and implements your product's access policy, or use [OpenE2EE Relay](https://open-e2ee.dev/relay) as the managed delivery path. The SDK does not require the managed service. [Review Relay plans and exact meter definitions.](https://open-e2ee.dev/relay/pricing)
122
98
 
123
- **Security model and protocol policy.** The [security model](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/SECURITY.md) states the threat model and the scope boundary. It also states the storage boundary and the resource limits. The [protocol policy](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/PROTOCOL_POLICY.md) states which protocol modes the SDK supports and which fail closed.
99
+ | Runtime | Storage path | Deployment boundary |
100
+ |---|---|---|
101
+ | Expo | [`expoStore`](./local/store/expo/README.md) | Configure SQLCipher before schema access. Requires a development build; it does not run in Expo Go. |
102
+ | Browser | [`indexedDbStore`](./local/store/web/README.md) | IndexedDB persists encrypted records, but same-origin JavaScript can access the records and their key. Review CSP, XSS, dependencies, and service workers. |
103
+ | Bare React Native | [`reactNativeStore`](./local/store/react-native/README.md) | Provide an atomic, durable key-value backend and run the exported backend conformance kit. |
104
+ | Node | [`nodeStore`](./local/store/node/README.md) | Set an explicit private data directory on a trusted local filesystem. |
124
105
 
125
- **Specifications, pinned by revision.** The implementation follows its own versioned profile based on these published specifications:
106
+ The [adapter guide](./ADAPTERS.md) defines every storage, relay, vault, and object-store boundary. The [client composition guide](./docs/CLIENT_COMPOSITION.md) shows an Expo and Convex integration.
126
107
 
127
- | Specification | Revision |
128
- |---|---|
129
- | [X3DH](https://signal.org/docs/specifications/x3dh/) | Revision 1, 2016-11-04 |
130
- | [PQXDH](https://signal.org/docs/specifications/pqxdh/) | Revision 3, 2023-05-24 (last updated 2024-01-23) |
131
- | [Double Ratchet](https://signal.org/docs/specifications/doubleratchet/) | Revision 4, 2025-11-04 |
132
- | [Sesame](https://signal.org/docs/specifications/sesame/) | Revision 2, 2017-04-14 |
133
- | [ML-KEM Braid](https://signal.org/docs/specifications/mlkembraid/) | Revision 1, 2025-02-21 (last updated 2025-09-26) |
134
- | [FIPS 203 (ML-KEM)](https://csrc.nist.gov/pubs/fips/203/final) | Final, 2024-08-13 |
135
- | [RFC 8032 (Ed25519)](https://www.rfc-editor.org/rfc/rfc8032.html) | — |
108
+ ## Security and assurance
136
109
 
137
- **Not wire-compatible, and specific about why.** This SDK cannot exchange messages or identities with Signal Messenger or `libsignal`. Its safety numbers will never match the ones a Signal Messenger client displays for the same two users. The cryptographic core is the same. The wire profile is deliberately its own.
110
+ The [assurance summary](./docs/ASSURANCE.md) states what the automated checks cover and what the public export does not contain. Public CI rebuilds, type-checks, audits, and runs this README example against the packed package.
138
111
 
139
- Identities are a versioned composite of separate X25519 and Ed25519 keys rather than one Curve25519 key. Signatures are therefore ordinary RFC 8032 Ed25519 rather than XEdDSA. ML-KEM-1024 keys and ciphertexts carry the tag `0x0A`, which differs from the round-3 Kyber1024 tag `0x08`. [DEVIATIONS](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md) is the complete account. It names every difference from the specifications and from `libsignal`, with the reason, the cost, and the file that implements it. The [security model](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/SECURITY.md) holds the threat model boundary.
112
+ JavaScript engines do not provide a machine-level constant-time contract or guaranteed zeroization. The [security model](./docs/SECURITY.md) defines the timing, same-process, storage, and metadata boundaries. The [protocol policy](./docs/PROTOCOL_POLICY.md) defines supported modes and fail-closed behavior.
140
113
 
141
- **Dependencies: 6.** The package has six direct production dependencies: `@noble/ciphers`, `@noble/curves`, `@noble/hashes`, `@noble/post-quantum`, `async-lock`, and `unique-names-generator`. They resolve to 6 packages in total. The only transitive edges run between the `@noble` packages, so the resolved tree adds nothing the list above does not already name. Everything else in the tree is a development or optional peer dependency.
114
+ Report a suspected vulnerability privately through the process in [SECURITY](./SECURITY.md). Do not open a public issue for it.
142
115
 
143
- **Automated checks.** The published repository is a mechanized export of a private engineering repository, through an allowlist. The automated checks live in that engineering repository, and they must pass before the export runs. The [assurance summary](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/ASSURANCE.md) carries the current run figures and explains what the checks cover, what stays unpublished, and why. Every release regenerates those figures from a real run, and no one hand-edits them. The published repository runs its own build, typecheck, and production dependency audit in [CI](https://github.com/open-e2ee/signal-protocol-js/actions/workflows/ci.yml) on every change.
116
+ ## Why developers choose this SDK
144
117
 
145
- **Constant-time posture, honestly.** JavaScript engines offer no machine-level constant-time contract, and this SDK cannot invent one. Selected paths carry best-effort source-level work:
118
+ The SDK gives TypeScript applications one maintained package for required post-quantum session establishment and ratcheting, multi-device messaging, groups, sealed sender, attachments, and safety numbers. It keeps protocol state on the device. Applications can operate a relay adapter or use OpenE2EE Relay for managed delivery.
146
119
 
147
- - a full scan when it compares equal-length MACs and identity bytes
148
- - fixed work on both decapsulation candidates, then a masked choice between them
149
- - equal-work rejection padding on selected replay and authentication paths
120
+ [Compare maintained alternatives and their limits.](https://open-e2ee.dev/product/#how-it-compares)
150
121
 
151
- These are not timing-equivalence proofs. Secret-influenced remainder and compression arithmetic remains. JIT compilation, allocation, garbage collection, and cache effects stay observable. `secureZeroBytes()` overwrites the exact typed array the caller hands it and nothing more. It does not touch copies, strings, or engine temporaries. The threat model does not cover hostile same-process code or a high-assurance co-resident timing adversary, and it says so.
122
+ ## Documentation
152
123
 
153
- **Reporting a vulnerability.** Email security@open-e2ee.dev rather than opening an issue. Acknowledgment within 72 hours, initial assessment within 7 days. [SECURITY.md](https://github.com/open-e2ee/signal-protocol-js/blob/main/SECURITY.md) carries the full policy.
124
+ - [Getting started](./docs/GETTING_STARTED.md): the integration sequence and mental model.
125
+ - [Package surface](./docs/PACKAGE_SURFACE.md): root exports, subpaths, adapters, and core concepts.
126
+ - [Recipes](./docs/RECIPES.md): messaging, multi-device, attachments, and usernames.
127
+ - [Architecture](./ARCHITECTURE.md) and [adapters](./ADAPTERS.md): layer ownership and composition boundaries.
128
+ - [Integration interfaces](./docs/INTERFACES.md): contracts for custom stores, vaults, relays, and object stores.
129
+ - [Error handling](./docs/ERROR_HANDLING.md) and [troubleshooting](./TROUBLESHOOTING.md).
130
+ - [Deviations](./docs/DEVIATIONS.md): differences from the specifications and libsignal, with reasons and costs.
131
+ - [Hosted API reference](https://docs.open-e2ee.dev/reference/api): exported types and methods.
154
132
 
155
- ## Documentation
133
+ ## Help and contributing
156
134
 
157
- Hosted guides, quickstarts per runtime, and concept docs live at
158
- [docs.open-e2ee.dev](https://docs.open-e2ee.dev). The in-repo references below
159
- carry the same version as the code:
160
-
161
- - [Getting Started](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/GETTING_STARTED.md): installation, mental model, first working client.
162
- - [Package Surface](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/PACKAGE_SURFACE.md): root exports, every subpath, adapter implementations, core concepts.
163
- - [Recipes](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/RECIPES.md): message flow, protocol policy, multi-device, attachments, usernames.
164
- - [Client Composition](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/CLIENT_COMPOSITION.md): production composition with Expo and Convex.
165
- - [Architecture](https://github.com/open-e2ee/signal-protocol-js/blob/main/ARCHITECTURE.md) and [Adapters](https://github.com/open-e2ee/signal-protocol-js/blob/main/ADAPTERS.md): layer model and composition boundaries.
166
- - [Integration Interfaces](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/INTERFACES.md): the interfaces to implement for custom storage, vaults, relays, and object stores.
167
- - [Error Handling](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/ERROR_HANDLING.md) and [Troubleshooting](https://github.com/open-e2ee/signal-protocol-js/blob/main/TROUBLESHOOTING.md).
168
- - [E2EE concepts](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/E2EE.md): what changes about your architecture when the relay cannot read.
169
- - [Deviations](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/DEVIATIONS.md): every difference from the Signal Protocol specifications and from `libsignal`, with reasons and costs.
170
- - [API Reference](https://github.com/open-e2ee/signal-protocol-js/blob/main/docs/api/README.md): generated from the exported declarations.
135
+ Open a [bug report](https://github.com/open-e2ee/signal-protocol-js/issues/new?template=bug_report.yml) or send [API and documentation feedback](https://github.com/open-e2ee/signal-protocol-js/issues/new?template=api_feedback.yml). Read [CONTRIBUTING](./CONTRIBUTING.md) before you propose code. Use the private process in [SECURITY](./SECURITY.md) for suspected vulnerabilities.
171
136
 
172
137
  ## License and warranty
173
138
 
174
- Licensed under `AGPL-3.0-or-later`. See [LICENSE](https://github.com/open-e2ee/signal-protocol-js/blob/main/LICENSE). A commercial license covers proprietary products that cannot meet AGPLv3 obligations. See [COMMERCIAL](https://github.com/open-e2ee/signal-protocol-js/blob/main/COMMERCIAL.md) or email licensing@open-e2ee.dev.
139
+ Licensed under AGPLv3 (`AGPL-3.0-or-later`). See [LICENSE](./LICENSE). A [commercial license](./COMMERCIAL.md) covers proprietary products that cannot meet AGPLv3 obligations.
175
140
 
176
- The license provides the software **as is**, without warranties or conditions of any kind. To the extent that applicable law permits, copyright holders and contributors are not liable for damages that arise from its use. Your application must evaluate this SDK against its own requirements. It must also secure its own deployment, storage, authentication, authorization, and operations. This summary does not modify the license. Sections 15 and 16 of the GNU Affero General Public License carry the complete "Disclaimer of Warranty" and "Limitation of Liability" text.
141
+ The license provides the software **as is**, without warranties or conditions of any kind. To the extent that applicable law permits, copyright holders and contributors are not liable for damages that arise from its use. Your application must evaluate the SDK against its requirements and secure its deployment, storage, authentication, authorization, and operations. This summary does not modify the license.
package/SECURITY.md CHANGED
@@ -7,8 +7,8 @@ backports.
7
7
 
8
8
  | Version | Supported |
9
9
  | ------- | ------------------ |
10
- | 0.3.x | :white_check_mark: |
11
- | < 0.3.0 | :x: |
10
+ | 1.0.x | :white_check_mark: |
11
+ | < 1.0.0 | :x: |
12
12
 
13
13
  ## Reporting a Vulnerability
14
14
 
@@ -1,7 +1,7 @@
1
1
  # Third-party notices
2
2
 
3
3
  This file records third-party source distributed with or adapted by the
4
- OpenE2EE SDK. Dependency distributions may contain additional notices.
4
+ OpenE2EE Signal Protocol SDK. Dependency distributions may contain additional notices.
5
5
 
6
6
  ## @noble/post-quantum
7
7
 
@@ -49,6 +49,7 @@ Error occurred?
49
49
 
50
50
  **"Identity key not found - client not initialized"**
51
51
 
52
+ <!-- doc-snippet:illustrative elided-call-arguments -->
52
53
  ```typescript
53
54
  // ❌ Wrong: forgot to initialize
54
55
  const signal = new SignalProtocolClient(); // Don't use constructor directly!
@@ -65,6 +66,7 @@ await signal.encryptMessage(...); // Works!
65
66
 
66
67
  Make sure the prekey bundle is fresh and valid:
67
68
 
69
+ <!-- doc-snippet:skip requires-external-context -->
68
70
  ```typescript
69
71
  // Fetch the latest prekey bundle from server
70
72
  const bundle = await convex.mutation(api.signal.keys.fetchPreKeyBundle, {
@@ -87,6 +89,7 @@ await signal.establishSession(sessionId, bobId, bundle);
87
89
 
88
90
  Session IDs must be in `userId:deviceId` format:
89
91
 
92
+ <!-- doc-snippet:skip requires-external-context -->
90
93
  ```typescript
91
94
  // ❌ Wrong: missing device ID
92
95
  await signal.encryptMessage('bob', 'Hello');
@@ -122,6 +125,7 @@ The protocol handles out-of-order messages automatically via MKSKIPPED. For fail
122
125
 
123
126
  ### Check Client State
124
127
 
128
+ <!-- doc-snippet:skip requires-external-context -->
125
129
  ```typescript
126
130
  // Get encryption statistics
127
131
  const stats = await signal.getStats();
@@ -132,6 +136,7 @@ console.log('OneTime prekeys remaining:', stats.oneTimePreKeysCount);
132
136
 
133
137
  ### Check Session Status
134
138
 
139
+ <!-- doc-snippet:skip requires-external-context -->
135
140
  ```typescript
136
141
  // Check if session exists
137
142
  const hasSession = await signal.hasSession('bob:1');
@@ -140,6 +145,7 @@ console.log('Has session with bob:1:', hasSession);
140
145
 
141
146
  ### Enable Debug Logging
142
147
 
148
+ <!-- doc-snippet:skip requires-external-context -->
143
149
  ```typescript
144
150
  const signal = await SignalProtocolClient.create(userId, {
145
151
  enableDebugLogging: true,
@@ -149,6 +155,7 @@ const signal = await SignalProtocolClient.create(userId, {
149
155
 
150
156
  ### Verify Identity Keys
151
157
 
158
+ <!-- doc-snippet:skip requires-external-context -->
152
159
  ```typescript
153
160
  // Generate the composite safety number from the locally pinned identity.
154
161
  const safetyNumber = await signal.verify(theirUserId);
@@ -11,6 +11,7 @@ second, conflicting source of truth. `SignalProtocolBlockingManager` centralizes
11
11
 
12
12
  ## Usage
13
13
 
14
+ <!-- doc-snippet:skip requires-external-context -->
14
15
  ```ts
15
16
  import {
16
17
  SignalProtocolBlockingManager,
package/client/README.md CHANGED
@@ -15,6 +15,7 @@ Every client needs `storage`. Local use can omit `relay`, and real messaging
15
15
  needs it. `protocol.postQuantum` and `protocol.braid` both default to
16
16
  `'required'`.
17
17
 
18
+ <!-- doc-snippet:skip requires-established-session -->
18
19
  ```ts
19
20
  import { createSignalProtocolClient, ProtocolAddress } from '@open-e2ee/signal-protocol-sdk';
20
21
  import { inMemoryStore } from '@open-e2ee/signal-protocol-sdk/local/store/memory';
@@ -32,6 +33,7 @@ await signal.encryptMessage(bob, 'hello');
32
33
 
33
34
  ### With relay
34
35
 
36
+ <!-- doc-snippet:skip requires-external-context -->
35
37
  ```ts
36
38
  import { createSignalProtocolClient } from '@open-e2ee/signal-protocol-sdk';
37
39
  import { convexRelay, type ConvexSignalProtocolRelayApi } from '@open-e2ee/signal-protocol-sdk/remote/relay/convex';
@@ -65,6 +67,7 @@ database-binding and SQLCipher bootstrap.
65
67
 
66
68
  Use product/security terms at the client seam:
67
69
 
70
+ <!-- doc-snippet:skip requires-external-context -->
68
71
  ```ts
69
72
  await createSignalProtocolClient({
70
73
  identity: { userId },
@@ -77,6 +80,7 @@ await createSignalProtocolClient({
77
80
  `compatible` only for an explicit product decision to support peers that
78
81
  publish no post-quantum material:
79
82
 
83
+ <!-- doc-snippet:skip requires-external-context -->
80
84
  ```ts
81
85
  await createSignalProtocolClient({
82
86
  identity: { userId },
@@ -87,6 +91,7 @@ await createSignalProtocolClient({
87
91
 
88
92
  Use direct SPQR only as an explicit product-reviewed escape hatch:
89
93
 
94
+ <!-- doc-snippet:skip requires-external-context -->
90
95
  ```ts
91
96
  await createSignalProtocolClient({
92
97
  identity: { userId },
@@ -99,6 +104,7 @@ await createSignalProtocolClient({
99
104
 
100
105
  Use typed device addresses instead of string session ids:
101
106
 
107
+ <!-- doc-snippet:skip requires-external-context -->
102
108
  ```ts
103
109
  import { ProtocolAddress } from '@open-e2ee/signal-protocol-sdk';
104
110
 
@@ -111,6 +117,7 @@ const asString = ProtocolAddress.toString(bob);
111
117
 
112
118
  ### Direct session control
113
119
 
120
+ <!-- doc-snippet:skip requires-external-context -->
114
121
  ```ts
115
122
  const bob = ProtocolAddress.create('bob', 1);
116
123
 
@@ -122,6 +129,7 @@ const plaintext = await signal.decryptMessage(bob, ciphertext);
122
129
 
123
130
  ### Multi-device send
124
131
 
132
+ <!-- doc-snippet:skip requires-external-context -->
125
133
  ```ts
126
134
  const result = await signal.send(recipientUserId, 'hello');
127
135
 
@@ -136,6 +144,7 @@ await appMessages.insertOutgoing({
136
144
 
137
145
  ### Server sync
138
146
 
147
+ <!-- doc-snippet:skip requires-external-context -->
139
148
  ```ts
140
149
  // Publish fresh public prekeys and rotate long-lived prekeys on schedule.
141
150
  await signal.syncToServer();
@@ -148,6 +157,7 @@ await signal.rotateKyberPreKey();
148
157
  Use the dedicated headless entry point from a background task after restoring
149
158
  the same application-owned storage and relay boundaries:
150
159
 
160
+ <!-- doc-snippet:skip requires-external-context -->
151
161
  ```ts
152
162
  import { rotateKeysHeadless } from '@open-e2ee/signal-protocol-sdk/client/headless';
153
163