Skip to content

Commit d1aee72

Browse files
committed
fix(metadata-protocol)!: a datasource save may name only its own stored credentials reference
A non-system save of a datasource through the metadata save door may name, in external.credentialsRef, only the reference its own stored row already holds (the own-reference rule). Anything else is refused with VALIDATION_ERROR / 400 before anything is written, with one answer whatever the reference names. Server-stated rewrites keep their pass-through. The judge is a helper beside protocol.ts; protocol.ts gains its import and one call site. Claude-Session: https://claude.ai/code/session_016WV4cx2wNeyC4kD8R4P7Ns Co-authored-by: Claude <noreply@anthropic.com>
1 parent d816620 commit d1aee72

2 files changed

Lines changed: 107 additions & 0 deletions

File tree

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* [#27762] The own-reference rule on the metadata save door, for a
5+
* `datasource` body's `external.credentialsRef`.
6+
*
7+
* The rule is the one #27582 set for the engine's secret fields and #27722
8+
* applied to the datasource admin door's create: **a non-system write may only
9+
* seal a new value or keep its own record's stored reference.** A credentials
10+
* reference is minted by the platform when a secret is bound (the datasource
11+
* admin door's `secret`), and the readers of a stored datasource act on
12+
* whatever reference its row holds. This door seals nothing, so the one
13+
* reference a save through it may name is the one its own stored row already
14+
* holds:
15+
*
16+
* - a create (no stored row) naming any reference is refused;
17+
* - an edit naming a reference other than its row's, or naming one where its
18+
* row holds none, is refused;
19+
* - an edit sending back its row's own reference — the GET → edit → PUT
20+
* round trip, since the read serves the reference — keeps it, and so does a
21+
* first draft sending back the reference of the active row it overlays;
22+
* - a body that names no reference is not judged here (what it stores is
23+
* unchanged by this rule).
24+
*
25+
* "Its own stored row" is the row the save writes, read the way
26+
* {@link authoredLockFamily} reads it for the lock family: the repository's
27+
* write address for the save's state, package and bundle member, and for a
28+
* draft with no draft row yet, the active row it overlays. Stored rows only:
29+
* a code-defined datasource is refused by the package door before this is
30+
* asked, and its declaration is no stored row.
31+
*
32+
* Refused `VALIDATION_ERROR` / 400 before anything is written, with ONE answer
33+
* whatever the reference names: the judge compares the value with the save's
34+
* own row and nothing else, never looks the reference up, and the message
35+
* never echoes it.
36+
*
37+
* Every save through `saveMetaItem` is judged — the REST `PUT` doors, the
38+
* runtime dispatcher's `/meta` door, MCP and in-process authoring, and the
39+
* package copy and unmanaged import, which write new rows that hold no
40+
* reference of their own. The server-stated rewrites of a row this store
41+
* already holds (`source` set: the stored-metadata migration) keep their
42+
* pass-through, as the system principal does under the #27582 rule.
43+
*/
44+
45+
import { itemDiscriminator } from '@objectstack/metadata-core';
46+
import type { SysMetadataRepository } from './sys-metadata-repository.js';
47+
48+
/** The `external.credentialsRef` a body names, or `undefined` when it names none. */
49+
function namedCredentialsRef(body: unknown): unknown {
50+
if (!body || typeof body !== 'object' || Array.isArray(body)) return undefined;
51+
const external = (body as { external?: unknown }).external;
52+
if (!external || typeof external !== 'object' || Array.isArray(external)) return undefined;
53+
return (external as { credentialsRef?: unknown }).credentialsRef;
54+
}
55+
56+
/**
57+
* The refusal a `datasource` save owes when its body names an
58+
* `external.credentialsRef` its own stored row does not hold, else `undefined`.
59+
* See the module header for the rule, the row it reads and who passes.
60+
*/
61+
export async function datasourceCredentialsRefSaveRefusal(args: {
62+
repo: SysMetadataRepository;
63+
/** Singular type name. */
64+
type: string;
65+
name: string;
66+
item: unknown;
67+
mode: 'draft' | 'publish';
68+
packageId: string | null | undefined;
69+
/** The server-stated `source` of a rewrite; `undefined` for every authoring save. */
70+
source: string | undefined;
71+
}): Promise<(Error & { code: 'VALIDATION_ERROR'; status: 400 }) | undefined> {
72+
if (args.type !== 'datasource' || args.source !== undefined) return undefined;
73+
const named = namedCredentialsRef(args.item);
74+
if (named === undefined) return undefined;
75+
const ref = { type: args.type, name: args.name, org: 'env' } as Parameters<SysMetadataRepository['headAt']>[0];
76+
const state: 'active' | 'draft' = args.mode === 'draft' ? 'draft' : 'active';
77+
const member = itemDiscriminator(args.type, args.item);
78+
const target = await args.repo.headAt(ref, { state, packageId: args.packageId ?? null, member });
79+
let head = target.head;
80+
if (!head && state === 'draft') {
81+
head = (await args.repo.headAt(ref, { state: 'active', packageId: target.packageId, member })).head;
82+
}
83+
const own = namedCredentialsRef(head?.body);
84+
if (typeof own === 'string' && own === named) return undefined;
85+
const err = new Error(
86+
`Datasource '${args.name}' was not saved: \`external.credentialsRef\` may only name the credentials `
87+
+ `reference this datasource's own stored definition already holds, because a reference is minted by the `
88+
+ `platform when a secret is bound. Send back the reference a read of this datasource serves, or omit the `
89+
+ `key to save it with no credential bound. To bind a credential, send the secret to the datasource admin `
90+
+ `door instead (Setup → Datasources, \`POST /api/v1/datasources\` or \`PATCH /api/v1/datasources/${args.name}\`).`,
91+
) as Error & { code: 'VALIDATION_ERROR'; status: 400 };
92+
err.code = 'VALIDATION_ERROR';
93+
err.status = 400;
94+
return err;
95+
}

‎packages/metadata-protocol/src/protocol.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -436,6 +436,8 @@ import { isWritablePackage, resolveAppPackageIdKey, shouldDropStorage, uninstall
436436
import { refuseUnmintableMetaType } from './protocol-unmintable-meta-type.js';
437437
// [#25467 cut 33] The deployment's SDUI component manifest, and the load-time page `requires` report against it.
438438
import { reportPageRequiresAbsentAtLoad, resolveSduiManifest } from './protocol-sdui-manifest.js';
439+
// [#27762] The own-reference rule for a datasource body's `external.credentialsRef` on the save door.
440+
import { datasourceCredentialsRefSaveRefusal } from './protocol-datasource-credentials-ref.js';
439441

440442
/**
441443
* Canonical Zod schema per metadata type lives in
@@ -21282,6 +21284,16 @@ export class ObjectStackProtocolImplementation implements
2128221284
if (datasourceRefusal) throw datasourceRefusal;
2128321285
}
2128421286

21287+
// [#27762] A `datasource` body may name, in `external.credentialsRef`, only the reference its own stored row
21288+
// holds: refused 400 before the authoring gate and every write. See {@link datasourceCredentialsRefSaveRefusal}.
21289+
{
21290+
const credentialsRefRefusal = await datasourceCredentialsRefSaveRefusal({
21291+
repo: this.getOverlayRepo(), type: singularType, name: request.name, item: request.item,
21292+
mode, packageId: request.packageId, source: request.source,
21293+
});
21294+
if (credentialsRefRefusal) throw credentialsRefRefusal;
21295+
}
21296+
2128521297
// [ADR-0138 D2b] A flow published with `runAs: 'system'` while an
2128621298
// anonymous endpoint of `type: 'flow'` names it is refused, in publish
2128721299
// mode only (a draft does not execute; its publish is judged at the

0 commit comments

Comments
 (0)