create-nevela 0.4.3 → 0.5.0

package/template/laravel/src/Access/SampleUsers.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace Nevela\Laravel\Access;
+
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Facades\Schema;
+use Nevela\Laravel\Auth\Account;
+use Nevela\Laravel\Models\Role;
+
+/**
+ * Ten people for a new app, so its Users screen, its roles and its permissions have
+ * something to show from the first run: two editors and eight users, one switched off.
+ *
+ * Like the starter admin they are made in the app's local database by the installer,
+ * never by a migration, so they don't follow the app to a server. They all share one
+ * password, which is printed when they are made, so they are never made in production.
+ */
+final class SampleUsers
+{
+    /** Name, role, and whether the account is switched on. The addresses are at example.com, which nobody owns. */
+    public const PEOPLE = [
+        ['Amara Okafor', Role::EDITOR, true],
+        ['Daniel Kim', Role::EDITOR, true],
+        ['Sofia Martinez', Role::USER, true],
+        ['James Mwangi', Role::USER, true],
+        ['Priya Nair', Role::USER, true],
+        ['Lucas Silva', Role::USER, true],
+        ['Hannah Schmidt', Role::USER, true],
+        ['Omar Haddad', Role::USER, true],
+        ['Grace Nakato', Role::USER, true],
+        ['Noah Williams', Role::USER, false],
+    ];
+
+    /** Ten accounts with one password that is written down in the docs have no place on a server. */
+    public static function allowed(): bool
+    {
+        return ! app()->environment('production');
+    }
+
+    /**
+     * Create the first `count` of them who don't exist yet. None, in production.
+     *
+     * @return list<array{name: string, email: string, role: string, active: bool}> Those created
+     */
+    public static function create(string $password, int $count = 10): array
+    {
+        if (! self::allowed() || $password === '') {
+            return [];
+        }
+        $model = Account::model();
+        $table = (new $model)->getTable();
+        $hash = Hash::make($password);
+        $created = [];
+
+        foreach (array_slice(self::PEOPLE, 0, max(0, $count)) as [$name, $role, $active]) {
+            $email = self::email($name);
+            if (Account::findByEmail($email)) {
+                continue;
+            }
+            $attributes = ['name' => $name, 'email' => $email, 'password' => $hash];
+            if (Schema::hasColumn($table, 'email_verified_at')) {
+                $attributes['email_verified_at'] = now();
+            }
+            if (Schema::hasColumn($table, 'active')) {
+                $attributes['active'] = $active;
+            }
+            $user = (new $model)->forceFill($attributes);
+            $user->save();
+            Access::grant($user, $role);
+            $created[] = ['name' => $name, 'email' => $email, 'role' => $role, 'active' => $active];
+        }
+
+        return $created;
+    }
+
+    /** "Amara Okafor" → amara.okafor@example.com */
+    public static function email(string $name): string
+    {
+        return strtolower(str_replace(' ', '.', $name)).'@example.com';
+    }
+}

package/template/laravel/src/Auth/Account.php

@@ -2,10 +2,13 @@
 
 namespace Nevela\Laravel\Auth;
 
+use Illuminate\Http\Exceptions\HttpResponseException;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Schema;
 use Illuminate\Validation\Rules\Password;
+use Nevela\Laravel\Access\Access;
+use Nevela\Laravel\Access\Permissions;
 use Nevela\Laravel\Media\Uploads;
 use Nevela\Laravel\Models\TwoFactor;
 use RuntimeException;
@@ -35,12 +38,20 @@ final class Account
     {
         $avatar = $user->avatar ?? null;
         $file = is_string($avatar) && $avatar !== '' ? Uploads::ref($avatar) : null;
+        $roles = Access::ready() ? Access::rolesOf($user)->pluck('name')->all() : [];
+        $grants = Access::grantsFor($user);
 
         return [
             'id' => (string) $user->getAuthIdentifier(),
             'name' => $user->name ?? null,
             'email' => $user->email ?? null,
-            'role' => $user->role ?? null,
+            // The first role, for code written when an account had one; "roles" has them all.
+            'role' => $roles[0] ?? ($user->role ?? null),
+            'roles' => $roles,
+            // Everything they may do, patterns already resolved, so a client only looks a
+            // permission up. Laravel decides each request for itself whatever a client shows.
+            'permissions' => Permissions::expand($grants),
+            'isAdmin' => Permissions::hasAll($grants),
             '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>.
@@ -62,6 +73,11 @@ final class Account
      */
     public static function signIn(mixed $user, Request $request): array
     {
+        // Every way of signing in ends here, so this is the one place a switched-off
+        // account is turned away, whichever way it came.
+        if (! Access::active($user)) {
+            throw new HttpResponseException(response()->json(['error' => 'This account has been switched off. Ask an administrator.', 'code' => 'ACCOUNT_DISABLED'], 403));
+        }
         if (! method_exists($user, 'createToken')) {
             throw new RuntimeException('Add Laravel\Sanctum\HasApiTokens to '.self::model().' to issue Nevela tokens.');
         }

package/template/laravel/src/Console/SetupCommand.php

@@ -15,9 +15,10 @@ final class SetupCommand extends Command
     protected $signature = 'nevela:setup
         {--name= : Name for the starter account}
         {--email= : Email for the starter account. Leave out to create no account}
-        {--password= : Password for the starter account}';
+        {--password= : Password for the starter account}
+        {--no-sample-users : Create the starter account only, without the ten sample users}';
 
-    protected $description = 'Finish setting up a new app: key, Sanctum\'s migration, generated files, migrations and a starter account';
+    protected $description = 'Finish setting up a new app: key, Sanctum\'s migration, generated files, migrations, a starter account and sample users';
 
     protected $hidden = true;
 
@@ -39,6 +40,7 @@ final class SetupCommand extends Command
         }
 
         if ($this->option('email')) {
+            // The first account in an app is its administrator.
             $status = $this->call('nevela:user', [
                 '--name' => $this->option('name') ?: 'Admin',
                 '--email' => $this->option('email'),
@@ -48,6 +50,13 @@ final class SetupCommand extends Command
                 // The app itself is fine; the installer says how to add an account by hand.
                 return 2;
             }
+            // Ten more people, with the same password, so the Users screen and the roles
+            // have something in them. Only with a password that was given here: one typed
+            // at a prompt isn't known to this command. Never in production (the command
+            // refuses), and missing them is no reason to call the setup failed.
+            if (! $this->option('no-sample-users') && $this->option('password')) {
+                $this->callSilently('nevela:user', ['--sample' => true, '--password' => $this->option('password')]);
+            }
         }
 
         return self::SUCCESS;

package/template/laravel/src/Console/UserCommand.php

@@ -1,59 +1,151 @@
-<?php
-
-namespace Nevela\Laravel\Console;
-
-use Illuminate\Console\Command;
-use Illuminate\Support\Facades\Hash;
-use Illuminate\Support\Facades\Validator;
-
-final class UserCommand extends Command
-{
-    protected $signature = 'nevela:user
-        {--name= : The person\'s name}
-        {--email= : The address they sign in with}
-        {--password= : Their password. Leave out to be asked for it without it showing}';
-
-    protected $description = 'Create a user who can sign in to the dashboard';
-
-    public function handle(): int
-    {
-        $model = config('auth.providers.users.model');
-        if (! is_string($model) || ! class_exists($model)) {
-            $this->components->error('No user model is configured in config/auth.php (auth.providers.users.model).');
-
-            return self::FAILURE;
-        }
-
-        $input = [
-            'name' => $this->option('name') ?? $this->ask('Name'),
-            'email' => $this->option('email') ?? $this->ask('Email'),
-            'password' => $this->option('password') ?? $this->secret('Password (at least 8 characters)'),
-        ];
-
-        $table = (new $model)->getTable();
-        $validator = Validator::make($input, [
-            'name' => ['required', 'string', 'max:255'],
-            'email' => ['required', 'email', 'max:255', "unique:{$table},email"],
-            'password' => ['required', 'string', 'min:8'],
-        ]);
-        if ($validator->fails()) {
-            foreach ($validator->errors()->all() as $message) {
-                $this->components->error($message);
-            }
-
-            return self::FAILURE;
-        }
-
-        // forceFill: this is the operator creating an account, not a form to guard.
-        $user = (new $model)->forceFill([
-            'name' => $input['name'],
-            'email' => $input['email'],
-            'password' => Hash::make($input['password']),
-        ]);
-        $user->save();
-
-        $this->components->info("Created {$input['email']}. They can sign in to the dashboard now.");
-
-        return self::SUCCESS;
-    }
-}
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Facades\Validator;
+use Nevela\Laravel\Access\Access;
+use Nevela\Laravel\Access\SampleUsers;
+use Nevela\Laravel\Auth\Account;
+use Nevela\Laravel\Models\Role;
+
+final class UserCommand extends Command
+{
+    protected $signature = 'nevela:user
+        {--name= : The person\'s name}
+        {--email= : The address they sign in with}
+        {--password= : Their password. Leave out to be asked for it without it showing}
+        {--role= : Their role: ADMIN, EDITOR, USER or one you have made. The first account is an ADMIN}
+        {--sample : Create the ten sample users instead: two editors and eight users}';
+
+    protected $description = 'Create a user who can sign in to the dashboard';
+
+    public function handle(): int
+    {
+        $model = config('auth.providers.users.model');
+        if (! is_string($model) || ! class_exists($model)) {
+            $this->components->error('No user model is configured in config/auth.php (auth.providers.users.model).');
+
+            return self::FAILURE;
+        }
+        if ($this->option('sample')) {
+            return $this->sample();
+        }
+
+        $asked = $this->option('email') === null;
+        $input = [
+            'name' => $this->option('name') ?? $this->ask('Name'),
+            // As it will be stored, so that what is checked is what is saved.
+            'email' => mb_strtolower(trim((string) ($this->option('email') ?? $this->ask('Email')))),
+            'password' => $this->option('password') ?? $this->secret('Password (at least 8 characters)'),
+        ];
+
+        $table = (new $model)->getTable();
+        $validator = Validator::make($input, [
+            'name' => ['required', 'string', 'max:255'],
+            // Compared without regard to capitals, whatever the database does: Ada@ and ada@ are one person.
+            'email' => ['required', 'email', 'max:255', function (string $attribute, mixed $value, \Closure $fail) {
+                if (is_string($value) && Account::findByEmail($value)) {
+                    $fail('Someone already has this email.');
+                }
+            }],
+            'password' => ['required', 'string', 'min:8'],
+        ]);
+        if ($validator->fails()) {
+            foreach ($validator->errors()->all() as $message) {
+                $this->components->error($message);
+            }
+
+            return self::FAILURE;
+        }
+
+        $role = $this->role($asked);
+        if ($role === false) {
+            return self::FAILURE;
+        }
+
+        // forceFill: this is the operator creating an account, not a form to guard.
+        $attributes = ['name' => $input['name'], 'email' => $input['email'], 'password' => Hash::make($input['password'])];
+        if (Schema::hasColumn($table, 'email_verified_at')) {
+            $attributes['email_verified_at'] = now();
+        }
+        $user = (new $model)->forceFill($attributes);
+        $user->save();
+        if ($role !== null) {
+            Access::grant($user, $role);
+        }
+
+        $as = $role === null ? '' : " as {$role}";
+        $this->components->info("Created {$attributes['email']}{$as}. They can sign in to the dashboard now.");
+        if ($role !== null && $role !== Role::ADMIN && ! $this->option('role')) {
+            $this->line("  To give them another role: the dashboard's Users screen, or <fg=cyan>--role=ADMIN</> here.");
+        }
+
+        return self::SUCCESS;
+    }
+
+    /**
+     * The role for the new account: null when this app has no roles yet (its migrations
+     * haven't run), false when the one asked for doesn't exist.
+     */
+    private function role(bool $asked): string|false|null
+    {
+        if (! Access::ready()) {
+            return null;
+        }
+        $names = Role::query()->orderByDesc('is_system')->orderBy('name')->pluck('name')->all();
+        $wanted = $this->option('role');
+        if ($wanted !== null) {
+            foreach ($names as $name) {
+                if (strcasecmp($name, (string) $wanted) === 0) {
+                    return $name;
+                }
+            }
+            $this->components->error("There is no role called \"{$wanted}\". The roles are: ".implode(', ', $names).'.');
+
+            return false;
+        }
+        // Someone has to be able to manage the rest: the first account is the administrator.
+        if (Access::otherAdmins() === 0) {
+            return Role::ADMIN;
+        }
+
+        return $asked && $this->input->isInteractive() ? (string) $this->choice('Role', $names, Role::USER) : Role::USER;
+    }
+
+    private function sample(): int
+    {
+        if (! Access::ready()) {
+            $this->components->error('Roles need a migration that has not been run: php nevela migrate');
+
+            return self::FAILURE;
+        }
+        if (! SampleUsers::allowed()) {
+            $this->components->error('Sample users are for development: ten accounts sharing one password. This app is in production, so none were made.');
+
+            return self::FAILURE;
+        }
+        $password = (string) ($this->option('password') ?? 'password');
+        if (mb_strlen($password) < 8) {
+            $this->components->error('Give the sample users a password of at least 8 characters, or leave --password out for "password".');
+
+            return self::FAILURE;
+        }
+        $created = SampleUsers::create($password);
+        if ($created === []) {
+            $this->components->info('The sample users are already here.');
+
+            return self::SUCCESS;
+        }
+        foreach ($created as $person) {
+            $this->components->twoColumnDetail("{$person['name']} <fg=gray>{$person['email']}</>", $person['role'].($person['active'] ? '' : ' <fg=gray>(switched off)</>'));
+        }
+        $this->newLine();
+        $this->components->info('Created '.count($created)." sample users. They all sign in with the password \"{$password}\".");
+        $this->line('  They are in this database only. Delete them before real use: the dashboard\'s Users screen.');
+
+        return self::SUCCESS;
+    }
+}

package/template/laravel/src/Generator/ResourceGenerator.php

@@ -806,34 +806,35 @@ final class ResourceGenerator
         /**
          * Who may do what with {$d->pluralLabel}. Generated once — this file is yours.
          *
-         * Default: any signed-in user (routes already require auth:sanctum). Tighten this
-         * before production, e.g. `return in_array(\$user->role, ['admin', 'staff']);`.
+         * Each action asks for a permission, which a person has through their roles
+         * (the dashboard's Roles screen). Add your own conditions beside them, e.g.
+         * `return \$user->can('{$d->table}.edit') && \${$var}->user_id === \$user->id;`.
          */
         class {$d->name}Policy
         {
             public function viewAny(User \$user): bool
             {
-                return true;
+                return \$user->can('{$d->table}.view');
             }
 
             public function view(User \$user, {$d->name} \${$var}): bool
             {
-                return true;
+                return \$user->can('{$d->table}.view');
             }
 
             public function create(User \$user): bool
             {
-                return true;
+                return \$user->can('{$d->table}.create');
             }
 
             public function update(User \$user, {$d->name} \${$var}): bool
             {
-                return true;
+                return \$user->can('{$d->table}.edit');
             }
 
             public function delete(User \$user, {$d->name} \${$var}): bool
             {
-                return true;
+                return \$user->can('{$d->table}.delete');
             }
         }
 

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

@@ -0,0 +1,24 @@
+<?php
+
+namespace Nevela\Laravel\Http\Access;
+
+use Closure;
+use Illuminate\Http\Request;
+use Nevela\Laravel\Access\Access;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * The users and roles endpoints need tables that an upgraded app doesn't have until it
+ * has run its migrations. Until then they say so, in place of a database error.
+ */
+final class RolesAreSetUp
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        if (! Access::ready()) {
+            return response()->json(['error' => 'Roles need a migration that has not been run: php nevela migrate', 'code' => 'MIGRATION_NEEDED'], 409);
+        }
+
+        return $next($request);
+    }
+}

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

@@ -0,0 +1,197 @@
+<?php
+
+namespace Nevela\Laravel\Http\Access;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Gate;
+use Illuminate\Validation\Rule;
+use Nevela\Laravel\Access\Access;
+use Nevela\Laravel\Access\Permissions;
+use Nevela\Laravel\Http\Auth\Answers;
+use Nevela\Laravel\Models\Role;
+use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+/**
+ * Roles: named sets of grants.
+ *
+ * The same ceiling as for users applies: a role can be given only what its editor holds,
+ * so editing roles is never a way to gain a permission. The ADMIN role always grants
+ * everything, and the three built-in roles keep their names and can't be deleted.
+ */
+final class RolesController
+{
+    use Answers;
+
+    /** GET _nevela/permissions: every permission there is, shaped for the roles screen. */
+    public function catalog(): JsonResponse
+    {
+        Gate::authorize('roles.view');
+
+        return response()->json(['modules' => Permissions::catalog(), 'total' => count(Permissions::keys())]);
+    }
+
+    /** GET _nevela/roles. Open to anyone who manages users too: the user form lists them. */
+    public function index(Request $request): JsonResponse
+    {
+        $user = $request->user();
+        if (! $user->can('roles.view') && ! $user->can('users.view')) {
+            throw new AccessDeniedHttpException("You don't have access to this.");
+        }
+        $counts = DB::table('nevela_role_user')->groupBy('role_id')->selectRaw('role_id, count(*) as users')->pluck('users', 'role_id');
+        $held = Access::grantsFor($user);
+        $roles = Role::query()->orderByDesc('is_system')->orderBy('name')->get();
+
+        return response()->json(['data' => $roles->map(fn (Role $role) => self::present($role, (int) ($counts[$role->id] ?? 0), $held))->all()]);
+    }
+
+    /** GET _nevela/roles/{id} */
+    public function show(Request $request, string $id): JsonResponse
+    {
+        Gate::authorize('roles.view');
+        $role = $this->find($id);
+
+        return response()->json(self::present($role, $this->users($role), Access::grantsFor($request->user())));
+    }
+
+    /** POST _nevela/roles */
+    public function store(Request $request): JsonResponse
+    {
+        Gate::authorize('roles.create');
+        $input = $this->validated($request, null);
+        if ($refused = $this->beyondCaller($request, $input['grants'])) {
+            return $refused;
+        }
+        $role = Role::query()->create(['name' => $input['name'], 'description' => $input['description'] ?? null, 'grants' => $input['grants'], 'is_system' => false]);
+
+        return response()->json(self::present($role, 0, Access::grantsFor($request->user())), 201);
+    }
+
+    /** PATCH _nevela/roles/{id}: any of name, description, grants. */
+    public function update(Request $request, string $id): JsonResponse
+    {
+        Gate::authorize('roles.edit');
+        $role = $this->find($id);
+        $input = $this->validated($request, $role);
+        $held = Access::grantsFor($request->user());
+
+        // A role that already allows more than its editor holds is not theirs to reshape.
+        if (Permissions::beyond($held, $role->grants) !== []) {
+            return $this->refuse('BEYOND_YOUR_OWN', "You can't change the {$role->name} role: it allows things your own roles don't.", 403);
+        }
+        if ($role->is_system && isset($input['name']) && $input['name'] !== $role->name) {
+            return $this->refuse('BUILT_IN', "The {$role->name} role is built in. It can be edited, and not renamed.", 409);
+        }
+        if (array_key_exists('grants', $input)) {
+            if ($role->name === Role::ADMIN && $role->is_system && ! in_array('*', $input['grants'], true)) {
+                return $this->refuse('BUILT_IN', 'The ADMIN role always allows everything. Make another role for less.', 409);
+            }
+            if ($refused = $this->beyondCaller($request, $input['grants'])) {
+                return $refused;
+            }
+        }
+
+        $role->fill(array_intersect_key($input, array_flip(['name', 'description', 'grants'])))->save();
+        Access::forget();
+
+        return response()->json(self::present($role, $this->users($role), $held));
+    }
+
+    /** DELETE _nevela/roles/{id} */
+    public function destroy(Request $request, string $id): JsonResponse|Response
+    {
+        Gate::authorize('roles.delete');
+        $role = $this->find($id);
+        if ($role->is_system) {
+            return $this->refuse('BUILT_IN', "The {$role->name} role is built in and can't be deleted.", 409);
+        }
+        if (Permissions::beyond(Access::grantsFor($request->user()), $role->grants) !== []) {
+            return $this->refuse('BEYOND_YOUR_OWN', "You can't delete the {$role->name} role: it allows things your own roles don't.", 403);
+        }
+        // Deleting it would quietly take its permissions from everyone who holds it.
+        if (($users = $this->users($role)) > 0) {
+            return $this->refuse('IN_USE', $users === 1 ? 'One user has this role. Give them another before deleting it.' : "{$users} users have this role. Give them another before deleting it.", 409);
+        }
+        $role->delete();
+        Access::forget();
+
+        return response()->noContent();
+    }
+
+    private function find(string $id): Role
+    {
+        return Role::query()->find($id) ?? throw new NotFoundHttpException('No such role.');
+    }
+
+    private function users(Role $role): int
+    {
+        return DB::table('nevela_role_user')->where('role_id', $role->id)->count();
+    }
+
+    /** @return array{name?: string, description?: string|null, grants?: list<string>} */
+    private function validated(Request $request, ?Role $role): array
+    {
+        $sometimes = $role ? ['sometimes'] : [];
+        $input = $request->validate([
+            'name' => [...$sometimes, 'required', 'string', 'min:2', 'max:80', 'regex:/^[\pL\pN][\pL\pN _-]*$/u', function (string $attribute, mixed $value, \Closure $fail) use ($role) {
+                // "Support" and "support" would be two roles nobody could tell apart.
+                $taken = Role::query()->whereRaw('lower(name) = ?', [mb_strtolower((string) $value)])->when($role, fn ($query) => $query->where('id', '!=', $role->id))->exists();
+                if ($taken) {
+                    $fail('There is already a role with this name.');
+                }
+            }],
+            'description' => ['sometimes', 'nullable', 'string', 'max:500'],
+            'grants' => [...$sometimes, 'present', 'array', 'max:2000'],
+            // bail: what follows reads the value as text, which a list sent in its place is not.
+            'grants.*' => ['bail', 'string', 'max:120', function (string $attribute, mixed $value, \Closure $fail) {
+                if (! is_string($value) || ! Permissions::understood($value)) {
+                    $fail(is_string($value) ? "\"{$value}\" isn't a permission this app has." : 'A grant is a piece of text.');
+                }
+            }],
+        ], ['name.regex' => 'Use letters, numbers, spaces, dashes and underscores.']);
+        if (isset($input['grants'])) {
+            $input['grants'] = array_values(array_unique($input['grants']));
+        }
+
+        return $input;
+    }
+
+    /** @param list<string> $grants */
+    private function beyondCaller(Request $request, array $grants): ?JsonResponse
+    {
+        $beyond = Permissions::beyond(Access::grantsFor($request->user()), $grants);
+        if ($beyond === []) {
+            return null;
+        }
+
+        return response()->json([
+            'error' => "A role can't allow more than you hold yourself: ".implode(', ', array_slice($beyond, 0, 6)).(count($beyond) > 6 ? ', and '.(count($beyond) - 6).' more' : '').'.',
+            'code' => 'BEYOND_YOUR_OWN',
+            'beyond' => $beyond,
+        ], 403);
+    }
+
+    /**
+     * @param  list<string>  $held  The grants of whoever is asking
+     * @return array<string, mixed>
+     */
+    public static function present(Role $role, int $users, array $held): array
+    {
+        return [
+            'id' => $role->id,
+            'name' => $role->name,
+            'description' => $role->description,
+            // As written, patterns included, and what they come to today.
+            'grants' => $role->grants,
+            'permissions' => Permissions::expand($role->grants),
+            'isSystem' => (bool) $role->is_system,
+            'isAdmin' => Permissions::hasAll($role->grants),
+            'users' => $users,
+            // Whether whoever is asking may give this role to someone, or change it.
+            'withinYours' => Permissions::beyond($held, $role->grants) === [],
+        ];
+    }
+}