Auth (Sessions, JWT, OAuth)

Pathrule4 Rules • 1 Memory • 1 Skill

A backend auth pattern covering the decisions agents get wrong: when to use server sessions versus JWTs, how to store tokens safely in httpOnly cookies, and how to wire OAuth/OIDC with PKCE. It encodes 2026 OWASP guidance on Argon2id password hashing, refresh token rotation, and CSRF defense so generated auth code is secure on the first pass.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

auth-sessions-jwt-oauth-review

src/

auth/

Never store auth tokens in localStorage

Default to server sessions; use JWT only when statelessness is required

Hash passwords with Argon2id, never fast hashes

OAuth/OIDC: PKCE, token rotation, and replay detection

middleware/

Protect cookie-based auth from CSRF

Rules

Never store auth tokens in localStorage/src/authhighstrictSession and refresh tokens must live in httpOnly cookies; never in web storage or non-httpOnly cookies.

1	Any token that authenticates a request must be set as an httpOnly cookie so JavaScript cannot read it and XSS cannot exfiltrate it.
2
3	- Set the session or refresh cookie with `httpOnly`, `secure`, `sameSite: 'lax'` (or `strict` for high-value actions), and the `__Host-` name prefix.
4	- Never write access tokens, refresh tokens, or session IDs to `localStorage`, `sessionStorage`, or non-httpOnly cookies.
5	- Keep access tokens short-lived (15 to 60 minutes) and refresh tokens long-lived (7 to 14 days) so a stolen access token expires quickly.
6	- If a short-lived access token must reach the browser for direct API calls, hold it in memory only — never in persistent storage.

Default to server sessions; use JWT only when statelessness is required/src/authhighstrictOpaque server sessions are revocable and carry no payload to leak; choose JWT only when cross-service stateless verification is genuinely needed.

1	Choosing the wrong token model is an architectural mistake that is expensive to reverse. The safer default is always an opaque session.
2
3	- Default to opaque server sessions stored in Redis or Postgres, returned to the browser as an httpOnly cookie. They are instantly revocable, carry no payload to leak, and are the simplest model to reason about.
4	- Reach for JWTs only when you genuinely need stateless verification across services or edge runtimes. Accept that revocation requires a denylist or very short TTLs.
5	- A signed JWT cannot be invalidated before expiry. Keep access token TTL at 15 to 60 minutes and pair with a rotating refresh token to limit the blast radius of a leaked token.
6	- Never put secrets, passwords, PII, or sensitive authorization claims in a JWT payload; it is base64, not encrypted, and is readable by anyone who holds it.

Hash passwords with Argon2id, never fast hashes/src/authhighstrictUse Argon2id at OWASP 2026 parameters; bcrypt at cost 12+ only as a legacy runtime fallback.

1	Passwords must be hashed with a memory-hard algorithm so offline cracking remains expensive even with modern hardware.
2
3	- Default to Argon2id via the `argon2` package using OWASP 2026 minimums: 19 MiB memory, 2 iterations, parallelism 1. Tune upward if your hardware allows without exceeding p95 login latency.
4	- Use bcrypt at cost factor 12 or higher only when Argon2 is unavailable in the target runtime.
5	- Never use `md5`, `sha1`, `sha256`, or any unsalted or single-round hash for passwords.
6	- Compare passwords using the library's built-in `verify` so the work factor and salt are read from the stored hash. Never write your own comparison.

Memories

OAuth/OIDC: PKCE, token rotation, and replay detection/src/authAuthorization Code + PKCE, validate all OIDC claims, rotate refresh tokens on every use with atomic replay detection.

1	Third-party login and delegated access must follow RFC 9700 (OAuth 2.0 Security BCP). Older tutorials recommend flows that are now deprecated or insecure.
2
3	- Always use the Authorization Code flow with PKCE, even for confidential clients. The implicit and resource-owner password grants are deprecated and absent from RFC 9700. Use `openid-client` or `oauth4webapi` instead of hand-rolling the flow.
4	- Validate the `state` parameter on callback to prevent CSRF. Before trusting any OIDC claim, verify the `id_token` signature, `iss`, `aud`, and `nonce`.
5	- Rotate refresh tokens on every use: issue a new refresh token and immediately invalidate the consumed one. If a consumed token is replayed, revoke the entire token family for that user.
6	- Make rotation atomic with a database transaction or a compare-and-swap lock so concurrent refresh requests cannot mint two valid tokens for one client session.
7	- Store OAuth tokens server-side under the same httpOnly cookie session, never in localStorage. The browser only needs the session cookie; the token exchange and storage live on the server.

Skills

auth-sessions-jwt-oauth-review/rootPre-merge checklist for any auth, session, JWT, or OAuth change.

1	---
2	name: auth-sessions-jwt-oauth-review
3	description: Use before merging any authentication change covering sessions, JWTs, OAuth/OIDC, password storage, cookies, CSRF, and token rotation. Run every item against the diff.
4	---
5
6	# Auth (Sessions, JWT, OAuth) review
7
8	- [ ] Tokens and session IDs are stored in httpOnly, secure, SameSite cookies with a `__Host-` prefix, never in localStorage or sessionStorage.
9	- [ ] Session vs JWT choice is justified: opaque server sessions by default, JWT only when stateless cross-service verification is required.
10	- [ ] Access tokens are short-lived (15 to 60 min); no secrets, passwords, or PII are in a JWT payload.
11	- [ ] Passwords are hashed with Argon2id at OWASP 2026 parameters (19 MiB, 2 iterations, parallelism 1), or bcrypt cost 12+ only as a documented runtime fallback.
12	- [ ] No fast or unsalted hash (md5, sha1, sha256) is used for passwords anywhere.
13	- [ ] Cookie-based endpoints enforce CSRF protection (SameSite + double-submit token) on all state-changing methods.
14	- [ ] OAuth uses Authorization Code + PKCE; implicit and password grants are absent.
15	- [ ] OIDC `id_token` signature, `iss`, `aud`, and `nonce` are verified before trusting any claim. `state` is validated against CSRF.
16	- [ ] Refresh tokens rotate on every use with replay detection that revokes the token family; rotation is atomic.
17	- [ ] Auth failures return generic messages and do not leak whether the user or password was wrong.

Why this pattern

AI agents reach for localStorage JWTs, weak password hashing, and missing CSRF defenses, shipping auth that breaks under XSS and token replay.

Built for Backend and full-stack teams building Node, TypeScript, or Python services that own login, sessions, and OAuth flows..

Keeps your assistant from:

Storing access or refresh tokens in localStorage where XSS can steal them
Hashing passwords with fast or unsalted algorithms like SHA-256 or MD5
Skipping refresh token rotation and CSRF protection on cookie-based auth

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-06-09

1	The browser sends auth cookies automatically on every matching request, including cross-site ones that SameSite alone does not fully cover in all scenarios. Every state-changing endpoint needs an explicit CSRF defense.
2
3	- Set `sameSite: 'lax'` as the baseline; upgrade to `strict` on sensitive write flows.
4	- Add a double-submit cookie token (for example `csrf-csrf`) validated on every unsafe method (POST, PUT, PATCH, DELETE). Pure stateless JWT-in-Authorization-header APIs that never use cookies do not need this.
5	- Verify `Origin` or `Referer` on state-changing requests as defense in depth.
6	- Treat GET, HEAD, and OPTIONS as safe; never mutate state inside them.