Skip to content

Commit b289090

Browse files
fix(plugin-security)!: an update or delete of a controlled_by_parent detail asks for edit access to its master on every write shape (ADR-0055 §3) (#25042)
Fixes #25012 Clause-②: no (narrowing) ## What this changes ADR-0055 §3 (`docs/adr/0055-master-detail-controlled-by-parent.md`): "editing/deleting/creating a detail requires **edit** access to its master". The `controlled_by_parent` detail write gate (`assertControlledByParentWrite`, step 2.8 of the security middleware) decided one write shape the engine routes without asking that question. It now asks it on every shape. - **The remaining shape is judged per master.** The gate collects the masters of the detail rows the write would reach, as the caller's own read returns them, and runs on each the same chain walk a by-id write runs. The first refusal is the answer, in the by-id leg's own envelope (`PERMISSION_DENIED`, 403, the same message), and nothing is written. On an on-behalf-of write both principals are asked, as on a by-id write. - **A verdict, never a scope.** No master set is composed into the write. The read derivation (`computeControlledByParentFilter`), `packages/objectql/**` and `packages/spec/**` are untouched, and #24932's ruling B (`6303721609`) on the master-scope mechanism gets no second spelling here. - **The chain walk is extracted verbatim** into `assertControlledByParentChainEditable`, so the insert, by-id and new legs run one copy. Git shows the walk's lines as unchanged context; one comment line in it is reworded. - **It fails closed where the rows cannot be enumerated.** A refused read of the detail refuses the write with that read's own refusal. Above the existing 10,000-row read cap, the existing `INVALID_FILTER` refusal answers. **Unchanged:** inserts and by-id writes (same path, same walk), system contexts, the read scope, the platform ownership floor (still applied on this shape; nothing here vouches it away), and every object that does not declare `controlled_by_parent`. **Reach**, stated abstractly under the disclosure ruling on #9387 (`5323310017`): it was re-measured before the change on a real `ObjectQL` + `SqlDriver` + `SecurityPlugin` + sharing stack, across every refusal leg, three principal classes and both tenancy postures. The measurement covers what bounded the rows. The readings are held privately by the seat. ## Tests New file: `packages/plugins/plugin-security/src/controlled-by-parent-write-shape-master-edit.test.ts`, 15 tests on a real stack (`ObjectQL` over better-sqlite3, the real `SecurityPlugin`, the real sharing service and middleware, contexts from `resolveAuthzContext` + `assembleExecutionContext`, `isolated` tenancy). Pinned behaviours: 1. A master the caller may not edit refuses the write. The refusal equals the by-id door's answer for the same caller and master (code, status and message, compared to the live by-id answer, not to a literal). This holds for each refusal leg, for a member, an org admin and an agent acting for a member, and for both verbs. Nothing is written. 2. One such master among editable ones refuses the whole write, and nothing is written under either. 3. A write whose rows all sit under editable masters lands as before. The rows it writes are unchanged: own rows only for a member and its agent (the floor), every row for an org admin. 4. A row the caller cannot read is not judged and is not written. 5. A caller whose read of the detail is refused gets that read's own refusal, and nothing is written. Ablation, one leg per pinned behaviour. Each leg was mutated through `scripts/ablation-replace.mjs` (anchor hit 1 to 0, blob changed on disk) and restored with `git checkout HEAD -- PATH`. Each restore was proven by blob equality with HEAD (`cdc1192e52`) and an empty `git diff HEAD`. No build step was needed: the suite imports the subject from `src/` relatively. | leg | mutation | observed | |---|---|---| | A | the new leg returns without judging | 11 red / 4 green: every refusal pin red, plus pin 5; pins 3 and 4 stay green | | B | every such write refused outright | 15 red / 0 green. The first attempt was a no-op: the replacement contained its anchor and the tool refused, so nothing ran. Re-anchored and re-run. | | C | rows enumerated as system instead of through the caller's read | 2 red: pins 4 and 5 | | D | the read's refusal swallowed as "no rows" | 1 red: pin 5 | | E | only the first master judged | 1 red: pin 2 | ## Verification (head `2f80e0db95`, base `origin/main` `3b3830ca22`) - `pnpm --workspace-concurrency=2 --filter '@objectstack/plugin-security^...' build`: lock `VERDICT command-exit 0`. - `pnpm --filter @objectstack/plugin-security test`: 200/200 files, 4129 passed, 45 skipped (taken at `44eef53692`; the merge from main touches none of this package's sources or dependencies). - `pnpm --filter @objectstack/plugin-security typecheck`: exit 0. This includes `check:test-typecheck`, which reports 0 files and 0 errors held in the debt ledger, so the new test compiles. - `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derives 69 commands (identical at `44eef53692` and `2f80e0db95`). All 69 ran under the lock at `2f80e0db95`, each exit captured before any pipe: 69 exit 0. `--ran` reconciliation: 69 derived, 69 run, 0 NOT-MEASURED (a derived zero), 0 UNRUN. At `44eef53692`, before the dogfood closure existed, `check:dual-build-cjs-loads` and `check:i18n` had exited 3 (PREREQUISITE NOT MET). They are green here. - Full dogfood battery (owed by `(narrowing)` and the title's `!`): dogfood closure built, then `pnpm --filter @objectstack/dogfood test` under the lock with no shard and no path. `VERDICT command-exit 0`: Test Files 284 passed and 3 skipped (287); Tests 2361 passed and 18 skipped (2379); no failures. - `node scripts/check-nul-bytes.mjs`: OK. ## Acceptance notes - **Two docblock sentences outside the claimed region now describe the old behaviour.** I left them untouched under the claim's hard stop (no other region of `security-plugin.ts`). The seat can approve a comment-only rider, or name a carrier. - The third bullet of the `RlsFilterOptions.masterGateCoversThisWrite` docblock says the gate "returns early and nothing replaces the floor" when no single id is addressed. Proposed: "does not vouch: the master gate judges this shape, but the floor stays, because dropping it here would widen the rows a member writes (a separate decision)". - Step 2.7's coverage-vouch parenthetical "(`extractSingleId`, or it returns early)". Proposed: "(`extractSingleId`; with no single id step 2.8 judges every master the write reaches instead)". - **Writes issued from inside another operation are judged too**, under the caller's context (a hook's or a cascade's), as step 2.8 judges their by-id twins. The write doors' readable narrowing excludes such writes, so for them the judged set is the rows the caller can read. - **Cost.** Each such write on a `controlled_by_parent` detail adds one read under the caller's context, one system read of the master references, and one chain walk per distinct master, each hop about three reads. The bound is the existing 10,000-row cap. - **Object-grained `security/explain`** (no record) for update or delete on a `controlled_by_parent` detail answers `allowed` with no master leg. It is a record-agnostic question; noted, not filed. ## Open question for the seat - **Refuse versus narrow, as the long-term answer for this shape.** This PR refuses: a verdict, with no master scope composed. Narrowing to editable masters would compose the caller's editable-master set into the write. That is a master scope, which ruling B decides, and ADR-0139 D1 refuses the engine leaf on write verbs. Refusing now is forward-compatible: a later move to narrowing would be a widening. - **Whether the floor should yield on this shape as it does by-id** (commit 6feac91) is a widening, and it is not taken here. --- **Seat's append** (`domain:services` seat 1, from the dev's patch-round report `6307856898` on #25012; the dev writes its PR body once): ## Patch round 1 (head `033fc75a09`) - **The two docblock sentences named in the Acceptance notes are now fixed in this PR**, as a comment-only rider. This follows the seat's ruling on the open question, letter A. `git diff HEAD~1 -- packages/plugins/plugin-security/src/security-plugin.ts` shows 7 lines in and 3 out, and every changed line is a comment line (0 non-comment lines). No code token changed. - The refuse-versus-narrow question is ruled A: keep refusing. - `origin/main` (`dfe60e3a0c`) was merged first, because it moved files the suite depends on (`packages/objectql`, `packages/drivers/driver-sql`, `packages/core`). - Re-verified on `033fc75a09` under the lock: - closure build exit 0; - `pnpm --filter @objectstack/plugin-security test`: 200/200 files, 4129 passed, 45 skipped; - `typecheck` exit 0; - full dogfood battery (no shard, no path): `VERDICT command-exit 0`, Test Files 284 passed and 3 skipped (287), Tests 2361 passed and 18 skipped (2379), no failures. **Seat's append** (from the dev's patch-round-2 report `6308106727` on #25012): ## Patch round 2 (head `e71bf1e576`) - The changeset headline and its ADR-0087 note are scoped to update and delete, as the reviewer asked; the diff from `033fc75a09` is that one changeset file, with no code change, so the `033fc75a09` dogfood battery stands. --- _Generated by [Claude Code](https://claude.ai/code/session_011TdZ8GjixNZFLz1xJD9zzK)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 63085c3 commit b289090

3 files changed

Lines changed: 619 additions & 9 deletions

File tree

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
'@objectstack/plugin-security': minor
3+
---
4+
5+
fix(plugin-security)!: an update or delete of a `controlled_by_parent` detail asks for edit access to its master on every write shape (ADR-0055 §3)
6+
7+
Clause-②: no (narrowing)
8+
9+
<!-- adr-0087: not-required (no-migration-prescription) No metadata moves: no spec key, authorable spelling, object definition, stored row or stored shape is added, removed, renamed or re-shaped, and no exported declaration is removed or narrowed, so there is nothing for `objectstack migrate meta` to rewrite. What changes is the answer the security plugin's master-detail write gate gives for one shape of write to a `controlled_by_parent` detail: it now asks the master-edit question a by-id update or delete already asks, and refuses where that question refuses. The remedy is a grant on the master or a narrower write, never a rewrite of a package source or a stored row. The other categories are closed on facts: the package publishes (not unpublished); no ADR-0087 id is named or touched (not registered or already-registered); and nothing exported is removed or narrowed (not runtime-interface-only, type-surface-only or runtime-export-retired). -->
10+
11+
ADR-0055 §3 says editing or deleting a detail requires edit access to its master, and it names no write shape as exempt. The master-detail write gate decided one shape of write to a `controlled_by_parent` detail without asking that question. It now asks it: the gate collects the masters of the detail rows the write would reach, as the caller's own read returns them, and runs on each master the check a by-id write runs. One master the caller may not edit refuses the whole write, and nothing is written. On a write made on a user's behalf, both principals are asked, as on a by-id write.
12+
13+
**BREAKING** for a caller that relied on that shape to write details under a master it may not edit. Shipped as `minor` under the launch-window convention for accept-set narrowings.
14+
15+
- **Before.** That shape of write changed or removed details under a master the caller may not edit, bounded only by what the caller could read and, for an organization member, by the platform ownership floor.
16+
- **Now.** It answers the refusal a by-id write of the same detail answers: `PERMISSION_DENIED` (403), naming the detail and the master-edit reason. A write whose rows all sit under masters the caller may edit lands as before and writes the same rows. A row the caller cannot read is not judged and is not written.
17+
- **Also refused.** A caller whose read of the detail is itself refused gets that read's refusal for this shape of write, because the masters of rows it cannot read cannot be established. A write reaching more than 10,000 readable rows answers `INVALID_FILTER` (400), the refusal the same count already answers.
18+
- **Unchanged.** Inserts and by-id updates and deletes; system contexts; the detail's read scope; the platform ownership floor; and every object that does not declare `controlled_by_parent`.
19+
20+
**What to do.** Grant the caller edit access on the master, or narrow the write to details under masters the caller may edit.

0 commit comments

Comments
 (0)