autotel 4.0.0 → 4.2.0

package/src/validate.ts

@@ -1,307 +0,0 @@
-/**
- * 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).
- */
-
-import { trace } from '@opentelemetry/api';
-import { createCounter } from './metric-helpers';
-import {
-  createStructuredError,
-  type StructuredError,
-} from './structured-error';
-import { hashJson } from './stable-hash';
-import type { SchemaLike } from './define-event';
-import {
-  VALIDATION_ATTR,
-  VALIDATION_ISSUE_CAP,
-  VALIDATION_METRICS,
-} from './validation-attributes';
-
-export type { SchemaLike } from './define-event';
-
-export type ValidationMode = 'observe' | 'reject';
-export type ValidationSeverity = 'info' | 'warning' | 'error';
-
-/** A single failing field, stripped of any payload values. */
-export 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. */
-export interface ValidationMismatch {
-  /** Contract id, e.g. `POST /orders` or `order.placed`. */
-  name: string;
-  boundary: string;
-  mode: ValidationMode;
-  issues: ValidationIssue[];
-  hash?: string;
-  severity?: ValidationSeverity;
-}
-
-let mismatchCounter: ReturnType<typeof createCounter> | undefined;
-function counter(): ReturnType<typeof createCounter> {
-  if (!mismatchCounter) {
-    mismatchCounter = createCounter(VALIDATION_METRICS.mismatches, {
-      description: 'Input payloads that did not match their declared shape',
-    });
-  }
-  return mismatchCounter;
-}
-
-type MismatchListener = (mismatch: ValidationMismatch) => void;
-const listeners = new Set<MismatchListener>();
-
-/**
- * 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).
- */
-export function onValidationMismatch(handler: MismatchListener): () => void {
-  listeners.add(handler);
-  return () => {
-    listeners.delete(handler);
-  };
-}
-
-const truncate = (values: string[]): string =>
-  values.slice(0, VALIDATION_ISSUE_CAP).join(',');
-
-/**
- * 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.
- */
-export function recordValidationMismatch(mismatch: ValidationMismatch): void {
-  try {
-    const paths = mismatch.issues.map((i) => i.path).filter(Boolean);
-    const codes = [...new Set(mismatch.issues.map((i) => i.code))];
-
-    const span = trace.getActiveSpan();
-    if (span) {
-      span.setAttributes({
-        [VALIDATION_ATTR.name]: mismatch.name,
-        [VALIDATION_ATTR.boundary]: mismatch.boundary,
-        [VALIDATION_ATTR.mode]: mismatch.mode,
-        [VALIDATION_ATTR.issueCount]: mismatch.issues.length,
-        [VALIDATION_ATTR.issuePaths]: truncate(paths),
-        [VALIDATION_ATTR.issueCodes]: truncate(codes),
-        ...(mismatch.hash ? { [VALIDATION_ATTR.hash]: mismatch.hash } : {}),
-        ...(mismatch.severity
-          ? { [VALIDATION_ATTR.severity]: mismatch.severity }
-          : {}),
-      });
-    }
-
-    try {
-      counter().add(1, {
-        boundary: mismatch.boundary,
-        validation: mismatch.name,
-        mode: mismatch.mode,
-      });
-    } catch {
-      // meter not initialised yet — skip the count, keep the span attrs
-    }
-
-    // Dispatch to every subscriber with per-listener fault isolation: one
-    // throwing subscriber must not starve its peers or break the boundary.
-    // Set iteration tolerates concurrent (un)subscription safely.
-    for (const listener of listeners) {
-      try {
-        listener(mismatch);
-      } catch {
-        // a misbehaving subscriber must not break the boundary or its peers
-      }
-    }
-  } catch {
-    // fail-open: telemetry must never break the validated boundary
-  }
-}
-
-/**
- * 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.
- */
-export function formatValidationIssues(error: unknown): ValidationIssue[] {
-  const raw = extractRawIssues(error);
-  return raw.map((issue) => toSafeIssue(issue));
-}
-
-function extractRawIssues(error: unknown): Array<Record<string, unknown>> {
-  if (error && typeof error === 'object') {
-    const candidate =
-      (error as { issues?: unknown }).issues ??
-      (error as { errors?: unknown }).errors;
-    if (Array.isArray(candidate)) {
-      return candidate.filter(
-        (i): i is Record<string, unknown> =>
-          i !== null && typeof i === 'object',
-      );
-    }
-  }
-  return [];
-}
-
-function toSafeIssue(issue: Record<string, unknown>): ValidationIssue {
-  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';
-  // `expected` is a declared type name in Zod (e.g. 'string'); safe. We never
-  // read `received`/`message`/`value`, which can carry the offending payload.
-  const expected =
-    typeof issue.expected === 'string' ? issue.expected : undefined;
-  return expected ? { path, code, expected } : { path, code };
-}
-
-export 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;
-}
-
-export type ValidatorResult<T> =
-  | { success: true; data: T }
-  | { success: false; issues: ValidationIssue[] };
-
-export 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;
-}
-
-function defaultRejectError(
-  issues: ValidationIssue[],
-  name: string,
-): StructuredError {
-  return 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, 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 },
-  });
-}
-
-/**
- * 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);
- * ```
- */
-export function defineValidator<T, S extends SchemaLike<T>>(
-  name: string,
-  schema: S,
-  options: DefineValidatorOptions<S> = {},
-): Validator<T> {
-  const mode = options.onMismatch ?? 'reject';
-  const boundary = options.boundary ?? 'input';
-  const hash = options.toJsonSchema
-    ? hashJson(options.toJsonSchema(schema))
-    : undefined;
-
-  const record = (issues: ValidationIssue[]): void => {
-    recordValidationMismatch({
-      name,
-      boundary,
-      mode,
-      issues,
-      hash,
-      severity: options.severity,
-    });
-  };
-
-  return {
-    name,
-    mode,
-    safeParse(input: unknown): ValidatorResult<T> {
-      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: unknown): T {
-      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)
-        );
-      }
-      // observe: continue with the raw input (documented type caveat)
-      return input as T;
-    },
-  };
-}

package/src/validation-attributes.ts

@@ -1,43 +0,0 @@
-/**
- * Validation telemetry wire constants — the single source of truth for the
- * `validation.*` span attributes and the `autotel.validation.mismatches` metric
- * emitted when an input payload (HTTP body, event, message) fails to match its
- * declared shape.
- *
- * Dependency-free and side-effect-free by design (mirrors `security-schema.ts`):
- * safe to import from anything that only needs the constant strings — a
- * dashboard, a CLI, an alert rule — without pulling in the OpenTelemetry SDK.
- *
- * These keys are a public API for the agents that query your telemetry. Treat a
- * rename here the way you'd treat a breaking change to any other contract.
- */
-
-export const VALIDATION_ATTR = {
-  /** Contract id of the validated boundary, e.g. `POST /orders`, `order.placed`. */
-  name: 'validation.name',
-  /** Where validation ran: `http` | `event` | `message` | a custom label. */
-  boundary: 'validation.boundary',
-  /** `observe` (recorded, request continues) or `reject` (recorded, then failed). */
-  mode: 'validation.mode',
-  /** Stable hash of the declared shape, when a JSON-schema projection is given. */
-  hash: 'validation.hash',
-  /** `info` | `warning` | `error`. */
-  severity: 'validation.severity',
-  /** Number of failing fields. */
-  issueCount: 'validation.issue.count',
-  /** Comma-separated failing field paths (capped). Never contains values. */
-  issuePaths: 'validation.issue.paths',
-  /** Comma-separated distinct issue codes (capped). Never contains values. */
-  issueCodes: 'validation.issue.codes',
-} as const;
-
-export type ValidationAttributeKey =
-  (typeof VALIDATION_ATTR)[keyof typeof VALIDATION_ATTR];
-
-export const VALIDATION_METRICS = {
-  /** Counter, labelled `{ boundary, validation, mode }`. */
-  mismatches: 'autotel.validation.mismatches',
-} as const;
-
-/** Max field paths / codes stamped onto a span, to bound attribute size. */
-export const VALIDATION_ISSUE_CAP = 20;

package/src/validation.test.ts

@@ -1,330 +0,0 @@
-/**
- * Tests for input validation
- */
-
-import { describe, it, expect } from 'vitest';
-import {
-  validateEventName,
-  validateAttributes,
-  validateEvent,
-  ValidationError,
-  getDefaultValidationConfig,
-} from './validation';
-
-describe('validateEventName()', () => {
-  it('should accept valid event names', () => {
-    expect(validateEventName('user.signup')).toBe('user.signup');
-    expect(validateEventName('order_completed')).toBe('order_completed');
-    expect(validateEventName('feature-used')).toBe('feature-used');
-    expect(validateEventName('app123.event456')).toBe('app123.event456');
-  });
-
-  it('should trim whitespace', () => {
-    expect(validateEventName('  user.signup  ')).toBe('user.signup');
-  });
-
-  it('should reject empty event names', () => {
-    expect(() => validateEventName('')).toThrow(ValidationError);
-    expect(() => validateEventName('   ')).toThrow(ValidationError);
-  });
-
-  it('should reject non-string event names', () => {
-    expect(() => validateEventName(123 as any)).toThrow(ValidationError);
-
-    expect(() => validateEventName(null as any)).toThrow(ValidationError);
-
-    expect(() => validateEventName(undefined as any)).toThrow(ValidationError);
-  });
-
-  it('should reject event names that are too long', () => {
-    const longName = 'a'.repeat(101);
-    expect(() => validateEventName(longName)).toThrow(ValidationError);
-  });
-
-  it('should reject event names with invalid characters', () => {
-    expect(() => validateEventName('user signup')).toThrow(ValidationError);
-    expect(() => validateEventName('user@signup')).toThrow(ValidationError);
-    expect(() => validateEventName('user/signup')).toThrow(ValidationError);
-    expect(() => validateEventName(String.raw`user\signup`)).toThrow(
-      ValidationError,
-    );
-  });
-});
-
-describe('validateAttributes()', () => {
-  it('should accept valid attributes', () => {
-    const attrs = {
-      userId: '123',
-      plan: 'pro',
-      count: 5,
-      active: true,
-    };
-
-    expect(validateAttributes(attrs)).toEqual(attrs);
-  });
-
-  it('should handle undefined attributes', () => {
-    // eslint-disable-next-line unicorn/no-useless-undefined
-    expect(validateAttributes(undefined)).toBeUndefined();
-  });
-
-  it('should reject non-object attributes', () => {
-    expect(() => validateAttributes('string' as any)).toThrow(ValidationError);
-
-    expect(() => validateAttributes(123 as any)).toThrow(ValidationError);
-
-    expect(() => validateAttributes([] as any)).toThrow(ValidationError);
-  });
-
-  it('should reject too many attributes', () => {
-    const config = getDefaultValidationConfig();
-    const attrs: Record<string, unknown> = {};
-    for (let i = 0; i < config.maxAttributeCount + 1; i++) {
-      attrs[`key${i}`] = 'value';
-    }
-
-    expect(() =>
-      validateAttributes(attrs as Record<string, string | number | boolean>),
-    ).toThrow(ValidationError);
-  });
-
-  it('should reject attribute keys that are too long', () => {
-    const longKey = 'a'.repeat(101);
-    const attrs = { [longKey]: 'value' };
-
-    expect(() => validateAttributes(attrs)).toThrow(ValidationError);
-  });
-
-  it('should truncate long string values', () => {
-    const longValue = 'a'.repeat(1500);
-    const attrs = { field: longValue };
-
-    const result = validateAttributes(attrs);
-    expect(result?.field).toBe('a'.repeat(1000) + '...');
-  });
-
-  it('should redact sensitive fields', () => {
-    const attrs = {
-      email: 'user@example.com',
-      password: 'secret123',
-      apiKey: 'abc123',
-      normalField: 'value',
-    };
-
-    const result = validateAttributes(attrs);
-    expect(result?.email).toBe('user@example.com');
-    expect(result?.password).toBe('[REDACTED]');
-    expect(result?.apiKey).toBe('[REDACTED]');
-    expect(result?.normalField).toBe('value');
-  });
-
-  it('should redact sensitive fields in nested objects', () => {
-    const attrs = {
-      user: {
-        password: 'secret123',
-        apiKey: 'abc123',
-      },
-      session: {
-        authToken: 'token-123',
-      },
-    };
-
-    const result = validateAttributes(attrs) as
-      | Record<string, Record<string, unknown>>
-      | undefined;
-
-    expect(result?.user?.password).toBe('[REDACTED]');
-    expect(result?.user?.apiKey).toBe('[REDACTED]');
-    expect(result?.session?.authToken).toBe('[REDACTED]');
-  });
-
-  it('should handle nested objects within depth limit', () => {
-    const attrs = {
-      user: {
-        profile: {
-          name: 'John',
-        },
-      },
-    };
-
-    const result = validateAttributes(
-      attrs as unknown as Record<string, string | number | boolean>,
-    );
-    expect(result).toEqual(attrs);
-  });
-
-  it('should truncate deeply nested objects', () => {
-    const attrs = {
-      level1: {
-        level2: {
-          level3: {
-            level4: {
-              tooDeep: 'value',
-            },
-          },
-        },
-      },
-    };
-
-    const result = validateAttributes(attrs as any) as any;
-    expect(result.level1.level2.level3.level4).toBe('[MAX_DEPTH_EXCEEDED]');
-  });
-
-  it('should handle arrays', () => {
-    const attrs = {
-      tags: ['tag1', 'tag2', 'tag3'],
-      scores: [1, 2, 3],
-    };
-
-    const result = validateAttributes(attrs as any);
-    expect(result).toEqual(attrs);
-  });
-
-  it('should handle circular references', () => {
-    const circular: any = { name: 'test' };
-    circular.self = circular;
-
-    const attrs = { data: circular };
-
-    const result = validateAttributes(attrs) as any;
-    expect(result.data).toBe('[CIRCULAR]');
-  });
-
-  it('should handle null and undefined values', () => {
-    const attrs = {
-      nullable: null,
-      undefinedField: undefined,
-      normalField: 'value',
-    };
-
-    const result = validateAttributes(attrs as any);
-    expect(result?.nullable).toBeNull();
-    expect(result?.undefinedField).toBeUndefined();
-    expect(result?.normalField).toBe('value');
-  });
-
-  it('should handle unsupported types', () => {
-    const attrs = {
-      func: () => {},
-      symbol: Symbol('test'),
-      normalField: 'value',
-    };
-
-    const result = validateAttributes(attrs as any);
-    expect(result?.func).toBe('[function]');
-    expect(result?.symbol).toBe('[symbol]');
-    expect(result?.normalField).toBe('value');
-  });
-});
-
-describe('validateEvent()', () => {
-  it('should validate both event name and attributes', () => {
-    const result = validateEvent('user.signup', {
-      userId: '123',
-      password: 'secret',
-    });
-
-    expect(result.eventName).toBe('user.signup');
-    expect(result.attributes?.userId).toBe('123');
-    expect(result.attributes?.password).toBe('[REDACTED]');
-  });
-
-  it('should handle events without attributes', () => {
-    const result = validateEvent('page.viewed');
-
-    expect(result.eventName).toBe('page.viewed');
-    expect(result.attributes).toBeUndefined();
-  });
-
-  it('should allow custom validation config', () => {
-    const result = validateEvent(
-      'test.event',
-      { field: 'value' },
-      { maxEventNameLength: 50 },
-    );
-
-    expect(result.eventName).toBe('test.event');
-    expect(result.attributes?.field).toBe('value');
-  });
-
-  it('should throw on invalid event name', () => {
-    expect(() => validateEvent('', { userId: '123' })).toThrow(ValidationError);
-  });
-
-  it('should throw on invalid attributes', () => {
-    expect(() => validateEvent('user.signup', 'invalid' as any)).toThrow(
-      ValidationError,
-    );
-  });
-});
-
-describe('Sensitive data patterns', () => {
-  it('should redact password fields', () => {
-    const attrs = {
-      password: 'secret',
-      userPassword: 'secret',
-      PASSWORD: 'secret',
-    };
-
-    const result = validateAttributes(attrs);
-    expect(result?.password).toBe('[REDACTED]');
-    expect(result?.userPassword).toBe('[REDACTED]');
-    expect(result?.PASSWORD).toBe('[REDACTED]');
-  });
-
-  it('should redact token fields', () => {
-    const attrs = {
-      token: 'abc123',
-      accessToken: 'abc123',
-      auth_token: 'abc123',
-    };
-
-    const result = validateAttributes(attrs);
-    expect(result?.token).toBe('[REDACTED]');
-    expect(result?.accessToken).toBe('[REDACTED]');
-    expect(result?.auth_token).toBe('[REDACTED]');
-  });
-
-  it('should redact API key fields', () => {
-    const attrs = {
-      apiKey: 'abc123',
-      api_key: 'abc123',
-      API_KEY: 'abc123',
-    };
-
-    const result = validateAttributes(attrs);
-    expect(result?.apiKey).toBe('[REDACTED]');
-    expect(result?.api_key).toBe('[REDACTED]');
-    expect(result?.API_KEY).toBe('[REDACTED]');
-  });
-
-  it('should redact auth fields (strings only)', () => {
-    const attrs = {
-      auth: 'abc123',
-      authorization: 'Bearer token',
-      // `authenticated` matches the /auth/i key pattern, but `true` is a
-      // boolean status — not a credential — so it passes through unchanged.
-      // Redacting it to the string '[REDACTED]' would silently corrupt its
-      // type without protecting any secret.
-      authenticated: true,
-    };
-
-    const result = validateAttributes(attrs);
-    expect(result?.auth).toBe('[REDACTED]');
-    expect(result?.authorization).toBe('[REDACTED]');
-    expect(result?.authenticated).toBe(true);
-  });
-
-  it('should not redact non-sensitive fields with similar names', () => {
-    const attrs = {
-      email: 'user@example.com',
-      username: 'john',
-      userId: '123',
-    };
-
-    const result = validateAttributes(attrs);
-    expect(result?.email).toBe('user@example.com');
-    expect(result?.username).toBe('john');
-    expect(result?.userId).toBe('123');
-  });
-});