@open-e2ee/signal-protocol-sdk 0.1.0 → 0.2.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 (62) hide show
  1. package/ARCHITECTURE.md +9 -1
  2. package/CHANGELOG.md +83 -0
  3. package/dist/client/config.d.ts +17 -1
  4. package/dist/client/config.d.ts.map +1 -1
  5. package/dist/client/config.js.map +1 -1
  6. package/dist/internal/crypto/utils.d.ts.map +1 -1
  7. package/dist/internal/crypto/utils.js +26 -1
  8. package/dist/internal/crypto/utils.js.map +1 -1
  9. package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts.map +1 -1
  10. package/dist/internal/encoding/proto/pq-ratchet-serialize.js +12 -4
  11. package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
  12. package/dist/internal/manager/manager.js +1 -1
  13. package/dist/internal/manager/manager.js.map +1 -1
  14. package/dist/internal/protocol/spqr/braid.d.ts.map +1 -1
  15. package/dist/internal/protocol/spqr/braid.js.map +1 -1
  16. package/dist/internal/protocol/spqr/index.d.ts +1 -1
  17. package/dist/internal/protocol/spqr/index.d.ts.map +1 -1
  18. package/dist/internal/protocol/spqr/index.js +0 -2
  19. package/dist/internal/protocol/spqr/index.js.map +1 -1
  20. package/dist/internal/protocol/spqr/message.d.ts +0 -18
  21. package/dist/internal/protocol/spqr/message.d.ts.map +1 -1
  22. package/dist/internal/protocol/spqr/message.js +1 -37
  23. package/dist/internal/protocol/spqr/message.js.map +1 -1
  24. package/dist/internal/protocol/spqr/ml-kem-braid/progress.d.ts +30 -0
  25. package/dist/internal/protocol/spqr/ml-kem-braid/progress.d.ts.map +1 -0
  26. package/dist/internal/protocol/spqr/ml-kem-braid/progress.js +45 -0
  27. package/dist/internal/protocol/spqr/ml-kem-braid/progress.js.map +1 -0
  28. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts +11 -8
  29. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
  30. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js +11 -8
  31. package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js.map +1 -1
  32. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts.map +1 -1
  33. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js +9 -2
  34. package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js.map +1 -1
  35. package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts +9 -6
  36. package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts.map +1 -1
  37. package/dist/internal/protocol/spqr/ml-kem-braid/types.js.map +1 -1
  38. package/dist/internal/protocol/spqr/spqr.d.ts +5 -3
  39. package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
  40. package/dist/internal/protocol/spqr/spqr.js +62 -7
  41. package/dist/internal/protocol/spqr/spqr.js.map +1 -1
  42. package/dist/internal/session/cipher.d.ts +4 -0
  43. package/dist/internal/session/cipher.d.ts.map +1 -1
  44. package/dist/internal/session/cipher.js +8 -3
  45. package/dist/internal/session/cipher.js.map +1 -1
  46. package/dist/internal/session/types.d.ts +8 -0
  47. package/dist/internal/session/types.d.ts.map +1 -1
  48. package/dist/local/store/node/database.d.ts +1 -1
  49. package/dist/local/store/node/database.js +1 -1
  50. package/dist/local/store/web/adapter.d.ts.map +1 -1
  51. package/dist/local/store/web/adapter.js +30 -17
  52. package/dist/local/store/web/adapter.js.map +1 -1
  53. package/dist/types/protocol-config.d.ts +44 -1
  54. package/dist/types/protocol-config.d.ts.map +1 -1
  55. package/dist/types/protocol-config.js +1 -0
  56. package/dist/types/protocol-config.js.map +1 -1
  57. package/dist/types/session.d.ts +1 -1
  58. package/dist/types/session.js +1 -1
  59. package/docs/ASSURANCE.md +5 -5
  60. package/docs/DEVIATIONS.md +72 -31
  61. package/docs/PROTOCOL_POLICY.md +6 -0
  62. package/package.json +2 -2
@@ -60,7 +60,7 @@ model and what is out of scope.
60
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
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
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, KEM-secret position, and — since `0.1.0-alpha.6` — on PQXDH §2.2's info-string construction. **Deviation:** ML-KEM-1024 (FIPS 203) replaces round-3 Kyber1024 | Standardized ML-KEM preferred over round-3 Kyber. The info string names it, and names this application rather than `libsignal`'s, as §2.1 and §2.2 require | Wire-incompatible with `libsignal` by construction, and the label now says so. Sessions established before `0.1.0-alpha.6` derive a different `SK` and cannot be continued |
63
+ | **X3DH / PQXDH** | X3DH rev. 1; PQXDH rev. 3 | **Faithful** on DH order, the `0xFF`×32 prefix, zero-salt HKDF, KEM-secret position, and PQXDH §2.2's info-string construction. **Deviation:** ML-KEM-1024 (FIPS 203) replaces round-3 Kyber1024 | Standardized ML-KEM preferred over round-3 Kyber. The info string names it, and names this application rather than `libsignal`'s, as §2.1 and §2.2 require | Wire-incompatible with `libsignal` by construction, and the label now says so. The info string is part of the derivation, so any peer that names a different one derives a different `SK` and cannot complete the handshake |
64
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
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
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 |
@@ -75,7 +75,7 @@ model and what is out of scope.
75
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
76
  | **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 |
77
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 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 |
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 |
78
+ | **Registration IDs** | `libsignal` `sealed_sender.rs` | **Faithful.** Generated in `[1, 16383]`, strictly inside the 14 bits the wire format reserves | — | — |
79
79
 
80
80
  ---
81
81
 
@@ -225,14 +225,13 @@ Registration IDs are generated in the closed range `[1, 16383]`
225
225
  `libsignal` rejects any ID where `id & 0x3FFF != id`
226
226
  ([`sealed_sender.rs:1508-1515`][ss]); `libsignal`'s own helper generates `[1, 16380]`.
227
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.
228
+ The upper bound is load-bearing rather than cosmetic. `16384` is `0x4000` and
229
+ does not fit in 14 bits, and the SDK's multi-recipient sealed-sender encoder
230
+ masks rather than rejects
231
+ (`internal/protocol/sealed-sender/v2-binary.ts:170-171`), so an ID one above
232
+ the range would reach the wire as `0`. The generated range is therefore
233
+ strictly narrower than `libsignal`'s accepted range, and a test asserts every
234
+ generated ID survives the mask unchanged.
236
235
 
237
236
  ---
238
237
 
@@ -280,23 +279,22 @@ this SDK is and runs. PQXDH §2.2 defines the info string as `info`, `curve`,
280
279
  defines the same `info` parameter, and §3.3 uses it as the HKDF info with
281
280
  nothing appended.
282
281
 
283
- Through `0.1.0-alpha.5` these were `libsignal`'s labels — `WhisperText` and
284
- `WhisperText_X25519_SHA-256_CRYSTALS-KYBER-1024` ([`pqxdh.rs:73-74`][pq]) —
285
- which was wrong on both parameters:
282
+ The SDK does not use `libsignal`'s labels — `WhisperText` and
283
+ `WhisperText_X25519_SHA-256_CRYSTALS-KYBER-1024` ([`pqxdh.rs:73-74`][pq]).
284
+ Inheriting them would be wrong on both parameters:
286
285
 
287
- 1. **`pqkem` named a KEM the SDK does not run**, violating §2.2. Worse than a
288
- labelling error: two implementations feeding an identical label derived
289
- *different* shared secrets, because the KEM underneath differed, with
290
- nothing at the KDF layer to signal it. Domain separation is the one job the
291
- info string has.
292
- 2. **`info` named someone else's application.** The specifications ask for an
293
- identifier of the application deriving the key. This SDK is not Signal
294
- Messenger, and the label saying otherwise was inherited, not chosen.
286
+ 1. **`pqkem` would name a KEM the SDK does not run**, violating §2.2. That is
287
+ worse than a labelling error: two implementations feeding an identical
288
+ label derive *different* shared secrets, because the KEM underneath
289
+ differs, with nothing at the KDF layer to signal it. Domain separation is
290
+ the one job the info string has.
291
+ 2. **`info` would name someone else's application.** The specifications ask
292
+ for an identifier of the application deriving the key. This SDK is not
293
+ Signal Messenger.
295
294
 
296
- Both are corrected as of `0.1.0-alpha.6`. This is a
297
- pre-1.0 format break: sessions established under the old labels derive a
298
- different `SK` and cannot be continued. Nothing else about the derivation
299
- changed.
295
+ Choosing the SDK's own labels is a pre-1.0 format break against sessions
296
+ established under `libsignal`'s: they derive a different `SK` and cannot be
297
+ continued. Nothing else about the derivation changes.
300
298
 
301
299
  An application that needs `libsignal`'s known-answer vectors can still get them
302
300
  by setting `protocolStrategy.keyExchangeInfoString` to the old label
@@ -489,8 +487,8 @@ past each boundary rather than on it.
489
487
  ## 4. SPQR and the ML-KEM Braid
490
488
 
491
489
  This is the same protocol as the SparsePostQuantumRatchet v1 protocol, implemented
492
- independently and pinned against `SparsePostQuantumRatchet v1.5.1` (commit
493
- `f2589fef`). The fidelity is high and specific:
490
+ independently and pinned against commit `fd32048`, which upstream tags
491
+ `SparsePostQuantumRatchet v1.5.3`. The fidelity is high and specific:
494
492
 
495
493
  - **KDF labels are byte-identical**, including the double space in
496
494
  `"Signal PQ Ratchet V1 Chain Start"` (`internal/crypto/kdf/hkdf.ts:353-368`).
@@ -507,6 +505,18 @@ independently and pinned against `SparsePostQuantumRatchet v1.5.1` (commit
507
505
  - **ML-KEM-768 with the same incremental split** (32-byte seed, 1152-byte vector,
508
506
  960/128-byte ciphertext parts).
509
507
 
508
+ The delta review that moved the pin forward from `f2589fef` found one behavioural
509
+ change upstream. Decoding a chain epoch direction now rejects a `next` chain key
510
+ whose length is neither zero nor 32 bytes. The internal next-key assertion checks
511
+ that same exact length rather than mere non-emptiness.
512
+
513
+ The SDK is already at least as strict. Restoring SPQR state requires every chain
514
+ key, root key, and skipped-message key to be canonical base64 for exactly 32
515
+ bytes (`internal/protocol/spqr/serialize.ts:44-72`). The SDK has no state in
516
+ which the key is absent. Two upstream error strings now name the value they
517
+ reject. The rest of the delta is proof-assistant annotation and loop rewriting,
518
+ which leaves behaviour unchanged.
519
+
510
520
  ### 4.1 The `hek` operand order diverges
511
521
 
512
522
  One divergence breaks interoperability completely. The SDK computes
@@ -549,7 +559,7 @@ braid session persisted under the former ordering.
549
559
 
550
560
  **Extension.** An opt-in direct mode (`protocol.braid: 'disabled'`) uses stock
551
561
  ML-KEM-768 and adds wire message types `0x80`–`0x82`
552
- (`internal/encoding/proto/pq-ratchet-serialize.ts:38-45`). `libsignal`'s parser rejects
562
+ (`internal/encoding/proto/pq-ratchet-serialize.ts:40-45`). `libsignal`'s parser rejects
553
563
  anything above `6`, so these are visible only within the SDK; they occupy a byte
554
564
  range `libsignal` has not claimed. This mode has no Signal Protocol analogue.
555
565
 
@@ -562,6 +572,37 @@ evicts by wall-clock timestamp, where `libsignal` triggers at `max_ooo × 11/10
562
572
  evicts by message index. `libsignal`'s rule is deterministic and index-anchored; the
563
573
  SDK's introduces a clock dependency into ratchet state.
564
574
 
575
+ **Deviation.** The varint decoder is the stricter of the two. It rejects any
576
+ value above `uint64` (`internal/encoding/proto/pq-ratchet-serialize.ts:163-186`).
577
+ `libsignal` accumulates into a `u64` and shifts the tenth byte by 63 places
578
+ (`src/v1/chunked/states/serialize.rs:154-181`). It therefore drops every bit at
579
+ or above 2^64 without an error. The two decoders differ only on malformed input,
580
+ because no encoder produces such a varint.
581
+
582
+ **Deviation.** The erasure layer works in whole chunks. It counts 32-byte
583
+ chunks and zero-pads the final chunk
584
+ (`internal/protocol/spqr/ml-kem-braid/rs/codec.ts:261` and `:810`). `libsignal`
585
+ instead counts GF(2^16) elements, and spreads the remainder across the sixteen
586
+ polynomials (`src/encoding/polynomial.rs:794-802`). The two agree on any input
587
+ whose length is a multiple of 32 bytes. All four braid components have such a
588
+ length, from the 96-byte header with MAC to the 1152-byte encapsulation-key
589
+ vector (`internal/protocol/spqr/ml-kem-braid/state-machine.ts:91-97`). The
590
+ divergence therefore reaches no byte on the wire.
591
+
592
+ **Deviation.** The `PolynomialEncoder` state message differs from `libsignal`'s
593
+ in three ways (`internal/protocol/spqr/ml-kem-braid/serialize.ts:400`, `:671-682`).
594
+ The SDK sets `pts` and `polys` together. The reference sets exactly one of the
595
+ two, and its schema says so (`src/proto/pq_ratchet.proto:8-16`). The SDK's `pts`
596
+ holds one data chunk for each 32 bytes of the component, where the reference
597
+ holds sixteen point vectors. The SDK also adds a `messageSize` field at number 4,
598
+ which the reference message does not define. `libsignal` refuses all three
599
+ (`src/encoding/polynomial.rs:597-616`).
600
+
601
+ Nothing in the SDK calls this codec. It reaches only the internal `ml-kem-braid`
602
+ barrel (`internal/protocol/spqr/ml-kem-braid/index.ts:197-198`), and no braid
603
+ session persists through it. Correcting the shape would change a persisted
604
+ format, so this entry records the divergence rather than repairing it.
605
+
565
606
  ### 4.3 The Triple Ratchet is faithful
566
607
 
567
608
  The post-quantum secret enters as the HKDF **salt** at message-key expansion, with
@@ -704,9 +745,9 @@ internally inconsistent about this.
704
745
  field `libsignal` uses to dispatch between prekey, regular, sender-key, and
705
746
  plaintext payloads ([`sealed_sender.rs:2055-2075`][ss]), as a leading byte
706
747
  using `libsignal`'s enum values, so the framing differs but the dispatch does
707
- not. Through 0.1.0-alpha.7 the field was absent and the unseal path
708
- reconstructed the envelope with a fixed type, which made sealed group messages
709
- undecryptable as group messages.
748
+ not. The field is what lets the unseal path restore the real message type
749
+ rather than reconstruct the envelope with a fixed one, which is what sealed
750
+ group messages need to decrypt as group messages.
710
751
 
711
752
  **`PLAINTEXT_CONTENT` (8) is a known wire value that this SDK rejects.**
712
753
  `libsignal` uses it to carry a `DecryptionErrorMessage` when no session exists
@@ -114,5 +114,11 @@ for diagnostics. It distinguishes post-quantum success from explicit classical
114
114
  compatibility fallback. Do not set `protocolStrategy.allowClassicalFallback`
115
115
  when `protocol.postQuantum` is present.
116
116
 
117
+ The advanced `protocolStrategy.onBraidProgress` callback reports ML-KEM Braid
118
+ chunk progress after every braid-mode send and receive: the chunks this side has
119
+ carried in the current epoch, the chunks the open transfers account for, the
120
+ epoch, and whether the operation produced the epoch secret. A direct-mode
121
+ session never raises it.
122
+
117
123
  Do not set `protocolStrategy.sckaMode` when `protocol` is present. Use
118
124
  `protocol.braid` so the public product policy owns the direct-vs-Braid choice.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-e2ee/signal-protocol-sdk",
3
- "version": "0.1.0",
3
+ "version": "0.2.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",
@@ -420,7 +420,7 @@
420
420
  "dependencies": {
421
421
  "@noble/ciphers": "^2.2.0",
422
422
  "@noble/curves": "^2.2.0",
423
- "@noble/hashes": "2.2.0",
423
+ "@noble/hashes": "2.3.0",
424
424
  "@noble/post-quantum": "^0.6.1",
425
425
  "async-lock": "^1.4.0",
426
426
  "unique-names-generator": "^4.7.1"