feat(security)!: ADR-0090 P3 — security publish linter (D7), delegated administration (D12), BU assignment anchor (#2711)

* feat(security)!: ADR-0090 P3 — security publish linter (D7), delegated administration (D12), BU assignment anchor

D7 — validateSecurityPosture in @objectstack/lint, gating os compile and
reported by os lint. Seven rules, each with a failing fixture: unset OWD on
custom objects (the objectui#2348 leave_request shape), retired OWD aliases
(fix-it), external dial wider than internal (D11), wildcard VAMA outside the
platform admin set (ADR-0066), high-privilege everyone-suggested sets, the
reserved word 'role' in security identifiers/labels (D3), and advisory
private-object-read-without-depth. The linter immediately caught real gaps:
app-crm shipped six objects with no OWD, app-showcase two, plus a 'role'
field on showcase_project_membership and the CLI golden corpus — all fixed
in this commit (grandfather stamps + engagement rename), proving the rule
set against its own repo.

D12 — DelegatedAdminGate in plugin-security. PermissionSetSchema.adminScope
(persisted as sys_permission_set.admin_scope) declares WHERE (BU subtree),
WHAT (manageAssignments / manageBindings / authorEnvironmentSets) and WHICH
sets a delegate may hand out (allowlist). Writes to sys_user_position,
sys_position_permission_set, sys_user_permission_set and sys_permission_set
are now governed: tenant admins (superuser wildcard) pass to ordinary
CRUD/RLS; delegates need a covering scope — subtree-anchored assignments,
allowlisted sets only (to others AND themselves), single-row writes,
granted_by audit stamping; plain CRUD holders with no scope are denied.
Granting/authoring a set that carries an adminScope requires strict
containment. everyone/guest anchors stay tenant-level only, and stored
assignments to an anchor are rejected for every caller.

ADR-0090 Addendum — sys_user_position.business_unit_id lands with its three
consumers: D12 delegation boundary (enforced), audit fact, and the
depth-anchor contract documented on IHierarchyScopeResolver for enterprise
resolvers.

D9 tightening — describeHighPrivilegeBits moved to @objectstack/spec/security
(shared by lint + runtime, re-exported from plugin-security) plus new
describeAnchorForbiddenBits: guest bindings now also reject edit bits.

D3 sweep — SysRole→SysPosition, SysUserRole→SysUserPosition,
SysRolePermissionSet→SysPositionPermissionSet (one-step, no aliases);
sys_position actions/list views/labels de-roled;
sys_business_unit_member.role_in_business_unit→function_in_business_unit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012oLzaP8n7A3YKFmgaHWC8H

* fix: stamp todo_task OWD (D7 linter), drop always-true ql conditional (CodeQL)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012oLzaP8n7A3YKFmgaHWC8H

---------

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

Author: os-zhuang

.changeset/adr-0090-p3-linter-delegated-admin.md

@@ -0,0 +1,21 @@
+---
+"@objectstack/spec": minor
+"@objectstack/lint": minor
+"@objectstack/cli": minor
+"@objectstack/plugin-security": major
+"@objectstack/platform-objects": major
+---
+
+ADR-0090 P3 — security-domain publish linter (D7) and delegated administration (D12).
+
+**D7 — `validateSecurityPosture` (@objectstack/lint), wired into `os compile` (errors gate the build) and `os lint`.** Rules, each with a failing fixture: `security-owd-unset` (custom object with no `sharingModel` — the objectui#2348 leave_request shape), `security-owd-alias` (retired D4 alias values, with fix-it), `security-external-wider-than-internal` (D11 `external ≤ internal`), `security-wildcard-vama` (`'*'` + View/Modify All outside the platform admin set, ADR-0066), `security-anchor-high-privilege` (an `isDefault`/everyone-suggested set carrying anchor-forbidden bits), `security-role-word` (D3 vocabulary freeze in security identifiers/labels; ARIA/page roles exempt), and advisory `security-private-no-readscope`.
+
+**D12 — delegated administration (@objectstack/plugin-security `DelegatedAdminGate`).** `PermissionSetSchema.adminScope` (new in spec, persisted as `sys_permission_set.admin_scope`) declares WHERE (a `sys_business_unit` subtree), WHAT (`manageAssignments` / `manageBindings` / `authorEnvironmentSets`), and WHICH sets a delegate may hand out (`assignablePermissionSets` allowlist). Writes to `sys_user_position`, `sys_position_permission_set`, `sys_user_permission_set`, and `sys_permission_set` are now governed: tenant-level admins (ADR-0066 superuser wildcard) pass through; delegates need a covering scope — inside their subtree, allowlisted sets only (to others AND themselves), single-row writes, `granted_by` audit-stamped; everyone else (including holders of plain CRUD on RBAC tables) is denied. Granting or authoring a set that itself carries an `adminScope` requires a held scope that STRICTLY contains it. The `everyone`/`guest` anchors stay tenant-level only, and direct position assignments to an anchor are rejected for every caller.
+
+**ADR-0090 Addendum — assignment-level BU anchor.** `sys_user_position.business_unit_id` lands with its three consumers scoped: D12 delegation boundary (enforced here), audit fact, and the depth-anchor contract for enterprise `hierarchy-scope-resolver` implementations (documented on `IHierarchyScopeResolver`).
+
+**D9 tier tightening.** `describeHighPrivilegeBits` moved to `@objectstack/spec/security` (re-exported from plugin-security) alongside new `describeAnchorForbiddenBits`: `guest` bindings now additionally reject edit bits (read-only by default; create stays the case-by-case exception).
+
+**BREAKING (@objectstack/plugin-security):** exports renamed to the ADR-0090 D3 vocabulary — `SysRole`→`SysPosition`, `SysUserRole`→`SysUserPosition`, `SysRolePermissionSet`→`SysPositionPermissionSet` (no aliases, pre-launch one-step rename). `sys_position` row actions/list views renamed (`activate_position`, …), labels relabeled Role→Position. Non-tenant-admin writes to the RBAC link tables without an `adminScope` are now denied (previously any CRUD grant on those tables sufficed).
+
+**BREAKING (@objectstack/platform-objects):** `sys_business_unit_member.role_in_business_unit` → `function_in_business_unit` (D3 reserved-word sweep; values member/lead/deputy unchanged).

docs/design/permission-model.md

@@ -208,8 +208,10 @@ being **structured data**:
 
 1. **A small, closed vocabulary** — 5 concepts, 4 OWD values, no aliases, banned words: the error
    space is shrunk before any checker runs. Strict authoring (rejects, never lenient-parses).
-2. **Publish linter** (security domain): unset OWD, everyone+high-privilege, non-admin superuser
-   wildcards, forbidden vocabulary — each rule traceable to an observed failure class.
+2. **Publish linter** (security domain, landed in P3 as `validateSecurityPosture` in
+   `@objectstack/lint`, gating `os compile`): unset OWD, retired OWD aliases, external dial wider
+   than internal, non-admin superuser wildcards, high-privilege everyone-suggested sets, forbidden
+   vocabulary — each rule traceable to an observed failure class and mirrored by a runtime gate.
 3. **Access-matrix snapshot**: publishes evaluate representative positions × objects and diff
    against the committed matrix; an unchanged matrix auto-passes, a changed one raises a human gate
    showing the *semantic* impact ("grants `sales_rep` (~1,200 users) org-wide read on
@@ -285,6 +287,26 @@ anything outside the allowlist — **including to themselves** — and can never
 things (the `everyone`/`guest` anchors, security publishes). Headquarters keeps one dashboard:
 the same explain engine answers "who *could have* granted this", not just "who did".
 
+**How it is authored (landed in P3).** An admin scope is a field on an ordinary permission set
+(`adminScope: { businessUnit, includeSubtree, manageAssignments, manageBindings,
+authorEnvironmentSets, assignablePermissionSets[] }`), so it is distributed via positions and
+audited like every other grant. The same set should also carry plain CRUD on the RBAC link
+tables (`sys_user_position`, `sys_position_permission_set`, `sys_user_permission_set`) — the
+scope authorizes *what* may be administered, the CRUD bits let the requests through at all.
+Runtime rules enforced by the `DelegatedAdminGate` (plugin-security):
+
+- assignments a delegate creates must be **anchored** (`sys_user_position.business_unit_id`)
+  inside their subtree, and are `granted_by`-stamped automatically;
+- every set reached by the write — bound to the assigned position, or granted directly — must be
+  in the allowlist; re-composing a position (bindings) requires every current holder to sit
+  inside the subtree;
+- 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);
+- delegates write **single rows by id** only (a broad filter-write cannot be boundary-checked);
+- 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.
+
 Planned next (tracked as follow-up ADRs, not yet in the model): **expiring grants** (contractor
 access that ends on a date, stand-in approvers during vacations, break-glass access that
 auto-revokes), **separation-of-duties rules** ("the person who creates vendors must not also

examples/app-crm/src/objects/account.object.ts

@@ -4,6 +4,11 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
 
 export const Account = ObjectSchema.create({
   name: 'crm_account',
+  // [ADR-0090 D1] Explicit grandfather stamp: record isolation for this demo
+  // object is intentionally org-shared; without this the new secure default
+  // (unset OWD => private) would owner-filter it, and the D7 publish linter
+  // (security-owd-unset) fails the build on an undeclared baseline.
+  sharingModel: 'public_read_write',
   label: 'Account',
   pluralLabel: 'Accounts',
   icon: 'building',

examples/app-crm/src/objects/activity.object.ts

@@ -4,6 +4,11 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
 
 export const Activity = ObjectSchema.create({
   name: 'crm_activity',
+  // [ADR-0090 D1] Explicit grandfather stamp: record isolation for this demo
+  // object is intentionally org-shared; without this the new secure default
+  // (unset OWD => private) would owner-filter it, and the D7 publish linter
+  // (security-owd-unset) fails the build on an undeclared baseline.
+  sharingModel: 'public_read_write',
   label: 'Activity',
   pluralLabel: 'Activities',
   icon: 'calendar-check',

examples/app-crm/src/objects/contact.object.ts

@@ -5,6 +5,11 @@ import { cel } from '@objectstack/spec';
 
 export const Contact = ObjectSchema.create({
   name: 'crm_contact',
+  // [ADR-0090 D1] Explicit grandfather stamp: record isolation for this demo
+  // object is intentionally org-shared; without this the new secure default
+  // (unset OWD => private) would owner-filter it, and the D7 publish linter
+  // (security-owd-unset) fails the build on an undeclared baseline.
+  sharingModel: 'public_read_write',
   label: 'Contact',
   pluralLabel: 'Contacts',
   icon: 'user',

examples/app-crm/src/objects/lead.object.ts

@@ -5,6 +5,11 @@ import { cel, P } from '@objectstack/spec';
 
 export const Lead = ObjectSchema.create({
   name: 'crm_lead',
+  // [ADR-0090 D1] Explicit grandfather stamp: record isolation for this demo
+  // object is intentionally org-shared; without this the new secure default
+  // (unset OWD => private) would owner-filter it, and the D7 publish linter
+  // (security-owd-unset) fails the build on an undeclared baseline.
+  sharingModel: 'public_read_write',
   label: 'Lead',
   pluralLabel: 'Leads',
   icon: 'funnel',

examples/app-crm/src/objects/opportunity-line-item.object.ts

@@ -16,6 +16,9 @@ import { cel } from '@objectstack/spec';
  */
 export const OpportunityLineItem = ObjectSchema.create({
   name: 'crm_opportunity_line_item',
+  // [ADR-0090 D1/D4] Master-detail child: record access follows the parent
+  // opportunity (the D7 publish linter requires the baseline to be declared).
+  sharingModel: 'controlled_by_parent',
   label: 'Line Item',
   pluralLabel: 'Line Items',
   icon: 'list',

examples/app-crm/src/objects/opportunity.object.ts

@@ -5,6 +5,11 @@ import { cel, P } from '@objectstack/spec';
 
 export const Opportunity = ObjectSchema.create({
   name: 'crm_opportunity',
+  // [ADR-0090 D1] Explicit grandfather stamp: record isolation for this demo
+  // object is intentionally org-shared; without this the new secure default
+  // (unset OWD => private) would owner-filter it, and the D7 publish linter
+  // (security-owd-unset) fails the build on an undeclared baseline.
+  sharingModel: 'public_read_write',
   label: 'Opportunity',
   pluralLabel: 'Opportunities',
   icon: 'trending-up',

examples/app-showcase/src/data/objects/semantic-zoo.object.ts

@@ -56,6 +56,10 @@ export const SemanticZoo = ObjectSchema.create({
 
 export const SemanticZooLegacy = ObjectSchema.create({
   name: 'showcase_semantic_zoo_legacy',
+  // [ADR-0090 D1] Explicit grandfather stamp: record isolation for this demo
+  // object is RLS-owned / intentionally public; without this the new secure
+  // default (unset OWD => private) would owner-filter it.
+  sharingModel: 'public_read_write',
   label: 'Semantic Zoo (Legacy)',
   pluralLabel: 'Semantic Zoo Legacies',
   icon: 'flask-round',

examples/app-showcase/src/data/objects/team.object.ts

@@ -28,6 +28,10 @@ export const Team = ObjectSchema.create({
 /** Junction row joining Team ↔ Project (many-to-many). */
 export const ProjectMembership = ObjectSchema.create({
   name: 'showcase_project_membership',
+  // [ADR-0090 D1] Explicit grandfather stamp: record isolation for this demo
+  // object is RLS-owned / intentionally public; without this the new secure
+  // default (unset OWD => private) would owner-filter it.
+  sharingModel: 'public_read_write',
   label: 'Project Membership',
   pluralLabel: 'Project Memberships',
   icon: 'link',
@@ -36,8 +40,10 @@ export const ProjectMembership = ObjectSchema.create({
   fields: {
     team: Field.masterDetail('showcase_team', { label: 'Team', required: true }),
     project: Field.masterDetail('showcase_project', { label: 'Project', required: true }),
-    role: Field.select({
-      label: 'Role',
+    // [ADR-0090 D3] Formerly `role` — reserved word; this is the team's
+    // engagement on the project, not a capability container.
+    engagement: Field.select({
+      label: 'Engagement',
       options: [
         { label: 'Owner', value: 'owner', default: true },
         { label: 'Contributor', value: 'contributor' },