Password Recovery Design: Anonymous Requests, Verified Resets, and Session Revocation

When a user forgets their password, the system should treat both known and unknown email addresses identically. A single-use, short-lived token moves the account into a confirmed reset state before revoking existing sessions. This state machine should be stored in the application database. Email delivery can be handled through a replaceable interface.

To prevent token misuse, each reset attempt must be logged and verified, ensuring that the same token cannot be used twice. The system should distinguish between bot signups and forgotten passwords, but both ultimately require the same trust boundary - verifying the email address through a challenge. The process begins with a simple request.

A browser submits an email address, which the API normalizes, records a hashed recovery request, and queues a message if a matching account is found. The response remains consistent whether the account is found or not. The reset link contains a random token, never the user ID or email, and upon clicking, it hashes the token, consumes it, updates the password, and revokes all active sessions for that account.

The system follows a clear privacy control by providing a "no such account" message for unknown requests. The state transitions are explicit: requested, delivered, confirmed, completed, and expired. The confirmed state indicates a successful token check, while the password change is still pending. Keeping the system straightforward helps in auditing and retry handling.

A framework-neutral core is provided, with a tiny repository and mailer interface to facilitate migration. The core is written in Python, using dataclasses, datetime, hashlib, hmac, and secrets for token generation and validation. The normalize_email function strips, converts to lowercase, and ensures consistent email addresses.

The digest_token function creates a hashed token using a pepper value for added security. The request_reset function handles the initial flow, checking if an account exists, generating a token, storing it, and enqueuing a reset message. The complete_reset function hashes the received token, locks the unused request, updates the account's password, marks the request as used, and revokes all sessions for the account. This approach ensures a secure, consistent, and privacy-preserving password recovery process.