Interop L0: the captured session

bench capture: a UDP relay between a real client and server logs every
datagram both directions - wire bytes as a network sees them, no internal
seams. Alongside: the session key (public API, the root SPEC derives every
packet key from), and ground truth - 20 messages up (sizes 1..1500 B, so
single- and multi-fragment are both on the wire), 20 echoed back, and a clean
close. 214 datagrams in interop/vectors/session-1.

Handshake datagrams are marked parse-only: their decryption needs ephemeral
keys no passive observer holds. Everything after is decryptable from the
session key - if SPEC.md documents the derivation well enough, which is
exactly what rung L1 tests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: 3x3xX3N0N

bench/src/main/kotlin/tessera/bench/InteropCapture.kt

@@ -0,0 +1,103 @@
+package tessera.bench
+
+import tessera.core.Handshake
+import tessera.transport.ConnConfig
+import tessera.transport.TesseraClient
+import tessera.transport.TesseraServer
+import java.io.File
+import java.net.DatagramPacket
+import java.net.DatagramSocket
+import java.net.InetSocketAddress
+import java.util.Locale
+import java.util.concurrent.ConcurrentLinkedQueue
+
+/**
+ * INTEROP L0 (docs/INTEROP.md): capture a complete session for the clean-room decoder.
+ *
+ * A UDP relay sits between a real client and a real server and logs every datagram in both directions —
+ * wire bytes exactly as a network would see them, no internal seams. Alongside, the run writes the one secret
+ * the decoder is entitled to (`TesseraConnection.sessionKey` — public API, the root from which SPEC derives
+ * every packet key) and the ground truth (the application messages each side sent).
+ *
+ * What the clean-room implementer gets: `datagrams.jsonl`, `meta.json`, `ground-truth.json`, and SPEC.md.
+ * What they must produce: the messages, byte-exact, from the datagrams — which requires varints, headers,
+ * header-protection removal, key derivation from the session key, AEAD open, frame parsing and reassembly to
+ * all be implementable from the document. Handshake datagrams (flagged F_INITIAL) are parse-only: their
+ * decryption needs ephemeral keys no passive observer has, and the capture marks them so.
+ *
+ * The workload is deliberately small and varied: 20 messages client->server (sizes 1..1500 B, so single- and
+ * multi-fragment paths are both on the wire), 20 echoes back, then a clean close (the CLOSE frame and linger
+ * behaviour are part of the capture).
+ *
+ * usage: bench capture [--out interop/vectors/session-1]
+ */
+fun captureMain(args: Array<String>) {
+    fun opt(k: String, d: String) = args.indexOf("--$k").let { if (it >= 0) args[it + 1] else d }
+    val outDir = File(opt("out", "interop/vectors/session-1")).apply { mkdirs() }
+
+    val keys = Handshake.generate()
+    val cfg = ConnConfig(pingIntervalMs = 0, idleTimeoutMs = 60_000)
+    val log = ConcurrentLinkedQueue<String>()
+    val t0 = System.nanoTime()
+    fun hex(b: ByteArray, len: Int) = buildString(len * 2) { for (i in 0 until len) append("%02x".format(b[i])) }
+
+    TesseraServer(InetSocketAddress("127.0.0.1", 0), keys, ByteArray(32) { it.toByte() }, cfg).use { server ->
+        // The relay: client talks to relayPort, relay forwards to the server, learns the client's address from
+        // the first datagram, and logs everything with direction and arrival order.
+        val relay = DatagramSocket(0, java.net.InetAddress.getLoopbackAddress())
+        val serverAddr = server.localAddress
+        var clientAddr: InetSocketAddress? = null
+        val relayThread = Thread {
+            val buf = ByteArray(65535)
+            try {
+                while (true) {
+                    val p = DatagramPacket(buf, buf.size)
+                    relay.receive(p)
+                    val from = p.socketAddress as InetSocketAddress
+                    val dir: String
+                    val to: InetSocketAddress
+                    if (from.port == serverAddr.port) { dir = "s2c"; to = clientAddr ?: continue }
+                    else { if (clientAddr == null) clientAddr = from; dir = "c2s"; to = serverAddr }
+                    log.add(String.format(Locale.ROOT, "{\"seq\":%d,\"tUs\":%d,\"dir\":\"%s\",\"len\":%d,\"hex\":\"%s\"}",
+                        log.size, (System.nanoTime() - t0) / 1000, dir, p.length, hex(buf, p.length)))
+                    relay.send(DatagramPacket(buf, p.length, to))
+                }
+            } catch (e: Exception) { /* relay closed */ }
+        }.apply { isDaemon = true; start() }
+
+        TesseraClient(cfg = cfg).use { client ->
+            val conn = client.connect(
+                InetSocketAddress("127.0.0.1", relay.localPort), keys.x25519Pub, keys.kemPub,
+                "interop-l0".toByteArray(), timeoutMs = 10_000)
+            val sconn = server.accept(5_000) ?: error("no accept")
+            val zeroRtt = sconn.receive(2_000) ?: error("no 0-rtt payload")
+
+            // deterministic, size-varied payloads; every byte position is predictable from (index, position)
+            fun payload(i: Int, size: Int) = ByteArray(size) { p -> ((i * 31 + p) and 0xFF).toByte() }
+            val sizes = listOf(1, 8, 64, 200, 500, 1200, 1201, 1350, 1500, 32, 1024, 900, 700, 300, 150, 77, 1499, 2, 128, 1300)
+            val c2s = ArrayList<ByteArray>(); val s2c = ArrayList<ByteArray>()
+            for ((i, sz) in sizes.withIndex()) {
+                val m = payload(i, sz); c2s.add(m); conn.send(m)
+                val got = sconn.receive(5_000) ?: error("server did not get msg $i")
+                check(got.contentEquals(m)) { "relay corrupted msg $i" }
+                val echo = payload(100 + i, sz); s2c.add(echo); sconn.send(echo)
+                check(conn.receive(5_000)?.contentEquals(echo) == true) { "echo $i not received" }
+            }
+            val sessionKey = conn.sessionKey.copyOf()
+            conn.close(); sconn.close()
+            Thread.sleep(500)   // let close linger / CLOSE frames traverse the relay
+            relay.close()
+
+            File(outDir, "datagrams.jsonl").writeText(log.joinToString("\n") + "\n")
+            File(outDir, "meta.json").writeText(String.format(Locale.ROOT,
+                "{\n  \"sessionKeyHex\": \"%s\",\n  \"clientIsInitiator\": true,\n  \"tagLen\": %d,\n" +
+                "  \"note\": \"datagrams with the top flag bit set (F_INITIAL) are handshake packets: parse-only, their decryption needs ephemeral keys a passive observer does not have. Everything else is decryptable from sessionKey per SPEC.\"\n}\n",
+                hex(sessionKey, sessionKey.size), cfg.tagLen))
+            fun arr(l: List<ByteArray>) = l.joinToString(",\n    ", "[\n    ", "\n  ]") { "\"" + hex(it, it.size) + "\"" }
+            File(outDir, "ground-truth.json").writeText(
+                "{\n  \"zeroRttPayloadHex\": \"" + hex(zeroRtt, zeroRtt.size) + "\",\n" +
+                "  \"clientToServer\": " + arr(c2s) + ",\n  \"serverToClient\": " + arr(s2c) + "\n}\n")
+            println("captured ${log.size} datagrams -> $outDir (sessionKey ${sessionKey.size} B, ${c2s.size}+${s2c.size} messages)")
+        }
+    }
+}

bench/src/main/kotlin/tessera/bench/Main.kt

@@ -135,6 +135,7 @@ fun main(args: Array<String>) {
             "idle" -> { idleMain(args.drop(1).toTypedArray()); return }
             "amp" -> { ampMain(args.drop(1).toTypedArray()); return }
             "vs" -> { vsMain(args.drop(1).toTypedArray()); return }
+            "capture" -> { captureMain(args.drop(1).toTypedArray()); return }
             "vsbulk" -> { vsBulkMain(args.drop(1).toTypedArray()); return }
             "connect" -> { connectBench(netem = netem); return }
             "coldstart" -> { coldStartMain(args.drop(1).toTypedArray()); return }

docs/THREAT-MODEL.md

@@ -0,0 +1,119 @@
+# Threat model
+
+Phase 0 of `docs/AUDIT-PLAN.md`. One page, adversary first. Tessera is a single-implementation research
+prototype, wire format v0, unaudited; nothing below has been independently reviewed. Claims about mechanisms
+are made against the code in `core/src/main/kotlin/tessera/core/`, not the prose docs; where the two disagree,
+the code is cited and the disagreement noted.
+
+## 1. Assets protected
+
+- **Payload confidentiality**, including against a recorder who stores traffic today and decrypts with a
+  quantum computer later. The handshake secret is hybrid X25519 + ML-KEM-768; breaking confidentiality of a
+  recorded session requires breaking both.
+- **Payload and header integrity.** Every post-handshake packet is ChaCha20-Poly1305 AEAD with the header as
+  AAD; an on-path modification fails authentication and the packet is dropped.
+- **Connection identity.** Packets are bound to a connection by keys, not by address; only a holder of the
+  connection's keys (or of the server's stateless-reset secret) can terminate or speak on a connection.
+- **Bounded reflection.** A spoofed source cannot use the server as a >3x amplifier, and cannot (beyond fixed
+  rate budgets) use it as a CPU oracle for ML-KEM decapsulations (`AddressValidation.kt`).
+
+**Not protected:**
+
+- **Traffic analysis.** Packet sizes, timing, rates, and direction are visible. No padding beyond the minimum
+  needed for the header-protection sample; no cover traffic.
+- **Connection linkability at the network layer.** The 4-byte short connection id rides in the clear on every
+  short packet (deliberately, per `PacketCrypto.kt`: header protection masks only the packet number and two
+  flag bits; the pathId bits and connId stay readable for load balancers). An observer can trivially track a
+  connection across its lifetime, and across a client rebind if the connId is kept.
+- **Peer anonymity.** IP addresses are not hidden; that is not this layer's job.
+- **Full forward secrecy of the first flight.** The session key is DH(client-ephemeral, server-static) plus
+  KEM against the server-static ML-KEM key (`Handshake.kt`). There is no server ephemeral in the exchange —
+  the code is "Noise-IK-shaped", not full IK with an `ee` token as SPEC's shorthand might suggest — so an
+  adversary who later obtains **both** server static private keys and recorded the traffic recovers the
+  session key. Key rotation (`secret_{n+1} = HKDF(secret_n)`) chains forward from that same secret and does
+  not repair this. Resumed sessions inherit the same bound via the ticket (below).
+
+## 2. Adversaries
+
+**Passive recorder (incl. harvest-now-decrypt-later).** Records everything, forever. Stopped by the hybrid
+key exchange: recovering plaintext requires the X25519 shared secret *and* the ML-KEM-768 shared secret
+(`Handshake.kt` concatenates both into HKDF). A future quantum attacker breaks X25519 but not ML-KEM; a
+classical attacker with a lattice break gets the KEM but not X25519. Caveat: a recorder who later steals the
+server's static keys wins (see forward-secrecy note above); a recorder who later steals a ticket key reads
+that ticket's resumed 0-RTT flights.
+
+**On-path active attacker.** Can drop, delay, reorder, modify, inject. Modification and injection fail the
+AEAD (per-attempt forgery 2^-128 at tag 16, 2^-64 at tag 8). Flipping the key-phase bit to provoke a spurious
+rotation is specifically handled: `KeyPhaseState.open` follows an update only after a packet authenticates
+under the pre-derived next-generation keys. Dropping and delaying are availability attacks and are not
+prevented — an on-path attacker can always kill a connection.
+
+**Off-path spoofer.** Sends packets with forged sources. Cannot forge data packets (no keys), cannot forge a
+stateless reset (the token is delivered inside the encrypted handshake reply and is an HMAC under a
+server-held secret, `StatelessReset.kt`), cannot amplify (3x bound before path validation, `PathValidation`;
+a Retry packet at 31 B against a >=1.2 KB initial is a deamplifier), and cannot burn KEM CPU past the fixed
+per-source and global token buckets — under pressure an unvalidated source gets a Retry token it never
+receives at a spoofed address (`AddressValidation.kt`). Known residue, documented in SPEC "Address
+validation": the Retry itself is unauthenticated, so an off-path guesser can inject one; the client accepts
+at most one per connect, from the addressed server only, and its retransmit train continues — cost is one
+extra initial, not a failed connect.
+
+**Malicious peer.** Holds valid keys; the crypto does not constrain it. It can lie in every frame: ACK
+inflation, credit/grant manipulation, ECN lies, bogus PMTUD, junk frames. Defences are parsers hardened by
+fuzzing (findings recorded in-code, e.g. the empty-packet check in `PacketCrypto.checkShort`), bounded
+decoder state, and rate/credit sanity limits — but a peer-driven resource-exhaustion review is exactly what
+an audit is for. Assume a malicious peer can waste this endpoint's memory and CPU up to the audited bounds
+and no confidentiality beyond its own connection.
+
+**Restarted / keyless server.** A server that crashed and lost all connection state can still emit a valid
+stateless reset: the reset secret derives from the operator-provided ticket key, which survives restarts, and
+the token is HMAC(secret, shortConnId) where the connId is readable on the client's retransmits
+(`StatelessReset.kt`). Reset emission is itself bounded (min-size packet requirement plus a 2000/s global
+bucket, SPEC "stateless reset") so the mechanism is not a reflector. The failure mode without it — client
+retransmits into a black hole until the 10 s idle timeout — is availability, not secrecy.
+
+## 3. Out of scope
+
+- **Key distribution.** Noise IK premise: the client already holds the server's static X25519 and ML-KEM
+  public keys, obtained out of band (pinning, TOFU, delegated credential). There is no PKI, no certificates,
+  no in-band identity. A client that accepts the wrong static key has lost before the first packet.
+- **DoS beyond the stated bounds.** The 3x amplification bound, the KEM admission budgets, and the reset/Retry
+  rate caps are the whole DoS story. Volumetric flooding of the link, state exhaustion by a peer with valid
+  keys past audited limits, and everything an on-path attacker can do by dropping are out of scope.
+- **Side channels beyond constant-time primitives.** Tag and token comparisons are constant-time
+  (`Arrays.constantTimeAreEqual`, the local `eq` in `AddressValidation.kt`); the crypto is BouncyCastle's.
+  Cache-timing of the JVM, the Rust SIMD datapath, and ML-KEM implementation side channels are not analyzed.
+- **Traffic analysis** of sizes, timing, and connection linkage (Section 1).
+
+## 4. Known accepted weaknesses
+
+- **`tagLen = 8` truncated-tag mode.** Negotiated in `ConnParams` (`Params.kt`): forgery ~2^-64 per attempt,
+  documented in-code as acceptable for media/game state, **not for transactions**. Truncation happens on the
+  wire only; the keystream and confidentiality argument are unchanged (SPEC v0.9). The truncated-tag open
+  path recomputes the full Poly1305 tag and compares a prefix in constant time (`PacketCrypto.openTruncated`).
+- **±10 s 0-RTT replay window with a seen-set.** `ZeroRtt.Server` and `Resumption.Server` reject timestamps
+  outside ±10 s and any fingerprint already seen inside the window. The fingerprint is 8 bytes (first 8 of
+  the random ePub; ticket-nonce xor client-nonce for resumption) — collision, not forgery, resistance; the
+  seen-set is pruned only above 100k entries. Within-window replay from a clock-skewed pair, and the fact
+  that 0-RTT data must be idempotent at the application layer regardless, are accepted and documented in the
+  code. A resumed connection additionally binds ts+nonce into the session key so a replayed ticket under a
+  fresh nonce yields a distinct key (`Resumption.sessionKey`).
+- **Single implementation, no interop evidence.** The v0 wire format has never been parsed by an independent
+  decoder (AUDIT-PLAN Phase 2 / TODO item 7). Every compatibility claim is self-referential.
+- **No audit.** No external cryptographic or implementation review has occurred. The handshake deviates from
+  proven Noise IK (hybrid KEM injection, no server ephemeral, 0-RTT layer) and those deltas are undocumented
+  formally — that is Phase 1.
+
+## 5. Mechanism inventory
+
+| Mechanism | Where | Notes |
+|---|---|---|
+| Hybrid handshake: X25519 + ML-KEM-768 into HKDF-SHA256 | `core/Handshake.kt` | Client ephemeral only; server static keys pinned out of band |
+| Packet AEAD (ChaCha20-Poly1305), header protection, truncated-tag open | `core/PacketCrypto.kt` (`PacketKeys`, `PacketProtection`) | RFC 9001 §5.4-shape HP; flags mask 0x63 leaves connId/pathId in clear by design |
+| Key update via phase bit; one retained previous generation; follow only after next-key auth | `core/PacketCrypto.kt` (`KeyPhaseState`) | HP key fixed at generation 0 for the connection's lifetime |
+| Automatic rotation policy: 2^20 packets or 1 GiB sealed per tx generation | SPEC v0.9; trigger in `transport` `transmit`, machinery `KeyPhaseState` | Policy, not a derived AEAD limit; counters freeze while an update is pending |
+| 0-RTT replay defence: ±10 s window + seen-set | `core/ZeroRtt.kt`, `core/Resumption.kt` | App-layer idempotence still required |
+| Stateless resumption tickets (server-encrypted, 7-day lifetime) | `core/Resumption.kt` | Ticket-key compromise reads resumed 0-RTT flights |
+| Stateless reset tokens: HMAC(derived secret, connId), constant-time match | `core/StatelessReset.kt` | Token delivered inside encrypted handshake reply; survives restart via ticket key |
+| Amplification bound (3x before path validation) + path challenge | `core/PathValidation.kt` | Bounds reflected bytes, not CPU |
+| KEM admission control: per-source/global buckets, pressure-triggered Retry tokens | `core/AddressValidation.kt` | Bounds CPU; fixed 8192-slot keyed table, no growth |