From 26d7f68ce179630bbe7090744c0f0a22e752ebab Mon Sep 17 00:00:00 2001 From: Rowan Date: Sun, 26 Jul 2026 15:37:58 -0400 Subject: [PATCH] =?UTF-8?q?CLAUDE.md:=20add=20the=20HOT=20block=20?= =?UTF-8?q?=E2=80=94=20the=20four=20C=20libraries=20had=20none?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Coverage was 6/12 across the lane and the four flagship libraries were the gap, which is the worst possible place for it: these are the repos most likely to be reasoned about by someone who did not write them. DISTILLED, NOT INVENTED. Every item below was already documented somewhere in this file; the hot block is the part a stranger must read FIRST, pulled to the top with file:line where the code says so itself. Nothing here is a new claim. The block answers one question: what in this repo looks like a defect and is not? That is the failure this mechanism exists to stop -- I reported netcode.rs's `netcode-official` crate name to Glenn as a defect when it was a deliberate workaround already written down in that repo's block, which I had not read. Examples of what would otherwise get "fixed": the flat linear scans that were chosen OVER a hash map because an attacker controls the keys; release builds that deliberately carry no config validation; serialize macros that hide `return false` on purpose; debug asserts deliberately kept off the untrusted read path so a hostile peer cannot crash a debug server. Glenn, 2026-07-26, emphatic: the per-repo hot block and the per-bud queue are "the most important things while you work." Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 0bdc3c3..2f8b8c3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,40 @@ + +## HOT — read before reasoning about this repo + +WHAT: the C reference implementation of the netcode protocol (encrypted, connection-oriented +UDP with connect tokens). NOT netcode.rs / netcode.go (the ports), NOT the crates.io crate +`netcode` (unrelated, taken 2017 — ours is `netcode-official`). + +**THE PROTOCOL IS THE PRODUCT.** `STANDARD.md` is the spec every implementation follows. A +change here that alters wire behaviour breaks every port and every third-party +implementation. Spec change first, code second, ports after — never the reverse. + +DECISIONS THAT READ AS BUGS (they are not — do not "fix" them) +- **One ~9,300-line file.** A deliberate style choice trading contribution ergonomics for + trivial integration (drop in two files, no build system). +- **Flat linear scans, not hash maps**, for per-client address lookup and the encryption + mapping search. A hash WAS considered and rejected: netcode targets ~100 players, and an + attacker controls the keys (source addresses) and could drive a hash into its worst case. + Linear is the hardened choice here, not the lazy one. +- **Connect-token single-use tracking is constant-time worst-case on purpose** + (netcode.c:3701, says so in a comment). Timing must not leak whether a token was seen. +- **Per-packet socket errors are ignored deliberately.** UDP is unreliable, so a send error + is semantically identical to a dropped packet; a persistently dead socket surfaces as a + connection timeout through the state machine. +- **The running server has no state machine of its own** — only stopped/started + (`netcode_server_running`). All other state is per-client. That is not an omission. +- **Global packet sequence starts at `1ULL << 63`** (netcode.c:3940) and is re-seeded on + BOTH start and stop. Nonce-space separation: pre-connection and per-client packets share + a key, so their nonces must not collide. Seeding on create only was the AEAD nonce-reuse + bug fixed in 1.4.0. Keep every seeding site. +- **Replay protection advances the window only AFTER authentication** (netcode.c:1863, + 1907). The cheap pre-decrypt reject is an optimisation; moving the window advance before + auth would let spoofed plaintext sequence numbers poison it. + +SECURITY: netcode 1.3.5 and earlier carry the nonce-reuse issue above; see SECURITY.md for +affected versions and which channels still serve them. + + # CLAUDE.md ## What this is