create-nevela 0.4.3 → 0.5.1

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

@@ -0,0 +1,271 @@
+<?php
+
+namespace Nevela\Laravel\Access;
+
+use Nevela\Laravel\Nevela;
+
+/**
+ * Every permission this app understands, and the rules for matching a grant against one.
+ *
+ * A permission is `feature.action`: "products.view", "users.edit". The feature is a
+ * resource's table, or one of the built-in ones (users, roles), or one the app adds in
+ * config/nevela.php. The action is one of create, view, edit, delete.
+ *
+ * A role holds grants, and a grant may be a pattern:
+ *
+ *   *                  everything
+ *   products.*         every action on products
+ *   *.view             viewing everything
+ *   @resources.*       every action on every resource, including ones added later
+ *   @resources.view    viewing every resource
+ *
+ * The model, the names and the matching rules are Grit's (internal/authz), so a role means
+ * the same thing in both.
+ */
+final class Permissions
+{
+    public const ACTIONS = ['create', 'view', 'edit', 'delete'];
+
+    /** @var list<array{key: string, name: string, groups: list<array{key: string, name: string, features: list<array{key: string, name: string, actions: list<string>}>}>}>|null */
+    private static ?array $catalog = null;
+
+    /**
+     * The catalog, shaped for the roles screen: modules, their groups, their features.
+     * Only the feature and the action appear in a permission; the rest is for reading.
+     *
+     * @return list<array{key: string, name: string, groups: list<array{key: string, name: string, features: list<array{key: string, name: string, actions: list<string>}>}>}>
+     */
+    public static function catalog(): array
+    {
+        if (self::$catalog !== null) {
+            return self::$catalog;
+        }
+
+        $taken = ['users' => true, 'roles' => true];
+        $modules = [[
+            'key' => 'access',
+            'name' => 'Access',
+            'groups' => [[
+                'key' => 'identity',
+                'name' => 'Identity',
+                'features' => [
+                    ['key' => 'users', 'name' => 'Users', 'actions' => self::ACTIONS],
+                    ['key' => 'roles', 'name' => 'Roles and permissions', 'actions' => self::ACTIONS],
+                ],
+            ]],
+        ]];
+
+        // One feature per resource, under the heading it has in the sidebar.
+        $groups = [];
+        foreach (Nevela::all() as $descriptor) {
+            if (isset($taken[$descriptor->table])) {
+                continue; // a resource on the users or roles table is governed by the built-in feature
+            }
+            $taken[$descriptor->table] = true;
+            $heading = trim((string) ($descriptor->group ?? '')) ?: 'Resources';
+            $groups[$heading] ??= ['key' => self::slug($heading), 'name' => $heading, 'features' => []];
+            $groups[$heading]['features'][] = ['key' => $descriptor->table, 'name' => $descriptor->pluralLabel, 'actions' => self::ACTIONS];
+        }
+        if ($groups !== []) {
+            $modules[] = ['key' => 'resources', 'name' => 'Resources', 'groups' => array_values($groups)];
+        }
+
+        // The app's own: config('nevela.permissions') = ['reports' => ['name' => 'Reports', 'actions' => ['view']]].
+        $custom = [];
+        foreach ((array) config('nevela.permissions', []) as $key => $feature) {
+            $key = is_string($key) ? $key : (string) ($feature['key'] ?? '');
+            if (! preg_match('/^[a-z][a-z0-9_]*$/', $key) || isset($taken[$key])) {
+                continue;
+            }
+            $taken[$key] = true;
+            $actions = array_values(array_intersect(self::ACTIONS, (array) ($feature['actions'] ?? self::ACTIONS)));
+            $custom[] = ['key' => $key, 'name' => (string) ($feature['name'] ?? ucfirst(str_replace('_', ' ', $key))), 'actions' => $actions ?: self::ACTIONS];
+        }
+        if ($custom !== []) {
+            $modules[] = ['key' => 'app', 'name' => 'App', 'groups' => [['key' => 'app', 'name' => 'App', 'features' => $custom]]];
+        }
+
+        return self::$catalog = $modules;
+    }
+
+    /** Forget the catalog, after the descriptors or the config change. */
+    public static function forget(): void
+    {
+        self::$catalog = null;
+    }
+
+    /**
+     * Every permission in the catalog, sorted.
+     *
+     * @return list<string>
+     */
+    public static function keys(): array
+    {
+        $keys = [];
+        foreach (self::catalog() as $module) {
+            foreach ($module['groups'] as $group) {
+                foreach ($group['features'] as $feature) {
+                    foreach ($feature['actions'] as $action) {
+                        $keys[] = "{$feature['key']}.{$action}";
+                    }
+                }
+            }
+        }
+        sort($keys);
+
+        return $keys;
+    }
+
+    /** Whether `ability` has the shape of a permission, so the gate answers for it. */
+    public static function isPermission(string $ability): bool
+    {
+        return (bool) preg_match('/^[a-z][a-z0-9_]*\.(create|view|edit|delete)$/', $ability);
+    }
+
+    /**
+     * Whether any of the grants allows `key`.
+     *
+     * @param  list<string>  $grants
+     */
+    public static function granted(array $grants, string $key): bool
+    {
+        foreach ($grants as $grant) {
+            if (is_string($grant) && self::matches($grant, $key)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Whether one grant covers one permission.
+     *
+     * A pattern is checked to its end: "products.*" covers "products.view", and "*.view"
+     * covers "products.view" and nothing else of products. Stopping at the first "*"
+     * would turn "*.view" into "everything".
+     */
+    public static function matches(string $pattern, string $key): bool
+    {
+        if ($pattern === '*' || $pattern === $key) {
+            return true;
+        }
+        $p = explode('.', $pattern);
+        $k = explode('.', $key);
+        if (count($p) !== 2 || count($k) !== 2) {
+            return false;
+        }
+        [$feature, $action] = $p;
+
+        if (str_starts_with($feature, '@')) {
+            if (! in_array($k[0], self::featuresOf(substr($feature, 1)), true)) {
+                return false;
+            }
+        } elseif ($feature !== '*' && $feature !== $k[0]) {
+            return false;
+        }
+
+        return $action === '*' || $action === $k[1];
+    }
+
+    /**
+     * The permissions a set of grants comes to, patterns resolved against the catalog.
+     * Clients are given this, so nothing outside this class has to match a pattern.
+     *
+     * @param  list<string>  $grants
+     * @return list<string>
+     */
+    public static function expand(array $grants): array
+    {
+        return array_values(array_filter(self::keys(), fn (string $key) => self::granted($grants, $key)));
+    }
+
+    /**
+     * Whether the grants come to everything there is.
+     *
+     * @param  list<string>  $grants
+     */
+    public static function hasAll(array $grants): bool
+    {
+        return in_array('*', $grants, true) || count(self::expand($grants)) === count(self::keys());
+    }
+
+    /**
+     * The requested grants that `held` does not cover. A pattern is covered only when
+     * everything it comes to is; one that comes to nothing is not.
+     *
+     * This is the ceiling: nobody hands out more than they hold.
+     *
+     * @param  list<string>  $held
+     * @param  list<string>  $requested
+     * @return list<string>
+     */
+    public static function beyond(array $held, array $requested): array
+    {
+        if (in_array('*', $held, true)) {
+            return [];
+        }
+        $beyond = [];
+        foreach ($requested as $grant) {
+            if ($grant === '*') {
+                $beyond[] = $grant;
+            } elseif (str_contains($grant, '*') || str_starts_with($grant, '@')) {
+                $keys = self::expand([$grant]);
+                $covered = $keys !== [];
+                foreach ($keys as $key) {
+                    $covered = $covered && self::granted($held, $key);
+                }
+                if (! $covered) {
+                    $beyond[] = $grant;
+                }
+            } elseif (! self::granted($held, $grant)) {
+                $beyond[] = $grant;
+            }
+        }
+
+        return $beyond;
+    }
+
+    /**
+     * Whether a grant is one the catalog understands: "*", a permission in it, or a pattern
+     * that comes to at least one. A module pattern is accepted for a module with nothing in
+     * it yet, because its point is to cover what is added later.
+     */
+    public static function understood(string $grant): bool
+    {
+        if ($grant === '*') {
+            return true;
+        }
+        if (! preg_match('/^(\*|@?[a-z][a-z0-9_]*)\.(\*|create|view|edit|delete)$/', $grant)) {
+            return false;
+        }
+        if (str_starts_with($grant, '@')) {
+            return in_array(substr(explode('.', $grant)[0], 1), ['access', 'resources', 'app'], true);
+        }
+
+        return self::expand([$grant]) !== [];
+    }
+
+    /** @return list<string> */
+    private static function featuresOf(string $module): array
+    {
+        $features = [];
+        foreach (self::catalog() as $entry) {
+            if ($entry['key'] !== $module) {
+                continue;
+            }
+            foreach ($entry['groups'] as $group) {
+                foreach ($group['features'] as $feature) {
+                    $features[] = $feature['key'];
+                }
+            }
+        }
+
+        return $features;
+    }
+
+    private static function slug(string $heading): string
+    {
+        return trim((string) preg_replace('/[^a-z0-9]+/', '-', strtolower($heading)), '-') ?: 'resources';
+    }
+}

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