---
name: authentication-flow-review
description: Conducts a comprehensive authentication security review covering login, sessions, tokens, and credential handling. Use when auditing authentication for vulnerabilities.
license: CC0-1.0
metadata:
  category: security
allowed-tools: Read Grep Glob Write
disable-model-invocation: true
argument-hint: "[path or scope]"
---

**Target:** $ARGUMENTS

If no target path is given above, review the entire codebase.

---

# Authentication Flow Review

> **Stack note:** The code examples and library references below use Node.js/Express conventions (`bcrypt`, `jsonwebtoken`, `zod`/`joi`, `req.body`, etc.). If the codebase uses a different language or framework, apply the same security principles and adapt the specifics — for example: `bcrypt` → `passlib`/`Argon2id` (Python), `spring-security` (Java), `bcrypt` (Go); `jsonwebtoken` → `PyJWT`, `java-jwt`, `golang-jwt/jwt`; `mongoose.set('sanitizeFilter')` → the equivalent ORM sanitization setting. Mark any checklist item Not Applicable if the concept doesn't apply to the detected stack.

Conduct a comprehensive authentication security review:

Check for:

1. Password hashing

   * Uses `bcrypt.hash()` with salt rounds ≥ 10 (ideally 12); async, not sync; no double-hashing on updates.
   * `bcrypt.compare()` used for login.
2. JWT secret/key strength & storage

   * Secrets/keys not hardcoded; loaded from env or secret manager; separate keys for access vs refresh.
   * Strong entropy (≥256-bit for HS256) or asymmetric (RS256/ES256) with rotation plan.
3. Token settings

   * Access token TTL 5–15 minutes; refresh token TTL 7–30 days; sliding sessions bounded by a max session age.
   * JWT `algorithms`, `issuer (iss)`, `audience (aud)`, `subject (sub)`, `jti`, `iat`, `exp`, and optional `nbf` are enforced in `verify`.

4. Refresh token implementation
   * Rotation on every use and reuse detection (if old RT is presented, revoke the whole session family).
   * RTs stored in HttpOnly, Secure, SameSite cookie (not localStorage); hashed at rest if persisted; per-device tracking (`jti`, `ua`, `ip`, `expiresAt`).

5. Session invalidation

   * On password change/reset, previously issued tokens are rejected (compare `pwdChangedAt` or increment `tokenVersion` vs `jwt.iat`).

6. Brute force protection

   * Rate limit login/reset/verify endpoints; progressive backoff per username+IP in a fast store (e.g., Redis); optional CAPTCHA after threshold.

7. Account enumeration defenses

   * Generic errors and identical status/timing for “user not found” vs “bad password”; optional jitter.

8. Password reset flow security

   * Reset tokens via `crypto.randomBytes(32)`, hashed at rest (SHA-256), short TTL (≤ 15–30 min), one-time use, invalidated after success.
   * No secrets in logs; throttle reset email sender.

9. Email verification

   * One-time, short-TTL verification tokens; server-side verified; no way to mark verified via mass-assignment/body fields.

10. SQL/NoSQL injection in auth paths

    * No use of user-controlled operators in filters; query sanitization enabled; no `$where`; parameterized SQL if applicable.

11. AuthZ integrity

    * Roles/permissions loaded server-side; deny-by-default; never trust role/claims purely from the JWT payload without verification and (for sensitive ops) a DB check.

12. Cookie & CSRF configuration (if cookies used)

    * `HttpOnly`, `Secure`, `SameSite=Lax|Strict`, narrow `path`/`domain`, explicit `Max-Age`.
    * CSRF protection on state-changing endpoints and refresh route (double-submit token or same-site strategy).

13. Input validation & normalization

    * Email/username normalization; length & charset checks; password policy; strong schema validation (zod/joi/celebrate).

14. Mass assignment risks

    * Updates whitelist allowed fields; cannot set `role`, `emailVerified`, `passwordResetToken`, etc., from `req.body`.

15. JWT misuse

    * No `jwt.decode()` for authorization decisions; always `jwt.verify()` with explicit `algorithms`.

16. Logging & telemetry

    * No logging of passwords, tokens, reset links, or PII; structured logs with redaction/allowlist.

17. Dependency & crypto hygiene

    * Maintained `jsonwebtoken` and `bcrypt` versions; no custom JWT parser; Node crypto used correctly; no MD5/SHA\* for password hashing.

18. Transport & CORS

    * HTTPS enforced; CORS locked to trusted origins; no wildcard credentials; preflight handled safely.

19. Open redirect / `next` param

    * Post-login redirection restricted to vetted paths/origins; no arbitrary `next=` redirects.

20. Operational controls

    * Secret rotation procedure; key separation for environments; monitoring for suspicious auth patterns; alerting on RT reuse.

Provide:

* A structured finding report with the following for each issue:

  * Title, Severity (Critical/High/Medium/Low), CWE (if applicable), Evidence (file, function, line ranges), and a short Why it matters.
  * Exploitability notes and, where safe, a minimal PoC or reproduction steps (no real secrets).
  * Remediation: precise code-level fix or config change (snippets welcome), plus defense-in-depth guidance.
* A summary risk score (0–10) and top 3–5 prioritized fixes that reduce risk fastest.
* A checklist diff: which items from the “Check for” list are Pass/Fail/Not Applicable.

Constraints & style:

* Be concrete and cite exact code locations and identifiers.
* Prefer minimal, drop-in fix snippets over prose.
* Do not invent files or functions that aren’t present; if context is missing, mark as Unable to verify and say what code would prove it.

Bonus (if applicable):

* Suggest hardening improvements (e.g., switching to RS256 with KMS-managed keys, adding `jti` blacklist service, adding device/session management UI, enabling `mongoose.set('sanitizeFilter', true)`).
* Provide quick tests to validate fixes (e.g., RT reuse test, password-changed invalidation test, NoSQLi payload test).


Provide specific vulnerabilities found with severity ratings.

Write this into a markdown file and place it in the audits/ folder.