|
| 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]); |
0 commit comments