Administration itself as a scoped grant — a business-unit subtree, an action set, and an assignable-set allowlist, with self-escalation structurally impossible (ADR-0090 D12).

Delegated Administration

A group with fifty subsidiaries cannot manage every grant from headquarters — but handing each subsidiary a full admin is worse. ADR-0090 D12's answer: administration itself becomes a scoped capability. A delegate can onboard their own staff and reshuffle their own positions, but can never grant anything outside an explicit allowlist — including to themselves — and can never touch tenant-level assets.

Because the scope lives on an ordinary permission set, it is distributed via positions, audited in the same tables, and explained by the same engine as every other grant. No parallel admin subsystem.

Authoring an admin scope

export const FieldOpsDelegate = definePermissionSet({
  name: 'field_ops_delegate',
  label: 'Field Ops Delegate Admin',
  // The scope authorizes WHAT may be administered…
  adminScope: {
    businessUnit: 'Field Operations',   // WHERE: this sys_business_unit subtree
    includeSubtree: true,               // default true
    manageAssignments: true,            // user ↔ position rows (sys_user_position)
    manageBindings: false,              // position ↔ set rows (sys_position_permission_set)
    authorEnvironmentSets: false,       // may they author environment-owned sets?
    assignablePermissionSets: ['showcase_contributor', 'showcase_manager'],
  },
  // …and plain CRUD on the RBAC link tables lets the requests through at all.
  // Both are required: table CRUD with NO scope is refused outright.
  objects: {
    sys_user_position: { allowRead: true, allowCreate: true, allowEdit: true, allowDelete: true },
    sys_position: { allowRead: true },
    sys_permission_set: { allowRead: true },
    sys_business_unit: { allowRead: true },
    sys_business_unit_member: { allowRead: true },
    sys_user: { allowRead: true },
  },
});

businessUnit names the subtree root by sys_business_unit.name; a misconfigured name resolves to an empty subtree and approves nothing (fail-closed).

What the runtime gate enforces

Writes to the governed tables (sys_user_position, sys_position_permission_set, sys_user_permission_set, sys_permission_set) pass through the DelegatedAdminGate:

Rule	Effect
Tenant admins pass through	The superuser wildcard reaches the ordinary CRUD/RLS checks — delegation constrains delegates, not HQ
Subtree anchoring	Assignments a delegate creates must be anchored (`sys_user_position.business_unit_id`) inside their subtree, and the target user must sit inside it
Allowlist, no self-escalation	Every set reached by the write — bound to the assigned position, or granted directly — must be on `assignablePermissionSets`. Granting an un-allowlisted set is refused for anyone, including the delegate themselves
Action flags	`manageAssignments` / `manageBindings` / `authorEnvironmentSets` gate their table classes independently; re-composing a position (`manageBindings`) additionally requires every current holder to sit inside the subtree
Strict containment	Granting or authoring a set that itself carries an `adminScope` requires a held scope that strictly contains it — handing your own exact scope to a peer is refused (no lateral propagation)
Single-row writes	Delegates write single rows by id only — a broad filter-write cannot be boundary-checked
Audit stamp	Every assignment a delegate creates is `granted_by`-stamped automatically
Tenant-level assets stay tenant-level	The `everyone`/`guest` audience anchors and security-domain publishes are untouchable from any delegated scope
No scope, no admin	Holders of plain CRUD on the RBAC tables with no scope are refused: administration is a scoped capability now, not a side effect of table access

Every rule above is exercised end-to-end by the showcase permission zoo (packages/qa/dogfood/test/showcase-permission-zoo.dogfood.test.ts): the in-subtree allowlisted assignment passes with a granted_by stamp; the out-of-subtree anchor, the off-allowlist grant (to self), and the manageBindings: false binding write are each refused.

The assignment anchor

Positions never bind to a business unit at the definition level — that would recreate the position-per-department explosion. The assignment row may: sys_user_position.business_unit_id names the unit the person holds the position in ("张三 is sales_manager of 华东"). It does exactly three things: anchors that assignment's depth grants to the subtree, provides the delegation boundary check above, and makes "manager of what" an auditable fact. Capability bits are never BU-scoped.

Explaining delegated decisions

The explain engine closes the loop twice:

explaining another user is authorized by manage_users or a delegated adminScope whose subtree covers that user — a delegate can diagnose their own people, and only their own people;
contributor attribution plus the granted_by stamp answer both who granted this and who could have.

Delegated Administration

Delegated Administration

Authoring an admin scope

What the runtime gate enforces

The assignment anchor

Explaining delegated decisions

See also

On this page