@open-e2ee/signal-protocol-sdk 0.1.0-alpha.3 → 0.1.0-alpha.5

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 (279) hide show
  1. package/CHANGELOG.md +82 -2
  2. package/NOTICE +3 -1
  3. package/README.md +10 -5
  4. package/dist/blocking/types.d.ts +1 -1
  5. package/dist/blocking/types.js +1 -1
  6. package/dist/client/client.d.ts +3 -3
  7. package/dist/client/client.js +4 -4
  8. package/dist/client/client.js.map +1 -1
  9. package/dist/client/compose.d.ts +1 -1
  10. package/dist/client/compose.d.ts.map +1 -1
  11. package/dist/client/config.d.ts +2 -2
  12. package/dist/client/event-hooks.d.ts +1 -1
  13. package/dist/client/headless.d.ts +2 -2
  14. package/dist/client/headless.js +2 -2
  15. package/dist/client/key-rotation-core.d.ts +4 -4
  16. package/dist/client/key-rotation-core.js +11 -11
  17. package/dist/client/key-rotation-core.js.map +1 -1
  18. package/dist/client/media.d.ts +2 -2
  19. package/dist/client/media.js +5 -5
  20. package/dist/client/media.js.map +1 -1
  21. package/dist/client/messages.js +2 -2
  22. package/dist/client/messages.js.map +1 -1
  23. package/dist/client/relay-subscription.js +17 -0
  24. package/dist/client/relay-subscription.js.map +1 -1
  25. package/dist/client/retry.js +1 -1
  26. package/dist/client/retry.js.map +1 -1
  27. package/dist/client/sealed-sender-ops.js +1 -1
  28. package/dist/client/sealed-sender-ops.js.map +1 -1
  29. package/dist/client/sessions.d.ts.map +1 -1
  30. package/dist/client/sessions.js +3 -0
  31. package/dist/client/sessions.js.map +1 -1
  32. package/dist/client/signal-service-cipher.d.ts +5 -1
  33. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  34. package/dist/client/signal-service-cipher.js +19 -14
  35. package/dist/client/signal-service-cipher.js.map +1 -1
  36. package/dist/device/provisioning.d.ts +3 -3
  37. package/dist/device/provisioning.js +2 -2
  38. package/dist/device/provisioning.js.map +1 -1
  39. package/dist/hooks/use-connection-presence.d.ts +2 -2
  40. package/dist/hooks/use-connection-presence.d.ts.map +1 -1
  41. package/dist/hooks/use-connection-presence.js +1 -1
  42. package/dist/hooks/use-group-membership.d.ts +2 -2
  43. package/dist/index.d.ts +2 -2
  44. package/dist/index.js +3 -3
  45. package/dist/index.js.map +1 -1
  46. package/dist/internal/crypto/index.js +1 -1
  47. package/dist/internal/crypto/index.js.map +1 -1
  48. package/dist/internal/crypto/kdf/hkdf.d.ts +1 -1
  49. package/dist/internal/crypto/kdf/hkdf.d.ts.map +1 -1
  50. package/dist/internal/crypto/kdf/hkdf.js +2 -2
  51. package/dist/internal/crypto/kdf/hkdf.js.map +1 -1
  52. package/dist/internal/crypto/key-prefix.d.ts +1 -1
  53. package/dist/internal/crypto/key-prefix.js +1 -1
  54. package/dist/internal/crypto/pq/kyber.d.ts +1 -1
  55. package/dist/internal/crypto/pq/kyber.js +1 -1
  56. package/dist/internal/crypto/symmetric/aes-gcm-siv.d.ts +1 -1
  57. package/dist/internal/crypto/symmetric/aes-gcm-siv.js +1 -1
  58. package/dist/internal/crypto/utils.d.ts +2 -2
  59. package/dist/internal/crypto/utils.js +2 -2
  60. package/dist/internal/encoding/proto/index.js +1 -1
  61. package/dist/internal/encoding/proto/index.js.map +1 -1
  62. package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts +2 -2
  63. package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts.map +1 -1
  64. package/dist/internal/encoding/proto/pq-ratchet-serialize.js +2 -2
  65. package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
  66. package/dist/internal/groups/group-id.d.ts +1 -1
  67. package/dist/internal/groups/group-id.js +1 -1
  68. package/dist/internal/groups/group-id.js.map +1 -1
  69. package/dist/internal/groups-v2/access-control.d.ts +8 -1
  70. package/dist/internal/groups-v2/access-control.d.ts.map +1 -1
  71. package/dist/internal/groups-v2/access-control.js +8 -1
  72. package/dist/internal/groups-v2/access-control.js.map +1 -1
  73. package/dist/internal/groups-v2/change-actions.d.ts +8 -3
  74. package/dist/internal/groups-v2/change-actions.d.ts.map +1 -1
  75. package/dist/internal/groups-v2/change-actions.js +8 -3
  76. package/dist/internal/groups-v2/change-actions.js.map +1 -1
  77. package/dist/internal/groups-v2/index.d.ts +7 -2
  78. package/dist/internal/groups-v2/index.d.ts.map +1 -1
  79. package/dist/internal/groups-v2/index.js.map +1 -1
  80. package/dist/internal/groups-v2/manager.d.ts +4 -2
  81. package/dist/internal/groups-v2/manager.d.ts.map +1 -1
  82. package/dist/internal/groups-v2/manager.js +5 -3
  83. package/dist/internal/groups-v2/manager.js.map +1 -1
  84. package/dist/internal/groups-v2/types.d.ts +10 -3
  85. package/dist/internal/groups-v2/types.d.ts.map +1 -1
  86. package/dist/internal/groups-v2/types.js.map +1 -1
  87. package/dist/internal/manager/manager.d.ts.map +1 -1
  88. package/dist/internal/manager/manager.js +25 -14
  89. package/dist/internal/manager/manager.js.map +1 -1
  90. package/dist/internal/protocol/double-ratchet/chains.d.ts +1 -1
  91. package/dist/internal/protocol/double-ratchet/chains.js +1 -1
  92. package/dist/internal/protocol/double-ratchet/ratchet.d.ts +1 -1
  93. package/dist/internal/protocol/double-ratchet/ratchet.js +1 -1
  94. package/dist/internal/protocol/sealed-sender/decryption.js +2 -2
  95. package/dist/internal/protocol/sealed-sender/decryption.js.map +1 -1
  96. package/dist/internal/protocol/sealed-sender/types.d.ts +1 -1
  97. package/dist/internal/protocol/sealed-sender/types.js +1 -1
  98. package/dist/internal/protocol/sender-keys/index.d.ts +1 -1
  99. package/dist/internal/protocol/sender-keys/manager.d.ts +2 -2
  100. package/dist/internal/protocol/sender-keys/manager.js +3 -3
  101. package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
  102. package/dist/internal/protocol/spqr/index.d.ts +1 -1
  103. package/dist/internal/protocol/spqr/index.js +1 -1
  104. package/dist/internal/protocol/spqr/message.d.ts +1 -1
  105. package/dist/internal/protocol/spqr/message.js +1 -1
  106. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts +3 -3
  107. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
  108. package/dist/internal/protocol/spqr/ml-kem-braid/rs/index.js +2 -2
  109. package/dist/internal/protocol/spqr/ml-kem-braid/rs/index.js.map +1 -1
  110. package/dist/internal/protocol/spqr/ml-kem-braid/rs/lagrange.d.ts +1 -1
  111. package/dist/internal/protocol/spqr/ml-kem-braid/rs/lagrange.js +1 -1
  112. package/dist/internal/protocol/spqr/ml-kem-braid/rs/lagrange.js.map +1 -1
  113. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts +1 -1
  114. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js +1 -1
  115. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js +5 -5
  116. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js.map +1 -1
  117. package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts +1 -1
  118. package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts.map +1 -1
  119. package/dist/internal/protocol/spqr/spqr.d.ts +9 -9
  120. package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
  121. package/dist/internal/protocol/spqr/spqr.js +9 -9
  122. package/dist/internal/protocol/spqr/spqr.js.map +1 -1
  123. package/dist/internal/protocol/triple-ratchet/ratchet.d.ts +1 -1
  124. package/dist/internal/protocol/triple-ratchet/ratchet.js +1 -1
  125. package/dist/internal/protocol/username/generate.d.ts +1 -1
  126. package/dist/internal/protocol/username/generate.js +1 -1
  127. package/dist/internal/protocol/username/hash.d.ts +1 -1
  128. package/dist/internal/protocol/username/hash.js +1 -1
  129. package/dist/internal/protocol/username/link.d.ts +1 -1
  130. package/dist/internal/protocol/username/link.js +1 -1
  131. package/dist/internal/protocol/username/proof.d.ts +1 -1
  132. package/dist/internal/protocol/username/proof.js +1 -1
  133. package/dist/internal/protocol/x3dh/x3dh.js +3 -3
  134. package/dist/internal/protocol/x3dh/x3dh.js.map +1 -1
  135. package/dist/internal/protocol/zk/groups/auth-credential.d.ts +5 -4
  136. package/dist/internal/protocol/zk/groups/auth-credential.d.ts.map +1 -1
  137. package/dist/internal/protocol/zk/groups/auth-credential.js.map +1 -1
  138. package/dist/internal/protocol/zk/groups/client-zk-group-cipher.d.ts +2 -2
  139. package/dist/internal/protocol/zk/groups/client-zk-group-cipher.js +2 -2
  140. package/dist/internal/sesame/device-registry.d.ts +11 -6
  141. package/dist/internal/sesame/device-registry.d.ts.map +1 -1
  142. package/dist/internal/sesame/device-registry.js +11 -7
  143. package/dist/internal/sesame/device-registry.js.map +1 -1
  144. package/dist/internal/sesame/manager.js +1 -1
  145. package/dist/internal/sesame/manager.js.map +1 -1
  146. package/dist/internal/session/cipher.d.ts.map +1 -1
  147. package/dist/internal/session/cipher.js +8 -0
  148. package/dist/internal/session/cipher.js.map +1 -1
  149. package/dist/internal/session/keys.d.ts +1 -1
  150. package/dist/keys/generation.d.ts +4 -3
  151. package/dist/keys/generation.d.ts.map +1 -1
  152. package/dist/keys/generation.js +2 -2
  153. package/dist/keys/generation.js.map +1 -1
  154. package/dist/keys/types.d.ts +1 -1
  155. package/dist/keys/types.d.ts.map +1 -1
  156. package/dist/local/store/expo/adapter.d.ts +3 -3
  157. package/dist/local/store/expo/adapter.js +2 -2
  158. package/dist/local/store/expo/db.js +1 -1
  159. package/dist/local/store/expo/db.js.map +1 -1
  160. package/dist/local/store/expo/index.d.ts +1 -1
  161. package/dist/local/store/expo/models/local-identity.d.ts +1 -1
  162. package/dist/local/store/expo/models/local-identity.js +1 -1
  163. package/dist/local/store/expo/models/sender-key.d.ts +3 -3
  164. package/dist/local/store/expo/models/sender-key.d.ts.map +1 -1
  165. package/dist/local/store/expo/models/sender-key.js +3 -3
  166. package/dist/local/store/expo/models/sender-key.js.map +1 -1
  167. package/dist/local/store/expo/schema.d.ts +1 -1
  168. package/dist/local/store/expo/schema.js +1 -1
  169. package/dist/local/store/expo/secure-store-options.d.ts +1 -1
  170. package/dist/local/store/mock/adapter.d.ts +6 -0
  171. package/dist/local/store/mock/adapter.d.ts.map +1 -1
  172. package/dist/local/store/mock/adapter.js +117 -47
  173. package/dist/local/store/mock/adapter.js.map +1 -1
  174. package/dist/local/store/mock/failures.d.ts +34 -0
  175. package/dist/local/store/mock/failures.d.ts.map +1 -0
  176. package/dist/local/store/mock/failures.js +75 -0
  177. package/dist/local/store/mock/failures.js.map +1 -0
  178. package/dist/local/store/mock/index.d.ts +4 -3
  179. package/dist/local/store/mock/index.d.ts.map +1 -1
  180. package/dist/local/store/mock/index.js +3 -2
  181. package/dist/local/store/mock/index.js.map +1 -1
  182. package/dist/local/store/node/database-key.js +1 -1
  183. package/dist/local/store/react-native/adapter.js +2 -2
  184. package/dist/local/store/react-native/adapter.js.map +1 -1
  185. package/dist/local/store/react-native/storage.d.ts +1 -1
  186. package/dist/local/store/web/adapter.d.ts.map +1 -1
  187. package/dist/local/store/web/adapter.js +14 -2
  188. package/dist/local/store/web/adapter.js.map +1 -1
  189. package/dist/local/vault/index.d.ts +1 -1
  190. package/dist/logger.d.ts +1 -1
  191. package/dist/logger.js +1 -1
  192. package/dist/media/index.d.ts +2 -2
  193. package/dist/media/index.js +2 -2
  194. package/dist/profile/cipher.d.ts +1 -1
  195. package/dist/profile/cipher.js +1 -1
  196. package/dist/profile/contact-state.d.ts +1 -1
  197. package/dist/profile/contact-state.js +1 -1
  198. package/dist/profile/crypto.d.ts +1 -1
  199. package/dist/profile/crypto.js +1 -1
  200. package/dist/profile/profile-key.js +1 -1
  201. package/dist/profile/update-service.d.ts +2 -2
  202. package/dist/profile/update-service.d.ts.map +1 -1
  203. package/dist/remote/object-store/convex-r2/server.d.ts +1 -1
  204. package/dist/remote/relay/convex/index.d.ts +1 -1
  205. package/dist/remote/relay/convex/index.js +1 -1
  206. package/dist/remote/relay/convex/relay.d.ts +2 -2
  207. package/dist/remote/relay/convex/relay.js +2 -2
  208. package/dist/remote/relay/convex/types.d.ts +7 -7
  209. package/dist/remote/relay/convex/types.js +1 -1
  210. package/dist/remote/relay/mock/adapter.d.ts +13 -2
  211. package/dist/remote/relay/mock/adapter.d.ts.map +1 -1
  212. package/dist/remote/relay/mock/adapter.js +165 -51
  213. package/dist/remote/relay/mock/adapter.js.map +1 -1
  214. package/dist/remote/relay/mock/failures.d.ts +57 -0
  215. package/dist/remote/relay/mock/failures.d.ts.map +1 -0
  216. package/dist/remote/relay/mock/failures.js +118 -0
  217. package/dist/remote/relay/mock/failures.js.map +1 -0
  218. package/dist/remote/relay/mock/index.d.ts +4 -3
  219. package/dist/remote/relay/mock/index.d.ts.map +1 -1
  220. package/dist/remote/relay/mock/index.js +4 -3
  221. package/dist/remote/relay/mock/index.js.map +1 -1
  222. package/dist/remote/relay/types.d.ts +1 -1
  223. package/dist/remote/relay/types.js +1 -1
  224. package/dist/safety/protobuf.d.ts +1 -1
  225. package/dist/safety/protobuf.d.ts.map +1 -1
  226. package/dist/types/api.d.ts +6 -6
  227. package/dist/types/errors.d.ts +2 -2
  228. package/dist/types/errors.d.ts.map +1 -1
  229. package/dist/types/errors.js +2 -2
  230. package/dist/types/errors.js.map +1 -1
  231. package/dist/types/protocol-config.d.ts +3 -2
  232. package/dist/types/protocol-config.d.ts.map +1 -1
  233. package/dist/types/protocol-config.js.map +1 -1
  234. package/dist/types/protocol-constants.d.ts +1 -1
  235. package/dist/types/protocol-constants.js +1 -1
  236. package/dist/utils/binary-transfer.d.ts +1 -1
  237. package/dist/utils/errors.d.ts +2 -2
  238. package/dist/utils/errors.js +2 -2
  239. package/dist/utils/retry.d.ts +2 -1
  240. package/dist/utils/retry.d.ts.map +1 -1
  241. package/dist/utils/retry.js +3 -1
  242. package/dist/utils/retry.js.map +1 -1
  243. package/dist/zk/groups.d.ts +1 -1
  244. package/dist/zk/groups.js +1 -1
  245. package/docs/CLIENT_COMPOSITION.md +5 -3
  246. package/docs/DEVIATIONS.md +892 -0
  247. package/docs/GETTING_STARTED.md +10 -6
  248. package/docs/PACKAGE_SURFACE.md +2 -2
  249. package/docs/PROTOCOL_POLICY.md +11 -2
  250. package/docs/RECIPES.md +4 -0
  251. package/docs/api/classes/SignalProtocolClient.md +4 -4
  252. package/docs/api/functions/createDefaultSignalLogger.md +2 -2
  253. package/docs/api/functions/resolveSignalLogger.md +2 -2
  254. package/docs/api/interfaces/BlockedRecipientEntry.md +1 -1
  255. package/docs/api/interfaces/ILogger.md +1 -1
  256. package/docs/api/interfaces/ISignalLocalSecretVault.md +2 -2
  257. package/docs/api/interfaces/ISignalLocalStore.md +2 -2
  258. package/docs/api/interfaces/ISignalProtocolClient.md +2 -2
  259. package/docs/api/interfaces/MLKEMBraidAgentState.md +1 -1
  260. package/docs/api/interfaces/PreKeyMaintenanceStore.md +2 -1
  261. package/docs/api/interfaces/SealedSenderConfig.md +2 -2
  262. package/docs/api/interfaces/SignalProtocolClientCompositionOptions.md +2 -2
  263. package/docs/api/interfaces/SignalProtocolClientConfig.md +2 -2
  264. package/docs/api/interfaces/SignalProtocolClientHooks.md +1 -1
  265. package/docs/api/interfaces/SignalProtocolClientIdentityConfig.md +1 -1
  266. package/docs/api/interfaces/SignalProtocolClientMediaConfig.md +3 -3
  267. package/docs/api/interfaces/SignalProtocolConfig.md +1 -1
  268. package/docs/api/namespaces/encoding/functions/bytesToUrlSafeBase64.md +2 -2
  269. package/docs/api/namespaces/keys/functions/generateKemOneTimePreKeys.md +1 -1
  270. package/docs/api/namespaces/media/functions/prepareMediaAttachmentUpload.md +1 -1
  271. package/docs/api/namespaces/media/functions/resolveMediaAttachment.md +1 -1
  272. package/docs/api/namespaces/media/variables/downloadMediaAttachment.md +1 -1
  273. package/docs/api/type-aliases/GroupId.md +1 -1
  274. package/docs/api/variables/MAX_RECEIVER_CHAINS.md +1 -1
  275. package/docs/api/variables/ONE_TIME_PREKEY_BATCH_SIZE.md +1 -1
  276. package/docs/api/variables/defaultSignalLogger.md +2 -2
  277. package/local/store/mock/README.md +31 -0
  278. package/package.json +2 -1
  279. package/remote/relay/mock/README.md +37 -0
@@ -107,7 +107,9 @@ This is the target DX the package is moving toward. It is shown here so app
107
107
  developers can understand the intended mental model while the current stable API
108
108
  still uses `storage`, `remoteObjectStore`, hooks, and transition-only media helpers.
109
109
 
110
+ <!-- mock-snippet:skip target-message-api-not-yet-shipped -->
110
111
  ```ts
112
+ // Real protocol and cryptography; simulated in-memory infrastructure.
111
113
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
112
114
  import { createInMemoryDeviceStorage } from "@open-e2ee/signal-protocol-sdk/device/storage/memory";
113
115
  import { mockRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/mock";
@@ -180,8 +182,8 @@ const signal = await createSignalProtocolClient({
180
182
  ```
181
183
 
182
184
  Attachments use the same message API. On Expo, pass the picker URI; the Signal
183
- client copies or persists the bytes through `deviceStorage.files` before upload
184
- so retry can continue after restart:
185
+ Protocol client copies or persists the bytes through `deviceStorage.files`
186
+ before upload so retry can continue after restart:
185
187
 
186
188
  ```ts
187
189
  await signal.messages.send({
@@ -226,7 +228,9 @@ Use mock adapters for local examples and development:
226
228
  the demo sends while Bob is offline, inspects the relay-visible ciphertext, and
227
229
  then starts Bob's subscription to show the decrypted plaintext entering the app.
228
230
 
231
+ <!-- mock-snippet:run getting-started-stable-local-clients -->
229
232
  ```ts
233
+ // Real protocol and cryptography; simulated in-memory infrastructure.
230
234
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
231
235
  import { mockStore } from "@open-e2ee/signal-protocol-sdk/local/store/mock";
232
236
  import { mockRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/mock";
@@ -522,8 +526,8 @@ partial-byte store. Native background download code should implement the same
522
526
  `MediaAttachmentTransfer` interface.
523
527
 
524
528
  For background-safe uploads, use the durable client operation. The current API
525
- persists bounded recovery metadata through the existing Signal storage adapter;
526
- the target message-first API moves that responsibility behind
529
+ persists bounded recovery metadata through the existing Signal Protocol storage
530
+ adapter; the target message-first API moves that responsibility behind
527
531
  `deviceStorage.messages`. The operation tries the upload when it is due and
528
532
  returns either a completed pointer or a pending job id for later recovery:
529
533
 
@@ -560,8 +564,8 @@ await signal.media.processPending({
560
564
  ```
561
565
 
562
566
  On receive, ask the media planner what work this device should do. Your app
563
- supplies the IDs it has already processed or cached; the Signal package returns
564
- the safe next step without taking ownership of your app database:
567
+ supplies the IDs it has already processed or cached; the Signal Protocol package
568
+ returns the safe next step without taking ownership of your app database:
565
569
 
566
570
  ```ts
567
571
  const mediaWork = media.planMediaAttachmentProcessing({
@@ -183,8 +183,8 @@ Both concrete adapters keep provider credentials in the application backend.
183
183
  Remote object storage is a normal first-class integration point for encrypted
184
184
  attachments and files, not a niche or internal-only adapter. Use
185
185
  `attachment.transfer` when your app has a foreground, background, resumable, or
186
- platform-native byte transfer implementation. The Signal package still owns
187
- encryption, digest verification, retry decisions, and pointer metadata.
186
+ platform-native byte transfer implementation. The Signal Protocol package still
187
+ owns encryption, digest verification, retry decisions, and pointer metadata.
188
188
 
189
189
  Object stores can return signed upload headers, and stores that return
190
190
  `protocol: 'tus'` automatically use the built-in resumable TUS transfer helper.
@@ -1,6 +1,12 @@
1
1
  # Protocol Policy Guide
2
2
 
3
- > Navigation: [README](../README.md) | [ARCHITECTURE](../ARCHITECTURE.md) | [Security](./SECURITY.md) | [Getting Started](./GETTING_STARTED.md) | **Protocol Policy**
3
+ > Navigation: [README](../README.md) | [ARCHITECTURE](../ARCHITECTURE.md) | [Security](./SECURITY.md) | [Getting Started](./GETTING_STARTED.md) | **Protocol Policy** | [Deviations](./DEVIATIONS.md)
4
+
5
+ This document covers **which protocol modes run** and which fail closed. For
6
+ **how the profile differs from the published specifications and from
7
+ `libsignal`** — the composite identity, the Ed25519-instead-of-XEdDSA signature
8
+ scheme, the ML-KEM Braid `hek` operand order, and the rest — see
9
+ [Deviations](./DEVIATIONS.md).
4
10
 
5
11
  The public Signal Protocol client policy is:
6
12
 
@@ -65,7 +71,10 @@ await createSignalProtocolClient({
65
71
 
66
72
  `braid: 'required'` uses the specification-defined ML-KEM Braid SPQR profile
67
73
  and is the default. HEK is `SHA3-256(ek_seed || ek_vector)`; that operand order
68
- is part of the public compatibility boundary.
74
+ is part of the public compatibility boundary. It follows the ML-KEM Braid
75
+ specification text and is the reverse of `libsignal`'s implementation, which means
76
+ braid sessions do not interoperate with `libsignal`'s and the KEM in this mode is not
77
+ stock FIPS 203 — see [Deviations §4.1](./DEVIATIONS.md#41-the-hek-operand-order-diverges).
69
78
 
70
79
  ```ts
71
80
  await createSignalProtocolClient({
package/docs/RECIPES.md CHANGED
@@ -13,7 +13,9 @@ uses public exports only.
13
13
  This local demo sends while Bob is offline so you can see the relay's encrypted
14
14
  envelope and Bob's decrypted plaintext in the same workflow.
15
15
 
16
+ <!-- mock-snippet:run recipes-two-local-clients -->
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 { mockStore } from "@open-e2ee/signal-protocol-sdk/local/store/mock";
19
21
  import { mockRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/mock";
@@ -133,7 +135,9 @@ before creating the client.
133
135
 
134
136
  ## Local development
135
137
 
138
+ <!-- mock-snippet:run recipes-local-development -->
136
139
  ```ts
140
+ // Real protocol and cryptography; simulated in-memory infrastructure.
137
141
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
138
142
  import { mockRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/mock";
139
143
  import { mockStore } from "@open-e2ee/signal-protocol-sdk/local/store/mock";
@@ -43,7 +43,7 @@ Device ID for this client instance (1 = primary, 2-5 = linked)
43
43
 
44
44
  Resolved logger for this client instance.
45
45
 
46
- This is the client-scoped logger used throughout the Signal runtime.
46
+ This is the client-scoped logger used throughout the Signal Protocol runtime.
47
47
 
48
48
  #### Implementation of
49
49
 
@@ -55,7 +55,7 @@ This is the client-scoped logger used throughout the Signal runtime.
55
55
 
56
56
  > `readonly` **media**: [`SignalProtocolClientMedia`](../interfaces/SignalProtocolClientMedia.md)
57
57
 
58
- Durable media job facade backed by the configured Signal local store.
58
+ Durable media job facade backed by the configured Signal Protocol local store.
59
59
 
60
60
  Use this for background-safe attachment uploads, downloads, and cleanup
61
61
  when the app provides media lifecycle callbacks in `config.media`.
@@ -1785,7 +1785,7 @@ Per Signal Protocol specification, rotate sender keys on **membership changes**:
1785
1785
  | Member ADDED | Distribute current key to new member (no rotation needed) |
1786
1786
  | Group metadata changed | Rotate recommended |
1787
1787
 
1788
- **Important**: Signal does NOT use periodic or message-count-based rotation.
1788
+ **Important**: The Signal Protocol does NOT use periodic or message-count-based rotation.
1789
1789
  Only rotate when membership changes to maintain forward secrecy.
1790
1790
 
1791
1791
  ## Why Rotate on Member Removal?
@@ -1919,7 +1919,7 @@ All inputs are normalized to Uint8Array before reaching the cipher layer.
1919
1919
 
1920
1920
  `string`
1921
1921
 
1922
- User ID or group ID (groups use Signal V2 prefix)
1922
+ User ID or group ID (groups use the Signal Protocol V2 prefix)
1923
1923
 
1924
1924
  ##### content
1925
1925
 
@@ -10,8 +10,8 @@
10
10
 
11
11
  Logging utilities for app composition
12
12
 
13
- Pass a logger into `createSignalProtocolClient()` to route Signal logs through your
14
- app logger or custom diagnostics pipeline.
13
+ Pass a logger into `createSignalProtocolClient()` to route Signal Protocol logs
14
+ through your app logger or custom diagnostics pipeline.
15
15
 
16
16
  ## Returns
17
17
 
@@ -10,8 +10,8 @@
10
10
 
11
11
  Logging utilities for app composition
12
12
 
13
- Pass a logger into `createSignalProtocolClient()` to route Signal logs through your
14
- app logger or custom diagnostics pipeline.
13
+ Pass a logger into `createSignalProtocolClient()` to route Signal Protocol logs
14
+ through your app logger or custom diagnostics pipeline.
15
15
 
16
16
  ## Parameters
17
17
 
@@ -6,7 +6,7 @@
6
6
 
7
7
  # Interface: BlockedRecipientEntry
8
8
 
9
- Signal blocking contracts.
9
+ Signal Protocol blocking contracts.
10
10
 
11
11
  Blocking is account/contact state, not message content. The core package owns
12
12
  the local blocking workflow and lets each app choose whether blocked state is
@@ -6,7 +6,7 @@
6
6
 
7
7
  # Interface: ILogger
8
8
 
9
- Signal package logging primitives.
9
+ Signal Protocol package logging primitives.
10
10
 
11
11
  The package resolves a logger once at composition time and passes it through
12
12
  explicit dependencies. This keeps logging package-local without relying on
@@ -6,11 +6,11 @@
6
6
 
7
7
  # Interface: ISignalLocalSecretVault
8
8
 
9
- Small local secret vault used to bootstrap a local Signal store.
9
+ Small local secret vault used to bootstrap a local Signal Protocol store.
10
10
 
11
11
  This interface is intentionally narrow: it exists for secrets that must
12
12
  remain outside the main local store, such as a database encryption key.
13
- It is not a second general-purpose Signal data store.
13
+ It is not a second general-purpose Signal Protocol data store.
14
14
 
15
15
  ## Methods
16
16
 
@@ -6,9 +6,9 @@
6
6
 
7
7
  # Interface: ISignalLocalStore
8
8
 
9
- Signal local store interface.
9
+ Signal Protocol local store interface.
10
10
 
11
- Canonical device/browser-local persistence for Signal protocol state:
11
+ Canonical device/browser-local persistence for Signal Protocol state:
12
12
  - identity keys and registrations
13
13
  - sessions and sender keys
14
14
  - SESAME multi-device state
@@ -36,7 +36,7 @@ Device ID for this client instance (1 = primary, 2-5 = linked)
36
36
 
37
37
  Resolved logger for this client instance.
38
38
 
39
- This is the client-scoped logger used throughout the Signal runtime.
39
+ This is the client-scoped logger used throughout the Signal Protocol runtime.
40
40
 
41
41
  ***
42
42
 
@@ -778,7 +778,7 @@ Send content to a recipient
778
778
 
779
779
  This is the primary API for sending encrypted content.
780
780
  Automatically handles:
781
- - Group vs user detection (Signal V2 prefix)
781
+ - Group vs user detection (Signal Protocol V2 prefix)
782
782
  - Content type routing (DataMessageInput, string, Uint8Array)
783
783
  - Multi-device fan-out
784
784
  - Sender key distribution for groups
@@ -52,7 +52,7 @@ Decoded CT1 stored for combined MAC verification with CT2
52
52
 
53
53
  > `optional` **ct1\_for\_mac?**: `Uint8Array`\<`ArrayBufferLike`\>
54
54
 
55
- CT1 copy stored for combined MAC computation with CT2 (Signal authenticates ct1||ct2)
55
+ CT1 copy stored for combined MAC computation with CT2 (libsignal authenticates ct1||ct2)
56
56
 
57
57
  ***
58
58
 
@@ -8,7 +8,8 @@
8
8
 
9
9
  App-provided persistence helpers for prekey replacement bookkeeping.
10
10
 
11
- Signal owns rotation semantics; concrete storage adapters own persistence.
11
+ The Signal Protocol client owns rotation semantics; concrete storage adapters
12
+ own persistence.
12
13
 
13
14
  ## Methods
14
15
 
@@ -52,8 +52,8 @@ Base64-encoded serialized SenderCertificate
52
52
 
53
53
  Optional host-provided contact profile state store.
54
54
 
55
- When present, Signal can use per-contact profile keys and
56
- unidentified-access mode for direct-message sealed sender sends
55
+ When present, the Signal Protocol client can use per-contact profile keys
56
+ and unidentified-access mode for direct-message sealed sender sends
57
57
  without importing the host app's persistence layer.
58
58
 
59
59
  ***
@@ -389,8 +389,8 @@ https://signal.org/docs/specifications/pqxdh/#publishing-keys
389
389
 
390
390
  App-owned media lifecycle callbacks for the SignalProtocolClient media queue.
391
391
 
392
- The queue itself is persisted through the existing Signal local storage
393
- adapter. These callbacks keep local bytes, plaintext caches, and product
392
+ The queue itself is persisted through the existing Signal Protocol local
393
+ storage adapter. These callbacks keep local bytes, plaintext caches, and product
394
394
  state in the app layer where they can share file permissions, UI state, and
395
395
  app database ownership.
396
396
 
@@ -407,8 +407,8 @@ https://signal.org/docs/specifications/pqxdh/#publishing-keys
407
407
 
408
408
  App-owned media lifecycle callbacks for the SignalProtocolClient media queue.
409
409
 
410
- The queue itself is persisted through the existing Signal local storage
411
- adapter. These callbacks keep local bytes, plaintext caches, and product
410
+ The queue itself is persisted through the existing Signal Protocol local
411
+ storage adapter. These callbacks keep local bytes, plaintext caches, and product
412
412
  state in the app layer where they can share file permissions, UI state, and
413
413
  app database ownership.
414
414
 
@@ -263,7 +263,7 @@ The session used for encryption
263
263
 
264
264
  `number`
265
265
 
266
- The message counter (Ns) - matches Signal proto field name
266
+ The message counter (Ns) - matches the libsignal proto field name
267
267
 
268
268
  #### Returns
269
269
 
@@ -16,7 +16,7 @@ A client represents one app install for one account and one device.
16
16
 
17
17
  > `optional` **deviceId?**: `number`
18
18
 
19
- Signal device identifier. Defaults to primary device 1.
19
+ Signal Protocol device identifier. Defaults to primary device 1.
20
20
 
21
21
  ***
22
22
 
@@ -46,8 +46,8 @@ Delete app-owned local cache state for a cleanup job.
46
46
 
47
47
  Load app-owned local bytes for a queued upload.
48
48
 
49
- The Signal package owns encryption and upload execution. The app owns draft
50
- files, cache paths, and file permissions, so bytes enter the queue through
49
+ The Signal Protocol package owns encryption and upload execution. The app owns
50
+ draft files, cache paths, and file permissions, so bytes enter the queue through
51
51
  this callback instead of hidden package storage.
52
52
 
53
53
  #### Parameters
@@ -80,7 +80,7 @@ Maximum attempts before a failing job is removed.
80
80
 
81
81
  > `optional` **maxJobs?**: `number`
82
82
 
83
- Bound the queue kept in the Signal local store metadata.
83
+ Bound the queue kept in the Signal Protocol local store metadata.
84
84
 
85
85
  #### Default
86
86
 
@@ -6,7 +6,7 @@
6
6
 
7
7
  # Interface: SignalProtocolConfig
8
8
 
9
- Public Signal protocol configuration.
9
+ Public Signal Protocol configuration.
10
10
 
11
11
  This keeps application code in product/security terms. Internal protocol
12
12
  strategy details such as X3DH fallback remain below the SignalProtocolClient seam.
@@ -15,8 +15,8 @@ URL-safe Base64 uses:
15
15
  - `_` instead of `/`
16
16
  - No padding (`=`)
17
17
 
18
- Used for R2 storage keys (attachments, profiles) following the Signal
19
- Messenger storage-key pattern.
18
+ Used for R2 storage keys (attachments, profiles), which must survive being
19
+ placed in a URL path without escaping.
20
20
 
21
21
  ## Parameters
22
22
 
@@ -16,7 +16,7 @@ Each key can only be used once for per-session post-quantum forward secrecy.
16
16
  Per PQXDH spec Section 3.2, these are signed one-time pqkem prekeys
17
17
  that the server prefers over the last-resort KEM prekey.
18
18
 
19
- Uses the same batch size as EC one-time prekeys (Signal uses 100 for both).
19
+ Uses the same batch size as EC one-time prekeys (libsignal uses 100 for both).
20
20
 
21
21
  ## Parameters
22
22
 
@@ -13,7 +13,7 @@ Encrypt and upload media bytes, returning a SDK attachment pointer.
13
13
  The encrypted object digest and object ID are computed once. Upload
14
14
  retries request fresh presigned URLs for that same key, which handles expired
15
15
  upload URLs without changing the pointer metadata that will be encrypted into
16
- the Signal message.
16
+ the Signal Protocol message.
17
17
 
18
18
  ## Parameters
19
19
 
@@ -8,7 +8,7 @@
8
8
 
9
9
  > **resolveMediaAttachment**(`attachment`, `options`): `Promise`\<[`ResolvedMediaAttachment`](../interfaces/ResolvedMediaAttachment.md)\>
10
10
 
11
- Download, verify, and decrypt a Signal media attachment pointer.
11
+ Download, verify, and decrypt a Signal Protocol media attachment pointer.
12
12
 
13
13
  This is the safe receive-side counterpart to attachment upload. It validates
14
14
  pointer metadata, downloads opaque ciphertext from the object store, verifies
@@ -8,7 +8,7 @@
8
8
 
9
9
  > `const` **downloadMediaAttachment**: (`attachment`, `options`) => `Promise`\<[`ResolvedMediaAttachment`](../interfaces/ResolvedMediaAttachment.md)\> = `resolveMediaAttachment`
10
10
 
11
- Download, verify, and decrypt a Signal media attachment pointer.
11
+ Download, verify, and decrypt a Signal Protocol media attachment pointer.
12
12
 
13
13
  This is the safe receive-side counterpart to attachment upload. It validates
14
14
  pointer metadata, downloads opaque ciphertext from the object store, verifies
@@ -11,7 +11,7 @@
11
11
  Branded type for prefixed group IDs
12
12
 
13
13
  Ensures compile-time safety for group ID handling.
14
- A GroupId is always a string with the Signal V2 prefix.
14
+ A GroupId is always a string with the Signal Protocol V2 prefix.
15
15
 
16
16
  ## Type Declaration
17
17
 
@@ -10,5 +10,5 @@
10
10
 
11
11
  Maximum number of receiver chains to store.
12
12
 
13
- Signal maintains up to 5 receiver chains for handling out-of-order
13
+ libsignal maintains up to 5 receiver chains for handling out-of-order
14
14
  DH ratchets. When a 6th chain would be added, the oldest is evicted.
@@ -10,7 +10,7 @@
10
10
 
11
11
  Batch size for one-time prekeys (both EC and KEM)
12
12
 
13
- Signal uses 100 for both EC and KEM one-time prekeys to maintain
13
+ libsignal uses 100 for both EC and KEM one-time prekeys to maintain
14
14
  protocol symmetry. This balances key availability with storage/upload costs.
15
15
 
16
16
  Per PQXDH specification, KEM one-time prekeys follow the same
@@ -10,8 +10,8 @@
10
10
 
11
11
  Logging utilities for app composition
12
12
 
13
- Pass a logger into `createSignalProtocolClient()` to route Signal logs through your
14
- app logger or custom diagnostics pipeline.
13
+ Pass a logger into `createSignalProtocolClient()` to route Signal Protocol logs
14
+ through your app logger or custom diagnostics pipeline.
15
15
 
16
16
  ## Example
17
17
 
@@ -3,6 +3,8 @@
3
3
  `MockSignalStore` implements `ISignalLocalStore` in memory for examples, local
4
4
  development, and deterministic application prototypes.
5
5
 
6
+ Real protocol and cryptography; simulated in-memory infrastructure.
7
+
6
8
  ## Why it exists
7
9
 
8
10
  It lets developers exercise client composition without choosing a durable
@@ -12,6 +14,7 @@ security or persistence boundary.
12
14
  ## Usage
13
15
 
14
16
  ```ts
17
+ // Real protocol and cryptography; simulated in-memory infrastructure.
15
18
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
16
19
  import { mockStore } from "@open-e2ee/signal-protocol-sdk/local/store/mock";
17
20
 
@@ -24,4 +27,32 @@ const client = await createSignalProtocolClient({
24
27
  All keys, sessions, and trust decisions disappear when the process or adapter
25
28
  is discarded. Never use this adapter for production accounts.
26
29
 
30
+ ## Deterministic storage failures
31
+
32
+ Failure mode is opt-in. A seed and cadence replay the same failing writes, or
33
+ you can target the next named store operation:
34
+
35
+ ```ts
36
+ // Real protocol and cryptography; simulated in-memory infrastructure.
37
+ import {
38
+ mockStore,
39
+ MockStorageWriteError,
40
+ } from "@open-e2ee/signal-protocol-sdk/local/store/mock";
41
+
42
+ const storage = mockStore({ failures: { seed: 7 } });
43
+ storage.failures.failNextWrite("setMetadata");
44
+
45
+ try {
46
+ await storage.setMetadata("draft", "encrypted-pointer");
47
+ } catch (error) {
48
+ if (error instanceof MockStorageWriteError) {
49
+ // The explicitly injected failure is consumed, so this retry succeeds.
50
+ await storage.setMetadata("draft", "encrypted-pointer");
51
+ }
52
+ }
53
+ ```
54
+
55
+ Use `writeFailureEvery` for a repeatable cadence. Failure selection uses the
56
+ configured seed and operation count, never `Math.random()` or wall-clock time.
57
+
27
58
  See the parent [storage guide](../README.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "0.1.0-alpha.3",
3
+ "version": "0.1.0-alpha.5",
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",
@@ -290,6 +290,7 @@
290
290
  "dist",
291
291
  "docs/ASSURANCE.md",
292
292
  "docs/CLIENT_COMPOSITION.md",
293
+ "docs/DEVIATIONS.md",
293
294
  "docs/DOCUMENTATION_STANDARDS.md",
294
295
  "docs/E2EE.md",
295
296
  "docs/ERROR_HANDLING.md",
@@ -3,6 +3,8 @@
3
3
  `MockSignalRelayServer` implements `ISignalRelayServer` in memory for examples
4
4
  and local application development.
5
5
 
6
+ Real protocol and cryptography; simulated in-memory infrastructure.
7
+
6
8
  ## Why it exists
7
9
 
8
10
  It provides device registration, public-prekey exchange, and encrypted-envelope
@@ -12,6 +14,7 @@ authorization or durability boundary.
12
14
  ## Usage
13
15
 
14
16
  ```ts
17
+ // Real protocol and cryptography; simulated in-memory infrastructure.
15
18
  import { createSignalProtocolClient } from "@open-e2ee/signal-protocol-sdk";
16
19
  import { mockStore } from "@open-e2ee/signal-protocol-sdk/local/store/mock";
17
20
  import { mockRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/mock";
@@ -29,4 +32,38 @@ All registered devices, public keys, mailboxes, and provisioning state disappear
29
32
  with the adapter. It performs no real account authentication, rate limiting,
30
33
  abuse prevention, or durable delivery and must not be used in production.
31
34
 
35
+ ## Deterministic failure and recovery exercises
36
+
37
+ Failure mode is opt-in and seeded. The default `mockRelay()` remains the
38
+ deterministic happy path:
39
+
40
+ ```ts
41
+ // Real protocol and cryptography; simulated in-memory infrastructure.
42
+ import { mockRelay } from "@open-e2ee/signal-protocol-sdk/remote/relay/mock";
43
+
44
+ const relay = mockRelay({
45
+ failures: {
46
+ seed: 7,
47
+ latencyMs: 20,
48
+ duplicateDeliveryEvery: 3,
49
+ reorderDeliveryPairs: true,
50
+ rejectAuthorization: true,
51
+ exhaustOneTimePreKeys: true,
52
+ },
53
+ });
54
+
55
+ relay.failures.disconnect("bob", 1);
56
+ // Sends remain in Bob's encrypted mailbox.
57
+ relay.failures.reconnect("bob", 1);
58
+ ```
59
+
60
+ `flushReordered()` releases an unmatched final envelope. `configure()` changes
61
+ a scenario without rebuilding clients. Authorization rejection raises
62
+ `SealedSenderAuthError`, allowing the client's documented identified-delivery
63
+ fallback. One-time-prekey exhaustion withholds both EC and KEM one-time keys but
64
+ keeps the KEM last-resort key, so strict-PQ examples exercise the intended
65
+ post-quantum recovery path rather than a silent classical downgrade. Failure
66
+ selection uses the configured seed and delivery count, never `Math.random()` or
67
+ wall-clock time.
68
+
32
69
  See the parent [relay guide](../README.md).