feat(auth): dedicated backup-code 2FA view + route

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app/Livewire/Auth/TwoFactorBackup.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace App\Livewire\Auth;
+
+use App\Livewire\Concerns\CompletesTwoFactorChallenge;
+use App\Models\User;
+use Illuminate\Validation\ValidationException;
+use Livewire\Attributes\Layout;
+use Livewire\Attributes\Validate;
+use Livewire\Component;
+
+#[Layout('layouts.auth')]
+class TwoFactorBackup extends Component
+{
+    use CompletesTwoFactorChallenge;
+
+    #[Validate('required|string')]
+    public string $code = '';
+
+    public function mount()
+    {
+        if (! session()->has('2fa.user')) {
+            return $this->redirect(route('login'), navigate: true);
+        }
+    }
+
+    public function verify()
+    {
+        $this->validate();
+
+        $this->assertNotRateLimited();
+
+        $user = User::find(session('2fa.user'));
+
+        if (! $user || ! $user->hasTwoFactorEnabled()) {
+            session()->forget(['2fa.user', '2fa.remember']);
+            throw ValidationException::withMessages(['code' => __('auth.session_expired')]);
+        }
+
+        // Backup-only view: a one-time recovery code is the sole accepted credential (no TOTP).
+        if (! $user->useRecoveryCode($this->code)) {
+            $this->hitRateLimit();
+            throw ValidationException::withMessages(['code' => __('auth.invalid_code')]);
+        }
+
+        $this->clearRateLimit();
+
+        return $this->completeLogin($user);
+    }
+
+    public function render()
+    {
+        return view('livewire.auth.two-factor-backup')->title(__('auth.title_challenge'));
+    }
+}

resources/views/livewire/auth/two-factor-backup.blade.php

@@ -0,0 +1,39 @@
+@php
+    $fieldText = 'h-12 w-full rounded-md border border-line bg-inset px-3 text-center font-mono text-sm text-ink placeholder:text-ink-4 focus:border-accent/40 focus:outline-none';
+    $label = 'mb-1.5 block font-mono text-[11px] uppercase tracking-wider text-ink-3';
+    $err = 'mt-1.5 flex items-center gap-1.5 font-mono text-[11px] text-offline';
+@endphp
+
+<div class="space-y-7">
+    <div class="space-y-1.5">
+        <p class="font-mono text-[10px] font-semibold uppercase tracking-[0.18em] text-accent-text">{{ __('auth.two_factor') }}</p>
+        <h1 class="font-display text-2xl font-bold tracking-tight text-ink">{{ __('auth.backup_heading') }}</h1>
+        <p class="font-mono text-xs text-ink-3">{{ __('auth.backup_subtitle') }}</p>
+    </div>
+
+    <form wire:submit="verify" class="space-y-4">
+        <div>
+            <label for="code" class="{{ $label }}">{{ __('auth.challenge_backup_label') }}</label>
+            <input wire:model="code" id="code" inputmode="text" autocomplete="one-time-code" autofocus
+                   class="{{ $fieldText }}" placeholder="{{ __('auth.challenge_backup_placeholder') }}" />
+            @error('code') <p class="{{ $err }}"><x-icon name="alert" class="h-3.5 w-3.5 shrink-0" />{{ $message }}</p> @enderror
+        </div>
+
+        <x-btn variant="primary" size="lg" type="submit" class="w-full" wire:loading.attr="disabled" wire:target="verify">
+            <svg wire:loading wire:target="verify" class="h-4 w-4 animate-spin" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" aria-hidden="true"><path d="M21 12a9 9 0 1 1-6.219-8.56" stroke-linecap="round" /></svg>
+            <span wire:loading.remove wire:target="verify">{{ __('common.confirm') }}</span>
+            <span wire:loading wire:target="verify">{{ __('auth.checking') }}</span>
+        </x-btn>
+    </form>
+
+    <div class="flex flex-col items-center gap-2.5">
+        @if ($this->pendingHasTotp || $this->webauthnAvailable())
+            <a href="{{ route('two-factor.challenge') }}" wire:navigate class="inline-flex items-center gap-1.5 font-mono text-[11px] text-ink-4 transition-colors hover:text-ink-2">
+                <x-icon name="chevron-left" class="h-3.5 w-3.5" /> {{ __('auth.back_to_options') }}
+            </a>
+        @endif
+        <a href="{{ route('login') }}" wire:navigate class="inline-flex items-center gap-1.5 font-mono text-[11px] text-ink-4 transition-colors hover:text-ink-2">
+            <x-icon name="chevron-left" class="h-3.5 w-3.5" /> {{ __('auth.back_to_login') }}
+        </a>
+    </div>
+</div>

routes/web.php

@@ -47,6 +47,7 @@ Route::middleware('guest')->group(function () {
     Route::get('/forgot-password', Auth\ForgotPassword::class)->name('password.request');
     Route::get('/reset-password/{token}', Auth\ResetPassword::class)->name('password.reset');
     Route::get('/two-factor-challenge', Auth\TwoFactorChallenge::class)->name('two-factor.challenge');
+    Route::get('/two-factor-challenge/backup', Auth\TwoFactorBackup::class)->name('two-factor.challenge.backup');
 });
 
 Route::middleware('auth')->group(function () {

tests/Feature/TwoFactorBackupTest.php

@@ -0,0 +1,146 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Livewire\Auth\TwoFactorBackup;
+use App\Livewire\Auth\TwoFactorChallenge;
+use App\Models\User;
+use App\Models\WebauthnCredential;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Cache;
+use Livewire\Livewire;
+use PragmaRX\Google2FAQRCode\Google2FA;
+use Tests\TestCase;
+
+class TwoFactorBackupTest extends TestCase
+{
+    use RefreshDatabase;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        Cache::flush(); // start every test with empty rate-limit buckets
+    }
+
+    private function enrolledUser(): User
+    {
+        return User::factory()->create([
+            'two_factor_secret' => (new Google2FA)->generateSecretKey(),
+            'two_factor_confirmed_at' => now(),
+        ]);
+    }
+
+    private function keyOnlyUser(): User
+    {
+        $u = User::factory()->create();
+        WebauthnCredential::create(['user_id' => $u->id, 'name' => 'k', 'credential_id' => 'cid', 'public_key' => '{}', 'sign_count' => 0]);
+
+        return $u->fresh();
+    }
+
+    public function test_backup_code_logs_in_and_is_consumed(): void
+    {
+        $user = $this->enrolledUser();
+        $code = $user->replaceRecoveryCodes()[0];
+        session()->put('2fa.user', $user->id);
+
+        Livewire::test(TwoFactorBackup::class)
+            ->set('code', $code)
+            ->call('verify')
+            ->assertRedirect(route('dashboard'));
+
+        $this->assertAuthenticatedAs($user);
+        $this->assertFalse($user->fresh()->useRecoveryCode($code)); // consumed
+    }
+
+    public function test_invalid_backup_code_fails(): void
+    {
+        $user = $this->enrolledUser();
+        $user->replaceRecoveryCodes();
+        session()->put('2fa.user', $user->id);
+
+        Livewire::test(TwoFactorBackup::class)
+            ->set('code', 'nope-nope')
+            ->call('verify')
+            ->assertHasErrors('code');
+
+        $this->assertGuest();
+    }
+
+    public function test_a_totp_code_is_not_accepted_on_the_backup_view(): void
+    {
+        $user = $this->enrolledUser();
+        $user->replaceRecoveryCodes();
+        $totp = (new Google2FA)->getCurrentOtp($user->two_factor_secret);
+        session()->put('2fa.user', $user->id);
+
+        Livewire::test(TwoFactorBackup::class)
+            ->set('code', $totp)
+            ->call('verify')
+            ->assertHasErrors('code');
+
+        $this->assertGuest();
+    }
+
+    public function test_requires_a_pending_2fa_session(): void
+    {
+        Livewire::test(TwoFactorBackup::class)
+            ->assertRedirect(route('login'));
+    }
+
+    public function test_field_and_login_link_render(): void
+    {
+        $user = $this->enrolledUser();
+        $user->replaceRecoveryCodes();
+        session()->put('2fa.user', $user->id);
+
+        Livewire::test(TwoFactorBackup::class)
+            ->assertSee(__('auth.backup_heading'))
+            ->assertSee(__('auth.challenge_backup_placeholder')) // the backup field is present
+            ->assertSee(__('auth.back_to_login'));
+    }
+
+    public function test_back_to_options_shown_for_a_totp_user(): void
+    {
+        $user = $this->enrolledUser();
+        $user->replaceRecoveryCodes();
+        session()->put('2fa.user', $user->id);
+
+        Livewire::test(TwoFactorBackup::class)
+            ->assertSee(__('auth.back_to_options'));
+    }
+
+    public function test_back_to_options_hidden_for_key_only_without_secure_context(): void
+    {
+        // No domain configured → webauthnAvailable() false, pendingHasTotp false: backup is the
+        // only path, so the "back to options" link would loop straight back here and is hidden.
+        $user = $this->keyOnlyUser();
+        $user->replaceRecoveryCodes();
+        session()->put('2fa.user', $user->id);
+
+        Livewire::test(TwoFactorBackup::class)
+            ->assertDontSee(__('auth.back_to_options'))
+            ->assertSee(__('auth.back_to_login'));
+    }
+
+    public function test_failed_backup_attempts_share_the_rate_limit_with_the_main_challenge(): void
+    {
+        $user = $this->enrolledUser();
+        $codes = $user->replaceRecoveryCodes();
+        session()->put('2fa.user', $user->id);
+
+        // 5 wrong backup attempts trip the per-(user+IP) bucket (5/60s).
+        for ($i = 0; $i < 5; $i++) {
+            Livewire::test(TwoFactorBackup::class)->set('code', 'wrong-'.$i)->call('verify');
+        }
+
+        // A genuinely valid, unused backup code is now refused on the MAIN challenge by the
+        // SAME shared bucket — proving one counter spans both components.
+        Livewire::test(TwoFactorChallenge::class)
+            ->set('code', $codes[0])
+            ->call('verify')
+            ->assertHasErrors('code');
+
+        $this->assertGuest();
+    }
+}