Use Case 009: Password Reset and Recovery

Overview

Description

This use case describes the complete process for users to reset their forgotten passwords and recover access to their accounts. The system provides a secure, time-limited password reset mechanism that includes email verification, token validation, password complexity enforcement, and password history checking to prevent reuse. The process also supports admin-initiated password resets and includes security measures such as rate limiting and abuse detection.

Actors

Preconditions

1. Application Manager is running and accessible
2. Email service (SMTP or AWS SES) is configured and operational
3. User account exists and is not locked or deleted
4. Password reset token expiration time is configured (default: 1 hour)
5. Password complexity requirements are defined
6. Password history tracking is enabled (last 5 passwords)
7. Rate limiting rules are configured

Postconditions

Success Postconditions

1. User's password is updated in the Identity database
2. All existing user sessions are invalidated (forced logout)
3. Password reset token is marked as used and invalidated
4. Password history is updated with new hashed password
5. Confirmation email sent to user
6. User can authenticate with new password
7. Activity logged in audit trail with timestamp and IP address

Failure Postconditions

1. Password not changed if validation fails
2. Invalid or expired tokens logged as security events
3. Rate limit violations logged and monitored
4. Multiple failed attempts trigger account security review
5. User notified of security events via email

Triggers

• User clicks "Forgot Password" link on login page
• User requests password reset via API
• Administrator initiates password reset for user
• User's account is flagged for mandatory password change
• Security system detects suspicious activity requiring password reset

Basic Flow (Happy Path)

sequenceDiagram
    actor User
    participant Web as Web UI
    participant API as Application Manager API
    participant DB as Identity Database
    participant Email as Email Service
    participant Cache as Token Cache

    User->>Web: Click "Forgot Password"
    Web->>User: Display password reset request form
    
    User->>Web: Enter email address
    Web->>API: POST /api/v1/auth/password-reset/request
    
    API->>DB: Find user by email
    DB->>API: User found
    
    API->>API: Check rate limits (email)
    API->>API: Generate secure reset token (GUID)
    API->>API: Set token expiration (now + 1 hour)
    
    API->>DB: Store PasswordResetToken record
    DB->>API: Token saved
    
    API->>Cache: Store token in cache (1 hour TTL)
    Cache->>API: Cached
    
    API->>Email: Send password reset email with token link
    Email->>User: Reset email delivered
    
    API->>Web: 200 OK (generic success message)
    Web->>User: "If account exists, reset email sent"
    
    Note over User,Email: User checks email
    
    User->>Email: Click reset link
    Email->>Web: GET /reset-password?token=xyz
    Web->>API: GET /api/v1/auth/password-reset/validate-token?token=xyz
    
    API->>Cache: Check token in cache
    alt Token in cache
        Cache->>API: Token valid
    else Token not in cache
        API->>DB: Query token from database
        DB->>API: Token found and valid
    end
    
    API->>Web: 200 OK (token valid)
    Web->>User: Display new password form
    
    User->>Web: Enter new password (2x for confirmation)
    Web->>API: POST /api/v1/auth/password-reset/complete
    
    API->>API: Validate password complexity
    API->>DB: Get user's password history
    DB->>API: Last 5 password hashes
    
    API->>API: Check new password against history
    API->>API: Hash new password (bcrypt)
    
    API->>DB: Update user password
    API->>DB: Add to password history
    API->>DB: Mark reset token as used
    API->>DB: Invalidate all user sessions
    
    DB->>API: Password updated successfully
    
    API->>Cache: Invalidate token from cache
    API->>Email: Send password change confirmation
    Email->>User: Confirmation email delivered
    
    API->>Web: 200 OK (password reset complete)
    Web->>User: "Password reset successful. Please login."
    Web->>User: Redirect to login page
    
    User->>Web: Login with new password
    Web->>API: POST /api/v1/auth/login
    API->>DB: Validate credentials
    DB->>API: Authentication successful
    API->>Web: Session created
    Web->>User: Redirect to dashboard

Detailed Steps

1. User Requests Password Reset

   • User navigates to login page
   • User clicks "Forgot Password" link
   • System displays password reset request form with email input

2. User Provides Email Address

   • User enters email address associated with account
   • User submits form
   • Web UI sends request to API

3. System Validates Request

   • Check email format is valid
   • Check rate limits for this email address (max 5 requests per hour)
   • Check rate limits for requesting IP (max 10 requests per hour)
   • If rate limited, return generic success message (don't reveal rate limit to attacker)

4. System Looks Up User

   • Query database for user by email address
   • If user not found, return generic success message (don't reveal user existence)
   • If user found, proceed to token generation

5. System Generates Reset Token

   • Generate cryptographically secure token (GUID/UUID v4)
   • Calculate expiration timestamp: now + 1 hour
   • Ensure token is unique (check against existing active tokens)

6. System Stores Reset Token

   • Create PasswordResetToken record with:
     • Token value (hashed for storage)
     • User ID
     • Expiration timestamp
     • Created timestamp
     • IsUsed = false
     • IP address of requester
   • Store in database
   • Cache token for fast validation (1 hour TTL)

7. System Sends Reset Email

   • Compose email with:
     • Password reset link containing token
     • Token expiration time (1 hour)
     • Security notice about not sharing the link
     • Link to contact support if not requested
   • Send via configured email provider
   • Log email delivery attempt

8. System Returns Success Response

   • Return 200 OK with generic message
   • Message: "If an account exists with that email, a password reset link has been sent."
   • This prevents email enumeration attacks

9. User Receives Reset Email

   • User checks email inbox (and spam folder if needed)
   • User reviews reset email and security notice
   • User clicks password reset link within 1 hour

10. System Validates Reset Token

    • Extract token from URL query parameter
    • Check token in cache for fast validation
    • If not in cache, query database
    • Verify token is not expired
    • Verify token is not already used
    • Verify token matches stored hash
    • If valid, display password reset form
    • If invalid/expired, display error and offer to request new token

11. User Enters New Password

    • User enters new password
    • User confirms new password (must match)
    • User submits form

12. System Validates New Password

    • Check password meets complexity requirements:
      • Minimum 12 characters
      • At least 1 uppercase letter
      • At least 1 lowercase letter
      • At least 1 number
      • At least 1 special character
    • Verify password confirmation matches
    • Retrieve user's password history (last 5 hashes)
    • Hash new password using bcrypt
    • Compare against password history
    • If password was used recently, reject with error message

13. System Updates Password

    • Hash new password using bcrypt (work factor 12)
    • Update user's PasswordHash field
    • Add new hash to password history
    • Mark reset token as used (IsUsed = true)
    • Set TokenUsedAt timestamp
    • Invalidate all existing user sessions (force logout all devices)
    • Clear any cached authentication data

14. System Sends Confirmation Email

    • Compose confirmation email:
      • Notify password was changed successfully
      • Include timestamp and IP address
      • Provide instructions if user didn't initiate change
      • Include link to contact support

• Send via email service

15. System Returns Success Response

    • Return 200 OK
    • Message: "Password reset successful. Please login with your new password."
    • Web UI redirects to login page after 3 seconds

16. User Logs In with New Password

    • User enters email and new password
    • System validates credentials
    • User gains access to account

Alternative Flows

Alt Flow 1: Reset Token Expired

sequenceDiagram
    actor User
    participant Web as Web UI
    participant API as Application Manager API
    participant DB as Identity Database

    User->>Web: Click expired reset link
    Web->>API: GET /api/v1/auth/password-reset/validate-token?token=xyz
    
    API->>DB: Query token
    DB->>API: Token found but expired
    
    API->>Web: 400 Bad Request (token expired)
    Web->>User: Display error message
    
    Web->>User: Show "Request New Reset Link" button
    User->>Web: Click "Request New Reset Link"
    Web->>User: Redirect to password reset request form
    
    Note over User,Web: User starts over (Basic Flow)

Steps:

1. User clicks reset link after 1 hour has passed
2. System validates token and detects expiration
3. System returns 400 Bad Request with error: "This password reset link has expired. Please request a new one."
4. Web UI displays error message with option to request new reset
5. User can click button to return to reset request form
6. Process restarts from Basic Flow step 1

Alt Flow 2: Invalid or Already Used Token

sequenceDiagram
    actor User
    participant Web as Web UI
    participant API as Application Manager API
    participant DB as Identity Database
    participant Security as Security Monitor

    User->>Web: Click reset link
    Web->>API: GET /api/v1/auth/password-reset/validate-token?token=invalid
    
    API->>DB: Query token
    
    alt Token not found
        DB->>API: No matching token
        API->>Security: Log potential security event
    else Token already used
        DB->>API: Token found, IsUsed=true
        API->>Security: Log duplicate use attempt
    end
    
    Security->>Security: Check for abuse patterns
    
    API->>Web: 400 Bad Request (invalid/used token)
    Web->>User: Display error message
    Web->>User: Offer to request new reset link

Steps:

1. User clicks invalid, tampered, or already-used token link
2. System attempts to validate token
3. System detects token is invalid or already used
4. System logs security event (potential attack)
5. System returns 400 Bad Request with generic error: "This password reset link is invalid or has already been used."
6. System checks for patterns of abuse from IP address
7. User is offered option to request new reset link
8. Security team is alerted if abuse pattern detected

Alt Flow 3: Password Fails Complexity Validation

flowchart TD
    A[User submits new password] --> B{Validate complexity}
    B -->|Too short| C[Return 400: Minimum 12 characters]
    B -->|No uppercase| D[Return 400: Must contain uppercase letter]
    B -->|No lowercase| E[Return 400: Must contain lowercase letter]
    B -->|No number| F[Return 400: Must contain number]
    B -->|No special char| G[Return 400: Must contain special character]
    B -->|Same as username| H[Return 400: Cannot contain username]
    B -->|Common password| I[Return 400: Password too common]
    B -->|Passwords don't match| J[Return 400: Passwords must match]
    B -->|Valid| K[Check password history]
    
    C --> L[User revises password]
    D --> L
    E --> L
    F --> L
    G --> L
    H --> L
    I --> L
    J --> L
    L --> A
    
    K --> M{In recent history?}
    M -->|Yes| N[Return 400: Cannot reuse recent password]
    M -->|No| O[Proceed with password update]
    N --> L

Steps:

1. User submits new password during Basic Flow step 11
2. System validates password complexity during step 12
3. System identifies specific validation failure
4. System returns 400 Bad Request with descriptive error
5. Web UI displays error message with password requirements
6. User corrects password and resubmits
7. Process continues from step 11

Alt Flow 4: Password in History (Reuse Prevention)

sequenceDiagram
    actor User
    participant API as Application Manager API
    participant DB as Identity Database

    User->>API: POST /api/v1/auth/password-reset/complete (new password)
    
    API->>API: Validate password complexity ✓
    API->>DB: Get user's password history
    DB->>API: Return last 5 password hashes
    
    API->>API: Hash new password with bcrypt
    API->>API: Compare against history hashes
    
    loop For each historical hash
        API->>API: bcrypt.compare(newPassword, historicalHash)
        alt Match found
            API->>API: Password reuse detected!
        end
    end
    
    API->>User: 400 Bad Request
    Note over User,API: "Password was recently used.<br/>Choose a different password."
    
    User->>API: Submit different password
    API->>API: Check against history again
    API->>User: Password accepted ✓

Steps:

1. User submits new password that passes complexity validation
2. System retrieves user's last 5 password hashes from database
3. System hashes the new password using bcrypt
4. System compares new hash against each historical hash using bcrypt.compare()
5. If match found, system rejects password
6. System returns 400 Bad Request: "This password was recently used. Please choose a different password."
7. User enters different password
8. System validates again and proceeds if unique

Alt Flow 5: Rate Limiting Exceeded

sequenceDiagram
    actor User
    participant API as Application Manager API
    participant Cache as Rate Limit Cache
    participant Security as Security Monitor

    User->>API: POST /api/v1/auth/password-reset/request (6th attempt in 1 hour)
    
    API->>Cache: Check rate limit for email
    Cache->>API: 5 requests already made in last hour
    
    API->>API: Rate limit exceeded
    API->>Security: Log rate limit violation
    Security->>Security: Check for attack patterns
    
    alt Suspicious pattern detected
        Security->>Security: Flag IP address for review
        Security->>Security: Send alert to security team
    end
    
    API->>User: 200 OK (generic success message)
    Note over User,API: Don't reveal rate limiting<br/>to prevent information disclosure
    
    Note over Cache: Reset counter after 1 hour

Steps:

1. User (or attacker) makes 6th password reset request within 1 hour
2. System checks rate limit counter in cache
3. System detects rate limit exceeded
4. System logs security event with IP address and email
5. System still returns 200 OK with generic success message (prevents revealing rate limit)
6. No email is actually sent
7. Security monitor checks for attack patterns
8. If suspicious, IP address is flagged and admin is alerted
9. User must wait 1 hour before next valid request

Alt Flow 6: Admin-Initiated Password Reset

sequenceDiagram
    actor Admin
    participant AdminUI as Admin Panel
    participant API as Application Manager API
    participant DB as Identity Database
    participant Email as Email Service
    actor User

    Admin->>AdminUI: Search for user account
    AdminUI->>API: GET /api/v1/admin/users?email=user@example.com
    API->>DB: Query user
    DB->>API: User found
    API->>AdminUI: Display user details
    
    Admin->>AdminUI: Click "Reset User Password"
    AdminUI->>Admin: Confirm action dialog
    Admin->>AdminUI: Confirm reset
    
    AdminUI->>API: POST /api/v1/admin/users/{userId}/password-reset
    
    API->>API: Verify admin permissions
    API->>API: Generate reset token
    API->>DB: Store reset token
    API->>DB: Set RequirePasswordChange flag
    
    alt Send reset email
        API->>Email: Send admin-initiated reset email
        Email->>User: Reset email delivered
    else Generate temporary password
        API->>API: Generate temporary password
        API->>DB: Update user password (temporary)
        API->>AdminUI: Return temporary password
        AdminUI->>Admin: Display temporary password
        Admin->>User: Provide temporary password via secure channel
    end
    
    API->>DB: Log admin action in audit trail
    API->>AdminUI: 200 OK (reset initiated)
    AdminUI->>Admin: Display success confirmation
    
    Note over User: User must change password on next login

Steps:

1. Administrator logs into admin panel
2. Administrator searches for user by email
3. System displays user account details
4. Administrator clicks "Reset User Password" button
5. System prompts for confirmation and reset method
6. Administrator selects method:
   • Option A: Send reset email (preferred)
   • Option B: Generate temporary password
7. If reset email:
   • System generates reset token (same as user-initiated)
   • Email sent to user with special note about admin reset
   • User follows normal reset process
8. If temporary password:
   • System generates strong temporary password
   • System updates user's password (marked as temporary)
   • System sets RequirePasswordChange = true
   • Temporary password displayed to admin once
   • Admin provides password to user through secure channel
   • User must change password on next login
9. System logs admin action with timestamp, admin ID, and reason
10. User receives notification of password reset

Alt Flow 7: Account Locked Due to Security

sequenceDiagram
    actor User
    participant API as Application Manager API
    participant DB as Identity Database
    participant Security as Security Monitor

    User->>API: POST /api/v1/auth/password-reset/request
    
    API->>DB: Find user by email
    DB->>API: User found
    
    API->>DB: Check account status
    DB->>API: Account locked (IsLocked=true)
    
    API->>Security: Log reset attempt for locked account
    Security->>Security: Evaluate security context
    
    API->>User: 200 OK (generic message)
    Note over User,API: Don't reveal account is locked
    
    Note over User: No email sent
    
    Security->>Security: Alert security team if suspicious

Steps:

1. User requests password reset for locked account
2. System finds user record but detects IsLocked = true
3. System logs security event (reset attempt on locked account)
4. System returns generic success message (don't reveal account status)
5. No email is sent to user
6. Security team is notified of locked account access attempt
7. User must contact support to unlock account
8. Support verifies identity before unlocking

Business Rules

Data Requirements

PasswordResetToken Schema

{
  "Id": "uuid-v4",
  "UserId": "uuid-v4 (foreign key to Users table)",
  "TokenHash": "string (SHA-256 hash of token)",
  "ExpiresAt": "datetime (UTC, created + 1 hour)",
  "CreatedAt": "datetime (UTC)",
  "IsUsed": "boolean (default: false)",
  "UsedAt": "datetime (UTC, nullable)",
  "RequestIpAddress": "string (IPv4 or IPv6)",
  "UseIpAddress": "string (IPv4 or IPv6, nullable)",
  "UserAgent": "string (optional, browser/device info)"
}

User Password Fields (Updated)

{
  "UserId": "uuid-v4",
  "PasswordHash": "string (bcrypt hash, work factor 12)",
  "PasswordChangedAt": "datetime (UTC)",
  "RequirePasswordChange": "boolean (default: false)",
  "FailedPasswordResetAttempts": "integer (default: 0)",
  "LastPasswordResetRequestAt": "datetime (UTC, nullable)",
  "IsLocked": "boolean (default: false)",
  "LockedAt": "datetime (UTC, nullable)",
  "LockReason": "string (nullable)"
}

PasswordHistory Schema

{
  "Id": "uuid-v4",
  "UserId": "uuid-v4 (foreign key)",
  "PasswordHash": "string (bcrypt hash)",
  "CreatedAt": "datetime (UTC)",
  "ChangedBy": "string (enum: User, Admin, System)"
}

Rate Limit Cache Entry

{
  "Key": "password-reset:{email-or-ip}",
  "RequestCount": "integer",
  "WindowStart": "datetime (UTC)",
  "ExpiresAt": "datetime (UTC, windowStart + 1 hour)"
}

User Interface

Password Reset Request Form

┌─────────────────────────────────────────────────────┐
│  Forgot Your Password?                              │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Enter your email address and we'll send you a     │
│  link to reset your password.                      │
│                                                     │
│  Email Address                                      │
│  ┌─────────────────────────────────────────────┐   │
│  │ your.email@example.com                      │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  ┌─────────────────────┐                           │
│  │  Send Reset Link     │                          │
│  └─────────────────────┘                           │
│                                                     │
│  [← Back to Login]                                  │
│                                                     │
└─────────────────────────────────────────────────────┘

Reset Email Sent Confirmation

┌─────────────────────────────────────────────────────┐
│  ✉️  Check Your Email                               │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  If an account exists with that email address,     │
│  we've sent a password reset link.                 │
│                                                     │
│  📧 Check your inbox for an email from:             │
│     noreply@riptide.example.com                    │
│                                                     │
│  ⏰ The reset link expires in 1 hour                │
│                                                     │
│  Didn't receive the email?                          │
│  • Check your spam/junk folder                      │
│  • Wait a few minutes and check again               │
│  • Make sure you entered the correct email          │
│                                                     │
│  [Request Another Reset Link]                       │
│                                                     │
│  [← Back to Login]                                  │
│                                                     │
└─────────────────────────────────────────────────────┘

New Password Entry Form

┌─────────────────────────────────────────────────────┐
│  Reset Your Password                                │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Create a strong password for your account.        │
│                                                     │
│  New Password                                       │
│  ┌─────────────────────────────────────────────┐   │
│  │ ••••••••••••••••                            │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  Password Strength: [████████░░] Strong            │
│                                                     │
│  Confirm New Password                               │
│  ┌─────────────────────────────────────────────┐   │
│  │ ••••••••••••••••                            │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  ✓ At least 12 characters                          │
│  ✓ Contains uppercase letter                       │
│  ✓ Contains lowercase letter                       │
│  ✓ Contains number                                 │
│  ✓ Contains special character                      │
│  ✗ Not recently used                               │
│                                                     │
│  ┌─────────────────────┐                           │
│  │  Reset Password      │                          │
│  └─────────────────────┘                           │
│                                                     │
│  [Cancel]                                           │
│                                                     │
└─────────────────────────────────────────────────────┘

Password Reset Success

┌─────────────────────────────────────────────────────┐
│  ✅ Password Reset Successful!                      │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Your password has been changed successfully.      │
│                                                     │
│  🔒 For security, all devices have been logged out. │
│                                                     │
│  You can now login with your new password.         │
│                                                     │
│  ┌─────────────────────┐                           │
│  │   Go to Login        │                          │
│  └─────────────────────┘                           │
│                                                     │
│  Redirecting in 3 seconds...                       │
│                                                     │
└─────────────────────────────────────────────────────┘

Token Expired Error

┌─────────────────────────────────────────────────────┐
│  ⚠️  Reset Link Expired                             │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  This password reset link has expired.             │
│                                                     │
│  ⏰ Reset links are valid for 1 hour only           │
│                                                     │
│  For security reasons, you'll need to request      │
│  a new password reset link.                        │
│                                                     │
│  ┌─────────────────────────┐                       │
│  │  Request New Reset Link  │                      │
│  └─────────────────────────┘                       │
│                                                     │
│  [← Back to Login]                                  │
│                                                     │
└─────────────────────────────────────────────────────┘

Admin Password Reset Panel

┌─────────────────────────────────────────────────────┐
│  Admin: Reset User Password                        │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  User: john.doe@example.com                        │
│  User ID: 550e8400-e29b-41d4-a716-446655440000     │
│  Status: Active                                     │
│                                                     │
│  Reset Method:                                      │
│  ○ Send password reset email (Recommended)         │
│  ○ Generate temporary password                     │
│                                                     │
│  Reason for Reset:                                  │
│  ┌─────────────────────────────────────────────┐   │
│  │ User requested password reset via support   │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  Options:                                           │
│  ☑ Require password change on next login           │
│  ☑ Invalidate all existing sessions                │
│  ☐ Send notification email to user                 │
│                                                     │
│  ⚠️  This action will be logged in the audit trail │
│                                                     │
│  ┌─────────────────────┐  [Cancel]                 │
│  │  Reset Password      │                          │
│  └─────────────────────┘                           │
│                                                     │
└─────────────────────────────────────────────────────┘

Email Templates

Password Reset Request Email

Subject: Reset Your Riptide Password

From: Riptide Support <noreply@riptide.example.com>
To: {{userEmail}}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Password Reset Request

Hello {{userName}},

We received a request to reset the password for your Riptide account.

To reset your password, click the link below:

┌─────────────────────────────────────────────────────┐
│  RESET MY PASSWORD                                  │
│  {{resetUrl}}?token={{resetToken}}                  │
└─────────────────────────────────────────────────────┘

⏰ This link expires in 1 hour (at {{expirationTime}})

🔒 Security Tips:
• Never share this link with anyone
• We will never ask for your password via email
• If you didn't request this reset, please ignore this email

If the button doesn't work, copy and paste this URL into your browser:
{{resetUrl}}?token={{resetToken}}

Need Help?
If you didn't request this password reset or need assistance,
please contact our support team:
📧 support@riptide.example.com
📞 1-800-RIPTIDE

Best regards,
The Riptide Team

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This is an automated message. Please do not reply to this email.

Request Details:
• Time: {{requestTime}} UTC
• IP Address: {{requestIp}}
• Browser: {{userAgent}}

Password Reset Confirmation Email

Subject: Your Riptide Password Was Changed

From: Riptide Security <security@riptide.example.com>
To: {{userEmail}}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Password Changed Successfully

Hello {{userName}},

This email confirms that your Riptide account password was changed 
successfully.

Change Details:
• Time: {{changeTime}} UTC
• IP Address: {{changeIp}}
• Location: {{geoLocation}}
• Device: {{deviceInfo}}

🔒 All existing sessions have been logged out for security.

⚠️  DIDN'T MAKE THIS CHANGE?

If you did not authorize this password change, your account may 
have been compromised. Take these steps immediately:

1. Click here to secure your account:
   {{securityUrl}}

2. Contact our security team:
   📧 security@riptide.example.com
   📞 1-800-RIPTIDE (24/7)

Security Recommendations:
✓ Use a unique password for Riptide
✓ Enable two-factor authentication
✓ Regularly review account activity
✓ Never share your password with anyone

Best regards,
The Riptide Security Team

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This is an automated security notification. Please do not reply.

Admin-Initiated Reset Email

Subject: Administrator Reset Your Riptide Password

From: Riptide Admin <admin@riptide.example.com>
To: {{userEmail}}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Admin Password Reset

Hello {{userName}},

A system administrator has initiated a password reset for your 
Riptide account.

Reason: {{resetReason}}

To set your new password, click the link below:

┌─────────────────────────────────────────────────────┐
│  RESET MY PASSWORD                                  │
│  {{resetUrl}}?token={{resetToken}}                  │
└─────────────────────────────────────────────────────┘

⏰ This link expires in 1 hour (at {{expirationTime}})

🔒 For security, all existing sessions have been logged out.

Admin Details:
• Admin: {{adminName}} ({{adminEmail}})
• Time: {{resetTime}} UTC
• Ticket: {{ticketNumber}}

If you have questions about this password reset, please contact
the administrator or our support team.

📧 support@riptide.example.com
📞 1-800-RIPTIDE

Best regards,
The Riptide Team

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Request ID: {{requestId}}

API Endpoints

Request Password Reset

Endpoint: POST /api/v1/auth/password-reset/request

Authentication: None (public endpoint)

Rate Limiting: 5 requests per email per hour, 10 requests per IP per hour

Request Body:

{
  "email": "user@example.com"
}

Success Response: 200 OK

{
  "message": "If an account exists with that email, a password reset link has been sent.",
  "requestId": "req-12345"
}

Notes:

• Always returns 200 OK even if email not found (prevents enumeration)
• No details about whether email exists in system
• No indication if rate limit was hit

Error Response: 400 Bad Request (invalid input only)

{
  "error": "ValidationError",
  "message": "Invalid email format",
  "field": "email"
}

Validate Reset Token

Endpoint: GET /api/v1/auth/password-reset/validate-token

Authentication: None (public endpoint)

Query Parameters:

• token (required): The reset token from email link

Success Response: 200 OK

{
  "valid": true,
  "expiresAt": "2026-01-30T12:30:00Z",
  "timeRemaining": "45 minutes"
}

Error Responses:

400 Bad Request - Token expired

{
  "error": "TokenExpired",
  "message": "This password reset link has expired. Please request a new one.",
  "valid": false
}

400 Bad Request - Token invalid or used

{
  "error": "InvalidToken",
  "message": "This password reset link is invalid or has already been used.",
  "valid": false
}

Complete Password Reset

Endpoint: POST /api/v1/auth/password-reset/complete

Authentication: None (token provides authentication)

Request Body:

{
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "newPassword": "MySecureP@ssw0rd2026",
  "confirmPassword": "MySecureP@ssw0rd2026"
}

Success Response: 200 OK

{
  "success": true,
  "message": "Password reset successful. You can now login with your new password.",
  "sessionsInvalidated": 3
}

Error Responses:

400 Bad Request - Validation error

{
  "error": "ValidationError",
  "message": "Password does not meet complexity requirements",
  "errors": {
    "newPassword": [
      "Password must be at least 12 characters",
      "Password must contain at least one special character"
    ]
  }
}

400 Bad Request - Password confirmation mismatch

{
  "error": "ValidationError",
  "message": "Passwords do not match",
  "field": "confirmPassword"
}

400 Bad Request - Password in history

{
  "error": "PasswordReuseError",
  "message": "This password was recently used. Please choose a different password.",
  "hint": "You cannot reuse any of your last 5 passwords"
}

400 Bad Request - Token expired or invalid

{
  "error": "InvalidToken",
  "message": "This password reset link is invalid or has expired."
}

Admin: Initiate User Password Reset

Endpoint: POST /api/v1/admin/users/{userId}/password-reset

Authentication: Required (Admin role)

Authorization: AdminRole required

Path Parameters:

• userId: UUID of user to reset password for

Request Body:

{
  "method": "email",
  "reason": "User requested password reset via support ticket #12345",
  "requirePasswordChange": true,
  "invalidateSessions": true,
  "sendNotification": true
}

Method Options:

• email: Send password reset email (preferred)
• temporary: Generate temporary password

Success Response: 200 OK

For method: email:

{
  "success": true,
  "method": "email",
  "message": "Password reset email sent to user",
  "emailSentTo": "user@example.com",
  "resetTokenExpiresAt": "2026-01-30T12:30:00Z",
  "auditLogId": "audit-550e8400"
}

For method: temporary:

{
  "success": true,
  "method": "temporary",
  "message": "Temporary password generated",
  "temporaryPassword": "Temp-P@ssw0rd-2026-XyZ",
  "requirePasswordChange": true,
  "note": "This password is shown once. User must change on next login.",
  "auditLogId": "audit-550e8401"
}

Error Responses:

403 Forbidden - Insufficient permissions

{
  "error": "Forbidden",
  "message": "Admin role required to reset user passwords"
}

404 Not Found - User not found

{
  "error": "NotFound",
  "message": "User not found",
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

Get Password Reset History (Admin)

Endpoint: GET /api/v1/admin/users/{userId}/password-reset-history

Authentication: Required (Admin role)

Authorization: AdminRole required

Query Parameters:

• limit (optional): Max records to return (default: 50, max: 100)
• offset (optional): Pagination offset (default: 0)

Success Response: 200 OK

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "totalResets": 5,
  "resets": [
    {
      "id": "reset-001",
      "requestedAt": "2026-01-30T10:00:00Z",
      "requestIpAddress": "192.168.1.100",
      "completedAt": "2026-01-30T10:15:00Z",
      "useIpAddress": "192.168.1.100",
      "method": "user_initiated",
      "status": "completed"
    },
    {
      "id": "reset-002",
      "requestedAt": "2026-01-25T14:30:00Z",
      "requestIpAddress": "192.168.1.50",
      "completedAt": null,
      "method": "user_initiated",
      "status": "expired"
    },
    {
      "id": "reset-003",
      "requestedAt": "2026-01-20T09:00:00Z",
      "requestIpAddress": "10.0.0.1",
      "completedAt": "2026-01-20T09:05:00Z",
      "method": "admin_initiated",
      "adminId": "admin-123",
      "adminEmail": "admin@riptide.example.com",
      "reason": "User locked out",
      "status": "completed"
    }
  ]
}

Performance Requirements

Security Considerations

Token Security

• Reset tokens must be cryptographically secure (GUID/UUID v4 using CSPRNG)
• Tokens stored as SHA-256 hashes in database (never plain text)
• Tokens are single-use only (marked as used after successful reset)
• Tokens expire after 1 hour (configurable, minimum 15 minutes, maximum 24 hours)
• Token generation includes uniqueness check to prevent collisions
• Tokens invalidated immediately when used, even if validation fails afterward
• Cache tokens with short TTL for performance (1 hour max)

Password Security

• Passwords hashed using bcrypt with work factor 12 (minimum 10, recommended 12-14)
• Password history maintained for last 5 passwords (configurable 3-10)
• Password history uses same hash algorithm (bcrypt) for comparison
• Password complexity requirements enforced on client and server
• Common/breached password check against known password databases (optional)
• Password strength meter displayed in real-time on UI

Rate Limiting

• Per-email rate limit: 5 requests per hour (prevents brute force against specific account)
• Per-IP rate limit: 10 requests per hour (prevents distributed attacks)
• Global rate limit: 1000 requests per minute (prevents DoS)
• Rate limit counters stored in Redis/cache for fast access
• Rate limit violations logged for security monitoring
• Progressive delays: First violation = no delay, subsequent = exponential backoff

Session Management

• All user sessions invalidated immediately upon password change
• Session tokens stored with password version/timestamp
• Old sessions rejected even if technically valid tokens
• Force logout across all devices (mobile, web, API clients)
• Clear any cached authentication data

Information Disclosure Prevention

• Generic success messages (don't reveal if email exists)
• Same response time whether email exists or not
• Don't reveal account locked status
• Don't reveal rate limiting to potential attackers
• Error messages don't leak sensitive information

Email Security

• Use TLS/SSL for SMTP connections
• SPF, DKIM, and DMARC configured for email authentication
• Reset links use HTTPS only
• Include security warnings in all emails
• Email content doesn't include sensitive data
• Unsubscribe link included for compliance

Audit Logging

• Log all password reset requests (email, IP, timestamp, user-agent)
• Log all token validations (success and failure)
• Log all password changes (timestamp, IP, method)
• Log all admin-initiated resets (admin ID, reason, method)
• Log all rate limit violations
• Log all token expiration and reuse attempts
• Retain logs for minimum 90 days (configurable by compliance requirements)

Abuse Detection

• Monitor for patterns:
  • Multiple resets from single IP
  • Multiple resets for single email
  • Token validation without use
  • Expired token access patterns
  • Abnormal geographic access patterns
• Automatic alerts for suspicious activity
• Account lockout after 10 failed reset attempts in 24 hours
• IP blocking for severe abuse patterns
• CAPTCHA challenge after multiple failed attempts (optional)

Admin Security

• Admin password resets require MFA verification
• Admin actions logged with full audit trail
• Temporary passwords are strongly generated (20+ chars, high entropy)
• Temporary passwords expire after first use or 24 hours
• Admin panel access restricted to specific IP ranges (optional)
• Admin actions require reason/justification

Testing Scenarios

Test Case 1: Successful Password Reset Flow

Given: Valid user account with email user@example.com
When: User requests reset, receives email, clicks link, enters valid new password
Then: Password updated, sessions invalidated, confirmation email sent
Verify:

• Reset token created in database with 1-hour expiration
• Email delivered with valid token link
• Token validation returns success
• New password passes all complexity checks
• New password not in password history
• Old password hash added to history
• All user sessions deleted
• Confirmation email received
• User can login with new password
• Old password rejected

Test Case 2: Expired Token Handling

Given: Password reset token created more than 1 hour ago
When: User clicks reset link with expired token
Then: Token validation fails with expiration error
Verify:

• Token marked as expired in database
• Error message displayed: "Reset link has expired"
• Option to request new reset link shown
• Security event logged
• No password change allowed

Test Case 3: Token Reuse Prevention

Given: Password reset token already used successfully
When: User attempts to use same token again
Then: Token validation fails with "already used" error
Verify:

• Token marked as IsUsed = true in database
• UsedAt timestamp recorded
• Error message displayed
• Security event logged
• Password cannot be changed again

Test Case 4: Password Complexity Validation

Given: User on password reset form
When: User enters password that fails complexity requirements
Then: Specific validation errors displayed
Test Scenarios:

• Password too short (< 12 chars): "Minimum 12 characters required"
• No uppercase: "Must contain uppercase letter"
• No lowercase: "Must contain lowercase letter"
• No number: "Must contain number"
• No special character: "Must contain special character"
• Contains username: "Cannot contain username" Verify:
• Each validation rule tested independently
• Multiple violations shown together
• Password not updated
• User remains on form with errors

Test Case 5: Password History Check

Given: User with 5 passwords in history
When: User attempts to reuse any of last 5 passwords
Then: Password rejected with history error
Verify:

• New password hashed with bcrypt
• Compared against all 5 historical hashes using bcrypt.compare()
• Match detected correctly
• Error message: "Password recently used"
• Suggestion to choose different password
• Password not updated
• User can submit different password successfully

Test Case 6: Rate Limiting - Email Based

Given: User email user@example.com
When: User requests password reset 6 times in 1 hour
Then: 6th request silently rate limited
Verify:

• First 5 requests succeed and send emails
• 6th request returns success message (generic)
• No email sent for 6th request
• Rate limit counter incremented in cache
• Security event logged
• After 1 hour, user can request again

Test Case 7: Rate Limiting - IP Based

Given: IP address 192.168.1.100
When: 11 reset requests from same IP for different emails
Then: 11th request silently rate limited
Verify:

• First 10 requests processed normally
• 11th request returns success but doesn't process
• IP rate limit counter in cache
• Security monitor alerted
• Potential abuse flagged

Test Case 8: Invalid/Tampered Token

Given: User receives reset email
When: User modifies token in URL before clicking
Then: Token validation fails
Verify:

• Token not found in database
• Error: "Invalid or expired token"
• Security event logged
• Potential attack flagged
• User offered option to request new token

Test Case 9: Email Not Found (Enumeration Prevention)

Given: Email address not registered in system
When: User requests password reset for non-existent email
Then: Generic success message returned
Verify:

• Same response as successful request
• Same response time (no timing attack)
• No email sent
• No database record created
• Request logged for security monitoring

Test Case 10: Admin-Initiated Reset with Email

Given: Admin logged in with proper permissions
When: Admin initiates password reset for user via email method
Then: Reset email sent to user with admin context
Verify:

• Admin permissions validated
• Reset token generated
• Email sent to user
• Email indicates admin-initiated reset
• Reason included in email
• Admin action logged in audit trail
• User receives email and can reset password
• RequirePasswordChange flag set if selected

Test Case 11: Admin-Initiated Reset with Temporary Password

Given: Admin logged in with proper permissions
When: Admin generates temporary password for user
Then: Strong temporary password created and displayed once
Verify:

• Temporary password is strong (20+ chars, mixed case, numbers, symbols)
• Password displayed to admin in UI
• User's password updated in database
• RequirePasswordChange = true set
• All user sessions invalidated
• Temporary password works for login
• User forced to change password on next login
• Admin action logged

Test Case 12: Locked Account Reset Attempt

Given: User account with IsLocked = true
When: User requests password reset
Then: Generic success message, no email sent
Verify:

• Account lock status checked
• Generic success message returned
• No email sent to user
• Security event logged
• Security team notified
• User must contact support to unlock

Test Case 13: Password Reset During Active Session

Given: User currently logged in with active session
When: User completes password reset successfully
Then: All sessions invalidated including current one
Verify:

• Password updated
• All session records deleted or marked invalid
• User's current session terminated
• User redirected to login page
• User must login with new password
• Confirmation email sent

Test Case 14: Email Delivery Failure

Given: SMTP server unavailable
When: User requests password reset
Then: Error handled gracefully
Verify:

• Reset token created successfully
• Email send attempt fails
• Failure logged with details
• Generic success message still shown to user
• Admin notified of email failure
• User can request resend
• System retries email delivery (optional)

Test Case 15: Concurrent Password Reset Requests

Given: User submits multiple reset requests rapidly
When: Multiple requests processed concurrently
Then: All requests handled correctly
Verify:

• Each request gets unique token
• No token collisions
• Rate limiting applied correctly
• All requests logged
• Latest token is valid
• Previous tokens remain valid until expiration

Test Case 16: Security Questions (Alternative Flow)

Given: Security questions enabled for account
When: User requests password reset
Then: Security questions presented before reset
Verify:

• User must answer security questions
• Correct answers required to proceed
• Incorrect answers limit (3 attempts)
• Account locked after failed attempts
• Success allows password reset
• Failure logged and monitored

Test Case 17: Mobile Device Reset Flow

Given: User on mobile device
When: User completes password reset
Then: Mobile-optimized experience provided
Verify:

• Forms responsive and mobile-friendly
• Password visibility toggle works
• Password strength meter displays correctly
• Success/error messages readable
• Redirects work on mobile browsers
• Deep links work (if native app)

Test Case 18: Password Confirmation Mismatch

Given: User entering new password
When: Password and confirmation don't match
Then: Validation error displayed
Verify:

• Error shown immediately (client-side)
• Error confirmed on server-side
• Specific message: "Passwords do not match"
• User can correct without losing progress
• Password requirements still visible

Monitoring and Analytics

Key Metrics to Track

Volume Metrics:

• Password Reset Requests: Total requests per day/week/month
• Successful Resets: Completed password changes
• Failed Resets: Failed attempts by reason (expired, invalid, complexity)
• Admin-Initiated Resets: Count and method distribution

Performance Metrics:

• Request Processing Time: P50, P95, P99 latencies
• Token Validation Time: Cache hits vs misses
• Email Delivery Time: Time from request to delivery
• Password Update Time: Database transaction duration

Security Metrics:

• Rate Limit Violations: By email and by IP
• Token Reuse Attempts: Potential security events
• Expired Token Access: Users clicking old links
• Password Complexity Failures: Most common violations
• Password History Violations: Reuse attempts
• Suspicious Patterns: Multiple resets, geographic anomalies

User Experience Metrics:

• Time to Reset: From request to completion
• Email Open Rate: Percentage of reset emails opened
• Link Click Rate: Percentage who click reset link
• Completion Rate: Requests that result in successful reset
• Abandonment Points: Where users drop off in process
• Mobile vs Desktop: Device-specific success rates

Business Metrics:

• Support Tickets Related to Resets: Volume and resolution time
• Account Lockouts: Due to reset abuse
• Fraud Indicators: Suspicious reset patterns

Alerts and Thresholds

Critical Alerts (Immediate Action Required):

• Password reset success rate < 70% for 15 minutes
• Email delivery failure rate > 20% for 5 minutes
• Database errors during password update
• Rate limiting system failure
• Mass password reset attempts (> 100/minute from single IP)

Warning Alerts (Review Required):

• Password reset request spike (> 300% above baseline)
• Email delivery rate < 90% for 1 hour
• Token validation failure rate > 15%
• Password complexity failure rate > 40%
• Abandoned resets > 50% for 1 hour

Security Alerts (Investigation Required):

• 10+ rate limit violations from single IP in 1 hour
• 5+ token reuse attempts for single user
• 20+ password history violations in 1 hour
• Geographic anomalies (reset from unusual country)
• Admin reset spike (> 50 in 1 hour)
• Account lockouts due to reset abuse

Dashboards

Operations Dashboard:

• Real-time reset request volume (line chart)
• Success vs failure rate (pie chart)
• Average completion time (gauge)
• Email delivery status (success/failure/pending)
• Top failure reasons (bar chart)
• Geographic distribution (map)

Security Dashboard:

• Rate limit violations (time series)
• Suspicious activity alerts (list)
• Token reuse attempts (count)
• Account lockouts (count)
• Failed complexity checks (breakdown)
• Admin-initiated resets (audit trail)

User Experience Dashboard:

• Funnel visualization (request → email → reset → complete)
• Abandonment points (drop-off analysis)
• Average time per step
• Mobile vs desktop success rates
• Browser/device breakdown
• User feedback/satisfaction scores

Related Use Cases

• UC-001: Trial User Self-Registration and Access
• UC-002: User Login and Session Management
• UC-003: User Profile and Settings Management
• UC-004: Account Security and Two-Factor Authentication
• UC-005: Admin User Management
• UC-006: Email Verification and Notification
• UC-007: Account Lockout and Security Response
• UC-008: Audit Logging and Compliance Reporting
• UC-010: Security Questions and Identity Verification

Notes and Assumptions

1. Email as Primary Channel: Password resets rely entirely on email delivery; alternative channels (SMS, authenticator apps) not currently supported
2. Single Active Token: Only one reset token active per user at a time; new request invalidates previous token
3. Session Invalidation: All sessions forcibly terminated on password change for security
4. No Password Recovery: Old passwords cannot be recovered; only reset to new password
5. Rate Limiting Philosophy: Prefer silent rate limiting over explicit errors to avoid information disclosure
6. Token Entropy: UUIDs provide sufficient entropy (122 bits) for security without need for longer tokens
7. Password History Storage: Bcrypt hashes stored directly; no need for separate salt storage (bcrypt includes salt)
8. Cache Dependency: Redis or similar required for performant rate limiting; fallback to database acceptable but slower
9. Email Template Customization: Templates should be customizable per deployment for branding
10. Compliance: GDPR, CCPA, SOC2 considerations addressed through audit logging and data retention policies
11. MFA Integration: If 2FA enabled, password reset may require additional verification (future enhancement)
12. Password Strength Meter: Client-side library (e.g., zxcvbn) used for real-time feedback
13. Localization: Currently English-only; internationalization planned for future releases
14. Mobile App Deep Links: Reset links should support deep linking to native mobile apps
15. Admin Permissions: Password reset capability requires specific admin permission; not all admins have access

Revision History

Document Owner: Platform Security Team
Stakeholders: Product Management, Engineering, Security, Customer Success
Review Cycle: Quarterly or as needed for security updates