Recipe: Password reset flow design

Overview

This recipe covers the full lifecycle: request, email delivery, token validation, and credential rotation. Every step is designed to prevent enumeration, token replay, and timing side-channels.

Flow Steps

1. 1
   User requests reset

   Collect email. Always return a generic success message regardless of whether the account exists.

2. 2
   Generate signed token

   Create a short-lived JWT or opaque token bound to the user ID and current password hash. Store hashed in the database.

3. 3
   Deliver magic link

   Send email with a single-use link. Include rate-limiting headers and a clear expiration window.

4. 4
   Validate and rotate

   Verify token signature, expiry, and single-use flag. Prompt for new password, then invalidate all existing sessions.

Security Considerations

• Constant-time token comparison to prevent timing attacks
• Rate-limit reset requests per IP and per account
• Expire tokens after 15 minutes
• Invalidate token immediately after first use
• Never reveal whether an email is registered