@hypequery/protocol 0.19.0 → 0.21.0

package/dist/visibility/resolve.js

@@ -0,0 +1,108 @@
+function pick(all, allowed) {
+    if (allowed === '*')
+        return new Set(all);
+    const permitted = new Set(allowed);
+    return new Set(all.filter(name => permitted.has(name)));
+}
+/** The measures a measure is computed from: a derived measure's inputs, or the one a time measure wraps. */
+function measureInputs(measure) {
+    if ('uses' in measure && Array.isArray(measure.uses)) {
+        return measure.uses.map((use) => String(use.measure));
+    }
+    if ('measure' in measure && typeof measure.measure === 'string')
+        return [measure.measure];
+    return [];
+}
+/**
+ * Whether a relationship's local join keys are visible. A joined `to` field
+ * holds the same values as its `from` key, so exposing the join while hiding
+ * the key would let a caller read the key back through the relationship.
+ * Execution joins on keys as physical columns, so a key counts as visible only
+ * when a visible dimension reads that column. A dimension merely named like
+ * the key doesn't count: it may read a different column.
+ */
+function joinKeysVisible(relationship, dataset, visible, allDimensions) {
+    if (allDimensions)
+        return true;
+    const keys = [String(relationship.from), ...(relationship.keys ?? []).map(key => String(key.from))];
+    return keys.every(key => dataset.dimensions.some(dimension => (visible.has(String(dimension.name))
+        && dimension.source.kind === 'column'
+        && dimension.source.column === key)));
+}
+/** A measure over the dataset's time axis (window or shift), which needs the time field. */
+function isTimeMeasure(measure) {
+    return 'measure' in measure && typeof measure.measure === 'string';
+}
+/**
+ * What one dataset exposes under a visibility policy, or null when the policy
+ * hides the dataset (RFC 0019).
+ *
+ * Names the policy lists but the contract doesn't have are ignored, so a
+ * policy written against one release keeps working after a later release
+ * removes a field. Visibility only narrows: a dimension the contract marks
+ * non-groupable or non-filterable stays so.
+ *
+ * - A one-hop `relationship.dimension` is visible only when the target dataset
+ *   and that dimension are visible in the target's own entry, and the
+ *   relationship's local join keys are visible.
+ * - A declared filter is visible only when the dimension it filters is.
+ * - The time field is visible only as a visible dimension; grouping by period
+ *   and time measures need it.
+ * - A measure is visible only when it is listed and every measure it is
+ *   computed from is visible too. A derived ratio over a hidden measure would
+ *   let a caller recover the hidden value.
+ * - Measures are authorized by name, independently of the dimensions they
+ *   aggregate: `revenue = sum(amount)` stays visible with `amount` hidden. A
+ *   `min`, `max`, `argMax` or `countDistinct` over a hidden dimension reveals
+ *   its values, so list measures explicitly rather than use `*` when a dataset
+ *   has any that must stay hidden; `*` also exposes measures added later.
+ * - Segments are not narrowed. Deployment contract 2, which this resolves, has
+ *   none.
+ */
+export function resolveProtocolVisibleDatasetFields(dataset, datasets, visibility) {
+    const entry = Object.hasOwn(visibility.datasets, String(dataset.name))
+        ? visibility.datasets[String(dataset.name)]
+        : undefined;
+    if (entry === undefined)
+        return null;
+    const local = pick(dataset.dimensions.map(dimension => String(dimension.name)), entry.dimensions);
+    const dimensions = new Set(local);
+    const timeField = dataset.timeField !== undefined && local.has(String(dataset.timeField));
+    const relationships = new Set();
+    for (const relationship of dataset.relationships) {
+        const target = datasets.get(String(relationship.target));
+        const targetEntry = target && Object.hasOwn(visibility.datasets, String(target.name))
+            ? visibility.datasets[String(target.name)]
+            : undefined;
+        if (!target || targetEntry === undefined)
+            continue;
+        if (!joinKeysVisible(relationship, dataset, local, entry.dimensions === '*'))
+            continue;
+        relationships.add(String(relationship.name));
+        const visible = pick(target.dimensions.map(dimension => String(dimension.name)), targetEntry.dimensions);
+        for (const name of visible)
+            dimensions.add(`${String(relationship.name)}.${name}`);
+    }
+    const filters = new Set(dataset.filters
+        .filter(filter => dimensions.has(String(filter.field)))
+        .map(filter => String(filter.name)));
+    const byName = new Map(dataset.measures.map(measure => [String(measure.name), measure]));
+    const listed = pick([...byName.keys()], entry.measures);
+    const decided = new Map();
+    const isVisible = (name, path) => {
+        const known = decided.get(name);
+        if (known !== undefined)
+            return known;
+        const measure = byName.get(name);
+        // A cycle can't occur in a valid contract; refuse rather than recurse.
+        const visible = measure !== undefined
+            && listed.has(name)
+            && !path.has(name)
+            && (!isTimeMeasure(measure) || timeField)
+            && measureInputs(measure).every(input => isVisible(input, new Set([...path, name])));
+        decided.set(name, visible);
+        return visible;
+    };
+    const measures = new Set([...byName.keys()].filter(name => isVisible(name, new Set())));
+    return Object.freeze({ dimensions, measures, filters, relationships, timeField });
+}

package/dist/visibility/types.d.ts

@@ -0,0 +1,32 @@
+/** Every field of its kind, including ones a later release adds. */
+export type ProtocolVisibleFields = '*' | readonly string[];
+export interface ProtocolDatasetVisibility {
+    readonly dimensions: ProtocolVisibleFields;
+    readonly measures: ProtocolVisibleFields;
+}
+/**
+ * Which datasets and fields a principal may see and query (RFC 0019).
+ *
+ * An allowlist: a dataset absent from `datasets` is hidden entirely, and a
+ * field absent from its dataset's list is hidden. It narrows what the
+ * contract publishes and never widens it.
+ */
+export interface ProtocolFieldVisibility {
+    readonly kind: 'hypequery-field-visibility';
+    readonly version: 1;
+    readonly datasets: Readonly<Record<string, ProtocolDatasetVisibility>>;
+}
+/** What one dataset exposes under a visibility policy. */
+export interface ProtocolVisibleDatasetFields {
+    /** Local dimension names and one-hop `relationship.dimension` names. */
+    readonly dimensions: ReadonlySet<string>;
+    readonly measures: ReadonlySet<string>;
+    /** Declared filter names whose field is a visible dimension. */
+    readonly filters: ReadonlySet<string>;
+    /** Relationships whose join keys and target are visible; only these contribute joined fields. */
+    readonly relationships: ReadonlySet<string>;
+    /** Whether the dataset's time field may be grouped by (`by`). */
+    readonly timeField: boolean;
+}
+export type ProtocolFieldVisibilityErrorCode = 'HQ_VISIBILITY_INVALID' | 'HQ_VISIBILITY_TOO_LARGE';
+//# sourceMappingURL=types.d.ts.map

package/dist/visibility/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/visibility/types.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,MAAM,MAAM,qBAAqB,GAAG,GAAG,GAAG,SAAS,MAAM,EAAE,CAAC;AAE5D,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC;CACxE;AAED,0DAA0D;AAC1D,MAAM,WAAW,4BAA4B;IAC3C,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,iGAAiG;IACjG,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5C,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,gCAAgC,GAAG,uBAAuB,GAAG,yBAAyB,CAAC"}

package/dist/visibility/types.js

@@ -0,0 +1 @@
+export {};

package/dist/visibility/validate.d.ts

@@ -0,0 +1,11 @@
+import type { ProtocolFieldVisibility } from './types.js';
+export declare const PROTOCOL_FIELD_VISIBILITY_LIMITS: Readonly<{
+    maxDatasets: 256;
+    maxFieldsPerList: 1024;
+}>;
+/**
+ * Parses an untrusted visibility record. Unknown keys, malformed names and
+ * oversized lists fail closed; the result is frozen with sorted field lists.
+ */
+export declare function validateProtocolFieldVisibility(input: unknown): ProtocolFieldVisibility;
+//# sourceMappingURL=validate.d.ts.map

package/dist/visibility/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/visibility/validate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,uBAAuB,EAExB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,gCAAgC;;;EAG3C,CAAC;AAoCH;;;GAGG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CA2BvF"}

package/dist/visibility/validate.js

@@ -0,0 +1,78 @@
+import { isProtocolIdentifier } from '../identifiers/index.js';
+import { visibilityError } from './errors.js';
+export const PROTOCOL_FIELD_VISIBILITY_LIMITS = Object.freeze({
+    maxDatasets: 256,
+    maxFieldsPerList: 1_024,
+});
+function isRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function exactKeys(value, keys, path) {
+    for (const key of Object.keys(value)) {
+        if (!keys.includes(key))
+            visibilityError('HQ_VISIBILITY_INVALID', `${path}.${key}`);
+    }
+    for (const key of keys) {
+        if (!Object.hasOwn(value, key))
+            visibilityError('HQ_VISIBILITY_INVALID', `${path}.${key}`);
+    }
+}
+function fields(value, path) {
+    if (value === '*')
+        return '*';
+    if (!Array.isArray(value))
+        visibilityError('HQ_VISIBILITY_INVALID', path);
+    if (value.length > PROTOCOL_FIELD_VISIBILITY_LIMITS.maxFieldsPerList) {
+        visibilityError('HQ_VISIBILITY_TOO_LARGE', path);
+    }
+    // Array.from visits holes as undefined, so a sparse list fails closed.
+    const names = Array.from(value, (name, index) => {
+        if (typeof name !== 'string' || !isProtocolIdentifier(name)) {
+            visibilityError('HQ_VISIBILITY_INVALID', `${path}[${index}]`);
+        }
+        return name;
+    });
+    if (new Set(names).size !== names.length)
+        visibilityError('HQ_VISIBILITY_INVALID', path);
+    return Object.freeze([...names].sort());
+}
+/**
+ * Parses an untrusted visibility record. Unknown keys, malformed names and
+ * oversized lists fail closed; the result is frozen with sorted field lists.
+ */
+export function validateProtocolFieldVisibility(input) {
+    if (!isRecord(input))
+        visibilityError('HQ_VISIBILITY_INVALID');
+    exactKeys(input, ['kind', 'version', 'datasets'], '$');
+    if (input.kind !== 'hypequery-field-visibility')
+        visibilityError('HQ_VISIBILITY_INVALID', '$.kind');
+    if (input.version !== 1)
+        visibilityError('HQ_VISIBILITY_INVALID', '$.version');
+    if (!isRecord(input.datasets))
+        visibilityError('HQ_VISIBILITY_INVALID', '$.datasets');
+    const entries = Object.entries(input.datasets);
+    if (entries.length > PROTOCOL_FIELD_VISIBILITY_LIMITS.maxDatasets) {
+        visibilityError('HQ_VISIBILITY_TOO_LARGE', '$.datasets');
+    }
+    const datasets = Object.create(null);
+    for (const [name, entry] of entries.sort(([left], [right]) => (left < right ? -1 : 1))) {
+        const path = `$.datasets.${name}`;
+        if (!isProtocolIdentifier(name))
+            visibilityError('HQ_VISIBILITY_INVALID', path);
+        if (!isRecord(entry))
+            visibilityError('HQ_VISIBILITY_INVALID', path);
+        exactKeys(entry, ['dimensions', 'measures'], path);
+        datasets[name] = Object.freeze({
+            dimensions: fields(entry.dimensions, `${path}.dimensions`),
+            measures: fields(entry.measures, `${path}.measures`),
+        });
+    }
+    return Object.freeze({
+        kind: 'hypequery-field-visibility',
+        version: 1,
+        datasets: Object.freeze(datasets),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/protocol",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Portable analytics contracts and TypeScript reference implementation for Hypequery",
   "keywords": [
     "hypequery",
@@ -27,12 +27,12 @@
     "README.md"
   ],
   "dependencies": {
-    "@noble/hashes": "^1.8.0"
+    "@noble/hashes": "^2.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.5"
   },
   "repository": {
     "type": "git",