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/Models/MfaBackupCode.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+final class MfaBackupCode extends Model
+{
+    protected $fillable = [
+        'user_id',
+        'code_hash',
+        'used',
+        'used_at',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'used' => 'boolean',
+            'used_at' => 'datetime',
+        ];
+    }
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function scopeUnused(Builder $query): Builder
+    {
+        return $query->where('used', false);
+    }
+}

api/app/Models/MfaEmailCode.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+final class MfaEmailCode extends Model
+{
+    protected $fillable = [
+        'user_id',
+        'code',
+        'expires_at',
+        'used',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'expires_at' => 'datetime',
+            'used' => 'boolean',
+        ];
+    }
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function scopeValid(Builder $query): Builder
+    {
+        return $query->where('used', false)
+            ->where('expires_at', '>', now());
+    }
+}

api/app/Models/TrustedDevice.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+final class TrustedDevice extends Model
+{
+    use HasUlids;
+
+    protected $fillable = [
+        'user_id',
+        'device_hash',
+        'device_name',
+        'ip_address',
+        'trusted_until',
+        'last_used_at',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'trusted_until' => 'datetime',
+            'last_used_at' => 'datetime',
+        ];
+    }
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function scopeActive(Builder $query): Builder
+    {
+        return $query->where('trusted_until', '>', now());
+    }
+}

api/app/Models/User.php

@@ -32,6 +32,11 @@ final class User extends Authenticatable
         'timezone',
         'locale',
         'avatar',
+        'mfa_enabled',
+        'mfa_method',
+        'mfa_secret',
+        'mfa_confirmed_at',
+        'mfa_enforced',
     ];
 
     public function getFullNameAttribute(): string
@@ -47,6 +52,7 @@ final class User extends Authenticatable
     protected $hidden = [
         'password',
         'remember_token',
+        'mfa_secret',
     ];
 
     protected function casts(): array
@@ -55,6 +61,9 @@ final class User extends Authenticatable
             'date_of_birth' => 'date',
             'email_verified_at' => 'datetime',
             'password' => 'hashed',
+            'mfa_enabled' => 'boolean',
+            'mfa_confirmed_at' => 'datetime',
+            'mfa_enforced' => 'boolean',
         ];
     }
 
@@ -92,6 +101,21 @@ final class User extends Authenticatable
         return $this->hasMany(UserOrganisationTag::class);
     }
 
+    public function mfaBackupCodes(): HasMany
+    {
+        return $this->hasMany(MfaBackupCode::class);
+    }
+
+    public function mfaEmailCodes(): HasMany
+    {
+        return $this->hasMany(MfaEmailCode::class);
+    }
+
+    public function trustedDevices(): HasMany
+    {
+        return $this->hasMany(TrustedDevice::class);
+    }
+
     public function tagsForOrganisation(string $organisationId): HasMany
     {
         return $this->organisationTags()->where('organisation_id', $organisationId);