feat(core): anchor PLATFORM_ADMIN on a verified OS_PLATFORM_OWNER_EMAIL match, inside the one derivation site (#13146)

* wip: platform-admin config anchor (L2)

* wip: tests for the config anchor

* wip: changeset, vitest alias, tsconfig paths

* test(core): make the platform-admin-config double refuse top-level combinators

check:where-matcher graded the new fixture's matches() as silently wrong:
with no combinator branch it read $or as a field name, compared row.$or
(undefined) against the array and excluded the row, leaving the suite
asserting on an empty result with nothing erroring.

Refuses instead of implementing, which is what most of this repo's
conforming doubles do and what the sibling batch-equivalence double
already spells. $in stays supported: it is a per-field value operator the
resolver really issues, not a top-level combinator.

* docs(core): the sys_permission_set standing reason named the position, not the row

Two defects in one sentence, both pre-existing on main:

- it said the row `platform_admin` is resolved by name; the row is
  `admin_full_access` and `platform_admin` is the POSITION that row derives
  (resolve-authz-context.ts:594 matches the row, :665-666 unshifts the
  position);
- 'un-makes every platform admin at once' stopped being true for a
  configured deployment: the config anchor sets the same standing off the
  caller's own sys_user row and never reads this table.

A flat replacement would only swap which half is wrong, so the reason is now
conditional and states the condition -- true whether or not
OS_PLATFORM_OWNER_EMAIL is declared. Reason string only; role, columns and
every executable path are untouched.

---------

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

Author: claude[bot]

.changeset/platform-admin-config-anchor.md

@@ -0,0 +1,16 @@
+---
+'@objectstack/core': minor
+'@objectstack/plugin-auth': minor
+---
+
+`PLATFORM_ADMIN` can now be anchored on deployment CONFIGURATION instead of a stored grant row: an account whose `sys_user.email` is on `OS_PLATFORM_OWNER_EMAIL` **and** whose `email_verified` reads verified resolves `PLATFORM_ADMIN` with the declared `admin_full_access` capability set, derived live on each authorization resolution (#11663 leg L2, design accepted 2026-08-25 as bundle 1A/2B/3A/4A/5A/6A/7A).
+
+**Additive — nothing is revoked.** The legacy unscoped `admin_full_access` grant still confers exactly as it did; a holder whose standing rests on the row alone now gets a once-per-process pointer at the configuration line that re-anchors them. A deployment that has declared no administrators resolves byte-identically to before: the config list is empty, the derivation answers "not an admin" before it reads any row, and the pinned batch-equivalence query multiset is unchanged.
+
+**The variable takes a list.** `OS_PLATFORM_OWNER_EMAIL` accepts one address or a comma-separated list of them — one normalization (`trim().toLowerCase()`), duplicates collapsed, blank entries dropped. ⛔ Any entry that is not an address **fails the whole variable closed** with a loud refusal naming it, rather than being skipped: silently dropping a typo would leave a narrower administrator set than the operator declared, with nothing anywhere to notice. Unset, blank or refused all mean **zero** config-derived administrators.
+
+**Verified-email match only.** An unverified account holding a configured address confers nothing, and an ABSENT `email_verified` column reads unverified. The match reads the caller's own **stored** `sys_user` row, never the caller-supplied session email.
+
+New exports from `@objectstack/core`: `resolvePlatformAdminEmails`, `parsePlatformAdminEmails`, `matchesConfiguredPlatformAdmin`, `normalizePlatformAdminEmail`, `PLATFORM_ADMIN_EMAIL_SEPARATOR`, `ADMIN_STANDING_NON_TABLE_INPUTS` and the test hooks beside them. `@objectstack/core` now depends on `@objectstack/types` (measured acyclic: `types` depends only on `spec`).
+
+`@objectstack/plugin-auth`'s break-glass guard follows the derivation, as it must: `ADMIN_STANDING_SURFACE.sys_user` is reclassified `derives`, the last-administrator enumeration counts config-derived administrators through the resolver's own predicate, and a fifth write shape is judged — a change of address or an `email_verified` reset that would leave the environment with no administrator is refused, naming the configuration as the remedy. An ordinary profile write still costs the guard no reads.

packages/core/package.json

@@ -33,6 +33,7 @@
   },
   "dependencies": {
     "@objectstack/spec": "workspace:*",
+    "@objectstack/types": "workspace:*",
     "zod": "^4.4.3"
   },
   "keywords": [

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

@@ -43,6 +43,7 @@
 import { describe, it, expect } from 'vitest';
 
 import { ADMIN_STANDING_SURFACE, adminStandingTables } from './admin-standing-surface.js';
+import { resetPlatformAdminEmailMemo } from './platform-admin.js';
 import { resolveAuthzContext } from './resolve-authz-context.js';
 
 /** table -> every column name the resolver touched on it. */
@@ -129,7 +130,24 @@ 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 }> = {
+const VARIANTS: Record<
+  string,
+  {
+    tables: Record<string, Array<Record<string, unknown>>>;
+    org?: string;
+    /**
+     * [#11663 L2] `OS_PLATFORM_OWNER_EMAIL` for this variant. The config anchor
+     * reads `sys_user.email` and `sys_user.email_verified` ONLY when the
+     * deployment declared administrators (pin P2 — an empty list answers
+     * "not an admin" before touching any row), so those two columns are
+     * invisible to every fixture that leaves the variable unset. That is
+     * exactly the "a conditional read is invisible in a fixture that never
+     * takes the branch" hazard this file's header names, so the branch gets a
+     * variant of its own.
+     */
+    platformAdminEmails?: string;
+  }
+> = {
   // Snake_case rows, unscoped in-window grant, active set: the happy platform-admin path.
   'snake-case rows, standing intact': {
     org: 'org_1',
@@ -241,17 +259,64 @@ const VARIANTS: Record<string, { tables: Record<string, Array<Record<string, unk
       ],
     },
   },
+
+  // [#11663 L2] The CONFIG anchor. No grant row anywhere: standing comes from
+  // the declared administrator list matched against this row's own `email`,
+  // gated on `email_verified`. This is the only variant in which those two
+  // columns are read at all, which is why the union needs it — without it the
+  // declaration below would have to omit them and the correspondence gate in
+  // plugin-auth would stop demanding a disposition for the very columns a
+  // write can revoke standing through.
+  'config-anchored platform admin': {
+    platformAdminEmails: 'ada@example.com',
+    tables: {
+      sys_user: [
+        { id: 'usr_1', email: 'ada@example.com', email_verified: true, ai_access: 0 },
+      ],
+      sys_member: [],
+      sys_user_position: [],
+      sys_position: [],
+      sys_position_permission_set: [],
+      sys_user_permission_set: [],
+      sys_permission_set: [],
+    },
+  },
 };
 
+/**
+ * Run `body` with `OS_PLATFORM_OWNER_EMAIL` set to exactly `value` (deleted when
+ * `undefined`), and the config memo dropped on BOTH sides.
+ *
+ * The memo is keyed on the raw string, so a worker that has already resolved
+ * one value would otherwise answer the next variant from the previous one's
+ * parse. Restoring the ambient value matters too: this suite must not decide
+ * what the rest of the worker's tests see.
+ */
+async function withPlatformAdminEmails<T>(value: string | undefined, body: () => Promise<T>): Promise<T> {
+  const prev = process.env.OS_PLATFORM_OWNER_EMAIL;
+  if (value === undefined) delete process.env.OS_PLATFORM_OWNER_EMAIL;
+  else process.env.OS_PLATFORM_OWNER_EMAIL = value;
+  resetPlatformAdminEmailMemo();
+  try {
+    return await body();
+  } finally {
+    if (prev === undefined) delete process.env.OS_PLATFORM_OWNER_EMAIL;
+    else process.env.OS_PLATFORM_OWNER_EMAIL = prev;
+    resetPlatformAdminEmailMemo();
+  }
+}
+
 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,
-  });
+  const { tables, org, platformAdminEmails } = VARIANTS[variant]!;
+  await withPlatformAdminEmails(platformAdminEmails, () =>
+    resolveAuthzContext({
+      ql: makeRecordingQl(tables, seen),
+      headers: headers(),
+      getSession: sessionFor('usr_1', org),
+      nowMs: NOW,
+    }),
+  );
   return seen;
 }
 
@@ -291,12 +356,14 @@ describe('[#8734] ADMIN_STANDING_SURFACE is what resolveAuthzContext actually re
   );
 
   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,
-    });
+    const ctx = await withPlatformAdminEmails(undefined, () =>
+      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.
@@ -316,6 +383,26 @@ describe('[#8734] ADMIN_STANDING_SURFACE is what resolveAuthzContext actually re
     expect(new Set(perVariant.values()).size).toBe(perVariant.size);
   });
 
+  it('[#11663 L2] the config variant reaches the CONFIG anchor, not a grant', async () => {
+    // The second positive control, for the second anchor. Without it the two
+    // new sys_user columns could go unobserved (the branch never taken) and the
+    // equality above would start passing over a path nothing walked — the exact
+    // shape the fixture-variant note at the top of this file warns about.
+    const v = VARIANTS['config-anchored platform admin']!;
+    const ctx = await withPlatformAdminEmails(v.platformAdminEmails, () =>
+      resolveAuthzContext({
+        ql: makeRecordingQl(v.tables, new Map()),
+        headers: headers(),
+        getSession: sessionFor('usr_1', v.org),
+        nowMs: NOW,
+      }),
+    );
+    expect(ctx.posture).toBe('PLATFORM_ADMIN');
+    expect(ctx.positions).toContain('platform_admin');
+    // …and it really is the config route: there is no grant row in the fixture.
+    expect(v.tables.sys_user_permission_set).toEqual([]);
+  });
+
   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);

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

@@ -55,6 +55,20 @@
  * the table-level half of the same guarantee: a resolver that starts deriving
  * administrator standing from a new table would otherwise be invisible to a
  * column-set comparison, because the new table appears in neither side's list.
+ *
+ * ## ⚠️ Tables are no longer the whole surface (#11663 L2)
+ *
+ * Since the platform-admin re-anchor's core leg, one input to the administrator
+ * derivation is NOT a table at all: the deployment's declared administrator
+ * list, read from the environment on every resolution
+ * (`security/platform-admin.ts`). A file that listed only tables would go on
+ * being perfectly accurate about the tables while silently claiming the
+ * derivation reads nothing else — the same shape as the stale comment this file
+ * replaced, one level up. {@link ADMIN_STANDING_NON_TABLE_INPUTS} is the place
+ * that says so, and it is deliberately a SEPARATE export rather than a
+ * pseudo-row in the table map: the map is compared for equality against
+ * observed table reads, and a pseudo-row would have to be excluded from that
+ * comparison by name, which is exactly the kind of special case that rots.
  */
 
 /** How a table this resolver reads relates to "who is an administrator". */
@@ -83,17 +97,25 @@ export interface AdminStandingTable {
  * principal, and therefore all of `resolveUserAuthzGrants`. The API-key
  * ADMISSION path (`resolveApiKeyAdmission`) is outside it on purpose: it
  * authenticates a principal and seeds `permissions` with the key's scopes, and
- * confers no administrator standing of its own — `hasPlatformAdminGrant` (§6b)
- * is set only from a `sys_permission_set` row reached through an UNSCOPED
- * `sys_user_permission_set` grant, never from a scope string.
+ * confers no administrator standing of its own — `hasPlatformAdminGrant` is set
+ * from a `sys_permission_set` row reached through an UNSCOPED
+ * `sys_user_permission_set` grant (§6b) or from the deployment config matched
+ * against the caller's own STORED `sys_user` row (§6b-config), never from a
+ * scope string and never from the caller-seedable `grants.email`.
  */
 export const ADMIN_STANDING_SURFACE: Readonly<Record<string, AdminStandingTable>> = {
   sys_permission_set: {
     role: 'derives',
     reason:
-      'The row `platform_admin` is resolved BY NAME from (§6b). Renaming it, deleting it or '
-      + 'switching it off (ADR-0049 `active`, read here since #8613) un-makes every platform '
-      + 'admin at once, with no identity table touched.',
+      'The row `admin_full_access` is resolved BY NAME from (§6b) — `platform_admin` is the '
+      + "POSITION that row derives, not the row's own name. Renaming it, deleting it or switching "
+      + 'it off (ADR-0049 `active`, read here since #8613) un-makes every GRANT-derived platform '
+      + 'admin at once, with no identity table touched. ⚠️ It does NOT un-make a CONFIG-derived '
+      + 'one (§6b-config, #11970): that route sets the same standing from '
+      + "`ADMIN_FULL_ACCESS_CAPABILITIES` in `@objectstack/spec` and matches the caller's own "
+      + 'stored `sys_user` row, so it touches an identity table and never reads this one. With '
+      + '`OS_PLATFORM_OWNER_EMAIL` unset the first sentence is the whole truth; with it declared, '
+      + 'this row stops being the single point that un-makes every administrator.',
     columns: [
       'id',
       'name',
@@ -146,12 +168,25 @@ export const ADMIN_STANDING_SURFACE: Readonly<Record<string, AdminStandingTable>
   },
 
   sys_user: {
-    role: 'reads-only',
+    role: 'derives',
     reason:
-      'Read for the `current_user.email` RLS fallback and the ADR-0024 `ai_seat` synthesis (§7). '
-      + 'Neither confers administrator standing. The guard does watch this table, but for the '
-      + 'ban/delete WRITE SHAPES — `banned` is never read here, so it is not a derivation column '
-      + 'and carries no standing-key list.',
+      '[#11663 L2] RECLASSIFIED from `reads-only`. This table used to be read only for the '
+      + '`current_user.email` RLS fallback and the ADR-0024 `ai_seat` synthesis (§7), and the '
+      + 'note here said so: "Neither confers administrator standing." That sentence is now FALSE. '
+      + 'The config anchor (§6b-config) matches the row\'s own `email` against the deployment\'s '
+      + 'declared administrator list and requires `email_verified` to read verified, so a write '
+      + 'that changes either column takes platform-admin standing away from a config-derived '
+      + 'administrator — an address change and an email_verified reset are both ordinary, '
+      + 'reachable writes, and neither touches a grant table. `banned` stays absent from the '
+      + 'column list because the resolver still never reads it; the guard watches the ban/delete '
+      + 'WRITE SHAPES on this table for its own reasons, which is a different question from what '
+      + 'this resolver consumes.',
+    columns: [
+      'id',
+      'email',
+      'email_verified',
+      'ai_access',
+    ],
   },
 
   sys_user_position: {
@@ -180,6 +215,46 @@ export const ADMIN_STANDING_SURFACE: Readonly<Record<string, AdminStandingTable>
   },
 };
 
+/** A derivation input that is not a table — see {@link ADMIN_STANDING_NON_TABLE_INPUTS}. */
+export interface AdminStandingNonTableInput {
+  /** How the value reaches the resolver, e.g. `env` for a process environment variable. */
+  readonly kind: 'env';
+  /** The exact spelling an operator sets — quotable verbatim in a refusal message. */
+  readonly name: string;
+  /** What it decides, and what a break-glass guard can and cannot do about it. */
+  readonly reason: string;
+}
+
+/**
+ * [#11663 L2] Inputs to the administrator derivation that no table write can
+ * reach — declared here so this file's silence about them cannot be read as
+ * "the derivation reads only tables".
+ *
+ * The practical consequence is the one worth writing down: a break-glass guard
+ * simulates a pending WRITE, and there is no write to simulate for any of
+ * these. Standing that rests on one of them is taken away by changing the
+ * deployment's configuration and rolling the process, which is deliberately
+ * outside every in-product path — including every path an agent could be talked
+ * into calling. That is the whole point of the config anchor, and it is also
+ * the reason a guard cannot promise to prevent this class of lockout: it can
+ * only refuse the writes it can see.
+ */
+export const ADMIN_STANDING_NON_TABLE_INPUTS: readonly AdminStandingNonTableInput[] = [
+  {
+    kind: 'env',
+    name: 'OS_PLATFORM_OWNER_EMAIL',
+    reason:
+      'The deployment\'s declared platform administrator(s) — one address or a comma-separated '
+      + 'list, matched case-insensitively against `sys_user.email` and conferring standing only '
+      + 'when that row\'s `email_verified` reads verified (§6b-config). Read live on every '
+      + 'derivation with a per-process memo keyed on the raw string, so a rolled process picks up '
+      + 'a change with no special path. Unset, blank, or carrying any unparseable entry means '
+      + 'ZERO config-derived administrators, fail closed. No runtime write reaches it, so no '
+      + 'break-glass guard can simulate a change to it: revocation is a configuration change plus '
+      + 'a process roll, by design.',
+  },
+];
+
 /** The tables a write to which can change who is an administrator. */
 export function adminStandingTables(): string[] {
   return Object.entries(ADMIN_STANDING_SURFACE)

packages/core/src/security/index.ts

@@ -155,11 +155,33 @@ export { isRowActive, type ActivatableRow } from './row-active.js';
 // single source `plugin-auth`'s break-glass standing-key lists correspond to.
 export {
   ADMIN_STANDING_SURFACE,
+  ADMIN_STANDING_NON_TABLE_INPUTS,
   adminStandingTables,
   adminStandingColumns,
   type AdminStandingTable,
+  type AdminStandingNonTableInput,
 } from './admin-standing-surface.js';
 
+// [#11663 L2] The DEPLOYMENT-CONFIG anchor for PLATFORM_ADMIN — parse,
+// normalization and match predicate for `OS_PLATFORM_OWNER_EMAIL`, consumed by
+// `resolve-authz-context.ts` §6b-config. Exported so the sibling legs
+// (plugin-auth's break-glass guard, plugin-security's bootstrap, the audit
+// surface) ask the SAME question instead of re-implementing the parse — which
+// is the whole reason the config read has exactly one home.
+export {
+  PLATFORM_ADMIN_EMAIL_SEPARATOR,
+  normalizePlatformAdminEmail,
+  parsePlatformAdminEmails,
+  resolvePlatformAdminEmails,
+  resetPlatformAdminEmailMemo,
+  matchesConfiguredPlatformAdmin,
+  reportLegacyPlatformAdminGrant,
+  resetLegacyPlatformAdminGrantReport,
+  setPlatformAdminConfigSink,
+  type PlatformAdminEmailConfig,
+  type PlatformAdminConfigSink,
+} from './platform-admin.js';
+
 // [#7678] ADR-0090 D5/D9 — the audience-binding suggestion `?status=` vocabulary,
 // shared by the runtime dispatcher's `/security` domain and the live REST route.
 export {