step 1/4: the permission engine is called permissions, not capabilities

The word meant four different things in this repo, not the three the offscale
doc records:

  1. the permission registry              → RENAMED here
  2. $OFFICER_ROOT/capabilities/ items    → kept; this is what capabilities are
  3. sidecar routing keys                 → step 3, becoming `handles`
  4. Lightning wallet features            → kept; a domain term, and on the wire
                                            to the mobile apps

The fourth was not in the doc and a global find-and-replace would have broken
the mobile wallet, which reads `{ kind, capabilities: Capability[] }` from the
wallet sidecar. So this renamed against an explicit file allowlist rather than
by sweeping the tree, and `CapabilityPage.tsx` — the UI for the item store, and
correctly named already — was left alone.

Moved: servers/capabilities/ → servers/permissions/, capability-gate.ts →
permission-gate.ts, users/capabilities-routes.ts → permissions-routes.ts,
hooks/useCapabilities.ts → usePermissions.ts. Identifiers follow.

Three breaks the typechecker could not see, all found by exercising it live.

The route paths moved with the prose sweep, so the server served
/user/permissions while the frontend still called /user/capabilities. A 404 on
every page load, and tsgo clean throughout.

The response FIELD moved too. `client.get<SelfPermissions>()` is an unchecked
cast, so `data.capabilities` became `undefined` at runtime with no compile
error — `can()` would have answered "no" to everything and the dock would have
emptied itself.

And the grants list was passed straight out of the database, so it arrived as
`{ role, capability, level }` while the screen read `grant.permission`. Every
role would have rendered as holding nothing. It is now mapped in the route:
the wire says `permission`, the column still says `capability`, and step 2
therefore changes nothing any client can see.

The stale react-query keys were the quiet one: two files still invalidated
['self-capabilities'] after the hook moved to ['self-permissions'], so
installing a plugin would have silently stopped refreshing the dock.

The database is untouched — `role_capabilities` and its `capability` column are
step 2, and the two call sites that cross that boundary say so in a comment.
Round-tripped the 9 live grants through the admin endpoint to prove the PUT
contract survived: 9 before, 9 after, Member's three intact.

Also reverted prettier churn on five landing-page files that a broad --write
picked up. Second time today; the lesson is not sticking.

tsgo clean. 797 tests, 787 pass, same 7 pre-existing failures — two of which
now read "path → permission" rather than "path → capability".

src/servers/permissions/authorize.ts

@@ -0,0 +1,174 @@
+import { getUserById, getRoleGrants } from 'officerdb';
+import type { UserRole } from 'officerdb';
+import {
+  PERMISSION_BY_KEY,
+  CORE_CAPABILITIES,
+  permissionForApiPath,
+  permissionForWsProvider,
+  isRequestAllowedAtLevel,
+  isSelfServiceRoute,
+  type PermissionLevel,
+} from './registry';
+
+// Resolving "may this account do this". Every deny path in the platform ends up here.
+//
+// Two rules run the whole file:
+//
+//   1. The owner bypasses everything. isSuperAdmin is the single question asked first, and a Super Admin
+//      never consults the grants table — which is why the schema refuses to store a row for that role.
+//   2. Everyone else gets core permissions plus whatever their ROLE has been granted, and nothing else.
+//      An unrecognised permission, a missing row, a database error, a user who no longer exists: all deny.
+//
+// Fail-closed is not decoration here. This function is what stands between a Member and a shell, and the
+// failure mode of a permissive default is not a bug report — it is someone else's session. Every catch in
+// this file returns "no", and none of them log-and-continue.
+
+export type EffectivePermissions = {
+  isOwner: boolean;
+  /** Permission key → level. Empty for an account with nothing granted; the owner's is never consulted. */
+  grants: Map<string, PermissionLevel>;
+};
+
+// ── Grant cache ───────────────────────────────────────────────────────────────────────────────────
+//
+// Keyed on ROLE, not user, so it holds at most one entry per role and a new account needs no warm-up.
+//
+// super-admin.ts deliberately does NOT cache, and says why: a cache with no invalidation contract is a
+// staleness bug waiting for whoever builds the role UI. This one has a contract — the only writer is the
+// grants API in api/users, which calls invalidateRoleGrants on every mutation, in this same process. That
+// is the entire set of writers; if a second one ever appears it has to call this too, which is why the
+// cache and its invalidator live in the same file as the reader that depends on them.
+const grantCache = new Map<UserRole, Map<string, PermissionLevel>>();
+
+/** Called by every path that writes a grant. Clears one role, or all of them. */
+export function invalidateRoleGrants(role?: UserRole): void {
+  if (role) grantCache.delete(role);
+  else grantCache.clear();
+}
+
+async function grantsForRole(role: UserRole): Promise<Map<string, PermissionLevel>> {
+  const cached = grantCache.get(role);
+  if (cached) return cached;
+  const grants = (await getRoleGrants(role)) as Map<string, PermissionLevel>;
+  grantCache.set(role, grants);
+  return grants;
+}
+
+/**
+ * What this account may reach, resolved from its role.
+ *
+ * Core permissions come in at `write` unconditionally: they are the caller's own profile, dock and bug
+ * reports, and a read-only version of "change your own password" is not a coherent thing to offer.
+ *
+ * `execution` and `admin` permissions are dropped even if a row somehow grants them. The API refuses to
+ * write such a row, but this is the layer that has to hold if one ever exists — a constraint the database
+ * does not enforce is a constraint the reader must.
+ */
+export async function getEffectivePermissions(userId: number | undefined): Promise<EffectivePermissions> {
+  const empty: EffectivePermissions = { isOwner: false, grants: new Map() };
+  if (!userId) return empty;
+
+  try {
+    const user = await getUserById(userId);
+    if (!user) return empty;
+    if (user.role === 'Super Admin') return { isOwner: true, grants: new Map() };
+
+    const grants = new Map<string, PermissionLevel>();
+    for (const permission of CORE_CAPABILITIES) grants.set(permission.key, 'write');
+
+    // Whether the kernel can enforce a boundary for this account. `confined` permissions are dropped
+    // without it — see below.
+    const hasOsAccount = !!user.osUser;
+
+    for (const [key, level] of await grantsForRole(user.role)) {
+      const permission = PERMISSION_BY_KEY.get(key);
+      // Unknown key: a permission that was renamed or removed while a grant survived. Ignore it — the
+      // alternative is honouring a name nothing defines.
+      if (!permission) continue;
+
+      // A confined permission touches the filesystem or runs a process, and is safe only because the
+      // account has its own Linux user to be confined to. Without one there is no boundary, so the grant
+      // resolves to nothing rather than to the owner's home — which is what it WOULD resolve to, since
+      // `getOwnerHomeDir` ignores the email it is passed, always.
+      //
+      // Dropped here rather than refused per-router so that one rule covers the HTTP routes, the
+      // websocket doors and the dock all at once. A member with `files` granted but no OS account sees no
+      // Files icon, gets a 403 from /api/file-browser, and cannot open the terminal socket — from this.
+      if (permission.kind === 'confined') {
+        if (!hasOsAccount) continue;
+        grants.set(key, level);
+        continue;
+      }
+
+      if (permission.kind !== 'app') continue;
+      grants.set(key, level);
+    }
+
+    return { isOwner: false, grants };
+  } catch {
+    // A transient database error must never grant anything. Deny, and let the next request retry.
+    return empty;
+  }
+}
+
+/**
+ * May this account make this HTTP request?
+ *
+ * `path` is the full request path. Paths outside `/api` are not this function's business — the DAV sync
+ * door authenticates with its own app password and never carries a platform account.
+ */
+export async function isApiRequestAllowed(
+  userId: number | undefined,
+  method: string,
+  path: string,
+): Promise<{ allowed: boolean; reason?: string }> {
+  const { isOwner, grants } = await getEffectivePermissions(userId);
+  if (isOwner) return { allowed: true };
+
+  const permission = permissionForApiPath(path);
+  // Totality guarantees every mounted, non-exempt prefix maps to a permission, so reaching this branch
+  // means either an exempt prefix (which the caller checks before us) or a path nothing serves. Deny:
+  // a 403 on a route that does not exist is not a leak, and a permissive default here would be.
+  if (!permission) return { allowed: false, reason: 'no permission covers this path' };
+
+  // Checked before kind, because a self-service route acts on the caller and is therefore not the thing
+  // the permission around it restricts. Exact method and path only — see the field's comment.
+  if (isSelfServiceRoute(permission, method, path)) return { allowed: true };
+
+  if (permission.kind === 'execution') {
+    return { allowed: false, reason: `${permission.label} runs as the server owner and cannot be shared` };
+  }
+  if (permission.kind === 'admin') {
+    return { allowed: false, reason: `${permission.label} is restricted to the server owner` };
+  }
+
+  const level = grants.get(permission.key);
+  if (!level) return { allowed: false, reason: `your role does not have access to ${permission.label}` };
+
+  if (!isRequestAllowedAtLevel(permission, level, method, path)) {
+    return { allowed: false, reason: `you have read-only access to ${permission.label}` };
+  }
+  return { allowed: true };
+}
+
+/**
+ * May this account open this WebSocket provider?
+ *
+ * There is no method to reason about, so a socket needs the permission at any level.
+ *
+ * That rule was written for cliamp and cliamp-audio — the music app's playback transport, and the only
+ * grantable sockets there have ever been. Both left on 2026-08-15 with `plugins/music/cliamp/`, so every
+ * provider reaching here today belongs to an `execution` permission and is refused above, structurally,
+ * rather than by being left off a list. The rule stays because the first plugin to own a socket needs it.
+ */
+export async function isWsProviderAllowed(userId: number | undefined, provider: string): Promise<boolean> {
+  const { isOwner, grants } = await getEffectivePermissions(userId);
+  if (isOwner) return true;
+
+  const permission = permissionForWsProvider(provider);
+  // `confined` is admissible here as well as `app`: getEffectivePermissions has already dropped confined
+  // grants for an account with no Linux user, so reaching this line with one in `grants` means the boundary
+  // exists. Anything still `execution` is refused structurally, by not being in the map at all.
+  if (!permission || (permission.kind !== 'app' && permission.kind !== 'confined')) return false;
+  return grants.has(permission.key);
+}