feat(auth): store 2FA recovery codes (encrypted) on users

Add the two_factor_recovery_codes column (encrypted:array) + User helpers
replaceRecoveryCodes / recoveryCodes / hasRecoveryCodes / useRecoveryCode
(one-time consumption). Hidden from serialization.

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

app/Models/User.php

@@ -8,9 +8,10 @@ use Illuminate\Database\Eloquent\Attributes\Hidden;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Notifications\Notifiable;
+use Illuminate\Support\Str;
 
 #[Fillable(['name', 'email', 'password', 'must_change_password', 'locale'])]
-#[Hidden(['password', 'remember_token', 'two_factor_secret'])]
+#[Hidden(['password', 'remember_token', 'two_factor_secret', 'two_factor_recovery_codes'])]
 class User extends Authenticatable
 {
     /** @use HasFactory<UserFactory> */
@@ -22,11 +23,53 @@ class User extends Authenticatable
             'email_verified_at' => 'datetime',
             'password' => 'hashed',
             'two_factor_secret' => 'encrypted',
+            'two_factor_recovery_codes' => 'encrypted:array',
             'two_factor_confirmed_at' => 'datetime',
             'must_change_password' => 'boolean',
         ];
     }
 
+    /** @return array<int, string> The 8 freshly generated one-time codes (also persisted). */
+    public function replaceRecoveryCodes(): array
+    {
+        $codes = array_map(
+            fn () => Str::random(10).'-'.Str::random(10),
+            range(1, 8),
+        );
+
+        $this->forceFill(['two_factor_recovery_codes' => $codes])->save();
+
+        return $codes;
+    }
+
+    /** @return array<int, string> */
+    public function recoveryCodes(): array
+    {
+        return $this->two_factor_recovery_codes ?? [];
+    }
+
+    public function hasRecoveryCodes(): bool
+    {
+        return count($this->recoveryCodes()) > 0;
+    }
+
+    /** Consume one recovery code (one-time). Returns true if it was valid + removed. */
+    public function useRecoveryCode(string $code): bool
+    {
+        $code = trim($code);
+        $codes = $this->recoveryCodes();
+
+        if (! in_array($code, $codes, true)) {
+            return false;
+        }
+
+        $this->forceFill([
+            'two_factor_recovery_codes' => array_values(array_filter($codes, fn ($c) => $c !== $code)),
+        ])->save();
+
+        return true;
+    }
+
     public function hasTwoFactorEnabled(): bool
     {
         return ! is_null($this->two_factor_confirmed_at) && ! is_null($this->two_factor_secret);

database/migrations/2026_06_14_000001_add_two_factor_recovery_codes_to_users_table.php

@@ -0,0 +1,22 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            $table->text('two_factor_recovery_codes')->nullable()->after('two_factor_secret');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            $table->dropColumn('two_factor_recovery_codes');
+        });
+    }
+};

tests/Feature/UserRecoveryCodesTest.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class UserRecoveryCodesTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_replace_generates_eight_unique_codes_and_persists(): void
+    {
+        $user = User::factory()->create();
+        $codes = $user->replaceRecoveryCodes();
+
+        $this->assertCount(8, $codes);
+        $this->assertCount(8, array_unique($codes));
+        $this->assertSame($codes, $user->fresh()->recoveryCodes());
+        $this->assertTrue($user->fresh()->hasRecoveryCodes());
+    }
+
+    public function test_use_recovery_code_consumes_once(): void
+    {
+        $user = User::factory()->create();
+        $codes = $user->replaceRecoveryCodes();
+        $one = $codes[0];
+
+        $this->assertTrue($user->useRecoveryCode(' '.$one.' ')); // trims
+        $this->assertFalse($user->fresh()->useRecoveryCode($one)); // already consumed
+        $this->assertFalse($user->fresh()->useRecoveryCode('not-a-code'));
+        $this->assertCount(7, $user->fresh()->recoveryCodes());
+    }
+}