Double-Submit Cookie CSRF Protection for Stateless Quantum-Safe Security Platforms with Webhook and API Key Exemptions

Stateless security platforms face a unique CSRF protection challenge: they must defend browser-based dashboard sessions against cross-site request forgery while simultaneously accepting legitimate cross-origin requests from Stripe webhooks, SAML identity provider callbacks, and API key-authenticated SDK clients. We present a double-submit cookie CSRF middleware for QCrypton that generates cryptographically random 256-bit tokens via Node.js built-in crypto, sets them as cookies with configurable security attributes (httpOnly=false for JavaScript access, secure in production, SameSite=strict), and validates them on state-changing requests (POST, PUT, DELETE, PATCH) via header (X-CSRF-Token) or body (_csrf) submission. The middleware implements three exemption classes: (1) path-based exemptions for webhook endpoints (/billing/webhook) and SAML callbacks (/auth/saml/callback) that receive server-to-server POSTs, (2) authentication-based exemption for Bearer token requests that are immune to CSRF by design, and (3) method-based exemption for safe HTTP methods (GET, HEAD, OPTIONS). The implementation requires zero external dependencies (61 LOC) and adds less than 0.01ms latency per request. We analyze the security properties of each exemption class and demonstrate that the middleware correctly protects browser sessions while preserving the platform's multi-interface architecture.

⸻

Key Contributions

1. Double-submit cookie CSRF pattern with 256-bit cryptographic tokens (zero dependencies)
2. Three-class exemption model: path-based (webhooks, SAML), auth-based (Bearer tokens), method-based (safe methods)
3. Dual token submission channels (X-CSRF-Token header + _csrf body field)
4. Security analysis of exemption safety for each exemption class
5. Sub-0.01ms per-request overhead with 24-hour token rotation

⸻

Technical Highlights

• Implementation Size: 61 lines of code, zero external dependencies
• Token Generation: crypto.randomBytes(32) — 256-bit entropy, 64-character hex string
• Cookie Settings: qcrypton_csrf cookie — httpOnly=false (JS must read), secure in production, SameSite=strict, path=/, maxAge=24h
• Validation: Compares cookie token against X-CSRF-Token header OR _csrf body field; 403 on mismatch or missing token
• Protected Methods: POST, PUT, DELETE, PATCH (state-changing requests only)
• Exempt Methods: GET, HEAD, OPTIONS — safe methods that set the cookie if not present
• Path Exemptions: /billing/webhook (Stripe server-to-server), /auth/saml/callback (IdP cross-origin POST)
• Auth Exemption: Requests with Authorization: Bearer header — immune to CSRF by design (browsers don't auto-attach Bearer tokens)
• Exemption Safety:
• Webhook paths: authenticated via Stripe webhook signature verification
• SAML callback: authenticated via XML digital signature
• Bearer token: explicit header inclusion proves code-level possession of API key
• Defense-in-Depth: SameSite=strict prevents cookie attachment on cross-origin requests; double-submit prevents token forgery — two independent layers
• Attack Resistance: Cross-origin form POST (token mismatch → blocked), XHR from attacker origin (SameSite → blocked), subdomain cookie injection (token comparison → blocked), brute force (2^256 space → infeasible)
• Comparison: csurf (deprecated, 200+ LOC, 4 deps, manual exemptions), csrf-csrf (300+ LOC, 2 deps) vs. QCrypton (61 LOC, 0 deps, built-in exemptions)

• ⁃ Performance: < 0.01ms per request for both token set (GET) and token validation (POST)