Auth (Sessions, JWT, OAuth)

Pathrule3 Rules • 2 Memories • 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

Hash passwords with Argon2id, never fast hashes

Sessions vs JWT: pick the right model

OAuth/OIDC and refresh token rotation

middleware/

Protect cookie-based auth from CSRF

Rules

Never store auth tokens in localStorage/src/authSession and refresh tokens must live in httpOnly cookies, never web storage.

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 fast.
6	- If a short-lived access token must reach the browser for API calls, hold it in memory only, never in persistent storage.

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

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

Memories

Sessions vs JWT: pick the right model/src/authDefault to server sessions; reach for JWT only when statelessness is required.

1	Choosing between server-side sessions and JWTs is the first auth decision and the one agents most often get wrong.
2
3	- Default to opaque server sessions stored in Redis or Postgres with an httpOnly cookie. They are revocable instantly, carry no payload to leak, and are simplest to reason about.
4	- Reach for JWTs only when you genuinely need stateless verification across services or edge runtimes, and accept that revocation requires a denylist or very short TTLs.
5	- A signed JWT cannot be invalidated before expiry, so keep access token TTL low (15 to 60 min) and pair it with a rotating refresh token.
6	- Do not put secrets or PII in a JWT payload; it is base64, not encrypted, and is readable by anyone holding it.

OAuth/OIDC and refresh token rotation/src/authUse Authorization Code + PKCE and rotate refresh tokens with replay detection.

1	For third-party login and delegated access, follow RFC 9700 (OAuth 2.0 Security BCP) rather than older tutorials.
2
3	- Always use the Authorization Code flow with PKCE, even for confidential clients; the implicit and password grants are deprecated. Use `openid-client` or `oauth4webapi` rather than hand-rolling the flow.
4	- Validate the `state` parameter against CSRF and validate the OIDC `id_token` signature, `iss`, `aud`, and `nonce` before trusting any claim.
5	- Rotate refresh tokens on every use: issue a new refresh token and invalidate the old one. If a consumed token is replayed, revoke the entire token family.
6	- Make rotation atomic with a DB transaction or lock so concurrent refreshes cannot mint two valid tokens for one client.

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	- [ ] Passwords are hashed with Argon2id at OWASP 2026 parameters (19 MiB, 2 iterations, parallelism 1), or bcrypt cost 12+ only as a documented fallback.
10	- [ ] No fast or unsalted hash (md5, sha1, sha256) is used for passwords anywhere.
11	- [ ] Session vs JWT choice is justified: opaque server sessions by default, JWT only when stateless verification is required.
12	- [ ] Access tokens are short lived (15 to 60 min); JWTs carry no secrets or PII in the payload.
13	- [ ] OAuth uses Authorization Code + PKCE; implicit and password grants are absent.
14	- [ ] OAuth `state` is validated and the OIDC `id_token` signature, `iss`, `aud`, and `nonce` are verified before trusting claims.
15	- [ ] Refresh tokens rotate on every use with replay detection that revokes the token family; rotation is atomic.
16	- [ ] Cookie-based endpoints enforce CSRF protection (SameSite plus double-submit token) on all state-changing methods.
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	Because the browser sends auth cookies automatically, every state-changing request needs an explicit CSRF defense.
2
3	- Set `sameSite: 'lax'` as the baseline and `strict` on sensitive POST/PUT/PATCH/DELETE flows; SameSite alone is not a complete defense.
4	- Add a double-submit cookie token (for example `csrf-csrf`) validated on every unsafe method; pure stateless JWT-in-header APIs that never use cookies can skip this.
5	- Verify `Origin` or `Referer` on state-changing requests as defense in depth.
6	- Treat `GET`, `HEAD`, and `OPTIONS` as safe and never mutate state in them.