Files
0pt/src/analytics/contract/query-request.ts
T
Claude Opus 5 b1884a89a5
CI (SIAX Cloud) / security (push) Successful in 25s
Security Scan (SIAX Cloud) / security (push) Successful in 24s
CI (SIAX Cloud) / integration (push) Successful in 39s
CI (SIAX Cloud) / security (pull_request) Successful in 25s
CI (SIAX Cloud) / quality (push) Successful in 57s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 20s
CI (SIAX Cloud) / integration (pull_request) Successful in 1m38s
CI (SIAX Cloud) / quality (pull_request) Successful in 1m59s
feat(analytics): BI-P016 — canonical query request contract, two compile targets
The eight-field AnalyticsQueryRequest BI-P016 names, verbatim, with the rule
that makes it safe enforced structurally rather than by convention: there is
no field that can carry SQL, and parseAnalyticsQueryRequest REJECTS unknown
keys instead of ignoring them. Ignoring an unsupported field is how it becomes
a supported one after the next refactor.

`tenant`, `tenant_id`, `project_id`, `database`, `catalog` and `table` are
rejected by name. INF0's Wave-2 cross-tenant hole was a tenant read out of a
request body; the fix that sticks is a request type in which the field does
not exist, and a parser that refuses it when a caller sends it anyway.

BI-P016's DoD ("same request compiles to ClickHouse/semantic engine without
consumer rewrite") is tested as an equality, not narrated: both targets are
projected onto a comparable shape and compared. The ClickHouse side of that
projection is obtained by PARSING the emitted SQL and its bound parameters in
the test — not by reading a field the compiler helpfully returned — so a
compiler that silently drops a filter fails the comparison instead of passing
it. The parser throws on any condition it does not recognise, which is what
would catch unbound caller text appearing in the statement.

BI-P011's forced tenant predicate is re-proven against this new path: five
request shapes are enumerated and each must have FORCED_TENANT_PREDICATE as
condition[0]; a blank tenant refuses to compile rather than emitting no
predicate; a hostile filter value appears only in params, never in sql.

45 tests, all failing-capable: every rejection assertion checks the SiaxError
code, and the DoD assertions compare reconstructed meaning rather than strings.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 02:00:07 +02:00

490 lines
19 KiB
TypeScript

/**
* 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<string, unknown> {
if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) invalid(`${what} must be an object`);
return raw as Record<string, unknown>;
}
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<string, unknown>, 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<string>([...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,
};
}