# Login and Authentication

## Overview

This journey covers how users sign in to the Customer Portal, how the two-step login flow works (password followed by a one-time code), what happens when a password is forgotten, and how session timeouts are handled. The portal uses email-plus-password credentials with a mandatory OTP (one-time password) verification step for security.

## Portal Flow

### Signing In

1. Go to the Login page at `/auth/login`. The page is titled **"Welcome back"** with the subtitle "Sign in to your Assist Solutions account."
2. You will see a form with the following fields:
   - **Email Address** (required)
   - **Password** (required)
   - **Remember me** checkbox
3. Below the form, there are links:
   - **Forgot your password?** -- takes you to the password reset flow.
   - **Don't have an account? Get started** -- takes you to the signup flow.
   - **Existing customer? Transfer your account** -- also takes you to the signup/migration flow.
4. Enter your email and password, then click **Sign in**.

### OTP Verification (Second Step)

After entering valid credentials, the portal does not log you in immediately. Instead:

1. The page changes to show **"Check your email"** with a mail icon.
2. A message says: "We sent a verification code to [masked email]" (for example, `t***@example.com`).
3. A 6-digit OTP input field appears.
4. A countdown timer shows how long until the code expires (displayed as MM:SS).
5. Enter the 6-digit code. It auto-submits when you enter all 6 digits, or you can click **Verify and Sign In** manually.
6. Below the input, there is a **"Remember this device for 7 days"** checkbox. If checked, you will not need to enter an OTP again on this device for 7 days.
7. If the code expires, a message appears: "Code expired. Please go back and try again."
8. A **Back to login** link lets you return to the credentials step to start over.
9. A help message at the bottom says: "Didn't receive the code? Check your spam folder or go back to try again."

### After Successful Login

- Once the OTP is verified, you see a brief loading overlay saying **"Redirecting to dashboard..."** with the subtitle "Please wait while we load your account."
- You are redirected to your account dashboard at `/account`.
- If you originally tried to access a specific page before being redirected to login, you will be taken back to that page instead of the dashboard.

### Login Error Messages

- If you enter incorrect credentials, an error message appears on the form.
- If your account is locked or there is a server issue, an appropriate error message is shown.
- If you land on the login page after being logged out, a banner appears at the top explaining why:
  - **Session Expired** (yellow warning): "For your security, your session expired. Please sign in again to continue."
  - **Signed Out For Your Safety** (red error): "We detected a security change and signed you out. Please sign in again to verify your session."
  - **Signed Out** (blue info): "You have been signed out. Sign in again whenever you're ready."

### Forgot Password Flow

1. From the login page, click **Forgot your password?**
2. You land on the **"Forgot password"** page with the subtitle "Enter your email address and we'll send you a reset link."
3. Enter your email address and click **Send reset link**.
4. The system sends a password reset email to that address.
5. A **Back to login** link is available at the bottom.

### Reset Password Flow

1. Open the reset link from your email. This takes you to `/auth/reset-password?token=...`.
2. The page is titled **"Reset your password"** with the subtitle "Set a new password for your account."
3. You will see two fields:
   - **New password** (required)
   - **Confirm password** (required)
4. Enter and confirm your new password, then click **Update password**.
5. If the reset link is missing or expired, you see a message: "The password reset link is missing or has expired. Please request a new link to continue." A button lets you **Request new reset link**.
6. A **Back to login** link is available at the bottom.

### Session Behavior

The portal manages your login session automatically:

- **Automatic refresh**: The system checks your session every 4 minutes and refreshes it if it is about to expire. This happens silently in the background.
- **Tab focus refresh**: When you switch back to the portal tab after being away, the system checks and refreshes your session if needed.
- **Session timeout warning**: About 5 minutes before your session expires, a popup dialog appears with the title **"Session Expiring Soon"**. It shows how many minutes are left and offers two buttons:
  - **Extend Session** -- refreshes your session so you stay logged in.
  - **Logout Now** -- logs you out immediately.
- **Session expired**: If you do not respond to the warning and the session expires, you are automatically logged out and redirected to the login page with the "Session Expired" banner.

### Logging Out

- You can log out at any time from the account menu.
- After logging out, you are redirected to the login page with the "Signed Out" info banner.

## What Happens in WHMCS

Login and authentication are handled entirely by the Customer Portal. WHMCS is not involved in the login process.

- No records are created or updated in WHMCS when a user logs in, logs out, or resets their password.
- Portal passwords are stored separately from WHMCS passwords. Changing a portal password does not affect the user's WHMCS password (if they had one from before migration).

## What Happens in Salesforce

Login and authentication are handled entirely by the Customer Portal. Salesforce is not involved in the login process.

- No records are created or updated in Salesforce when a user logs in, logs out, or resets their password.

## Key Things to Verify

- **Happy path login**: Enter valid email and password, receive OTP, enter OTP, confirm you land on the dashboard.
- **Wrong password**: Enter an incorrect password and confirm an error message appears. The OTP step should not be reached.
- **Wrong OTP**: Enter the correct password but then an incorrect OTP code. Confirm an error message appears.
- **Expired OTP**: Wait for the OTP countdown to reach zero. Confirm the "Code expired" message appears and you must go back to try again.
- **Remember this device**: Check the "Remember this device for 7 days" box during OTP. Log out and log back in. Confirm you are not asked for OTP again on the same browser.
- **Forgot password flow**: Click "Forgot your password?", enter email, confirm the reset email is sent. Open the reset link, set a new password, confirm you can log in with the new password.
- **Expired reset link**: Try using an old or invalid reset link. Confirm the "link is missing or has expired" message appears.
- **Session timeout**: Stay logged in without activity until the session timeout warning appears. Click "Extend Session" and confirm the session continues. Alternatively, let it expire and confirm you are redirected to the login page.
- **Redirect after login**: Navigate directly to a protected page (for example `/account/services`) while logged out. Confirm you are redirected to login, and after logging in you are taken back to `/account/services` (not the default dashboard).
- **Already logged in**: Navigate to `/auth/login` while already logged in. Confirm you are automatically redirected away from the login page to your dashboard.
- **Logout banner messages**: Log out manually and confirm the "Signed Out" info banner. Let a session expire and confirm the "Session Expired" warning banner.
