feat(plugin-audit): record-view auditing — who viewed which record (#8992) (#9515)

* feat(plugin-audit): record-view auditing — the `read` action, its writer, and its view (#8992)

`sys_audit_log` covered writes only: `actionFor()` maps exactly
afterInsert/afterUpdate/afterDelete, and the shipped list views confirmed the
scope. "Who viewed this customer record, and when?" was unanswerable.

Adds the `read` action WRITER-FIRST — the emission point, its tests, and the
`record_views` list view that surfaces it, in one stroke, which is the only way
a value is allowed onto this enum (#8147 / #8315).

Scope is the maintainer's 2026-08-16 ruling, and each pin is code:

- record-detail views only — `extractDetailReadId` requires one materialized
  record AND a primary-key pin, so list/search reads produce nothing;
- per-object opt-in, closed — one input, used as the narrow `afterFind`
  registration target, so a non-audited read costs no dispatch;
- batched off the request path — the hook enqueues and returns; each row keeps
  the VIEW instant via the system-context `created_at` exemption (#4447).

The row carries no field values: `afterFind` runs ahead of the security
middleware's field masking, so `ctx.result` is pre-mask plaintext.

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

* test(plugin-audit): give the harness objects their owning package id

`registry.registerObject(schema, packageId)` requires the owner; the one-arg
call ran fine but failed `tsc --noEmit`.

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

* test(plugin-audit): type the engine query options instead of erasing them to `any`

The new read-audit suite added 22 sites to the `query-options-erasure`
test-surface ratchet (240 -> 262). Fixed at the source: every find/findOne/
insert options bag is now passed typed, and the shared read context is a named
`ReadContext` alias off `EngineQueryOptions['context']`. The ratchet returns to
240 — flat, not raised.

This is not count-satisfying hygiene here. The gate's #8210 caveat is that in a
package whose tsconfig excludes test files, typing these buys no compiler guard
today. plugin-audit does NOT exclude them, so `tsc` reads this file and a wrong
options key is a real compile error rather than a silently dropped one (#4674).

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

---------

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

Author: os-project-manager

.changeset/wise-pugs-attend.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/plugin-audit": minor
+---
+
+Record-view auditing: `sys_audit_log` can now answer "who viewed which record"
+
+`sys_audit_log` covered writes only, so the question every regulated-industry
+security review opens with — *who viewed this customer record, and when?* — had
+no answer short of custom work. The ledger now has a `read` action, its writer,
+and the `record_views` list view that surfaces it.
+
+Scope is deliberately narrow (maintainer ruling 2026-08-16):
+
+- **Record-detail views only.** A read qualifies when it materialized one record
+  and its predicate pinned the primary key — the shape `GET /data/:object/:id`
+  produces. List and search reads are not audited.
+- **Per-object opt-in, closed.** Nothing is recorded until a deployment names the
+  objects: `new AuditPlugin({ readAudit: { objects: ['contact', 'account'] } })`.
+  There is no global switch and no exception list, and an empty opt-in registers
+  no hook at all, so the default posture costs a read nothing.
+- **Batched off the request path.** The hook buffers and returns; rows are
+  persisted on a later tick, size- or timer-triggered, and flushed on shutdown.
+  Each row keeps the instant the record was VIEWED, not the instant its batch
+  drained.
+
+The row records who, what and when — never field values. Read auditing runs
+inside the security middleware, ahead of its field masking, so the record it sees
+is pre-mask; copying values in would mint a plaintext copy of exactly what
+field-level security withholds, in the table compliance staff are granted broad
+access to.
+
+Two boundaries are declared rather than left to be discovered: a system-elevated
+read (`api.sudo()`, formula recomputes, roll-ups) writes no row, and neither does
+a read with no principal to name.

packages/plugins/plugin-audit/src/audit-plugin.ts

@@ -14,9 +14,44 @@ import { SysAuditLog, SysActivity, SysComment } from './objects/index.js';
 // @objectstack/service-storage for the same ownership reason (ADR-0052 §3: a
 // file↔record link belongs with storage, not the compliance ledger).
 import { installAuditWriters, type AuditI18nSurface, type MessagingEmitSurface } from './audit-writers.js';
+import { installReadAuditWriter, type ReadAuditWriterHandle } from './read-audit.js';
 import { createAuthEventAuditSink } from './auth-event-audit.js';
 import { installCommentAccessHooks, installCommentReadVisibility } from './comment-access-hooks.js';
 
+/**
+ * [#8992] Read/view audit configuration — the per-object opt-in, closed.
+ *
+ * Not a global flag with exceptions: the maintainer's 2026-08-16 ruling chose a
+ * closed opt-in deliberately, because on a compliance surface the failure modes
+ * of the two shapes are not symmetric. A global flag that forgets an exception
+ * over-collects (noisy, expensive, and it buries the views an auditor is
+ * looking for); an opt-in that forgets an object under-collects, which is
+ * visible the moment anyone asks the question this capability exists to answer.
+ */
+export interface AuditPluginReadAuditOptions {
+  /**
+   * Objects whose RECORD-DETAIL views are recorded as `read` rows in
+   * `sys_audit_log`. Absent or empty installs no hook at all — a deployment
+   * that opts nothing in pays nothing on its read path.
+   *
+   * ⛔ Scope is record-detail views only (a read that materialized one record
+   * and pinned its primary key). List and search results are NOT audited: that
+   * is a deferred follow-up, and a deferral that leaked rows anyway would not
+   * be one.
+   */
+  objects?: readonly string[];
+  /** Flush once this many views are buffered. Default 50. */
+  maxBatchSize?: number;
+  /** Flush this long after the first view of a batch. Default 2000ms. */
+  flushIntervalMs?: number;
+}
+
+/** Constructor options for {@link AuditPlugin}. */
+export interface AuditPluginOptions {
+  /** [#8992] Record-view auditing. Off unless objects are named. */
+  readAudit?: AuditPluginReadAuditOptions;
+}
+
 /**
  * AuditPlugin
  *
@@ -39,6 +74,16 @@ export class AuditPlugin implements Plugin {
    */
   providesServices = ['audit'];
 
+  /**
+   * [#8992] The record-view writer's handle, held so `destroy()` can flush the
+   * tail. A batched ledger that never flushes on shutdown loses its last batch
+   * on every clean restart — silently, because the reads it describes all
+   * succeeded.
+   */
+  private readAuditWriter: ReadAuditWriterHandle | null = null;
+
+  constructor(private readonly options: AuditPluginOptions = {}) {}
+
   async init(ctx: PluginContext): Promise<void> {
     // Register audit system objects via the manifest service.
     ctx.getService<{ register(m: any): void }>('manifest').register({
@@ -162,6 +207,28 @@ export class AuditPlugin implements Plugin {
       installAuditWriters(engine as any, this.name, { getMessaging, getI18n, getLocale });
       ctx.logger.info('AuditPlugin: audit + activity writers installed');
 
+      // [#8992] Record-view auditing — the `read` half of the ledger. Installed
+      // only over the objects this deployment opted in, and returns null when
+      // that set is empty, so the default posture costs a read exactly nothing.
+      const readAuditObjects = this.options.readAudit?.objects ?? [];
+      this.readAuditWriter = installReadAuditWriter(engine, {
+        objects: readAuditObjects,
+        packageId: this.name,
+        logger: ctx.logger,
+        ...(this.options.readAudit?.maxBatchSize !== undefined
+          ? { maxBatchSize: this.options.readAudit.maxBatchSize }
+          : {}),
+        ...(this.options.readAudit?.flushIntervalMs !== undefined
+          ? { flushIntervalMs: this.options.readAudit.flushIntervalMs }
+          : {}),
+      });
+      if (this.readAuditWriter) {
+        ctx.logger.info(
+          `AuditPlugin: record-view auditing installed on ${this.readAuditWriter.auditedObjects.length} object(s) — `
+            + `${this.readAuditWriter.auditedObjects.join(', ')}`,
+        );
+      }
+
       // #4630 — record-level authorization for sys_comment: a comment's access
       // derives from the record its `thread_id` names, exactly as an
       // attachment's derives from its parent (service-storage's
@@ -306,4 +373,20 @@ export class AuditPlugin implements Plugin {
       );
     }
   }
+
+  /**
+   * [#8992] Flush the record-view tail on shutdown.
+   *
+   * Batching is what keeps the ledger write off the read path, and the price of
+   * a buffer is that a clean shutdown can take the last batch with it. The
+   * views in it already returned 200, so nothing else would ever report the
+   * loss. `stop()` cancels the timer and drains what is left; it never throws
+   * (the batcher's `persist` reports and swallows), so this can never turn a
+   * clean shutdown into a failed one.
+   */
+  async destroy(): Promise<void> {
+    const writer = this.readAuditWriter;
+    this.readAuditWriter = null;
+    if (writer) await writer.stop();
+  }
 }

packages/plugins/plugin-audit/src/audit-writers.ts

@@ -95,7 +95,10 @@ export interface AuditWriterOptions {
  * Skip rules avoid recursion and noise:
  *  - Never audit the audit/activity tables themselves.
  *  - Never audit session/presence/auth tables (high-frequency, low value).
- *  - Read-only operations (`afterFind`) are never audited.
+ *  - Read-only operations (`afterFind`) are not audited BY THIS WRITER. Since
+ *    #8992 the `read` action has its own writer in `read-audit.ts`, installed
+ *    separately and only over the objects a deployment opts in: record-detail
+ *    views, batched off the request path. This writer stays write-only.
  *
  * All writes go through `ctx.api.sudo()` so they bypass record-level
  * permissions and always succeed regardless of the calling user's RBAC.
@@ -187,8 +190,15 @@ const SKIP_OBJECTS = new Set<string>([
  * are one list, so neither can drift from the other. The early return stays as
  * defence in depth — it is what protects every non-hook caller of these
  * handlers, and it keeps audit behaviour bit-for-bit conserved by this change.
+ *
+ * [#8992] EXPORTED because the read/view writer (`read-audit.ts`) needs the same
+ * subtraction and must not keep a second copy of it. Every reason an object is
+ * excluded from write auditing — recursion, auth/session noise, ADR-0057
+ * telemetry plumbing — applies unchanged to auditing its READS, and two
+ * hand-kept lists would disagree the day either is fixed. Same rule this
+ * docblock already states one paragraph up, now across two files.
  */
-const AUDIT_EXCLUDED_OBJECTS: string[] = [...SKIP_OBJECTS];
+export const AUDIT_EXCLUDED_OBJECTS: string[] = [...SKIP_OBJECTS];
 
 /** Fields that are noise in diffs (always change, never user-meaningful). */
 const NOISE_FIELDS = new Set<string>([

packages/plugins/plugin-audit/src/index.ts

@@ -10,6 +10,21 @@
 export { AuditPlugin } from './audit-plugin.js';
 export { createFieldPresenceProbe, installAuditWriters } from './audit-writers.js';
 export { createAuthEventAuditSink } from './auth-event-audit.js';
+export {
+  createReadAuditBatcher,
+  extractDetailReadId,
+  installReadAuditWriter,
+  READ_AUDIT_ACTION,
+} from './read-audit.js';
+export type {
+  ReadAuditBatcher,
+  ReadAuditBatcherOptions,
+  ReadAuditEvent,
+  ReadAuditLogger,
+  ReadAuditTimers,
+  ReadAuditWriterHandle,
+  ReadAuditWriterOptions,
+} from './read-audit.js';
 export type {
   AuthEventAuditLogger,
   AuthEventAuditSink,

packages/plugins/plugin-audit/src/objects/sys-audit-log-retired-actions.test.ts

@@ -72,6 +72,7 @@ const RETIRED_ACTIONS: ReadonlyArray<readonly [action: string, prescription: str
  */
 const ACTIONS_WITH_WRITERS: ReadonlyArray<readonly [action: string, writer: string]> = [
   ['create', 'plugin-audit/src/audit-writers.ts — actionFor(afterInsert)'],
+  ['read', 'plugin-audit/src/read-audit.ts — installReadAuditWriter afterFind hook (#8992)'],
   ['update', 'plugin-audit/src/audit-writers.ts — actionFor(afterUpdate)'],
   ['delete', 'plugin-audit/src/audit-writers.ts — actionFor(afterDelete)'],
   ['login', 'plugin-audit/src/auth-event-audit.ts — createAuthEventAuditSink (#8144)'],

packages/plugins/plugin-audit/src/objects/sys-audit-log.object.ts

@@ -72,6 +72,27 @@ export const SysAuditLog = ObjectSchema.create({
       sort: [{ field: 'created_at', order: 'desc' }],
       pagination: { pageSize: 50 },
     },
+    // [#8992] The `read` action's shipped surface. A ledger value with no view
+    // is half of the empty-widget defect the 2026-08-12 ruling named; this card
+    // adds the action and the screen that answers its question in one stroke.
+    // `record_views` is the "who viewed this record" query as a list: actor
+    // first, because that is the column an auditor scans.
+    record_views: {
+      type: 'grid',
+      name: 'record_views',
+      label: 'Record Views',
+      data: { provider: 'object', object: 'sys_audit_log' },
+      columns: ['created_at', 'user_id', 'object_name', 'record_id', 'ip_address'],
+      filter: [{ field: 'action', operator: 'in', value: ['read'] }],
+      sort: [{ field: 'created_at', order: 'desc' }],
+      pagination: { pageSize: 50 },
+      emptyState: {
+        title: 'No record views recorded',
+        message:
+          'Record-view auditing is opt-in per object. Rows appear here once an object is added to the audit '
+          + "plugin's readAudit.objects list and someone opens one of its records.",
+      },
+    },
     config_changes: {
       type: 'grid',
       name: 'config_changes',
@@ -135,8 +156,17 @@ export const SysAuditLog = ObjectSchema.create({
     // and silently, because every field here is `readonly: true` and
     // `validateRecord` skips readonly fields, so nothing would ever go red.
     // See #8147 for the escalation.
+    // [#8992, maintainer ruling 2026-08-16] `read` joins the enum WRITER-FIRST,
+    // which is the only way a value is allowed back onto this surface (the
+    // docblock in `sys-audit-log-retired-actions.test.ts` states the rule and
+    // the pin enforces it). Its writer is `read-audit.ts`'s `afterFind` hook,
+    // its shipped surface is the `record_views` list view above, and both
+    // landed in the same PR as this line. Scope is the ruling's MVP:
+    // record-detail views on per-object opt-in, batched off the request path —
+    // so a deployment that opts nothing in never writes one, and the value is
+    // narrow rather than absent (审计面宁窄勿谎).
     action: Field.select(
-      ['create', 'update', 'delete', 'login', 'logout', 'config_change', 'import'],
+      ['create', 'read', 'update', 'delete', 'login', 'logout', 'config_change', 'import'],
       {
         label: 'Action',
         required: true,