feat(admins): soft-retire, durable issuer names, and bulk actions (#1509)

Close deactivate/reactivate polish plus admins.bulk with list checkboxes,
keeping ban/comm Admin cells on snapshot names after hard delete.

Author: maxijabase

AGENTS.md

@@ -4888,6 +4888,7 @@ contributions without contacting every contributor individually.
 | Edit a docs page or add a new one (the Astro + Starlight site published at sbpp.github.io) | `docs/src/content/docs/<group>/<slug>.md` (or `.mdx` when the page uses tabs / cards / asides — e.g. `getting-started/quickstart.mdx`, `setup/mariadb.mdx`). New pages also need a sidebar entry in `docs/astro.config.mjs` (the `sidebar:` array). Site config + theme tokens live in `docs/astro.config.mjs` + `docs/src/styles/sbpp.css`. The Starlight chrome ships from `@astrojs/starlight`; layout overrides land under `docs/src/components/` (see `ThemeProvider.astro` for the canonical override shape). Local dev: `cd docs && npm install && npm run dev`. CI gates: `.github/workflows/docs-build.yml` (per-PR build), `docs-deploy-trigger.yml` (main → repository_dispatch into sbpp.github.io), `docs-screenshots.yml` (gated on the `affects-ui` label, runs `docs/scripts/capture.mjs`). Source of truth is here; sbpp.github.io is the deploy shell only (#1333). |
 | Refresh installer / panel screenshots used in docs pages | `docs/scripts/capture.mjs` (Playwright; `npm run capture` in `docs/`). Output lands under `docs/src/assets/auto/{install,panel}/<stable-slug>.png` so docs pages keep referencing the same path across runs. CI does this automatically on PRs labelled `affects-ui`; locally run after `./sbpp.sh up`. STEAM_API_KEY is the all-zero dummy `00000000000000000000000000000000`. |
 | Add a JSON action                      | `web/api/handlers/_register.php` + `web/api/handlers/<topic>.php` |
+| Soft-retire / hard-delete admins, keep ban+comm issuer names, or bulk-select on the admins list (#1509) | Soft-retire: `admins.enabled` + `admins.deactivate` / `admins.reactivate` in `web/api/handlers/admins.php` (Active/Inactive chips + dialogs in `page_admin_admins_list.tpl`). Hard delete still snapshots `bans.admin_name` / `comms.admin_name` before DELETE (migration `811.php`). Issuer display: `COALESCE(NULLIF(*.admin_name, ''), AD.user)` → template paints **Unknown**, never "deleted admin" on the Admin cell (comments still say "deleted admin" per #1500). Bulk: `admins.bulk` (`op` = `deactivate` \| `reactivate` \| `remove` \| `set_web_group` \| `set_srv_group`, partial `applied`/`skipped`) + checkbox column / sticky bar in `page_admin_admins_list.tpl`. Guards: no self on deactivate/remove; owners skipped. Tests: `AdminsTest` + `AdminEnabledAttributionTest` + `admin-deactivate-bulk.spec.ts`. |
 | Add or audit a publicly-reachable, unauthenticated auth surface (anything in `web/api/handlers/auth.php` or sibling registered as `requireAuth: false`) without leaking per-account state | The reference shape is `api_auth_lost_password` + `_api_auth_lost_password_generic_response` in `web/api/handlers/auth.php` (#1456). All reachable branches MUST return the same envelope; operator-side toggles (e.g. `config.enablenormallogin`) MAY surface as a per-toggle error code because the value is the same for every caller. The pre-#1456 shape branched on `not_registered` / `mail_failed` and let an unauthenticated visitor enumerate registered admin emails one request at a time by reading the painted toast back. See "Public auth surfaces: response-shape uniformity" in Conventions for the full contract (audit-log discipline, DB-write gating, SMTP gating, the documented response-time residual risk) + the matching Anti-patterns entry. Regression guards: `web/tests/api/AuthTest.php::testLostPasswordResponseIsIdenticalForKnownAndUnknownEmail` (byte-for-byte wire assertion) + `web/tests/api/__snapshots__/auth/lost_password_generic.json` (locked envelope) + `web/tests/e2e/specs/flows/lostpassword-toast.spec.ts` (chrome-side parity: same painted toast for known + unknown emails). Sibling surfaces still subject to follow-up (documented under the convention): `api_auth_login` branches its `Api::redirect()` target on per-account state via `?m=…` flags. |
 | Resolve / override the JSON-API endpoint URL the client-side `sb.api.call(...)` POSTs to | `web/scripts/api.js` (`resolveEndpoint()` — runs once at script-load, computes `new URL('../api.php', document.currentScript.src).href`). The script lives at `/scripts/api.js` regardless of which page loads it, so resolving `../api.php` against the script's own URL lands on the panel-root `/api.php` for top-level page renders, iframe-routed surfaces (`pages/admin.kickit.php` / `pages/admin.blockit.php`), AND subdir installs (`https://host/sourcebans/` → script at `…/scripts/api.js` → endpoint at `…/api.php`). The endpoint stays writable on `sb.api` so callers can swap it; do not edit the resolver to a bare `'./api.php'` literal — that's the pre-#1433 regression shape that 404s every iframe round-trip (`./api.php` resolves against the iframe's document URL `/pages/admin.kickit.php` → `/pages/api.php`, no such route). **Load via static `<script src="…">` only** — `document.currentScript` is `null` when the script is appended programmatically (`document.createElement('script')`, `<script>document.write(...)</script>`, async loaders, ES-module `import()`), and a null `currentScript` collapses `SCRIPT_SRC` to the empty string and silently falls back to the bare-relative `./api.php` — i.e. the exact pre-#1433 bug. The three static load sites in the default theme are `core/header.tpl` (top-level panel chrome → `./scripts/api.js`), `page_kickit.tpl`, and `page_blockit.tpl` (iframe surfaces → `../scripts/api.js`); a theme fork that wants to lazy-load needs its own paired endpoint resolver. Pinned by `web/tests/integration/ApiJsEndpointResolutionTest.php` (static) + `web/tests/e2e/specs/flows/kickit-iframe.spec.ts` (runtime). |
 | Stamp `SB_VERSION` / `MAJOR_REVISION` before compiling SourceMod plugins | `game/addons/sourcemod/scripting/scripts/resolve-plugin-version.sh` → `include/sbpp_version.inc` (included from `sourcebanspp.inc` + `sbpp_checker.sp`). Tiers: `SBPP_RELEASE_VERSION` (release tag in `release.yml`) → `web/configs/version.json` → `git describe` → `dev`. Checked-in `sbpp_version.inc` is the direct-compile fallback. Regression: `web/tests/integration/PluginVersionResolveTest.php`. |

web/api/handlers/_register.php

@@ -60,6 +60,7 @@
 Api::register('admins.remove',            'api_admins_remove',            ADMIN_OWNER | ADMIN_DELETE_ADMINS);
 Api::register('admins.deactivate',        'api_admins_deactivate',        ADMIN_OWNER | ADMIN_DELETE_ADMINS);
 Api::register('admins.reactivate',        'api_admins_reactivate',        ADMIN_OWNER | ADMIN_DELETE_ADMINS);
+Api::register('admins.bulk',              'api_admins_bulk',              ADMIN_OWNER | ADMIN_DELETE_ADMINS | ADMIN_EDIT_ADMINS);
 Api::register('admins.edit_perms',        'api_admins_edit_perms',        ADMIN_OWNER | ADMIN_EDIT_ADMINS);
 Api::register('admins.generate_password', 'api_admins_generate_password', 0, true);
 

web/api/handlers/admins.php

@@ -117,7 +117,7 @@ function api_admins_remove(array $params): array
  * blocks panel login and SourceMod admin load via `enabled = 0`.
  *
  * @param array{aid?: int|string, ureason?: string} $params
- * @return array{aid: int, enabled: int, rehash: ?string, message: array{title: string, body: string, kind: string}}
+ * @return array{aid: int, enabled: int, rehash: string|null, message: array{title: string, body: string, kind: string}}
  */
 function api_admins_deactivate(array $params): array
 {
@@ -169,7 +169,7 @@ function api_admins_deactivate(array $params): array
  * Restore a soft-retired admin (`enabled = 1`).
  *
  * @param array{aid?: int|string, ureason?: string} $params
- * @return array{aid: int, enabled: int, rehash: ?string, message: array{title: string, body: string, kind: string}}
+ * @return array{aid: int, enabled: int, rehash: string|null, message: array{title: string, body: string, kind: string}}
  */
 function api_admins_reactivate(array $params): array
 {
@@ -214,6 +214,251 @@ function api_admins_reactivate(array $params): array
     ];
 }
 
+/**
+ * Apply one lifecycle / group op to many admin ids. Partial success:
+ * owner / self / not-found / already-* rows land in `skipped` and the
+ * rest still commit. Per-op permission is re-checked inside so a caller
+ * holding only EDIT_ADMINS cannot deactivate via this entry point.
+ *
+ * Inputs:
+ *   - `op`    (string, required) — `deactivate` | `reactivate` | `remove`
+ *     | `set_web_group` | `set_srv_group`
+ *   - `aids`  (list of int, required, max 100)
+ *   - `ureason` (string, optional) — deactivate / remove
+ *   - `gid`   (int, required for set_web_group) — 0 clears web group
+ *   - `srv_group_id` (int, required for set_srv_group) — 0 clears SM group
+ *
+ * @param array{
+ *     op?: string,
+ *     aids?: list<int|string>,
+ *     ureason?: string,
+ *     gid?: int|string,
+ *     srv_group_id?: int|string
+ * } $params
+ * @return array{
+ *     op: string,
+ *     applied: list<int>,
+ *     skipped: list<array{aid: int, reason: string}>,
+ *     rehash: string|null,
+ *     message: array{title: string, body: string, kind: string}
+ * }
+ */
+function api_admins_bulk(array $params): array
+{
+    global $userbank;
+
+    $op = trim((string) ($params['op'] ?? ''));
+    $allowedOps = ['deactivate', 'reactivate', 'remove', 'set_web_group', 'set_srv_group'];
+    if (!in_array($op, $allowedOps, true)) {
+        throw new ApiError('validation', 'Unknown bulk op.', 'op');
+    }
+
+    $rawAids = $params['aids'] ?? null;
+    if (!is_array($rawAids) || $rawAids === []) {
+        throw new ApiError('validation', 'Select at least one admin.', 'aids');
+    }
+    if (count($rawAids) > 100) {
+        throw new ApiError('validation', 'Bulk selection is limited to 100 admins.', 'aids');
+    }
+
+    $aids = [];
+    foreach ($rawAids as $raw) {
+        $aid = (int) $raw;
+        if ($aid > 0 && !in_array($aid, $aids, true)) {
+            $aids[] = $aid;
+        }
+    }
+    if ($aids === []) {
+        throw new ApiError('validation', 'Select at least one admin.', 'aids');
+    }
+
+    $isLifecycle = in_array($op, ['deactivate', 'reactivate', 'remove'], true);
+    if ($isLifecycle) {
+        if (!$userbank->HasAccess(WebPermission::mask(WebPermission::Owner, WebPermission::DeleteAdmins))) {
+            throw new ApiError('forbidden', 'You do not have permission to deactivate or delete admins.');
+        }
+    } else {
+        if (!$userbank->HasAccess(WebPermission::mask(WebPermission::Owner, WebPermission::EditAdmins))) {
+            throw new ApiError('forbidden', 'You do not have permission to edit admin groups.');
+        }
+    }
+
+    $ureason = trim((string) ($params['ureason'] ?? ''));
+    $actorAid = (int) $userbank->GetAid();
+    $gid = (int) ($params['gid'] ?? 0);
+    $srvGroupId = (int) ($params['srv_group_id'] ?? 0);
+
+    if ($op === 'set_web_group' && !array_key_exists('gid', $params)) {
+        throw new ApiError('validation', 'Web group is required.', 'gid');
+    }
+    if ($op === 'set_srv_group' && !array_key_exists('srv_group_id', $params)) {
+        throw new ApiError('validation', 'Server group is required.', 'srv_group_id');
+    }
+
+    $applied = [];
+    $skipped = [];
+    $rehashSids = [];
+
+    foreach ($aids as $aid) {
+        if ($isLifecycle && $aid === $actorAid && in_array($op, ['deactivate', 'remove'], true)) {
+            $skipped[] = ['aid' => $aid, 'reason' => 'self'];
+            continue;
+        }
+
+        try {
+            $result = match ($op) {
+                'deactivate' => api_admins_deactivate(['aid' => $aid, 'ureason' => $ureason]),
+                'reactivate' => api_admins_reactivate(['aid' => $aid, 'ureason' => $ureason]),
+                'remove' => api_admins_remove(['aid' => $aid, 'ureason' => $ureason]),
+                'set_web_group' => _api_admins_set_web_group($aid, $gid),
+                'set_srv_group' => _api_admins_set_srv_group($aid, $srvGroupId),
+            };
+            $applied[] = $aid;
+            if (!empty($result['rehash']) && is_string($result['rehash'])) {
+                foreach (explode(',', $result['rehash']) as $sid) {
+                    $sid = (int) $sid;
+                    if ($sid > 0 && !in_array($sid, $rehashSids, true)) {
+                        $rehashSids[] = $sid;
+                    }
+                }
+            }
+        } catch (ApiError $e) {
+            $skipped[] = ['aid' => $aid, 'reason' => $e->errorCode];
+        }
+    }
+
+    $appliedN = count($applied);
+    $skippedN = count($skipped);
+    $titles = [
+        'deactivate' => 'Admins deactivated',
+        'reactivate' => 'Admins reactivated',
+        'remove' => 'Admins deleted',
+        'set_web_group' => 'Web group updated',
+        'set_srv_group' => 'Server group updated',
+    ];
+    $verbs = [
+        'deactivate' => 'deactivated',
+        'reactivate' => 'reactivated',
+        'remove' => 'deleted',
+        'set_web_group' => 'updated',
+        'set_srv_group' => 'updated',
+    ];
+    $body = $appliedN . ' ' . $verbs[$op];
+    if ($skippedN > 0) {
+        $body .= ', ' . $skippedN . ' skipped';
+    }
+    $body .= '.';
+
+    return [
+        'op' => $op,
+        'applied' => $applied,
+        'skipped' => $skipped,
+        'rehash' => $rehashSids ? implode(',', $rehashSids) : null,
+        'message' => [
+            'title' => $titles[$op],
+            'body' => $body,
+            'kind' => $appliedN > 0 ? 'green' : 'red',
+        ],
+    ];
+}
+
+/**
+ * @return array{rehash: string|null}
+ */
+function _api_admins_set_web_group(int $aid, int $gid): array
+{
+    $admin = $GLOBALS['PDO']->query(
+        "SELECT aid, user, password, email, extraflags FROM `:prefix_admins` WHERE aid = :aid"
+    );
+    $GLOBALS['PDO']->bind(':aid', $aid);
+    $admin = $GLOBALS['PDO']->single();
+    if (!$admin) {
+        throw new ApiError('not_found', 'Admin not found.');
+    }
+
+    if ($gid > 0) {
+        $group = $GLOBALS['PDO']->query(
+            "SELECT gid FROM `:prefix_groups` WHERE gid = :gid AND type != 3"
+        );
+        $GLOBALS['PDO']->bind(':gid', $gid);
+        if (!$GLOBALS['PDO']->single()) {
+            throw new ApiError('validation', 'Unknown web group.', 'gid');
+        }
+        $password = (string) ($admin['password'] ?? '');
+        $email = (string) ($admin['email'] ?? '');
+        if ($password === '' || $email === '') {
+            throw new ApiError(
+                'missing_credentials',
+                'Admins need a password and email before you can give them web permissions.',
+            );
+        }
+    }
+
+    $persistGid = max(0, $gid);
+    $GLOBALS['PDO']->query('UPDATE `:prefix_admins` SET `gid` = :gid WHERE `aid` = :aid');
+    $GLOBALS['PDO']->bind(':gid', $persistGid);
+    $GLOBALS['PDO']->bind(':aid', $aid);
+    $GLOBALS['PDO']->execute();
+
+    $allservers = _api_admins_rehash_sids($aid);
+    Log::add(
+        LogType::Message,
+        "Admin's Groups Updated",
+        "Admin ({$admin['user']}) web group has been updated.",
+    );
+
+    return ['rehash' => $allservers ? implode(',', $allservers) : null];
+}
+
+/**
+ * @return array{rehash: string|null}
+ */
+function _api_admins_set_srv_group(int $aid, int $srvGroupId): array
+{
+    $admin = $GLOBALS['PDO']->query(
+        "SELECT aid, user, extraflags FROM `:prefix_admins` WHERE aid = :aid"
+    );
+    $GLOBALS['PDO']->bind(':aid', $aid);
+    $admin = $GLOBALS['PDO']->single();
+    if (!$admin) {
+        throw new ApiError('not_found', 'Admin not found.');
+    }
+
+    $resolvedGroupName = '';
+    $persistId = 0;
+    if ($srvGroupId > 0) {
+        $GLOBALS['PDO']->query('SELECT id, name FROM `:prefix_srvgroups` WHERE id = :id');
+        $GLOBALS['PDO']->bind(':id', $srvGroupId);
+        $row = $GLOBALS['PDO']->single();
+        if (!$row) {
+            throw new ApiError('validation', 'Unknown server group.', 'srv_group_id');
+        }
+        $resolvedGroupName = (string) ($row['name'] ?? '');
+        $persistId = (int) $row['id'];
+    }
+
+    $GLOBALS['PDO']->query('UPDATE `:prefix_admins` SET `srv_group` = :name WHERE `aid` = :aid');
+    $GLOBALS['PDO']->bind(':name', $resolvedGroupName);
+    $GLOBALS['PDO']->bind(':aid', $aid);
+    $GLOBALS['PDO']->execute();
+
+    $GLOBALS['PDO']->query(
+        'UPDATE `:prefix_admins_servers_groups` SET `group_id` = :gid WHERE `admin_id` = :aid'
+    );
+    $GLOBALS['PDO']->bind(':gid', $persistId > 0 ? $persistId : -1);
+    $GLOBALS['PDO']->bind(':aid', $aid);
+    $GLOBALS['PDO']->execute();
+
+    $allservers = _api_admins_rehash_sids($aid);
+    Log::add(
+        LogType::Message,
+        "Admin's Groups Updated",
+        "Admin ({$admin['user']}) server group has been updated.",
+    );
+
+    return ['rehash' => $allservers ? implode(',', $allservers) : null];
+}
+
 /**
  * Server SIDs that need `sm_rehash` after an admin access change.
  *

web/includes/View/AdminAdminsListView.php

@@ -36,6 +36,8 @@ final class AdminAdminsListView extends View
      * @param string $active_view One of `active` / `inactive` / `all`
      * @param string $chip_base_link Base href for the Active/Inactive/All chips
      *     (search filters preserved; `view=` appended per chip)
+     * @param list<array{gid: int|string, name: string}> $web_groups
+     * @param list<array{id: int|string, name: string}> $srv_groups
      */
     public function __construct(
         public readonly bool $can_list_admins,
@@ -46,6 +48,9 @@ public function __construct(
         public readonly array $admins,
         public readonly string $active_view = 'active',
         public readonly string $chip_base_link = 'index.php?p=admin&c=admins&section=admins',
+        public readonly array $web_groups = [],
+        public readonly array $srv_groups = [],
+        public readonly int $current_aid = 0,
     ) {
     }
 }

web/pages/admin.admins.php

@@ -451,6 +451,7 @@
     $admin['server_flag_string'] = SmFlagsToSb((string) ($userbank->GetProperty("srv_flags", $admin['aid']) ?? ''));
     $admin['web_flag_string']    = BitToString((int) ($userbank->GetProperty("extraflags", $admin['aid']) ?? 0));
     $admin['enabled']            = (int) ($admin['enabled'] ?? 1);
+    $admin['is_owner']           = (((int) ($userbank->GetProperty("extraflags", $admin['aid']) ?? 0)) & ADMIN_OWNER) !== 0;
 
     $lastvisit = $userbank->GetProperty("lastvisit", $admin['aid']);
     if (!$lastvisit) {
@@ -513,6 +514,9 @@
 
 $chipBase = 'index.php?p=admin&c=admins&section=admins' . $advSearchString;
 
+$bulkWebGroups = $GLOBALS['PDO']->query('SELECT gid, name FROM `:prefix_groups` WHERE type != 3 ORDER BY name')->resultset();
+$bulkSrvGroups = $GLOBALS['PDO']->query('SELECT id, name FROM `:prefix_srvgroups` ORDER BY name')->resultset();
+
 \Sbpp\View\Renderer::render($theme, new \Sbpp\View\AdminAdminsListView(
     // We pass the can_* gates explicitly rather than splatting
     // ...Perms::for($userbank): the helper's @return array<string,bool>
@@ -529,4 +533,7 @@
     admins: $admin_list,
     active_view: $view,
     chip_base_link: $chipBase,
+    web_groups: $bulkWebGroups,
+    srv_groups: $bulkSrvGroups,
+    current_aid: (int) $userbank->GetAid(),
 ));