Defines CSRF defenses for browser-authenticated state changes using same-site request design, server-validated tokens or headers, origin checks, safe methods, and tests for login and cross-origin edge cases.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
For cookie-authenticated browser mutations, require a server-verifiable anti-CSRF signal that an attacker cannot submit cross-site. Use SameSite cookies and Origin checks as defense in depth, not as the sole universal control.
Scope
- Protected request classes, cookie attributes, token/header pattern, origin validation, CORS, login CSRF, API exceptions, rotation, and testing.
- Browser requests where ambient credentials authenticate the user.
- Framework and proxy configuration evidence.
Outside this block
- Cross-site scripting prevention; XSS can defeat many CSRF controls and needs separate defenses.
- Adding CSRF tokens to non-browser bearer-token clients that do not use ambient credentials.
Contract
- Safe methods do not change state; every cookie-authenticated unsafe method uses the selected token/header control.
- The token is bound to a session or cryptographically tied to it, validated server-side, unpredictable, and absent from logs and URLs.
- Origin or Referer validation uses a strict configured target origin and trusted proxy reconstruction.
- Session cookies use Secure, HttpOnly where appropriate, and an explicit SameSite policy compatible with real sign-in flows.
- CORS never combines arbitrary origins with credentialed requests, and custom-header APIs allow only trusted origins.
- Login, logout, upload, GraphQL, method override, and content-type variations are included in endpoint inventory and tests.
Implementation guidance
- Prefer framework-maintained synchronizer token or signed double-submit implementation over custom cryptography.
- Reject simple cross-site content types for JSON mutation endpoints and require a custom header.
- Inventory mutations from route metadata in CI to detect unprotected additions.
- Rotate session-linked tokens on authentication changes while handling multiple tabs deliberately.
Failure handling and safeguards
- Missing or invalid signals deny the mutation with a generic response and emit rate-limited security telemetry.
- If Origin is absent, apply the explicit fallback policy; never treat an arbitrary Referer substring as a match.
- If a federated sign-in callback needs cross-site cookies, isolate and validate it with state/nonce rather than weakening every endpoint.
Verification and operations
- Measure CSRF denials by endpoint/reason, missing Origin, token mismatch, and false-positive support cases without logging tokens.
- Run cross-origin browser tests against production-like cookie, proxy, and CORS settings.
- Review route inventory whenever authentication transport changes.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.