@hypequery/serve 0.13.6 → 0.14.0

package/dist/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAmB,MAAM,KAAK,CAAC;AAEzC,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EAKX,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,EAGb,MAAM,YAAY,CAAC;AAMpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAOrD,OAAO,EAAE,KAAK,kBAAkB,EAAqB,MAAM,WAAW,CAAC;AAoMvE,MAAM,WAAW,sBAAsB,CACrC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW;IAEzB,QAAQ,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IACnD,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;IACtC,cAAc,CAAC,EAAE,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACtD,iBAAiB,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;IAChE,YAAY,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,eAAO,MAAM,eAAe,GAC1B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW,EAEzB,SAAS,sBAAsB,CAAC,QAAQ,EAAE,KAAK,CAAC,KAC/C,OAAO,CAAC,aAAa,CA2TvB,CAAC;AAEF,UAAU,cAAc,CACtB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW;IAEzB,MAAM,EAAE,OAAO,aAAa,EAAE,WAAW,CAAC;IAC1C,iBAAiB,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;IAChE,cAAc,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;IACtC,YAAY,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,cAAc,CAAC,EAAE,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACtD,KAAK,CAAC,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,UAAU,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACxC;AAED,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW,EACzB,iIAUC,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAG,YA0CpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,MAAM,MAAM,EACZ,cAAc,MAAM,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EACvD,UAAU,cAAc;;;;;;;;;;;;;;;;;;;;;CA8BzB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAC7B,MAAM,MAAM,EACZ,aAAa,MAAM,EACnB,UAAU,WAAW;;;;;;;;;;;;;;;;;;;;;;;;CAyBmD,CAAC"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAmB,MAAM,KAAK,CAAC;AAEzC,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EAKX,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,EAGb,MAAM,YAAY,CAAC;AAMpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAOrD,OAAO,EAAE,KAAK,kBAAkB,EAAqB,MAAM,WAAW,CAAC;AA0OvE,MAAM,WAAW,sBAAsB,CACrC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW;IAEzB,QAAQ,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IACnD,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;IACtC,cAAc,CAAC,EAAE,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACtD,iBAAiB,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;IAChE,YAAY,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,eAAO,MAAM,eAAe,GAC1B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW,EAEzB,SAAS,sBAAsB,CAAC,QAAQ,EAAE,KAAK,CAAC,KAC/C,OAAO,CAAC,aAAa,CA4TvB,CAAC;AAEF,UAAU,cAAc,CACtB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW;IAEzB,MAAM,EAAE,OAAO,aAAa,EAAE,WAAW,CAAC;IAC1C,iBAAiB,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;IAChE,cAAc,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;IACtC,YAAY,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,cAAc,CAAC,EAAE,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACtD,KAAK,CAAC,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,UAAU,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACxC;AAED,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW,EACzB,iIAUC,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAG,YAkDpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,MAAM,MAAM,EACZ,cAAc,MAAM,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EACvD,UAAU,cAAc;;;;;;;;;;;;;;;;;;;;;CA8BzB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAC7B,MAAM,MAAM,EACZ,aAAa,MAAM,EACnB,UAAU,WAAW;;;;;;;;;;;;;;;;;;;;;;;;CAyBmD,CAAC"}

package/dist/pipeline.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { warnTenantMisconfiguration } from './tenant.js';
 import { applySemanticTenantRuntime } from './semantic/utils/tenant-runtime.js';
-import { generateRequestId } from './utils.js';
+import { generateRequestId, validateCorrelationId } from './utils.js';
 import { buildOpenApiDocument } from './openapi.js';
 import { buildDocsHtml } from './docs-ui.js';
 import { ServeHttpError } from './errors.js';
@@ -134,12 +134,37 @@ const resolveContext = async (factory, request, auth) => {
     }
     return cloneContext(factory);
 };
-const resolveRequestId = (request, provided) => provided ?? request.headers['x-request-id'] ?? request.headers['x-trace-id'] ?? generateRequestId();
+/**
+ * Resolve the authoritative request id and the optional external correlation id.
+ *
+ * The authoritative id is always server-generated unless a trusted in-process caller passes
+ * one explicitly; a network-supplied `x-request-id`/`x-trace-id` is NEVER treated as
+ * authoritative. Any caller-supplied value is validated and length-bounded and surfaced only
+ * as a separate correlation id, so it cannot inject control characters into logs/headers or
+ * spoof cross-request correlation.
+ */
+const resolveRequestContext = (request, provided) => ({
+    requestId: validateCorrelationId(provided) ?? generateRequestId(),
+    correlationId: validateCorrelationId(request.headers['x-request-id']) ??
+        validateCorrelationId(request.headers['x-trace-id']),
+});
+const withManagedTraceHeaders = (headers, requestId, correlationId) => ({
+    ...Object.fromEntries(Object.entries(headers ?? {}).filter(([key]) => {
+        const normalized = key.toLowerCase();
+        return normalized !== 'x-request-id' && normalized !== 'x-correlation-id';
+    })),
+    'x-request-id': requestId,
+    ...(correlationId ? { 'x-correlation-id': correlationId } : {}),
+});
 export const executeEndpoint = async (options) => {
     const { endpoint, request, requestId: explicitRequestId, authStrategies, contextFactory, globalMiddlewares, tenantConfig, hooks = {}, queryLogger, additionalContext, verboseAuthErrors = false, // Default to secure mode for production safety
     sanitizeErrors = true, // Default to secure mode for HTTP requests
      } = options;
-    const requestId = resolveRequestId(request, explicitRequestId);
+    const { requestId, correlationId } = resolveRequestContext(request, explicitRequestId);
+    // Echoed alongside the authoritative x-request-id; only ever a validated caller value.
+    const traceHeaders = correlationId
+        ? { 'x-correlation-id': correlationId }
+        : {};
     const locals = {};
     let cacheTtlMs = endpoint.cacheTtlMs ?? null;
     const setCacheTtl = (ttl) => {
@@ -206,7 +231,7 @@ export const executeEndpoint = async (options) => {
                 ...(verboseAuthErrors && { strategies_attempted: strategies.length }),
                 ...(verboseAuthErrors && authErrorInfo?.details ? { auth_error: authErrorInfo.details } : {}),
                 endpoint: endpoint.metadata.path,
-            }, { 'x-request-id': requestId, 'cache-control': 'no-store' });
+            }, { 'x-request-id': requestId, ...traceHeaders, 'cache-control': 'no-store' });
         }
         context.auth = authContext;
         // Check role/scope authorization after successful authentication
@@ -232,7 +257,7 @@ export const executeEndpoint = async (options) => {
                     actual: authzResult.actual,
                 }),
                 endpoint: endpoint.metadata.path,
-            }, { 'x-request-id': requestId, 'cache-control': 'no-store' });
+            }, { 'x-request-id': requestId, ...traceHeaders, 'cache-control': 'no-store' });
         }
         const resolvedContext = await resolveContext(contextFactory, request, authContext);
         Object.assign(context, resolvedContext, additionalContext);
@@ -255,7 +280,7 @@ export const executeEndpoint = async (options) => {
                 return createErrorResponse(403, 'FORBIDDEN', errorMessage, {
                     reason: 'missing_tenant_context',
                     tenant_required: true,
-                }, { 'x-request-id': requestId, 'cache-control': 'no-store' });
+                }, { 'x-request-id': requestId, ...traceHeaders, 'cache-control': 'no-store' });
             }
             if (tenantId) {
                 context.tenantId = tenantId;
@@ -291,7 +316,7 @@ export const executeEndpoint = async (options) => {
             });
             return createErrorResponse(400, 'VALIDATION_ERROR', 'Request validation failed', {
                 issues: validationResult.error.issues,
-            }, { 'x-request-id': requestId });
+            }, { 'x-request-id': requestId, ...traceHeaders });
         }
         context.input = validationResult.data;
         const pipeline = [
@@ -299,10 +324,7 @@ export const executeEndpoint = async (options) => {
             ...endpoint.middlewares,
         ];
         const result = await runMiddlewares(pipeline, context, () => endpoint.handler(context));
-        const headers = {
-            ...(endpoint.defaultHeaders ?? {}),
-            'x-request-id': requestId,
-        };
+        const headers = withManagedTraceHeaders(endpoint.defaultHeaders, requestId, correlationId);
         // Authenticated and tenant-aware responses must never be shared by an
         // intermediary cache. Endpoint TTLs only opt public, tenant-independent
         // responses into shared caching.
@@ -377,7 +399,7 @@ export const executeEndpoint = async (options) => {
             'status' in error &&
             'payload' in error) {
             const structured = error;
-            const response = createErrorResponse(structured.status, structured.payload.type, structured.payload.message, undefined, { 'x-request-id': requestId, ...(structured.headers ?? {}) });
+            const response = createErrorResponse(structured.status, structured.payload.type, structured.payload.message, undefined, withManagedTraceHeaders(structured.headers, requestId, correlationId));
             return response;
         }
         // When sanitizeErrors is enabled (default for HTTP), hide internal error
@@ -386,20 +408,24 @@ export const executeEndpoint = async (options) => {
         const errorMessage = sanitizeErrors
             ? 'An unexpected error occurred'
             : (error instanceof Error ? error.message : String(error));
-        return createErrorResponse(500, 'INTERNAL_SERVER_ERROR', errorMessage, undefined, { 'x-request-id': requestId });
+        return createErrorResponse(500, 'INTERNAL_SERVER_ERROR', errorMessage, undefined, { 'x-request-id': requestId, ...traceHeaders });
     }
 };
 export const createServeHandler = ({ router, globalMiddlewares, authStrategies, tenantConfig, contextFactory, hooks, queryLogger, verboseAuthErrors = false, corsConfig, }) => {
     return async (request) => {
+        const { requestId, correlationId } = resolveRequestContext(request);
+        const traceHeaders = correlationId
+            ? { 'x-correlation-id': correlationId }
+            : {};
         // Handle CORS preflight and compute headers for actual requests
         const { preflightResponse, corsHeaders } = handleCorsRequest(corsConfig ?? null, request);
         if (preflightResponse) {
+            preflightResponse.headers = withManagedTraceHeaders(preflightResponse.headers, requestId, correlationId);
             return preflightResponse;
         }
-        const requestId = resolveRequestId(request);
         const endpoint = router.match(request.method, request.path);
         if (!endpoint) {
-            const response = createErrorResponse(404, 'NOT_FOUND', `No endpoint registered for ${request.method} ${request.path}`, undefined, { 'x-request-id': requestId });
+            const response = createErrorResponse(404, 'NOT_FOUND', `No endpoint registered for ${request.method} ${request.path}`, undefined, { 'x-request-id': requestId, ...traceHeaders });
             response.headers = { ...response.headers, ...corsHeaders };
             return response;
         }

package/dist/utils.d.ts

@@ -1,5 +1,14 @@
 export declare const ensureArray: <T>(value: T | T[] | undefined | null) => T[];
 export declare const mergeTags: (existing: string[], next?: string[]) => string[];
 export declare const generateRequestId: () => string;
+/** Upper bound on an accepted external correlation id, in UTF-8 bytes. */
+export declare const MAX_CORRELATION_ID_BYTES = 200;
+/**
+ * Validate a caller-supplied external correlation id (e.g. `x-request-id`). This value is
+ * never authoritative — the authoritative request id is generated server-side. Returns the
+ * trimmed value when it is a safe, bounded string, or `undefined` when absent or rejected
+ * (empty, control characters, or over {@link MAX_CORRELATION_ID_BYTES}).
+ */
+export declare const validateCorrelationId: (value?: string) => string | undefined;
 export declare const normalizeHeaderMap: (headers?: Record<string, string | undefined>) => Record<string, string | undefined>;
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,GAAG,IAAI,KAAG,CAAC,EAKnE,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,UAAU,MAAM,EAAE,EAAE,OAAO,MAAM,EAAE,aAG5D,CAAC;AAEF,eAAO,MAAM,iBAAiB,QAAO,MAKpC,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAC7B,UAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAM,KAC/C,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAInC,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,GAAG,IAAI,KAAG,CAAC,EAKnE,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,UAAU,MAAM,EAAE,EAAE,OAAO,MAAM,EAAE,aAG5D,CAAC;AAEF,eAAO,MAAM,iBAAiB,QAAO,MAKpC,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAS5C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,KAAG,MAAM,GAAG,SAU/D,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAC7B,UAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAM,KAC/C,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAInC,CAAC"}

package/dist/utils.js

@@ -14,6 +14,36 @@ export const generateRequestId = () => {
     }
     return `req_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
 };
+/** Upper bound on an accepted external correlation id, in UTF-8 bytes. */
+export const MAX_CORRELATION_ID_BYTES = 200;
+// C0 controls, DEL, and C1 controls — rejected so a caller-supplied correlation id can
+// never inject newlines/control sequences into logs or response headers.
+// eslint-disable-next-line no-control-regex -- control chars are exactly what we reject
+const CORRELATION_CONTROL_CHARS = /[\u0000-\u001F\u007F-\u009F]/;
+const CORRELATION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/;
+const correlationIdEncoder = new TextEncoder();
+/**
+ * Validate a caller-supplied external correlation id (e.g. `x-request-id`). This value is
+ * never authoritative — the authoritative request id is generated server-side. Returns the
+ * trimmed value when it is a safe, bounded string, or `undefined` when absent or rejected
+ * (empty, control characters, or over {@link MAX_CORRELATION_ID_BYTES}).
+ */
+export const validateCorrelationId = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (CORRELATION_CONTROL_CHARS.test(trimmed))
+        return undefined;
+    // Keep external identifiers in a narrow ASCII grammar so Unicode
+    // confusables and whitespace cannot produce visually ambiguous values.
+    if (!CORRELATION_ID_PATTERN.test(trimmed))
+        return undefined;
+    if (correlationIdEncoder.encode(trimmed).length > MAX_CORRELATION_ID_BYTES)
+        return undefined;
+    return trimmed;
+};
 export const normalizeHeaderMap = (headers = {}) => {
     return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/serve",
-  "version": "0.13.6",
+  "version": "0.14.0",
   "description": "Declarative HTTP server for exposing hypequery analytics endpoints",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,7 +27,7 @@
     "openapi-typescript": "^7.13.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5",
-    "@hypequery/datasets": "^0.12.7"
+    "@hypequery/datasets": "^0.13.0"
   },
   "peerDependencies": {
     "tsx": "^4.0.0"