Skip to content

Commit de1f609

Browse files
committed
docs(objectql,rest,metadata-core): the stored-row read gate's prose states the rule only
Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L9qibwurKjbb54r3yD6yJg
1 parent 757ff0c commit de1f609

6 files changed

Lines changed: 26 additions & 40 deletions

‎packages/metadata-core/src/stored-metadata-type-read-admission.ts‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,8 @@
1414
* - the `/meta` read doors, whose type-level read admission
1515
* (`metaTypeReadRefusal`, `@objectstack/rest`) refuses a caller without the
1616
* 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
17+
* - every caller-context engine read of the family's rows, whichever door
18+
* issues it, narrowed by
2019
* {@link storedMetadataTypesWithheldFrom}, which the engine composes into
2120
* the read's predicate (`stored-metadata-type-read-gate.ts`,
2221
* `@objectstack/objectql`).

‎packages/objectql/src/stored-metadata-type-read-gate.test.ts‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -95,10 +95,7 @@ function makeDriver() {
9595

9696
/** A datasource administrator: holds the row's capability (platform administrators do). */
9797
const ADMIN = { userId: 'u_admin', systemPermissions: [CAPABILITY, 'manage_metadata', 'studio.access'] };
98-
/**
99-
* The shipped organization administrator's capability set — below datasource
100-
* administration (`organization_admin`, `@objectstack/plugin-security`).
101-
*/
98+
/** A caller below datasource administration. */
10299
const ORG_ADMIN = { userId: 'u_org_admin', systemPermissions: ['manage_org_users', 'setup.access', 'setup.write', 'manage_mailboxes'] };
103100
/** A caller that may enter Studio (and so read the history table) without datasource administration. */
104101
const STUDIO_AUTHOR = { userId: 'u_author', systemPermissions: ['studio.access', 'manage_metadata'] };
@@ -121,7 +118,7 @@ describe('[#27884] stored-row read gate on the stored-metadata tables', () => {
121118
vi.spyOn((engine as any).logger, 'debug').mockImplementation(() => undefined);
122119
});
123120

124-
it('a datasource administrator reads the row whole: connection configuration and credentialsRef', async () => {
121+
it('a datasource administrator reads the row whole', async () => {
125122
const rows = await engine.find('sys_metadata', { where: { type: 'datasource' }, context: ADMIN });
126123
expect(rows).toHaveLength(1);
127124
const body = JSON.parse(rows[0].metadata);
@@ -132,7 +129,7 @@ describe('[#27884] stored-row read gate on the stored-metadata tables', () => {
132129
expect(await engine.count('sys_metadata', { context: ADMIN })).toBe(3);
133130
});
134131

135-
for (const [label, caller] of [['the built-in organization administrator', ORG_ADMIN], ['a plain reader', READER]] as const) {
132+
for (const [label, caller] of [['a caller below datasource administration', ORG_ADMIN], ['a plain reader', READER]] as const) {
136133
it(`${label} is served no datasource-family row on sys_metadata (find, findOne, count, aggregate)`, async () => {
137134
const listed = await engine.find('sys_metadata', { context: caller });
138135
expect(listed.map((r: any) => r.type).sort()).toEqual(['view']);

‎packages/objectql/src/stored-metadata-type-read-gate.ts‎

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,13 @@
1010
*
1111
* A datasource document is a row of the stored-metadata family
1212
* (`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.
13+
* `/meta` read doors admit a caller to a datasource-family type only when it
14+
* holds `manage_platform_settings` (`metaTypeReadRefusal`, `@objectstack/rest`).
15+
* The rule is that one document admits one set of callers at every exit that
16+
* serves it, so the stored row admits exactly those callers too.
2217
*
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
18+
* Every caller-context read of the family passes this engine's middleware
19+
* chain, so the rule is applied once, here, from the one table both exits read
2520
* (`STORED_METADATA_TYPE_READ_CAPABILITIES`, `@objectstack/metadata-core`):
2621
* for a caller missing a row's capability, `type NOT IN (those types)` is
2722
* AND-composed into the read's predicate. ⛔ Never a second copy of the table,

‎packages/qa/dogfood/test/datasource-stored-row-read-admission.dogfood.test.ts‎

Lines changed: 11 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,15 @@
11
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
22
//
33
// [#27884] A datasource definition is served only to datasource
4-
// administrators, whichever door reads it. The metadata read door
5-
// (`GET /api/v1/meta/datasource`) already admits only holders of the
6-
// datasource family's read capability; the stored row the definition lives in
7-
// is also a record of the stored-metadata table, and the generic data door must
8-
// admit the same callers to it. Pinned at the REST doors of a booted stack,
9-
// with the platform's own security composition:
4+
// administrators, at every exit that serves it: the stored row the definition
5+
// lives in admits the same callers the metadata read door
6+
// (`GET /api/v1/meta/datasource`) admits. Pinned at the REST doors of a booted
7+
// stack, with the platform's own security composition:
108
//
11-
// - the platform administrator reads the row whole through the data door,
12-
// connection configuration and `external.credentialsRef` included;
13-
// - the shipped organization-administrator set (below datasource
14-
// administration) and a plain member are served no row: the list and the
15-
// query answer none, a get of the row's id answers 404, and the metadata
16-
// door refuses them as before;
17-
// - parity: for each caller, the data door serves the row exactly when the
9+
// - the platform administrator reads the row whole;
10+
// - a caller below datasource administration and a plain member are served
11+
// no row, and the metadata door refuses them as before;
12+
// - parity: for each caller, the stored row is served exactly when the
1813
// metadata door serves the definition.
1914

2015
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
@@ -92,7 +87,7 @@ describe('[#27884] the stored row of a datasource definition admits only datasou
9287
await stack?.stop();
9388
});
9489

95-
it('the platform administrator reads the row whole: connection configuration and credentialsRef', async () => {
90+
it('the platform administrator reads the row whole', async () => {
9691
const list = await call(tokens.admin, 'GET', `/data/sys_metadata?type=datasource&name=${DS}&fields=name,type,metadata`);
9792
expect(list.status, list.text).toBe(200);
9893
const [row] = listRows(list);
@@ -104,7 +99,7 @@ describe('[#27884] the stored row of a datasource definition admits only datasou
10499
});
105100

106101
for (const who of ['orgAdmin', 'member'] as const) {
107-
it(`${who === 'orgAdmin' ? 'the built-in organization administrator' : 'a plain member'} is served no row through any data-door read`, async () => {
102+
it(`${who === 'orgAdmin' ? 'a caller below datasource administration' : 'a plain member'} is served no row`, async () => {
108103
const token = tokens[who];
109104
const list = await call(token, 'GET', `/data/sys_metadata?type=datasource&fields=name,type,metadata`);
110105
// 403 (the object is not readable at all) or 200 with no datasource row.
@@ -124,7 +119,7 @@ describe('[#27884] the stored row of a datasource definition admits only datasou
124119
});
125120
}
126121

127-
it('parity: each caller is served the row by the data door exactly when the metadata door serves the definition', async () => {
122+
it('parity: each caller is served the stored row exactly when the metadata door serves the definition', async () => {
128123
for (const who of ['admin', 'orgAdmin', 'member'] as const) {
129124
const meta = await call(tokens[who], 'GET', `/meta/datasource/${DS}`);
130125
const data = await call(tokens[who], 'GET', `/data/sys_metadata/${encodeURIComponent(rowId)}`);

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2078,8 +2078,8 @@ export function isPublicAudienceRead(
20782078
* (`@objectstack/metadata-core`), and this name is that same frozen object. The
20792079
* engine's stored-row read gate (`@objectstack/objectql`) narrows every
20802080
* 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.
2081+
* row, so no exit serves a document of a listed type to a caller this gate
2082+
* refuses. A row is added THERE, and reaches both exits.
20832083
*/
20842084
export const META_TYPE_READ_CAPABILITIES: Readonly<Record<string, string>> = STORED_METADATA_TYPE_READ_CAPABILITIES;
20852085

‎packages/rest/src/meta-type-read-stored-row-parity.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ import { META_TYPE_READ_CAPABILITIES, metaTypeReadRefusal } from './meta-item-re
1919
const CALLERS: Record<string, unknown> = {
2020
platformAdmin: { userId: 'u_admin', systemPermissions: ['manage_platform_settings', 'manage_metadata', 'studio.access', 'setup.access'] },
2121
datasourceAdminOnly: { userId: 'u_ds', systemPermissions: ['manage_platform_settings'] },
22-
organizationAdmin: { userId: 'u_org', systemPermissions: ['manage_org_users', 'setup.access', 'setup.write', 'manage_mailboxes'] },
22+
belowDatasourceAdmin: { userId: 'u_org', systemPermissions: ['manage_org_users', 'setup.access', 'setup.write', 'manage_mailboxes'] },
2323
studioAuthor: { userId: 'u_author', systemPermissions: ['studio.access', 'manage_metadata'] },
2424
member: { userId: 'u_member', systemPermissions: [] },
2525
noCapabilitySet: { userId: 'u_bare' },
@@ -42,6 +42,6 @@ describe('[#27884] one read row for a datasource-family document, at both exits'
4242

4343
it('a holder is withheld nothing; a caller below datasource administration is withheld every gated type', () => {
4444
expect(storedMetadataTypesWithheldFrom(CALLERS.platformAdmin)).toEqual([]);
45-
expect(storedMetadataTypesWithheldFrom(CALLERS.organizationAdmin).sort()).toEqual(['datasource', 'external_catalog']);
45+
expect(storedMetadataTypesWithheldFrom(CALLERS.belowDatasourceAdmin).sort()).toEqual(['datasource', 'external_catalog']);
4646
});
4747
});

0 commit comments

Comments
 (0)