feat(security): bind last-admin standing-key lists to the authz resolver's measured read surface (#8734) (#8801)

The break-glass guard's three standing-key lists are a cache of which columns
resolveAuthzContext reads when deriving administrator standing. Nothing bound
them together — the correspondence was a comment, and it had already gone false
once (#6084's comment named 'active' as invisible; #8613 made it a
resolution-time predicate).

Two links replace the prose:

1. packages/core declares ADMIN_STANDING_SURFACE beside the resolver and asserts
   it EQUALS what the real resolveAuthzContext reads, observed at runtime through
   a recording engine (property accesses + where keys, per table). Observation
   rather than static extraction because the reads that matter live in helpers:
   isRowActive reads 'active', isGrantActive reads the ADR-0091 bounds.

2. plugin-auth exports its lists plus STANDING_KEYS_BY_TABLE /
   STANDING_KEY_EXCLUSIONS, and a gate requires every measured column to be
   either standing-bearing or excluded with a reason. No third state.

No guard behaviour changes: every list keeps its exact values, and the gate is
one-directional so it can only ever demand the guard judges more.


Claude-Session: https://claude.ai/code/session_01NaS1PAHJcPfAA2acnV53Tn

Co-authored-by: Claude <noreply@anthropic.com>

Author: Jack Q

.changeset/last-admin-standing-keys-gate.md

@@ -0,0 +1,59 @@
+---
+"@objectstack/core": minor
+"@objectstack/plugin-auth": minor
+---
+
+feat(security): bind the break-glass standing-key lists to what the authz resolver actually reads — the correspondence stops being prose (#8734)
+
+`plugin-auth`'s last-administrator guard (ADR-0024 D5.2) decides whether a
+pending write can empty the administrator population by testing the payload
+against three standing-key lists (`MEMBER_STANDING_KEYS`,
+`GRANT_STANDING_KEYS`, `PERMISSION_SET_STANDING_KEYS`). A payload touching none
+of them is skipped without any reads — so a column `resolveAuthzContext` starts
+reading that a list omits is a write class the guard **silently stops judging**,
+on the one path whose failure mode is an installation-wide administrator lockout
+with no in-product recovery.
+
+Nothing bound the two together. The correspondence lived in a comment, and it
+had already gone false once: #6084 wrote — naming `active` explicitly — that
+everything a permission-set write touches other than `name` is invisible to "who
+is an administrator". That was true when written; #8613 made `active` a
+resolution-time predicate and the sentence became false. Nothing mechanical
+would have caught it, because the guard's own tests stay green precisely when
+the guard is never consulted.
+
+**The mechanism is two links, and the first one is a measurement.**
+
+- `@objectstack/core` now exports `ADMIN_STANDING_SURFACE` — declared beside the
+  resolver, listing every table the administrator-derivation path reads, each
+  classified `derives` or `reads-only` with its reason, and for the deriving
+  tables every column read. It is asserted **equal** to what the real
+  `resolveAuthzContext` reads, observed at runtime through a recording engine
+  that records every property access and every `where` key per table. Observation
+  rather than source extraction because the reads that matter have moved into
+  helpers: `active` is read by `isRowActive(row)` and the ADR-0091 window bounds
+  by `isGrantActive(row, now)`, neither named at the resolver's own call site —
+  the exact shape #8613 had.
+
+- `@objectstack/plugin-auth` now exports its standing-key lists plus
+  `STANDING_KEYS_BY_TABLE` and `STANDING_KEY_EXCLUSIONS`, and a gate requires
+  every column of that measured surface to have an answer: it is standing-bearing
+  (in a list) or it is excluded with the reason it cannot empty the administrator
+  population. There is no third state — the third state is what `active` was
+  between #6084 and #8613.
+
+So a resolver change that starts reading a new column fails at the first link
+until the declaration is updated, and at the second until the guard has an
+explicit answer for it. Landing #8613 green would have required writing down that
+deactivating `admin_full_access` cannot empty the administrator population —
+which is false, and which is what the old comment asserted by accident.
+
+**No guard behaviour changes.** Every list keeps exactly the values it had; the
+gate is one-directional by construction (it can only ever demand that the guard
+judges *more*), because the other direction would put pressure on a break-glass
+guard to fire less often.
+
+The table-level half is covered too: a resolver that started deriving
+administrator standing from a **new** table is invisible to any column-set
+comparison, since the table is absent from both sides — so the surface enumerates
+every table the path reads, and an unclassified one fails.

packages/core/src/security/admin-standing-surface.test.ts

@@ -0,0 +1,324 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#8734] The FIRST of the two links that bind `plugin-auth`'s break-glass
+ * standing-key lists to what this resolver actually reads.
+ *
+ * This half answers one question mechanically: **which columns does
+ * `resolveAuthzContext` read on the tables administrator standing is derived
+ * from?** It answers it by OBSERVATION — the real resolver is driven over a
+ * recording engine that returns `Proxy`-wrapped rows and records every property
+ * access, plus every `where` key, per table — and asserts the answer equals
+ * `ADMIN_STANDING_SURFACE`.
+ *
+ * The second link lives in `plugin-auth`
+ * (`last-admin-standing-keys.test.ts`): it requires every column declared here
+ * to be either in a standing-key list or explicitly excluded with a reason. So
+ * a resolver change that starts reading a new column fails HERE until the
+ * declaration is updated, and fails THERE until the guard has an answer for it.
+ *
+ * ## Why observation rather than a static extractor
+ *
+ * A source-parsing gate would have to follow `psRowsAll` into `psRows` into the
+ * `for (const ps of psRows)` loop to learn that `ps.name` is a read of
+ * `sys_permission_set.name` — real dataflow analysis, brittle in exactly the
+ * places that matter. Worse, it would have to inline the helpers: `active` is
+ * never named on the resolver's own call site (`isRowActive(r)` reads it), and
+ * neither is `valid_from` (`isGrantActive(row, now)` reads it). #8613's whole
+ * defect was a read that moved into a predicate; a gate that reads the caller
+ * and not the callee would have missed it for the same reason the comment did.
+ *
+ * ## Why the fixtures come in variants
+ *
+ * A conditional read is invisible in a fixture that never takes the branch. The
+ * resolver's tolerated-spelling chains are the sharp case: `r.organization_id ??
+ * r.organizationId` never touches the camelCase spelling while the snake_case
+ * one is non-nullish. So the observation is the UNION over fixtures chosen to
+ * take both sides of every such chain — snake-only rows, camel-only rows, and a
+ * pass where the flags and windows are set the other way. `assertVariantsStay-
+ * Distinct` keeps that honest: if two variants ever observe the same set, one of
+ * them has stopped contributing and the union has silently narrowed.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import { ADMIN_STANDING_SURFACE, adminStandingTables } from './admin-standing-surface.js';
+import { resolveAuthzContext } from './resolve-authz-context.js';
+
+/** table -> every column name the resolver touched on it. */
+type Observation = Map<string, Set<string>>;
+
+const camelOf = (key: string): string => key.replace(/_([a-z])/g, (_m, c: string) => c.toUpperCase());
+
+/**
+ * An ObjectQL stand-in that records what the resolver READS.
+ *
+ * Two rules keep the recording faithful:
+ *
+ *  - the `where` match runs against the RAW row, never the proxy, so the fake
+ *    driver's own reads are not mistaken for the resolver's;
+ *  - `where` keys ARE recorded, because filtering on a column is reading it —
+ *    a resolver that started passing `where: { active: true }` would be
+ *    consuming `active` just as surely as `isRowActive` does.
+ *
+ * The matcher resolves a column through either spelling so a camelCase-only
+ * fixture still matches a snake_case `where`; that leniency is the harness's,
+ * never the resolver's, and it exists so the camel variant can reach the same
+ * code path rather than returning nothing.
+ */
+function makeRecordingQl(tables: Record<string, Array<Record<string, unknown>>>, seen: Observation) {
+  const note = (table: string, column: string): void => {
+    let cols = seen.get(table);
+    if (!cols) {
+      cols = new Set<string>();
+      seen.set(table, cols);
+    }
+    cols.add(column);
+  };
+  const raw = (row: Record<string, unknown>, key: string): unknown =>
+    key in row ? row[key] : row[camelOf(key)];
+
+  return {
+    async find(object: string, opts: { where?: Record<string, unknown> } = {}) {
+      if (!seen.has(object)) seen.set(object, new Set<string>());
+      const where = opts?.where ?? {};
+      for (const key of Object.keys(where)) {
+        if (!key.startsWith('$')) note(object, key);
+      }
+      const rows = (tables[object] ?? []).filter((row) =>
+        Object.entries(where).every(([key, cond]) => {
+          if (cond && typeof cond === 'object') {
+            const c = cond as Record<string, unknown>;
+            if ('$in' in c) return (c.$in as unknown[]).includes(raw(row, key));
+            if ('$nin' in c) return !(c.$nin as unknown[]).includes(raw(row, key));
+            if ('$ne' in c) return raw(row, key) !== c.$ne;
+          }
+          return raw(row, key) === cond;
+        }),
+      );
+      return rows.map(
+        (row) =>
+          new Proxy(row, {
+            get(target, prop, receiver) {
+              // `then` would make the row look thenable to an `await`; symbols
+              // are never column names.
+              if (typeof prop === 'string' && prop !== 'then') note(object, prop);
+              return Reflect.get(target, prop, receiver);
+            },
+          }),
+      );
+    },
+  };
+}
+
+const headers = () => new Headers();
+const sessionFor = (userId: string, org?: string) => async () => ({
+  user: { id: userId, email: 'ada@example.com' },
+  session: { activeOrganizationId: org ?? null },
+});
+
+const HOUR = 3_600_000;
+const NOW = Date.parse('2026-08-15T00:00:00.000Z');
+
+/**
+ * Fixture variants, each reaching the platform-admin derivation and each
+ * deliberately taking a different side of the resolver's conditional reads.
+ */
+const VARIANTS: Record<string, { tables: Record<string, Array<Record<string, unknown>>>; org?: string }> = {
+  // Snake_case rows, unscoped in-window grant, active set: the happy platform-admin path.
+  'snake-case rows, standing intact': {
+    org: 'org_1',
+    tables: {
+      sys_user: [{ id: 'usr_1', email: 'ada@example.com', ai_access: 1 }],
+      sys_member: [
+        { id: 'mem_1', user_id: 'usr_1', organization_id: 'org_1', role: 'owner', valid_from: null, valid_until: null },
+      ],
+      sys_user_position: [
+        { id: 'upo_1', user_id: 'usr_1', position: 'contributor', organization_id: null, valid_from: null, valid_until: null },
+      ],
+      sys_position: [{ id: 'pos_1', name: 'contributor', active: true }],
+      sys_position_permission_set: [{ position_id: 'pos_1', permission_set_id: 'pst_2' }],
+      sys_user_permission_set: [
+        {
+          id: 'ups_1',
+          user_id: 'usr_1',
+          permission_set_id: 'pst_1',
+          organization_id: null,
+          valid_from: null,
+          valid_until: null,
+        },
+      ],
+      sys_permission_set: [
+        {
+          id: 'pst_1',
+          name: 'admin_full_access',
+          active: true,
+          system_permissions: ['view_all_records'],
+          tab_permissions: { setup: 'visible' },
+        },
+        { id: 'pst_2', name: 'contributor_set', active: true },
+      ],
+    },
+  },
+
+  // camelCase-only rows: every `snake ?? camel` chain must fall through to its
+  // second limb, which is the only way the camelCase spellings are observed.
+  'camelCase-only rows': {
+    org: 'org_1',
+    tables: {
+      sys_user: [{ id: 'usr_1', email: 'ada@example.com', ai_access: true }],
+      sys_member: [{ id: 'mem_1', userId: 'usr_1', organizationId: 'org_1', role: 'admin' }],
+      sys_user_position: [{ id: 'upo_1', userId: 'usr_1', position: 'contributor' }],
+      sys_position: [{ id: 'pos_1', name: 'contributor', active: true }],
+      sys_position_permission_set: [{ positionId: 'pos_1', permissionSetId: 'pst_2' }],
+      sys_user_permission_set: [{ id: 'ups_1', userId: 'usr_1', permissionSetId: 'pst_1' }],
+      sys_permission_set: [
+        {
+          id: 'pst_1',
+          name: 'admin_full_access',
+          active: true,
+          systemPermissions: ['view_all_records'],
+          tabPermissions: { setup: 'visible' },
+        },
+        { id: 'pst_2', name: 'contributor_set', active: true },
+      ],
+    },
+  },
+
+  // Standing taken away every way the resolver knows: the set switched off
+  // (ADR-0049), the grant scoped to an organization, the window closed
+  // (ADR-0091), the position deactivated, and the JSON blobs stored as strings.
+  'standing revoked every way': {
+    org: 'org_1',
+    tables: {
+      sys_user: [{ id: 'usr_1', email: 'ada@example.com', ai_access: 0 }],
+      sys_member: [
+        {
+          id: 'mem_1',
+          user_id: 'usr_1',
+          organization_id: 'org_1',
+          role: 'member',
+          valid_from: new Date(NOW - HOUR).toISOString(),
+          valid_until: new Date(NOW + HOUR).toISOString(),
+        },
+      ],
+      sys_user_position: [
+        {
+          id: 'upo_1',
+          user_id: 'usr_1',
+          position: 'contributor',
+          organization_id: 'org_1',
+          valid_from: new Date(NOW - HOUR).toISOString(),
+          valid_until: new Date(NOW - 1).toISOString(),
+        },
+      ],
+      sys_position: [{ id: 'pos_1', name: 'contributor', active: false }],
+      sys_position_permission_set: [{ position_id: 'pos_1', permission_set_id: 'pst_2' }],
+      sys_user_permission_set: [
+        {
+          id: 'ups_1',
+          user_id: 'usr_1',
+          permission_set_id: 'pst_1',
+          organization_id: 'org_1',
+          valid_from: new Date(NOW - HOUR).toISOString(),
+          valid_until: new Date(NOW + HOUR).toISOString(),
+        },
+      ],
+      sys_permission_set: [
+        {
+          id: 'pst_1',
+          name: 'admin_full_access',
+          active: false,
+          system_permissions: JSON.stringify(['view_all_records']),
+          tab_permissions: JSON.stringify({ setup: 'visible' }),
+        },
+        { id: 'pst_2', name: 'contributor_set', active: true },
+      ],
+    },
+  },
+};
+
+async function observe(variant: keyof typeof VARIANTS): Promise<Observation> {
+  const seen: Observation = new Map();
+  const { tables, org } = VARIANTS[variant];
+  await resolveAuthzContext({
+    ql: makeRecordingQl(tables, seen),
+    headers: headers(),
+    getSession: sessionFor('usr_1', org),
+    nowMs: NOW,
+  });
+  return seen;
+}
+
+async function observeAll(): Promise<Observation> {
+  const union: Observation = new Map();
+  for (const name of Object.keys(VARIANTS)) {
+    const seen = await observe(name);
+    for (const [table, cols] of seen) {
+      const into = union.get(table) ?? new Set<string>();
+      for (const col of cols) into.add(col);
+      union.set(table, into);
+    }
+  }
+  return union;
+}
+
+const sorted = (s: Iterable<string>): string[] => [...s].sort();
+
+describe('[#8734] ADMIN_STANDING_SURFACE is what resolveAuthzContext actually reads', () => {
+  it('declares every table the resolution path reads — a new one must be classified', async () => {
+    const union = await observeAll();
+    expect(sorted(union.keys())).toEqual(sorted(Object.keys(ADMIN_STANDING_SURFACE)));
+  });
+
+  it.each(adminStandingTables())(
+    'declares exactly the columns read on %s',
+    async (table) => {
+      const union = await observeAll();
+      const observed = sorted(union.get(table) ?? []);
+      const declared = sorted(ADMIN_STANDING_SURFACE[table]!.columns ?? []);
+      // Equality, not containment, in BOTH directions on purpose. An undeclared
+      // read is the #8613 defect. A declared column nothing reads is the stale
+      // comment this file replaced, and left alone it would go on demanding a
+      // guard entry for a column that stopped mattering.
+      expect(observed).toEqual(declared);
+    },
+  );
+
+  it('reaches the platform-admin derivation — otherwise the observation proves nothing', async () => {
+    const ctx = await resolveAuthzContext({
+      ql: makeRecordingQl(VARIANTS['snake-case rows, standing intact']!.tables, new Map()),
+      headers: headers(),
+      getSession: sessionFor('usr_1', 'org_1'),
+      nowMs: NOW,
+    });
+    // A positive control on the fixture itself: if the happy variant ever stops
+    // resolving a platform admin, every column below it goes unobserved and the
+    // equality above starts passing over a path nothing walked.
+    expect(ctx.positions).toContain('platform_admin');
+    expect(ctx.posture).toBe('PLATFORM_ADMIN');
+  });
+
+  it('keeps the variants distinct — a variant that stops contributing narrows the union silently', async () => {
+    const perVariant = new Map<string, string>();
+    for (const name of Object.keys(VARIANTS)) {
+      const seen = await observe(name);
+      const signature = sorted(seen.keys())
+        .map((t) => `${t}:${sorted(seen.get(t)!).join(',')}`)
+        .join('|');
+      perVariant.set(name, signature);
+    }
+    expect(new Set(perVariant.values()).size).toBe(perVariant.size);
+  });
+
+  it('every declared table carries a reason, and only deriving tables carry columns', () => {
+    for (const [table, entry] of Object.entries(ADMIN_STANDING_SURFACE)) {
+      expect(entry.reason.length, `${table} needs a reason`).toBeGreaterThan(40);
+      if (entry.role === 'derives') {
+        expect(entry.columns, `${table} derives standing and must declare its columns`).toBeDefined();
+      } else {
+        expect(entry.columns, `${table} reads only and must not declare columns`).toBeUndefined();
+      }
+    }
+  });
+});