Skip to content

Commit 119931d

Browse files
fix(objectql,rest,metadata-core)!: a datasource definition's stored row is served only to datasource administrators (#27884) (#28465)
domain:server#1 · os-tesla · session_01L9qibwurKjbb54r3yD6yJg <!-- claude-projects-attribution: {"github_login":"os-tesla"} --> _Requested by **Tesla** · [project thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6JaoLxa2hmovTvgRDEhw3svMof)_ Fixes #27884 Clause-②: no (narrowing for readers below datasource administration) Metadata-protocol: none ## 维护者速读 - 改了什么:数据源定义(datasource / external_catalog)所在的元数据存储行,现在只对持有 `manage_platform_settings` 的数据源管理员提供;与 `/meta` 类型读取门用的是同一张“类型→能力”表,没有新增规则、权限名或键。 - 为什么改:同一份数据源定义原来在两个出口对两组调用者开放,按裁决 A 统一为同一组读者;连接配置的问题也由本卡关闭。 - 风险与回滚:低于数据源管理员的读者不再能看到这些行(BREAKING 读集收窄,changeset 已写明补救);管理员与系统读取不变;回滚即还原本 PR。 - 先看:`packages/metadata-core/src/stored-metadata-type-read-admission.ts`(唯一的那张表),再看 `packages/objectql/src/stored-metadata-type-read-gate.ts`。 - 两分钟验证:`pnpm --filter @objectstack/objectql exec vitest run src/stored-metadata-type-read-gate.test.ts` 与 `pnpm --filter @objectstack/rest exec vitest run src/meta-type-read-stored-row-parity.test.ts`。 - 需要你做的:席位的契约复审(收窄一侧)后落地。 ## What changes A stored-row read exit admits only datasource administrators. - **One row.** The type-to-capability table that the metadata read door already used moves to `@objectstack/metadata-core` as `STORED_METADATA_TYPE_READ_CAPABILITIES` (`datasource`, `external_catalog` → `manage_platform_settings`), with `storedMetadataTypesWithheldFrom(caller)` and `isCapabilityGatedStoredMetadataType(type)`. `@objectstack/rest` keeps exporting `META_TYPE_READ_CAPABILITIES`, now the same frozen object; the metadata read door answers exactly as before. - **The stored row.** The engine applies that same row to every caller-context read of the stored-metadata tables (`find`, `findOne`, `count`, `aggregate`): a caller without a type's capability is served no row of that type, and a read of such a row's id answers as a read of a row that does not exist. Holders of the capability, platform administrators among them, are served everything as before; system reads are unchanged. - **Events.** A record-change event of a row of a gated type carries no metadata body to any subscriber. - **Flows.** A flow run under a user identity is a caller like any other: below datasource administration its read of a gated type is served no row. A flow run under the system identity is unchanged. - **Docs.** The isSystem census page gains the row for the new gate's system-read exemption (generated register refreshed). - No new rule, permission name or key. No `packages/spec` change, no `packages/metadata-protocol/src/protocol.ts` change. ## Why Ruling A on #27884 (record 6545628488): one document admits one set of callers at every exit that serves it, reusing the one capability row the `/meta` type gate names. Caller-aware redaction and a redactor-type parameter are out of scope. ## Verification - Unit pins (objectql): an administrator reads the row whole; a caller below datasource administration and a plain reader are served no gated row on find / findOne / count / aggregate; the history table is gated by the same row; a system read is not narrowed; the composed predicate names exactly the withheld types; events of gated rows withhold the body while an ungated row keeps it. - Parity pins (rest): `META_TYPE_READ_CAPABILITIES` is the shared frozen row, and for six callers the metadata door refuses a type exactly when the stored-row gate withholds it. - Dogfood (booted stack, platform security composition): an administrator is served the row whole; callers below datasource administration are served nothing; for each caller the stored row is served exactly when the metadata door serves the definition. - Ablations, each red then restored byte-identical: gate removed (4 objectql pins red), row withheld from everyone (3 red, the administrator pin among them), event arm removed (2 red), a second copy of the row in rest (3 parity pins red), gate removed from the built objectql dist (dogfood + parity pins red; and, separately, the 3 user-identity flow pins red with the other 22 in those files green). - Suites: objectql 506 files / 9836 tests passed; metadata-core + rest 21 files / 875 tests passed; sibling reader suite `@objectstack/service-automation` 244 files / 3105 tests passed (its flow `get_record` pins on the stored-metadata family now run their projection cases under the system identity and pin that a user-identity run below datasource administration is served no row); typecheck of the three packages exit 0; scoped `eslint` over the touched files exit 0; derived gates all exit 0 on the final head (record below); full `@objectstack/dogfood` battery (record below). <!-- verification-record --> Verification record, final head `0b381cd7`: - `node scripts/pm/dispatch-gates.mjs --commands` on `0b381cd7` → 96 derived commands, all run with `</dev/null`, all `exit 0`; `dispatch-gates --ran` → 96 derived, 96 run, 0 NOT-MEASURED, 0 UNRUN. - Fixed during the sweep: `check:objectql-double-limit` (pin driver honours the limit), `check:query-options-erasure` (typed query options, test surface back to 236), `check:where-matcher` (pin matcher refuses unknown combinators), `check:system-context-census` (census row 18d + regenerated register). - `pnpm --filter @objectstack/dogfood test` (whole battery on `1e838c5c`, under the verify lock, concurrent with a gate sweep): 361 files passed, 3 skipped, 1 failed — `automation-authoring-doors-durable.dogfood.test.ts`, a 5000 ms test timeout on a flow update under the shared load; that file re-run alone: 7/7 passed. The commits after it change prose, a changeset line and service-automation tests only; the new dogfood file re-ran on `de1f609b`: 4/4 passed. - `@objectstack/service-automation` whole suite on `0b381cd7`: 244 files / 3105 tests passed. - `npx eslint` over the touched source and test files: exit 0. Clause-② and Metadata-protocol are declared on the lines above and in the changeset. ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (`packages/spec` untouched) - [x] 2. Every name I added uses the casing for its kind. - [x] 3. No formatter ran; `pnpm lint` passes (scoped to the touched files). - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [x] 6. `packages/spec` touched: n/a. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English (the 维护者速读 section is the maintainer's Chinese digest). - [x] The *Before Submitting* list in CONTRIBUTING.md is done. ## Acceptance notes - Readers below datasource administration are no longer served stored datasource or federation-catalog rows; the remedy is to grant `manage_platform_settings` or read through the datasource admin door as such a caller. - Contract review: PASS at `0b381cd7`. --- https://claude.ai/code/session_01L9qibwurKjbb54r3yD6yJg 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 9b1dc99 commit 119931d

14 files changed

Lines changed: 670 additions & 20 deletions
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
'@objectstack/metadata-core': patch
3+
'@objectstack/objectql': patch
4+
'@objectstack/rest': patch
5+
---
6+
7+
fix(objectql,rest,metadata-core)!: a datasource definition's stored row is served only to datasource administrators, whichever exit reads it (#27884)
8+
9+
Clause-②: no (narrowing for readers below datasource administration)
10+
Metadata-protocol: none
11+
12+
<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed, renamed or re-shaped, and no metadata an author writes changes meaning: a stored datasource definition is written, stored and served to its administrators exactly as before. What narrows is which readers a stored row of a capability-gated type is served to. There is nothing for a migration to rewrite and no tombstone; a reader who needs the definition is granted the capability. -->
13+
14+
**BREAKING** read-set narrowing for callers below datasource administration. The metadata read door already served a `datasource` or `external_catalog` definition only to holders of `manage_platform_settings`, the capability the datasource family's own door requires. The stored row each definition lives in now admits the same readers, so one document admits one set of callers at every exit.
15+
16+
- **One row.** The type-to-capability table moves to `@objectstack/metadata-core` as `STORED_METADATA_TYPE_READ_CAPABILITIES`, with `storedMetadataTypesWithheldFrom(caller)` and `isCapabilityGatedStoredMetadataType(type)`. `@objectstack/rest` keeps exporting `META_TYPE_READ_CAPABILITIES`, now that same frozen object, and the metadata read door answers exactly as before.
17+
- **Now.** A caller-context read of a stored metadata row of a listed type, by a caller without the type's capability, is served no row: a list or count leaves it out, and a read of its id answers as a read of a row that does not exist. Holders of the capability, platform administrators among them, are served everything as before. System reads are unchanged.
18+
- **Events.** A record-change event of such a row carries no metadata body to any subscriber; the row's other columns are unchanged.
19+
- **Who sees it.** A reader below datasource administration is no longer served stored datasource or federation-catalog rows.
20+
21+
**The remedy.** Grant `manage_platform_settings` to a caller that needs a datasource definition, or read it through the datasource admin door (`GET /api/v1/datasources/:name`) as such a caller.

‎content/docs/permissions/system-context.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,7 @@ bugs — it is the protection or the side effect that silently does not happen.
122122
| 18 | REST anonymous-deny seam satisfied | rest | Get: `enforceAuth` passes with no `userId`. Not reachable from the wire — `isSystem` is never set on an inbound request | `enforceAuth` |
123123
| 18b | Settings namespace read scope not applied | service-settings | Get: a read of `sys_setting`, `sys_setting_audit` or `sys_platform_setting` across every namespace, whatever each namespace's `readPermission` names — the settings service's own reads of its stores take this path. Lose: the per-namespace read gate the generic data API applies to every other caller, the same rule the settings routes enforce | `settingsReadDoorMiddleware` |
124124
| 18c | **Credential-column filter / sort refusal not applied** — a `where`, `orderBy`, per-aggregation `filter` or `expand` entry naming a `password` / `secret` column is evaluated | objectql | Get: the server's own match on a stored credential value, a lookup that never returns it. Every other caller, administrators included, is refused `400 INVALID_FIELD` for anything but a has-a-value check (ADR-0100). Lose: nothing a wire caller reaches — `isSystem` is never set on an inbound request | `rejectCredentialEvaluation` |
125+
| 18d | **Stored-metadata type read gate not applied** — a read of `sys_metadata` / `sys_metadata_history` is not narrowed by the capability its row's type requires | objectql | Get: every row of the family on `find` / `findOne` / `count` / `aggregate` — the metadata loader, the `/meta` doors' own store reads, boot (a read with no execution context is not narrowed either). Lose: the narrowing that serves a stored row of a capability-gated type (`datasource`, `external_catalog`) only to holders of the capability the `/meta` type gate names for it | `storedMetadataTypeReadFilter` |
125126

126127
### 2. Write pipeline and data integrity
127128

@@ -543,6 +544,7 @@ and CI refuses one that differs from what the tree produces.
543544
| `packages/objectql/src/engine.ts#insert` | 3 | 21, 22 |
544545
| `packages/objectql/src/engine.ts#isSystem` | 1 | 64 |
545546
| `packages/objectql/src/engine.ts#update` | 4 | 19, 20 |
547+
| `packages/objectql/src/stored-metadata-type-read-gate.ts#storedMetadataTypeReadFilter` | 1 | 18d |
546548
| `packages/observability/src/perf-timing.ts#isPerfDisclosurePrincipal` | 1 | 13 |
547549
| `packages/plugins/organizations/src/organizations-plugin.ts#start` | 1 | 62 |
548550
| `packages/plugins/plugin-approvals/src/approval-service.ts#comment` | 1 | 43 |

‎packages/metadata-core/src/index.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,11 @@ export * from './item-key-discriminators.js';
101101
// axis. Sunk here because the doors live in `@objectstack/runtime` and
102102
// `@objectstack/rest`, which share no other common home.
103103
export * from './meta-write-capability.js';
104+
// [#27884] The read-side twin: which readers a stored metadata document of a
105+
// capability-gated type (datasource, external_catalog) is served to, asked by the
106+
// `/meta` type gate (`@objectstack/rest`) and the engine's stored-row read gate
107+
// (`@objectstack/objectql`) alike.
108+
export * from './stored-metadata-type-read-admission.js';
104109

105110
// [commit 1408fe385 / #10101] The shared platform-row organization resolver — sunk here
106111
// from `@objectstack/plugin-audit` per the maintainer ruling recorded on
Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* [#27884] Which READERS a stored metadata document of a capability-gated type
5+
* is served to — the ONE row both exits that serve the document ask.
6+
*
7+
* ## The two exits, one row
8+
*
9+
* A datasource document (a driver, its connection configuration and the handle
10+
* of its bound secret) is stored as a row of the stored-metadata family
11+
* (`sys_metadata`, and its version snapshots in `sys_metadata_history`), typed
12+
* by the row's `type` column. It is served through two exits:
13+
*
14+
* - the `/meta` read doors, whose type-level read admission
15+
* (`metaTypeReadRefusal`, `@objectstack/rest`) refuses a caller without the
16+
* row's capability before any store read; and
17+
* - every caller-context engine read of the family's rows, whichever door
18+
* issues it, narrowed by
19+
* {@link storedMetadataTypesWithheldFrom}, which the engine composes into
20+
* the read's predicate (`stored-metadata-type-read-gate.ts`,
21+
* `@objectstack/objectql`).
22+
*
23+
* One operation reached through two mounted routes cannot admit two different
24+
* sets of callers, so both read THIS table. It lives here because the `/meta`
25+
* gate lives in `@objectstack/rest` and the engine gate in
26+
* `@objectstack/objectql`, neither of which depends on the other, and this
27+
* package is the one both already depend on. `@objectstack/rest` re-exports it
28+
* as `META_TYPE_READ_CAPABILITIES`, the same frozen object.
29+
*
30+
* ## The rows, and why each capability
31+
*
32+
* - `datasource` → `manage_platform_settings`. The datasource family's own
33+
* door — `GET /api/v1/datasources[/:name]` (`DATASOURCE_ADMIN_CAPABILITY`,
34+
* `@objectstack/service-datasource`) — serves exactly that configuration and
35+
* admits only this capability.
36+
* - `external_catalog` → `manage_platform_settings`. The cached remote-schema
37+
* snapshot of a federated datasource: the remote tables and columns the
38+
* federation family's read door introspects live and admits only this
39+
* capability for.
40+
*
41+
* ⛔ A row names the capability the type's OWN door already requires —
42+
* matched, never minted; a type with no such door has no row. ⛔ Never a
43+
* second copy of this table at either exit.
44+
*/
45+
export const STORED_METADATA_TYPE_READ_CAPABILITIES: Readonly<Record<string, string>> = Object.freeze({
46+
datasource: 'manage_platform_settings',
47+
external_catalog: 'manage_platform_settings',
48+
});
49+
50+
/**
51+
* [#27884] The stored metadata types a caller is NOT served, read from
52+
* {@link STORED_METADATA_TYPE_READ_CAPABILITIES}: every type whose capability
53+
* is absent from the caller's resolved `systemPermissions` (the capability set
54+
* the request's authorization resolver stamps on the execution context).
55+
*
56+
* Empty for a holder of every row's capability. Every listed type for a caller
57+
* that carries no capability set at all, an anonymous one included: absence is
58+
* never a grant. The caller's `isSystem` is not read here — an elevated read is
59+
* the platform's own, and the engine gate admits it before asking.
60+
*/
61+
export function storedMetadataTypesWithheldFrom(caller: unknown): string[] {
62+
const held = caller && typeof caller === 'object'
63+
? (caller as { systemPermissions?: unknown }).systemPermissions
64+
: undefined;
65+
const holds = Array.isArray(held) ? held : [];
66+
return Object.entries(STORED_METADATA_TYPE_READ_CAPABILITIES)
67+
.filter(([, capability]) => !holds.includes(capability))
68+
.map(([type]) => type);
69+
}
70+
71+
/**
72+
* [#27884] Whether stored documents of `type` are served only to holders of a
73+
* capability — the question a caller-blind exit asks (a realtime event, whose
74+
* subscribers are unknown at publish, withholds such a document's body from
75+
* everyone).
76+
*/
77+
export function isCapabilityGatedStoredMetadataType(type: unknown): boolean {
78+
return typeof type === 'string'
79+
&& Object.prototype.hasOwnProperty.call(STORED_METADATA_TYPE_READ_CAPABILITIES, type);
80+
}

‎packages/objectql/src/engine-realtime-publish.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,9 @@ import {
6363
omitInternalFieldsFromWriteResponse,
6464
} from '@objectstack/core';
6565
import { TenantLayer0VerdictSchema } from '@objectstack/spec/security';
66+
// [#27884] The one row of capability-gated stored metadata types — the row the
67+
// `/meta` type gate and the engine's stored-row read gate read.
68+
import { isCapabilityGatedStoredMetadataType } from '@objectstack/metadata-core';
6669
import { resolveTenantFieldName, carriesOrganization } from './tenancy/system-write-organization.js';
6770
import type { ObjectQL } from './engine.js';
6871

@@ -131,7 +134,9 @@ function eventRecordBody(value: unknown): Record<string, unknown> | undefined {
131134
*
132135
* `fullRow` is the whole written record (`input.after`), read for the `type`
133136
* column that selects the redactor — a `changes` patch need not carry it. A
134-
* body the redactor cannot judge is DROPPED from the event (fail-closed): the
137+
* body of a capability-gated type (`isCapabilityGatedStoredMetadataType`,
138+
* #27884) is DROPPED for every subscriber. A body the redactor cannot judge is
139+
* DROPPED from the event (fail-closed): the
135140
* key is omitted rather than published raw. A non-record body, and every object
136141
* outside the set, pass through unchanged. Pure: the event body is a fresh
137142
* object, never the stored row.
@@ -149,7 +154,13 @@ function redactEventMetadataBody(
149154
: (fullRow && typeof fullRow === 'object' && !Array.isArray(fullRow)
150155
? (fullRow as Record<string, unknown>)[STORED_METADATA_TYPE_COLUMN]
151156
: undefined);
152-
const outcome = redactStoredMetadataBody(type, body[STORED_METADATA_BODY_COLUMN]);
157+
// [#27884] A document of a capability-gated type (a datasource's connection
158+
// configuration and secret handle) is served only to holders of the type's
159+
// read capability, and the event's subscribers are not known here — so its
160+
// body is withheld from every subscriber, the fail-closed arm below.
161+
const outcome = isCapabilityGatedStoredMetadataType(type)
162+
? ({ ok: false } as const)
163+
: redactStoredMetadataBody(type, body[STORED_METADATA_BODY_COLUMN]);
153164
if (outcome.ok) {
154165
if (outcome.body === body[STORED_METADATA_BODY_COLUMN]) return body;
155166
return { ...body, [STORED_METADATA_BODY_COLUMN]: outcome.body };

‎packages/objectql/src/engine-realtime-stored-metadata-body.test.ts‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -109,16 +109,18 @@ describe('[#21120] realtime data.record.* events redact a stored metadata body',
109109
expect(published).toHaveLength(1);
110110
const payload = published[0].payload as Record<string, any>;
111111
expect(JSON.stringify(payload)).not.toContain(CRED);
112-
// The event still describes the row — type survives, the body is still present but projected.
112+
// The event still describes the row — type survives. [#27884] A datasource
113+
// body is withheld whole (the connection configuration with it): the
114+
// type's documents are served only to holders of its read capability, and
115+
// an event's subscribers are unknown at publish.
113116
expect(payload.after.type).toBe('datasource');
114-
expect(payload.after.metadata).toBeDefined();
115-
expect(JSON.parse(payload.after.metadata).config.authToken).toBeUndefined();
116-
expect(JSON.parse(payload.after.metadata).config.url).toBe('libsql://db.turso.io');
117+
expect(payload.after).not.toHaveProperty('metadata');
118+
expect(JSON.stringify(payload)).not.toContain('libsql://db.turso.io');
117119
});
118120

119-
it('a credential-free sys_metadata body rides the event unchanged', async () => {
120-
const clean = JSON.stringify({ name: 'v', driver: 'postgres', config: { host: 'h', database: 'd' } });
121-
await engine.insert('sys_metadata', { id: 'm2', type: 'datasource', name: 'v', metadata: clean });
121+
it('a credential-free sys_metadata body of an ungated type rides the event unchanged', async () => {
122+
const clean = JSON.stringify({ name: 'v', label: 'V', type: 'grid' });
123+
await engine.insert('sys_metadata', { id: 'm2', type: 'view', name: 'v', metadata: clean });
122124
const payload = published[0].payload as Record<string, any>;
123125
expect(payload.after.metadata).toBe(clean);
124126
});

‎packages/objectql/src/engine.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,8 @@ import { buildDriverOptions, driverReadScope, driverWriteTarget, engineLayer0Ver
158158
import { announceOpenMigrationGates, isOrganizationOwnershipCertified, isValueShapesMigrationVerified, noteAdmittedValueShapeViolation, readFileReferencesFlagRow, readMigrationFlagVerified, supplyTenantKeyCertifiedResolver, wasDatastoreCreatedFromEmpty } from './engine-migration-flags.js';
159159
import { ExecutionContext, ExecutionContextSchema, type InstalledPackageSource } from '@objectstack/spec/kernel';
160160
import { isStoredMetadataBodyObject } from '@objectstack/spec/kernel';
161+
// [#27884] The stored-row read gate, registered on the family's tables below.
162+
import { STORED_METADATA_TYPE_READ_GATE_OBJECTS, storedMetadataTypeReadGate } from './stored-metadata-type-read-gate.js';
161163
import type { FlowFunctionEffect } from '@objectstack/spec/automation';
162164
// Imported from spec directly rather than through `@objectstack/core`'s
163165
// re-export block: that block is labelled backward-compatibility, and this
@@ -5126,6 +5128,14 @@ export class ObjectQL implements IObjectQLEngine {
51265128
if (process?.env?.OBJECTQL_WARN_LEGACY_HANDLER === '1') {
51275129
(this as any)._warnLegacyHandler = true;
51285130
}
5131+
// [#27884] The stored-row read gate: a caller-context read of a
5132+
// stored-metadata table serves a capability-gated type's documents only to
5133+
// holders of that capability — the row the `/meta` type gate reads. In the
5134+
// constructor, so no engine serves those tables without it. See
5135+
// `stored-metadata-type-read-gate.ts`.
5136+
for (const object of STORED_METADATA_TYPE_READ_GATE_OBJECTS) {
5137+
this.registerMiddleware(storedMetadataTypeReadGate, { object });
5138+
}
51295139
this.logger.info('ObjectQL Engine Instance Created');
51305140
}
51315141

0 commit comments

Comments
 (0)