Repository navigation
Commit 0373715
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
File tree
- .changeset
- packages
- plugins/plugin-security/src
- verify/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 | + | |
| 20 | + | |
| 21 | + | |
Large diffs are not rendered by default.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1213 | 1213 | | |
1214 | 1214 | | |
1215 | 1215 | | |
| 1216 | + | |
| 1217 | + | |
| 1218 | + | |
| 1219 | + | |
| 1220 | + | |
| 1221 | + | |
| 1222 | + | |
1216 | 1223 | | |
1217 | 1224 | | |
1218 | 1225 | | |
1219 | 1226 | | |
1220 | 1227 | | |
1221 | 1228 | | |
| 1229 | + | |
| 1230 | + | |
| 1231 | + | |
| 1232 | + | |
| 1233 | + | |
| 1234 | + | |
| 1235 | + | |
| 1236 | + | |
| 1237 | + | |
1222 | 1238 | | |
1223 | 1239 | | |
1224 | 1240 | | |
| |||
2011 | 2027 | | |
2012 | 2028 | | |
2013 | 2029 | | |
2014 | | - | |
| 2030 | + | |
2015 | 2031 | | |
2016 | 2032 | | |
2017 | 2033 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
210 | 210 | | |
211 | 211 | | |
212 | 212 | | |
213 | | - | |
214 | | - | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
215 | 217 | | |
216 | 218 | | |
217 | 219 | | |
| |||
0 commit comments