@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.
- package/ARCHITECTURE.md +9 -1
- package/CHANGELOG.md +83 -0
- package/dist/client/config.d.ts +17 -1
- package/dist/client/config.d.ts.map +1 -1
- package/dist/client/config.js.map +1 -1
- package/dist/internal/crypto/utils.d.ts.map +1 -1
- package/dist/internal/crypto/utils.js +26 -1
- package/dist/internal/crypto/utils.js.map +1 -1
- package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts.map +1 -1
- package/dist/internal/encoding/proto/pq-ratchet-serialize.js +12 -4
- package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
- package/dist/internal/manager/manager.js +1 -1
- package/dist/internal/manager/manager.js.map +1 -1
- package/dist/internal/protocol/spqr/braid.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/braid.js.map +1 -1
- package/dist/internal/protocol/spqr/index.d.ts +1 -1
- package/dist/internal/protocol/spqr/index.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/index.js +0 -2
- package/dist/internal/protocol/spqr/index.js.map +1 -1
- package/dist/internal/protocol/spqr/message.d.ts +0 -18
- package/dist/internal/protocol/spqr/message.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/message.js +1 -37
- package/dist/internal/protocol/spqr/message.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/progress.d.ts +30 -0
- package/dist/internal/protocol/spqr/ml-kem-braid/progress.d.ts.map +1 -0
- package/dist/internal/protocol/spqr/ml-kem-braid/progress.js +45 -0
- package/dist/internal/protocol/spqr/ml-kem-braid/progress.js.map +1 -0
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts +11 -8
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js +11 -8
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js +9 -2
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts +9 -6
- package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/types.js.map +1 -1
- package/dist/internal/protocol/spqr/spqr.d.ts +5 -3
- package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/spqr.js +62 -7
- package/dist/internal/protocol/spqr/spqr.js.map +1 -1
- package/dist/internal/session/cipher.d.ts +4 -0
- package/dist/internal/session/cipher.d.ts.map +1 -1
- package/dist/internal/session/cipher.js +8 -3
- package/dist/internal/session/cipher.js.map +1 -1
- package/dist/internal/session/types.d.ts +8 -0
- package/dist/internal/session/types.d.ts.map +1 -1
- package/dist/local/store/node/database.d.ts +1 -1
- package/dist/local/store/node/database.js +1 -1
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +30 -17
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/types/protocol-config.d.ts +44 -1
- package/dist/types/protocol-config.d.ts.map +1 -1
- package/dist/types/protocol-config.js +1 -0
- package/dist/types/protocol-config.js.map +1 -1
- package/dist/types/session.d.ts +1 -1
- package/dist/types/session.js +1 -1
- package/docs/ASSURANCE.md +5 -5
- package/docs/DEVIATIONS.md +72 -31
- package/docs/PROTOCOL_POLICY.md +6 -0
- package/package.json +2 -2
package/docs/DEVIATIONS.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
(`internal/protocol/sealed-sender/v2-binary.ts:170-171`), so
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
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
|
-
|
|
284
|
-
`WhisperText_X25519_SHA-256_CRYSTALS-KYBER-1024` ([`pqxdh.rs:73-74`][pq])
|
|
285
|
-
|
|
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`
|
|
288
|
-
labelling error: two implementations feeding an identical
|
|
289
|
-
*different* shared secrets, because the KEM underneath
|
|
290
|
-
nothing at the KDF layer to signal it. Domain separation is
|
|
291
|
-
info string has.
|
|
292
|
-
2. **`info`
|
|
293
|
-
identifier of the application deriving the key. This SDK is not
|
|
294
|
-
Messenger
|
|
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
|
-
|
|
297
|
-
|
|
298
|
-
|
|
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
|
|
493
|
-
`
|
|
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:
|
|
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.
|
|
708
|
-
|
|
709
|
-
|
|
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
|
package/docs/PROTOCOL_POLICY.md
CHANGED
|
@@ -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.
|
|
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.
|
|
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"
|