autotel 3.4.4 → 3.6.0

package/src/security-schema.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import {
+  SECURITY_ATTR,
+  SECURITY_DENIED_STATUSES,
+  SECURITY_SEVERITIES,
+  SECURITY_SEVERITY_RANK,
+  escalateSecuritySeverity,
+  parseSecuritySeverity,
+  securitySeverityAtLeast,
+} from './security-schema';
+
+describe('security-schema', () => {
+  it('ranks severities in declaration order', () => {
+    const ranks = SECURITY_SEVERITIES.map((s) => SECURITY_SEVERITY_RANK[s]);
+    expect(ranks).toEqual([0, 1, 2, 3]);
+  });
+
+  it('parses valid severities and falls back on garbage', () => {
+    expect(parseSecuritySeverity('critical')).toBe('critical');
+    expect(parseSecuritySeverity('warning')).toBe('warning');
+    expect(parseSecuritySeverity('CRITICAL')).toBe('info');
+    expect(parseSecuritySeverity(42)).toBe('info');
+    expect(parseSecuritySeverity(undefined)).toBe('info');
+    expect(parseSecuritySeverity(undefined, 'warning')).toBe('warning');
+  });
+
+  it('compares severities against a threshold', () => {
+    expect(securitySeverityAtLeast('error', 'warning')).toBe(true);
+    expect(securitySeverityAtLeast('warning', 'warning')).toBe(true);
+    expect(securitySeverityAtLeast('info', 'warning')).toBe(false);
+  });
+
+  it('escalates to the floor but never downgrades', () => {
+    expect(escalateSecuritySeverity('info', 'error')).toBe('error');
+    expect(escalateSecuritySeverity('error', 'error')).toBe('error');
+    expect(escalateSecuritySeverity('critical', 'error')).toBe('critical');
+  });
+
+  it('keeps the attribute contract stable', () => {
+    expect(SECURITY_ATTR.event).toBe('security.event');
+    expect(SECURITY_ATTR.severity).toBe('security.severity');
+    expect(SECURITY_ATTR.suspiciousRequest).toBe('security.suspicious_request');
+    expect(SECURITY_DENIED_STATUSES).toEqual([401, 403, 429]);
+  });
+});

package/src/security-schema.ts

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ */
+
+export type SecuritySeverity = 'info' | 'warning' | 'error' | 'critical';
+
+/** All severities, lowest first. */
+export const SECURITY_SEVERITIES: readonly SecuritySeverity[] = [
+  'info',
+  'warning',
+  'error',
+  'critical',
+];
+
+/** Numeric rank per severity for threshold comparisons. */
+export const SECURITY_SEVERITY_RANK: Record<SecuritySeverity, number> = {
+  info: 0,
+  warning: 1,
+  error: 2,
+  critical: 3,
+};
+
+/**
+ * Parse an untrusted value (span attribute, event payload field) into a
+ * severity, falling back when it is missing or malformed.
+ */
+export function parseSecuritySeverity(
+  value: unknown,
+  fallback: SecuritySeverity = 'info',
+): SecuritySeverity {
+  return typeof value === 'string' && value in SECURITY_SEVERITY_RANK
+    ? (value as SecuritySeverity)
+    : fallback;
+}
+
+/** `true` when `severity` meets or exceeds `min`. */
+export function securitySeverityAtLeast(
+  severity: SecuritySeverity,
+  min: SecuritySeverity,
+): boolean {
+  return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[min];
+}
+
+/** The higher-ranked of two severities (e.g. escalate failures to ≥ error). */
+export function escalateSecuritySeverity(
+  severity: SecuritySeverity,
+  floor: SecuritySeverity,
+): SecuritySeverity {
+  return SECURITY_SEVERITY_RANK[severity] >= SECURITY_SEVERITY_RANK[floor]
+    ? severity
+    : floor;
+}
+
+/**
+ * Span attribute keys of the security schema. Emitters and consumers must
+ * reference these instead of re-typing the strings.
+ */
+export const 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',
+} as const;
+
+/** Metric names emitted by the security instrumentation. */
+export const SECURITY_METRICS = {
+  events: 'autotel.security.events',
+  httpSuspicious: 'autotel.security.http.suspicious',
+  httpDenied: 'autotel.security.http.denied',
+  anomaly: 'autotel.security.anomaly',
+  heartbeat: 'autotel.security.heartbeat',
+} as const;
+
+/** HTTP statuses counted as denied responses by default. */
+export const SECURITY_DENIED_STATUSES: readonly number[] = [401, 403, 429];
+
+/**
+ * Span attributes carrying the HTTP response status, current semconv
+ * first, legacy fallback second.
+ */
+export const HTTP_STATUS_ATTRIBUTES: readonly string[] = [
+  'http.response.status_code',
+  'http.status_code',
+];

package/src/stable-hash.ts

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Deterministic JSON stringify with sorted object keys, so two structurally
+ * equal values always produce the same string regardless of key insertion
+ * order. Shared by `defineEvent` and the validation layer for stable schema
+ * hashes.
+ */
+export function stableStringify(value: unknown): string {
+  if (value === null || value === undefined || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map((v) => stableStringify(v)).join(',') + ']';
+  }
+  const obj = value as Record<string, unknown>;
+  const body = Object.keys(obj)
+    .toSorted()
+    .map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k]))
+    .join(',');
+  return '{' + body + '}';
+}
+
+/** Stable sha256 of any JSON-serializable value. */
+export function hashJson(value: unknown): string {
+  return createHash('sha256').update(stableStringify(value)).digest('hex');
+}

package/src/validate.test.ts

@@ -0,0 +1,285 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { trace } from '@opentelemetry/api';
+
+const counterAdd = vi.hoisted(() => vi.fn());
+vi.mock('./metric-helpers', () => ({
+  createCounter: () => ({ add: counterAdd }),
+}));
+
+import {
+  defineValidator,
+  recordValidationMismatch,
+  formatValidationIssues,
+  onValidationMismatch,
+  type ValidationMismatch,
+} from './validate';
+import { VALIDATION_ATTR } from './validation-attributes';
+
+/** A fake `SchemaLike` so tests don't depend on Zod. */
+function schema<T>(
+  decide: (input: unknown) => { success: true; data: T } | { success: false; error: unknown },
+) {
+  return { safeParse: decide };
+}
+
+/** A Zod-shaped error whose message/received embed a secret value. */
+const SECRET = '123-45-6789';
+const zodLikeError = {
+  issues: [
+    {
+      path: ['user', 'ssn'],
+      code: 'invalid_type',
+      expected: 'string',
+      received: SECRET, // value — must never escape
+      message: `Expected string, received ${SECRET}`, // value — must never escape
+    },
+  ],
+};
+
+let setAttributes: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  setAttributes = vi.fn();
+  vi.spyOn(trace, 'getActiveSpan').mockReturnValue({
+    setAttributes,
+  } as never);
+  counterAdd.mockClear();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('formatValidationIssues — PII guard', () => {
+  it('keeps only path, code, and declared type — never values or messages', () => {
+    const issues = formatValidationIssues(zodLikeError);
+    expect(issues).toEqual([
+      { path: 'user.ssn', code: 'invalid_type', expected: 'string' },
+    ]);
+    // The secret must not appear anywhere in the serialized output.
+    expect(JSON.stringify(issues)).not.toContain(SECRET);
+  });
+
+  it('handles a generic { errors: [...] } shape', () => {
+    const issues = formatValidationIssues({
+      errors: [{ path: ['a'], code: 'custom' }],
+    });
+    expect(issues).toEqual([{ path: 'a', code: 'custom' }]);
+  });
+
+  it('returns [] for unrecognised errors', () => {
+    expect(formatValidationIssues(new Error('boom'))).toEqual([]);
+    expect(formatValidationIssues()).toEqual([]);
+    expect(formatValidationIssues('nope')).toEqual([]);
+  });
+
+  it('defaults a missing code and root path', () => {
+    expect(formatValidationIssues({ issues: [{}] })).toEqual([
+      { path: '', code: 'invalid' },
+    ]);
+  });
+});
+
+describe('recordValidationMismatch', () => {
+  const mismatch: ValidationMismatch = {
+    name: 'POST /orders',
+    boundary: 'http',
+    mode: 'reject',
+    issues: [
+      { path: 'a', code: 'invalid_type' },
+      { path: 'b', code: 'too_small' },
+      { path: 'c', code: 'invalid_type' },
+    ],
+    hash: 'abc123',
+    severity: 'warning',
+  };
+
+  it('sets validation.* attributes on the active span', () => {
+    recordValidationMismatch(mismatch);
+    expect(setAttributes).toHaveBeenCalledWith(
+      expect.objectContaining({
+        [VALIDATION_ATTR.name]: 'POST /orders',
+        [VALIDATION_ATTR.boundary]: 'http',
+        [VALIDATION_ATTR.mode]: 'reject',
+        [VALIDATION_ATTR.issueCount]: 3,
+        [VALIDATION_ATTR.issuePaths]: 'a,b,c',
+        [VALIDATION_ATTR.issueCodes]: 'invalid_type,too_small', // deduped
+        [VALIDATION_ATTR.hash]: 'abc123',
+        [VALIDATION_ATTR.severity]: 'warning',
+      }),
+    );
+  });
+
+  it('increments the mismatch counter with boundary/validation/mode labels', () => {
+    recordValidationMismatch(mismatch);
+    expect(counterAdd).toHaveBeenCalledWith(1, {
+      boundary: 'http',
+      validation: 'POST /orders',
+      mode: 'reject',
+    });
+  });
+
+  it('skips span attributes when there is no active span (fail-open)', () => {
+    vi.spyOn(trace, 'getActiveSpan').mockReturnValue();
+    expect(() => recordValidationMismatch(mismatch)).not.toThrow();
+  });
+
+  it('never throws even if the span sink throws', () => {
+    setAttributes.mockImplementation(() => {
+      throw new Error('span boom');
+    });
+    expect(() => recordValidationMismatch(mismatch)).not.toThrow();
+  });
+});
+
+describe('onValidationMismatch', () => {
+  const mismatch = (name: string): ValidationMismatch => ({
+    name,
+    boundary: 'event',
+    mode: 'observe',
+    issues: [],
+  });
+
+  // The listener registry is module-global; track every unsubscribe so a test
+  // can't leak a subscriber into the next one.
+  const cleanups: Array<() => void> = [];
+  const register = (handler: (m: ValidationMismatch) => void) => {
+    const off = onValidationMismatch(handler);
+    cleanups.push(off);
+    return off;
+  };
+  afterEach(() => {
+    while (cleanups.length > 0) cleanups.pop()!();
+  });
+
+  it('invokes a registered listener and can unsubscribe', () => {
+    const seen: ValidationMismatch[] = [];
+    const off = register((m) => seen.push(m));
+    recordValidationMismatch(mismatch('x'));
+    expect(seen).toHaveLength(1);
+    off();
+    recordValidationMismatch(mismatch('y'));
+    expect(seen).toHaveLength(1); // not called after unsubscribe
+  });
+
+  it('delivers each mismatch to every simultaneous subscriber', () => {
+    // The real case: autotel-audit registers a security bridge while the app
+    // registers its own webhook/logger — both must fire.
+    const audit: string[] = [];
+    const webhook: string[] = [];
+    register((m) => audit.push(m.name));
+    register((m) => webhook.push(m.name));
+
+    recordValidationMismatch(mismatch('POST /login'));
+
+    expect(audit).toEqual(['POST /login']);
+    expect(webhook).toEqual(['POST /login']);
+  });
+
+  it('unsubscribes each subscriber independently', () => {
+    const a: string[] = [];
+    const b: string[] = [];
+    const offA = register((m) => a.push(m.name));
+    register((m) => b.push(m.name));
+
+    recordValidationMismatch(mismatch('first'));
+    offA(); // remove only A
+    recordValidationMismatch(mismatch('second'));
+
+    expect(a).toEqual(['first']); // A stopped after unsubscribe
+    expect(b).toEqual(['first', 'second']); // B keeps firing
+  });
+
+  it('isolates faults: a throwing subscriber neither throws nor starves peers', () => {
+    const survivor: string[] = [];
+    register(() => {
+      throw new Error('subscriber boom');
+    });
+    register((m) => survivor.push(m.name));
+
+    expect(() => recordValidationMismatch(mismatch('z'))).not.toThrow();
+    expect(survivor).toEqual(['z']); // the healthy subscriber still fired
+  });
+
+  it('treats a re-registered identical handler as a single subscription', () => {
+    const seen: string[] = [];
+    const handler = (m: ValidationMismatch) => seen.push(m.name);
+    register(handler);
+    register(handler); // Set semantics → still one
+    recordValidationMismatch(mismatch('once'));
+    expect(seen).toEqual(['once']);
+  });
+});
+
+describe('defineValidator', () => {
+  const ok = schema<{ a: number }>(() => ({ success: true, data: { a: 1 } }));
+  const bad = schema<{ a: number }>(() => ({
+    success: false,
+    error: zodLikeError,
+  }));
+
+  it('reject mode (default): records then throws a 400 structured error', () => {
+    const v = defineValidator('POST /orders', bad, { boundary: 'http' });
+    expect(v.mode).toBe('reject');
+    try {
+      v.parse({ user: { ssn: SECRET } });
+      throw new Error('should have thrown');
+    } catch (error) {
+      const e = error as { status?: number; code?: string; message: string };
+      expect(e.status).toBe(400);
+      expect(e.code).toBe('validation_failed');
+      // even the thrown error must not leak the value
+      expect(JSON.stringify({ m: e.message })).not.toContain(SECRET);
+    }
+    expect(setAttributes).toHaveBeenCalled();
+  });
+
+  it('observe mode: records then returns the raw input (no throw)', () => {
+    const v = defineValidator('order.placed', bad, {
+      boundary: 'event',
+      onMismatch: 'observe',
+    });
+    const raw = { user: { ssn: SECRET } };
+    expect(v.parse(raw)).toBe(raw);
+    expect(setAttributes).toHaveBeenCalledWith(
+      expect.objectContaining({ [VALIDATION_ATTR.mode]: 'observe' }),
+    );
+  });
+
+  it('returns parsed data and records nothing on success', () => {
+    const v = defineValidator('ok', ok);
+    expect(v.parse({})).toEqual({ a: 1 });
+    expect(setAttributes).not.toHaveBeenCalled();
+    expect(counterAdd).not.toHaveBeenCalled();
+  });
+
+  it('safeParse returns a discriminated result and never throws', () => {
+    const v = defineValidator('POST /orders', bad);
+    const result = v.safeParse({});
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.issues[0]).toEqual({
+        path: 'user.ssn',
+        code: 'invalid_type',
+        expected: 'string',
+      });
+    }
+  });
+
+  it('honors a custom onReject error builder', () => {
+    const v = defineValidator('x', bad, {
+      onReject: () => new Error('custom reject'),
+    });
+    expect(() => v.parse({})).toThrow('custom reject');
+  });
+
+  it('emits a stable validation.hash when toJsonSchema is provided', () => {
+    const v = defineValidator('x', bad, {
+      toJsonSchema: () => ({ type: 'object' }),
+    });
+    v.safeParse({});
+    const attrs = setAttributes.mock.calls[0][0];
+    expect(typeof attrs[VALIDATION_ATTR.hash]).toBe('string');
+    expect(attrs[VALIDATION_ATTR.hash]).toHaveLength(64); // sha256 hex
+  });
+});