a commander's bound is a rule, not a list

the allow list shipped an hour ago was a snapshot. plugin permissions
register at mount, so a plugin installed after a commander was created was
missing from its list and failed as a bare 403 with nothing saying why —
and every future thing a commander is meant to do is exactly that shape:
notify a device, send mail, spawn a sub-agent, hand a transcription to an
idle one, reach a plugin that does not exist yet.

so a credential now narrows two ways, and both only subtract:

  permissions   an ALLOW list. exact, a snapshot. right for a credential
                with one job.
  excludedKinds kinds it may never reach, resolved against the LIVE
                registry on every request. right for a credential whose
                job is open-ended.

a commander gets the second: every kind except admin. bounded away from
installing plugins, managing users and roles and changing server settings,
forever — and open to everything the platform learns to do, with nothing
to re-issue. still intersected with the account, so for a member it
narrows itself against their role.

verified against the running server with a commander-shaped key: tasks,
notify, file-browser and the transcribe PLUGIN all reach their routes;
/api/users, /api/plugins and /api/roles are 403. the plugin case is the
one an allow list could not have passed — it was mounted long after any
key was minted.

the commander's CLAUDE.md says what it cannot do in the rule's own terms,
and that a 403 is an answer rather than a problem to route around.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043

src/servers/permissions/authorize.ts

@@ -1,4 +1,5 @@
 import { getUserById, getRoleGrants } from 'officerdb';
+import type { CredentialScope } from '../auth-token';
 import type { UserRole } from 'officerdb';
 import {
   PERMISSION_BY_KEY,
@@ -141,18 +142,42 @@ export async function isApiRequestAllowed(
   userId: number | undefined,
   method: string,
   path: string,
-  credential?: string[] | null,
+  scope?: CredentialScope | null,
 ): Promise<{ allowed: boolean; reason?: string }> {
-  return decideApiRequest(await getEffectivePermissions(userId), method, path, credential);
+  return decideApiRequest(await getEffectivePermissions(userId), method, path, scope);
+}
+
+/**
+ * Does this credential's own narrowing admit this permission?
+ *
+ * Two rules, both subtractive, and an absent one admits everything:
+ *
+ * - `excludeKinds` is resolved against the LIVE registry, so it keeps meaning what it meant as the
+ *   platform grows. That is what makes it right for a commander: excluded from administration forever,
+ *   and able to reach a plugin installed long after it was minted. An allow list cannot express that —
+ *   it names what existed on the day it was written, so next year's plugin is simply missing from it.
+ * - `allow` is an exact list, for a credential with one job.
+ *
+ * An unresolvable permission is refused rather than admitted: a path nothing serves must not become
+ * reachable by failing to resolve, which is the same rule the unnarrowed path already applies below.
+ */
+function credentialAdmits(
+  scope: CredentialScope,
+  permission: { key: string; kind: string } | null | undefined,
+): boolean {
+  if (!permission) return false;
+  if (scope.excludeKinds?.includes(permission.kind)) return false;
+  if (Array.isArray(scope.allow) && !scope.allow.includes(permission.key)) return false;
+  return true;
 }
 
 /**
  * The decision, given an already-resolved account. Pure, and where every rule below actually lives.
  *
- * `credential` is the narrowing carried by an API key — the permission keys THAT key may reach, or
- * null/undefined for one that carries its holder's full authority (which is every key a human has minted
- * and every session JWT). It is an intersection, never a union: a key cannot reach what its account
- * could not, and its account cannot reach, through this key, what the key does not name.
+ * `scope` is the narrowing carried by an API key, or null/undefined for one that carries its holder's
+ * full authority (which is every key a human has minted and every session JWT). It is an intersection,
+ * never a union: a key cannot reach what its account could not, and its account cannot reach, through
+ * this key, what the key excludes.
  *
  * **It is checked before the owner bypass, and that is the whole point.** A Super Admin consults no
  * grants table, so a credential carrying the owner's identity is unbounded by construction — which is
@@ -163,17 +188,14 @@ export function decideApiRequest(
   effective: EffectivePermissions,
   method: string,
   path: string,
-  credential?: string[] | null,
+  scope?: CredentialScope | null,
 ): { allowed: boolean; reason?: string } {
   const { isOwner, grants } = effective;
 
-  if (credential) {
-    const scoped = permissionForApiPath(path);
-    // Same deny-the-unmapped rule as below, one step earlier: a narrowed credential naming nothing that
-    // covers this path cannot be allowed onto it by failing to resolve the path.
-    if (!scoped || !credential.includes(scoped.key)) {
-      return { allowed: false, reason: 'this credential is not permitted to use that' };
-    }
+  // Same deny-the-unmapped rule as below, one step earlier: a path this cannot resolve must not become
+  // reachable by failing to resolve.
+  if (scope && !credentialAdmits(scope, permissionForApiPath(path))) {
+    return { allowed: false, reason: 'this credential is not permitted to use that' };
   }
 
   if (isOwner) return { allowed: true };
@@ -224,25 +246,22 @@ export function decideApiRequest(
 export async function isWsProviderAllowed(
   userId: number | undefined,
   provider: string,
-  credential?: string[] | null,
+  scope?: CredentialScope | null,
 ): Promise<boolean> {
-  return decideWsProvider(await getEffectivePermissions(userId), provider, credential);
+  return decideWsProvider(await getEffectivePermissions(userId), provider, scope);
 }
 
 /** The decision, given an already-resolved account. See `isWsProviderAllowed` for why level is not read. */
 export function decideWsProvider(
   effective: EffectivePermissions,
   provider: string,
-  credential?: string[] | null,
+  scope?: CredentialScope | null,
 ): boolean {
   const { isOwner, grants } = effective;
 
   // Before the owner bypass, for the reason given in `decideApiRequest`. A socket is the one door a
   // narrowed credential must not walk through just because it authenticated.
-  if (credential) {
-    const scoped = permissionForWsProvider(provider);
-    if (!scoped || !credential.includes(scoped.key)) return false;
-  }
+  if (scope && !credentialAdmits(scope, permissionForWsProvider(provider))) return false;
 
   if (isOwner) return true;