diff --git a/quic/plans/2026-04-26-quic-stack-status.md b/quic/plans/2026-04-26-quic-stack-status.md index 07f878f81..4008faa4b 100644 --- a/quic/plans/2026-04-26-quic-stack-status.md +++ b/quic/plans/2026-04-26-quic-stack-status.md @@ -1,16 +1,24 @@ -# QUIC + WebTransport stack — current state (2026-04-26) +# QUIC + WebTransport stack — current state -This document is the post-implementation snapshot of `:quic`. It supersedes -the original [pure-kotlin QUIC + WebTransport plan](../../docs/plans/2026-04-22-pure-kotlin-quic-webtransport-plan.md) -which was written before any code shipped and is now historical. +Living status doc for `:quic`. First written 2026-04-26 as the post-implementation +snapshot of the [pure-kotlin QUIC + WebTransport +plan](../../docs/plans/2026-04-22-pure-kotlin-quic-webtransport-plan.md); +last full rewrite **2026-05-09** after a four-RFC compliance audit (RFC 9000, +9001, 9002, 9221 + 9114 + 9204) found the doc had drifted ~2 weeks behind +shipping work. The original plan is now historical. ## TL;DR `:quic` is a self-contained Kotlin-Multiplatform module that speaks QUIC v1 -+ HTTP/3 + WebTransport against real-world servers (aioquic + picoquic -verified; nestsClient/MoQ on top). It uses Quartz crypto primitives only — -no BouncyCastle, no JNI. ~8.5k lines of production code, ~5k lines of -tests, 39 test files, five rounds of parallel audit + fix passes. ++ HTTP/3 + WebTransport against real-world servers (aioquic + picoquic + +quic-go interop verified, including 0-RTT). Pure Kotlin: Quartz crypto +primitives + JCA AEAD only — no BouncyCastle, no JNI. ~17k lines of +production code, 81 test files, ten-plus rounds of audit + fix passes +since 2026-04-26. + +The 2026-05-09 audit confirmed the core handshake / packet protection / +loss recovery / frame routing surface is RFC-grade. Real gaps are listed +in [§ RFC compliance gaps](#rfc-compliance-gaps-2026-05-09). ## What shipped vs the original plan @@ -20,18 +28,18 @@ tests, 39 test files, five rounds of parallel audit + fix passes. | B. TLS 1.3 | 3 wk | done | RFC 8446 client state machine, X25519 ECDHE, RFC 8448 §3 vectors pass bit-for-bit | | C. Initial + Handshake packets | 2 wk | done | RFC 9001 §A.2/§A.3 vectors pass; ChaCha20 per §A.5 | | D. 1-RTT + STREAM | 1 wk | done | Stream offset reassembly, FIN, fuzzed | -| E. ACK + flow control | 1 wk | done | MAX_DATA / MAX_STREAM_DATA / MAX_STREAMS routing + writer enforcement | +| E. ACK + flow control | 1 wk | done | MAX_DATA / MAX_STREAM_DATA / MAX_STREAMS routing + writer enforcement + per-stream receive enforcement | | F. Loss recovery + congestion control | 1 wk | done (no CC) | RFC 9002 §5/§6 RTT estimator + packet/time-threshold loss detection + PTO + per-frame retransmit shipped 2026-05-05; congestion control still TBD | | G. Datagram extension | ½ wk | done | RFC 9221 frames + bounded incoming queue | -| H. Connection lifecycle | 1 wk | done | CONNECTION_CLOSE, idle timeout, draining/closing, idempotent driver close | +| H. Connection lifecycle | 1 wk | done | CONNECTION_CLOSE, draining/closing, idempotent driver close (idle-timeout enforcement still missing — see gaps) | | I. HTTP/3 | 2 wk | done | Control stream + SETTINGS + GOAWAY (with id-regression check) + duplicate-id rejection | | J. QPACK | 2 wk | done | Static-table + Huffman + integer codec (RFC 7541 §B + RFC 9204 §B.1 vectors) | | K. Extended CONNECT + WT | 1 wk | done | Stream-type prefixes, HTTP Datagram + WT_CLOSE_SESSION capsule | -| L. Interop + hardening | 2 wk | done + much more | Live interop against aioquic Docker; **5 rounds of audit + fix** beyond the plan | +| L. Interop + hardening | 2 wk | done + much more | Live interop against aioquic + picoquic + quic-go; **10+ rounds of audit + fix**, multiplexing, 0-RTT, key update, ECN, path migration | -The original plan estimated 17–19 weeks. We ran the full sequence plus five -unscheduled audit rounds. Every audit found real bugs; the suite is what -caught them on regression. +The original plan estimated 17–19 weeks. We shipped the full sequence plus +a long tail of audit-driven hardening. Every audit found real bugs; the +test suite is what catches them on regression. ## What's actually in the module @@ -43,51 +51,61 @@ quic/ │ ├── Buffer.kt ← QuicReader / QuicWriter │ ├── Varint.kt ← RFC 9000 §16 │ ├── connection/ ← QuicConnection orchestrator + Driver - │ │ ├── QuicConnection.kt (≈ 600 lines, the hub) + │ │ ├── QuicConnection.kt (≈ 2800 lines, the hub) │ │ ├── QuicConnectionDriver.kt (read/send loops + close) │ │ ├── QuicConnectionParser.kt (feedDatagram + dispatchFrames) │ │ ├── QuicConnectionWriter.kt (drainOutbound + flow-control updates) + │ │ ├── PathValidator.kt ← RFC 9000 §5.1.2 + §8.2 + §9 │ │ ├── PacketProtection.kt + builder │ │ ├── PacketNumberSpace.kt │ │ ├── ConnectionId.kt + TransportParameters.kt - │ │ └── EncryptionLevel.kt + LevelState.kt - │ ├── crypto/ ← Aead, header protection, HKDF helpers, AesEcbHeaderProtection, - │ │ ChaCha20HeaderProtection, ChaCha20Poly1305Aead, InitialSecrets, + │ │ ├── EncryptionLevel.kt + LevelState.kt + │ │ └── recovery/ ← RecoveryToken, SentPacket, + │ │ AckedPackets, QuicLossDetection + │ ├── crypto/ ← Aead, header protection, HKDF helpers, + │ │ AesEcbHeaderProtection, ChaCha20HeaderProtection, + │ │ ChaCha20Poly1305Aead, InitialSecrets, │ │ PlatformAesOneBlock, PlatformChaCha20Block (expect), │ │ bestAes128GcmAead (expect) │ ├── frame/ ← Frame.kt sealed hierarchy + FrameFuzzerTest target - │ │ includes RESET_STREAM / STOP_SENDING / NEW_TOKEN + │ │ includes RESET_STREAM / STOP_SENDING / NEW_TOKEN / + │ │ PATH_CHALLENGE / PATH_RESPONSE / NEW_CONNECTION_ID / + │ │ RETIRE_CONNECTION_ID / ACK_ECN │ ├── http3/ ← Http3FrameReader + Http3Settings + frame types - │ ├── packet/ ← LongHeaderPacket, ShortHeaderPacket, RetryPacket, peekHeader + │ ├── packet/ ← LongHeaderPacket, ShortHeaderPacket (with + │ │ reserved-bit + key-phase peek), RetryPacket, peekHeader │ ├── qpack/ ← QpackDecoder, QpackEncoder, QpackHuffman, QpackInteger, │ │ QpackStaticTable - │ ├── connection/recovery/ ← RecoveryToken + SentPacket + QuicLossDetection - │ │ (RFC 9002 §5/§6 RTT estimator + loss detection + - │ │ PTO; per-frame retransmit dispatch) │ ├── recovery/ ← AckTracker (with ack-eliciting gating) - │ ├── stream/ ← QuicStream, ReceiveBuffer (with FIN-fully-read), SendBuffer, StreamId - │ ├── tls/ ← TlsClient state machine + ClientHello/ServerHello/EE/Cert/CV/Finished - │ │ codecs, TlsKeySchedule, TlsTranscriptHash (incremental), TlsConstants, + │ ├── stream/ ← QuicStream, ReceiveBuffer (with FIN-fully-read + + │ │ per-stream receive-limit), SendBuffer, StreamId + │ ├── tls/ ← TlsClient state machine + ClientHello (incl. PSK + + │ │ early_data resumption variant) / ServerHello / EE / + │ │ Cert / CV / Finished / NewSessionTicket codecs, + │ │ TlsKeySchedule (incl. 0-RTT + resumption_master_secret), + │ │ TlsTranscriptHash (incremental), TlsConstants, │ │ PermissiveCertificateValidator, TlsRunningSha256 (expect) │ ├── transport/ ← UdpSocket (expect) │ └── webtransport/ ← QuicWebTransportFactory + QuicWebTransportSessionState + │ WtPeerStreamDemux + WtCapsule + WtDatagram + ExtendedConnect └── jvmAndroid/kotlin/com/vitorpamplona/quic/ ├── crypto/JcaAesGcmAead.kt ← cached JCA Cipher per direction with IV-reuse fallback + ├── crypto/JcaChaCha20Poly1305Aead.kt ← JCA ChaCha20-Poly1305 (with Quartz fallback) ├── crypto/PlatformCrypto.kt ← actuals - ├── tls/JdkCertificateValidator.kt ← system-trust-store chain validation + RSA-PSS / ECDSA / Ed25519 + ├── tls/JdkCertificateValidator.kt ← system-trust-store chain validation + PSL filter + + │ RSA-PSS / ECDSA / Ed25519 ├── tls/TlsRunningSha256.kt ← MessageDigest.clone()-based incremental hash └── transport/UdpSocket.kt ← DatagramChannel + suspend wrapper ``` ## Crypto surface -Quartz primitives only: +Quartz primitives + JCA only: | Primitive | Source | |---|---| | AES-128-GCM | `JcaAesGcmAead` (jvmAndroid) — cached `Cipher` per direction; `Aes128Gcm` singleton (commonMain) for non-hot paths | -| ChaCha20-Poly1305 | Quartz `ChaCha20Poly1305` (commonMain pure-Kotlin) wrapped in `ChaCha20Poly1305Aead` | +| ChaCha20-Poly1305 | `JcaChaCha20Poly1305Aead` (jvmAndroid, JCA fast path) with Quartz pure-Kotlin fallback in `ChaCha20Poly1305Aead` | | HKDF-Extract / Expand-Label | Quartz `Hkdf` + `MacInstance`; thin RFC 8446 §7.1 helper in `crypto/HkdfHelpers.kt` | | SHA-256 (one-shot) | Quartz `sha256(...)` | | SHA-256 (incremental, for transcript) | `TlsRunningSha256` (expect/actual; jvmAndroid wraps `MessageDigest.clone()`) | @@ -101,32 +119,58 @@ X.509 chain validation, hostname verification, signature verification all delegate to JDK `TrustManagerFactory` / `Signature.getInstance(...)`. `CertificateValidator` is a non-null typed parameter — tests pass an explicit `PermissiveCertificateValidator`; production passes -`JdkCertificateValidator`. +`JdkCertificateValidator` (with PSL-subset wildcard rules). ## What we deliberately don't do - **QUIC server role.** Client-only. -- **0-RTT / session resumption.** No PSK extension offered; an arriving - ServerFinished without prior Certificate is hard-failed. -- **Connection migration / preferred address / multiple paths.** `NEW_CONNECTION_ID` - and `PATH_*` frames decode (so peers don't break us) but aren't acted on. - **Path MTU discovery.** Fixed 1200-byte ceiling per RFC 9000 §14. +- **Anti-amplification limits (server side).** We're a client; the server + applies its own. - **HTTP/3 server push.** -- **QPACK dynamic-table inserts on the encoder.** We send literal-only; - decoder accepts dynamic-table indexed lines. -- **ECN / anti-amplification limits.** We're a client. -- **TLS Key-Update / NewSessionTicket.** Detected and refused (KeyUpdate - fails the connection rather than silently desynchronising). -- **Congestion control (NewReno / CUBIC / BBR).** Loss detection is in - place (RFC 9002 §5/§6) but no rate-limiting feedback loop reacts to - losses; we send as fast as the application provides bytes. Independent - follow-up. +- **QPACK dynamic-table inserts on the encoder.** We send literal + + static-indexed only; decoder accepts dynamic-table indexed lines. +- **Congestion control (NewReno / CUBIC / BBR).** Loss detection is + in place (RFC 9002 §5/§6) but no rate-limiting feedback loop reacts + to losses; we send as fast as the application provides bytes. See + [`2026-05-05-congestion-control.md`](2026-05-05-congestion-control.md) + (parked indefinitely; acceptable for moq-lite audio). + +## What's now shipped that the original "deliberately don't do" list disclaimed + +The plan's pre-rewrite version listed the following as out-of-scope. They +shipped between 2026-04-26 and 2026-05-09 and now WORK: + +- **0-RTT / session resumption.** TLS 1.3 PSK + `early_data` extension on + both ends; client caches `resumption_master_secret`, parses + `NewSessionTicket`, and replays 0-RTT data with prior-connection ALPN + + transport params. Verified against picoquic and quic-go. +- **TLS Key-Update / NewSessionTicket.** RFC 9001 §6 1-RTT key update — + client-initiated AND peer-initiated. `KEY_PHASE`-bit peek before AEAD, + in-flight gate, PN-regression check on the rotation packet, proper + HKDF roll of `application_traffic_secret_N+1`. +- **NEW_CONNECTION_ID / RETIRE_CONNECTION_ID handling, including + `retire_prior_to`** per RFC 9000 §5.1.2 + §19.15 (`PathValidator.recordPeerNewConnectionId` + with full state machine: stale-offer retire, watermark monotonicity, + pool-full bound, duplicate-with-mismatch rejection). +- **Path validation (client- and server-initiated).** RFC 9000 §8.2 + + §9 — full PATH_CHALLENGE / PATH_RESPONSE round-trip, 3*PTO timeout + per §8.2.4, abrupt migration to a new DCID on success, forced + rotation when `retire_prior_to` exceeds the active CID. +- **ECN (1-RTT only).** ECT(0) on outbound, `ACK_ECN` (0x03) frames + with truthful CE / ECT(0) / ECT(1) counters. Initial / Handshake + ACKs intentionally skip ECN counts (interop conservatism). + +The remaining pre-rewrite "don't do" items (server role, PMTU, HTTP/3 +push, QPACK encoder dynamic table, CC) are still out-of-scope. ## Verified interop - **aioquic** (Python): `quic-interop-runner`-style Docker setup; full - handshake + Extended CONNECT + h3 datagram round-trip. -- **picoquic** (C): Docker image, lightweight HTTP/3 GET. + handshake + multiplexing + Extended CONNECT + h3 datagram round-trip. +- **picoquic** (C): Docker image, h3, 0-RTT, key-update, longRTT, ECN + test cases pass. +- **quic-go** (Go): 0-RTT pass. - **In-memory pipe** (`InMemoryQuicPipe`, modeled on Cloudflare quiche's `Pipe`) drives both sides of the handshake in one JVM for fast tests without sockets. @@ -137,13 +181,19 @@ gates on the audio-rooms completion plan ## Audit summary -| Round | Focus | Findings | Status | -|---|---|---|---| -| 1 | Initial review (pre-interop) | 6 critical correctness/security bugs | all fixed | -| 2 | TLS hardening + lifecycle | hangs + TLS edge cases | all fixed | -| 3 | Performance + concurrency | cipher caching, polling, transcript O(n²) | all fixed | -| 4 | Core + TLS + perf + coverage gaps (4 parallel agents) | ~30 items including 4 CRITICAL interop blockers | all fixed; comprehensive regression tests added | -| 5 | Regression check + concurrency-specific (2 parallel agents) | 1 CRITICAL ackEliciting regression I'd just introduced + WT scope leak + others | all fixed | +| Round | Date | Focus | Findings | Status | +|---|---|---|---|---| +| 1 | 2026-04-22 | Initial review (pre-interop) | 6 critical correctness/security bugs | all fixed | +| 2 | 2026-04-23 | TLS hardening + lifecycle | hangs + TLS edge cases | all fixed | +| 3 | 2026-04-24 | Performance + concurrency | cipher caching, polling, transcript O(n²) | all fixed | +| 4 | 2026-04-25 | Core + TLS + perf + coverage gaps (4 parallel agents) | ~30 items including 4 CRITICAL interop blockers | all fixed; comprehensive regression tests added | +| 5 | 2026-04-26 | Regression check + concurrency-specific (2 parallel agents) | 1 CRITICAL ackEliciting regression I'd just introduced + WT scope leak + others | all fixed | +| 6 | 2026-05-04 | Per-frame retransmit + SendBuffer rewrite | retain-until-ACK + control-frame retx + STREAM/CRYPTO recovery | all fixed; see [`2026-05-04-control-frame-retransmit.md`](2026-05-04-control-frame-retransmit.md) | +| 7 | 2026-05-05 | Loss-detection timer + PSK rejection signal | RFC 9002 §6.1.2 timer; PSK rejection recover-in-place | all fixed | +| 8 | 2026-05-06 | Path validation pass 1 + 2 | DCID rotation, retire-prior-to monotonicity, abrupt migration | all fixed | +| 9 | 2026-05-07 | DoS hardening + reserved-bit checks + TLS bounds + SendBuffer shrink | bound peer-controlled buffers and channels | all fixed | +| 10 | 2026-05-08 | Lock-split design + close-under-load + key-update PN gate | streamsLock + lifecycleLock split | all fixed; see [`2026-05-08-lock-split-design.md`](2026-05-08-lock-split-design.md) | +| 11 | 2026-05-09 | Four-RFC compliance audit (4 parallel agents: 9000, 9001, 9002, 9221+9114+9204) | ~15 items, mostly receive-side validation gaps | catalogued in [§ RFC compliance gaps](#rfc-compliance-gaps-2026-05-09) below | Every fix carries an inline `audit-N #M` reference comment so the regression test → fix → comment chain is auditable. The whole audit corpus is in the @@ -151,35 +201,48 @@ git log (commits whose subject starts with `fix(quic):` or `perf(quic):`). ## Test inventory -Roughly grouped: +81 `*Test.kt` files. Roughly grouped: - **RFC vectors:** RFC 8448 §3 (TLS handshake), RFC 9001 §A.1–A.5 (Initial encrypt/decrypt, Retry, ChaCha20, server-side HP), RFC 9204 §B.1 (QPACK), RFC 7541 (Huffman). - **End-to-end pipe tests:** `InMemoryQuicPipeTest`, `CoalescedPacketSkipTest`, `ReceiveLimitEnforcementTest`, `PeerStreamLimitTest`, `FrameRoutingTest`, - `AckElicitingFramesTest`. + `AckElicitingFramesTest`, `MultiplexingRoundTripTest`, + `MultiplexingThroughputTest`, `MultiplexingCoalescingTest`, + `MultiStreamFinDeliveryTest`, `MultiplexingAioquicTpsTest`. - **Adversarial:** `FrameFuzzerTest`, `HostilePacketInputTest`, - `TlsSecurityPropertiesTest`, `HelloRetryRequestTest`. + `TlsSecurityPropertiesTest`, `HelloRetryRequestTest`, + `CloseDatagramRfcComplianceTest`, `CloseUnderLoadTest`. - **Crypto:** `JcaAesGcmAeadTest`, `ChaCha20Poly1305AeadTest`, `TlsTranscriptHashTest`. - **WT / HTTP/3:** `CapsuleReaderTest`, `WtPeerStreamDemuxTest`, `WtFramingTest`. - **Recovery:** `AckTrackerCoalescedTest`, `AckTrackerGatingTest`, - `RecoveryTokenTest`, `SentPacketTest`, `ReceiverFlowControlTest` (9 - cases mirrored from neqo `fc.rs`), `QuicLossDetectionTest`, - `PtoTest`, `QuicConnectionRetransmitTest`, - `SendBufferRetainUntilAckTest` (14 cases for the rewrite), - `StreamRetransmitTest`, `CryptoRetransmitTest`, - `ResetStopSendingEmitTest` (7 cases). -- **Interop:** `InteropRunner` (jvmTest, drives a real socket against a - Dockerised aioquic; opt-in, not in CI). + `AckTrackerPurgeOnAckOfAckTest`, `RecoveryTokenTest`, `SentPacketTest`, + `ReceiverFlowControlTest` (9 cases mirrored from neqo `fc.rs`), + `QuicLossDetectionTest`, `PtoTest`, `PtoCryptoRetransmitTest`, + `QuicConnectionRetransmitTest`, `RetransmitIntegrationTest`, + `SendBufferRetainUntilAckTest` (14 cases), `StreamRetransmitTest`, + `CryptoRetransmitTest`, `ResetStopSendingEmitTest` (7 cases), + `OnTokensLostTest`, `MoqLiteLossHarnessTest`. +- **Path validation / migration:** `PathValidatorTest`, + `PathValidationTest`, `ClientPathMigrationTest`. +- **Key lifecycle:** `KeyDiscardTest`, `KeyUpdatePeerInitiatedTest`. +- **Concurrency / soak:** `BatchedOpenLockContractTest`, + `StreamRetirementSoakTest`, `QuicHeapSoakTest`, + `QuicConnectionDriverLifecycleTest`. +- **Misc:** `VersionNegotiationTest`, `RetryHandlingTest`, + `PacketNumberSpaceTest`, `ConnectionIdTest`, + `FlowControlSnapshotTest`, `PendingFlowControlEmitTest`, + `PeerStreamCreditExtensionTest`, `PeerUniStreamDrainTest`. +- **Interop (jvmTest, opt-in):** `InteropRunner` drives a real socket + against a Dockerised aioquic / picoquic / quic-go. Not in CI. ## Known limitations / deferred work -These are the items future audit rounds keep flagging that we've -consciously not tackled — all confined to the steady-state path that audio -rooms don't exercise heavily: +These are items future audit rounds keep flagging that we've consciously +not tackled: 1. ~~**No STREAM retransmit on loss** (audit-4 #10).~~ **Resolved 2026-05-05** — `SendBuffer` rewritten for retain-until-ACK with three-state range @@ -188,27 +251,85 @@ rooms don't exercise heavily: and RESET_STREAM / STOP_SENDING / NEW_CONNECTION_ID retransmit. See [`2026-05-04-control-frame-retransmit.md`](2026-05-04-control-frame-retransmit.md). 2. ~~**`SendBuffer` doesn't retain bytes until ACK.**~~ Resolved with #1. -3. ~~**No Initial / Handshake key discard.**~~ **Resolved 2026-05-05** — - `LevelState.discardKeys()` nulls the AEAD protection, replaces the - per-level CRYPTO buffers and ack-tracker with empty instances, and - clears the sent-packet map. Initial keys discarded by the writer - after the first Handshake packet is built (RFC 9001 §4.9.1); - Handshake keys discarded by the parser on receipt of HANDSHAKE_DONE - (RFC 9001 §4.9.2 + §4.1.2 client-side handshake confirmation). -4. **No path validation for `NEW_CONNECTION_ID`.** We don't migrate. -5. **Stateless reset detection.** Stateless-reset packets look like - corruption to us. +3. ~~**No Initial / Handshake key discard.**~~ **Resolved 2026-05-05.** +4. ~~**No path validation for `NEW_CONNECTION_ID`.**~~ **Resolved 2026-05-06–08** — + full client-initiated DCID rotation + server-initiated path + validation per RFC 9000 §8.2 + §9. See `PathValidator.kt` and the + three test files (`PathValidatorTest`, `PathValidationTest`, + `ClientPathMigrationTest`). +5. **Stateless reset detection.** Stateless-reset tokens are now + *recorded* (per `PeerConnectionIdEntry`) but no inbound check + compares "looks-like-noise" datagrams against the token list. RFC + 9000 §10.3. 6. ~~**`AckTracker.purgeBelow` threshold semantics.**~~ **Resolved - 2026-05-05** — `RecoveryToken.Ack` now carries `(level, largestAcked)`; - the writer captures these from the AckFrame at emit time, and - `QuicConnection.onTokensAcked` purges the matching per-level inbound - tracker on ACK-of-ACK. The wrong purge in the parser is gone. + 2026-05-05.** 7. **Driver direct unit tests** require turning `UdpSocket` from `expect class` into an interface so the test side can stub. The driver is covered indirectly by every pipe-based test plus the live interop runner. 8. **No congestion control.** Loss detection is wired but nothing - throttles send rate in response. Independent ~1-2 wk project. + throttles send rate in response. Independent ~1–2 wk project. + See [`2026-05-05-congestion-control.md`](2026-05-05-congestion-control.md). + +## RFC compliance gaps (2026-05-09) + +Catalogued from a four-agent compliance audit (RFC 9000 / 9001 / 9002 / +9221+9114+9204). Each item lists the spec section, the gap, and +file:line evidence. Severity: + +- 🔴 **High** — exploitable by a hostile peer (resource exhaustion, + silent desync, RTT poisoning). +- 🟡 **Medium** — interop or correctness risk; cooperative peers + unaffected. +- 🟦 **Low / cosmetic** — diagnostic loss, doesn't break the wire. + +### Receive-side validation gaps + +| RFC § | Sev | Gap | Evidence | +|---|---|---|---| +| RFC 9000 §17.3 | 🔴 | **Inbound short-header fixed-bit (0x40) not validated.** RFC says fixed-bit MUST be 1 on receive. Form-bit (0x80) and reserved-bit (0x18) ARE checked, but 0x40 is never asserted post-HP-unmask. | `ShortHeaderPacket.kt:163-187` (form-bit checked, fixed-bit not) | +| RFC 9000 §10.1 | 🔴 | **`max_idle_timeout` not enforced.** Decoded into config and advertised, but no idle deadline tracking, no auto-close on silence. Connection lives forever if no I/O happens. | `QuicConnection.kt:1040,1054,1069`; `QuicConnectionDriver.kt` (no idle timer) | +| RFC 9000 §4.1 | 🟡 | **Connection-level inbound flow control missing.** Per-stream `receiveLimit` IS enforced (`QuicConnectionParser.kt:655`) — peer overshoot closes the connection. But the aggregate connection-level cap (matching what we advertised in `initial_max_data`) is not tracked on the receive side. | `QuicConnectionParser.kt:735-743` (only updates send-side credit on MAX_DATA) | +| RFC 9000 §3 | 🟡 | **Stream state machine implicit, not validated.** The 10-state machine (Ready / Send / Data Sent / Data Recvd / Reset Sent / Reset Recvd × directions) is encoded as flags + buffer content. STREAM frames arriving after a RESET_STREAM are silently absorbed instead of raising STREAM_STATE_ERROR. (FIN-size mismatch *is* caught — `QuicConnectionParser.kt:672-685`.) | `QuicStream.kt:35-51` (no explicit state field) | +| RFC 9000 §10.2 | 🟡 | **No DRAINING state.** Closing transitions go CONNECTED → CLOSING → CLOSED without the 3 × PTO hold the spec mandates. Late inbound packets after our own CONNECTION_CLOSE may not get a re-emitted close. | `QuicConnection.kt:301,1441-1531` (Status enum has no DRAINING) | +| RFC 9000 §10.3 | 🟡 | **Stateless reset detection missing.** Tokens are stored in `PeerConnectionIdEntry` but no inbound matcher compares fail-to-decrypt datagrams against the token list. Spoofed peer-side resets look like noise. | `PathValidator.kt:35-43`; no consumer in parser | +| RFC 9001 §6.6 | 🟡 | **AEAD invocation limit not tracked.** AES-128-GCM is bounded at 2^23 invocations (~8M packets). Past the limit, key rotation is mandatory. We don't count, don't rotate, don't close with AEAD_LIMIT_REACHED. ChaCha20 is effectively unbounded so less critical. | `Aead.kt`, `JcaAesGcmAead.kt` (no counter) | + +### Transport-parameter bounds + +| RFC § | Sev | Gap | Evidence | +|---|---|---|---| +| RFC 9000 §18.2 | 🟡 | **`max_udp_payload_size < 1200` not rejected.** Spec says minimum 1200; smaller values MUST close with TRANSPORT_PARAMETER_ERROR. | `TransportParameters.kt:165` (decode-only) | +| RFC 9000 §18.2 | 🟡 | **`ack_delay_exponent > 20` not rejected.** Spec maximum is 20. | `TransportParameters.kt:166` (decode-only) | +| RFC 9000 §18.2 | 🟡 | **`active_connection_id_limit < 2` not rejected.** Spec minimum is 2. (We already cap our own pool at the peer's value via `PathValidator.maxUnusedCids`, so the runtime risk is bounded — just no explicit error.) | `TransportParameters.kt:168`; `QuicConnection.kt:582` | +| RFC 9000 §13.2.5 | 🟦 | **`ack_delay_exponent` decode uses our config, not peer's advertised value.** Default (3) matches both ends in practice, but a peer that advertises a non-default exponent gets misinterpreted ACK delays. The shift IS overflow-safe (`QuicConnectionParser.kt:540-553`), just keyed off the wrong side's parameter. | `QuicConnectionParser.kt:547` (uses `conn.config.ackDelayExponent`) | + +### HTTP/3 + DATAGRAM gaps + +| RFC § | Sev | Gap | Evidence | +|---|---|---|---| +| RFC 9114 §7.2.4.1 | 🟡 | **HTTP/2 reserved SETTINGS ids 0x02/0x03/0x04/0x05 not rejected.** RFC says receipt MUST close with H3_SETTINGS_ERROR. We accept and store. | `Http3Settings.kt:85-121` | +| RFC 9221 §3 | 🟡 | **Outbound DATAGRAM size not gated by peer's `max_datagram_frame_size`.** Encoder will send oversize frames; spec-conformant peers will close with PROTOCOL_VIOLATION. | `Frame.kt:278-291` (no size check on send) | +| RFC 9114 §6.2.1 | 🟦 | **Closing the control stream surfaces a flag rather than auto-closing.** Spec says closing the control stream is H3_CLOSED_CRITICAL_STREAM. Caller must poll `peerH3ProtocolError` and close. | `Http3FrameReader.kt`; `WtPeerStreamDemux.kt` | + +### TLS / error reporting cosmetics + +| RFC § | Sev | Gap | Evidence | +|---|---|---|---| +| RFC 9001 §4.8 | 🟦 | **TLS alerts not mapped to CRYPTO_ERROR + alert_code.** Connection still closes (a generic `QuicCodecException` propagates) but the alert code is lost — debuggability hit, not a wire-spec violation. | `TlsClient.kt:311-317` (catches as `Throwable`) | +| RFC 9000 §22 | 🟦 | **Several error codes never emitted.** INVALID_TOKEN (no Retry token validation), CRYPTO_BUFFER_EXCEEDED (no buffer limit), KEY_UPDATE_ERROR (uses generic exception path on KeyUpdate failures, despite key update being implemented). | various | + +### Gaps the 2026-05-09 audit got WRONG + +For audit traceability — three audit findings fingered code that's +actually compliant. Listed here so future audit rounds don't repeat +them: + +| Audit claim | Reality | +|---|---| +| "Inbound flow-control enforcement missing." | Per-stream IS enforced. `QuicConnectionParser.kt:655` raises a connection close when STREAM offset+len exceeds `stream.receiveLimit`. The actual gap is *connection-level* (above). | +| "ack_delay_exponent not applied on decode." | IS applied at `QuicConnectionParser.kt:540-553`, with explicit overflow protection per audit-4. The actual gap is using *our* exponent instead of the peer's. | +| "Short-header reserved bits not validated." | ARE validated at `ShortHeaderPacket.kt:182-187` — `QuicProtocolViolationException` raised on any of the 0x18 bits set. The `0x30` mask the audit cited was a mis-read of RFC 9000 §17.3 (reserved bits are 0x18). | ## Pointers @@ -216,5 +337,7 @@ rooms don't exercise heavily: - Audio-rooms NIP draft: `docs/plans/2026-04-22-nip-audio-rooms-draft.md` - Completion plan: `nestsClient/plans/2026-04-26-audio-rooms-completion.md` - Retransmit plan + implementation log: [`2026-05-04-control-frame-retransmit.md`](2026-05-04-control-frame-retransmit.md) +- Congestion control deferral rationale: [`2026-05-05-congestion-control.md`](2026-05-05-congestion-control.md) +- Lock-split design: [`2026-05-08-lock-split-design.md`](2026-05-08-lock-split-design.md) - Live interop runner: `quic/src/jvmTest/.../interop/InteropRunner.kt` -- Audit history: `git log --grep='audit' -- quic/` +- Audit history: `git log --grep='audit\|fix(quic)\|feat(quic)' -- quic/`