1225 lines
48 KiB
Markdown
1225 lines
48 KiB
Markdown
# Optional, Pluggable 2FA Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Make 2FA optional and pluggable — the operator secures the account with TOTP, a security key (WebAuthn), both, or nothing — replacing forced-TOTP onboarding and the dedicated recovery-codes page (now a modal).
|
|
|
|
**Architecture:** `User` gains a per-factor predicate (`hasTotp()`) while `hasTwoFactorEnabled()` becomes "either factor". Onboarding stops forcing 2FA (only the password rotation stays forced). Recovery codes are generated on the first factor, cleared on the last, shown in a `wire-elements/modal`. The login challenge and Settings adapt to whichever factor(s) exist.
|
|
|
|
**Tech Stack:** Laravel 13, Livewire 3 (class-based), wire-elements/modal, pragmarx/google2fa-qrcode (TOTP), web-auth/webauthn-lib (WebAuthn), Tailwind v4, bilingual `lang/{de,en}` (R16).
|
|
|
|
**Spec:** `docs/superpowers/specs/2026-06-14-optional-pluggable-2fa-design.md`
|
|
|
|
---
|
|
|
|
## Conventions for every task
|
|
|
|
- Run all tooling in the container: `docker compose exec -T app php artisan test --filter <Name>`, `docker compose exec -T app ./vendor/bin/pint <files>`.
|
|
- UI strings are localized in **both** `lang/de/*` and `lang/en/*` with identical keys (R16); no emoji (R9).
|
|
- Destructive confirmations use `wire-elements/modal` (R5), never `confirm()`/`wire:confirm`.
|
|
- After the last task: rebuild assets, R12 browser verify (bare-IP, DE+EN), Codex review (R15) clean, then release.
|
|
|
|
## File Structure
|
|
|
|
| File | Responsibility | Change |
|
|
|---|---|---|
|
|
| `app/Models/User.php` | Factor predicates + recovery-code lifecycle | add `hasTotp()`, redefine `hasTwoFactorEnabled()`/`securityOnboarded()`, add `resetIfNoFactor()` |
|
|
| `app/Http/Middleware/EnsureSecurityOnboarded.php` | Onboarding gate | drop the 2FA redirect |
|
|
| `app/Livewire/Auth/PasswordChange.php` | Forced password rotation | redirect to dashboard |
|
|
| `app/Livewire/Auth/TwoFactorSetup.php` | TOTP enrollment | app layout, guard on `hasTotp()`, generate codes + open modal |
|
|
| `app/Livewire/Auth/TwoFactorChallenge.php` | Login second step | TOTP check only when `hasTotp()`; field gated |
|
|
| `app/Livewire/Auth/ForgotPassword.php` | Password recovery proof | TOTP check only when `hasTotp()` |
|
|
| `app/Livewire/Settings/Index.php` | Manage TOTP factor | remove-TOTP always allowed + `resetIfNoFactor()`; hint flag |
|
|
| `app/Livewire/Settings/WebauthnKeys.php` | Manage keys | gate on `available()` only; first-key codes; last-key reset |
|
|
| `app/Livewire/Modals/RecoveryCodes.php` (NEW) | Recovery-codes modal | show/download/regenerate |
|
|
| `resources/views/livewire/modals/recovery-codes.blade.php` (NEW) | Modal view | — |
|
|
| `app/Livewire/Auth/RecoveryCodes.php` (DELETE) | Old full-page recovery | removed |
|
|
| `resources/views/livewire/auth/recovery-codes.blade.php` (DELETE) | Old view | removed |
|
|
| `routes/web.php` | Routes | remove `two-factor.recovery`, keep download |
|
|
| `resources/views/livewire/auth/two-factor-challenge.blade.php` | Challenge UI | gate TOTP field |
|
|
| `resources/views/livewire/settings/index.blade.php` | Security tab | modal trigger, hint, TOTP remove |
|
|
| `resources/views/livewire/auth/forgot-password.blade.php` | Forgot copy | no-2FA note |
|
|
| `resources/views/livewire/auth/two-factor-setup.blade.php` | Setup page | (works under app layout) |
|
|
| `lang/{de,en}/auth.php`, `lang/{de,en}/settings.php` | Strings | new keys |
|
|
|
|
---
|
|
|
|
### Task 1: `User` factor semantics + recovery lifecycle
|
|
|
|
**Files:**
|
|
- Modify: `app/Models/User.php:85-98`
|
|
- Test: `tests/Feature/UserFactorSemanticsTest.php` (Create)
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `tests/Feature/UserFactorSemanticsTest.php`:
|
|
|
|
```php
|
|
<?php
|
|
|
|
namespace Tests\Feature;
|
|
|
|
use App\Models\User;
|
|
use App\Models\WebauthnCredential;
|
|
use Illuminate\Foundation\Testing\RefreshDatabase;
|
|
use Tests\TestCase;
|
|
|
|
class UserFactorSemanticsTest extends TestCase
|
|
{
|
|
use RefreshDatabase;
|
|
|
|
private function totpUser(): User
|
|
{
|
|
return User::factory()->create(['two_factor_secret' => 'S', 'two_factor_confirmed_at' => now()]);
|
|
}
|
|
|
|
private function keyUser(): 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_has_totp_only_reflects_totp(): void
|
|
{
|
|
$this->assertTrue($this->totpUser()->hasTotp());
|
|
$this->assertFalse($this->keyUser()->hasTotp());
|
|
}
|
|
|
|
public function test_has_two_factor_enabled_is_either_factor(): void
|
|
{
|
|
$this->assertTrue($this->totpUser()->hasTwoFactorEnabled());
|
|
$this->assertTrue($this->keyUser()->hasTwoFactorEnabled());
|
|
$this->assertFalse(User::factory()->create()->hasTwoFactorEnabled());
|
|
}
|
|
|
|
public function test_security_onboarded_is_password_rotation_only(): void
|
|
{
|
|
$this->assertTrue(User::factory()->create(['must_change_password' => false])->securityOnboarded());
|
|
$this->assertFalse(User::factory()->create(['must_change_password' => true])->securityOnboarded());
|
|
}
|
|
|
|
public function test_reset_if_no_factor_clears_codes_only_when_no_factor_remains(): void
|
|
{
|
|
$totp = $this->totpUser();
|
|
$totp->replaceRecoveryCodes();
|
|
$totp->resetIfNoFactor();
|
|
$this->assertTrue($totp->fresh()->hasRecoveryCodes(), 'codes kept while a factor remains');
|
|
|
|
$none = User::factory()->create();
|
|
$none->replaceRecoveryCodes();
|
|
$none->resetIfNoFactor();
|
|
$this->assertFalse($none->fresh()->hasRecoveryCodes(), 'codes cleared when no factor remains');
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Run it to confirm it fails**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter UserFactorSemanticsTest`
|
|
Expected: FAIL — `hasTotp()` / `resetIfNoFactor()` undefined.
|
|
|
|
- [ ] **Step 3: Implement the semantics**
|
|
|
|
In `app/Models/User.php`, replace the `hasTwoFactorEnabled()` + `securityOnboarded()` block (lines 85-98) with:
|
|
|
|
```php
|
|
/** TOTP factor only: an authenticator secret was confirmed. */
|
|
public function hasTotp(): bool
|
|
{
|
|
return ! is_null($this->two_factor_confirmed_at) && ! is_null($this->two_factor_secret);
|
|
}
|
|
|
|
/** 2FA is satisfied by EITHER factor — TOTP or a registered security key. */
|
|
public function hasTwoFactorEnabled(): bool
|
|
{
|
|
return $this->hasTotp() || $this->hasWebauthnCredentials();
|
|
}
|
|
|
|
/**
|
|
* Completed the security onboarding. 2FA is now OPTIONAL, so this is just the forced
|
|
* password rotation — the gate EnsureSecurityOnboarded and the broadcast channels use.
|
|
*/
|
|
public function securityOnboarded(): bool
|
|
{
|
|
return ! $this->must_change_password;
|
|
}
|
|
|
|
/**
|
|
* When neither factor remains (no TOTP, no keys), 2FA is fully off — so drop the backup
|
|
* codes (nothing left to recover into). Call after removing any factor.
|
|
*/
|
|
public function resetIfNoFactor(): void
|
|
{
|
|
if (! $this->hasTotp() && ! $this->hasWebauthnCredentials()) {
|
|
$this->forceFill(['two_factor_recovery_codes' => null])->save();
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Run the test to confirm it passes**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter UserFactorSemanticsTest`
|
|
Expected: PASS (4 tests).
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
docker compose exec -T app ./vendor/bin/pint app/Models/User.php tests/Feature/UserFactorSemanticsTest.php
|
|
git add app/Models/User.php tests/Feature/UserFactorSemanticsTest.php
|
|
git commit -m "feat(2fa): pluggable factor semantics on User (hasTotp, either-factor, resetIfNoFactor)"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 2: Onboarding stops forcing 2FA
|
|
|
|
**Files:**
|
|
- Modify: `app/Http/Middleware/EnsureSecurityOnboarded.php:20-28`
|
|
- Modify: `app/Livewire/Auth/PasswordChange.php:35-36`
|
|
- Test: `tests/Feature/OptionalOnboardingTest.php` (Create)
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `tests/Feature/OptionalOnboardingTest.php`:
|
|
|
|
```php
|
|
<?php
|
|
|
|
namespace Tests\Feature;
|
|
|
|
use App\Models\User;
|
|
use Illuminate\Foundation\Testing\RefreshDatabase;
|
|
use Livewire\Livewire;
|
|
use App\Livewire\Auth\PasswordChange;
|
|
use Tests\TestCase;
|
|
|
|
class OptionalOnboardingTest extends TestCase
|
|
{
|
|
use RefreshDatabase;
|
|
|
|
public function test_rotated_user_without_2fa_reaches_the_dashboard(): void
|
|
{
|
|
$user = User::factory()->create(['must_change_password' => false]);
|
|
|
|
$this->actingAs($user)->get('/')->assertOk();
|
|
}
|
|
|
|
public function test_user_that_must_change_password_is_still_redirected(): void
|
|
{
|
|
$user = User::factory()->create(['must_change_password' => true]);
|
|
|
|
$this->actingAs($user)->get('/')->assertRedirect(route('password.change'));
|
|
}
|
|
|
|
public function test_password_change_lands_on_dashboard_not_2fa_setup(): void
|
|
{
|
|
$user = User::factory()->create(['must_change_password' => true, 'password' => bcrypt('old-Password-1')]);
|
|
|
|
Livewire::actingAs($user)->test(PasswordChange::class)
|
|
->set('current', 'old-Password-1')
|
|
->set('password', 'new-Password-123')
|
|
->set('password_confirmation', 'new-Password-123')
|
|
->call('update')
|
|
->assertRedirect(route('dashboard'));
|
|
}
|
|
|
|
public function test_broadcast_gate_passes_on_password_rotation_alone(): void
|
|
{
|
|
$user = User::factory()->create(['must_change_password' => false]);
|
|
|
|
$this->assertTrue($user->securityOnboarded());
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Run it to confirm it fails**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter OptionalOnboardingTest`
|
|
Expected: FAIL — `/` redirects an un-enrolled user to `two-factor.setup`; PasswordChange redirects to `two-factor.setup`.
|
|
|
|
- [ ] **Step 3: Drop the 2FA redirect in the middleware**
|
|
|
|
In `app/Http/Middleware/EnsureSecurityOnboarded.php`, replace the body of `handle()` (lines 17-31) with:
|
|
|
|
```php
|
|
$user = $request->user();
|
|
|
|
if ($user && $user->must_change_password && ! $request->routeIs('password.change', 'logout')) {
|
|
return redirect()->route('password.change');
|
|
}
|
|
|
|
return $next($request);
|
|
```
|
|
|
|
Also update the class docblock (lines 9-12) to:
|
|
|
|
```php
|
|
/**
|
|
* After login, force the seeded-password rotation before the panel is reachable.
|
|
* 2FA is optional (offered in Settings), so it is NOT forced here.
|
|
*/
|
|
```
|
|
|
|
- [ ] **Step 4: Redirect PasswordChange to the dashboard**
|
|
|
|
In `app/Livewire/Auth/PasswordChange.php`, replace lines 35-36:
|
|
|
|
```php
|
|
// 2FA is optional now — go straight to the panel; 2FA is offered in Settings.
|
|
return $this->redirect(route('dashboard'), navigate: true);
|
|
```
|
|
|
|
- [ ] **Step 5: Run the test to confirm it passes**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter OptionalOnboardingTest`
|
|
Expected: PASS (4 tests).
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
docker compose exec -T app ./vendor/bin/pint app/Http/Middleware/EnsureSecurityOnboarded.php app/Livewire/Auth/PasswordChange.php tests/Feature/OptionalOnboardingTest.php
|
|
git add app/Http/Middleware/EnsureSecurityOnboarded.php app/Livewire/Auth/PasswordChange.php tests/Feature/OptionalOnboardingTest.php
|
|
git commit -m "feat(2fa): onboarding no longer forces 2FA (only password rotation)"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 3: Recovery-codes MODAL (replace the full-page view)
|
|
|
|
**Files:**
|
|
- Create: `app/Livewire/Modals/RecoveryCodes.php`
|
|
- Create: `resources/views/livewire/modals/recovery-codes.blade.php`
|
|
- Delete: `app/Livewire/Auth/RecoveryCodes.php`, `resources/views/livewire/auth/recovery-codes.blade.php`
|
|
- Modify: `routes/web.php:58` (remove `two-factor.recovery` route; keep download at 59-67)
|
|
- Modify: `lang/de/auth.php`, `lang/en/auth.php` (modal title key)
|
|
- Test: `tests/Feature/RecoveryCodesModalTest.php` (Create)
|
|
- Delete test: `tests/Feature/RecoveryCodesViewTest.php`
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `tests/Feature/RecoveryCodesModalTest.php`:
|
|
|
|
```php
|
|
<?php
|
|
|
|
namespace Tests\Feature;
|
|
|
|
use App\Livewire\Modals\RecoveryCodes;
|
|
use App\Models\User;
|
|
use Illuminate\Foundation\Testing\RefreshDatabase;
|
|
use Livewire\Livewire;
|
|
use Tests\TestCase;
|
|
|
|
class RecoveryCodesModalTest extends TestCase
|
|
{
|
|
use RefreshDatabase;
|
|
|
|
public function test_modal_lists_the_current_codes(): void
|
|
{
|
|
$user = User::factory()->create();
|
|
$codes = $user->replaceRecoveryCodes();
|
|
|
|
Livewire::actingAs($user)->test(RecoveryCodes::class)
|
|
->assertSee($codes[0])
|
|
->assertSee($codes[7]);
|
|
}
|
|
|
|
public function test_regenerate_replaces_the_codes(): void
|
|
{
|
|
$user = User::factory()->create();
|
|
$old = $user->replaceRecoveryCodes();
|
|
|
|
Livewire::actingAs($user)->test(RecoveryCodes::class)
|
|
->call('regenerate')
|
|
->assertDontSee($old[0]);
|
|
|
|
$this->assertNotEquals($old, $user->fresh()->recoveryCodes());
|
|
}
|
|
|
|
public function test_old_recovery_route_is_gone(): void
|
|
{
|
|
$this->assertFalse(\Illuminate\Support\Facades\Route::has('two-factor.recovery'));
|
|
$this->assertTrue(\Illuminate\Support\Facades\Route::has('two-factor.recovery.download'));
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Run it to confirm it fails**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter RecoveryCodesModalTest`
|
|
Expected: FAIL — `App\Livewire\Modals\RecoveryCodes` does not exist; `two-factor.recovery` still registered.
|
|
|
|
- [ ] **Step 3: Create the modal component**
|
|
|
|
Create `app/Livewire/Modals/RecoveryCodes.php`:
|
|
|
|
```php
|
|
<?php
|
|
|
|
namespace App\Livewire\Modals;
|
|
|
|
use App\Models\AuditEvent;
|
|
use Illuminate\Support\Facades\Auth;
|
|
use LivewireUI\Modal\ModalComponent;
|
|
|
|
/**
|
|
* Backup (recovery) codes, shown once in a modal. Opened on first-factor enrollment and
|
|
* from Settings → Security ("Backup-Codes verwalten"). The download endpoint stays a route.
|
|
*/
|
|
class RecoveryCodes extends ModalComponent
|
|
{
|
|
public static function modalMaxWidth(): string
|
|
{
|
|
return 'lg';
|
|
}
|
|
|
|
/** @return array<int, string> */
|
|
public function codes(): array
|
|
{
|
|
return Auth::user()->recoveryCodes();
|
|
}
|
|
|
|
/** Regenerate the current user's backup codes (invalidates the old set). */
|
|
public function regenerate(): void
|
|
{
|
|
Auth::user()->replaceRecoveryCodes();
|
|
|
|
AuditEvent::create([
|
|
'user_id' => Auth::id(),
|
|
'actor' => Auth::user()->name ?? 'system',
|
|
'action' => 'two_factor.recovery_regenerate',
|
|
'target' => Auth::user()->email,
|
|
'ip' => request()->ip(),
|
|
]);
|
|
|
|
$this->dispatch('notify', message: __('auth.recovery_regenerated'));
|
|
}
|
|
|
|
public function render()
|
|
{
|
|
return view('livewire.modals.recovery-codes', ['codes' => $this->codes()]);
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Create the modal view**
|
|
|
|
Create `resources/views/livewire/modals/recovery-codes.blade.php`:
|
|
|
|
```blade
|
|
<div class="p-5 sm:p-6">
|
|
<div class="flex items-start gap-3.5">
|
|
<span class="grid h-10 w-10 shrink-0 place-items-center rounded-md border border-accent/30 bg-accent/10 text-accent-text">
|
|
<x-icon name="shield" class="h-5 w-5" />
|
|
</span>
|
|
<div class="min-w-0 flex-1">
|
|
<h2 class="font-display text-base font-semibold text-ink">{{ __('auth.recovery_heading') }}</h2>
|
|
<p class="mt-1 text-sm leading-relaxed text-ink-2">{{ __('auth.recovery_subtitle') }}</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="mt-4 flex items-start gap-2.5 rounded-md border border-warning/25 bg-warning/10 px-4 py-3">
|
|
<x-icon name="alert" class="mt-0.5 h-4 w-4 shrink-0 text-warning" />
|
|
<p class="text-sm text-ink-2">{{ __('auth.recovery_warning') }}</p>
|
|
</div>
|
|
|
|
<div class="mt-4 grid grid-cols-1 gap-2 rounded-md border border-line bg-inset p-4 sm:grid-cols-2">
|
|
@foreach ($codes as $c)
|
|
<span class="font-mono text-sm tracking-wide text-ink">{{ $c }}</span>
|
|
@endforeach
|
|
</div>
|
|
|
|
<div class="mt-6 flex flex-wrap items-center gap-2">
|
|
<x-btn href="{{ route('two-factor.recovery.download') }}" variant="secondary">
|
|
<x-icon name="folder" class="h-3.5 w-3.5" /> {{ __('auth.recovery_download') }}
|
|
</x-btn>
|
|
<x-btn variant="secondary" wire:click="regenerate" wire:target="regenerate" wire:loading.attr="disabled">
|
|
<x-icon name="rotate" class="h-3.5 w-3.5" /> {{ __('auth.recovery_regenerate') }}
|
|
</x-btn>
|
|
<x-btn variant="primary" class="ml-auto" wire:click="$dispatch('closeModal')">{{ __('auth.recovery_done') }}</x-btn>
|
|
</div>
|
|
</div>
|
|
```
|
|
|
|
- [ ] **Step 5: Remove the old full-page route**
|
|
|
|
In `routes/web.php`, delete line 58 (the `two-factor.recovery` GET route) and adjust the comment block (lines 56-57) to:
|
|
|
|
```php
|
|
// 2FA backup-codes download — the codes themselves are shown in a modal (Modals\RecoveryCodes).
|
|
```
|
|
|
|
Keep the download route (lines 59-67) intact.
|
|
|
|
- [ ] **Step 6: Delete the old full-page component, view, and its test**
|
|
|
|
```bash
|
|
git rm app/Livewire/Auth/RecoveryCodes.php resources/views/livewire/auth/recovery-codes.blade.php tests/Feature/RecoveryCodesViewTest.php
|
|
```
|
|
|
|
- [ ] **Step 7: Add the modal title key (kept for parity; reuse existing recovery_* keys)**
|
|
|
|
No new key is strictly required — the modal reuses `auth.recovery_heading/subtitle/warning/download/regenerate/done`. Verify `lang/de/auth.php` and `lang/en/auth.php` still contain them (they do, lines ~78-85). Remove the now-unused `auth.title_recovery` key from both files (it titled the deleted page):
|
|
|
|
In `lang/de/auth.php` and `lang/en/auth.php`, delete the `'title_recovery' => …` line.
|
|
|
|
- [ ] **Step 8: Run the test to confirm it passes**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter RecoveryCodesModalTest`
|
|
Expected: PASS (3 tests).
|
|
|
|
- [ ] **Step 9: Commit**
|
|
|
|
```bash
|
|
docker compose exec -T app ./vendor/bin/pint app/Livewire/Modals/RecoveryCodes.php tests/Feature/RecoveryCodesModalTest.php
|
|
git add -A
|
|
git commit -m "feat(2fa): recovery codes become a modal; drop the dedicated page + route"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 4: First-factor code generation + open the modal
|
|
|
|
**Files:**
|
|
- Modify: `app/Livewire/Auth/TwoFactorSetup.php` (layout, mount guard, confirm flow)
|
|
- Modify: `app/Livewire/Settings/WebauthnKeys.php:28-47` (first-key codes)
|
|
- Modify: `app/Livewire/Settings/Index.php` (mount reads the flash to open the modal)
|
|
- Modify: `resources/views/livewire/settings/index.blade.php` (x-init opens modal on flash)
|
|
- Test: `tests/Feature/FirstFactorCodesTest.php` (Create)
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `tests/Feature/FirstFactorCodesTest.php`:
|
|
|
|
```php
|
|
<?php
|
|
|
|
namespace Tests\Feature;
|
|
|
|
use App\Livewire\Auth\TwoFactorSetup;
|
|
use App\Livewire\Settings\WebauthnKeys;
|
|
use App\Models\User;
|
|
use App\Models\WebauthnCredential;
|
|
use App\Services\WebauthnService;
|
|
use Illuminate\Foundation\Testing\RefreshDatabase;
|
|
use Livewire\Livewire;
|
|
use Mockery;
|
|
use PragmaRX\Google2FAQRCode\Google2FA;
|
|
use Tests\TestCase;
|
|
|
|
class FirstFactorCodesTest extends TestCase
|
|
{
|
|
use RefreshDatabase;
|
|
|
|
protected function tearDown(): void
|
|
{
|
|
Mockery::close();
|
|
parent::tearDown();
|
|
}
|
|
|
|
public function test_first_totp_confirm_generates_codes_and_opens_modal(): void
|
|
{
|
|
$user = User::factory()->create();
|
|
$g = new Google2FA;
|
|
$secret = $g->generateSecretKey();
|
|
|
|
$component = Livewire::actingAs($user)->test(TwoFactorSetup::class);
|
|
$component->set('secret', $secret)
|
|
->set('code', $g->getCurrentOtp($secret))
|
|
->call('confirm')
|
|
->assertRedirect(route('settings'));
|
|
|
|
$this->assertTrue($user->fresh()->hasRecoveryCodes());
|
|
$this->assertTrue(session('open_recovery_modal'));
|
|
}
|
|
|
|
public function test_first_key_register_generates_codes_and_opens_modal(): void
|
|
{
|
|
$user = User::factory()->create();
|
|
|
|
$svc = Mockery::mock(WebauthnService::class);
|
|
$svc->shouldReceive('available')->andReturnTrue();
|
|
$svc->shouldReceive('verifyRegistration')->andReturnUsing(fn ($u, $a, $name) => WebauthnCredential::create([
|
|
'user_id' => $u->id, 'name' => $name, 'credential_id' => 'cid', 'public_key' => '{}', 'sign_count' => 0,
|
|
]));
|
|
app()->instance(WebauthnService::class, $svc);
|
|
|
|
Livewire::actingAs($user)->test(WebauthnKeys::class)
|
|
->set('newName', 'YubiKey 5C')
|
|
->call('register', ['dummy' => true], $svc)
|
|
->assertDispatched('openModal');
|
|
|
|
$this->assertTrue($user->fresh()->hasRecoveryCodes());
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Run it to confirm it fails**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter FirstFactorCodesTest`
|
|
Expected: FAIL — TOTP confirm redirects to the removed `two-factor.recovery` route; key register does not generate codes nor dispatch `openModal`.
|
|
|
|
- [ ] **Step 3: Rework TwoFactorSetup**
|
|
|
|
In `app/Livewire/Auth/TwoFactorSetup.php`:
|
|
|
|
Change the layout attribute (line 12) to:
|
|
|
|
```php
|
|
#[Layout('layouts.app')]
|
|
```
|
|
|
|
Change `mount()` (lines 20-27) — guard on `hasTotp()` so a key-only user can still add TOTP:
|
|
|
|
```php
|
|
public function mount()
|
|
{
|
|
if (Auth::user()->hasTotp()) {
|
|
return $this->redirect(route('settings'), navigate: true);
|
|
}
|
|
|
|
$this->secret = (new Google2FA)->generateSecretKey();
|
|
}
|
|
```
|
|
|
|
Change `confirm()` (lines 29-46) — generate codes only if none exist, flash the modal flag, redirect to Settings:
|
|
|
|
```php
|
|
public function confirm()
|
|
{
|
|
$this->validate();
|
|
|
|
if (! (new Google2FA)->verifyKey($this->secret, preg_replace('/\s+/', '', $this->code))) {
|
|
throw ValidationException::withMessages(['code' => __('auth.code_mismatch')]);
|
|
}
|
|
|
|
Auth::user()->forceFill([
|
|
'two_factor_secret' => $this->secret,
|
|
'two_factor_confirmed_at' => now(),
|
|
])->save();
|
|
|
|
// First factor enrolled and no codes yet → generate the single recovery set and
|
|
// ask Settings to pop the modal (the app layout hosts wire-elements/modal).
|
|
if (! Auth::user()->hasRecoveryCodes()) {
|
|
Auth::user()->replaceRecoveryCodes();
|
|
session()->flash('open_recovery_modal', true);
|
|
}
|
|
|
|
return $this->redirect(route('settings'), navigate: true);
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Generate codes on the first key in WebauthnKeys::register()**
|
|
|
|
In `app/Livewire/Settings/WebauthnKeys.php`, inside `register()` after the credential is created (after line 35 `$this->reset('newName');`), insert:
|
|
|
|
```php
|
|
// First factor enrolled and no codes yet → generate + show the recovery modal.
|
|
if (! Auth::user()->hasRecoveryCodes()) {
|
|
Auth::user()->replaceRecoveryCodes();
|
|
$this->dispatch('openModal', component: 'modals.recovery-codes');
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 5: Settings opens the modal when the flash is set**
|
|
|
|
In `app/Livewire/Settings/Index.php`, extend `mount()` (lines 28-32) to land on the security tab and expose the flash:
|
|
|
|
```php
|
|
public bool $openRecoveryModal = false;
|
|
|
|
public function mount(): void
|
|
{
|
|
$this->name = Auth::user()->name;
|
|
$this->email = Auth::user()->email;
|
|
|
|
if (session('open_recovery_modal')) {
|
|
$this->tab = 'security';
|
|
$this->openRecoveryModal = true;
|
|
}
|
|
}
|
|
```
|
|
|
|
(Add the `public bool $openRecoveryModal = false;` property near the other public props, above `mount()`.)
|
|
|
|
- [ ] **Step 6: The security tab dispatches openModal via x-init when flagged**
|
|
|
|
In `resources/views/livewire/settings/index.blade.php`, immediately after the opening `<div class="space-y-5">` (line 13), add:
|
|
|
|
```blade
|
|
@if ($openRecoveryModal)
|
|
<div x-data x-init="$dispatch('openModal', { component: 'modals.recovery-codes' })"></div>
|
|
@endif
|
|
```
|
|
|
|
- [ ] **Step 7: Run the test to confirm it passes**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter FirstFactorCodesTest`
|
|
Expected: PASS (2 tests).
|
|
|
|
- [ ] **Step 8: Commit**
|
|
|
|
```bash
|
|
docker compose exec -T app ./vendor/bin/pint app/Livewire/Auth/TwoFactorSetup.php app/Livewire/Settings/WebauthnKeys.php app/Livewire/Settings/Index.php tests/Feature/FirstFactorCodesTest.php
|
|
git add -A
|
|
git commit -m "feat(2fa): generate recovery codes on the first factor + open the modal"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 5: Login challenge adapts to whichever factor exists
|
|
|
|
**Files:**
|
|
- Modify: `app/Livewire/Auth/TwoFactorChallenge.php:47-49` (verify) + add `hasTotp()` helper for the view
|
|
- Modify: `resources/views/livewire/auth/two-factor-challenge.blade.php` (gate the TOTP field)
|
|
- Test: `tests/Feature/ChallengeFactorAdaptTest.php` (Create)
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `tests/Feature/ChallengeFactorAdaptTest.php`:
|
|
|
|
```php
|
|
<?php
|
|
|
|
namespace Tests\Feature;
|
|
|
|
use App\Livewire\Auth\TwoFactorChallenge;
|
|
use App\Models\User;
|
|
use App\Models\WebauthnCredential;
|
|
use Illuminate\Foundation\Testing\RefreshDatabase;
|
|
use Livewire\Livewire;
|
|
use Tests\TestCase;
|
|
|
|
class ChallengeFactorAdaptTest extends TestCase
|
|
{
|
|
use RefreshDatabase;
|
|
|
|
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_key_only_user_has_no_totp_field_but_a_backup_code_works(): void
|
|
{
|
|
$user = $this->keyOnlyUser();
|
|
$codes = $user->replaceRecoveryCodes();
|
|
session(['2fa.user' => $user->id, '2fa.remember' => false]);
|
|
|
|
Livewire::test(TwoFactorChallenge::class)
|
|
->assertSet('pendingHasTotp', false)
|
|
->set('code', $codes[0])
|
|
->call('verify')
|
|
->assertRedirect(route('dashboard'));
|
|
|
|
$this->assertAuthenticatedAs($user);
|
|
}
|
|
|
|
public function test_totp_user_sees_the_field(): void
|
|
{
|
|
$user = User::factory()->create(['two_factor_secret' => 'S', 'two_factor_confirmed_at' => now()]);
|
|
session(['2fa.user' => $user->id, '2fa.remember' => false]);
|
|
|
|
Livewire::test(TwoFactorChallenge::class)->assertSet('pendingHasTotp', true);
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Run it to confirm it fails**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter ChallengeFactorAdaptTest`
|
|
Expected: FAIL — `pendingHasTotp` is not defined; `verify()` calls `Google2FA::verifyKey()` with a null secret for the key-only user (error/false before the backup-code fallback is reached safely).
|
|
|
|
- [ ] **Step 3: Guard the TOTP check + expose the predicate**
|
|
|
|
In `app/Livewire/Auth/TwoFactorChallenge.php`:
|
|
|
|
Add a public computed property for the view. After `mount()` (line 26), add:
|
|
|
|
```php
|
|
/** Whether the PENDING user has TOTP — the code field renders only then. */
|
|
public function getPendingHasTotpProperty(): bool
|
|
{
|
|
return (bool) User::find(session('2fa.user'))?->hasTotp();
|
|
}
|
|
```
|
|
|
|
Replace the TOTP-or-backup check (lines 47-49) with a guarded version:
|
|
|
|
```php
|
|
// Accept the TOTP code only when the pending user actually has TOTP, otherwise a
|
|
// null secret would break verifyKey; always allow a one-time backup (recovery) code.
|
|
$valid = ($user->hasTotp() && (new Google2FA)->verifyKey($user->two_factor_secret, preg_replace('/\s+/', '', $this->code)))
|
|
|| $user->useRecoveryCode($this->code);
|
|
```
|
|
|
|
> Note: Livewire exposes `getPendingHasTotpProperty()` to Blade as `$pendingHasTotp` and to `assertSet('pendingHasTotp', …)`.
|
|
|
|
- [ ] **Step 4: Gate the TOTP field in the view**
|
|
|
|
In `resources/views/livewire/auth/two-factor-challenge.blade.php`, wrap the code `<input>`/label block in `@if ($this->pendingHasTotp) … @endif`, and make the backup-code hint always available. Read the file first; the field is the `wire:model="code"` input group. Replace its surrounding block with:
|
|
|
|
```blade
|
|
@if ($this->pendingHasTotp)
|
|
{{-- existing TOTP code label + input group, unchanged --}}
|
|
@endif
|
|
```
|
|
|
|
Keeping: the "Mit Security-Key anmelden" button (already gated by `$this->webauthnAvailable()`), and the backup-code hint (`auth.challenge_recovery_hint`). For a key-only user the `code` input must still be reachable to type a backup code — if the only input was inside the `@if`, add a single shared code input shown when `! $this->pendingHasTotp` too, labelled with `auth.challenge_recovery_hint`. Concretely, structure the form as:
|
|
|
|
```blade
|
|
<div>
|
|
<label class="{{ $label }}">
|
|
{{ $this->pendingHasTotp ? __('auth.challenge_code_label') : __('auth.challenge_backup_label') }}
|
|
</label>
|
|
<input wire:model="code" inputmode="numeric" autocomplete="one-time-code" autofocus
|
|
placeholder="{{ $this->pendingHasTotp ? __('auth.challenge_code_placeholder') : __('auth.challenge_backup_placeholder') }}"
|
|
class="{{ $field }} font-mono tracking-[0.3em]" />
|
|
@error('code') <p class="{{ $err }}"><x-icon name="alert" class="h-3.5 w-3.5 shrink-0" />{{ $message }}</p> @enderror
|
|
</div>
|
|
```
|
|
|
|
> The single `code` input serves TOTP for a TOTP user and a backup code for a key-only user; `verify()` already tries both paths. Match the existing `$label`/`$field`/`$err` locals at the top of the view (read it; they mirror the login view). If those locals are absent, reuse the classes already present on the existing input.
|
|
|
|
- [ ] **Step 5: Add the new challenge label keys (de + en)**
|
|
|
|
In `lang/de/auth.php` add (near the other `challenge_*` keys):
|
|
|
|
```php
|
|
'challenge_code_label' => 'Authenticator-Code',
|
|
'challenge_code_placeholder' => '123456',
|
|
'challenge_backup_label' => 'Backup-Code',
|
|
'challenge_backup_placeholder' => 'xxxxxxxxxx-xxxxxxxxxx',
|
|
```
|
|
|
|
In `lang/en/auth.php` add the same keys:
|
|
|
|
```php
|
|
'challenge_code_label' => 'Authenticator code',
|
|
'challenge_code_placeholder' => '123456',
|
|
'challenge_backup_label' => 'Backup code',
|
|
'challenge_backup_placeholder' => 'xxxxxxxxxx-xxxxxxxxxx',
|
|
```
|
|
|
|
(If `challenge_code_label`/`challenge_code_placeholder` already exist in the file, reuse them and only add the two `challenge_backup_*` keys.)
|
|
|
|
- [ ] **Step 6: Run the test to confirm it passes**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter ChallengeFactorAdaptTest`
|
|
Expected: PASS (2 tests).
|
|
|
|
- [ ] **Step 7: Commit**
|
|
|
|
```bash
|
|
docker compose exec -T app ./vendor/bin/pint app/Livewire/Auth/TwoFactorChallenge.php tests/Feature/ChallengeFactorAdaptTest.php
|
|
git add -A
|
|
git commit -m "feat(2fa): challenge adapts to factor — TOTP field gated, key-only uses backup code"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 6: Settings — manage factors independently
|
|
|
|
**Files:**
|
|
- Modify: `app/Livewire/Settings/Index.php:77-90` (disableTwoFactor → remove TOTP + reset)
|
|
- Modify: `app/Livewire/Settings/WebauthnKeys.php:20,32,97` (gate on `available()` only; last-key reset)
|
|
- Modify: `resources/views/livewire/settings/index.blade.php` (TOTP card always removable, "empfohlen" hint, recovery modal trigger)
|
|
- Modify: `lang/{de,en}/settings.php` (hint + TOTP-remove keys)
|
|
- Test: `tests/Feature/SettingsFactorManagementTest.php` (Create)
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `tests/Feature/SettingsFactorManagementTest.php`:
|
|
|
|
```php
|
|
<?php
|
|
|
|
namespace Tests\Feature;
|
|
|
|
use App\Livewire\Settings\Index;
|
|
use App\Livewire\Settings\WebauthnKeys;
|
|
use App\Models\User;
|
|
use App\Models\WebauthnCredential;
|
|
use App\Services\WebauthnService;
|
|
use Illuminate\Foundation\Testing\RefreshDatabase;
|
|
use Livewire\Livewire;
|
|
use Mockery;
|
|
use Tests\TestCase;
|
|
|
|
class SettingsFactorManagementTest extends TestCase
|
|
{
|
|
use RefreshDatabase;
|
|
|
|
protected function tearDown(): void
|
|
{
|
|
Mockery::close();
|
|
parent::tearDown();
|
|
}
|
|
|
|
public function test_removing_totp_when_it_is_the_only_factor_clears_codes(): void
|
|
{
|
|
$user = User::factory()->create(['two_factor_secret' => 'S', 'two_factor_confirmed_at' => now()]);
|
|
$user->replaceRecoveryCodes();
|
|
|
|
Livewire::actingAs($user)->test(Index::class)->call('disableTwoFactor');
|
|
|
|
$fresh = $user->fresh();
|
|
$this->assertFalse($fresh->hasTotp());
|
|
$this->assertFalse($fresh->hasRecoveryCodes(), 'last factor removed → codes cleared');
|
|
}
|
|
|
|
public function test_removing_totp_keeps_codes_when_a_key_remains(): void
|
|
{
|
|
$user = User::factory()->create(['two_factor_secret' => 'S', 'two_factor_confirmed_at' => now()]);
|
|
WebauthnCredential::create(['user_id' => $user->id, 'name' => 'k', 'credential_id' => 'cid', 'public_key' => '{}', 'sign_count' => 0]);
|
|
$user->replaceRecoveryCodes();
|
|
|
|
Livewire::actingAs($user->fresh())->test(Index::class)->call('disableTwoFactor');
|
|
|
|
$fresh = $user->fresh();
|
|
$this->assertFalse($fresh->hasTotp());
|
|
$this->assertTrue($fresh->hasWebauthnCredentials());
|
|
$this->assertTrue($fresh->hasRecoveryCodes(), 'key remains → codes kept');
|
|
}
|
|
|
|
public function test_a_key_can_be_the_first_factor_without_existing_2fa(): void
|
|
{
|
|
$user = User::factory()->create(); // no TOTP, no key
|
|
|
|
$svc = Mockery::mock(WebauthnService::class);
|
|
$svc->shouldReceive('available')->andReturnTrue();
|
|
$svc->shouldReceive('registrationOptions')->andReturn(['ok' => true]);
|
|
app()->instance(WebauthnService::class, $svc);
|
|
|
|
// options() must NOT 404 just because the user has no 2FA yet.
|
|
Livewire::actingAs($user)->test(WebauthnKeys::class)
|
|
->set('newName', 'YubiKey')
|
|
->call('options', $svc)
|
|
->assertReturned(['ok' => true]);
|
|
}
|
|
|
|
public function test_removing_the_last_key_clears_codes(): void
|
|
{
|
|
$user = User::factory()->create();
|
|
$cred = WebauthnCredential::create(['user_id' => $user->id, 'name' => 'k', 'credential_id' => 'cid', 'public_key' => '{}', 'sign_count' => 0]);
|
|
$user->replaceRecoveryCodes();
|
|
|
|
$svc = Mockery::mock(WebauthnService::class);
|
|
$svc->shouldReceive('available')->andReturnTrue();
|
|
app()->instance(WebauthnService::class, $svc);
|
|
|
|
Livewire::actingAs($user->fresh())->test(WebauthnKeys::class)->call('remove', $cred->id, $svc);
|
|
|
|
$this->assertFalse($user->fresh()->hasRecoveryCodes());
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Run it to confirm it fails**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter SettingsFactorManagementTest`
|
|
Expected: FAIL — `disableTwoFactor` nukes keys + does not reset codes conditionally; `WebauthnKeys::options()`/`register()` 404 without `hasTwoFactorEnabled()`; `remove()` does not reset codes.
|
|
|
|
- [ ] **Step 3: Reframe `disableTwoFactor` to remove only TOTP**
|
|
|
|
In `app/Livewire/Settings/Index.php`, replace `disableTwoFactor()` (lines 77-90) with:
|
|
|
|
```php
|
|
#[On('twoFactorDisabled')]
|
|
public function disableTwoFactor(): void
|
|
{
|
|
// Remove the TOTP factor only — security keys are managed on their own card. If no
|
|
// factor remains afterwards, the backup codes are dropped too.
|
|
Auth::user()->forceFill([
|
|
'two_factor_secret' => null,
|
|
'two_factor_confirmed_at' => null,
|
|
])->save();
|
|
|
|
Auth::user()->resetIfNoFactor();
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Gate WebauthnKeys on `available()` only + reset on last-key removal**
|
|
|
|
In `app/Livewire/Settings/WebauthnKeys.php`:
|
|
|
|
`options()` line 20 — drop the 2FA requirement:
|
|
|
|
```php
|
|
abort_unless($webauthn->available(), 404);
|
|
```
|
|
|
|
`register()` line 32 — same:
|
|
|
|
```php
|
|
abort_unless($webauthn->available(), 404);
|
|
```
|
|
|
|
`remove()` — after the credential is deleted and audited (after line 90 `$this->dispatch('notify', …)`), add the reset:
|
|
|
|
```php
|
|
Auth::user()->resetIfNoFactor();
|
|
```
|
|
|
|
`render()` line 97 — the key card is available purely on the service gate now:
|
|
|
|
```php
|
|
'available' => app(WebauthnService::class)->available(),
|
|
```
|
|
|
|
- [ ] **Step 5: Settings security tab — TOTP always removable, hint, modal trigger**
|
|
|
|
In `resources/views/livewire/settings/index.blade.php`, replace the 2FA panel block (lines 99-119) with:
|
|
|
|
```blade
|
|
<x-panel :title="__('settings.twofa_title')" :subtitle="__('settings.twofa_subtitle')">
|
|
@unless ($twoFactorEnabled)
|
|
<div class="mb-4 flex items-start gap-2.5 rounded-md border border-accent/25 bg-accent/10 px-4 py-3">
|
|
<x-icon name="shield" class="mt-0.5 h-4 w-4 shrink-0 text-accent-text" />
|
|
<p class="text-sm text-ink-2">{{ __('settings.twofa_recommended') }}</p>
|
|
</div>
|
|
@endunless
|
|
|
|
<div class="flex flex-wrap items-center justify-between gap-3">
|
|
<div class="flex items-center gap-3">
|
|
<x-status-dot :status="$hasTotp ? 'online' : 'offline'" />
|
|
<div>
|
|
<p class="text-sm text-ink">{{ $hasTotp ? __('settings.twofa_status_on') : __('settings.twofa_status_off') }}</p>
|
|
<p class="font-mono text-[11px] text-ink-3">{{ $hasTotp ? __('settings.twofa_hint_on') : __('settings.twofa_hint_off') }}</p>
|
|
</div>
|
|
</div>
|
|
<div class="flex items-center gap-2">
|
|
@if ($twoFactorEnabled)
|
|
<x-btn variant="secondary" wire:click="$dispatch('openModal', { component: 'modals.recovery-codes' })">{{ __('auth.recovery_manage') }}</x-btn>
|
|
@endif
|
|
@if ($hasTotp)
|
|
<x-btn variant="danger-soft" wire:click="confirmDisableTwoFactor">{{ __('settings.twofa_remove_totp') }}</x-btn>
|
|
@else
|
|
<x-btn variant="accent" :href="route('two-factor.setup')" wire:navigate>
|
|
<x-icon name="shield" class="h-3.5 w-3.5" /> {{ __('settings.twofa_setup') }}
|
|
</x-btn>
|
|
@endif
|
|
</div>
|
|
</div>
|
|
</x-panel>
|
|
|
|
<livewire:settings.webauthn-keys />
|
|
```
|
|
|
|
- [ ] **Step 6: Pass `hasTotp` into the Settings view**
|
|
|
|
In `app/Livewire/Settings/Index.php`, `render()` — add `hasTotp` alongside `twoFactorEnabled`:
|
|
|
|
```php
|
|
return view('livewire.settings.index', [
|
|
'twoFactorEnabled' => Auth::user()->hasTwoFactorEnabled(),
|
|
'hasTotp' => Auth::user()->hasTotp(),
|
|
])->title(__('settings.title'));
|
|
```
|
|
|
|
- [ ] **Step 7: Add the new settings keys (de + en)**
|
|
|
|
In `lang/de/settings.php` add:
|
|
|
|
```php
|
|
'twofa_recommended' => '2FA ist optional, aber empfohlen — sichere dein Konto mit einem Authenticator oder Security-Key.',
|
|
'twofa_remove_totp' => 'Authenticator entfernen',
|
|
```
|
|
|
|
In `lang/en/settings.php` add:
|
|
|
|
```php
|
|
'twofa_recommended' => '2FA is optional but recommended — secure your account with an authenticator or a security key.',
|
|
'twofa_remove_totp' => 'Remove authenticator',
|
|
```
|
|
|
|
- [ ] **Step 8: Run the test to confirm it passes**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter SettingsFactorManagementTest`
|
|
Expected: PASS (4 tests).
|
|
|
|
- [ ] **Step 9: Update the disable-2FA confirm copy (it no longer nukes keys)**
|
|
|
|
In `lang/de/settings.php` and `lang/en/settings.php`, soften `disable_2fa_heading`/`disable_2fa_body`/`disable_2fa_notify` to refer to the **authenticator** only (not "2FA"), e.g. DE `disable_2fa_heading` → `'Authenticator entfernen'`, `disable_2fa_body` → `'Den Authenticator (TOTP) als Faktor entfernen? Security-Keys bleiben bestehen.'`. Mirror in EN. (Read both files; keep keys, change values.)
|
|
|
|
- [ ] **Step 10: Commit**
|
|
|
|
```bash
|
|
docker compose exec -T app ./vendor/bin/pint app/Livewire/Settings/Index.php app/Livewire/Settings/WebauthnKeys.php tests/Feature/SettingsFactorManagementTest.php
|
|
git add -A
|
|
git commit -m "feat(2fa): Settings manages TOTP + keys independently; key can be the only factor; empfohlen hint"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 7: forgot-password — key-only safe + no-2FA copy
|
|
|
|
**Files:**
|
|
- Modify: `app/Livewire/Auth/ForgotPassword.php:66-68` (guard verifyKey on hasTotp)
|
|
- Modify: `resources/views/livewire/auth/forgot-password.blade.php` (no-2FA note)
|
|
- Modify: `lang/{de,en}/auth.php` (no-2FA reset note)
|
|
- Test: `tests/Feature/ForgotPasswordKeyOnlyTest.php` (Create)
|
|
|
|
- [ ] **Step 1: Write the failing test**
|
|
|
|
Create `tests/Feature/ForgotPasswordKeyOnlyTest.php`:
|
|
|
|
```php
|
|
<?php
|
|
|
|
namespace Tests\Feature;
|
|
|
|
use App\Livewire\Auth\ForgotPassword;
|
|
use App\Models\User;
|
|
use App\Models\WebauthnCredential;
|
|
use Illuminate\Foundation\Testing\RefreshDatabase;
|
|
use Livewire\Livewire;
|
|
use Tests\TestCase;
|
|
|
|
class ForgotPasswordKeyOnlyTest extends TestCase
|
|
{
|
|
use RefreshDatabase;
|
|
|
|
public function test_key_only_user_resets_with_a_backup_code(): void
|
|
{
|
|
$user = User::factory()->create(['must_change_password' => false]);
|
|
WebauthnCredential::create(['user_id' => $user->id, 'name' => 'k', 'credential_id' => 'cid', 'public_key' => '{}', 'sign_count' => 0]);
|
|
$codes = $user->fresh()->replaceRecoveryCodes();
|
|
|
|
Livewire::test(ForgotPassword::class)
|
|
->set('email', $user->email)
|
|
->set('code', $codes[0])
|
|
->set('password', 'brand-New-Pass-9')
|
|
->set('password_confirmation', 'brand-New-Pass-9')
|
|
->call('resetPassword')
|
|
->assertRedirect(route('login'));
|
|
|
|
$this->assertTrue(\Illuminate\Support\Facades\Hash::check('brand-New-Pass-9', $user->fresh()->password));
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Run it to confirm it fails**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter ForgotPasswordKeyOnlyTest`
|
|
Expected: FAIL — `Google2FA::verifyKey()` is called with the key-only user's null `two_factor_secret` before the backup-code fallback, throwing or short-circuiting.
|
|
|
|
- [ ] **Step 3: Guard the TOTP check**
|
|
|
|
In `app/Livewire/Auth/ForgotPassword.php`, replace the `$ok` assignment (lines 66-68) with:
|
|
|
|
```php
|
|
$ok = $user
|
|
&& $user->hasTwoFactorEnabled()
|
|
&& (($user->hasTotp() && (new Google2FA)->verifyKey($user->two_factor_secret, $clean))
|
|
|| $user->useRecoveryCode($this->code));
|
|
```
|
|
|
|
- [ ] **Step 4: Add the no-2FA reset note to the view + lang**
|
|
|
|
In `resources/views/livewire/auth/forgot-password.blade.php`, add a small hint near the form footer:
|
|
|
|
```blade
|
|
<p class="font-mono text-[11px] text-ink-4">{{ __('auth.reset_no_2fa_note') }}</p>
|
|
```
|
|
|
|
In `lang/de/auth.php`:
|
|
|
|
```php
|
|
'reset_no_2fa_note' => 'Ohne 2FA ist die Wiederherstellung nur per E-Mail-Link (falls SMTP konfiguriert) oder über den Befehl clusev:reset-admin möglich.',
|
|
```
|
|
|
|
In `lang/en/auth.php`:
|
|
|
|
```php
|
|
'reset_no_2fa_note' => 'Without 2FA, recovery is only possible via the email link (if SMTP is configured) or the clusev:reset-admin command.',
|
|
```
|
|
|
|
- [ ] **Step 5: Run the test to confirm it passes**
|
|
|
|
Run: `docker compose exec -T app php artisan test --filter ForgotPasswordKeyOnlyTest`
|
|
Expected: PASS.
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
docker compose exec -T app ./vendor/bin/pint app/Livewire/Auth/ForgotPassword.php tests/Feature/ForgotPasswordKeyOnlyTest.php
|
|
git add -A
|
|
git commit -m "feat(2fa): forgot-password is key-only safe + states the no-2FA recovery path"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 8: Regression sweep, R12 browser verify, Codex, release
|
|
|
|
**Files:**
|
|
- Modify (as needed): the existing 2FA tests whose assumptions changed
|
|
- Modify: `config/clusev.php:6` (version bump)
|
|
- Modify: `CHANGELOG.md`
|
|
|
|
- [ ] **Step 1: Run the full suite and fix fallout**
|
|
|
|
Run: `docker compose exec -T app php artisan test`
|
|
Expected: green. Likely files needing small updates because semantics changed:
|
|
- `tests/Feature/WebauthnKeysTest.php`, `tests/Feature/WebauthnOptionsTest.php`, `tests/Feature/WebauthnAvailableTest.php`: any test that set up `two_factor_confirmed_at`/secret purely to satisfy the old `hasTwoFactorEnabled()` gate on `options()`/`register()` can drop that setup (the gate is now `available()` only). Where a test asserted a 404 for a key attempt without TOTP, invert it to expect success.
|
|
- `tests/Feature/TwoFactorChallengeRecoveryTest.php`, `tests/Feature/TwoFactorWebauthnTest.php`: should still pass; if any asserts the challenge view contains the TOTP field for a key-only user, update to the new gated behaviour.
|
|
- Fix each failure by reading the test and aligning it with the spec (TOTP-only field, either-factor `hasTwoFactorEnabled`, codes lifecycle). Do not weaken security assertions.
|
|
|
|
- [ ] **Step 2: Build assets**
|
|
|
|
Run: `docker compose run --rm --no-deps -u "${HOST_UID}:${HOST_GID}" app npm run build`
|
|
Expected: `✓ built`.
|
|
|
|
- [ ] **Step 3: R12 browser verification (bare-IP, DE + EN)**
|
|
|
|
With a connected browser at `http://10.10.90.136`, verify at 375/768/1280:
|
|
- Login as the admin → after password rotation a no-2FA account reaches the **dashboard** (no forced 2FA).
|
|
- `/settings` → Security tab: the **"2FA empfohlen"** hint shows; the **TOTP card** offers *Einrichten*; the **Security-Keys** card shows the domain-unavailable hint on bare IP.
|
|
- Enroll TOTP at `/two-factor-setup` → on confirm you land on **Settings** and the **recovery-codes modal** pops with 8 codes + Download + Neu erzeugen + Gespeichert.
|
|
- After enrolling, the TOTP card shows *Authenticator entfernen*; **Backup-Codes verwalten** opens the modal.
|
|
- Remove the authenticator → codes cleared, hint returns.
|
|
- Switch locale (DE↔EN) and re-check the same screens for leaked `group.key`/`@`/`{{ }}` tokens (R17) and HTTP 200 + zero console errors.
|
|
- Log out, log in again with TOTP → the **challenge** shows the Authenticator field; entering a backup code also works.
|
|
|
|
Use the browser tools to confirm zero console errors on each touched route.
|
|
|
|
- [ ] **Step 4: Codex review (R15)**
|
|
|
|
Run a Codex review over the full diff (`git diff main...HEAD` or the working branch range). Fix every P1 and security finding; re-run until clean.
|
|
|
|
- [ ] **Step 5: Version bump + CHANGELOG**
|
|
|
|
In `config/clusev.php` line 6, bump `'version' => '0.7.0'` (new feature). Add a `## v0.7.0` section to `CHANGELOG.md` summarizing: optional/pluggable 2FA (TOTP and/or WebAuthn, or off), recovery codes as a modal, onboarding no longer forces 2FA.
|
|
|
|
- [ ] **Step 6: Final suite + commit + finish**
|
|
|
|
```bash
|
|
docker compose exec -T app php artisan test
|
|
docker compose exec -T app ./vendor/bin/pint
|
|
git add -A
|
|
git commit -m "release: optional pluggable 2FA (v0.7.0)"
|
|
```
|
|
|
|
Then invoke `superpowers:finishing-a-development-branch` to complete the work.
|
|
|
|
---
|
|
|
|
## Self-Review
|
|
|
|
**Spec coverage:**
|
|
- §1 Factor semantics → Task 1 (`hasTotp`, either-factor `hasTwoFactorEnabled`, `securityOnboarded` = `!must_change_password`, `resetIfNoFactor`). Callers using `securityOnboarded()`/`hasTwoFactorEnabled()` (`routes/channels.php`, Login) need no edit — they call the methods whose behaviour changed; Login routing to the challenge for a key-only user is correct (Task 5 makes the challenge usable). ✓
|
|
- §2 Onboarding not forced → Task 2 (middleware + PasswordChange → dashboard; broadcast gate). ✓
|
|
- §3 Recovery codes modal → Task 3 (new modal + view, delete page/view/route, keep download) + Task 4 (generate on first factor, open modal) + Task 6 (Settings "verwalten" → modal). ✓
|
|
- §4 Challenge adapts → Task 5 (verify guarded, field gated, key-only backup code). ✓
|
|
- §5 Settings manage factors → Task 6 (TOTP removable always + reset, keys gated on `available()` only + last-key reset, "empfohlen" hint, disable copy reframed). ✓
|
|
- §6 forgot-password → Task 7 (key-only safe, no-2FA note). ✓
|
|
- Files-touched + Testing sections → covered across Tasks 1-8; R12/Codex in Task 8. ✓
|
|
|
|
**Placeholder scan:** No "TBD"/"handle edge cases"; the one structural Blade edit (challenge field) gives the concrete replacement markup. The "existing 2FA tests" updates in Task 8 are inherently read-then-fix but bounded with explicit guidance per file. ✓
|
|
|
|
**Type consistency:** Method names consistent across tasks — `hasTotp()`, `hasTwoFactorEnabled()`, `securityOnboarded()`, `resetIfNoFactor()`, `hasRecoveryCodes()`, `replaceRecoveryCodes()`, `recoveryCodes()`. Modal component `App\Livewire\Modals\RecoveryCodes` ↔ dispatch name `modals.recovery-codes` ↔ view `livewire.modals.recovery-codes`. Flash key `open_recovery_modal` set in Task 4 (TwoFactorSetup) and read in Task 4 (Settings). View locals `hasTotp`/`twoFactorEnabled` defined in Task 6 `render()` and used in the Task 6 blade. ✓
|