feat(authz): ADR-0066 D1 — capability registry (sys_capability records) (#2239)

Promotes authorization capabilities from bare strings to first-class records
(layer 1 of the ADR-0066 three-way separation). New `sys_capability` system
object (name/label/description/scope[platform|org]/managed_by[platform|package|
admin]/active), registered + given a Setup → Access Control nav entry.

Back-compat: bootstrapSystemCapabilities seeds the curated platform capabilities
(manage_users, manage_org_users, manage_metadata, manage_platform_settings,
setup.access, studio.access) PLUS any capability referenced by the default
grants' systemPermissions — idempotently, on kernel:ready. systemPermissions[]
and requiredPermissions[] keep referencing capabilities BY NAME (the strings ARE
the references), so nothing migrates; the registry is the catalog/definition.

Named `sys_capability` (not the ADR's loose `sys_permission`) to avoid collision
with `sys_permission_set` and match ADR-0066's "capability" vocabulary.

Tests: +6 (object shape + seeding idempotency/derivation). plugin-security full
DTS + 139 tests green.

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

Author: 3 people

packages/plugins/plugin-security/src/bootstrap-system-capabilities.test.ts

@@ -0,0 +1,62 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { bootstrapSystemCapabilities, KNOWN_CAPABILITIES } from './bootstrap-system-capabilities.js';
+
+/** Minimal in-memory ql for sys_capability seeding. */
+function makeQl() {
+  const rows: any[] = [];
+  return {
+    rows,
+    async find(object: string, q: any) {
+      if (object !== 'sys_capability') return [];
+      const where = q?.where ?? {};
+      return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+    },
+    async insert(object: string, data: any) {
+      if (object !== 'sys_capability') return null;
+      rows.push({ ...data });
+      return { id: data.id };
+    },
+    async update(object: string, data: any) {
+      if (object !== 'sys_capability') return;
+      const r = rows.find((x) => x.id === data.id);
+      if (r) Object.assign(r, data);
+    },
+  };
+}
+
+describe('bootstrapSystemCapabilities (ADR-0066 D1 back-compat seed)', () => {
+  it('seeds the curated platform capabilities as records (idempotent)', async () => {
+    const ql = makeQl();
+    const r1 = await bootstrapSystemCapabilities(ql, []);
+    expect(r1.seeded).toBe(KNOWN_CAPABILITIES.length);
+    // every known capability is now a row with managed_by=platform + active
+    for (const cap of KNOWN_CAPABILITIES) {
+      const row = ql.rows.find((x) => x.name === cap.name);
+      expect(row).toBeDefined();
+      expect(row.managed_by).toBe('platform');
+      expect(row.active).toBe(true);
+      expect(row.scope).toBe(cap.scope);
+    }
+    // re-run → no new inserts (idempotent)
+    const r2 = await bootstrapSystemCapabilities(ql, []);
+    expect(r2.seeded).toBe(0);
+    expect(ql.rows.length).toBe(KNOWN_CAPABILITIES.length);
+  });
+
+  it('derives extra capabilities referenced by permission sets', async () => {
+    const ql = makeQl();
+    await bootstrapSystemCapabilities(ql, [{ systemPermissions: ['manage_users', 'export_data', 'approve_invoice'] }]);
+    expect(ql.rows.find((x) => x.name === 'export_data')).toBeDefined();
+    expect(ql.rows.find((x) => x.name === 'approve_invoice')).toBeDefined();
+    // org-scoped known capability keeps its scope
+    expect(ql.rows.find((x) => x.name === 'manage_org_users')?.scope).toBe('org');
+  });
+
+  it('marks manage_org_users as org-scoped and the rest platform', () => {
+    const org = KNOWN_CAPABILITIES.find((c) => c.name === 'manage_org_users');
+    expect(org?.scope).toBe('org');
+    expect(KNOWN_CAPABILITIES.filter((c) => c.scope === 'platform').length).toBeGreaterThanOrEqual(5);
+  });
+});

packages/plugins/plugin-security/src/bootstrap-system-capabilities.ts

@@ -0,0 +1,120 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * bootstrapSystemCapabilities — back-compat seed the capability registry
+ * (ADR-0066 D1).
+ *
+ * Promotes the platform's authorization capabilities from bare strings to
+ * first-class `sys_capability` records. Idempotently upserts (by `name`):
+ *   1. a CURATED set of well-known platform capabilities (label/description/
+ *      scope), and
+ *   2. any capability referenced by the seeded permission sets'
+ *      `systemPermissions[]` that isn't in the curated set (derived defaults),
+ * so every string a default grant references resolves to a definition record
+ * while existing string references keep working unchanged (no migration).
+ *
+ * Pre-launch posture: upsert only — never prune (admins may add their own
+ * capabilities in Setup; package-declared capabilities arrive via their own
+ * seeding). Platform-seeded rows are `managed_by: 'platform'` so they are not
+ * presented as admin-deletable. Runs on `kernel:ready` alongside the other
+ * security bootstraps.
+ */
+
+const SYSTEM_CTX = { isSystem: true };
+
+function genId(prefix: string): string {
+  const rand = Math.random().toString(36).slice(2, 10);
+  const ts = Date.now().toString(36);
+  return `${prefix}_${ts}${rand}`;
+}
+
+async function tryFind(ql: any, object: string, where: any, limit = 1): Promise<any[]> {
+  try {
+    const rows = await ql.find(object, { where, limit }, { context: SYSTEM_CTX });
+    return Array.isArray(rows) ? rows : [];
+  } catch { return []; }
+}
+async function tryInsert(ql: any, object: string, data: any): Promise<any | null> {
+  try { return await ql.insert(object, data, { context: SYSTEM_CTX }); } catch { return null; }
+}
+async function tryUpdate(ql: any, object: string, data: any): Promise<boolean> {
+  try { await ql.update(object, data, { context: SYSTEM_CTX }); return true; } catch { return false; }
+}
+
+interface CapabilityDef {
+  name: string;
+  label: string;
+  description: string;
+  scope: 'platform' | 'org';
+}
+
+/**
+ * Well-known platform capabilities. Exported so tests + tooling can assert the
+ * back-compat set. `managed_by` is always `'platform'` for these.
+ */
+export const KNOWN_CAPABILITIES: readonly CapabilityDef[] = [
+  { name: 'manage_users', label: 'Manage Users', description: 'Create, edit, and deactivate users across the platform.', scope: 'platform' },
+  { name: 'manage_org_users', label: 'Manage Organization Users', description: 'Manage members within the caller’s organization.', scope: 'org' },
+  { name: 'manage_metadata', label: 'Manage Metadata', description: 'Author and publish object/view/flow and other metadata.', scope: 'platform' },
+  { name: 'manage_platform_settings', label: 'Manage Platform Settings', description: 'Configure global platform settings (mail, storage, AI, licensing, …) and platform-only Setup pages.', scope: 'platform' },
+  { name: 'setup.access', label: 'Setup Access', description: 'Enter the Setup app shell.', scope: 'platform' },
+  { name: 'studio.access', label: 'Studio Access', description: 'Enter the Studio metadata-design surfaces.', scope: 'platform' },
+];
+
+function humanize(name: string): string {
+  return name
+    .replace(/[._]/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+interface SeedOptions {
+  logger?: { info?: (m: string, meta?: Record<string, any>) => void; warn?: (m: string, meta?: Record<string, any>) => void };
+}
+
+export async function bootstrapSystemCapabilities(
+  ql: any,
+  permissionSets: Array<{ systemPermissions?: string[] }> = [],
+  options: SeedOptions = {},
+): Promise<{ seeded: number; updated: number; total: number }> {
+  if (!ql || typeof ql.find !== 'function' || typeof ql.insert !== 'function') {
+    return { seeded: 0, updated: 0, total: 0 };
+  }
+
+  // Build the full definition set: curated first, then any extra capability
+  // string referenced by the seeded permission sets (derived defaults).
+  const byName = new Map<string, CapabilityDef>();
+  for (const c of KNOWN_CAPABILITIES) byName.set(c.name, c);
+  for (const ps of permissionSets) {
+    for (const cap of ps?.systemPermissions ?? []) {
+      if (typeof cap === 'string' && cap && !byName.has(cap)) {
+        byName.set(cap, { name: cap, label: humanize(cap), description: `Capability ${cap}.`, scope: 'platform' });
+      }
+    }
+  }
+
+  let seeded = 0;
+  let updated = 0;
+  for (const def of byName.values()) {
+    const existing = await tryFind(ql, 'sys_capability', { name: def.name }, 1);
+    if (existing[0]?.id) {
+      // Keep label/description/scope fresh, but do NOT clobber admin edits to
+      // managed_by/active — only platform-owned fields are reconciled.
+      if (await tryUpdate(ql, 'sys_capability', { id: existing[0].id, label: def.label, description: def.description, scope: def.scope })) {
+        updated += 1;
+      }
+    } else {
+      const created = await tryInsert(ql, 'sys_capability', {
+        id: genId('cap'),
+        name: def.name,
+        label: def.label,
+        description: def.description,
+        scope: def.scope,
+        managed_by: 'platform',
+        active: true,
+      });
+      if (created) seeded += 1;
+    }
+  }
+  options.logger?.info?.('[security] system capabilities seeded into sys_capability (ADR-0066 D1)', { seeded, updated, total: byName.size });
+  return { seeded, updated, total: byName.size };
+}

packages/plugins/plugin-security/src/manifest.ts

@@ -11,6 +11,7 @@
 import {
   SysPermissionSet,
   SysRole,
+  SysCapability,
   SysUserPermissionSet,
   SysRolePermissionSet,
   SysUserRole,
@@ -23,6 +24,7 @@ export const SECURITY_PLUGIN_VERSION = '1.0.0';
 /** Security objects owned by plugin-security. */
 export const securityObjects = [
   SysRole,
+  SysCapability,
   SysPermissionSet,
   SysUserPermissionSet,
   SysRolePermissionSet,

packages/plugins/plugin-security/src/objects/index.ts

@@ -10,6 +10,7 @@
  */
 
 export { SysRole } from './sys-role.object.js';
+export { SysCapability } from './sys-capability.object.js';
 export { SysPermissionSet } from './sys-permission-set.object.js';
 export { SysUserPermissionSet } from './sys-user-permission-set.object.js';
 export { SysRolePermissionSet } from './sys-role-permission-set.object.js';

packages/plugins/plugin-security/src/objects/rbac-objects.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
-import { SysRole, SysPermissionSet, defaultPermissionSets } from './index.js';
+import { SysRole, SysPermissionSet, SysCapability, defaultPermissionSets } from './index.js';
 
 /**
  * RBAC object + default-permission-set assertions. Moved here with the objects
@@ -119,3 +119,30 @@ describe('RBAC object canonical names + row actions', () => {
     expect(names).toEqual(['activate_permission_set', 'clone_permission_set', 'deactivate_permission_set']);
   });
 });
+
+
+describe('sys_capability — ADR-0066 D1 capability registry', () => {
+  it('is a system config object with the canonical name', () => {
+    expect(SysCapability.name).toBe('sys_capability');
+    expect(SysCapability.isSystem).toBe(true);
+    expect(SysCapability.managedBy).toBe('config');
+  });
+
+  it('declares name/label/scope/managed_by fields', () => {
+    const f: any = SysCapability.fields;
+    expect(f.name).toBeDefined();
+    expect(f.label).toBeDefined();
+    expect(f.scope).toBeDefined();
+    expect(f.managed_by).toBeDefined();
+    // scope + managed_by are constrained selects
+    const scopeOpts = (f.scope.options ?? []).map((o: any) => o.value).sort();
+    expect(scopeOpts).toEqual(['org', 'platform']);
+    const mbOpts = (f.managed_by.options ?? []).map((o: any) => o.value).sort();
+    expect(mbOpts).toEqual(['admin', 'package', 'platform']);
+  });
+
+  it('enforces a unique index on name', () => {
+    const nameIdx = (SysCapability.indexes ?? []).find((i: any) => Array.isArray(i.fields) && i.fields.includes('name'));
+    expect(nameIdx?.unique).toBe(true);
+  });
+});