This document is the operator-facing reference for eru-http's security surface. Each defense is listed with:

• Status — enforced by default, opt-in, or documented gap.
• Config knob (if any) — the HttpServerConfig / WebSocketServerConfig / TlsConfig field that controls it.
• Defended by — the hostile spec that exercises the mitigation against unpatched-adjacent traffic. These live under **/hostile/ and only run with HOSTILE=true sbt testAll.
• RFC / CVE — the standards citation or CVE class the defense addresses.

Byte-faithful path contract (default). The server does NOT percent-decode or normalize request paths; they reach handlers exactly as parsed from the wire. Handlers that dereference the path for file-system or DB lookups MUST normalize themselves (e.g. Path.of(p).normalize().startsWith(base)). Strict-mode rejects the clearly-invalid byte sequences (control chars, \0, \r) but still does not decode.

On by default in the edge preset (HttpServerConfig.edge) and opt-in otherwise via HttpServerConfig.perIpGovernanceEnabled = true. The default config keeps it off because a library cannot know whether it sits directly on untrusted traffic; an edge-exposed deployment should use HttpServerConfig.edge or enable it explicitly. When enabled:

429 responses include Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. 429 does NOT close the TCP connection — keep-alive is preserved across rate-limited requests.

PROXY-protocol + XFF resolution rules:

• PROXY v2 preamble is parsed on the raw socket before the TLS handshake for both plain and TLS connections (a PROXY-emitting LB sends the preamble first, so no LB-side TLS termination is required). With Optional mode and a non-PROXY TLS peer, the peeked ClientHello bytes are replayed into the TLS stream untouched.
• XFF is trusted only when the TCP peer falls inside a configured trusted-proxies CIDR; the leftmost untrusted value in the chain is the subject. Malformed / all-trusted chains fall back to TCP peer.

The redirect policy follows RFC 9110 Section 11.5: a protection space cannot extend outside the scope of its server, so credentials are dropped when a redirect resolves to a different origin (scheme, host, or port, with default ports normalized per RFC 6454). Same-origin redirects keep them. QUERY content is replayed on 301/302/307/308 per RFC 10008 Section 2.5 — query content follows redirects exactly like POST bodies; treat query content that must not leave an origin accordingly.

Cross-check against the nginx 2026 advisory list (the classes most likely to surface in general-purpose HTTP servers). Non-applicable entries are classes that cannot arise in this codebase: it has no HTTP/3 implementation as of 1.0.0, no mp4/SSI/slice/charset/rewrite/resolver modules, and all parsing runs on a memory-safe runtime with explicit bounds (no C-style buffers).

The security surface closed before 1.0.0: body-stream framing failures now answer 400 instead of silently truncating, the PROXY v2 preamble is parsed on the raw socket before the TLS handshake, header-read deadlines answer 408 on plain and TLS paths, Middleware.bodyLimit bounds uploads per content type, and WebSocket closeTimeout is enforced. What follows are the remaining deliberate design decisions.

1. Byte-faithful URI path contract — see "HTTP/1.1 framing" above. Strict mode (default as of 1.0.0) rejects control characters; it does NOT decode or normalize. Handlers that do filesystem / DB lookups MUST normalize themselves.

2. Per-IP governance is off in the default config, on in edge. The default config cannot know whether it faces untrusted traffic directly. Edge-exposed deployments should use HttpServerConfig.edge or enable governance explicitly; behind a trusted LB it stays optional. Dropped connections at the connection cap get a TCP close with no HTTP response — that is deliberate DoS economics for accept floods, while request-rate overruns do answer 429 with Retry-After.

3. Per-read header deadlines, not a total-header deadline. The header phase is bounded per read operation (nginx client_header_timeout semantics): a client whose inter-read gap exceeds readHeaderTimeout is cut with a 408, and each deadline fires at socket level so the channel stays open for that 408. A client that keeps sending header bytes faster than the deadline is making legitimate progress.

HOSTILE=true sbt testAll

Gated behind HOSTILE=true so it doesn't slow the default dev loop. testAll forces the run; a plain test skips suites whose cached results are fresh. All scenarios are expected to pass on HEAD; any failure is either a regression or a tightened invariant that requires spec updates.

See HOSTILE_TESTING.md for the test-writing conventions.

Open a security advisory on the repo rather than a public issue.