create-nevela 0.3.0 → 0.4.2

package/template/laravel/src/Auth/Totp.php

@@ -0,0 +1,106 @@
+<?php
+
+namespace Nevela\Laravel\Auth;
+
+/**
+ * Time-based one-time passwords (RFC 6238), as every authenticator app implements them:
+ * SHA-1, six digits, a new code every 30 seconds. Pure PHP, no dependencies.
+ */
+final class Totp
+{
+    private const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+    private const PERIOD = 30;
+
+    private const DIGITS = 6;
+
+    /** A new secret, as the base32 text an authenticator app is given. 160 bits, as the RFC recommends. */
+    public static function secret(): string
+    {
+        return self::base32(random_bytes(20));
+    }
+
+    /** The code for a moment in time. */
+    public static function code(string $secret, ?int $at = null): string
+    {
+        $counter = intdiv($at ?? time(), self::PERIOD);
+        $hash = hash_hmac('sha1', pack('J', $counter), self::bytes($secret), true);
+        $offset = ord($hash[19]) & 0x0F;
+        $number = (unpack('N', substr($hash, $offset, 4))[1] & 0x7FFFFFFF) % (10 ** self::DIGITS);
+
+        return str_pad((string) $number, self::DIGITS, '0', STR_PAD_LEFT);
+    }
+
+    /**
+     * Whether a code is right, now or one step either side: clocks drift, and a code typed
+     * as it changes should still work.
+     */
+    public static function verify(string $secret, string $code, ?int $at = null): bool
+    {
+        return self::step($secret, $code, $at) !== null;
+    }
+
+    /**
+     * Which 30-second step a right code belongs to, or null when the code is wrong.
+     *
+     * A caller that signs someone in keeps the step, and refuses a code from that step or
+     * an earlier one next time: a code is a one-time password, and without this the same
+     * six digits would work again for up to ninety seconds for anyone who saw them typed.
+     */
+    public static function step(string $secret, string $code, ?int $at = null): ?int
+    {
+        $code = preg_replace('/\s+/', '', $code) ?? '';
+        if (! preg_match('/^\d{6}$/', $code)) {
+            return null;
+        }
+        $at ??= time();
+        foreach ([0, -1, 1] as $offset) {
+            if (hash_equals(self::code($secret, $at + $offset * self::PERIOD), $code)) {
+                return intdiv($at, self::PERIOD) + $offset;
+            }
+        }
+
+        return null;
+    }
+
+    /** What an authenticator app scans: the secret, and the names it files it under. */
+    public static function uri(string $secret, string $account, string $issuer): string
+    {
+        return 'otpauth://totp/'.rawurlencode($issuer).':'.rawurlencode($account)
+            .'?secret='.$secret.'&issuer='.rawurlencode($issuer).'&algorithm=SHA1&digits='.self::DIGITS.'&period='.self::PERIOD;
+    }
+
+    private static function base32(string $bytes): string
+    {
+        $bits = '';
+        foreach (str_split($bytes) as $byte) {
+            $bits .= str_pad(decbin(ord($byte)), 8, '0', STR_PAD_LEFT);
+        }
+        $text = '';
+        foreach (str_split($bits, 5) as $chunk) {
+            $text .= self::ALPHABET[bindec(str_pad($chunk, 5, '0'))];
+        }
+
+        return $text;
+    }
+
+    private static function bytes(string $secret): string
+    {
+        $bits = '';
+        foreach (str_split(strtoupper(rtrim($secret, '='))) as $char) {
+            $index = strpos(self::ALPHABET, $char);
+            if ($index === false) {
+                continue;
+            }
+            $bits .= str_pad(decbin($index), 5, '0', STR_PAD_LEFT);
+        }
+        $bytes = '';
+        foreach (str_split($bits, 8) as $chunk) {
+            if (strlen($chunk) === 8) {
+                $bytes .= chr(bindec($chunk));
+            }
+        }
+
+        return $bytes;
+    }
+}

package/template/laravel/src/Auth/Web.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace Nevela\Laravel\Auth;
+
+use Illuminate\Http\Request;
+
+/**
+ * Where the dashboard is.
+ *
+ * Emails link to it, and a passkey is tied to its address, so Laravel has to know it. The
+ * dashboard says where it is on each request (the X-Nevela-Origin header), because in
+ * development it moves to another port when 3000 is taken. What it says is only believed
+ * when it is the configured address, or a localhost address while the app is in
+ * development: otherwise anyone could have a sign-in link point at a site of their own.
+ */
+final class Web
+{
+    private const LOCAL_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
+
+    public static function configured(): string
+    {
+        return self::originOf((string) config('nevela.auth.web_url', 'http://localhost:3000')) ?? 'http://localhost:3000';
+    }
+
+    /** The dashboard's origin for this request: "https://app.example.com", no path. */
+    public static function origin(?Request $request = null): string
+    {
+        $claimed = self::originOf((string) ($request ?? request())->header('X-Nevela-Origin', ''));
+
+        return $claimed !== null && self::allowed($claimed) ? $claimed : self::configured();
+    }
+
+    public static function allowed(string $origin): bool
+    {
+        $origin = self::originOf($origin);
+        if ($origin === null) {
+            return false;
+        }
+        if ($origin === self::configured()) {
+            return true;
+        }
+
+        return app()->environment('local', 'testing') && in_array(parse_url($origin, PHP_URL_HOST), self::LOCAL_HOSTS, true);
+    }
+
+    /** A page of the dashboard, e.g. url('/reset-password', ['token' => …]). */
+    public static function url(string $path, array $query = [], ?Request $request = null): string
+    {
+        return self::origin($request).'/'.ltrim($path, '/').($query === [] ? '' : '?'.http_build_query($query));
+    }
+
+    /** The host a passkey is bound to: the dashboard's, without scheme or port. */
+    public static function host(?Request $request = null): string
+    {
+        return (string) parse_url(self::origin($request), PHP_URL_HOST);
+    }
+
+    /** Only a path on the dashboard, never another site: for "where to go after signing in". */
+    public static function path(mixed $value, string $fallback = '/dashboard'): string
+    {
+        // One leading slash, and no backslash or control character anywhere: browsers drop
+        // tabs and newlines from an address, which turns "/<tab>/evil.example" into "//evil.example".
+        return is_string($value) && preg_match('#^/(?!/)[^\\\\\x00-\x1F\x7F]*$#', $value) === 1 ? $value : $fallback;
+    }
+
+    private static function originOf(string $url): ?string
+    {
+        $parts = parse_url(trim($url));
+        if (! is_array($parts) || ! in_array($parts['scheme'] ?? '', ['http', 'https'], true) || empty($parts['host'])) {
+            return null;
+        }
+
+        return strtolower($parts['scheme'].'://'.$parts['host']).(isset($parts['port']) ? ':'.$parts['port'] : '');
+    }
+}

package/template/laravel/src/Console/GenerateCommand.php

@@ -90,6 +90,7 @@ final class GenerateCommand extends Command
         }
         $files[] = $generator->routes($all);
         $files[] = $generator->registry($all);
+        $files[] = $generator->authConfig((array) config('nevela.auth', []));
 
         $roots = ['api' => base_path()];
         if (($web = config('nevela.web_path')) && is_dir($web)) {

package/template/laravel/src/Console/UpdateCommand.php

@@ -80,6 +80,41 @@ final class UpdateCommand extends Command
         return preg_match('/^\^\d+\.\d+(\.\d+)?$/', $constraint) === 1;
     }
 
+    /**
+     * Files an earlier upgrade should have removed and didn't: path => the fingerprint of
+     * the template's own version of it.
+     *
+     * An upgrade to 0.4.0 left the old sign-in form in place, importing an action that no
+     * longer exists, which stops `next build`. The record has already moved on, so the
+     * ordinary plan can't see it. It is removed here, but only when it is byte for byte
+     * the template's file: one you have edited is yours and is left alone. A copy is kept
+     * beside the backups, and an undo that goes back to a version which had the file puts
+     * it back.
+     */
+    private const LEFTOVERS = [
+        'components/auth/sign-in-form.tsx' => 'aed2e3389ec0b85df2bbe02f9e91579982d0e5ab',
+    ];
+
+    /** @param bool $check Say what would be removed, and remove nothing */
+    private function clearLeftovers(string $web, bool $check = false): void
+    {
+        $state = DashboardState::read($web);
+        foreach (self::LEFTOVERS as $path => $fingerprint) {
+            $file = "{$web}/{$path}";
+            if (! is_file($file) || isset($state->files[$path]) || DashboardUpdate::hash((string) file_get_contents($file)) !== $fingerprint) {
+                continue;
+            }
+            if ($check) {
+                $this->components->twoColumnDetail($path, '<fg=gray>would remove: an earlier upgrade should have</>');
+
+                continue;
+            }
+            $this->put("{$web}/.nevela/backups/leftovers/{$path}", (string) file_get_contents($file));
+            unlink($file);
+            $this->components->twoColumnDetail($path, '<fg=gray>removed: an earlier upgrade should have (copy in .nevela/backups/leftovers)</>');
+        }
+    }
+
     private function pendingMigrations(): int
     {
         try {
@@ -204,6 +239,7 @@ final class UpdateCommand extends Command
 
             return self::SUCCESS;
         }
+        $this->clearLeftovers($web, $check);
         $state = DashboardState::read($web);
         $from = $state->template ?? self::FIRST_TRACKED;
         // In --check the package hasn't been updated, so look at the newest dashboard there is.
@@ -267,13 +303,19 @@ final class UpdateCommand extends Command
                 } elseif ($action === DashboardUpdate::CONFLICT) {
                     // Yours stays. The new version is put where you can compare the two.
                     $this->put("{$web}/{$incoming}/{$path}", $next[$path]);
+                } elseif ($action === DashboardUpdate::REMOVED && is_file("{$web}/{$path}")) {
+                    // The template dropped it and you never changed it, so it is the template's
+                    // file, not yours. Left behind, it would go on being compiled against code
+                    // that has moved on, and break the build. It is in the backup.
+                    $this->put("{$web}/{$backup}/{$path}", (string) file_get_contents("{$web}/{$path}"));
+                    unlink("{$web}/{$path}");
                 }
             }
             $this->components->twoColumnDetail($path, match ($action) {
                 DashboardUpdate::UPDATE => $check ? '<fg=blue>would update</>' : '<fg=blue>updated</>',
                 DashboardUpdate::ADD => $check ? '<fg=green>would add</>' : '<fg=green>added</>',
                 DashboardUpdate::CONFLICT => '<fg=yellow>kept yours — changed in the template too</>',
-                DashboardUpdate::REMOVED => '<fg=gray>no longer in the template</>',
+                DashboardUpdate::REMOVED => $check ? '<fg=gray>would remove: no longer in the template</>' : '<fg=gray>removed: no longer in the template</>',
             });
         }
 
@@ -289,7 +331,7 @@ final class UpdateCommand extends Command
         $this->newLine();
 
         if (! $check) {
-            $touched = $done[DashboardUpdate::UPDATE] !== [] || $done[DashboardUpdate::ADD] !== [] || ($packages['changed'] ?? []) !== [];
+            $touched = $done[DashboardUpdate::UPDATE] !== [] || $done[DashboardUpdate::ADD] !== [] || $done[DashboardUpdate::REMOVED] !== [] || ($packages['changed'] ?? []) !== [];
             if ($packages && $packages['changed']) {
                 $this->put("{$web}/{$backup}/package.json", (string) file_get_contents("{$web}/package.json"));
                 file_put_contents("{$web}/package.json", $packages['json']);
@@ -318,7 +360,7 @@ final class UpdateCommand extends Command
             $state->write($web);
 
             if ($touched) {
-                $this->line("  Every file this replaced was copied to <fg=cyan>{$this->relative($web)}/{$backup}</> first. To put it all back: <fg=cyan>php nevela upgrade --undo</>");
+                $this->line("  Every file this replaced or removed was copied to <fg=cyan>{$this->relative($web)}/{$backup}</> first. To put it all back: <fg=cyan>php nevela upgrade --undo</>");
             }
         }
         if ($done[DashboardUpdate::CONFLICT] !== []) {
@@ -326,7 +368,7 @@ final class UpdateCommand extends Command
             $this->components->warn("{$count} file(s) changed in the template and in your app. Yours were kept.".($check ? '' : " The template's new versions are in {$this->relative($web)}/{$incoming} for you to compare."));
         }
         if ($done[DashboardUpdate::REMOVED] !== []) {
-            $this->line('  '.count($done[DashboardUpdate::REMOVED])." file(s) are no longer part of the template. They were left in place; delete them if you don't use them.");
+            $this->line('  '.count($done[DashboardUpdate::REMOVED]).' file(s) the template no longer has '.($check ? 'would be' : 'were').' removed. You had not changed them; a file you changed is always kept.');
         }
         if (! $check && ($packages['changed'] ?? [])) {
             $this->line('  The dashboard\'s dependencies changed. Install them: <fg=cyan>cd '.$this->relative($web).' && '.DevCommand::packageManager($web).' install</>');
@@ -383,6 +425,16 @@ final class UpdateCommand extends Command
         if (is_file("{$dir}/.nevela.json")) {
             copy("{$dir}/.nevela.json", DashboardState::path($web));
         }
+        // A leftover cleared since belongs to the version this goes back to, so it returns.
+        $before = DashboardState::read($web);
+        foreach (array_keys(self::LEFTOVERS) as $path) {
+            $copy = "{$web}/.nevela/backups/leftovers/{$path}";
+            if (isset($before->files[$path]) && ! is_file("{$web}/{$path}") && is_file($copy)) {
+                $this->put("{$web}/{$path}", (string) file_get_contents($copy));
+                $this->components->twoColumnDetail($path, '<fg=blue>restored</>');
+                $restored++;
+            }
+        }
 
         $this->newLine();
         $this->components->info("Put back {$restored} file(s). The dashboard is as it was before the update from {$last['from']} to {$last['to']}.");

package/template/laravel/src/Generator/ResourceGenerator.php

@@ -314,6 +314,66 @@ final class ResourceGenerator
         TS);
     }
 
+    /**
+     * How people sign in, for the dashboard's screens: which buttons to draw. The choices
+     * are made in the Laravel app's config/nevela.php, which is also what enforces them.
+     *
+     * @param  array<string, mixed>  $auth  The "auth" section of config/nevela.php
+     */
+    public function authConfig(array $auth): GeneratedFile
+    {
+        $flag = fn (string $key, bool $default = true) => (bool) data_get($auth, $key, $default) ? 'true' : 'false';
+        $m = self::M;
+        $e = self::E;
+
+        return new GeneratedFile(GeneratedFile::TARGET_WEB, 'lib/auth-config.ts', <<<TS
+        /**
+         * How people sign in to this app.
+         *
+         * Written by `php nevela generate` from the "auth" section of config/nevela.php in the
+         * Laravel app. Change a setting there, then generate again: Laravel refuses a method
+         * that is switched off, and this file keeps the screens from offering it.
+         *
+         * Email and password sign-in is always available.
+         */
+        export type SocialProvider = "google" | "github" | "apple" | "microsoft";
+
+        {$m}
+        export const authConfig = {
+          /** People can create their own account at /sign-up. */
+          registration: {$flag('registration', false)},
+          /** A sign-in link by email. */
+          magicLink: {$flag('magic_link')},
+          /** A 6-digit sign-in code by email. */
+          emailOtp: {$flag('email_code')},
+          /** Face ID, Touch ID, Windows Hello or a security key. */
+          passkeys: {$flag('passkeys')},
+          twoFactor: {
+            /** Codes from an authenticator app (TOTP), with backup codes. */
+            authenticator: {$flag('two_factor.authenticator')},
+            /** Codes by email as the second step. */
+            email: {$flag('two_factor.email')},
+          },
+          /** Refuse password sign-in until the email address is verified. */
+          requireEmailVerification: {$flag('require_email_verification', false)},
+          /** Check new passwords against Have I Been Pwned's breach list. */
+          checkBreachedPasswords: {$flag('check_breached_passwords')},
+          /** Signing in with Google, GitHub and the like isn't part of Nevela yet. */
+          social: [] as SocialProvider[],
+        };
+        {$e}
+
+        /** Whether any second factor can be set up. */
+        export const twoFactorAvailable = authConfig.twoFactor.authenticator || authConfig.twoFactor.email;
+
+        /** The social providers that are switched on and configured. None yet. */
+        export function enabledSocialProviders(): SocialProvider[] {
+          return authConfig.social;
+        }
+
+        TS);
+    }
+
     /** @param list<Descriptor> $all */
     public function routes(array $all): GeneratedFile
     {

package/template/laravel/src/Http/Auth/AccountController.php

@@ -0,0 +1,252 @@
+<?php
+
+namespace Nevela\Laravel\Http\Auth;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Facades\Schema;
+use Nevela\Laravel\Auth\Account;
+use Nevela\Laravel\Auth\AuthMail;
+use Nevela\Laravel\Auth\Challenges;
+use Nevela\Laravel\Auth\Web;
+use Nevela\Laravel\Http\UploadController;
+use Nevela\Laravel\Models\Upload;
+use Nevela\Laravel\Rules\UploadKey;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\Field;
+
+/**
+ * An account and what its owner can do with it: create it, prove the email address,
+ * change the name, the picture and the password, and see and sign out its devices.
+ */
+final class AccountController
+{
+    use Answers;
+
+    private const VERIFY_SECONDS = 3600;
+
+    private const RESET_SECONDS = 3600;
+
+    /** POST auth/register */
+    public function register(Request $request): JsonResponse
+    {
+        $this->enabled('registration');
+        $model = Account::model();
+        $input = $request->validate([
+            'name' => ['required', 'string', 'max:255'],
+            'email' => ['required', 'email', 'max:255'],
+            'password' => Account::passwordRules(),
+        ]);
+        if (Account::findByEmail($input['email'])) {
+            return $this->refuse('USER_ALREADY_EXISTS', 'An account with this email already exists. Sign in instead.', 422);
+        }
+
+        $user = new $model;
+        $attributes = ['name' => $input['name'], 'email' => mb_strtolower(trim($input['email'])), 'password' => Hash::make($input['password'])];
+        $role = config('nevela.auth.default_role');
+        if ($role !== null && Schema::hasColumn($user->getTable(), 'role')) {
+            $attributes['role'] = $role;
+        }
+        $user->forceFill($attributes)->save();
+        self::sendVerification($user, $request);
+
+        if (config('nevela.auth.require_email_verification', false)) {
+            return response()->json(['verify' => true, 'user' => Account::describe($user)], 201);
+        }
+
+        return response()->json(Account::signIn($user, $request), 201);
+    }
+
+    /** Email a code, and a link that carries it, to prove an address. */
+    public static function sendVerification(mixed $user, Request $request, ?string $next = null): void
+    {
+        if (! Challenges::mayIssue('verify-email', mb_strtolower($user->email))) {
+            return;
+        }
+        [$code, $hash] = Challenges::code();
+        Challenges::put('verify-email', mb_strtolower($user->email), ['user' => (string) $user->getAuthIdentifier(), 'code' => $hash], self::VERIFY_SECONDS);
+        $url = Web::url('/verify-email', ['email' => $user->email, 'code' => $code, 'next' => Web::path($next, '/dashboard/account')], $request);
+        AuthMail::send($user->email, 'Verify your email for '.AuthMail::app(), ["Your verification code is {$code}.", 'Or use the button. Both expire in an hour.'], ['Verify email', $url], "{$code}  {$url}");
+    }
+
+    /** POST auth/email/send: send the verification email again. */
+    public function resendVerification(Request $request): JsonResponse
+    {
+        $input = $request->validate(['email' => ['nullable', 'email'], 'next' => ['nullable', 'string', 'max:2000']]);
+        $user = $request->user('sanctum') ?? (isset($input['email']) ? Account::findByEmail($input['email']) : null);
+        if ($user && $user->email_verified_at === null) {
+            self::sendVerification($user, $request, $input['next'] ?? null);
+        }
+
+        return response()->json(['sent' => true]);
+    }
+
+    /** POST auth/email/verify */
+    public function verifyEmail(Request $request): JsonResponse
+    {
+        $input = $request->validate(['email' => ['required', 'email'], 'code' => ['required', 'string', 'max:16']]);
+        $id = mb_strtolower(trim($input['email']));
+        $pending = Challenges::get('verify-email', $id);
+        if ($pending === null) {
+            return $this->refuse('OTP_EXPIRED', 'That code has expired. Ask for a new one.', 401);
+        }
+        if (! hash_equals($pending['code'], Challenges::hash($input['code']))) {
+            return Challenges::miss('verify-email', $id)
+                ? $this->refuse('INVALID_OTP', "That code isn't right. Check it and try again.", 401)
+                : $this->refuse('TOO_MANY_ATTEMPTS', 'Too many attempts. Ask for a new code.', 429);
+        }
+        Challenges::forget('verify-email', $id);
+        $user = Account::model()::query()->find($pending['user']);
+        if (! $user) {
+            return $this->refuse('OTP_EXPIRED', 'That code has expired. Ask for a new one.', 401);
+        }
+        $user->forceFill(['email_verified_at' => $user->email_verified_at ?? now()])->save();
+
+        // Someone verifying from the email on a new device is signed in there; someone
+        // already signed in just gets their account back, verified.
+        return $request->user('sanctum')
+            ? response()->json(['user' => Account::describe($user)])
+            : SignInController::finish($user, $request, byEmail: true);
+    }
+
+    /** PATCH auth/me: the name, and the picture (the key of an image uploaded with PUT auth/avatar). */
+    public function update(Request $request): JsonResponse
+    {
+        $user = $request->user();
+        $input = $request->validate([
+            'name' => ['sometimes', 'required', 'string', 'max:255'],
+            'avatar' => ['sometimes', 'nullable', 'string', 'max:512', new UploadKey('User', 'avatar')],
+        ]);
+        if (array_key_exists('avatar', $input) && $input['avatar'] !== null) {
+            // Only a picture this person uploaded: a key is not a secret between users.
+            $own = Upload::query()->where('key', $input['avatar'])->where('uploaded_by', (string) $user->getAuthIdentifier())->exists();
+            if (! $own) {
+                return $this->refuse('INVALID_AVATAR', 'Upload the picture again.', 422);
+            }
+        }
+        if (array_key_exists('avatar', $input) && ! Schema::hasColumn($user->getTable(), 'avatar')) {
+            return $this->refuse('MIGRATION_NEEDED', 'Profile pictures need a migration that has not been run: php artisan migrate', 409);
+        }
+        $user->forceFill($input)->save();
+
+        return response()->json(['user' => Account::describe($user)]);
+    }
+
+    /**
+     * PUT auth/avatar?name=me.jpg: the picture is the request body. It goes through the
+     * same optimiser as any image field, with the "avatar" profile: a 400×400 square
+     * and an 80×80 thumbnail. The account is pointed at it straight away.
+     */
+    public function avatar(Request $request): JsonResponse
+    {
+        $user = $request->user();
+        if (! Schema::hasColumn($user->getTable(), 'avatar')) {
+            return $this->refuse('MIGRATION_NEEDED', 'Profile pictures need a migration that has not been run: php artisan migrate', 409);
+        }
+        $field = new Field('avatar', 'file', required: false, accept: ['image'], profile: 'avatar');
+        $upload = UploadController::receive($request, new Descriptor('User', ['avatar' => $field], $user->getTable(), 'users', 'User', 'Users'), $field);
+        if ($upload instanceof JsonResponse) {
+            return $upload;
+        }
+        $user->forceFill(['avatar' => $upload->key])->save();
+
+        return response()->json(['user' => Account::describe($user)], 201);
+    }
+
+    /** POST auth/password: change it, knowing the current one. */
+    public function changePassword(Request $request): JsonResponse
+    {
+        $user = $request->user();
+        $input = $request->validate([
+            'currentPassword' => ['required', 'string'],
+            'newPassword' => Account::passwordRules(),
+            'revokeOtherSessions' => ['nullable', 'boolean'],
+        ]);
+        if (! Hash::check($input['currentPassword'], (string) $user->getAuthPassword())) {
+            return $this->refuse('INVALID_PASSWORD', "That isn't your current password.", 422);
+        }
+        $user->forceFill(['password' => Hash::make($input['newPassword'])])->save();
+        if ($input['revokeOtherSessions'] ?? false) {
+            Account::revokeTokens($user, $user->currentAccessToken()?->getKey());
+        }
+        AuthMail::send($user->email, 'Your '.AuthMail::app().' password was changed', ['The password for your account was just changed.', "If that wasn't you, reset it now and check the devices signed in to your account."]);
+
+        return response()->json(['changed' => true]);
+    }
+
+    /** POST auth/password/forgot: email a link to choose a new password. */
+    public function forgotPassword(Request $request): JsonResponse
+    {
+        $input = $request->validate(['email' => ['required', 'email']]);
+        if ($user = Account::findByEmail($input['email'])) {
+            $token = Challenges::start('reset-password', ['user' => (string) $user->getAuthIdentifier()], self::RESET_SECONDS);
+            $url = Web::url('/reset-password', ['token' => $token], $request);
+            AuthMail::send($user->email, 'Reset your '.AuthMail::app().' password', ['Use this link to choose a new password. It works once and expires in an hour.'], ['Choose a new password', $url], $url);
+        }
+
+        return response()->json(['sent' => true]);
+    }
+
+    /** POST auth/password/reset */
+    public function resetPassword(Request $request): JsonResponse
+    {
+        $input = $request->validate(['token' => ['required', 'string'], 'newPassword' => Account::passwordRules()]);
+        $pending = Challenges::take('reset-password', $input['token']);
+        $user = $pending ? Account::model()::query()->find($pending['user']) : null;
+        if (! $user) {
+            return $this->refuse('INVALID_TOKEN', 'That reset link has expired or was already used. Ask for a new one.', 401);
+        }
+        // Whoever opened the link owns the address, and every device is signed out:
+        // a reset is what someone does when they think another person has got in.
+        $user->forceFill(['password' => Hash::make($input['newPassword']), 'email_verified_at' => $user->email_verified_at ?? now()])->save();
+        Account::revokeTokens($user);
+
+        return response()->json(['reset' => true]);
+    }
+
+    /** GET auth/sessions: the devices signed in to this account. */
+    public function sessions(Request $request): JsonResponse
+    {
+        $user = $request->user();
+        $current = $user->currentAccessToken()?->getKey();
+        $tracked = Schema::hasColumn('personal_access_tokens', 'user_agent');
+        $rows = DB::table('personal_access_tokens')
+            ->where('tokenable_type', $user->getMorphClass())->where('tokenable_id', $user->getAuthIdentifier())
+            ->orderByDesc('last_used_at')->orderByDesc('created_at')->get();
+
+        return response()->json([
+            'current' => $current === null ? null : (string) $current,
+            'data' => $rows->map(fn ($row) => [
+                'id' => (string) $row->id,
+                'name' => $row->name,
+                'userAgent' => $tracked ? $row->user_agent : null,
+                'ipAddress' => $tracked ? $row->ip_address : null,
+                'createdAt' => $row->created_at ? date(DATE_ATOM, strtotime($row->created_at)) : null,
+                'lastUsedAt' => $row->last_used_at ? date(DATE_ATOM, strtotime($row->last_used_at)) : null,
+                'current' => (string) $row->id === (string) $current,
+            ])->all(),
+        ]);
+    }
+
+    /** DELETE auth/sessions/{id}: sign one device out. */
+    public function revokeSession(Request $request, string $id): Response
+    {
+        $user = $request->user();
+        DB::table('personal_access_tokens')
+            ->where('tokenable_type', $user->getMorphClass())->where('tokenable_id', $user->getAuthIdentifier())
+            ->where('id', $id)->delete();
+
+        return response()->noContent();
+    }
+
+    /** DELETE auth/sessions: sign every other device out. */
+    public function revokeOtherSessions(Request $request): JsonResponse
+    {
+        $user = $request->user();
+
+        return response()->json(['revoked' => Account::revokeTokens($user, $user->currentAccessToken()?->getKey())]);
+    }
+}

package/template/laravel/src/Http/Auth/Answers.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Nevela\Laravel\Http\Auth;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Hash;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+/** What the auth controllers share: how they refuse, and how they check a setting or a password. */
+trait Answers
+{
+    private function refuse(string $code, string $message, int $status = 400): JsonResponse
+    {
+        return response()->json(['error' => $message, 'code' => $code], $status);
+    }
+
+    /** A method switched off in config/nevela.php is refused, not just hidden. */
+    private function enabled(string $setting): void
+    {
+        if (! config("nevela.auth.{$setting}", true)) {
+            throw new NotFoundHttpException("This sign-in method isn't enabled.");
+        }
+    }
+
+    /** Changing how an account is protected takes its password again. */
+    private function passwordConfirmed(Request $request): bool
+    {
+        $password = $request->input('password');
+
+        return is_string($password) && Hash::check($password, (string) $request->user()->getAuthPassword());
+    }
+}