fix(plugin-audit): a read of the compliance ledger returns only the rows about records the caller can read (#21175)

[objectstack-fleet]

Fixes #21175
Clause-②: no

A read of the compliance ledger (sys_audit_log) now returns only the rows about records the caller can read. This implements triage's ruling A on the card (5932888473): the ledger takes the activity stream's parent-record read gate (#20833, PR #21069), and that gate reads the engine's own answer.

Status. Draft. The product consequence for admins (see Acceptance notes) is awaiting the maintainer's decision on #21175; this PR's behaviour is unchanged by patch round 1.

Patch round 1: what changed since the first push

• Merged origin/main at 1ecb871b (merge commit 77d3cc05; no rebase, no force-push). PR fix(plugin-audit,plugin-approvals)!: refuse a query over activity text, ledger snapshots or the approval snapshot for a reader withheld a field of its record (#21154) #21179 (security(plugin-audit): a filter over the stored activity text answers by row presence: the generic list door evaluates the predicate at rest, before #21081's read-time redaction, so a reader can probe a field value it is not served #21154) is in that merge. Its audit-plugin.ts mount and this PR's mount sat in different hunks of the same block and merged without a conflict. The census page (content/docs/permissions/system-context.mdx) did conflict: row 45 now names both the query guard and the ledger read gate, and the declared counts were regenerated by gen:system-context-census (114 sites).

• Mount order. Engine middleware runs in registration order. On sys_audit_log the order is now: (1) the query guard from security(plugin-audit): a filter over the stored activity text answers by row presence: the generic list door evaluates the predicate at rest, before #21081's read-time redaction, so a reader can probe a field value it is not served #21154, (2) the ledger field redaction from security(plugin-audit): the compliance ledger's create/update rows serve a withheld field's stored value in their before/after snapshots to a reader whose sets grant the ledger read, while the data plane serves that reader without the key #21155, (3) this PR's parent-record read gate. On sys_activity it is: (1) the query guard, (2) the activity read gate, (3) the activity field redaction. Each guarantee holds:

  • the guard judges a query before any read gate runs its pre-scan, so a refused query never pays it;
  • the read gate ANDs its WHERE before the read executes;
  • the redaction narrows the rows that come back, which are only the rows the gate kept.

  The mount comment in audit-plugin.ts states this order.

• Changeset, now in the activity gate's form (plugin-audit: sys_activity has no parent-record read gate, so any object-level read opens every activity row in the environment. Add the same read filter sys_comment has, keeping rows whose parent record the caller can read #20833 / PR fix(plugin-audit)!: an engine read of sys_activity returns only the rows whose parent record the caller can read #21069): minor, a BREAKING paragraph, and Clause-②: no (narrowing). The arm is there because this narrows what a read returns and no accept set widens; the PR line above keeps the claim's no. It carries the ADR-0087 not-required (no-migration-prescription) marker (check-adr-0087-registration: 1 declared-breaking changeset, carrying its disposition) and a Migration paragraph.

• CI red on the previous head. The red was Dogfood Regression Gate (3/3); reproduced locally on that head. The failing case was admin-ledger-decision-metadata.dogfood.test.ts, a pin security(plugin-auth): the compliance-ledger row an admin create-user writes carries a withheld user field's value in its decision metadata, which a ledger reader withheld that field is served #21174 landed on main after this branch's first merge. Its readers could open only their own user row through the data door (measured: each reader got 404 on the subject user). Under the parent-record rule they are served none of the subject's ledger rows, so its armed check disarmed. Old to new: the fixture's reader sets now add view-all on the user object, a row-scope grant only. A new armed control asserts that every reader opens the subject through the data door (measured 200 for all five). No assertion changed: its armed check still measures that each reader is withheld exactly its field class, and all 8 cases pass.

• Docs. content/docs/permissions/record-view-auditing.mdx, "Reading the trail": the sentence saying ledger queries go through the data service "like any other object" now states the read rule. A view row is served outside system context only to a caller who can read its record. Views of a record that has since been deleted stay stored and are served only to system-context reads.

Measured first, on a real boot (classes only)

The re-measure was private and its readings stay in the dispatch's scratch. It ran on main at b9087d77 (PR #21171 in), and again at this branch's first head. The stack was bootStack, org-bound, with the real SecurityPlugin, auth, REST and AuditPlugin. The rows were written by the CRUD mirror and the auth-event sink. The member holds the ledger read through one explicit permission set; the admin is the seeded admin. "Parent" means the same caller's read of the row's record through the data door.

door	caller	parent, through the data door	before	after
list GET /data/sys_audit_log	member	404: a private record's create, update and delete rows	returned	absent
list	member	404: other users' sessions (their login rows)	returned	absent
list	member	200	returned	returned
by id GET /data/sys_audit_log/:id	member	404	200	404
list, by id	admin	200: every existing record	returned	returned
list	admin, member	the record no longer exists (delete rows, a deleted record's other rows, logout rows)	returned	absent
list total	member	(any)	51	42, the rows returned
list total	admin	(any)	51	47, the rows returned

What changed

• parent-record-read-gate.ts (new): the activity gate's mechanism, moved out of activity-read-visibility.ts and parameterized per gate. It still asks resolveReadableParentIds, the one readability answer the comment and activity gates share. Nothing derives row scope a second way.
• activity-read-visibility.ts: now a thin declaration over the shared module. Its exports (parseActivityParentObject, which the security(plugin-audit): a filter over the stored activity text answers by row presence: the generic list door evaluates the predicate at rest, before #21081's read-time redaction, so a reader can probe a field value it is not served #21154 guard imports, included), scan options, sentinel and log lines are unchanged, and its unit and integration pins pass unedited.
• audit-log-read-visibility.ts (new): installAuditLogReadVisibility, the ledger's declaration, with the row classes below.
• audit-plugin.ts: one mount with its order comment, plus the no-middleware-seam warning now names the ledger read gate.
• content/docs/permissions/system-context.mdx, row 45: the census anchor for the new early return on system context.

Row classes: the stated answer for rows the gate cannot judge

Measured per writer:

• About a record (object_name + record_id): the CRUD mirror's create, update and delete rows; record-view read rows; plugin-auth's administrative create and update on a user; and login / logout, which name the session. Judged by the record gate.
• About a record that no longer exists: no caller can read the record, so these rows are excluded for every caller that is not system context, admins included. That covers every delete row, every logout row (sign-out deletes the session, measured), and a sign-in row whose session has since been removed. The rows stay stored.
• About no record (no record_id, and an action that is not a record action): the run-level import, config_change and platform_admin_standing_change rows, and an auth event without a session id. These are outside the gate's class and are served under the ledger's own grant, as before. Why this differs from the activity gate, which excludes every row that names no parent:
  • the activity stream has no platform producer of such rows;
  • these rows have three producers, and a shipped consumer reads them through the data door (the config_changes view, pinned by the settings dogfood test as the admin);
  • none of them carries a record's field values (the per-writer measurement in audit-log-field-redaction.ts).
• Excluded, fail closed: a record action (create, read, update, delete) that names no record, a record under an object the engine does not know, and a row naming the ledger itself.

Pins

• audit-log-read-visibility.integration.test.ts uses a real kernel, the real AuditPlugin, the real CRUD mirror and a real SQLite driver. It covers find, findOne, count, aggregate, a scoped query, the batching count, every row class, and an admin control. 12 tests.
• audit-log-read-visibility.test.ts covers the class rule, the fail-closed branches, the scan bound and its order pass-through, and the inert seam. 13 tests.
• packages/qa/dogfood/test/audit-log-parent-read-gate.dogfood.test.ts covers the public doors above on a real boot. Each returned row's record is opened through the same door as the same reader. It also covers a row about no record from its real producer (a settings write), a deleted record's rows, and the admin control. 8 tests.
• Composition consequences on other cards' pins (adapted, not weakened):
  • security(plugin-audit): the compliance ledger's create/update rows serve a withheld field's stored value in their before/after snapshots to a reader whose sets grant the ledger read, while the data plane serves that reader without the key #21155's unit test now pins the redaction of rows no non-system door serves on redactAuditLogRows over the row at rest. Its field-values dogfood pin checks the live record's rows.
  • security(plugin-auth): the compliance-ledger row an admin create-user writes carries a withheld user field's value in its decision metadata, which a ledger reader withheld that field is served #21174's admin-ledger pin is described above.

Ablation: put the forbidden behaviour back, red, restore

Both mutations ran from committed state through scripts/ablation-replace.mjs, and each restore was proven: blob equals HEAD and git diff HEAD is empty.

• Mount removed (the one installAuditLogReadVisibility(...) call in audit-plugin.ts; anchor 1 → 0).
  • Leg A, source-resolved: the integration pin gave 8 failed, 4 passed of 12.
  • Leg B, dogfood, resolved from dist/: plugin-audit was rebuilt, and ablation-dist-preflight --absent proved the call gone. The dogfood pin then gave 5 failed, 3 passed of 8.
  • Restore: a rebuild, the preflight proved the call present and the tree clean, and the pin re-ran 8 of 8.
• The class rule widened (a record action naming no record treated as outside the gate): the unit and integration pins gave 6 failed, 19 passed of 25.
• security(plugin-auth): the compliance-ledger row an admin create-user writes carries a withheld user field's value in its decision metadata, which a ledger reader withheld that field is served #21174's pin without the reader view-all grant (the previous head's fixture), on the merged build: its armed check disarmed. All five readers were served no mirror row about the subject.

Verification at HEAD d376985f

Every exit code was captured before any pipe.

• pnpm --filter @objectstack/plugin-audit test: 35 files, 535 tests passed. pnpm --filter @objectstack/plugin-audit typecheck: exit 0, test layer included. pnpm --filter @objectstack/dogfood typecheck: exit 0. plugin-approvals payload-predicate-guard.test.ts: 20 passed.
• Dogfood shard 3/3 (OS_TEST_SHARD=3/3, CI's slice): 54 files passed, 1 skipped; 523 tests passed, 2 skipped.
• Ledger and neighbour pins, 12 files: this PR's dogfood pin; security(plugin-audit): the compliance ledger's create/update rows serve a withheld field's stored value in their before/after snapshots to a reader whose sets grant the ledger read, while the data plane serves that reader without the key #21155's audit-log-field-values; security(plugin-audit): an activity row composed at write time may carry a changed field's values to a reader who can read the parent record but not that field (unmeasured; measure first) #21081's activity-field-values; security(plugin-audit): a filter over the stored activity text answers by row presence: the generic list door evaluates the predicate at rest, before #21081's read-time redaction, so a reader can probe a field value it is not served #21154's activity-text-predicate and audit-log-admin-search; activity-parent-read-gate; auth-session-audit-trail; settings-config-change-audit; admin-identity-audit-trail; security(plugin-auth): the compliance-ledger row an admin create-user writes carries a withheld user field's value in its decision metadata, which a ledger reader withheld that field is served #21174's admin-ledger-decision-metadata (8 of 8 after the fixture change); comments-permission-matrix; membership-actor-attribution. All green: eleven ran at b415f4d7, whose tree differs from this head only in the admin-ledger pin, and that pin ran at this head.
• dispatch-gates --commands: 94 families derived; 93 ran with exit 0 and 1 is NOT MEASURED. spec check:skill-examples exited 0 after the client SDK it reads was built. check:dual-build-cjs-loads exited 3, PREREQUISITE NOT MET: it needs a whole-repo build, and CI runs it. dispatch-gates --ran: 94 accounted for, 0 unrun. main moved again after 1ecb871b; this round merges main once, as dispatched.
• Lint, a declared narrowing: eslint --no-inline-config --format json over the 10 changed TypeScript files reports 10 files linted, 0 errors and 0 warnings. An ignored file would report a warning. eslint.config.mjs sets no parserOptions.project and no typed rule, so this diff cannot move a verdict on an untouched file. The whole-repo pnpm lint runs in CI.

Acceptance notes

• Admins lose the trail of deleted records and of sign-outs on every door that is not system context, including Setup's Audit Logs. The rows stay stored. This is the consequence awaiting the maintainer's decision on security(plugin-audit): sys_audit_log has no parent-record read gate, so a ledger reader is served the rows about a record the data plane answers 404 to (the ledger's #20833) #21175.
• Interim mitigation. domain:engine reports (5936411631 on security(plugin-audit): sys_audit_log has no parent-record read gate, so a ledger reader is served the rows about a record the data plane answers 404 to (the ledger's #20833) #21175) that this gate shrinks [security] The compliance ledger stores a JWT signing-key row's key material in its create snapshot, and an admin is served it through the ledger's by-id door while the key object itself declares no API door #21197's reach to admins: the gate stops serving a member the ledger rows about a key-material record that member cannot open. The admin half of [security] The compliance ledger stores a JWT signing-key row's key material in its create snapshot, and an admin is served it through the ledger's by-id door while the key object itself declares no API door #21197 stands, and that card's own mechanism is separate.
• Scan bound. The shared 2,000-row pre-scan bound now applies to the ledger, which is a larger table than the activity stream. A broad read past the bound fails closed and logs a warning: rows outside the window, and the total they would add, are omitted. A record timeline scopes by object_name and record_id and never reaches the bound.
• Not measured: doors onto the ledger that answer outside the engine's middleware chain (GET /search, the analytics dataset over the ledger, export), and a boot with more than one organization.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-audit, touching 44 documentable anchor(s).

43 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 7c5a311a5829ae3b550a3eeb9bb984f06be8b865.

⛔ 10 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 9 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7c5a311a5829ae3b550a3eeb9bb984f06be8b865 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 150c6c20ebc0f0ec0772cff19b149ffe7d911ff3 — the merge of head d376985f37a411720a0ef33e4acc86ad137d4a36 into base 7c5a311a5829ae3b550a3eeb9bb984f06be8b865, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 150c6c20ebc0f0ec0772cff19b149ffe7d911ff3 && git checkout 150c6c20ebc0f0ec0772cff19b149ffe7d911ff3
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7c5a311a5829ae3b550a3eeb9bb984f06be8b865 d376985f37a411720a0ef33e4acc86ad137d4a36 && git checkout -B drift-repro 7c5a311a5829ae3b550a3eeb9bb984f06be8b865 && git merge --no-ff d376985f37a411720a0ef33e4acc86ad137d4a36

node scripts/docs-audit/affected-docs.mjs --json 7c5a311a5829ae3b550a3eeb9bb984f06be8b865

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 7c5a311a5829ae3b550a3eeb9bb984f06be8b865 → pass the list as
args.docs, on the commit named under Which tree this was computed on.