Skip to content

Commit 51a12c0

Browse files
feat(lint): warn when a permission set's own View All / Modify All makes its field mask inert (#29724)
<!-- claude-projects-attribution: {"github_login":"os-warren"} --> _Requested by **Warren** · [project thread](https://claude.ai/code/project/chan_01U5RdnAAmkSQmZbqh6FtqZ8?thread=cmsg_01U5RdnAAmkSQmZbqh6FtqZ8W3xWg9UzvjKRfew8ju8Fz6)_ Fixes #29544 Clause-②: yes (widening) Metadata-protocol: none ## 维护者速读 - 改了什么:`@objectstack/lint` 新增一条 warning 规则 `security-superuser-field-mask-inert`。权限集在某对象上持有「查看全部」或「修改全部」,同一集合又对该对象的字段写了 `readable: false`(或在「修改全部」下的编辑锁)时,提示这个遮罩对持有人不生效,并给出改法。 - 为什么改:按 #29106 的裁决 A,超级用户位对该对象的每个字段都投 readable/editable 票,同集合的遮罩成了摆设;作者以为字段藏住了,其实没有,仓里已有两个测试夹具因此被修过。 - 风险与回滚:只是 warning,任何入口都不拒收(运行时发布门禁实测记为 advisory)。示例、showcase、平台默认权限集普查均为 0 条。回滚即还原本 PR,无迁移。 - 先看:`packages/lint/src/validate-security-posture.ts` 中新规则段(紧挨 Modify All 删除段之前)与 `holdsSuperuserBypass` 副本;`packages/cli/test/superuser-bypass-mirror-parity.test.ts`。 - 两分钟验证:`pnpm --filter @objectstack/lint exec vitest run --maxWorkers=2 src/validate-security-posture.test.ts -t inert`,预期 8 个测试全绿。 - 需要你做的:无,席位落地 ## What changes After ruling A on #29106 (ruling of record 6573563853), a permission set that holds View All or Modify All on an object votes on every field of that object in both field merges (`superuserFieldVote` in `@objectstack/core`). So the same set's `readable: false` on that object hides the field from none of its holders, and under Modify All its edit lock (`editable: false`, or `editable` omitted, which parses to false) holds none of them back. The pair is legal, so nothing warned the author. New rule id `security-superuser-field-mask-inert`, severity **warning**, pushed from `validateSecurityPosture`'s permission-set loop. That function is the existing `validateSecurityPosture` entry in `AUTHORING_RULES`, so the warning runs on `os lint`, `os validate`, `os build` and the runtime publish gate for a `permission` write (measured on the built `runtime.js`: `runRuntimeAuthoringRules({ type: 'permission', … })` returns it under `advisories`, `errors` empty). - `viewAllRecords` beside `readable: false` → finding. - `modifyAllRecords` beside `readable: false` or an edit lock → finding; one finding per entry, naming both when both are inert. - `viewAllRecords` beside an edit lock → no finding (View All never widens a write, so the lock binds). - One set at a time: another set's bypass also unmasks a holder of both sets, but no author wrote an inert entry there. Example message: `viewAllRecords on objects.sys_user votes on every field of "sys_user", so readable: false on 'sys_user.email' binds none of this set's holders`. Hint: remove the bit and reach the rows with `readScope` / `writeScope` or a row-level policy, or delete the entry if the bypass is meant. **The bypass reading.** `@objectstack/lint` depends on `@objectstack/spec` alone, so it cannot import core. `holdsSuperuserBypass` is copied verbatim into `validate-security-posture.ts` (the `objects[name] || objects['*']` lookup, `Boolean(...)` bits, Modify All implies View All) and exported from the lint barrel under the same name. `packages/cli/test/superuser-bypass-mirror-parity.test.ts` imports core's function and lint's copy and asserts they answer alike over a 410-case matrix (own entry × wildcard entry, each absent / null / empty / view / modify / both / false / truthy and falsy non-booleans, × object × bit, plus sets with no usable `objects`). The seat ruled this route (claim amendment 6593310531). The entry's bits are read as parsing writes them: an omitted `readable` is `true`, an omitted `editable` is `false`. A raw set and its parse give the same answer (pinned). Files (6, +402 / -1): - `packages/lint/src/validate-security-posture.ts`: the id, the `holdsSuperuserBypass` copy, the arm, a header table row. - `packages/lint/src/rule-explanations.ts`: the id's `os explain` entry. - `packages/lint/src/index.ts`: exports the id and `holdsSuperuserBypass`. - `packages/lint/src/validate-security-posture.test.ts`: a new top-level `describe` (8 cases), plus the file's meta-guards: the id in `RULE_IDS`, a reachability-corpus fixture, push-site count 19 → 20, read surfaces `set` / `op` / `mask`, and `inertBits` under plumbing. - `packages/cli/test/superuser-bypass-mirror-parity.test.ts`: the parity pin (new file). - `.changeset/29544-superuser-field-mask-inert.md`: patch for `@objectstack/lint`. New public names: the rule id and the `holdsSuperuserBypass` export from `@objectstack/lint` (same name as core's on purpose: it is the same function). ## Why The two repo fixtures the card names (`resume-decider-identity.integration.test.ts`, `explain-principal-person.test.ts`) went inert silently and were repaired by #29387. The composed sets in `admin-ledger-decision-metadata.dogfood.test.ts` are built from shared consts, so a grep for the pair does not find them. Reading the normalized set does. ## Tests `validate-security-posture.test.ts`, new `describe` "a field mask its own set's View All / Modify All makes inert". Each case is a set parsed by `PermissionSetSchema` unless it says otherwise: 1. The resume-decider fixture before its repair (Modify All + `restricted_note` edit lock) → one warning. 2. The explain-principal-person fixture before its repair (View All + `email` read mask) → one warning. 3. The admin-ledger dogfood's composed sets, spelled from shared consts as that file does: `ald_withhold_set` and `ald_withhold_only_set` each fire once on `sys_user.email`; the `editable: false` grants beside View All and `ald_unmask_set` fire nothing. 4. Modify All + `readable: false` → warning; View All + edit lock → nothing. 5. Wildcard: `'*'` Modify All with no entry for the object → warning; `'*'` Modify All plus an explicit entry without the bit → nothing (lookup, not merge). 6. Unparsed `{ readable: true }` under Modify All → warning, and equal to the parsed set's answer. 7. Controls: the two fixtures as repaired (row policy + mask; org read/write depth + lock), and a bypass in one set beside a mask in another → nothing. 8. One-line message (≤ 200 chars) and hint, naming the bit and the entry; `explainRule` defined for the id. Red first, on `61adbe57` (tests plus the id constant, no arm): 7 failed, 1 passed (the control case). Parity: `pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2 test/superuser-bypass-mirror-parity.test.ts`: 3/3. Ablation of the parity pin (rule committed first; `node scripts/ablation-replace.mjs`, run under a restore trap): in lint's copy, the anchor `const op = (objects[objectName] || objects['*']) as` was replaced with the wildcard-first lookup (anchor 1 → 0, blob `df680307` → `37845e72`). `pnpm --filter @objectstack/lint build`, then `node scripts/ablation-dist-preflight.mjs @objectstack/lint 'objects["*"] || objects[objectName]' --source-marker=…`: marker in 4 built files, tree reading passed, exit 0. Parity test: 2 failed, 1 passed, with 60 diverging cases listed. Restored: blob equals HEAD `df680307`, `git diff HEAD` empty. After a rebuild, the preflight `--absent` check exited 0 (marker absent from all 20 built files, tree clean), and the parity test passed 3/3. ## Acceptance notes - Census, run with the rule on built `dist/` over loaded modules: `examples/app-crm` 2 sets → 0; `examples/app-todo`, `examples/app-multi-package` 0 sets; the showcase (`examples/app-showcase/src/security/permission-sets.ts`) 9 sets, 2 with field entries → 0; the platform baseline (`plugin-security`'s `default-permission-sets.ts`) 9 sets, 6 with field entries → 0. - Test fixtures can't be loaded outside vitest, so they were read by hand, not run. 24 files carry both a bypass bit and a field entry. Only the admin-ledger dogfood's two composed sets would fire (case 3). The two repaired fixtures are clean. The rest put the bit and the mask in different sets (`fls-superuser-vote*`, `explain-engine`), on different objects (`delete-reference-cleanup-system-identity`), or on a `'*'` entry without the bits (`security-plugin.test.ts`). - Noted, not filed: by the same ruling, the admin-ledger dogfood's `withheld` and `wildcard` readers are not actually withheld `email`: their own set's View All on `sys_user` unbinds the mask. That file's header calls the View All "a row-scope grant, not a field one". The file still passes, because it asserts that no reader is served a subject row at all (deployment-level rows), so no assertion depends on the mask. It is not edited here, since the census does not force it. Carrier: none; the seat decides. - A `when`-conditioned edit lock under Modify All is reported like any other lock, because the merge applies the super-user vote under every `when` verdict (plugin-security's explain report already calls such an entry superseded). The spec refuses `readable: false` beside `when`, so no conditioned read mask exists to judge. ## Verification <details><summary>Package suites and typecheck</summary> All on head `c20d3a56` (after the second `origin/main` merge, which auto-merged a sibling rule's lines in `index.ts` and `rule-explanations.ts`), after `pnpm --filter '@objectstack/core...' --filter '@objectstack/lint...' build`: - `pnpm --filter @objectstack/lint exec vitest run --maxWorkers=2`: Test Files 192 passed (192); Tests 7942 passed (7942). - `pnpm --filter @objectstack/lint typecheck`: exit 0 (`tsc --noEmit` and `check:test-typecheck: OK`, debt unchanged at 2 files / 6 errors). - `pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2 test/superuser-bypass-mirror-parity.test.ts`: 3/3. - `packages/cli` typecheck: narrowed, and declared here. Its full `tsc` needs the 63-package build closure, so it is left to `TypeScript Type Check`. Locally, the new file alone compiled under `packages/cli/tsconfig.test.json`'s options (a scratch tsconfig extending it, `files` set to the one test, `--listFiles`): exit 0, the file in the program, both `core/dist/index.d.ts` and `lint/dist/index.d.ts` resolved. - `test:repo` is not run locally (CI's `Test Core`): the diff touches no `repo`-project test. </details> <details><summary>Derived gates and lint</summary> On head `c20d3a56`, `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 58 commands from the 6-path change set (the same 58 as on the first head). All 58 recorded `exit 0`, and `--ran` reconciled them: "58 derived, 58 run, 0 NOT-MEASURED, 0 UNRUN". `pnpm lint`: exit 0 (outside the derivation). On the first head, two had exited 3 (prerequisite not met): `check-plugin-teardown-shape.mjs --self-test` needed an unshallow clone (`git fetch --unshallow origin main`, then 48 cases pass), and `check:dual-build-cjs-loads` needed built `dist/`. On the final head it reports 115 require entry points across 70 packages load. Among them: `check:cross-package-test-inputs` (31 packages read outside themselves, all declared), `check:test-source-alias`, `check:undeclared-dep-imports`, `check:doc-authoring` and `check:issue-citations`, all exit 0. </details> ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (No spec hunk.) - [x] 2. Every name I added uses the casing for its kind. - [x] 3. No formatter ran; `pnpm lint` passes. - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [x] 6. `packages/spec` touched: n/a. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English. - [x] The *Before Submitting* list in CONTRIBUTING.md is done. --- _Generated by [Claude Code](https://claude.ai/code/session_01JQwxbYxYhTvMoYjkUw8XvV)_ <!-- signed: domain:server#3 · os-warren · session_01JQwxbYyp6wSRcywGFK2L4A --> --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent c9c6828 commit 51a12c0

6 files changed

Lines changed: 402 additions & 1 deletion

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/lint': patch
3+
---
4+
5+
feat(lint): warn when a permission set's own View All or Modify All makes its field mask inert
6+
7+
Clause-②: yes (widening)
8+
Metadata-protocol: none
9+
10+
A permission set holding View All (`viewAllRecords`) or Modify All (`modifyAllRecords`) on an object votes on every field of it in the field-permission merge (ADR-0066 D2 as amended). So that set's own `readable: false` on the object hides the field from none of its holders, and under Modify All its edit lock (`editable: false`, or `editable` omitted) holds none of them back either. The new warning `security-superuser-field-mask-inert` names the entry, the bit that unbinds it and the fix: remove the bit and reach the rows with `readScope` / `writeScope` or a row-level policy, or delete the entry if the bypass is meant. View All beside an edit lock is not reported, because View All never widens a write.
11+
12+
The warning never refuses anything. It runs wherever `validateSecurityPosture` runs: `os lint`, `os validate`, `os build` and the runtime publish gate for a permission set, where it is reported as an advisory.
13+
14+
The rule reads the bypass the way the runtime does, through `holdsSuperuserBypass`, now exported from `@objectstack/lint`: a verbatim copy of the function of that name in `@objectstack/core` (the set's own entry for the object, else its `'*'` entry, as a lookup and never a merge).
Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* The author-time copy of the super-user bypass answers exactly as the
5+
* runtime's own reading does, over one case matrix.
6+
*
7+
* `holdsSuperuserBypass` (`@objectstack/core`, `security/effective-object-permissions.ts`)
8+
* is the ONE reading of "does this set hold View All / Modify All on this
9+
* object": the row bypass and both field merges ask it (ADR-0066 D2, ruling
10+
* of record 6573563853 letter A). `@objectstack/lint` depends on
11+
* `@objectstack/spec` alone, so its `security-superuser-field-mask-inert`
12+
* rule reads the bypass through a verbatim COPY exported under the same name.
13+
* A copy is a second reading the day the two drift, and a drifted lint either
14+
* warns about a mask the runtime enforces or stays silent about one it
15+
* ignores. This package depends on both, so the parity is pinned here: a
16+
* change to either function reds this file until the other follows.
17+
*
18+
* The matrix is the cartesian product of what the lookup reads: the set's own
19+
* entry for the object and its `'*'` entry, each absent, `null`, empty, or
20+
* carrying View All, Modify All, both, or a non-boolean truthy / falsy bit
21+
* (the reading is `Boolean(...)`, not `=== true`); the object asked about; and
22+
* the bit. Plus the sets with no usable `objects` at all.
23+
*/
24+
25+
import { describe, expect, it } from 'vitest';
26+
import { holdsSuperuserBypass as runtimeReading } from '@objectstack/core';
27+
import { holdsSuperuserBypass as authoringCopy } from '@objectstack/lint';
28+
29+
const ENTRIES: ReadonlyArray<[string, unknown]> = [
30+
['absent', undefined],
31+
['null', null],
32+
['empty', {}],
33+
['view', { allowRead: true, viewAllRecords: true }],
34+
['modify', { allowRead: true, allowEdit: true, modifyAllRecords: true }],
35+
['both', { viewAllRecords: true, modifyAllRecords: true }],
36+
['neither, spelled false', { viewAllRecords: false, modifyAllRecords: false }],
37+
['view, truthy non-boolean', { viewAllRecords: 1 }],
38+
['modify, truthy non-boolean', { modifyAllRecords: 'yes' }],
39+
['modify, falsy non-boolean', { modifyAllRecords: 0 }],
40+
];
41+
const OBJECTS = ['deal', '*'] as const;
42+
const BITS = ['view', 'modify'] as const;
43+
44+
type Case = { label: string; set: unknown; objectName: string; bit: 'view' | 'modify' };
45+
46+
function matrix(): Case[] {
47+
const cases: Case[] = [];
48+
for (const [ownLabel, own] of ENTRIES) {
49+
for (const [wildLabel, wild] of ENTRIES) {
50+
const objects: Record<string, unknown> = {};
51+
if (own !== undefined) objects.deal = own;
52+
if (wild !== undefined) objects['*'] = wild;
53+
for (const objectName of OBJECTS) {
54+
for (const bit of BITS) {
55+
cases.push({ label: `deal: ${ownLabel} · '*': ${wildLabel} · ask ${objectName} for ${bit}`, set: { objects }, objectName, bit });
56+
}
57+
}
58+
}
59+
}
60+
for (const set of [null, undefined, {}, { objects: null }, { objects: 'deal' }]) {
61+
for (const bit of BITS) cases.push({ label: `set ${JSON.stringify(set) ?? 'undefined'} · ${bit}`, set, objectName: 'deal', bit });
62+
}
63+
return cases;
64+
}
65+
66+
const CASES = matrix();
67+
type Reading = (set: never, objectName: string, bit: 'view' | 'modify') => boolean;
68+
const ask = (fn: Reading, c: Case) => fn(c.set as never, c.objectName, c.bit);
69+
70+
describe('holdsSuperuserBypass — the lint copy and the runtime reading agree', () => {
71+
it('the matrix is the product it claims, and it exercises both answers', () => {
72+
// 10 own entries x 10 wildcard entries x 2 objects x 2 bits, plus 5 sets x 2 bits.
73+
expect(CASES).toHaveLength(410);
74+
const answers = CASES.map((c) => ask(runtimeReading as Reading, c));
75+
expect(answers.filter(Boolean).length).toBeGreaterThan(0);
76+
expect(answers.filter((a) => !a).length).toBeGreaterThan(0);
77+
});
78+
79+
it('answers every case of the matrix alike', () => {
80+
const diverging = CASES.filter((c) => ask(authoringCopy as Reading, c) !== ask(runtimeReading as Reading, c)).map(
81+
(c) => `${c.label}: runtime ${ask(runtimeReading as Reading, c)}, lint ${ask(authoringCopy as Reading, c)}`,
82+
);
83+
expect(diverging).toEqual([]);
84+
});
85+
86+
it('a few readings the rule depends on, spelled out', () => {
87+
for (const fn of [runtimeReading, authoringCopy] as Reading[]) {
88+
const read = (set: unknown, bit: 'view' | 'modify') => fn(set as never, 'deal', bit);
89+
// Modify All implies View All; View All never implies Modify All.
90+
expect(read({ objects: { deal: { modifyAllRecords: true } } }, 'view')).toBe(true);
91+
expect(read({ objects: { deal: { viewAllRecords: true } } }, 'modify')).toBe(false);
92+
// The wildcard answers for an object the set does not name ...
93+
expect(read({ objects: { '*': { modifyAllRecords: true } } }, 'modify')).toBe(true);
94+
// ... and an entry that names the object answers alone: a lookup, never a merge.
95+
expect(read({ objects: { '*': { modifyAllRecords: true }, deal: { allowRead: true } } }, 'modify')).toBe(false);
96+
}
97+
});
98+
});

‎packages/lint/src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -361,6 +361,8 @@ export {
361361
SECURITY_CBP_NO_RELATION,
362362
SECURITY_CBP_AMBIGUOUS_RELATION,
363363
SECURITY_CBP_OWNER_POLICY_WITHOUT_OPT_IN,
364+
SECURITY_SUPERUSER_FIELD_MASK_INERT,
365+
holdsSuperuserBypass,
364366
} from './validate-security-posture.js';
365367
export type { SecurityFinding, SecuritySeverity } from './validate-security-posture.js';
366368

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -889,6 +889,30 @@ const SECURITY_MODIFY_ALL_DELETE_WITHHELD_EXPLANATION: RuleExplanation = {
889889
],
890890
};
891891

892+
const SECURITY_SUPERUSER_FIELD_MASK_INERT_EXPLANATION: RuleExplanation = {
893+
rule: 'security-superuser-field-mask-inert',
894+
covers: 'why a field mask beside View All or Modify All hides nothing',
895+
paragraphs: [
896+
'`viewAllRecords` (View All) and `modifyAllRecords` (Modify All) are the super-user bypass on an object. ' +
897+
'A set that holds one votes on every field of that object when the field permissions are merged: View ' +
898+
'All votes `readable: true`, Modify All votes `readable: true` and `editable: true` (ADR-0066 D2 as ' +
899+
'amended). The merge is a union, so a `readable: false` the same set declares on that object hides the ' +
900+
'field from none of the set\'s holders, and under Modify All its edit lock (`editable: false`, or ' +
901+
'`editable` omitted, which parses to false) holds none of them back either. The stored set still reads ' +
902+
'as masked, which is why an author or a reviewer takes the field to be protected.',
903+
'The set\'s bypass is read the way the runtime reads it: its own entry for the object when it has one, ' +
904+
'otherwise its `\'*\'` entry, as a lookup and never a merge. View All beside an edit lock is not ' +
905+
'reported, because View All never widens a write, so that lock still binds. Only the set that declares ' +
906+
'the entry is judged: a holder of two sets is unmasked by the other set\'s bypass too, but no author ' +
907+
'wrote an inert entry there.',
908+
'This is a warning, not an error: the pair is legal and no door refuses it. To fix it, decide which half ' +
909+
'is meant. If the field must stay hidden or read-only, remove the bypass bit from the object entry and ' +
910+
'reach every row another way, with `readScope: \'org\'` / `writeScope: \'org\'` on the entry or a ' +
911+
'`rowLevelSecurity` policy whose condition every row satisfies; the mask then binds. If the bypass is ' +
912+
'meant, delete the field entry, which never took effect.',
913+
],
914+
};
915+
892916
const SECURITY_OWD_ALIAS_EXPLANATION: RuleExplanation = {
893917
rule: 'security-owd-alias',
894918
covers: 'which sharing values are retired or misplaced',
@@ -5563,6 +5587,7 @@ export const RULE_EXPLANATIONS: Readonly<Record<string, RuleExplanation>> = Obje
55635587
[SECURITY_MASTER_DETAIL_UNGRANTED_EXPLANATION.rule]: SECURITY_MASTER_DETAIL_UNGRANTED_EXPLANATION,
55645588
[SECURITY_WILDCARD_VAMA_EXPLANATION.rule]: SECURITY_WILDCARD_VAMA_EXPLANATION,
55655589
[SECURITY_MODIFY_ALL_DELETE_WITHHELD_EXPLANATION.rule]: SECURITY_MODIFY_ALL_DELETE_WITHHELD_EXPLANATION,
5590+
[SECURITY_SUPERUSER_FIELD_MASK_INERT_EXPLANATION.rule]: SECURITY_SUPERUSER_FIELD_MASK_INERT_EXPLANATION,
55665591
[SECURITY_OWD_ALIAS_EXPLANATION.rule]: SECURITY_OWD_ALIAS_EXPLANATION,
55675592
[SECURITY_DELEGATION_MISSING_REASON_EXPLANATION.rule]: SECURITY_DELEGATION_MISSING_REASON_EXPLANATION,
55685593
[VISIBILITY_ROOT_MISLAYERED_EXPLANATION.rule]: VISIBILITY_ROOT_MISLAYERED_EXPLANATION,

0 commit comments

Comments
 (0)