feat: settings, two-factor management, email verification screen and CI

What was left between this and a real starter kit.

/settings holds the profile, the password, and two-factor: the QR code,
the secret for anyone who cannot scan it, the recovery codes, and the
confirmation step. Three pages rather than one, because Fortify puts the
validation errors from all three forms in the same bag and a single page
could not tell the reader which form had failed.

A trap worth naming, and the reason the two-factor page is tested: with
the confirm option on, hasEnabledTwoFactorAuthentication() stays false
until a code has been entered. A page keyed on it — as this one was —
offers "turn on" forever and never lets anyone finish. The state comes
from the secret and the confirmation timestamp instead.

The two-factor page asks for the password again, matching what Fortify
enforces on the endpoints behind it, so it cannot show a secret those
endpoints would then refuse to act on.

The email verification screen is registered although the feature is off,
so switching it on is the one uncommented line the README promises
rather than one line and a missing view.

CI runs the suite on push, building the assets first: @Vite throws
without a manifest, which is exactly what makes a freshly created
application look broken to whoever tries it first.

Author: BlueStarSystem

.github/workflows/tests.yml

@@ -0,0 +1,44 @@
+name: Tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          extensions: sqlite3, pdo_sqlite
+          coverage: none
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install PHP dependencies
+        run: composer install --prefer-dist --no-interaction --no-progress
+
+      - name: Prepare the application
+        run: |
+          cp .env.example .env
+          php artisan key:generate
+          touch database/database.sqlite
+          php artisan migrate --force
+
+      # The suite renders every page, and @vite throws without a manifest, so the
+      # assets have to exist before the tests run. Skipping this is what makes a
+      # freshly created application look broken to whoever tries it first.
+      - name: Build the assets
+        run: |
+          npm ci
+          npm run build
+
+      - name: Run the tests
+        run: php artisan test

README.md

@@ -38,18 +38,26 @@ The dashboard sits behind `auth`; the landing page and the component overview st
 because a kit that hides its own shop window shows nothing to the person deciding whether to
 use it.
 
+## Settings
+
+Under `/settings`, behind `auth`: the profile, the password, and two-factor authentication with
+its QR code, its recovery codes, and the confirmation step that only counts it as on once a code
+has actually worked. The two-factor page asks for the password again before it will show a
+secret, matching what Fortify enforces on the endpoints behind it.
+
+Email verification is off, as it is in a plain Laravel install — but its screen is here and
+wired, so turning it on really is one uncommented line in `config/fortify.php` plus
+`MustVerifyEmail` on the user model.
+
 ## What is not here yet
 
 Stated plainly, because a starter kit that pretends to be finished wastes your afternoon:
 
-- **No settings or profile pages.** Fortify's update-profile and update-password endpoints are
-  enabled, but there is no screen for them yet, and no screen to turn two-factor on.
 - **Passkeys are off.** Fortify ships them; they need a WebAuthn ceremony in JavaScript this kit
   does not have. A sign-in button that cannot sign anyone in is worse than no button.
-- **Email verification is off**, as it is in a plain Laravel install. Uncomment
-  `Features::emailVerification()` and the `MustVerifyEmail` interface on the user model.
 - **The test suite fails until you build the assets.** `@vite` throws without a manifest, which
-  is true of every Laravel starter kit; run `npm install && npm run build` first.
+  is true of every Laravel starter kit; run `npm install && npm run build` first. CI does it in
+  the right order.
 
 ## Requirements
 

app/Providers/FortifyServiceProvider.php

@@ -41,6 +41,13 @@ public function boot(): void
         Fortify::confirmPasswordView(fn () => view('auth.confirm-password'));
         Fortify::twoFactorChallengeView(fn () => view('auth.two-factor-challenge'));
 
+        /*
+         * Registered even though email verification is off in config/fortify.php:
+         * turning the feature on should be one uncommented line, not one line and
+         * then a missing view.
+         */
+        Fortify::verifyEmailView(fn () => view('auth.verify-email'));
+
         Fortify::createUsersUsing(CreateNewUser::class);
         Fortify::updateUserProfileInformationUsing(UpdateUserProfileInformation::class);
         Fortify::updateUserPasswordsUsing(UpdateUserPassword::class);

resources/views/auth/verify-email.blade.php

@@ -0,0 +1,23 @@
+<x-layouts.auth title="Verify your email" heading="Verify your email">
+    <x-slot:subheading>We sent a link to the address you signed up with.</x-slot:subheading>
+
+    @if (session('status') === 'verification-link-sent')
+        <x-aura::alert variant="success" class="mb-6">A new link is on its way.</x-aura::alert>
+    @endif
+
+    <x-aura::text class="mb-6 text-sm">
+        Click the link in that email to finish. If it never arrives, we can send another.
+    </x-aura::text>
+
+    <div class="flex flex-wrap items-center gap-3">
+        <form method="POST" action="{{ route('verification.send') }}">
+            @csrf
+            <x-aura::button type="submit" variant="primary">Send it again</x-aura::button>
+        </form>
+
+        <form method="POST" action="{{ route('logout') }}">
+            @csrf
+            <x-aura::button type="submit" variant="ghost">Sign out</x-aura::button>
+        </form>
+    </div>
+</x-layouts.auth>

resources/views/components/layouts/app.blade.php

@@ -49,6 +49,7 @@
                     </x-slot:trigger>
 
                     <x-aura::dropdown.item href="{{ url('/dashboard') }}" icon="home">Dashboard</x-aura::dropdown.item>
+                    <x-aura::dropdown.item href="{{ route('settings.profile') }}" icon="settings">Settings</x-aura::dropdown.item>
                     <x-aura::dropdown.separator />
                     {{-- Signing out is a state change, so it is a POST with a token,
                          never a link someone can be tricked into following. --}}

resources/views/components/settings-nav.blade.php

@@ -0,0 +1,23 @@
+@props(['current'])
+
+@php
+    $items = [
+        ['route' => 'settings.profile', 'label' => 'Profile'],
+        ['route' => 'settings.password', 'label' => 'Password'],
+        ['route' => 'settings.two-factor', 'label' => 'Two-factor'],
+    ];
+@endphp
+
+<nav class="mb-8 flex flex-wrap gap-2" aria-label="Settings">
+    @foreach ($items as $item)
+        @php $active = $current === $item['route']; @endphp
+        <a
+            href="{{ route($item['route']) }}"
+            @if ($active) aria-current="page" @endif
+            class="rounded-lg px-3 py-1.5 text-sm no-underline transition
+                {{ $active
+                    ? 'bg-aura-primary-600 text-white'
+                    : 'text-gray-600 hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-gray-800' }}"
+        >{{ $item['label'] }}</a>
+    @endforeach
+</nav>

resources/views/settings/password.blade.php

@@ -0,0 +1,43 @@
+<x-layouts.app title="Password">
+    <x-aura::heading level="1">Settings</x-aura::heading>
+    <x-settings-nav current="settings.password" />
+
+    @if (session('status') === 'password-updated')
+        <x-aura::alert variant="success" class="mb-6">Your password has been changed.</x-aura::alert>
+    @endif
+
+    <x-aura::card class="max-w-2xl">
+        <x-aura::heading level="2" class="mb-1">Change password</x-aura::heading>
+        <x-aura::text class="mb-6 text-sm">Use a long password you do not use anywhere else.</x-aura::text>
+
+        <form method="POST" action="{{ route('user-password.update') }}" class="aura-form-fluid space-y-5">
+            @csrf
+            @method('PUT')
+
+            <x-aura::password-input
+                label="Current password"
+                name="current_password"
+                autocomplete="current-password"
+                required
+                :error="$errors->first('current_password')"
+            />
+
+            <x-aura::password-input
+                label="New password"
+                name="password"
+                autocomplete="new-password"
+                required
+                :error="$errors->first('password')"
+            />
+
+            <x-aura::password-input
+                label="Confirm new password"
+                name="password_confirmation"
+                autocomplete="new-password"
+                required
+            />
+
+            <x-aura::button type="submit" variant="primary">Change password</x-aura::button>
+        </form>
+    </x-aura::card>
+</x-layouts.app>

resources/views/settings/profile.blade.php

@@ -0,0 +1,39 @@
+<x-layouts.app title="Profile">
+    <x-aura::heading level="1">Settings</x-aura::heading>
+    <x-settings-nav current="settings.profile" />
+
+    @if (session('status') === 'profile-information-updated')
+        <x-aura::alert variant="success" class="mb-6">Your profile has been updated.</x-aura::alert>
+    @endif
+
+    <x-aura::card class="max-w-2xl">
+        <x-aura::heading level="2" class="mb-1">Profile information</x-aura::heading>
+        <x-aura::text class="mb-6 text-sm">The name and email address on your account.</x-aura::text>
+
+        <form method="POST" action="{{ route('user-profile-information.update') }}" class="aura-form-fluid space-y-5">
+            @csrf
+            @method('PUT')
+
+            <x-aura::input
+                label="Name"
+                name="name"
+                value="{{ old('name', auth()->user()->name) }}"
+                autocomplete="name"
+                required
+                :error="$errors->first('name')"
+            />
+
+            <x-aura::input
+                label="Email"
+                name="email"
+                type="email"
+                value="{{ old('email', auth()->user()->email) }}"
+                autocomplete="username"
+                required
+                :error="$errors->first('email')"
+            />
+
+            <x-aura::button type="submit" variant="primary">Save</x-aura::button>
+        </form>
+    </x-aura::card>
+</x-layouts.app>

resources/views/settings/two-factor.blade.php

@@ -0,0 +1,109 @@
+<x-layouts.app title="Two-factor authentication">
+    @php
+        $user = auth()->user();
+
+        /*
+         * Not hasEnabledTwoFactorAuthentication(): with the confirm option on, that
+         * method stays false until the user has entered a code, so a page keyed on
+         * it would offer "turn on" forever and never let anyone finish. What matters
+         * here is whether a secret exists yet, and whether it has been confirmed.
+         */
+        $started = ! is_null($user->two_factor_secret);
+        $confirmed = ! is_null($user->two_factor_confirmed_at);
+    @endphp
+
+    <x-aura::heading level="1">Settings</x-aura::heading>
+    <x-settings-nav current="settings.two-factor" />
+
+    @if (session('status') === 'two-factor-authentication-enabled')
+        <x-aura::alert variant="info" class="mb-6">
+            Scan the code below with your authenticator app, then enter the six digits it shows to finish.
+        </x-aura::alert>
+    @endif
+
+    @if (session('status') === 'two-factor-authentication-confirmed')
+        <x-aura::alert variant="success" class="mb-6">Two-factor authentication is on.</x-aura::alert>
+    @endif
+
+    @if (session('status') === 'two-factor-authentication-disabled')
+        <x-aura::alert variant="success" class="mb-6">Two-factor authentication is off.</x-aura::alert>
+    @endif
+
+    <x-aura::card class="max-w-2xl">
+        <div class="mb-1 flex items-center gap-3">
+            <x-aura::heading level="2">Two-factor authentication</x-aura::heading>
+            @if ($confirmed)
+                <x-aura::badge variant="success">On</x-aura::badge>
+            @elseif ($started)
+                <x-aura::badge variant="warning">Waiting for confirmation</x-aura::badge>
+            @else
+                <x-aura::badge variant="secondary">Off</x-aura::badge>
+            @endif
+        </div>
+
+        <x-aura::text class="mb-6 text-sm">
+            A second step at sign-in: a six-digit code from an app on your phone, so a stolen
+            password is not enough on its own.
+        </x-aura::text>
+
+        @if (! $started)
+            <form method="POST" action="{{ route('two-factor.enable') }}">
+                @csrf
+                <x-aura::button type="submit" variant="primary">Turn on</x-aura::button>
+            </form>
+        @else
+            @unless ($confirmed)
+                {{-- The secret is shown once, while it is being set up, and never again.
+                     The QR is rendered by Fortify from the user's own secret. --}}
+                <div class="mb-6 flex flex-wrap items-start gap-6">
+                    <div class="rounded-lg bg-white p-3">{!! $user->twoFactorQrCodeSvg() !!}</div>
+
+                    <div class="text-sm">
+                        <p class="mb-2 text-gray-600 dark:text-gray-400">Cannot scan it? Enter this key by hand:</p>
+                        <code class="break-all">{{ decrypt($user->two_factor_secret) }}</code>
+                    </div>
+                </div>
+
+                <form method="POST" action="{{ route('two-factor.confirm') }}" class="aura-form-fluid mb-8 space-y-4">
+                    @csrf
+
+                    <x-aura::input
+                        label="Code from your app"
+                        name="code"
+                        inputmode="numeric"
+                        autocomplete="one-time-code"
+                        required
+                        :error="$errors->confirmTwoFactorAuthentication->first('code')"
+                    />
+
+                    <x-aura::button type="submit" variant="primary">Finish turning it on</x-aura::button>
+                </form>
+            @endunless
+
+            <div class="mb-8">
+                <x-aura::heading level="3" class="mb-1">Recovery codes</x-aura::heading>
+                <x-aura::text class="mb-4 text-sm">
+                    Each one signs you in once, for when the phone is not to hand. Keep them
+                    somewhere other than the phone.
+                </x-aura::text>
+
+                <ul class="mb-4 grid gap-1 font-mono text-sm sm:grid-cols-2">
+                    @foreach ($user->recoveryCodes() as $code)
+                        <li>{{ $code }}</li>
+                    @endforeach
+                </ul>
+
+                <form method="POST" action="{{ route('two-factor.regenerate-recovery-codes') }}">
+                    @csrf
+                    <x-aura::button type="submit" variant="secondary" size="sm">Generate new codes</x-aura::button>
+                </form>
+            </div>
+
+            <form method="POST" action="{{ route('two-factor.disable') }}">
+                @csrf
+                @method('DELETE')
+                <x-aura::button type="submit" variant="danger">Turn off</x-aura::button>
+            </form>
+        @endif
+    </x-aura::card>
+</x-layouts.app>

routes/web.php

@@ -13,3 +13,15 @@
         'blocks' => $catalogue->blocks(),
     ]);
 })->name('components');
+
+/*
+ * Fortify owns the endpoints behind these screens; the screens themselves are
+ * ours. The two-factor page asks for the password again before it will show a
+ * secret, matching the confirmPassword option in config/fortify.php — otherwise
+ * it would display a QR code that the endpoints then refuse to act on.
+ */
+Route::middleware(['auth'])->prefix('settings')->name('settings.')->group(function () {
+    Route::view('/profile', 'settings.profile')->name('profile');
+    Route::view('/password', 'settings.password')->name('password');
+    Route::view('/two-factor', 'settings.two-factor')->middleware('password.confirm')->name('two-factor');
+});