fix(plugin-security)!: a field the caller may not read is judged as a cross-field comparand exactly as it is as a filter key (#20932)

[objectstack-fleet]

Fixes #20932
Clause-②: no (narrowing)

What this changes

The security layer's field predicate guard refuses a query that filters, sorts, groups or aggregates by a field the caller's field-level permissions hide (403 PERMISSION_DENIED), because which rows answer would disclose the value the field mask withholds. It collected the fields a condition names from the condition's keys only, so a hidden field named only as a cross-field comparand was never judged by that rule.

collectConditionFields now also collects the field every cross-field comparand inside a field constraint names, into the same set, and the existing field rule judges it. One collection, one rule, no second guard. A hidden field as a comparand now answers the same refusal (code, status and body) as the same hidden field written as a key.

Dispatched by the domain:services seat (seat post #6021), session session_01XY5uCwTjZj7884yYtyur4H; claim comment 5919655256, triage direction 5919556782.

Per position (disclosure-safe: classes, no request shapes)

Comparand position the filter grammar admits	Door	Before (class)	After
The whole comparand of a scalar comparison (each of $eq $ne $gt $gte $lt $lte)	data read	served: the comparison was answered	403 PERMISSION_DENIED, body equal to the key form's
Under a logical group ($and, $or, $not, and nested groups)	data read	served	same refusal as the key form
The whole-day offset wrapper: its base reference	data read	served	same refusal as the key form
The whole-day offset wrapper: its offset column	data read	served	same refusal as the key form
The query condition of a grouped query (plain, and under $or)	aggregate path	served	same refusal as the key form
A per-aggregation filter	aggregate path	served	same refusal as the key form
having	guard (unit pin)	not collected	collected, same refusal as the key form at the guard; not pinned through a route (see Acceptance notes)
A member of a list operator, an endpoint of a range operator	none	not a comparand position: the grammar refuses a reference there	unchanged, not pinned

A comparand naming a field the caller may read is served as before (the control, in every position above).

Mechanism readings

• D1, the collector and its callers. collectConditionFields is called by itself (logical groups) and by collectQueryFields (where, having, each aggregation's filter). collectQueryFields is called only by assertReadableQueryFields, which has one call site: the security plugin's engine middleware, for every verb that carries a predicate (the read, findOne, count and aggregate on the caller's query; bulk update / delete on the caller's own condition). The package index re-exports all three; no in-repo consumer outside tests. So the aggregate path is not a separate caller: it gets the widened collection through the same call.
• D2, the comparand reader. FieldReferenceSchema from @objectstack/spec/data, the grammar's exported declaration of a cross-field reference (including the whole-day offset's own nested reference). No function that yields the referenced field is exported: the filter module's and the driver readers' reference predicates are module-private. So each node of a field constraint is asked of the schema itself (safeParse), the same reading objectql's having filter already takes. The walk carries no operator list and no position list: it visits every node of the constraint, so a position the grammar admits is covered without being named. packages/spec/src, packages/objectql/src and service-analytics are untouched.
• D3, positions. The grammar admits a reference as the whole comparand of the six scalar comparisons, with or without the whole-day offset (whose offset may itself be a reference), under any logical nesting, in each clause that carries a condition. It refuses one as a list member or a range endpoint. Every admitted position is pinned.
• D4, the refusal. The key form is the reference: the route pins read it first, per hidden field and per path, and require the comparand form's status and whole body to equal it; the unit pins require equal code, status, message and details.
• D6, Clause-②. Widening measured absent: no export added or removed (the package index and manifest are untouched, the new helper is module-private), and the collected set only grows, so nothing refused before is served now. Narrowing measured present: on the pre-fix source, all 15 route refusal pins answered 200 where the fix answers 403. Line 2 read by scripts/pm/clause2-line.mjs (readClause2Line): declared, value no, arm narrowing. The changeset is minor with the BREAKING banner and its ADR-0087 marker.

Pins, red/green and ablation

Commits: the pins (9e602fe84, red on that commit by design), the fix (3b34899fc), the changeset wording (215bc699b, HEAD). Pushed together only after the fix was committed.

• packages/plugins/plugin-security/src/predicate-guard.test.ts: the collection and the verdict, per position, with the key form as the reference and a readable-comparand control.
• packages/rest/src/data-field-comparand-permission.test.ts: the real SecurityPlugin on a real ObjectQL over a real SqlDriver, through the data query route, on the data read and the aggregate path, each refusal compared with the key form's, each position with its readable control.

All readings below were taken on HEAD 215bc699b.

• Red/green on the committed tree (predicate-guard.ts restored from the pins commit, pins at HEAD, package rebuilt and the built output proven to carry no comparand collection): unit 23 failed / 12 passed (35), route 15 failed / 15 passed (30). Every refusal pin red, every control green. Green leg (restored from HEAD by absolute path, blob equal to the HEAD blob, git diff HEAD 0 bytes, rebuilt, fix proven present in the built output): unit 35/35, route 30/30.
• Ablation of the widened collection (the collector's call replaced by a no-op reference so the package still compiles; the mutation proven on disk by anchor count 1 to 0 and blob change; rebuilt; built output proven without the call): predicted unit 23 failed / 12 passed and route 15 failed / 15 passed; observed exactly that. Restored: blob equal to the HEAD blob, git diff HEAD empty, rebuilt, the call present in the built output again. A first attempt that deleted the call outright did not build (the helper became unused), so the suite would have read a stale build; it was discarded and is not counted.

Tests and gates

• pnpm --filter @objectstack/plugin-security test: 149 files passed; 3252 passed, 23 skipped. Exit 0.
• pnpm --filter @objectstack/plugin-security typecheck: exit 0 (source, scripts, and the test layer under tsconfig.test.json, 0 debt entries).
• pnpm --filter @objectstack/rest test: 244 files passed; 4895 passed, 114 skipped. Exit 0.
• pnpm --filter @objectstack/rest typecheck: exit 0; the new route pin is in the program.
• Gates: node scripts/pm/dispatch-gates.mjs --commands at 215bc699b derives 64 commands; those plus the 4 roster families named at dispatch (check-changeset-fixed, check:authz-resolver, check:error-code-casing, check:filter-alias-parity) were run one at a time, each exit code captured before any pipe: 68 of 68 exit 0. A full build (72 tasks) preceded the gates that read built output. Reconciliation: ✓ dispatch-gates --ran: 64 derived famil(ies) accounted for — 64 run, 0 NOT-MEASURED.
• Lint, narrowed and proven: the population is the three changed TypeScript files (eslint's own config applies to each; it ignores the changeset); eslint --no-inline-config --format json reports 3 files, 0 errors, 0 warnings; this repo's config enables no type-aware linting, so the diff cannot move the verdict on any untouched file. The repo-wide pnpm lint is CI's.
• The client envelope-caller census needs no row: the pins call no censused client method.

Acceptance notes

• having: a comparand there is collected and pinned at the guard (unit); it is NOT MEASURED through a route.
• findOne, count, bulk update / delete: covered by construction (the guard's single call site serves every verb that carries a predicate) and by the collector pins; not pinned per verb in the committed suite.
• Analytics: inherits the fix through the engine path; not touched and not pinned here. Its own gate is security(analytics): the native-SQL strategy answers a query naming a field the caller has no field-level read permission for, where the engine and the ObjectQL strategy refuse 403 #20917's (PR fix(service-analytics)!: one field-level read gate at the analytics door, before either strategy (#20917) #20931).
• A comparand inside a nested-relation condition is collected by the same walk and judged against the queried object's own field permissions (the refusing direction). NOT MEASURED.
• Drivers: the route pin runs on SQLite only; the guard runs before any driver.
• main moved: origin/main is at 013f97df9, 8 commits past this branch's base 1571aedce (read just before this PR opened). None touches this claim's surface, so the branch is not merged (per the dispatch order); this PR's CI on the merge ref reads the merged tree. dispatch-gates flagged three of its derivation inputs as changed on main (two ADR-anchor files for other packages and the doc-authoring prose-id baseline); the derived family list is unchanged.
• CI: not awaited; the CI-only lanes dispatch-gates names (the test shards, temporal conformance, dogfood, build core, the workspace type-check lanes, the artifact-roster and wide-population families) are CI's.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

2 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• 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 — 16 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 013f97df93ed66d0aeec45ec1d507da303991260 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 4c872c3218cf3c889e77273f9b8ab553329c1245 — the merge of head 215bc699b144e8436b8908d01f4a0f40dc51c306 into base 013f97df93ed66d0aeec45ec1d507da303991260, 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 4c872c3218cf3c889e77273f9b8ab553329c1245 && git checkout 4c872c3218cf3c889e77273f9b8ab553329c1245
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 013f97df93ed66d0aeec45ec1d507da303991260 215bc699b144e8436b8908d01f4a0f40dc51c306 && git checkout -B drift-repro 013f97df93ed66d0aeec45ec1d507da303991260 && git merge --no-ff 215bc699b144e8436b8908d01f4a0f40dc51c306

node scripts/docs-audit/affected-docs.mjs --json 013f97df93ed66d0aeec45ec1d507da303991260

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

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 215bc699b144e8436b8908d01f4a0f40dc51c306
Local-runs: none

Read at 2026-09-30T22:59Z: card #20932 (body and its 4 comments: triage 5919556782, claim 5919655256, dev report 5921030474, seat ACCEPT 5921051412 — the last is context, not an input to this verdict), PR #20954 (body, 4-file list, 1 comment, net diff against main from merge base 1571aedce), and the check-runs on the head. Disclosure discipline (security family) holds in this record: classes and positions only, the card's own vocabulary, no request shape, no field spelling from the pins, no returned value beyond the code the card names.

Check-runs on the head, latest run per name, read 2026-09-30T22:54Z: 34 names — 31 success, 3 skipped (Build Docs, Console Pin Gate, Packed-tarball smoke opt-in), 0 failure, 0 in progress. Check Changeset (which runs the ADR-0087 registration gate and the level-axis gate against the merge base) and Lint & Repo Gates are among the 31. Nothing is pending, so this verdict is unconditional.

① Derived judgments

Read off the diff against the pre-fix source, the guard's one call site (security-plugin.ts, step 2.9 of the engine middleware) and the filter grammar at the head (FieldReferenceSchema, packages/spec/src/data/filter.zod.ts).

1. Accept-set NARROWING at the field predicate guard — right. collectConditionFields now also walks each non-logical key's value and adds the first segment of every node that FieldReferenceSchema.safeParse accepts, into the one set the existing rule judges. A query whose field constraint carries a cross-field comparand naming a field the caller may not read is refused with the key form's refusal (same constructor, same reason, same offending-field detail), where before it was served. This is triage's direction 5919556782 verbatim: one collection, one rule, no second guard, no operator or position list. The set only grows, so nothing refused before is served now.
2. Reach of the collection — right, and derived from the grammar, not a list. collectQueryFields calls the collector on where, having and each aggregation's filter, so all three clauses inherit it. The grammar at the head admits a reference as the whole comparand of the six scalar comparisons and in the whole-day offset wrapper (the wrapper's own nested reference is a { $field }-only shape, which FieldReferenceSchema also accepts, so the offset column is collected too — pinned); it refuses a reference as a list member or a range endpoint. In those two refused positions a reference naming a hidden field now meets the guard's 403 before the grammar's 400 — the same order the key form already has — and the changeset states it. Right.
3. Every predicate-carrying verb, one call site — right. assertReadableQueryFields is called once, at step 2.9, on the caller's AST for the read, findOne, count and aggregate, and on the caller's own where for bulk update / delete; the collector walks that where too. The aggregate path is therefore not a separate caller: grouped bodies sent through the data query route reach the engine's aggregate verb and the same middleware. The step runs BEFORE RLS injection (step 3), so a row-level policy that compares against a hidden field is untouched — which the changeset also says. The guard's permission map already folds the ADR-0090 D10 delegator intersection and the spec/security: field masking is all-or-nothing — no partial masking (phone last-4, ID middle-8), and maskingRule was pruned as dead in 2026-06 #8993 partial-mask fold, so a comparand naming a masked-for-this-caller field is refused by the same fold, with no second list. Right.
4. Dotted comparand gated on its first segment — right; identical to the key rule, so a relation traversal in a comparand is judged by the local relation field's permission exactly as a dotted key is.
5. Public surface — no widening, right. No export added or removed; collectConditionFields, collectQueryFields and assertReadableQueryFields keep their signatures and return a superset only for inputs that carry a reference; the new helper is module-private. @objectstack/spec was already a dependency of plugin-security and ./data is an existing subpath export, so the new import moves no manifest. packages/spec/src, packages/objectql/src, service-analytics and every governed surface are untouched; the four files are all inside the claim's file surface; head repo is the base repo.
6. The nested-relation corner — right as a security fix, wording corrected (carried to ③). Inside a nested-relation condition the walk collects a comparand reference and judges it against the QUERIED object's permission map, while a nested KEY there is not collected (pre-existing rule: gate on the relation field). So the two forms are not symmetric in that corner; the asymmetry is fail-closed — at worst an over-refusal when a related-object field name coincides with a hidden or masked local field — and it can never serve a local hidden field. The related object's own hidden fields are judged by neither form; that is pre-existing and outside this card's class.
7. Refusal-equality pins — right. The route pins read the key form's refusal per hidden field and per path FIRST and hold the comparand form to the same status and whole body; the unit pins hold code, status, message and details equal; a readable comparand is the control in every position on both paths. The red/green (unit 23 red / route 15 red on the pins commit, all green at the head) and the ablation (collector call made a no-op, predicted = observed, restore proven) are the dev's readings on the head; the check-runs on the head (Test Core 1–6, type-check lanes) are the gate verdicts, and they are green.
8. Disclosure — right. The card, the PR body, the changeset text (which ships in CHANGELOG.md) and the three commit messages state the gap by class and position; the only request shapes are inside the two pin files, which the claim's file surface names. Commit trailers are the model-free pair.

② Semver level

• Changeset .changeset/20932-predicate-guard-comparand.md: @objectstack/plugin-security: minor, the BREAKING banner, a migration paragraph, and exactly one ADR-0087 marker: not-required (no-migration-prescription).
• Level — right. A no (narrowing) is BREAKING (AGENTS.md Post-Task §3); during the launch window a breaking change ships as minor and never major (check-changeset-no-major). patch would be wrong (the change is not a fix of what the guard already refused; it narrows what is served), and skip-changeset would be wrong (a released package's runtime behaviour moves). The PR title's ! marker agrees.
• ADR-0087 disposition — right. No authorable key, spelling, export or stored shape moves, so objectstack migrate meta has nothing to rewrite; the body's "grant the field's read permission, or compare against a readable field" is operational guidance to an administrator, not a code-rewrite prescription, so the category's one mechanical refusal does not bite. The gate that reads this (Check Changeset) concluded success on the head.
• No changeset for @objectstack/rest — right: the diff adds a test file there and nothing that publishes.
• Clause-②: line: no (narrowing) — right on both halves. no: no new export and no new accepted input, so nothing widens. (narrowing): measured present — every route refusal pin answered served on the pre-fix source and refused at the head. The line is spelled identically in the PR body (line 2), the fix commit and the changeset.

③ Boundary flags

open_questions in the dev report: none — nothing to answer.

Dev flags (PR Acceptance notes, out_of_scope_findings, deviations), each answered:

1. A comparand inside a nested-relation condition (out_of_scope_findings[0], carrier none, NOT MEASURED) — answered with a correction. The dev's "can only over-refuse, never serve a hidden field" holds for the queried object's fields; the precise shape is ① item 6: comparand collected, nested key not, judged against the local permission map, fail-closed. Acceptable for a p0 security fix in this direction. Disposition per the finding rule (no carrier ⇒ Acceptance notes) stands; if the owning seat later measures a reach for the over-refusal (a related-object field name coinciding with a hidden local field, under a grammar that resolves the reference on the related row), it is a class-c card of its own — not a hold on this PR.
2. having pinned at the guard only, not through a route — answered: the guard walks having through the same collectQueryFields call as where; whether a route carries having is [P2] data: QueryAST declares 12 members no executor runs — the liveness ledger governs metadata types, not the request surface #4286's open enforce-or-remove question, not this card's. Accepted.
3. findOne, count, bulk update / delete not pinned per verb — answered by construction, verified at the one call site (① item 3). Accepted.
4. Analytics not touched, not pinned — answered: outside the claim by the order's exclusion; it inherits the collection through the engine path; its own gate is security(analytics): the native-SQL strategy answers a query naming a field the caller has no field-level read permission for, where the engine and the ObjectQL strategy refuse 403 #20917's. Accepted.
5. Drivers (route pin on SQLite only) — answered: the guard runs in engine middleware before any driver is reached. Accepted.
6. main moved 8 commits past the base, branch not merged — answered: no commit touches the claim's surface; CI ran on the merge ref and is green. Accepted.
7. CI not awaited by the dev — answered here: every check on the head has concluded (see the roster above); nothing pending.
8. Four runs, three restarts; PR opened and assigned by the previous run; measurements re-used with recorded exit codes; ablation taken on the fix commit whose diff to the head is one changeset line — answered: the re-used readings are each tied to the head sha, and the ablation's tree differs from the head only in a file no test reads. No second write was spent. Accepted.
9. No empty-branch probe push — answered: the order's disclosure clause forbids a push before the fix is committed on the pins; the first push carried both. Accepted.
10. Docs drift check: nothing to list — answered: the guard's documented rule ("filtering, sorting, grouping or aggregating by a hidden field is refused") is strengthened, not contradicted; no hand-written page names the collector. No flag.

Escalations: none. Landing note for the owning seat: no governed path is touched, so this record is not a Tier S carrier; the ordinary landing rule applies (the PR is still a draft).

Implemented-by: claude/issue-20932-predicate-guard-comparand
Reviewed-by: session_01XY5uCwTjZj7884yYtyur4H

VERDICT: PASS

---

Generated by Claude Code