[0.3] Password Reset

1. Front Matter

• Title: Password Reset

• Author: Sean Patrick Caintic

• Reviewers: Joshua Uriel Tribiana

• Created: February 2026

• Status: Approved

• References:

  • Issue: [0.3] Password Reset #69

  • Milestone: [0] Auth & Security

2. Introduction & Goals

• Problem Summary: Users who forget their passwords need a secure, self-service recovery mechanism via email. The reset flow must be time-limited and single-use to prevent abuse.

• Goals:

  • Implement email-based password reset with 1-hour token validity

  • Provide password visibility toggle on reset form

  • Show password strength and match validation

  • Invalidate token after successful use

• Non-Goals:

  • SMS-based reset (email only)

  • Security questions

  • Admin-initiated password resets

• Glossary:

  • Reset Token: Single-use, time-limited code sent via email

  • OTP: One-time password/code for verification

3. High-Level Architecture

• System Diagram:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Reset Request  │────▶│  Clerk Auth     │────▶│  Email Service  │
│  (Email Input)  │     │  (Token Gen)    │     │  (Token Link)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Password       │◀────│  Token Verify   │◀────│  User Clicks    │
│  Update Form    │     │  (Expiry Check) │     │  Email Link     │
└─────────────────┘     └─────────────────┘     └─────────────────┘

• Technologies Used:

  • Clerk - Token generation and email sending

  • Shadcn/UI - Form components

  • Lucide Icons - Eye toggle icons

4. Detailed Design & Implementation

• Data Model / Schema: No custom tables. Clerk manages reset tokens internally.

• API Specification: Uses Clerk's built-in reset flow, no custom endpoints.

  • signIn.create({ strategy: "reset_password_email_code" }) - Request reset

  • signIn.attemptFirstFactor() - Verify token and set password

• Logic & Workflows:

  Reset Flow:

  1. User enters email (instant)

  2. Clerk generates token (1 hour validity)

  3. Email sent (less than 30 seconds)

  4. User clicks link (redirects to form)

  5. User enters new password

  6. Token verified and invalidated (single use)

  Password Form Features:

  • Eye icon toggle for visibility

  • Strength indicator (weak/medium/strong)

  • Real-time match validation

  Key Files:

  • app/(auth)/forgot-password/page.tsx - Email input form

  • app/(auth)/reset-password/page.tsx - New password form

5. Infrastructure & Operations

• Dependencies:

  • Clerk - Token management and email delivery

• Monitoring & Alerting: Clerk Dashboard: Failed reset attempts, email delivery status

• Deployment Plan: No migrations. Clerk handles token storage.

6. Testing & Quality Assurance

• Test Strategy:

  • Manual: Full reset flow, email receipt

  • E2E: Password update success

• Known Limitations:

  • Token expires after 1 hour (not configurable)

  • No retry limit on reset requests (rate limited by Clerk)

7. Maintenance & Support

• Troubleshooting:

  • Email not received → Check spam folder, verify email exists

  • Token expired error → Request new reset link

  • Invalid token error → Token already used, request new one

• Changelog:

  • 1.0 (Feb 2026): Initial implementation

Document Version

1.0 - Approved, Feature deployed to production, 02/17/2026