create-nevela 0.3.0 → 0.4.1

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);
+    }
+}

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
     {