feat(security): ADR-0057 ERP authorization core — scope-depth, business units, seed declared RBAC (#2077)

Dataverse-core / Salesforce-discipline hybrid. Adds the ERP partition + scope-depth
+ hierarchy-rollup core on top of the existing widening layer, and makes the role
system self-owned (decoupled from better-auth membership). Closes #2077.

- D1 scope-depth grants on ObjectPermission (own/unit/unit_and_below/org): security
  stashes the grant's depth, sharing widens the owner-match (owner IN unit-set) and
  still OR's in shares. No RLS-compiler change. Proof: showcase-scope-depth (4).
- D2 rename sys_department → sys_business_unit (pre-launch clean rename, no aliases):
  object + member table + BusinessUnitGraphService + recipient enum + fields + i18n.
- D3 BU rollup via BusinessUnitGraphService subtree expansion.
- D4 sys_user_role (platform-owned RBAC assignment); resolve-execution-context merges
  it with sys_member.role.
- D5 re-home role_and_subordinates onto the working BU subtree. Proof:
  showcase-bu-hierarchy-sharing (4).
- D6 seed stack-declared roles + sharingRules at boot (bootstrapDeclaredRoles /
  bootstrapDeclaredSharingRules; AppPlugin surfaces security metadata; seeders read
  the engine registry; field-equality CEL→criteria_json; owner/group experimental).
  Proof: showcase-declarative-rbac-seeding (4). Closes #2077.
- D8 authz-conformance matrix rows for the new primitives.
- Fix latent over-grant: engine.find({filter}) was silently ignored (driver reads
  `where`); normalize filter→where in the engine. objectql 670 green.

Full dogfood 21 files / 122 tests; objectql 670 / runtime 395 / security 112 /
sharing 63 / approvals 90 — all green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

docs/adr/0057-erp-authorization-core-business-units-and-scope-depth.md

@@ -44,6 +44,14 @@ export const AUTHZ_CONFORMANCE: AuthzPrimitive[] = [
   { id: 'default-profile', summary: 'app-declared default profile (isDefault)', state: 'enforced',
     enforcement: 'plugin-security/security-plugin.ts fallback resolution', proof: 'showcase-default-profile.dogfood.test.ts' },
 
+  // ── ADR-0057 — ERP authorization core (enforced + e2e proven) ──────────
+  { id: 'scope-depth', summary: 'permission-grant access DEPTH (own/unit/unit_and_below/org)', state: 'enforced',
+    enforcement: 'plugin-security getEffectiveScope (stash) + plugin-sharing resolveOwnerScopeIds (owner IN unit-set) — ADR-0057 D1', proof: 'showcase-scope-depth.dogfood.test.ts' },
+  { id: 'declarative-rbac-seeding', summary: 'stack-declared roles + sharingRules seeded at boot (#2077)', state: 'enforced',
+    enforcement: 'plugin-security bootstrapDeclaredRoles + plugin-sharing bootstrapDeclaredSharingRules — ADR-0057 D6', proof: 'showcase-declarative-rbac-seeding.dogfood.test.ts' },
+  { id: 'rbac-role-assignment', summary: 'platform-owned RBAC assignment (sys_user_role, decoupled from better-auth membership)', state: 'enforced',
+    enforcement: 'runtime/resolve-execution-context.ts reads sys_user_role (union sys_member.role) — ADR-0057 D4' },
+
   // ── Enforced (unit-proven; e2e proof is a follow-on) ───────────────────
   { id: 'object-crud', summary: 'object CRUD permissions', state: 'enforced',
     enforcement: 'plugin-security/security-plugin.ts checkObjectPermission (fail-closed 403)' },
@@ -54,9 +62,9 @@ export const AUTHZ_CONFORMANCE: AuthzPrimitive[] = [
   { id: 'record-share', summary: 'manual record shares (sys_record_share)', state: 'enforced',
     enforcement: 'plugin-sharing/sharing-service.ts buildReadFilter/canEdit' },
   { id: 'sharing-rules', summary: 'criteria/owner sharing rules', state: 'enforced',
-    enforcement: 'plugin-sharing/sharing-rule-service.ts (materialized into sys_record_share)' },
-  { id: 'role-hierarchy', summary: 'role-hierarchy widening (role_and_subordinates)', state: 'enforced',
-    enforcement: 'plugin-sharing/role-graph.ts RoleGraphService (sys_role.parent)' },
+    enforcement: 'plugin-sharing/sharing-rule-service.ts (materialized into sys_record_share)', proof: 'showcase-bu-hierarchy-sharing.dogfood.test.ts' },
+  { id: 'hierarchy-widening', summary: 'hierarchy widening — a unit + its subordinate units gain access', state: 'enforced',
+    enforcement: 'plugin-sharing/business-unit-graph.ts BusinessUnitGraphService subtree (business_unit recipient) — ADR-0057 D5 re-homed off the never-existent sys_role.parent', proof: 'showcase-bu-hierarchy-sharing.dogfood.test.ts' },
   { id: 'rls-compiler-fail-closed', summary: 'uncompilable RLS predicate is surfaced/denied, not dropped', state: 'enforced',
     enforcement: 'plugin-security/rls-compiler.ts isSupportedRlsExpression + warn' },
   { id: 'system-permissions', summary: 'systemPermissions / tab-app gating', state: 'enforced',

packages/dogfood/test/authz-conformance.matrix.ts

@@ -0,0 +1,103 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// ADR-0057 D6 (reconciles ADR-0056 D6 / #2077 demo) — a sharing rule whose
+// recipient is a BUSINESS UNIT widens access DOWN the hierarchy: the unit's
+// members AND every subordinate (descendant) unit's members gain access via the
+// `sys_business_unit` tree (BFS). This is the honest re-homing of the broken
+// `role_and_subordinates` (sys_role.parent never existed) onto the working
+// business-unit tree. Proven end-to-end: the rule materialises sys_record_share
+// rows; a non-owner in the unit subtree can then read a private record.
+//
+// @proof: showcase-bu-hierarchy-sharing
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import showcaseStack from '@objectstack/example-showcase';
+import { bootStack, type VerifyStack } from '@objectstack/verify';
+
+const OBJ = '/data/showcase_private_note';
+const SYS = { isSystem: true } as const;
+
+describe('showcase: business-unit hierarchy sharing rule (ADR-0057 D6 / #2077)', () => {
+  let stack: VerifyStack;
+  let ql: any;
+  let ownerTok: string, mgrTok: string, contribTok: string, outsiderTok: string;
+  let noteId: string;
+
+  beforeAll(async () => {
+    stack = await bootStack(showcaseStack);
+    await stack.signIn();
+    ownerTok = await stack.signUp('bu-owner@verify.test');
+    mgrTok = await stack.signUp('bu-mgr@verify.test');       // parent BU
+    contribTok = await stack.signUp('bu-contrib@verify.test'); // child BU
+    outsiderTok = await stack.signUp('bu-outsider@verify.test'); // no BU
+
+    ql = await stack.kernel.getServiceAsync('objectql');
+    const sys = (o: string, d: any) => ql.insert(o, d, { context: SYS });
+    const uid = async (e: string) => (await ql.findOne('sys_user', { where: { email: e }, context: SYS }))?.id;
+    const mgrId = await uid('bu-mgr@verify.test');
+    const contribId = await uid('bu-contrib@verify.test');
+
+    let org = await ql.findOne('sys_organization', { where: {}, context: SYS }).catch(() => null);
+    const orgId = org?.id ?? 'org_bu';
+    if (!org) await sys('sys_organization', { id: orgId, name: 'BU Org', slug: 'bu_org' }).catch(() => {});
+
+    // parent ⊃ child
+    await sys('sys_business_unit', { id: 'bu_h_parent', name: 'Region', kind: 'division', organization_id: orgId, active: true });
+    await sys('sys_business_unit', { id: 'bu_h_child', name: 'Team', kind: 'department', parent_business_unit_id: 'bu_h_parent', organization_id: orgId, active: true });
+    await sys('sys_business_unit_member', { id: 'bm_mgr', business_unit_id: 'bu_h_parent', user_id: mgrId });
+    await sys('sys_business_unit_member', { id: 'bm_contrib', business_unit_id: 'bu_h_child', user_id: contribId });
+
+    // owner creates a PRIVATE note — only the owner can see it by default.
+    const c = await stack.apiAs(ownerTok, 'POST', OBJ, { title: 'BU-shared note' });
+    expect(c.status, 'owner creates note').toBeLessThan(300);
+    noteId = (await c.json())?.id ?? (await c.json())?.record?.id;
+    if (!noteId) {
+      const row = await ql.findOne('showcase_private_note', { where: { title: 'BU-shared note' }, context: SYS });
+      noteId = row?.id;
+    }
+
+    // Define a sharing rule: share ALL private notes with the PARENT business
+    // unit (and, via the tree, its descendants). Recipient = business_unit.
+    const rules: any = stack.kernel.getService('sharingRules');
+    await rules.defineRule({
+      name: 'share_notes_with_region',
+      label: 'Notes → Region (BU subtree)',
+      object: 'showcase_private_note',
+      recipientType: 'business_unit',
+      recipientId: 'bu_h_parent',
+      accessLevel: 'read',
+      active: true,
+    }, SYS);
+    // Materialise grants for existing records.
+    await rules.evaluateRule('share_notes_with_region', SYS);
+  }, 90_000);
+
+  afterAll(async () => { await stack?.stop(); });
+
+  it('materialises sys_record_share rows for the BU subtree', async () => {
+    const shares = await ql.find('sys_record_share', {
+      where: { object_name: 'showcase_private_note', record_id: noteId, source: 'rule' },
+      context: SYS,
+    });
+    const recipients = (shares ?? []).map((s: any) => s.recipient_id);
+    const mgrId = (await ql.findOne('sys_user', { where: { email: 'bu-mgr@verify.test' }, context: SYS }))?.id;
+    const contribId = (await ql.findOne('sys_user', { where: { email: 'bu-contrib@verify.test' }, context: SYS }))?.id;
+    expect(recipients, 'parent-BU member granted').toContain(mgrId);
+    expect(recipients, 'child-BU (subordinate) member granted via hierarchy').toContain(contribId);
+  });
+
+  it('a manager in the unit can READ the owner\'s private note', async () => {
+    const r = await stack.apiAs(mgrTok, 'GET', `${OBJ}/${noteId}`);
+    expect(r.status, 'manager reads via BU share').toBe(200);
+  });
+
+  it('a contributor in a SUBORDINATE unit can READ it too (hierarchy widening)', async () => {
+    const r = await stack.apiAs(contribTok, 'GET', `${OBJ}/${noteId}`);
+    expect(r.status, 'subordinate-unit member reads via hierarchy widening').toBe(200);
+  });
+
+  it('an outsider (no business unit) is NOT granted access', async () => {
+    const r = await stack.apiAs(outsiderTok, 'GET', `${OBJ}/${noteId}`);
+    expect(r.status, 'outsider stays denied').not.toBe(200);
+  });
+});

packages/dogfood/test/showcase-bu-hierarchy-sharing.dogfood.test.ts

@@ -0,0 +1,56 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// ADR-0057 D6 / #2077 — stack-declared `roles` + `sharingRules` are seeded into
+// sys_role / sys_sharing_rule at boot, so they stop being decorative. The issue
+// reported booting the showcase yielded sys_role count = 0 and sys_sharing_rule
+// count = 0. This proves the opposite, plus the spec→runtime translation.
+//
+// @proof: showcase-declarative-rbac-seeding
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import showcaseStack from '@objectstack/example-showcase';
+import { bootStack, type VerifyStack } from '@objectstack/verify';
+
+describe('showcase: declarative RBAC seeding (ADR-0057 D6 / #2077)', () => {
+  let stack: VerifyStack;
+  let ql: any;
+
+  beforeAll(async () => {
+    stack = await bootStack(showcaseStack);
+    await stack.signIn();
+    ql = await stack.kernel.getServiceAsync('objectql');
+  }, 60_000);
+  afterAll(async () => { await stack?.stop(); });
+
+  it('declared roles land in sys_role (was count = 0)', async () => {
+    const roles = await ql.find('sys_role', { where: {}, context: { isSystem: true } });
+    const names = (roles ?? []).map((r: any) => r.name);
+    expect(names, 'showcase declares contributor/manager/exec').toEqual(
+      expect.arrayContaining(['contributor', 'manager', 'exec']),
+    );
+  });
+
+  it('declared criteria sharing rule lands in sys_sharing_rule, CEL→criteria_json translated', async () => {
+    const rules = await ql.find('sys_sharing_rule', { where: {}, context: { isSystem: true } });
+    const red = (rules ?? []).find((r: any) => r.name === 'share_red_projects_with_execs');
+    expect(red, 'criteria rule seeded (was count = 0)').toBeTruthy();
+    expect(red.object_name).toBe('showcase_project');
+    expect(red.recipient_type).toBe('role');
+    expect(red.recipient_id).toBe('exec');
+    // condition "record.health == 'red'" → JSON FilterCondition { health: 'red' }
+    const criteria = JSON.parse(red.criteria_json);
+    expect(criteria).toEqual({ health: 'red' });
+  });
+
+  it('owner-based rule is NOT seeded as a match-all (experimental, ADR-0049 honesty)', async () => {
+    const rules = await ql.find('sys_sharing_rule', { where: {}, context: { isSystem: true } });
+    const owner = (rules ?? []).find((r: any) => r.name === 'share_contributor_tasks_with_manager');
+    // owner-type has no static criteria_json equivalent → skipped, not seeded over-broadly.
+    expect(owner, 'owner-based rule must not silently over-share').toBeFalsy();
+  });
+
+  it('re-seed is idempotent (no duplicate rows on a second boot)', async () => {
+    const roles = await ql.find('sys_role', { where: { name: 'manager' }, context: { isSystem: true } });
+    expect((roles ?? []).length, 'exactly one manager role').toBe(1);
+  });
+});

packages/dogfood/test/showcase-declarative-rbac-seeding.dogfood.test.ts

@@ -0,0 +1,121 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// ADR-0057 D1 — scope-depth read grants on the REAL showcase app.
+// A grant's `readScope` widens the owner-match for an owner-scoped (`private`)
+// object: `unit` → records owned by my business-unit co-members; `unit_and_below`
+// → my BU plus all descendant BUs (BFS). Sharing still widens on top; cross-BU
+// stays isolated. ('own' depth is already proven by showcase-private-owd.)
+//
+// @proof: showcase-scope-depth
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import showcaseStack from '@objectstack/example-showcase';
+import { bootStack, type VerifyStack } from '@objectstack/verify';
+import { SecurityPlugin, securityDefaultPermissionSets } from '@objectstack/plugin-security';
+import { PermissionSetSchema } from '@objectstack/spec/security';
+
+const OBJ = '/data/showcase_private_note';
+const WHO = ['alice', 'bob', 'carol', 'dave'] as const;
+type Who = (typeof WHO)[number];
+
+function scopeProfile(scope: 'unit' | 'unit_and_below') {
+  return PermissionSetSchema.parse({
+    name: `scope_${scope}_profile`,
+    label: `Scope ${scope}`,
+    isProfile: true,
+    isDefault: true,
+    objects: {
+      showcase_private_note: {
+        allowRead: true, allowCreate: true, allowEdit: true,
+        readScope: scope, writeScope: scope,
+      },
+    },
+  });
+}
+
+interface World { stack: VerifyStack; tokens: Record<Who, string>; }
+
+// Build a BU world: bu_parent ⊃ bu_child (sibling bu_other is separate).
+// alice+carol ∈ bu_parent, bob ∈ bu_child, dave ∈ bu_other. Each owns one note.
+async function bootScopeWorld(scope: 'unit' | 'unit_and_below'): Promise<World> {
+  const stack = await bootStack(showcaseStack, {
+    security: new SecurityPlugin({
+      defaultPermissionSets: [...securityDefaultPermissionSets, scopeProfile(scope)],
+    }),
+  });
+  await stack.signIn();
+  const tokens = {} as Record<Who, string>;
+  for (const who of WHO) tokens[who] = await stack.signUp(`scope-${who}-${scope}@verify.test`);
+
+  const ql: any = await stack.kernel.getServiceAsync('objectql');
+  const sys = (o: string, d: any) => ql.insert(o, d, { context: { isSystem: true } });
+  const uid = async (who: Who) =>
+    (await ql.findOne('sys_user', { where: { email: `scope-${who}-${scope}@verify.test` }, context: { isSystem: true } }))?.id;
+  const id = {} as Record<Who, string>;
+  for (const who of WHO) id[who] = await uid(who);
+
+  // org (BU.organization_id is required) — reuse any existing, else create one.
+  let org = await ql.findOne('sys_organization', { where: {}, context: { isSystem: true } }).catch(() => null);
+  let orgId = org?.id;
+  if (!orgId) { orgId = 'org_scope'; await sys('sys_organization', { id: orgId, name: 'Scope Org', slug: `scope_${scope}` }).catch(() => {}); }
+
+  const p = `${scope}`;
+  await sys('sys_business_unit', { id: `bu_parent_${p}`, name: 'Parent', kind: 'division', organization_id: orgId, active: true });
+  await sys('sys_business_unit', { id: `bu_child_${p}`, name: 'Child', kind: 'department', parent_business_unit_id: `bu_parent_${p}`, organization_id: orgId, active: true });
+  await sys('sys_business_unit', { id: `bu_other_${p}`, name: 'Other', kind: 'division', organization_id: orgId, active: true });
+  await sys('sys_business_unit_member', { id: `m_a_${p}`, business_unit_id: `bu_parent_${p}`, user_id: id.alice });
+  await sys('sys_business_unit_member', { id: `m_c_${p}`, business_unit_id: `bu_parent_${p}`, user_id: id.carol });
+  await sys('sys_business_unit_member', { id: `m_b_${p}`, business_unit_id: `bu_child_${p}`, user_id: id.bob });
+  await sys('sys_business_unit_member', { id: `m_d_${p}`, business_unit_id: `bu_other_${p}`, user_id: id.dave });
+
+  for (const who of WHO) {
+    const r = await stack.apiAs(tokens[who], 'POST', OBJ, { title: `${who} note` });
+    expect(r.status, `${who} creates note`).toBeLessThan(300);
+  }
+  return { stack, tokens };
+}
+
+async function titles(stack: VerifyStack, token: string): Promise<string[]> {
+  const r = await stack.apiAs(token, 'GET', OBJ);
+  expect(r.status).toBe(200);
+  const b: any = await r.json();
+  return (b.records ?? b.data ?? b ?? []).map((x: any) => x.title).filter(Boolean);
+}
+
+describe('showcase: scope-depth read — `unit` (ADR-0057 D1)', () => {
+  let world: World;
+  beforeAll(async () => { world = await bootScopeWorld('unit'); }, 120_000);
+  afterAll(async () => { await world?.stack?.stop(); });
+
+  it('widens to BU co-members, NOT child or sibling BUs', async () => {
+    const t = await titles(world.stack, world.tokens.alice);
+    expect(t).toContain('alice note');   // own
+    expect(t).toContain('carol note');   // same BU (widened)
+    expect(t).not.toContain('bob note');  // child BU — `unit` does not descend
+    expect(t).not.toContain('dave note'); // sibling BU — isolated
+  });
+
+  it('a lone child member sees only their own', async () => {
+    const t = await titles(world.stack, world.tokens.bob);
+    expect(t.sort()).toEqual(['bob note']);
+  });
+});
+
+describe('showcase: scope-depth read — `unit_and_below` (ADR-0057 D1)', () => {
+  let world: World;
+  beforeAll(async () => { world = await bootScopeWorld('unit_and_below'); }, 120_000);
+  afterAll(async () => { await world?.stack?.stop(); });
+
+  it('descends into child BUs (BFS subtree)', async () => {
+    const t = await titles(world.stack, world.tokens.alice);
+    expect(t).toContain('alice note');   // own
+    expect(t).toContain('carol note');   // same BU
+    expect(t).toContain('bob note');     // child BU — subtree descent
+    expect(t).not.toContain('dave note'); // sibling root — still isolated
+  });
+
+  it('the child member does NOT roll up into the parent', async () => {
+    const t = await titles(world.stack, world.tokens.bob);
+    expect(t.sort()).toEqual(['bob note']); // child has no descendants; no upward visibility
+  });
+});

packages/dogfood/test/showcase-scope-depth.dogfood.test.ts

@@ -1866,6 +1866,15 @@ export class ObjectQL implements IDataEngine {
     const ast: QueryAST = { object, ...query };
     // Remove context from the AST — it's not a driver concern
     delete (ast as any).context;
+    // Normalize the `filter` alias → `where`. The DataEngine contract
+    // (`spec/data/data-engine.zod.ts`) exposes both, but the driver AST only
+    // understands `where`; an internal caller passing `{ filter }` would
+    // otherwise match ALL rows (silent over-grant — surfaced by ADR-0057's
+    // sharing/graph read path). `where` wins when both are present.
+    if ((ast as any).filter != null && ast.where == null) {
+      ast.where = (ast as any).filter;
+    }
+    delete (ast as any).filter;
     // Normalize OData `top` alias → standard `limit`
     if ((ast as any).top != null && ast.limit == null) {
       ast.limit = (ast as any).top;

packages/objectql/src/engine.ts

@@ -37,8 +37,8 @@ import {
   SysInvitation,
   SysTeam,
   SysTeamMember,
-  SysDepartment,
-  SysDepartmentMember,
+  SysBusinessUnit,
+  SysBusinessUnitMember,
   SysApiKey,
   SysTwoFactor,
   SysDeviceCode,
@@ -130,8 +130,8 @@ export default defineStack({
     SysInvitation,
     SysTeam,
     SysTeamMember,
-    SysDepartment,
-    SysDepartmentMember,
+    SysBusinessUnit,
+    SysBusinessUnitMember,
     SysApiKey,
     SysTwoFactor,
     SysDeviceCode,

packages/platform-objects/scripts/i18n-extract.config.ts

@@ -47,7 +47,7 @@ export const SETUP_NAV_CONTRIBUTIONS: NavigationContribution[] = [
     priority: BASE_PRIORITY,
     items: [
       { id: 'nav_users', type: 'object', label: 'Users', objectName: 'sys_user', icon: 'user' },
-      { id: 'nav_departments', type: 'object', label: 'Departments', objectName: 'sys_department', icon: 'building', requiresObject: 'sys_department' },
+      { id: 'nav_departments', type: 'object', label: 'Departments', objectName: 'sys_business_unit', icon: 'building', requiresObject: 'sys_business_unit' },
       { id: 'nav_teams', type: 'object', label: 'Teams', objectName: 'sys_team', icon: 'users-round' },
       { id: 'nav_organizations', type: 'object', label: 'Organizations', objectName: 'sys_organization', icon: 'building-2' },
       { id: 'nav_invitations', type: 'object', label: 'Invitations', objectName: 'sys_invitation', icon: 'mail' },