My-Weekly-ToDo-List/.planning/phases/01-setup-and-authentication/01-02-PLAN.md

---
phase: 01-setup-and-authentication
plan: 02
type: execute
wave: 1
depends_on: []
files_modified: 
  - src/app/api/auth/forgot-password/route.ts
  - src/app/api/auth/reset-password/route.ts
  - src/app/api/auth/verify-email/route.ts
  - src/app/auth/forgot-password/page.tsx
  - src/app/auth/reset-password/page.tsx
  - src/app/auth/verify-email/page.tsx
  - src/components/PasswordResetForm.tsx
  - src/components/EmailVerificationForm.tsx
autonomous: true
must_haves:
  truths:
    - User receives email verification after signup
    - User can reset password via email link
    - User can access email verification page after signup
  artifacts:
    - path: "src/app/api/auth/forgot-password/route.ts"
      provides: "POST endpoint for initiating password reset process"
      exports: ["POST"]
    - path: "src/app/api/auth/reset-password/route.ts"
      provides: "POST endpoint for resetting password with token validation"
      exports: ["POST"]
    - path: "src/app/api/auth/verify-email/route.ts"
      provides: "GET endpoint for verifying email with token"
      exports: ["GET"]
    - path: "src/app/auth/forgot-password/page.tsx"
      provides: "Forgot password page component with form handling"
      min_lines: 20
    - path: "src/app/auth/reset-password/page.tsx"
      provides: "Reset password page component with form handling"
      min_lines: 20
    - path: "src/app/auth/verify-email/page.tsx"
      provides: "Email verification page component with token handling"
      min_lines: 20
  key_links:
    - from: "src/app/auth/forgot-password/page.tsx"
      to: "/api/auth/forgot-password"
      via: "fetch API call"
      pattern: "fetch.*api/auth/forgot-password"
    - from: "src/app/auth/reset-password/page.tsx"
      to: "/api/auth/reset-password"
      via: "fetch API call"
      pattern: "fetch.*api/auth/reset-password"
    - from: "src/app/api/auth/forgot-password/route.ts"
      to: "prisma.user"
      via: "database lookup for email verification"
      pattern: "prisma\\.user\\.(findUnique)"
    - from: "src/app/api/auth/reset-password/route.ts"
      to: "prisma.user"
      via: "database lookup and update"
      pattern: "prisma\\.user\\.(findUnique|update)"
---

# Phase 1, Plan 2: Complete Authentication Flow

## Objective

Implement the complete authentication flow including email verification, password reset, and middleware protection for authenticated routes.

## Purpose

This plan expands the authentication system to include comprehensive email verification and password recovery mechanisms. These features improve user experience by enabling account recovery and ensuring email authenticity.

## Output

- Complete email verification flow with token-based verification
- Password reset functionality with token-based process
- Dedicated pages for password reset and email verification
- Supporting components for these flows

## Context

Building upon the foundation established in Plan 1, this plan implements the remaining authentication features. We'll need to add API endpoints to handle:
- Password reset requests
- Email verification with tokens
- Support for forgot password flow
- UI components for these flows

## Tasks

<task type="auto">
  <name>Implement Password Reset Request Endpoint</name>
  <files>src/app/api/auth/forgot-password/route.ts</files>
  <action>
    Implement the POST endpoint for initiating password reset:
    - Add validation for required email field
    - Look up user by email in database using Prisma
    - Generate a secure password reset token with expiration (e.g., 1 hour)
    - Store the token and expiration in the user record
    - Send password reset email with link containing token
    - Return appropriate response regardless of whether user exists (prevents enumeration attacks)
    
    The implementation should:
    - Use secure random token generation for password reset
    - Set appropriate expiration time (e.g., 1 hour)
    - Send email using configured email service (details in infrastructure)
    - Not reveal if email exists in system to prevent enumeration
  </action>
  <verify>Run `curl -X POST http://localhost:3001/api/auth/forgot-password -H "Content-Type: application/json" -d '{"email":"test@example.com"}'` and verify behavior</verify>
  <done>User can request password reset and receive confirmation without revealing account existence</done>
</task>

<task type="auto">
  <name>Implement Password Reset Confirmation Endpoint</name>
  <files>src/app/api/auth/reset-password/route.ts</files>
  <action>
    Implement the POST endpoint for completing password reset:
    - Validate the presence of email and token parameters
    - Look up user by email in database using Prisma
    - Verify that the reset token matches and hasn't expired
    - Hash the new password using bcryptjs with salt rounds >= 10
    - Update the user's password and clear the reset token
    - Return success message to indicate password reset completion
    
    The implementation should:
    - Validate token expiration before allowing reset
    - Ensure token matches exactly stored value
    - Clear the reset token after successful use
    - Return appropriate error responses for invalid or expired tokens
    - Use bcryptjs for password hashing
  </action>
  <verify>Run `curl -X POST http://localhost:3001/api/auth/reset-password -H "Content-Type: application/json" -d '{"email":"test@example.com","token":"reset-token","password":"newpassword"}'` and verify behavior</verify>
  <done>User can complete password reset with valid token and receive confirmation</done>
</task>

<task type="auto">
  <name>Implement Email Verification Endpoint</name>
  <files>src/app/api/auth/verify-email/route.ts</files>
  <action>
    Implement the GET endpoint for email verification:
    - Extract token from query parameters
    - Look up user by email verification token in database using Prisma
    - Verify that token hasn't expired
    - Update user's verifiedAt field to current timestamp
    - Clear the verification token
    - Redirect to appropriate page (login or dashboard) with success message
    
    The implementation should:
    - Use query parameters for token (as GET requests are used for verification)
    - Validate token before allowing verification
    - Set verification timestamp upon successful verification
    - Clear token from database after verification
    - Handle invalid/missing/expired tokens gracefully
  </action>
  <verify>Visit `http://localhost:3001/api/auth/verify-email?token=verification-token` and verify behavior</verify>
  <done>User can verify email address with valid token and receive confirmation</done>
</task>

<task type="auto">
  <name>Create Forgot Password Page</name>
  <files>src/app/auth/forgot-password/page.tsx</files>
  <action>
    Create a dedicated page for the forgot password flow:
    - Add form for entering email address
    - Display appropriate success/error messages
    - Implement form submission handler calling /api/auth/forgot-password
    - Add loading states during submission
    - Include clear user instructions and navigation back to login
    
    The page should:
    - Be responsive and accessible
    - Provide clear feedback on submission
    - Be styled consistently with the rest of the application
    - Have a link back to login page
  </action>
  <verify>Visit http://localhost:3001/auth/forgot-password and verify form renders correctly</verify>
  <done>Forgot password page is accessible, visually consistent, and functional</done>
</task>

<task type="auto">
  <name>Create Reset Password Page</name>
  <files>src/app/auth/reset-password/page.tsx</files>
  <action>
    Create a dedicated page for password reset:
    - Accept token from URL query parameters
    - Add form for entering new password
    - Implement form submission handler calling /api/auth/reset-password
    - Display appropriate success/error messages
    - Add loading states during submission
    - Include clear user instructions and navigation back to login
    
    The page should:
    - Be responsive and accessible
    - Handle invalid or expired tokens gracefully
    - Provide clear feedback on submission
    - Be styled consistently with the rest of the application
    - Have a link back to login page
  </action>
  <verify>Visit http://localhost:3001/auth/reset-password?token=test-token and verify form renders correctly</verify>
  <done>Password reset page is accessible, visually consistent, and functional</done>
</task>

<task type="auto">
  <name>Create Email Verification Page</name>
  <files>src/app/auth/verify-email/page.tsx</files>
  <action>
    Create a dedicated page for email verification:
    - Accept token from URL query parameters
    - Call the verification endpoint (/api/auth/verify-email)
    - Display appropriate success/error messages
    - Include user instructions and navigation back to login
    - Redirect to login or dashboard after successful verification
    
    The page should:
    - Be responsive and accessible
    - Handle verification process automatically
    - Provide clear feedback on verification status
    - Be styled consistently with the rest of the application
  </action>
  <verify>Visit http://localhost:3001/auth/verify-email?token=test-token and verify behavior</verify>
  <done>Email verification page is accessible, visually consistent, and functional</done>
</task>

<verification>
- All authentication API endpoints for password reset and email verification are functional
- Users can request password reset via email
- Users can reset their password with token
- Users can verify their email address with token
- Dedicated pages display properly for all authentication flows
</verification>

<success_criteria>
- User receives and can verify email address after signup
- User can reset password via email link
- User can access email verification page after signup
</success_criteria>

<output>
After completion, create `.planning/phases/01-setup-and-authentication/01-02-SUMMARY.md`
</output>