clatterjs

Noise post-quantum (PQ) handshakes in TypeScript using @noble/ciphers, @noble/hashes, and @noble/post-quantum (ML-KEM).

Test matrix & parity (vs the clatter Rust crate)

| Area | clatter (Rust) | clatterjs | | --- | --- | --- | | PQ smokes (26 patterns × 8 cipher/hash × ML-KEM sizes) | tests/src/smoke.rs | tests/smoke_pq.test.ts — set TEST_MATRIX=ci for the full matrix; test / test:fast use one cipher/hash and fewer KEM sizes for speed | | verify_handshake transport | tests/src/lib.rs | tests/helpers/harness.ts — verifyHandshake / verifyHandshakePq | | PQ pattern list (order) | pq_handshake_patterns() | src/pqPatterns.ts + export { pqHandshakePatterns } from package root | | TransportState API + tests | src/transportstate.rs + #[cfg(test)] | src/transportState.ts + tests/transportState.test.ts + tests/transport_nq_oneway.test.ts (noise_n one-way violations mirrored) | | Deterministic PQ (DummyRng) | no_getrandom_smoke.rs | tests/no_getrandom_pq.test.ts, tests/helpers/dummyRng.ts (optional first-message snapshot) | | Symmetric + cipher unit tests | symmetricstate.rs / cipherstate.rs | tests/symmetricState.test.ts, tests/cipherState.test.ts | | HandshakePattern PSK + PQ order | handshakepattern.rs | tests/handshakePattern.test.ts | | PQ PSK runtime (pq.rs) | handshakestate/pq.rs | tests/pqHandshake.psk.test.ts | | NQ smokes + no_getrandom + vectors hook | smoke, no_getrandom_smoke, vectors | tests/smoke_nq.test.ts, tests/no_getrandom_nq.test.ts, tests/tier2_nq_vectors.test.ts (optional vectors file currently parse-smoke only) | | Hybrid + dual-layer | smoke hybrid/dual-layer sections | tests/tier3_hybrid.test.ts (smokes + CI matrix), tests/no_getrandom_hybrid_duallayer.test.ts (deterministic no_getrandom parity) | | Hybrid PSK runtime (hybrid.rs) | handshakestate/hybrid.rs | tests/hybridHandshake.psk.test.ts |

Single-KEM vs two vendors: clatter’s Rust tests sometimes cross-check PQClean vs rust_crypto ML-KEM in one run. clatterjs uses a single KEM implementation (@noble/post-quantum); a second KEM back end would be required for the same cross-vendor check.

Scripts

• npm test / npm run test:fast — TEST_MATRIX=fast: one cipher/hash and reduced KEM set; suitable for local development.
• npm run test:ci — TEST_MATRIX=ci: full PQ matrix (all ML-KEM sizes, all eight cipher/hash pairs). Allow several minutes; Vitest is configured with an extended testTimeout in CI.
• npx vitest run tests/transport_nq_oneway.test.ts — direct run for noise_n one-way transport parity checks.
• npx vitest run tests/hybridHandshake.psk.test.ts tests/no_getrandom_hybrid_duallayer.test.ts — targeted hybrid parity checks.

CI timeouts

The full matrix runs hundreds of KEM handshakes. Use test:ci only in CI (or on demand). Adjust testTimeout in vitest.config.ts if hardware is slower.