nick-doc/04 - Flows/Password Reset Flow.md

title, tags, related_models, related_apis

title	tags	related_models	related_apis
Password Reset Flow	flow auth password-reset email	User	POST /api/auth/request-password-reset POST /api/auth/reset-password-with-code POST /api/auth/reset-password

Last updated: 2026-05-29 — aligned with code (see Doc vs Code Audit Report)

[!caution] Audit note — last reviewed 2026-05-29 Several discrepancies between frontend code, backend code, and this document were identified and corrected in this revision. See inline ⚠️ markers for known bugs and mismatches.

Password Reset Flow

Self-service password recovery. There are two separate reset endpoints with different security characteristics:

Endpoint	Mechanism	Password complexity enforced?
POST /api/auth/reset-password-with-code	6-digit emailed code	No — no validation middleware
POST /api/auth/reset-password	Token-based (link in email)	Yes — passwordResetValidation requires uppercase + lowercase + digit

The primary UI-driven path uses the code-based endpoint. The token-based endpoint is a legacy/alternative variant.

Actors

• User who has forgotten their password.
• Frontend — frontend/src/auth/view/jwt/jwt-reset-password-view.tsx (request) and jwt-update-password-view.tsx (submit new password).
• Backend — AuthController.requestPasswordReset and AuthController.resetPasswordWithCode in backend/src/services/auth/authController.ts.
• MongoDB — User collection (passwordResetCode, passwordResetCodeExpires, refreshTokens).
• Email service — emailService.sendPasswordResetCodeEmail.

Preconditions

• The account exists and status === "active" (deleted accounts are silently treated as non-existent).
• The user has access to the email inbox associated with the account.
• A 6-digit code is valid for 1 hour (authController.ts:556).

Step-by-step narrative

1. User clicks "Forgot password?" on the sign-in page and lands at /auth/jwt/reset-password.
2. User enters their email and submits.
3. Frontend POSTs POST /api/auth/request-password-reset { email }.
4. Backend authController.requestPasswordReset (:542-574):
   • User.findOne({ email, status: "active" }). If absent, returns 200 with the same generic message — no enumeration.
   • Generates a 6-digit code via authService.generateVerificationCode() (Math.floor(100000 + Math.random() * 900000)).
   • Saves passwordResetCode and passwordResetCodeExpires = now + 3_600_000 ms on the user.
   • Calls emailService.sendPasswordResetCodeEmail(email, firstName, code).
5. Response: 200 "If an account with this email exists, a password reset code has been sent" regardless of outcome.
6. User receives the email and enters the code + new password on /auth/jwt/update-password.
7. Frontend POSTs POST /api/auth/reset-password-with-code { email, code, password }.
8. Backend authController.resetPasswordWithCode (:611-657):
   • Validates code format /^\d{6}$/ — codes of any other length will always fail here.
   • User.findOne({ email, passwordResetCode: code, passwordResetCodeExpires: { $gt: now }, status: "active" }). Mismatch → 400 Invalid or expired reset code.
   • Hashes the new password with bcrypt cost 12. No password complexity validation is applied — weak passwords such as 123456 or aaaaaa are accepted without error.
   • Sets user.password = hashed, clears passwordResetCode and passwordResetCodeExpires, wipes user.refreshTokens = [] to invalidate all existing sessions.
   • Saves.
9. Response: 200 "Password reset successfully". Frontend redirects to /auth/jwt/sign-in for a fresh login.

Sequence diagram

sequenceDiagram
    autonumber
    actor U as User
    participant FE as Frontend
    participant BE as Backend
    participant DB as MongoDB
    participant MAIL as Email Service

    U->>FE: Click "Forgot password", enter email
    FE->>BE: POST /api/auth/request-password-reset { email }
    BE->>DB: User.findOne({ email, status: "active" })
    alt user found
        BE->>BE: code = generateVerificationCode() [6 digits]
        BE->>DB: user.passwordResetCode = code\nexpires = +1h
        BE->>MAIL: sendPasswordResetCodeEmail(email, firstName, code)
        MAIL-->>U: Email with 6-digit code
    end
    BE-->>FE: 200 "if account exists, code sent"

    U->>FE: Enter code + new password
    FE->>BE: POST /api/auth/reset-password-with-code { email, code, password }
    BE->>BE: isValidVerificationCode(code) [/^\d{6}$/]
    BE->>DB: User.findOne({ email, code, expires>now })
    BE->>BE: bcrypt.hash(password, 12) [no complexity check]
    BE->>DB: user.password = hash\nuser.refreshTokens = []\nclear reset fields
    BE-->>FE: 200 "Password reset successfully"
    FE-->>U: Redirect /auth/jwt/sign-in

API calls

Method	Endpoint	Source	Notes
POST	/api/auth/request-password-reset	authRoutes.ts:44-47	Sends 6-digit code by email
POST	/api/auth/reset-password-with-code	authRoutes.ts:54-56	Code-based; no complexity validation
POST	/api/auth/reset-password	authRoutes.ts:49-52	Token-based variant; enforces complexity via passwordResetValidation

Two-endpoint comparison

[!important] Code-based vs token-based reset endpoints

POST /api/auth/reset-password-with-code (primary UI path)

• Uses a 6-digit numeric code delivered by email.
• isValidVerificationCode() validates with /^\d{6}$/.
• Has no password complexity middleware. Any string is accepted as the new password.

POST /api/auth/reset-password (legacy token-based path)

• Uses a URL token (link in email) rather than a short code.
• Enforces password complexity via passwordResetValidation middleware (requires uppercase, lowercase, and a digit).

The two endpoints provide inconsistent security guarantees. Users who reset via the code flow can set a weak password that would be rejected by the token flow.

Database writes

• users collection: on request, sets passwordResetCode + passwordResetCodeExpires. On submit, replaces password, clears reset fields, and empties refreshTokens.

Socket events emitted

• None.

Side effects

• Email: one transactional message containing the 6-digit code.
• Server-side log: authController.ts:559 console.log includes the generated code in plain text — same hardening note as Registration Flow.
• Session invalidation: All refresh tokens cleared → all devices forced to re-login after password change. Access tokens still valid until expiry (typically minutes).

Error / edge cases

• Unknown email → always 200, generic message. No enumeration.
• Invalid code format → 400 from isValidVerificationCode guard before DB lookup.
• Expired code (>1h) → 400 Invalid or expired reset code.
• Multiple parallel requests → each overwrites the previous passwordResetCode; the latest email wins, prior codes silently invalidated.
• User attempts reset on deleted account → treated as unknown (no email sent, 200 returned).
• Email delivery failure → response still 200; user can request again.
• Access tokens still valid post-reset → unavoidable with stateless JWT; mitigated by short TTL. Critical operations should re-verify password.

[!warning] Plaintext code in logs Same as Registration Flow: the reset code is console.log-ed by the controller in all environments. Restrict log access in production or gate the log behind NODE_ENV !== 'production'.

Known issues summary

Issue	Severity	Details
No password complexity on code-based reset	Security gap	POST /api/auth/reset-password-with-code has no complexity middleware; weak passwords accepted
Inconsistent complexity between reset endpoints	Security gap	Token-based reset enforces complexity; code-based reset does not

Linked flows

• Authentication Flow — user re-signs-in after reset.
• Registration Flow — same code-generation utility.

Source files

• Backend: backend/src/services/auth/authController.ts:542-657
• Backend: backend/src/services/email/emailService.ts (sendPasswordResetCodeEmail)
• Frontend: frontend/src/auth/view/jwt/jwt-reset-password-view.tsx
• Frontend: frontend/src/auth/view/jwt/jwt-update-password-view.tsx
• Frontend: frontend/src/auth/context/jwt/action.ts:181-200, :261-276