feat: add post-quantum hybrid Noise handshake

[paschal533]

Post-quantum hybrid Noise handshake (XXhfs) for js-libp2p-noise

Implements Noise_XXhfs_25519+ML-KEM-768_ChaChaPoly_SHA256 — the hybrid Noise handshake combining X25519 (classical) with ML-KEM-768 (post-quantum) in the KEM slot, as proposed in libp2p/specs#723.

Status: Research/WIP — not ready for merge, intended to demonstrate the integration point and validate cross-language interop.

What this adds

• src/crypto/pqc.ts — ML-KEM-768 IKem backend via @noble/post-quantum
• src/crypto/pqc.wasm.ts — WASM-accelerated backend (pure-JS stub until WASM is rebuilt for ML-KEM-768)
• src/protocol-pqc.ts — XXhfs handshake state machine wrapping the existing Noise XX machinery
• src/noise-hfs.ts — NoiseHFS ConnectionEncrypter, protocol ID /noise-mlkem768-hfs/0.1.0
• test/pqc-kem.spec.ts, test/pqc-protocol.spec.ts, test/pqc-noise.spec.ts, test/pqc-vectors.spec.ts — test suite
• scripts/noise-hfs-dial.mjs — standalone TCP dialer for cross-language interop testing

Cross-language interop

Tested against royzah/rust-libp2p PR #1 (Rust) and py-libp2p PR #1310 (Python):

Pair	Result
Rust listener + Python dialer	✅ PASS
Rust listener + JS dialer	✅ PASS
Python listener + JS dialer	✅ PASS

All three runtimes speak Noise_XXhfs_25519+ML-KEM-768_ChaChaPoly_SHA256 on /noise-mlkem768-hfs/0.1.0.

Key design decision

X-Wing (which bundles X25519 + ML-KEM-768 as a single KEM) was considered but rejected: the Noise XXhfs pattern already provides classical security through its own DH tokens (ee, es, se), making the X25519 inside X-Wing redundant. Raw ML-KEM-768 in the ekem1 slot is the architecturally correct choice.

ML-KEM-768 sizes

Field	Size
Public key (encapsulation key)	1184 B
Secret key (decapsulation key)	2400 B
Ciphertext	1088 B
Shared secret	32 B
Message A wire size	1216 B (e=32 + e1=1184)
Encrypted ciphertext	1104 B (1088 + 16 AEAD)

[paschal533]

Quick update: I've put together a standalone example repo that shows the XXhfs handshake working end-to-end with real libp2p nodes. It's at https://github.com/paschal533/pqc-libp2p-example

The repo has two layers. The first is a pure-crypto walkthrough you can run with node scripts/handshake-walkthrough.js. It steps through the full XXhfs handshake in process with annotated output showing each message, the X-Wing encapsulate/decapsulate, and a KEM match confirmation. No libp2p involved, just the raw crypto.

The second is a full libp2p setup: a Node.js listener (npm run listener) and a browser client (npm run browser:dev) both negotiating /noise-pq/1.0.0 over WebSockets. You paste the multiaddr into the browser UI, hit Connect, and it shows the remote peer ID, the protocol, and the handshake latency.

I'm also finalising a research paper covering the design rationale, security analysis, and benchmark numbers. I'll link it here once it's ready.

If anyone wants to try it out and has feedback, especially on the API surface or anything that looks off in the handshake walkthrough, I'd really appreciate it.

[paschal533]

Ran the live cross-language interop test today, JS listener, Python dialer, real TCP connection.

Setup:

• Terminal 1: cd js-libp2p-noise && node scripts/node-listener.mjs (JS responder, port 8000)
• Terminal 2: cd py-libp2p && python scripts/interop_dial.py (Python initiator, feat(security): Noise XXhfs post-quantum handshake for py-libp2p (research/WIP) libp2p/py-libp2p#1310)

JS listener output:

Listener peer ID: 12D3KooWHFFVYwAnVQHZTqZhcq1woX11xKsMnujNDPbDyh77kLBa
Protocol: /noise-pq/1.0.0

Listening on tcp://127.0.0.1:8000
Waiting for Python dialer...

Incoming TCP connection from 127.0.0.1:PORT
Starting NoiseHFS responder handshake...
Handshake complete! Remote peer: 12D3KooWRPBkhDbfQmRJjVpR7hkEAmu8FP6mEaTBW61BAryeNjAH
Sent: "hello from JS"
Received: "hello from Python"

✅ INTEROP SUCCESS: Both sides exchanged messages through NoiseHFS!

Python dialer output:

[interop_dial] TCP connection established
[interop_dial] Starting XXhfs handshake (Python = initiator)...
[interop_dial] Handshake complete! Remote peer: 12D3KooWHFFVYwAnVQHZTqZhcq1woX11xKsMnujNDPbDyh77kLBa
[interop_dial] Received from JS: "hello from JS"
[interop_dial] Sent to JS: "hello from Python"

INTEROP SUCCESS
Python <-> JavaScript NoiseHFS handshake complete.
Protocol: Noise_XXhfs_25519+XWing_ChaChaPoly_SHA256

Both runtimes independently derived the same session keys and successfully exchanged encrypted messages. The scripts/node-listener.mjs added in the latest commit is all you need on the JS side to reproduce this.

Node.js v22, Python 3.13, Windows 11.

[paschal533]

WASM backend results + Amdahl's Law finding

Following up on the performance numbers in the PR description. I built a Rust WASM module for the X-Wing KEM to see how much headroom there is on the KEM side, and the results turned up something interesting worth documenting here.

What was built

A standalone Rust crate (src-wasm/) compiled with wasm-pack to a 58 KB .wasm binary. Stack: ml-kem 0.3.0-rc.2 (RustCrypto FIPS 203), x25519-dalek 2.0, sha3 0.10, wasm-bindgen 0.2. Three exported functions: xwing_keygen, xwing_encapsulate, xwing_decapsulate. The secret key is stored as a 64-byte ML-KEM seed rather than the expanded 2400-byte decapsulation key, so the full keypair output is 1312 bytes instead of 3648.

KEM micro-benchmark results (Node.js v22.17.1, x64)

Operation	Pure-JS ms/op	WASM ms/op	Speedup
generateKemKeyPair	3.42	1.40	2.4x
encapsulate	8.32	2.19	3.8x
decapsulate	7.33	3.10	2.4x
Full KEM round-trip	21.43	6.72	3.2x

The WASM numbers are stable across runs (less than 10% variance). The pure-JS numbers show more variance because of V8 JIT tier transitions on a busy dev machine.

The surprising part: full handshake barely moves

Protocol	ms/handshake
Noise_XX classical	~19 ms
Noise_XXhfs pure-JS KEM	~93 ms
Noise_XXhfs WASM KEM	~91 ms

The WASM KEM is 3.2x faster but the full handshake only improves by about 2%. This is Amdahl's Law in action. The KEM is not the only thing happening in a handshake. A complete XXhfs exchange also does roughly:

• 8 SHA-256 invocations
• 4 HKDF derivations
• 4 ChaCha20-Poly1305 AEAD operations
• 2 X25519 DH computations
• 2 Ed25519 signature verifications
• 2 Protobuf encode/decode passes
• 6 async task boundaries (Promise.all, stream reads/writes)

All of those are still pure-JS on pureJsCrypto / @noble/*. The KEM accounts for maybe 25-30% of the total handshake time. Speeding up just that part can only recover a limited fraction of the overhead.

What this means for the ~35-44 ms overhead

To actually get the full handshake close to classical, you need one of:

1. Native Node.js ML-KEM support (planned for v24+) - this would also help the SHA-256/ChaCha20 path since those are already native via defaultCrypto. Best case outcome.
2. A full WASM crypto backend covering all Noise primitives, not just the KEM. Significantly more work but achievable.
3. WebCrypto ML-KEM in browsers when it eventually lands.

For now the WASM module is a useful reference showing what the KEM-only ceiling looks like, and the 58 KB binary is small enough to ship without concern. But the big win on handshake latency is going to come from the Node.js native path, not from this.

The updated benchmark table and this analysis are now in the research write-up. Happy to add a note to benchmarks/results.md here too if that would be useful for reviewers.