authentication.yaml

# Authentication Security Code Review Guidelines
# Comprehensive rules for authentication security best practices
# Version: 1.0
# Last Updated: 2026-01-02

name: Authentication Security Guidelines
description: Code review guidelines for authentication security covering password handling, session management, MFA, OAuth/OIDC, JWT, and rate limiting

globs:
  - "**/*.py"
  - "**/*.js"
  - "**/*.ts"
  - "**/*.java"
  - "**/*.go"
  - "**/*.rb"
  - "**/*.php"
  - "**/*.cs"
  - "**/*auth*"
  - "**/*login*"
  - "**/*session*"
  - "**/*password*"
  - "**/*token*"
  - "**/*oauth*"
  - "**/*jwt*"

rules:
  # ============================================================================
  # PASSWORD HANDLING RULES
  # ============================================================================
  
  - name: use-strong-password-hashing
    description: >
      Always use bcrypt, argon2, or scrypt for password hashing. Never use MD5, SHA1, SHA256,
      or other fast hashing algorithms for passwords. Fast hashes are vulnerable to brute force
      and rainbow table attacks. Bcrypt with cost factor >= 12, or Argon2id are recommended.
    severity: critical

  - name: generate-unique-salts
    description: >
      Generate a cryptographically random unique salt for each password. Never reuse salts
      across users or use predictable salts. Modern password hashing functions like bcrypt
      and argon2 handle salt generation automatically - ensure you're using them correctly.
    severity: critical

  - name: enforce-password-complexity
    description: >
      Enforce reasonable password complexity requirements: minimum 8-12 characters, check
      against common password lists (Have I Been Pwned API), and avoid overly restrictive
      rules that lead to predictable patterns. Consider using zxcvbn for strength estimation.
    severity: high

  - name: secure-password-reset
    description: >
      Password reset tokens must be cryptographically random (>= 128 bits), single-use,
      time-limited (< 1 hour), and invalidated after use or password change. Never send
      passwords in email. Use secure token storage with hashing.
    severity: high

  - name: no-plaintext-password-storage
    description: >
      Never store passwords in plaintext, reversibly encrypted form, or logs. Passwords
      should only exist in memory briefly during authentication and then be securely zeroed.
      Check that password fields are not logged in request/response logging.
    severity: critical

  # ============================================================================
  # SESSION MANAGEMENT RULES
  # ============================================================================

  - name: secure-session-cookies
    description: >
      Session cookies must have Secure (HTTPS only), HttpOnly (no JavaScript access), and
      SameSite=Lax or Strict attributes. Set appropriate Domain and Path restrictions.
      Use __Host- prefix for additional security on sensitive cookies.
    severity: high

  - name: implement-session-timeout
    description: >
      Implement both idle timeout (15-30 minutes for sensitive apps) and absolute timeout
      (8-24 hours). Require re-authentication for sensitive operations. Clearly communicate
      timeout to users and provide graceful session extension mechanisms.
    severity: medium

  - name: prevent-session-fixation
    description: >
      Regenerate session ID after successful authentication, privilege level change, or
      any security-sensitive operation. Never accept session IDs from URL parameters.
      Invalidate old session tokens completely.
    severity: high

  - name: implement-token-rotation
    description: >
      Implement refresh token rotation - issue new refresh token with each use and invalidate
      the old one. Detect and respond to refresh token reuse as potential theft. Implement
      token families for detecting concurrent usage.
    severity: high

  - name: secure-session-storage
    description: >
      Store session data server-side, not in cookies (except session ID). If using JWT or
      client-side sessions, ensure they're signed and optionally encrypted. Validate session
      data integrity on every request. Use secure, distributed session stores in production.
    severity: medium

  # ============================================================================
  # MULTI-FACTOR AUTHENTICATION RULES
  # ============================================================================

  - name: implement-totp-securely
    description: >
      TOTP implementation must use cryptographically secure secret generation (>= 160 bits),
      time drift tolerance of ±1-2 windows, and rate limiting on verification attempts.
      Display secret via QR code and backup text. Verify TOTP setup before enabling.
    severity: high

  - name: secure-backup-codes
    description: >
      Generate backup codes using CSPRNG, store them hashed (bcrypt/argon2), make them
      single-use, and limit the number (8-10). Show codes only once during generation.
      Track and notify on backup code usage. Allow regeneration with re-authentication.
    severity: high

  - name: prevent-mfa-bypass
    description: >
      Ensure MFA cannot be bypassed through account recovery, API endpoints, or race
      conditions. All authentication paths must enforce MFA. Require MFA re-verification
      for MFA settings changes. Implement step-up authentication for sensitive operations.
    severity: critical

  - name: secure-mfa-enrollment
    description: >
      Require current password verification before MFA enrollment changes. Send
      notifications for MFA changes. Implement a grace period before MFA removal takes
      effect. Consider requiring admin approval for MFA removal on high-privilege accounts.
    severity: high

  # ============================================================================
  # OAUTH/OIDC RULES
  # ============================================================================

  - name: validate-oauth-state-parameter
    description: >
      Always use and validate the state parameter in OAuth flows to prevent CSRF attacks.
      State must be cryptographically random, bound to user session, and verified before
      token exchange. Reject authorization responses with missing or invalid state.
    severity: critical

  - name: implement-pkce
    description: >
      Use PKCE (Proof Key for Code Exchange) for all OAuth flows, especially public
      clients (SPAs, mobile apps). Use S256 code_challenge_method, never plain. PKCE
      prevents authorization code interception attacks. Required for OAuth 2.1.
    severity: high

  - name: secure-token-storage
    description: >
      Store access tokens securely: httpOnly cookies for web, secure storage for mobile
      (Keychain/Keystore). Never store tokens in localStorage (XSS vulnerable). Use
      short-lived access tokens with refresh tokens. Clear tokens on logout.
    severity: high

  - name: validate-oauth-scopes
    description: >
      Request minimum necessary OAuth scopes. Validate granted scopes match requested.
      Enforce scope restrictions in your application. Don't assume all requested scopes
      are granted. Re-validate scopes on sensitive operations.
    severity: medium

  - name: validate-redirect-uri
    description: >
      Strictly validate redirect_uri against pre-registered URIs. Use exact matching,
      not prefix or regex matching. Never allow open redirects in OAuth flows. Validate
      on both authorization and token endpoints.
    severity: critical

  # ============================================================================
  # JWT RULES
  # ============================================================================

  - name: verify-jwt-algorithm
    description: >
      Always verify the JWT algorithm matches expected value. Never accept 'none' algorithm.
      Prevent algorithm confusion attacks (RS256 vs HS256). Whitelist allowed algorithms
      explicitly. Reject tokens with unexpected algorithms before verification.
    severity: critical

  - name: validate-jwt-expiration
    description: >
      Always set and validate exp (expiration) claim. Use short expiration for access
      tokens (5-15 minutes). Implement clock skew tolerance (30-60 seconds max). Reject
      expired tokens. Include iat (issued at) for audit purposes.
    severity: high

  - name: verify-jwt-signature
    description: >
      Always verify JWT signature before trusting claims. Use the correct key for
      verification. For asymmetric algorithms, use public key only for verification.
      Rotate signing keys periodically. Support multiple keys during rotation.
    severity: critical

  - name: validate-jwt-claims
    description: >
      Validate all relevant JWT claims: iss (issuer), aud (audience), sub (subject).
      Reject tokens from unexpected issuers or for wrong audiences. Validate custom
      claims used for authorization. Log claim validation failures.
    severity: high

  - name: secure-jwt-key-management
    description: >
      Use strong keys for JWT signing: HS256 requires >= 256-bit keys, RSA requires
      >= 2048-bit keys. Store private keys securely (HSM, KMS). Never expose private
      signing keys. Use asymmetric algorithms when tokens are verified by third parties.
    severity: high

  # ============================================================================
  # RATE LIMITING AND BRUTE FORCE RULES
  # ============================================================================

  - name: implement-login-rate-limiting
    description: >
      Rate limit login attempts by username AND by IP address. Implement progressive
      delays. After multiple failures, require CAPTCHA or temporary lockout. Track
      failed attempts across distributed systems. Alert on brute force patterns.
    severity: high

  - name: implement-account-lockout
    description: >
      Implement account lockout after failed login attempts (e.g., 5 attempts = 15 min
      lockout). Use exponential backoff. Notify users of lockouts via email. Provide
      secure unlock mechanism. Don't reveal whether account exists in lockout messages.
    severity: high

  - name: prevent-credential-stuffing
    description: >
      Protect against credential stuffing with rate limiting, CAPTCHA, device fingerprinting,
      and anomaly detection. Check passwords against breach databases (Have I Been Pwned).
      Implement step-up authentication for suspicious logins. Monitor for bot patterns.
    severity: high

  - name: protect-enumeration
    description: >
      Prevent username/email enumeration through consistent responses for login, registration,
      and password reset. Use same response time and message regardless of account existence.
      Rate limit enumeration endpoints strictly.
    severity: medium