create-nevela 0.2.1 → 0.4.1

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

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/StatusCommand.php

@@ -30,7 +30,7 @@ final class StatusCommand extends Command
         $latest = Releases::latest();
         $row('Nevela', Nevela::VERSION.match (true) {
             $latest === null => ' <fg=gray>(couldn\'t check for a newer one)</>',
-            version_compare($latest, Nevela::VERSION, '>') => " <fg=yellow>({$latest} is out: php nevela update)</>",
+            version_compare($latest, Nevela::VERSION, '>') => " <fg=yellow>({$latest} is out: php nevela upgrade)</>",
             default => ' <fg=green>(latest)</>',
         });
         $row('Laravel / PHP', app()->version().' / '.PHP_VERSION);
@@ -99,7 +99,7 @@ final class StatusCommand extends Command
             // What this app has made its own. An update leaves every one of these alone.
             $changes = $state->yourChanges($web);
             if ($changes === null) {
-                $row('Your dashboard changes', '<fg=gray>not tracked yet: php nevela update records them</>');
+                $row('Your dashboard changes', '<fg=gray>not tracked yet: php nevela upgrade records them</>');
             } else {
                 $count = count($changes['changed']) + count($changes['deleted']);
                 $row('Your dashboard changes', $count === 0 ? 'none' : "{$count} file(s), kept on every update");