Repository navigation
Commit 13227b5
feat(lint): warn when a permission set reads a roll-up summary over child data it cannot read (#31046)
security#1 · os-tesla · session_01L9qibvynRbCtMndW8EHNGc
Clause-②: yes (widening) — `@objectstack/lint` exports one new rule
function, `validateRollupSourceVisibility`, its two rule-id constants
`SECURITY_ROLLUP_SOURCE_UNREADABLE` and
`SECURITY_ROLLUP_SOURCE_ROW_SCOPED`, and two finding types; nothing that
passed before is refused.
Metadata-protocol: none
## 维护者速读
- 改了什么:`@objectstack/lint`
新增一条作者期提示规则。权限集能看到父对象上的汇总(roll-up)字段,但读不到子对象、读不到被汇总的子字段、读不到汇总 `filter`
用到的子字段,或子对象行被行级策略收窄时,`os lint` / `os validate` / `os build`
会提示。「能读」按运行时的三道门判断:对象授权、字段条目、`requiredPermissions` 能力门(View All 不解除能力门)。
- 为什么改:按维护者裁决(2026-11-06,选项
A),汇总字段保持已文档化的语义:系统身份按整个子集合重算,读取时只看父字段自己的字段权限。作者配置权限集时需要被告知这一点,此前没有任何提示。
- 风险与回滚:只有 warning 与 info,任何入口都不拒收,默认不会让 `os lint` / `os validate` 失败(仅
`--strict` 会把 warning 当错误);不上运行时发布门禁。示例应用实测:showcase 9 条 warning、2 条
info,crm / todo / multi-package 为 0。回滚即还原本 PR,无迁移。
-
先看:`packages/lint/src/validate-rollup-source-visibility.ts`(三道门与判定顺序);`packages/lint/src/authoring-rules.ts`
新增条目(advisory、只在 CLI
的理由);`packages/lint/src/validate-rollup-source-visibility.test.ts`。
- 两分钟验证:`pnpm --filter @objectstack/lint exec vitest run --maxWorkers=2
src/validate-rollup-source-visibility.test.ts`,预期 43 个测试全绿。
- 需要你做的:无,席位落地
## What changes
A `summary` (roll-up) field keeps its documented semantics: it is a
stored column on the parent, recomputed as the system over the whole
child collection after every child write, and on read it follows only
the parent field's own field-level security
(`content/docs/data-modeling/fields.mdx`, the roll-up section; the "Why
the recompute is system-elevated" docblock in
`packages/objectql/src/engine-summaries-and-expansion.ts`; ADR-0035
"Server-side rollup"). So a permission set that can see the summary
column still reads the roll-up when it cannot read the child data the
roll-up aggregates. Nothing told the author that when they configured
the set. This adds an author-time rule that does.
### "Can read", as the runtime decides it
The rule folds the three gates the runtime applies, on both sides of the
roll-up:
- **Object grant.** The set's own entry for the object, otherwise its
`'*'` entry. A `'*'` entry covers an `access.default: 'private'` object
only with View All / Modify All (`resolveObjectPermission`).
- **Field entry.** `readable: false` hides the field, unless the set
holds View All / Modify All on the object, which votes every field
readable. A set with no entry for a field reads it.
- **Capability gate (ADR-0066 D3).** The read is refused, or the field
hidden, unless the set's `systemPermissions` hold every listed
capability. It reads:
- the object's `requiredPermissions`, as a list or as the `read` bucket
of the per-operation map (`objectReadAdmission` step 4);
- the field's `requiredPermissions` (`foldFieldRequiredPermissions`).
View All and Modify All lift neither.
### What is judged, per permission set × summary field
The pair is judged only when the set can see the summary column. That
means it reads the parent object and the summary field through all three
gates. A set that cannot see the column learns nothing from it and is
not reported.
Then, over the child object `summaryOperations.object` names, in order,
with one finding per pair:
| Arm | Rule id | Severity |
|---|---|---|
| (ii) the set cannot read the child object (no grant, or the object's
read capability missing) | `security-rollup-source-unreadable` | warning
|
| (i) the set cannot read `summaryOperations.field` (`readable: false`,
or the field's capability missing) | `security-rollup-source-unreadable`
| warning |
| (i′) the set cannot read a top-level field key of
`summaryOperations.filter`, by the same test |
`security-rollup-source-unreadable` | warning |
| (iii) all of the above are readable, but the set's reads of the child
meet a row policy (see below) | `security-rollup-source-row-scoped` |
info |
Notes on the arms:
- (i) and (ii) share one id because the consequence and the remedy are
the same.
- A `count` reads no value, so its `field` is not judged. Its `filter`
is judged.
- In a filter, a dotted key reads through a lookup into another object
and is not judged.
- A child object this stack does not define is not judged.
Row policies for (iii):
- **Policies that count:**
- one of the set's own read-class `rowLevelSecurity` entries: `select`
or `all`, on the child or `'*'`, not `enabled: false`, with a `using`;
- when the set carries none of those, the child's `defaultRowScope`.
- **View All / Modify All on the child skips this arm only on the
postures where the runtime's read filter skips business row security**
(`posturePermits` in `security-plugin-rls-filter.ts`):
- a private child;
- a child with tenancy off;
- an auth-managed child.
On any other child the set's policies still narrow its rows and are
noted.
### Example findings (from the test fixture)
```text
permission set "warehouse_staff" · summary field "invoice.total"
"invoice.total" summarizes "invoice_line.amount", which permission set "warehouse_staff" cannot read without capability "finance.read"; a roll-up aggregates the whole child collection and follows only the parent field's own permissions
fix: If its value should not be visible to this set, set fields["invoice.total"]: { readable: false } on it. That hides "invoice.total" from every holder of the set, and a co-held set with no entry for it does not restore it (View All or Modify All on "invoice" does); to keep it for some holders, declare fields["invoice.total"]: { readable: true } in the sets they hold
```
```text
"invoice.high_lines" counts "invoice_line" records filtered on "invoice_line.band", which permission set "warehouse_staff" cannot read without capability "grading"; …
```
The fix line states how far the remedy reaches. In the field merge only
sets that declare an entry vote, so `readable: false` on one set hides
the column from every holder of that set. When the set holds View All or
Modify All on the parent, the fix line says to remove that bit first,
because a `readable: false` entry does not hide a field from a set
holding either.
### Registration
- One `AUTHORING_RULES` entry: `tier: 'advisory'`, `input: 'parsed'`,
all three commands, `surfaces: ['cli']`.
- `surfaceReason` gives the actual reason the rule stays CLI-only:
nothing yet measures, per write, what a `permission` save hands this
rule. Crossing on `permission` writes is a separate decision, with the
measured crossing of `validateRetiredPermissionResidue` (#17936) as the
precedent. Crossing on `object` writes as well would fall under the
`RUNTIME_OBJECT_ADVISORY_VOLUME` fence.
### Files
- `packages/lint/src/validate-rollup-source-visibility.ts` (new): the
rule, the two ids, the finding types.
- `packages/lint/src/authoring-rules.ts`: the registry entry.
- `packages/lint/src/index.ts`: exports the function, the two ids and
the types.
- `packages/lint/src/rule-explanations.ts`: an `os explain` entry for
each id. They cover:
- the three gates;
- the filter fields judged, and dotted filter keys not judged;
- the row-security posture of View All;
- the reach of the remedy.
- `packages/lint/src/validate-rollup-source-visibility.test.ts` (new):
43 cases.
- `content/docs/data-modeling/fields.mdx`: the roll-up section's
sentence on the rule and the reach of the remedy.
- `content/docs/deployment/validating-metadata.mdx`: the rule's row in
the four-doors table, plus the transcript's rule count.
- `content/docs/deployment/cli.mdx`,
`content/docs/getting-started/build-with-claude-code.mdx`,
`content/docs/ui/react-pages.mdx`: the CLI transcript's author-time rule
count, 63 to 64 (`check:docs-transcript-drift`).
- `.changeset/rollup-source-visibility-lint.md`: `@objectstack/lint`
patch.
## Tests
`validate-rollup-source-visibility.test.ts` has 43 cases. Every positive
case runs through the registry runner (`runAuthoringRules`), so the
cases go red when the registration goes.
- **(i) hidden child field:**
- `invoice_line.amount` hidden warns on `invoice.total`, and not on the
`count` beside it;
- the same answer on `lint`, `validate` and `build`, never as an error;
- a set parsed by `PermissionSetSchema` answers what the raw one does.
- **(ii) unreadable child object:**
- no entry on the child;
- an entry with `allowRead: false`;
- a `'*'` read grant beside a private child;
- the count is reported too, and there is one finding per summary.
- **Capability gate:**
- Warns:
- a gated child field the set lacks the capability for;
- several capabilities, with the missing ones named;
- a gated child object, in both the list form and the `{ read }` map
form, with the count included;
- View All / Modify All on the child with a missing field or object
capability.
- Silent:
- a gated summary column, including under View All on the parent;
- a gated parent object, in both forms.
- Controls:
- a held capability reads the field, the object, the summary column and
the parent;
- a map that gates only `update` / `delete` does not gate a read.
- **Filter fields:**
- a filter on a hidden field warns on the filtered count and the
filtered sum;
- a filter on a capability-gated field warns, and holding the capability
is the control;
- every authored filter shape is read: `$and` / `$or`, `$not`, an AST
triple, an AST `and` group;
- silent when every filtered field is readable;
- a dotted key is not judged.
- **(iii) row-scoped note:**
- the set's own `select` policy, an `all` policy, a `'*'` policy, the
child's `defaultRowScope`, and `positions` named in the message;
- policies that do not scope a read are silent: disabled, `update`,
another object, check-only;
- a held read-class policy displaces the default row scope.
- **View All on the child:**
- it makes a hidden child field readable;
- on a public child, the set's read policy and the child's default row
scope are still noted;
- silent on a private child, `tenancy.enabled: false`,
`systemFields.tenant: false` and `managedBy: 'better-auth'`, for both
bits;
- control: a tenancy-off child without the bypass is noted.
- **Other negatives:**
- the set reads the source;
- the summary column is hidden for the set;
- the set cannot read the parent;
- a `'*'` grant over a public child;
- a child this stack does not define.
- **Verdict text:**
- inline snapshots of the message for each arm (hidden field, unreadable
object, capability-gated field, capability-gated filter field, row
policy);
- inline snapshots of the hint, both normal and with View All on the
parent;
- one line each;
- an `os explain` entry for each id;
- the registry entry is advisory and has a `surfaceReason`.
Ablations on 44f8346. Each was a one-shot `node
scripts/ablation-replace.mjs` over the new test file plus
`authoring-rule-wiring.test.ts` (69 tests). Each was restored by `git
checkout HEAD -- <file>`, the restored blob equals HEAD, and the tree
was clean afterwards.
| Ablation | Change | Result | Blob after restore |
|---|---|---|---|
| Registration | the `AUTHORING_RULES` entry deleted | 29 failed / 40
passed | `823eb6d538` |
| Capability gate | `missingCapabilities` always empty | 9 failed / 60
passed: every capability-gate positive and silence case, the capability
filter case and the snapshot case. The controls stay green. |
`f5a9fc04d6` |
| Row-security posture | the posture test forced true | 2 failed / 67
passed: the two public-child View All note cases | `f5a9fc04d6` |
| Filter fields | filter keys dropped | 4 failed / 65 passed: the three
filter positives and the snapshot case | `f5a9fc04d6` |
## Acceptance notes
- **Example apps,** measured on 44f8346 with `os lint --json` and `os
validate --json` (exit 0 on all four):
- `app-showcase`: 9 warnings and 2 notes, the same findings as before
this round;
- `app-crm`, `app-todo`, `app-multi-package`: none.
- No example object or field declares `requiredPermissions`, so the
capability arm adds nothing there.
- Showcase's filtered roll-ups (`rejected_count`, `approved_amount` and
the others on `showcase_expense_report`) are already reported through
the child-object arm for `showcase_member_default`.
- The apps are unchanged.
- Showcase's breakdown:
- `showcase_member_default` cannot read `showcase_expense_line`: 6
warnings;
- `showcase_client_liaison` cannot read `showcase_task`: 2 warnings;
- `showcase_ops` cannot read `showcase_invoice_line`: 1 warning;
- `showcase_contributor`'s `task_own_rows` narrows `showcase_task`: 2
notes.
- **Left out of (iii), by design:** record sharing (`sharingModel`,
`readScope`). Only a policy's presence is judged, never its predicate.
- **Each set is judged on its own:** a holder of two sets reads what
their union grants, capabilities included.
- **Left to separate cards, per the review:**
- the runtime publish gate (option B);
- an acknowledgement for intentional roll-ups, and fixing the showcase
sets after that decision.
- **Not catalogued** in
`skills/objectstack-data/references/lint-rules.md`: that table is a
selection, and `skills/**` is a governed surface.
## Verification
Everything below ran on 44f8346, the head. The commit before it,
ee601bf, is the fix round; 44f8346 only moves a tracker id out of
the `surfaceReason` string into an adjacent comment.
- `pnpm --filter @objectstack/lint test`: Test Files 197 passed (197),
Tests 8331 passed.
- `pnpm --filter @objectstack/lint typecheck`: exit 0
(`check:test-typecheck: OK`). The public surface is unchanged from the
previous head (same exports, same types), so the consumer typecheck from
the first round (77 of 77 turbo tasks) still covers it. `Type Check ·
consumer gates` and `Type Check · workspace` are green on this head.
- `node scripts/pm/dispatch-gates.mjs --commands` on 44f8346: 88
commands, each run with stdin from `/dev/null`, all exit 0, including
`check:doc-authoring`. `--ran` with the recorded exit codes: 88 derived,
88 run, 0 NOT-MEASURED, 0 UNRUN.
- `node scripts/pm/check-governed-merges.mjs --branch
origin/claude/sec-hardening-r14`: NOT governed, 0 of 11 paths, 1228
changed lines (+1224 / −4).
- CI on 44f8346: 57 success, 8 skipped, 0 failure.
- Dogfood: not derived (no `!` in the title, no `(narrowing)` arm).
---
_Generated by [Claude
Code](https://claude.ai/code/session_01L9qibvynRbCtMndW8EHNGc)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent b5106af commit 13227b5
11 files changed
Lines changed: 1224 additions & 4 deletions
File tree
- .changeset
- content/docs
- data-modeling
- deployment
- getting-started
- ui
- packages/lint/src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
376 | 376 | | |
377 | 377 | | |
378 | 378 | | |
| 379 | + | |
| 380 | + | |
| 381 | + | |
| 382 | + | |
| 383 | + | |
| 384 | + | |
| 385 | + | |
| 386 | + | |
| 387 | + | |
| 388 | + | |
| 389 | + | |
379 | 390 | | |
380 | 391 | | |
381 | 392 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
776 | 776 | | |
777 | 777 | | |
778 | 778 | | |
779 | | - | |
| 779 | + | |
780 | 780 | | |
781 | 781 | | |
782 | 782 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
524 | 524 | | |
525 | 525 | | |
526 | 526 | | |
| 527 | + | |
527 | 528 | | |
528 | 529 | | |
529 | 530 | | |
| |||
809 | 810 | | |
810 | 811 | | |
811 | 812 | | |
812 | | - | |
| 813 | + | |
813 | 814 | | |
814 | 815 | | |
815 | 816 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
310 | 310 | | |
311 | 311 | | |
312 | 312 | | |
313 | | - | |
| 313 | + | |
314 | 314 | | |
315 | 315 | | |
316 | 316 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
404 | 404 | | |
405 | 405 | | |
406 | 406 | | |
407 | | - | |
| 407 | + | |
408 | 408 | | |
409 | 409 | | |
410 | 410 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
140 | 140 | | |
141 | 141 | | |
142 | 142 | | |
| 143 | + | |
143 | 144 | | |
144 | 145 | | |
145 | 146 | | |
| |||
2551 | 2552 | | |
2552 | 2553 | | |
2553 | 2554 | | |
| 2555 | + | |
| 2556 | + | |
| 2557 | + | |
| 2558 | + | |
| 2559 | + | |
| 2560 | + | |
| 2561 | + | |
| 2562 | + | |
| 2563 | + | |
| 2564 | + | |
| 2565 | + | |
| 2566 | + | |
| 2567 | + | |
| 2568 | + | |
| 2569 | + | |
| 2570 | + | |
| 2571 | + | |
| 2572 | + | |
| 2573 | + | |
| 2574 | + | |
| 2575 | + | |
| 2576 | + | |
| 2577 | + | |
| 2578 | + | |
| 2579 | + | |
2554 | 2580 | | |
2555 | 2581 | | |
2556 | 2582 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
371 | 371 | | |
372 | 372 | | |
373 | 373 | | |
| 374 | + | |
| 375 | + | |
| 376 | + | |
| 377 | + | |
| 378 | + | |
| 379 | + | |
| 380 | + | |
| 381 | + | |
| 382 | + | |
| 383 | + | |
| 384 | + | |
| 385 | + | |
| 386 | + | |
| 387 | + | |
374 | 388 | | |
375 | 389 | | |
376 | 390 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
921 | 921 | | |
922 | 922 | | |
923 | 923 | | |
| 924 | + | |
| 925 | + | |
| 926 | + | |
| 927 | + | |
| 928 | + | |
| 929 | + | |
| 930 | + | |
| 931 | + | |
| 932 | + | |
| 933 | + | |
| 934 | + | |
| 935 | + | |
| 936 | + | |
| 937 | + | |
| 938 | + | |
| 939 | + | |
| 940 | + | |
| 941 | + | |
| 942 | + | |
| 943 | + | |
| 944 | + | |
| 945 | + | |
| 946 | + | |
| 947 | + | |
| 948 | + | |
| 949 | + | |
| 950 | + | |
| 951 | + | |
| 952 | + | |
| 953 | + | |
| 954 | + | |
| 955 | + | |
| 956 | + | |
| 957 | + | |
| 958 | + | |
| 959 | + | |
| 960 | + | |
| 961 | + | |
| 962 | + | |
| 963 | + | |
| 964 | + | |
| 965 | + | |
| 966 | + | |
| 967 | + | |
| 968 | + | |
| 969 | + | |
| 970 | + | |
| 971 | + | |
| 972 | + | |
| 973 | + | |
| 974 | + | |
| 975 | + | |
| 976 | + | |
| 977 | + | |
| 978 | + | |
| 979 | + | |
| 980 | + | |
| 981 | + | |
| 982 | + | |
| 983 | + | |
| 984 | + | |
| 985 | + | |
924 | 986 | | |
925 | 987 | | |
926 | 988 | | |
| |||
5717 | 5779 | | |
5718 | 5780 | | |
5719 | 5781 | | |
| 5782 | + | |
| 5783 | + | |
5720 | 5784 | | |
5721 | 5785 | | |
5722 | 5786 | | |
| |||
0 commit comments