feat(spec,plugin-audit): the compliance ledger's audit capability exempts its holder from the parent-record read gate (#21260)

WIP: declaration, default grant, the gate's one exemption, pins and docs.

Claude-Session: https://claude.ai/code/session_01DiCSbmJrkzNhuEAier4VoJ
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

content/docs/permissions/record-view-auditing.mdx

@@ -209,8 +209,13 @@ every field is `readonly`, so the ledger is never written through a form.
 Programmatic queries go through `services.data` against `sys_audit_log`. Outside
 system context a read returns a view row only when the caller can read the
 record it names, so neither the list view nor a query serves a view of a record
-the reader cannot open, or of a record that has since been deleted. Those rows
-stay stored, and a system-context read still returns them. Rows carry the
+the reader cannot open, or of a record that has since been deleted, unless the
+reader holds the `view_all_audit_log` capability. Its holder is served every
+ledger row its grant on `sys_audit_log` reaches, with each snapshot still
+narrowed by field-level security. Platform administrators hold it by default;
+anyone else holds it only through a permission set whose `systemPermissions`
+grant it. Those rows stay stored, and a system-context read still returns them.
+Rows carry the
 ADR-0057 `audit` lifecycle class: retained hot for
 90 days, then archived for seven years where an `archive` datasource is
 registered.

packages/plugins/plugin-audit/src/activity-read-visibility.test.ts

@@ -9,6 +9,7 @@
 
 import { describe, it, expect, vi } from 'vitest';
 import { installActivityReadVisibility, parseActivityParent } from './activity-read-visibility.js';
+import { LEDGER_AUDIT_CAPABILITY } from './audit-log-read-visibility.js';
 import type { CommentAccessEngine, CommentReadMiddlewareCtx } from './comment-access-hooks.js';
 
 const DENY = { id: '__activity_parent_denied__' };
@@ -198,6 +199,16 @@ describe('installActivityReadVisibility', () => {
     expect(calls.probes[0].context).not.toHaveProperty('__expandRead');
   });
 
+  it('[#21260] a holder of the ledger’s audit capability is narrowed here exactly like any caller', async () => {
+    const scan = () => [{ object_name: 'crm_case', record_id: 'c1' }];
+    for (const operation of ['find', 'findOne', 'count', 'aggregate'] as const) {
+      const { mw, calls } = install({ scan, readable: { crm_case: [] } });
+      const holder = { userId: 'u1', systemPermissions: [LEDGER_AUDIT_CAPABILITY] };
+      expect((await read(mw, { operation, context: holder })).where).toEqual(DENY);
+      expect(calls.scans).toHaveLength(1);
+    }
+  });
+
   it('is inert on an engine without the middleware seam', () => {
     const engine: CommentAccessEngine = { registerHook: () => {}, find: async () => [], findOne: async () => null };
     expect(() => installActivityReadVisibility(engine, silentLogger())).not.toThrow();

packages/plugins/plugin-audit/src/activity-read-visibility.ts

@@ -62,7 +62,11 @@ import {
 
 const ACTIVITY_OBJECT = 'sys_activity';
 
-/** The activity stream's gate: every row naming no parent is excluded. */
+/**
+ * The activity stream's gate: every row naming no parent is excluded, and no
+ * caller is exempt. The compliance ledger's audit capability exempts its holder
+ * from the ledger's gate only (#21260: the ruling names the ledger).
+ */
 const ACTIVITY_GATE: ParentRecordGate = {
   object: ACTIVITY_OBJECT,
   seam: 'activity read visibility',

packages/plugins/plugin-audit/src/audit-log-read-visibility.integration.test.ts

@@ -48,6 +48,8 @@ const SYS = { isSystem: true } as const;
 const MEMBER = { userId: 'u_member', tenantId: 'org_1', positions: ['org_member'] };
 const OTHER = { userId: 'u_other', tenantId: 'org_1', positions: ['org_member'] };
 const ADMIN = { userId: 'u_admin', tenantId: 'org_1', positions: ['org_admin'] };
+/** [#21260] A member holding the ledger's audit capability, and owning nothing. */
+const HOLDER = { userId: 'u_auditor', tenantId: 'org_1', positions: ['org_member'], systemPermissions: ['view_all_audit_log'] };
 
 const ownedObject = {
   name: OWNED,
@@ -260,4 +262,20 @@ describe('[#21175] sys_audit_log read visibility — the plugin read path', () =
     const rows = await engine.find(LEDGER, { context: SYS });
     expect(rows.length).toBe(allRows.length);
   });
+
+  it('[#21260] a holder of the ledger audit capability is served every row, deleted and unreadable records included', async () => {
+    const rows = await engine.find(LEDGER, { context: HOLDER });
+    expect(keys(rows)).toEqual(keys(allRows));
+    expect(await engine.count(LEDGER, {}, { context: HOLDER })).toBe(allRows.length);
+    expect((await engine.findOne(LEDGER, {
+      where: { object_name: OWNED, record_id: ids.mineGone, action: 'delete' }, context: HOLDER,
+    }))?.record_id).toBe(ids.mineGone);
+  });
+
+  it('[#21260] the same holder is still narrowed on the activity stream', async () => {
+    const aboutGone = { record_id: { $in: [ids.mineGone, ids.boardGone, ids.theirs] } };
+    const atRest = await engine.find('sys_activity', { where: aboutGone, context: SYS });
+    expect(atRest.length).toBeGreaterThan(0);
+    expect(await engine.find('sys_activity', { where: aboutGone, context: HOLDER })).toEqual([]);
+  });
 });

packages/plugins/plugin-audit/src/audit-log-read-visibility.test.ts

@@ -8,7 +8,13 @@
  */
 
 import { describe, it, expect, vi } from 'vitest';
-import { installAuditLogReadVisibility, isLedgerRowAboutNoRecord } from './audit-log-read-visibility.js';
+import { ADMIN_FULL_ACCESS_CAPABILITIES } from '@objectstack/spec';
+import { PLATFORM_CAPABILITIES } from '@objectstack/spec/security';
+import {
+  LEDGER_AUDIT_CAPABILITY,
+  installAuditLogReadVisibility,
+  isLedgerRowAboutNoRecord,
+} from './audit-log-read-visibility.js';
 import type { CommentAccessEngine, CommentReadMiddlewareCtx } from './comment-access-hooks.js';
 
 const DENY = { id: '__audit_log_parent_denied__' };
@@ -212,3 +218,45 @@ describe('installAuditLogReadVisibility', () => {
     expect(() => installAuditLogReadVisibility(engine, silentLogger())).not.toThrow();
   });
 });
+
+describe('[#21260] the ledger audit capability', () => {
+  const unreadable = () => [
+    { id: 'l1', action: 'delete', object_name: 'crm_case', record_id: 'c1' },
+    { id: 'l2', action: 'logout', object_name: 'sys_session', record_id: 's1' },
+  ];
+  const holder = { userId: 'u1', systemPermissions: ['setup.access', LEDGER_AUDIT_CAPABILITY] };
+
+  it('is the capability the platform declares, platform-scoped, and grants platform administrators by default', () => {
+    expect(PLATFORM_CAPABILITIES.find((c) => c.name === LEDGER_AUDIT_CAPABILITY)?.scope).toBe('platform');
+    expect(ADMIN_FULL_ACCESS_CAPABILITIES.systemPermissions).toContain(LEDGER_AUDIT_CAPABILITY);
+  });
+
+  it('its holder is not narrowed, on any read operation, and nothing is scanned for it', async () => {
+    for (const operation of ['find', 'findOne', 'count', 'aggregate'] as const) {
+      const { mw, calls } = install({ scan: unreadable, readable: { crm_case: [], sys_session: [] } });
+      const existing = { action: 'delete' };
+      const { where, ran } = await read(mw, { operation, context: holder, ast: { object: 'sys_audit_log', where: existing } });
+      expect(ran).toBe(true);
+      expect(where).toBe(existing);
+      expect(calls.scans).toEqual([]);
+      expect(calls.probes).toEqual([]);
+    }
+  });
+
+  it('its holder’s broad read never meets the pre-scan bound', async () => {
+    const logger = silentLogger();
+    const rows = Array.from({ length: 2000 }, (_, i) => ({ id: `l${i}`, action: 'update', object_name: 'crm_case', record_id: `c${i}` }));
+    const { mw, calls } = install({ scan: () => rows, readable: { crm_case: [] }, logger });
+    expect((await read(mw, { context: holder })).where).toBeUndefined();
+    expect(calls.scans).toEqual([]);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('a caller without it gets exactly the parent-record gate: other capabilities, a non-list, or none', async () => {
+    for (const systemPermissions of [['setup.access', 'manage_users'], LEDGER_AUDIT_CAPABILITY, undefined]) {
+      const { mw, calls } = install({ scan: unreadable, readable: { crm_case: [], sys_session: [] } });
+      expect((await read(mw, { context: { userId: 'u1', systemPermissions } })).where).toEqual(DENY);
+      expect(calls.scans).toHaveLength(1);
+    }
+  });
+});

packages/plugins/plugin-audit/src/audit-log-read-visibility.ts

@@ -32,9 +32,10 @@
  *    `update` on a `sys_user`, and the auth-event sink's `login` / `logout`,
  *    which name the session (`auth-event-audit.ts`). Judged by the record gate.
  *    A record that no longer exists is read by no caller, so its rows are
- *    excluded for every caller that is not system context: every `delete` row,
- *    every other row about a deleted record, and every `logout` row (sign-out
- *    deletes the session it names).
+ *    excluded for every caller that is not system context and does not hold
+ *    the audit capability below: every `delete` row, every other row about a
+ *    deleted record, and every `logout` row (sign-out deletes the session it
+ *    names).
  *  - **Rows about no record** — they name no `record_id` and their action is
  *    not a record action: the run-level `import` (plugin-auth's user import),
  *    `config_change` (service-settings) and `platform_admin_standing_change`
@@ -58,6 +59,18 @@
  * this gate keeps, a snapshot still serves a parent field only to a reader the
  * security service serves that field unmasked.
  *
+ * ## The audit capability (#21260, ruling B on #21175)
+ *
+ * A caller holding {@link LEDGER_AUDIT_CAPABILITY} is not narrowed by this
+ * gate: it is served the deletion and sign-out trail, the rows about records
+ * it cannot open, and a broad read whole (the gate's pre-scan, and so its
+ * bound, never runs for it). It still needs the ledger's own object grant,
+ * and the field redaction still narrows every snapshot it is served. Platform
+ * administrators hold it by default (`ADMIN_FULL_ACCESS_CAPABILITIES` in
+ * `@objectstack/spec`); every other position only by explicit grant. The
+ * exemption is the shared mechanism's (`ParentRecordGate.exemptCapability`),
+ * declared here and nowhere else: the activity stream's gate declares none.
+ *
  * System-context reads (the platform-admin standing boot reading its last
  * roster, the writers' own reads) and context-less programmatic calls are not
  * narrowed, as for every gate in this package: every real transport carries a
@@ -99,11 +112,20 @@ export function isLedgerRowAboutNoRecord(row: Record<string, unknown>): boolean
   return typeof action === 'string' && action !== '' && !RECORD_ACTIONS.has(action);
 }
 
+/**
+ * The compliance ledger's audit capability: its holder is exempt from this
+ * gate. Declared in `PLATFORM_CAPABILITIES` (`@objectstack/spec/security`) and
+ * granted by `ADMIN_FULL_ACCESS_CAPABILITIES`; this spelling is pinned against
+ * both in `audit-log-read-visibility.test.ts`.
+ */
+export const LEDGER_AUDIT_CAPABILITY = 'view_all_audit_log';
+
 const LEDGER_GATE: ParentRecordGate = {
   object: LEDGER_OBJECT,
   seam: 'audit log read visibility',
   denyAll: { id: '__audit_log_parent_denied__' },
   outsideClass: { fields: ['action'], test: isLedgerRowAboutNoRecord },
+  exemptCapability: LEDGER_AUDIT_CAPABILITY,
 };
 
 /**

packages/plugins/plugin-audit/src/parent-record-read-gate.ts

@@ -41,6 +41,16 @@
  * rows that name NO record and that the gate states are not about one. Those
  * are kept by their stored id, so the branch can only match rows the pre-scan
  * saw. A gate that declares none (the activity stream) excludes them too.
+ *
+ * The one declared exemption is a gate's
+ * {@link ParentRecordGate.exemptCapability}: a caller holding that capability
+ * is not narrowed by the gate at all — no pre-scan, so no pre-scan bound, and
+ * nothing ANDed in. Only this gate is skipped: the object's own grant, the other
+ * read seams on it (a field redaction, a query guard) and every other gate
+ * still apply. Held means the caller's resolved `systemPermissions`, the one
+ * capability set the request's authorization resolver stamps on the execution
+ * context and every other capability check reads. A gate that declares none
+ * (the activity stream) exempts no caller.
  */
 
 import {
@@ -92,6 +102,22 @@ export interface ParentRecordGate {
   denyAll: Readonly<Record<string, unknown>>;
   /** Absent: every row that names no parent record is excluded. */
   outsideClass?: OutsideClassRows;
+  /**
+   * A capability whose holder this gate does not narrow. Absent: no caller is
+   * exempt. Must name a capability the platform declares and grants
+   * deliberately; the ledger's is pinned against `PLATFORM_CAPABILITIES`.
+   */
+  exemptCapability?: string;
+}
+
+/**
+ * Whether the caller holds `capability`: its resolved `systemPermissions`, as
+ * the request's authorization resolver stamped them on the execution context.
+ * Absent, or not a list, is not held.
+ */
+function callerHoldsCapability(context: CommentReadMiddlewareCtx['context'], capability: string): boolean {
+  const held = context?.systemPermissions;
+  return Array.isArray(held) && held.includes(capability);
 }
 
 /**
@@ -133,16 +159,20 @@ export function andIntoWhere(ctx: CommentReadMiddlewareCtx, filter: unknown): vo
 
 /**
  * The parent-visibility WHERE for one read of `gate.object`: `null` when the
- * query matches no rows (nothing to narrow), one `$in` branch per parent
- * object holding the readable ids (plus the outside-class rows' ids), or the
- * gate's deny-all sentinel.
+ * caller holds the gate's exempt capability or the query matches no rows
+ * (nothing to narrow), one `$in` branch per parent object holding the readable
+ * ids (plus the outside-class rows' ids), or the gate's deny-all sentinel.
  */
 export async function computeParentRecordFilter(
   engine: CommentAccessEngine,
   ctx: CommentReadMiddlewareCtx,
   logger: CommentAccessLogger,
   gate: ParentRecordGate,
 ): Promise<unknown | null> {
+  // 0. The gate's declared exemption, decided before anything is scanned, so a
+  //    holder's broad read never meets the pre-scan bound.
+  if (gate.exemptCapability && callerHoldsCapability(ctx.context, gate.exemptCapability)) return null;
+
   // 1. The parent pairs the query would touch, read under SYSTEM context (the
   //    caller may not see the rows yet; that is what is being decided). The
   //    caller's own order rides along, so on a table larger than the scan

packages/plugins/plugin-security/src/objects/default-permission-sets.test.ts

@@ -361,6 +361,11 @@ describe('sys_comment delete is moderation-shaped, not ownership-shaped (#8839)'
  * exact pre-#11965 inline value (comments elided); if this pin fails, the spec
  * export changed the declared capability set — that is a capability change
  * riding on a refactor card, and it must not land silently.
+ *
+ * One capability change has landed on purpose since, on its own card, and is
+ * written into the literal below: `view_all_audit_log` (#21260, ruling B on
+ * #21175 — platform administrators hold the compliance ledger's audit
+ * capability by default).
  */
 describe('admin_full_access imports the kernel capability declaration unchanged (#11965)', () => {
   it('parsed declaration deep-equals the pre-#11965 inline literal', () => {
@@ -386,11 +391,20 @@ describe('admin_full_access imports the kernel capability declaration unchanged
         'setup.access',
         'setup.write',
         'studio.access',
+        // [#21260] added on purpose — see the docblock above.
+        'view_all_audit_log',
       ],
     });
     expect(setByName('admin_full_access')).toEqual(preMove);
   });
 
+  it('[#21260] no other shipped set carries the ledger audit capability: every other position holds it only by explicit grant', () => {
+    const holders = (defaultPermissionSets as any[])
+      .filter((s) => (s.systemPermissions ?? []).includes('view_all_audit_log'))
+      .map((s) => s.name);
+    expect(holders).toEqual(['admin_full_access']);
+  });
+
   it('the imported spec constant is the declaration content — no local fork', () => {
     const admin = setByName('admin_full_access');
     // Same values, sourced from the one spec-exported copy.