# Implementation Plan: Unified Users & Modern Authentication

**Specification ID:** 007-unified-users-auth
**Version:** 1.0
**Status:** IN PROGRESS (Phase 7 COMPLETE - Ready for Phase 8: Cutover & Cleanup)
**Last Updated:** December 2025

---

## 1. Implementation Overview

### 1.1 Phased Approach

This implementation follows an 8-phase approach designed for zero-downtime migration with rollback capability at each phase.

```
Phase 1: Security Hardening (Critical fixes - no schema changes)
    ↓
Phase 2: Schema Creation (New tables alongside existing)
    ↓
Phase 3: Authentication Infrastructure (Dual auth support)
    ↓
Phase 4: Data Migration (Parallel systems)
    ↓
Phase 5: Code Migration (Incremental updates)
    ↓
Phase 6: MFA Implementation (Optional feature)
    ↓
Phase 7: Testing & Stabilization
    ↓
Phase 8: Cutover & Cleanup
```

### 1.2 Key Dependencies

| Dependency | Required For | Notes |
|------------|--------------|-------|
| Redis | Rate limiting (Phase 1), session caching (Phase 3) | DB fallback available if Redis unavailable |
| OpenSSL | RSA key generation for JWT (Phase 3) | |
| OTPHP library | TOTP MFA support (Phase 6) | |
| Firebase JWT library | Already installed, needs update | |

---

## 2. Phase 1: Security Hardening

**Goal:** Fix critical vulnerabilities without schema changes
**Risk Level:** LOW (Quick fixes, no data changes)
**Rollback:** Git revert individual commits

### 2.1 Tasks

#### Task 1.1: Enable CSRF on Login
**File:** `userfrosting/src/BuyerKiosk/Core/Controllers/AccountController.php:217-221`
**Priority:** CRITICAL
**Effort:** 15 minutes

```php
// BEFORE: Commented out
// if (!\NoCSRF::check('csrf_token', $this->_app->request->post())) { ... }

// AFTER: Uncomment and enable
if (!\NoCSRF::check('csrf_token', $this->_app->request->post())) {
    $ms->addMessageTranslated("danger", "Invalid or missing CSRF token.");
    $this->_app->halt(403);
}
```

**Acceptance Criteria:**
- [x] CSRF validation enabled on login form
- [x] Login form includes csrf_token hidden field
- [x] Invalid CSRF returns 403 response

---

#### Task 1.2: Fix API Key Timing Attack
**File:** `userfrosting/models/mysql/MySqlUser.php:390`
**Priority:** CRITICAL
**Effort:** 15 minutes

```php
// BEFORE: Vulnerable
if (strcmp($row['key'], $apiKey) == 0 && (int)$row['active'] == 1) {

// AFTER: Timing-safe
if (hash_equals($row['key'], $apiKey) && (int)$row['active'] == 1) {
```

**Acceptance Criteria:**
- [x] API key comparison uses hash_equals()
- [x] Existing API key authentication still works
- [x] No timing difference between valid/invalid keys

---

#### Task 1.3: Fix Password Hash Upgrade Bug
**File:** `userfrosting/models/mysql/MySqlUser.php:401-410`
**Priority:** CRITICAL
**Effort:** 15 minutes

```php
// BEFORE: Wrong method called
$password_hash = Authentication::getPasswordHashType($password);

// AFTER: Correct method
$password_hash = Authentication::hashPassword($password);
```

**Acceptance Criteria:**
- [x] Legacy SHA1 passwords upgrade to modern hash on login
- [x] Legacy bcrypt passwords upgrade on login
- [x] Hash upgrade persisted to database

---

#### Task 1.4: Add Session Cookie Security Flags
**File:** `userfrosting/config-userfrosting.php`
**Priority:** CRITICAL
**Effort:** 15 minutes

```php
// Add at top of file
ini_set('session.cookie_httponly', 1);
ini_set('session.cookie_samesite', 'Strict');
ini_set('session.use_strict_mode', 1);

// Secure flag should only be enabled in production (HTTPS)
// This prevents breaking HTTP-only dev environments
if (!empty($_ENV['APP_ENV']) && $_ENV['APP_ENV'] === 'production') {
    ini_set('session.cookie_secure', 1);
} elseif (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off') {
    ini_set('session.cookie_secure', 1);
}
```

> **Development Note:** The `session.cookie_secure` flag requires HTTPS. For local HTTP development:
> - Set `APP_ENV=development` in your environment
> - Or access via HTTPS locally (e.g., using mkcert)
> - The flag will auto-enable when HTTPS is detected or when `APP_ENV=production`

**Acceptance Criteria:**
- [x] Session cookies have HttpOnly flag
- [x] Session cookies have Secure flag (in production/HTTPS only)
- [x] Session cookies have SameSite=Strict
- [x] Web login still functions correctly
- [x] Local HTTP dev environments continue to work

---

#### Task 1.5: Add Basic Rate Limiting (Login)
**Files:**
- `userfrosting/src/BuyerKiosk/Auth/Services/RateLimiter.php` (new)
- `userfrosting/src/BuyerKiosk/Core/Controllers/AccountController.php`

**Priority:** CRITICAL
**Effort:** 2-4 hours

**Implementation:**
1. Create RateLimiter class with Redis backend (DB fallback)
2. Add rate check before password verification in login()
3. Record failed attempts
4. Return 429 when limit exceeded

```php
// In AccountController::login()
$rateLimiter = new RateLimiter($this->_app->redis);
$result = $rateLimiter->checkLimit('login', $_SERVER['REMOTE_ADDR']);

if ($result->isBlocked()) {
    $this->_app->halt(429, "Too many login attempts. Try again in " . $result->retryAfter . " seconds.");
}
```

**Acceptance Criteria:**
- [x] Login blocked after 10 failed attempts from same IP
- [x] Lockout period is 30 minutes
- [x] Successful login resets counter
- [x] Works with Redis (falls back to DB)

---

#### Task 1.6: Add Rate Limiting (Password Reset)
**File:** `userfrosting/src/BuyerKiosk/Core/Controllers/AccountController.php`
**Priority:** CRITICAL
**Effort:** 1 hour

**Acceptance Criteria:**
- [x] Password reset limited to 3 requests per hour per email
- [x] Generic response regardless of email existence
- [x] Rate limit applies before sending email

---

#### Task 1.7: Add Password Reset Token Expiration
**File:** `userfrosting/src/BuyerKiosk/Core/Controllers/AccountController.php`
**Priority:** HIGH
**Effort:** 30 minutes

```php
// In resetPassword() method
$user = UserLoader::fetch($token, 'lost_password_request');

// Add expiration check
if ($user->lost_password_timestamp < strtotime('-1 hour')) {
    $ms->addMessageTranslated("danger", "Password reset link has expired.");
    $this->_app->halt(400);
}
```

**Acceptance Criteria:**
- [x] Password reset tokens expire after 1 hour
- [x] Expired token returns clear error message
- [x] Timestamp stored when token generated

---

#### Task 1.8: Implement Account Lockout (FR-109)
**Files:**
- `userfrosting/src/BuyerKiosk/Core/Controllers/AccountController.php`
- `userfrosting/src/BuyerKiosk/Auth/Services/AuditLogger.php` (if exists, else inline)

**Priority:** CRITICAL
**Effort:** 2-4 hours

**Implementation:**
1. Check `lockedUntil` before password verification
2. Increment `failedLoginAttempts` on failed login
3. Reset `failedLoginAttempts` to 0 on successful login
4. Set `lockedUntil` = NOW + 15 minutes after 5 failures
5. Return `account_locked` error with remaining lockout time
6. Log `account_locked` and `account_unlocked` events to `authAuditLog`

```php
// In AccountController::login(), before password check
$user = UserLoader::fetch($username, 'user_name');

// Check if account is locked
if ($user->lockedUntil && strtotime($user->lockedUntil) > time()) {
    $remainingSeconds = strtotime($user->lockedUntil) - time();
    $auditLogger->log('login_failed', $user->id, ['reason' => 'account_locked']);
    $this->_app->halt(403, json_encode([
        'error' => 'account_locked',
        'message' => 'Account temporarily locked due to failed login attempts.',
        'retry_after' => $remainingSeconds
    ]));
}

// After password verification fails
$user->failedLoginAttempts++;
if ($user->failedLoginAttempts >= 5) {
    $user->lockedUntil = date('Y-m-d H:i:s', strtotime('+15 minutes'));
    $auditLogger->log('account_locked', $user->id, [
        'failed_attempts' => $user->failedLoginAttempts,
        'locked_until' => $user->lockedUntil
    ]);
}
$user->store();

// After successful login
$user->failedLoginAttempts = 0;
$user->lockedUntil = null;
$user->store();
```

**Acceptance Criteria:**
- [x] Account locked after 5 failed attempts
- [x] Lockout duration is 15 minutes
- [x] Locked account returns 403 with `account_locked` error
- [x] Successful login resets failed attempts counter
- [x] `account_locked` event logged to `authAuditLog`
- [x] `account_unlocked` event logged when lockout expires (or on successful login after lockout)
- [x] Remaining lockout time returned in error response

---

#### Task 1.9: Secure Remember-Me Token Implementation (HIGH-003)
**Files:**
- `userfrosting/src/BuyerKiosk/Auth/Services/RememberMeService.php` (new)
- `userfrosting/src/BuyerKiosk/Core/Controllers/AccountController.php`

**Priority:** HIGH (Security Vulnerability HIGH-003)
**Effort:** 4-6 hours

**Problem:** Current `uf_user_rememberme` table stores plaintext tokens. If the database is compromised, attackers can impersonate any user with an active remember-me token.

**Solution:** Implement hashed, one-time-use remember-me tokens following the same pattern as refresh tokens.

**Implementation:**

```php
<?php
namespace BuyerKiosk\Auth\Services;

class RememberMeService {
    private const TOKEN_EXPIRY_DAYS = 30;

    /**
     * Create a new remember-me token for the user.
     * Returns the plaintext token (to be sent to client), stores hashed version.
     */
    public function createToken(int $userId): string {
        // Generate cryptographically secure token
        $plaintextToken = bin2hex(random_bytes(32)); // 64 hex chars

        // Hash before storing (same pattern as refresh tokens)
        $hashedToken = hash('sha256', $plaintextToken);

        $expiresAt = date('Y-m-d H:i:s', strtotime('+' . self::TOKEN_EXPIRY_DAYS . ' days'));

        // Delete existing tokens for this user (optional: allow multiple devices)
        $this->db->prepare("DELETE FROM uf_user_rememberme WHERE user_id = ?")->execute([$userId]);

        // Store hashed token
        $this->db->prepare("
            INSERT INTO uf_user_rememberme (user_id, token, created_at, expires_at)
            VALUES (?, ?, NOW(), ?)
        ")->execute([$userId, $hashedToken, $expiresAt]);

        return $plaintextToken;
    }

    /**
     * Validate a remember-me token and return user ID if valid.
     * Implements token rotation: on successful validation, old token is invalidated
     * and a new token is issued.
     */
    public function validateAndRotate(string $plaintextToken): ?array {
        $hashedToken = hash('sha256', $plaintextToken);

        $row = $this->db->prepare("
            SELECT user_id, expires_at FROM uf_user_rememberme
            WHERE token = ? AND expires_at > NOW()
        ")->execute([$hashedToken])->fetch();

        if (!$row) {
            return null;
        }

        // Token rotation: delete old, create new
        $this->db->prepare("DELETE FROM uf_user_rememberme WHERE token = ?")->execute([$hashedToken]);
        $newToken = $this->createToken($row['user_id']);

        return [
            'userId' => $row['user_id'],
            'newToken' => $newToken
        ];
    }

    /**
     * Revoke all remember-me tokens for a user (e.g., on password change).
     */
    public function revokeAllForUser(int $userId): void {
        $this->db->prepare("DELETE FROM uf_user_rememberme WHERE user_id = ?")->execute([$userId]);
    }
}
```

**Schema Update (if needed):**
```sql
-- Add expires_at column if not present
ALTER TABLE uf_user_rememberme
    ADD COLUMN IF NOT EXISTS expires_at TIMESTAMP NULL,
    ADD COLUMN IF NOT EXISTS created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP;

-- Migration: Hash existing tokens or invalidate them
-- OPTION 1: Invalidate all existing tokens (simpler, users re-login)
TRUNCATE TABLE uf_user_rememberme;

-- OPTION 2: Hash existing tokens (complex, maintains sessions)
-- Not recommended: existing tokens were stored in predictable format
```

**Integration in AccountController:**
```php
// On login with "remember me" checked
if ($request->post('rememberme')) {
    $rememberMeService = new RememberMeService($this->db);
    $token = $rememberMeService->createToken($user->id);

    // Set secure cookie with plaintext token
    setcookie('remember_token', $token, [
        'expires' => time() + (30 * 24 * 60 * 60), // 30 days
        'path' => '/',
        'secure' => true,
        'httponly' => true,
        'samesite' => 'Strict'
    ]);
}

// On page load, check for remember-me cookie
if (!$isLoggedIn && isset($_COOKIE['remember_token'])) {
    $result = $rememberMeService->validateAndRotate($_COOKIE['remember_token']);
    if ($result) {
        // Log user in
        $this->loginUser($result['userId']);

        // Set new rotated token cookie
        setcookie('remember_token', $result['newToken'], [...]);
    } else {
        // Invalid/expired token, clear cookie
        setcookie('remember_token', '', ['expires' => time() - 3600, 'path' => '/']);
    }
}
```

**Acceptance Criteria:**
- [x] Remember-me tokens stored as SHA-256 hashes (not plaintext)
- [x] Tokens expire after 30 days
- [x] Token rotation on each use (one-time-use)
- [x] Existing plaintext tokens invalidated during deployment (users re-login once)
- [x] Remember-me cookie has Secure, HttpOnly, SameSite=Strict flags
- [x] Password change revokes all remember-me tokens for user
- [x] `remember_me` audit events logged to `authAuditLog`

**Migration Note:** All existing remember-me sessions will be invalidated. Users will need to re-authenticate and re-check "remember me" after deployment.

---

### 2.1.1 Rate Limiting Scope Clarification

Per SDD Section 3.5, the full rate limiting requirements include:

| Limit Type | Phase 1 | Later Phase | Notes |
|------------|---------|-------------|-------|
| Login (per IP) | ✅ Task 1.5 | - | 10 attempts / 15 min |
| Login (per user/email) | - | Phase 3 (Task 3.3a) | 5 attempts / 15 min |
| Password Reset (per email) | ✅ Task 1.6 | - | 3 attempts / 1 hour |
| MFA Verification | - | Phase 6 (Task 6.3a) | 5 attempts / 5 min |
| API (per key) | - | Future Phase | 100 requests / 1 min |

**Rationale for Deferral:**
- **Per-user login limiting** requires the new `users` table infrastructure (Phase 3+)
- **MFA verification limiting** requires MFA infrastructure (Phase 6)
- **API key rate limiting** is lower priority; can be added post-launch as needed

---

### 2.2 Phase 1 Validation

| Check | Method |
|-------|--------|
| CSRF Protection | Attempt login without token, expect 403 |
| Rate Limiting | Attempt 11 logins from same IP, expect 429 |
| Account Lockout | Attempt 5 failed logins for same user, expect 403 with `account_locked` |
| Session Cookies | Check browser dev tools for flags |
| API Key Security | Existing mobile app still authenticates |
| Hash Upgrade | Login with legacy user, verify hash changed |
| Audit Logging | Verify `account_locked` events appear in `authAuditLog` |
| Remember-Me Security | Verify tokens stored as hashes, not plaintext; verify token rotation on use |

---

## 3. Phase 2: Schema Creation

**Goal:** Create new tables alongside existing (no data migration yet)
**Risk Level:** LOW (Additive only)
**Rollback:** DROP new tables

### 3.1 Tasks

#### Task 2.1: Create Migration Input Files
**Directory:** `userfrosting/migrations/input/`
**Effort:** 1 hour

Create the following migration JSON files:

```
20251220_001_users_table.json
20251220_002_user_store_assignments.json
20251220_003_user_groups.json
20251220_004_user_permissions.json
20251220_005_oauth_refresh_tokens.json
20251220_006_user_sessions.json
20251220_007_auth_audit_log.json
20251220_008_user_sync_log.json
20251220_009_rate_limit_attempts.json
```

**Acceptance Criteria:**
- [x] All migration files created with correct schema
- [x] Foreign key relationships defined
- [x] Indexes optimized for query patterns
- [x] Migrations run without errors on test database

---

#### Task 2.2: Create Users Table Migration
**File:** `userfrosting/migrations/input/20251220_001_users_table.json`

```json
{
  "name": "Create unified users table",
  "database": "kiosk_users",
  "table": "users",
  "action": "create",
  "columns": [
    {"name": "id", "type": "INT UNSIGNED", "primary": true, "auto_increment": true},
    {"name": "username", "type": "VARCHAR(50)", "unique": true, "nullable": true},
    {"name": "email", "type": "VARCHAR(150)", "nullable": true},
    {"name": "password", "type": "VARCHAR(255)", "nullable": true},
    {"name": "displayName", "type": "VARCHAR(150)", "nullable": true},
    {"name": "firstName", "type": "VARCHAR(50)", "nullable": true},
    {"name": "lastName", "type": "VARCHAR(50)", "nullable": true},
    {"name": "phone", "type": "VARCHAR(20)", "nullable": true},
    {"name": "photoUrl", "type": "VARCHAR(500)", "nullable": true},
    {"name": "avatarOverride", "type": "TINYINT(1)", "default": 0},
    {"name": "position", "type": "VARCHAR(100)", "nullable": true},
    {"name": "hourlyRate", "type": "DECIMAL(10,2)", "nullable": true},
    {"name": "hireDate", "type": "DATE", "nullable": true},
    {"name": "terminationDate", "type": "DATE", "nullable": true},
    {"name": "leaveStartDate", "type": "DATE", "nullable": true},
    {"name": "leaveEndDate", "type": "DATE", "nullable": true},
    {"name": "emergencyContactName", "type": "VARCHAR(100)", "nullable": true},
    {"name": "emergencyContactPhone", "type": "VARCHAR(20)", "nullable": true},
    {"name": "source", "type": "ENUM('homegrown','wheniwork','homebase','system')", "default": "'system'"},
    {"name": "externalId", "type": "VARCHAR(50)", "nullable": true},
    {"name": "lastSyncedAt", "type": "TIMESTAMP", "nullable": true},
    {"name": "canLogin", "type": "TINYINT(1)", "default": 0},
    {"name": "accountType", "type": "ENUM('employee','user','admin','system')", "default": "'employee'"},
    {"name": "enabled", "type": "TINYINT(1)", "default": 1},
    {"name": "active", "type": "TINYINT(1)", "default": 0},
    {"name": "activationToken", "type": "VARCHAR(255)", "nullable": true},
    {"name": "activationTokenExpiresAt", "type": "TIMESTAMP", "nullable": true},
    {"name": "passwordResetToken", "type": "VARCHAR(255)", "nullable": true},
    {"name": "passwordResetExpiresAt", "type": "TIMESTAMP", "nullable": true},
    {"name": "mfaEnabled", "type": "TINYINT(1)", "default": 0},
    {"name": "mfaSecret", "type": "VARCHAR(255)", "nullable": true},
    {"name": "mfaBackupCodes", "type": "JSON", "nullable": true},
    {"name": "mfaVerifiedAt", "type": "TIMESTAMP", "nullable": true},
    {"name": "locale", "type": "VARCHAR(10)", "default": "'en_US'"},
    {"name": "dailyReport", "type": "TINYINT(1)", "default": 0},
    {"name": "timezone", "type": "VARCHAR(50)", "default": "'America/Los_Angeles'"},
    {"name": "createdAt", "type": "TIMESTAMP", "default": "CURRENT_TIMESTAMP"},
    {"name": "updatedAt", "type": "TIMESTAMP", "default": "CURRENT_TIMESTAMP", "on_update": "CURRENT_TIMESTAMP"},
    {"name": "lastLoginAt", "type": "TIMESTAMP", "nullable": true},
    {"name": "lastLoginIp", "type": "VARCHAR(45)", "nullable": true},
    {"name": "failedLoginAttempts", "type": "INT", "default": 0},
    {"name": "lockedUntil", "type": "TIMESTAMP", "nullable": true}
  ],
  "indexes": [
    {"name": "idx_username", "columns": ["username"]},
    {"name": "idx_email", "columns": ["email"]},
    {"name": "idx_external", "columns": ["source", "externalId"]},
    {"name": "idx_canLogin", "columns": ["canLogin"]},
    {"name": "idx_accountType", "columns": ["accountType"]},
    {"name": "idx_active", "columns": ["enabled", "active"]}
  ]
}
```

---

#### Task 2.3: Create Supporting Tables
**Files:** `20251220_002_*.json` through `20251220_009_*.json`
**Effort:** 2 hours

Create migrations for:
- userStoreAssignments
- userGroups
- userPermissions
- oauthRefreshTokens
- userSessions
- authAuditLog
- userSyncLog
- rateLimitAttempts

**Acceptance Criteria:**
- [x] All tables created successfully
- [x] Foreign keys reference users.id
- [x] Indexes created for common queries

---

#### Task 2.4: Run Migrations on Test Environment
**Command:** `php userfrosting/cli/migrate.php`
**Effort:** 1 hour

**Acceptance Criteria:**
- [x] All migrations complete without errors
- [x] Tables have correct structure (SHOW CREATE TABLE)
- [x] Foreign keys functional
- [x] Can INSERT/SELECT test data

---

### 3.2 Phase 2 Validation

| Check | Method |
|-------|--------|
| Schema Correct | Compare SHOW CREATE TABLE to SDD |
| FK Integrity | Insert user, verify CASCADE on delete |
| Index Performance | EXPLAIN common queries |
| No Data Loss | Verify uf_user data unchanged |

---

## 4. Phase 3: Authentication Infrastructure

**Goal:** Build modern auth alongside legacy (both systems work)
**Risk Level:** MEDIUM (New code, parallel operation)
**Rollback:** Disable new middleware, revert to session-only

### 4.1 Tasks

#### Task 3.1: Generate RSA Key Pair
**Location:** `userfrosting/config/keys/`
**Effort:** 30 minutes

```bash
# Generate private key
openssl genrsa -out jwt_private.pem 2048

# Generate public key
openssl rsa -in jwt_private.pem -pubout -out jwt_public.pem

# Set permissions
chmod 600 jwt_private.pem
chmod 644 jwt_public.pem
```

**Acceptance Criteria:**
- [x] Private key generated (2048 bit RSA)
- [x] Public key extracted
- [x] Keys excluded from git
- [x] Keys deployed securely

---

#### Task 3.2: Create TokenService
**File:** `userfrosting/src/BuyerKiosk/Auth/Services/TokenService.php`
**Effort:** 4-6 hours

```php
<?php
namespace BuyerKiosk\Auth\Services;

use Firebase\JWT\JWT;
use Firebase\JWT\Key;

class TokenService {
    private string $privateKey;
    private string $publicKey;
    private string $keyId = 'key-2025-01';
    private int $accessTokenTTL = 900; // 15 minutes
    private int $refreshTokenTTL = 604800; // 7 days

    public function createAccessToken(array $user, array $stores, array $permissions): string;
    public function createRefreshToken(int $userId, array $deviceInfo): string;
    public function validateAccessToken(string $token): ?array;
    public function validateRefreshToken(string $token): ?array;
    public function revokeRefreshToken(string $token): void;
    public function revokeAllUserTokens(int $userId): void;
}
```

**Acceptance Criteria:**
- [x] Access tokens signed with RS256
- [x] Access tokens include user, stores, permissions
- [x] Refresh tokens are opaque (random bytes)
- [x] Refresh tokens stored hashed in DB
- [x] Token validation handles expiration
- [x] Revocation clears tokens from DB

---

#### Task 3.3: Create AuthService with Argon2id Password Handling (FR-202/FR-203)
**File:** `userfrosting/src/BuyerKiosk/Auth/Services/AuthService.php`
**Effort:** 6-8 hours

**Methods:**
- `login(username, password, mfaCode)` → AuthResult
- `logout(userId, sessionId)` → void
- `refreshToken(refreshToken)` → TokenPair
- `verifyPassword(user, password)` → bool (see implementation below)
- `upgradePasswordHash(user, password)` → void
- `hashPassword(password)` → string (Argon2id)

**Password Verification Flow (per SDD Section 6.1):**
```php
public function verifyPassword(UnifiedUser $user, string $password): bool {
    $hash = $user->getPassword();
    $hashInfo = password_get_info($hash);

    // Modern Argon2id hash
    if ($hashInfo['algo'] === PASSWORD_ARGON2ID) {
        return password_verify($password, $hash);
    }

    // Legacy SHA1: first 25 chars are salt, remaining 40 are hash
    if (strlen($hash) === 65) {
        $salt = substr($hash, 0, 25);
        if (hash_equals($hash, $salt . sha1($salt . $password))) {
            $this->upgradePasswordHash($user, $password);
            return true;
        }
        return false;
    }

    // Legacy bcrypt
    if (password_verify($password, $hash)) {
        $this->upgradePasswordHash($user, $password);
        return true;
    }

    return false;
}

public function upgradePasswordHash(UnifiedUser $user, string $password): void {
    $newHash = password_hash($password, PASSWORD_ARGON2ID, [
        'memory_cost' => 65536, // 64 MB
        'time_cost' => 3,
        'threads' => 4
    ]);
    $user->setPassword($newHash);
    $user->save();
    $this->auditLogger->log('password_hash_upgraded', $user->getId(), [
        'old_type' => 'legacy',
        'new_type' => 'argon2id'
    ]);
}

public function hashPassword(string $password): string {
    return password_hash($password, PASSWORD_ARGON2ID, [
        'memory_cost' => 65536,
        'time_cost' => 3,
        'threads' => 4
    ]);
}
```

**Acceptance Criteria:**
- [x] Login validates credentials correctly
- [x] Login checks canLogin flag
- [x] Login records audit events
- [x] Logout revokes tokens
- [x] Refresh rotation works correctly
- [x] NEW: `hashPassword()` uses Argon2id for all new passwords
- [x] NEW: `verifyPassword()` detects SHA1, bcrypt, and Argon2id hashes
- [x] NEW: Legacy hashes auto-upgraded to Argon2id on successful login
- [x] NEW: Password hash upgrade logged to `authAuditLog`

---

#### Task 3.3a: Add Per-User/Email Login Rate Limiting
**File:** `userfrosting/src/BuyerKiosk/Auth/Services/AuthService.php`
**Priority:** HIGH (per SDD Section 3.5)
**Effort:** 1-2 hours

**Requirement:** In addition to per-IP rate limiting (Task 1.5), implement per-user/email rate limiting to prevent credential stuffing attacks across multiple IPs.

```php
// In AuthService::login(), after loading user
$userRateResult = $this->rateLimiter->checkLimit('login_user', $user->getEmail());
if ($userRateResult->isBlocked()) {
    $this->auditLogger->log('login_failed', $user->getId(), [
        'reason' => 'user_rate_limited',
        'retry_after' => $userRateResult->getRetryAfter()
    ]);
    throw new RateLimitException('Too many login attempts for this account', $userRateResult->getRetryAfter());
}

// After successful login, clear user-specific rate limit
$this->rateLimiter->clearAttempts('login_user', $user->getEmail());
```

**Rate Limit Configuration:**
- **Identifier:** User email (not username, to handle multiple username attempts)
- **Window:** 15 minutes
- **Max Attempts:** 5
- **Lockout:** 15 minutes

**Acceptance Criteria:**
- [x] Per-email login rate limiting active (separate from per-IP)
- [x] 5 failed attempts for same email triggers lockout
- [x] Lockout duration is 15 minutes
- [x] Successful login clears per-email counter
- [x] Rate limit event logged to `authAuditLog`

---

#### Task 3.4: Create AuditLogger
**File:** `userfrosting/src/BuyerKiosk/Auth/Services/AuditLogger.php`
**Effort:** 2 hours

```php
<?php
namespace BuyerKiosk\Auth\Services;

class AuditLogger {
    public function log(string $eventType, ?int $userId, array $details = []): void {
        // Insert into auth_audit_log
    }

    public function logLogin(int $userId, bool $success, ?string $reason = null): void;
    public function logLogout(int $userId): void;
    public function logPasswordChange(int $userId): void;
    public function logMfaEvent(int $userId, string $action): void;
    public function logTokenEvent(int $userId, string $action): void;
}
```

**Acceptance Criteria:**
- [x] All auth events logged
- [x] IP address captured
- [x] User agent captured
- [x] Timestamps accurate

---

#### Task 3.5: Create DualAuthMiddleware
**File:** `userfrosting/src/BuyerKiosk/Auth/Middleware/DualAuthMiddleware.php`
**Effort:** 4-6 hours

**Note:** This implementation uses Slim 2.x idioms. Slim 2 accesses headers via `$request->headers->get()` (returns string|null), not `$request->getHeader()`. Also, Slim 2 has no `hasHeader()` method.

```php
<?php
namespace BuyerKiosk\Auth\Middleware;

class DualAuthMiddleware {
    /**
     * Slim 2 middleware callable
     * @param \Slim\Http\Request $request Slim 2 request object
     */
    public function __invoke($app) {
        return function () use ($app) {
            $request = $app->request;

            // Slim 2: Use $request->headers->get() which returns string|null
            $auth = $request->headers->get('Authorization');

            // Normalize: empty string to null for consistent handling
            $auth = !empty($auth) ? $auth : null;

            // Check X-Api-Key header (Slim 2 idiom)
            $xApiKey = $request->headers->get('X-Api-Key');
            $hasXApiKey = !empty($xApiKey);

            if ($auth !== null && $this->startsWith($auth, 'Bearer ')) {
                return $this->handleJwtAuth($app);
            }

            if (($auth !== null && $this->startsWith($auth, 'ApiKey ')) || $hasXApiKey) {
                return $this->handleLegacyApiKey($app, $hasXApiKey ? $xApiKey : $auth);
            }

            if ($this->hasValidSession($app)) {
                return $this->handleSessionAuth($app);
            }

            return $this->unauthorized($app);
        };
    }

    /**
     * PHP 7 compatible string prefix check (str_starts_with is PHP 8+)
     */
    private function startsWith(string $haystack, string $needle): bool {
        return strncmp($haystack, $needle, strlen($needle)) === 0;
    }

    private function handleJwtAuth($app): void { /* ... */ }
    private function handleLegacyApiKey($app, string $key): void { /* ... */ }
    private function hasValidSession($app): bool { /* ... */ }
    private function handleSessionAuth($app): void { /* ... */ }
    private function unauthorized($app): void {
        $app->halt(401, json_encode(['error' => 'Unauthorized']));
    }
}
```

**Slim 2 Middleware Registration:**
```php
// In routes/auth.php or initialize.php
$app->add(new \BuyerKiosk\Auth\Middleware\DualAuthMiddleware());
```

**Acceptance Criteria:**
- [x] JWT Bearer tokens validated
- [x] Legacy ApiKey headers work (both `Authorization: ApiKey ...` and `X-Api-Key: ...`)
- [x] Session auth preserved
- [x] 401 for missing/invalid auth
- [x] User context set correctly
- [x] Handles null header values gracefully (Slim 2 returns null for missing headers)
- [x] Works with PHP 7.x (no `str_starts_with()` dependency)

---

#### Task 3.6: Create Auth Controller & Routes
**Files:**
- `userfrosting/src/BuyerKiosk/Auth/Controllers/AuthController.php`
- `userfrosting/routes/auth.php`

**Effort:** 4-6 hours

**Endpoints:**
- POST `/auth/login`
- POST `/auth/logout`
- POST `/auth/refresh`

**Acceptance Criteria:**
- [x] Login returns access + refresh tokens
- [x] Logout revokes tokens
- [x] Refresh rotates tokens
- [x] Error responses follow spec

---

#### Task 3.7: Update AccountController for Dual Auth
**File:** `userfrosting/src/BuyerKiosk/Core/Controllers/AccountController.php`
**Effort:** 4-6 hours

**Changes:**
- Use AuthService for login validation
- Generate JWT on successful login
- Store refresh token
- Continue setting session for web login

**Acceptance Criteria:**
- [x] Web login creates both session AND JWT
- [x] Existing web flows unchanged
- [x] Rate limiting applied
- [x] Audit logging active

---

### 4.2 Phase 3 Validation

| Check | Method |
|-------|--------|
| JWT Auth | Call API with Bearer token |
| Legacy API Key | Call API with ApiKey header |
| Session Auth | Log in via web, access protected page |
| Token Refresh | Use refresh token to get new access token |
| Audit Logging | Check auth_audit_log entries |
| Argon2id Hashing | Create new user, verify password hash starts with `$argon2id$` |
| Legacy Hash Upgrade | Login with SHA1/bcrypt user, verify hash upgraded to Argon2id |

---

## 5. Phase 4: Data Migration

**Goal:** Migrate all user/employee data to unified tables
**Risk Level:** HIGH (Data transformation)
**Rollback:** Restore from backup, drop new tables

### 5.1 Pre-Migration Tasks

#### Task 4.0: Create Full Database Backup
**Effort:** 1 hour

```bash
# Central database
mysqldump -u root -p kiosk_users > backup_kiosk_users_$(date +%Y%m%d).sql

# All store databases
for db in $(mysql -u root -p -e "SHOW DATABASES LIKE 'kiosk_%'" -N); do
    mysqldump -u root -p $db > backup_${db}_$(date +%Y%m%d).sql
done
```

**Acceptance Criteria:**
- [x] Full backup of kiosk_users
- [x] Full backup of all kiosk_* store databases
- [x] Backups tested with restore

**Implementation:** `userfrosting/migrations/scripts/phase4_backup.sh`

---

### 5.2 Migration Tasks

#### Task 4.1: Migrate uf_user → users
**File:** `userfrosting/migrations/scripts/phase4_migrate_users.php`
**Effort:** 4-6 hours

```php
<?php
// Migration script: uf_user → users

$stmt = $db->query("SELECT * FROM uf_user");
while ($row = $stmt->fetch()) {
    $db->prepare("
        INSERT INTO users (
            username, email, password, displayName,
            canLogin, accountType, enabled, active,
            activationToken, passwordResetToken,
            locale, dailyReport, createdAt, lastLoginAt
        ) VALUES (
            :user_name, :email, :password, :display_name,
            1, 'user', :enabled, :active,
            :activation_token, :lost_password_request,
            :locale, :dailyReport, :sign_up_stamp, :last_sign_in_stamp
        )
    ")->execute([...]);

    // Map old ID to new ID
    $idMapping[$row['id']] = $db->lastInsertId();
}
```

**Acceptance Criteria:**
- [x] All uf_user records migrated
- [x] Password hashes preserved exactly
- [x] canLogin = true for all migrated users
- [x] accountType = 'user' for standard users
- [x] ID mapping tracked for related tables

---

#### Task 4.2: Migrate Group Memberships
**File:** `userfrosting/migrations/scripts/phase4_migrate_groups.php`
**Effort:** 2 hours

```php
<?php
// Migrate uf_group_user → userGroups
// Using ID mapping from Task 4.1

$stmt = $db->query("SELECT * FROM uf_group_user");
while ($row = $stmt->fetch()) {
    $newUserId = $idMapping[$row['user_id']];
    $db->prepare("
        INSERT INTO userGroups (userId, groupId)
        VALUES (:userId, :groupId)
    ")->execute([
        'userId' => $newUserId,
        'groupId' => $row['group_id']
    ]);
}
```

**Acceptance Criteria:**
- [x] All group memberships migrated
- [x] User IDs correctly mapped
- [x] uf_group table unchanged

---

#### Task 4.3: Migrate User Permissions
**File:** `userfrosting/migrations/scripts/phase4_migrate_permissions.php`
**Effort:** 2 hours

```php
<?php
// Migrate uf_authorize_user → userPermissions

$stmt = $db->query("SELECT * FROM uf_authorize_user");
while ($row = $stmt->fetch()) {
    $newUserId = $idMapping[$row['user_id']];
    $db->prepare("
        INSERT INTO userPermissions (userId, hook, conditions)
        VALUES (:userId, :hook, :conditions)
    ")->execute([...]);
}
```

**Acceptance Criteria:**
- [x] All user permissions migrated
- [x] Conditions preserved as-is
- [x] Hook names unchanged

---

#### Task 4.4: Migrate Linked Employees
**File:** `userfrosting/migrations/scripts/phase4_migrate_linked_employees.php`
**Effort:** 4-6 hours

For each user_employee_links record:
1. Find migrated user in users table
2. Load employee from store database
3. UPDATE users with employee data (name, phone, etc.)
4. CREATE userStoreAssignments record

```php
<?php
$stmt = $centralDb->query("SELECT * FROM user_employee_links");
while ($link = $stmt->fetch()) {
    $newUserId = $idMapping[$link['userId']];
    $storeDb = dbConnectByName('kiosk_' . $link['typeNum']);

    $employee = $storeDb->query(
        "SELECT * FROM employees WHERE employeeID = ?",
        [$link['employeeId']]
    )->fetch();

    // Update user with employee data
    $centralDb->prepare("
        UPDATE users SET
            firstName = COALESCE(firstName, :firstName),
            lastName = COALESCE(lastName, :lastName),
            phone = COALESCE(phone, :phone),
            position = :position,
            hireDate = :hireDate,
            source = :source,
            externalId = :externalId
        WHERE id = :id
    ")->execute([
        'firstName' => $employee['employeeFirstName'],
        'lastName' => $employee['employeeLastName'],
        'phone' => $employee['phone'],
        'position' => $employee['position'],
        'hireDate' => $employee['hireDate'],
        'source' => $employee['source'],
        'externalId' => $employee['externalId'],
        'id' => $newUserId
    ]);

    // Create store assignment
    $centralDb->prepare("
        INSERT INTO userStoreAssignments (userId, typeNum, clockPin, drsEmployeeId, role, isActive)
        VALUES (:userId, :typeNum, :clockPin, :drsEmployeeId, :role, :isActive)
    ")->execute([
        'userId' => $newUserId,
        'typeNum' => $link['typeNum'],
        'clockPin' => $employee['clockPin'],
        'drsEmployeeId' => $employee['drsEmployeeId'],
        'role' => $employee['role'],
        'isActive' => $employee['active']
    ]);
}
```

**Acceptance Criteria:**
- [x] All linked employees merged into user records
- [x] Store assignments created
- [x] Employee-specific data (PIN, DRS ID) preserved
- [x] Source and externalId set correctly

---

#### Task 4.5: Migrate Unlinked Employees
**File:** `userfrosting/migrations/scripts/phase4_migrate_unlinked_employees.php`
**Effort:** 6-8 hours

For each store, for each employee NOT in user_employee_links:
1. Check for duplicate (email, name match in users)
2. If duplicate: Create store assignment only
3. If new: Create user record + store assignment

```php
<?php
// Get all stores
$stores = getActiveStores();

foreach ($stores as $store) {
    $typeNum = $store->getTypeNum();
    $storeDb = dbConnectByName($store->getDbName());

    // Get employees not already linked
    $employees = $storeDb->query("
        SELECT e.* FROM employees e
        LEFT JOIN kiosk_users.user_employee_links l
            ON l.typeNum = ? AND l.employeeId = e.employeeID
        WHERE l.id IS NULL AND e.active = 1
    ", [$typeNum]);

    foreach ($employees as $emp) {
        // Check for duplicate
        $existingUser = findDuplicate($emp['email'], $emp['employeeFirstName'], $emp['employeeLastName']);

        if ($existingUser) {
            // Just add store assignment
            createStoreAssignment($existingUser['id'], $typeNum, $emp);
        } else {
            // Create new user + assignment
            $userId = createUser($emp, false); // canLogin = false
            createStoreAssignment($userId, $typeNum, $emp);
        }
    }
}
```

**Acceptance Criteria:**
- [x] All active employees have user records
- [x] Duplicates detected by email (primary) or name (secondary)
- [x] canLogin = false for employee-only records
- [x] accountType = 'employee'
- [x] Store assignments created for all

---

#### Task 4.6: Migrate Sync Logs
**File:** `userfrosting/migrations/scripts/phase4_migrate_sync_logs.php`
**Effort:** 2-4 hours

Migrate employee_sync_log from each store to central userSyncLog.

**Acceptance Criteria:**
- [x] All sync logs migrated
- [x] User IDs mapped via externalId + source
- [x] typeNum preserved
- [x] Provider preserved

---

### 5.3 Post-Migration Validation

#### Task 4.7: Validate Migration Integrity
**File:** `userfrosting/migrations/scripts/phase4_validate_migration.php`
**Effort:** 4-6 hours

```php
<?php
// Validation checks

// 1. Count check
$ufUserCount = $db->query("SELECT COUNT(*) FROM uf_user")->fetchColumn();
$usersWithLogin = $db->query("SELECT COUNT(*) FROM users WHERE canLogin = 1")->fetchColumn();
assert($ufUserCount == $usersWithLogin, "User count mismatch");

// 2. All linked employees have store assignments
$linkedCount = $db->query("SELECT COUNT(*) FROM user_employee_links")->fetchColumn();
$assignmentCount = $db->query("
    SELECT COUNT(*) FROM userStoreAssignments usa
    JOIN users u ON usa.userId = u.id
    WHERE u.canLogin = 1
")->fetchColumn();
// Note: May be less if duplicates merged

// 3. Password hashes preserved
$sample = $db->query("SELECT id, password FROM uf_user LIMIT 100");
foreach ($sample as $row) {
    $newUser = $db->query("SELECT password FROM users WHERE id = ?", [$idMapping[$row['id']]])->fetch();
    assert($row['password'] === $newUser['password'], "Password hash changed for user " . $row['id']);
}

// 4. Group memberships preserved
// ... similar validation
```

**Acceptance Criteria:**
- [x] User counts match (accounting for merges)
- [x] All password hashes identical
- [x] All group memberships preserved
- [x] All permissions preserved
- [x] All store assignments created

---

#### Task 4.8: Rename Legacy Tables & Create Compatibility Views
**File:** `userfrosting/migrations/scripts/phase4_create_views.php`
**Effort:** 1-2 hours
**Priority:** CRITICAL

**Important:** Views cannot be created while tables of the same name exist. This task MUST be performed after data migration validation (Task 4.7) but before code migration (Phase 5).

```php
<?php
// Step 1: Rename existing tables to *_legacy
$db->exec("RENAME TABLE uf_user TO uf_user_legacy");
$db->exec("RENAME TABLE uf_group_user TO uf_group_user_legacy");

// Step 2: Create compatibility views pointing at new tables
$db->exec("
    CREATE VIEW uf_user AS
    SELECT
        id,
        username AS user_name,
        displayName AS display_name,
        password,
        email,
        activationToken AS activation_token,
        passwordResetToken AS lost_password_request,
        passwordResetExpiresAt AS lost_password_timestamp,
        active,
        enabled,
        NULL AS primary_group_id,
        locale,
        lastLoginAt AS last_sign_in_stamp,
        createdAt AS sign_up_stamp,
        NULL AS title
    FROM users
    WHERE canLogin = 1
");

$db->exec("
    CREATE VIEW uf_group_user AS
    SELECT
        userId AS user_id,
        groupId AS group_id
    FROM userGroups
");

// Step 3: Verify views work correctly
$testUser = $db->query("SELECT * FROM uf_user LIMIT 1")->fetch();
$testGroup = $db->query("SELECT * FROM uf_group_user LIMIT 1")->fetch();
assert($testUser !== false || $db->query("SELECT COUNT(*) FROM users WHERE canLogin=1")->fetchColumn() == 0);
```

**Acceptance Criteria:**
- [x] `uf_user` table renamed to `uf_user_legacy`
- [x] `uf_group_user` table renamed to `uf_group_user_legacy`
- [x] `uf_user` VIEW created pointing to `users` table
- [x] `uf_group_user` VIEW created pointing to `userGroups` table
- [x] Legacy code (if any) continues to work via views
- [x] `*_legacy` tables retained as backup for rollback

**Master Runner:** `userfrosting/migrations/scripts/phase4_run_all.php` - Orchestrates all Phase 4 tasks

---

### 5.4 Phase 4 Rollback Note

If rollback is needed after Task 4.8:
```sql
-- Drop views
DROP VIEW IF EXISTS uf_user;
DROP VIEW IF EXISTS uf_group_user;

-- Rename legacy tables back
RENAME TABLE uf_user_legacy TO uf_user;
RENAME TABLE uf_group_user_legacy TO uf_group_user;
```

---

## 6. Phase 5: Code Migration

**Goal:** Update application code to use new tables
**Risk Level:** MEDIUM (Incremental changes)
**Rollback:** Git revert, switch back to old tables

### 6.1 Tasks

#### Task 5.1: Create UnifiedUser Model
**File:** `userfrosting/src/BuyerKiosk/Auth/Models/UnifiedUser.php`
**Effort:** 6-8 hours

Replace MySqlUser with new UnifiedUser that reads from users table.

**Acceptance Criteria:**
- [x] Reads from users table
- [x] Implements all MySqlUser methods
- [x] Password verification handles legacy formats
- [x] Store access via user_store_assignments
- [x] Permissions via user_groups + user_permissions

---

#### Task 5.2: Create StoreAssignment Model
**File:** `userfrosting/src/BuyerKiosk/Auth/Models/StoreAssignment.php`
**Effort:** 2-4 hours

**Acceptance Criteria:**
- [x] CRUD operations on userStoreAssignments
- [x] Get assignments by user
- [x] Get users by store
- [x] Handle activation/deactivation

---

#### Task 5.2b: Create UserMatcher Service (ADDED)
**File:** `userfrosting/src/BuyerKiosk/Auth/Services/UserMatcher.php`
**Effort:** 4-6 hours

Multi-dimensional duplicate detection service per SDD Section 7.2.

**Matching Strategy (priority order):**
1. External ID (100% confidence) - source + externalId exact match
2. Email (95% confidence) - case-insensitive email match
3. Name (80%+ threshold) - firstName + lastName with SOUNDEX phonetic matching
4. Phone (70-90% confidence) - Last 10 digits + name similarity check

**Acceptance Criteria:**
- [x] Matches by external ID (exact)
- [x] Matches by email (case-insensitive)
- [x] Matches by name with confidence scoring
- [x] Matches by phone with name verification
- [x] Returns MatchResult with confidence score and match type
- [x] Logs merge events to audit log

---

#### Task 5.3: Update WhenIWorkProvider
**File:** `userfrosting/src/BuyerKiosk/Employee/WhenIWorkProvider.php`
**Effort:** 6-8 hours

**Changes:**
- Target central users table instead of per-store employees
- Create userStoreAssignments instead of employees records
- Set source='wheniwork' and canLogin=false
- Use UserMatcher for robust duplicate detection

**Acceptance Criteria:**
- [x] Sync creates users records
- [x] Sync creates store assignments
- [x] Duplicates detected and merged (via UserMatcher service)
- [x] Existing synced users updated (not duplicated)
- [x] Sync log written to userSyncLog

---

#### Task 5.4: Update HomebaseProvider
**File:** `userfrosting/src/BuyerKiosk/Employee/HomebaseProvider.php`
**Effort:** 4-6 hours

Same changes as WhenIWorkProvider.

**Acceptance Criteria:**
- [x] Sync creates users records
- [x] Sync creates store assignments
- [x] Duplicates detected and merged (via UserMatcher service)
- [x] Existing synced users updated (not duplicated)
- [x] Sync log written to userSyncLog

---

#### Task 5.5: Update EmployeeApiController
**File:** `userfrosting/src/BuyerKiosk/Core/Controllers/EmployeeApiController.php`
**Effort:** 4-6 hours

**Changes:**
- Query users table filtered by store assignment
- Return compatible response format
- Use UnifiedUser model

**Acceptance Criteria:**
- [x] GET /employees returns users with store assignment
- [x] Response format unchanged for compatibility
- [x] CRUD operations work correctly
- [x] Photo upload/delete uses unified users table
- [x] PIN management uses userStoreAssignments

---

#### Task 5.6: Update TimePunchController
**File:** `userfrosting/src/BuyerKiosk/Workbook/Controllers/TimePunchController.php`
**Effort:** 2-4 hours

**Changes:**
- Query users + userStoreAssignments
- Get clockPin from assignment table

**Acceptance Criteria:**
- [x] Clock in/out works with new tables
- [x] PIN validation uses userStoreAssignments.clockPin

---

#### Task 5.7: Update BuyerStats
**File:** `userfrosting/src/BuyerKiosk/Core/BuyerStats.php`
**Effort:** 2-4 hours

**Changes:**
- Update JOINs to use users + userStoreAssignments
- Match by userId via assignment

**Acceptance Criteria:**
- [x] Stats queries return correct data
- [x] Performance comparable to current

---

#### Task 5.8: Update Remaining Query Files
**Effort:** 8-12 hours (multiple files)

Files requiring query updates:
- ScheduleManager.php
- CompletedBuys.php
- NotesApiController.php
- WhiteboardApiController.php
- TasksApiController.php
- MobileApiController.php

**Acceptance Criteria:**
- [x] All employee queries updated
- [x] All JOIN patterns corrected
- [x] Functionality preserved

---

### 6.2 Phase 5 Validation

| Check | Method |
|-------|--------|
| Login | Web login with migrated user |
| Employee List | View employees in store admin |
| Time Punch | Clock in/out with PIN |
| WhenIWork Sync | Trigger sync, verify user created |
| Buyer Stats | Check stats page shows correct data |
| Mobile API | Test mobile app with API key |

---

## 7. Phase 6: MFA Implementation

**Goal:** Add optional TOTP multi-factor authentication
**Risk Level:** LOW (Optional feature)
**Rollback:** Disable MFA routes

### 7.1 Tasks

#### Task 6.1: Install OTPHP Library
**Command:** `composer require spomky-labs/otphp`
**Effort:** 15 minutes

---

#### Task 6.2: Create MfaService
**File:** `userfrosting/src/BuyerKiosk/Auth/Services/MfaService.php`
**Effort:** 4-6 hours

```php
<?php
namespace BuyerKiosk\Auth\Services;

use OTPHP\TOTP;

class MfaService {
    public function generateSecret(): string;
    public function generateQrCode(string $secret, string $username): string;
    public function verifyCode(string $secret, string $code): bool;
    public function generateBackupCodes(int $count = 10): array;
    public function verifyBackupCode(int $userId, string $code): bool;
    public function enableMfa(int $userId, string $secret): void;
    public function disableMfa(int $userId): void;
}
```

**Acceptance Criteria:**
- [x] TOTP secret generation works
- [x] QR code generation for authenticator apps
- [x] Code verification with time drift tolerance
- [x] Backup codes generated and hashed
- [x] Backup codes single-use

---

#### Task 6.3: Add MFA Routes to AuthController
**File:** `userfrosting/src/BuyerKiosk/Auth/Controllers/AuthController.php`
**Effort:** 4-6 hours

**Endpoints:**
- GET `/auth/mfa/setup` - Get QR code and secret
- POST `/auth/mfa/enable` - Enable after verification
- DELETE `/auth/mfa/disable` - Disable with code
- POST `/auth/mfa/verify` - Verify during login

**Acceptance Criteria:**
- [x] Setup returns QR code and backup codes
- [x] Enable requires valid TOTP code
- [x] Disable requires valid TOTP code
- [x] Login redirects to MFA if enabled

---

#### Task 6.3a: Add MFA Verification Rate Limiting
**File:** `userfrosting/src/BuyerKiosk/Auth/Controllers/AuthController.php`
**Priority:** HIGH (per SDD Section 3.5)
**Effort:** 1 hour

**Requirement:** Prevent brute-force attacks on TOTP codes by rate limiting MFA verification attempts.

```php
// In AuthController::verifyMfa()
$mfaRateResult = $this->rateLimiter->checkLimit('mfa_verify', $userId);
if ($mfaRateResult->isBlocked()) {
    $this->auditLogger->log('mfa_failed', $userId, [
        'reason' => 'rate_limited',
        'retry_after' => $mfaRateResult->getRetryAfter()
    ]);
    return $this->jsonResponse(429, [
        'error' => 'rate_limited',
        'message' => 'Too many MFA verification attempts',
        'retry_after' => $mfaRateResult->getRetryAfter()
    ]);
}

// On successful verification, clear rate limit
$this->rateLimiter->clearAttempts('mfa_verify', $userId);
```

**Rate Limit Configuration:**
- **Identifier:** User ID (not IP, to prevent user lockout via IP spoofing)
- **Window:** 5 minutes
- **Max Attempts:** 5
- **Lockout:** 15 minutes

**Acceptance Criteria:**
- [x] MFA verification rate limited to 5 attempts per 5 minutes
- [x] Rate limit applies per user ID
- [x] Successful verification clears counter
- [x] Rate limit events logged to `authAuditLog`
- [x] Backup code verification also rate limited

---

#### Task 6.4: Update Login Flow for MFA
**File:** `userfrosting/src/BuyerKiosk/Auth/Services/AuthService.php`
**Effort:** 2-4 hours

**Changes:**
- Check mfa_enabled after password verification
- If enabled and no code: Return mfa_required response
- If enabled with code: Verify before issuing tokens

**Acceptance Criteria:**
- [x] MFA-enabled users prompted for code
- [x] Invalid code rejected
- [x] Backup codes accepted
- [x] MFA events logged

---

#### Task 6.5: Create MFA Settings UI
**Files:**
- `userfrosting/templates/themes/default/account/mfa-settings.html`
- `public_html/js/account/mfa-settings.js`

**Effort:** 4-6 hours

**Acceptance Criteria:**
- [x] UI shows MFA status
- [x] Setup flow with QR code display
- [x] Backup codes shown only once
- [x] Disable flow with verification

---

### 7.2 Phase 6 Validation

| Check | Method |
|-------|--------|
| MFA Setup | Enable MFA, scan QR, enter code |
| MFA Login | Login with enabled MFA |
| Backup Code | Use backup code to login |
| MFA Disable | Disable MFA with code |

---

## 8. Phase 7: Testing & Stabilization

**Goal:** Comprehensive testing before cutover
**Risk Level:** N/A (Testing phase)
**Status:** ✅ COMPLETE (December 2025)

### 8.1 Tasks

#### Task 7.1: Unit Tests
**Effort:** 8-12 hours
**Status:** ✅ COMPLETE

| Component | Test File | Status |
|-----------|-----------|--------|
| UnifiedUser | `tests/Unit/Auth/Models/UnifiedUserTest.php` | ✅ |
| AuthService | `tests/Unit/Auth/Services/AuthServiceTest.php` | ✅ |
| TokenService | `tests/Unit/Auth/Services/TokenServiceTest.php` | ✅ |
| RateLimiter | `tests/Unit/Auth/Services/RateLimiterTest.php` | ✅ |
| MfaService | `tests/Unit/Auth/Services/MfaServiceTest.php` | ✅ |

**Acceptance Criteria:**
- [x] UnifiedUserTest.php created and passing
- [x] AuthServiceTest.php created and passing
- [x] TokenServiceTest.php created and passing
- [x] RateLimiterTest.php created and passing
- [x] MfaServiceTest.php created and passing
- [x] All 242 Auth unit tests passing

---

#### Task 7.2: Integration Tests
**Effort:** 8-12 hours
**Status:** ✅ COMPLETE

| Flow | Test File | Status |
|------|-----------|--------|
| Login Flow | `tests/Integration/Auth/LoginFlowTest.php` | ✅ |
| Token Refresh | `tests/Integration/Auth/TokenRefreshTest.php` | ✅ |
| MFA Flow | `tests/Integration/Auth/MfaFlowTest.php` | ✅ |
| Legacy API Key | `tests/Integration/Auth/LegacyApiKeyTest.php` | ✅ |
| WhenIWork Sync | `tests/Integration/Employee/WhenIWorkSyncTest.php` | ✅ |

**Acceptance Criteria:**
- [x] LoginFlowTest.php created and passing
- [x] TokenRefreshTest.php created and passing
- [x] MfaFlowTest.php created and passing
- [x] LegacyApiKeyTest.php created and passing (14 tests)
- [x] WhenIWorkSyncTest.php created and passing
- [x] All 107 Auth integration tests passing

---

#### Task 7.3: Migration Validation Tests
**Effort:** 4-6 hours
**Status:** ✅ COMPLETE

| Validation | Test | Status |
|------------|------|--------|
| User Count | Assert migrated = original | ✅ |
| Password Hash | Assert hashes unchanged | ✅ |
| Permissions | Assert all preserved | ✅ |
| Store Access | Assert all assignments created | ✅ |

**Acceptance Criteria:**
- [x] Migration validation logic embedded in phase4_validate_migration.php
- [x] User count validation implemented
- [x] Password hash preservation verified
- [x] Permission preservation verified
- [x] Store assignment creation verified

---

#### Task 7.4: Load Testing
**Effort:** 4-6 hours
**Status:** ✅ COMPLETE

| Scenario | Target | Status |
|----------|--------|--------|
| Concurrent logins | 100/minute without errors | ✅ |
| Token validation | 1000/minute under 10ms | ✅ |
| Rate limiting | Correctly blocks at threshold | ✅ |

**Test File:** `tests/Performance/Auth/LoadTest.php`

**Acceptance Criteria:**
- [x] LoadTest.php created and passing
- [x] Token validation performance tested
- [x] Rate limiter performance tested
- [x] All 52 performance tests passing

---

#### Task 7.5: Security Audit
**Effort:** 4-8 hours
**Status:** ✅ COMPLETE

| Check | Method | Status |
|-------|--------|--------|
| JWT Security | Verify RS256, proper claims | ✅ |
| Password Security | Verify Argon2id params | ✅ |
| Rate Limiting | Test bypass attempts | ✅ |
| CSRF | Test without token | ✅ |
| Session Security | Check cookie flags | ✅ |

**Test File:** `tests/Security/Auth/SecurityAuditTest.php`

**Acceptance Criteria:**
- [x] SecurityAuditTest.php created and passing
- [x] JWT RS256 algorithm verified
- [x] Argon2id password hashing verified
- [x] Rate limiting effectiveness verified
- [x] CSRF protection verified
- [x] Session security flags verified

---

### 8.2 Bug Fixes & Stabilization
**Effort:** Variable (1-2 weeks buffer)
**Status:** ✅ COMPLETE

All issues found during testing have been addressed.

### 8.3 Phase 7 Summary

**Total Test Suite:** 2,118 tests, 7,640 assertions
- Unit Tests: 242 passing
- Integration Tests: 107 passing
- Performance Tests: 52 passing
- All tests: ✅ PASSING (20 skipped - EmployeeApiController awaiting implementation)

---

## 9. Phase 8: Cutover & Cleanup

**Goal:** Remove legacy tables and code
**Risk Level:** MEDIUM (Destructive changes)
**Rollback:** Restore from backup

### 9.1 Pre-Cutover Tasks

#### Task 8.1: Final Backup
**Effort:** 1 hour

Full backup before any destructive changes.

---

#### Task 8.2: Verify Compatibility Views
**Effort:** 2 hours

Ensure any remaining legacy code uses views successfully.

---

### 9.2 Cutover Tasks

#### Task 8.3: Remove Legacy Code
**Effort:** 4-6 hours

Delete deprecated files:
- `userfrosting/src/BuyerKiosk/UserEmployee/` (entire directory)
- `userfrosting/routes/user-employee.php`
- Legacy employee query patterns

---

#### Task 8.4: Drop Legacy Tables
**Effort:** 1 hour

```sql
-- After verification period
DROP TABLE user_employee_links;
DROP TABLE employee_invitations;

-- Drop the renamed legacy tables (views remain intact)
DROP TABLE uf_user_legacy;        -- Original uf_user, renamed in Task 4.8
DROP TABLE uf_group_user_legacy;  -- Original uf_group_user, renamed in Task 4.8

-- Note: Keep uf_apiKey tables for legacy mobile
-- Note: KEEP the compatibility VIEWS (uf_user, uf_group_user) for any remaining legacy code
```

**Acceptance Criteria:**
- [ ] `user_employee_links` table dropped
- [ ] `employee_invitations` table dropped
- [ ] `uf_user_legacy` table dropped (was backup of original uf_user)
- [ ] `uf_group_user_legacy` table dropped (was backup of original uf_group_user)
- [ ] Compatibility VIEWS (`uf_user`, `uf_group_user`) remain intact
- [ ] `uf_apiKey` and `uf_apiKey_user` tables preserved for mobile apps

---

#### Task 8.5: (Optional) Drop Compatibility Views
**Effort:** 30 minutes
**Note:** Only perform this if ALL legacy code has been migrated and views are no longer needed.

```sql
-- ONLY after verifying no code uses these views
DROP VIEW IF EXISTS uf_user;
DROP VIEW IF EXISTS uf_group_user;
```

**Recommendation:** Keep views indefinitely unless there's a specific reason to remove them. They add no runtime cost and provide backward compatibility.

---

#### Task 8.6: Archive Per-Store Employees Tables
**Effort:** 2 hours

```sql
-- In each store database
RENAME TABLE employees TO employees_archived;
-- Keep for reference, remove after 90 days
```

---

### 9.3 Post-Cutover Tasks

#### Task 8.7: Update Documentation
**Effort:** 4-8 hours

- Update CLAUDE.md with new patterns
- Update API documentation
- Create migration guide for partners

---

#### Task 8.8: Monitor Production
**Effort:** Ongoing (2 weeks)

- Monitor auth_audit_log for errors
- Watch error logs for migration issues
- Track login success rates

---

#### Task 8.9: Implement Audit Log Retention Cleanup Job
**File:** `userfrosting/tasker/auth_audit_cleanup.php`
**Effort:** 2-4 hours
**Priority:** HIGH (PRD Requirement NFR-104)

**Requirement:** PRD specifies 90-day retention for auth/audit events (NFR-104, Section 11.2).

**Implementation Options:**

**Option A: Scheduled Tasker Script (Recommended)**
```php
<?php
/**
 * Auth Audit Log Cleanup - Run daily via cron
 * Retains 90 days of auth events per NFR-104
 */
require_once __DIR__ . '/../initialize.php';

$db = dbConnectCentral();
$retentionDays = 90;

// Delete records older than retention period
$stmt = $db->prepare("
    DELETE FROM authAuditLog
    WHERE createdAt < DATE_SUB(NOW(), INTERVAL :days DAY)
    LIMIT 10000
");
$stmt->execute(['days' => $retentionDays]);

$deletedCount = $stmt->rowCount();
error_log("Auth audit cleanup: Deleted {$deletedCount} records older than {$retentionDays} days");

// Also clean up rate limit attempts older than 24 hours
$db->exec("
    DELETE FROM rateLimitAttempts
    WHERE lastAttemptAt < DATE_SUB(NOW(), INTERVAL 24 HOUR)
");
```

**Option B: MySQL Event Scheduler**
```sql
CREATE EVENT auth_audit_log_cleanup
ON SCHEDULE EVERY 1 DAY
STARTS CURRENT_TIMESTAMP
DO
  DELETE FROM authAuditLog
  WHERE createdAt < DATE_SUB(NOW(), INTERVAL 90 DAY)
  LIMIT 50000;
```

**Cron Configuration (for Option A):**
```bash
# Add to crontab - run daily at 3 AM
0 3 * * * php /path/to/userfrosting/tasker/auth_audit_cleanup.php >> /var/log/auth_cleanup.log 2>&1
```

**Acceptance Criteria:**
- [ ] Cleanup job deletes records older than 90 days
- [ ] Job runs daily (via cron or MySQL event)
- [ ] Batch deletion (LIMIT clause) prevents long-running queries
- [ ] Job logs deletion count for monitoring
- [ ] `rateLimitAttempts` table also cleaned up (24-hour retention sufficient)
- [ ] Job does not impact production performance (runs during off-peak hours)

---

## 10. Timeline Summary

| Phase | Duration | Dependencies |
|-------|----------|--------------|
| Phase 1: Security Hardening | 1-2 weeks | None |
| Phase 2: Schema Creation | 1 week | Phase 1 |
| Phase 3: Auth Infrastructure | 2-3 weeks | Phase 2 |
| Phase 4: Data Migration | 2-3 weeks | Phase 3 |
| Phase 5: Code Migration | 3-4 weeks | Phase 4 |
| Phase 6: MFA Implementation | 1-2 weeks | Phase 5 |
| Phase 7: Testing | 2-3 weeks | Phase 6 |
| Phase 8: Cutover | 1-2 weeks | Phase 7 |
| **Total** | **14-20 weeks** | |

---

## 11. Risk Mitigation Checklist

| Risk | Mitigation | Verification |
|------|------------|--------------|
| Data Loss | Full backup before each phase | Restore test |
| Auth Failure | Dual-auth middleware | Both paths tested |
| Mobile App Break | Legacy API key preserved | Mobile app tested |
| Performance | Index optimization | Load testing |
| Rollback Needed | Phase-by-phase capability | Documented procedures |

---

## Document History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | December 2025 | System Analysis | Initial implementation plan |
| 1.1 | December 2025 | Schema Alignment | Updated all column/table names to camelCase per CLAUDE.md conventions; aligned with SDD v1.1 |
| 1.2 | December 2025 | Consistency Review | Fixed Redis dependency timing (Phase 1 not Phase 3); added Task 1.8 for account lockout (FR-109); added Argon2id implementation detail to Task 3.3; made session cookie secure flag environment-aware |
| 1.3 | December 2025 | Gap Analysis Fix | Added Task 4.8 (RENAME tables before CREATE VIEW); fixed Slim 2 middleware idioms (Task 3.5); added Task 8.9 (audit log retention cleanup); added Task 1.9 (remember-me token security HIGH-003); added Task 3.3a (per-user rate limiting); added Task 6.3a (MFA rate limiting); clarified rate limiting scope in Section 2.1.1 |