feat(plugin-security): ADR-0066 D2/D3 — enforce private posture, requiredPermissions, posture-gated RLS bypass

- D2 CRUD: a `private` object is not covered by a non-super-user '*' wildcard
  grant (resolveObjectPermission); access needs an explicit per-object grant OR
  the View/Modify All Data super-user wildcard. Explicit grants always honored.
- D3 capability AND-gate: object `requiredPermissions` checked before the CRUD
  grant (caller's systemPermissions union); missing capability → deny.
- ① posture-gated super-user RLS bypass: on a private/platform-global object,
  viewAllRecords bypasses read RLS and modifyAllRecords bypasses write RLS
  (incl. pre-image + post-image check) — so a platform admin who is also an org
  admin sees all rows, while the bypass never leaks cross-tenant data on
  ordinary tenant business objects.
- New getObjectSecurityMeta cache (private/tenancy/requiredPermissions),
  invalidated on metadata change. Evaluator: getSystemPermissions,
  hasSuperuserRead/WriteBypass; checkObjectPermission/getEffectiveScope take an
  isPrivate option (backward-compatible).
- 10 new tests (evaluator units + full-middleware integration). Full DTS green.

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

Author: os-zhuang

packages/plugins/plugin-security/src/permission-evaluator.ts

@@ -26,6 +26,30 @@ const OPERATION_TO_PERMISSION: Record<string, keyof ObjectPermission> = {
  */
 const DESTRUCTIVE_OPERATIONS = new Set<string>(['transfer', 'restore', 'purge']);
 
+/**
+ * [ADR-0066 D2] Resolve the object permission a permission set contributes for
+ * `objectName`, honouring the secure-by-default posture:
+ *
+ *  - an EXPLICIT per-object grant (`ps.objects[objectName]`) always applies;
+ *  - the `'*'` wildcard applies to a `public` object (today's allow-by-default);
+ *  - for a `private` object the `'*'` wildcard applies ONLY when it carries the
+ *    super-user bypass bits (`viewAllRecords`/`modifyAllRecords` — the Salesforce
+ *    "View/Modify All Data" power). A plain `'*': {allowRead:true}` does NOT cover
+ *    a private object; access then requires an explicit per-object grant.
+ */
+function resolveObjectPermission(
+  ps: PermissionSet,
+  objectName: string,
+  isPrivate: boolean,
+): ObjectPermission | undefined {
+  const explicit = ps.objects?.[objectName];
+  if (explicit) return explicit;
+  const wild = ps.objects?.['*'];
+  if (!wild) return undefined;
+  if (!isPrivate) return wild;
+  return wild.viewAllRecords || wild.modifyAllRecords ? wild : undefined;
+}
+
 /**
  * PermissionEvaluator
  * 
@@ -40,7 +64,9 @@ export class PermissionEvaluator {
   checkObjectPermission(
     operation: string,
     objectName: string,
-    permissionSets: PermissionSet[]
+    permissionSets: PermissionSet[],
+    /** [ADR-0066 D2] When the object is `private`, the `'*'` wildcard only covers it if it is a super-user grant. */
+    opts: { isPrivate?: boolean } = {},
   ): boolean {
     const permKey = OPERATION_TO_PERMISSION[operation];
     if (!permKey) {
@@ -51,10 +77,10 @@ export class PermissionEvaluator {
     }
 
     for (const ps of permissionSets) {
-      // Honour the `'*'` wildcard sentinel — admin permission sets typically
-      // grant blanket access via a single `objects: { '*': … }` entry rather
-      // than enumerating every system object.
-      const objPerm = ps.objects?.[objectName] ?? ps.objects?.['*'];
+      // [ADR-0066 D2] Honour the `'*'` wildcard sentinel — admin permission
+      // sets grant blanket access via a single `objects: { '*': … }` entry —
+      // but a `private` object is excluded from a non-super-user wildcard.
+      const objPerm = resolveObjectPermission(ps, objectName, opts.isPrivate ?? false);
       if (objPerm) {
         // Check if modifyAllRecords is set (super-user bypass for write ops)
         if (['allowEdit', 'allowDelete'].includes(permKey) && objPerm.modifyAllRecords) {
@@ -87,13 +113,14 @@ export class PermissionEvaluator {
     opClass: 'read' | 'write',
     objectName: string,
     permissionSets: PermissionSet[],
+    opts: { isPrivate?: boolean } = {},
   ): 'own' | 'own_and_reports' | 'unit' | 'unit_and_below' | 'org' {
     const RANK = { own: 0, own_and_reports: 1, unit: 2, unit_and_below: 3, org: 4 } as const;
     const ORDER = ['own', 'own_and_reports', 'unit', 'unit_and_below', 'org'] as const;
     let widest = -1;
     let matched = false;
     for (const ps of permissionSets) {
-      const op: any = ps.objects?.[objectName] ?? ps.objects?.['*'];
+      const op: any = resolveObjectPermission(ps, objectName, opts.isPrivate ?? false);
       if (!op) continue;
       matched = true;
       if (opClass === 'read' && (op.viewAllRecords || op.modifyAllRecords)) return 'org';
@@ -106,6 +133,51 @@ export class PermissionEvaluator {
     return ORDER[widest < 0 ? 0 : widest];
   }
 
+  /**
+   * [ADR-0066 D3] Union of `systemPermissions` (capabilities) the caller holds
+   * across the resolved permission sets — used to enforce a resource's
+   * `requiredPermissions` AND-gate.
+   */
+  getSystemPermissions(permissionSets: PermissionSet[]): Set<string> {
+    const out = new Set<string>();
+    for (const ps of permissionSets) {
+      for (const cap of ps.systemPermissions ?? []) out.add(cap);
+    }
+    return out;
+  }
+
+  /**
+   * [ADR-0066 D2 / ①] Does any resolved set grant the super-user READ bypass
+   * (`viewAllRecords`/`modifyAllRecords`, the "View All Data" power) for the
+   * object? Honours the private posture (see {@link resolveObjectPermission}).
+   * The security plugin uses this to skip wildcard RLS on private/platform-global
+   * objects so a platform admin sees all rows.
+   */
+  hasSuperuserReadBypass(
+    objectName: string,
+    permissionSets: PermissionSet[],
+    opts: { isPrivate?: boolean } = {},
+  ): boolean {
+    for (const ps of permissionSets) {
+      const op = resolveObjectPermission(ps, objectName, opts.isPrivate ?? false);
+      if (op && (op.viewAllRecords || op.modifyAllRecords)) return true;
+    }
+    return false;
+  }
+
+  /** [ADR-0066 D2 / ①] Super-user WRITE bypass (`modifyAllRecords`) for the object. */
+  hasSuperuserWriteBypass(
+    objectName: string,
+    permissionSets: PermissionSet[],
+    opts: { isPrivate?: boolean } = {},
+  ): boolean {
+    for (const ps of permissionSets) {
+      const op = resolveObjectPermission(ps, objectName, opts.isPrivate ?? false);
+      if (op && op.modifyAllRecords) return true;
+    }
+    return false;
+  }
+
   /**
    * Get the merged field permissions for an object.
    * Returns a map of field names to their effective permissions.

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

@@ -389,6 +389,102 @@ describe('SecurityPlugin', () => {
     expect(opCtx.ast.where).toEqual({ organization_id: 'org-1' });
   });
 
+  // -------------------------------------------------------------------------
+  // ADR-0066 D2/D3 — private posture + requiredPermissions (full middleware)
+  // -------------------------------------------------------------------------
+  describe('ADR-0066 private posture + requiredPermissions (middleware)', () => {
+    const memberSet: PermissionSet = {
+      name: 'member_default', label: 'Member', isProfile: true,
+      objects: { '*': { allowRead: true, allowCreate: true, allowEdit: true, allowDelete: true } },
+    } as any;
+    // Platform super-admin: super-user wildcard + the capability + a tenant_isolation
+    // RLS policy (to prove the posture-gated bypass actually short-circuits it).
+    const adminSet: PermissionSet = {
+      name: 'admin_full_access', label: 'Admin', isProfile: true,
+      objects: { '*': { allowRead: true, allowCreate: true, allowEdit: true, allowDelete: true, viewAllRecords: true, modifyAllRecords: true } },
+      systemPermissions: ['manage_platform_settings'],
+      rowLevelSecurity: [
+        { name: 'tenant_isolation', object: '*', operation: 'all', using: 'organization_id = current_user.organization_id' },
+      ],
+    } as any;
+
+    it('DENIES a non-admin (plain wildcard) on a private object — wildcard does not cover it', async () => {
+      const plugin = new SecurityPlugin({ fallbackPermissionSet: 'member_default' });
+      const harness = makeMiddlewareCtx({
+        permissionSets: [memberSet],
+        objectFields: ['id', 'organization_id', 'signed_token'],
+        schemaExtra: { access: { default: 'private' } },
+        orgScoping: true,
+      });
+      await plugin.init(harness.ctx);
+      await plugin.start(harness.ctx);
+      const opCtx: any = {
+        object: 'task', operation: 'find', ast: { where: undefined },
+        context: { userId: 'u1', tenantId: 'org-1', roles: [], permissions: [] },
+      };
+      await expect(harness.run(opCtx)).rejects.toMatchObject({ name: 'PermissionDeniedError' });
+    });
+
+    it('DENIES a caller missing the required capability (D3 AND-gate)', async () => {
+      const plugin = new SecurityPlugin({ fallbackPermissionSet: 'member_default' });
+      const harness = makeMiddlewareCtx({
+        permissionSets: [memberSet],
+        objectFields: ['id', 'organization_id', 'signed_token'],
+        schemaExtra: { requiredPermissions: ['manage_platform_settings'] },
+      });
+      await plugin.init(harness.ctx);
+      await plugin.start(harness.ctx);
+      const opCtx: any = {
+        object: 'task', operation: 'find', ast: { where: undefined },
+        context: { userId: 'u1', tenantId: 'org-1', roles: [], permissions: [] },
+      };
+      await expect(harness.run(opCtx)).rejects.toMatchObject({
+        name: 'PermissionDeniedError',
+        message: expect.stringContaining('requires capability'),
+      });
+    });
+
+    it('ALLOWS the platform admin and BYPASSES wildcard RLS on a private object (read)', async () => {
+      const plugin = new SecurityPlugin({ fallbackPermissionSet: 'admin_full_access' });
+      const harness = makeMiddlewareCtx({
+        permissionSets: [adminSet],
+        objectFields: ['id', 'organization_id', 'signed_token'],
+        schemaExtra: { access: { default: 'private' }, requiredPermissions: ['manage_platform_settings'] },
+        orgScoping: true,
+      });
+      await plugin.init(harness.ctx);
+      await plugin.start(harness.ctx);
+      const opCtx: any = {
+        object: 'task', operation: 'find', ast: { where: undefined },
+        context: { userId: 'admin', tenantId: 'org-1', roles: ['admin_full_access'], permissions: [] },
+      };
+      await expect(harness.run(opCtx)).resolves.toBeDefined();
+      // Without the bypass this would be { organization_id: 'org-1' } and the
+      // platform admin would miss null-/cross-org rows (the sys_license bug).
+      expect(opCtx.ast.where).toBeUndefined();
+    });
+
+    it('BYPASSES the write pre-image check for a modifyAll admin on a private object', async () => {
+      const plugin = new SecurityPlugin({ fallbackPermissionSet: 'admin_full_access' });
+      const harness = makeMiddlewareCtx({
+        permissionSets: [adminSet],
+        objectFields: ['id', 'organization_id', 'signed_token'],
+        schemaExtra: { access: { default: 'private' }, requiredPermissions: ['manage_platform_settings'] },
+        orgScoping: true,
+        findOneImpl: () => null, // would DENY if the pre-image check ran
+      });
+      await plugin.init(harness.ctx);
+      await plugin.start(harness.ctx);
+      const opCtx: any = {
+        object: 'task', operation: 'update',
+        data: { id: 'r1', signed_token: 'x' }, options: { where: { id: 'r1' } },
+        context: { userId: 'admin', tenantId: 'org-1', roles: ['admin_full_access'], permissions: [] },
+      };
+      await expect(harness.run(opCtx)).resolves.toBeDefined();
+      expect(harness.findOne).not.toHaveBeenCalled();
+    });
+  });
+
   // -------------------------------------------------------------------------
   // getReadFilter service (ADR-0021 D-C) — the reusable READ scope the
   // analytics raw-SQL path bridges to. Must produce the SAME FilterCondition
@@ -891,6 +987,63 @@ describe('PermissionEvaluator', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// PermissionEvaluator — ADR-0066 D2 (private posture) + D3 (capabilities)
+// ---------------------------------------------------------------------------
+describe('PermissionEvaluator — ADR-0066 posture + capabilities', () => {
+  const ps = (name: string, objects: PermissionSet['objects'] = {}, systemPermissions?: string[]): PermissionSet =>
+    ({ name, objects, ...(systemPermissions ? { systemPermissions } : {}) });
+  const plainWildcard = ps('member', { '*': { allowRead: true, allowCreate: true, allowEdit: true, allowDelete: true } });
+  const superWildcard = ps('admin', { '*': { allowRead: true, allowCreate: true, allowEdit: true, allowDelete: true, viewAllRecords: true, modifyAllRecords: true } });
+  const explicitGrant = ps('license_reader', { sys_license: { allowRead: true, allowCreate: false, allowEdit: false, allowDelete: false } });
+
+  it('private object is NOT covered by a plain (non-superuser) wildcard', () => {
+    const ev = new PermissionEvaluator();
+    expect(ev.checkObjectPermission('find', 'sys_license', [plainWildcard], { isPrivate: true })).toBe(false);
+    // ...but a public object still is (today's allow-by-default).
+    expect(ev.checkObjectPermission('find', 'crm_account', [plainWildcard])).toBe(true);
+    expect(ev.checkObjectPermission('find', 'crm_account', [plainWildcard], { isPrivate: false })).toBe(true);
+  });
+
+  it('private object IS covered by a super-user wildcard (View/Modify All Data)', () => {
+    const ev = new PermissionEvaluator();
+    expect(ev.checkObjectPermission('find', 'sys_license', [superWildcard], { isPrivate: true })).toBe(true);
+    expect(ev.checkObjectPermission('insert', 'sys_license', [superWildcard], { isPrivate: true })).toBe(true);
+    expect(ev.checkObjectPermission('update', 'sys_license', [superWildcard], { isPrivate: true })).toBe(true);
+  });
+
+  it('private object IS covered by an explicit per-object grant (no superuser bit needed)', () => {
+    const ev = new PermissionEvaluator();
+    expect(ev.checkObjectPermission('find', 'sys_license', [explicitGrant], { isPrivate: true })).toBe(true);
+    expect(ev.checkObjectPermission('update', 'sys_license', [explicitGrant], { isPrivate: true })).toBe(false);
+  });
+
+  it('getSystemPermissions unions capabilities across sets', () => {
+    const ev = new PermissionEvaluator();
+    const a = ps('a', {}, ['manage_users', 'export_data']);
+    const b = ps('b', {}, ['export_data', 'manage_platform_settings']);
+    expect([...ev.getSystemPermissions([a, b])].sort()).toEqual(['export_data', 'manage_platform_settings', 'manage_users']);
+    expect([...ev.getSystemPermissions([plainWildcard])]).toEqual([]);
+  });
+
+  it('hasSuperuserReadBypass honours the private posture', () => {
+    const ev = new PermissionEvaluator();
+    // plain wildcard: bypasses on a public object, NOT on a private one.
+    expect(ev.hasSuperuserReadBypass('crm_account', [plainWildcard], { isPrivate: false })).toBe(false); // no viewAll bit
+    expect(ev.hasSuperuserReadBypass('sys_license', [superWildcard], { isPrivate: true })).toBe(true);
+    expect(ev.hasSuperuserReadBypass('sys_license', [plainWildcard], { isPrivate: true })).toBe(false);
+    // explicit grant without viewAll → no read bypass.
+    expect(ev.hasSuperuserReadBypass('sys_license', [explicitGrant], { isPrivate: true })).toBe(false);
+  });
+
+  it('hasSuperuserWriteBypass requires modifyAllRecords', () => {
+    const ev = new PermissionEvaluator();
+    const viewOnly = ps('vo', { '*': { allowRead: true, viewAllRecords: true } });
+    expect(ev.hasSuperuserWriteBypass('sys_license', [superWildcard], { isPrivate: true })).toBe(true);
+    expect(ev.hasSuperuserWriteBypass('sys_license', [viewOnly], { isPrivate: true })).toBe(false);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // FieldMasker
 // ---------------------------------------------------------------------------