feat(plugin-security)!: the security readers read the catalog and the activation ledger (ADR-0131 cutover stage 2a)

.changeset/15204-s2a-security-readers.md

@@ -0,0 +1,40 @@
+---
+'@objectstack/core': minor
+'@objectstack/plugin-security': minor
+---
+
+feat(plugin-security)!: the security plugin's own readers (set resolution, the delegated-administration gate, the permission explainer and the position-assignment refusal) read the security catalog and the activation ledger, not the catalog rows (ADR-0131 D3/D4)
+
+Clause-②: yes
+
+<!-- adr-0087: not-required (already-registered position-permission-sets-declared) stage 1 registered this cutover: row-only catalog items confer nothing, and this changeset carries that rule to the security plugin's own readers -->
+
+**BREAKING** (enforcement stops reading `sys_permission_set` rows), shipped as `minor` under the launch-window convention for breaking changes. This is the second step of the cutover that `position-permission-sets-declared` registers: the authorization resolver already reads the catalog; now the security plugin's readers read the same catalog.
+
+**Permission-set resolution (`@objectstack/plugin-security`).**
+
+- FROM: a set name the metadata service and the bootstrap sets did not answer was loaded from a `sys_permission_set` row (the caller's organization's, else an organization-less one), its object map and field map included, and dropped when the row's `active` was false.
+- TO: it is loaded from the security catalog (the environment registry the security plugin binds to its engine): every package's sets and every set an author saved through the metadata door. A set that only a row carries resolves nothing. The resolver already granted nothing through such a set; now its object and field permissions stop applying too.
+- Fix: declare the set through the metadata door (`PUT /api/v1/meta/permission/NAME`) or in a package.
+- A permission set that resolves only because a POSITION of the same name was folded into the request is dropped when the activation ledger (`sys_metadata_activation`, type `permission`) switched it off. The row's `active` column is not read.
+
+**Delegated administration (ADR-0090 D12).**
+
+- FROM: the sets a position distributes were its `sys_position_permission_set` rows in the caller's organization; `delegatable` was the organization's `sys_position` row's; the assignable-positions listing (`describeDelegableScope`) listed `sys_position` rows; a direct grant's set (and its `adminScope`) was its `sys_permission_set` row.
+- TO: all four read the security catalog by name. A position distributes the sets its definition's `permissionSets` names, so the containment check and the listing see a binding declared only on the definition. `delegatable` is the definition's. The listing offers every position the catalog holds. A direct grant's set is the catalog's definition of the name the grant carries; a grant naming a set the catalog does not hold is refused for a delegate (a tenant administrator is not judged).
+- A name a position's `permissionSets` carries that the catalog does not hold must be on the delegate's allowlist too. It grants nothing today, but it starts granting as soon as a set of that name is authored.
+- A catalog read that fails refuses the delegate's write. Before, it approved it as "distributes nothing".
+
+**The permission explainer.** "deactivated" is read from the activation ledger through the resolver's own read, so explain and enforce agree. A direct grant whose set the catalog does not hold is reported neither as expired nor as deactivated: there is no set to lose.
+
+**Position assignments (`sys_user_position.position`).**
+
+- FROM: refused `400 VALIDATION_FAILED` unless a `sys_position` row (the writer's organization's, or an organization-less one) carried the name. A position declared only in a package or saved only through the metadata door was refused.
+- TO: refused unless the security catalog holds a position of that name. A registry-declared position is accepted. A name only a `sys_position` row carries (with no definition) is refused, because it grants nothing. A deactivated position is still accepted.
+
+**One position name per deployment under `single`.**
+
+- FROM: a Setup create of a position, or a rename into a name, that an environment definition already held overwrote that definition (another organization's label and description, an empty `permissionSets`).
+- TO: refused `409 UNIQUE_VIOLATION`, the answer a second row of the name in one organization already gets, and the row write is undone. This covers a definition another organization's row wrote, one saved through the metadata door, and one an application stack declares. A name a package or a built-in holds keeps its `403 NOT_OVERRIDABLE`.
+
+**`@objectstack/core`.** `readDisabledCatalogNames(ql, positions, sets)` is exported: the resolver's one read of the activation ledger. It returns the names switched off for this deployment and is now shared by the explainer and the security plugin.

content/docs/permissions/authorization.mdx

@@ -430,7 +430,8 @@ an expiry: deactivation is an incident-response control, installation-wide,
 and there is no date on the user's own grant row to notice — without the
 state, the admin diagnosing "why did access disappear" would get the same
 answer as for a user who never held the grant, with no pointer to the
-catalogue row somebody switched off. Reported for the grant rows explain
+`sys_metadata_activation` row somebody switched off — the explainer reads the
+same ledger the resolver does, so explain and enforce agree. Reported for the grant rows explain
 already walks: `sys_user_position` rows and direct `sys_user_permission_set`
 grants (a deactivated set reached only through an active position's linkage is
 not re-derived — that would replicate the resolver's aggregation).
@@ -455,9 +456,12 @@ Deactivation is an incident-response control, so what it does **not** touch is
 deliberate. Administration surfaces keep listing and editing a deactivated
 position — an admin must still be able to unbind and clean up what they just
 switched off — and the write gates that judge audience-anchor bindings and a
-delegated administrator's blast radius keep reading every row, deactivated
-included: dropping rows there would make a refused binding *permitted* and a
-delegate's boundary *narrower*, which is the opposite of switching access off.
+delegated administrator's blast radius do not consult the activation ledger:
+they judge every binding and assignment in front of them — including the
+permission sets a position's definition names — whether or not the ledger
+switched it off, because skipping a switched-off one would make a refused
+binding *permitted* and a delegate's boundary *narrower*, which is the
+opposite of switching access off.
 
 ## Governance: how "declared = enforced" is kept true
 

content/docs/permissions/system-context.mdx

@@ -129,7 +129,7 @@ that silently does not happen.
 | 21b | **`readonly` strip bypassed — the write PREVIEW (`ObjectQL.validate`)** | objectql | Same as 19–21, in the preview: it runs the write's caller-write strips under the write's own gate, so a system preview reports no `readonly` drop and judges the value a system write would store. The `computed` strip of a `formula` value is NOT gated here or on either write verb — no driver has a column for it, so it runs for every caller | `packages/objectql/src/engine.ts#validate` |
 | 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing. One exception: a `formula` value, which the `computed` strip takes from every caller, so strict still refuses it | `packages/objectql/src/engine.ts#insert`, `packages/objectql/src/readonly-strict-errors.ts#READONLY_CLASS_REASONS` |
 | 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `packages/objectql/src/engine.ts#assertReferencesResolve` |
-| 23b | **Position-catalog check skipped** — a `sys_user_position` write whose `position` names no `sys_position` row is not refused | plugin-security | Get: a system writer can store an assignment naming no catalog row — the seed loader writes `stack.data` from `AppPlugin.start()`, before `kernel:ready` seeds the declared position catalog, so a refusal there would fail every authored assignment seed on a fresh boot. Lose: such a row grants nothing and nothing says so. A non-system insert, or a non-system update that changes `position`, is refused `400 VALIDATION_FAILED` / `reference_not_found` instead when no catalog row the writer's context reaches carries the name: its organization's rows plus the organization-less ones, read as `{ ...context, isSystem: true }`, never a bare `{ isSystem: true }`, so a name only another organization carries is refused like one nobody carries. It is the same stand-down, and the same tenant scope, as the engine's referential-integrity check for a lookup column | `packages/plugins/plugin-security/src/position-catalog-refusal.ts#assertPositionNamesCatalogRow` |
+| 23b | **Position-catalog check skipped** — a `sys_user_position` write whose `position` names no position in the security catalog is not refused | plugin-security | Get: a system writer can store an assignment naming no position — the seed loader writes `stack.data` from `AppPlugin.start()`, before `kernel:ready` seeds the declared position catalog, so a refusal there would fail every authored assignment seed on a fresh boot. Lose: such a row grants nothing and nothing says so. A non-system insert, or a non-system update that changes `position`, is refused `400 VALIDATION_FAILED` / `reference_not_found` instead when the security catalog holds no position of that name: the environment registry (ADR-0131 D3), one per deployment, which takes no organization, so a name only a `sys_position` row carries — any organization's — is refused like one nobody carries. It is the same stand-down as the engine's referential-integrity check for a lookup column | `packages/plugins/plugin-security/src/position-catalog-refusal.ts#assertPositionNamesCatalogRow` |
 | 23c | **Grant-name check relaxed for an unresolvable id** — a `sys_user_permission_set` write that supplies `permission_set` beside a `permission_set_id` naming no set the writer's context reaches keeps the supplied name | plugin-security | Get: a system writer can store a grant naming a set whose row does not exist yet — seed replay and boot provisioning may write the grant before the set row, the ordering the engine's referential-integrity check also stands down for. Lose: such a row's name is unchecked until a backfill names it. Everything else is judged for every caller, system included: the name is derived from the id on every write that carries one, and a supplied name that names any other set is refused `400 VALIDATION_FAILED` / `invalid_value`; a non-system caller's name beside an unresolvable id is refused the same way, read as `{ ...context, isSystem: true }` through the hook's `ctx.api.sudo()`, never a bare `{ isSystem: true }` (ADR-0131 D4) | `packages/plugins/plugin-security/src/grant-permission-set-name.ts#settle` |
 | 23d | **Grant-holder membership check skipped** — a `sys_user_position` or `sys_user_permission_set` write naming a user with no `sys_member` row in the row's organization is not refused | plugin-security | Get: a system writer can store such a grant — invitation acceptance writes the membership and its placement together, and seed replay, the organization-admin reconcile and the platform bootstraps write grants as the system. Lose: such a row takes effect once its user is admitted to the organization. A non-system insert, or a non-system update that moves `user_id` or `organization_id`, is refused `400 VALIDATION_FAILED` / `reference_not_found` at `user_id` instead, for every caller, a platform administrator included; the membership is read as `{ isSystem: true, tenantId }` with `tenantId` the row's own organization, never another one. A row stored with no organization is a global grant and is not judged | `packages/plugins/plugin-security/src/grant-holder-membership-refusal.ts#onInsert`, `#onUpdate` |
 | 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `packages/objectql/src/engine.ts#buildDriverOptions` |

packages/core/src/security/index.ts

@@ -156,6 +156,10 @@ export {
   // [#20580] The session arm's membership check (#15409 ruling B), so the
   // permission explainer resolves the user it explains through the same one.
   vetOrganizationClaim,
+  // [ADR-0049, ADR-0131 D3, ADR-0126 §4] The one deactivation read of the
+  // security catalog — the `sys_metadata_activation` ledger, never a catalog
+  // row's `active` column — shared with the explainer and the security plugin.
+  readDisabledCatalogNames,
   resolveLocalizationContext,
   type ResolvedAuthzContext,
   type ResolveAuthzInput,
@@ -232,7 +236,8 @@ export { isRowActive, type ActivatableRow } from './row-active.js';
 // ADR-0131 D2–D4 — the ONE by-name read of the security catalog (positions,
 // permission sets, capabilities) over the engine registry and the metadata
 // service. It says a definition EXISTS under a name, never that it is in
-// effect: the row `active` flag above stays the authority for that.
+// effect: the activation ledger is the authority for that
+// (`readDisabledCatalogNames`, exported with the resolver below).
 export {
   createSecurityCatalogReader,
   bindSecurityCatalogReader,

packages/core/src/security/resolve-authz-context.ts

@@ -771,8 +771,13 @@ function ledgerUnregistered(ql: any): boolean {
  * engine answers "object not found" rather than a missing table — so the
  * registry is asked first, as `ObjectQLPlugin`'s own ledger hydration does,
  * and the read is not issued. An engine with no registry to ask is read.
+ *
+ * Exported so every other reader of "is this switched off" — the permission
+ * explainer's dropped-grant report, the security plugin's position-name fold —
+ * asks this one read instead of a second copy, and explain and enforce cannot
+ * disagree about deactivation.
  */
-async function readDisabledCatalogNames(
+export async function readDisabledCatalogNames(
   ql: any,
   positions: readonly string[],
   sets: readonly string[],

packages/core/src/security/security-catalog.ts

@@ -67,13 +67,14 @@
  *
  * ## What this read does NOT answer
  *
- *  - ⛔ **Whether an item is in effect.** Deactivation lives on the catalog
- *    ROW (`sys_position.active`, `sys_permission_set.active`; standing ruling:
- *    the row flag stays authoritative), and no definition carries it. An entry
- *    here says a definition EXISTS under that name — never that it grants. A
- *    caller that drops the row flag because it now reads definitions would let
- *    a deactivated set grant again: the one widening this card must never
- *    open. Read the flag with `isRowActive` (`row-active.ts`) as before.
+ *  - ⛔ **Whether an item is in effect.** No definition carries the switch:
+ *    deactivation is the activation ledger's (`sys_metadata_activation`, one
+ *    row per `(metadata_type, name)`; ADR-0126 §3 regime C as ADR-0131 D6
+ *    amends it), read through `readDisabledCatalogNames`
+ *    (`resolve-authz-context.ts`) — never a catalog row's `active` column. An
+ *    entry here says a definition EXISTS under that name — never that it
+ *    grants. A caller that reads a definition and skips the ledger would let a
+ *    deactivated set grant again: the one widening this read must never open.
  *  - **The position → permission-set binding as a separate fact.** It is part
  *    of the position definition (`PositionSchema.permissionSets`, ADR-0131
  *    D3/D4); the resolver reads it from the entry this module answers, and no

packages/plugins/plugin-security/src/__tests__/security-catalog.testkit.ts

@@ -54,7 +54,7 @@ export function catalogFromTables(tables: Record<string, readonly unknown[] | un
   for (const row of setRows) {
     if (typeof row.name !== 'string' || permissions.some((d) => d.name === row.name)) continue;
     const definition: Definition = { name: row.name };
-    for (const [column, key] of [['system_permissions', 'systemPermissions'], ['tab_permissions', 'tabPermissions'], ['object_permissions', 'objects']] as const) {
+    for (const [column, key] of [['system_permissions', 'systemPermissions'], ['tab_permissions', 'tabPermissions'], ['object_permissions', 'objects'], ['admin_scope', 'adminScope']] as const) {
       const value = parsed(row[column] ?? row[key]);
       if (value !== undefined && value !== null) definition[key] = value;
     }
@@ -65,9 +65,16 @@ export function catalogFromTables(tables: Record<string, readonly unknown[] | un
     permissionSets: setRows,
     bindings: (tables.sys_position_permission_set ?? []) as Definition[],
   });
+  // A position definition also carries the row's `delegatable` (ADR-0091 D3),
+  // which the delegated-administration gate reads from the definition.
+  const positionRows = (tables.sys_position ?? []) as Definition[];
+  const delegatable = (name: string): boolean =>
+    positionRows.some((r) => r.name === name && (r.delegatable === true || r.delegatable === 1 || r.delegatable === '1'));
   return {
     permissions,
-    positions: positions.flatMap((f) => (f.fate === 'conflicting' ? [] : [{ name: f.name, permissionSets: [...f.permissionSets] }])),
+    positions: positions.flatMap((f) => (f.fate === 'conflicting'
+      ? []
+      : [{ name: f.name, permissionSets: [...f.permissionSets], ...(delegatable(f.name) ? { delegatable: true } : {}) }])),
   };
 }