amethyst/docs/plans/2026-04-22-pure-kotlin-quic-webtransport-plan.md

# Pure-Kotlin QUIC + WebTransport plan

## Context

The Audio Rooms feature (NIP-53 kind 30312) is wire-incompatible with anything but
WebTransport over QUIC, because that's what the nostrnests/nests MoQ relay speaks.
Phases 3a / 3c / 3d of the rollout shipped the entire Kotlin stack from NIP-98 auth
through MoQ framing through Opus playback — every layer except the WebTransport
factory itself, which is a stub that throws `WebTransportException(NotImplemented)`.

We tried the easy path (depend on a Java QUIC library) and exhausted it:

| Library | Outcome |
|---|---|
| `tech.kwik:kwik-core`, `tech.kwik:kwik`, `tech.kwik:flupke` | Maven Central returns `Could not find` for every coord/version we tried. |
| `io.netty.incubator:netty-incubator-codec-http3` | Resolves, **but** it depends on `netty-incubator-codec-native-quic` (JNI to Cloudflare quiche) which has no Android-compatible native classifier published. Compile-time green, runtime `UnsatisfiedLinkError`. |
| Cronet | QUIC support is internal; WebTransport not exposed in any stable public API. |
| WebView JavaScript bridge | Rejected by product. |

So the path forward is a **pure-Kotlin QUIC client** with just enough WebTransport
on top to interop with nests. This plan scopes that work honestly.

## Scope

### What we build in pure Kotlin

- QUIC v1 client per RFC 9000 (no server, no version negotiation beyond v1).
- QUIC-TLS binding per RFC 9001 (CRYPTO-frame splicing, per-level keys, header
  protection).
- QUIC loss recovery + congestion control per RFC 9002 (NewReno minimum).
- QUIC datagram extension per RFC 9221.
- HTTP/3 client subset per RFC 9114 (control stream, SETTINGS, request streams).
- QPACK encoder per RFC 9204 (literal-only emit; full decoder).
- Extended CONNECT (RFC 8441 / WT-H3 draft-13) for `:protocol = webtransport`.
- WebTransport over HTTP/3 framing: stream-type prefix bytes, capsule protocol
  for `WT_SESSION_CLOSE`.
- HTTP Datagrams per RFC 9297 carrying WT datagrams.

### What we delegate

- **TLS 1.3 AEAD ciphers** → Quartz's existing `AESGCM` (common, with AAD
  support) + `ChaCha20Poly1305` (common, pure-Kotlin).
- **HKDF primitives** → Quartz's existing `Hkdf` class + its `MacInstance`
  (HMAC-SHA256). We add one thin helper — HKDF-Expand-Label from RFC 8446 §7.1
  — on top, plus a general `hkdfExpand(prk, info, length)` since Quartz only
  ships NIP-44's specialised `fastExpand`.
- **Key agreement** → Quartz's existing `X25519` (common expect/actual).
- **SHA-256 hashing** → Quartz's existing `Sha256` (common expect/actual).
- **Cert chain signature verification** → Quartz's `Ed25519` where the leaf
  uses Ed25519; JDK `Signature.getInstance("SHA256withRSA")` /
  `"SHA256withECDSA"` for the common cases (nests typically uses Let's Encrypt
  ECDSA certs).
- **X.509 parsing + chain validation** → JDK `CertificateFactory` +
  `TrustManagerFactory.getInstance(...).init(null as KeyStore?)` (Android
  system trust store).
- **AES-ECB for QUIC header protection** (one block, 5-byte sample) → JDK
  `Cipher.getInstance("AES/ECB/NoPadding")` — trivial, no dep.
- **SecureRandom** → Quartz's `RandomInstance` / `SecureRandom`.

**No BouncyCastle dependency.** The QUIC-TLS cryptographic surface is already
fully covered by Quartz's primitives — nip44Encryption/crypto (AEAD + HKDF +
ChaCha20 + Poly1305), marmot/mls/crypto (X25519 + Ed25519 + Curve25519Field),
utils/ciphers/AESGCM, utils/mac, utils/sha256, utils/SecureRandom. We write
the TLS 1.3 client state machine ourselves using those primitives.

### Explicitly out of scope

- QUIC server role.
- 0-RTT / session tickets (defer until needed).
- Connection migration / preferred address.
- Multiple concurrent paths.
- Path MTU discovery (assume 1200-byte safe ceiling).
- HTTP/3 server push.
- QPACK dynamic table on the encoder side (use literal-only headers; still decode
  dynamic table from the peer).
- ECN-based congestion signalling.
- Anti-amplification limits (we're a client; rarely matters).

## Architecture

**Module placement:** a new top-level Gradle module `:quic` sibling to
`:quartz`, `:commons`, `:nestsClient`. It's a KMP module (commonMain + an
`androidMain` + `jvmMain` pair via a shared `jvmAndroid` source set, mirroring
Quartz's pattern) so it's reusable for future non-Nests consumers
(Nostr-over-QUIC relays, desktop audio, iOS later). `:quic` takes
`api(project(":quartz"))` so the crypto primitives are available without
re-exporting. `:nestsClient` drops its `transport/` subpackage and declares
`implementation(project(":quic"))` instead.

**settings.gradle delta:**

```groovy
include ':quartz'
include ':commons'
include ':ammolite'
include ':quic'            // NEW — pure-Kotlin QUIC + HTTP/3 + WebTransport
include ':nestsClient'     // gains `implementation project(':quic')`
include ':desktopApp'
include ':cli'
```

**Package layout under `:quic`:**

```
quic/
├── build.gradle.kts           ← KMP module, api(project(":quartz"))
└── src/
    ├── commonMain/kotlin/com/vitorpamplona/quic/
    │   ├── Varint.kt             ← migrated from nestsClient/moq/Varint.kt
    │   ├── crypto/               ← HkdfExpandLabel + thin helpers
    │   ├── tls/                  ← TLS 1.3 client state machine
    │   ├── packet/               ← long/short-header codec + protection
    │   ├── frame/                ← CRYPTO, STREAM, ACK, MAX_*, CONNECTION_CLOSE…
    │   ├── stream/               ← per-stream buffers + flow control
    │   ├── recovery/             ← loss detection + PTO + NewReno
    │   ├── connection/           ← QuicConnection state machine
    │   ├── http3/                ← RFC 9114 client
    │   ├── qpack/                ← RFC 9204 encoder/decoder
    │   └── webtransport/
    │       ├── ExtendedConnect.kt
    │       ├── WtStreamType.kt   ← 0x41 (bidi) / 0x54 (uni)
    │       ├── WtCapsule.kt      ← WT_SESSION_CLOSE = 0x2843
    │       └── QuicWebTransportFactory.kt  ← implements nestsClient's WebTransportFactory
    ├── jvmAndroid/kotlin/com/vitorpamplona/quic/
    │   └── transport/
    │       └── UdpSocket.kt      ← DatagramChannel + suspend wrapper
    ├── commonTest/
    └── jvmTest/                   ← RFC 8448 / RFC 9001 vector tests
```

**Migrations when `:quic` lands:**

- `nestsClient/src/commonMain/kotlin/com/vitorpamplona/nestsclient/moq/Varint.kt`
  moves to `:quic` at `com.vitorpamplona.quic.Varint`. The existing MoQ codec
  (Phase 3c) imports the new path. Mechanical change — one commit.
- The `nestsClient/transport/` package (`WebTransportSession` +
  `FakeWebTransport` + `KwikWebTransportFactory` stub) stays in `:nestsClient`
  because that's the seam `:nestsClient`'s audio pipeline talks to. The real
  implementation `QuicWebTransportFactory` lives in `:quic` and implements
  `nestsClient.transport.WebTransportFactory` — `:nestsClient` swaps its
  constructor call from `KwikWebTransportFactory()` to
  `QuicWebTransportFactory()`, nothing else changes upstream.

**Why a dedicated module (Option A):**

- **Single responsibility.** `:quic` is a transport library; `:nestsClient`
  is an audio-room client. They have nothing conceptually in common beyond
  nests happens to run over WebTransport.
- **Reusability.** Future Nostr-over-QUIC relay work, any Kotlin project that
  wants MoQ, desktop / iOS targets all pull `:quic` directly. Potentially
  extractable to an open-source library later — pure-Kotlin QUIC barely
  exists in the JVM ecosystem, so this would be genuinely valuable beyond
  Amethyst.
- **Security boundary.** QUIC + TLS is the code you want smallest, isolated,
  and auditable without reading audio-room code around it. A dedicated module
  enforces the boundary.
- **Test isolation.** `:quic` tests run on `commonTest` / `jvmTest` — fast
  feedback. They never touch `:nestsClient`'s fakes.
- **Build graph.** `:quic` has no Android-framework dependencies (no
  `MediaCodec`, no `AudioTrack`), so it compiles clean as a pure KMP lib and
  targets iOS / desktop trivially when those arrive.
- **Charter.** Quartz is labeled "Nostr protocol only, no UI" in the project's
  CLAUDE.md. QUIC isn't Nostr; it doesn't fit Quartz's charter.

Naming note: the existing `KwikWebTransportFactory.kt` stub in `:nestsClient`
is renamed to reference the real implementation `QuicWebTransportFactory` in
`:quic`. `AudioRoomConnectionViewModel` updates its constructor call in one
line, no protocol impact.

## Phase breakdown (one developer, full-time estimates)

Each phase ends with green commonTest tests that exercise its layer in isolation,
plus an integration test against the next layer up.

### Phase A — Foundations (1 week)
- Create new `:quic` module (KMP, `api(project(":quartz"))`), register in
  `settings.gradle`, port `Varint.kt` from `:nestsClient` and update MoQ
  imports, add `:nestsClient` → `implementation(project(":quic"))` wire.
- UDP socket abstraction (`DatagramChannel`, suspend wrapper, single-receive
  loop) in `jvmAndroid`.
- Connection ID generation (cryptographically random, 8-byte source IDs).
- Packet number space tracking (Initial, Handshake, Application).
- Largest-acked / next-pn tracking per space.
- **Tests:** varint tests migrate with the file; add CID + packet-number-space
  unit tests. Full MoQ + nestsClient test suite stays green after the
  Varint migration.

### Phase B — TLS 1.3 client state machine (3 weeks)

Built entirely on Quartz primitives; no BouncyCastle.

- `HkdfExpandLabel` helper per RFC 8446 §7.1 on top of Quartz's `Hkdf.extract`
  + a new `hkdfExpand(prk, info, length)` written against `MacInstance`.
- `TlsKeySchedule` — derive Early / Handshake / Master secrets + per-direction
  traffic secrets per RFC 8446 §7.1.
- `TlsTranscriptHash` — running SHA-256 over the handshake messages using
  Quartz's `Sha256`.
- `TlsCipherSuite` — the three QUIC-mandatory suites: TLS_AES_128_GCM_SHA256
  (uses Quartz `AESGCM`), TLS_CHACHA20_POLY1305_SHA256 (uses Quartz
  `ChaCha20Poly1305`), and optionally TLS_AES_256_GCM_SHA384 (SHA-384 is the
  only primitive not yet in Quartz; skip this suite for v1).
- `TlsKeyExchange` — X25519 via Quartz `X25519.generateKeyPair()` +
  `X25519.dh()`.
- `TlsClientHello` / `TlsServerHello` / `TlsEncryptedExtensions` /
  `TlsCertificate` / `TlsCertificateVerify` / `TlsFinished` encode/decode.
- QUIC transport parameters TLS extension (codec for the opaque blob carrying
  `initial_max_data`, `max_idle_timeout`, `max_datagram_frame_size`, etc.).
- Certificate chain validation delegated to JDK `TrustManagerFactory`.
- `TlsClient` state machine: drive handshake by consuming CRYPTO-frame payload
  bytes and producing outbound CRYPTO-frame payload bytes; expose per-
  encryption-level secrets as they're derived so the QUIC layer can install
  keys.
- **Tests:** RFC 8448 §3 (Simple 1-RTT Handshake) test vectors — bit-for-bit
  reproduction of the Client's generated bytes given fixed randomness. In-
  process handshake against a minimal test TLS server built with the same
  primitives.

### Phase C — Initial + Handshake packets (2 weeks)
- Long-header packet codec (Type, Version, DCID, SCID, Token, Length, PN).
- Header protection (AES-ECB sample mask for AES suites, ChaCha20 for CC20).
- Payload protection via JCA AEAD; nonce = packet-number XOR static IV.
- Initial-secret derivation with the v1 salt (RFC 9001 §5.2).
- CRYPTO frame encode/decode with offset reassembly.
- **Tests:** decode the `Initial` packet from RFC 9001 Appendix A.2 (Cloudflare's
  test vectors). Bit-for-bit match required.

### Phase D — 1-RTT + STREAM frames (1 week)
- Short-header packet codec.
- STREAM frame encode/decode with OFF/LEN/FIN bits.
- Per-stream receive buffer with out-of-order chunk reassembly.
- Per-stream send buffer with retransmit hold (until ACKed).
- **Tests:** stream offset reassembly against a property-based fuzz that injects
  random reordering / duplication.

### Phase E — ACK + flow control (1 week)
- ACK frame encoding (ranges from packet-number tracking).
- Connection-level + stream-level send credits.
- MAX_DATA, MAX_STREAM_DATA, MAX_STREAMS handling.
- DATA_BLOCKED / STREAM_DATA_BLOCKED emission when blocked.
- **Tests:** unit tests for credit accounting + ACK range encoding edge cases.

### Phase F — Loss recovery + congestion control (1 week)
- PTO timer per RFC 9002 §6.
- RACK-based loss detection (packet-threshold + time-threshold).
- NewReno congestion controller (slow start, congestion avoidance, recovery).
- Pacing not strictly required for v1; optional time-spaced send.
- **Tests:** simulate packet loss at controlled rates; assert retransmissions
  arrive within PTO + cwnd doesn't oscillate pathologically.

### Phase G — Datagram extension (2 days)
- DATAGRAM frame (frame types 0x30 / 0x31).
- Negotiate `max_datagram_frame_size` transport parameter.
- **Tests:** datagram round-trip against in-process test server.

### Phase H — Connection lifecycle (1 week)
- Transport parameters codec (~30 parameters; only ~10 we send).
- CONNECTION_CLOSE handling (transport vs. application-level).
- Idle timeout (default 30 s, both sides MIN).
- Draining + closing states per RFC 9000 §10.2.
- **Tests:** assert clean close round-trip; assert idle timeout fires.

**End of Phase H = working QUIC client.** ~9 weeks elapsed.

### Phase I — HTTP/3 (2 weeks)
- Unidirectional control stream (peer-direction opens with stream-type 0x00).
- SETTINGS frame (we MUST emit `SETTINGS_ENABLE_CONNECT_PROTOCOL = 1`,
  `SETTINGS_ENABLE_WEBTRANSPORT = 1`, `SETTINGS_H3_DATAGRAM = 1`).
- HEADERS frame (carrying QPACK output).
- DATA frame.
- GOAWAY handling.
- **Tests:** SETTINGS round-trip; HEADERS+DATA request/response.

### Phase J — QPACK (2 weeks)
- Static table (RFC 9204 Appendix A).
- Encoder: literal-with-name-reference + literal-without-name-reference only.
  No dynamic table inserts on our side. Simplifies massively; nests will accept
  literals.
- Decoder: full dynamic table support so we can read what nests sends.
- Huffman codec (RFC 9204 Appendix B).
- Encoder + decoder streams (the two QPACK uni streams).
- **Tests:** decode known-good QPACK headers from the IETF interop corpus.

### Phase K — Extended CONNECT + WebTransport (1 week)
- HEADERS request with `:method=CONNECT`, `:protocol=webtransport`,
  `:scheme=https`, `:authority=...`, `:path=...`.
- Response handling (2xx → session open, 4xx/5xx → ConnectRejected).
- Stream-type prefix bytes (0x41 client-bidi, 0x54 client-uni).
- Capsule protocol for graceful close (capsule type 0x2843 = WT_CLOSE_SESSION).
- HTTP Datagram (RFC 9297) wrapping WT datagrams with quarter-stream-id prefix.
- Wire into existing `WebTransportSession` interface.
- **Tests:** unit tests for capsule + datagram framing; integration test using
  the in-process H3 server from Phase J.

### Phase L — Interop + hardening (2 weeks)
- Run against `nests-rs` locally. Fix every protocol mismatch.
- Run against `nostrnests.com` once local works.
- Fuzz testing: malformed packet acceptance, off-by-one frame lengths, etc.
- Performance pass: confirm < 10 ms median round-trip on local testing.

**End of Phase L = audible audio against real nests.** ~16 weeks elapsed.

## Validation strategy

1. **Unit tests per phase.** Already established pattern in nestsClient.
2. **In-process integration**, Phase B onward: spin up a BC-based QUIC server
   in the same JVM and let client + server drive each other. No real network.
3. **`quic-interop-runner` corpus** (Phase L): the IETF QUIC WG publishes
   reference test vectors for client behavior across every implementation. We
   can replay their packet captures and assert correct decoding.
4. **Local nests-rs** (Phase L): run nests' Rust reference server in Docker;
   point our client at it. Verifies real Extended CONNECT + MoQ on top.
5. **Production `nostrnests.com`** (Phase L): final confidence step.

## Risks + stop conditions

| Risk | Mitigation | Stop condition |
|---|---|---|
| Quartz's `Hkdf` only ships the NIP-44-specialised `fastExpand`, not a general-purpose expand | Write generic `hkdfExpand(prk, info, length)` in Phase B on top of `MacInstance`; upstream the helper back to Quartz `utils/` | Trivial — add one file |
| Quartz's `X25519` doesn't accept arbitrary-length secrets or has subtle incompatibilities with TLS 1.3's derivation | Verify in Phase B day-1 with a micro-test: `X25519.dh(fixed_priv, fixed_pub)` against RFC 7748 test vector | If mismatched, pin a specific Quartz version or fork the primitive |
| Header protection edge cases mis-encode 4-byte packet numbers | RFC 9001 has explicit test vectors | None — must work |
| QPACK dynamic table from nests is more aggressive than literal-only | Decoder supports full dynamic table; only encoder is literal-only | If nests rejects literal-only encoded headers, add minimal encoder dynamic table (~+1 week) |
| Loss recovery oscillates badly under real RTT variance | NewReno is conservative enough | If empirically bad, swap to BBRv1 implementation reference (~+2 weeks) |
| Server certs use RSA + SHA-256 / ECDSA P-256 / Ed25519 — we need all three sig verifiers | JDK `Signature.getInstance("SHA256withRSA")` + `Signature.getInstance("SHA256withECDSA")` cover RSA + ECDSA; Quartz `Ed25519` covers Ed25519 | None — all three are cheap |
| WebTransport draft mismatch with nests | Pin to whatever draft nests serves; advertise both legacy + current setting IDs | Hard fail back to documenting the version skew |

**Hard abandonment trigger:** if at end of Phase D (~6 weeks in) we cannot pass
the RFC 9001 Appendix A test vectors bit-for-bit, the implementation has a deep
bug we can't shake without dedicated cryptographic review. At that point the
honest call is to wait for an Android-compatible Java QUIC library to ship
elsewhere.

## Timeline summary

| Phase | Weeks | Cumulative |
|---|---|---|
| A. Foundations | 1 | 1 |
| B. TLS 1.3 client on Quartz primitives | 3 | 4 |
| C. Initial + Handshake packets | 2 | 6 |
| D. 1-RTT + STREAM | 1 | 7 |
| E. ACK + flow control | 1 | 8 |
| F. Loss + congestion | 1 | 9 |
| G. Datagrams | ½ | 9.5 |
| H. Connection lifecycle | 1 | 10.5 |
| I. HTTP/3 | 2 | 12.5 |
| J. QPACK | 2 | 14.5 |
| K. Extended CONNECT + WT | 1 | 15.5 |
| L. Interop + hardening | 2 | 17.5 |

**17-19 weeks of full-time work for one developer**, or 5-6 months at a
normal review-and-iteration cadence. TLS 1.3 is +1 week vs. the original
BC-adapter estimate because we write the state machine ourselves, but the
total is within the same band and we've eliminated the external-library
integration risk entirely. Add a security review of the QUIC + TLS + new
HKDF-Expand helper before shipping to users — minimum 2 weeks calendar
time, possibly external.

## Dependencies to add

**None.** Every cryptographic primitive lives in Quartz already:

| Primitive | Quartz location |
|---|---|
| AES-128-GCM with AAD | `utils/ciphers/AESGCM.kt` (commonMain expect, jvmAndroid actual via JCA) |
| ChaCha20-Poly1305 | `nip44Encryption/crypto/ChaCha20Poly1305.kt` (commonMain, pure Kotlin) |
| HKDF-Extract + MAC | `nip44Encryption/crypto/Hkdf.kt` + `utils/mac/MacInstance.kt` |
| SHA-256 | `utils/sha256/Sha256.kt` |
| X25519 ECDH | `marmot/mls/crypto/X25519.kt` (commonMain expect) |
| Ed25519 signatures | `marmot/mls/crypto/Ed25519.kt` |
| SecureRandom | `utils/SecureRandom.kt` + `utils/RandomInstance.kt` |

Nothing goes into `gradle/libs.versions.toml`. AES-ECB for header protection
is one-block and uses JDK `javax.crypto.Cipher` directly (no provider swap).

One small helper lives in the new `quic/crypto/` package:
`HkdfExpandLabel` (RFC 8446 §7.1) built on `MacInstance`. If it's clean, we
upstream it to Quartz's `Hkdf` as a general-purpose `expand(prk, info,
length)`.

## What ships first

Phases A+B+C in a single PR demonstrating TLS over QUIC handshake completion
against an in-process test server, bit-matching RFC 9001 vectors. That's the
proof-of-concept gate. If it works, the rest is execution. If it doesn't, we
abandon and revisit.