Skip to content

Commit d442c74

Browse files
committed
feat(spec,security): controlled_by_parent admits an optional master; its null-master rows read by owner
ADR-0055 §1 and §2 as amended by maintainer ruling A: the only master_detail of a controlled_by_parent object may be declared required: false. A row that names its master is read through it as before; a row whose master reference is empty is read by its owner and by View All on the detail, through a second arm OR-ed with the master arm inside computeControlledByParentFilter. Writes are unchanged. Work in progress: tests for lint and plugin-security, the ADR and the changesets follow. Co-authored-by: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WV4cxZsyeZedvM4Ea8Ahs
1 parent 98f640d commit d442c74

21 files changed

Lines changed: 816 additions & 180 deletions

‎packages/lint/src/data-model-rules.ts‎

Lines changed: 38 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -336,6 +336,19 @@ const CBP_ORPHAN_CONSEQUENCE =
336336
* 2. `required: true` + `readonly: true`;
337337
* 3. `required: true` + `system: true`.
338338
*
339+
* ⚠️ Amended by ruling A of #30905 (ADR-0055 §1 as amended): the object's
340+
* ONLY `master_detail`, declared `required: false`, is its optional master — a
341+
* detail row may name none, and such a row is read by its owner and by View
342+
* All on the detail — so that spelling passes, and only `readonly` / `system`
343+
* on it is reported (the parse refuses it too, shape `master-not-writable`).
344+
* Shape 1 now reads: `required` absent (or not a boolean) on any
345+
* `master_detail`, or `false` on one beside another `master_detail`. On the
346+
* sole `master_detail` an absent `required` is reported with both honest
347+
* spellings, because the parse cannot see the omission (it reads the parsed
348+
* `false`, so it admits the optional master) while `ObjectSchema.create()`
349+
* forces it to `true`: one source, two meanings, until the author writes one.
350+
* The fix stays `required: true`, the reading the builder already gives it.
351+
*
339352
* Why these three. A `controlled_by_parent` detail derives ALL of its record
340353
* access from the master its `master_detail` reference names (ADR-0055: such an
341354
* object "must declare exactly one required `master_detail` field"). Record
@@ -394,21 +407,37 @@ function cbpMasterReferenceFinding(
394407
fieldPath: string,
395408
parent: string,
396409
def: any,
410+
masterDetailCount: number,
397411
): LintIssue | undefined {
398-
const missingRequired = def.required !== true;
412+
// [ADR-0055 §1 as amended · #30905 ruling A] The object's ONLY
413+
// `master_detail`, declared `required: false`, is its optional master — the
414+
// spelling passes. Beside another `master_detail` an explicit `false` is
415+
// judged as before; an omitted `required` is reported on every field.
416+
const soleMasterDetail = masterDetailCount === 1;
417+
const optionalMaster = soleMasterDetail && def.required === false;
418+
const missingRequired = def.required !== true && !optionalMaster;
419+
// On the sole `master_detail`, an omitted (or non-boolean) `required` has
420+
// two honest spellings; elsewhere only `required: true` is one.
421+
const eitherSpelling = missingRequired && soleMasterDetail;
399422
const flags = (['readonly', 'system'] as const).filter((flag) => def[flag] === true);
400423
if (!missingRequired && flags.length === 0) return undefined;
401424

402425
const subject = `master_detail "${objectName}.${fieldName}" → ${parent}`;
426+
const requirement = eitherSpelling
427+
? 'must declare required: true (or required: false for an optional master)'
428+
: 'must be required';
403429
// [#22161] One verdict per shape, ending in the one shared consequence; the
404430
// derivation (why the record is unreadable, why the flags skip the check)
405431
// is `os explain` text.
406432
const message = missingRequired
407433
? flags.length === 0
408-
? `${subject} must be required: ${CBP_ORPHAN_CONSEQUENCE}`
409-
: `${subject} must be required and not marked ${flags.join(' or ')}: ${CBP_ORPHAN_CONSEQUENCE}`
410-
: `${subject} is marked ${flags.join(' and ')}, which skips its required check: ` +
411-
CBP_ORPHAN_CONSEQUENCE;
434+
? `${subject} ${requirement}: ${CBP_ORPHAN_CONSEQUENCE}`
435+
: `${subject} ${requirement} and not be marked ${flags.join(' or ')}: ${CBP_ORPHAN_CONSEQUENCE}`
436+
: optionalMaster
437+
? `${subject} is the optional master and is marked ${flags.join(' and ')}, which no detail ` +
438+
'write supplies: the master reference must be writable'
439+
: `${subject} is marked ${flags.join(' and ')}, which skips its required check: ` +
440+
CBP_ORPHAN_CONSEQUENCE;
412441

413442
return {
414443
severity: 'error',
@@ -1016,7 +1045,10 @@ export function lintDataModel(objects: any[]): LintIssue[] {
10161045
// `master_detail` is a likely-wrong choice and stays a `warning`,
10171046
// byte-for-byte as before.
10181047
if (obj.sharingModel === 'controlled_by_parent') {
1019-
const finding = cbpMasterReferenceFinding(obj.name, fieldName, fieldPath, parent, def);
1048+
const masterDetailCount = fields.filter(({ def: f }) => f?.type === 'master_detail').length;
1049+
const finding = cbpMasterReferenceFinding(
1050+
obj.name, fieldName, fieldPath, parent, def, masterDetailCount,
1051+
);
10201052
if (finding) issues.push(finding);
10211053
} else if (def.required !== true) {
10221054
issues.push({

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

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -719,8 +719,10 @@ const SECURITY_CBP_NO_RELATION_EXPLANATION: RuleExplanation = {
719719
paragraphs: [
720720
'A `controlled_by_parent` object says its access comes from its master. ADR-0055 §1 names that ' +
721721
'master by exactly one `master_detail` field declared `required: true`, with a `reference` to the ' +
722-
'master object, and by nothing else: a `master_detail` without `required: true` and a required ' +
723-
'`lookup` derive no access.',
722+
'master object, or, as amended, with no such field, by the object\'s ONLY `master_detail` declared ' +
723+
'`required: false`, an optional master (a detail row with an empty master reference is read by its ' +
724+
'owner and by View All on the detail). Nothing else names it: a `master_detail` that declares no ' +
725+
'`required`, one declared `required: false` beside another, and a required `lookup` derive no access.',
724726
'Both runtime halves refuse an object without one: every read is DENIED, and every write is refused ' +
725727
'with 422 INVALID_METADATA — as a metadata defect rather than a permission denial — so the object ' +
726728
'is unusable rather than merely locked down. System objects are judged too, because the runtime ' +
@@ -3309,16 +3311,26 @@ const RELATIONSHIP_MASTER_DETAIL_REQUIRED_EXPLANATION: RuleExplanation = {
33093311
'`masterFK IN (accessible master ids)` — never matches an empty master, so a detail saved ' +
33103312
'without one is readable by nobody and refused on every later write. Record validation never ' +
33113313
'checks a field that is not `required`, and skips `readonly` and `system` fields before its ' +
3312-
'required check, so on the three shapes reported — `required` absent or false, ' +
3314+
'required check, so on the three shapes reported — `required` absent, or false beside another ' +
3315+
'`master_detail`, ' +
33133316
'`required: true` with `readonly: true`, and `required: true` with `system: true` — the ' +
33143317
'security gate (`assertControlledByParentWrite`) is the only thing refusing such an insert.',
3318+
'One spelling passes: the object\'s ONLY `master_detail`, declared `required: false`, is an ' +
3319+
'optional master (ADR-0055 §1 as amended). A detail row with an empty master reference is read ' +
3320+
'by its owner (`owner_id`) and by a holder of View All on the detail, by nobody else; a row ' +
3321+
'that names a master is read through it as before. (The security gate still refuses a write ' +
3322+
'that leaves the reference empty.) `readonly` or `system` on it is ' +
3323+
'still reported. An omitted `required` is reported on every `master_detail`: the spec parse ' +
3324+
'reads the parsed `false` and admits it as the optional master, while `ObjectSchema.create()` ' +
3325+
'forces it to `true`, so one source would mean two things. Write `required: true` (every detail ' +
3326+
'names its master) or `required: false` (a detail may name none).',
33153327
'Every `master_detail` field of such an object is judged, not only the one the runtime resolves ' +
3316-
'as the master: that is the scope `ObjectSchema.create()` enforces when it forces ' +
3317-
'`required: true` and refuses an explicit `required: false`. The spec parse also ' +
3318-
'refuses every shape that leaves the object without exactly one writable required master, so ' +
3319-
'`os validate`, `os build` and the save door stop there; a shape on a second, non-required ' +
3320-
'`master_detail` beside the master is this rule\'s report alone. One finding per field, located ' +
3321-
'at its first defect.',
3328+
'as the master: that is the scope `ObjectSchema.create()` enforces when it forces an omitted ' +
3329+
'`required` to `true` and refuses an explicit `required: false` beside another `master_detail`. ' +
3330+
'The spec parse also refuses every shape that leaves the object without exactly one writable ' +
3331+
'master, so `os validate`, `os build` and the save door stop there; a shape on a second, ' +
3332+
'non-required `master_detail` beside the master is this rule\'s report alone. One finding per ' +
3333+
'field, located at its first defect.',
33223334
DATA_MODEL_SWEEP_REACH,
33233335
],
33243336
};

‎packages/lint/src/validate-security-posture.ts‎

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,12 @@
122122
*/
123123

124124
import { parseCelToAst, sqlPredicateToCel, type CelAstNode } from '@objectstack/formula';
125-
import { controlledByParentOwnerMayEdit, isControlledByParentMasterField, referenceCarrierOf } from '@objectstack/spec/data';
125+
import {
126+
controlledByParentMasterOf,
127+
controlledByParentOwnerMayEdit,
128+
isControlledByParentMasterField,
129+
referenceCarrierOf,
130+
} from '@objectstack/spec/data';
126131
import { describeAnchorForbiddenBits, type AnchorBindingContext } from '@objectstack/spec/security';
127132
import {
128133
indexObjectGraph,
@@ -375,6 +380,12 @@ interface CbpRelation {
375380
* `security-controlled-by-parent-no-relation`, two or more is
376381
* `security-controlled-by-parent-ambiguous-relation`.
377382
*
383+
* ⚠️ Amended by ruling A of #30905 (ADR-0055 §1 as amended): with none
384+
* declared `required: true`, the object's ONLY `master_detail`, declared
385+
* `required: false` (read `=== false`, so an omitted `required` is not it), is
386+
* the one candidate, an optional master. The spec's `controlledByParentMasterOf`
387+
* picks it, as the parse does.
388+
*
378389
* This used to be a three-tier table (`CBP_TIERS`, #7503 / #14747) mirroring a
379390
* three-tier fallback in the runtime: a required `master_detail`, else ANY
380391
* `master_detail`, else a required `lookup`. ADR-0055 §1 never recorded the
@@ -400,9 +411,21 @@ interface CbpRelation {
400411
* names the real defect (the alias key) rather than this rule guessing past it.
401412
*/
402413
function cbpMasterCandidates(obj: AnyRec): CbpRelation[] {
403-
return recordsOf(obj.fields)
404-
.filter((f) => isControlledByParentMasterField(f) && refOf(f))
405-
.map((f) => ({ field: String(f.name ?? '?'), type: 'master_detail', master: refOf(f) as string }));
414+
const fields = recordsOf(obj.fields);
415+
const relationOf = (f: AnyRec): CbpRelation => ({
416+
field: String(f.name ?? '?'),
417+
type: 'master_detail',
418+
master: refOf(f) as string,
419+
});
420+
const required = fields.filter((f) => isControlledByParentMasterField(f) && refOf(f)).map(relationOf);
421+
if (required.length > 0) return required;
422+
// [ADR-0055 §1 as amended · #30905 ruling A] With no required one, the
423+
// object's only `master_detail` declared `required: false` is its optional
424+
// master — the spec's resolver says which, so the parse and this linter
425+
// still read one sentence.
426+
const master = controlledByParentMasterOf(Object.fromEntries(fields.map((f) => [String(f.name ?? '?'), f])));
427+
const optional = master?.optional ? fields.find((f) => String(f.name ?? '?') === master.field) : undefined;
428+
return optional && refOf(optional) ? [relationOf(optional)] : [];
406429
}
407430

408431
/**
@@ -636,8 +659,9 @@ function pushCbpNoRelation(findings: SecurityFinding[], objName: string, path: s
636659
// the object is unusable rather than locked down are this id's
637660
// `os explain` entry.
638661
message:
639-
`declares sharingModel 'controlled_by_parent' but no required master_detail field to derive access ` +
640-
`from, so every read is denied and every write refused (422 INVALID_METADATA)`,
662+
`declares sharingModel 'controlled_by_parent' but no master_detail field to derive access from ` +
663+
`(one declared required: true, or its only one declared required: false), so every read is ` +
664+
`denied and every write refused (422 INVALID_METADATA)`,
641665
// [#22161] One remedy line; that an object with no master decides its
642666
// own baseline, and what each value means, is this id's `os explain`
643667
// entry.

‎packages/objectql/src/engine-readable-ids-permission-formula.ts‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@
6464
* stays on the class, the contract, and its function keeps the placeholder.
6565
*/
6666

67-
import { ReadableIds, RLS_DENY_FILTER, isControlledByParentMasterField, markFilterSubtreeProvenance } from '@objectstack/spec/data';
67+
import { ReadableIds, RLS_DENY_FILTER, controlledByParentMasterOf, markFilterSubtreeProvenance } from '@objectstack/spec/data';
6868
import type { FilterCondition } from '@objectstack/spec/data';
6969
import type { ExecutionContext } from '@objectstack/spec/kernel';
7070
import { toEvalPermissions, type EvalError, type EvalPermissions } from '@objectstack/formula';
@@ -215,10 +215,13 @@ export function findUnservableControlledByParentMasters(
215215
const found: UnservableControlledByParentMaster[] = [];
216216
for (const object of this._registry.getAllObjects() as Array<{ name?: string; sharingModel?: unknown; fields?: Record<string, unknown> }>) {
217217
if (object?.sharingModel !== 'controlled_by_parent' || typeof object.name !== 'string') continue;
218-
const masters = Object.entries(object.fields ?? {}).filter(([, f]) => isControlledByParentMasterField(f));
219-
if (masters.length !== 1) continue;
220-
const [field, def] = masters[0];
221-
const master = (def as { reference?: unknown }).reference;
218+
// [ADR-0055 §1 as amended · #30905 ruling A] The one master, required or
219+
// optional: an optional master's rows that name one are read through the
220+
// same leaf over it.
221+
const relation = controlledByParentMasterOf(object.fields);
222+
if (!relation) continue;
223+
const field = relation.field;
224+
const master = (object.fields?.[field] as { reference?: unknown } | undefined)?.reference;
222225
if (typeof master !== 'string' || !this._registry.getObject(master)) continue;
223226
const uncomposable = this.uncomposableReadableIdsParent(object.name, master);
224227
if (uncomposable) found.push({ detail: object.name, field, master, ...uncomposable });

‎packages/objectql/src/engine.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1650,14 +1650,15 @@ export class ObjectQL implements IObjectQLEngine {
16501650
* master an object-scoped read middleware narrows, or one bound to another
16511651
* datasource than the detail — judged by the read path's own predicate
16521652
* ({@link uncomposableReadableIdsParent}). A detail's access derives from its
1653-
* one required `master_detail` (ADR-0055 §1), so such a declaration is one
1653+
* one master `master_detail` (ADR-0055 §1: the required one, or as amended
1654+
* its only one declared `required: false`), so such a declaration is one
16541655
* the runtime cannot honour: `ObjectQLPlugin` refuses the boot on any entry.
16551656
*
16561657
* Both facts are deployment facts (the datasource mapping, a package's
16571658
* default datasource, lifecycle routing, the middleware registrations), so
16581659
* the answer is final only once every plugin has registered its middleware —
16591660
* which several do inside their own `kernel:ready` handler. Asked earlier, it
1660-
* is short. A detail with no single required master, or whose master the
1661+
* is short. A detail with no single master, or whose master the
16611662
* registry does not hold, is no entry: other rules own those.
16621663
*/
16631664
findUnservableControlledByParentMasters(): UnservableControlledByParentMaster[] {

0 commit comments

Comments
 (0)