create-nevela 0.3.0 → 0.4.1

package/index.mjs

@@ -7,6 +7,7 @@
 // No dependencies on purpose: this runs before anything is installed.
 
 import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -454,7 +455,14 @@ async function main() {
   // The dashboard first, so its packages can download while Composer works on Laravel.
   // The two don't touch each other, and Composer is the long part.
   copyWebTemplate(web, { name, title });
-  write(path.join(web, '.env.local'), '# Where the Laravel API is, including its prefix.\nNEVELA_API_URL=http://127.0.0.1:8000/api\n');
+  // Shared by the dashboard and the API, so the API can believe what the dashboard tells it
+  // about a person's browser (for the list of devices signed in to an account). Made here,
+  // per app, and never the same twice.
+  const proxySecret = crypto.randomBytes(24).toString('hex');
+  write(
+    path.join(web, '.env.local'),
+    `# Where the Laravel API is, including its prefix.\nNEVELA_API_URL=http://127.0.0.1:8000/api\n\n# The same value as in apps/api/.env. It lets the API trust this app's word on a visitor's browser.\nNEVELA_PROXY_SECRET=${proxySecret}\n`,
+  );
   if (pm === 'pnpm') {
     // Its own workspace file: lets sharp build, and keeps pnpm from adopting a workspace further up.
     write(path.join(web, 'pnpm-workspace.yaml'), 'allowBuilds:\n  sharp: true\n');
@@ -510,6 +518,9 @@ async function main() {
     // artisan command is slow for the same reason the index was: files read for the first time.
     const env = path.join(api, '.env');
     if (!fs.existsSync(env) && fs.existsSync(`${env}.example`)) fs.copyFileSync(`${env}.example`, env);
+    if (fs.existsSync(env) && !/^NEVELA_PROXY_SECRET=/m.test(fs.readFileSync(env, 'utf8'))) {
+      fs.appendFileSync(env, `\n# The same value as in apps/web/.env.local.\nNEVELA_PROXY_SECRET=${proxySecret}\n`);
+    }
     const sqlite = path.join(api, 'database', 'database.sqlite');
     if (/^DB_CONNECTION=sqlite\s*$/m.test(fs.readFileSync(env, 'utf8')) && !fs.existsSync(sqlite)) fs.writeFileSync(sqlite, '');
     return addApiTokens(path.join(api, 'app', 'Models', 'User.php'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nevela",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Create a new Nevela app: a Laravel API and a Next.js dashboard from one resource description.",
   "type": "module",
   "bin": {

package/template/laravel/composer.json

@@ -30,7 +30,8 @@
         "illuminate/support": "^11.0|^12.0|^13.0",
         "illuminate/database": "^11.17|^12.0|^13.0",
         "illuminate/http": "^11.0|^12.0|^13.0",
-        "illuminate/console": "^11.0|^12.0|^13.0"
+        "illuminate/console": "^11.0|^12.0|^13.0",
+        "lbuchs/webauthn": "^2.2"
     },
     "require-dev": {
         "phpunit/phpunit": "^11.0"

package/template/laravel/config/nevela.php

@@ -24,10 +24,75 @@ return [
     'prefix' => 'api',
     'middleware' => ['api', 'auth:sanctum'],
 
-    /* Token auth endpoints for the Next.js app: POST/DELETE {prefix}/auth/token, GET {prefix}/auth/me. */
+    /*
+    | Signing in. Every endpoint is under {prefix}/auth. Email and password is always
+    | available; the rest can be switched off here. A method that is off is refused by the
+    | API, not just hidden, and `php artisan nevela:generate` writes these choices to the
+    | dashboard (apps/web/lib/auth-config.ts) so its screens agree.
+    */
     'auth' => [
         'enabled' => true,
         'token_name' => 'nevela-web',
+
+        /*
+        | Let anyone create their own account at /sign-up. Off by default, and accounts come
+        | from `php nevela user`: a generated policy lets every signed-in user do everything
+        | until you tighten it, so open sign-up on an untouched app would hand the dashboard
+        | to whoever finds it. Tighten app/Policies first, then set NEVELA_REGISTRATION=true.
+        */
+        'registration' => (bool) env('NEVELA_REGISTRATION', false),
+
+        /* A sign-in link by email. */
+        'magic_link' => true,
+
+        /* A 6-digit sign-in code by email. */
+        'email_code' => true,
+
+        /* Face ID, Touch ID, Windows Hello or a security key. */
+        'passkeys' => true,
+
+        'two_factor' => [
+            /* Codes from an authenticator app (TOTP), with backup codes. */
+            'authenticator' => true,
+            /* Codes by email as the second step. */
+            'email' => true,
+        ],
+
+        /* Refuse password sign-in until the email address is verified. */
+        'require_email_verification' => false,
+
+        /*
+        | Check new passwords against Have I Been Pwned's breach list. Only the first five
+        | characters of the password's hash are sent, and an outage lets the password through.
+        */
+        'check_breached_passwords' => true,
+
+        /*
+        | Sign-in attempts are limited to ten a minute per account. This is the limit per
+        | address on top of that. It is high because the dashboard's server makes the calls:
+        | to Laravel, everyone using the dashboard comes from that one address.
+        */
+        'attempts_per_address' => 300,
+
+        /* The role a self-registered account starts with. Null leaves the column alone. */
+        'default_role' => null,
+
+        /*
+        | Where the dashboard is, for the links in emails and for passkeys, which are tied
+        | to its address. In development any localhost port is accepted as well, because
+        | the dashboard moves to another port when 3000 is taken.
+        */
+        'web_url' => env('NEVELA_WEB_URL', 'http://localhost:3000'),
+
+        /*
+        | A secret the dashboard's server and Laravel share, so Laravel can believe what the
+        | dashboard says about a person's browser and address (for the list of devices).
+        | Put the same value in the dashboard's .env.local. New apps get one when created.
+        */
+        'proxy_secret' => env('NEVELA_PROXY_SECRET'),
+
+        /* The name an authenticator app and a passkey prompt show. Null: the app's name. */
+        'issuer' => null,
     ],
 
     /* List defaults, matching Flare's client. */

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