create-nevela 0.4.3 → 0.5.0

package/template/laravel/src/Http/Access/UsersController.php

@@ -0,0 +1,382 @@
+<?php
+
+namespace Nevela\Laravel\Http\Access;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Gate;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Validation\Rule;
+use Nevela\Laravel\Access\Access;
+use Nevela\Laravel\Access\Permissions;
+use Nevela\Laravel\Auth\Account;
+use Nevela\Laravel\Auth\AuthMail;
+use Nevela\Laravel\Http\Auth\Answers;
+use Nevela\Laravel\Media\Uploads;
+use Nevela\Laravel\Models\Role;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+/**
+ * The people who can sign in, for someone allowed to manage them.
+ *
+ * Three rules sit on top of the permissions (users.view, .create, .edit, .delete), so that
+ * managing users is never a way to take more than you were given:
+ *
+ *   - you hand out only roles whose grants you hold yourself;
+ *   - you change only accounts that may do no more than you. Otherwise setting someone's
+ *     password, or their email and then asking for a reset, would be a way to sign in as
+ *     them and have what they have;
+ *   - the last administrator can't be removed, switched off or demoted, by anyone.
+ */
+final class UsersController
+{
+    use Answers;
+
+    /** GET _nevela/users?q=&role=&status=&page=&perPage= */
+    public function index(Request $request): JsonResponse
+    {
+        Gate::authorize('users.view');
+        $input = $request->validate([
+            'q' => ['nullable', 'string', 'max:200'],
+            'role' => ['nullable', 'string', 'max:64'],
+            'status' => ['nullable', Rule::in(['active', 'inactive'])],
+            'page' => ['nullable', 'integer', 'min:1'],
+            'perPage' => ['nullable', 'integer', 'min:1', 'max:100'],
+        ]);
+        $model = Account::model();
+        $instance = new $model;
+        $query = $model::query();
+
+        if (($search = trim((string) ($input['q'] ?? ''))) !== '') {
+            $pattern = '%'.str_replace(['\\', '%', '_'], ['\\\\', '\\%', '\\_'], mb_strtolower($search)).'%';
+            $query->where(fn ($where) => $where->whereRaw('lower(name) like ?', [$pattern])->orWhereRaw('lower(email) like ?', [$pattern]));
+        }
+        if (! empty($input['role'])) {
+            // Read as a list first: the link table keeps ids as text, whatever type they are here.
+            $query->whereIn($instance->getKeyName(), DB::table('nevela_role_user')->where('role_id', $input['role'])->pluck('user_id')->all());
+        }
+        if (isset($input['status']) && Schema::hasColumn($instance->getTable(), 'active')) {
+            $query->where('active', $input['status'] === 'active');
+        }
+
+        $perPage = (int) ($input['perPage'] ?? 25);
+        $page = (int) ($input['page'] ?? 1);
+        $total = (clone $query)->count();
+        $users = $query->orderBy('name')->orderBy($instance->getKeyName())->forPage($page, $perPage)->get();
+
+        return response()->json([
+            'data' => self::present($users, $request->user()),
+            'meta' => ['page' => $page, 'perPage' => $perPage, 'total' => $total, 'totalPages' => max(1, (int) ceil($total / $perPage))],
+        ]);
+    }
+
+    /** GET _nevela/users/{id} */
+    public function show(Request $request, string $id): JsonResponse
+    {
+        Gate::authorize('users.view');
+
+        return response()->json(self::present(collect([$this->find($id)]), $request->user())[0]);
+    }
+
+    /** POST _nevela/users */
+    public function store(Request $request): JsonResponse
+    {
+        Gate::authorize('users.create');
+        $model = Account::model();
+        $user = new $model;
+        $input = $request->validate([
+            'name' => ['required', 'string', 'max:255'],
+            'email' => ['required', 'email', 'max:255'],
+            'password' => Account::passwordRules(),
+            'roles' => ['present', 'array', 'max:50'],
+            'roles.*' => ['string', 'max:64'],
+            'active' => ['nullable', 'boolean'],
+        ]);
+        if (Account::findByEmail($input['email'])) {
+            return response()->json(['error' => 'Validation failed.', 'issues' => [['path' => 'email', 'message' => 'Someone already has this email.']]], 422);
+        }
+        $roles = $this->roles($input['roles']);
+        if ($roles instanceof JsonResponse) {
+            return $roles;
+        }
+        if ($refused = $this->beyondCaller($request, $roles)) {
+            return $refused;
+        }
+
+        $attributes = ['name' => $input['name'], 'email' => mb_strtolower(trim($input['email'])), 'password' => Hash::make($input['password'])];
+        if (Schema::hasColumn($user->getTable(), 'active')) {
+            $attributes['active'] = (bool) ($input['active'] ?? true);
+        }
+        if (Schema::hasColumn($user->getTable(), 'email_verified_at')) {
+            // Someone allowed to create users vouches for the address.
+            $attributes['email_verified_at'] = now();
+        }
+        $user->forceFill($attributes)->save();
+        Access::assign($user, $roles->pluck('id')->all());
+
+        return response()->json(self::present(collect([$user]), $request->user())[0], 201);
+    }
+
+    /** PATCH _nevela/users/{id}: any of name, email, password, roles, active. */
+    public function update(Request $request, string $id): JsonResponse
+    {
+        Gate::authorize('users.edit');
+        $user = $this->find($id);
+        $caller = $request->user();
+        $self = (string) $caller->getAuthIdentifier() === (string) $user->getAuthIdentifier();
+        $input = $request->validate([
+            'name' => ['sometimes', 'required', 'string', 'max:255'],
+            'email' => ['sometimes', 'required', 'email', 'max:255'],
+            'password' => ['sometimes', ...Account::passwordRules()],
+            'roles' => ['sometimes', 'array', 'max:50'],
+            'roles.*' => ['string', 'max:64'],
+            'active' => ['sometimes', 'boolean'],
+        ]);
+
+        $wasAdmin = $this->holdsEverything($user);
+        if (! $self && ($refused = $this->aboveCaller($caller, $user, 'change'))) {
+            return $refused;
+        }
+        if (isset($input['email'])) {
+            $taken = Account::findByEmail($input['email']);
+            if ($taken && (string) $taken->getAuthIdentifier() !== (string) $user->getAuthIdentifier()) {
+                return response()->json(['error' => 'Validation failed.', 'issues' => [['path' => 'email', 'message' => 'Someone already has this email.']]], 422);
+            }
+        }
+
+        $roles = null;
+        if (array_key_exists('roles', $input)) {
+            $roles = $this->roles($input['roles']);
+            if ($roles instanceof JsonResponse) {
+                return $roles;
+            }
+            // Only what is being added is checked: a role they already hold isn't being handed out.
+            $held = Access::rolesOf($user)->pluck('id')->all();
+            if ($refused = $this->beyondCaller($request, $roles->reject(fn (Role $role) => in_array($role->id, $held, true)))) {
+                return $refused;
+            }
+        }
+
+        $deactivating = array_key_exists('active', $input) && ! $input['active'] && Access::active($user);
+        if ($deactivating && $self) {
+            return $this->refuse('SELF', "You can't switch your own account off. Ask another administrator.", 409);
+        }
+        $demoting = $roles !== null && $wasAdmin && ! $roles->contains(fn (Role $role) => Permissions::hasAll($role->grants));
+        if (($deactivating || $demoting) && $wasAdmin && Access::active($user) && Access::otherAdmins($user) === 0) {
+            return $this->refuse('LAST_ADMIN', 'This is the only administrator. Make someone else an administrator first.', 409);
+        }
+
+        $attributes = [];
+        if (isset($input['name'])) {
+            $attributes['name'] = $input['name'];
+        }
+        if (isset($input['email'])) {
+            $attributes['email'] = mb_strtolower(trim($input['email']));
+        }
+        if (isset($input['password'])) {
+            $attributes['password'] = Hash::make($input['password']);
+        }
+        if (array_key_exists('active', $input) && Schema::hasColumn($user->getTable(), 'active')) {
+            $attributes['active'] = (bool) $input['active'];
+        }
+        if ($attributes !== []) {
+            $user->forceFill($attributes)->save();
+        }
+        if ($roles !== null) {
+            Access::assign($user, $roles->pluck('id')->all());
+        }
+
+        // A new password or a switched-off account ends every session it had. Their own
+        // session survives their own password change, as it does on the account page.
+        if ($deactivating || isset($input['password'])) {
+            Account::revokeTokens($user, $self ? $caller->currentAccessToken()?->getKey() : null);
+        }
+        if (isset($input['password']) && ! $self) {
+            AuthMail::send($user->email, 'Your '.AuthMail::app().' password was changed', ['An administrator set a new password for your account.', "If you weren't expecting this, ask them about it before signing in."]);
+        }
+        Access::forget();
+
+        return response()->json(self::present(collect([$user->refresh()]), $caller)[0]);
+    }
+
+    /** DELETE _nevela/users/{id} */
+    public function destroy(Request $request, string $id): JsonResponse|Response
+    {
+        Gate::authorize('users.delete');
+        $user = $this->find($id);
+        $caller = $request->user();
+        if ((string) $caller->getAuthIdentifier() === (string) $user->getAuthIdentifier()) {
+            return $this->refuse('SELF', "You can't delete your own account here.", 409);
+        }
+        if ($refused = $this->aboveCaller($caller, $user, 'delete')) {
+            return $refused;
+        }
+        if ($this->holdsEverything($user) && Access::active($user) && Access::otherAdmins($user) === 0) {
+            return $this->refuse('LAST_ADMIN', 'This is the only administrator. Make someone else an administrator first.', 409);
+        }
+
+        $key = (string) $user->getAuthIdentifier();
+        DB::transaction(function () use ($user, $key) {
+            Account::revokeTokens($user);
+            DB::table('nevela_role_user')->where('user_id', $key)->delete();
+            foreach (['nevela_two_factor', 'nevela_passkeys'] as $table) {
+                if (Schema::hasTable($table)) {
+                    DB::table($table)->where('user_id', $key)->delete();
+                }
+            }
+            $user->delete();
+        });
+        Access::forget();
+
+        return response()->noContent();
+    }
+
+    /** DELETE _nevela/users/{id}/sessions: sign them out of every device. */
+    public function revokeSessions(Request $request, string $id): JsonResponse
+    {
+        Gate::authorize('users.edit');
+        $user = $this->find($id);
+        $self = (string) $request->user()->getAuthIdentifier() === (string) $user->getAuthIdentifier();
+        if (! $self && ($refused = $this->aboveCaller($request->user(), $user, 'sign out'))) {
+            return $refused;
+        }
+
+        return response()->json(['revoked' => Account::revokeTokens($user, $self ? $request->user()->currentAccessToken()?->getKey() : null)]);
+    }
+
+    private function find(string $id): mixed
+    {
+        return Account::model()::query()->find($id) ?? throw new NotFoundHttpException('No such user.');
+    }
+
+    /**
+     * A refusal when the account may do something the caller may not, and null otherwise.
+     *
+     * What the account may do is read from its roles, not from whether it is switched on:
+     * a switched-off administrator is still not for a lesser manager to give a new
+     * password and switch back on.
+     */
+    private function aboveCaller(mixed $caller, mixed $user, string $verb): ?JsonResponse
+    {
+        if (self::within(Access::grantsFor($caller), $user)) {
+            return null;
+        }
+
+        return $this->holdsEverything($user)
+            ? $this->refuse('ADMIN_ONLY', "Only an administrator can {$verb} an administrator's account.", 403)
+            : $this->refuse('ABOVE_YOUR_OWN', "You can't {$verb} this account: it may do things your own roles don't allow.", 403);
+    }
+
+    /**
+     * Whether everything an account's roles allow is covered by `$held`.
+     *
+     * @param  list<string>  $held
+     * @param  iterable<Role>|null  $roles  The account's roles, when they are already at hand
+     */
+    private static function within(array $held, mixed $user, ?iterable $roles = null): bool
+    {
+        $theirs = [];
+        foreach ($roles ?? Access::rolesOf($user) as $role) {
+            array_push($theirs, ...$role->grants);
+        }
+
+        return Permissions::beyond($held, $theirs) === [];
+    }
+
+    /** Whether this account holds a role that comes to everything. */
+    private function holdsEverything(mixed $user): bool
+    {
+        return Access::rolesOf($user)->contains(fn (Role $role) => Permissions::hasAll($role->grants));
+    }
+
+    /**
+     * The roles named by id, or a 422 when one doesn't exist.
+     *
+     * @param  list<string>  $ids
+     * @return Collection<int, Role>|JsonResponse
+     */
+    private function roles(array $ids): Collection|JsonResponse
+    {
+        $ids = array_values(array_unique($ids));
+        $roles = Role::query()->whereIn('id', $ids)->get();
+        if ($roles->count() !== count($ids)) {
+            return response()->json(['error' => 'Validation failed.', 'issues' => [['path' => 'roles', 'message' => 'One of those roles no longer exists. Reload and try again.']]], 422);
+        }
+
+        return $roles;
+    }
+
+    /** @param Collection<int, Role> $roles */
+    private function beyondCaller(Request $request, Collection $roles): ?JsonResponse
+    {
+        $held = Access::grantsFor($request->user());
+        foreach ($roles as $role) {
+            if (Permissions::beyond($held, $role->grants) !== []) {
+                return $this->refuse('BEYOND_YOUR_OWN', "You can't give someone the {$role->name} role: it allows things your own roles don't.", 403);
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Users as the dashboard shows them, with what a list needs asked for once and not per row.
+     *
+     * @param  Collection<int, mixed>  $users
+     * @return list<array<string, mixed>>
+     */
+    public static function present(Collection $users, mixed $caller): array
+    {
+        $ids = $users->map(fn ($user) => (string) $user->getAuthIdentifier())->all();
+        if ($ids === []) {
+            return [];
+        }
+        $roles = Role::query()->get()->keyBy('id');
+        $held = [];
+        foreach (DB::table('nevela_role_user')->whereIn('user_id', $ids)->get() as $link) {
+            if ($role = $roles->get($link->role_id)) {
+                $held[$link->user_id][] = $role;
+            }
+        }
+        $secondStep = Schema::hasTable('nevela_two_factor')
+            ? DB::table('nevela_two_factor')->whereIn('user_id', $ids)->whereNotNull('enabled_at')->pluck('user_id')->flip()
+            : collect();
+        $first = $users->first();
+        $devices = DB::table('personal_access_tokens')
+            ->where('tokenable_type', $first->getMorphClass())->whereIn('tokenable_id', $ids)
+            ->groupBy('tokenable_id')->selectRaw('tokenable_id, count(*) as devices, max(last_used_at) as last_used_at')
+            ->get()->keyBy(fn ($row) => (string) $row->tokenable_id);
+
+        $callerGrants = Access::grantsFor($caller);
+
+        return $users->map(function ($user) use ($held, $secondStep, $devices, $caller, $callerGrants) {
+            $id = (string) $user->getAuthIdentifier();
+            $mine = collect($held[$id] ?? [])->sortBy('name')->values();
+            $avatar = $user->avatar ?? null;
+            $file = is_string($avatar) && $avatar !== '' ? Uploads::ref($avatar) : null;
+            $seen = $devices->get($id);
+
+            return [
+                'id' => $id,
+                'name' => $user->name ?? null,
+                'email' => $user->email ?? null,
+                'active' => Access::active($user),
+                'emailVerified' => ($user->email_verified_at ?? null) !== null,
+                'twoFactorEnabled' => $secondStep->has($id),
+                'image' => $file ? ($file['renditions']->thumb['url'] ?? $file['url']) : null,
+                'roles' => $mine->map(fn (Role $role) => ['id' => $role->id, 'name' => $role->name])->all(),
+                'isAdmin' => $mine->contains(fn (Role $role) => Permissions::hasAll($role->grants)),
+                'isSelf' => $id === (string) $caller->getAuthIdentifier(),
+                // Whether whoever is asking may change this account: it may do no more than they may.
+                'withinYours' => self::within($callerGrants, $user, $mine),
+                'devices' => (int) ($seen->devices ?? 0),
+                'lastActiveAt' => ! empty($seen?->last_used_at) ? date(DATE_ATOM, strtotime($seen->last_used_at)) : null,
+                'createdAt' => $user->created_at?->toAtomString(),
+            ];
+        })->all();
+    }
+}

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

@@ -8,6 +8,7 @@ use Illuminate\Http\Response;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Hash;
 use Illuminate\Support\Facades\Schema;
+use Nevela\Laravel\Access\Access;
 use Nevela\Laravel\Auth\Account;
 use Nevela\Laravel\Auth\AuthMail;
 use Nevela\Laravel\Auth\Challenges;
@@ -46,11 +47,14 @@ final class AccountController
 
         $user = new $model;
         $attributes = ['name' => $input['name'], 'email' => mb_strtolower(trim($input['email'])), 'password' => Hash::make($input['password'])];
-        $role = config('nevela.auth.default_role');
+        $role = config('nevela.auth.default_role', 'USER');
         if ($role !== null && Schema::hasColumn($user->getTable(), 'role')) {
             $attributes['role'] = $role;
         }
         $user->forceFill($attributes)->save();
+        if (is_string($role) && $role !== '') {
+            Access::grant($user, $role);
+        }
         self::sendVerification($user, $request);
 
         if (config('nevela.auth.require_email_verification', false)) {

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

@@ -0,0 +1,73 @@
+<?php
+
+namespace Nevela\Laravel\Models;
+
+use Illuminate\Database\Eloquent\Concerns\HasUuids;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * A named set of grants. See Nevela\Laravel\Access\Permissions for what a grant is.
+ *
+ * Grants are kept as written, patterns included: a role holding "products.*" goes on
+ * covering products when an action is added, which a list of the permissions it came to
+ * on the day it was saved would not.
+ *
+ * @property string $id
+ * @property string $name
+ * @property string|null $description
+ * @property list<string> $grants
+ * @property bool $is_system
+ */
+class Role extends Model
+{
+    use HasUuids;
+
+    /** The three every app starts with. They can be edited, and not renamed or deleted. */
+    public const ADMIN = 'ADMIN';
+
+    public const EDITOR = 'EDITOR';
+
+    public const USER = 'USER';
+
+    protected $table = 'nevela_roles';
+
+    protected $guarded = [];
+
+    protected function casts(): array
+    {
+        return ['is_system' => 'boolean'];
+    }
+
+    /**
+     * The grants, as a list. A value that can't be read comes to no grants at all: this
+     * decides who may do what, and the safe way to fail is to refuse.
+     *
+     * @return list<string>
+     */
+    public function getGrantsAttribute(mixed $value): array
+    {
+        $decoded = is_string($value) ? json_decode($value, true) : $value;
+
+        return is_array($decoded) ? array_values(array_filter($decoded, 'is_string')) : [];
+    }
+
+    /** @param list<string>|null $value */
+    public function setGrantsAttribute(mixed $value): void
+    {
+        $this->attributes['grants'] = json_encode(array_values(array_unique(array_filter((array) $value, 'is_string'))));
+    }
+
+    /**
+     * The roles a new app is given.
+     *
+     * @return list<array{name: string, description: string, grants: list<string>}>
+     */
+    public static function defaults(): array
+    {
+        return [
+            ['name' => self::ADMIN, 'description' => 'Full access to every feature and action.', 'grants' => ['*']],
+            ['name' => self::EDITOR, 'description' => 'Works with the app\'s records. Sees who the users are, and manages neither users nor roles.', 'grants' => ['@resources.*', 'users.view']],
+            ['name' => self::USER, 'description' => 'A standard account. Signs in and manages its own profile, and nothing else.', 'grants' => []],
+        ];
+    }
+}

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.4.3';
+    public const VERSION = '0.5.0';
 
     /** @var array<string, Descriptor> */
     private static array $descriptors = [];
@@ -63,6 +63,7 @@ final class Nevela
     public static function forget(): void
     {
         self::$descriptors = [];
+        Access\Permissions::forget();
     }
 
     /**

package/template/laravel/src/NevelaServiceProvider.php

@@ -6,9 +6,12 @@ use Illuminate\Contracts\Debug\ExceptionHandler;
 use Illuminate\Cache\RateLimiting\Limit;
 use Illuminate\Foundation\Console\ServeCommand;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Gate;
 use Illuminate\Support\Facades\RateLimiter;
 use Illuminate\Support\Facades\Route;
 use Illuminate\Support\ServiceProvider;
+use Nevela\Laravel\Access\Access;
+use Nevela\Laravel\Access\Permissions;
 use Nevela\Laravel\Console\DevCommand;
 use Nevela\Laravel\Console\GenerateCommand;
 use Nevela\Laravel\Console\MakeResourceCommand;
@@ -18,6 +21,9 @@ use Nevela\Laravel\Console\StatusCommand;
 use Nevela\Laravel\Console\UpdateCommand;
 use Nevela\Laravel\Console\UserCommand;
 use Nevela\Laravel\Console\VersionCommand;
+use Nevela\Laravel\Http\Access\RolesAreSetUp;
+use Nevela\Laravel\Http\Access\RolesController;
+use Nevela\Laravel\Http\Access\UsersController;
 use Nevela\Laravel\Http\FlareErrors;
 use Nevela\Laravel\Http\Auth\AccountController;
 use Nevela\Laravel\Http\Auth\SecurityController;
@@ -59,6 +65,12 @@ final class NevelaServiceProvider extends ServiceProvider
             }
         });
 
+        // An ability shaped like a permission ("products.view") is answered from the
+        // person's roles. So `$user->can('products.view')`, `Gate::authorize(...)` and
+        // `@can` all work, in a policy or anywhere else. Any other ability is left to
+        // the app's own policies and gates.
+        Gate::before(fn ($user, $ability) => is_string($ability) && Permissions::isPermission($ability) ? Access::allows($user, $ability) : null);
+
         if (! $this->app->routesAreCached()) {
             $this->registerRoutes();
         }
@@ -159,6 +171,23 @@ final class NevelaServiceProvider extends ServiceProvider
                 'data' => array_map(fn ($name) => (array) Uploads::profile($name), array_keys((array) config('nevela.uploads.profiles', ['default' => []]))),
             ]))->name('profiles');
 
+            // Users and roles, for whoever holds the permissions to manage them.
+            Route::middleware(RolesAreSetUp::class)->group(function () {
+                Route::get('_nevela/users', [UsersController::class, 'index'])->name('users.index');
+                Route::post('_nevela/users', [UsersController::class, 'store'])->name('users.store');
+                Route::get('_nevela/users/{id}', [UsersController::class, 'show'])->name('users.show');
+                Route::patch('_nevela/users/{id}', [UsersController::class, 'update'])->name('users.update');
+                Route::delete('_nevela/users/{id}', [UsersController::class, 'destroy'])->name('users.destroy');
+                Route::delete('_nevela/users/{id}/sessions', [UsersController::class, 'revokeSessions'])->name('users.sessions.revoke');
+
+                Route::get('_nevela/permissions', [RolesController::class, 'catalog'])->name('permissions');
+                Route::get('_nevela/roles', [RolesController::class, 'index'])->name('roles.index');
+                Route::post('_nevela/roles', [RolesController::class, 'store'])->name('roles.store');
+                Route::get('_nevela/roles/{id}', [RolesController::class, 'show'])->name('roles.show');
+                Route::patch('_nevela/roles/{id}', [RolesController::class, 'update'])->name('roles.update');
+                Route::delete('_nevela/roles/{id}', [RolesController::class, 'destroy'])->name('roles.destroy');
+            });
+
             // The descriptors, so the web app (and tooling) can check it matches the API.
             Route::get('_nevela/resources', fn () => response()->json([
                 'data' => array_map(fn ($d) => $d->toArray(), Nevela::all()),

package/template/web/app/api/[...path]/route.ts

@@ -64,7 +64,11 @@ export async function GET(request: NextRequest, context: Context) {
     const value = request.headers.get(name);
     if (value) conditional[name] = value;
   }
-  return forward(url, { method: "GET", headers: { Accept: request.headers.get("accept") ?? "application/json", ...conditional } }, !isFile);
+  // The API's answers are JSON, whatever the browser said it would accept. Asked that way,
+  // a request with no session is told 401; asked as a page, Laravel would try to send it
+  // to a sign-in route this app doesn't have. A file is asked for as the browser wants it.
+  const accept = isFile ? (request.headers.get("accept") ?? "*/*") : "application/json";
+  return forward(url, { method: "GET", headers: { Accept: accept, ...conditional } }, !isFile);
 }
 
 export async function PUT(request: NextRequest, context: Context) {

package/template/web/app/dashboard/access/actions.ts

@@ -0,0 +1,70 @@
+"use server";
+
+import { revalidatePath } from "next/cache";
+import { accessError, type ManagedRole, type ManagedUser } from "@/lib/access";
+import { laravel } from "@/lib/laravel";
+import { getSession } from "@/lib/session";
+
+/**
+ * Changes to users and roles. Each one is a call to Laravel, which checks the person's
+ * permissions and the rules on top of them (nobody hands out more than they hold; the
+ * last administrator stays), and whose answer is passed back as it is.
+ */
+
+export type AccessResult<T = unknown> = { ok: true; data: T } | { ok: false; error: string; issues?: { path: string; message: string }[] };
+
+async function send<T>(path: string, method: "POST" | "PATCH" | "DELETE", body?: unknown): Promise<AccessResult<T>> {
+  if (!(await getSession())) return { ok: false, error: "Sign in to continue." };
+  const response = await laravel(path, { method, body });
+  if (!response.ok) {
+    const issues = (response.body as { issues?: { path: string; message: string }[] } | null)?.issues;
+    return { ok: false, error: accessError(response), ...(issues ? { issues } : {}) };
+  }
+  revalidatePath("/dashboard/access", "layout");
+  return { ok: true, data: response.body as T };
+}
+
+export interface UserInput {
+  name?: string;
+  email?: string;
+  /** Left out, the password stays as it is. */
+  password?: string;
+  /** Role ids. */
+  roles?: string[];
+  active?: boolean;
+}
+
+export async function createUserAction(input: UserInput): Promise<AccessResult<ManagedUser>> {
+  return send("_nevela/users", "POST", input);
+}
+
+export async function updateUserAction(id: string, input: UserInput): Promise<AccessResult<ManagedUser>> {
+  return send(`_nevela/users/${encodeURIComponent(id)}`, "PATCH", input);
+}
+
+export async function deleteUserAction(id: string): Promise<AccessResult<null>> {
+  return send(`_nevela/users/${encodeURIComponent(id)}`, "DELETE");
+}
+
+/** Sign someone out of every device. */
+export async function signOutUserAction(id: string): Promise<AccessResult<{ revoked: number }>> {
+  return send(`_nevela/users/${encodeURIComponent(id)}/sessions`, "DELETE");
+}
+
+export interface RoleInput {
+  name?: string;
+  description?: string | null;
+  grants?: string[];
+}
+
+export async function createRoleAction(input: RoleInput): Promise<AccessResult<ManagedRole>> {
+  return send("_nevela/roles", "POST", input);
+}
+
+export async function updateRoleAction(id: string, input: RoleInput): Promise<AccessResult<ManagedRole>> {
+  return send(`_nevela/roles/${encodeURIComponent(id)}`, "PATCH", input);
+}
+
+export async function deleteRoleAction(id: string): Promise<AccessResult<null>> {
+  return send(`_nevela/roles/${encodeURIComponent(id)}`, "DELETE");
+}