Secure Password Reset Systems

# CHAPTER 13

Secure Password Reset Systems #

1. Introduction #

2. Learning Objectives #

• Identify common security flaws in naive password reset workflows.

• Design a database schema for storing temporary reset tokens.

• Generate cryptographically secure, random tokens.

• Architect the complete, secure "Forgot Password" to "Reset Password" workflow.

• Understand the importance of token hashing and timing limits.

3. Beginner-Friendly Explanation #

• Bad Security: The teller says, "Okay, what do you want your new key to look like?" and changes the lock immediately. (Anyone could walk in and claim to be you).

• Good Security: The teller says, "I can't change it right now. I just mailed a special, sealed letter to your house. Inside the letter is a random, 64-character code. That code is only valid for 15 minutes. When you bring that specific code back to the bank, *then* I will let you change the lock."

A secure password reset system guarantees that the person requesting the change physically possesses the email account associated with the user profile.

4. The Naive (Dangerous) Implementation #

1. 1. User types email john@example.com.

1. 2. Backend generates a 4-digit code 1234 and saves it to the user's database row.

1. 3. Backend emails 1234 to John.

1. 4. User types 1234 and a new password. Account updated.

The Flaw: A 4-digit code only has 10,000 combinations. A hacker can write a script to submit 0000, 0001, 0002... and guess the code in 3 seconds, instantly hijacking the account without ever seeing the email.

5. Step 1: The Database Schema #

SQL Schema:

CREATE TABLE password_resets (
    id INT AUTO_INCREMENT PRIMARY KEY,
    user_id INT NOT NULL,
    token_hash VARCHAR(255) NOT NULL, -- Never store the raw token!
    expires_at DATETIME NOT NULL,
    used BOOLEAN DEFAULT FALSE
);

6. Step 2: Generating the Request #

const crypto = require('crypto');

// 1. Generate a massive, mathematically random token (Hexadecimal string)
const rawToken = crypto.randomBytes(32).toString('hex');

// 2. Hash the token for database storage (Just like an API Key!)
const hashedToken = crypto.createHash('sha256').update(rawToken).digest('hex');

// 3. Set expiration (e.g., 15 minutes from now)
const expirationTime = new Date(Date.now() + 15 * 60 * 1000);

// 4. Save to the `password_resets` database table
await database.insertResetToken(user.id, hashedToken, expirationTime);

// 5. Build the secure URL containing the RAW token
const resetUrl = `https://yourfrontend.com/reset-password?token=${rawToken}&userId=${user.id}`;

// 6. Email the `resetUrl` to the user's registered email address using an email API (like SendGrid).

7. Step 3: Verifying the Token #

// POST /api/reset-password
const { userId, rawToken, newPassword } = req.body;

// 1. Find the token record in the database for this user that has NOT been used
const resetRecord = await database.findValidResetRecord(userId);

if (!resetRecord) {
    return res.status(400).json({ error: "Invalid or expired reset token." });
}

// 2. Check Expiration Time
if (new Date() > resetRecord.expires_at) {
    return res.status(400).json({ error: "Token has expired. Please request a new one." });
}

// 3. Hash the incoming rawToken and compare it to the database hash
const incomingHash = crypto.createHash('sha256').update(rawToken).digest('hex');

if (incomingHash !== resetRecord.token_hash) {
    return res.status(400).json({ error: "Invalid token." });
}

// 4. SUCCESS! The token is valid.
// Hash the NEW password and update the Users table
const newPasswordHash = await bcrypt.hash(newPassword, 10);
await database.updateUserPassword(userId, newPasswordHash);

// 5. CRITICAL: Mark this specific token as USED so it cannot be used again!
await database.markTokenAsUsed(resetRecord.id);

res.json({ message: "Password updated successfully!" });

8. Backend Workflow: Why Hash the Token? #

9. Best Practices #

• Vague Responses: When a user submits an email to the "Forgot Password" form, NEVER return an error saying "Email not found in database." This allows hackers to scan your site to discover which emails belong to registered users (User Enumeration). Always return a vague success message: "If that email exists in our system, a reset link has been sent."

• Invalidate Old Sessions: When a password is successfully reset, you should immediately revoke all active JWTs or Sessions for that user across all devices. If their account was hacked, changing the password should forcefully kick the hacker out.

10. Common Mistakes #

• No Rate Limiting: Hackers use automated scripts to submit 10,000 "Forgot Password" requests for a victim's email. This spams the victim's inbox, costing you money in email API fees. Always rate-limit the Forgot Password endpoint (e.g., max 3 requests per hour per IP address).

11. Exercises #

1. 1. Trace the architectural workflow of a secure Password Reset. Explain why the raw token is mailed to the user, but only the hashed version is stored in the database.

12. Coding Challenges #

• Challenge: Conceptualize how you would implement the "Invalidate Old Sessions" best practice if you are using stateless JWTs. Since you cannot delete a stateless JWT, what field could you add to the Users database table, and check within your middleware, to instantly invalidate all previously issued JWTs when a password changes? (Hint: A password_version integer).

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain the phenomenon of "User Enumeration" via a Forgot Password endpoint. How do you architect your API response to completely neutralize this vulnerability?

• Q: Walk me through a cryptographically secure Password Reset workflow. Specifically address token generation, database storage, expiration handling, and token invalidation.

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #