create-nevela 0.2.1 → 0.4.1

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

@@ -0,0 +1,188 @@
+<?php
+
+namespace Nevela\Laravel\Http\Auth;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use Illuminate\Support\Str;
+use Nevela\Laravel\Auth\Account;
+use Nevela\Laravel\Auth\AuthMail;
+use Nevela\Laravel\Auth\Challenges;
+use Nevela\Laravel\Auth\Passkeys;
+use Nevela\Laravel\Auth\Totp;
+use Nevela\Laravel\Models\Passkey;
+use Nevela\Laravel\Models\TwoFactor;
+use RuntimeException;
+
+/**
+ * How a signed-in person protects their account: a second step for password sign-in,
+ * and passkeys. Anything that weakens the account takes the password again.
+ */
+final class SecurityController
+{
+    use Answers;
+
+    private const BACKUP_CODES = 10;
+
+    /**
+     * POST auth/two-factor/enable
+     *
+     * With `method: "totp"` this starts setting up an authenticator app: it answers with
+     * the secret (as the address a QR code holds) and backup codes, and nothing is
+     * switched on until a code from the app is confirmed. With `method: "email"` codes
+     * are emailed at sign-in, and it is on straight away.
+     */
+    public function enable(Request $request): JsonResponse
+    {
+        $input = $request->validate(['password' => ['required', 'string'], 'method' => ['nullable', 'in:totp,email,otp']]);
+        if (! $this->passwordConfirmed($request)) {
+            return $this->refuse('INVALID_PASSWORD', "That isn't your password.", 422);
+        }
+        $user = $request->user();
+        $method = ($input['method'] ?? 'totp') === 'totp' ? 'totp' : 'email';
+        $this->enabled($method === 'totp' ? 'two_factor.authenticator' : 'two_factor.email');
+
+        [$codes, $hashes] = self::backupCodes();
+        $second = TwoFactor::query()->firstOrNew(['user_id' => (string) $user->getAuthIdentifier()]);
+
+        if ($method === 'email') {
+            $second->fill(['backup_codes' => $hashes, 'enabled_at' => $second->enabled_at ?? now()])->save();
+
+            return response()->json(['enabled' => true, 'backupCodes' => $codes]);
+        }
+
+        $secret = Totp::secret();
+        // Not confirmed yet: sign-in keeps working as it did until a code proves the app has the secret.
+        $second->fill(['secret' => $secret, 'totp_confirmed_at' => null, 'backup_codes' => $hashes])->save();
+
+        return response()->json([
+            'enabled' => false,
+            'totpURI' => Totp::uri($secret, (string) $user->email, AuthMail::app()),
+            'secret' => $secret,
+            'backupCodes' => $codes,
+        ]);
+    }
+
+    /** POST auth/two-factor/confirm: a code from the authenticator app switches it on. */
+    public function confirm(Request $request): JsonResponse
+    {
+        $input = $request->validate(['code' => ['required', 'string', 'max:16']]);
+        $second = Account::twoFactor($request->user());
+        if ($second?->secret === null) {
+            return $this->refuse('TWO_FACTOR_NOT_STARTED', 'Start setting up two-factor first.', 409);
+        }
+        // Spent like any other code, so the one that confirmed the app can't then sign in with it.
+        if (! $second->spendCode($input['code'])) {
+            return $this->refuse('INVALID_TWO_FACTOR_CODE', "That code isn't right. Check it and try again.", 422);
+        }
+        $second->fill(['totp_confirmed_at' => now(), 'enabled_at' => $second->enabled_at ?? now()])->save();
+
+        return response()->json(['enabled' => true, 'user' => Account::describe($request->user())]);
+    }
+
+    /** POST auth/two-factor/disable */
+    public function disable(Request $request): JsonResponse
+    {
+        if (! $this->passwordConfirmed($request)) {
+            return $this->refuse('INVALID_PASSWORD', "That isn't your password.", 422);
+        }
+        TwoFactor::query()->where('user_id', (string) $request->user()->getAuthIdentifier())->delete();
+        AuthMail::send($request->user()->email, 'Two-factor was turned off for your '.AuthMail::app().' account', ['Two-factor sign-in was just turned off for your account.', "If that wasn't you, change your password now."]);
+
+        return response()->json(['enabled' => false]);
+    }
+
+    /** POST auth/two-factor/backup-codes: new codes; the old ones stop working. */
+    public function regenerateBackupCodes(Request $request): JsonResponse
+    {
+        if (! $this->passwordConfirmed($request)) {
+            return $this->refuse('INVALID_PASSWORD', "That isn't your password.", 422);
+        }
+        $second = Account::twoFactor($request->user());
+        if ($second?->enabled_at === null) {
+            return $this->refuse('TWO_FACTOR_NOT_ENABLED', 'Two-factor is not turned on.', 409);
+        }
+        [$codes, $hashes] = self::backupCodes();
+        $second->fill(['backup_codes' => $hashes])->save();
+
+        return response()->json(['backupCodes' => $codes]);
+    }
+
+    /**
+     * Ten codes to keep somewhere safe, each good for one sign-in when the phone isn't
+     * to hand. Shown once; only their hashes are kept.
+     *
+     * @return array{0: list<string>, 1: list<string>}
+     */
+    private static function backupCodes(): array
+    {
+        $codes = [];
+        for ($i = 0; $i < self::BACKUP_CODES; $i++) {
+            $codes[] = strtolower(Str::random(5).'-'.Str::random(5));
+        }
+
+        return [$codes, array_map(Challenges::hash(...), $codes)];
+    }
+
+    /** GET auth/passkeys */
+    public function passkeys(Request $request): JsonResponse
+    {
+        $this->enabled('passkeys');
+
+        return response()->json([
+            'data' => Passkey::query()->where('user_id', (string) $request->user()->getAuthIdentifier())->orderBy('created_at')->get()->map(self::describe(...))->all(),
+        ]);
+    }
+
+    /** POST auth/passkeys/options: start adding a passkey. */
+    public function passkeyOptions(Request $request): JsonResponse
+    {
+        $this->enabled('passkeys');
+
+        return response()->json(Passkeys::creationOptions($request->user(), $request));
+    }
+
+    /** POST auth/passkeys: finish adding it. */
+    public function addPasskey(Request $request): JsonResponse
+    {
+        $this->enabled('passkeys');
+        $input = $request->validate(['challenge' => ['required', 'string'], 'response' => ['required', 'array'], 'name' => ['nullable', 'string', 'max:80']]);
+        try {
+            $passkey = Passkeys::create($request->user(), $input['challenge'], $input['response'], $input['name'] ?? null, $request);
+        } catch (RuntimeException $e) {
+            return $this->refuse('PASSKEY_FAILED', $e->getMessage(), 422);
+        }
+
+        return response()->json(self::describe($passkey), 201);
+    }
+
+    /** PATCH auth/passkeys/{id}: rename it. */
+    public function renamePasskey(Request $request, string $id): JsonResponse
+    {
+        $input = $request->validate(['name' => ['required', 'string', 'max:80']]);
+        $passkey = Passkey::query()->where('user_id', (string) $request->user()->getAuthIdentifier())->findOrFail($id);
+        $passkey->fill(['name' => trim($input['name'])])->save();
+
+        return response()->json(self::describe($passkey));
+    }
+
+    /** DELETE auth/passkeys/{id} */
+    public function removePasskey(Request $request, string $id): Response
+    {
+        Passkey::query()->where('user_id', (string) $request->user()->getAuthIdentifier())->where('id', $id)->delete();
+
+        return response()->noContent();
+    }
+
+    /** @return array<string, mixed> */
+    private static function describe(Passkey $passkey): array
+    {
+        return [
+            'id' => $passkey->id,
+            'name' => $passkey->name,
+            'createdAt' => $passkey->created_at?->toJSON(),
+            'lastUsedAt' => $passkey->last_used_at?->toJSON(),
+        ];
+    }
+}

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