fix(router): harden CSRF — constant-time compare + mandatory EncryptionKey

[jcsvwinston]

Summary

Closes the two CSRF security gaps from the 2026-05-14 post-sprint audit §7. Designed in ADR-006. Lands on top of v0.7.0.

pkg/router is a stable surface — the change is additive on the API and deliberate on behaviour (see BREAKING below).

Security fixes

• Constant-time token comparison. The old submitted != token short-circuited on the first mismatched byte — a timing side-channel that leaks how many leading bytes of the CSRF token an attacker guessed correctly. Now crypto/subtle.ConstantTimeCompare.
• EncryptionKey is no longer derived from the cookie name. CSRFOptions.defaults() filled an empty EncryptionKey with sha256(CookieName) — a globally-predictable AES key (the cookie name is public, defaults to "_csrf"). Every deployment that enabled EnableXSRFCookie without an explicit key had a forgeable XSRF-TOKEN cookie. The weak-key derivation is removed; the key is now mandatory and validated.
• encryptToken/decryptToken no longer slice the key with key[:32] (panicked at request time on a short key, silently truncated a long one) — the key goes straight to aes.NewCipher, which validates length.
• Fixed a latent bug where a too-short ciphertext decrypted to "" with a nil error.
• generateCSRFToken panics on a crypto/rand failure rather than issuing a half-filled token.
• The X-XSRF-TOKEN header is only read when EnableXSRFCookie is true.

API (additive — contract baseline updated)

• router.NewCSRFMiddleware(CSRFOptions) (func(http.Handler) http.Handler, error) — error-returning constructor; returns router.ErrCSRFEncryptionKey on a misconfiguration.
• router.ErrCSRFEncryptionKey — sentinel error.
• CSRFMiddleware keeps its exact signature and becomes the regexp.MustCompile-style wrapper: it panics at construction (never on the request path) when EnableXSRFCookie is set without a 32-byte key.

⚠️ BREAKING (pre-v1.0, stable surface)

An app calling CSRFMiddleware with EnableXSRFCookie: true and no (or a non-32-byte) EncryptionKey previously started successfully with a weak/truncated key; it now panics at startup. Migration: set EncryptionKey to exactly 32 bytes, sourced from the environment or a secret manager — see docs/guides/CSRF_GUIDE.md. Apps with EnableXSRFCookie: false (the default) are unaffected. Documented in CHANGELOG.md under Changed; per contract-guardian, no DEP- entry is needed (no symbol removed or renamed).

Iteration review loop

architect-reviewer PASS (1 WARN), code-reviewer NITS, security-auditor PASS (2 LOW), contract-guardian PASS — no blockers. In-scope review fixes applied in the same PR: removed the dead OriginOnly status-code branch, guarded the X-XSRF-TOKEN header read, corrected an inaccurate godoc comment, added tamper-rejection tests. Deferred follow-ups (CSRF middleware logger, EncryptionKey []byte type, Secure cookie default) recorded in CURRENT_ITERATION.md.

Test plan

• pkg/router/csrf_hardening_test.go — key validation (missing/short/long/valid), CSRFMiddleware panic path, defaults() no longer derives a key, constant-time accept/reject (same-length and different-length wrong tokens), XSRF-cookie round-trip, tampered X-XSRF-TOKEN rejection (bit-flip / garbage / truncated — must reject, must not panic), X-XSRF-TOKEN ignored when EnableXSRFCookie is false, encryptToken/decryptToken defensive behaviour.
• Existing TestCSRFMiddleware_* in router_test.go — still pass.
• go test ./... — clean.
• go test ./contracts/ — freeze green; NewCSRFMiddleware + ErrCSRFEncryptionKey added to the baseline, correctly sorted.
• go vet ./pkg/router/ — clean.

🤖 Generated with Claude Code