Skip to content

Commit 13227b5

Browse files
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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
'@objectstack/lint': patch
3+
---
4+
5+
feat(lint): warn when a permission set reads a roll-up summary over child data it cannot read
6+
7+
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 the `RollupSourceVisibilityFinding` / `RollupSourceVisibilitySeverity` types; nothing that passed before is refused.
8+
Metadata-protocol: none
9+
10+
A `summary` (roll-up) field keeps its documented semantics: the engine recomputes it as the system over the whole child collection, and on read it follows only the parent field's own field-level security. So a permission set that can see the summary field still reads the roll-up when it cannot read the aggregated child field, a child field the roll-up's `filter` tests, or the child object, or when it reads only some child rows. Two new author-time findings now say so, for each permission set and each summary field it can see:
11+
12+
- `security-rollup-source-unreadable` (warning) — the set cannot read `summaryOperations.object`, `summaryOperations.field`, or a top-level field key of `summaryOperations.filter`. A `count` reads no value, so its `field` is not judged; its `filter` is.
13+
- `security-rollup-source-row-scoped` (info) — the set reads all of those, but one of its own read-class `rowLevelSecurity` policies on the child, or the child's `defaultRowScope`, narrows which child rows it reads.
14+
15+
"Can read" follows the runtime's three gates: the object grant (its own entry, otherwise `'*'`, which covers a private object only with View All or Modify All), the field entry (`readable: false`, made inert by View All or Modify All on the object), and the capability gate (an object's or field's `requiredPermissions` against the set's `systemPermissions`, which View All and Modify All do not lift). A set holding View All or Modify All on the child is still reported for a capability-gated child object or field, and for a row policy unless the child is private, has tenancy off or is auth-managed, the postures on which the bypass skips row security. A summary field the set cannot see, through any of the three gates on the parent, is not reported.
16+
17+
The fix line names the remedy and its reach: `fields: { 'invoice.total': { readable: false } }` on the set hides the summary field from every holder of that set, and a co-held set with no entry for it does not restore it; to keep it for some holders, declare `readable: true` on it in the sets they hold.
18+
19+
Both findings are advisory: they never fail `os lint`, `os validate` or `os build` (only `--strict` promotes a warning), and the rule does not run at the runtime publish gate. `os explain security-rollup-source-unreadable` and `os explain security-rollup-source-row-scoped` print the full reasoning.

‎content/docs/data-modeling/fields.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -376,6 +376,17 @@ decision that governs the write is the one on the **child**. The parent's own
376376
row is unaffected — a user still needs edit access to change any other field on
377377
it — and the summary column stays subject to the parent's field-level security
378378
on read.
379+
So a permission set that cannot read the aggregated child field, a child field
380+
the roll-up's `filter` tests, or the child object (whether through its object
381+
grant, its field entries or a `requiredPermissions` capability it does not hold),
382+
or that reads only some child rows, still reads the roll-up; `os lint`,
383+
`os validate` and `os build` tell you about each such set
384+
(the `security-rollup-source-unreadable` warning, and the `security-rollup-source-row-scoped`
385+
note — see [the one gate, four doors](/docs/deployment/validating-metadata#the-one-gate-four-doors)).
386+
If the value should not be visible, set `readable: false` on the summary field in
387+
that set: it hides the field from every holder of the set, and another set they
388+
hold with no entry for the field does not restore it, so declare `readable: true`
389+
on the field in the sets whose holders should keep it.
379390
380391
A child validation rule can read a parent summary one hop through its
381392
reference, for example "each supplier has at most one primary contact" as a

‎content/docs/deployment/cli.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -776,7 +776,7 @@ os compile --json # JSON output for CI pipelines
776776
→ Normalizing stack definition...
777777
→ Lowering inline handlers...
778778
→ Validating protocol compliance...
779-
→ Running author-time rules (63)...
779+
→ Running author-time rules (64)...
780780
→ Checking that every required capability has a provider installable in this edition...
781781
→ Collecting package docs (ADR-0046)... 0 collected
782782
→ Writing artifact...

‎content/docs/deployment/validating-metadata.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -524,6 +524,7 @@ orthogonal to both, and no cell here can carry it; it is written out in
524524
| Row-level-security predicates (#4983) — a permission set's policies, an object's `defaultRowScope`, a membership key's `filter` and a field permission entry's `when` (#25866); at the save door also a membership key nothing owns (#25234) | ✓ | ✓ | ✓ | ✓ᵖᵉᵒ |
525525
| Membership key declarations — `userField` / `valueField` columns, one key on one object, a key the registered resolver also owns (save door only) (#25234) | ✓ | ✓ | ✓ | ✓ᵒ |
526526
| Advisory: retired permission residue — the `allowRestore` / `allowPurge` default the parse strips in silence (`permission-retired-lifecycle-residue`, #17425) | ✓ | ✓ | ✓ | ✓ᵖᵉ |
527+
| Advisory: a roll-up a permission set reads over child data it cannot read — the child object, the aggregated child field or a field the roll-up's `filter` tests unreadable to the set, through its grants, its field entries or a `requiredPermissions` capability it lacks (`security-rollup-source-unreadable`, a warning), or child rows a row-level policy narrows (`security-rollup-source-row-scoped`, a note); a roll-up aggregates the whole child collection and follows only the parent field's own permissions | ✓ | ✓ | ✓ | — |
527528
| Platform-schedule `create_record` organization (#6285) | — | — | — | ✓ᶠ |
528529
| Public-form anonymous intake on this deployment's tenancy posture — advisory only (#21476) | — | — | — | ✓ᵛ |
529530
| Public-form file fields — a form open to anonymous intake whose sections declare a `file`, `image`, `avatar`, `video` or `audio` field (#25650) | ✓ | ✓ | ✓ | ✓ᵛ |
@@ -809,7 +810,7 @@ A clean run walks the registry and reports timing:
809810
Config: /path/to/support-desk/objectstack.config.ts
810811
Load time: 21ms
811812
→ Validating against ObjectStack Protocol...
812-
→ Running author-time rules (63)...
813+
→ Running author-time rules (64)...
813814
→ Checking that every required capability has a provider installable in this edition...
814815
→ Checking package docs (ADR-0046)...
815816

‎content/docs/getting-started/build-with-claude-code.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -310,7 +310,7 @@ visible: 'status != "resolved"'
310310
◆ Validate
311311
────────────────────────────────────────
312312
→ Validating against ObjectStack Protocol...
313-
→ Running author-time rules (63)...
313+
→ Running author-time rules (64)...
314314
315315
✗ Author-time rules failed (1 issue)
316316
• stack · action 'resolve_ticket' visible: bare reference `status` — a

‎content/docs/ui/react-pages.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -404,7 +404,7 @@ objectstack validate
404404
────────────────────────────────────────
405405
→ Loading configuration...
406406
→ Validating against ObjectStack Protocol...
407-
→ Running author-time rules (63)...
407+
→ Running author-time rules (64)...
408408
→ Checking that every required capability has a provider installable in this edition...
409409
→ Checking package docs (ADR-0046)...
410410

‎packages/lint/src/authoring-rules.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,7 @@ import { validateSecurityPosture, validateSecurityRoleWord } from './validate-se
140140
import { validateOrgAxisRedLines } from './validate-org-axis-red-lines.js';
141141
import { validateSharingRuleEnforceability } from './validate-sharing-rule-enforceability.js';
142142
import { validateExternalOwnerSharing } from './validate-external-owner-sharing.js';
143+
import { validateRollupSourceVisibility } from './validate-rollup-source-visibility.js';
143144
import { validateRlsPredicateEnforceability } from './validate-rls-predicate-enforceability.js';
144145
import {
145146
validateMembershipKeyDeclarations,
@@ -2551,6 +2552,31 @@ export const AUTHORING_RULES: readonly AuthoringRule[] = [
25512552
surfaceReason: RUNTIME_OBJECT_ADVISORY_VOLUME,
25522553
run: (stack) => validateExternalOwnerSharing(stack),
25532554
},
2555+
// A roll-up `summary` a permission set reads, over child data the same set
2556+
// cannot read — a hidden source field, an unreadable child object, or child
2557+
// rows a row-level policy narrows. The roll-up keeps its documented
2558+
// semantics (system-elevated, the whole child collection, the parent field's
2559+
// own FLS on read); this tells the author so where they configure the set.
2560+
// Advisory: the pair is legal and often meant.
2561+
{
2562+
name: 'validateRollupSourceVisibility',
2563+
tier: 'advisory',
2564+
input: 'parsed',
2565+
commands: ALL,
2566+
source: 'packages/lint/src/validate-rollup-source-visibility.ts',
2567+
surfaces: CLI_ONLY,
2568+
// The precedent the reason below names is #17936, the measured crossing of
2569+
// `validateRetiredPermissionResidue` onto `permission` writes.
2570+
surfaceReason:
2571+
'Advisory-tier rule over permission-set × summary-field pairs: it cannot refuse a write. CLI-only ' +
2572+
'because the crossing it would take is unmeasured: nothing yet measures, per write, what a ' +
2573+
'`permission` save hands this rule (the set, and the parent and child objects it judges the set ' +
2574+
'against), which is the measurement taken before `validateRetiredPermissionResidue` crossed on ' +
2575+
'`permission` writes. Crossing on `permission` writes is therefore a separate decision with that ' +
2576+
'precedent; crossing on `object` writes as well would fall under the RUNTIME_OBJECT_ADVISORY_VOLUME ' +
2577+
'fence. Never a bare `runtimeTypes` edit.',
2578+
run: (stack) => validateRollupSourceVisibility(stack),
2579+
},
25542580
// #4983 — the sibling surface of the rule above, and ADR-0056 D4's gate,
25552581
// which had never been wired to anything: `isSupportedRlsExpression` existed
25562582
// solely so an authoring command could reject a predicate the runtime drops,

‎packages/lint/src/index.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -371,6 +371,20 @@ export {
371371
} from './validate-security-posture.js';
372372
export type { SecurityFinding, SecuritySeverity } from './validate-security-posture.js';
373373

374+
// A roll-up summary a permission set reads over child data the same set cannot
375+
// read: the roll-up aggregates the whole child collection and answers only to
376+
// the parent field's own permissions, so the author is told where they
377+
// configure the set.
378+
export {
379+
validateRollupSourceVisibility,
380+
SECURITY_ROLLUP_SOURCE_UNREADABLE,
381+
SECURITY_ROLLUP_SOURCE_ROW_SCOPED,
382+
} from './validate-rollup-source-visibility.js';
383+
export type {
384+
RollupSourceVisibilityFinding,
385+
RollupSourceVisibilitySeverity,
386+
} from './validate-rollup-source-visibility.js';
387+
374388
export {
375389
validateOrgAxisRedLines,
376390
ORG_AXIS_PERMISSION_INHERITANCE,

‎packages/lint/src/rule-explanations.ts‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -921,6 +921,68 @@ const SECURITY_SUPERUSER_FIELD_MASK_INERT_EXPLANATION: RuleExplanation = {
921921
],
922922
};
923923

924+
const SECURITY_ROLLUP_SOURCE_UNREADABLE_EXPLANATION: RuleExplanation = {
925+
rule: 'security-rollup-source-unreadable',
926+
covers: 'why a roll-up shows child data its reader cannot read',
927+
paragraphs: [
928+
'A `summary` field is a column stored on the parent. The engine recomputes it after every child write, ' +
929+
'as the system and over the whole child collection, so the value is a property of the parent, never of ' +
930+
'one reader\'s view of the children. On read the column answers only to the parent field\'s own ' +
931+
'field-level security. A permission set that cannot read the child object, the aggregated child field, ' +
932+
'or a child field the roll-up\'s `filter` tests therefore still reads the roll-up: the sum, average, ' +
933+
'minimum, maximum or count of child values it cannot read one by one.',
934+
'"Can read" is judged as the runtime decides it, through three gates. The object grant: the set\'s own ' +
935+
'entry for the object, otherwise its `\'*\'` entry, which covers a private object only with View All ' +
936+
'or Modify All. The field entry: `readable: false` hides the field, unless the set holds View All or ' +
937+
'Modify All on the object; a set with no entry for a field reads it. The capability gate: an object\'s ' +
938+
'`requiredPermissions` (the list, or the `read` bucket of the per-operation map) and a field\'s ' +
939+
'`requiredPermissions` refuse the read unless the set\'s `systemPermissions` hold every listed ' +
940+
'capability. View All and Modify All do not lift the capability gate, so a set holding them on the ' +
941+
'child is still reported for a gated child object or field.',
942+
'Reported for each permission set and each summary field the set can see: it reads the parent object ' +
943+
'and the summary field through all three gates. A set that cannot see the column is not reported. A ' +
944+
'`count` reads no value, so its `field` is not judged; the fields its `filter` tests are. Only the ' +
945+
'top-level keys of a `filter` are judged: a dotted key reads through a lookup into another object and ' +
946+
'is not. A child object this stack does not define is not judged. Each set is judged on its own: a ' +
947+
'holder of two sets reads what their union grants, capabilities included.',
948+
'This is a warning, not an error: the pair is legal and is often meant, such as an order total shown to ' +
949+
'staff who may not see line costs. If the value should not be visible to the set, hide the summary ' +
950+
'column for it with `fields: { \'<object>.<summary>\': { readable: false } }`. That entry hides the ' +
951+
'column from every holder of the set, and a co-held set with no entry for the column does not restore ' +
952+
'it, because only sets that declare an entry vote in the field merge (View All or Modify All on the ' +
953+
'parent in a co-held set does restore it); to keep the column for some ' +
954+
'holders, declare `readable: true` on it in the sets they hold. A set that holds View All or Modify All ' +
955+
'on the parent must drop that bit first, because the bypass makes the entry inert. If the set may see ' +
956+
'the child data, grant the read on the child instead.',
957+
],
958+
};
959+
960+
const SECURITY_ROLLUP_SOURCE_ROW_SCOPED_EXPLANATION: RuleExplanation = {
961+
rule: 'security-rollup-source-row-scoped',
962+
covers: 'why a roll-up counts child rows its reader cannot see',
963+
paragraphs: [
964+
'A `summary` field is recomputed as the system over the whole child collection and, on read, answers ' +
965+
'only to the parent field\'s own field-level security. Row-level security on the child narrows which ' +
966+
'child rows a reader sees, not what the roll-up adds up, so a reader whose rows are scoped still reads ' +
967+
'a total, count or extreme taken over every child row of the parent.',
968+
'Reported as a note when the permission set can see the summary column and reads the child object, the ' +
969+
'aggregated field and the fields the roll-up\'s `filter` tests, and its reads of the child meet a row ' +
970+
'policy: one of its own `rowLevelSecurity` entries that applies to a read of the child (not ' +
971+
'`enabled: false`, `object` the child or `\'*\'`, `operation` `select` or `all`) with a `using` ' +
972+
'predicate, or, when it carries no such entry, the child\'s `defaultRowScope`. A set holding View All ' +
973+
'or Modify All on the child skips row security only where the runtime lets it: a private child, a ' +
974+
'child with tenancy off, or an auth-managed one. On any other child its policies still narrow its ' +
975+
'rows and are reported. Only the policy\'s presence is judged, never its predicate: whether a ' +
976+
'predicate admits every row a parent\'s roll-up reads depends on the data. A policy that lists ' +
977+
'`positions` narrows the rows of those holders only, and the note names them. Record sharing ' +
978+
'(`sharingModel`, `readScope`) is not read.',
979+
'If the roll-up should not be visible to the narrowed reader, hide the summary column for the set with ' +
980+
'`fields: { \'<object>.<summary>\': { readable: false } }`. That entry hides it from every holder of the ' +
981+
'set, and a co-held set with no entry does not restore it; declare `readable: true` on it in the sets ' +
982+
'whose holders should keep it. If the total over every row is meant, nothing needs to change.',
983+
],
984+
};
985+
924986
const SECURITY_OWD_ALIAS_EXPLANATION: RuleExplanation = {
925987
rule: 'security-owd-alias',
926988
covers: 'which sharing values are retired or misplaced',
@@ -5717,6 +5779,8 @@ export const RULE_EXPLANATIONS: Readonly<Record<string, RuleExplanation>> = Obje
57175779
[SECURITY_WILDCARD_VAMA_EXPLANATION.rule]: SECURITY_WILDCARD_VAMA_EXPLANATION,
57185780
[SECURITY_MODIFY_ALL_DELETE_WITHHELD_EXPLANATION.rule]: SECURITY_MODIFY_ALL_DELETE_WITHHELD_EXPLANATION,
57195781
[SECURITY_SUPERUSER_FIELD_MASK_INERT_EXPLANATION.rule]: SECURITY_SUPERUSER_FIELD_MASK_INERT_EXPLANATION,
5782+
[SECURITY_ROLLUP_SOURCE_UNREADABLE_EXPLANATION.rule]: SECURITY_ROLLUP_SOURCE_UNREADABLE_EXPLANATION,
5783+
[SECURITY_ROLLUP_SOURCE_ROW_SCOPED_EXPLANATION.rule]: SECURITY_ROLLUP_SOURCE_ROW_SCOPED_EXPLANATION,
57205784
[SECURITY_OWD_ALIAS_EXPLANATION.rule]: SECURITY_OWD_ALIAS_EXPLANATION,
57215785
[SECURITY_DELEGATION_MISSING_REASON_EXPLANATION.rule]: SECURITY_DELEGATION_MISSING_REASON_EXPLANATION,
57225786
[VISIBILITY_ROOT_MISLAYERED_EXPLANATION.rule]: VISIBILITY_ROOT_MISLAYERED_EXPLANATION,

0 commit comments

Comments
 (0)