feat: replace token-based impersonation with enterprise-grade header-based system

Replaces the insecure token-in-localStorage approach with a header-based
impersonation system backed by cache sessions and MFA verification.

Key changes:
- New impersonation_sessions audit table (immutable, ULID PK)
- MFA verification required to start impersonation (TOTP/email/backup)
- X-Impersonate-User header + HandleImpersonation middleware
- Per-request auth context swap (admin session never modified)
- IP pinning, sensitive route blocking, no nesting, sliding 60-min TTL
- Activity log auto-tagged with impersonated_by during sessions
- Frontend: sessionStorage, BroadcastChannel sync, countdown timer
- ImpersonateDialog with reason + MFA verification flow
- 26 comprehensive tests covering core, middleware, audit, lifecycle

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

api/app/Http/Controllers/Api/V1/Admin/AdminImpersonationController.php

@@ -4,39 +4,114 @@ declare(strict_types=1);
 
 namespace App\Http\Controllers\Api\V1\Admin;
 
+use App\Enums\MfaMethod;
 use App\Http\Controllers\Controller;
+use App\Http\Requests\Admin\StartImpersonationRequest;
 use App\Http\Resources\Admin\AdminUserResource;
+use App\Http\Resources\Admin\ImpersonationSessionResource;
 use App\Models\User;
 use App\Services\ImpersonationService;
+use App\Services\MfaService;
 use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
 
 final class AdminImpersonationController extends Controller
 {
     public function __construct(
         private readonly ImpersonationService $impersonationService,
+        private readonly MfaService $mfaService,
     ) {}
 
-    public function start(User $user): JsonResponse
+    /**
+     * Start impersonating a user.
+     * POST /admin/impersonate/{user}
+     */
+    public function start(StartImpersonationRequest $request, User $user): JsonResponse
     {
         /** @var User $admin */
         $admin = auth()->user();
-        $result = $this->impersonationService->start($admin, $user);
+
+        $session = $this->impersonationService->start(
+            admin: $admin,
+            targetUser: $user,
+            reason: $request->validated('reason'),
+            mfaCode: $request->validated('mfa_code'),
+            mfaMethod: MfaMethod::from($request->validated('mfa_method')),
+            ipAddress: $request->ip(),
+            userAgent: $request->userAgent(),
+        );
+
+        $session->load('targetUser.organisations');
 
         return $this->success([
-            'token' => $result['token'],
-            'user' => new AdminUserResource($result['user']->load('organisations')),
-            'admin_id' => $result['admin_id'],
+            'session' => new ImpersonationSessionResource($session),
+            'user' => new AdminUserResource($session->targetUser),
         ]);
     }
 
-    public function stop(): JsonResponse
+    /**
+     * Stop impersonation.
+     * POST /admin/stop-impersonation
+     * Called by the admin (without X-Impersonate-User header).
+     */
+    public function stop(Request $request): JsonResponse
     {
-        /** @var User $currentUser */
-        $currentUser = auth()->user();
-        $admin = $this->impersonationService->stop($currentUser);
+        /** @var User $admin */
+        $admin = $request->user();
+
+        $session = $this->impersonationService->getActiveSessionForAdmin($admin);
+
+        if (! $session) {
+            return $this->error('No active impersonation session.', 400);
+        }
+
+        $this->impersonationService->stop($session);
 
         return $this->success([
             'user' => new AdminUserResource($admin->load('organisations')),
         ]);
     }
+
+    /**
+     * Get impersonation status.
+     * GET /admin/impersonate/status
+     */
+    public function status(Request $request): JsonResponse
+    {
+        /** @var User $admin */
+        $admin = $request->user();
+
+        $session = $this->impersonationService->getActiveSessionForAdmin($admin);
+
+        if (! $session) {
+            return $this->success([
+                'active' => false,
+            ]);
+        }
+
+        $session->load('targetUser');
+
+        return $this->success([
+            'active' => true,
+            'session' => new ImpersonationSessionResource($session),
+        ]);
+    }
+
+    /**
+     * Send MFA email code for impersonation verification.
+     * POST /admin/impersonate/send-mfa-code
+     */
+    public function sendMfaCode(Request $request): JsonResponse
+    {
+        /** @var User $admin */
+        $admin = $request->user();
+
+        if (! $admin->mfa_enabled) {
+            return $this->error('MFA is not enabled.', 403);
+        }
+
+        $this->mfaService->sendEmailCode($admin);
+
+        return $this->success(null, 'Verification code sent.');
+    }
 }