Password Reset

Overview Description

The password reset feature allows users to recover access to their accounts when they forget their passwords. It uses a secure token-based system where users request a reset link via email, then use the link to set a new password. The system integrates with Firebase Authentication for secure password management.

Activity Diagram

flowchart TD
    A[User requests password reset] --> B[Validate email address]
    B --> C{Email valid?}
    C -->|No| D[Return validation error]
    C -->|Yes| E[Check if user exists]
    
    E --> F{User found?}
    F -->|No| G[Return user not found error]
    F -->|Yes| H[Check user status]
    
    H --> I{User active?}
    I -->|No| J[Return inactive user error]
    I -->|Yes| K[Generate reset token]
    
    K --> L[Store token in database]
    L --> M[Send reset email]
    M --> N{Email sent?}
    
    N -->|Yes| O[Return success response]
    N -->|No| P[Return email error]
    
    O --> Q[User receives email]
    Q --> R[User clicks reset link]
    R --> S[Validate reset token]
    
    S --> T{Token valid?}
    T -->|No| U[Return invalid token error]
    T -->|Yes| V[Allow password change]
    
    V --> W[Update password in Firebase]
    W --> X[Clear reset token]
    X --> Y[Return success response]
    
    style A fill:#e1f5fe
    style O fill:#c8e6c9
    style Y fill:#c8e6c9
    style D fill:#ffcdd2
    style G fill:#ffcdd2
    style J fill:#ffcdd2
    style P fill:#ffcdd2
    style U fill:#ffcdd2

Sequence Diagram

Request Password Reset

sequenceDiagram
    participant Client
    participant ForgotController
    participant AuthService
    participant Database
    participant EmailService
    
    Client->>ForgotController: POST /api/v1/general/auth/forgot
    Note over Client,ForgotController: {email, url}
    
    ForgotController->>ForgotController: Validate request data
    ForgotController->>AuthService: sendResetPassEmail(email, url)
    
    AuthService->>Database: Find user by email
    Database-->>AuthService: User data
    
    AuthService->>AuthService: Check user status
    AuthService->>AuthService: Generate reset token
    
    AuthService->>Database: Store reset token
    Database-->>AuthService: Token stored
    
    AuthService->>EmailService: Send reset email
    EmailService-->>AuthService: Email sent
    
    AuthService-->>ForgotController: Reset email sent successfully
    
    ForgotController->>Client: 200 OK + success message

Reset Password with Token

sequenceDiagram
    participant Client
    participant ResetController
    participant AuthService
    participant Firebase
    participant Database
    
    Client->>ResetController: POST /api/v1/general/auth/reset
    Note over Client,ResetController: {token, password}
    
    ResetController->>ResetController: Validate request data
    ResetController->>AuthService: resetPassword(token, password)
    
    AuthService->>Database: Find reset token
    Database-->>AuthService: Token data
    
    AuthService->>AuthService: Validate token expiration
    AuthService->>Firebase: Update user password
    Firebase-->>AuthService: Password updated
    
    AuthService->>Database: Clear reset token
    Database-->>AuthService: Token cleared
    
    AuthService-->>ResetController: Password reset successful
    
    ResetController->>Client: 200 OK + success message

Steps

1. Request Validation: Validate email format and reset URL
2. User Lookup: Find user by email address
3. Status Check: Verify user account is active
4. Token Generation: Create secure reset token with expiration
5. Token Storage: Save token in password_resets table
6. Email Dispatch: Send password reset link via email
7. Token Validation: Verify token when user clicks reset link
8. Password Update: Update password in Firebase Authentication
9. Cleanup: Remove used reset token from database

Database Related Tables & Fields

erDiagram
    users {
        bigint id PK "Primary key"
        varchar name "User's full name"
        varchar email UK "User's email address"
        varchar uid "Firebase UID"
        varchar payment_provider_customer_id "Payment provider customer ID"
        tinyint status "User status (1: active, 0: inactive)"
        varchar remember_token "Laravel remember token"
        timestamp created_at "Creation timestamp"
        timestamp updated_at "Last update timestamp"
        timestamp deleted_at "Soft delete timestamp"
        boolean is_first_login "First login flag"
    }
    
    password_resets {
        varchar email PK "User's email address"
        varchar token "Reset token"
        timestamp created_at "Token creation timestamp"
    }
    
    users ||--o{ password_resets : "requests"

API Endpoints

Request Password Reset

• URL: POST /api/v1/general/auth/forgot
• Headers: Content-Type: application/json
• Body:

  {
    "email": "user@example.com",
    "url": "https://app.example.com/reset-password"
  }
  

Reset Password

• URL: POST /api/v1/general/auth/reset
• Headers: Content-Type: application/json
• Body:

  {
    "token": "reset_token_from_email",
    "password": "new_password"
  }
  

Response

Success Response (Forgot Password)

• Status: 200 OK
• Body:

  {
    "message": "Password reset link sent to your email"
  }
  

Success Response (Reset Password)

• Status: 200 OK
• Body:

  {
    "message": "Password reset successfully"
  }
  

Error Handling

Additional Notes

• Token Security: Reset tokens are cryptographically secure and time-limited
• Email Integration: Uses Laravel's built-in email system for delivery
• Firebase Integration: Password updates are synchronized with Firebase Authentication
• Rate Limiting: Password reset requests are limited to prevent abuse
• Token Expiration: Reset tokens expire after a configurable time period
• Password Validation: New passwords must meet security requirements
• Audit Trail: Password reset attempts are logged for security monitoring
• Multiple Attempts: Users can request multiple reset links if needed