feat(security): Noise XXhfs post-quantum handshake for py-libp2p (research/WIP)

[paschal533]

Noise XXhfs post-quantum handshake for py-libp2p (research/WIP)

Implements Noise_XXhfs_25519+MLKEM768_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. The wire format is specified in libp2p/specs#727, a Stage 1A Working Draft by @royzah. My own draft, libp2p/specs#716, was closed on 2026-09-18 in favour of #727 so that one document rather than two carries the proposal; its text stays readable at https://github.com/paschal533/specs/tree/master/noise-pq, and the material it covered (test vectors, the interoperability matrix, wire sizes and the downgrade analysis) was offered to #727.

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

Breaking change (2026-09-17): the suite was renamed from Noise_XXhfs_25519+ML-KEM-768_ChaChaPoly_SHA256, because Noise (revision 34, §8.2) allows only alphanumerics and / in algorithm names. The name is hashed into the handshake hash, so old-name and new-name peers cannot complete a handshake, and the protocol id moved from /noise-mlkem768-hfs/0.1.0 to /noise-mlkem768-hfs/0.2.0. Message sizes are unchanged. /noise-mlkem768-hfs/0.2.0 is the id this branch ships, not a spec-endorsed one: #727 writes /noise-mlkem768-hfs/0.1.0 and lists the identifier string as the first of its open issues, so this will follow whatever #727 settles on.

Update, 2026-09-19: a C-backed ML-KEM-768 backend is now the default

The branch previously had one KEM backend, kyber-py, which is pure Python. It is no longer the default.

• MLKEM768NativeKem implements the same IKem contract over cryptography.hazmat.primitives.asymmetric.mlkem, which reaches ML-KEM-768 in C through OpenSSL 3.5+, AWS-LC or BoringSSL depending on how cryptography was built.
• make_fast_kem() selects it whenever it can be constructed, and falls back to kyber-py otherwise. Taking the fallback logs a warning that names the cause and says plainly that kyber-py's own package metadata states it is not constant time and must not be used for cryptographic applications.
• Selection is memoised per process. It used to be re-run for every inbound connection, which charged an ML-KEM probe to every unauthenticated peer before it had authenticated anything; it is now resolved once, at TransportPQ construction, so a host with no working backend fails at construction rather than on its first connection.
• kyber-py stays in the pq extra as the pure-Python fallback and as the second implementation the cross-backend parity tests check against.

Two asymmetries between the backends are deliberate and pinned by tests. cryptography's encapsulate() returns (shared_secret, ciphertext) while the IKem contract is (ciphertext, shared_secret), so the adapter swaps the pair; transposing it would put a 1088-byte ciphertext where a 32-byte key belongs, so there is an explicit guard for it. And cryptography exposes only the 64-byte FIPS 203 seed (d || z) as the private key, where kyber-py exposes the 2400-byte expanded decapsulation key. The secret key never goes on the wire, so only pk (1184 B) and ct (1088 B) are interoperability surfaces, and both are identical under the two backends.

Nothing on the wire changes. Both backends produce a 1184-byte encapsulation key, a 1088-byte ciphertext and a 32-byte shared secret; a ciphertext from either decapsulates to the same shared secret under the other; and the deterministic vector fixture is byte-identical before and after. The vector generator deliberately stays on kyber-py, which is recorded in the script header.

Performance

Measured as alternating paired arms of one session, four passes of thirty iterations, each pass interleaving the classical and hybrid handshakes and alternating which runs first. Python 3.13.14, cryptography 50.0.1, Windows 11 Pro x64, in-memory trio channel pairs, this branch at c8d16e63:

Python arm	classical Noise_XX	hybrid Noise_XXhfs	overhead	KEM share
kyber-py (pure Python)	2.25 to 2.30 ms	24.73 to 25.31 ms	10.76x to 10.87x	~91%
MLKEM768NativeKem (C-backed)	2.05 to 2.21 ms	2.99 to 3.15 ms	1.42x to 1.44x	~30%

Ranges are the two pass medians for that arm; the overhead is the median of the per-iteration paired ratios within each pass. The kyber-py arm is the control, and it matters more than the headline: it reproduces the 10.7x and the ~91% published from a session nine days earlier, which is what makes this a before and after of one change rather than two benchmarks on two days. An earlier run of the same change on the same machine, with a slightly faster classical baseline, put the ratio nearer 1.7x; the two sessions bracket it between roughly 1.4x and 1.7x, and what does not move is the order of magnitude.

Standalone KEM microbenchmarks are unstable in both absolute terms and ratio, and should be read with more caution than the handshake figures above. Across four measurement sessions the C-backed-to-kyber-py ratio on an encapsulate-plus-decapsulate round trip came out at 33x, 37x, 38x and 43x, while kyber-py's own absolute round trip swung by roughly a factor of two within a single day: about 16.6 ms in the block adjacent to the paired passes against 34.8 ms in a later block (0.45 ms and 0.91 ms C-backed respectively). Read it as one to two orders of magnitude, not as a figure. An earlier one-off probe reported 47.8x; it does not reproduce and is withdrawn.

The contrast with the handshake table is methodological rather than incidental. The handshake ratios are paired: every iteration measures the classical and hybrid handshakes next to each other and the ratio is formed within the pass, so drift is common mode and largely cancels, which is why they hold to 1.42x to 1.44x and 10.76x to 10.87x. The KEM microbenchmarks are not paired against anything, so each one absorbs whatever state the machine was in. An earlier version of this description claimed the KEM ratio was stable while the absolutes moved; that was inferred from the two blocks that happen to agree at 37x and 38x, and the 33x and 43x sessions show it does not hold, so the claim is withdrawn. All of these are performance measurements only and say nothing about side-channel resistance.

All figures are from one machine. There is no second-hardware measurement, and benchmarks/bench_noise_pq.py now records and prints which backend make_fast_kem() actually selected, because the two differ by more than an order of magnitude and an unattributed number is not usable.

Dependency changes

• Core dependencies gain cryptography>=42.0.0. It was previously undeclared and arrived transitively through aioquic. 42.0.0 is established from the code rather than guessed: the newest API the core importers use unguarded is x509.Certificate.not_valid_before_utc / not_valid_after_utc, in libp2p/transport/quic/security.py and libp2p/transport/webtransport/certificate.py, added in 42.0.0. It is also exactly what aioquic already declares, so it adds no new constraint in practice.
• The pq extra is ["cryptography>=48.0.0", "kyber-py>=0.9.0"]. The 48.0.0 floor is where the native backend's requirement belongs rather than in core, because pyOpenSSL <= 25.3.0 caps cryptography below 47 and a hard core floor of 48 would make those environments unresolvable.
• The test dependency group gains cryptography>=48.0.0 alongside kyber-py, so CI exercises both backends instead of skipping the native half of the parity and mixed-backend tests.
• The pq-fast extra is removed. It installed liboqs-python, which nothing in the branch ever selected.

Security hardening, 2026-09-18 and 2026-09-19

A white-box audit of this branch found issues the 48-run interop matrix did not catch, because interop tests exercise well-formed peers.

• Handshake message lengths are validated, and the parser fails closed. The XXhfs parser previously extracted every field with a bare Python slice and checked no message length at all. Python slices do not raise, so a short message silently yielded a short field, and PyNaCl's crypto_scalarmult does no length validation either: it hands both operands to libsodium, which unconditionally reads 32 bytes from each. A remote peer could therefore drive an out-of-bounds read in native code. Two attacker-controlled paths reached it. Message A is entirely pre-authentication. Message C is worse in kind, because the static key length there is chosen after a successful AEAD decryption, so a peer that completes A and B honestly can forge a valid 20-byte ciphertext whose plaintext is only 4 bytes and still reach crypto_scalarmult. Messages A, B and C are now length-checked before parsing, against both the fixed-token minimum and a maximum of that plus a 4096-byte payload ceiling, which bounds the unauthenticated trailing blob mixed into the transcript hash well below the 65535-byte frame limit.
• A typed error. HandshakeMalformed(NoiseFailure) is raised for these rejections, matching how classical libp2p/security/noise/patterns.py reports handshake failures. Previously a truncated message surfaced as nacl.exceptions.RuntimeError, cryptography.exceptions.InvalidTag or a bare ValueError crossing the ISecureTransport boundary.
• The interop harness greeting is bounded and the run has a deadline, so the test scripts cannot be driven to read unboundedly or hang.

To be clear about what is not done: this is a research branch and has had no third-party security audit. The findings above were found by reading the code, not by fuzzing, and there is no fuzz harness in the branch.

Update, 2026-09-22: transcript-bound security protocol negotiation

multistream-select chooses the connection encrypter in plaintext, before any handshake runs, so an on-path attacker can strip a proposal or forge an na and push two peers that both prefer the hybrid suite onto classical /noise. Both sides then complete a valid, mutually authenticated session and neither can tell. The interop matrix above does not cover this, because those harnesses start the handshake directly on TCP.

This branch now carries a defence for it, off by default and enabled per transport with transcript_binding. Each peer states the security protocols it has configured inside the encrypted handshake payload, bound to the Noise transcript hash, and both peers recompute what the negotiation should have produced:

expected = the first protocol the dialer offered that the listener also supports

The listener catches a stripped proposal, the dialer catches a forged na, and the selected protocol never goes on the wire, because each peer already knows which one it is running. A mismatch raises SecurityProtocolDowngrade(NoiseFailure). Both Noise transports have it, classical and XXhfs.

Two bindings are implemented. The extension variant adds a separate transcript_sig field and stays wire compatible with peers that do not implement it. The identity variant folds the binding into identity_sig, which is one signature rather than two.

identity is not incrementally deployable, and not only in the sense of missing a feature. The protocol list is inside identity_sig, so a peer that sends no list signed a different message and the handshake fails during signature verification, before any mode is consulted: warn mode does not soften it. A node configured that way cannot connect to a stock libp2p peer at all, nor to a peer using extension. Falling back to the unbound form on failure would let an attacker strip the binding at will, so the incompatibility is deliberate, and it is pinned by tests rather than left to be discovered. Deploying identity means giving it its own protocol identifier.

Why the extra signature is kept, although it is redundant against the attacker it was written for. The handshake payload is AEAD-encrypted with h as associated data, and identity_sig binds the peer's static key to its identity key, so a list carried inside that payload already cannot be altered, reordered, replayed across sessions or spliced between the classical and hybrid suites; the protocol name seeds h and therefore the whole key schedule. Against the multistream-select attacker, transcript_sig adds nothing.

The reason to keep it is that identity_sig is session-independent. It covers SIGNED_DATA_PREFIX followed by the Noise static public key and nothing else: no transcript, no nonce. It is a replayable statement about a long-lived key, so the authentication of everything in the payload rests on possession of the X25519 static key rather than the identity key. A transcript-bound signature is the only element in the handshake that shows the identity key is live in this session, which is what an ML-DSA identity key would need in order to make the hybrid suite post-quantum authenticated rather than post-quantum confidential only.

Where the transcript hash comes from, and why the two paths differ. PatternXXhfs owns its SymmetricState, so it reads ss.h directly at the point the payload is encrypted or decrypted. The classical path runs on the third-party noiseprotocol package, whose write_message runs the tokens and encrypts the payload in one call, so the payload cannot be built after h is final without a scoped hook on encrypt_and_hash. The hook is installed only when binding is enabled, refuses to nest, removes itself with dict.pop so it cannot mask an in-flight exception from a finally block, and raises if it never fired rather than silently shipping the empty placeholder as the payload. The alternative is owning an XX state machine the way pq/noise_state.py does, which is a much larger change; the asymmetry is deliberate and commented.

A bug found in review, before this was committed. Under the identity variant, building the signed data from the remote peer's protocol list was attacker reachable: the canonical encoding rejects a list longer than MAX_PROTOCOLS by raising, and that call sat outside the try, so a peer sending 33 short protocol strings made verify_handshake_payload_sig raise ValueError out of a function documented to return bool. A caller catching NoiseFailure to reject a peer and keep serving would have seen an unclassified exception instead. It is now caught and the signature rejected, which is what the extension variant already did for the same input, and a test covers both variants.

Wire format. NoiseExtensions gains security_protocols (field 4) and transcript_sig (field 5). early_data keeps field 3, so no existing wire format changes. Fields 4 and 5 rather than 3 and 4 because field 3 was already taken here, and renumbering a field this implementation already ships would break its own wire format for no gain. Regenerated with protoc 6.32.1, matching the committed gencode version.

Cross-implementation vectors. Two implementations can agree on every word of the design and still fail to interoperate over one byte: a different canonical encoding, a different signature prefix, or different protobuf field numbers. Each side's own tests pass and the handshake fails in the field. tests/fixtures/transcript-binding-vectors.json is generated by the TypeScript implementation in ChainSafe/js-libp2p-noise PR #665, and tests/security/noise/test_transcript_vectors.py verifies signatures it produced rather than round-tripping our own, which is what proves the two agree on the bytes. Two of the five vectors are ['ab', 'c'] and ['a', 'bc'], which collide under naive concatenation, so an implementation that drops the length prefixes passes its own round-trip tests and fails this file.

What it does not do. It cannot see a downgrade out of Noise entirely. A real node's offered set may include /tls/1.0.0, and an attacker who strips every Noise proposal forces TLS, where no Noise handshake runs and nothing checks anything. That is the attacker's best move, and covering it needs the check in the shared upgrader, where the full offered set lives, rather than inside one secure transport. It also cannot see an attacker who strips the extension itself, since that is indistinguishable from talking to an older peer. And it protects a session only when both peers implement it. (Superseded: see the 2026-09-25 update below, which closes the cross-language interop gate this sentence described as open.)

_PatternXXWithCerthashes in the WebTransport session reimplements handshake_outbound inline and does not route through the new helpers, so the binding is neither sent nor checked there. Nothing passes it a config today, so it is not live, but it is a fail-open by construction and is the next thing to fix on this path.

Unrelated fix in the same branch. scripts/audit_paths.py excluded venv, site-packages and friends with patterns written using forward slashes, matched against str(Path). On Windows that string uses backslashes, so none of the exclusions matched and the audit walked the entire virtualenv: 63,201 findings, 6,631 of them P0 or P1, which fails the pre-commit hook on every commit. It now matches against a normalised forward-slash form, reconfigures stdout to UTF-8 so the non-ASCII status characters do not raise on a legacy Windows codepage, and excludes build/, which is setuptools output and gitignored.

Tests. 92 added. tests/core/security with tests/security/noise collects 419, of which 418 pass; the one failure is a pre-existing lru_cache interaction in test_kem_native.py that predates this change and is unrelated to it.

Test module	Count
tests/core/security/noise/test_transcript_binding.py	50
tests/security/noise/test_transcript_vectors.py	35
tests/security/noise/pq/test_transcript_binding_pq.py	7

Update, 2026-09-25: the two binding variants are deployed separately, and the interop gate is met

Two changes since the section above, one of which corrects it.

Each variant now only exists where it can work. Both were selectable on both encrypters, which made one of the four combinations unusable: the identity variant on /noise. It widens what identity_sig covers, and /noise is an identifier every libp2p implementation already answers to, so such a peer negotiates /noise successfully and then fails signature verification against all of them, in any mode. Offering that behind a flag is offering a network partition behind a flag, so it is refused at construction now, with a message saying where the variant is available instead.

The extension variant stays on /noise, since it is the only one that can ship incrementally. The identity variant lives on the hybrid suite and moves the protocol identifier to /noise-mlkem768-hfs/0.3.0. The identifier is the mechanism rather than bookkeeping: a peer verifying a different message must not answer to the identifier used by peers that do not, or multistream-select pairs them and the difference surfaces as a signature error instead of as no protocol in common. 0.3.0 derives from the 0.2.0 this branch ships and follows whatever #727 settles on for the base.

Because that identifier is now a string literal in two implementations, the cross-implementation vector file records both identifiers alongside the signature prefixes and field numbers, and each implementation asserts its own constants against it. A typo there fails no implementation's own tests: it shows up in the field as two peers with no protocol in common. Verified by changing 0.3.0 to 0.3.1 on one side and watching it fail with the exact mismatch.

The interop harnesses now have a flag, so the gate the section above said was open is closed. --transcript-binding off|extension|identity and --simulate-downgrade, driven from the matrix runner by TRANSCRIPT_BINDING and SIMULATE_DOWNGRADE. Four runs, all in pq-noise-artifacts:

run	mode	result
20260925T123204Z	off	48 of 48
20260925T124411Z	extension	48 of 48
20260925T125139Z	identity, JS and Python	12 of 12
negative-controls/C-downgrade-extension	extension, simulated downgrade	0 of 4 passed
negative-controls/C-downgrade-identity	identity, simulated downgrade	0 of 4 passed

The off run is the regression check: an off run invokes exactly what it always did, so 48 of 48 says this feature changed nothing for the four implementations.

The extension run is the one worth reading. Only JS and Python are bound; the Nim and Rust harnesses have no flag and ran unbound. That is the experiment rather than a gap: a peer that binds its handshake completed with three implementations that know nothing about the mechanism, because an older peer ignores the unknown extension fields. Incremental deployability was previously an argument about protobuf semantics and is now a measured outcome.

The identity run is restricted to JS and Python, and the runner refuses Nim or Rust by name for that mode, because a bound peer cannot talk to an unbound one at all there. Producing 48 failures instead would read as a protocol bug rather than a configuration error.

The negative controls are the half that makes the rest mean anything, and 0 of 4 passing is the pass condition. Both peers offer a protocol neither runs but both claim to prefer, so each concludes the other should have negotiated it. Every run fails naming /noise-interop-phantom/1.0.0 as what should have been negotiated, on both sides and in both languages.

That control is not ceremony. The first version of the harness flag reported success in every mode while exercising nothing, because the encrypter takes (components, init) and the option had been placed in components, where it is silently ignored. Same-implementation runs passed because both sides were equally unbound. Only the cross-language run exposed it.

Correction to the section above. It said a live cross-language handshake with the flag on was not done, and that the agreement so far was on the bytes rather than on a connection. That is no longer true, in either direction and in both variants.

Still not covered, unchanged: a downgrade out of Noise entirely, to /tls, is invisible to this, and it needs the check in the shared upgrader rather than inside one encrypter. The matrix harnesses start the handshake directly on TCP, so they exercise the binding but not multistream-select negotiation itself; experiments/downgrade-demo is what covers the negotiation path against real libp2p nodes.

What this adds

• libp2p/security/noise/pq/kem.py: MLKEM768Kem (kyber-py) and MLKEM768NativeKem (cryptography, C-backed)
• libp2p/security/noise/pq/patterns_pq.py: PatternXXhfs handshake state machine, with length validation and HandshakeMalformed
• libp2p/security/noise/pq/noise_state.py: NoiseStateXXhfs (HKDF chain, cipher state)
• libp2p/security/noise/pq/transport_pq.py: TransportPQ ISecureTransport, protocol ID /noise-mlkem768-hfs/0.2.0, KEM resolved once at construction
• libp2p/security/noise/pq/kem_backends.py: make_fast_kem() factory (C-backed by default, kyber-py fallback behind a warning) and KeypairPool
• tests/security/noise/pq/: 162 tests, including test_kem_native.py (57) for the C-backed backend and cross-backend interoperability, and test_vectors_pq.py, which replays tests/fixtures/mlkem768-xxhfs-vectors.json and checks the three handshake messages, the handshake hash and both split() cipher keys
• scripts/interop_dial_mlkem768.py: TCP dialer harness driving PatternXXhfs
• scripts/interop_listen_mlkem768.py: TCP listener harness driving PatternXXhfs
• benchmarks/bench_noise_pq.py: classical vs hybrid handshake benchmark, sampled in interleaved pairs, reporting both KEM backends and naming the one selected

Test count. 162 at c8d16e63, against 56 when this description was first written. The increase is almost entirely the backend work and the hardening: 57 tests for MLKEM768NativeKem itself, the parametrisation of the pattern and transport suites so the full handshake runs end to end under each backend in turn, and 25 tests for malformed, truncated and oversized handshake messages.

Test module	Count
test_kem.py	12
test_kem_native.py	57
test_noise_state.py	15
test_patterns_pq.py	22
test_transport_pq.py	16
test_vectors_pq.py	10
test_handshake_validation.py	25
test_interop_io.py	5
Total	162

Cross-language interop

On 2026-09-19 a neutral runner drove four implementations: this branch, js-libp2p-noise PR #665 (TypeScript), nim-libp2p PR #2811 (Nim), and rust-libp2p PR #6481 by @royzah (Rust) with the harness from royzah/rust-libp2p PR #1. Every ordered listener/dialer pairing, each implementation against itself included, ran three times with this branch at c8d16e63: 48 runs, 48 passed.

listener \ dialer	JS	Python	Nim	Rust
JS	3/3	3/3	3/3	3/3
Python	3/3	3/3	3/3	3/3
Nim	3/3	3/3	3/3	3/3
Rust	3/3	3/3	3/3	3/3

This is the first matrix run with the C-backed ML-KEM-768 backend on the Python side, so it is also the evidence that switching backend changed nothing on the wire. None of the 96 logs carries the fallback warning that backend selection emits when it drops to kyber-py, which is the positive evidence that the C-backed path was the one under test.

A run passes only if both sides exit cleanly, each side reports the other's actual peer id, and one encrypted greeting goes each way, which exercises both split() cipher states. All runs were over loopback TCP on one Windows 11 machine. The harnesses start the handshake directly on TCP, so multistream-select negotiation of the protocol id is not covered. Results, versions.txt and all 96 logs: pq-noise-artifacts, run 20260919T223056Z. Negative controls (an old-name build that fails against every other implementation, and a fabricated identity that the cross-check catches): interop/negative-controls.

Earlier results, corrected. An earlier version of this description showed a June 2026 table (Rust listener + Python dialer, Rust listener + JS dialer, Python listener + JS dialer, all PASS) on /noise-mlkem768-hfs/0.1.0 with the hyphenated name, run by scripts/interop_all.sh. Those runs were handshake-only: the script counted a pair as passing when the dialer exited cleanly and printed a peer id, and no transport frames were exchanged. The Python dialer was a standalone re-implementation of the handshake, not PatternXXhfs. The Rust listener was ours, from royzah/rust-libp2p#1, not part of #6481, and was built against a June snow that still used the hyphenated name. interop_all.sh is removed and the matrix above replaces that table. Details: artifacts README.

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.

KEM API note

Both backends return the shared secret first: kyber-py's ML_KEM_768.encaps(pk) returns (ss, ct), and cryptography's encapsulate() returns (shared_secret, ciphertext). Both adapters correct the order to (ct, ss) per the IKem interface, and a test pins it.

ML-KEM-768 sizes

Field	Size
Public key (encapsulation key)	1184 B
Secret key (decapsulation key)	2400 B kyber-py, 64 B seed cryptography (never on the wire)
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]

Just ran the live interop test end-to-end... wanted to confirm it actually works before people try to reproduce it.

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)

Output:

2026-04-17 13:09:45 [interop_dial] Local peer ID: 12D3KooWRPBkhDbfQmRJjVpR7hkEAmu8FP6mEaTBW61BAryeNjAH
2026-04-17 13:09:45 [interop_dial] Connecting to JS listener at 127.0.0.1:8000
2026-04-17 13:09:45 [interop_dial] TCP connection established
2026-04-17 13:09:45 [interop_dial] Starting XXhfs handshake (Python = initiator)...
2026-04-17 13:09:45 [interop_dial] Handshake complete! Remote peer: 12D3KooWHFFVYwAnVQHZTqZhcq1woX11xKsMnujNDPbDyh77kLBa
2026-04-17 13:09:45 [interop_dial] Received from JS: "hello from JS"
2026-04-17 13:09:45 [interop_dial] Sent to JS: "hello from Python"

============================================================
INTEROP SUCCESS
Python <-> JavaScript NoiseHFS handshake complete.
Protocol: Noise_XXhfs_25519+XWing_ChaChaPoly_SHA256
Local peer:  12D3KooWRPBkhDbfQmRJjVpR7hkEAmu8FP6mEaTBW61BAryeNjAH
Remote peer: 12D3KooWHFFVYwAnVQHZTqZhcq1woX11xKsMnujNDPbDyh77kLBa
============================================================

Two completely separate runtimes, one real TCP socket, same handshake keys on both ends. The cross-language test vectors in test_vectors_pq.py already verify byte-level compatibility statically, this confirms it works dynamically over an actual connection too.

The JS listener script (scripts/node-listener.mjs) is now committed to the js-libp2p-noise PR branch so anyone can reproduce this: ChainSafe/js-libp2p-noise#665

Node.js v22, Python 3.13, Windows 11, both sides happy.

[paschal533]

Performance update: WASM KEM results from the JS side and what they mean here

I ran more detailed performance work on the JS implementation this week and wanted to share the findings here since they are relevant to both PRs.

What I measured on the JS side

Built a Rust WASM module for X-Wing (58 KB binary, ml-kem 0.3.0-rc.2 + x25519-dalek + sha3) and benchmarked it against the pure-JS noble backend.

KEM micro-benchmarks (Node.js v22.17.1):

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

The WASM KEM is 3.2x faster on the KEM operations. But the full handshake barely moves:

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

Less than 2% improvement on the full handshake even though the KEM is 3x faster. This is Amdahl's Law. The KEM accounts for maybe 25-30% of total handshake time. The rest is SHA-256, ChaCha20-Poly1305, HKDF, X25519, Ed25519, Protobuf, and async scheduling overhead, all of which are still running in interpreted code regardless of what the KEM is doing.

What this means for the Python benchmarks

The Python numbers in this PR (10x overhead vs classical, ~40 ms for XXhfs) are in a similar position. Swapping kyber-py for liboqs-python would speed up the KEM operations considerably, maybe 10-20x on that component alone, but if the rest of the handshake is in pure Python the total improvement will be limited by the same bottleneck.

From a rough breakdown: the KEM round-trip in Python is about 38 ms (10.5 + 12.3 + 15.5 ms). The full handshake is 40.7 ms, which means the non-KEM overhead is only about 2-3 ms. So actually the Python situation is the inverse of JS - the KEM dominates much more strongly here (around 90% of handshake time vs maybe 30% in JS). That means a fast KEM backend like liboqs would make a much bigger difference in Python than it does in JS.

If liboqs-python is available, switching to it for the KEM path should bring the XXhfs handshake close to the classical baseline. The make_fast_kem() pattern in kem_backends.py is designed for exactly that: it picks liboqs if available and falls back to kyber-py.

Summary

• On the JS side: WASM KEM is 3x faster for the KEM, but the full handshake improvement is under 2%. The bottleneck is the rest of the crypto stack. The path to meaningful improvement is native Node.js ML-KEM (v24+).
• On the Python side: the KEM is a much larger share of total handshake time, so a fast KEM backend (liboqs) would actually move the needle significantly. Worth making that the default recommendation when liboqs is available.

Happy to share the full benchmark script if useful.

[paschal533]

Posting actual benchmark numbers from the bench_noise_pq.py suite (Python 3.13.1, Windows 11 Pro x64, in-memory connections, kyber-py baseline).

KEM micro-benchmarks

Operation	ms/op	ops/s
X-Wing keygen	8.09	123.6
X-Wing encapsulate	8.30	120.5
X-Wing decapsulate	10.76	92.9
KEM round-trip (encap + decap)	19.06	--

Handshake latency (round-trip, in-memory)

Protocol	ms/op	ops/s
Classical Noise XX	3.32	301.2
Noise XXhfs (PQ)	42.96	23.3
Overhead	12.9x	--

Transport throughput (post-handshake)

Payload	Classical	PQ	Ratio
1 KB	8.0 MB/s	8.1 MB/s	1.02x
10 KB	61.0 MB/s	62.7 MB/s	1.03x
60 KB	215.9 MB/s	227.9 MB/s	1.06x

A few notes on these numbers:

The KEM round-trip accounts for 63% of total XXhfs handshake time (27.15 ms out of 42.96 ms). The remaining 15.81 ms is non-KEM overhead, which is notably higher than the 3.32 ms classical baseline. The extra cost comes from ChaCha20-Poly1305 encryption of the 1,120-byte KEM ciphertext, HKDF key derivation, and Ed25519 signing, all running in CPython without native acceleration.

Using Amdahl's Law with f = 0.632 and a ~50x speedup from liboqs:

new_time = 42.96 * ((1 - 0.632) + 0.632 / 50) = 42.96 * 0.381 ~= 16.4 ms

So the liboqs backend is predicted to bring XXhfs down to roughly 16 ms, about 5x over the classical baseline rather than matching it. Still a substantial win (12.9x to 5x), and transport throughput is already on par with classical since both paths use the same ChaCha20-Poly1305 cipher state after the handshake.

The make_fast_kem() function and pq-fast optional dependency group added in this PR handle the liboqs selection automatically. When liboqs is not installed, the fallback to kyber-py is seamless and the numbers above reflect that fallback path.

[acul71]

@paschal533

AI PR Review — #1310

PR: feat(security): Noise XXhfs post-quantum handshake for py-libp2p (research/WIP)
Author: @paschal533
Branch: feat/pqc-noise-xxhfs → main
State: Open (Draft)
Review date: 2026-06-08
Reviewer: AI-assisted review (py-libp2p PR review prompt)

---

1. Summary of Changes

This PR adds exploratory support for a post-quantum Noise handshake under protocol ID /noise-pq/1.0.0, implementing Noise_XXhfs_25519+XWing_ChaChaPoly_SHA256. The classical /noise transport and PatternXX are untouched.

New modules (all under libp2p/security/noise/pq/):

Module	Role
kem.py	X-Wing hybrid KEM (ML-KEM-768 + X25519) with IKem protocol
kem_backends.py	Optional liboqs C backend, make_fast_kem(), KeypairPool
noise_state.py	Standalone SymmetricState / CipherState for XXhfs
patterns_pq.py	PatternXXhfs three-message handshake state machine
transport_pq.py	TransportPQ implementing ISecureTransport

Supporting additions:

• 92 tests under tests/security/noise/pq/ (KEM, state, patterns, transport, cross-implementation vectors)
• scripts/interop_dial.py — live TCP dialer for Python↔JS interop
• benchmarks/bench_noise_pq.py + benchmarks/results.md
• Optional pq-fast extra in pyproject.toml for liboqs

Related context (not issues):

• Discussion #1306 — design planning thread
• ChainSafe/js-libp2p-noise#665 — JS counterpart
• libp2p/specs#716 — Stage 1 working draft spec

Breaking changes: None. This is additive and opt-in via a new protocol ID.

Author intent: Explicitly marked as draft/research — "Nothing here is intended for merge right now."

---

2. Branch Sync Status and Merge Conflicts

Branch Sync Status

• Status: ℹ️ Ahead of origin/main (no divergence)
• Details: 0 6 — branch is 0 commits behind and 6 commits ahead of origin/main
• Recent merge commit from maintainer @acul71 (Merge branch 'main' into feat/pqc-noise-xxhfs) keeps the branch current

Merge Conflict Analysis

✅ No merge conflicts detected. The PR branch merges cleanly into origin/main.

---

3. Strengths

• Clean isolation. All PQC code lives in a new pq/ subpackage; classical Noise is unmodified, reducing regression risk.
• Sound architectural choice. A dedicated XXhfs state machine (rather than extending noiseprotocol) aligns with maintainer guidance in Discussion Post-Quantum Noise handshake for py-libp2p (XXhfs + X-Wing KEM) #1306 and correctly handles custom e1/ekem1 tokens.
• Pluggable KEM design. The IKem protocol with XWingKem (pure Python) and LibOQSXWingKem (C) backends is well thought out; make_fast_kem() provides sensible auto-selection with graceful fallback.
• Strong test structure. Layered tests from KEM primitives → symmetric state → full handshake → transport interface → cross-implementation vectors. Error paths (bad signatures, peer ID mismatch, wrong key sizes) are covered.
• Wire compatibility evidence. When vector fixtures are available, 47 byte-level assertions against js-libp2p-noise vectors provide strong interop proof. Author also demonstrated live Python↔JS TCP interop.
• Identity handling matches classical Noise. Ed25519 libp2p identity signatures via existing make_handshake_payload_sig / verify_handshake_payload_sig abstractions — correct separation from the PQC KEM layer.
• Performance awareness. Benchmarks, Amdahl's Law analysis, and documented latency/wire-size trade-offs show mature engineering thinking.
• Code quality (partial). Ruff, mypy, formatting, and most pre-commit hooks pass on the PR branch.

---

4. Issues Found

Critical

• File: pyproject.toml
• Line(s): 20–49 (core dependencies), 90–94 (optional-dependencies)
• Issue: kyber-py is not declared as a dependency anywhere, yet kem.py imports it at module level. Any import of libp2p.security.noise.pq fails without manually installing kyber-py.
• Suggestion: Add kyber-py to either core dependencies or a dedicated optional extra (e.g. pq or pq-fast). At minimum, declare it in the test dependency group so CI and contributors can run PQ tests. Consider lazy-importing in kem.py so noise_state.py can be imported independently.

pyproject.toml — lines 20–49, 90–94

dependencies = [
    ...
    "pynacl>=1.3.0",
    # kyber-py is MISSING — required by libp2p/security/noise/pq/kem.py
    ...
]

[project.optional-dependencies]
pq-fast = [
    "liboqs-python>=0.12.0",
    "PyNaCl>=1.5.0",  # already a core dep
]

---

• File: PR metadata / process
• Line(s): N/A
• Issue: No linked GitHub issue (Fixes #XXX). Project policy requires every mergeable PR to reference an issue. Maintainer @acul71 explicitly asked to hold off on opening a tracking issue until spec discussion progresses ("Hold on on the tracking issue, let's discuss more and wait for specs").
• Suggestion: Acceptable for a draft research PR, but must be resolved before merge: open a tracking issue once noise-pq: add Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256 spec (Stage 1 Working Draft) specs#716 stabilizes, link it in the PR body, and add a newsfragment.

---

• File: tests/security/noise/pq/test_vectors_pq.py
• Line(s): 45–51, 269–271
• Issue: Cross-implementation test vectors are not vendored in the repo. Tests look for ../js-libp2p-noise/test/fixtures/pqc-test-vectors.json (sibling directory outside the repo). In a clean checkout/CI environment, 47 vector tests are silently skipped — contradicting the PR claim that they run in CI.
• Suggestion: Commit pqc-test-vectors.json under tests/fixtures/ (or similar) and update _VECTORS_PATH to a repo-relative path. This is the primary wire-compatibility proof and should not depend on a local sibling checkout.

tests/security/noise/pq/test_vectors_pq.py — lines 45–51

_VECTORS_PATH = (
    Path(__file__).parents[4].parent  # PQC-Research/
    / "js-libp2p-noise"
    / "test"
    / "fixtures"
    / "pqc-test-vectors.json"
)

---

• File: tox.ini / CI configuration
• Line(s): 22–23
• Issue: PQ tests under tests/security/noise/pq/ are never executed in CI. The core tox env runs only tests/core. PQ test collection failures therefore do not block CI core jobs, masking the missing kyber-py dependency.
• Suggestion: Add a security or pq tox env (or extend an existing env) that runs tests/security/noise/pq/ with kyber-py installed. Wire this into CI.

---

Major

• File: libp2p/security/noise/pq/__init__.py
• Line(s): 17–18
• Issue: Eager imports of TransportPQ, make_fast_kem, etc. cause the entire PQ package (including kyber-py) to load when any submodule is imported — even noise_state, which has no KEM dependency. This breaks test_noise_state.py collection without kyber-py.
• Suggestion: Use lazy imports in __init__.py or remove re-exports that force the import chain at package init time.

libp2p/security/noise/pq/__init__.py — lines 17–18

from .transport_pq import PROTOCOL_ID, TransportPQ
from .kem_backends import KeypairPool, LibOQSXWingKem, make_fast_kem

---

• File: libp2p/security/noise/pq/patterns_pq.py
• Line(s): 1–22 (module docstring)
• Issue: Module docstring uses indented pseudo-code blocks that break Sphinx/ReST parsing, causing docs CI failure.
• Suggestion: Rewrite the module docstring using proper ReST literal blocks or remove the structured layout from the module-level docstring (keep it in comments or a separate doc page).

---

• File: libp2p/security/noise/pq/kem_backends.py
• Line(s): 213–262
• Issue: KeypairPool is implemented and exported but not wired into PatternXXhfs or TransportPQ. Handshakes still call self.kem.keygen() synchronously on the critical path (line 199 of patterns_pq.py), paying full keygen latency (~8–20 ms with kyber-py) per connection.
• Suggestion: Either integrate KeypairPool into PatternXXhfs (injectable via constructor) or document clearly that it is experimental/optional infrastructure not yet used by the transport.

---

• File: libp2p/security/noise/pq/noise_state.py
• Line(s): 107–116
• Issue: mix_key_and_hash() is implemented (for HFS 3-output HKDF per Noise HFS spec) but never called anywhere. patterns_pq.py uses mix_key() for KEM shared secrets instead.
• Suggestion: Verify against the Noise HFS spec and js-libp2p-noise reference implementation whether ekem1 should use MixKey or MixKeyAndHash. If mix_key() is correct (vectors suggest it is), remove or document the unused method to avoid confusion.

---

• File: libp2p/security/noise/pq/kem.py, kem_backends.py
• Line(s): kem.py 76–93, kem_backends.py 61–69
• Issue: _xwing_combine() is duplicated in two modules with identical logic.
• Suggestion: Extract to a shared internal module (e.g. _xwing.py) to prevent drift.

---

• File: newsfragments/
• Line(s): N/A
• Issue: No newsfragment file present. Mandatory for merge per project policy.
• Suggestion: Expected for draft; add <ISSUE>.feature.rst once a tracking issue exists.

---

Minor

• File: libp2p/security/noise/pq/kem_backends.py
• Line(s): 289–291
• Issue: pyrefly reports run_in_executor(None, self._kem.keygen) type mismatch (bound method vs expected callable signature).
• Suggestion: Wrap in a lambda or use functools.partial for cleaner typing: loop.run_in_executor(None, self._kem.keygen) → loop.run_in_executor(None, lambda: self._kem.keygen()).

---

• File: tests/security/noise/pq/test_patterns_pq.py, test_transport_pq.py
• Line(s): multiple
• Issue: Test helper classes _MemoryConn, _WriteCapture are not typed as IRawConnection; pyrefly reports ~24 bad-argument-type errors.
• Suggestion: Make test doubles explicitly implement IRawConnection or cast at call sites.

---

• File: pyproject.toml
• Line(s): 91–94
• Issue: pq-fast extra lists PyNaCl>=1.5.0 which is already a core dependency.
• Suggestion: Remove redundant PyNaCl from pq-fast; keep only liboqs-python.

---

• File: libp2p/security/noise/pq/patterns_pq.py
• Line(s): 161–173
• Issue: handshake_outbound accepts remote_peer: ID | None to skip peer ID verification — useful for interop but weakens authentication if used in production.
• Suggestion: Document prominently that remote_peer=None disables peer ID binding; consider restricting to test-only via a separate method or flag.

---

5. Security Review

Overall: The cryptographic design appears sound for a research implementation. No critical vulnerabilities identified in the handshake logic itself.

Area	Assessment
KEM hybrid (X-Wing)	Correct ML-KEM-768 + X25519 combiner with domain separation label; length checks on all key material
Identity authentication	Reuses established libp2p Ed25519 signature verification — same as classical Noise
Transcript binding	Protocol name hashed into initial state; ChaCha20-Poly1305 with handshake hash as AD
Input validation	Key/ciphertext length checks raise ValueError; signature failures raise InvalidSignature
Randomness	Uses nacl.utils.random for ephemeral keys — appropriate

Items to monitor:

• Risk: Pure-Python kyber-py backend may not have the same side-channel resistance as liboqs for production deployments

• Impact: Medium (timing/leakage in hostile environments)

• Mitigation: Document that pq-fast / liboqs is recommended for production; pure-Python path is for development/interop only

• Risk: remote_peer=None in handshake_outbound skips peer ID verification

• Impact: Low (test/interop only if used carefully)

• Mitigation: Do not expose in production API without explicit opt-in and documentation

• Risk: liboqs auto-install probe can block ~5 seconds on first call when C library absent (mitigated by _LIBOQS_AVAILABLE cache)

• Impact: Low

• Mitigation: Already cached; consider documenting the first-call delay

Security Impact: Low (for draft/research scope)

---

6. Documentation and Examples

Item	Status
Module docstrings	Present and detailed in most files; patterns_pq.py module docstring breaks Sphinx
Public API docs (__init__.py)	Good usage example for TransportPQ and optional fast backend
Sphinx integration	Auto-generated libp2p.security.noise.pq page exists but not in toctree; docstring errors prevent clean build
User-facing tutorial/guide	Missing — no docs page explaining PQC Noise setup, optional deps, or interop workflow
README update	Missing — no mention of /noise-pq/1.0.0 or pip install libp2p[pq-fast]

Recommendation: For eventual merge, add a short guide under docs/ covering protocol ID, dependency installation, BasicHost integration, and interop testing. Fix ReST docstring formatting in patterns_pq.py.

---

7. Newsfragment Requirement

⚠️ BLOCKER for merge (acceptable for current draft status)

• Severity: CRITICAL / BLOCKER (when targeting merge)
• Issue: No newsfragment file and no linked GitHub issue
• Impact: PR cannot be approved per project policy without:
  1. A linked tracking issue
  2. A valid newsfragment <ISSUE>.feature.rst
• Current state: Maintainer @acul71 requested waiting on the tracking issue until specs mature. Author acknowledges draft status.
• Action Required (before merge): Open issue → link in PR → add newsfragment

---

8. Tests and Validation

Linting (make lint)

Check	Result
yaml, toml, whitespace, pyupgrade	✅ Passed
ruff + ruff format	✅ Passed
mdformat	✅ Passed
mypy	✅ Passed
pyrefly	❌ Failed (exit code 1)
Cross-platform path audit	✅ Passed

pyrefly errors (33 shown):

• 3× [import-error] — kyber_py.ml_kem not found (2 files), oqs not found (1 file)
• 1× [bad-argument-type] — kem_backends.py:290 run_in_executor bound method
• 3× [implicitly-defined-attribute] — test_kem.py setup_method attributes
• 26× [bad-argument-type] — test mock connections not typed as IRawConnection

Overall lint: ❌ Failed due to pyrefly

Type Checking (make typecheck)

• mypy: ✅ Passed
• pyrefly: ❌ Failed (same 33 errors as above)

Test Execution (make test)

Metric	Value
Passed	2795
Skipped	16
Errors	5 (all PQ test collection — ModuleNotFoundError: kyber_py)
Failed	0
Duration	~106 s

PQ tests (with kyber-py manually installed):

Metric	Value
Passed	45
Skipped	47 (vector tests — fixture file not present)
Failed	0
Duration	~0.5 s

Key observation: The 47 skipped vector tests are the PR's primary interop proof. They do not run in default CI or clean checkouts.

Documentation Build (make linux-docs)

❌ Failed (warnings treated as errors)

Errors:

• patterns_pq.py module docstring: Unexpected indentation (lines 10–11)
• patterns_pq.py handshake_outbound docstring: Unexpected indentation (line 6)
• libp2p.security.noise.pq.rst: document isn't included in any toctree

CI Status (GitHub Actions)

Job	Result
tox core (3.10–3.13)	✅ Pass
tox interop, demos, utils, wheel	✅ Pass
tox lint (3.10–3.13)	❌ Fail
tox docs (3.10)	❌ Fail
windows core (3.11)	❌ Fail
Read the Docs	✅ Pass

---

9. Recommendations for Improvement

1. Declare kyber-py in pyproject.toml (test group at minimum; consider pq optional extra for runtime).
2. Vendor test vectors into the repo and fix _VECTORS_PATH — this is the highest-value test asset.
3. Add PQ tests to CI via a dedicated tox env with kyber-py installed.
4. Fix Sphinx docstrings in patterns_pq.py to unblock docs build.
5. Lazy-load heavy imports in pq/__init__.py to decouple noise_state from KEM dependencies.
6. Open tracking issue when spec discussion allows (per @acul71 guidance); link in PR and add newsfragment.
7. Wire or document KeypairPool — either integrate into handshake or mark as experimental.
8. Deduplicate _xwing_combine into a shared module.
9. Add pyrefly stubs for kyber_py and oqs (or # pyrefly: ignore with justification) to unblock lint CI.
10. Add user documentation for /noise-pq/1.0.0 setup before marking PR ready for review.

---

10. Questions for the Author

1. Was the decision to use mix_key() rather than mix_key_and_hash() for the ekem1 token verified against the latest Noise HFS spec draft and js-libp2p-noise#665? The unused mix_key_and_hash() method suggests possible spec ambiguity.
2. Can the cross-implementation vector file be committed to this repo (or fetched as a test fixture submodule) so CI can run the 47 vector assertions?
3. Is KeypairPool intended to be integrated into PatternXXhfs before merge, or kept as optional infrastructure for callers to wire manually?
4. Should kyber-py be a hard dependency, or only pulled in via an optional pq extra to keep the default install lean?
5. What is the plan for protocol ID alignment if noise-pq: add Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256 spec (Stage 1 Working Draft) specs#716 settles on a different string than /noise-pq/1.0.0?
6. Has Go interop been attempted or planned, as mentioned in the PR body's merge criteria?

---

11. Overall Assessment

Criterion	Rating
Quality Rating	Good (for research/exploratory draft)
Security Impact	Low
Merge Readiness	Not ready (by author intent + project blockers)
Confidence	High

Summary: This is high-quality exploratory work that makes a concrete, reviewable contribution to the libp2p PQC handshake discussion. The modular design, pluggable KEM backends, layered tests, and live JS interop are strong foundations. The author correctly labels it as draft/WIP, and maintainer guidance to wait for spec stabilization is appropriate.

For merge readiness, the blockers are primarily process and infrastructure rather than cryptographic correctness: missing issue/newsfragment (expected for now), undeclared kyber-py dependency, non-vendored test vectors silently skipped in CI, PQ tests excluded from tox, and docs/lint CI failures. None of these diminish the research value of the PR, but all must be addressed before it can graduate from draft to mergeable.

Recommended next step: Continue using this PR as a feedback vehicle. Address dependency/CI/vector vendoring when the author is ready to move toward merge, coordinated with libp2p/specs#716 and a tracking issue.

[paschal533]

Thanks for the thorough review @acul71 this is exactly the kind of structured feedback that turns a draft into something mergeable. I've gone through every recommendation and question. Here's a full accounting of what's been addressed.

---

Response to Section 9: Recommendations

1. Declare kyber-py in pyproject.toml ✅
kyber-py>=0.4.0 is now declared in both the pq optional extra (runtime) and the testing group. The pq-fast extra adds liboqs-python on top.

2. Vendor test vectors ✅
tests/security/noise/pq/vectors/xxhfs_test_vectors.json is committed directly in the repo. _VECTORS_PATH in test_vectors_pq.py resolves relative to the test file so it works in any checkout.

3. Add PQ tests to CI ✅
tox.ini now has a pq environment ([testenv:pq]) that installs kyber-py and runs only the PQ test suite. .github/workflows/tox.yml invokes it on every push/PR. The previously-skipped 47 vector tests now run and pass in CI.

4. Fix Sphinx docstrings ✅
The patterns_pq.py module-level docstring and the handshake_outbound Args: / Returns: / Raises: sections were rewritten as proper RST (no Args: prose sections that Sphinx interprets as block quotes). docs/libp2p.security.noise.pq.rst is included in the libp2p.security.noise toctree. make linux-docs (Sphinx dummy build) now exits clean with 0 warnings across all 105 source files.

5. Lazy-load in pq/__init__.py ✅
PEP 562 __getattr__ is used so importing libp2p.security.noise.pq does not pull in kyber_py or oqs until a KEM class is actually accessed. Importing the package in an environment without either optional dep installed is now safe.

6. Open tracking issue ⏳ Pending spec stabilisation (per @acul71's guidance, acknowledged).

7. Wire or document KeypairPool ✅ (documented as optional)
KeypairPool is left as caller-wired optional infrastructure rather than embedded inside PatternXXhfs. The rationale: embedding it would force every user to deal with asyncio / trio event loop lifecycle, but not all callers need pre-warming (e.g. one-shot scripts). The module docstring in kem_backends.py now documents the usage pattern and the expected speedup.

8. Deduplicate _xwing_combine ✅
The combining function lives in libp2p/security/noise/pq/_xwing.py. Both XWingKem (kyber-py) and LibOQSXWingKem import _xwing_combine from there, no duplication.

9. Add pyrefly stubs / suppress with justification ✅

• kyber_py and oqs are third-party packages with no distributed type stubs. # type: ignore[import-error] is added at the relevant import sites with an inline note explaining the absence.
• The run_in_executor bound-method mismatch uses # type: ignore[arg-type] (trying lambda: self._kem.keygen() still fails. pyrefly rejects the lambda's inferred type too, so suppression is the right call here rather than a forced workaround that would change runtime behaviour).
• The test doubles (_MemoryConn, _WriteCapture) now inherit from IRawConnection, which eliminates all 26 bad-argument-type errors structurally and prevents future interface drift.
• Result: 0 pyrefly errors.

10. Add user documentation ✅
docs/libp2p.security.noise.pq.rst is now in the toctree and documents: protocol ID, dependency installation (pip install libp2p[pq] / [pq-fast]), BasicHost integration snippet, and backend selection.

---

Response to Section 10: Questions

Q1. mix_key() vs mix_key_and_hash() for the ekem1 token verified against spec?

Yes, verified. Noise spec §5.2 specifies that MixKeyAndHash (3-output HKDF: ck, temp_h, temp_k) is used exclusively for psk tokens, because the extra temp_h output folds the PSK into the handshake transcript hash. KEM tokens in the HFS extension like ekem1 use MixKey (2-output HKDF: ck, k), identical to how DH tokens are processed. This matches the behaviour in js-libp2p-noise#665. The mix_key_and_hash method remains in NoiseSymmetricState for full Noise API completeness (it would be needed for a XXhfs+psk2 variant), but it is not called by the XXhfs token sequence. Both the docstring and both ss.mix_key(ss_kem) call sites in patterns_pq.py now have inline comments explaining this to prevent future confusion.

Q2. Can the cross-implementation vector file be committed?

Done see recommendation 2 above. The vectors are committed as tests/security/noise/pq/vectors/xxhfs_test_vectors.json and run in CI.

Q3. Is KeypairPool intended to be integrated before merge?

No. it stays caller-wired. The handshake is correct and complete without it; KeypairPool is a performance optimisation for applications that open many connections and want to eliminate keygen latency from the hot path. Embedding it inside PatternXXhfs would add async event-loop coupling to a class that is currently synchronous-constructible, which is an unnecessary constraint. The kem_backends.py docstring documents the intended usage.

Q4. Should kyber-py be a hard dependency or only via an optional extra?

Optional extra, but required for the test suite. The install footprint of kyber-py is small (~50 KB, pure Python, no build step), but it is a specialised dep that production libp2p users will not generally need unless they are explicitly using the PQ handshake. The current split pq optional extra for runtime, testing group for CI keeps the default install lean while ensuring the test suite always has what it needs.

Q5. Protocol ID alignment with libp2p/specs#716?

/noise-pq/1.0.0 is a working string for the draft. If libp2p/specs#716 lands on a different identifier, it is a one-line change in transport_pq.py (PROTOCOL_ID) and the full string in patterns_pq.py (PROTOCOL_NAME). I am watching that thread and will update in sync with the spec.

Q6. Go interop planned?

Not yet attempted programmatically. The cross-language static test vectors (same vectors that now run in CI) cover byte-level correctness for the handshake transcript, key schedule, and cipher state, which is the meaningful interop claim. Dynamic Go interop would require a matching go-libp2p PR implementing the same pattern, which does not exist yet. That is listed as a future merge criterion in the PR description.

---

Additional: live runtime integration test

Beyond unit tests, I ran a live in-process node test: two new_host() instances each configured with only TransportPQ as their security transport, connected over loopback TCP, completed the XXhfs handshake, and exchanged a round-trip message. The demo is committed as examples/pq_noise/pq_demo.py and can be run with python examples/pq_noise/pq_demo.py.

Output (kyber-py backend, Windows 11):

[listener] PeerID : 12D3KooWGn1jVaLf4hvuunBcx1aweKoNe9MFWzrGSnh9p8LWgDC1
[dialer]   PeerID : 12D3KooWPDKNUrWiNkXAdoTZnVr1JYZ1go2L8huhFMEo8pDHci4z
[dialer]   Connecting (XXhfs handshake starting)...
[dialer]   Connected in 7033.9 ms

  PQ Noise XXhfs (X-Wing KEM) -- live node integration
  Handshake + connect : 7033.9 ms   (incl. liboqs 5s probe on first run)
  Message sent        : b'post-quantum hello!'
  Reply received      : b'pq-ack:post-quantum hello!'

  PASS -- PQ-secured round-trip succeeded

The 7-second figure includes the liboqs-python auto-install probe that runs once per process on systems without the C library. The actual PQ crypto is the remainder. With liboqs properly installed the probe is skipped entirely.

---

Current CI status post-push: tox pq env passes (92/92 tests), Sphinx dummy build clean (0 warnings across 105 source files), ruff 0 errors, pyrefly 0 errors, mypy passes. The only open item is the tracking issue + newsfragment, which waits on spec stabilisation per @acul71's guidance.

[acul71]

AI PR Review — #1310 (v1)

PR: feat(security): Noise XXhfs post-quantum handshake for py-libp2p (research/WIP)
Author: @paschal533
Branch: feat/pqc-noise-xxhfs → main
State: Open (Draft)
Review date: 2026-06-09
Reviewer: AI-assisted review (py-libp2p PR review prompt)
Prior review: v0 (2026-06-08, posted on this PR by @acul71)

---

1. Summary of Changes

This PR adds exploratory support for a post-quantum Noise handshake under protocol ID /noise-pq/1.0.0, implementing Noise_XXhfs_25519+XWing_ChaChaPoly_SHA256. The classical /noise transport and PatternXX are untouched.

New modules (all under libp2p/security/noise/pq/):

Module	Role
_xwing.py	Shared X-Wing combiner (single source of truth for both KEM backends)
kem.py	X-Wing hybrid KEM (ML-KEM-768 + X25519) with IKem protocol
kem_backends.py	Optional liboqs C backend, make_fast_kem(), KeypairPool
noise_state.py	Standalone SymmetricState / CipherState for XXhfs
patterns_pq.py	PatternXXhfs three-message handshake state machine
transport_pq.py	TransportPQ implementing ISecureTransport

Supporting additions:

• 92 tests under tests/security/noise/pq/ (KEM, state, patterns, transport, cross-implementation vectors)
• Vendored vectors at tests/fixtures/pqc-test-vectors.json
• scripts/interop_dial.py — live TCP dialer for Python↔JS interop
• examples/pq_noise/pq_demo.py — in-process two-node integration demo
• benchmarks/bench_noise_pq.py + benchmarks/results.md
• Optional pq / pq-fast extras in pyproject.toml
• Dedicated tox pq environment wired into CI

Related context (not issues):

• Discussion #1306 — design planning thread
• ChainSafe/js-libp2p-noise#665 — JS counterpart
• libp2p/specs#716 — Stage 1 working draft spec

Breaking changes: None. Additive and opt-in via a new protocol ID.

Author intent: Explicitly marked as draft/research — "Nothing here is intended for merge right now."

Since review v0: The author addressed most infrastructure feedback from @acul71's posted review (dependencies, vectors, CI, docs, lazy imports, deduplication).

---

2. Branch Sync Status and Merge Conflicts

Branch Sync Status

• Status: ℹ️ Ahead of libp2p-https/main (no divergence)
• Details: 0 18 — branch is 0 commits behind and 18 commits ahead of main

Merge Conflict Analysis

✅ No merge conflicts detected. The PR branch merges cleanly into main.

---

3. Strengths

• Clean isolation. All PQC code lives in a new pq/ subpackage; classical Noise is unmodified.
• Sound architectural choice. Dedicated XXhfs state machine aligns with maintainer guidance in Discussion Post-Quantum Noise handshake for py-libp2p (XXhfs + X-Wing KEM) #1306 (@acul71 recommended against extending noiseprotocol).
• Responsive iteration. Author addressed the bulk of v0 review feedback within days: vendored vectors, pq tox env, lazy package imports, Sphinx fixes, _xwing.py extraction, test double typing, and a live demo.
• Pluggable KEM design. IKem with XWingKem (kyber-py) and LibOQSXWingKem (liboqs) backends; make_fast_kem() auto-selects with graceful fallback.
• Strong test structure. Layered tests from KEM primitives → symmetric state → full handshake → transport interface → 47 byte-level cross-implementation vector assertions (all 92 PQ tests pass locally and in CI pq env).
• Wire compatibility evidence. Vendored vectors now run in CI on every clean checkout; author also demonstrated live Python↔JS TCP interop.
• Identity handling matches classical Noise. Ed25519 libp2p identity signatures via existing abstractions — correct separation from the PQC KEM layer.
• Documentation improved. docs/libp2p.security.noise.pq.rst in toctree; remote_peer=None security warning in docstring; examples/pq_noise/pq_demo.py demonstrates end-to-end host wiring.

---

4. Issues Found

Critical

• File: PR metadata / process
• Line(s): N/A
• Issue: No linked GitHub issue (Fixes #XXX) and no newsfragment. Maintainer @acul71 explicitly requested waiting on a tracking issue until spec discussion progresses ("Hold on on the tracking issue, let's discuss more and wait for specs").
• Suggestion: Acceptable for the current draft/research phase per maintainer guidance. Before marking ready for review, open a tracking issue, link it in the PR body, and add <ISSUE>.feature.rst.

---

Major

• File: libp2p/security/noise/pq/transport_pq.py, patterns_pq.py
• Line(s): transport_pq.py 51; patterns_pq.py 64
• Issue: TransportPQ.get_pattern() and PatternXXhfs default to make_fast_kem(), which probes liboqs on every new pattern instance. On systems without the C library, the first probe can block ~5 seconds (mitigated by _LIBOQS_AVAILABLE cache after the first failure, but every new process pays once). The pq_demo output showed a 7 s connect time largely from this probe.
• Suggestion: Consider defaulting to XWingKem() for predictable dev ergonomics and documenting make_fast_kem() as an explicit opt-in for production. Alternatively, probe liboqs once at module import with a clear log line.

libp2p/security/noise/pq/transport_pq.py — lines 45–52

    def get_pattern(self) -> PatternXXhfs:
        """Return a fresh PatternXXhfs for a single handshake."""
        return PatternXXhfs(
            local_peer=self.local_peer,
            libp2p_privkey=self.libp2p_privkey,
            noise_static_key=self.noise_privkey,
            kem=make_fast_kem(),
        )

---

• File: tests/security/noise/pq/test_vectors_pq.py
• Line(s): 37–42
• Issue: Vector tests import private implementation details (_ML_KEM_CT_SIZE, _xwing_combine) from kem.py rather than from _xwing.py or public constants. This couples tests to internal module layout and bypasses the lazy-import boundary in XWingKem.
• Suggestion: Import _xwing_combine from _xwing.py and expose size constants as module-level public names in kem.py (or a shared constants module) for test use.

---

• File: newsfragments/
• Line(s): N/A
• Issue: No newsfragment file present. Mandatory for merge per project policy.
• Suggestion: Expected for draft; add once a tracking issue exists.

---

Minor

• File: libp2p/security/noise/pq/kem_backends.py
• Line(s): 93
• Issue: pyrefly resolves import oqs only when liboqs-python is installed (optional pq-fast extra). Environments without it may see a static [import-error] from pyrefly even though runtime fallback is correct.
• Suggestion: For contributor ergonomics on minimal installs, consider a stubs/oqs/__init__.pyi (same pattern as stubs/miniupnpc/ for issue Type checker error with miniupnpc import #1009) so lint/typecheck passes without the optional C dependency.

---

• File: libp2p/security/noise/pq/kem_backends.py
• Line(s): 278–279
• Issue: run_in_executor(None, self._kem.keygen) uses # type: ignore[arg-type] suppression. Acceptable given pyrefly's bound-method limitation.
• Suggestion: No action required unless a cleaner typing pattern emerges.

---

• File: docs/libp2p.security.noise.pq.rst
• Line(s): 1–54
• Issue: API reference page is automodule-only; no user-facing setup guide (install extras, BasicHost wiring, interop workflow) beyond what's in __init__.py docstring and the example script.
• Suggestion: Add a short narrative section to the RST page or link prominently to examples/pq_noise/pq_demo.py before merge.

---

5. Security Review

Overall: Cryptographic design appears sound for a research implementation. No new vulnerabilities identified beyond items already noted in v0.

Area	Assessment
KEM hybrid (X-Wing)	Correct ML-KEM-768 + X25519 combiner in _xwing.py; length checks on key material
Identity authentication	Reuses established libp2p Ed25519 signature verification
Transcript binding	Protocol name hashed into initial state; ChaCha20-Poly1305 with handshake hash as AD
Input validation	Key/ciphertext length checks; signature failures raise InvalidSignature
remote_peer=None	Now documented with Sphinx .. warning:: — signature verified but peer-ID binding skipped

Items to monitor:

• Risk: Pure-Python kyber-py backend may lack side-channel resistance of liboqs in hostile environments

• Impact: Medium

• Mitigation: Document pq-fast / liboqs for production; kyber-py for dev/interop

• Risk: liboqs auto-install probe on first make_fast_kem() call when C library absent

• Impact: Low (DoS on local process startup, not wire protocol)

• Mitigation: Cache is in place; consider not probing by default in transport

Security Impact: Low (for draft/research scope)

---

6. Documentation and Examples

Item	Status
Module docstrings	✅ Fixed since v0; Sphinx builds clean locally
Sphinx integration	✅ libp2p.security.noise.pq in toctree; 106 source files, 0 warnings locally
examples/pq_noise/pq_demo.py	✅ Added — demonstrates new_host + TransportPQ round-trip
scripts/interop_dial.py	✅ Present for JS interop
User-facing tutorial	⚠️ Partial — automodule docs exist; no dedicated getting-started guide
README update	❌ No mention of /noise-pq/1.0.0 or pip install libp2p[pq]

---

7. Newsfragment Requirement

⚠️ BLOCKER for merge (acceptable for current draft status per @acul71)

• Severity: CRITICAL / BLOCKER (when targeting merge)
• Issue: No newsfragment and no linked GitHub issue
• Impact: Cannot approve per project policy without issue + <ISSUE>.feature.rst
• Current state: Maintainer requested deferring the tracking issue until libp2p/specs stabilizes. Author acknowledges.
• Action Required (before merge): Open issue → link in PR → add newsfragment

---

8. Tests and Validation

Validation was run on branch feat/pqc-noise-xxhfs with dev dependencies installed (kyber-py via test group; liboqs-python for full pyrefly coverage of the optional oqs import).

Linting (make lint)

Check	Result
yaml, toml, whitespace, pyupgrade	✅ Passed
ruff + ruff format	✅ Passed
mdformat	✅ Passed
mypy	✅ Passed
pyrefly	✅ Passed (with liboqs-python installed)
Cross-platform path audit	✅ Passed

Overall lint: ✅ Passed

Type Checking (make typecheck)

• mypy: ✅ Passed
• pyrefly: ✅ Passed

Test Execution (make test)

Metric	Value
Passed	2887
Skipped	16
Failed	0
Errored	0
Duration	~116 s

PQ tests are included in the full tests/ tree when kyber-py is installed (via dev test dependency group).

PQ Test Suite (pytest tests/security/noise/pq/)

Metric	Value
Passed	92
Skipped	0
Failed	0
Duration	~0.7 s

All 47 cross-implementation vector assertions pass against vendored fixtures.

Documentation Build (make linux-docs)

✅ Passed locally — 106 source files, 0 Sphinx warnings/errors

CI Status (GitHub Actions, latest push)

Job	Result
tox pq (3.10–3.13)	✅ Pass
tox core, interop, demos, utils, wheel (3.10–3.13)	✅ Pass
tox docs (3.10)	✅ Pass
tox lint (3.10–3.13)	⚠️ May require liboqs-python or stubs/oqs/ for pyrefly on minimal installs
windows core/demos/utils/wheel	✅ Pass
Read the Docs	❌ Fail (build 33042886 — may be unrelated to PQ changes; tox docs passed)

---

9. Recommendations for Improvement

1. Open tracking issue + newsfragment when @acul71 signals spec readiness (per maintainer guidance).
2. Revisit default KEM selection — consider XWingKem() as transport default to avoid liboqs probe latency in dev/demo paths.
3. Decouple vector tests from private kem.py symbols — import from _xwing.py / public constants.
4. Add user-facing setup guide before marking PR ready — short section in docs covering pip install libp2p[pq], host wiring, and interop pointers.
5. Optional: add stubs/oqs/__init__.pyi so pyrefly passes on minimal dev installs without pq-fast.

Resolved since v0 (no further action)

• ✅ kyber-py declared in pq extra and test dependency group
• ✅ Test vectors vendored at tests/fixtures/pqc-test-vectors.json
• ✅ tox pq env in CI
• ✅ Sphinx docstring fixes
• ✅ PEP 562 lazy imports in pq/__init__.py
• ✅ _xwing_combine deduplicated to _xwing.py
• ✅ mix_key() vs mix_key_and_hash() documented for ekem1
• ✅ Test doubles implement IRawConnection
• ✅ Redundant PyNaCl removed from pq-fast
• ✅ remote_peer=None security warning added

---

10. Questions for the Author

1. Is the ~5 s liboqs probe on first TransportPQ handshake acceptable for the default path, or should XWingKem() be the default with liboqs as explicit opt-in?
2. Has Read the Docs build 33042886 been investigated? tox docs passes; the RTD failure may be environmental but should be confirmed before merge.
3. When noise-pq: add Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256 spec (Stage 1 Working Draft) specs#716 settles on a protocol ID, will you coordinate the one-line PROTOCOL_ID change with js-libp2p-noise and go implementations?

---

11. Overall Assessment

Criterion	Rating
Quality Rating	Good (improved since v0)
Security Impact	Low
Merge Readiness	Not ready (draft by author intent + process blockers)
Confidence	High

Summary: Substantial progress since review v0. The author systematically addressed maintainer feedback on dependencies, vectors, CI coverage, documentation, and code structure. Cryptographic correctness is well evidenced by 92 passing tests including byte-level JS interop vectors and live TCP interop. Lint, typecheck, tests, and docs all pass with standard dev dependencies plus the optional pq-fast extra where needed for pyrefly. Process blockers (tracking issue, newsfragment) remain appropriately deferred per @acul71's guidance until the libp2p PQC spec discussion matures.

Recommended next step: Continue using this PR as a feedback vehicle until specs and a tracking issue are ready.

[paschal533]

Hi @acul71 Thanks for the thorough v1 review addressing the open items inline.

CI is now fully green (as of commit 4a9460f):

Answers to the questions:

Q1 liboqs probe latency as default: Agreed. I'll change transport_pq.py to default to XWingKem() and document make_fast_kem() / pq-fast as an explicit opt-in for production. The 5-second probe on first call in the default path is bad ergonomics and the benchmark analysis in this thread already shows liboqs matters more on Python than JS anyway, that deserves to be a deliberate choice, not an automatic one.

Q2 RTD build 33042886: Investigated and fixed. The failure was specific to this PR's changes, not an environmental fluke.

Q3 Protocol ID coordination: Yes, the plan is to treat PROTOCOL_ID = "/noise-pq/1.0.0" as a single constant to sync across py-libp2p, js-libp2p-noise (#665), and any go implementation once libp2p/specs#716 stabilises on an identifier. The constant is isolated to one line in transport_pq.py so the change is a one-liner when specs are ready.

---

On the remaining major items: Vector test decoupling (import _xwing_combine from _xwing directly, surface size constants publicly) and the user-facing setup guide are the next two I'll address on this branch. Newsfragment and tracking issue remain deferred per your earlier guidance.

[paschal533]

Pushed the protocol rename, the id bump, library-based interop harnesses and a benchmark refresh. This is a breaking change on the wire.

Rename. Noise_XXhfs_25519+ML-KEM-768_ChaChaPoly_SHA256 becomes Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256 in noise_state.PROTOCOL_NAME and PatternXXhfs. Noise (revision 34, §8.2) allows only alphanumerics and / in algorithm names, so the hyphenated form was never valid (@royzah spotted it). The name is hashed into the handshake hash h, so this is wire-incompatible with earlier builds: message A is unchanged, and everything from the encrypted part of message B onwards differs. The rationale is written up in specs#716 §2.1.

Id. TransportPQ now uses /noise-mlkem768-hfs/0.2.0. On 14 Sept I said I'd expect a bump rather than a rename. It turned out to need both: the rename breaks compatibility, so the id moves to keep old and new builds from negotiating a handshake that can only fail on message B. (libp2p/specs#727 has the same name but still uses 0.1.0; I've raised it on #716.)

Vectors. tests/fixtures/mlkem768-xxhfs-vectors.json is regenerated under the new name, and test_vectors_pq.py now also pins handshake_hash, cs1_k and cs2_k (the fields the JS fixture carries), not only the three messages. The PQ suite in tests/security/noise/pq is 56 tests, all passing at cea85ba7. The Python and JS fixtures are still two files, not one shared file.

Interop, 48/48. scripts/interop_dial_mlkem768.py and scripts/interop_listen_mlkem768.py now drive py-libp2p's own PatternXXhfs, and a neutral runner pairs them with the TypeScript, Nim and Rust implementations. It runs every ordered listener/dialer pairing, Python against itself included, three times each, on 2026-09-17 with this branch at cea85ba7. A run passes only if both sides exit cleanly, each reports the other's actual peer id, and one encrypted greeting goes each way, which exercises both split() cipher states. Everything ran over loopback TCP on one machine, with no multistream-select. Results and logs.

Negative controls. A TypeScript build with only the old name fails against this branch in both roles: InvalidTag() when Python dials, and an invalid tag on message B when Python listens (control A, re-run with the matrix). A dialer that prints a fake peer id is caught by the identity cross-check (control B, from the earlier run 20260917T015709Z).

Correction. The June 2026 interop in the description was handshake-only. scripts/interop_all.sh counted a pair as passing when the dialer exited cleanly and printed a peer id, and no transport frames were exchanged. The Python dialer then was also a standalone re-implementation of the handshake, not PatternXXhfs. The Rust listener in those pairs was ours (royzah/rust-libp2p#1), built against a June snow that still used the hyphenated name. interop_all.sh is removed, and the run above replaces those results. Details: artifacts README.

Benchmarks. benchmarks/results.md is regenerated. The X-Wing-era numbers I mentioned on 14 Sept are gone. bench_noise_pq.py now interleaves classical and hybrid handshakes per iteration. The cross-language write-up for the 2026-09-17 session is in SUMMARY.md. For Python: 12.0x overhead. That's the median of the 5 pass-level values, each the median of 50 per-iteration ratios, with a range of 11.3–12.4x, kyber-py pure Python. Absolute latencies from that session aren't comparable with earlier sessions (see the file).

[paschal533]

Update on this branch, and the description above has been rewritten to match.

The ML-KEM-768 backend is no longer pure Python. MLKEM768NativeKem implements the same
IKem contract over cryptography.hazmat.primitives.asymmetric.mlkem, which reaches ML-KEM-768
in C through OpenSSL 3.5+, AWS-LC or BoringSSL. make_fast_kem() now returns it whenever it can
be constructed and falls back to kyber-py otherwise, logging a warning that says plainly that
kyber-py's own metadata states it is not constant time. Selection is memoised per process; it
used to be re-run for every inbound connection, which charged an ML-KEM probe to every
unauthenticated peer.

The performance claim this branch has carried is now a before and after rather than a
comparison across languages. Both backends measured as alternating paired arms of one session,
four passes of thirty iterations, classical and hybrid interleaved within each pass:

Python arm	classical Noise_XX	hybrid Noise_XXhfs	overhead	KEM share
kyber-py (pure Python)	2.25 to 2.30 ms	24.73 to 25.31 ms	10.76x to 10.87x	~91%
MLKEM768NativeKem (C-backed)	2.05 to 2.21 ms	2.99 to 3.15 ms	1.42x to 1.44x	~30%

The kyber-py arm is the point of the exercise, not the headline: it reproduces the 10.7x and
the ~91% published from a session nine days earlier, which is what makes this one measurement of
one change rather than two benchmarks on two days. Three measurement sessions have now been run on this machine: two agree at about 1.42x and an
earlier one, with a slightly faster classical baseline, put it nearer 1.7x. I report 1.42x
because two of the three agree on it. All figures are from one machine and there is no
second-hardware measurement.

Dependencies moved. cryptography>=42.0.0 is now a declared core dependency; it was
undeclared and arrived transitively through aioquic, and 42.0.0 is derived from the newest API
the core importers actually use unguarded (not_valid_before_utc / not_valid_after_utc) rather
than guessed. The native backend's cryptography>=48.0.0 lives in the pq extra, not in core,
because pyOpenSSL <= 25.3.0 caps cryptography below 47 and a hard core floor of 48 would make
those environments unresolvable. The dead pq-fast extra, which installed liboqs-python that
nothing selected, is gone.

A pre-authentication memory-safety fix. The XXhfs parser previously sliced every field
without checking a single message length. Python slices do not raise, and PyNaCl's
crypto_scalarmult does no length validation either, so a short message could drive an
out-of-bounds read in libsodium. Message A is entirely pre-authentication; message C is worse in
kind, because the static key length there is chosen after a successful AEAD decryption, so a peer
that completes A and B honestly can forge a 20-byte ciphertext whose plaintext is 4 bytes and
still reach the sink. All three messages are now length-checked before parsing, against the
fixed-token minimum and a 4096-byte payload ceiling, and rejections raise a typed
HandshakeMalformed(NoiseFailure) instead of leaking nacl.exceptions.RuntimeError or a bare
ValueError across the ISecureTransport boundary. This was found by reading the code, not by
fuzzing, and the 48-run interop matrix did not catch it, because interop tests exercise
well-formed peers.

Nothing on the wire changed, which is the other thing worth saying: same 1184-byte
encapsulation key, same 1088-byte ciphertext, byte-identical deterministic vectors, and the
cross-language matrix re-ran at 48 of 48 with the C-backed backend on the Python side, with no
fallback warning in any of the 96 logs. Tests are at 162, from 56.

CI is green at c4477a2b, and getting there found one more real bug: on Python 3.10
asyncio.TimeoutError is a distinct class from the builtin TimeoutError, unified only in
3.11, so the harness deadline helper caught the wrong one and let the raw asyncio error escape.
Only the 3.10 job failed, which is the signature of exactly that difference. The other two
failures were mine rather than the code's: a type-checker hook I had been skipping locally
flagged that _select_kem_class returned type[IKem] when IKem is a Protocol and so has no
constructor, and three docstring entries wrapped onto a deeper-indented continuation line,
which the docs build treats as an error.

Still research/WIP and still not proposed for merge.

[paschal533]

Updated the description with a 2026-09-25 section. Two things, one of which corrects what I wrote there on the 22nd.

Each binding variant now only exists where it can work. The identity variant is refused at construction on /noise, because it widens what identity_sig covers and /noise is an identifier every implementation already answers to, so such a peer would negotiate successfully and then fail verification against all of them. It lives on the hybrid suite instead, under /noise-mlkem768-hfs/0.3.0.

The interop harnesses have a flag now, so the gate I listed as open is closed: 48/48 with the mechanism off, 48/48 with the extension variant where only JS and Python are bound and Nim and Rust ran unbound, 12/12 for the identity variant, and 0/4 passing in each simulated-downgrade control, which is the pass condition there. Runs and logs are in pq-noise-artifacts/interop.

The extension result is the one I would point at: a bound peer completed with three implementations that know nothing about the mechanism. That claim was previously an argument about protobuf semantics.