---
name: auth-jwt-session
description: Implements authentication and session management (JWT issuing/verification, refresh rotation, sessions, cookies, OAuth2/OIDC flows, RBAC checks) when building or fixing how a backend logs users in and authorizes requests.
when_to_use: User is implementing login/logout, JWT or session handling, refresh tokens, cookie config, OAuth/OIDC, or RBAC/permission checks. This is implementation; broad vulnerability auditing of a diff is security-review.
---

## When to Use

Use when writing or fixing the code that logs a user in and authorizes their requests:

- Implementing `login` / `logout` / `whoami` endpoints or commands
- Issuing or verifying JWTs (access + refresh)
- Refresh-token rotation, revocation, denylist/allowlist
- Setting auth cookies (flags, scope, expiry)
- Wiring an OAuth2 / OIDC provider (authorization-code + PKCE)
- Adding RBAC / scope / permission checks to protected routes

NOT for: auditing an existing diff for vulnerabilities (use `security-review`), or pure DB/RLS work in a managed Postgres stack (use the `supabase` skill).

## Steps

**1. Choose the session model first — write it down before coding.**
- Stateless JWT: no server lookup per request; cannot instantly revoke. Use short access TTL (5–15 min) to bound the blast radius.
- Server session (opaque ID → store): instant revocation, server round-trip per request.
- Default for most APIs: **access JWT (short) + refresh token (long, server-tracked)**. This is the rest of these steps.

**2. Pick the signing algorithm and lock it.**
- Symmetric `HS256`: one secret signs AND verifies — only for a single-service monolith.
- Asymmetric `RS256`/`ES256`: private key signs, public key (JWKS) verifies — required when a separate service verifies tokens.
- On verify, **pass an explicit allowlist** of algorithms (e.g. `algorithms: ["RS256"]`). Never let the library read `alg` from the token header.
- Store signing keys outside the repo: env var / secret manager / KMS. Never commit a key or check a literal secret into source.

**3. Build the access token with minimal, validated claims.**
- Set `exp` (short), `iat`, `iss`, `aud`, and a stable `sub` (user id). Add a `jti` if you ever need per-token revocation.
- Put role/scope claims in only if every verifier trusts the issuer; otherwise look up authz server-side.
- On verify, check signature AND `exp`, `iss`, `aud` — a valid signature on a token for another audience is still invalid here.

**4. Implement refresh rotation + revocation.**
- Store each refresh token (hashed, never plaintext) with `user_id`, `expires_at`, `revoked_at`, and a `family_id`.
- On refresh: verify it exists, is unexpired, unrevoked → issue NEW access + NEW refresh, then mark the old one revoked (rotation).
- **Reuse detection:** if an already-revoked refresh token is presented, revoke the entire `family_id` — that means a stolen token was replayed.
- On logout: revoke the refresh token (and family). Access tokens stay valid until `exp` — that's expected with stateless JWT; keep access TTL short so this window is tiny.

**5. Set cookies correctly (if browser-facing).**
- Refresh token in cookie: `HttpOnly; Secure; SameSite=Lax` (or `Strict` if no cross-site nav), `Path=/auth/refresh` to limit where it's sent.
- Never put a token in `localStorage` if XSS is in scope — `HttpOnly` cookie is the point.
- `SameSite=None` REQUIRES `Secure` and only for genuine cross-site needs; pair with CSRF protection.

**6. OAuth2 / OIDC: authorization-code + PKCE only.**
- Generate `code_verifier` (random) → `code_challenge = S256(verifier)`. Send challenge on the authorize request; send verifier on the token exchange.
- Generate a random `state`, store it tied to the session, and verify it on callback (CSRF defense).
- For OIDC, generate a `nonce`, send it, and verify it in the returned ID token.
- Validate the ID token: signature via the provider's JWKS, plus `iss`, `aud`, `exp`, `nonce`. Never trust the `userinfo` response without validating the token first.
- Do not use the implicit flow. Do not embed a client secret in a public/CLI/SPA client — use PKCE without a secret.

**7. Authorize every protected route — deny by default.**
- Centralize: one middleware/guard that runs on all protected routes and returns 401/403 unless an explicit check passes. No route is public unless explicitly marked.
- Check the specific permission/scope for the action, not just "is logged in." A valid token is authentication, not authorization.
- Re-check ownership for resource access (does THIS user own THIS object), not only role.

## Common Errors

- **`alg: none` / algorithm confusion** — verifier trusts the token's own `alg`. An attacker sends `alg: none` (no signature) or swaps `RS256→HS256` and signs with the public key as an HMAC secret. Fix: hardcode the accepted algorithm list on verify.
- **Verifying signature but not `exp`/`aud`/`iss`** — many libraries verify the signature only unless you opt in to claim validation. An expired or wrong-audience token passes. Explicitly require these claims.
- **Refresh rotation without reuse detection** — you rotate tokens but don't revoke the family when an old one reappears, so a stolen token works until it naturally expires. Revoke the whole family on reuse.
- **Refresh tokens stored in plaintext** — a DB leak hands out live sessions. Store a hash; compare by hash.
- **Long-lived access tokens** — using a multi-hour access TTL "to avoid refresh complexity" means logout/ban does nothing for hours. Keep access short; put longevity in the refresh path.
- **Cookie missing `HttpOnly`/`Secure`** — token readable by JS (XSS) or sent over plaintext. Both flags on the auth cookie, always.
- **Same secret/key across environments** — a leaked staging key forges prod tokens. Separate keys per environment.
- **Timing-unsafe token compare** — comparing opaque tokens/secrets with `==` leaks length/content via timing. Use a constant-time compare.
- **Logging tokens** — access/refresh tokens or `Authorization` headers in request logs. Redact before logging.
- **Authn mistaken for authz** — "user is logged in" used as the only gate; any logged-in user reaches admin routes. Check the specific scope/role/ownership.

## Verify

Write tests that prove rejection, not just the happy path:

1. **Tampered token** — flip one byte of the signature → verify returns 401, never the user.
2. **`alg: none`** — craft an unsigned token with valid-looking claims → rejected.
3. **Expired token** — `exp` in the past → 401 (confirms claim validation runs, not just signature).
4. **Wrong audience/issuer** — valid signature, wrong `aud` → rejected.
5. **Refresh reuse** — use a refresh token, then present the old (rotated) one → that token AND its family are revoked; subsequent refresh fails.
6. **Logout** — after logout, the refresh token no longer mints access tokens.
7. **Authz** — a valid token lacking the required scope/role → 403 on a protected route; deny-by-default holds on an unmapped route.
8. **OAuth state/PKCE** — callback with mismatched `state` → rejected; token exchange with wrong `code_verifier` → fails.
9. **Secret scan** — `git grep` / a secrets scanner over the diff finds no literal keys or tokens; confirm logs redact `Authorization`.

Run the test suite to green before declaring done. A passing login flow with no rejection tests is not done.