How to Handle Password Resets in Node.js

How to Handle Password Resets in Node.js

Password reset is a common feature with real security pitfalls. Here is how to do it right.

The Flow

1. User clicks "Forgot password" and submits their email.
2. Server generates a one-time reset token (random, unguessable).
3. Server stores the hash of the token with an expiry (e.g., 15 min) on the user.
4. Server emails the user a link containing the token (e.g., /reset-password?token=abc).
5. User clicks the link, enters a new password.
6. Server verifies the token (compare hash, check expiry), hashes the new password, saves, and invalidates the token.

Generate a Token

const crypto = require('crypto');
const token = crypto.randomBytes(32).toString('hex');
const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
const expiresAt = new Date(Date.now() + 15 * 60 * 1000);

Store the hash, not the raw token. If the database is leaked, attackers cannot use the tokens.

Store on User

user.resetTokenHash = tokenHash;
user.resetTokenExpiresAt = expiresAt;
await user.save();

Email the Link

await sendEmail({
  to: user.email,
  subject: 'Password reset',
  body: `Click here to reset your password: https://app.com/reset-password?token=${token}`
});

The raw token goes in the URL. The hash is stored. An attacker who reads the database cannot use the hash.

Verify on Reset

router.post('/reset-password', asyncHandler(async (req, res) => {
  const { token, newPassword } = req.body;
  const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
  const user = await User.findOne({ resetTokenHash: tokenHash, resetTokenExpiresAt: { $gt: Date.now() } });
  if (!user) return res.status(400).json({ error: 'Invalid or expired token' });
  user.passwordHash = newPassword;
  user.resetTokenHash = undefined;
  user.resetTokenExpiresAt = undefined;
  await user.save();
  res.json({ message: 'Password reset' });
}));

The pre('save') hook hashes the new password. The token is invalidated by clearing the fields.

Security Considerations

• Token expiry: 15 min is good. Do not use 24 hours.
• One-time use: invalidate the token after a successful reset.
• Hash the stored token: never store raw tokens.
• Rate limit the request endpoint: prevent email flooding.
• Do not reveal if the email exists: return the same response whether the email is registered or not, to prevent enumeration.
• Notify the user after reset: send an email saying the password was changed.
• Invalidate sessions: after a reset, invalidate all existing JWTs (e.g., bump a tokenVersion field).

Common Mistakes

• Storing raw tokens instead of hashes.
• Long expiry (24 hours).
• Reusing tokens (no invalidation after reset).
• Revealing whether the email is registered.
• Not rate limiting the request endpoint.

The Takeaway

Handle password resets by generating a random token, storing its hash with a 15-min expiry, emailing a link with the raw token, verifying the hash on reset, hashing the new password, and invalidating the token. Hash stored tokens. Rate limit. Do not reveal if the email exists. Notify the user after reset.