Skip to content

Commit 0373715

Browse files
feat(security, verify): a controlled_by_parent row with no master is written by its owner or by Modify All on the detail (#31082)
Fixes #30906 Clause-②: yes Metadata-protocol: semantic Skills-docs: follow-up #30907 ## 维护者速读 - 改了什么:可选主表(`required: false`)的 `controlled_by_parent` 子对象里,主表引用为空的行现在可以写了:它的属主(`owner_id`)或对该子对象有「修改全部」的人可以改、删,其他人(包括只有「查看全部」的人)一律 403;新建一条不挂主表的行直接放行,创建者就是属主;给这种行挂上主表,要对那条主记录有编辑权;把已挂的主表清空,要对原主记录有编辑权,「属主可编辑」开关不覆盖清空。链式子对象(如联系人下的备注)在联系人没挂客户时,同样按联系人的属主规则判。`os verify` 的父级写入证明同时覆盖「挂主表」和「不挂主表」两种行,`security/explain` 会说明这条属主规则。 - 为什么改:您对 #30905 的裁决「A」:没有客户的联系人是私有联系人,只属于它的属主。这是三张卡的第 2 张;第 1 张放开了声明和读,写一直是 422,这类联系人建不出来、也改不了。 - 风险与回滚:只放宽「可选主表且引用为空的行」这一类(以前一律 422),必填主表的所有答复逐字节不变;能看不等于能改,「查看全部」的人改不了别人的私有行。回滚即撤 PR,无数据迁移。 - 先看:`packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts` 里的 `nullMasterRowWritable`,以及 `assertControlledByParentWrite` 中 `masterId == null && rel.optional` 那一段;再看 `controlled-by-parent-optional-master.test.ts` 末尾的真实引擎用例块。 - 两分钟验证:`pnpm --filter @objectstack/plugin-security exec vitest run src/controlled-by-parent-optional-master.test.ts`,预期 47 个全部通过;把 `nullMasterRowWritable` 改成恒返回 true 再跑,会红 10 个(见下文消融)。 - 需要你做的:无,席位落地。 ## What changes **`@objectstack/plugin-security` — the write gate (ADR-0055 §3, step 2.8).** A row of an OPTIONAL master (`CbpRelation.optional`) whose master reference is empty used to answer `422 MISSING_REQUIRED_FIELD` on every write. It is now judged, on every shape the gate judges: - **Owner rule** (`nullMasterRowWritable`, new): such a row is written by its owner (`owner_id`, non-null, equal to the principal's `userId`) and by a holder of `modifyAllRecords` on its object (`PermissionEvaluator.hasSuperuserWriteBypass`). Everyone else is refused `403 PERMISSION_DENIED`, `details: { operation, object, recordId }` naming the row, leg `master_chain`. A queue row (no owner) and every row of an object without an `owner_id` column are Modify All's alone. - **Create**: an insert (single or batch) naming no optional master is admitted; the creator becomes the owner (the platform's owner stamp). Every master a batch's rows do name is still asked. - **Update / delete by id** of a stored null-master row: the owner rule. Step 2.7 hands a detail's ownership floor to this gate, so without it a principal who merely READS the row (View All) could write it. - **Predicate writes** (`multi: true`): `controlledByParentPredicateWriteMasters` returns the selected null-master rows beside the masters (`CbpPredicateWriteSelection`) instead of throwing; each is judged by the owner rule, and a body naming a master is asked even when every selected row names none. - **Setting a master** (none → M): the row's owner rule, then edit on M. **Emptying one** (M → none): the §3 walk with edit on the stored master. The `ownerMayEdit` leg steps aside for a body that empties an optional master (card item 4). - **Chains**: a hop whose master is itself `controlled_by_parent` with an optional master of its own, left empty, ends the chain and asks the owner rule of that row (card item 5). - **On behalf of**: both passes ask the owner rule, each of its own principal (agent, then delegator). `ISecurityService.checkControlledByParentWrite` answers `allow` or `deny` / `master_chain` for such a row. - The frozen `#9137` branch is untouched: the new block runs ahead of it and only for `rel.optional`, which none of the three frozen shapes can be (a master with no `required` derives no relation at all; `readonly`/`system` is refused by `masterNotWritable` first). A required master is answered byte for byte as before. Ownership transfer stays on `allowTransfer`. - **`security/explain`** names the owner rule when the served check refuses a null-master record (it would otherwise narrate the refusal as an unwalkable chain). **`@objectstack/verify` — the ADR-0054 proof.** `deriveParentWriteReachCases` marks an optional-master detail (`optionalMaster: true`, via the spec's `controlledByParentMasterOf`). `runParentWriteReachProofs` proves it in both cases: its records under a master as every detail, and a new `masters: 'none'` reach per persona where the expectation is the owner rule — edit/delete allowed iff the persona holds the verb AND (owns the record OR holds Modify All on the object); create naming no master allowed iff it holds create. A null-master record the persona cannot read is listed in `unreadableDetails`, not probed. ## Tests - `packages/plugins/plugin-security/src/controlled-by-parent-optional-master.test.ts`: card 1's "write gate is unchanged" block now pins the admitted insert; a new top-level block on the real engine (SQL driver, real sharing service, `member_default` floor) pins create, by-id update/delete (owner, View-All reader, Modify All, queue row, no owner column, non-reader), setting and emptying a master (with and without the opt-in), the chain hop, predicate update/delete, both on-behalf-of passes, the served member, and a required-master control. Every refusal asserts `code` + `status` + `details` and the stored row. Two explain pins for the narration. - `packages/verify/src/parent-write-reach.test.ts`: `pwr_contact` (optional master) joins the fixture; a new case proves the null-master reach per persona (View All on the detail is refused another's record, Modify All writes it, the owner writes its own); the count pins move to the measured totals. Every negative pin was ablated: forbidden behaviour put back through `scripts/ablation-replace.mjs` (anchor must hit, restore proven against HEAD), suite red, restored. | Ablation | Red | |:---|:---| | A1 owner rule admits everyone | 10 failed / 35 passed | | A2 `ownerMayEdit` leg covers an emptying body | 1 (the emptying refusal) | | A3 predicate asks the body's master only when a selected row names one | 1 | | A4 setting a master on a null-master row asks nothing of it | 1 | | A5 chain hop ends without the owner rule | 1 | | A7 predicate null-master rows unjudged | 1 | | A8 by-id null-master row unjudged | 8 | | A9 explain without the null-master argument | 1 | | verify A1 through `dist/` | `pwr_contact` CONTRADICTED on 2 of 64 writes | A4's first attempt was a no-op (the tool refused it: the replacement text already occurred, so the mutation did not count as landed); it was re-run in `--delete` mode and went red. The verify ablation was built into `dist/` and checked by `ablation-dist-preflight.mjs` on both legs (marker present after mutate, absent after restore). ## Acceptance notes - **Mechanism assumptions, measured.** (1) Step 2.7 hands the floor to the gate on every non-delegated by-id write of a `controlled_by_parent` detail (`masterGateCoversThisWrite = !delegatorSets`, `platformFloorYieldsToObjectWriteModel`): A1 shows a View-All reader's update of a row created by another principal LANDS once the owner rule is removed, so the rule has to live inside the gate. (2) `@objectstack/verify` synthesis does skip non-required relations (`seedRecord`), but every probe pinned the master explicitly, so the family produced no null-master record before this change; the new reach seeds the empty reference explicitly. - **The refusal's leg is `master_chain`.** `ControlledByParentWriteDenialLeg` is a closed spec vocabulary and `packages/spec/**` is outside this card; `master_chain` is the leg its text already gives "a master that is itself controlled_by_parent ... has an empty master reference", and here the chain ends at the row itself. A dedicated leg would be a spec contract change. - **Card item 3 is read fail-closed.** Setting a master on a null-master row asks the row's own owner rule first, then edit on the new master: an account editor who reads, but does not own, someone's private contact cannot adopt it. Pinned. - A principal who cannot read a null-master row meets the read door at step 2.7 (`404 RECORD_NOT_FOUND`) before the gate, as for every hidden row. Pinned. - An insert of a null-master row on an object with no `owner_id` column is admitted (card item 2), and its creator cannot read it back: such rows are View All's to read and Modify All's to write, as card 1 reads them. - **Prose owed elsewhere, left untouched here (outside this card's surface):** the ADR-0055 2026-11-06 amendment still says §3 is unchanged and "is amended again for §3 then" (`docs/adr/**`, Tier H); the spec contract docs of `master_chain` and `master_reference_missing` do not mention the optional master. Card 3 (#30907) teaches the docs and skills. - The verify proof covers the detail's own null master; the chain hop over a null-master middle row is pinned in the plugin-security suite only. ## Verification <details> <summary>Full package suites, on head e6bb523</summary> - `pnpm --filter @objectstack/plugin-security exec vitest run --maxWorkers=2`: Test Files 248 passed (248), Tests 5796 passed, 45 skipped (5841). VERDICT command-exit 0. - `pnpm --filter @objectstack/verify exec vitest run --maxWorkers=2`: Test Files 48 passed (48), Tests 409 passed (409). VERDICT command-exit 0. - `pnpm --filter @objectstack/plugin-security typecheck` and `pnpm --filter @objectstack/verify typecheck` (each with its test layer): exit 0. - `pnpm exec eslint --no-inline-config` over the six changed source files: exit 0. </details> <details> <summary>Derived gate families, on head e6bb523</summary> `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 63 commands from the 7 changed paths (1085 changed lines, under the 3000 threshold). Each was run with its exit code recorded before any pipe, then `--ran` reconciled: 63 derived, 61 run, 2 NOT MEASURED, 0 UNRUN. - NOT MEASURED: `pnpm check:dual-build-cjs-loads` (exit 3, PREREQUISITE NOT MET: needs every package's `dist/`, a whole-tree build) and `pnpm check:i18n` (exit 3, PREREQUISITE NOT MET: needs the built CLI and its extract closure). Both run in CI's `Lint & Repo Gates`. - `node scripts/check-plugin-teardown-shape.mjs --self-test` first exited 3 (its positive control is pinned to a commit this shallow checkout lacked); the one commit was fetched and the re-run exited 0. - Every other derived command exited 0. </details> --- _Generated by [Claude Code](https://claude.ai/code/session_017xRBcTJTE7kSbcMoJQ4Txf)_ <!-- signed: domain:server#1 · sunhaolin · session_017xRBcTJTE7kSbcMoJQ4Txf --> --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 24bc259 commit 0373715

8 files changed

Lines changed: 1037 additions & 54 deletions
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
'@objectstack/plugin-security': minor
3+
'@objectstack/verify': minor
4+
---
5+
6+
feat(security, verify): the `controlled_by_parent` write gate judges a detail row whose optional master is empty — its owner or Modify All on the detail writes it
7+
8+
Clause-②: yes
9+
Metadata-protocol: semantic
10+
Skills-docs: follow-up #30907
11+
12+
A `controlled_by_parent` object whose only `master_detail` is declared `required: false` (an optional master) could already be declared, and its rows that name no master were already read by their owner and by View All on the detail. Writing such a row was refused with `422 MISSING_REQUIRED_FIELD`. It is now judged:
13+
14+
- **Create.** An insert that names no master is admitted to anyone the detail's own `create` grant admits, and its creator becomes its owner. A batch is admitted the same way; every master its rows do name is still asked.
15+
- **Update and delete.** A stored row that names no master is written by its owner (`owner_id` equal to the caller) and by a holder of `modifyAllRecords` on the detail, and refused `403 PERMISSION_DENIED` for everyone else, a holder of View All included. A row with no owner (a queue row), and every row of an object with no `owner_id` column, is Modify All's alone. The same rule judges each row a predicate update or delete (`multi: true`) selects, both principals of an on-behalf-of write, and `ISecurityService.checkControlledByParentWrite` (a refusal there is `deny` on the `master_chain` leg).
16+
- **Setting a master** (none → M, M1 → M2) asks edit on the master the body names, as before. **Emptying one** (M → none) asks edit on the master the row leaves: the `sharing.controlledByParent.ownerMayEdit` opt-in, which lets an owner update a row with read on its master, does not cover a body that empties the master, so an owner who only reads the account cannot detach a contact and make it private.
17+
- **Chains.** A master that is itself `controlled_by_parent` with an optional master of its own, and names none, ends the chain: writing its details asks the same rule of that row (its owner, or Modify All on its object).
18+
- Ownership transfer is unchanged: a body that names another owner is still gated by `allowTransfer`.
19+
- **`@objectstack/verify`.** The parent write reach family proves an optional-master detail in both cases: its records under a master, as every detail, and its records that name none, by the rule above (`ParentWriteReachReach.masters: 'none'`, with `masterRead: 'none'` and `unreadableDetails`).
20+
21+
A required master is unchanged: a row whose stored required master is empty still answers `422 MISSING_REQUIRED_FIELD`.

‎packages/plugins/plugin-security/src/controlled-by-parent-optional-master.test.ts‎

Lines changed: 501 additions & 16 deletions
Large diffs are not rendered by default.

‎packages/plugins/plugin-security/src/explain-engine.ts‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1213,12 +1213,28 @@ const MASTER_CHECKED_BY_ID_WRITES: ReadonlySet<string> = new Set(['update', 'del
12131213
function masterWriteCheckRefusal(
12141214
outcome: ControlledByParentWriteOutcome,
12151215
verb: string,
1216+
/**
1217+
* [ADR-0055 §3 as amended · #30905 ruling A] The record's master reference
1218+
* key when its OPTIONAL master is empty ({@link nullMasterReferenceOf}):
1219+
* the check then judged the record by its owner rule, not by a master, and
1220+
* its `master_chain` refusal is narrated as that rule.
1221+
*/
1222+
nullMasterFk?: string,
12161223
): { outcome: ExplainRecordAttribution['outcome']; detail: string } | undefined {
12171224
switch (outcome?.outcome) {
12181225
case 'allow':
12191226
case 'not_applicable':
12201227
return undefined;
12211228
case 'deny':
1229+
if (nullMasterFk !== undefined && outcome.leg === 'master_chain') {
1230+
return {
1231+
outcome: 'excluded',
1232+
detail: `${MASTER_DERIVED} when it names one, and it names none: its master reference '${nullMasterFk}' is ` +
1233+
`empty, so the master-detail write check the by-id ${verb} runs admits only its owner and a holder of ` +
1234+
`Modify All on the object, and refuses this ${verb} on its 'master_chain' leg. ` +
1235+
`The ${verb} answers 403 PERMISSION_DENIED.`,
1236+
};
1237+
}
12221238
return {
12231239
outcome: 'excluded',
12241240
detail: `${MASTER_DERIVED}: the master-detail write check the by-id ${verb} runs refuses this ${verb} on its ` +
@@ -2011,7 +2027,7 @@ async function applyRecordAttribution(
20112027
const masterFault = masterOrFault === DEPENDENCY_FAULT;
20122028
const masterRefusal = masterOrFault === undefined || masterOrFault === DEPENDENCY_FAULT
20132029
? undefined
2014-
: masterWriteCheckRefusal(masterOrFault, engineOp);
2030+
: masterWriteCheckRefusal(masterOrFault, engineOp, nullMasterReferenceOf(deps, object, record as Record<string, unknown>));
20152031
// [ADR-0055] A record-grained read of a `controlled_by_parent` record meets
20162032
// a master leg too: the read door ANDs the record's master-derived read scope
20172033
// (the master ids the principal can read, the chain included) into the find,

‎packages/plugins/plugin-security/src/security-plugin-cbp-relation.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -210,8 +210,10 @@ export function resolveCbpRelation(
210210
// the validator's test it mirrors and cannot widen if the resolver
211211
// changes — and it did: an OPTIONAL master (#30905 ruling A) resolves
212212
// with `required: false`, so this is `false` there and the master gate
213-
// keeps answering an insert that leaves the reference empty (the write
214-
// gate is unchanged by that ruling: such an insert is still refused).
213+
// keeps answering an insert that leaves the reference empty itself: it
214+
// admits it, by the optional master's own rule (`CbpRelation.optional`
215+
// in the write gate — the row is then its creator's), never by handing
216+
// the omission to validation.
215217
omissionRefusedByValidation:
216218
def?.type === 'master_detail' && !!def?.required && !def?.readonly && !def?.system,
217219
// [#25095] From the same def, asked of the parse's own predicate.

0 commit comments

Comments
 (0)