feat: add post-quantum hybrid Noise handshake

[paschal533]

What this PR does

This adds a second connection encrypter to the package alongside the existing noise(): a post-quantum hybrid handshake called noiseHFS() that implements the Noise_XXhfs_25519+XWing_ChaChaPoly_SHA256 pattern.

The idea is that you can swap noise() for noiseHFS() in your libp2p config and get quantum-safe forward secrecy without giving up any classical security. The handshake is secure if either X25519 or ML-KEM-768 is unbroken.

Background

Store-Now-Decrypt-Later is the main near-term quantum threat for libp2p connections. An adversary capturing encrypted traffic today could decrypt it once a large enough quantum computer exists. Upgrading forward secrecy now (before quantum computers arrive) is the practical defense.

The Noise HFS spec (https://github.com/noiseprotocol/noise_hfs_spec) defines how to add a KEM alongside the existing DH operations in any Noise pattern. This PR applies that to XX, using X-Wing as the KEM.

X-Wing (IETF draft-connolly-cfrg-xwing-kem) is a hybrid of ML-KEM-768 (FIPS 203) and X25519, combined via SHA3-256. Using a hybrid means neither primitive has to be trusted alone -- the combined secret is secure as long as at least one of them is.

Protocol details

• Protocol name: Noise_XXhfs_25519+XWing_ChaChaPoly_SHA256
• libp2p protocol ID: /noise-pq/1.0.0
• KEM library: @noble/post-quantum v0.6.0 (pure JS, works in browsers and Node.js without WASM or native bindings)

The handshake pattern is:

-> e, e1
<- e, ee, ekem1, s, es
-> s, se

The two new tokens are e1 (initiator sends KEM ephemeral public key in Message A) and ekem1 (responder encapsulates and sends back the encrypted KEM ciphertext in Message B, then both sides mix the KEM shared secret into the chaining key).

Message C is unchanged from classical XX.

Wire sizes (empty payload)

Message	Classical XX	XXhfs	Delta
Msg A (initiator to responder)	32 B	1,248 B	+1,216 B
Msg B (responder to initiator)	96 B	1,232 B	+1,136 B
Msg C (initiator to responder)	64 B	64 B	0 B
Total	192 B	2,544 B	+2,352 B

With a real NoiseHandshakePayload (Ed25519 identity + extensions): approximately 500 B classical XX vs approximately 2,852 B for XXhfs.

Performance (Node.js v22.17.1, pure JS)

	ops/s	ms/op
X-Wing keygen	293	3.42
X-Wing encapsulate	120	8.32
X-Wing decapsulate	136	7.33
Classical XX handshake	114	8.75
XXhfs handshake	23	44.18

The ~5x slowdown over classical XX is dominated by X-Wing (about 21 ms per round-trip). Native WASM or Node.js native ML-KEM support (when it lands) would improve this by roughly 3-10x. See benchmarks/results.md for the full breakdown.

New files

File	Description
src/kem.ts	IKem interface
src/crypto/pqc.ts	X-Wing KEM backend (pure JS)
src/crypto/pqc.node.ts	Node.js backend slot with TODO for native ML-KEM-768
src/protocol-pqc.ts	XXhfsHandshakeState state machine
src/performHandshake-hfs.ts	Initiator and responder orchestration
src/noise-hfs.ts	NoiseHFS encrypter + noiseHFS() factory
NOISE_HFS_SPEC.md	Full wire format spec + security analysis
benchmarks/benchmark-pqc.js	Benchmark runner
benchmarks/results.md	Measured results
scripts/generate-pqc-vectors.js	Deterministic test vector generator
test/fixtures/pqc-test-vectors.json	5 committed test vectors
test/pqc-kem.spec.ts	IKem unit tests (17)
test/pqc-protocol.spec.ts	Handshake state machine tests (18)
test/pqc-noise.spec.ts	Integration tests (12)
test/pqc-vectors.spec.ts	Test vector verification (52)

Usage

import { createLibp2p } from 'libp2p'
import { noiseHFS } from '@chainsafe/libp2p-noise'

const node = await createLibp2p({
  connectionEncrypters: [noiseHFS()],
  // ... other options
})

Both peers must use noiseHFS(). It is not backward-compatible with the classical /noise protocol because the handshake message layout differs.

Notes on PR #3432

js-libp2p PR #3432 (feat: Post quantum identities with ML-DSA by @dozyio) adds ML-DSA identity support. When that lands, NoiseHFS will support ML-DSA identity keys automatically because privateKey.sign() is key-type aware. No changes needed in this layer.

With ML-DSA identity on both sides, the full-PQ wire size would be approximately 9,400 bytes total. benchmarks/results.md has the full breakdown. For most use cases, noiseHFS() with Ed25519 identity is a reasonable first step that covers the main Store-Now-Decrypt-Later threat without waiting for the identity layer migration.

Test plan

• pnpm build passes with no TypeScript errors
• pnpm test:node passes all 99 new tests (plus existing suite)
• node benchmarks/benchmark-pqc.js runs and produces output matching benchmarks/results.md
• node scripts/generate-pqc-vectors.js regenerates identical vectors (deterministic)
• Review NOISE_HFS_SPEC.md for protocol correctness