create-nevela 0.2.1 → 0.4.1

package/README.md

@@ -36,21 +36,32 @@ php nevela resource Product --fields="name:string, sku:string!, price:money"
 
 That writes the Laravel code and the dashboard pages, and creates the table. `php nevela` lists everything else.
 
-## Updating an app later
+## The nevela command
+
+Install this package once and you have a `nevela` command, in every shell:
 
 ```sh
-php nevela update
+npm install -g create-nevela
 ```
 
-That updates the Laravel package, regenerates, and updates the dashboard files you have not changed. Files you changed are kept, and everything it replaces is backed up first.
+```sh
+nevela new my-app      # anywhere: create an app
+nevela update          # anywhere: update the nevela command itself
+nevela dev             # inside an app: run the API and the dashboard
+nevela upgrade         # inside an app: bring it to the latest Nevela
+```
 
-If `php` is not a command in your shell (Git Bash with Laravel Herd), or the app is an old one, run it through this package instead. It works in any shell and on an app of any age:
+As in Grit, `update` is for the tool and `upgrade` is for an app.
+
+## Upgrading an app later
 
 ```sh
-npx create-nevela update
+nevela upgrade
 ```
 
-Installed globally (`npm install -g create-nevela`), it gives you a `nevela` command: `nevela update`, `nevela dev`, `nevela status`, `nevela resource …`. See https://nevela-docs.vercel.app/guides/updating/.
+That updates the Laravel package, regenerates, and upgrades the dashboard files you have not changed. Files you changed are kept, and everything it replaces is backed up first.
+
+Without the command installed, `npx create-nevela upgrade` does the same, in any shell and on an app of any age. So does the app's own launcher, `php nevela upgrade`. See https://nevela-docs.vercel.app/guides/updating/.
 
 ## Options
 

package/index.mjs

@@ -7,15 +7,17 @@
 // 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';
 import readline from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
-import { latestRelease, onPackagist } from './packagist.mjs';
-import { COMMANDS, findProject, forward, update } from './project.mjs';
+import { isNewer, latestRelease, onPackagist } from './packagist.mjs';
+import { COMMANDS, findProject, forward, upgrade } from './project.mjs';
 import { shellLine, spawnCommand, windows } from './shell.mjs';
-import { newerVersion, runVersion } from './selfupdate.mjs';
+import { latestVersion, newerVersion, runVersion } from './selfupdate.mjs';
+import { globalInstall, INSTALL_COMMAND } from './tool.mjs';
 import { copyLaravelPackage, copyWebTemplate, fromRepository, templateRecord } from './template.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -41,12 +43,15 @@ const HELP = `
 
   Create a new Nevela app: a Laravel API and a Next.js dashboard.
 
-  ${bold('Create an app')}
-    pnpm create nevela <name> [options]
-    npm create nevela@latest <name> -- [options]
+  ${bold('Get the nevela command')}  (once; everything below is then this short)
+    npm install -g create-nevela
 
-  ${bold('Inside an app')}  (also as: nevela <command>, once installed with npm install -g create-nevela)
-    nevela update              Update Nevela and the dashboard to the latest version
+  ${bold('Anywhere')}
+    nevela new <name> [options]   Create an app. Without the command: pnpm create nevela <name>
+    nevela update                 Update the nevela command itself to the latest version
+
+  ${bold('Inside an app')}
+    nevela upgrade             Bring this app to the latest Nevela: the package and the dashboard
     nevela dev                 Run the API and the dashboard
     nevela status              Check versions, migrations, users and the dashboard
     nevela resource <Name> --fields="…" [--seed]
@@ -301,7 +306,7 @@ Everything else runs from this folder too, with \`php nevela\`:
 \`\`\`sh
 php nevela user        # add someone who can sign in
 php nevela status      # versions, migrations, users, and what the dashboard is talking to
-php nevela update      # update Nevela and the dashboard
+php nevela upgrade     # bring this app to the latest Nevela
 php nevela             # everything it can do
 \`\`\`
 
@@ -328,25 +333,82 @@ async function inProject(name, args) {
     fail(`"${name}" runs inside a Nevela app, and this folder isn't in one.`, `To create an app:  pnpm create nevela my-app`);
   }
   if (name === 'version') console.log(`create-nevela ${VERSION}`);
-  if (name !== 'update') process.exit(forward(project, name, args));
+  if (name !== 'upgrade') process.exit(forward(project, name, args));
 
-  // Updating is the one command that must not run on stale code itself.
+  // Upgrading is the one command that must not run on stale code itself: it is the newest
+  // installer that knows what an older app needs repaired. So even a nevela command that
+  // hasn't been updated in a while upgrades an app correctly.
   if (!process.env.NEVELA_NO_SELF_UPDATE && !fromRepository) {
     const newer = await newerVersion(VERSION);
     if (newer) {
-      const status = await runVersion(newer, ['update', ...args]);
+      const status = await runVersion(newer, ['upgrade', ...args]);
       if (status !== null) process.exit(status);
     }
   }
-  console.log(`\n  ${indigo(bold('Nevela'))} ${dim('update')}\n`);
+  console.log(`\n  ${indigo(bold('Nevela'))} ${dim('upgrade')}\n`);
   const releases = await latestRelease();
-  const status = await update(project, args, { latest: releases, say: (line) => console.log(`  ${green('✔')} ${line}`) });
+  const status = await upgrade(project, args, { latest: releases, say: (line) => console.log(`  ${green('✔')} ${line}`) });
   process.exit(status);
 }
 
+/**
+ * `nevela update`, from anywhere: update the nevela command itself.
+ *
+ * As in Grit, updating the tool and upgrading an app are two commands. This one doesn't
+ * touch any app; it ends by saying how to upgrade the one you are in, if you are in one.
+ *
+ * It returns instead of calling process.exit(): on Windows, exiting in the same moment a
+ * fetch() has just finished trips an assertion inside Node and prints a crash.
+ */
+async function updateTool(args) {
+  const project = findProject(process.cwd());
+  const install = fromRepository ? null : globalInstall(here);
+
+  if (!install) {
+    // Run through npx or `pnpm dlx`, which fetch the latest every time, started by an
+    // older nevela command that fetched this one to do its work, or a copy in a project's
+    // own node_modules. There is no installed command to update. Inside an app, "update" used to mean "upgrade this app", and
+    // instructions saying so are still around, so that is what it does.
+    if (project) {
+      console.log(`\n  ${dim(`"update" now updates the nevela command, and an app is brought up to date with "upgrade". Upgrading this app.`)}`);
+      await inProject('upgrade', args);
+    }
+    console.log(`\n  ${indigo(bold('Nevela'))} ${dim(`v${VERSION}`)}\n`);
+    console.log(`  The nevela command isn't installed on this computer, so there is nothing to update.`);
+    console.log(`  To install it:  ${bold(INSTALL_COMMAND)}`);
+    console.log(`  Then, anywhere: ${bold('nevela new my-app')}   and inside an app: ${bold('nevela upgrade')}, ${bold('nevela dev')}\n`);
+    return;
+  }
+
+  console.log(`\n  ${indigo(bold('Nevela'))} ${dim('update')}\n`);
+  const latest = await latestVersion();
+  const newer = latest !== null && isNewer(latest, VERSION) ? latest : null;
+  if (latest === null) {
+    // Not the same as being up to date, so it isn't reported as that.
+    console.log(`  ${red('!')} Couldn't reach npm to see whether there is a newer nevela than ${bold(VERSION)}. Nothing was changed.`);
+    console.log(`    Try again when you are online, or run:  ${install.command.join(' ')}`);
+    process.exitCode = 1;
+  } else if (!newer) {
+    console.log(`  ${green('✔')} nevela ${bold(VERSION)} is the latest.`);
+  } else {
+    console.log(`  Updating the nevela command ${bold(VERSION)} → ${bold(newer)} ${dim(`(${install.command.join(' ')})`)}\n`);
+    const [command, ...rest] = install.command;
+    const result = spawnCommand(command, rest, { stdio: 'inherit' });
+    if (result.error || result.status !== 0) {
+      fail(`Couldn't update the nevela command.`, `Run it yourself to see why:  ${install.command.join(' ')}`);
+    }
+    console.log(`\n  ${green('✔')} nevela is now ${bold(newer)}.`);
+  }
+  if (project) {
+    console.log(`  ${dim('This app is not changed by that. To bring it to the latest Nevela:')} ${bold('nevela upgrade')}`);
+  }
+  console.log('');
+}
+
 async function main() {
   const argv = process.argv.slice(2);
   if (argv[0] === 'new') argv.shift();
+  else if (argv[0] === 'update') return updateTool(argv.slice(1));
   else if (COMMANDS.includes(argv[0])) await inProject(argv[0], argv.slice(1));
   const options = parseArgs(argv);
 
@@ -393,13 +455,20 @@ 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');
   }
   // Which dashboard this app started from, with a fingerprint of every file in it.
-  // `nevela update` compares against these to tell the files you changed from the ones
+  // `nevela upgrade` compares against these to tell the files you changed from the ones
   // you didn't, so an update never overwrites your work.
   write(path.join(web, '.nevela.json'), `${JSON.stringify(templateRecord(VERSION), null, 4)}\n`);
   writeRootFiles(root, { name, title, pm, admin: options.user ? ADMIN : null });
@@ -449,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'));
@@ -510,7 +582,7 @@ async function main() {
     console.log(`  ${dim(`That account is in this app's local database only. Add your own: ${nevela} user`)}`);
   }
   console.log(`\n  Add your first resource: ${dim(`${nevela} resource Product --fields="name:string, price:money"`)}`);
-  console.log(`  Check the app: ${dim(`${nevela} status`)}   Update it later: ${dim(`${nevela} update`)}   Everything: ${dim(nevela)}`);
+  console.log(`  Check the app: ${dim(`${nevela} status`)}   Upgrade it later: ${dim(`${nevela} upgrade`)}   Everything: ${dim(nevela)}`);
   if (nevela !== 'php nevela') {
     console.log(`\n  ${dim(`In this shell "php" isn't a command (your PHP is php.bat), so use ${nevela}. In PowerShell, php nevela works too.`)}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nevela",
-  "version": "0.2.1",
+  "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": {
@@ -14,6 +14,7 @@
     "selfupdate.mjs",
     "shell.mjs",
     "project.mjs",
+    "tool.mjs",
     "template",
     "LICENSE"
   ],

package/project.mjs

@@ -2,7 +2,7 @@
 //
 // The same commands as the app's own `php nevela`, but started from Node. That matters in
 // shells where typing `php` doesn't work (Git Bash with Laravel Herd, where PHP is
-// php.bat), and for `update`, which has to work on an app of any age, including one from
+// php.bat), and for `upgrade`, which has to work on an app of any age, including one from
 // before the app had a launcher at all.
 
 import fs from 'node:fs';
@@ -11,7 +11,7 @@ import { isNewer, satisfiesCaret } from './packagist.mjs';
 import { spawnCommand } from './shell.mjs';
 
 /** What `nevela <name>` runs: these go to `php artisan nevela:<name>`. */
-const NEVELA = ['update', 'dev', 'status', 'version', 'resource', 'generate', 'seed', 'user'];
+const NEVELA = ['upgrade', 'dev', 'status', 'version', 'resource', 'generate', 'seed', 'user'];
 /** These go to the artisan command of the same name. */
 const ARTISAN = ['migrate', 'tinker', 'test', 'serve'];
 
@@ -108,8 +108,13 @@ function inApp(project, command, args) {
   return result.status ?? 1;
 }
 
-/** `nevela update`: bring an app of any age to the latest Nevela. */
-export async function update(project, args, { latest, say }) {
+/**
+ * `nevela upgrade`: bring an app of any age to the latest Nevela.
+ *
+ * The artisan command is called by its older name, nevela:update, which every version of
+ * the package answers to (from 0.3.0 it is an alias of nevela:upgrade).
+ */
+export async function upgrade(project, args, { latest, say }) {
   const check = args.includes('--check');
   const manifestFile = path.join(project.api, 'composer.json');
   const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));

package/selfupdate.mjs

@@ -14,17 +14,27 @@ import { isNewer } from './packagist.mjs';
 
 const REGISTRY = 'https://registry.npmjs.org/create-nevela';
 
-/** The newest create-nevela on npm when it is newer than `current`, else null. Never throws. */
-export async function newerVersion(current) {
+/** The newest create-nevela on npm, or null when npm couldn't be asked. Never throws. */
+export async function latestVersion() {
   try {
     const response = await fetch(`${REGISTRY}/latest`, { signal: AbortSignal.timeout(4000) });
     const latest = (await response.json()).version;
-    return isNewer(latest, current) ? latest : null;
+    return typeof latest === 'string' && /^\d+\.\d+\.\d+$/.test(latest) ? latest : null;
   } catch {
     return null;
   }
 }
 
+/**
+ * The newest create-nevela on npm when it is newer than `current`, else null. Never throws.
+ * Null also when npm couldn't be asked: callers that only want to run the newest carry on
+ * with what they have.
+ */
+export async function newerVersion(current) {
+  const latest = await latestVersion();
+  return latest !== null && isNewer(latest, current) ? latest : null;
+}
+
 /**
  * Unpack a .tar (already gunzipped) into `dir`. Enough of the format for an npm tarball:
  * regular files and directories, with the long-name extensions npm uses.

package/template/laravel/README.md

@@ -43,7 +43,7 @@ Needs PHP 8.2 or newer and Laravel 11, 12 or 13.
 | `nevela:generate` | Regenerate after changing a descriptor. Your own code is kept. |
 | `nevela:seed` | Fill a resource with plausible records, and print how long it took. |
 | `nevela:user` | Create someone who can sign in. |
-| `nevela:update` | Update the package, the generated code and the dashboard. |
+| `nevela:upgrade` | Bring the app to the latest Nevela: the package, the generated code and the dashboard. `nevela:update` is its older name and still works. |
 
 Full documentation: https://nevela-docs.vercel.app
 

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