🔐 Authentication

{
  "success": false,
  "errorCode": "RATE_LIMITED",
  "message": "Too many requests. Please wait and try again."
}
// Response headers:
// X-RateLimit-Limit: 10
// X-RateLimit-Remaining: 0
// Retry-After: 900

// ─── Step 1: Fetch the CSRF token ────────────────────────────────────────────
// credentials: "include" is MANDATORY — without it the browser will not store
// the csrf_token cookie that the server sets in the response.

const res = await fetch("https://api.example.workers.dev/api/auth/csrf-token", {
  method: "GET",
  credentials: "include",   // ← stores the csrf_token cookie from Set-Cookie header
});
const { data } = await res.json();
const csrfToken = data.csrfToken; // store in memory — NOT localStorage

// What happens at this point:
//   Server sets:   Set-Cookie: csrf_token=a3f9c2...; SameSite=None; Secure
//   Browser stores: csrf_token cookie under api.example.workers.dev domain
//   Your code holds: csrfToken variable = "a3f9c2..."

// ─── Step 2: Call any mutating route (login, register, etc.) ─────────────────
// credentials: "include" is MANDATORY again — without it the browser will NOT
// send the csrf_token cookie back to the server on this cross-origin request.

const loginRes = await fetch("https://api.example.workers.dev/api/auth/login", {
  method: "POST",
  credentials: "include",       // ← sends the csrf_token cookie automatically
  headers: {
    "Content-Type": "application/json",
    "X-CSRF-Token": csrfToken,  // ← you send the token value in the header
  },
  body: JSON.stringify({ usernameOrEmail: "...", password: "..." }),
});

// What the server checks:
//   cookie  csrf_token   = "a3f9c2..."   (sent by browser automatically)
//   header  X-CSRF-Token = "a3f9c2..."   (sent by your code above)
//   match → ✅ request passes

// For axios use withCredentials instead of credentials: "include"

// Step 1 — get token
const { data } = await axios.get("/api/auth/csrf-token", {
  withCredentials: true,   // ← stores csrf_token cookie
});
const csrfToken = data.data.csrfToken;

// Step 2 — login
await axios.post("/api/auth/login", { usernameOrEmail: "...", password: "..." }, {
  withCredentials: true,       // ← sends csrf_token cookie
  headers: { "X-CSRF-Token": csrfToken },
});

// Cookie was never stored (missing credentials: "include" on csrf-token fetch)
{ "errorCode": "CSRF_DETECTED", "message": "CSRF token missing. Call GET /api/auth/csrf-token first." }

// Cookie stored but not sent (missing credentials: "include" on login fetch)
{ "errorCode": "CSRF_DETECTED", "message": "CSRF token missing. Call GET /api/auth/csrf-token first." }

// Cookie sent but X-CSRF-Token header missing or wrong value
{ "errorCode": "CSRF_DETECTED", "message": "CSRF token invalid. Token in header does not match cookie." }

// The browser stores cookies per domain — under the domain that SET them.
// The csrf_token cookie is set by the backend, so it lives on the backend domain.
// This is correct. The browser will send it back to that backend domain automatically.

Frontend origin:  killaseason-7yl.pages.dev
Backend origin:   ai-tools-backend.ericfulio39.workers.dev

GET /api/auth/csrf-token
  └─ Response: Set-Cookie: csrf_token=ee47...; Domain=ai-tools-backend.ericfulio39.workers.dev
                                                SameSite=None; Secure; HttpOnly=false
  └─ Browser stores csrf_token under: ai-tools-backend.ericfulio39.workers.dev  ← correct
  └─ NOT stored under killaseason domain                                          ← also correct

POST /api/auth/login  (from killaseason frontend → to backend)
  └─ Browser sees: request is going TO ai-tools-backend.ericfulio39.workers.dev
  └─ Browser finds: csrf_token cookie belongs to that domain
  └─ SameSite=None: cookie is allowed on cross-site requests
  └─ credentials: "include": tells browser to actually attach it
  └─ Result: Cookie: csrf_token=ee47...  is sent ✅

// SameSite controls when the browser attaches a cookie to outgoing requests.

SameSite=Strict  → cookie sent ONLY when request comes from the same site as cookie domain
                   killaseason → backend = cross-site → cookie BLOCKED ❌

SameSite=Lax     → cookie sent on same-site + top-level navigation GET requests
                   POST cross-origin = cookie BLOCKED ❌

SameSite=None    → cookie sent on ALL requests including cross-site, requires Secure=true
                   killaseason → backend = cross-site → cookie SENT ✅

// auth cookies (access_token, refresh_token) use SameSite=Lax because they are
// used by the dashboard on the same .workers.dev domain as the backend.
// csrf_token uses SameSite=None because the frontend (pages.dev) is cross-site.

// Set on: POST /login, POST /verify-email, POST /refresh, GET /google/callback, POST /register/complete
// Cleared on: POST /logout

access_token   httpOnly=true  Secure=true  SameSite=Lax  MaxAge=15min
refresh_token  httpOnly=true  Secure=true  SameSite=Lax  MaxAge=30days

// httpOnly=true → JS cannot read these. Browser sends them automatically.
// SameSite=Lax  → works for dashboard (same .workers.dev domain as backend).
//                 Does NOT work for killaseason (different domain).
//                 For killaseason: access_token and refresh_token are also
//                 returned in the response body so the frontend can store and
//                 send them via Authorization header instead of cookie.

// csrf_token cookie:
csrf_token     httpOnly=false  Secure=true  SameSite=None  MaxAge=1hr
// httpOnly=false → JS must be able to read it (that's what makes Double Submit work).