Password Reset

1. What does this feature do? (High-Level Overview)

The Password Reset feature allows users to securely reset their password using Two-Factor Authentication verification. It works independently of whether the user has 2FA enabled for login, ensuring secure password recovery through SMS or Email verification.

2. Who is this for? (Roles & Permissions)

• All Users: Any registered user (employees or parents) who has forgotten their password.
• No authentication required for the reset process (public endpoints).
• Must have valid email or phone to receive verification codes.

3. Business Rules & Enforcements

• Rule 1: Password reset always requires 2FA verification, even if user doesn’t have 2FA enabled for login.
• Rule 2: Reset codes expire after 10 minutes (same as regular 2FA codes).
• Rule 3: Reset tokens expire after 15 minutes after code verification.
• Rule 4: Password must be at least 8 characters and confirmed.
• Rule 5: Users can choose SMS or Email verification method.
• Rule 6: Maximum 5 verification attempts per code.
• Rule 7: Development mode does NOT bypass password reset verification (always requires real codes).
• Rule 8: Account must be ACTIVE status to reset password.

4. How-To Guide (Step-by-Step)

Complete Password Reset Flow

Step 1: Navigate to Forgot Password

• Click “Forgot Password?” link on login page
• Redirects to /forgot-password

Step 2: Enter Email Address

Forgot Your Password?

Enter your email address and we'll help you reset your password.

Email Address: _______________

[Back to Login] [Continue]

Step 3: System Processing

1. Searches for user in Users table
2. Searches for user in Parents table (if not found in Users)
3. Checks account status (must be ACTIVE)
4. Determines available verification methods

Step 4: Method Selection Response

Step 5: Select Verification Method

Verify Your Identity

To reset your password, we need to verify your identity.

Choose how you want to receive your verification code:

○ Text Message (SMS)
  Send code to 55****67

○ Email
  Send code to u***@example.com

[Back] [Send Code]

Step 6: Send Verification Code

Important: context: "password_reset" allows sending codes even if user doesn’t have 2FA enabled.

Step 7: Code Sent Confirmation

Step 8: Enter Verification Code

Redirects to /reset-password-verify

Enter Verification Code

We sent a 6-digit code to u***@example.com

Code: [_] [_] [_] [_] [_] [_]

Code expires in: 9:45

[Didn't receive code? Resend] [Back] [Verify]

Step 9: Code Verification

1. Finds user by email
2. Verifies code with PASSWORD_RESET context
3. Always verifies against stored hash (no development mode bypass)
4. Generates 15-minute reset token
5. Stores token in two_factor_code field (reused for reset token)
6. Marks as verified

Step 10: Reset Token Response

Step 11: Enter New Password

Redirects to /reset-password-change with reset_token in state

Create New Password

Please enter your new password.

New Password: ********
Confirm Password: ********

Password must be at least 8 characters.

[Back] [Change Password]

Step 12: Password Change Processing

1. Finds user by email
2. Verifies reset token matches stored hash
3. Checks token not expired (15 minutes from verification)
4. Checks two_factor_verified flag is true
5. Updates password
6. Clears all 2FA fields (including reset token)

Step 13: Success Response

{
  "message": "Password changed successfully. You can now login with your new password."
}

Step 14: Redirect to Login

Password Changed Successfully!

Your password has been updated. You can now log in with your new password.

[Go to Login]

---

6. What happens if…? (Edge Cases / FAQ)

• Q: What if I enter the wrong email address?

  • A: For security, the system doesn’t indicate whether the email exists or not. You’ll receive a generic “Please select a verification method” response even if the email doesn’t exist (to prevent email enumeration). However, you won’t receive a verification code.

• Q: Can I use password reset if I don’t have 2FA enabled?

  • A: Yes! Password reset uses 2FA verification regardless of whether you have 2FA enabled for login. This ensures password reset security for all users.

• Q: What happens if my verification code expires during password reset?

  • A: You’ll see “Verification code has expired” when submitting. Click “Resend Code” to receive a new one. The process restarts from code verification (you don’t need to re-enter your email).

• Q: How long is the reset token valid?

  • A: The reset token expires 15 minutes after code verification. If it expires, you must restart the entire process from “Forgot Password.”

• Q: Can I use development mode bypass for password reset?

  • A: No! Development mode only affects LOGIN context. Password reset always requires real verification codes, even in development. This prevents security vulnerabilities.

• Q: What happens to my 2FA settings after password reset?

  • A: All 2FA fields are cleared as a security measure. If you had 2FA enabled, you’ll need to re-enable it and generate new backup codes after logging in with your new password.

• Q: Can I reset password for inactive accounts?

  • A: No, only ACTIVE accounts can reset passwords. Accounts with BLACK_LIST or other inactive statuses will be rejected.

• Q: What if I fail all 5 verification attempts?

  • A: The verification code is cleared and you must request a new code. Your ability to reset password is not blocked - just request a new code and try again.

• Q: Can I use a backup code for password reset?

  • A: No, backup codes are only for login authentication. Password reset requires fresh verification via SMS or Email.

---

Security Features

Security Measures

No Email Enumeration:

• Same response whether email exists or not
• Prevents attackers from discovering valid emails

Rate Limiting:

• 20 code requests per hour per method
• Prevents abuse

Short Expiration:

• 10 minutes for verification codes
• 15 minutes for reset tokens
• Minimizes attack window

One-Time Use:

• Reset token cleared after password change
• Cannot reuse tokens

Password Requirements:

• Minimum 8 characters
• Must match confirmation
• Hashed with bcrypt

2FA Field Clearing:

• All 2FA fields cleared after reset
• Forces re-enablement if desired
• Prevents old codes from working

Audit Trail

Password resets are logged in:

• Laravel application logs
• Login sessions table (after successful login with new password)
• Activity logs (if enabled)

Error Messages

Generic errors prevent information leakage:

• “Invalid credentials” (email not found)
• “Verification code has expired” (don’t reveal email existence)
• “Invalid reset token” (don’t reveal token details)