create-nevela 0.3.0 → 0.4.2

package/template/laravel/database/migrations/2026_10_05_000000_create_nevela_auth_tables.php

@@ -0,0 +1,66 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+// What two-factor sign-in, passkeys, the profile picture and the list of devices need.
+// Columns are only added where they are missing, so an app that already has an "avatar"
+// column, say, keeps its own.
+return new class extends Migration
+{
+    public function up(): void
+    {
+        if (Schema::hasTable('users') && ! Schema::hasColumn('users', 'avatar')) {
+            Schema::table('users', function (Blueprint $table) {
+                // The key of an uploaded image (see nevela_uploads), not a URL.
+                $table->string('avatar', 512)->nullable();
+            });
+        }
+
+        // A device is a Sanctum token; these say which browser and where it signed in from.
+        if (Schema::hasTable('personal_access_tokens')) {
+            Schema::table('personal_access_tokens', function (Blueprint $table) {
+                if (! Schema::hasColumn('personal_access_tokens', 'ip_address')) {
+                    $table->string('ip_address', 45)->nullable();
+                }
+                if (! Schema::hasColumn('personal_access_tokens', 'user_agent')) {
+                    $table->string('user_agent', 512)->nullable();
+                }
+            });
+        }
+
+        Schema::create('nevela_two_factor', function (Blueprint $table) {
+            $table->uuid('id')->primary();
+            $table->string('user_id')->unique();
+            // The authenticator app's secret, encrypted. Null when only email codes are used.
+            $table->text('secret')->nullable();
+            $table->timestamp('totp_confirmed_at')->nullable();
+            // The 30-second step of the last code accepted, so the same code isn't taken twice.
+            $table->unsignedBigInteger('totp_last_step')->nullable();
+            // Hashes of the backup codes not used yet, encrypted.
+            $table->text('backup_codes')->nullable();
+            $table->timestamp('enabled_at')->nullable();
+            $table->timestamps();
+        });
+
+        Schema::create('nevela_passkeys', function (Blueprint $table) {
+            $table->uuid('id')->primary();
+            $table->string('user_id')->index();
+            $table->string('name')->nullable();
+            $table->string('credential_id', 1024)->unique();
+            $table->text('public_key');
+            $table->unsignedBigInteger('counter')->default(0);
+            $table->json('transports')->nullable();
+            $table->string('aaguid')->nullable();
+            $table->timestamp('last_used_at')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('nevela_passkeys');
+        Schema::dropIfExists('nevela_two_factor');
+    }
+};

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

@@ -0,0 +1,140 @@
+<?php
+
+namespace Nevela\Laravel\Auth;
+
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Validation\Rules\Password;
+use Nevela\Laravel\Media\Uploads;
+use Nevela\Laravel\Models\TwoFactor;
+use RuntimeException;
+
+/**
+ * The signed-in person, as the API describes them, and the tokens that are their devices.
+ */
+final class Account
+{
+    /** The app's user model. */
+    public static function model(): string
+    {
+        return (string) config('auth.providers.users.model');
+    }
+
+    public static function findByEmail(string $email): mixed
+    {
+        return self::model()::query()->whereRaw('lower(email) = ?', [mb_strtolower(trim($email))])->first();
+    }
+
+    /**
+     * What a client needs to know about a user.
+     *
+     * @return array<string, mixed>
+     */
+    public static function describe(mixed $user): array
+    {
+        $avatar = $user->avatar ?? null;
+        $file = is_string($avatar) && $avatar !== '' ? Uploads::ref($avatar) : null;
+
+        return [
+            'id' => (string) $user->getAuthIdentifier(),
+            'name' => $user->name ?? null,
+            'email' => $user->email ?? null,
+            'role' => $user->role ?? null,
+            'emailVerified' => ($user->email_verified_at ?? null) !== null,
+            'twoFactorEnabled' => self::twoFactor($user)?->enabled_at !== null,
+            // The key is what is stored; "image" is the small rendition, ready for an <img>.
+            'avatar' => $file ? $avatar : null,
+            'avatarFile' => $file,
+            'image' => $file ? ($file['renditions']->thumb['url'] ?? $file['url']) : null,
+        ];
+    }
+
+    public static function twoFactor(mixed $user): ?TwoFactor
+    {
+        return TwoFactor::query()->where('user_id', (string) $user->getAuthIdentifier())->first();
+    }
+
+    /**
+     * Sign someone in: a new Sanctum token, remembered with the browser it was made for.
+     *
+     * @return array{token: string, user: array<string, mixed>}
+     */
+    public static function signIn(mixed $user, Request $request): array
+    {
+        if (! method_exists($user, 'createToken')) {
+            throw new RuntimeException('Add Laravel\Sanctum\HasApiTokens to '.self::model().' to issue Nevela tokens.');
+        }
+        $name = (string) ($request->input('deviceName') ?: config('nevela.auth.token_name', 'nevela-web'));
+        $token = $user->createToken(mb_substr($name, 0, 255));
+        self::remember($token->accessToken->getKey(), $request);
+
+        return ['token' => $token->plainTextToken, 'user' => self::describe($user)];
+    }
+
+    /**
+     * The browser's address and name. The dashboard's server makes the call to Laravel,
+     * so it passes these on from the person's own request; a direct API client is itself.
+     */
+    private static function remember(mixed $tokenId, Request $request): void
+    {
+        if (! Schema::hasColumn('personal_access_tokens', 'user_agent')) {
+            return; // the migration hasn't been run yet; signing in still works
+        }
+        $dashboard = self::fromDashboard($request);
+        $ip = $dashboard ? (string) $request->header('X-Nevela-Ip', '') : '';
+        $agent = $dashboard ? (string) $request->header('X-Nevela-User-Agent', '') : '';
+        DB::table('personal_access_tokens')->where('id', $tokenId)->update([
+            'ip_address' => filter_var($ip, FILTER_VALIDATE_IP) ? $ip : $request->ip(),
+            'user_agent' => mb_substr($agent !== '' ? $agent : (string) $request->userAgent(), 0, 512) ?: null,
+        ]);
+    }
+
+    /**
+     * Whether a request comes from the dashboard's server, and so may speak for a browser.
+     *
+     * Anyone can call the API directly and send the same headers, so they are believed only
+     * with the secret the dashboard and Laravel share (NEVELA_PROXY_SECRET in both). Without
+     * one configured they are believed from this machine while the app is in development,
+     * and otherwise not at all: a device then shows the address the request really came from.
+     */
+    public static function fromDashboard(Request $request): bool
+    {
+        $secret = config('nevela.auth.proxy_secret');
+        if (is_string($secret) && $secret !== '') {
+            return hash_equals($secret, (string) $request->header('X-Nevela-Proxy-Secret', ''));
+        }
+
+        return app()->environment('local') && in_array($request->ip(), ['127.0.0.1', '::1'], true);
+    }
+
+    /**
+     * The rules a new password has to meet. Length is what is required; the dashboard
+     * shows the rest as advice. A password found in a breach is refused, because it is
+     * in the lists attackers try first however strong it looks.
+     *
+     * @return list<mixed>
+     */
+    public static function passwordRules(): array
+    {
+        $rule = Password::min(8);
+        if (config('nevela.auth.check_breached_passwords', true) && ! app()->runningUnitTests()) {
+            $rule = $rule->uncompromised();
+        }
+
+        return ['required', 'string', 'max:128', $rule];
+    }
+
+    /** Sign every device out, except the one asking when `$except` is given. */
+    public static function revokeTokens(mixed $user, mixed $except = null): int
+    {
+        $query = DB::table('personal_access_tokens')
+            ->where('tokenable_type', $user->getMorphClass())
+            ->where('tokenable_id', $user->getAuthIdentifier());
+        if ($except !== null) {
+            $query->where('id', '!=', $except);
+        }
+
+        return $query->delete();
+    }
+}

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

@@ -0,0 +1,77 @@
+<?php
+
+namespace Nevela\Laravel\Auth;
+
+use Illuminate\Notifications\Messages\MailMessage;
+use Illuminate\Notifications\Notification;
+use Illuminate\Support\Facades\Notification as Notifications;
+use Throwable;
+
+/**
+ * The emails signing in needs: codes, links, and notices that something changed.
+ *
+ * Sent with whatever mailer the Laravel app is configured with. In development that is
+ * usually the log, where nobody looks, so the code or link is also printed to the
+ * server's output: with `nevela dev` it appears in the terminal as it is "sent".
+ */
+final class AuthMail
+{
+    /**
+     * @param  list<string>  $lines  Paragraphs, in order
+     * @param  array{0: string, 1: string}|null  $action  A button: [label, url]
+     * @param  string|null  $secret  The code or link, for the development console
+     */
+    /**
+     * What was sent while tests run, so a test can read the code it was "emailed".
+     *
+     * @var list<array{email: string, subject: string, lines: list<string>, action: array{0: string, 1: string}|null, secret: string|null}>
+     */
+    public static array $outbox = [];
+
+    public static function send(string $email, string $subject, array $lines, ?array $action = null, ?string $secret = null): void
+    {
+        if (app()->runningUnitTests()) {
+            self::$outbox[] = compact('email', 'subject', 'lines', 'action', 'secret');
+        }
+        if (app()->environment('local') && $secret !== null) {
+            // The dev server shows its error output; nothing else of the request is printed there.
+            @file_put_contents('php://stderr', "Nevela mail to {$email}: {$subject}\n    {$secret}\n");
+        }
+
+        try {
+            Notifications::route('mail', $email)->notify(new class($subject, $lines, $action) extends Notification
+            {
+                /** @param list<string> $lines @param array{0: string, 1: string}|null $action */
+                public function __construct(private string $subject, private array $lines, private ?array $action) {}
+
+                /** @return list<string> */
+                public function via(object $notifiable): array
+                {
+                    return ['mail'];
+                }
+
+                public function toMail(object $notifiable): MailMessage
+                {
+                    $message = (new MailMessage)->subject($this->subject);
+                    foreach ($this->lines as $line) {
+                        $message->line($line);
+                    }
+                    if ($this->action !== null) {
+                        $message->action($this->action[0], $this->action[1]);
+                    }
+
+                    return $message->line("If you didn't ask for this, you can ignore this email.");
+                }
+            });
+        } catch (Throwable $e) {
+            // A mail server being down must not tell the visitor anything, or break sign-in
+            // for an address that may not even exist. It is reported for the developer.
+            report($e);
+        }
+    }
+
+    public static function app(): string
+    {
+        return (string) (config('nevela.auth.issuer') ?: config('app.name', 'Nevela'));
+    }
+}

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

@@ -0,0 +1,135 @@
+<?php
+
+namespace Nevela\Laravel\Auth;
+
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\RateLimiter;
+use Illuminate\Support\Str;
+
+/**
+ * Things that are valid once and briefly: a sign-in waiting for its second step, an
+ * emailed code, a passkey ceremony's challenge, a sign-in link.
+ *
+ * Kept in the cache, under a key made from a hash of the id, so reading the cache doesn't
+ * give anyone a usable id. Codes are kept as hashes for the same reason.
+ */
+final class Challenges
+{
+    /** How many wrong codes are tolerated before the challenge is thrown away. */
+    public const ATTEMPTS = 5;
+
+    /**
+     * @param  array<string, mixed>  $data
+     * @return string The id to hand to the client
+     */
+    public static function start(string $type, array $data, int $seconds): string
+    {
+        $id = Str::random(48);
+        Cache::put(self::key($type, $id), $data + ['attempts' => 0, 'expires' => time() + $seconds], $seconds);
+
+        return $id;
+    }
+
+    /**
+     * The same, under an id the caller chooses: an emailed code is found again by the
+     * address it was sent to.
+     *
+     * @param  array<string, mixed>  $data
+     */
+    public static function put(string $type, string $id, array $data, int $seconds): void
+    {
+        Cache::put(self::key($type, $id), $data + ['attempts' => 0, 'expires' => time() + $seconds], $seconds);
+    }
+
+    /** @return array<string, mixed>|null */
+    public static function get(string $type, ?string $id): ?array
+    {
+        if ($id === null || $id === '') {
+            return null;
+        }
+        $data = Cache::get(self::key($type, $id));
+
+        return is_array($data) && ($data['expires'] ?? 0) >= time() ? $data : null;
+    }
+
+    /** Read it and make sure it can't be read again. @return array<string, mixed>|null */
+    public static function take(string $type, ?string $id): ?array
+    {
+        $data = self::get($type, $id);
+        if ($data !== null) {
+            Cache::forget(self::key($type, (string) $id));
+        }
+
+        return $data;
+    }
+
+    /** @param array<string, mixed> $changes */
+    public static function update(string $type, string $id, array $changes): void
+    {
+        $data = self::get($type, $id);
+        if ($data !== null) {
+            Cache::put(self::key($type, $id), $changes + $data, max(1, $data['expires'] - time()));
+        }
+    }
+
+    /**
+     * Count a wrong answer. Returns false when that was one too many, and the challenge
+     * is gone: whoever is guessing has to start again.
+     */
+    public static function miss(string $type, string $id): bool
+    {
+        $data = self::get($type, $id);
+        if ($data === null) {
+            return false;
+        }
+        if ($data['attempts'] + 1 >= self::ATTEMPTS) {
+            Cache::forget(self::key($type, $id));
+
+            return false;
+        }
+        self::update($type, $id, ['attempts' => $data['attempts'] + 1]);
+
+        return true;
+    }
+
+    public static function forget(string $type, string $id): void
+    {
+        Cache::forget(self::key($type, $id));
+    }
+
+    /**
+     * Whether another emailed code may be sent for this purpose to this person.
+     *
+     * A six-digit code allows five wrong guesses, so the number of codes is what limits
+     * guessing: at six codes an hour, trying every code takes several years, where
+     * unlimited codes would take months. A person who really needs a seventh waits.
+     */
+    public static function mayIssue(string $type, string $who, int $perHour = 6): bool
+    {
+        $key = 'nevela:auth:issued:'.$type.':'.hash('sha256', $who);
+        if (RateLimiter::tooManyAttempts($key, $perHour)) {
+            return false;
+        }
+        RateLimiter::hit($key, 3600);
+
+        return true;
+    }
+
+    /** A six-digit code, and the hash of it to keep. @return array{0: string, 1: string} */
+    public static function code(): array
+    {
+        $code = str_pad((string) random_int(0, 999999), 6, '0', STR_PAD_LEFT);
+
+        return [$code, self::hash($code)];
+    }
+
+    public static function hash(string $value): string
+    {
+        return hash_hmac('sha256', preg_replace('/\s+/', '', $value) ?? '', (string) config('app.key'));
+    }
+
+    private static function key(string $type, string $id): string
+    {
+        return 'nevela:auth:'.$type.':'.hash('sha256', $id);
+    }
+}

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

@@ -0,0 +1,206 @@
+<?php
+
+namespace Nevela\Laravel\Auth;
+
+use Illuminate\Http\Request;
+use lbuchs\WebAuthn\Binary\ByteBuffer;
+use lbuchs\WebAuthn\WebAuthn;
+use Nevela\Laravel\Models\Passkey;
+use RuntimeException;
+use Throwable;
+
+/**
+ * Passkeys (WebAuthn): creating one, and signing in with one.
+ *
+ * Each is a ceremony in two halves. Laravel hands out a random challenge; the person's
+ * device signs it with a key that never leaves the device; Laravel checks the signature
+ * against the public key it was given when the passkey was made. The parsing and the
+ * cryptography are lbuchs/webauthn's. What is checked here on top of it:
+ *
+ * - the challenge is one this app issued, minutes ago, and is used once,
+ * - the page that ran the ceremony is the dashboard, compared exactly (the library
+ *   accepts any host that merely ends with the right name), and
+ * - the passkey belongs to the person it is being used for.
+ */
+final class Passkeys
+{
+    /** How long someone has to complete the prompt on their device. */
+    private const SECONDS = 300;
+
+    private static function server(Request $request): WebAuthn
+    {
+        // "none": no proof of the device's make is asked for. It isn't needed to sign
+        // someone in, and asking makes browsers show an extra consent prompt.
+        return new WebAuthn(AuthMail::app(), Web::host($request), ['none'], true);
+    }
+
+    /**
+     * Options for `navigator.credentials.create()`.
+     *
+     * @return array{challenge: string, options: mixed}
+     */
+    public static function creationOptions(mixed $user, Request $request): array
+    {
+        $server = self::server($request);
+        $existing = Passkey::query()->where('user_id', (string) $user->getAuthIdentifier())->pluck('credential_id')
+            ->map(fn (string $id) => new ByteBuffer(self::decode($id)))->all();
+
+        // A discoverable credential ("resident key"), so signing in doesn't need an email first.
+        $options = $server->getCreateArgs(
+            (string) $user->getAuthIdentifier(),
+            (string) $user->email,
+            (string) ($user->name ?: $user->email),
+            self::SECONDS,
+            true,
+            'preferred',
+            null,
+            $existing,
+        );
+
+        return [
+            'challenge' => Challenges::start('passkey-create', [
+                'user' => (string) $user->getAuthIdentifier(),
+                'value' => self::encode($server->getChallenge()->getBinaryString()),
+                'origin' => Web::origin($request),
+            ], self::SECONDS),
+            'options' => $options->publicKey,
+        ];
+    }
+
+    /**
+     * @param  array<string, mixed>  $response  What the browser's credential produced
+     *
+     * @throws RuntimeException with a message for the person
+     */
+    public static function create(mixed $user, string $challengeId, array $response, ?string $name, Request $request): Passkey
+    {
+        $challenge = Challenges::take('passkey-create', $challengeId);
+        if ($challenge === null || $challenge['user'] !== (string) $user->getAuthIdentifier()) {
+            throw new RuntimeException('That took too long. Try adding the passkey again.');
+        }
+        $clientData = self::decode((string) ($response['clientDataJSON'] ?? ''));
+        self::assertOrigin($clientData, $challenge['origin']);
+
+        try {
+            $data = self::server($request)->processCreate(
+                $clientData,
+                self::decode((string) ($response['attestationObject'] ?? '')),
+                self::decode($challenge['value']),
+                false,
+                true,
+                false,
+            );
+        } catch (Throwable $e) {
+            report($e);
+            throw new RuntimeException("That passkey couldn't be checked. Try again.");
+        }
+
+        $credentialId = self::encode($data->credentialId);
+        if (Passkey::query()->where('credential_id', $credentialId)->exists()) {
+            throw new RuntimeException('That passkey is already added.');
+        }
+        $transports = array_values(array_filter((array) ($response['transports'] ?? []), fn ($t) => is_string($t) && preg_match('/^[a-z-]{2,20}$/', $t)));
+
+        return Passkey::create([
+            'user_id' => (string) $user->getAuthIdentifier(),
+            'name' => $name !== null && trim($name) !== '' ? mb_substr(trim($name), 0, 80) : null,
+            'credential_id' => $credentialId,
+            'public_key' => $data->credentialPublicKey,
+            'counter' => (int) ($data->signatureCounter ?? 0),
+            'transports' => $transports ?: null,
+            'aaguid' => is_string($data->AAGUID ?? null) ? bin2hex($data->AAGUID) : null,
+        ]);
+    }
+
+    /**
+     * Options for `navigator.credentials.get()`. No list of allowed passkeys: the device
+     * offers the ones it has for this site, which is what lets someone sign in without
+     * typing an email, and tells a visitor nothing about who has an account.
+     *
+     * @return array{challenge: string, options: mixed}
+     */
+    public static function requestOptions(Request $request): array
+    {
+        $server = self::server($request);
+        $options = $server->getGetArgs([], self::SECONDS, true, true, true, true, true, 'preferred');
+
+        return [
+            'challenge' => Challenges::start('passkey-get', [
+                'value' => self::encode($server->getChallenge()->getBinaryString()),
+                'origin' => Web::origin($request),
+            ], self::SECONDS),
+            'options' => $options->publicKey,
+        ];
+    }
+
+    /**
+     * Check a sign-in and return whose passkey it was.
+     *
+     * @param  array<string, mixed>  $response
+     *
+     * @throws RuntimeException with a message for the person
+     */
+    public static function verify(string $challengeId, array $response, Request $request): Passkey
+    {
+        $failed = "That passkey didn't work. Try again, or sign in another way.";
+        $challenge = Challenges::take('passkey-get', $challengeId);
+        if ($challenge === null) {
+            throw new RuntimeException('That took too long. Try the passkey again.');
+        }
+        $passkey = Passkey::query()->where('credential_id', (string) ($response['id'] ?? ''))->first();
+        if ($passkey === null) {
+            throw new RuntimeException("This passkey isn't registered here any more. Sign in another way.");
+        }
+        $clientData = self::decode((string) ($response['clientDataJSON'] ?? ''));
+        self::assertOrigin($clientData, $challenge['origin']);
+
+        // The device says whose passkey it is. It has to agree with our record.
+        $handle = (string) ($response['userHandle'] ?? '');
+        if ($handle !== '' && ! hash_equals($passkey->user_id, self::decode($handle))) {
+            throw new RuntimeException($failed);
+        }
+
+        $server = self::server($request);
+        try {
+            $server->processGet(
+                $clientData,
+                self::decode((string) ($response['authenticatorData'] ?? '')),
+                self::decode((string) ($response['signature'] ?? '')),
+                $passkey->public_key,
+                self::decode($challenge['value']),
+                // A counter that goes backwards means the key was copied. Passkeys synced
+                // between someone's devices always report 0, which is not checked.
+                $passkey->counter > 0 ? $passkey->counter : null,
+                false,
+                true,
+            );
+        } catch (Throwable $e) {
+            report($e);
+            throw new RuntimeException($failed);
+        }
+
+        $passkey->forceFill(['counter' => (int) ($server->getSignatureCounter() ?? $passkey->counter), 'last_used_at' => now()])->save();
+
+        return $passkey;
+    }
+
+    /** The page that ran the ceremony has to be the dashboard, exactly. */
+    private static function assertOrigin(string $clientDataJson, string $expected): void
+    {
+        $clientData = json_decode($clientDataJson, true);
+        $origin = is_array($clientData) ? (string) ($clientData['origin'] ?? '') : '';
+        if ($origin === '' || rtrim(strtolower($origin), '/') !== $expected) {
+            throw new RuntimeException("This passkey request didn't come from the app's own address.");
+        }
+    }
+
+    public static function encode(string $binary): string
+    {
+        return rtrim(strtr(base64_encode($binary), '+/', '-_'), '=');
+    }
+
+    public static function decode(string $text): string
+    {
+        return (string) base64_decode(strtr($text, '-_', '+/'), false);
+    }
+}