/** * src/analytics/contract/query-request.ts * ======================================== * BI-P016 — QUERY REQUEST CONTRACT. * * The canonical shape every SIAX product/application API speaks when it wants * analytics: * * AnalyticsQueryRequest { dataset metrics[] dimensions[] filters[] * timeRange orderBy limit format } * * BI-P016's hard rule: "The default product/application API must NOT accept * arbitrary SQL." That is enforced structurally, not by a review convention — * there is no field in this type that can carry SQL, and * `parseAnalyticsQueryRequest` REJECTS unknown keys rather than ignoring them. * A caller who adds `sql`, `where`, `having` or `expression` gets * INVALID_REQUEST, not silent truncation; silent truncation is how an * "unsupported" field becomes a supported one after the next refactor. * * Everything in this request is a NAME, resolved through a declared catalog * (`QueryResolution`) before it can reach a compiler. Caller text therefore * never becomes a SQL identifier and never becomes a SQL literal — the two * ways injection happens. * * WHY THIS IS SEPARATE FROM `MetricQueryRequest` (engine/query-compiler.ts): * that type is the ENGINE's internal, already-resolved, single-metric input, * and it carries `tenant_id` because the engine sets it. This one is the * CONSUMER-facing contract: it has no tenant field at all, because a consumer * must never be able to name a tenant. INF0's Wave-2 hole was exactly a tenant * read out of a request body; the fix that sticks is a request type in which * the field does not exist. */ import { SiaxError } from '../../platform/errors'; // ── vocabulary ───────────────────────────────────────────────────────────── /** * Filter operators. A CLOSED list: every one compiles to a fixed SQL shape * with bound parameters. There is no "raw" or "expression" operator, and * adding one would have to survive `filter-operators-are-closed` in * tests/analytics/query-request-contract.test.ts. */ export const FILTER_OPERATORS = [ 'eq', 'ne', 'in', 'not_in', 'lt', 'lte', 'gt', 'gte', 'contains', 'is_null', 'is_not_null', ] as const; export type FilterOperator = (typeof FILTER_OPERATORS)[number]; /** Operators that take exactly one value. */ const SINGLE_VALUE_OPERATORS: readonly FilterOperator[] = ['eq', 'ne', 'lt', 'lte', 'gt', 'gte', 'contains']; /** Operators that take one-or-more values. */ const MULTI_VALUE_OPERATORS: readonly FilterOperator[] = ['in', 'not_in']; /** Operators that take NO value. Supplying one is a rejection, not a shrug. */ const NO_VALUE_OPERATORS: readonly FilterOperator[] = ['is_null', 'is_not_null']; export const TIME_GRAINS = ['hour', 'day', 'week', 'month', 'quarter', 'year'] as const; export type TimeGrain = (typeof TIME_GRAINS)[number]; export const ORDER_DIRECTIONS = ['asc', 'desc'] as const; export type OrderDirection = (typeof ORDER_DIRECTIONS)[number]; /** Result encodings, matching `QueryResult.encoding` (BI-P002/BI-P005). */ export const REQUEST_FORMATS = ['json', 'arrow_ipc'] as const; export type RequestFormat = (typeof REQUEST_FORMATS)[number]; // ── the request ──────────────────────────────────────────────────────────── export interface AnalyticsFilter { /** Caller-facing dimension NAME. Resolved through the catalog, never spliced. */ dimension: string; operator: FilterOperator; /** Literal values. They travel as bound parameters; never as SQL text. */ values?: string[]; } export interface AnalyticsTimeRange { /** * Caller-facing time dimension name. Omitted means "the dataset's declared * primary time dimension", which the resolution supplies — a consumer never * has to know the physical column. */ dimension?: string; /** ISO-8601 inclusive lower bound. */ from?: string; /** ISO-8601 EXCLUSIVE upper bound (half-open, so adjacent ranges never double count). */ to?: string; grain?: TimeGrain; } export interface AnalyticsOrderBy { /** * A metric name or a dimension name that ALREADY APPEARS in this request. * Ordering by something not selected is refused: it is both a correctness * trap and the obvious place to smuggle an expression. */ ref: string; direction: OrderDirection; } /** BI-P016's canonical request, field-for-field. */ export interface AnalyticsQueryRequest { dataset: string; metrics: string[]; dimensions: string[]; filters: AnalyticsFilter[]; timeRange?: AnalyticsTimeRange; orderBy?: AnalyticsOrderBy[]; limit?: number; format?: RequestFormat; } /** The exact keys the contract accepts at the top level. */ export const ANALYTICS_QUERY_REQUEST_KEYS = [ 'dataset', 'metrics', 'dimensions', 'filters', 'timeRange', 'orderBy', 'limit', 'format', ] as const; /** * Keys a caller might reach for when they want to smuggle SQL. Listed * explicitly so the rejection MESSAGE names the rule rather than saying * "unknown key" — an integrator who tries `sql` should learn why, not guess. * The unknown-key rejection below covers everything, listed or not. */ const SQL_SMELLING_KEYS = new Set([ 'sql', 'query', 'rawSql', 'raw_sql', 'raw', 'where', 'having', 'expression', 'expr', 'select', 'from', 'groupBy', 'group_by', 'sqlFragment', 'unsafe', 'tenant', 'tenant_id', 'tenantId', 'project_id', 'database', 'catalog', 'table', ]); const MAX_METRICS = 16; const MAX_DIMENSIONS = 8; const MAX_FILTERS = 32; const MAX_FILTER_VALUES = 500; const MAX_ORDER_BY = 8; /** A name is a catalog key, not free text; keep it short and boring. */ const MAX_NAME_LENGTH = 128; /** A filter VALUE is data (it is bound, never spliced) but still bounded. */ const MAX_VALUE_LENGTH = 4096; export const DEFAULT_REQUEST_LIMIT = 1000; function invalid(detail: string): never { throw new SiaxError('INVALID_REQUEST', '0pt.analytics', detail); } function asObject(raw: unknown, what: string): Record { if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) invalid(`${what} must be an object`); return raw as Record; } function asName(raw: unknown, what: string): string { if (typeof raw !== 'string') invalid(`${what} must be a string`); const v = raw.trim(); if (!v) invalid(`${what} must not be empty`); if (v.length > MAX_NAME_LENGTH) invalid(`${what} exceeds ${MAX_NAME_LENGTH} characters`); return v; } function rejectUnknownKeys(obj: Record, allowed: readonly string[], what: string): void { for (const key of Object.keys(obj)) { if (allowed.includes(key)) continue; if (SQL_SMELLING_KEYS.has(key)) { invalid( `"${key}" is not part of the analytics query contract — the product API does not accept SQL, ` + `catalogs, or tenant selection (BI-P016)`, ); } invalid(`unknown field "${key}" in ${what}`); } } /** * Parse and VALIDATE an untrusted request body into the canonical contract. * * Fail-closed at every branch: an unparseable field is a rejection, never a * default. The only defaulting this function does is `filters: []`, * `dimensions: []` and `limit`, and each of those defaults is strictly * narrower than any value a caller could have supplied. */ export function parseAnalyticsQueryRequest(raw: unknown): AnalyticsQueryRequest { const obj = asObject(raw, 'analytics query request'); rejectUnknownKeys(obj, ANALYTICS_QUERY_REQUEST_KEYS, 'analytics query request'); const dataset = asName(obj.dataset, 'dataset'); if (!Array.isArray(obj.metrics)) invalid('metrics must be an array'); if (obj.metrics.length === 0) invalid('at least one metric is required'); if (obj.metrics.length > MAX_METRICS) invalid(`at most ${MAX_METRICS} metrics per request`); const metrics = obj.metrics.map((m, i) => asName(m, `metrics[${i}]`)); if (new Set(metrics).size !== metrics.length) invalid('metrics contains duplicates'); const rawDimensions = obj.dimensions ?? []; if (!Array.isArray(rawDimensions)) invalid('dimensions must be an array'); if (rawDimensions.length > MAX_DIMENSIONS) invalid(`at most ${MAX_DIMENSIONS} dimensions per request`); const dimensions = rawDimensions.map((d, i) => asName(d, `dimensions[${i}]`)); if (new Set(dimensions).size !== dimensions.length) invalid('dimensions contains duplicates'); const rawFilters = obj.filters ?? []; if (!Array.isArray(rawFilters)) invalid('filters must be an array'); if (rawFilters.length > MAX_FILTERS) invalid(`at most ${MAX_FILTERS} filters per request`); const filters = rawFilters.map((f, i) => parseFilter(f, i)); const timeRange = obj.timeRange === undefined ? undefined : parseTimeRange(obj.timeRange); const rawOrderBy = obj.orderBy ?? []; if (!Array.isArray(rawOrderBy)) invalid('orderBy must be an array'); if (rawOrderBy.length > MAX_ORDER_BY) invalid(`at most ${MAX_ORDER_BY} orderBy entries`); const orderBy = rawOrderBy.map((o, i) => parseOrderBy(o, i)); const selectable = new Set([...metrics, ...dimensions]); for (const o of orderBy) { if (!selectable.has(o.ref)) { invalid(`orderBy "${o.ref}" is neither a requested metric nor a requested dimension`); } } let limit = DEFAULT_REQUEST_LIMIT; if (obj.limit !== undefined) { if (typeof obj.limit !== 'number' || !Number.isFinite(obj.limit)) invalid('limit must be a finite number'); if (!Number.isInteger(obj.limit)) invalid('limit must be an integer'); if (obj.limit < 1) invalid('limit must be >= 1'); limit = obj.limit; } let format: RequestFormat = 'json'; if (obj.format !== undefined) { if (typeof obj.format !== 'string' || !(REQUEST_FORMATS as readonly string[]).includes(obj.format)) { invalid(`format must be one of ${REQUEST_FORMATS.join(', ')}`); } format = obj.format as RequestFormat; } return { dataset, metrics, dimensions, filters, timeRange, orderBy, limit, format }; } function parseFilter(raw: unknown, index: number): AnalyticsFilter { const obj = asObject(raw, `filters[${index}]`); rejectUnknownKeys(obj, ['dimension', 'operator', 'values'], `filters[${index}]`); const dimension = asName(obj.dimension, `filters[${index}].dimension`); if (typeof obj.operator !== 'string' || !(FILTER_OPERATORS as readonly string[]).includes(obj.operator)) { invalid(`filters[${index}].operator must be one of ${FILTER_OPERATORS.join(', ')}`); } const operator = obj.operator as FilterOperator; if (NO_VALUE_OPERATORS.includes(operator)) { if (obj.values !== undefined) invalid(`filters[${index}].operator "${operator}" takes no values`); return { dimension, operator }; } if (!Array.isArray(obj.values)) invalid(`filters[${index}].values must be an array`); if (obj.values.length === 0) invalid(`filters[${index}].values must not be empty`); if (obj.values.length > MAX_FILTER_VALUES) { invalid(`filters[${index}].values exceeds ${MAX_FILTER_VALUES} entries`); } if (SINGLE_VALUE_OPERATORS.includes(operator) && obj.values.length !== 1) { invalid(`filters[${index}].operator "${operator}" takes exactly one value`); } if (!MULTI_VALUE_OPERATORS.includes(operator) && !SINGLE_VALUE_OPERATORS.includes(operator)) { invalid(`filters[${index}].operator "${operator}" is not a value operator`); } const values = obj.values.map((v, i) => { if (typeof v !== 'string') invalid(`filters[${index}].values[${i}] must be a string`); if (v.length > MAX_VALUE_LENGTH) invalid(`filters[${index}].values[${i}] exceeds ${MAX_VALUE_LENGTH} characters`); return v; }); return { dimension, operator, values }; } function parseTimeRange(raw: unknown): AnalyticsTimeRange { const obj = asObject(raw, 'timeRange'); rejectUnknownKeys(obj, ['dimension', 'from', 'to', 'grain'], 'timeRange'); const out: AnalyticsTimeRange = {}; if (obj.dimension !== undefined) out.dimension = asName(obj.dimension, 'timeRange.dimension'); if (obj.from !== undefined) out.from = asIsoInstant(obj.from, 'timeRange.from'); if (obj.to !== undefined) out.to = asIsoInstant(obj.to, 'timeRange.to'); if (obj.grain !== undefined) { if (typeof obj.grain !== 'string' || !(TIME_GRAINS as readonly string[]).includes(obj.grain)) { invalid(`timeRange.grain must be one of ${TIME_GRAINS.join(', ')}`); } out.grain = obj.grain as TimeGrain; } if (out.from && out.to && Date.parse(out.from) >= Date.parse(out.to)) { invalid('timeRange.from must be strictly before timeRange.to'); } return out; } /** * A timestamp is validated as a real instant, not merely as "a string that * gets bound". It is bound as a parameter either way, so this is not the * injection defence — it is the defence against a nonsense range silently * producing an empty answer that a dashboard renders as "zero sales". */ function asIsoInstant(raw: unknown, what: string): string { if (typeof raw !== 'string') invalid(`${what} must be an ISO-8601 string`); const v = raw.trim(); if (!/^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:?\d{2})?)?$/.test(v)) { invalid(`${what} is not an ISO-8601 timestamp`); } if (Number.isNaN(Date.parse(v))) invalid(`${what} is not a valid timestamp`); return v; } function parseOrderBy(raw: unknown, index: number): AnalyticsOrderBy { const obj = asObject(raw, `orderBy[${index}]`); rejectUnknownKeys(obj, ['ref', 'direction'], `orderBy[${index}]`); const ref = asName(obj.ref, `orderBy[${index}].ref`); if (typeof obj.direction !== 'string' || !(ORDER_DIRECTIONS as readonly string[]).includes(obj.direction)) { invalid(`orderBy[${index}].direction must be one of ${ORDER_DIRECTIONS.join(', ')}`); } return { ref, direction: obj.direction as OrderDirection }; } // ── resolution: names -> declared catalog entries ────────────────────────── /** * What a metric NAME resolves to. Supplied from `MetricDefinition` rows * (BI-P002/BI-P028); the compilers never invent one. */ export interface ResolvedMetric { name: string; metric_id: string; /** The `metric` key stored in the analytics event table. */ event_metric_key: string; aggregation: 'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct'; /** Dimension names this metric may legitimately be sliced by. */ allowed_dimensions: readonly string[]; unit?: string; } /** What a dimension NAME resolves to. Supplied from `DimensionDefinition` rows. */ export interface ResolvedDimension { name: string; dimension_id: string; /** Physical key inside `dim_names`. Validated as an identifier downstream. */ field_name: string; } /** * The declared surface for ONE dataset, for ONE tenant. A compiler is handed * this; it cannot reach past it. An unresolvable name is a rejection. */ export interface QueryResolution { dataset_id: string; /** Semantic model version this resolution came from — part of the cache key (BI-P020). */ semantic_model_version?: number; metric(name: string): ResolvedMetric | undefined; dimension(name: string): ResolvedDimension | undefined; /** Physical time dimension used when `timeRange.dimension` is omitted. */ defaultTimeDimension?: string; } export function queryResolutionFrom(args: { dataset_id: string; metrics: readonly ResolvedMetric[]; dimensions: readonly ResolvedDimension[]; semantic_model_version?: number; defaultTimeDimension?: string; }): QueryResolution { const metricMap = new Map(args.metrics.map((m) => [m.name, m])); const dimMap = new Map(args.dimensions.map((d) => [d.name, d])); return { dataset_id: args.dataset_id, semantic_model_version: args.semantic_model_version, defaultTimeDimension: args.defaultTimeDimension, // Map lookups: "__proto__" / "constructor" resolve to undefined, as they must. metric: (name) => metricMap.get(name), dimension: (name) => dimMap.get(name), }; } /** * Resolve every name in a request, or refuse the request. * * This is the single place where "a caller said X" becomes "the catalog * declares Y". Both compile targets (ClickHouse and semantic) consume the * RESOLVED form, which is why BI-P016's DoD holds: the consumer writes one * request and neither target sees consumer text. */ export interface ResolvedQuery { request: AnalyticsQueryRequest; dataset_id: string; metrics: ResolvedMetric[]; dimensions: ResolvedDimension[]; filters: Array<{ filter: AnalyticsFilter; dimension: ResolvedDimension }>; timeDimension?: string; semantic_model_version?: number; } export function resolveAnalyticsQuery( request: AnalyticsQueryRequest, resolution: QueryResolution, ): ResolvedQuery { if (request.dataset !== resolution.dataset_id) { // The resolution is built FOR a dataset the caller was authorised to read // (BI-P006 grants). A mismatch means the caller is asking about something // else entirely, and answering from this resolution would be a leak. throw new SiaxError( 'AUTHORIZATION_DENIED', '0pt.analytics', 'requested dataset does not match the authorised resolution', ); } const metrics = request.metrics.map((name) => { const m = resolution.metric(name); if (!m) invalid(`unknown metric "${name}" for this dataset`); return m; }); const dimensions = request.dimensions.map((name) => { const d = resolution.dimension(name); if (!d) invalid(`unknown dimension "${name}" for this dataset`); return d; }); // Every requested dimension must be legitimate for EVERY requested metric. // Slicing a metric by a dimension its definition does not allow is how a // "harmless" grouping turns into an unintended disclosure. for (const m of metrics) { for (const d of dimensions) { if (!m.allowed_dimensions.includes(d.name)) { throw new SiaxError( 'AUTHORIZATION_DENIED', '0pt.analytics', `metric "${m.name}" may not be sliced by dimension "${d.name}"`, ); } } } const filters = request.filters.map((f) => { const d = resolution.dimension(f.dimension); if (!d) invalid(`unknown filter dimension "${f.dimension}"`); return { filter: f, dimension: d }; }); let timeDimension: string | undefined; if (request.timeRange) { if (request.timeRange.dimension) { const d = resolution.dimension(request.timeRange.dimension); if (!d) invalid(`unknown time dimension "${request.timeRange.dimension}"`); timeDimension = d.field_name; } else { timeDimension = resolution.defaultTimeDimension; if ((request.timeRange.from || request.timeRange.to) && !timeDimension) { invalid('dataset declares no default time dimension; timeRange.dimension is required'); } } } return { request, dataset_id: resolution.dataset_id, metrics, dimensions, filters, timeDimension, semantic_model_version: resolution.semantic_model_version, }; }