feat: enterprise MFA with TOTP, email codes, backup codes, and trusted devices

Three verification methods (TOTP authenticator, email code, backup codes),
trusted device management with 30-day expiry, role-based enforcement for
super_admin and org_admin, admin reset capability, and full test coverage
(46 tests). Modifies login flow to support MFA challenge/response with
temporary session tokens stored in cache.

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

api/app/Http/Controllers/Api/V1/LoginController.php

@@ -4,10 +4,13 @@ declare(strict_types=1);
 
 namespace App\Http\Controllers\Api\V1;
 
+use App\Enums\MfaMethod;
 use App\Http\Controllers\Api\V1\Traits\SetAuthCookie;
 use App\Http\Controllers\Controller;
 use App\Http\Requests\Api\V1\LoginRequest;
 use App\Http\Resources\Api\V1\MeResource;
+use App\Models\User;
+use App\Services\MfaService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\Log;
@@ -16,9 +19,13 @@ final class LoginController extends Controller
 {
     use SetAuthCookie;
 
+    public function __construct(
+        private MfaService $mfaService,
+    ) {}
+
     public function __invoke(LoginRequest $request): JsonResponse
     {
-        if (!Auth::attempt($request->only('email', 'password'))) {
+        if (! Auth::attempt($request->only('email', 'password'))) {
             Log::warning('Failed login attempt', [
                 'email' => $request->validated('email'),
                 'ip' => $request->ip(),
@@ -28,7 +35,55 @@ final class LoginController extends Controller
             return $this->unauthorized('Invalid credentials');
         }
 
-        $user = Auth::user()->load([
+        $user = Auth::user();
+
+        // MFA enabled and confirmed — check trusted device or require MFA
+        if ($user->mfa_enabled && $user->mfa_confirmed_at) {
+            $fingerprint = $request->header('X-Device-Fingerprint');
+            if ($fingerprint && $this->mfaService->isDeviceTrusted($user, $fingerprint)) {
+                return $this->issueToken($user, $request);
+            }
+
+            // MFA required — return session token instead of auth token
+            Auth::guard('web')->logout();
+            $mfaSession = $this->mfaService->createMfaSession($user, $request->ip());
+
+            // Auto-send email code if email is the preferred method
+            if ($user->mfa_method === MfaMethod::EMAIL->value) {
+                try {
+                    $this->mfaService->sendEmailCode($user);
+                } catch (\DomainException) {
+                    // Rate limited — code was already sent recently
+                }
+            }
+
+            return response()->json([
+                'success' => true,
+                'mfa_required' => true,
+                ...$mfaSession,
+            ]);
+        }
+
+        // MFA required by policy but not yet set up — issue token with flag
+        if ($this->mfaService->isMfaRequired($user) && ! $user->mfa_enabled) {
+            $response = $this->issueToken($user, $request);
+            $data = $response->getData(true);
+            $data['mfa_setup_required'] = true;
+
+            $cookieName = $this->resolveCookieName($request);
+            $token = $user->createToken('auth-token')->plainTextToken;
+
+            return response()->json($data)
+                ->withCookie($this->makeAuthCookie($cookieName, $token));
+        }
+
+        // No MFA — issue token as normal
+        return $this->issueToken($user, $request);
+    }
+
+    private function issueToken(User $user, LoginRequest $request): JsonResponse
+    {
+        $user->load([
             'organisations',
             'roles',
             'permissions',