# TOTP End-to-End Test Proposal

## Test Objective
Test ALL aspects of TOTP functionality regardless of current state (TOTP enabled or disabled).

## Test Flow

### Scenario A: TOTP Currently Enabled (Bob already enrolled)

1. **Login** with email/password
   - Response: `requires_totp: true`
   
2. **Get Secret from DB** (or use environment variable)
   - Since secret is encrypted/hashed in DB, we need to either:
     - Store it in environment/file from previous enrollment, OR
     - User provides it as input, OR  
     - Use backup code from previous enrollment
   
3. **Generate TOTP Code** using stored secret/backup code
   
4. **Verify TOTP** to complete login
   - Endpoint: `/auth/totp/verify`
   - Get auth_token
   
5. **Check TOTP Status**
   - Endpoint: `/auth/totp/status`
   - Confirm: `totp_enabled: true`
   
6. **Disable TOTP**
   - Endpoint: `/auth/totp/disable`
   - Provide password
   
7. **Logout**
   
8. **Continue to Scenario B steps 2-14**

### Scenario B: TOTP Currently Disabled (or after completing Scenario A)

1. **Login** with email/password
   - Response: `token` (no TOTP required)
   
2. **Check TOTP Status**
   - Endpoint: `/auth/totp/status`
   - Confirm: `totp_enabled: false`
   
3. **Enroll in TOTP**
   - Endpoint: `/auth/totp/enroll`
   - Store: secret, backup_codes, provisioning_uri, qr_code
   
4. **Generate TOTP Code** from new secret
   - Use timezone-aware UTC
   
5. **Verify Enrollment**
   - Endpoint: `/auth/totp/verify-enrollment`
   - Provide generated code
   
6. **Check TOTP Status Again**
   - Confirm: `totp_enabled: true`
   - Confirm: `backup_codes_remaining: 10`
   - Confirm: `verified_at` is set
   
7. **Logout**
   
8. **Login** with email/password
   - Response: `requires_totp: true`
   
9. **Generate TOTP Code** from stored secret
   
10. **Verify TOTP** to complete login
    - Endpoint: `/auth/totp/verify`
    - Get auth_token
    
11. **Confirm Logged In**
    - Endpoint: `/auth/me`
    - Verify user data returned
    
12. **Test Backup Code** (new login)
    - Logout
    - Login with email/password
    - Use backup code instead of TOTP
    - Endpoint: `/auth/totp/verify` with `is_backup_code: true`
    
13. **Check Backup Codes Remaining**
    - Should be 9 (one consumed)
    
14. **Regenerate Backup Codes**
    - Endpoint: `/auth/totp/regenerate-backup-codes`
    - Provide password
    - Get new set of 10 codes

## Implementation Strategy

### Secret Persistence Between Test Runs

**Option 1: Environment Variable** (Recommended)
```python
import os

# Save secret after first successful enrollment
SECRET_FILE = ".totp_test_secret"

if os.path.exists(SECRET_FILE):
    with open(SECRET_FILE) as f:
        data = json.load(f)
        known_secret = data.get("secret")
        known_backup_codes = data.get("backup_codes", [])
else:
    known_secret = None
    known_backup_codes = []

# After enrollment, save for next run
with open(SECRET_FILE, 'w') as f:
    json.dump({
        "secret": new_secret,
        "backup_codes": new_backup_codes  
    }, f)
```

**Option 2: Test Database State**
- Include SQL query to fetch secret from DB (if stored in plain text for testing)
- Or decrypt if encrypted

**Option 3: Manual Input**
- Prompt user for secret/backup code if TOTP already enabled
- Less automated but more flexible

## Expected Assertions

1. ✅ Login without TOTP works when disabled
2. ✅ Enrollment generates secret, QR code, backup codes
3. ✅ Enrollment verification accepts valid TOTP code
4. ✅ TOTP status shows enabled after verification
5. ✅ Login requires TOTP when enabled
6. ✅ TOTP verification works during login
7. ✅ Backup code works for authentication
8. ✅ Backup codes decrement when used
9. ✅ Backup code regeneration works  
10. ✅ TOTP disable works with correct password
11. ✅ Login works without TOTP after disabling

## Test Data Management

Store in `.totp_test_data.json` (gitignored):
```json
{
  "user": "bob@acme-corp.com",
  "secret": "BWAQAP55...",
  "backup_codes": ["code1", "code2", ...],
  "enrollment_date": "2026-01-14T03:12:00Z",
  "last_test_run": "2026-01-14T03:15:00Z"
}
```

## Error Handling

- Connection errors → clear message about server not running
- 401 errors → check if token/credentials are correct
- TOTP code failures → check time synchronization
- Backup code failures → check if already used

## Success Criteria

Test passes when:
1. All 14 steps complete without errors
2. All assertions pass
3. Test can run multiple times (idempotent)
4. Works from both initial states (TOTP enabled/disabled)

---

**Please review this proposal. Once approved, I'll implement it.**