create-nevela 0.3.0 → 0.4.1

package/template/laravel/src/Http/Auth/SignInController.php

@@ -0,0 +1,302 @@
+<?php
+
+namespace Nevela\Laravel\Http\Auth;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Hash;
+use Nevela\Laravel\Auth\Account;
+use Nevela\Laravel\Auth\AuthMail;
+use Nevela\Laravel\Auth\Challenges;
+use Nevela\Laravel\Auth\Passkeys;
+use Nevela\Laravel\Auth\Web;
+use Nevela\Laravel\Models\TwoFactor;
+use RuntimeException;
+
+/**
+ * Getting signed in: with a password (and a second step when one is set up), a passkey,
+ * an emailed link or an emailed code. Each ends the same way, with a Sanctum token.
+ *
+ * Errors carry a `code` beside the message, so a client can say something more useful
+ * than the message, in its own words.
+ */
+final class SignInController
+{
+    use Answers;
+
+    /** How long a sign-in waits for its second step, and an emailed code or link lasts. */
+    private const SECOND_STEP = 600;
+
+    private const EMAILED = 300;
+
+    /** Which ways of signing in are switched on, for a client drawing the sign-in page. */
+    public function config(): JsonResponse
+    {
+        return response()->json(self::methods());
+    }
+
+    /** @return array<string, mixed> */
+    public static function methods(): array
+    {
+        return [
+            'registration' => (bool) config('nevela.auth.registration', false),
+            'magicLink' => (bool) config('nevela.auth.magic_link', true),
+            'emailCode' => (bool) config('nevela.auth.email_code', true),
+            'passkeys' => (bool) config('nevela.auth.passkeys', true),
+            'twoFactor' => [
+                'authenticator' => (bool) config('nevela.auth.two_factor.authenticator', true),
+                'email' => (bool) config('nevela.auth.two_factor.email', true),
+            ],
+            'requireEmailVerification' => (bool) config('nevela.auth.require_email_verification', false),
+        ];
+    }
+
+    /** POST auth/token: email and password. */
+    public function password(Request $request): JsonResponse
+    {
+        $input = $request->validate([
+            'email' => ['required', 'email'],
+            'password' => ['required', 'string'],
+            'deviceName' => ['nullable', 'string', 'max:255'],
+        ]);
+
+        $user = Account::findByEmail($input['email']);
+        // A password is checked even when there is no such account, against a hash of
+        // nothing: otherwise "no such account" would answer faster than "wrong password",
+        // and the difference tells a visitor which addresses have accounts.
+        $right = Hash::check($input['password'], $user ? (string) $user->getAuthPassword() : self::decoy());
+        if (! $user || ! $right) {
+            return $this->refuse('INVALID_EMAIL_OR_PASSWORD', "That email and password don't match.", 401);
+        }
+        if (config('nevela.auth.require_email_verification', false) && $user->email_verified_at === null) {
+            AccountController::sendVerification($user, $request);
+
+            return $this->refuse('EMAIL_NOT_VERIFIED', "Verify your email first: we've sent you a new link.", 403);
+        }
+
+        return self::finish($user, $request);
+    }
+
+    /**
+     * The first step is done: sign the person in, or ask for the second step.
+     *
+     * When the first step was an email (a sign-in link, a sign-in code, a verification
+     * code), an emailed code is not offered as the second: it would be the same thing
+     * twice, and someone who had only got into the mailbox would be let in. So an account
+     * with an authenticator app is asked for the app or a backup code, and an account
+     * whose only second step is email is signed in, which is all its owner asked for.
+     */
+    public static function finish(mixed $user, Request $request, bool $byEmail = false): JsonResponse
+    {
+        $second = Account::twoFactor($user);
+        $app = $second?->usesAuthenticator() && config('nevela.auth.two_factor.authenticator', true);
+        if ($second?->enabled_at === null || ($byEmail && ! $app)) {
+            return response()->json(Account::signIn($user, $request), 201);
+        }
+
+        $methods = array_values(array_filter([
+            $app ? 'totp' : null,
+            ! $byEmail && config('nevela.auth.two_factor.email', true) ? 'email' : null,
+            ($second->backup_codes ?? []) !== [] ? 'backup' : null,
+        ]));
+
+        return response()->json([
+            'twoFactor' => true,
+            'challenge' => Challenges::start('two-factor', ['user' => (string) $user->getAuthIdentifier(), 'device' => $request->input('deviceName'), 'methods' => $methods], self::SECOND_STEP),
+            'methods' => $methods,
+        ]);
+    }
+
+    /** A password hash that matches nothing, made once per process with the app's own hashing settings. */
+    private static function decoy(): string
+    {
+        static $hash = null;
+
+        return $hash ??= Hash::make(bin2hex(random_bytes(16)));
+    }
+
+    /** POST auth/two-factor/send: email a code for a sign-in that is waiting for its second step. */
+    public function sendSecondStep(Request $request): JsonResponse
+    {
+        $this->enabled('two_factor.email');
+        $challenge = (string) $request->input('challenge');
+        $pending = Challenges::get('two-factor', $challenge);
+        $user = $pending ? Account::model()::query()->find($pending['user']) : null;
+        if (! $user) {
+            return $this->refuse('SESSION_EXPIRED', 'That sign-in has expired. Start again.', 401);
+        }
+        if (! in_array('email', $pending['methods'] ?? [], true)) {
+            return $this->refuse('METHOD_NOT_ALLOWED', "An emailed code can't be the second step for this sign-in. Use your authenticator app or a backup code.", 422);
+        }
+
+        if (! Challenges::mayIssue('two-factor', (string) $pending['user'])) {
+            return $this->refuse('TOO_MANY_ATTEMPTS', 'Too many codes were asked for. Try again in an hour, or use another method.', 429);
+        }
+        [$code, $hash] = Challenges::code();
+        Challenges::update('two-factor', $challenge, ['code' => $hash]);
+        AuthMail::send($user->email, 'Your '.AuthMail::app().' sign-in code', ["Your sign-in code is {$code}.", 'It expires in 10 minutes.'], null, $code);
+
+        return response()->json(['sent' => true]);
+    }
+
+    /** POST auth/two-factor/verify: finish a password sign-in with a code. */
+    public function secondStep(Request $request): JsonResponse
+    {
+        $input = $request->validate([
+            'challenge' => ['required', 'string'],
+            'method' => ['required', 'in:totp,email,backup'],
+            'code' => ['required', 'string', 'max:64'],
+        ]);
+        $pending = Challenges::get('two-factor', $input['challenge']);
+        $user = $pending ? Account::model()::query()->find($pending['user']) : null;
+        $second = $user ? Account::twoFactor($user) : null;
+        if (! $user || $second?->enabled_at === null) {
+            return $this->refuse('SESSION_EXPIRED', 'That sign-in has expired. Start again.', 401);
+        }
+
+        if (! in_array($input['method'], $pending['methods'] ?? [], true)) {
+            return $this->refuse('METHOD_NOT_ALLOWED', "That isn't a way to finish this sign-in. Use your authenticator app or a backup code.", 422);
+        }
+        $right = match ($input['method']) {
+            'totp' => $second->usesAuthenticator() && $second->spendCode($input['code']),
+            'email' => isset($pending['code']) && hash_equals($pending['code'], Challenges::hash($input['code'])),
+            'backup' => self::spendBackupCode($second, $input['code']),
+        };
+        if (! $right) {
+            return Challenges::miss('two-factor', $input['challenge'])
+                ? $this->refuse('INVALID_TWO_FACTOR_CODE', "That code isn't right. Check it and try again.", 401)
+                : $this->refuse('TOO_MANY_ATTEMPTS', 'Too many attempts. Sign in again.', 429);
+        }
+
+        Challenges::forget('two-factor', $input['challenge']);
+        $request->merge(['deviceName' => $pending['device'] ?? null]);
+
+        return response()->json(Account::signIn($user, $request), 201);
+    }
+
+    /**
+     * A backup code works once. The row is locked while it is read and written, so two
+     * requests arriving together with the same code can't both be let in.
+     */
+    private static function spendBackupCode(TwoFactor $second, string $code): bool
+    {
+        $hash = Challenges::hash(strtolower($code));
+
+        return DB::transaction(function () use ($second, $hash) {
+            $row = TwoFactor::query()->whereKey($second->getKey())->lockForUpdate()->first();
+            $codes = $row?->backup_codes ?? [];
+            foreach ($codes as $index => $stored) {
+                if (hash_equals($stored, $hash)) {
+                    unset($codes[$index]);
+                    $row->forceFill(['backup_codes' => array_values($codes)])->save();
+
+                    return true;
+                }
+            }
+
+            return false;
+        });
+    }
+
+    /** POST auth/magic-link: email a link that signs the person in. */
+    public function sendLink(Request $request): JsonResponse
+    {
+        $this->enabled('magic_link');
+        $input = $request->validate(['email' => ['required', 'email'], 'next' => ['nullable', 'string', 'max:2000']]);
+
+        // The answer is the same whether or not the address has an account.
+        if ($user = Account::findByEmail($input['email'])) {
+            $token = Challenges::start('magic-link', ['user' => (string) $user->getAuthIdentifier()], self::EMAILED);
+            $url = Web::url('/api/auth/magic-link', ['token' => $token, 'next' => Web::path($input['next'] ?? null)], $request);
+            AuthMail::send($user->email, 'Sign in to '.AuthMail::app(), ['Use this link to sign in. It works once and expires in 5 minutes.'], ['Sign in', $url], $url);
+        }
+
+        return response()->json(['sent' => true]);
+    }
+
+    /** POST auth/magic-link/verify */
+    public function link(Request $request): JsonResponse
+    {
+        $this->enabled('magic_link');
+        $pending = Challenges::take('magic-link', (string) $request->input('token'));
+        $user = $pending ? Account::model()::query()->find($pending['user']) : null;
+        if (! $user) {
+            return $this->refuse('INVALID_TOKEN', 'That sign-in link has expired or was already used. Ask for a new one.', 401);
+        }
+        // Opening a link sent to the address proves the address.
+        if ($user->email_verified_at === null) {
+            $user->forceFill(['email_verified_at' => now()])->save();
+        }
+
+        return self::finish($user, $request, byEmail: true);
+    }
+
+    /** POST auth/email-code: email a six-digit sign-in code. */
+    public function sendCode(Request $request): JsonResponse
+    {
+        $this->enabled('email_code');
+        $input = $request->validate(['email' => ['required', 'email']]);
+
+        if (($user = Account::findByEmail($input['email'])) && Challenges::mayIssue('email-code', mb_strtolower($user->email))) {
+            [$code, $hash] = Challenges::code();
+            Challenges::put('email-code', mb_strtolower($user->email), ['user' => (string) $user->getAuthIdentifier(), 'code' => $hash], self::EMAILED);
+            AuthMail::send($user->email, 'Your '.AuthMail::app().' sign-in code', ["Your sign-in code is {$code}.", 'It expires in 5 minutes.'], null, $code);
+        }
+
+        return response()->json(['sent' => true]);
+    }
+
+    /** POST auth/email-code/verify */
+    public function code(Request $request): JsonResponse
+    {
+        $this->enabled('email_code');
+        $input = $request->validate(['email' => ['required', 'email'], 'code' => ['required', 'string', 'max:16']]);
+        $id = mb_strtolower(trim($input['email']));
+        $pending = Challenges::get('email-code', $id);
+        if ($pending === null) {
+            return $this->refuse('OTP_EXPIRED', 'That code has expired. Ask for a new one.', 401);
+        }
+        if (! hash_equals($pending['code'], Challenges::hash($input['code']))) {
+            return Challenges::miss('email-code', $id)
+                ? $this->refuse('INVALID_OTP', "That code isn't right. Check it and try again.", 401)
+                : $this->refuse('TOO_MANY_ATTEMPTS', 'Too many attempts. Ask for a new code.', 429);
+        }
+        Challenges::forget('email-code', $id);
+        $user = Account::model()::query()->find($pending['user']);
+        if (! $user) {
+            return $this->refuse('OTP_EXPIRED', 'That code has expired. Ask for a new one.', 401);
+        }
+        if ($user->email_verified_at === null) {
+            $user->forceFill(['email_verified_at' => now()])->save();
+        }
+
+        return self::finish($user, $request, byEmail: true);
+    }
+
+    /** POST auth/passkey/options: what the browser needs to ask the device for a passkey. */
+    public function passkeyOptions(Request $request): JsonResponse
+    {
+        $this->enabled('passkeys');
+
+        return response()->json(Passkeys::requestOptions($request));
+    }
+
+    /** POST auth/passkey: sign in with the passkey the device answered with. */
+    public function passkey(Request $request): JsonResponse
+    {
+        $this->enabled('passkeys');
+        $input = $request->validate(['challenge' => ['required', 'string'], 'response' => ['required', 'array']]);
+        try {
+            $passkey = Passkeys::verify($input['challenge'], $input['response'], $request);
+        } catch (RuntimeException $e) {
+            return $this->refuse('PASSKEY_FAILED', $e->getMessage(), 401);
+        }
+        $user = Account::model()::query()->find($passkey->user_id);
+        if (! $user) {
+            return $this->refuse('PASSKEY_FAILED', "This passkey's account no longer exists.", 401);
+        }
+
+        return response()->json(Account::signIn($user, $request), 201);
+    }
+}

package/template/laravel/src/Http/TokenController.php

@@ -5,49 +5,36 @@ namespace Nevela\Laravel\Http;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Http\Response;
-use Illuminate\Support\Facades\Hash;
-use Illuminate\Validation\ValidationException;
-use RuntimeException;
+use Nevela\Laravel\Auth\Account;
 
 /**
- * Sanctum personal access tokens for the Next.js app.
+ * The Sanctum token a client is signed in with: who it belongs to, and giving it up.
  *
- * The Next.js server exchanges credentials for a token, keeps it in an httpOnly cookie,
- * and sends it as `Authorization: Bearer …` on every call to Laravel. The browser never
- * sees the token.
+ * The Next.js server keeps the token in an httpOnly cookie and sends it as
+ * `Authorization: Bearer …` on every call to Laravel. The browser never sees it.
+ * Getting a token is Auth\SignInController's job.
  */
 final class TokenController
 {
-    public function store(Request $request): JsonResponse
-    {
-        $credentials = $request->validate([
-            'email' => ['required', 'email'],
-            'password' => ['required', 'string'],
-            'deviceName' => ['nullable', 'string', 'max:255'],
-        ]);
-
-        $model = config('auth.providers.users.model');
-        $user = $model::query()->where('email', $credentials['email'])->first();
-        if (! $user || ! Hash::check($credentials['password'], $user->getAuthPassword())) {
-            throw ValidationException::withMessages(['email' => 'These credentials do not match our records.']);
-        }
-        if (! method_exists($user, 'createToken')) {
-            throw new RuntimeException('Add Laravel\Sanctum\HasApiTokens to '.$model.' to issue Nevela tokens.');
-        }
-
-        $token = $user->createToken($credentials['deviceName'] ?? config('nevela.auth.token_name', 'nevela-web'));
-
-        return response()->json(['token' => $token->plainTextToken, 'user' => self::user($user)], 201);
-    }
-
+    /** GET auth/me */
     public function show(Request $request): JsonResponse
     {
-        return response()->json(['user' => self::user($request->user())]);
+        $token = $request->user()->currentAccessToken();
+
+        return response()->json([
+            'user' => self::user($request->user()),
+            // Which of the account's devices is asking: its id in GET auth/sessions.
+            'session' => ['id' => $token && method_exists($token, 'getKey') ? (string) $token->getKey() : null],
+        ]);
     }
 
+    /** DELETE auth/token: sign this device out. */
     public function destroy(Request $request): Response
     {
-        $request->user()?->currentAccessToken()?->delete();
+        $token = $request->user()?->currentAccessToken();
+        if ($token && method_exists($token, 'delete')) {
+            $token->delete();
+        }
 
         return response()->noContent();
     }
@@ -55,11 +42,6 @@ final class TokenController
     /** What the dashboard needs to know about the signed-in user. */
     public static function user(mixed $user): array
     {
-        return [
-            'id' => (string) $user->getAuthIdentifier(),
-            'name' => $user->name ?? null,
-            'email' => $user->email ?? null,
-            'role' => $user->role ?? null,
-        ];
+        return Account::describe($user);
     }
 }

package/template/laravel/src/Http/UploadController.php

@@ -12,6 +12,8 @@ use Nevela\Laravel\Media\UploadRejected;
 use Nevela\Laravel\Media\Uploads;
 use Nevela\Laravel\Models\Upload;
 use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\Field;
 use Symfony\Component\HttpFoundation\Response;
 
 /**
@@ -30,24 +32,36 @@ final class UploadController
         try {
             $descriptor = Nevela::resource($resource);
         } catch (InvalidArgumentException) {
-            return $this->refuse(404, "There is no resource called {$resource}.");
+            return self::refuse(404, "There is no resource called {$resource}.");
         }
         $definition = $descriptor->fields[$field] ?? null;
         if ($definition === null || $definition->kind !== 'file') {
-            return $this->refuse(404, "{$resource} has no file field called {$field}.");
+            return self::refuse(404, "{$resource} has no file field called {$field}.");
         }
         $model = 'App\\Models\\'.$descriptor->name;
         // Storing a file is a write, so it takes the permission to create a record. Being
         // allowed to look at the resource is not enough.
         if (class_exists($model) && Gate::getPolicyFor($model) !== null && ! Gate::allows('create', $model)) {
-            return $this->refuse(403, "You can't upload files to {$descriptor->pluralLabel}.");
+            return self::refuse(403, "You can't upload files to {$descriptor->pluralLabel}.");
         }
 
+        $upload = self::receive($request, $descriptor, $definition);
+
+        return $upload instanceof JsonResponse ? $upload : response()->json(Uploads::ref($upload->key), 201);
+    }
+
+    /**
+     * Take the file in a request's body, check it against a field and store it. Returns
+     * the upload, or the response that says why it was refused. Shared with the profile
+     * picture, which is an image field on the user without being a generated resource.
+     */
+    public static function receive(Request $request, Descriptor $descriptor, Field $definition): Upload|JsonResponse
+    {
         $name = basename(str_replace('\\', '/', (string) $request->query('name', 'file')));
         $limit = Uploads::maxBytes();
         $megabytes = round($limit / 1024 / 1024, 1);
         if ((int) $request->header('Content-Length', '0') > $limit) {
-            return $this->refuse(413, "{$name} is larger than the {$megabytes} MB this field takes.");
+            return self::refuse(413, "{$name} is larger than the {$megabytes} MB this field takes.");
         }
 
         // Copied to a temporary file with the limit enforced while it arrives: the length
@@ -62,10 +76,10 @@ final class UploadController
                 fclose($out);
             }
             if ($written === false || $written === 0) {
-                return $this->refuse(422, 'The upload arrived empty. Try again.');
+                return self::refuse(422, 'The upload arrived empty. Try again.');
             }
             if ($written > $limit) {
-                return $this->refuse(413, "{$name} is larger than the {$megabytes} MB this field takes.");
+                return self::refuse(413, "{$name} is larger than the {$megabytes} MB this field takes.");
             }
 
             $mime = FileTypes::sniff($path);
@@ -75,16 +89,14 @@ final class UploadController
             if (FileTypes::forbidden($mime) || ! FileTypes::accepts($definition->accept, $effective) || ! FileTypes::consistent($declared, $mime)) {
                 $wanted = in_array('any', $definition->accept, true) ? 'a file this field can store' : implode(' or ', $definition->accept).' data';
 
-                return $this->refuse(422, "{$name} doesn't contain {$wanted}. It may have been renamed; choose the original file.");
+                return self::refuse(422, "{$name} doesn't contain {$wanted}. It may have been renamed; choose the original file.");
             }
 
             try {
-                $upload = Uploads::store($descriptor, $definition, $name, $path, strtolower(trim(explode(';', $effective)[0])), (string) ($request->user()?->getAuthIdentifier() ?? '') ?: null);
+                return Uploads::store($descriptor, $definition, $name, $path, strtolower(trim(explode(';', $effective)[0])), (string) ($request->user()?->getAuthIdentifier() ?? '') ?: null);
             } catch (UploadRejected $e) {
-                return $this->refuse(422, $e->getMessage());
+                return self::refuse(422, $e->getMessage());
             }
-
-            return response()->json(Uploads::ref($upload->key), 201);
         } finally {
             @unlink($path);
         }
@@ -140,7 +152,7 @@ final class UploadController
         ]);
     }
 
-    private function refuse(int $status, string $message): JsonResponse
+    private static function refuse(int $status, string $message): JsonResponse
     {
         return response()->json(['error' => $message], $status);
     }

package/template/laravel/src/Models/Passkey.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Nevela\Laravel\Models;
+
+use Illuminate\Database\Eloquent\Concerns\HasUuids;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * A passkey: the public half of a key pair whose private half never leaves the person's
+ * device. Nothing here is secret.
+ *
+ * @property string $user_id
+ * @property string|null $name
+ * @property string $credential_id  base64url
+ * @property string $public_key     PEM
+ * @property int $counter
+ * @property list<string>|null $transports
+ * @property \Illuminate\Support\Carbon|null $last_used_at
+ */
+class Passkey extends Model
+{
+    use HasUuids;
+
+    protected $table = 'nevela_passkeys';
+
+    protected $guarded = [];
+
+    protected $hidden = ['public_key'];
+
+    protected function casts(): array
+    {
+        return [
+            'counter' => 'integer',
+            'transports' => 'array',
+            'last_used_at' => 'datetime',
+        ];
+    }
+}

package/template/laravel/src/Models/TwoFactor.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace Nevela\Laravel\Models;
+
+use Illuminate\Database\Eloquent\Concerns\HasUuids;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * One person's second step for signing in.
+ *
+ * The authenticator app's secret and the backup codes are encrypted with the app key:
+ * a copy of the database alone is not enough to produce a code. Backup codes are also
+ * only kept as hashes.
+ *
+ * @property string $user_id
+ * @property string|null $secret
+ * @property \Illuminate\Support\Carbon|null $totp_confirmed_at
+ * @property list<string>|null $backup_codes
+ * @property \Illuminate\Support\Carbon|null $enabled_at
+ */
+class TwoFactor extends Model
+{
+    use HasUuids;
+
+    protected $table = 'nevela_two_factor';
+
+    protected $guarded = [];
+
+    protected $hidden = ['secret', 'backup_codes'];
+
+    protected function casts(): array
+    {
+        return [
+            'secret' => 'encrypted',
+            'backup_codes' => 'encrypted:array',
+            'totp_confirmed_at' => 'datetime',
+            'enabled_at' => 'datetime',
+        ];
+    }
+
+    /**
+     * Accept a code from the authenticator app, once. False when the code is wrong, or
+     * when it is one that was already used (or older than one that was).
+     */
+    public function spendCode(string $code): bool
+    {
+        $step = $this->secret === null ? null : \Nevela\Laravel\Auth\Totp::step((string) $this->secret, $code);
+        if ($step === null) {
+            return false;
+        }
+        // One statement decides it, so two requests with the same code can't both win.
+        $taken = static::query()->whereKey($this->getKey())
+            ->where(fn ($query) => $query->whereNull('totp_last_step')->orWhere('totp_last_step', '<', $step))
+            ->update(['totp_last_step' => $step]);
+
+        return $taken === 1;
+    }
+
+    /** Whether codes from an authenticator app are set up and confirmed. */
+    public function usesAuthenticator(): bool
+    {
+        return $this->secret !== null && $this->totp_confirmed_at !== null;
+    }
+}

package/template/laravel/src/Nevela.php

@@ -18,7 +18,7 @@ use Nevela\Laravel\Support\Naming;
 final class Nevela
 {
     /** Written by `pnpm release`; the same number as the repository's git tag. */
-    public const VERSION = '0.3.0';
+    public const VERSION = '0.4.1';
 
     /** @var array<string, Descriptor> */
     private static array $descriptors = [];