Password Reset

Schema validation

The request body is validated with a Zod schema that checks the email format. Invalid or XSS-flagged input returns 400 or 403 before any database query runs.

User lookup

sendTempPasswordResetLink queries the users table for a matching email. If no user is found, the uniLimiter is consumed for the composite key ${IP}_${email} and the function returns without sending an email.

OAuth-only rejection

If the user's password_hash is 'no_password', the user authenticated exclusively through OAuth and has no password to reset. The function returns without sending an email.

Link generation

A unique JTI is generated using crypto.randomUUID() + crypto.randomBytes(64).toString('hex'), producing a 164-character string. A random challenge is generated with crypto.randomBytes(128).toString('hex'), then SHA-256 hashed.

A temporary JWT is signed with:

Link delivery

The reset URL is built from magic_links.paths.pathForPasswordResetLink and magic_links.domain, with visitor, token, random, and reason appended as query parameters. The link is sent to the user's email via resetPasswordEmail.

Minimum response time

The controller enforces a 3-second minimum response time using Date.now() at the start and waitSomeTime() in the finally block. This prevents timing-based enumeration regardless of how quickly the database query completes.

Schema validation

The query string is validated with a Zod schema (buildInMfaFlows). Malformed or XSS-flagged values return 400 or 403.

IP rate limit

A per-IP limiter (consecutiveForIpPassword) is checked before JWT verification. Repeated failures from the same IP are blocked progressively.

JWT verification

verifyTempJwtLink verifies the signed token. An invalid or expired token returns 400.

Visitor match

The visitor query parameter must match payload.visitor. A mismatch returns 400.

Payload integrity

The following checks run against the decoded payload:

• payload.purpose must equal reason (PASSWORD_RESET)
• payload.subject must equal PASSWORD_RESET_{visitor}
• The SHA-256 hash of random must match payload.randomHashed via crypto.timingSafeEqual

Any mismatch returns 401.

JTI replay check

The usedJtiLimiter is checked. If the JTI has been blocked (consumed on a prior POST), the request returns 400 with 'Link is not valid or expired'.

GET count enforcement

An in-memory counter tracks how many times this JTI has been accessed via GET. Exceeding allowedPerSuccessfulGet (default 5) returns 400.

Content type check

The request must have Content-Type: application/json. Any other content type returns 400.

Link purpose check

req.link.purpose must be PASSWORD_RESET and req.link.subject must be PASSWORD_RESET_{visitor}. A mismatch returns 400.

Rate limit checks

The three limiters above are checked in order: JTI limiter, IP limiter, then composite union limiter. Any failure returns 429.

Schema validation

The request body is validated against the passwords Zod schema, which requires both password and confirmedPassword. Invalid input returns 400.

Password match

password and confirmedPassword are compared. A mismatch returns 400 with { "error": "Password doesn't match", "banned": false }.

Breach check

The password is checked against the HaveIBeenPwned API via isPwned. If the password appears in a known data breach, the request is rejected with 400:

{
  "ok": false,
  "error": "Our system identified this password in X data breaches. Please choose a different password."
}

Password hashing

The new password is hashed with Argon2id via hashPassword.

User lookup

The user record is fetched from the database using the visitor_id from the link token, locked with FOR UPDATE inside a transaction.

Password update

UPDATE users
SET password_hash = ?
WHERE id = ? AND visitor_id = ?
LIMIT 1

If affectedRows is not exactly 1, the transaction rolls back and 400 is returned.

Session revocation

All active refresh tokens for the user are invalidated:

UPDATE refresh_tokens
SET valid = 0
WHERE user_id = ? AND valid = 1

JTI block

The JTI is blocked in usedJtiLimiter for 20 minutes, preventing link reuse.

Notification email

After a successful commit, a security notification email is sent to the user's address with the subject "Security Alert: Password Reset Successful". The email includes a link to the login page configured at magic_links.notificationEmail.loginPageLink.

Rate limiter cleanup

All consecutive caches and the union limiter for the composite key are reset on success.