autotel 3.4.4 → 3.6.0

package/dist/security-schema.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Security telemetry wire schema — the single source of truth for the
+ * `security.*` span-attribute contract emitted by `autotel-audit`
+ * (`securityEvent()`, `withSecurity()`, `createSecuritySignalProcessor()`)
+ * and consumed by `autotel-subscribers`, `autotel-devtools`, and the
+ * `autotel security` CLI commands.
+ *
+ * Dependency-free and side-effect-free by design: safe to import from
+ * browser bundles (devtools widget) and anything else that only needs
+ * the constants, without pulling in the OpenTelemetry SDK.
+ */
+type SecuritySeverity = 'info' | 'warning' | 'error' | 'critical';
+/** All severities, lowest first. */
+declare const SECURITY_SEVERITIES: readonly SecuritySeverity[];
+/** Numeric rank per severity for threshold comparisons. */
+declare const SECURITY_SEVERITY_RANK: Record<SecuritySeverity, number>;
+/**
+ * Parse an untrusted value (span attribute, event payload field) into a
+ * severity, falling back when it is missing or malformed.
+ */
+declare function parseSecuritySeverity(value: unknown, fallback?: SecuritySeverity): SecuritySeverity;
+/** `true` when `severity` meets or exceeds `min`. */
+declare function securitySeverityAtLeast(severity: SecuritySeverity, min: SecuritySeverity): boolean;
+/** The higher-ranked of two severities (e.g. escalate failures to ≥ error). */
+declare function escalateSecuritySeverity(severity: SecuritySeverity, floor: SecuritySeverity): SecuritySeverity;
+/**
+ * Span attribute keys of the security schema. Emitters and consumers must
+ * reference these instead of re-typing the strings.
+ */
+declare const SECURITY_ATTR: {
+    /** Marker set on every span carrying a security event. */
+    readonly marker: "autotel.security";
+    /** Set when the event was force-kept through tail sampling. */
+    readonly forceKeep: "autotel.security.force_keep";
+    readonly event: "security.event";
+    readonly category: "security.category";
+    readonly outcome: "security.outcome";
+    readonly severity: "security.severity";
+    readonly actorId: "security.actor_id";
+    readonly targetType: "security.target_type";
+    readonly targetId: "security.target_id";
+    readonly tenantId: "security.tenant_id";
+    readonly reason: "security.reason";
+    /** Custom metadata keys dropped because they looked credential-shaped. */
+    readonly droppedKeys: "security.dropped_keys";
+    /** Set by the signal processor on suspicious request paths. */
+    readonly suspiciousRequest: "security.suspicious_request";
+    /** Pattern name that flagged a suspicious request, e.g. `path_traversal`. */
+    readonly signal: "security.signal";
+};
+/** Metric names emitted by the security instrumentation. */
+declare const SECURITY_METRICS: {
+    readonly events: "autotel.security.events";
+    readonly httpSuspicious: "autotel.security.http.suspicious";
+    readonly httpDenied: "autotel.security.http.denied";
+    readonly anomaly: "autotel.security.anomaly";
+    readonly heartbeat: "autotel.security.heartbeat";
+};
+/** HTTP statuses counted as denied responses by default. */
+declare const SECURITY_DENIED_STATUSES: readonly number[];
+/**
+ * Span attributes carrying the HTTP response status, current semconv
+ * first, legacy fallback second.
+ */
+declare const HTTP_STATUS_ATTRIBUTES: readonly string[];
+
+export { HTTP_STATUS_ATTRIBUTES, SECURITY_ATTR, SECURITY_DENIED_STATUSES, SECURITY_METRICS, SECURITY_SEVERITIES, SECURITY_SEVERITY_RANK, type SecuritySeverity, escalateSecuritySeverity, parseSecuritySeverity, securitySeverityAtLeast };

package/dist/security-schema.js

@@ -0,0 +1,59 @@
+// src/security-schema.ts
+var SECURITY_SEVERITIES = [
+  "info",
+  "warning",
+  "error",
+  "critical"
+];
+var SECURITY_SEVERITY_RANK = {
+  info: 0,
+  warning: 1,
+  error: 2,
+  critical: 3
+};
+function parseSecuritySeverity(value, fallback = "info") {
+  return typeof value === "string" && value in SECURITY_SEVERITY_RANK ? value : fallback;
+}
+function securitySeverityAtLeast(severity, min) {
+  return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[min];
+}
+function escalateSecuritySeverity(severity, floor) {
+  return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[floor] ? severity : floor;
+}
+var SECURITY_ATTR = {
+  /** Marker set on every span carrying a security event. */
+  marker: "autotel.security",
+  /** Set when the event was force-kept through tail sampling. */
+  forceKeep: "autotel.security.force_keep",
+  event: "security.event",
+  category: "security.category",
+  outcome: "security.outcome",
+  severity: "security.severity",
+  actorId: "security.actor_id",
+  targetType: "security.target_type",
+  targetId: "security.target_id",
+  tenantId: "security.tenant_id",
+  reason: "security.reason",
+  /** Custom metadata keys dropped because they looked credential-shaped. */
+  droppedKeys: "security.dropped_keys",
+  /** Set by the signal processor on suspicious request paths. */
+  suspiciousRequest: "security.suspicious_request",
+  /** Pattern name that flagged a suspicious request, e.g. `path_traversal`. */
+  signal: "security.signal"
+};
+var SECURITY_METRICS = {
+  events: "autotel.security.events",
+  httpSuspicious: "autotel.security.http.suspicious",
+  httpDenied: "autotel.security.http.denied",
+  anomaly: "autotel.security.anomaly",
+  heartbeat: "autotel.security.heartbeat"
+};
+var SECURITY_DENIED_STATUSES = [401, 403, 429];
+var HTTP_STATUS_ATTRIBUTES = [
+  "http.response.status_code",
+  "http.status_code"
+];
+
+export { HTTP_STATUS_ATTRIBUTES, SECURITY_ATTR, SECURITY_DENIED_STATUSES, SECURITY_METRICS, SECURITY_SEVERITIES, SECURITY_SEVERITY_RANK, escalateSecuritySeverity, parseSecuritySeverity, securitySeverityAtLeast };
+//# sourceMappingURL=security-schema.js.map
+//# sourceMappingURL=security-schema.js.map

package/dist/security-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/security-schema.ts"],"names":[],"mappings":";AAeO,IAAM,mBAAA,GAAmD;AAAA,EAC9D,MAAA;AAAA,EACA,SAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF;AAGO,IAAM,sBAAA,GAA2D;AAAA,EACtE,IAAA,EAAM,CAAA;AAAA,EACN,OAAA,EAAS,CAAA;AAAA,EACT,KAAA,EAAO,CAAA;AAAA,EACP,QAAA,EAAU;AACZ;AAMO,SAAS,qBAAA,CACd,KAAA,EACA,QAAA,GAA6B,MAAA,EACX;AAClB,EAAA,OAAO,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,IAAS,yBACxC,KAAA,GACD,QAAA;AACN;AAGO,SAAS,uBAAA,CACd,UACA,GAAA,EACS;AACT,EAAA,OAAO,sBAAA,CAAuB,QAAQ,CAAA,IAAK,sBAAA,CAAuB,GAAG,CAAA;AACvE;AAGO,SAAS,wBAAA,CACd,UACA,KAAA,EACkB;AAClB,EAAA,OAAO,uBAAuB,QAAQ,CAAA,IAAK,sBAAA,CAAuB,KAAK,IACnE,QAAA,GACA,KAAA;AACN;AAMO,IAAM,aAAA,GAAgB;AAAA;AAAA,EAE3B,MAAA,EAAQ,kBAAA;AAAA;AAAA,EAER,SAAA,EAAW,6BAAA;AAAA,EACX,KAAA,EAAO,gBAAA;AAAA,EACP,QAAA,EAAU,mBAAA;AAAA,EACV,OAAA,EAAS,kBAAA;AAAA,EACT,QAAA,EAAU,mBAAA;AAAA,EACV,OAAA,EAAS,mBAAA;AAAA,EACT,UAAA,EAAY,sBAAA;AAAA,EACZ,QAAA,EAAU,oBAAA;AAAA,EACV,QAAA,EAAU,oBAAA;AAAA,EACV,MAAA,EAAQ,iBAAA;AAAA;AAAA,EAER,WAAA,EAAa,uBAAA;AAAA;AAAA,EAEb,iBAAA,EAAmB,6BAAA;AAAA;AAAA,EAEnB,MAAA,EAAQ;AACV;AAGO,IAAM,gBAAA,GAAmB;AAAA,EAC9B,MAAA,EAAQ,yBAAA;AAAA,EACR,cAAA,EAAgB,kCAAA;AAAA,EAChB,UAAA,EAAY,8BAAA;AAAA,EACZ,OAAA,EAAS,0BAAA;AAAA,EACT,SAAA,EAAW;AACb;AAGO,IAAM,wBAAA,GAA8C,CAAC,GAAA,EAAK,GAAA,EAAK,GAAG;AAMlE,IAAM,sBAAA,GAA4C;AAAA,EACvD,2BAAA;AAAA,EACA;AACF","file":"security-schema.js","sourcesContent":["/**\n * Security telemetry wire schema — the single source of truth for the\n * `security.*` span-attribute contract emitted by `autotel-audit`\n * (`securityEvent()`, `withSecurity()`, `createSecuritySignalProcessor()`)\n * and consumed by `autotel-subscribers`, `autotel-devtools`, and the\n * `autotel security` CLI commands.\n *\n * Dependency-free and side-effect-free by design: safe to import from\n * browser bundles (devtools widget) and anything else that only needs\n * the constants, without pulling in the OpenTelemetry SDK.\n */\n\nexport type SecuritySeverity = 'info' | 'warning' | 'error' | 'critical';\n\n/** All severities, lowest first. */\nexport const SECURITY_SEVERITIES: readonly SecuritySeverity[] = [\n  'info',\n  'warning',\n  'error',\n  'critical',\n];\n\n/** Numeric rank per severity for threshold comparisons. */\nexport const SECURITY_SEVERITY_RANK: Record<SecuritySeverity, number> = {\n  info: 0,\n  warning: 1,\n  error: 2,\n  critical: 3,\n};\n\n/**\n * Parse an untrusted value (span attribute, event payload field) into a\n * severity, falling back when it is missing or malformed.\n */\nexport function parseSecuritySeverity(\n  value: unknown,\n  fallback: SecuritySeverity = 'info',\n): SecuritySeverity {\n  return typeof value === 'string' && value in SECURITY_SEVERITY_RANK\n    ? (value as SecuritySeverity)\n    : fallback;\n}\n\n/** `true` when `severity` meets or exceeds `min`. */\nexport function securitySeverityAtLeast(\n  severity: SecuritySeverity,\n  min: SecuritySeverity,\n): boolean {\n  return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[min];\n}\n\n/** The higher-ranked of two severities (e.g. escalate failures to ≥ error). */\nexport function escalateSecuritySeverity(\n  severity: SecuritySeverity,\n  floor: SecuritySeverity,\n): SecuritySeverity {\n  return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[floor]\n    ? severity\n    : floor;\n}\n\n/**\n * Span attribute keys of the security schema. Emitters and consumers must\n * reference these instead of re-typing the strings.\n */\nexport const SECURITY_ATTR = {\n  /** Marker set on every span carrying a security event. */\n  marker: 'autotel.security',\n  /** Set when the event was force-kept through tail sampling. */\n  forceKeep: 'autotel.security.force_keep',\n  event: 'security.event',\n  category: 'security.category',\n  outcome: 'security.outcome',\n  severity: 'security.severity',\n  actorId: 'security.actor_id',\n  targetType: 'security.target_type',\n  targetId: 'security.target_id',\n  tenantId: 'security.tenant_id',\n  reason: 'security.reason',\n  /** Custom metadata keys dropped because they looked credential-shaped. */\n  droppedKeys: 'security.dropped_keys',\n  /** Set by the signal processor on suspicious request paths. */\n  suspiciousRequest: 'security.suspicious_request',\n  /** Pattern name that flagged a suspicious request, e.g. `path_traversal`. */\n  signal: 'security.signal',\n} as const;\n\n/** Metric names emitted by the security instrumentation. */\nexport const SECURITY_METRICS = {\n  events: 'autotel.security.events',\n  httpSuspicious: 'autotel.security.http.suspicious',\n  httpDenied: 'autotel.security.http.denied',\n  anomaly: 'autotel.security.anomaly',\n  heartbeat: 'autotel.security.heartbeat',\n} as const;\n\n/** HTTP statuses counted as denied responses by default. */\nexport const SECURITY_DENIED_STATUSES: readonly number[] = [401, 403, 429];\n\n/**\n * Span attributes carrying the HTTP response status, current semconv\n * first, legacy fallback second.\n */\nexport const HTTP_STATUS_ATTRIBUTES: readonly string[] = [\n  'http.response.status_code',\n  'http.status_code',\n];\n"]}

package/dist/semantic-helpers.cjs

@@ -1,10 +1,11 @@
 'use strict';
 
-var chunkVG2ABKJX_cjs = require('./chunk-VG2ABKJX.cjs');
-require('./chunk-FGNDN2FD.cjs');
+var chunkKYXZS3EA_cjs = require('./chunk-KYXZS3EA.cjs');
+require('./chunk-V7UBMJAB.cjs');
 require('./chunk-OPPXYVEZ.cjs');
 require('./chunk-VQTCQKHQ.cjs');
-require('./chunk-Z7PW3KHL.cjs');
+require('./chunk-FMTHVSYY.cjs');
+require('./chunk-EE6CPXKH.cjs');
 require('./chunk-R7QYGZUP.cjs');
 require('./chunk-QWW3E3JM.cjs');
 require('./chunk-CEAQK2QY.cjs');
@@ -23,19 +24,19 @@ require('./chunk-YREV3LGG.cjs');
 
 Object.defineProperty(exports, "traceDB", {
   enumerable: true,
-  get: function () { return chunkVG2ABKJX_cjs.traceDB; }
+  get: function () { return chunkKYXZS3EA_cjs.traceDB; }
 });
 Object.defineProperty(exports, "traceHTTP", {
   enumerable: true,
-  get: function () { return chunkVG2ABKJX_cjs.traceHTTP; }
+  get: function () { return chunkKYXZS3EA_cjs.traceHTTP; }
 });
 Object.defineProperty(exports, "traceLLM", {
   enumerable: true,
-  get: function () { return chunkVG2ABKJX_cjs.traceLLM; }
+  get: function () { return chunkKYXZS3EA_cjs.traceLLM; }
 });
 Object.defineProperty(exports, "traceMessaging", {
   enumerable: true,
-  get: function () { return chunkVG2ABKJX_cjs.traceMessaging; }
+  get: function () { return chunkKYXZS3EA_cjs.traceMessaging; }
 });
 //# sourceMappingURL=semantic-helpers.cjs.map
 //# sourceMappingURL=semantic-helpers.cjs.map

package/dist/semantic-helpers.js

@@ -1,8 +1,9 @@
-export { traceDB, traceHTTP, traceLLM, traceMessaging } from './chunk-NVGPMGI4.js';
-import './chunk-YWCESU4Y.js';
+export { traceDB, traceHTTP, traceLLM, traceMessaging } from './chunk-N25JDZSC.js';
+import './chunk-T7JO2TCP.js';
 import './chunk-HT5JQKN2.js';
 import './chunk-SEO6NAQT.js';
-import './chunk-O4JZUCUE.js';
+import './chunk-66YJ66GG.js';
+import './chunk-LVIPBYFE.js';
 import './chunk-ALPYR2GC.js';
 import './chunk-CMHVQR6P.js';
 import './chunk-A4E5AQFK.js';

package/dist/validate.cjs

@@ -0,0 +1,138 @@
+'use strict';
+
+var chunkT5WRA76K_cjs = require('./chunk-T5WRA76K.cjs');
+var chunkE6TERL5O_cjs = require('./chunk-E6TERL5O.cjs');
+var chunkWJH6IYU2_cjs = require('./chunk-WJH6IYU2.cjs');
+var chunkEE6CPXKH_cjs = require('./chunk-EE6CPXKH.cjs');
+require('./chunk-ESLWRGAG.cjs');
+require('./chunk-YREV3LGG.cjs');
+var api = require('@opentelemetry/api');
+
+var mismatchCounter;
+function counter() {
+  if (!mismatchCounter) {
+    mismatchCounter = chunkWJH6IYU2_cjs.createCounter(chunkT5WRA76K_cjs.VALIDATION_METRICS.mismatches, {
+      description: "Input payloads that did not match their declared shape"
+    });
+  }
+  return mismatchCounter;
+}
+var listeners = /* @__PURE__ */ new Set();
+function onValidationMismatch(handler) {
+  listeners.add(handler);
+  return () => {
+    listeners.delete(handler);
+  };
+}
+var truncate = (values) => values.slice(0, chunkT5WRA76K_cjs.VALIDATION_ISSUE_CAP).join(",");
+function recordValidationMismatch(mismatch) {
+  try {
+    const paths = mismatch.issues.map((i) => i.path).filter(Boolean);
+    const codes = [...new Set(mismatch.issues.map((i) => i.code))];
+    const span = api.trace.getActiveSpan();
+    if (span) {
+      span.setAttributes({
+        [chunkT5WRA76K_cjs.VALIDATION_ATTR.name]: mismatch.name,
+        [chunkT5WRA76K_cjs.VALIDATION_ATTR.boundary]: mismatch.boundary,
+        [chunkT5WRA76K_cjs.VALIDATION_ATTR.mode]: mismatch.mode,
+        [chunkT5WRA76K_cjs.VALIDATION_ATTR.issueCount]: mismatch.issues.length,
+        [chunkT5WRA76K_cjs.VALIDATION_ATTR.issuePaths]: truncate(paths),
+        [chunkT5WRA76K_cjs.VALIDATION_ATTR.issueCodes]: truncate(codes),
+        ...mismatch.hash ? { [chunkT5WRA76K_cjs.VALIDATION_ATTR.hash]: mismatch.hash } : {},
+        ...mismatch.severity ? { [chunkT5WRA76K_cjs.VALIDATION_ATTR.severity]: mismatch.severity } : {}
+      });
+    }
+    try {
+      counter().add(1, {
+        boundary: mismatch.boundary,
+        validation: mismatch.name,
+        mode: mismatch.mode
+      });
+    } catch {
+    }
+    for (const listener of listeners) {
+      try {
+        listener(mismatch);
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+function formatValidationIssues(error) {
+  const raw = extractRawIssues(error);
+  return raw.map((issue) => toSafeIssue(issue));
+}
+function extractRawIssues(error) {
+  if (error && typeof error === "object") {
+    const candidate = error.issues ?? error.errors;
+    if (Array.isArray(candidate)) {
+      return candidate.filter(
+        (i) => i !== null && typeof i === "object"
+      );
+    }
+  }
+  return [];
+}
+function toSafeIssue(issue) {
+  const rawPath = issue.path;
+  const path = Array.isArray(rawPath) ? rawPath.map(String).join(".") : typeof rawPath === "string" ? rawPath : "";
+  const code = typeof issue.code === "string" ? issue.code : "invalid";
+  const expected = typeof issue.expected === "string" ? issue.expected : void 0;
+  return expected ? { path, code, expected } : { path, code };
+}
+function defaultRejectError(issues, name) {
+  return chunkEE6CPXKH_cjs.createStructuredError({
+    name: "ValidationError",
+    status: 400,
+    code: "validation_failed",
+    message: `Input for "${name}" did not match its declared shape.`,
+    why: `${issues.length} field(s) failed validation: ${issues.map((i) => i.path || "(root)").slice(0, chunkT5WRA76K_cjs.VALIDATION_ISSUE_CAP).join(", ")}.`,
+    fix: "Send a payload that matches the schema, or switch this validator to observe mode while you investigate.",
+    // PII-safe: paths + codes only, no received values.
+    details: { validation: name, issues }
+  });
+}
+function defineValidator(name, schema, options = {}) {
+  const mode = options.onMismatch ?? "reject";
+  const boundary = options.boundary ?? "input";
+  const hash = options.toJsonSchema ? chunkE6TERL5O_cjs.hashJson(options.toJsonSchema(schema)) : void 0;
+  const record = (issues) => {
+    recordValidationMismatch({
+      name,
+      boundary,
+      mode,
+      issues,
+      hash,
+      severity: options.severity
+    });
+  };
+  return {
+    name,
+    mode,
+    safeParse(input) {
+      const parsed = schema.safeParse(input);
+      if (parsed.success) return { success: true, data: parsed.data };
+      const issues = formatValidationIssues(parsed.error);
+      record(issues);
+      return { success: false, issues };
+    },
+    parse(input) {
+      const parsed = schema.safeParse(input);
+      if (parsed.success) return parsed.data;
+      const issues = formatValidationIssues(parsed.error);
+      record(issues);
+      if (mode === "reject") {
+        throw options.onReject?.(issues, name) ?? defaultRejectError(issues, name);
+      }
+      return input;
+    }
+  };
+}
+
+exports.defineValidator = defineValidator;
+exports.formatValidationIssues = formatValidationIssues;
+exports.onValidationMismatch = onValidationMismatch;
+exports.recordValidationMismatch = recordValidationMismatch;
+//# sourceMappingURL=validate.cjs.map
+//# sourceMappingURL=validate.cjs.map

package/dist/validate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/validate.ts"],"names":["createCounter","VALIDATION_METRICS","VALIDATION_ISSUE_CAP","trace","VALIDATION_ATTR","createStructuredError","hashJson"],"mappings":"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","file":"validate.cjs","sourcesContent":["/**\n * Validation telemetry — connect runtime input validation (Zod or any\n * `safeParse` schema) to your traces and metrics at the boundaries where bad\n * data actually enters: HTTP bodies, events, messages.\n *\n * Today a `safeParse` failure either throws (no span, no metric, no alert) or\n * is silently swallowed in a handler. `defineValidator` makes the mismatch\n * **observable** — a `validation.*` span attribute set and a counter\n * incremented — with a per-validator `observe` vs `reject` mode:\n *\n * - `reject` (default): record telemetry, then throw a structured 400-shaped\n *   error so the boundary can fail cleanly.\n * - `observe`: record telemetry, return the raw input so the handler continues\n *   — useful for measuring real-world drift before you enforce it.\n *\n * **Not a security feature by default.** A malformed body is usually a bug or\n * version skew, not an attack. Validation telemetry is first-class on its own\n * metric; escalation to the security path is a deliberate opt-in via\n * {@link onValidationMismatch} (e.g. wired by `autotel-audit`), never automatic.\n *\n * **PII-safe by construction.** Only field *paths*, issue *codes*, and the\n * declared *type* are ever recorded — never the offending value, and never a\n * validator's error `message` (which routinely embeds the received value).\n */\n\nimport { trace } from '@opentelemetry/api';\nimport { createCounter } from './metric-helpers';\nimport { createStructuredError, type StructuredError } from './structured-error';\nimport { hashJson } from './stable-hash';\nimport type { SchemaLike } from './define-event';\nimport {\n  VALIDATION_ATTR,\n  VALIDATION_ISSUE_CAP,\n  VALIDATION_METRICS,\n} from './validation-attributes';\n\nexport type { SchemaLike } from './define-event';\n\nexport type ValidationMode = 'observe' | 'reject';\nexport type ValidationSeverity = 'info' | 'warning' | 'error';\n\n/** A single failing field, stripped of any payload values. */\nexport interface ValidationIssue {\n  /** Dotted field path, e.g. `items.0.price`. Never a value. */\n  path: string;\n  /** Issue code (e.g. Zod's `invalid_type`, `too_small`). Never a value. */\n  code: string;\n  /** Declared type/constraint summary, e.g. `string`. Never a received value. */\n  expected?: string;\n}\n\n/** Everything the recorder needs — already PII-stripped by the caller. */\nexport interface ValidationMismatch {\n  /** Contract id, e.g. `POST /orders` or `order.placed`. */\n  name: string;\n  boundary: string;\n  mode: ValidationMode;\n  issues: ValidationIssue[];\n  hash?: string;\n  severity?: ValidationSeverity;\n}\n\nlet mismatchCounter: ReturnType<typeof createCounter> | undefined;\nfunction counter(): ReturnType<typeof createCounter> {\n  if (!mismatchCounter) {\n    mismatchCounter = createCounter(VALIDATION_METRICS.mismatches, {\n      description: 'Input payloads that did not match their declared shape',\n    });\n  }\n  return mismatchCounter;\n}\n\ntype MismatchListener = (mismatch: ValidationMismatch) => void;\nconst listeners = new Set<MismatchListener>();\n\n/**\n * Register an explicit handler called on every recorded mismatch — the opt-in\n * seam for escalating to security events, a webhook, or a custom sink. There is\n * no automatic, package-presence-driven escalation: nothing fires here unless\n * you (or a package you wire up) register a handler.\n *\n * Multiple subscribers coexist: a package (e.g. `autotel-audit` bridging to\n * security events) and your own app code (a webhook, a logger) can both\n * register and all fire. Returns an unsubscribe fn that removes only this\n * handler; registering the same function twice is a no-op (Set semantics).\n */\nexport function onValidationMismatch(handler: MismatchListener): () => void {\n  listeners.add(handler);\n  return () => {\n    listeners.delete(handler);\n  };\n}\n\nconst truncate = (values: string[]): string =>\n  values.slice(0, VALIDATION_ISSUE_CAP).join(',');\n\n/**\n * Record a validation mismatch as telemetry: `validation.*` attributes on the\n * active span (if any) and an increment on `autotel.validation.mismatches`.\n * Fail-open — never throws, so instrumentation can't break the boundary.\n */\nexport function recordValidationMismatch(mismatch: ValidationMismatch): void {\n  try {\n    const paths = mismatch.issues.map((i) => i.path).filter(Boolean);\n    const codes = [...new Set(mismatch.issues.map((i) => i.code))];\n\n    const span = trace.getActiveSpan();\n    if (span) {\n      span.setAttributes({\n        [VALIDATION_ATTR.name]: mismatch.name,\n        [VALIDATION_ATTR.boundary]: mismatch.boundary,\n        [VALIDATION_ATTR.mode]: mismatch.mode,\n        [VALIDATION_ATTR.issueCount]: mismatch.issues.length,\n        [VALIDATION_ATTR.issuePaths]: truncate(paths),\n        [VALIDATION_ATTR.issueCodes]: truncate(codes),\n        ...(mismatch.hash ? { [VALIDATION_ATTR.hash]: mismatch.hash } : {}),\n        ...(mismatch.severity\n          ? { [VALIDATION_ATTR.severity]: mismatch.severity }\n          : {}),\n      });\n    }\n\n    try {\n      counter().add(1, {\n        boundary: mismatch.boundary,\n        validation: mismatch.name,\n        mode: mismatch.mode,\n      });\n    } catch {\n      // meter not initialised yet — skip the count, keep the span attrs\n    }\n\n    // Dispatch to every subscriber with per-listener fault isolation: one\n    // throwing subscriber must not starve its peers or break the boundary.\n    // Set iteration tolerates concurrent (un)subscription safely.\n    for (const listener of listeners) {\n      try {\n        listener(mismatch);\n      } catch {\n        // a misbehaving subscriber must not break the boundary or its peers\n      }\n    }\n  } catch {\n    // fail-open: telemetry must never break the validated boundary\n  }\n}\n\n/**\n * Normalise an arbitrary validation error into PII-safe issues. Reads only\n * `path`, `code`, and (when it is a declared type name) `expected` — and never\n * `message`, `received`, or any value-bearing field. Understands the Zod shape\n * (`error.issues`) and a generic `error.errors` fallback; returns `[]` for\n * anything unrecognised.\n */\nexport function formatValidationIssues(error: unknown): ValidationIssue[] {\n  const raw = extractRawIssues(error);\n  return raw.map((issue) => toSafeIssue(issue));\n}\n\nfunction extractRawIssues(error: unknown): Array<Record<string, unknown>> {\n  if (error && typeof error === 'object') {\n    const candidate =\n      (error as { issues?: unknown }).issues ??\n      (error as { errors?: unknown }).errors;\n    if (Array.isArray(candidate)) {\n      return candidate.filter(\n        (i): i is Record<string, unknown> => i !== null && typeof i === 'object',\n      );\n    }\n  }\n  return [];\n}\n\nfunction toSafeIssue(issue: Record<string, unknown>): ValidationIssue {\n  const rawPath = issue.path;\n  const path = Array.isArray(rawPath)\n    ? rawPath.map(String).join('.')\n    : typeof rawPath === 'string'\n      ? rawPath\n      : '';\n  const code = typeof issue.code === 'string' ? issue.code : 'invalid';\n  // `expected` is a declared type name in Zod (e.g. 'string'); safe. We never\n  // read `received`/`message`/`value`, which can carry the offending payload.\n  const expected =\n    typeof issue.expected === 'string' ? issue.expected : undefined;\n  return expected ? { path, code, expected } : { path, code };\n}\n\nexport interface DefineValidatorOptions<S> {\n  /** Where validation runs. Defaults to `input`. */\n  boundary?: string;\n  /** `reject` (default): record then throw. `observe`: record then continue. */\n  onMismatch?: ValidationMode;\n  /** Project the schema to JSON Schema for a stable `validation.hash`. */\n  toJsonSchema?: (schema: S) => unknown;\n  severity?: ValidationSeverity;\n  /** Build the error thrown in `reject` mode (defaults to a 400 structured error). */\n  onReject?: (issues: ValidationIssue[], name: string) => Error;\n}\n\nexport type ValidatorResult<T> =\n  | { success: true; data: T }\n  | { success: false; issues: ValidationIssue[] };\n\nexport interface Validator<T> {\n  readonly name: string;\n  readonly mode: ValidationMode;\n  /** Validate and record on failure; never throws. */\n  safeParse(input: unknown): ValidatorResult<T>;\n  /**\n   * Validate, record on failure, then apply the mode: `reject` throws,\n   * `observe` returns the raw input so the handler can continue.\n   */\n  parse(input: unknown): T;\n}\n\nfunction defaultRejectError(\n  issues: ValidationIssue[],\n  name: string,\n): StructuredError {\n  return createStructuredError({\n    name: 'ValidationError',\n    status: 400,\n    code: 'validation_failed',\n    message: `Input for \"${name}\" did not match its declared shape.`,\n    why: `${issues.length} field(s) failed validation: ${issues\n      .map((i) => i.path || '(root)')\n      .slice(0, VALIDATION_ISSUE_CAP)\n      .join(', ')}.`,\n    fix: 'Send a payload that matches the schema, or switch this validator to observe mode while you investigate.',\n    // PII-safe: paths + codes only, no received values.\n    details: { validation: name, issues },\n  });\n}\n\n/**\n * Declare an expected input shape once and get a validator that records every\n * mismatch as telemetry.\n *\n * @example\n * ```ts\n * import { z } from 'zod';\n * import { defineValidator } from 'autotel/validate';\n *\n * const OrderBody = defineValidator('POST /orders', z.object({\n *   items: z.array(z.object({ sku: z.string(), qty: z.number().int() })),\n * }), { boundary: 'http', toJsonSchema: (s) => z.toJSONSchema(s) });\n *\n * // reject mode (default): records + throws a 400-shaped structured error\n * const order = OrderBody.parse(req.body);\n *\n * // observe mode: records, returns the result, never throws\n * const result = OrderBody.safeParse(req.body);\n * if (!result.success) metrics.onDrift(result.issues);\n * ```\n */\nexport function defineValidator<T, S extends SchemaLike<T>>(\n  name: string,\n  schema: S,\n  options: DefineValidatorOptions<S> = {},\n): Validator<T> {\n  const mode = options.onMismatch ?? 'reject';\n  const boundary = options.boundary ?? 'input';\n  const hash = options.toJsonSchema\n    ? hashJson(options.toJsonSchema(schema))\n    : undefined;\n\n  const record = (issues: ValidationIssue[]): void => {\n    recordValidationMismatch({\n      name,\n      boundary,\n      mode,\n      issues,\n      hash,\n      severity: options.severity,\n    });\n  };\n\n  return {\n    name,\n    mode,\n    safeParse(input: unknown): ValidatorResult<T> {\n      const parsed = schema.safeParse(input);\n      if (parsed.success) return { success: true, data: parsed.data };\n      const issues = formatValidationIssues(parsed.error);\n      record(issues);\n      return { success: false, issues };\n    },\n    parse(input: unknown): T {\n      const parsed = schema.safeParse(input);\n      if (parsed.success) return parsed.data;\n      const issues = formatValidationIssues(parsed.error);\n      record(issues);\n      if (mode === 'reject') {\n        throw options.onReject?.(issues, name) ?? defaultRejectError(issues, name);\n      }\n      // observe: continue with the raw input (documented type caveat)\n      return input as T;\n    },\n  };\n}\n"]}

package/dist/validate.d.cts

@@ -0,0 +1,129 @@
+import { S as SchemaLike } from './define-event-ClP3T1Jx.cjs';
+import './event-subscriber.cjs';
+
+/**
+ * Validation telemetry — connect runtime input validation (Zod or any
+ * `safeParse` schema) to your traces and metrics at the boundaries where bad
+ * data actually enters: HTTP bodies, events, messages.
+ *
+ * Today a `safeParse` failure either throws (no span, no metric, no alert) or
+ * is silently swallowed in a handler. `defineValidator` makes the mismatch
+ * **observable** — a `validation.*` span attribute set and a counter
+ * incremented — with a per-validator `observe` vs `reject` mode:
+ *
+ * - `reject` (default): record telemetry, then throw a structured 400-shaped
+ *   error so the boundary can fail cleanly.
+ * - `observe`: record telemetry, return the raw input so the handler continues
+ *   — useful for measuring real-world drift before you enforce it.
+ *
+ * **Not a security feature by default.** A malformed body is usually a bug or
+ * version skew, not an attack. Validation telemetry is first-class on its own
+ * metric; escalation to the security path is a deliberate opt-in via
+ * {@link onValidationMismatch} (e.g. wired by `autotel-audit`), never automatic.
+ *
+ * **PII-safe by construction.** Only field *paths*, issue *codes*, and the
+ * declared *type* are ever recorded — never the offending value, and never a
+ * validator's error `message` (which routinely embeds the received value).
+ */
+
+type ValidationMode = 'observe' | 'reject';
+type ValidationSeverity = 'info' | 'warning' | 'error';
+/** A single failing field, stripped of any payload values. */
+interface ValidationIssue {
+    /** Dotted field path, e.g. `items.0.price`. Never a value. */
+    path: string;
+    /** Issue code (e.g. Zod's `invalid_type`, `too_small`). Never a value. */
+    code: string;
+    /** Declared type/constraint summary, e.g. `string`. Never a received value. */
+    expected?: string;
+}
+/** Everything the recorder needs — already PII-stripped by the caller. */
+interface ValidationMismatch {
+    /** Contract id, e.g. `POST /orders` or `order.placed`. */
+    name: string;
+    boundary: string;
+    mode: ValidationMode;
+    issues: ValidationIssue[];
+    hash?: string;
+    severity?: ValidationSeverity;
+}
+type MismatchListener = (mismatch: ValidationMismatch) => void;
+/**
+ * Register an explicit handler called on every recorded mismatch — the opt-in
+ * seam for escalating to security events, a webhook, or a custom sink. There is
+ * no automatic, package-presence-driven escalation: nothing fires here unless
+ * you (or a package you wire up) register a handler.
+ *
+ * Multiple subscribers coexist: a package (e.g. `autotel-audit` bridging to
+ * security events) and your own app code (a webhook, a logger) can both
+ * register and all fire. Returns an unsubscribe fn that removes only this
+ * handler; registering the same function twice is a no-op (Set semantics).
+ */
+declare function onValidationMismatch(handler: MismatchListener): () => void;
+/**
+ * Record a validation mismatch as telemetry: `validation.*` attributes on the
+ * active span (if any) and an increment on `autotel.validation.mismatches`.
+ * Fail-open — never throws, so instrumentation can't break the boundary.
+ */
+declare function recordValidationMismatch(mismatch: ValidationMismatch): void;
+/**
+ * Normalise an arbitrary validation error into PII-safe issues. Reads only
+ * `path`, `code`, and (when it is a declared type name) `expected` — and never
+ * `message`, `received`, or any value-bearing field. Understands the Zod shape
+ * (`error.issues`) and a generic `error.errors` fallback; returns `[]` for
+ * anything unrecognised.
+ */
+declare function formatValidationIssues(error: unknown): ValidationIssue[];
+interface DefineValidatorOptions<S> {
+    /** Where validation runs. Defaults to `input`. */
+    boundary?: string;
+    /** `reject` (default): record then throw. `observe`: record then continue. */
+    onMismatch?: ValidationMode;
+    /** Project the schema to JSON Schema for a stable `validation.hash`. */
+    toJsonSchema?: (schema: S) => unknown;
+    severity?: ValidationSeverity;
+    /** Build the error thrown in `reject` mode (defaults to a 400 structured error). */
+    onReject?: (issues: ValidationIssue[], name: string) => Error;
+}
+type ValidatorResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    issues: ValidationIssue[];
+};
+interface Validator<T> {
+    readonly name: string;
+    readonly mode: ValidationMode;
+    /** Validate and record on failure; never throws. */
+    safeParse(input: unknown): ValidatorResult<T>;
+    /**
+     * Validate, record on failure, then apply the mode: `reject` throws,
+     * `observe` returns the raw input so the handler can continue.
+     */
+    parse(input: unknown): T;
+}
+/**
+ * Declare an expected input shape once and get a validator that records every
+ * mismatch as telemetry.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { defineValidator } from 'autotel/validate';
+ *
+ * const OrderBody = defineValidator('POST /orders', z.object({
+ *   items: z.array(z.object({ sku: z.string(), qty: z.number().int() })),
+ * }), { boundary: 'http', toJsonSchema: (s) => z.toJSONSchema(s) });
+ *
+ * // reject mode (default): records + throws a 400-shaped structured error
+ * const order = OrderBody.parse(req.body);
+ *
+ * // observe mode: records, returns the result, never throws
+ * const result = OrderBody.safeParse(req.body);
+ * if (!result.success) metrics.onDrift(result.issues);
+ * ```
+ */
+declare function defineValidator<T, S extends SchemaLike<T>>(name: string, schema: S, options?: DefineValidatorOptions<S>): Validator<T>;
+
+export { type DefineValidatorOptions, SchemaLike, type ValidationIssue, type ValidationMismatch, type ValidationMode, type ValidationSeverity, type Validator, type ValidatorResult, defineValidator, formatValidationIssues, onValidationMismatch, recordValidationMismatch };

package/dist/validate.d.ts

@@ -0,0 +1,129 @@
+import { S as SchemaLike } from './define-event-BL6Li7CM.js';
+import './event-subscriber.js';
+
+/**
+ * Validation telemetry — connect runtime input validation (Zod or any
+ * `safeParse` schema) to your traces and metrics at the boundaries where bad
+ * data actually enters: HTTP bodies, events, messages.
+ *
+ * Today a `safeParse` failure either throws (no span, no metric, no alert) or
+ * is silently swallowed in a handler. `defineValidator` makes the mismatch
+ * **observable** — a `validation.*` span attribute set and a counter
+ * incremented — with a per-validator `observe` vs `reject` mode:
+ *
+ * - `reject` (default): record telemetry, then throw a structured 400-shaped
+ *   error so the boundary can fail cleanly.
+ * - `observe`: record telemetry, return the raw input so the handler continues
+ *   — useful for measuring real-world drift before you enforce it.
+ *
+ * **Not a security feature by default.** A malformed body is usually a bug or
+ * version skew, not an attack. Validation telemetry is first-class on its own
+ * metric; escalation to the security path is a deliberate opt-in via
+ * {@link onValidationMismatch} (e.g. wired by `autotel-audit`), never automatic.
+ *
+ * **PII-safe by construction.** Only field *paths*, issue *codes*, and the
+ * declared *type* are ever recorded — never the offending value, and never a
+ * validator's error `message` (which routinely embeds the received value).
+ */
+
+type ValidationMode = 'observe' | 'reject';
+type ValidationSeverity = 'info' | 'warning' | 'error';
+/** A single failing field, stripped of any payload values. */
+interface ValidationIssue {
+    /** Dotted field path, e.g. `items.0.price`. Never a value. */
+    path: string;
+    /** Issue code (e.g. Zod's `invalid_type`, `too_small`). Never a value. */
+    code: string;
+    /** Declared type/constraint summary, e.g. `string`. Never a received value. */
+    expected?: string;
+}
+/** Everything the recorder needs — already PII-stripped by the caller. */
+interface ValidationMismatch {
+    /** Contract id, e.g. `POST /orders` or `order.placed`. */
+    name: string;
+    boundary: string;
+    mode: ValidationMode;
+    issues: ValidationIssue[];
+    hash?: string;
+    severity?: ValidationSeverity;
+}
+type MismatchListener = (mismatch: ValidationMismatch) => void;
+/**
+ * Register an explicit handler called on every recorded mismatch — the opt-in
+ * seam for escalating to security events, a webhook, or a custom sink. There is
+ * no automatic, package-presence-driven escalation: nothing fires here unless
+ * you (or a package you wire up) register a handler.
+ *
+ * Multiple subscribers coexist: a package (e.g. `autotel-audit` bridging to
+ * security events) and your own app code (a webhook, a logger) can both
+ * register and all fire. Returns an unsubscribe fn that removes only this
+ * handler; registering the same function twice is a no-op (Set semantics).
+ */
+declare function onValidationMismatch(handler: MismatchListener): () => void;
+/**
+ * Record a validation mismatch as telemetry: `validation.*` attributes on the
+ * active span (if any) and an increment on `autotel.validation.mismatches`.
+ * Fail-open — never throws, so instrumentation can't break the boundary.
+ */
+declare function recordValidationMismatch(mismatch: ValidationMismatch): void;
+/**
+ * Normalise an arbitrary validation error into PII-safe issues. Reads only
+ * `path`, `code`, and (when it is a declared type name) `expected` — and never
+ * `message`, `received`, or any value-bearing field. Understands the Zod shape
+ * (`error.issues`) and a generic `error.errors` fallback; returns `[]` for
+ * anything unrecognised.
+ */
+declare function formatValidationIssues(error: unknown): ValidationIssue[];
+interface DefineValidatorOptions<S> {
+    /** Where validation runs. Defaults to `input`. */
+    boundary?: string;
+    /** `reject` (default): record then throw. `observe`: record then continue. */
+    onMismatch?: ValidationMode;
+    /** Project the schema to JSON Schema for a stable `validation.hash`. */
+    toJsonSchema?: (schema: S) => unknown;
+    severity?: ValidationSeverity;
+    /** Build the error thrown in `reject` mode (defaults to a 400 structured error). */
+    onReject?: (issues: ValidationIssue[], name: string) => Error;
+}
+type ValidatorResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    issues: ValidationIssue[];
+};
+interface Validator<T> {
+    readonly name: string;
+    readonly mode: ValidationMode;
+    /** Validate and record on failure; never throws. */
+    safeParse(input: unknown): ValidatorResult<T>;
+    /**
+     * Validate, record on failure, then apply the mode: `reject` throws,
+     * `observe` returns the raw input so the handler can continue.
+     */
+    parse(input: unknown): T;
+}
+/**
+ * Declare an expected input shape once and get a validator that records every
+ * mismatch as telemetry.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { defineValidator } from 'autotel/validate';
+ *
+ * const OrderBody = defineValidator('POST /orders', z.object({
+ *   items: z.array(z.object({ sku: z.string(), qty: z.number().int() })),
+ * }), { boundary: 'http', toJsonSchema: (s) => z.toJSONSchema(s) });
+ *
+ * // reject mode (default): records + throws a 400-shaped structured error
+ * const order = OrderBody.parse(req.body);
+ *
+ * // observe mode: records, returns the result, never throws
+ * const result = OrderBody.safeParse(req.body);
+ * if (!result.success) metrics.onDrift(result.issues);
+ * ```
+ */
+declare function defineValidator<T, S extends SchemaLike<T>>(name: string, schema: S, options?: DefineValidatorOptions<S>): Validator<T>;
+
+export { type DefineValidatorOptions, SchemaLike, type ValidationIssue, type ValidationMismatch, type ValidationMode, type ValidationSeverity, type Validator, type ValidatorResult, defineValidator, formatValidationIssues, onValidationMismatch, recordValidationMismatch };