# SmartDocs 360 Login Flow Documentation

## Overview

SmartDocs 360 uses a two-step authentication process:
1. **Username/Password Authentication** - Standard credential entry
2. **Multi-Factor Authentication (MFA)** - Time-based One-Time Password (TOTP)

After successful authentication, users are redirected to the SmartDocs 360 application.

---

## Login Flow Steps

### Step 1: Navigate to SSO Login Page

**URL**: `https://sso.uat.bgl360.com.au/?app=smartdocs&&appFilter=smartdocs`

**Page Elements**:
- Page Title: `Login | BGL - SMSF and Corporate Compliance`
- SmartDocs 360 logo image
- Username textbox (data-testid: `username-input`)
- Password textbox (data-testid: `password-input`)
- "Sign In" button (data-testid: `submit-button`)
- "Forgot your Password" link
- "Sign in with Xero" button (alternative authentication method)

**Actions**:
1. Wait for page to load completely
2. Enter username into the username textbox
3. Enter password into the password textbox
4. Click the "Sign In" button

**Expected Result**: Redirect to MFA page

---

### Step 2: Multi-Factor Authentication (MFA)

**Page Elements**:
- Page Title: `Login | BGL - SMSF and Corporate Compliance`
- Heading: "Enter Security Code"
- Instructions: "Enter the 6-digit code provided by your authenticator app."
- Security code textbox (role: textbox, name: "Enter Security Code")
- "Trust this device" checkbox
- "Submit" button
- "I have a new phone or need to reset my MFA" link
- Important notice about device trust duration (24 hours for ATO-connected software)

**Actions**:
1. Generate a 6-digit TOTP code using the shared secret key
2. Enter the TOTP code into the security code textbox
3. (Optional) Check "Trust this device" if desired
4. Click the "Submit" button

**Expected Result**: Redirect to SmartDocs 360 application

**Notes**:
- The Submit button is disabled until a valid 6-digit code is entered
- TOTP codes are time-based and expire after 30 seconds
- Device trust is limited to 24 hours for users accessing ATO-connected software

---

### Step 3: Successful Login

**Final URL**: `https://uat.bglsmartdocs.com/host/#/entities`

**Page Elements**:
- Page Title: `Entities | SmartDocs 360`
- SmartDocs 360 application interface with:
  - Entity selector dropdown
  - "Upload Documents" button
  - Search bar for entity lookup
  - Entity list table showing:
    - Entity Name column (sortable)
    - SmartDocs 360 Email column (sortable)
    - Action buttons for each entity
  - "New Entity" button
  - Navigation sidebar with Entities and Settings links

**Expected Result**: User is successfully logged in and viewing the Entities page

---

## TOTP Generation Implementation

### Using otplib npm Package

The TOTP (Time-based One-Time Password) follows RFC 6238 standard. Instead of implementing the algorithm manually, we use the `otplib` npm package which provides a robust and well-tested implementation.

### Installation

```bash
npm install otplib
```
### TypeScript Implementation

```typescript
import { authenticator } from 'otplib';

// TOTP generation function using otplib
export function generateTOTP(secret: string): string {
  // Generate a 6-digit TOTP code
  const token = authenticator.generate(secret);
  return token;
}

// Usage
const secret = 'OYH5UZHOS2PR6MGMJ5SZ7LSTSBLEF7BB7RRR6G25VXMVD6WIIVKQ';
const totp = generateTOTP(secret);
console.log(totp); // Outputs 6-digit code
```

## Key Findings

### Test IDs Available
The login page uses Playwright-friendly test IDs:
- `username-input` - Username field
- `password-input` - Password field
- `submit-button` - Sign In button

### MFA Page Uses Role Selectors
The MFA page doesn't use test IDs but can be accessed via:
- Role selector: `getByRole('textbox', { name: 'Enter Security Code' })`
- Role selector: `getByRole('button', { name: 'Submit' })`

### URL Changes
- Start: `https://sso.uat.bgl360.com.au/?app=smartdocs&&appFilter=smartdocs`
- After login: `https://uat.bglsmartdocs.com/host/#/entities`

### Authentication Tokens
The application uses session-based authentication. After successful login, authentication state is maintained through browser cookies/session storage.

### Error Handling Considerations
- Invalid credentials will show an error on the login page
- Expired or incorrect TOTP codes will show an error on the MFA page
- TOTP codes have a 30-second validity window

---

## Recommendations for Test Automation

1. **Create a Login Fixture**: Implement a reusable authentication fixture that:
   - Performs the complete login flow
   - Stores authentication state
   - Reuses the authenticated state across tests

2. **TOTP Helper Function**: Extract TOTP generation into a utility function that can be imported by tests

3. **Wait Strategies**: Use explicit waits for page transitions between login, MFA, and application pages

4. **Error Scenarios**: Test edge cases such as:
   - Invalid credentials
   - Expired TOTP codes
   - Network timeouts
   - MFA reset flow

5. **State Management**: Consider using Playwright's `storageState` to save and reuse authentication state across test runs

---

## Screenshots

- [Login Page Initial State](.playwright-mcp/screenshots/)
- [MFA Page](.playwright-mcp/screenshots/)
- [Entities Page (Post-Login)](.playwright-mcp/smartdocs360-entities-page.png)
