@hypequery/protocol 0.10.2 → 0.11.0

package/dist/cache-keys/cache-keys.d.ts

@@ -0,0 +1,19 @@
+import { type DeriveProtocolCacheKeyOptions, type ProtocolCacheKeyErrorCode } from './types.js';
+export declare class ProtocolCacheKeyError extends Error {
+    readonly code: ProtocolCacheKeyErrorCode;
+    constructor(code: ProtocolCacheKeyErrorCode);
+}
+/**
+ * Derives the opaque namespace prefix. Truncated to 16 bytes because it is a
+ * grouping label for prefix operations, not an authentication tag.
+ */
+export declare function deriveProtocolCacheNamespaceToken(secret: Uint8Array, project: string, environment: string): string;
+/**
+ * Derives the opaque store key for one canonical preimage (RFC 0013).
+ *
+ * The preimage never appears in the result. An unkeyed digest would be
+ * offline-guessable — the schema is public and identifier value spaces are
+ * small — so the derivation is an HMAC under a per-namespace secret.
+ */
+export declare function deriveProtocolCacheKey(options: DeriveProtocolCacheKeyOptions): string;
+//# sourceMappingURL=cache-keys.d.ts.map

package/dist/cache-keys/cache-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-keys.d.ts","sourceRoot":"","sources":["../../src/cache-keys/cache-keys.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC/B,MAAM,YAAY,CAAC;AAUpB,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;gBAE7B,IAAI,EAAE,yBAAyB;CAO5C;AA8FD;;;GAGG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,CAUR;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,MAAM,CA8BrF"}

package/dist/cache-keys/cache-keys.js

@@ -0,0 +1,141 @@
+import { hmac } from '@noble/hashes/hmac';
+import { sha256 } from '@noble/hashes/sha2';
+import { validateProtocolDeploymentReleaseTarget } from '../releases/validate.js';
+import { PROTOCOL_CACHE_KEY_LIMITS, } from './types.js';
+const SCHEME = 'hq1';
+const NAMESPACE_DOMAIN = 'hypequery.cache.namespace.v1';
+const ENTRY_DOMAIN = 'hypequery.cache.entry.v1';
+const textEncoder = new TextEncoder();
+const BASE64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+export class ProtocolCacheKeyError extends Error {
+    code;
+    constructor(code) {
+        // The message is the code and nothing else: an error here has the secret
+        // and the preimage in scope, and neither may reach a log.
+        super(code);
+        this.name = 'ProtocolCacheKeyError';
+        this.code = code;
+    }
+}
+function cacheKeyError(code) {
+    throw new ProtocolCacheKeyError(code);
+}
+/** RFC 4648 base64url without padding. */
+function base64url(bytes) {
+    let out = '';
+    for (let index = 0; index < bytes.length; index += 3) {
+        const b0 = bytes[index];
+        const b1 = bytes[index + 1];
+        const b2 = bytes[index + 2];
+        out += BASE64URL[b0 >> 2];
+        out += BASE64URL[((b0 & 0x03) << 4) | ((b1 ?? 0) >> 4)];
+        if (b1 === undefined)
+            break;
+        out += BASE64URL[((b1 & 0x0f) << 2) | ((b2 ?? 0) >> 6)];
+        if (b2 === undefined)
+            break;
+        out += BASE64URL[b2 & 0x3f];
+    }
+    return out;
+}
+/**
+ * Joins parts with a single 0x00 byte. RFC 0008 restricts deployment target
+ * tokens to an ASCII grammar that excludes 0x00, so the concatenation is
+ * injective — which is why the namespace must be validated before this runs.
+ */
+function joinNulSeparated(parts) {
+    const total = parts.reduce((sum, part) => sum + part.byteLength, 0) + parts.length - 1;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    parts.forEach((part, index) => {
+        if (index > 0) {
+            out[offset] = 0x00;
+            offset += 1;
+        }
+        out.set(part, offset);
+        offset += part.byteLength;
+    });
+    return out;
+}
+function requireSecret(secret) {
+    if (!secret || secret.byteLength === 0)
+        cacheKeyError('HQ_CACHE_KEY_SECRET_MISSING');
+    if (secret.byteLength < PROTOCOL_CACHE_KEY_LIMITS.minSecretBytes) {
+        cacheKeyError('HQ_CACHE_KEY_SECRET_TOO_SHORT');
+    }
+    return secret;
+}
+function requireNamespace(namespace) {
+    try {
+        const target = validateProtocolDeploymentReleaseTarget(namespace);
+        return {
+            project: textEncoder.encode(target.project),
+            environment: textEncoder.encode(target.environment),
+        };
+    }
+    catch {
+        // Deliberately does not forward release-target validation details: a
+        // single code keeps callers from branching on namespace internals.
+        cacheKeyError('HQ_CACHE_KEY_INVALID_NAMESPACE');
+    }
+}
+function requireKeyVersion(keyVersion) {
+    if (typeof keyVersion !== 'number'
+        || !Number.isSafeInteger(keyVersion)
+        || keyVersion < PROTOCOL_CACHE_KEY_LIMITS.minKeyVersion
+        || keyVersion > PROTOCOL_CACHE_KEY_LIMITS.maxKeyVersion) {
+        cacheKeyError('HQ_CACHE_KEY_INVALID_VERSION');
+    }
+    return keyVersion;
+}
+function requirePreimage(preimage) {
+    if (typeof preimage === 'string'
+        && preimage.length > PROTOCOL_CACHE_KEY_LIMITS.maxPreimageBytes) {
+        cacheKeyError('HQ_CACHE_KEY_PREIMAGE_TOO_LARGE');
+    }
+    const bytes = typeof preimage === 'string' ? textEncoder.encode(preimage) : preimage;
+    if (bytes.byteLength > PROTOCOL_CACHE_KEY_LIMITS.maxPreimageBytes) {
+        cacheKeyError('HQ_CACHE_KEY_PREIMAGE_TOO_LARGE');
+    }
+    return bytes;
+}
+/**
+ * Derives the opaque namespace prefix. Truncated to 16 bytes because it is a
+ * grouping label for prefix operations, not an authentication tag.
+ */
+export function deriveProtocolCacheNamespaceToken(secret, project, environment) {
+    const key = requireSecret(secret);
+    const namespace = requireNamespace({ project, environment });
+    const input = joinNulSeparated([
+        textEncoder.encode(NAMESPACE_DOMAIN),
+        namespace.project,
+        namespace.environment,
+    ]);
+    const mac = hmac(sha256, key, input);
+    return base64url(mac.slice(0, PROTOCOL_CACHE_KEY_LIMITS.namespaceTokenBytes));
+}
+/**
+ * Derives the opaque store key for one canonical preimage (RFC 0013).
+ *
+ * The preimage never appears in the result. An unkeyed digest would be
+ * offline-guessable — the schema is public and identifier value spaces are
+ * small — so the derivation is an HMAC under a per-namespace secret.
+ */
+export function deriveProtocolCacheKey(options) {
+    const secret = requireSecret(options.secret);
+    const { project, environment } = requireNamespace(options.namespace);
+    const keyVersion = requireKeyVersion(options.keyVersion);
+    const preimage = requirePreimage(options.preimage);
+    const namespaceToken = base64url(hmac(sha256, secret, joinNulSeparated([textEncoder.encode(NAMESPACE_DOMAIN), project, environment])).slice(0, PROTOCOL_CACHE_KEY_LIMITS.namespaceTokenBytes));
+    // The namespace participates in the entry MAC directly, not only through the
+    // prefix, so two namespaces cannot collide even in a store that ignores
+    // prefixes.
+    const entryMac = hmac(sha256, secret, joinNulSeparated([textEncoder.encode(ENTRY_DOMAIN), project, environment, preimage]));
+    const key = `${SCHEME}.${keyVersion}.${namespaceToken}.${base64url(entryMac)}`;
+    /* c8 ignore next 3 -- unreachable with version-1 limits; a guard against a
+       future format change silently exceeding what stores accept. */
+    if (textEncoder.encode(key).byteLength > PROTOCOL_CACHE_KEY_LIMITS.maxStoreKeyBytes) {
+        cacheKeyError('HQ_CACHE_KEY_INVALID_VERSION');
+    }
+    return key;
+}

package/dist/cache-keys/index.d.ts

@@ -0,0 +1,4 @@
+export { ProtocolCacheKeyError, deriveProtocolCacheKey, deriveProtocolCacheNamespaceToken, } from './cache-keys.js';
+export { PROTOCOL_CACHE_KEY_LIMITS } from './types.js';
+export type { DeriveProtocolCacheKeyOptions, ProtocolCacheKeyErrorCode, ProtocolCacheKeyNamespace, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache-keys/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache-keys/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,iCAAiC,GAClC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACvD,YAAY,EACV,6BAA6B,EAC7B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,YAAY,CAAC"}

package/dist/cache-keys/index.js

@@ -0,0 +1,2 @@
+export { ProtocolCacheKeyError, deriveProtocolCacheKey, deriveProtocolCacheNamespaceToken, } from './cache-keys.js';
+export { PROTOCOL_CACHE_KEY_LIMITS } from './types.js';

package/dist/cache-keys/types.d.ts

@@ -0,0 +1,26 @@
+/** Absolute limits for cache key version 1 (RFC 0013). */
+export declare const PROTOCOL_CACHE_KEY_LIMITS: {
+    readonly minSecretBytes: 32;
+    readonly maxPreimageBytes: 1048576;
+    readonly namespaceTokenBytes: 16;
+    readonly entryMacBytes: 32;
+    readonly maxStoreKeyBytes: 128;
+    readonly minKeyVersion: 1;
+    readonly maxKeyVersion: 2147483647;
+};
+export type ProtocolCacheKeyErrorCode = 'HQ_CACHE_KEY_SECRET_MISSING' | 'HQ_CACHE_KEY_SECRET_TOO_SHORT' | 'HQ_CACHE_KEY_INVALID_NAMESPACE' | 'HQ_CACHE_KEY_INVALID_VERSION' | 'HQ_CACHE_KEY_PREIMAGE_TOO_LARGE';
+/** The RFC 0008 deployment target a cache entry belongs to. */
+export interface ProtocolCacheKeyNamespace {
+    readonly project: string;
+    readonly environment: string;
+}
+export interface DeriveProtocolCacheKeyOptions {
+    /** At least 32 bytes, distinct per namespace, never derived from a name. */
+    readonly secret: Uint8Array;
+    readonly namespace: ProtocolCacheKeyNamespace;
+    /** Increments whenever the namespace secret is rotated. */
+    readonly keyVersion: number;
+    /** Canonical bytes identifying the query. Stays in memory. */
+    readonly preimage: Uint8Array | string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cache-keys/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cache-keys/types.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,eAAO,MAAM,yBAAyB;;;;;;;;CAQ5B,CAAC;AAEX,MAAM,MAAM,yBAAyB,GACjC,6BAA6B,GAC7B,+BAA+B,GAC/B,gCAAgC,GAChC,8BAA8B,GAC9B,iCAAiC,CAAC;AAEtC,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,6BAA6B;IAC5C,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAC;IAC9C,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC;CACxC"}

package/dist/cache-keys/types.js

@@ -0,0 +1,10 @@
+/** Absolute limits for cache key version 1 (RFC 0013). */
+export const PROTOCOL_CACHE_KEY_LIMITS = {
+    minSecretBytes: 32,
+    maxPreimageBytes: 1_048_576,
+    namespaceTokenBytes: 16,
+    entryMacBytes: 32,
+    maxStoreKeyBytes: 128,
+    minKeyVersion: 1,
+    maxKeyVersion: 2_147_483_647,
+};

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 export { DEFAULT_CANONICAL_VALUE_LIMITS, ProtocolValueError, decodeCanonicalValue, encodeCanonicalValue, encodeCanonicalValueToString, hashCanonicalValue, validateCanonicalValue, } from './values/index.js';
 export type { ArrayTaggedValue, BytesTaggedValue, CanonicalValue, CanonicalValueLimits, CanonicalValueOptions, DateTaggedValue, DatetimeTaggedValue, DecimalTaggedValue, EnumTaggedValue, IntegerTaggedValue, MapTaggedValue, ProtocolValueErrorCode, TaggedValue, TupleTaggedValue, UuidTaggedValue, } from './values/index.js';
 export { PROTOCOL_IDENTIFIER_LIMITS, ProtocolIdentifierError, isProtocolIdentifier, isProtocolQualifiedIdentifier, joinProtocolQualifiedIdentifier, parseProtocolIdentifier, parseProtocolQualifiedIdentifier, splitProtocolQualifiedIdentifier, } from './identifiers/index.js';
+export { PROTOCOL_CACHE_KEY_LIMITS, ProtocolCacheKeyError, deriveProtocolCacheKey, deriveProtocolCacheNamespaceToken, } from './cache-keys/index.js';
 export { DEFAULT_PROTOCOL_EXPRESSION_LIMITS, ProtocolExpressionError, validateProtocolExpression, validateProtocolSemanticQuery, } from './expressions/index.js';
 export { DEFAULT_PROTOCOL_SCHEMA_LIMITS, DEFAULT_PROTOCOL_SCHEMA_VALUE_LIMITS, ProtocolSchemaError, ProtocolSchemaValueError, applyProtocolSchemaValue, createProtocolSchemaValueParser, resolveProtocolSchemaValueLimits, validateProtocolSchema, } from './schemas/index.js';
 export type { ProtocolSchema, ProtocolSchemaErrorCode, ProtocolSchemaLimits, ProtocolSchemaOptions, ProtocolSchemaValueLimits, ProtocolSchemaValueOptions, ProtocolSchemaValueParser, } from './schemas/index.js';
 export type { ProtocolAggregation, ProtocolBinaryOperator, ProtocolComparisonOperator, ProtocolDatasetQuery, ProtocolExpression, ProtocolExpressionErrorCode, ProtocolExpressionLimits, ProtocolExpressionOptions, ProtocolFunctionName, ProtocolMetricQuery, ProtocolOrderBy, ProtocolSemanticQuery, ProtocolTimeGrain, } from './expressions/index.js';
+export type { DeriveProtocolCacheKeyOptions, ProtocolCacheKeyErrorCode, ProtocolCacheKeyNamespace, } from './cache-keys/index.js';
 export type { ProtocolIdentifier, ProtocolIdentifierErrorCode, ProtocolQualifiedIdentifier, } from './identifiers/index.js';
 export { DEFAULT_PROTOCOL_QUERY_IMPLEMENTATION_LIMITS, ProtocolQueryImplementationError, validateProtocolQueryImplementation, validateProtocolSqlExpression, } from './query-implementations/index.js';
 export { DEFAULT_PROTOCOL_QUERY_EVENT_LIMITS, ProtocolQueryDiagnosticsError, ProtocolQueryEventError, validateProtocolQueryDiagnostics, validateProtocolQueryEvent, } from './events/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export { DEFAULT_CANONICAL_VALUE_LIMITS, ProtocolValueError, decodeCanonicalValue, encodeCanonicalValue, encodeCanonicalValueToString, hashCanonicalValue, validateCanonicalValue, } from './values/index.js';
 export { PROTOCOL_IDENTIFIER_LIMITS, ProtocolIdentifierError, isProtocolIdentifier, isProtocolQualifiedIdentifier, joinProtocolQualifiedIdentifier, parseProtocolIdentifier, parseProtocolQualifiedIdentifier, splitProtocolQualifiedIdentifier, } from './identifiers/index.js';
+export { PROTOCOL_CACHE_KEY_LIMITS, ProtocolCacheKeyError, deriveProtocolCacheKey, deriveProtocolCacheNamespaceToken, } from './cache-keys/index.js';
 export { DEFAULT_PROTOCOL_EXPRESSION_LIMITS, ProtocolExpressionError, validateProtocolExpression, validateProtocolSemanticQuery, } from './expressions/index.js';
 export { DEFAULT_PROTOCOL_SCHEMA_LIMITS, DEFAULT_PROTOCOL_SCHEMA_VALUE_LIMITS, ProtocolSchemaError, ProtocolSchemaValueError, applyProtocolSchemaValue, createProtocolSchemaValueParser, resolveProtocolSchemaValueLimits, validateProtocolSchema, } from './schemas/index.js';
 export { DEFAULT_PROTOCOL_QUERY_IMPLEMENTATION_LIMITS, ProtocolQueryImplementationError, validateProtocolQueryImplementation, validateProtocolSqlExpression, } from './query-implementations/index.js';

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

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/values/validate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA0VpB,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAOhB;AAYD,kFAAkF;AAClF,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,QAAQ,CAAC,oBAAoB,CAAC,EACtC,sBAAsB,CAAC,EAAE,MAAM,GAC9B,cAAc,CAGhB;AAED,6EAA6E;AAC7E,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,QAAQ,CAAC,oBAAoB,CAAC,EACtC,sBAAsB,CAAC,EAAE,MAAM,GAC9B,cAAc,CAEhB"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/values/validate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAqWpB,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAOhB;AAYD,kFAAkF;AAClF,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,QAAQ,CAAC,oBAAoB,CAAC,EACtC,sBAAsB,CAAC,EAAE,MAAM,GAC9B,cAAc,CAGhB;AAED,6EAA6E;AAC7E,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,QAAQ,CAAC,oBAAoB,CAAC,EACtC,sBAAsB,CAAC,EAAE,MAAM,GAC9B,cAAc,CAEhB"}

package/dist/values/validate.js

@@ -40,10 +40,15 @@ function requireMetadataInteger(value, path) {
     }
     return value;
 }
+// Tab, line feed, and carriage return are permitted so authored prose can
+// span lines; JCS escapes them deterministically. Every other C0 control, DEL,
+// and the C1 range stay forbidden.
+const ALLOWED_CONTROL_CHARACTERS = new Set([0x09, 0x0a, 0x0d]);
 function validateUnicode(value, path, maxBytes) {
     for (let index = 0; index < value.length; index += 1) {
         const code = value.charCodeAt(index);
-        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f)) {
+        if ((code <= 0x1f && !ALLOWED_CONTROL_CHARACTERS.has(code))
+            || (code >= 0x7f && code <= 0x9f)) {
             valueError('HQ_VALUE_CONTROL_CHARACTER', path);
         }
         if (code >= 0xd800 && code <= 0xdbff) {
@@ -139,7 +144,10 @@ function validateDatetimeTag(tag, path) {
     }
     const timezone = requireString(tag.timezone, `${path}.timezone`);
     validateUnicode(timezone, `${path}.timezone`, 64);
-    if (timezone !== 'UTC' && !/^[A-Za-z_]+(?:\/[A-Za-z0-9_+-]+)+$/.test(timezone)) {
+    // Single-component identifiers are valid: UTC, EST, GMT, CET, and MST7MDT
+    // are all real tzdb entries. Existence is checked at deployment time
+    // against the server's system.time_zones, not here.
+    if (!/^[A-Za-z][A-Za-z0-9_+-]*(?:\/[A-Za-z0-9_+-]+)*$/.test(timezone)) {
         valueError('HQ_VALUE_INVALID_FORMAT', `${path}.timezone`);
     }
     const value = requireString(tag.value, `${path}.value`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/protocol",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Portable analytics contracts and TypeScript reference implementation for Hypequery",
   "keywords": [
     "hypequery",