SkyMoney/SECURITY_FORGOT_PASSWORD.md

Security Forgot Password Controls

Implemented Controls

• Public entry points:
  • POST /auth/forgot-password/request
  • POST /auth/forgot-password/confirm
• Enumeration resistance:
  • Request endpoint always returns 200 with a generic success message.
  • No account existence signal for unknown/unverified emails.
• Verified-account gate:
  • Reset tokens are issued only when emailVerified=true.
• Token security:
  • Reset links contain uid and raw token in query params.
  • Server stores only SHA-256(token).
  • Token type is password_reset.
  • Token must match uid, be unused, and be unexpired.
  • Token is consumed once (usedAt) and cannot be reused.
• Session invalidation:
  • Added User.passwordChangedAt.
  • JWT auth middleware rejects tokens with iat <= passwordChangedAt.
  • Reset and authenticated password-change both set passwordChangedAt.
• Abuse controls:
  • Request endpoint: per-IP + email-fingerprint route keying.
  • Confirm endpoint: per-IP + uid-fingerprint route keying.
  • Endpoint-specific rate limits via env config.
• Logging hygiene:
  • Structured security events for request/email/confirm outcomes.
  • No plaintext password or raw token in logs.
• Misconfiguration resilience:
  • Email send failures do not leak through API response shape.
  • Generic response is preserved if SMTP is unavailable.

Environment Settings

• PASSWORD_RESET_TTL_MINUTES (default 30)
• PASSWORD_RESET_RATE_LIMIT_PER_MINUTE (default 5)
• PASSWORD_RESET_CONFIRM_RATE_LIMIT_PER_MINUTE (default 10)

Operational Verification

1. Verify /auth/forgot-password/request always returns the same JSON for unknown, unverified, and verified addresses.
2. Verify only verified users get EmailToken(type=password_reset) rows.
3. Verify confirm succeeds once and fails on replay.
4. Verify pre-reset session cookies fail on protected routes after successful reset.
5. Verify security logs contain auth.password_reset.* events and no raw token values.