Skip to content

Commit 77e4f31

Browse files
committed
fix(plugin-security)!: refuse every write that sets a controlled_by_parent master reference declared readonly or system (ADR-0055 §1)
Ruling 6345869077 on #25095 (route B, refuse at the write gate). The relation still resolves for such a declaration, so reads, the cache and the unresolved report are unchanged and stored rows keep their master. CbpRelation.masterNotWritable is now read from the same field def the relation came from, judged by the parse's own predicate on that one def. The gate refuses, before any master is asked and before anything is written, every insert (single or batch, with or without a master in the body) and every update whose body carries the reference key (any value, null included), 422 INVALID_METADATA with the parse's message. A delete and an update that leaves the key alone take the path they took before. The same answer for every caller the gate judges; the system bypass is unchanged. Tests: the suite is renamed to controlled-by-parent-unwritable-master-write and now covers a member and a platform admin, ordinary and sys_-named objects, inserts with and without a master, batch inserts, updates naming a master or null, and the controls (stored rows read, an update without the key, a delete, a system create, the in-repo declaration shape). The [#8688] flagged-insert pin in controlled-by-parent-sharing and the unjudged-reference pins in controlled-by-parent-every-row-master move to the new answer; the stored-master-first ordering pin moves to the validated detail. The stale AUTHORABLE wording and the two stale freeze-note paragraphs are corrected. Claude-Session: https://claude.ai/code/session_01LQG7z3CxDLtiMaHLbTFSeB Co-authored-by: Claude <noreply@anthropic.com>
1 parent a9002e5 commit 77e4f31

8 files changed

Lines changed: 612 additions & 512 deletions

‎.changeset/25095-cbp-unwritable-master-insert.md‎

Lines changed: 0 additions & 24 deletions
This file was deleted.
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
'@objectstack/plugin-security': patch
3+
---
4+
5+
fix(plugin-security)!: under a `controlled_by_parent` declaration whose one master reference is `readonly` or `system`, every write that sets that reference is refused (ADR-0055 §1)
6+
7+
Clause-②: no (narrowing)
8+
9+
Metadata-protocol: none
10+
11+
<!-- adr-0087: not-required (already-registered cbp-master-relation-tiers-retired) registered before this change, and it covers it: that entry's stored-row listing (`os migrate meta --stored`) already reports this declaration as `master-not-writable`, with the prescription below. Nothing new 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. What changes is the answer the security plugin's write gate gives on an object that reached the registry with a declaration the parse already refuses. -->
12+
13+
**BREAKING** for a caller that relied on such a write landing. A non-protocol change, shipped as `patch`.
14+
15+
ADR-0055 §1 derives a `controlled_by_parent` detail's access from exactly one required `master_detail` field that every write of a detail supplies. The parse refuses that master when it is declared `readonly: true` or `system: true`, so an object with it reaches the runtime only through a door that does not parse: a raw `registerObject` or `registerApp`, a `defineStack` call with `strict: false`, or a stored object the boot registers under its `[metadata_spec_invalid]` diagnostic. On such an object the security plugin's write gate let writes that set the master reference through, and a detail could end up outside the master its access derives from, readable by nobody, while the write reported success.
16+
17+
- **Before.** An insert under that declaration was written when it named a master. An update could set the reference.
18+
- **Now.** Every write that sets the reference answers `INVALID_METADATA` (422) and writes nothing, before any master is asked: every insert, single or batch, whether or not it names a master, and every update whose body carries the reference key, whatever the value, `null` included. The message is the parse's own refusal of the declaration, prefixed with the write it refused, so it names the object, the field, each flag and the fix. It is the same for every caller the gate judges.
19+
- **Unchanged.**
20+
- The rows already stored: the gate still derives their read access from that field, so they keep their master and are read as before.
21+
- A delete, and an update whose body leaves the reference key out.
22+
- System contexts, every object declared with an ordinary required master, and every object that does not declare `controlled_by_parent`.
23+
24+
**What to do.** Fix the declaration as the parse says: remove `readonly: true` and `system: true` from the master reference and declare it as an ordinary required field. If the rows must outlive their parent, the object is not a detail: give it its own `sharingModel` (`private`, `public_read` or `public_read_write`).

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

Lines changed: 24 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -27,16 +27,16 @@
2727
* - each master a batch names is asked once, in row order;
2828
* - a row naming no master, under a reference required-field validation
2929
* judges, is answered by validation as before;
30-
* - under a reference required-field validation does not judge, a batch
31-
* create naming a master the caller may not edit is refused on that master
32-
* (for an agent, whose own pass runs first, on the empty-master answer),
33-
* and every other batch create is still refused whole, as before;
34-
* - an update that empties the master reference, under a reference
35-
* required-field validation does not judge, is refused — addressed by
36-
* `where`, in its body and by predicate — with the empty-master refusal, and
37-
* nothing is written; under a reference validation judges, validation's
38-
* answer is unchanged; and an update that leaves the reference out lands as
39-
* it did.
30+
* - under a reference required-field validation does not judge — one the
31+
* declaration keeps from the author, which the parse refuses — every batch
32+
* create is refused whole as the declaration defect it is (#25095), before
33+
* any master is asked, and nothing is written;
34+
* - an update that empties the master reference is refused — addressed by
35+
* `where`, in its body and by predicate — and nothing is written: under a
36+
* reference validation judges, by validation as before, after the master
37+
* the row is stored under is asked; under one it does not judge, as the
38+
* declaration defect (#25095); and an update that leaves the reference out
39+
* lands as it did.
4040
*
4141
* Real stack: `ObjectQL` over better-sqlite3, the real `SecurityPlugin`, the
4242
* real sharing service and middleware, the real protocol, and contexts
@@ -83,7 +83,9 @@ const D = { rls: 'qa_cbp_erm_detail_rls', chain: 'qa_cbp_erm_detail_chain' } as
8383
/**
8484
* A detail under `M.rls` whose master reference required-field validation does
8585
* not judge (`validateRecord` skips a provenance-flagged field), so the gate is
86-
* the one thing that holds the reference populated.
86+
* the one thing that holds the reference populated. The parse refuses the
87+
* declaration (`master-not-writable`), and since #25095 the gate refuses every
88+
* write that sets the reference as that defect.
8789
*/
8890
const UNJUDGED = 'qa_cbp_erm_detail_unjudged';
8991

@@ -457,27 +459,20 @@ describe('ADR-0055 §1 · §3 — every row a write stores in a controlled_by_pa
457459
});
458460
});
459461

460-
it('under a reference validation does not judge: a batch create naming a master the caller may not edit is refused on that master, and every other batch create is still refused whole', async () => {
462+
it('under a reference validation does not judge: every batch create is refused whole as the declaration defect, before any master is asked, and nothing is written', async () => {
461463
for (const caller of Object.keys(CALLERS) as Caller[]) {
462464
const { user, onBehalf } = CALLERS[caller];
463465
const context = await rig.contextOf(user, onBehalf);
466+
// [#25095] The single create's answer, even naming a master the caller may not edit.
464467
const refusal = await rig.insert(UNJUDGED, rig.rows([held('rls')])[0]!, context);
465-
expect(refusal).toMatchObject({ kind: 'refused', code: 'PERMISSION_DENIED', status: 403 });
468+
expect(refusal).toMatchObject({ kind: 'refused', code: 'INVALID_METADATA', status: 422 });
466469
for (const door of DOORS) {
467470
const refused = rig.rows([free('rls'), held('rls')]);
468-
const outcome = await rig.batch[door](UNJUDGED, refused, context);
469-
if (onBehalf) {
470-
// The agent's own pass runs first and whole: its sets may edit both
471-
// masters, so it meets the batch's empty-master answer before the
472-
// member's pass asks the master the member may not edit. Refused all
473-
// the same, and nothing is written.
474-
expect({ caller, door, outcome }).toMatchObject({ caller, door, outcome: { kind: 'refused', code: 'MISSING_REQUIRED_FIELD', status: 422 } });
475-
} else {
471+
const whole = rig.rows([free('rls'), free('rls', 2)]);
472+
for (const rows of [refused, whole]) {
473+
const outcome = await rig.batch[door](UNJUDGED, rows, context);
476474
expect({ caller, door, outcome: envelope(outcome) }).toEqual({ caller, door, outcome: envelope(refusal) });
477475
}
478-
const whole = rig.rows([free('rls'), free('rls', 2)]);
479-
expect({ caller, door, outcome: await rig.batch[door](UNJUDGED, whole, context) })
480-
.toMatchObject({ caller, door, outcome: { kind: 'refused', code: 'MISSING_REQUIRED_FIELD', status: 422 } });
481476
const after = await rig.stored(UNJUDGED, [...ids(refused), ...ids(whole)]);
482477
for (const [id, row] of Object.entries(after)) expect({ caller, door, id, row }).toEqual({ caller, door, id, row: null });
483478
}
@@ -486,13 +481,13 @@ describe('ADR-0055 §1 · §3 — every row a write stores in a controlled_by_pa
486481

487482
describe('an update never empties the master reference a detail derives its access from', () => {
488483
for (const caller of Object.keys(CALLERS) as Caller[]) {
489-
it(`${caller}: under a reference validation does not judge, it is refused on every update shape, and nothing is written`, async () => {
484+
it(`${caller}: under a reference validation does not judge, it is refused on every update shape as the declaration defect, and nothing is written`, async () => {
490485
const { user, onBehalf } = CALLERS[caller];
491486
const context = await rig.contextOf(user, onBehalf);
492487
for (const shape of UPDATES) {
493488
const id = await rig.seed(UNJUDGED, free('rls'), user);
494489
const outcome = await rig.update[shape](UNJUDGED, id, { master: null, note: 'written' }, context);
495-
expect({ shape, outcome }).toMatchObject({ shape, outcome: { kind: 'refused', code: 'MISSING_REQUIRED_FIELD', status: 422 } });
490+
expect({ shape, outcome }).toMatchObject({ shape, outcome: { kind: 'refused', code: 'INVALID_METADATA', status: 422 } });
496491
expect({ shape, row: (await rig.stored(UNJUDGED, [id]))[id] }).toEqual({ shape, row: { master: free('rls'), note: 'seed' } });
497492
// The control: the same update leaving the reference out lands.
498493
const control = await rig.update[shape](UNJUDGED, id, { note: 'written' }, context);
@@ -515,10 +510,10 @@ describe('ADR-0055 §1 · §3 — every row a write stores in a controlled_by_pa
515510
it('the master the row is stored under is asked first: one the caller may not edit refuses on it', async () => {
516511
const context = await rig.contextOf(MEMBER, false);
517512
for (const shape of UPDATES) {
518-
const id = await rig.seed(UNJUDGED, held('rls'), MEMBER);
519-
const outcome = await rig.update[shape](UNJUDGED, id, { master: null }, context);
513+
const id = await rig.seed(D.rls, held('rls'), MEMBER);
514+
const outcome = await rig.update[shape](D.rls, id, { master: null }, context);
520515
expect({ shape, outcome }).toMatchObject({ shape, outcome: { kind: 'refused', code: 'PERMISSION_DENIED', status: 403 } });
521-
expect({ shape, row: (await rig.stored(UNJUDGED, [id]))[id] }).toEqual({ shape, row: { master: held('rls'), note: 'seed' } });
516+
expect({ shape, row: (await rig.stored(D.rls, [id]))[id] }).toEqual({ shape, row: { master: held('rls'), note: 'seed' } });
522517
}
523518
});
524519
});

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

Lines changed: 21 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ import { matchesFilterCondition } from '@objectstack/formula';
4848
// to the source in the checkout rather than a prebuilt dist.
4949
import { validateRecord, assertEngineFindOnePredicate } from '@objectstack/objectql';
5050
import type { PermissionSet } from '@objectstack/spec/security';
51-
import { ObjectSchema } from '@objectstack/spec/data';
51+
import { ObjectSchema, controlledByParentMasterRefusal } from '@objectstack/spec/data';
5252

5353
const REP = 'usr_rep';
5454
const OTHER = 'usr_other';
@@ -100,11 +100,13 @@ const CONTACT_SCHEMA_NO_MASTER_DETAIL = {
100100
* `validateRecord` (`@objectstack/objectql`) walks every declared field on an
101101
* insert but skips provenance-flagged ones outright — `if (def.system ||
102102
* def.readonly) continue;` — before the required check, and never fires on a
103-
* field that is not `required` at all. The `readonly` / `system` shapes below
104-
* are AUTHORABLE (nothing at runtime refuses either flag on a required
105-
* `master_detail`), so on each of them this gate is the only refusal an absent
106-
* master FK meets, and each must still answer 422 — the suite asserts that
107-
* against the REAL validator rather than against a belief about it.
103+
* field that is not `required` at all. On the `readonly` / `system` shapes
104+
* below this gate is therefore the only refusal an absent master FK meets —
105+
* the suite asserts that against the REAL validator rather than against a
106+
* belief about it. Neither is authorable any more: the parse refuses both
107+
* (`master-not-writable`, #25092), so they reach the runtime only through a
108+
* door that does not parse, and there the gate refuses every insert under
109+
* them as the declaration defect, `422 INVALID_METADATA` (#25095).
108110
*
109111
* [#23100] The first shape, a `master_detail` with no `required`, was the third
110112
* member of this set while `resolveCbpRelation`'s second fallback resolved it.
@@ -718,8 +720,9 @@ describe('[#5815] getReadFilter enforces the same read scope as the engine middl
718720
* 2026-08-15 supersedes #7474's envelope choice for one of its two shapes. An
719721
* INSERT that omits the FK is handed to required-field validation (`400
720722
* VALIDATION_FAILED` with `fields[]`) wherever validation provably refuses it;
721-
* the row above still holds for the stored-row shape and for the three
722-
* declarations validation does not cover. The insert leg below was rewritten
723+
* the row above still holds for the stored-row shape. [#25095] Of the three
724+
* declarations validation does not cover, the two flagged ones now answer an
725+
* insert `422 INVALID_METADATA` instead (the third resolves no relation). The insert leg below was rewritten
723726
* for that ruling, not adjusted to match observed behaviour — the successor
724727
* asserts both sides of the condition.
725728
*/
@@ -917,7 +920,7 @@ describe('[#7474] the six refusal legs answer with six envelopes, not one', () =
917920
});
918921

919922
/**
920-
* [#8688] The three shapes the stand-down deliberately does NOT cover.
923+
* [#8688] The shapes the stand-down deliberately does NOT cover.
921924
*
922925
* `validateRecord` skips provenance-flagged fields before the required check
923926
* (`if (def.system || def.readonly) continue;`) and never fires on a field
@@ -926,23 +929,28 @@ describe('[#7474] the six refusal legs answer with six envelopes, not one', () =
926929
* (`fk IN (readable masters)`), so readable by nobody, and answering 422 on
927930
* every later by-id write. Each case asserts BOTH halves: the gate still
928931
* refuses, AND the real validator raises nothing, which is why it must.
932+
*
933+
* [#25095] The gate's answer for the two flagged shapes moved: the parse
934+
* refuses the declaration (`master-not-writable`), and the gate refuses every
935+
* insert under it as that defect, `422 INVALID_METADATA` with the parse's own
936+
* message, before the empty-master branch is reached.
929937
*/
930938
it.each([
931939
['`required` + `readonly`', 'master-readonly' as const, CONTACT_SCHEMA_MASTER_READONLY],
932940
['`required` + `system`', 'master-system' as const, CONTACT_SCHEMA_MASTER_SYSTEM],
933-
])('[#8688] 422 MISSING_REQUIRED_FIELD survives on insert: %s', async (_label, detail, schema) => {
941+
])('[#8688 → #25095] the gate still refuses an insert omitting the master: %s', async (_label, detail, schema) => {
934942
const payload = { name: 'New contact' };
935943

936944
// Validation does not cover this shape — nothing downstream would refuse.
937945
expect(() => validateRecord(schema as any, payload, 'insert')).not.toThrow();
938946

939-
// …so the gate keeps answering, in the envelope and wording it always had.
947+
// …so the gate answers, as the declaration defect the parse refuses.
940948
const h = await boot({ shareLevel: 'edit', detail });
941949
const err = await refusalOf(h.insertContact(payload));
942-
expect(err.code).toBe('MISSING_REQUIRED_FIELD');
950+
expect(err.code).toBe('INVALID_METADATA');
943951
expect(err.status).toBe(422);
944952
expect(err.statusCode).toBe(422);
945-
expect(err.message).toContain("did not supply 'account'");
953+
expect(err.message).toContain(controlledByParentMasterRefusal(schema.name, schema.sharingModel, schema.fields)!.message);
946954
expect(err.message).not.toContain('requires edit access to its master record');
947955
});
948956

0 commit comments

Comments
 (0)