|
| 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 | +} |
0 commit comments