libsoliton/REVIEW-2026-09-08.md

libsoliton core review — 2026-09-08 (single-reviewer trial)

Overall assessment

libsoliton is shippable as reviewed. Across the full primitive stack, the key exchange, the double ratchet, streaming/storage AEAD, call keys, auth, and verification, I found no defect at medium severity or above. The areas the brief flagged as highest-risk are handled correctly and defensively: every AEAD nonce is provably unique within its key's lifetime (ratchet counter-mode nonces are a strict function of a monotonic send_count that aborts at u32::MAX before it can wrap; the first-message key reuses the epoch key only at counter 0 with a random nonce and a distinct AAD; streaming nonces are injective over (index, tag_byte); storage uses fresh random nonces). Secret-dependent comparisons all use subtle/constant-time paths (MAC/token in auth_verify, all-zero key/secret guards, fingerprint checks against untrusted wire data, ratchet-pk epoch identification, shared-secret zero-check in X25519 DH). Key material is wrapped in Zeroizing/ZeroizeOnDrop and every keygen/DH/KEM path explicitly zeroizes the Copy-type stack staging buffers before returning. The double-ratchet state machine is the strongest single piece: encrypt is atomic-by-ordering (all fallible ops precede any mutation), decrypt takes a full snapshot and rolls back on any error, duplicate detection is deferred past AEAD to avoid a timing oracle, the seen-sets and epoch keys rotate correctly across direction changes, and from_bytes has an extensive battery of structural/co-presence/all-zero guards.

The weakest areas are documentation-vs-code drift and a heavy reliance on documented caller obligations, neither of which is a code defect. Two footguns that could produce catastrophic nonce reuse — double-from_bytes and reusing a streaming (index, is_last) pair — are real, but both are deprecated/ &self-random-access APIs with explicit in-code warnings and safe alternatives (from_bytes_with_min_epoch, sequential encrypt_chunk), so they fall under the brief's "documented decision" exclusion. The one concrete mismatch worth fixing is a one-off in the recv_seen cap (code is stricter than the docs claim; safe direction). I would ship it; the notes below are hygiene, not blockers.

Findings (medium and above)

None.

Notes below medium

• low — recv_seen/prev_recv_seen cap is off-by-one vs the documentation. soliton/src/ratchet/mod.rs:582 (and :573) reject with ChainExhausted when self.recv_seen.len() + 1 >= MAX_RECV_SEEN (65536), i.e. the set can hold at most 65535 entries and the 65536th distinct-counter decrypt is rejected. The CHEATSHEET ("the 65536th distinct-counter decrypt succeeds … the 65537th returns ChainExhausted") and the MAX_RECV_SEEN comment in soliton/src/constants.rs:83 both state the limit one message higher. The code is the safe/conservative side (it keeps the live set always serializable, matching the >= MAX_RECV_SEEN reject in to_bytes at :1060/:1074 and from_bytes at :1292/:1316), so this is a doc/reimplementor-guidance error, not a security defect. No test would catch it without a 65k-message epoch.

• info — contradictory comments about HKDF PRK zeroization. soliton/src/primitives/hkdf.rs:19-22 states "The hkdf crate's internal PRK is not zeroized on drop (hkdf 0.13.0-rc.5 has no zeroize feature)", while soliton/soliton/Cargo.toml:26-29 explains that sha3 0.11-rc + the hmac zeroize feature were chosen specifically so the keyed SHA3 state used by HMAC/HKDF is ZeroizeOnDrop. Since Hkdf<Sha3_256> stores its PRK as an Hmac<Sha3_256> field, that field's drop should in fact zeroize the PRK. The two comments can't both be right; reconcile them so maintainers don't reason from the pessimistic one. Either way the PRK lifetime is a short-lived local, so the practical exposure is minimal.

• info — streaming compressed-empty non-final chunk skips the size check. soliton/src/streaming.rs:527 gates decompression on self.compressed && !decrypted.is_empty(); a compressed non-final chunk that AEAD-decrypts to zero bytes would return (empty, is_last=false) without the decompressed.len() != STREAM_CHUNK_SIZE guard at :533. Unreachable in practice: producing a valid AEAD chunk requires the stream key, and the legitimate encryptor never emits an empty non-final chunk (non-final plaintext must be exactly STREAM_CHUNK_SIZE, which compresses to non-empty). Latent only.

• info — Copy-typed key material leaves brief stack residue by design. random::random_array, hmac_sha3_256, and the various [u8; 32] deref-copies documented throughout return Copy values the callee can't zeroize. Every in-library use zeroizes the staging copy (e.g. x25519.rs:62, mlkem.rs:162, call.rs:312, ratchet.rs:174), and the hazard is called out in the CHEATSHEET for callers. Noted for completeness, not a defect.

• info — nonce-reuse footguns are deprecated/documented, not defects. Double-from_bytes (ratchet/mod.rs:1114, #[deprecated], with an explicit double-deserialization warning and the from_bytes_with_min_epoch safe path) and reusing a streaming (index, is_last) pair via encrypt_chunk_at (streaming.rs:281, explicit SECURITY warning) both cause catastrophic nonce reuse if misused, but each ships with a safe alternative and in-code warnings.

Coverage

Read in full (to the test boundary given in the brief), in dependency order: README.md; CHEATSHEET.md (all 2354 lines); soliton/Cargo.toml; src/lib.rs; src/error.rs; src/constants.rs (1–163); src/primitives/mod.rs; src/primitives/random.rs (1–34); src/primitives/sha3_256.rs (1–28); src/primitives/hmac.rs (1–40); src/primitives/hkdf.rs (1–44); src/primitives/aead.rs (1–109); src/primitives/ed25519.rs (1–58); src/primitives/x25519.rs (1–105); src/primitives/mlkem.rs (1–314); src/primitives/mldsa.rs (1–436); src/primitives/xwing.rs (1–395); src/primitives/argon2.rs (1–145); src/identity/mod.rs (1–349); src/auth/mod.rs (1–102); src/kex/mod.rs (1–924); src/verification.rs (1–125); src/ratchet/mod.rs (1–1606); src/streaming.rs (1–549); src/storage/mod.rs (1–593); src/call.rs (1–318). No file was skimmed; every allowed source file was read line-by-line. Test modules, tests/, benches/, fuzz/, build.rs, Specification.md, Abstract.md, and all non-core crates were not opened, per the brief. No build or scratch experiment was needed — the notes were settled by reading. Constants in constants.rs were cross-checked against the standard sizes (ML-KEM-768 1184/2400/1088, ML-DSA-65 1952/3309/32 seed, X25519/Ed25519 32/64, X-Wing 1216/2432/1120, composite 3200/2496, hybrid sig 3373) and against every use site; all agree.