feat(spec,security): OrgScopingEntitlement grows platform-global exemption + unbounded-admin suppression, consumed by Layer 0 arming (#12704)

* feat(spec,security): OrgScopingEntitlement platform-global exemption + unbounded-admin suppression

Part of objectstack-ai/cloud#1653 (Phase 1).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore(spec): regenerate security-shard artifacts + PlatformGlobalObjects type alias

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore: changeset for OrgScopingEntitlement wall-shaping keys

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/orange-planets-sniff.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/spec': minor
+'@objectstack/plugin-security': minor
+---
+
+`OrgScopingEntitlement` grows two per-deployment wall-shaping keys, both declared by the mounted `org-scoping` runtime and consumed by plugin-security when arming the Layer 0 organization wall, both fail-closed (absent ⇒ byte-identical behaviour):
+
+- `platformGlobalObjects?: readonly string[]` — objects THIS deployment declares platform-global; Layer 0 does not wall them here (read filtering, the ADR-0123 D2 no-active-org write refusal, the forge guard, and the Layer 1 wildcard-`organization_id` policy drop all follow, because they read the same per-object security meta). Exact machine names only; a junk shape is refused loudly and exempts nothing.
+- `suppressUnboundedOrgAdminGrant?: boolean` — the walled-posture `organization_admin` auto-grant hands out `organization_admin_no_bypass` (no unbounded `viewAllRecords`/`modifyAllRecords`) instead; the superseded-variant reconcile converges standing grants in both directions.
+
+New spec exports: `PlatformGlobalObjectsSchema`, `PlatformGlobalObjects`, `OrgScopingEntitlementSchema`.

content/docs/references/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Protocol Reference
-description: Every schema published by @objectstack/spec — 1584 schemas across 14 protocol modules
+description: Every schema published by @objectstack/spec — 1586 schemas across 14 protocol modules
 ---
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -28,12 +28,12 @@ counts are sums of the rows they head. Regenerate with
 | [Integration Protocol](/docs/references/integration) | 1 | 27 | The single connector protocol (ADR-0097) — catalog descriptors and provider-bound instances. |
 | [Kernel Protocol](/docs/references/kernel) | 31 | 171 | Plugin lifecycle and manifests, capabilities and security, metadata loading, service registry. |
 | [QA Protocol](/docs/references/qa) | 1 | 8 | Declarative test suites — scenarios, steps, actions and assertions. |
-| [Security Protocol](/docs/references/security) | 5 | 27 | Permission sets, row-level security, sharing rules, tenancy posture. |
+| [Security Protocol](/docs/references/security) | 5 | 29 | Permission sets, row-level security, sharing rules, tenancy posture. |
 | [Shared Protocol](/docs/references/shared) | 8 | 32 | Primitives used across every protocol — identifiers, HTTP, expressions, error maps, enums. |
 | [Studio Protocol](/docs/references/studio) | 3 | 35 | Studio designer metadata — the authoring surfaces for the protocols above. |
 | [System Protocol](/docs/references/system) | 36 | 288 | The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance. |
 | [UI Protocol](/docs/references/ui) | 16 | 152 | Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI layer. |
-| **Total** | **199** | **1584** | 14 protocol modules |
+| **Total** | **199** | **1586** | 14 protocol modules |
 
 ---
 
@@ -269,14 +269,14 @@ Declarative test suites — scenarios, steps, actions and assertions.
 
 ## Security Protocol
 
-**Source:** `packages/spec/src/security/` · **Import:** `@objectstack/spec/security` · **5 pages, 27 schemas**
+**Source:** `packages/spec/src/security/` · **Import:** `@objectstack/spec/security` · **5 pages, 29 schemas**
 
 Permission sets, row-level security, sharing rules, tenancy posture.
 
 | File | Schemas |
 | :--- | :--- |
 | [`explain.zod.ts`](/docs/references/security/explain) | `AccessMatrix`, `AccessMatrixEntry`, `AuthzPosture`, `ExplainDecision`, `ExplainLayer`, `ExplainMatchedRule`, `ExplainOperation`, `ExplainRecordAttribution`, `ExplainRequest` |
-| [`misc`](/docs/references/security/misc) *(no single source file)* | `CapabilityDeclaration`, `TenancyPosture` |
+| [`misc`](/docs/references/security/misc) *(no single source file)* | `CapabilityDeclaration`, `OrgScopingEntitlement`, `PlatformGlobalObjects`, `TenancyPosture` |
 | [`permission.zod.ts`](/docs/references/security/permission) | `AdminScope`, `EffectiveObjectPermission`, `FieldPermission`, `ObjectAccessScope`, `ObjectPermission`, `PermissionSet` |
 | [`rls.zod.ts`](/docs/references/security/rls) | `RLSEvaluationResult`, `RLSOperation`, `RLSUserContext`, `RowLevelSecurityPolicy` |
 | [`sharing.zod.ts`](/docs/references/security/sharing) | `CriteriaSharingRule`, `OWDModel`, `ShareRecipientType`, `SharingLevel`, `SharingRule`, `SharingRuleType` |

content/docs/references/security/misc.mdx

@@ -8,8 +8,8 @@ description: Misc protocol schemas
 ## TypeScript Usage
 
 ```typescript
-import { CapabilityDeclarationSchema, TenancyPostureSchema } from '@objectstack/spec/security';
-import type { CapabilityDeclaration, TenancyPosture } from '@objectstack/spec/security';
+import { CapabilityDeclarationSchema, OrgScopingEntitlementSchema, PlatformGlobalObjectsSchema, TenancyPostureSchema } from '@objectstack/spec/security';
+import type { CapabilityDeclaration, OrgScopingEntitlement, PlatformGlobalObjects, TenancyPosture } from '@objectstack/spec/security';
 
 // Validate data
 const result = CapabilityDeclarationSchema.parse(data);
@@ -37,6 +37,26 @@ const result = CapabilityDeclarationSchema.parse(data);
 | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
 
 
+---
+
+## OrgScopingEntitlement
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **supportedPostures** | `Enum<'single' \| 'group' \| 'isolated'>[]` | optional |  |
+| **platformGlobalObjects** | `string[]` | optional |  |
+| **suppressUnboundedOrgAdminGrant** | `boolean` | optional |  |
+
+
+---
+
+## PlatformGlobalObjects
+
+**Type:** `string[]`
+
+
 ---
 
 ## TenancyPosture

packages/plugins/plugin-security/src/auto-org-admin-grant.test.ts

@@ -387,6 +387,100 @@ describe('[ADR-0105 D4] posture selects the org-admin variant', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// [#12699] Deployment-declared suppression of the unbounded walled grant.
+//
+// D4's "the wall bounds the superbits" rationale stops holding on a deployment
+// that carves platform-global objects OUT of the wall
+// (`OrgScopingEntitlement.platformGlobalObjects`), so the same entitlement may
+// declare `suppressUnboundedOrgAdminGrant: true` and the walled auto-grant
+// hands out the de-VAMA'd variant there too. Fail closed: absent ⇒ D4's
+// posture-keyed behaviour byte-identical (the block above IS that pin).
+// ---------------------------------------------------------------------------
+describe('[#12699] suppressUnboundedOrgAdminGrant', () => {
+  const seedBoth = () =>
+    makeStub({
+      sys_permission_set: [ORG_ADMIN_SET, ORG_ADMIN_NO_BYPASS_SET],
+      sys_member: [{ id: 'm1', user_id: 'u1', organization_id: 'o1', role: 'owner' }],
+      sys_user_permission_set: [],
+    });
+
+  it('suppression ON: `isolated` grants the de-VAMA\'d variant', async () => {
+    const stub = seedBoth();
+    const res = await reconcileOrgAdminGrant(stub, 'u1', 'o1', {
+      posture: 'isolated',
+      suppressUnboundedOrgAdminGrant: true,
+    });
+    expect(res.action).toBe('granted');
+    expect(stub.tables.sys_user_permission_set).toHaveLength(1);
+    expect(stub.tables.sys_user_permission_set[0].permission_set_id).toBe('ps_org_admin_nb');
+  });
+
+  it('suppression ON: `group` grants the de-VAMA\'d variant too', async () => {
+    const stub = seedBoth();
+    await reconcileOrgAdminGrant(stub, 'u1', 'o1', {
+      posture: 'group',
+      suppressUnboundedOrgAdminGrant: true,
+    });
+    expect(stub.tables.sys_user_permission_set[0].permission_set_id).toBe('ps_org_admin_nb');
+  });
+
+  it('suppression OFF (explicit false) is byte-identical to today: `isolated` grants the full set', async () => {
+    const stub = seedBoth();
+    await reconcileOrgAdminGrant(stub, 'u1', 'o1', {
+      posture: 'isolated',
+      suppressUnboundedOrgAdminGrant: false,
+    });
+    expect(stub.tables.sys_user_permission_set[0].permission_set_id).toBe('ps_org_admin');
+  });
+
+  it('turning suppression on REVOKES a standing unbounded grant (superseded-variant convergence)', async () => {
+    const stub = seedBoth();
+    await reconcileOrgAdminGrant(stub, 'u1', 'o1', { posture: 'isolated' });
+    expect(stub.tables.sys_user_permission_set[0].permission_set_id).toBe('ps_org_admin');
+
+    await reconcileOrgAdminGrant(stub, 'u1', 'o1', {
+      posture: 'isolated',
+      suppressUnboundedOrgAdminGrant: true,
+    });
+    expect(stub.tables.sys_user_permission_set).toHaveLength(1);
+    expect(stub.tables.sys_user_permission_set[0].permission_set_id).toBe('ps_org_admin_nb');
+
+    // ...and a deployment that withdraws the declaration converges back —
+    // the fail-closed default protects any deployment RELYING on the auto-grant.
+    await reconcileOrgAdminGrant(stub, 'u1', 'o1', { posture: 'isolated' });
+    expect(stub.tables.sys_user_permission_set).toHaveLength(1);
+    expect(stub.tables.sys_user_permission_set[0].permission_set_id).toBe('ps_org_admin');
+  });
+
+  it('backfill threads the suppression to every pair AND the orphan sweep', async () => {
+    const stub = makeStub({
+      sys_permission_set: [ORG_ADMIN_SET, ORG_ADMIN_NO_BYPASS_SET],
+      sys_member: [
+        { id: 'm1', user_id: 'u1', organization_id: 'o1', role: 'owner' },
+        { id: 'm2', user_id: 'u2', organization_id: 'o1', role: 'admin' },
+      ],
+      // Pre-existing unbounded grants from a pre-suppression walled boot, plus
+      // one orphan (no membership row) that only the sweep can reach.
+      sys_user_permission_set: [
+        { id: 'ups1', user_id: 'u1', organization_id: 'o1', permission_set_id: 'ps_org_admin' },
+        { id: 'ups2', user_id: 'u2', organization_id: 'o1', permission_set_id: 'ps_org_admin' },
+        { id: 'ups3', user_id: 'u9', organization_id: 'o1', permission_set_id: 'ps_org_admin' },
+      ],
+    });
+
+    await backfillOrgAdminGrants(stub, {
+      posture: 'isolated',
+      suppressUnboundedOrgAdminGrant: true,
+    });
+
+    const grants = stub.tables.sys_user_permission_set;
+    expect(grants).toHaveLength(2);
+    expect(grants.every((g) => g.permission_set_id === 'ps_org_admin_nb')).toBe(true);
+    expect(grants.some((g) => g.user_id === 'u9')).toBe(false);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // [#4586] Hop 2 of the elevation chain stops discarding provenance.
 //

packages/plugins/plugin-security/src/auto-org-admin-grant.ts

@@ -52,14 +52,32 @@ const SYSTEM_CTX = { isSystem: true } as const;
  * there instead. Deliberate blanket visibility remains available through
  * `admin_full_access` or an explicitly authored set; it just stops being a side
  * effect of a better-auth membership role.
+ *
+ * [#12699] `suppressUnbounded` is the deployment's own veto on the walled
+ * branch (`OrgScopingEntitlement.suppressUnboundedOrgAdminGrant`): D4's "Layer
+ * 0 bounds it" rationale stops holding on a deployment that carves
+ * platform-global objects OUT of the wall, so such a deployment declares that
+ * arming a walled posture must NOT auto-grant the unbounded superbits — the
+ * de-VAMA'd variant is granted on walled postures too. Fail closed: `false`/
+ * absent keeps today's posture-keyed behaviour exactly.
  */
-export function orgAdminSetNameForPosture(posture: TenancyPosture): string {
-  return postureEnforcesWall(posture) ? ORGANIZATION_ADMIN : ORGANIZATION_ADMIN_NO_BYPASS;
+export function orgAdminSetNameForPosture(
+  posture: TenancyPosture,
+  suppressUnbounded = false,
+): string {
+  return postureEnforcesWall(posture) && !suppressUnbounded
+    ? ORGANIZATION_ADMIN
+    : ORGANIZATION_ADMIN_NO_BYPASS;
 }
 
-/** The variant NOT granted under `posture` — reconciled away so a posture change converges. */
-function supersededOrgAdminSetName(posture: TenancyPosture): string {
-  return postureEnforcesWall(posture) ? ORGANIZATION_ADMIN_NO_BYPASS : ORGANIZATION_ADMIN;
+/**
+ * The variant NOT granted under `posture` — reconciled away so a posture (or
+ * [#12699] suppression) change converges on exactly one org-admin grant.
+ */
+function supersededOrgAdminSetName(posture: TenancyPosture, suppressUnbounded = false): string {
+  return orgAdminSetNameForPosture(posture, suppressUnbounded) === ORGANIZATION_ADMIN
+    ? ORGANIZATION_ADMIN_NO_BYPASS
+    : ORGANIZATION_ADMIN;
 }
 
 interface MaybeLogger {
@@ -259,6 +277,12 @@ export async function reconcileOrgAdminGrant(
      * did this" (ADR-0118 D1).
      */
     attributedUserId?: string;
+    /**
+     * [#12699] The deployment's `OrgScopingEntitlement.suppressUnboundedOrgAdminGrant`
+     * declaration, threaded by the caller (SecurityPlugin reads it live off the
+     * `org-scoping` service). Default `false` — today's behaviour exactly.
+     */
+    suppressUnboundedOrgAdminGrant?: boolean;
   } = {},
 ): Promise<{
   action: 'granted' | 'revoked' | 'noop' | 'skipped';
@@ -276,8 +300,9 @@ export async function reconcileOrgAdminGrant(
   // `single` (the wall-less, conservative choice) when a caller does not supply
   // one: an unknown posture must not hand out unbounded superuser bits.
   const posture: TenancyPosture = options.posture ?? 'single';
-  const grantSetName = orgAdminSetNameForPosture(posture);
-  const supersededSetName = supersededOrgAdminSetName(posture);
+  const suppressUnbounded = options.suppressUnboundedOrgAdminGrant === true;
+  const grantSetName = orgAdminSetNameForPosture(posture, suppressUnbounded);
+  const supersededSetName = supersededOrgAdminSetName(posture, suppressUnbounded);
 
   const permSetId = await resolvePermissionSetId(ql, grantSetName, logger);
   if (!permSetId) {
@@ -414,15 +439,26 @@ export async function reconcileOrgAdminGrant(
  */
 export async function backfillOrgAdminGrants(
   ql: any,
-  options: { logger?: MaybeLogger; limit?: number; posture?: TenancyPosture } = {},
+  options: {
+    logger?: MaybeLogger;
+    limit?: number;
+    posture?: TenancyPosture;
+    /** [#12699] See {@link reconcileOrgAdminGrant}'s option of the same name. */
+    suppressUnboundedOrgAdminGrant?: boolean;
+  } = {},
 ): Promise<{ scanned: number; granted: number; revoked: number; skipped: number }> {
   const logger = options.logger;
   const limit = options.limit ?? 5000;
   const posture: TenancyPosture = options.posture ?? 'single';
+  const suppressUnbounded = options.suppressUnboundedOrgAdminGrant === true;
   const summary = { scanned: 0, granted: 0, revoked: 0, skipped: 0 };
   if (!ql || typeof ql.find !== 'function') return summary;
 
-  const permSetId = await resolvePermissionSetId(ql, orgAdminSetNameForPosture(posture), logger);
+  const permSetId = await resolvePermissionSetId(
+    ql,
+    orgAdminSetNameForPosture(posture, suppressUnbounded),
+    logger,
+  );
   if (!permSetId) {
     logger?.debug?.('[security] org-admin backfill skipped — permission set missing');
     return summary;
@@ -432,7 +468,7 @@ export async function backfillOrgAdminGrants(
   // exactly the rows whose bits must stop applying.
   const supersededId = await resolvePermissionSetId(
     ql,
-    supersededOrgAdminSetName(posture),
+    supersededOrgAdminSetName(posture, suppressUnbounded),
     logger,
   );
 
@@ -448,7 +484,11 @@ export async function backfillOrgAdminGrants(
     if (seen.has(key)) continue;
     seen.add(key);
     summary.scanned += 1;
-    const res = await reconcileOrgAdminGrant(ql, userId, orgId, { logger, posture });
+    const res = await reconcileOrgAdminGrant(ql, userId, orgId, {
+      logger,
+      posture,
+      suppressUnboundedOrgAdminGrant: suppressUnbounded,
+    });
     if (res.action === 'granted') summary.granted += 1;
     else if (res.action === 'revoked') summary.revoked += 1;
     else if (res.action === 'skipped') summary.skipped += 1;
@@ -471,7 +511,11 @@ export async function backfillOrgAdminGrants(
     if (!userId || !orgId) continue;
     const key = `${userId}|${orgId}`;
     if (seen.has(key)) continue;
-    const res = await reconcileOrgAdminGrant(ql, userId, orgId, { logger, posture });
+    const res = await reconcileOrgAdminGrant(ql, userId, orgId, {
+      logger,
+      posture,
+      suppressUnboundedOrgAdminGrant: suppressUnbounded,
+    });
     if (res.action === 'revoked') summary.revoked += 1;
   }