create-nevela 0.6.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nevela",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Create a new Nevela app: a Laravel API and a Next.js dashboard from one resource description.",
   "type": "module",
   "bin": {

package/template/laravel/config/nevela.php

@@ -86,6 +86,13 @@ return [
         */
         'attempts_per_address' => 300,
 
+        /*
+        | Let people close their own account, from the dashboard's Account page. A closed
+        | account is kept under Deleted accounts, for an administrator to restore or remove
+        | for good. Off: only someone who may delete users can close one.
+        */
+        'close_account' => true,
+
         /*
         | The role a self-registered account starts with. USER allows nothing beyond the
         | person's own account, which is what makes open sign-up safe. Null gives no role.

package/template/laravel/database/migrations/2026_10_09_000000_create_nevela_closed_accounts.php

@@ -0,0 +1,52 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+// Deleted accounts.
+//
+// Closing an account, or deleting one from the Users screen, no longer removes it: it is
+// marked closed, signed out everywhere, and kept so that it can be restored. And an email
+// that had an account stays known after the account is removed for good, as a fingerprint
+// the address can't be read back from, so the same person can't simply sign up again.
+return new class extends Migration
+{
+    public function up(): void
+    {
+        $model = config('auth.providers.users.model');
+        $users = is_string($model) && class_exists($model) ? (new $model)->getTable() : 'users';
+
+        if (Schema::hasTable($users)) {
+            Schema::table($users, function (Blueprint $table) use ($users) {
+                if (! Schema::hasColumn($users, 'closed_at')) {
+                    // Set: the account is closed. It can't sign in, and isn't among the users.
+                    $table->timestamp('closed_at')->nullable()->index();
+                }
+                if (! Schema::hasColumn($users, 'closed_by')) {
+                    // The id of whoever closed it: the account's own id when its owner did.
+                    $table->string('closed_by')->nullable();
+                }
+            });
+        }
+
+        Schema::create('nevela_blocked_emails', function (Blueprint $table) {
+            $table->uuid('id')->primary();
+            // HMAC-SHA256 of the address, keyed with the app key. Not the address.
+            $table->char('fingerprint', 64)->unique();
+            // Enough to recognise it by, for whoever decides to allow it again: "m•••@gmail.com".
+            $table->string('hint');
+            // The closed account it belongs to, while that is still kept. Null once the
+            // account has been removed for good: then this row is all that is left of it.
+            $table->string('user_id')->nullable()->index();
+            $table->timestamp('blocked_at');
+        });
+    }
+
+    public function down(): void
+    {
+        // The two columns stay: an app may have had its own before this ran, and a closed
+        // account that lost its mark would be an open one again.
+        Schema::dropIfExists('nevela_blocked_emails');
+    }
+};

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

@@ -50,7 +50,7 @@ final class Access
         if (isset(self::$grants[$user])) {
             return self::$grants[$user];
         }
-        if (! self::active($user)) {
+        if (! self::active($user) || ClosedAccounts::isClosed($user)) {
             return self::$grants[$user] = [];
         }
 
@@ -141,7 +141,7 @@ final class Access
         $key = $instance->getKeyName();
         $hasActive = Schema::hasColumn($table, 'active');
 
-        $all =Role::query()->get()->filter(fn (Role $role) => Permissions::hasAll($role->grants))->pluck('id')->all();
+        $all = Role::query()->get()->filter(fn (Role $role) => Permissions::hasAll($role->grants))->pluck('id')->all();
         $ids = DB::table('nevela_role_user')->whereIn('role_id', $all)->distinct()->pluck('user_id')->all();
         if ($except !== null) {
             $ids = array_values(array_diff($ids, [(string) $except->getAuthIdentifier()]));
@@ -150,7 +150,7 @@ final class Access
             return 0;
         }
 
-        return $model::query()->whereIn($key, $ids)->when($hasActive, fn ($query) => $query->where('active', true))->count();
+        return ClosedAccounts::open()->whereIn($key, $ids)->when($hasActive, fn ($query) => $query->where('active', true))->count();
     }
 
     /** Forget what has been worked out, after roles or who holds them change. */

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

@@ -0,0 +1,228 @@
+<?php
+
+namespace Nevela\Laravel\Access;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Str;
+use Nevela\Laravel\Auth\Account;
+
+/**
+ * Accounts that were closed, and the emails that may not have a new one.
+ *
+ * A closed account is kept: its owner closed it, or someone deleted it from the Users
+ * screen. It can't sign in, is signed out everywhere and is no longer among the users,
+ * and it can be restored with everything it had. Removing it for good deletes the account
+ * and leaves a fingerprint of its email behind, so that signing up again with the same
+ * address is refused until someone allows it.
+ *
+ * The fingerprint is an HMAC of the address keyed with the app key: the address can't be
+ * read back from it, and it is of no use to anyone holding only the database.
+ */
+final class ClosedAccounts
+{
+    public const BLOCKED = 'nevela_blocked_emails';
+
+    private static bool $ready = false;
+
+    /**
+     * Whether the app has run the migration this needs. Until it has, deleting a user
+     * removes them as it always did, and nothing here is offered.
+     */
+    public static function ready(): bool
+    {
+        if (self::$ready) {
+            return true;
+        }
+        $model = Account::model();
+        if (! class_exists($model)) {
+            return false;
+        }
+
+        // Only "yes" is remembered: the column can arrive later in the same process.
+        return self::$ready = Schema::hasTable(self::BLOCKED) && Schema::hasColumn((new $model)->getTable(), 'closed_at');
+    }
+
+    /** For tests that add and drop the tables within one process. */
+    public static function reset(): void
+    {
+        self::$ready = false;
+    }
+
+    public static function isClosed(mixed $user): bool
+    {
+        $attributes = is_object($user) && method_exists($user, 'getAttributes') ? $user->getAttributes() : [];
+
+        return isset($attributes['closed_at']);
+    }
+
+    /** The app's users, without the closed ones. */
+    public static function open(): Builder
+    {
+        return Account::model()::query()->when(self::ready(), fn (Builder $query) => $query->whereNull('closed_at'));
+    }
+
+    /** Only the closed ones. Nobody, in an app that keeps none. */
+    public static function closed(): Builder
+    {
+        return Account::model()::query()->when(self::ready(), fn (Builder $query) => $query->whereNotNull('closed_at'), fn (Builder $query) => $query->whereRaw('1 = 0'));
+    }
+
+    /** @return list<string> The ids of the closed accounts, as the roles table keeps ids: text. */
+    public static function ids(): array
+    {
+        if (! self::ready()) {
+            return [];
+        }
+        $model = Account::model();
+
+        return self::closed()->pluck((new $model)->getKeyName())->map(fn ($id) => (string) $id)->all();
+    }
+
+    /**
+     * An address as the person behind it, for telling whether two are the same mailbox:
+     * lower case, without a "+tag", and for Gmail without the dots it ignores. So closing
+     * mark@gmail.com also covers m.ark+new@gmail.com.
+     */
+    public static function canonical(string $email): string
+    {
+        $email = mb_strtolower(trim($email));
+        $at = strrpos($email, '@');
+        if ($at === false) {
+            return $email;
+        }
+        $local = substr($email, 0, $at);
+        $domain = substr($email, $at + 1);
+        $plain = explode('+', $local, 2)[0];
+        if (in_array($domain, ['gmail.com', 'googlemail.com'], true)) {
+            $plain = str_replace('.', '', $plain);
+            $domain = 'gmail.com';
+        }
+
+        return ($plain !== '' ? $plain : $local).'@'.$domain;
+    }
+
+    public static function fingerprint(string $email): string
+    {
+        return hash_hmac('sha256', self::canonical($email), (string) config('app.key'));
+    }
+
+    /**
+     * The fingerprint an email has now, and the ones it had under the app's earlier keys
+     * (APP_PREVIOUS_KEYS). An email blocked before the key was rotated is still blocked.
+     *
+     * @return list<string>
+     */
+    public static function fingerprints(string $email): array
+    {
+        $canonical = self::canonical($email);
+        $keys = [(string) config('app.key'), ...array_filter((array) config('app.previous_keys', []), 'is_string')];
+
+        return array_values(array_unique(array_map(fn (string $key) => hash_hmac('sha256', $canonical, $key), $keys)));
+    }
+
+    /** "m•••@gmail.com": enough to recognise an address by, and not the address. */
+    public static function hint(string $email): string
+    {
+        $email = mb_strtolower(trim($email));
+        $at = strrpos($email, '@');
+
+        return $at === false || $at === 0 ? '•••' : mb_substr($email, 0, 1).'•••'.substr($email, $at);
+    }
+
+    /**
+     * What stands in the way of a new account with this email: "closed" when a closed
+     * account has it and could be restored, "blocked" when its account was removed for
+     * good, and null when nothing does.
+     *
+     * @param  mixed  $except  An account whose own email this may be
+     */
+    public static function standing(string $email, mixed $except = null): ?string
+    {
+        if (! self::ready()) {
+            return null;
+        }
+        // An entry for a closed account first: that one can be restored.
+        $row = DB::table(self::BLOCKED)->whereIn('fingerprint', self::fingerprints($email))->orderByRaw('case when user_id is null then 1 else 0 end')->first();
+        if (! $row || ($except !== null && $row->user_id !== null && $row->user_id === (string) $except->getAuthIdentifier())) {
+            return null;
+        }
+
+        return $row->user_id !== null ? 'closed' : 'blocked';
+    }
+
+    /**
+     * Close an account. It is signed out everywhere, and kept.
+     *
+     * @param  mixed  $by  Whoever is closing it: the account itself, or the person deleting it
+     */
+    public static function close(mixed $user, mixed $by = null): void
+    {
+        DB::transaction(function () use ($user, $by) {
+            $user->forceFill(['closed_at' => now(), 'closed_by' => $by === null ? null : (string) $by->getAuthIdentifier()])->save();
+            Account::revokeTokens($user);
+            self::block((string) $user->email, (string) $user->getAuthIdentifier());
+        });
+        Access::forget();
+    }
+
+    /** Open a closed account again, as it was: its roles, its password, its second step. */
+    public static function restore(mixed $user): void
+    {
+        DB::transaction(function () use ($user) {
+            DB::table(self::BLOCKED)->where('user_id', (string) $user->getAuthIdentifier())->delete();
+            $user->forceFill(['closed_at' => null, 'closed_by' => null])->save();
+        });
+        Access::forget();
+    }
+
+    /** Remove a closed account for good. Its email stays blocked until someone allows it. */
+    public static function purge(mixed $user): void
+    {
+        $email = (string) $user->email;
+        DB::transaction(function () use ($user, $email) {
+            self::remove($user);
+            self::block($email, null);
+        });
+    }
+
+    /** Delete an account and what hangs off it. Nothing is kept. */
+    public static function remove(mixed $user): void
+    {
+        $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();
+    }
+
+    /** Let an email whose account was removed for good be used again. False when there is no such entry. */
+    public static function allow(string $id): bool
+    {
+        return DB::table(self::BLOCKED)->where('id', $id)->whereNull('user_id')->delete() > 0;
+    }
+
+    /** Remember an email by its fingerprint: for a closed account, or with no account left. */
+    private static function block(string $email, ?string $userId): void
+    {
+        // One entry per mailbox, under today's key: an entry made under an earlier key is brought up to date.
+        $fingerprint = self::fingerprint($email);
+        $values = ['fingerprint' => $fingerprint, 'hint' => self::hint($email), 'user_id' => $userId, 'blocked_at' => now()];
+        $existing = DB::table(self::BLOCKED)->whereIn('fingerprint', self::fingerprints($email))->orderBy('blocked_at')->pluck('id')->all();
+        if ($existing === []) {
+            DB::table(self::BLOCKED)->insert(['id' => (string) Str::uuid()] + $values);
+
+            return;
+        }
+        DB::table(self::BLOCKED)->whereIn('id', array_slice($existing, 1))->delete();
+        DB::table(self::BLOCKED)->where('id', $existing[0])->update($values);
+    }
+}

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

@@ -57,10 +57,8 @@ final class SampleUsers
             if (Account::findByEmail($email)) {
                 continue;
             }
+            // Their addresses are made up, and nobody has proved one: they are not "verified".
             $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;
             }

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

@@ -8,6 +8,7 @@ use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Schema;
 use Illuminate\Validation\Rules\Password;
 use Nevela\Laravel\Access\Access;
+use Nevela\Laravel\Access\ClosedAccounts;
 use Nevela\Laravel\Access\Permissions;
 use Nevela\Laravel\Media\Uploads;
 use Nevela\Laravel\Models\TwoFactor;
@@ -24,6 +25,7 @@ final class Account
         return (string) config('auth.providers.users.model');
     }
 
+    /** Whoever has this email, a closed account included: an address belongs to one account, open or not. */
     public static function findByEmail(string $email): mixed
     {
         return self::model()::query()->whereRaw('lower(email) = ?', [mb_strtolower(trim($email))])->first();
@@ -73,8 +75,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.
+        // Every way of signing in ends here, so this is the one place a closed or
+        // switched-off account is turned away, whichever way it came.
+        if (ClosedAccounts::isClosed($user)) {
+            throw new HttpResponseException(response()->json(['error' => 'This account was closed. Ask an administrator to restore it.', 'code' => 'ACCOUNT_CLOSED'], 403));
+        }
         if (! Access::active($user)) {
             throw new HttpResponseException(response()->json(['error' => 'This account has been switched off. Ask an administrator.', 'code' => 'ACCOUNT_DISABLED'], 403));
         }

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

@@ -5,6 +5,8 @@ namespace Nevela\Laravel\Console;
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Schema;
+use Nevela\Laravel\Access\ClosedAccounts;
 use Nevela\Laravel\Nevela;
 use Nevela\Laravel\Support\DashboardState;
 use Nevela\Laravel\Support\Releases;
@@ -60,8 +62,10 @@ final class StatusCommand extends Command
             $model = config('auth.providers.users.model');
             if (is_string($model) && class_exists($model)) {
                 try {
-                    $users = $model::query()->count();
-                    $row('Users who can sign in', $users > 0 ? (string) $users : $bad('none: php nevela user'));
+                    // A closed account is kept, and can't sign in.
+                    $users = ClosedAccounts::open()->count();
+                    $closed = ClosedAccounts::closed()->count();
+                    $row('Users who can sign in', ($users > 0 ? (string) $users : $bad('none: php nevela user')).($closed > 0 ? " <fg=gray>and {$closed} deleted, kept to restore</>" : ''));
                 } catch (Throwable) {
                     $row('Users who can sign in', $bad('the users table is missing: php nevela migrate'));
                 }
@@ -82,7 +86,10 @@ final class StatusCommand extends Command
         }
         foreach ($resources as $resource) {
             try {
-                $row("Resource: {$resource->name}", number_format(DB::table($resource->table)->count()).' records');
+                // What is in the trash is still in the table, and isn't one of the records.
+                $trashed = Schema::hasColumn($resource->table, 'deleted_at') ? DB::table($resource->table)->whereNotNull('deleted_at')->count() : 0;
+                $records = DB::table($resource->table)->count() - $trashed;
+                $row("Resource: {$resource->name}", number_format($records).' records'.($trashed > 0 ? ' <fg=gray>and '.number_format($trashed).' in the trash</>' : ''));
             } catch (Throwable) {
                 $row("Resource: {$resource->name}", $bad("the {$resource->table} table is missing: php nevela migrate"));
             }

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

@@ -18,6 +18,7 @@ final class UserCommand extends Command
         {--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}
+        {--verified : Mark the email as verified. Only for an address you know is theirs}
         {--sample : Create the ten sample users instead: two editors and eight users}';
 
     protected $description = 'Create a user who can sign in to the dashboard';
@@ -68,7 +69,10 @@ final class UserCommand extends Command
 
         // 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')) {
+        // "Verified" means the owner has proved the address is theirs, by a link or a code
+        // sent to it. Making an account here proves nothing of the kind, so it starts
+        // unverified unless whoever runs this says they know the address is right.
+        if ($this->option('verified') && Schema::hasColumn($table, 'email_verified_at')) {
             $attributes['email_verified_at'] = now();
         }
         $user = (new $model)->forceFill($attributes);

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

@@ -359,6 +359,8 @@ final class ResourceGenerator
           requireEmailVerification: {$flag('require_email_verification', false)},
           /** Check new passwords against Have I Been Pwned's breach list. */
           checkBreachedPasswords: {$flag('check_breached_passwords')},
+          /** People can close their own account, from the Account page. */
+          closeAccount: {$flag('close_account')},
           /** Signing in with Google, GitHub and the like isn't part of Nevela yet. */
           social: [] as SocialProvider[],
         };

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

@@ -0,0 +1,56 @@
+<?php
+
+namespace Nevela\Laravel\Http\Access;
+
+use Illuminate\Http\JsonResponse;
+use Nevela\Laravel\Access\Access;
+use Nevela\Laravel\Access\Permissions;
+use Nevela\Laravel\Models\Role;
+
+/**
+ * The rule that managing accounts is never a way to take more than you were given: you
+ * act only on accounts that may do no more than you. Shared by the controllers that
+ * change, delete, restore and remove them.
+ */
+trait Ceiling
+{
+    /**
+     * 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));
+    }
+}

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

@@ -0,0 +1,155 @@
+<?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 Nevela\Laravel\Access\ClosedAccounts;
+use Nevela\Laravel\Auth\Account;
+use Nevela\Laravel\Auth\AuthMail;
+use Nevela\Laravel\Http\Auth\Answers;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+/**
+ * Accounts that were closed: to restore, or to remove for good. And the emails whose
+ * accounts were removed for good, which can't sign up again until one is allowed.
+ *
+ * All of it is for whoever may delete users (users.delete), under the same rule as the
+ * Users screen: you act only on accounts that may do no more than you.
+ */
+final class DeletedAccountsController
+{
+    use Answers;
+    use Ceiling;
+
+    /** GET _nevela/deleted-accounts?q=&page=&perPage=: the latest closed first. */
+    public function index(Request $request): JsonResponse
+    {
+        Gate::authorize('users.delete');
+        if ($refused = $this->notReady()) {
+            return $refused;
+        }
+        $input = $request->validate([
+            'q' => ['nullable', 'string', 'max:200'],
+            'page' => ['nullable', 'integer', 'min:1'],
+            'perPage' => ['nullable', 'integer', 'min:1', 'max:100'],
+        ]);
+        $model = Account::model();
+        $key = (new $model)->getKeyName();
+        $query = ClosedAccounts::closed();
+        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]));
+        }
+
+        $perPage = (int) ($input['perPage'] ?? 25);
+        $page = (int) ($input['page'] ?? 1);
+        $total = (clone $query)->count();
+        $users = $query->orderByDesc('closed_at')->orderBy($key)->forPage($page, $perPage)->get();
+
+        // Who closed each: themselves, or someone whose name is worth showing.
+        $closers = $users->pluck('closed_by')->filter()->unique()->values()->all();
+        $names = $closers === [] ? collect() : $model::query()->whereIn($key, $closers)->pluck('name', $key);
+        $rows = UsersController::present($users, $request->user());
+        foreach ($users->values() as $index => $user) {
+            $by = $user->closed_by === null ? null : (string) $user->closed_by;
+            $own = $by !== null && $by === (string) $user->getAuthIdentifier();
+            $rows[$index] += [
+                'closedAt' => $user->closed_at ? date(DATE_ATOM, strtotime((string) $user->closed_at)) : null,
+                // "self": its owner closed it. "admin": someone deleted it from the Users screen.
+                'closedBy' => $by === null ? null : ($own ? 'self' : 'admin'),
+                'closedByName' => $by === null || $own ? null : ($names[$by] ?? null),
+            ];
+        }
+
+        return response()->json([
+            'data' => $rows,
+            'meta' => ['page' => $page, 'perPage' => $perPage, 'total' => $total, 'totalPages' => max(1, (int) ceil($total / $perPage))],
+            'blocked' => DB::table(ClosedAccounts::BLOCKED)->whereNull('user_id')->count(),
+        ]);
+    }
+
+    /** POST _nevela/deleted-accounts/{id}/restore: open it again, as it was. */
+    public function restore(Request $request, string $id): JsonResponse
+    {
+        Gate::authorize('users.delete');
+        if ($refused = $this->notReady()) {
+            return $refused;
+        }
+        $user = $this->find($id);
+        if ($refused = $this->aboveCaller($request->user(), $user, 'restore')) {
+            return $refused;
+        }
+        ClosedAccounts::restore($user);
+        AuthMail::send($user->email, 'Your '.AuthMail::app().' account is open again', ['Your account has been restored, with everything it had.', 'Sign in the way you did before: your password is the one you last used.']);
+
+        return response()->json(UsersController::present(collect([$user->refresh()]), $request->user())[0]);
+    }
+
+    /** DELETE _nevela/deleted-accounts/{id}: remove it for good. Its email stays blocked. */
+    public function destroy(Request $request, string $id): JsonResponse|Response
+    {
+        Gate::authorize('users.delete');
+        if ($refused = $this->notReady()) {
+            return $refused;
+        }
+        $user = $this->find($id);
+        if ($refused = $this->aboveCaller($request->user(), $user, 'remove')) {
+            return $refused;
+        }
+        ClosedAccounts::purge($user);
+
+        return response()->noContent();
+    }
+
+    /** GET _nevela/blocked-emails?page=&perPage=: emails whose accounts were removed for good. */
+    public function blocked(Request $request): JsonResponse
+    {
+        Gate::authorize('users.delete');
+        if ($refused = $this->notReady()) {
+            return $refused;
+        }
+        $input = $request->validate(['page' => ['nullable', 'integer', 'min:1'], 'perPage' => ['nullable', 'integer', 'min:1', 'max:100']]);
+        $perPage = (int) ($input['perPage'] ?? 25);
+        $page = (int) ($input['page'] ?? 1);
+        $query = DB::table(ClosedAccounts::BLOCKED)->whereNull('user_id');
+        $total = (clone $query)->count();
+
+        return response()->json([
+            'data' => $query->orderByDesc('blocked_at')->orderBy('id')->forPage($page, $perPage)->get()->map(fn ($row) => [
+                'id' => (string) $row->id,
+                'hint' => $row->hint,
+                'blockedAt' => date(DATE_ATOM, strtotime((string) $row->blocked_at)),
+            ])->all(),
+            'meta' => ['page' => $page, 'perPage' => $perPage, 'total' => $total, 'totalPages' => max(1, (int) ceil($total / $perPage))],
+        ]);
+    }
+
+    /** DELETE _nevela/blocked-emails/{id}: let that email have an account again. */
+    public function allow(string $id): JsonResponse|Response
+    {
+        Gate::authorize('users.delete');
+        if ($refused = $this->notReady()) {
+            return $refused;
+        }
+        if (! ClosedAccounts::allow($id)) {
+            throw new NotFoundHttpException('No such blocked email.');
+        }
+
+        return response()->noContent();
+    }
+
+    private function find(string $id): mixed
+    {
+        return ClosedAccounts::closed()->find($id) ?? throw new NotFoundHttpException('No such deleted account.');
+    }
+
+    /** An upgraded app keeps no deleted accounts until it has run its migrations. */
+    private function notReady(): ?JsonResponse
+    {
+        return ClosedAccounts::ready() ? null : $this->refuse('MIGRATION_NEEDED', 'Deleted accounts need a migration that has not been run: php nevela migrate', 409);
+    }
+}