@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
@@ -0,0 +1,892 @@
1
+ # Deviations from the Signal Protocol Specifications
2
+
3
+ > Navigation: [README](../README.md) | [ARCHITECTURE](../ARCHITECTURE.md) |
4
+ > [Security](./SECURITY.md) | [Protocol Policy](./PROTOCOL_POLICY.md) |
5
+ > **Deviations**
6
+
7
+ ## What compatibility means here
8
+
9
+ This SDK implements the same cryptographic core as the published Signal Protocol
10
+ specifications — X3DH/PQXDH key agreement, the Double Ratchet, the ML-KEM Braid
11
+ post-quantum ratchet, Sesame multi-device session management, sealed sender, and
12
+ the Signal Protocol's zero-knowledge group credential system. In many places it is faithful
13
+ down to the byte: the same KDF labels, the same chain-key constants, the same
14
+ protobuf field numbers, the same iteration counts.
15
+
16
+ It is **not wire-compatible with Signal Messenger or with `libsignal`**, and it
17
+ is not intended to be. Messages produced by this SDK cannot be decrypted by a
18
+ Signal Messenger client, identities cannot be exchanged, safety numbers computed here
19
+ cannot be compared against safety numbers shown in Signal Messenger, and sessions cannot be
20
+ migrated in either direction. This is a distinct wire profile —
21
+ `IndependentProfileV1` — that shares the Signal Protocol's cryptographic design and
22
+ deliberately does not share its encoding.
23
+
24
+ That distinction matters in a specific way. Reading "implements X3DH and the
25
+ Double Ratchet" reasonably leads someone to expect interoperability. There is
26
+ none. Reading "safety numbers compatible with Signal Messenger" would reasonably
27
+ lead someone to expect that a user could verify a contact by comparing a number
28
+ shown in this SDK against the same contact's number in Signal Messenger. They
29
+ cannot; the numbers are computed over different inputs and will never match.
30
+
31
+ This document is the complete, honest account of where and why the profile
32
+ differs. Each entry names the implementing file, the specification section or
33
+ `libsignal` source it departs from, the engineering reason, and the cost. Where a
34
+ deviation weakens an assurance that a reader of the specification would
35
+ reasonably assume, that is stated plainly rather than framed as a feature.
36
+
37
+ Deviations fall into three kinds:
38
+
39
+ - **Deviation** — does something different from the specification or from
40
+ `libsignal`, deliberately.
41
+ - **Extension** — adds a mechanism the specification does not describe.
42
+ - **Independent design** — shares a name and a goal with a Signal Protocol system, but is
43
+ the SDK's own construction rather than a port of the corresponding `libsignal` system.
44
+
45
+ A fourth label, **faithful**, appears in the table where an area follows the
46
+ specification closely enough that its presence in this document is only to
47
+ delimit what the neighbouring deviations do and do not touch.
48
+
49
+ Companion documents: [Protocol Policy](./PROTOCOL_POLICY.md) states which
50
+ protocol modes run and which fail closed; this document states how the profile
51
+ differs from the specifications. [Security](./SECURITY.md) states the threat
52
+ model and what is out of scope.
53
+
54
+ ---
55
+
56
+ ## Summary
57
+
58
+ | Area | Specification followed | Deviation or extension | Why | Consequence |
59
+ |---|---|---|---|---|
60
+ | **Identity keys** | X3DH §2.2; `libsignal` `identity_key.rs` | **Deviation.** A 67-byte composite of separate X25519 and Ed25519 keys replaces the single 33-byte Curve25519 identity key | Avoids XEdDSA, a non-standard signature scheme with no vetted JavaScript implementation; standard Ed25519 is independently verifiable | Two keys to store and rotate; larger identity; **no wire compatibility for any identity-bearing material** |
61
+ | **Prekey signatures** | X3DH §2.2, §4.5 | **Deviation.** RFC 8032 Ed25519 over a domain-separated context binding the identity commitment, algorithm tag, and key ID — not XEdDSA over the bare key | Defeats cross-algorithm and cross-key-ID substitution that a bare-key signature does not cover | Strictly stronger binding; signatures are unverifiable by Signal Messenger clients and vice versa |
62
+ | **Safety numbers** | `libsignal` `fingerprint.rs` | **Deviation.** Iteration and digit encoding are byte-identical, but the input is a composite-identity commitment under an SDK domain string, the QR version is `3`, and the two halves are ordered by user ID rather than by digit string | Follows from the composite identity; a single-key fingerprint cannot authenticate both components | **Safety numbers are not comparable to Signal Messenger's.** The ordering rule also differs from `libsignal` even on the single-key path |
63
+ | **X3DH / PQXDH** | X3DH rev. 1; PQXDH rev. 3 | **Faithful** on DH order, the `0xFF`×32 prefix, zero-salt HKDF, and KEM-secret position. **Deviation:** ML-KEM-1024 (FIPS 203) runs under an info string naming `CRYSTALS-KYBER-1024` | Standardized ML-KEM preferred over round-3 Kyber; the label was inherited from `libsignal` and not updated | Identical label with a different KEM means the same transcript derives a **different** shared secret, with no domain separation signalling it. Violates PQXDH §2.2 |
64
+ | **Associated data** | X3DH §3.3 | **Deviation.** `AD` is a domain-separated HMAC input over SHA-256 commitments to both composite identities, not `IK_A ‖ IK_B` | Binds the Ed25519 component, which a raw-key `AD` would leave uncovered | Stronger binding; wire-incompatible |
65
+ | **Double Ratchet** | Double Ratchet rev. 4 | **Faithful** on `WhisperRatchet`, `WhisperMessageKeys`, the `0x01`/`0x02` seeds, the 80-byte split, AES-256-CBC, the `0x44` version byte, and 8-byte MAC truncation | — | The ratchet core follows the Double Ratchet specification |
66
+ | **Message wire format** | `libsignal` `wire.proto` | **Faithful** field numbers 1–8. **Extension:** fields at 100+ carry identity type and ML-KEM one-time prekey material. **Deviation:** address binding uses variable-length UTF-8 user IDs and 4-byte device IDs instead of 17-byte ServiceIds and 1-byte device IDs | The SDK binds application-defined identifiers, not Signal Messenger ACIs | Wire-incompatible; a Signal Messenger client would silently ignore the added fields |
67
+ | **Skipped keys and archiving** | Double Ratchet §2.6; `libsignal` `consts.rs` | **Deviation.** The 2000-key cap is global rather than per-chain, eviction is by wall-clock timestamp, and skipped keys expire after 7 days. Session records serialize as JSON, not protobuf | Simpler storage accounting and bounded growth | **Legitimate messages can become undecryptable** where `libsignal` would still decrypt them: a 5× smaller effective cap, cross-chain eviction, and a hard 7-day limit for offline recipients |
68
+ | **Padding** | — | **Extension.** ISO 7816-4 bit padding to 160-byte buckets inside the library | Length hiding by default rather than left to the application | `libsignal` does not pad at this layer; Signal Messenger's apps do. PKCS#7 then adds a block, so ciphertext lands 16 bytes past each boundary |
69
+ | **SPQR / ML-KEM Braid** | ML-KEM Braid rev. 1 | **Deviation.** Same protocol, same KDF labels, same Reed–Solomon parameters, byte-identical message framing — except `hek = SHA3-256(ek_seed ‖ ek_vector)`, the operand order the specification states, which is the reverse of `libsignal`'s implementation | The normative text was followed over the executable reference | Wire-visible. Headers, ciphertexts, and shared secrets diverge; a braid session cannot complete a single epoch against `libsignal`'s implementation. Also means the KEM is not FIPS 203 in braid mode |
70
+ | **Triple Ratchet** | `libsignal` `triple_ratchet.rs` | **Faithful.** The PQ secret enters as the HKDF salt at message-key expansion, same label, same order | — | The braiding construction follows the ML-KEM Braid specification |
71
+ | **Sesame** | Sesame rev. 2 | **Deviation** on session expiry (§4.2 applies only to unacknowledged sessions) and on deleted devices (hard-removed rather than marked stale). **Extensions:** QR provisioning, device transfer, encrypted device names, identity-change gating, a 5-device cap | Product requirements the specification does not address | Hard deletion **drops the MAXLATENCY window, so in-flight messages from a just-removed device become permanently undecryptable**. Device transfer clones ratchet state, which weakens the forward-secrecy bound |
72
+ | **Sealed sender v1** | `libsignal` `sealed_sender.rs` | **Deviation.** Correct labels, cipher, and MAC length, but the 96-byte HKDF output is split `(cipher, mac, chain)` where `libsignal` splits `(chain, cipher, mac)`; keys in the salt omit the `0x05` type byte; the inner envelope is a hand-rolled varint format rather than the `UnidentifiedSenderMessage.Message` protobuf | The slice order and the missing prefix are unintentional; the envelope is a deliberate simplification | Self-consistent and secure, but every v1 key sits in a different slot than `libsignal`'s. The envelope also drops the message-type field |
73
+ | **Sealed sender v2** | `libsignal` `sealed_sender.rs` | **Faithful** on all four labels, the KEM, AES-256-GCM-SIV, the multi-recipient binary format, and the `0x3FFF` registration-ID mask | — | The v2 construction follows `libsignal` |
74
+ | **Delivery token** | `libsignal` `profile_key.rs` | **Faithful.** `deriveAccessKey` follows `libsignal`'s `ProfileKey::derive_access_key`, and reproduces `libsignal`'s published known-answer values | — | Not an SDK invention, despite what the module name suggests |
75
+ | **Sender keys** | `libsignal` `sender_keys.rs` | **Deviation.** Protobuf field numbers and `0x33` framing match, and the `0x01`/`0x02` seeds match, but message-key derivation **omits HKDF-Extract**, signatures are Ed25519 not XEdDSA, and `distributionUuid` carries a UTF-8 string rather than 16 UUID bytes | The Ed25519 choice follows the identity profile; the missing Extract appears unintentional | Group message keys differ from `libsignal`'s for the same chain key. Confirmed numerically, not merely by inspection |
76
+ | **Groups v2** | Signal Private Group System | **Independent design.** Real zkgroup primitives underneath, but the client is the state authority: it re-encrypts and uploads whole group state, and server signatures are not verified | Ships a working group system without a validating server | The relay **cannot validate group changes**, so it cannot enforce roles or membership. This is a materially weaker trust model than the Signal Private Group System, where the server validates every change against zero-knowledge presentations |
77
+ | **zkgroup / zkcredential** | `libsignal` `zkgroup`, `zkcredential`, `poksho` | **Faithful** port of the Ristretto255 KVAC and Sigma-protocol system, verified against `libsignal`'s known-answer vectors. **Deviation:** server parameter derivation uses SDK-specific labels | Server keys are the SDK's own trust root, not Signal Messenger's | The zero-knowledge properties are real. Credentials are not interchangeable with Signal Messenger's |
78
+ | **Registration IDs** | `libsignal` `sealed_sender.rs` | **Faithful** as of 0.1.0-alpha.4. Generated in `[1, 16383]`, strictly inside the 14 bits the wire format reserves | — | Through alpha.3 the range ran to 16384, which masked to `0` on the wire in multi-recipient sealed sender for roughly 1 install in 16,384 |
79
+
80
+ ---
81
+
82
+ ## 1. Identity keys and signatures
83
+
84
+ ### 1.1 Composite identity replaces the single Curve25519 key
85
+
86
+ `libsignal` represents an identity as one Curve25519 public key serialized as
87
+ `0x05 ‖ key` — 33 bytes ([`identity_key.rs:23-49`][ik]). The same private key is
88
+ used both for Diffie-Hellman and, via XEdDSA, for signing.
89
+
90
+ This SDK stores a versioned tuple of two separate keys
91
+ (`keys/identity.ts:20-23`, `:66-72`):
92
+
93
+ ```text
94
+ 0x01 version
95
+ || 0x01 || 32-byte X25519 public key DH component
96
+ || 0x02 || 32-byte Ed25519 public key signing component
97
+ ```
98
+
99
+ 67 bytes, X25519 first. Decoding fails closed on any wrong version byte, tag, or
100
+ length (`keys/identity.ts:75-96`).
101
+
102
+ **Why.** XEdDSA ([spec][xeddsa]) lets one Curve25519 key serve both roles by
103
+ converting a Montgomery point to an Edwards point at signing time. It is
104
+ elegant, and it is also non-standard: no vetted JavaScript implementation exists,
105
+ the conversion has sign-bit handling that is easy to get subtly wrong, and the
106
+ resulting signatures cannot be checked by any general-purpose Ed25519 verifier.
107
+ Carrying an explicit Ed25519 key costs 32 bytes and one more key to manage, and
108
+ buys signatures that any RFC 8032 implementation can verify and that auditors can
109
+ reason about without first reasoning about curve conversion.
110
+
111
+ **Cost.** Two keys to generate, store, rotate, and back up. A larger identity on
112
+ the wire and at rest. And no wire compatibility for anything that carries an
113
+ identity: prekey bundles, initial messages, sender certificates, safety numbers.
114
+ `libsignal`'s `IdentityKey::decode` reads the leading `0x01` as an unknown key
115
+ type and errors.
116
+
117
+ A commitment binds the tuple (`keys/identity.ts:98-100`):
118
+
119
+ ```text
120
+ SHA-256(UTF8("signal-protocol-js composite identity v1") || CompositeIdentityV1)
121
+ ```
122
+
123
+ A commitment received from a relay, cache, or caller is never trusted; it is
124
+ recomputed and compared in constant time (`keys/identity.ts:103-111`), and every
125
+ producer of stored identity bytes is forced through a decode/re-encode round trip
126
+ so that two encodings of the same key cannot forge an identity-change event
127
+ (`keys/identity.ts:154-161`). `libsignal` has no commitment concept, because a
128
+ single-key format has nothing to bind together.
129
+
130
+ **Not ported.** `libsignal`'s ACI↔PNI alternate-identity signature
131
+ ([`identity_key.rs:61-70`][ik]) has no SDK equivalent. ACI and PNI are fully
132
+ independent identities here with independent trust histories; neither certifies
133
+ the other. An application that wants a user's two identities linked must
134
+ establish that link itself.
135
+
136
+ ### 1.2 Prekey signatures are Ed25519 over a domain-separated context
137
+
138
+ `libsignal` signs the bare serialized public key with the identity key via
139
+ XEdDSA, and verifies the same way ([`session.rs:199-213`][sess]).
140
+
141
+ This SDK signs, with the separate Ed25519 key (`keys/prekey-signature.ts:39-45`):
142
+
143
+ ```text
144
+ UTF8("signal-protocol-js prekey signature v1")
145
+ || SHA-256 identity commitment
146
+ || algorithm tag (1 byte)
147
+ || key ID (uint32, big-endian)
148
+ || serialized public key
149
+ ```
150
+
151
+ ML-KEM prekeys must carry their `0x0A` tag inside the signed bytes
152
+ (`keys/prekey-signature.ts:33-38`).
153
+
154
+ **Why.** A bare-key signature says only "the identity holder signed these 32
155
+ bytes." It does not say which algorithm the key is for, which key ID it occupies,
156
+ or which identity it belongs to. Binding all three defeats cross-algorithm
157
+ substitution (presenting an X25519 signature as an ML-KEM one) and cross-key-ID
158
+ substitution. This is strictly stronger than the specification requires.
159
+
160
+ **Cost.** Wire incompatibility, and a signature format that no Signal Messenger
161
+ implementation can verify.
162
+
163
+ The same Ed25519-instead-of-XEdDSA choice applies to sealed sender certificates
164
+ (`internal/protocol/sealed-sender/certificate.ts:59`, `:106`) and to sender key
165
+ messages (§7.2).
166
+
167
+ XEdDSA and VXEdDSA are not implemented, not stubbed, and not claimed anywhere in
168
+ this codebase. Where the frozen upstream specification snapshots mention them,
169
+ that is upstream text; the SDK's own documentation consistently states that
170
+ ordinary Ed25519 is used instead.
171
+
172
+ ### 1.3 Safety numbers are not comparable to Signal Messenger's
173
+
174
+ State this without hedging: **a safety number produced by this SDK will never
175
+ match the safety number Signal Messenger shows for the same two users.** A user cannot
176
+ verify a contact by reading a number out of one application and comparing it
177
+ against the other.
178
+
179
+ Three independent reasons, any one of which is sufficient.
180
+
181
+ **The user-facing number is computed over a composite commitment.**
182
+ `client.verify()` uses `generateCompositeSafetyNumber`
183
+ (`client/sessions.ts:326`, `:432-433`), whose per-party hash iterates over
184
+ `UTF8("signal-protocol-js composite safety number v1") ‖ type-tagged user ID ‖
185
+ SHA-256 identity commitment` (`safety/core.ts:48-50`, `:205-233`). None of that
186
+ input exists in `libsignal`'s construction ([`fingerprint.rs:161-192`][fp]).
187
+
188
+ **The identity material differs.** Even the raw input is a 67-byte two-key tuple
189
+ rather than a 33-byte `0x05 ‖ X25519` key.
190
+
191
+ **The two halves are ordered by a different rule.** This one applies even on the
192
+ SDK's low-level single-key path, which is otherwise byte-identical to
193
+ `libsignal`. The SDK orders by user identifier — `localId.localeCompare(remoteId)`
194
+ (`safety/core.ts:177`) — where `libsignal` orders by the encoded digit strings
195
+ themselves ([`fingerprint.rs:32-40`][fp]). Both rules are symmetric, so the two
196
+ parties always agree with each other; they simply do not agree with Signal Messenger, and
197
+ roughly half the time the halves come out in the opposite order. `localeCompare`
198
+ is additionally locale-sensitive, so two devices with different default locales
199
+ can in principle disagree with each other on the ordering of the same pair of
200
+ user IDs.
201
+
202
+ What *is* faithful: the iteration is byte-for-byte `libsignal`'s — 5200
203
+ iterations of SHA-512 over `0x0000 ‖ key ‖ id`, then `hash ‖ key`
204
+ (`safety/core.ts:138-143` vs [`fingerprint.rs:170-189`][fp]) — as is the digit
205
+ encoding (six 5-byte big-endian chunks mod 100000, 30 digits per party) and the
206
+ scannable-fingerprint protobuf layout (`safety/protobuf.ts:94-109`). The
207
+ cross-verification swap and constant-time comparison match as well.
208
+
209
+ The QR format version is the SDK's own: `3` for the composite path
210
+ (`safety/core.ts:46`), where `libsignal` knows only versions 1 and 2 and returns
211
+ `VersionMismatch` for anything else. Using a distinct version in the same
212
+ protobuf namespace is the correct fail-closed choice — a Signal Messenger client rejects
213
+ the code rather than misreading it.
214
+
215
+ The SDK also offers an emoji fingerprint (`safety/core.ts:308-392`) and
216
+ verification deep links (`safety/url.ts`). Both are extensions with no
217
+ `libsignal` counterpart. Note that the emoji form is derived from one party's
218
+ fingerprint only, so it carries roughly half the information of the 60-digit
219
+ number and should not be presented to users as an equal-strength alternative.
220
+
221
+ ### 1.4 Registration ID range
222
+
223
+ Registration IDs are generated in the closed range `[1, 16383]`
224
+ (`keys/generation.ts:43-46`). The wire format reserves exactly 14 bits, and
225
+ `libsignal` rejects any ID where `id & 0x3FFF != id`
226
+ ([`sealed_sender.rs:1508-1515`][ss]); `libsignal`'s own helper generates `[1, 16380]`.
227
+
228
+ Through 0.1.0-alpha.3 the range was `[1, 16384]`, an off-by-one: 16384 is
229
+ `0x4000` and does not fit in 14 bits, and the SDK's multi-recipient sealed sender
230
+ encoder masks rather than rejects
231
+ (`internal/protocol/sealed-sender/v2-binary.ts:170-171`), so a generated `16384`
232
+ was written to the wire as `0` — roughly 1 install in 16,384. This is corrected
233
+ as of 0.1.0-alpha.4; the generated range is now strictly narrower than
234
+ `libsignal`'s accepted range, and a regression test asserts every generated ID
235
+ survives the mask unchanged.
236
+
237
+ ---
238
+
239
+ ## 2. X3DH and PQXDH
240
+
241
+ The key agreement is the most faithful area in the codebase. The DH computation
242
+ order, the 32-byte `0xFF` discontinuity prefix, the zero-filled HKDF salt, the
243
+ single-step derivation over the full concatenation, the position of the KEM
244
+ shared secret (appended last), and the 96-byte output split all match
245
+ `libsignal` exactly.
246
+
247
+ - Initiator DH order `DH(IK_A,SPK_B)`, `DH(EK_A,IK_B)`, `DH(EK_A,SPK_B)`,
248
+ `DH(EK_A,OPK_B)`: `internal/protocol/pqxdh/pqxdh.ts:243-264` vs
249
+ [`pqxdh.rs:202-224`][pq]. Spec X3DH §3.3.
250
+ - `F = 0xFF × 32` prefix: `internal/protocol/pqxdh/pqxdh.ts:267-271` vs
251
+ [`pqxdh.rs:200`][pq]. Spec X3DH §2.2.
252
+ - KEM secret appended after all DH outputs, then one HKDF:
253
+ `internal/protocol/pqxdh/pqxdh.ts:365-374` vs [`pqxdh.rs:226-230`][pq]. Spec
254
+ PQXDH §3.3.
255
+
256
+ Two hardening extensions go beyond the specification at no interop cost: every
257
+ remote X25519 point is validated before any DH is computed
258
+ (`internal/protocol/pqxdh/pqxdh.ts:219-227`), and prekey bundles are validated
259
+ far more strictly than `libsignal` requires
260
+ (`internal/session/handshake.ts:107-138`).
261
+
262
+ ### 2.1 ML-KEM-1024 runs under an info string naming Kyber
263
+
264
+ The SDK uses ML-KEM-1024 (FIPS 203) where `libsignal` uses round-3 Kyber1024,
265
+ tagged `0x0A` rather than `0x08` (`internal/crypto/pq/kyber.ts:79`). That much is
266
+ deliberate: the standardized algorithm is preferred over the round-3 draft, and a
267
+ single unambiguous tag is preferred over carrying a legacy fallback.
268
+
269
+ The info string was not updated to match (`types/protocol-config.ts:365`):
270
+
271
+ ```text
272
+ WhisperText_X25519_SHA-256_CRYSTALS-KYBER-1024
273
+ ```
274
+
275
+ This is byte-identical to `libsignal`'s label ([`pqxdh.rs:73-74`][pq]) while
276
+ naming a KEM the SDK does not use. Two consequences:
277
+
278
+ 1. **It violates the SDK's own pinned specification.** PQXDH §2.2 requires the
279
+ info string to be the concatenation of the four PQXDH parameters *including
280
+ the actual `pqkem`*. The running `pqkem` is ML-KEM-1024; the string says
281
+ CRYSTALS-KYBER-1024.
282
+ 2. **It removes the domain separation that would make the incompatibility
283
+ self-evident.** Two implementations feeding the identical label derive
284
+ different shared secrets, because the KEM underneath differs. A label naming
285
+ ML-KEM-1024 would make the non-interoperability explicit at the KDF layer.
286
+
287
+ Changing the label to name ML-KEM-1024 would satisfy §2.2 and improve the
288
+ situation. It is a pre-1.0 format break, and is flagged rather than fixed here.
289
+
290
+ ### 2.2 Associated data binds identity commitments
291
+
292
+ X3DH §3.3 specifies `AD = Encode(IK_A) ‖ Encode(IK_B)`, and `libsignal`
293
+ implements exactly that with raw 33-byte serialized keys
294
+ ([`protocol.rs:225-241`][proto]).
295
+
296
+ The SDK computes (`internal/session/identity-binding.ts:11-25`):
297
+
298
+ ```text
299
+ HMAC-SHA256(mac_key,
300
+ UTF8("signal-protocol-js composite identity message mac v1")
301
+ || SHA-256 commitment to sender's composite identity
302
+ || SHA-256 commitment to receiver's composite identity
303
+ || version byte || protobuf bytes
304
+ )[0..8]
305
+ ```
306
+
307
+ **Why.** With a two-key identity, an `AD` over the DH key alone would leave the
308
+ Ed25519 signing component unbound — the component that authenticates every prekey
309
+ the peer will ever publish. Hashing the commitment covers both.
310
+
311
+ **Cost.** This is the single largest wire deviation in the message path. The
312
+ truncation to 8 bytes matches `libsignal`'s convention, and the construction is sound
313
+ and domain-separated, but a Signal Messenger client and this SDK cannot exchange a single
314
+ message.
315
+
316
+ ### 2.3 One-time prekey deletion is deferred
317
+
318
+ PQXDH §3.4 has Bob delete a used one-time prekey after successful decryption. The
319
+ SDK records a pending deletion (`internal/manager/manager.ts:940-952`) and
320
+ commits it only once a prekey message decrypts
321
+ (`internal/session/cipher.ts:1189-1200`). This is compliant in letter and widens
322
+ the window in which the same first ciphertext can be replayed before commit;
323
+ duplicate and missing-prekey conditions are refused auto-recovery
324
+ (`internal/session/cipher.ts:1519-1527`).
325
+
326
+ ### 2.4 Ratchet initialization details
327
+
328
+ Two differences at the boundary between key agreement and the ratchet:
329
+
330
+ **Alice reuses her key-agreement ephemeral as her first ratchet key**
331
+ (`internal/session/builder.ts:159-171`). `libsignal` generates a fresh sending
332
+ ratchet key distinct from the handshake ephemeral ([`ratchet.rs:77-81`][rat]), so
333
+ the prekey message's base key and the first message's ratchet key differ. Here
334
+ they are the same value. No concrete attack follows, but it is a reduction in key
335
+ separation and it is wire-visible.
336
+
337
+ **Bob initializes without a sending chain** (`internal/session/builder.ts:326-364`),
338
+ deriving chains on the first DH ratchet, where `libsignal` seeds a sending chain
339
+ immediately ([`ratchet.rs:137-172`][rat]). A side effect is that bytes 32–64 of
340
+ the 96-byte derivation — the initial chain key — never produce a message key on
341
+ either side. The 96-byte split is retained for shape compatibility, but only the
342
+ root key and the SPQR key are load-bearing.
343
+
344
+ ### 2.5 Classical fallback is retained but gated
345
+
346
+ `libsignal` has removed X3DH entirely and rejects pre-Kyber prekey messages
347
+ ([`session.rs:105-112`][sess]). The SDK keeps the X3DH path reachable only via an
348
+ explicit opt-in; the default is fail-closed, and any PQXDH failure raises rather
349
+ than silently downgrading (`internal/session/handshake.ts:167-260`). This is a
350
+ downgrade surface that `libsignal` has closed, and it is documented in
351
+ [Protocol Policy](./PROTOCOL_POLICY.md).
352
+
353
+ ---
354
+
355
+ ## 3. Double Ratchet and wire format
356
+
357
+ ### 3.1 The ratchet core is faithful
358
+
359
+ Byte-for-byte with `libsignal`: the `0x01`/`0x02` chain-key seeds
360
+ (`internal/crypto/kdf/hkdf.ts:183-195` vs [`keys.rs:148-149`][rk]), the
361
+ `WhisperMessageKeys` expansion to 80 bytes split 32/32/16
362
+ (`internal/crypto/kdf/hkdf.ts:215-243` vs [`keys.rs:100-118`][rk]), the
363
+ `WhisperRatchet` root-key step producing a 64-byte split
364
+ (`internal/crypto/kdf/hkdf.ts:141-161` vs [`keys.rs:199-218`][rk]), the DH ratchet
365
+ half-step ordering, `MAX_RECEIVER_CHAINS = 5`, AES-256-CBC with PKCS#7, the
366
+ `0x44` version byte, and 8-byte MAC truncation.
367
+
368
+ Message framing matches too: `[version byte] ‖ protobuf ‖ [8-byte HMAC]` for
369
+ messages and `[version byte] ‖ protobuf` for prekey messages
370
+ (`internal/encoding/proto/envelope.ts:104-168`). What goes *into* the MAC does
371
+ not — see §2.2.
372
+
373
+ Protobuf fields 1–8 match [`wire.proto`][wp] exactly, including `libsignal`'s
374
+ non-obvious ordering where `registrationId` is field 5 and `signedPreKeyId` is
375
+ field 6.
376
+
377
+ ### 3.2 Added fields and address binding
378
+
379
+ **Extension.** The SDK adds fields in the 100+ range that `libsignal` does not
380
+ have: `recipientIdentityType` on both message types, and `kemOneTimePreKeyId` /
381
+ `kemOneTimeCiphertext` on prekey messages
382
+ (`internal/encoding/proto/signal-message.ts:80`, `:226-228`). High numbering
383
+ avoids collision with future upstream fields. A Signal Messenger client would parse the
384
+ message and silently ignore them, losing the identity-type binding.
385
+
386
+ **Deviation.** `libsignal` binds addresses as a 17-byte fixed-width ServiceId plus
387
+ a 1-byte device ID ([`protocol.rs:246-260`][proto]). The SDK binds a
388
+ format-version byte, a varint-length-prefixed UTF-8 user ID, and a 4-byte
389
+ big-endian device ID (`internal/encoding/proto/signal-message.ts:84-92`). The
390
+ encoding is unambiguous, but it authenticates an application-defined identifier
391
+ rather than a Signal Messenger ACI or PNI — which is the correct thing for this SDK to bind
392
+ and an incompatible thing to put on the wire.
393
+
394
+ The SDK is also stricter than `libsignal` on decode, requiring fields that
395
+ `libsignal` treats as optional for backward compatibility and enforcing exact
396
+ lengths (`internal/encoding/proto/signal-message.ts:332-340`, `:488-505`). Safer,
397
+ and one more reason the formats cannot meet.
398
+
399
+ ### 3.3 Skipped-key retention is materially tighter than libsignal's
400
+
401
+ The constants match — `MAX_MESSAGE_KEYS = 2000`, `MAX_FORWARD_JUMPS = 25000`
402
+ (`internal/protocol/double-ratchet/ratchet.ts:194-227` vs [`consts.rs:8-9`][consts])
403
+ — but they are applied differently, and the difference is user-visible.
404
+
405
+ **The cap is global, not per-chain.** `libsignal` applies 2000 to each chain's key
406
+ vector ([`double_ratchet.rs:349-361`][dr]), so with five receiver chains the true
407
+ system capacity is 10,000 skipped keys. The SDK counts across all chains and
408
+ evicts when the total reaches 2000
409
+ (`internal/protocol/double-ratchet/chains.ts:478-513`). The effective capacity is
410
+ 5× smaller, and traffic on a newer chain can evict keys belonging to an older one.
411
+
412
+ **Eviction is by wall-clock timestamp**, scanning every chain for the oldest
413
+ entry (`internal/protocol/double-ratchet/chains.ts:414-463`), where `libsignal`
414
+ evicts strictly by insertion position. `Date.now()` is not monotonic, so eviction
415
+ order is not deterministic across clock adjustments.
416
+
417
+ **Skipped keys expire after 7 days**
418
+ (`internal/protocol/double-ratchet/ratchet.ts:197`). `libsignal` has no
419
+ time-based expiry for message keys at all.
420
+
421
+ Taken together: **there are message-delivery patterns where this SDK reports an
422
+ undecryptable message and `libsignal` would have decrypted it.** A recipient
423
+ offline for more than a week, or one receiving heavy traffic on a new chain while
424
+ older-chain messages are still in flight, can lose messages that the
425
+ specification's own limits would have preserved. The bounds are defensible as
426
+ storage hygiene; the consequence should not be a surprise.
427
+
428
+ Two related extensions: a `processedChains` map rejects messages bearing a ratchet
429
+ key from an already-retired chain (`internal/protocol/double-ratchet/ratchet.ts:141-153`),
430
+ closing a replay gap that `libsignal` handles only via its five-chain window; and
431
+ self-sessions get a finite 100,000-message skip limit
432
+ (`internal/session/validation.ts:453-461`) where `libsignal` uses `usize::MAX`.
433
+
434
+ ### 3.4 Session archiving and serialization
435
+
436
+ The cap matches (40 archived states, [`consts.rs:11`][consts]), but the structure
437
+ differs. `libsignal` keeps an ordered list with strict insertion-order eviction
438
+ ([`session.rs:787-830`][st]); the SDK keeps a map keyed by base key and trims by
439
+ `lastUsedAt` (`types/session.ts:815-847`). Archiving a session whose base key
440
+ already exists overwrites rather than appends, so the effective history can be
441
+ shorter than 40.
442
+
443
+ `libsignal` clears unacknowledged prekey state before archiving a session; the SDK
444
+ does not. Retired sessions therefore keep pending prekey references alive in
445
+ storage.
446
+
447
+ **Session records serialize as JSON, not protobuf** (`types/session.ts:1002-1028`).
448
+ This is acknowledged in the source as a simplicity and debuggability choice.
449
+ Consequences worth naming: stored sessions are not portable to or from any Signal Messenger
450
+ client, and key material sits in immutable JavaScript strings that cannot be
451
+ zeroed, where `libsignal`'s byte vectors can be.
452
+
453
+ ### 3.5 Padding
454
+
455
+ **Extension.** Message plaintext is padded to 160-byte buckets with ISO 7816-4 bit
456
+ padding — a `0x80` terminator followed by zeros
457
+ (`internal/crypto/symmetric/padding.ts:19-60`). Unpadding scans backwards and
458
+ rejects malformed padding with a deliberately generic error to avoid a padding
459
+ oracle.
460
+
461
+ `libsignal` does not bucket-pad at this layer; in Signal Messenger, that lives in the client
462
+ applications. Doing it in the library means length hiding is on by default rather
463
+ than a thing each integrator must remember.
464
+
465
+ One imprecision: because the padded plaintext is an exact multiple of 160 and
466
+ AES-CBC then applies PKCS#7, a full block is always appended. A 5-byte message
467
+ produces 160 padded bytes and 176 ciphertext bytes. Length is still quantized in
468
+ 160-byte steps, so the hiding property holds; the ciphertext simply sits 16 bytes
469
+ past each boundary rather than on it.
470
+
471
+ ---
472
+
473
+ ## 4. SPQR and the ML-KEM Braid
474
+
475
+ This is the same protocol as the SparsePostQuantumRatchet v1 protocol, implemented
476
+ independently and pinned against `SparsePostQuantumRatchet v1.5.1` (commit
477
+ `f2589fef`). The fidelity is high and specific:
478
+
479
+ - **KDF labels are byte-identical**, including the double space in
480
+ `"Signal PQ Ratchet V1 Chain Start"` (`internal/crypto/kdf/hkdf.ts:353-368`).
481
+ - **The authenticator construction matches**, including `PROTOCOL_INFO =
482
+ "Signal_PQCKA_V1_MLKEM768"` and the `:ekheader` / `:ciphertext` MAC inputs
483
+ (`internal/protocol/spqr/ml-kem-braid/kdf.ts:32-92`).
484
+ - **The Reed–Solomon erasure layer matches**: GF(2^16) with primitive polynomial
485
+ `0x1100b`, 32-byte chunks, 16 polynomials, degree bound 35. Reed–Solomon is
486
+ present in `libsignal`; it is not an SDK addition.
487
+ - **The production wire framing is byte-compatible**:
488
+ `VERSION ‖ LEB128(epoch) ‖ LEB128(chain_index) ‖ MSG_TYPE ‖ [LEB128(chunk_index) ‖ CHUNK]`
489
+ (`internal/encoding/proto/pq-ratchet-serialize.ts`), matching `libsignal`'s
490
+ `serialize.rs`, with the same message-type values and the same epoch offset.
491
+ - **ML-KEM-768 with the same incremental split** (32-byte seed, 1152-byte vector,
492
+ 960/128-byte ciphertext parts).
493
+
494
+ ### 4.1 The `hek` operand order diverges
495
+
496
+ One divergence breaks interoperability completely. The SDK computes
497
+ (`internal/protocol/spqr/ml-kem-braid/noble-pq/index.ts:841-843`):
498
+
499
+ ```text
500
+ hek = SHA3-256(ek_seed || ek_vector)
501
+ ```
502
+
503
+ `libsignal`, via libcrux, builds the encapsulation key as
504
+ `t̂ ‖ ρ` before hashing — the reverse order.
505
+
506
+ The SDK follows the **normative text of the published ML-KEM Braid
507
+ specification**, which states seed-first ordering. `libsignal` follows FIPS 203,
508
+ which serializes vector-first. The specification and the reference implementation
509
+ disagree, and the SDK chose the specification.
510
+
511
+ The value feeds the Fujisaki–Okamoto transform, so the consequences cascade:
512
+ different header bytes, so `libsignal`'s header validation rejects the SDK's output;
513
+ different ciphertext; different shared secret; different epoch secret; different
514
+ authenticator ratchet. **A braid session between this SDK and Signal Messenger's
515
+ implementation cannot complete a single epoch.**
516
+
517
+ Two further consequences a reader should not have to infer:
518
+
519
+ - **In braid mode the KEM is not FIPS 203 ML-KEM-768.** It is ML-KEM-768 with a
520
+ modified `hek` derivation. The security argument is unaffected — the hash input
521
+ is a permutation of the same material — but a FIPS conformance claim would not
522
+ hold for this path. Direct (non-braid) mode uses stock ML-KEM-768.
523
+ - The SDK resolves the same spec-versus-code conflict in the *opposite* direction
524
+ elsewhere: for `KDF_AUTH`, it follows the `libsignal` Rust reference rather than the
525
+ written specification. The two choices are individually defensible and
526
+ collectively inconsistent about which artifact is authoritative.
527
+
528
+ The operand order is part of the public compatibility boundary stated in
529
+ [Protocol Policy](./PROTOCOL_POLICY.md). Changing it later would invalidate every
530
+ braid session persisted under the former ordering.
531
+
532
+ ### 4.2 Direct mode and state format
533
+
534
+ **Extension.** An opt-in direct mode (`protocol.braid: 'disabled'`) uses stock
535
+ ML-KEM-768 and adds wire message types `0x80`–`0x82`
536
+ (`internal/encoding/proto/pq-ratchet-serialize.ts:38-45`). `libsignal`'s parser rejects
537
+ anything above `6`, so these are visible only within the SDK; they occupy a byte
538
+ range `libsignal` has not claimed. This mode has no Signal Protocol analogue.
539
+
540
+ **Independent design.** Persisted SPQR state uses a flat message with 20 fields
541
+ where `libsignal` uses an 11-variant `oneof` over nested structures. Serialized SPQR
542
+ state is not portable in either direction.
543
+
544
+ **Deviation.** Skipped-key eviction in the SPQR chain triggers at the cap and
545
+ evicts by wall-clock timestamp, where `libsignal` triggers at `max_ooo × 11/10 + 1` and
546
+ evicts by message index. `libsignal`'s rule is deterministic and index-anchored; the
547
+ SDK's introduces a clock dependency into ratchet state.
548
+
549
+ ### 4.3 The Triple Ratchet is faithful
550
+
551
+ The post-quantum secret enters as the HKDF **salt** at message-key expansion, with
552
+ the classical message key as IKM and the `WhisperMessageKeys` label
553
+ (`internal/session/cipher.ts:453-510`) — the same combination order and the same
554
+ label as [`triple_ratchet.rs`][tr]. There is no root-key braiding in either
555
+ implementation.
556
+
557
+ Note that `internal/protocol/triple-ratchet/` contains a second, unused hybrid KDF
558
+ using the label `'Signal Triple Ratchet V1'`. It is exported but not called from
559
+ the message path, and it is incompatible with what the SDK actually puts on the
560
+ wire. It is documented in the PR that accompanied this file as cleanup work.
561
+
562
+ ---
563
+
564
+ ## 5. Sesame
565
+
566
+ Sesame has no reference implementation to compare against — `libsignal` does not
567
+ implement it; device and session management lives in the Signal Messenger service and its
568
+ clients. Everything below is measured against the pinned specification text
569
+ (revision 2) alone.
570
+
571
+ Faithful: the user-record and device-record structure (§3.1), the per-device
572
+ session fan-out on send including the sender's own other devices (§3.3), the
573
+ bounded send loop (§3.3, §6.5), discard-all-changes-on-error handled
574
+ transactionally (§3.3, §3.4, §6.7), and creating a session on receive only from an
575
+ initiating message (§3.4). The per-user identity model is one of the two the
576
+ specification explicitly permits (§3.1).
577
+
578
+ ### 5.1 Deleted devices are removed rather than marked stale
579
+
580
+ §3.1 and §3.3 require a removed device's record to be marked stale and retained
581
+ for MAXLATENCY, so that messages already in flight from that device still
582
+ decrypt. The SDK removes the record immediately
583
+ (`internal/sesame/manager.ts:2098-2102`).
584
+
585
+ **Consequence, stated plainly: a message sent by a device that was removed moments
586
+ earlier becomes permanently undecryptable.** The specification's staleness window
587
+ exists precisely to prevent this. This is the most substantive contradiction of
588
+ the Sesame text in the codebase.
589
+
590
+ Relatedly, the SDK reuses the word `stale` for a different concept — a device
591
+ *list* that needs refetching (`internal/sesame/types.ts:476-483`) — rather than
592
+ the specification's meaning of a deleted user or device.
593
+
594
+ ### 5.2 Session expiry applies only to unacknowledged sessions
595
+
596
+ §4.2 is unconditional: at MAXSEND past its timestamp, a session must no longer be
597
+ used for encryption. The SDK applies that bound only to sessions that have never
598
+ received a reply (`internal/sesame/types.ts:175-199`). A session that received one
599
+ message on its first day remains a valid encryption session indefinitely.
600
+
601
+ The configuration field is honestly renamed to `maxUnacknowledgedSessionAge` to
602
+ reflect this. The gap worth naming is that the §4.2 invariant check
603
+ (`internal/sesame/validation.ts:93-101`) is still validated against that renamed
604
+ quantity, so it is enforcing the specification's arithmetic over a value that no
605
+ longer carries the specification's meaning.
606
+
607
+ ### 5.3 Device limit
608
+
609
+ A hard cap of 5 devices per user (`internal/sesame/types.ts:45-50`, enforced at
610
+ `internal/sesame/manager.ts:285-290`). §6.5 recommends *a* limit without fixing
611
+ one; `libsignal` permits device IDs up to 127. This is a product decision, and a
612
+ source comment attributing it to the Signal Protocol is inaccurate.
613
+
614
+ ### 5.4 Extensions: provisioning, transfer, device names
615
+
616
+ None of these exist in Sesame rev. 2, which says nothing about how devices come to
617
+ exist, are named, or migrate.
618
+
619
+ **QR device provisioning** (`device/provisioning.ts`). Ephemeral X25519 ECDH →
620
+ HKDF → AES-256-GCM, with a `signalprotocol://link-device` QR scheme, strict prefix
621
+ and key validation, a 5-minute TTL, and rollback on both server and local failure.
622
+ The construction is sound. The property worth naming: the provisioning key is not
623
+ bound to the primary device's long-term identity, so the channel is authenticated
624
+ only by out-of-band display of the QR code.
625
+
626
+ **Device transfer** (`device/transfer.ts`). Clones the identity private key and
627
+ live ratchet state to a new device. This is useful and it **violates the
628
+ invariant Sesame is built on** — one device record, one device, its own sessions.
629
+ After a transfer, two physical devices hold the same identity private key and the
630
+ same ratchet state for every peer. Peer messages decrypted by one desynchronize
631
+ the other, and duplicating ratchet state weakens the forward-secrecy guarantee
632
+ that compromise of one endpoint is bounded to that endpoint. Archived sessions are
633
+ deliberately dropped on restore, which also discards the convergence state §3.4
634
+ depends on.
635
+
636
+ **Encrypted device names** (`device/device-name-crypto.ts`). A three-field
637
+ protobuf with a synthetic IV derived by HMAC and AES-256-CTR — the standard SIV
638
+ pattern, correctly constructed. No specification counterpart.
639
+
640
+ **Identity-change gating.** Unseen identities are TOFU-pinned; a changed identity
641
+ sets `pendingVerification` and blocks sending until the application accepts the
642
+ rotation (`internal/sesame/manager.ts:561-566`, `:1682-1714`). Sesame rev. 2 has
643
+ no such concept. This is a genuine improvement.
644
+
645
+ **Not implemented:** proof of possession. Device registration does not require the
646
+ device to sign a server-issued nonce with the identity private key, so
647
+ registration places more trust in the relay than §6.3's discussion assumes. A
648
+ deployment that needs this must add it at the application layer.
649
+
650
+ ---
651
+
652
+ ## 6. Sealed sender
653
+
654
+ ### 6.1 Version 2 is faithful
655
+
656
+ All four HKDF labels are byte-identical, the KEM construction and its
657
+ direction-swapped IKM orderings match, the authentication tag is the same 16-byte
658
+ raw HKDF output, AES-256-GCM-SIV is used with a zero nonce and no AAD as
659
+ `libsignal` does, and the multi-recipient binary format — version bytes
660
+ `0x22`/`0x23`, varint count, 17-byte ServiceIds, the packed device ID and 14-bit
661
+ registration ID, the `0x3FFF` mask — matches ([`sealed_sender.rs:1023-1153`][ss],
662
+ `:1306-1360`). Certificate validation order and semantics match as well, including
663
+ the non-short-circuiting trust-root loop that avoids revealing which root
664
+ validated.
665
+
666
+ ### 6.2 Version 1 diverges in three places
667
+
668
+ **The 96-byte HKDF output is split in a different order.** `libsignal` derives
669
+ `(chain_key, cipher_key, mac_key)` ([`sealed_sender.rs:711-746`][ss]); the SDK
670
+ derives `(cipher, mac, chain)`
671
+ (`internal/protocol/sealed-sender/encryption.ts:164-166`). The construction is
672
+ self-consistent and secure — the keys are independent HKDF output either way — but
673
+ every v1 key sits in a different slot than `libsignal`'s. This is an
674
+ implementation divergence rather than a design decision, and the SDK's own pinned
675
+ specification document records the same order, so the two are at least consistent
676
+ with each other.
677
+
678
+ **Public keys in the v1 salt and in certificates omit the `0x05` type byte.**
679
+ `libsignal` uses the 33-byte serialized form; the SDK uses raw 32 bytes and
680
+ enforces that length
681
+ (`internal/protocol/sealed-sender/certificate.ts:306-309`). Notably the SDK's own
682
+ v2 path *does* apply the `0x05` prefix, so the two sealed-sender versions are
683
+ internally inconsistent about this.
684
+
685
+ **The inner envelope is a hand-rolled varint format**
686
+ (`internal/protocol/sealed-sender/encryption.ts:46-86`) rather than the
687
+ `UnidentifiedSenderMessage.Message` protobuf. It omits the message-type field that
688
+ `libsignal` uses to dispatch between prekey and regular messages
689
+ ([`sealed_sender.rs:2055-2075`][ss]); the unseal path reconstructs the envelope
690
+ with a fixed type instead.
691
+
692
+ ### 6.3 The delivery token follows `libsignal`, not an SDK invention
693
+
694
+ Despite the module name, `deriveAccessKey`
695
+ (`internal/protocol/sealed-sender/delivery-token.ts:52-91`) is `libsignal`'s
696
+ `ProfileKey::derive_access_key` — AES-256-GCM over 16 zero bytes with a zero
697
+ nonce, truncated to 16 bytes — and it reproduces the values `libsignal`
698
+ publishes for that derivation. It is a 16-byte value derived from the
699
+ recipient's profile key
700
+ that proves to the relay that the sender knows that profile key, gating anonymous
701
+ delivery to contacts. It never enters the sealed-sender wire format; it is
702
+ presented out of band.
703
+
704
+ The SDK's own documentation previously described a different, 12-byte HKDF
705
+ construction that no code implements. That description is wrong and is corrected
706
+ in the PR accompanying this file.
707
+
708
+ Certificate signatures use Ed25519 rather than XEdDSA, per §1.2, so SDK
709
+ certificates cannot validate against a Signal Messenger trust root or vice versa. The
710
+ revocation list is empty where `libsignal` revokes one key ID, which is
711
+ appropriate for a different trust root but worth noting.
712
+
713
+ ---
714
+
715
+ ## 7. Sender keys and groups
716
+
717
+ ### 7.1 Sender key message format
718
+
719
+ Protobuf field numbers and types match [`wire.proto`][wp] exactly, the
720
+ `[version byte] ‖ protobuf ‖ [64-byte signature]` framing with version `0x33`
721
+ matches, the `0x01`/`0x02` chain seeds and the `WhisperGroup` info string match,
722
+ AES-256-CBC with the derived IV matches, and the capacity constants match.
723
+
724
+ Three things do not:
725
+
726
+ **`distributionUuid` carries a UTF-8 string, not 16 UUID bytes.** The SDK writes
727
+ `groupId:userId:deviceId:timestamp`
728
+ (`internal/protocol/sender-keys/manager.ts:266`, `:493`); `libsignal` writes
729
+ exactly 16 raw bytes and rejects anything else on parse. Related: `chain_id` is
730
+ an FNV-1a hash of that string rather than a random 31-bit value.
731
+
732
+ **Signatures are Ed25519, not XEdDSA**, per §1.2 — and `libsignal` serializes the
733
+ signing key as 33 bytes where the SDK uses 32.
734
+
735
+ ### 7.2 Message-key derivation omits HKDF-Extract
736
+
737
+ This one is worth stating precisely because the field numbers and labels above
738
+ make the format look compatible.
739
+
740
+ `libsignal` derives sender message keys with
741
+ `Hkdf::<Sha256>::new(None, &seed).expand(b"WhisperGroup", 48)`
742
+ ([`sender_keys.rs:36-38`][sk]). `Hkdf::new` performs HKDF-**Extract** first:
743
+ `PRK = HMAC-SHA256(salt = zeros[32], seed)`. Only then does it expand.
744
+
745
+ The SDK calls `hkdfExpand(seed, info, 48)` directly
746
+ (`internal/protocol/sender-keys/manager.ts:1062-1066`), where `hkdfExpand`
747
+ (`internal/crypto/kdf/hkdf.ts:86-116`) is pure RFC 5869 Expand using the seed
748
+ itself as the PRK. The extract step is missing.
749
+
750
+ The derived IV and cipher key therefore differ from `libsignal`'s for the same
751
+ chain key. This was confirmed numerically, not merely by inspection: for a chain
752
+ key of 32 repeated `0x42` bytes, the SDK derives IV
753
+ `2a56b9eb80b3c1ffebd97221b2175960` where `libsignal` derives
754
+ `890d51ea73e564722351dc0d5a09142c`.
755
+
756
+ This appears unintentional. It is not a weakness — omitting Extract from a
757
+ uniformly random HMAC output is cryptographically fine — but the repository's own
758
+ sender-keys note claims equivalence with `libsignal` at this step, and that claim
759
+ is incorrect. Flagged for correction.
760
+
761
+ ### 7.3 Groups v2 is an independent design
762
+
763
+ The zero-knowledge primitives underneath are real and faithful (§7.4). The group
764
+ system built on them is not the Signal Private Group System.
765
+
766
+ What is faithful: role and access-control enum values match `libsignal`'s exactly,
767
+ group ID derivation from the master key is correct, the `__signal_group__v2__!`
768
+ identifier encoding follows `libsignal`, authentication genuinely uses zkgroup
769
+ credentials, and member identifiers and profile keys are encrypted with real
770
+ `UidCiphertext` and `ProfileKeyCiphertext`.
771
+
772
+ What differs, and it is structural:
773
+
774
+ **The client is the state authority.** The SDK's client applies a change,
775
+ re-encrypts the entire group state, and uploads it
776
+ (`internal/groups-v2/manager.ts:1176-1193`). Signal Messenger's client submits only a set of
777
+ change actions, each carrying zero-knowledge presentations, and the **server**
778
+ validates every action and signs the result.
779
+
780
+ **Consequence, stated plainly: the relay cannot validate group changes.** It can
781
+ compare an expected version number and nothing else. It cannot verify that the
782
+ member making a change was permitted to make it, because the change actions carry
783
+ no zero-knowledge presentations for it to check. Any authenticated member can
784
+ rewrite roles, membership, and the ban list. Server signatures are returned but
785
+ never verified on receipt.
786
+
787
+ This is a materially weaker trust model than the Signal Private Group System, and
788
+ anyone deploying group messaging on this SDK needs to know it: group membership
789
+ and roles are enforced by cooperating clients, not by the server, and not
790
+ cryptographically against a malicious member. It is a reasonable position for an
791
+ SDK that ships without a validating server component, and it is not what a reader
792
+ of the Signal Private Group System documentation would assume.
793
+
794
+ **Serialization is JSON**, not protobuf, both for group state
795
+ (`internal/groups-v2/manager.ts:1229-1236`) and for the blob payloads inside the
796
+ AES-256-GCM-SIV envelope (`internal/groups-v2/encrypted-state.ts:70-81`). Every
797
+ encrypted group title and description is undecryptable by Signal Messenger even with the
798
+ correct master key.
799
+
800
+ **Invite links** use `https://join.open-e2ee.dev/#` with a 49-byte raw payload
801
+ (`internal/groups-v2/invite-link.ts:36`, `:78-85`), where `libsignal` uses
802
+ `https://signal.group/#` with a protobuf. This is labelled accurately in source as
803
+ the package's own format.
804
+
805
+ ### 7.4 The zero-knowledge layer is a faithful port
806
+
807
+ Stated directly, because "zk" in a codebase often means something weaker: this is
808
+ a genuine zero-knowledge credential system, not HMAC tokens, not signatures, not a
809
+ placeholder.
810
+
811
+ `internal/protocol/zk/` implements the Sigma protocol over Ristretto255 with
812
+ Fiat–Shamir, matching `poksho`'s protocol label
813
+ `POKSHO_Ristretto_SHOHMACSHA256` exactly, and the Chase–Perrin–Zaverucha algebraic
814
+ MAC credential system matching `zkcredential`'s five domain labels byte for byte.
815
+ The Lizard encoding, `UidStruct` derivation, `AuthCredentialWithPni` flow, and
816
+ redemption window all match `libsignal`. The strongest evidence is a test that
817
+ asserts the 416-byte serialized system parameters against a hex string taken from
818
+ `libsignal`'s own Rust test, and passes.
819
+
820
+ One deviation: server secret parameters are derived under four SDK-specific labels
821
+ rather than `libsignal`'s single seeded derivation
822
+ (`internal/protocol/zk/groups/server-params.ts:43-54`). The same randomness
823
+ therefore yields different server keys, and credentials are not interchangeable
824
+ with Signal Messenger's. That follows from the SDK being its own trust root.
825
+
826
+ Credential serialization is also ad hoc and carries no version byte, where
827
+ `libsignal` uses a leading version byte. That is a forward-compatibility gap
828
+ rather than a security one.
829
+
830
+ ---
831
+
832
+ ## Unverified and needs review
833
+
834
+ Listed rather than asserted, because these could not be confirmed in source
835
+ within this review.
836
+
837
+ - **Whether a sealed-sender-wrapped prekey message decrypts end to end.** The
838
+ unseal path reconstructs the envelope with a fixed message type
839
+ (`client/sealed-sender-ops.ts:263-265`), and an adjacent comment suggests the
840
+ Sesame layer re-derives the initiation state from the ciphertext. That path was
841
+ not traced and the integration tests were not executed. If Sesame does not
842
+ self-detect, first-contact sealed messages would be affected.
843
+ - **Whether the session-identity-key check the sealed-sender note requires is
844
+ enforced downstream.** The decrypt path compares the certificate's identity key
845
+ against the decrypted static key but does not consult the session store. In
846
+ `libsignal` the equivalent guarantee arrives later via the identity store.
847
+ - **Whether `@noble/post-quantum`'s ML-KEM-1024 is byte-identical to libcrux's.**
848
+ The repository claims pinned known-answer-test coverage; those tests were not
849
+ executed as part of this review.
850
+ - **Lizard encoding correctness against `libsignal`'s vectors.** The forward and
851
+ inverse Elligator maps are hand-implemented in TypeScript. Structure and labels
852
+ are correct and unit tests exist, but the outputs were not diffed against
853
+ `libsignal`'s. A subtle error here would silently corrupt every `UidStruct`.
854
+ - **SPQR state-machine transition equivalence.** State names, message types, and
855
+ chunk counts match `libsignal`'s; the eleven-state transition table was not diffed
856
+ transition by transition.
857
+ - **Whether the SPQR decoder enforces a bound on stored points.** `libsignal` caps
858
+ stored points per polynomial; no equivalent bound was located in the SDK's
859
+ decoder.
860
+ - **Whether SPQR state mutations are rolled back when message authentication
861
+ fails.** `libsignal` commits the new state only after the MAC and decryption
862
+ succeed; the SDK's receive path mutates state during decode, and the caller's
863
+ rollback behaviour was not traced.
864
+ - **Whether an equivalent of `libsignal`'s `promote_matching_session` exists.**
865
+ `libsignal` matches archived sessions on `(version, base key)`; the SDK's map is
866
+ keyed on base key alone.
867
+
868
+ ---
869
+
870
+ ## Reporting an error in this document
871
+
872
+ If something here is wrong — a citation that does not say what it is claimed to
873
+ say, a deviation that has since been fixed, or a deviation that is missing —
874
+ email security@open-e2ee.dev or open an issue. A deviations document that has
875
+ drifted from the code is worse than none, because it invites exactly the
876
+ assumption it exists to prevent.
877
+
878
+ [ik]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/identity_key.rs
879
+ [fp]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/fingerprint.rs
880
+ [sess]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/session.rs
881
+ [pq]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/pqxdh.rs
882
+ [rat]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/ratchet.rs
883
+ [rk]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/ratchet/keys.rs
884
+ [dr]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/double_ratchet.rs
885
+ [proto]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/protocol.rs
886
+ [wp]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/proto/wire.proto
887
+ [consts]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/consts.rs
888
+ [st]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/state/session.rs
889
+ [ss]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/sealed_sender.rs
890
+ [sk]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/sender_keys.rs
891
+ [tr]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/triple_ratchet.rs
892
+ [xeddsa]: https://signal.org/docs/specifications/xeddsa/