@open-e2ee/signal-protocol-sdk 0.4.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (255) hide show
  1. package/CHANGELOG.md +126 -5
  2. package/COMMERCIAL.md +1 -1
  3. package/README.md +10 -7
  4. package/SECURITY.md +2 -2
  5. package/THIRD_PARTY_NOTICES.md +1 -1
  6. package/device/README.md +7 -5
  7. package/dist/client/client.d.ts +3 -2
  8. package/dist/client/client.d.ts.map +1 -1
  9. package/dist/client/client.js +58 -25
  10. package/dist/client/client.js.map +1 -1
  11. package/dist/client/config.d.ts +46 -7
  12. package/dist/client/config.d.ts.map +1 -1
  13. package/dist/client/config.js +2 -2
  14. package/dist/client/config.js.map +1 -1
  15. package/dist/client/constants.d.ts +4 -2
  16. package/dist/client/constants.d.ts.map +1 -1
  17. package/dist/client/constants.js +4 -2
  18. package/dist/client/constants.js.map +1 -1
  19. package/dist/client/group-outbox.d.ts +38 -0
  20. package/dist/client/group-outbox.d.ts.map +1 -0
  21. package/dist/client/group-outbox.js +224 -0
  22. package/dist/client/group-outbox.js.map +1 -0
  23. package/dist/client/group-sealed-sender.d.ts +28 -0
  24. package/dist/client/group-sealed-sender.d.ts.map +1 -0
  25. package/dist/client/group-sealed-sender.js +74 -0
  26. package/dist/client/group-sealed-sender.js.map +1 -0
  27. package/dist/client/hosted-connection.d.ts +16 -0
  28. package/dist/client/hosted-connection.d.ts.map +1 -0
  29. package/dist/client/hosted-connection.js +255 -0
  30. package/dist/client/hosted-connection.js.map +1 -0
  31. package/dist/client/hosted-push.d.ts +57 -0
  32. package/dist/client/hosted-push.d.ts.map +1 -0
  33. package/dist/client/hosted-push.js +115 -0
  34. package/dist/client/hosted-push.js.map +1 -0
  35. package/dist/client/hosted-transport.d.ts +158 -0
  36. package/dist/client/hosted-transport.d.ts.map +1 -0
  37. package/dist/client/hosted-transport.js +926 -0
  38. package/dist/client/hosted-transport.js.map +1 -0
  39. package/dist/client/hosted.d.ts +223 -0
  40. package/dist/client/hosted.d.ts.map +1 -0
  41. package/dist/client/hosted.js +541 -0
  42. package/dist/client/hosted.js.map +1 -0
  43. package/dist/client/index.d.ts +5 -3
  44. package/dist/client/index.d.ts.map +1 -1
  45. package/dist/client/index.js +2 -0
  46. package/dist/client/index.js.map +1 -1
  47. package/dist/client/messages.d.ts.map +1 -1
  48. package/dist/client/messages.js +4 -5
  49. package/dist/client/messages.js.map +1 -1
  50. package/dist/client/relay-subscription.d.ts.map +1 -1
  51. package/dist/client/relay-subscription.js +37 -7
  52. package/dist/client/relay-subscription.js.map +1 -1
  53. package/dist/client/{sealed-sender-ops.d.ts → sealed-sender.d.ts} +39 -22
  54. package/dist/client/sealed-sender.d.ts.map +1 -0
  55. package/dist/client/sealed-sender.js +296 -0
  56. package/dist/client/sealed-sender.js.map +1 -0
  57. package/dist/client/signal-service-cipher.d.ts +23 -26
  58. package/dist/client/signal-service-cipher.d.ts.map +1 -1
  59. package/dist/client/signal-service-cipher.js +468 -706
  60. package/dist/client/signal-service-cipher.js.map +1 -1
  61. package/dist/client/types.d.ts +18 -3
  62. package/dist/client/types.d.ts.map +1 -1
  63. package/dist/client/types.js +6 -0
  64. package/dist/client/types.js.map +1 -1
  65. package/dist/device/index.d.ts +2 -2
  66. package/dist/device/index.d.ts.map +1 -1
  67. package/dist/device/index.js +1 -1
  68. package/dist/device/index.js.map +1 -1
  69. package/dist/device/transfer.d.ts +7 -43
  70. package/dist/device/transfer.d.ts.map +1 -1
  71. package/dist/device/transfer.js +31 -150
  72. package/dist/device/transfer.js.map +1 -1
  73. package/dist/device/types.d.ts +6 -47
  74. package/dist/device/types.d.ts.map +1 -1
  75. package/dist/device/types.js +1 -1
  76. package/dist/device/types.js.map +1 -1
  77. package/dist/index.d.ts +6 -5
  78. package/dist/index.d.ts.map +1 -1
  79. package/dist/index.js +2 -1
  80. package/dist/index.js.map +1 -1
  81. package/dist/internal/encoding/proto/pq-ratchet-serialize.js +1 -1
  82. package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
  83. package/dist/internal/encoding/proto/primitives.js +1 -1
  84. package/dist/internal/encoding/proto/primitives.js.map +1 -1
  85. package/dist/internal/groups/manager.d.ts +3 -3
  86. package/dist/internal/groups/manager.d.ts.map +1 -1
  87. package/dist/internal/groups/manager.js +5 -4
  88. package/dist/internal/groups/manager.js.map +1 -1
  89. package/dist/internal/protocol/sealed-sender/certificate.d.ts +10 -4
  90. package/dist/internal/protocol/sealed-sender/certificate.d.ts.map +1 -1
  91. package/dist/internal/protocol/sealed-sender/certificate.js +64 -7
  92. package/dist/internal/protocol/sealed-sender/certificate.js.map +1 -1
  93. package/dist/internal/protocol/sealed-sender/decryption.d.ts +34 -47
  94. package/dist/internal/protocol/sealed-sender/decryption.d.ts.map +1 -1
  95. package/dist/internal/protocol/sealed-sender/decryption.js +95 -182
  96. package/dist/internal/protocol/sealed-sender/decryption.js.map +1 -1
  97. package/dist/internal/protocol/sealed-sender/encryption.d.ts +49 -64
  98. package/dist/internal/protocol/sealed-sender/encryption.d.ts.map +1 -1
  99. package/dist/internal/protocol/sealed-sender/encryption.js +120 -123
  100. package/dist/internal/protocol/sealed-sender/encryption.js.map +1 -1
  101. package/dist/internal/protocol/sealed-sender/index.d.ts +5 -7
  102. package/dist/internal/protocol/sealed-sender/index.d.ts.map +1 -1
  103. package/dist/internal/protocol/sealed-sender/index.js +4 -12
  104. package/dist/internal/protocol/sealed-sender/index.js.map +1 -1
  105. package/dist/internal/protocol/sealed-sender/{v2-helpers.d.ts → multi-recipient-crypto.d.ts} +1 -1
  106. package/dist/internal/protocol/sealed-sender/multi-recipient-crypto.d.ts.map +1 -0
  107. package/dist/internal/protocol/sealed-sender/{v2-helpers.js → multi-recipient-crypto.js} +1 -1
  108. package/dist/internal/protocol/sealed-sender/multi-recipient-crypto.js.map +1 -0
  109. package/dist/internal/protocol/sealed-sender/{v2-binary.d.ts → multi-recipient-message.d.ts} +3 -2
  110. package/dist/internal/protocol/sealed-sender/multi-recipient-message.d.ts.map +1 -0
  111. package/dist/internal/protocol/sealed-sender/{v2-binary.js → multi-recipient-message.js} +16 -8
  112. package/dist/internal/protocol/sealed-sender/multi-recipient-message.js.map +1 -0
  113. package/dist/internal/protocol/sealed-sender/proto/index.d.ts +3 -0
  114. package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
  115. package/dist/internal/protocol/sealed-sender/proto/index.js +25 -2
  116. package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
  117. package/dist/internal/protocol/sealed-sender/trust-root.d.ts +11 -1
  118. package/dist/internal/protocol/sealed-sender/trust-root.d.ts.map +1 -1
  119. package/dist/internal/protocol/sealed-sender/trust-root.js +13 -1
  120. package/dist/internal/protocol/sealed-sender/trust-root.js.map +1 -1
  121. package/dist/internal/protocol/sealed-sender/types.d.ts +20 -135
  122. package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
  123. package/dist/internal/protocol/sealed-sender/types.js +15 -6
  124. package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
  125. package/dist/internal/protocol/sender-keys/manager.d.ts +22 -1
  126. package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
  127. package/dist/internal/protocol/sender-keys/manager.js +39 -4
  128. package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
  129. package/dist/internal/protocol/spqr/braid-serialize.js +1 -1
  130. package/dist/internal/protocol/spqr/braid-serialize.js.map +1 -1
  131. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js +4 -4
  132. package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js.map +1 -1
  133. package/dist/internal/protocol/zk/groups/index.d.ts +1 -1
  134. package/dist/internal/protocol/zk/groups/index.d.ts.map +1 -1
  135. package/dist/internal/protocol/zk/groups/index.js +1 -1
  136. package/dist/internal/protocol/zk/groups/index.js.map +1 -1
  137. package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts +37 -12
  138. package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts.map +1 -1
  139. package/dist/internal/protocol/zk/groups/profile-key-credential.js +104 -31
  140. package/dist/internal/protocol/zk/groups/profile-key-credential.js.map +1 -1
  141. package/dist/local/store/expo/adapter.d.ts +1 -0
  142. package/dist/local/store/expo/adapter.d.ts.map +1 -1
  143. package/dist/local/store/expo/adapter.js +3 -0
  144. package/dist/local/store/expo/adapter.js.map +1 -1
  145. package/dist/local/store/expo/key-storage.d.ts +1 -0
  146. package/dist/local/store/expo/key-storage.d.ts.map +1 -1
  147. package/dist/local/store/expo/key-storage.js +4 -0
  148. package/dist/local/store/expo/key-storage.js.map +1 -1
  149. package/dist/local/store/memory/adapter.d.ts +1 -0
  150. package/dist/local/store/memory/adapter.d.ts.map +1 -1
  151. package/dist/local/store/memory/adapter.js +4 -0
  152. package/dist/local/store/memory/adapter.js.map +1 -1
  153. package/dist/local/store/node/adapter.d.ts +1 -0
  154. package/dist/local/store/node/adapter.d.ts.map +1 -1
  155. package/dist/local/store/node/adapter.js +3 -0
  156. package/dist/local/store/node/adapter.js.map +1 -1
  157. package/dist/local/store/node/database.d.ts +1 -0
  158. package/dist/local/store/node/database.d.ts.map +1 -1
  159. package/dist/local/store/node/database.js +5 -0
  160. package/dist/local/store/node/database.js.map +1 -1
  161. package/dist/local/store/react-native/adapter.d.ts +1 -0
  162. package/dist/local/store/react-native/adapter.d.ts.map +1 -1
  163. package/dist/local/store/react-native/adapter.js +4 -0
  164. package/dist/local/store/react-native/adapter.js.map +1 -1
  165. package/dist/local/store/react-native/reference-backend.js +1 -1
  166. package/dist/local/store/react-native/reference-backend.js.map +1 -1
  167. package/dist/local/store/reliability.d.ts +63 -0
  168. package/dist/local/store/reliability.d.ts.map +1 -0
  169. package/dist/local/store/reliability.js +219 -0
  170. package/dist/local/store/reliability.js.map +1 -0
  171. package/dist/local/store/web/adapter.d.ts +1 -0
  172. package/dist/local/store/web/adapter.d.ts.map +1 -1
  173. package/dist/local/store/web/adapter.js +5 -0
  174. package/dist/local/store/web/adapter.js.map +1 -1
  175. package/dist/media/index.d.ts.map +1 -1
  176. package/dist/media/index.js +7 -4
  177. package/dist/media/index.js.map +1 -1
  178. package/dist/remote/object-store/convex-r2/server.d.ts +4 -2
  179. package/dist/remote/object-store/convex-r2/server.d.ts.map +1 -1
  180. package/dist/remote/object-store/convex-r2/server.js +8 -0
  181. package/dist/remote/object-store/convex-r2/server.js.map +1 -1
  182. package/dist/remote/object-store/convex-r2/storage.d.ts +5 -1
  183. package/dist/remote/object-store/convex-r2/storage.d.ts.map +1 -1
  184. package/dist/remote/object-store/convex-r2/storage.js +1 -0
  185. package/dist/remote/object-store/convex-r2/storage.js.map +1 -1
  186. package/dist/remote/object-store/types.d.ts +2 -0
  187. package/dist/remote/object-store/types.d.ts.map +1 -1
  188. package/dist/remote/object-store/validation.d.ts.map +1 -1
  189. package/dist/remote/object-store/validation.js +3 -0
  190. package/dist/remote/object-store/validation.js.map +1 -1
  191. package/dist/remote/relay/convex/backend.d.ts +7 -18
  192. package/dist/remote/relay/convex/backend.d.ts.map +1 -1
  193. package/dist/remote/relay/convex/backend.js +15 -24
  194. package/dist/remote/relay/convex/backend.js.map +1 -1
  195. package/dist/remote/relay/convex/component/_generated/component.d.ts +10 -18
  196. package/dist/remote/relay/convex/component/_generated/component.d.ts.map +1 -1
  197. package/dist/remote/relay/convex/component/certificates.d.ts.map +1 -1
  198. package/dist/remote/relay/convex/component/certificates.js +14 -5
  199. package/dist/remote/relay/convex/component/certificates.js.map +1 -1
  200. package/dist/remote/relay/convex/component/messages.d.ts +3 -17
  201. package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
  202. package/dist/remote/relay/convex/component/messages.js +28 -56
  203. package/dist/remote/relay/convex/component/messages.js.map +1 -1
  204. package/dist/remote/relay/convex/component/schema.d.ts +6 -6
  205. package/dist/remote/relay/convex/component/schema.js +2 -2
  206. package/dist/remote/relay/convex/component/schema.js.map +1 -1
  207. package/dist/remote/relay/convex/component/zkAuth.d.ts +7 -1
  208. package/dist/remote/relay/convex/component/zkAuth.d.ts.map +1 -1
  209. package/dist/remote/relay/convex/component/zkAuth.js +29 -14
  210. package/dist/remote/relay/convex/component/zkAuth.js.map +1 -1
  211. package/dist/remote/relay/convex/relay.d.ts +3 -6
  212. package/dist/remote/relay/convex/relay.d.ts.map +1 -1
  213. package/dist/remote/relay/convex/relay.js +23 -50
  214. package/dist/remote/relay/convex/relay.js.map +1 -1
  215. package/dist/remote/relay/index.d.ts +1 -1
  216. package/dist/remote/relay/index.d.ts.map +1 -1
  217. package/dist/remote/relay/index.js.map +1 -1
  218. package/dist/remote/relay/memory/adapter.d.ts +5 -11
  219. package/dist/remote/relay/memory/adapter.d.ts.map +1 -1
  220. package/dist/remote/relay/memory/adapter.js +41 -34
  221. package/dist/remote/relay/memory/adapter.js.map +1 -1
  222. package/dist/remote/relay/types.d.ts +19 -29
  223. package/dist/remote/relay/types.d.ts.map +1 -1
  224. package/dist/types/api.d.ts +2 -0
  225. package/dist/types/api.d.ts.map +1 -1
  226. package/dist/types/errors.d.ts +8 -1
  227. package/dist/types/errors.d.ts.map +1 -1
  228. package/dist/types/errors.js +9 -2
  229. package/dist/types/errors.js.map +1 -1
  230. package/dist/types/protocol-config.d.ts +1 -1
  231. package/dist/username/link.d.ts.map +1 -1
  232. package/dist/username/link.js +1 -1
  233. package/dist/username/link.js.map +1 -1
  234. package/docs/ASSURANCE.md +5 -5
  235. package/docs/DEVIATIONS.md +32 -61
  236. package/docs/GETTING_STARTED.md +7 -0
  237. package/docs/SECURITY.md +6 -0
  238. package/package.json +2 -2
  239. package/remote/relay/convex/component/README.md +28 -24
  240. package/scripts/oe-groups.mjs +5 -1
  241. package/dist/client/sealed-sender-ops.d.ts.map +0 -1
  242. package/dist/client/sealed-sender-ops.js +0 -203
  243. package/dist/client/sealed-sender-ops.js.map +0 -1
  244. package/dist/internal/protocol/sealed-sender/decryption-v2.d.ts +0 -46
  245. package/dist/internal/protocol/sealed-sender/decryption-v2.d.ts.map +0 -1
  246. package/dist/internal/protocol/sealed-sender/decryption-v2.js +0 -198
  247. package/dist/internal/protocol/sealed-sender/decryption-v2.js.map +0 -1
  248. package/dist/internal/protocol/sealed-sender/encryption-v2.d.ts +0 -56
  249. package/dist/internal/protocol/sealed-sender/encryption-v2.d.ts.map +0 -1
  250. package/dist/internal/protocol/sealed-sender/encryption-v2.js +0 -163
  251. package/dist/internal/protocol/sealed-sender/encryption-v2.js.map +0 -1
  252. package/dist/internal/protocol/sealed-sender/v2-binary.d.ts.map +0 -1
  253. package/dist/internal/protocol/sealed-sender/v2-binary.js.map +0 -1
  254. package/dist/internal/protocol/sealed-sender/v2-helpers.d.ts.map +0 -1
  255. package/dist/internal/protocol/sealed-sender/v2-helpers.js.map +0 -1
@@ -57,7 +57,7 @@ Deviations fall into three kinds:
57
57
  `libsignal` system.
58
58
 
59
59
  A fourth label, **faithful**, appears in the table for an area that follows the
60
- specification closely. Such a row is here only to delimit what the neighbouring
60
+ specification closely. Such a row is here only to delimit what the neighboring
61
61
  deviations do and do not touch.
62
62
 
63
63
  Companion documents: [Protocol Policy](./PROTOCOL_POLICY.md) states which
@@ -83,12 +83,11 @@ model and what is out of scope.
83
83
  | **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 |
84
84
  | **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 |
85
85
  | **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 |
86
- | **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, though it now carries the same message-type values | The slice order and the missing prefix are unintentional; the framing is a deliberate simplification | Self-consistent and secure, but every v1 key sits in a different slot than `libsignal`'s |
87
- | **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` |
86
+ | **Sealed sender** | `libsignal` `sealed_sender.rs` | **Faithful** on the multi-recipient transport labels, KEM, AES-256-GCM-SIV, binary format, and `0x3FFF` registration-ID mask. **Extension:** sender and server certificates require signed Relay scope and issuer validity under operator-owned Ed25519 roots | Binds anonymous delivery to one Relay deployment and supports explicit issuer rotation and revocation | The transport follows `libsignal`; certificates are not interchangeable with Signal Messenger or another deployment |
88
87
  | **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 |
89
88
  | **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 |
90
- | **Groups** | Signal Private Group System | **Independent design.** Real zkgroup primitives underneath; the server validates every change against zero-knowledge presentations and signs the accepted result, and clients verify those signatures. **Deviation:** profile-key credential issuance is not blinded — the issuing server sees the raw profile key at issuance time | Ships a validating group server with an enforcement contract (S1–S14) specified in-tree | Not wire-compatible with the Signal Private Group System; credentials are not interchangeable. The unblinded issuance path means a hostile issuance server learns profile keys, which the Signal Private Group System's blinded issuance prevents |
91
- | **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 is structured as four labelled derivations rather than one seeded derivation | Server keys are the deploying operator's own trust root (each deployment generates its own seed), not Signal Messenger's | The zero-knowledge properties are real. Credentials are not interchangeable with Signal Messenger's |
89
+ | **Groups** | Signal Private Group System | **Independent design.** Real zkgroup primitives underneath; profile-key credential issuance blinds the ACI-bound profile-key attribute, the server validates every change against zero-knowledge presentations and signs the accepted result, and clients verify those signatures | Ships a validating group server with an enforcement contract (S1–S14) specified in-tree | Not wire-compatible with the Signal Private Group System; credentials are not interchangeable. The issuer sees the authenticated ACI and redemption window, but not the raw profile key |
90
+ | **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 is structured as four labeled derivations rather than one seeded derivation | Server keys are the deploying operator's own trust root (each deployment generates its own seed), not Signal Messenger's | The zero-knowledge properties are real. Credentials are not interchangeable with Signal Messenger's |
92
91
  | **Registration IDs** | `libsignal` `sealed_sender.rs` | **Faithful.** Generated in `[1, 16383]`, strictly inside the 14 bits the wire format reserves | — | — |
93
92
 
94
93
  ---
@@ -247,7 +246,7 @@ The SDK generates registration IDs in the closed range `[1, 16383]`
247
246
  The upper bound is load-bearing rather than cosmetic. The value `16384` is
248
247
  `0x4000` and does not fit in 14 bits. The SDK's multi-recipient sealed-sender
249
248
  encoder masks rather than rejects
250
- (`internal/protocol/sealed-sender/v2-binary.ts:170-171`), so an ID one above
249
+ (`internal/protocol/sealed-sender/multi-recipient-message.ts`), so an ID one above
251
250
  the range would reach the wire as `0`. The generated range is therefore strictly
252
251
  narrower than `libsignal`'s accepted range, and a test asserts that every
253
252
  generated ID survives the mask unchanged.
@@ -307,7 +306,7 @@ The SDK does not use `libsignal`'s labels, `WhisperText` and
307
306
  Inheriting them would be wrong on both parameters:
308
307
 
309
308
  1. **`pqkem` would name a KEM the SDK does not run**, violating §2.2. That is
310
- worse than a labelling error. Two implementations feeding an identical label
309
+ worse than a labeling error. Two implementations feeding an identical label
311
310
  derive *different* shared secrets. The KEM underneath differs, and nothing at
312
311
  the KDF layer signals it. Domain separation is the one job the info string
313
312
  has.
@@ -538,7 +537,7 @@ independently and pinned against commit `fd32048`, which upstream tags
538
537
  - **ML-KEM-768 with the same incremental split** (32-byte seed, 1152-byte vector,
539
538
  960/128-byte ciphertext parts).
540
539
 
541
- The delta review that moved the pin forward from `f2589fef` found one behavioural
540
+ The delta review that moved the pin forward from `f2589fef` found one behavioral
542
541
  change upstream. Decoding a chain epoch direction now rejects a `next` chain key
543
542
  whose length is neither zero nor 32 bytes. The internal next-key assertion checks
544
543
  that same exact length rather than mere non-emptiness.
@@ -548,7 +547,7 @@ key, root key, and skipped-message key to be canonical base64 for exactly 32
548
547
  bytes (`internal/protocol/spqr/serialize.ts:44-72`). The SDK has no state in
549
548
  which the key is absent. Two upstream error strings now name the value they
550
549
  reject. The rest of the delta is proof-assistant annotation and loop rewriting,
551
- which leaves behaviour unchanged.
550
+ which leaves behavior unchanged.
552
551
 
553
552
  ### 4.1 The `hek` operand order diverges
554
553
 
@@ -758,7 +757,7 @@ possession must add it at the application layer.
758
757
 
759
758
  ## 6. Sealed sender
760
759
 
761
- ### 6.1 Version 2 is faithful
760
+ ### 6.1 The multi-recipient transport is faithful
762
761
 
763
762
  These parts match `libsignal`:
764
763
 
@@ -771,39 +770,9 @@ These parts match `libsignal`:
771
770
  ServiceIds
772
771
  - the packed device ID with its 14-bit registration ID and `0x3FFF` mask
773
772
 
774
- Certificate validation order and semantics match as well. That includes the
775
- trust-root loop, which does not short-circuit and therefore does not reveal which
776
- root validated.
777
-
778
- ### 6.2 Version 1 diverges in three places
779
-
780
- **The SDK splits the 96-byte HKDF output in a different order.** `libsignal`
781
- derives `(chain_key, cipher_key, mac_key)` ([`sealed_sender.rs:711-746`][ss]).
782
- The SDK derives `(cipher, mac, chain)`
783
- (`internal/protocol/sealed-sender/encryption.ts:164-166`). The construction is
784
- self-consistent and secure, because the keys are independent HKDF output either
785
- way. Every v1 key still sits in a different slot than `libsignal`'s. This is an
786
- implementation divergence rather than a design decision. The SDK's own pinned
787
- specification document records the same order, so the two agree with each other.
788
-
789
- **Public keys in the v1 salt and in certificates omit the `0x05` type byte.**
790
- `libsignal` uses the 33-byte serialized form. The SDK uses raw 32 bytes and
791
- enforces that length
792
- (`internal/protocol/sealed-sender/certificate.ts:306-309`). The SDK's own v2 path
793
- *does* apply the `0x05` prefix, so the two sealed-sender versions disagree with
794
- each other.
795
-
796
- **The inner envelope is a hand-rolled varint format**
797
- (`internal/protocol/sealed-sender/encryption.ts:46-86`) rather than the
798
- `UnidentifiedSenderMessage.Message` protobuf. It still carries the message-type
799
- field that `libsignal` dispatches on, which selects between prekey, regular,
800
- sender-key, and plaintext payloads ([`sealed_sender.rs:2055-2075`][ss]). The
801
- field is a leading byte holding `libsignal`'s enum values. The framing therefore
802
- differs while the dispatch does not.
803
-
804
- That field lets the unseal path restore the real message type. Without it the
805
- path would rebuild the envelope with a fixed type, and a sealed group message
806
- would not decrypt as a group message.
773
+ The base trust-root loop also matches. It does not short-circuit and therefore
774
+ does not reveal which root validated. Required signed scope and issuer-validity
775
+ checks extend the upstream certificate semantics.
807
776
 
808
777
  **`PLAINTEXT_CONTENT` (8) is a known wire value that this SDK rejects.**
809
778
  `libsignal` uses it to carry a `DecryptionErrorMessage` when no session exists
@@ -829,7 +798,7 @@ one pattern: sealed messages from one peer stack fail with that error while
829
798
  messages from this SDK succeed. Check the leading content-type byte before you
830
799
  treat that as a cryptographic failure.
831
800
 
832
- ### 6.3 The delivery token follows `libsignal`, not an SDK invention
801
+ ### 6.2 The delivery token follows `libsignal`, not an SDK invention
833
802
 
834
803
  Despite the module name, `deriveAccessKey`
835
804
  (`internal/protocol/sealed-sender/delivery-token.ts:52-91`) is `libsignal`'s
@@ -846,10 +815,11 @@ The SDK's own documentation once described a different, 12-byte HKDF
846
815
  construction that no code implements. That description is wrong, and the PR that
847
816
  accompanies this file corrects it.
848
817
 
849
- Certificate signatures use Ed25519 rather than XEdDSA, per §1.2, so SDK
850
- certificates cannot validate against a Signal Messenger trust root or vice versa. The
851
- revocation list is empty where `libsignal` revokes one key ID, which is
852
- appropriate for a different trust root but worth noting.
818
+ Certificate signatures use Ed25519 rather than XEdDSA, per §1.2. The signed
819
+ Relay scope and issuer-validity interval are deployment extensions. Hosted and
820
+ self-hosted deployments use disjoint operator roots, issuers, scopes, and
821
+ revocation policy. Their certificates cannot validate against each other or a
822
+ Signal Messenger trust root.
853
823
 
854
824
  ---
855
825
 
@@ -940,17 +910,18 @@ implements that contract. On every applied change, clients verify the server's
940
910
  signature, the group binding, the strict version sequence, and the pre-state
941
911
  authorization.
942
912
 
943
- **Profile-key credential issuance is not blinded**. The issuance endpoint
944
- receives the raw 32-byte profile key, so the issuing server sees every user's
945
- profile key in plaintext at issuance time. The Signal Private Group System issues
946
- profile-key credentials over a *blinded* commitment, so its server never learns
947
- the key. The blinding primitives exist in this codebase
948
- (`internal/protocol/zk/credentials/issuance.ts`), but nothing wires them into
949
- this path. Section 12.1 of the in-tree group specification carries the same
950
- caveat.
913
+ **Profile-key credential issuance uses a package-owned blinded wire format**.
914
+ The client sends a fixed-width serialized request that contains an ephemeral
915
+ blinding public key and an ACI-bound blinded profile-key attribute. The issuer
916
+ sees the authenticated ACI and the public redemption time, but it does not
917
+ receive the raw 32-byte profile key or the client's blinding secret. The client
918
+ verifies and unblinds the signed response with the matching request context.
919
+ Fresh request randomness makes two requests for the same ACI and profile key
920
+ unlinkable from the blinded request bytes.
951
921
 
952
- Until blinded issuance ships, a deployer must assume that the issuance server
953
- learns profile keys, and therefore profile names and avatars.
922
+ This preserves the Signal Private Group System's issuer-privacy property, but
923
+ the request and response encodings remain this SDK's own and are not
924
+ interchangeable with Signal Messenger or `libsignal` credentials.
954
925
 
955
926
  **Serialization is JSON**, not protobuf, both for group state
956
927
  (`internal/groups/manager.ts:1229-1236`) and for the blob payloads inside the
@@ -982,7 +953,7 @@ system parameters against a hex string taken from `libsignal`'s own Rust test,
982
953
  and it passes.
983
954
 
984
955
  One deviation remains. The SDK derives server secret parameters through four
985
- separately labelled key derivations, where `libsignal` uses a single seeded
956
+ separately labeled key derivations, where `libsignal` uses a single seeded
986
957
  derivation (`internal/protocol/zk/groups/server-params.ts:43-54`). The same
987
958
  randomness therefore yields different server keys.
988
959
 
@@ -1004,7 +975,7 @@ confirm any of them in source.
1004
975
 
1005
976
  - **Does a sealed-sender-wrapped prekey message decrypt end to end?** The unseal
1006
977
  path rebuilds the envelope with a fixed message type
1007
- (`client/sealed-sender-ops.ts:263-265`). An adjacent comment suggests that the
978
+ (`client/sealed-sender.ts`). An adjacent comment suggests that the
1008
979
  Sesame layer re-derives the initiation state from the ciphertext. This review
1009
980
  traced neither that path nor the integration tests. First-contact sealed
1010
981
  messages break if Sesame does not detect the state itself.
@@ -1031,7 +1002,7 @@ confirm any of them in source.
1031
1002
  `libsignal` commits the new state only after the MAC and the decryption
1032
1003
  succeed. The SDK's receive
1033
1004
  path mutates state during decode, and this review did not trace the caller's
1034
- rollback behaviour.
1005
+ rollback behavior.
1035
1006
  - **Does an equivalent of `libsignal`'s `promote_matching_session` exist?**
1036
1007
  `libsignal` matches archived sessions on `(version, base key)`. The SDK keys
1037
1008
  its map on the base key alone.
@@ -101,6 +101,13 @@ flowchart LR
101
101
  envelopes.
102
102
  - The remote object store carries encrypted attachment/media bytes only.
103
103
 
104
+ You can operate these server-side interfaces through a shipped or custom
105
+ adapter. You can instead use [OpenE2EE Relay](https://open-e2ee.dev/relay) for
106
+ managed encrypted delivery, private encrypted attachment storage, push wakes,
107
+ and lifecycle controls. The SDK does not require the managed service. The
108
+ [Relay pricing page](https://open-e2ee.dev/relay/pricing) defines its exact
109
+ meters and limits.
110
+
104
111
  ## Target Message-First API Preview
105
112
 
106
113
  This is the target DX the package moves toward. It appears here so app
package/docs/SECURITY.md CHANGED
@@ -64,6 +64,12 @@ round-3 Kyber1024 tagged `0x08`.
64
64
  using ML-KEM-768 and bounded Reed-Solomon decoding.
65
65
  - HEK follows the ML-KEM Braid specification:
66
66
  `SHA3-256(ek_seed || ek_vector)`.
67
+ - FIPS 203 serializes the encapsulation key vector-first, and the braid HEK
68
+ order is seed-first. Braid mode therefore runs ML-KEM-768 with a modified
69
+ encapsulation-key commitment, and the SDK makes no FIPS 203 conformance claim
70
+ for that path.
71
+ - The modification reaches only the braid path. Direct ML-KEM-768 SCKA uses
72
+ stock ML-KEM-768, and PQXDH uses standardized FIPS 203 ML-KEM-1024 behavior.
67
73
  - The SDK applies `KDF_OK` once when raw ML-KEM output enters the epoch
68
74
  boundary. Braid output is already an epoch secret and is not derived a second
69
75
  time.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "0.4.0",
3
+ "version": "2.0.0",
4
4
  "description": "Signal Protocol E2EE SDK for TypeScript — Expo, React Native, browser, and Node. Post-quantum PQXDH and Double Ratchet.",
5
5
  "keywords": [
6
6
  "open-e2ee",
@@ -421,7 +421,7 @@
421
421
  "dependencies": {
422
422
  "@noble/ciphers": "^2.3.0",
423
423
  "@noble/curves": "^2.2.0",
424
- "@noble/hashes": "2.3.0",
424
+ "@noble/hashes": "2.4.0",
425
425
  "@noble/post-quantum": "^0.7.0",
426
426
  "async-lock": "^1.4.0",
427
427
  "unique-names-generator": "^4.7.1"
@@ -152,7 +152,6 @@ export const {
152
152
  getPendingMessages,
153
153
  markDelivered,
154
154
  getActiveDevices,
155
- sendUnidentified,
156
155
  sendMultiRecipientUnidentified,
157
156
  sendRetryRequest,
158
157
  getPendingRetryRequests,
@@ -232,8 +231,8 @@ issuance also resolves identity. Group wrappers pass client arguments through
232
231
  untouched because group reads and writes authenticate membership solely through
233
232
  the supplied zero-knowledge presentation.
234
233
 
235
- `sendUnidentified` and `sendMultiRecipientUnidentified` are the deliberate
236
- exception: those sealed-sender paths do **not** call `identify`. They authorize
234
+ `sendMultiRecipientUnidentified` is the deliberate exception: this
235
+ sealed-sender path does **not** call `identify`. It authorizes
237
236
  the bearer request with the target's unidentified-access key or verified group
238
237
  send material, which keeps delivery available without an authenticated
239
238
  application session. Rejections carry structured `ConvexError` data. The relay
@@ -277,16 +276,16 @@ component. Each authenticated fetcher/target-account pair receives ten fetches
277
276
  per fixed one-minute window. The eleventh request fails with structured
278
277
  `RATE_LIMITED` data and HTTP-equivalent status 429.
279
278
 
280
- ## Upgrading: clear `messages` before deploying this version
279
+ ## Upgrading to 2.0: clear `messages` before deployment
281
280
 
282
- This version drops two shapes from the `messages` table: the optional
283
- `groupId` field, and `plaintext_content` from the `messageType` union.
281
+ Version 2.0 replaces the optional `urgent` and `ephemeral` booleans with one
282
+ required `deliveryClass`. Every 1.x `messages` row lacks that field.
284
283
 
285
284
  Convex validates every existing document against the new schema **during the
286
- push**, before any of your code runs. A stored row carrying a `groupId`, or one
287
- whose `messageType` is `plaintext_content`, therefore fails the deploy. No
288
- migration mutation can fix it, because the deploy that would ship the mutation
289
- is the deploy that fails. The order has to be: clear first, deploy second.
285
+ push**, before any of your code runs. Any retained 1.x row therefore fails the
286
+ deploy. No migration mutation can run first, because the deploy that would ship
287
+ it is the deploy that fails. The order is: empty the table first, then deploy.
288
+ Version 2.0 does not keep a compatibility field or parser for the old shape.
290
289
 
291
290
  Messages are transient by design. The table has a seven-day TTL and an hourly
292
291
  cleanup cron. Clients re-request undelivered messages through the retry path,
@@ -301,9 +300,7 @@ npx convex data messages --component signalProtocol
301
300
  ```
302
301
 
303
302
  Add `--prod` or `--deployment <name-or-reference>` to target a deployment other
304
- than your dev one. A deployment that never relayed a group message, and never
305
- had a caller pass `plaintext_content`, has no affected rows and needs no
306
- action. No send path in this SDK ever produced the latter.
303
+ than your development deployment. An empty table needs no action.
307
304
 
308
305
  If there are rows, either wait or clear:
309
306
 
@@ -330,8 +327,8 @@ Add `--prod` for the default production deployment or
330
327
  - generates a cryptographically random 32-byte seed only when the secret is
331
328
  absent
332
329
  - writes the seed to the selected Convex deployment through stdin
333
- - prints two labelled base64 roots: the serialized group trust root and the
334
- Ed25519 sender-certificate root
330
+ - prints the serialized group trust root, the Ed25519 sender-certificate root,
331
+ and the sender-certificate relay scope as labeled base64 values
335
332
 
336
333
  Pin both in the client build. See
337
334
  [Sender certificate trust root](#sender-certificate-trust-root) for where each
@@ -350,18 +347,21 @@ from the group signing key by distinct KDF labels
350
347
  (`open-e2ee:sealed-sender:root:v1` / `:server:v1`). Clients verify inbound
351
348
  sealed-sender certificates against the matching Ed25519 **root** public key.
352
349
 
353
- `oe-groups trust-root` prints both roots, labelled:
350
+ `oe-groups trust-root` prints both roots, labeled:
354
351
 
355
352
  ```
356
353
  group trust root: <base64>
357
354
  sealed sender trust root: <base64>
355
+ sealed sender relay scope: <base64>
358
356
  ```
359
357
 
360
358
  The two roots go in different places and are not interchangeable. The group
361
359
  trust root goes into the group configuration, and the sealed-sender root into
362
- `sealedSender.trustRoots` in the client build. Pin both at build time. Never
363
- fetch either from a relay at runtime, because a relay that chooses its own
364
- validation root can mint certificates for any sender.
360
+ `sealedSender.trustRoots` in the client build. Put the matching relay scope into
361
+ `sealedSender.relayScopeId`, and configure the operator-owned issuer revocation
362
+ list in `sealedSender.revokedIssuerKeyIds`. Pin these values at build time.
363
+ Never fetch them from a relay at runtime, because a relay that chooses its own
364
+ validation policy can mint certificates for any sender.
365
365
 
366
366
  The component derives both from the same deployment secret, so rotating
367
367
  `OE_GROUPS_SERVER_SECRET` rotates both and strands clients pinned to either
@@ -451,8 +451,12 @@ The component cannot do it while its identity has no device field.
451
451
 
452
452
  ## Profile-key issuance threat model
453
453
 
454
- `issueProfileKeyCredentialMutation` receives the raw 32-byte profile key. The
455
- group server therefore sees the plaintext profile key at issuance time. The
456
- credential proof hides it in later group presentations, but issuance in this
457
- credential layer is not blinded. Blinded issuance is a future credential-layer
458
- candidate and is explicitly outside this component's scope.
454
+ `issueProfileKeyCredentialMutation` receives a 160-byte blinded request bound
455
+ to the authenticated ACI. The group server sees the ACI and redemption window,
456
+ but it does not receive the raw 32-byte profile key or the client's ephemeral
457
+ blinding secret. The client unblinds and verifies the response before it uses
458
+ the credential in a group presentation.
459
+
460
+ `setUnidentifiedAccessKeyMutation` is a separate delivery-authorization seam.
461
+ It receives only the 16-byte access key that the client derives from its
462
+ profile key. Credential issuance does not derive or register that access key.
@@ -94,7 +94,7 @@ async function printTrustRoot(args) {
94
94
  const [
95
95
  { generateServerSecretParams, getServerPublicParams },
96
96
  { encodeGroupTrustRoot },
97
- { deriveSealedSenderRootPublicKey },
97
+ { deriveSealedSenderRootPublicKey, deriveSealedSenderScopeId },
98
98
  ] = await Promise.all([
99
99
  // pathToFileURL: dynamic import of a bare absolute path fails on
100
100
  // Windows, where the ESM loader requires a file:// URL.
@@ -136,6 +136,7 @@ async function printTrustRoot(args) {
136
136
  const sealedSenderRoot = await deriveSealedSenderRootPublicKey(
137
137
  secretParams.signingKeyPair.signingKey
138
138
  );
139
+ const sealedSenderScope = await deriveSealedSenderScopeId(sealedSenderRoot);
139
140
 
140
141
  // Two independently pinned roots, printed with labels because they go to
141
142
  // different places in the client build and are not interchangeable.
@@ -145,6 +146,9 @@ async function printTrustRoot(args) {
145
146
  process.stdout.write(
146
147
  `sealed sender trust root: ${Buffer.from(sealedSenderRoot).toString('base64')}\n`
147
148
  );
149
+ process.stdout.write(
150
+ `sealed sender relay scope: ${Buffer.from(sealedSenderScope).toString('base64')}\n`
151
+ );
148
152
  }
149
153
 
150
154
  const [command, ...args] = process.argv.slice(2);
@@ -1 +0,0 @@
1
- {"version":3,"file":"sealed-sender-ops.d.ts","sourceRoot":"","sources":["../../client/sealed-sender-ops.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAA+B,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAEtE,OAAO,EACL,uBAAuB,EAGxB,MAAM,0CAA0C,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,CAAC;AACV,wBAAsB,WAAW,CAC/B,gBAAgB,EAAE,MAAM,EACxB,uBAAuB,EAAE,MAAM,EAC/B,qBAAqB,EAAE,UAAU,EACjC,uBAAuB,EAAE,UAAU,EACnC,OAAO,EAAE,kBAAkB,EAC3B,eAAe,CAAC,EAAE,OAAO,EACzB,WAAW,CAAC,EAAE,uBAAuB,GACpC,OAAO,CAAC,MAAM,CAAC,CAkCjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,sBAAsB,EAAE,MAAM,EAC9B,wBAAwB,EAAE,UAAU,EACpC,aAAa,EAAE,MAAM,EACrB,iBAAiB,EAAE,MAAM,EACzB,MAAM,EAAE,kBAAkB,EAC1B,cAAc,CAAC,EAAE,OAAO,GACvB,OAAO,CAAC;IACT,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,WAAW,EAAE,uBAAuB,CAAC;CACtC,CAAC,CAgED;AA8ED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,QAAQ,EAC1B,QAAQ,EAAE;IACR,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,WAAW,EAAE,uBAAuB,CAAC;CACtC,GACA,QAAQ,CAQV;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,uBAAuB,GACnC,QAAQ,CAAC,aAAa,CAAC,CAUzB"}
@@ -1,203 +0,0 @@
1
- /**
2
- * Sealed Sender Operations
3
- *
4
- * Provides seal/unseal wrapping for the message send/receive pipeline.
5
- * Called by SignalProtocolServiceCipher when sealed sender is enabled.
6
- *
7
- * @see https://signal.org/blog/sealed-sender/
8
- */
9
- import { resolveSignalProtocolLogger } from '../logger.js';
10
- import { SealedSenderContentType, SEALED_SENDER_V2_SERVICE_ID_VERSION, SEALED_SENDER_V2_UUID_VERSION, } from '../internal/protocol/sealed-sender/types.js';
11
- export async function sealMessage(ciphertextBase64, senderCertificateBase64, senderIdentityPrivate, recipientIdentityPublic, _config, _providedLogger, contentType) {
12
- const { seal, deserializeSenderCertificate, encodeUnidentifiedSenderMessage } = await import('../internal/protocol/sealed-sender/index.js');
13
- const { base64ToBytes, bytesToBase64 } = await import('../internal/crypto/index.js');
14
- // Deserialize the sender certificate
15
- const certBytes = base64ToBytes(senderCertificateBase64);
16
- const senderCertificate = deserializeSenderCertificate(certBytes);
17
- // Convert ciphertext to bytes for seal()
18
- const signalProtocolMessage = base64ToBytes(ciphertextBase64);
19
- // Seal the message
20
- const sealed = await seal({
21
- senderCertificate,
22
- senderIdentityPrivate,
23
- recipientIdentityPublic,
24
- signalProtocolMessage,
25
- contentType,
26
- });
27
- // Serialize: version byte + protobuf-encoded message (Sealed Sender wire format)
28
- const protoBytes = encodeUnidentifiedSenderMessage({
29
- ephemeralPublic: base64ToBytes(sealed.ephemeralPublic),
30
- encryptedStatic: base64ToBytes(sealed.encryptedStatic),
31
- encryptedMessage: base64ToBytes(sealed.encryptedMessage),
32
- });
33
- // Prepend version byte
34
- const sealedBytes = new Uint8Array(1 + protoBytes.length);
35
- sealedBytes[0] = sealed.version;
36
- sealedBytes.set(protoBytes, 1);
37
- return bytesToBase64(sealedBytes);
38
- }
39
- /**
40
- * Unseal a sealed sender message to reveal the sender and inner ciphertext.
41
- *
42
- * Called when an incoming envelope has messageType === 'unidentified_sender'.
43
- * Validates the certificate chain, reveals sender identity, and returns
44
- * the inner Signal Protocol ciphertext for normal decryption.
45
- *
46
- * @param sealedCiphertextBase64 - Base64-encoded sealed sender message
47
- * @param recipientIdentityPrivate - Recipient's X25519 identity private key
48
- * @param recipientUuid - Recipient's user ID (for self-send detection)
49
- * @param recipientDeviceId - Recipient's device ID
50
- * @param config - Sealed sender config with trust roots
51
- * @returns Unsealed envelope info with sender identity and inner ciphertext
52
- */
53
- export async function unsealMessage(sealedCiphertextBase64, recipientIdentityPrivate, recipientUuid, recipientDeviceId, config, providedLogger) {
54
- const logger = resolveSignalProtocolLogger(providedLogger);
55
- const { base64ToBytes, bytesToBase64 } = await import('../internal/crypto/index.js');
56
- // Decode sealed bytes and check version byte for V1 vs V2 dispatch
57
- const sealedBytes = base64ToBytes(sealedCiphertextBase64);
58
- const versionByte = sealedBytes[0];
59
- // V2 detection: 0x22 = UUID version (ReceivedMessage), 0x23 = ServiceId version
60
- if (versionByte === SEALED_SENDER_V2_UUID_VERSION ||
61
- versionByte === SEALED_SENDER_V2_SERVICE_ID_VERSION) {
62
- return unsealV2Message(sealedBytes, recipientIdentityPrivate, recipientUuid, recipientDeviceId, config, logger);
63
- }
64
- // V1 path (0x11). Existing code
65
- const { unseal, decodeUnidentifiedSenderMessage } = await import('../internal/protocol/sealed-sender/index.js');
66
- const version = versionByte;
67
- const sealedProto = decodeUnidentifiedSenderMessage(sealedBytes.subarray(1));
68
- // Build the UnidentifiedSenderMessage structure
69
- const sealedMessage = {
70
- version,
71
- ephemeralPublic: bytesToBase64(sealedProto.ephemeralPublic),
72
- encryptedStatic: bytesToBase64(sealedProto.encryptedStatic),
73
- encryptedMessage: bytesToBase64(sealedProto.encryptedMessage),
74
- };
75
- // Build trust roots as base64 strings
76
- const trustRoots = config.trustRoots.map((root) => bytesToBase64(root));
77
- // Unseal the message
78
- const content = await unseal({
79
- sealedMessage,
80
- recipientIdentityPrivate,
81
- trustRoots,
82
- recipientUuid,
83
- recipientDeviceId,
84
- });
85
- logger.debug('Sealed sender message unsealed', {
86
- category: 'E2EE',
87
- data: {
88
- senderUuid: content.senderCertificate.senderUuid,
89
- senderDeviceId: content.senderCertificate.senderDeviceId,
90
- },
91
- });
92
- return {
93
- senderUserId: content.senderCertificate.senderUuid,
94
- senderDeviceId: content.senderCertificate.senderDeviceId,
95
- innerCiphertextBase64: content.signalProtocolMessage,
96
- contentType: content.contentType,
97
- };
98
- }
99
- /**
100
- * Unseal a V2 multi-recipient sealed sender message (per-device view).
101
- *
102
- * The server constructs a per-device view: [0x22][C_i(32)][AT_i(16)][e_pub(32)][ciphertext]
103
- * We deserialize this, build a SealedSenderV2Message, and call unsealV2().
104
- */
105
- async function unsealV2Message(sealedBytes, recipientIdentityPrivate, recipientUuid, recipientDeviceId, config, logger) {
106
- const { deserializeReceivedMessage } = await import('../internal/protocol/sealed-sender/v2-binary.js');
107
- const { unsealV2 } = await import('../internal/protocol/sealed-sender/decryption-v2.js');
108
- const { bytesToBase64 } = await import('../internal/crypto/index.js');
109
- const { x25519 } = await import('@noble/curves/ed25519.js');
110
- // 1. Deserialize per-device ReceivedMessage
111
- const deserialized = deserializeReceivedMessage(sealedBytes);
112
- // 2. Derive recipient public key from private
113
- const recipientIdentityPublic = x25519.getPublicKey(recipientIdentityPrivate);
114
- // 3. Build SealedSenderV2Message with single recipient entry
115
- const message = {
116
- version: SEALED_SENDER_V2_UUID_VERSION,
117
- ephemeralPublic: bytesToBase64(deserialized.ephemeralPublic),
118
- recipients: [
119
- {
120
- serviceId: recipientUuid,
121
- deviceId: recipientDeviceId,
122
- registrationId: 0, // Not needed for unseal. Only used in send path
123
- encryptedMessageKey: bytesToBase64(deserialized.encryptedMessageKey),
124
- authenticationTag: bytesToBase64(deserialized.authenticationTag),
125
- },
126
- ],
127
- messageCiphertext: bytesToBase64(deserialized.messageCiphertext),
128
- };
129
- // 4. Build trust roots as Base64 strings
130
- const trustRoots = config.trustRoots.map((root) => bytesToBase64(root));
131
- // 5. Call unsealV2
132
- const content = await unsealV2({
133
- sealedMessage: message,
134
- recipientIdentityPrivate,
135
- recipientIdentityPublic,
136
- recipientServiceId: recipientUuid,
137
- recipientDeviceId,
138
- trustRoots,
139
- });
140
- logger.debug('V2 sealed sender message unsealed', {
141
- category: 'E2EE',
142
- data: {
143
- senderUuid: content.senderCertificate.senderUuid,
144
- senderDeviceId: content.senderCertificate.senderDeviceId,
145
- },
146
- });
147
- return {
148
- senderUserId: content.senderCertificate.senderUuid,
149
- senderDeviceId: content.senderCertificate.senderDeviceId,
150
- innerCiphertextBase64: content.signalProtocolMessage,
151
- contentType: content.contentType,
152
- };
153
- }
154
- /**
155
- * Reconstruct an Envelope from an unsealed message.
156
- *
157
- * Takes the original sealed sender envelope (with empty sender fields)
158
- * and fills in the sender identity revealed by unsealing.
159
- *
160
- * @param originalEnvelope - The incoming envelope with messageType 'unidentified_sender'
161
- * @param unsealed - The unsealed sender info and inner ciphertext
162
- * @returns A new envelope with real sender info and the inner ciphertext
163
- */
164
- export function reconstructEnvelope(originalEnvelope, unsealed) {
165
- return {
166
- ...originalEnvelope,
167
- senderUserId: unsealed.senderUserId,
168
- senderDeviceId: unsealed.senderDeviceId,
169
- ciphertext: unsealed.innerCiphertextBase64,
170
- messageType: envelopeTypeForContent(unsealed.contentType),
171
- };
172
- }
173
- /**
174
- * Map a sealed envelope's content type onto the envelope type the decrypt
175
- * path routes on.
176
- *
177
- * Exported because both receive paths need it. `SignalProtocolServiceCipher`
178
- * via `reconstructEnvelope`, and `SignalProtocolClient.processIncomingEnvelope`
179
- * directly. Two copies of this mapping would drift.
180
- *
181
- * `SENDERKEY_MESSAGE` is the only case that matters here. It is what keeps
182
- * group routing working now that no group identifier travels on an envelope,
183
- * sealed or otherwise. Both `PREKEY_MESSAGE` and `MESSAGE` decrypt as pairwise
184
- * ratchet messages, and the ratchet distinguishes them from the payload
185
- * itself.
186
- *
187
- * The default is unreachable: `isSealedSenderContentType` rejects every other
188
- * value at the parse, so nothing arrives here that this function cannot map.
189
- * It exists so that adding an enum member without a route fails loudly rather
190
- * than silently decrypting as something it is not.
191
- */
192
- export function envelopeTypeForContent(contentType) {
193
- switch (contentType) {
194
- case SealedSenderContentType.SENDERKEY_MESSAGE:
195
- return 'sender_key';
196
- case SealedSenderContentType.PREKEY_MESSAGE:
197
- case SealedSenderContentType.MESSAGE:
198
- return 'ciphertext';
199
- default:
200
- throw new Error('Unsupported sealed sender content type');
201
- }
202
- }
203
- //# sourceMappingURL=sealed-sender-ops.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"sealed-sender-ops.js","sourceRoot":"","sources":["../../client/sealed-sender-ops.ts"],"names":[],"mappings":"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"}