Skip to content

Commit 5679a8d

Browse files
committed
fix(objectql,rest,metadata-core): serve capability-gated stored metadata rows only to holders of the type's read capability
One read row for datasource-family documents, shared by the /meta type gate and a new engine read gate on the stored-metadata tables; realtime events of those rows carry no body. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L9qibwurKjbb54r3yD6yJg
1 parent 630b407 commit 5679a8d

6 files changed

Lines changed: 203 additions & 6 deletions

File tree

‎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: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
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 engine read of the family's rows — the generic data door's list,
18+
* get, query, count and export legs on both transports, and every other
19+
* reader that runs a caller's context through the engine — narrowed by
20+
* {@link storedMetadataTypesWithheldFrom}, which the engine composes into
21+
* the read's predicate (`stored-metadata-type-read-gate.ts`,
22+
* `@objectstack/objectql`).
23+
*
24+
* One operation reached through two mounted routes cannot admit two different
25+
* sets of callers, so both read THIS table. It lives here because the `/meta`
26+
* gate lives in `@objectstack/rest` and the engine gate in
27+
* `@objectstack/objectql`, neither of which depends on the other, and this
28+
* package is the one both already depend on. `@objectstack/rest` re-exports it
29+
* as `META_TYPE_READ_CAPABILITIES`, the same frozen object.
30+
*
31+
* ## The rows, and why each capability
32+
*
33+
* - `datasource` → `manage_platform_settings`. The datasource family's own
34+
* door — `GET /api/v1/datasources[/:name]` (`DATASOURCE_ADMIN_CAPABILITY`,
35+
* `@objectstack/service-datasource`) — serves exactly that configuration and
36+
* admits only this capability.
37+
* - `external_catalog` → `manage_platform_settings`. The cached remote-schema
38+
* snapshot of a federated datasource: the remote tables and columns the
39+
* federation family's read door introspects live and admits only this
40+
* capability for.
41+
*
42+
* ⛔ A row names the capability the type's OWN door already requires —
43+
* matched, never minted; a type with no such door has no row. ⛔ Never a
44+
* second copy of this table at either exit.
45+
*/
46+
export const STORED_METADATA_TYPE_READ_CAPABILITIES: Readonly<Record<string, string>> = Object.freeze({
47+
datasource: 'manage_platform_settings',
48+
external_catalog: 'manage_platform_settings',
49+
});
50+
51+
/**
52+
* [#27884] The stored metadata types a caller is NOT served, read from
53+
* {@link STORED_METADATA_TYPE_READ_CAPABILITIES}: every type whose capability
54+
* is absent from the caller's resolved `systemPermissions` (the capability set
55+
* the request's authorization resolver stamps on the execution context).
56+
*
57+
* Empty for a holder of every row's capability. Every listed type for a caller
58+
* that carries no capability set at all, an anonymous one included: absence is
59+
* never a grant. The caller's `isSystem` is not read here — an elevated read is
60+
* the platform's own, and the engine gate admits it before asking.
61+
*/
62+
export function storedMetadataTypesWithheldFrom(caller: unknown): string[] {
63+
const held = caller && typeof caller === 'object'
64+
? (caller as { systemPermissions?: unknown }).systemPermissions
65+
: undefined;
66+
const holds = Array.isArray(held) ? held : [];
67+
return Object.entries(STORED_METADATA_TYPE_READ_CAPABILITIES)
68+
.filter(([, capability]) => !holds.includes(capability))
69+
.map(([type]) => type);
70+
}
71+
72+
/**
73+
* [#27884] Whether stored documents of `type` are served only to holders of a
74+
* capability — the question a caller-blind exit asks (a realtime event, whose
75+
* subscribers are unknown at publish, withholds such a document's body from
76+
* everyone).
77+
*/
78+
export function isCapabilityGatedStoredMetadataType(type: unknown): boolean {
79+
return typeof type === 'string'
80+
&& Object.prototype.hasOwnProperty.call(STORED_METADATA_TYPE_READ_CAPABILITIES, type);
81+
}

‎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.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
@@ -5125,6 +5127,14 @@ export class ObjectQL implements IObjectQLEngine {
51255127
if (process?.env?.OBJECTQL_WARN_LEGACY_HANDLER === '1') {
51265128
(this as any)._warnLegacyHandler = true;
51275129
}
5130+
// [#27884] The stored-row read gate: a caller-context read of a
5131+
// stored-metadata table serves a capability-gated type's documents only to
5132+
// holders of that capability — the row the `/meta` type gate reads. In the
5133+
// constructor, so no engine serves those tables without it. See
5134+
// `stored-metadata-type-read-gate.ts`.
5135+
for (const object of STORED_METADATA_TYPE_READ_GATE_OBJECTS) {
5136+
this.registerMiddleware(storedMetadataTypeReadGate, { object });
5137+
}
51285138
this.logger.info('ObjectQL Engine Instance Created');
51295139
}
51305140

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* [#27884] The engine's stored-row read gate: a caller is served a
5+
* stored-metadata row of a capability-gated type (`datasource`,
6+
* `external_catalog`) only when it holds the capability the `/meta` type gate
7+
* names for that type.
8+
*
9+
* ## Why here, and why one middleware
10+
*
11+
* A datasource document is a row of the stored-metadata family
12+
* (`sys_metadata`, and its version snapshots in `sys_metadata_history`). The
13+
* `/meta` read doors refuse a caller without `manage_platform_settings` before
14+
* any store read (`metaTypeReadRefusal`, `@objectstack/rest`), but the same row
15+
* is also reachable as a RECORD: the generic data door's list, get, query,
16+
* count and export legs, on both transports, and any other reader that runs a
17+
* caller's context through the engine. A record read is admitted by the
18+
* object's grants, and a permission set that reads every object (a built-in
19+
* administrative set below platform administration among them) reads the
20+
* family's tables like any other. So the same document admitted two sets of
21+
* callers through two exits.
22+
*
23+
* Every one of those reads passes this engine's middleware chain, so the rule
24+
* is applied once, here, from the one table both exits read
25+
* (`STORED_METADATA_TYPE_READ_CAPABILITIES`, `@objectstack/metadata-core`):
26+
* for a caller missing a row's capability, `type NOT IN (those types)` is
27+
* AND-composed into the read's predicate. ⛔ Never a second copy of the table,
28+
* and never a per-door restatement of this gate.
29+
*
30+
* ## What it answers
31+
*
32+
* No row: a list and a count exclude the withheld types, and a get of a
33+
* withheld row answers as a get of a row that does not exist, so the read is no
34+
* existence oracle either. The object's own grants, field-level security, the
35+
* tenant wall and the family's body projection still apply to every row it
36+
* leaves in. `find`, `findOne`, `count` and `aggregate` are the reads; writes
37+
* are not judged here (the generic door admits none on these tables, and the
38+
* metadata protocol writes them under its own admission).
39+
*
40+
* A holder of every row's capability is not narrowed at all. A system read
41+
* (`isSystem`) and a read with no execution context are the platform's own —
42+
* the metadata loader, the `/meta` doors' store reads, boot — and are not
43+
* narrowed, the posture every engine read gate takes.
44+
*/
45+
46+
import { isStoredMetadataBodyObject, STORED_METADATA_BODY_OBJECTS, STORED_METADATA_TYPE_COLUMN } from '@objectstack/spec/kernel';
47+
import { storedMetadataTypesWithheldFrom } from '@objectstack/metadata-core';
48+
import type { EngineMiddleware, OperationContext } from './engine.js';
49+
50+
/** The engine reads this gate narrows. */
51+
export const STORED_METADATA_TYPE_READ_GATE_OPS: ReadonlySet<string> = new Set(['find', 'findOne', 'count', 'aggregate']);
52+
53+
/**
54+
* The predicate this gate AND-composes into a caller's read of a
55+
* stored-metadata table, or `undefined` when it composes nothing: an object
56+
* outside the family, a write, a system or context-less read, or a caller that
57+
* holds every row's capability.
58+
*/
59+
export function storedMetadataTypeReadFilter(
60+
op: Pick<OperationContext, 'object' | 'operation' | 'context'>,
61+
): Record<string, unknown> | undefined {
62+
if (!isStoredMetadataBodyObject(op.object)) return undefined;
63+
if (!STORED_METADATA_TYPE_READ_GATE_OPS.has(op.operation)) return undefined;
64+
if (!op.context || op.context.isSystem) return undefined;
65+
const withheld = storedMetadataTypesWithheldFrom(op.context);
66+
if (withheld.length === 0) return undefined;
67+
return { [STORED_METADATA_TYPE_COLUMN]: { $nin: withheld } };
68+
}
69+
70+
/** The gate itself: compose the filter into the read's WHERE, then go on. */
71+
export const storedMetadataTypeReadGate: EngineMiddleware = async (ctx, next) => {
72+
const filter = storedMetadataTypeReadFilter(ctx);
73+
if (filter) {
74+
// A read with no AST would have nothing to narrow; fail closed rather than
75+
// serve it unnarrowed.
76+
const ast = (ctx.ast ??= { object: ctx.object } as NonNullable<OperationContext['ast']>);
77+
ast.where = ast.where ? { $and: [ast.where, filter] } : filter;
78+
}
79+
return next();
80+
};
81+
82+
/** The tables the gate is registered on — the family, by its one definition. */
83+
export const STORED_METADATA_TYPE_READ_GATE_OBJECTS: readonly string[] = Object.freeze([...STORED_METADATA_BODY_OBJECTS]);

‎packages/rest/src/meta-item-read-gate.ts‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,9 @@ import {
7777
relateObjectSchemaMaskPosture,
7878
resolveObjectSchemaRuntimeView,
7979
type ObjectSchemaMaskPosture,
80+
// [#27884] The type-level read row, shared with the engine's stored-row
81+
// read gate — see `META_TYPE_READ_CAPABILITIES` below.
82+
STORED_METADATA_TYPE_READ_CAPABILITIES,
8083
} from '@objectstack/metadata-core';
8184
import { ANONYMOUS_DENY_CODE, ANONYMOUS_DENY_MESSAGE, ANONYMOUS_DENY_STATUS } from '@objectstack/core';
8285
// [#22614] The registry's one spelling of a container's binding, through its
@@ -2070,11 +2073,15 @@ export function isPublicAudienceRead(
20702073
* (every route `registerMetadataEndpoints` mounts) and the runtime
20712074
* dispatcher's `handleMetadataRequest`. ⛔ A row added here reaches both; a
20722075
* check added in one transport alone is the split this module exists to close.
2076+
*
2077+
* [#27884] The table itself is `STORED_METADATA_TYPE_READ_CAPABILITIES`
2078+
* (`@objectstack/metadata-core`), and this name is that same frozen object. The
2079+
* engine's stored-row read gate (`@objectstack/objectql`) narrows every
2080+
* caller-context read of `sys_metadata` / `sys_metadata_history` by the same
2081+
* row, so the generic data door cannot serve a document of a listed type to a
2082+
* caller this gate refuses. A row is added THERE, and reaches both exits.
20732083
*/
2074-
export const META_TYPE_READ_CAPABILITIES: Readonly<Record<string, string>> = Object.freeze({
2075-
datasource: 'manage_platform_settings',
2076-
external_catalog: 'manage_platform_settings',
2077-
});
2084+
export const META_TYPE_READ_CAPABILITIES: Readonly<Record<string, string>> = STORED_METADATA_TYPE_READ_CAPABILITIES;
20782085

20792086
/**
20802087
* [#21087] Why a `/meta` read of a {@link META_TYPE_READ_CAPABILITIES} type is

0 commit comments

Comments
 (0)