autotel-audit 0.3.2 → 0.4.1

package/src/context.ts

@@ -1,145 +0,0 @@
-import { getTraceContext, otelTrace } from 'autotel';
-
-export interface AuditContext {
-  traceId: string;
-  spanId: string;
-  correlationId: string;
-  setAttribute(key: string, value: string | number | boolean): void;
-  setAttributes(
-    attrs: Record<string, string | number | boolean | string[] | number[] | boolean[]>,
-  ): void;
-}
-
-const MISSING_CONTEXT_MESSAGE =
-  '[autotel-audit] No active trace context. Wrap the call in trace()/instrument(), pass options.ctx, ' +
-  'or set options.onMissingContext to "warn"/"skip" to degrade gracefully instead of throwing.';
-
-/**
- * Resolve an audit context without throwing. Returns `null` when no trace context
- * is available, so callers can degrade gracefully (best-effort instrumentation).
- */
-const INVALID_TRACE_ID = '00000000000000000000000000000000';
-
-export function resolveContextSafe(ctx?: AuditContext): AuditContext | null {
-  if (ctx) return ctx;
-
-  const span = otelTrace.getActiveSpan();
-  if (!span) return null;
-
-  // Resolve trace ids from autotel's context when available, otherwise from the
-  // active OTel span itself, so audit works in any OTel setup — not only inside
-  // autotel's own `trace()`.
-  const ids = getTraceContext();
-  const sc = span.spanContext();
-  const traceId = ids?.traceId ?? sc.traceId;
-  if (!traceId || traceId === INVALID_TRACE_ID) return null;
-
-  return {
-    traceId,
-    spanId: ids?.spanId ?? sc.spanId,
-    correlationId: ids?.correlationId ?? traceId.slice(0, 16),
-    setAttribute: (key, value) => span.setAttribute(key, value),
-    setAttributes: (attrs) => span.setAttributes(attrs),
-  };
-}
-
-export function resolveContext(ctx?: AuditContext): AuditContext {
-  const resolved = resolveContextSafe(ctx);
-  if (resolved) return resolved;
-  throw new Error(MISSING_CONTEXT_MESSAGE);
-}
-
-export { MISSING_CONTEXT_MESSAGE };
-
-/**
- * How instrumentation should behave when no trace context is available.
- *
- * - `throw` — fail fast (original behaviour). Use when telemetry is mandatory.
- * - `warn` — run the wrapped handler un-audited and log one warning per action (default).
- * - `skip` — run the wrapped handler un-audited, silently.
- *
- * Telemetry is observability: a missing context should never crash the business
- * logic it wraps, so the default is best-effort (`warn`).
- */
-export type OnMissingContext = 'throw' | 'warn' | 'skip';
-
-/** A no-op {@link AuditContext} whose attribute setters do nothing. */
-export function noopAuditContext(): AuditContext {
-  return {
-    traceId: '',
-    spanId: '',
-    correlationId: '',
-    setAttribute() {},
-    setAttributes() {},
-  };
-}
-
-const warnedMissingContext = new Set<string>();
-const warnedMissingLogger = new Set<string>();
-
-/** Warn (once per action) that instrumentation is running without a trace context. */
-export function warnMissingContextOnce(action: string): void {
-  if (warnedMissingContext.has(action)) return;
-  warnedMissingContext.add(action);
-  console.warn(
-    `[autotel-audit] No active trace context for "${action}" — running un-audited. ` +
-      'Wrap the call in trace()/instrument() or pass options.ctx to capture telemetry. ' +
-      '(set options.onMissingContext: "throw" to fail fast, or "skip" to silence this warning)',
-  );
-}
-
-/** Warn (once per action) that attributes were recorded but no canonical log line emitted. */
-export function warnMissingLoggerOnce(action: string): void {
-  if (warnedMissingLogger.has(action)) return;
-  warnedMissingLogger.add(action);
-  console.warn(
-    `[autotel-audit] No request logger for "${action}" — attributes were recorded on the span, ` +
-      'but no canonical log line was emitted. Pass options.logger or run inside runWithRequestContext().',
-  );
-}
-
-export function toAttributeValue(
-  value: unknown,
-): string | number | boolean | string[] | number[] | boolean[] | undefined {
-  if (
-    typeof value === 'string' ||
-    typeof value === 'number' ||
-    typeof value === 'boolean'
-  ) {
-    return value;
-  }
-
-  if (Array.isArray(value)) {
-    if (value.every((entry) => typeof entry === 'string')) {
-      return value;
-    }
-
-    if (value.every((entry) => typeof entry === 'number')) {
-      return value;
-    }
-
-    if (value.every((entry) => typeof entry === 'boolean')) {
-      return value;
-    }
-
-    try {
-      return JSON.stringify(value);
-    } catch {
-      return '<serialization-failed>';
-    }
-  }
-
-  if (value instanceof Date) {
-    return value.toISOString();
-  }
-
-  if (value === null || value === undefined) {
-    return undefined;
-  }
-
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return '<serialization-failed>';
-  }
-}

package/src/index.test.ts

@@ -1,183 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { otelTrace } from 'autotel';
-import {
-  forceKeepAuditEvent,
-  setAuditAttributes,
-  withAudit,
-  type AuditMetadata,
-} from './index';
-
-const setAttribute = vi.fn();
-const setAttributes = vi.fn();
-const mockCtx = {
-  traceId: 'trace-1',
-  spanId: 'span-1',
-  correlationId: 'corr-1',
-  setAttribute,
-  setAttributes,
-  setStatus: vi.fn(),
-  addLink: vi.fn(),
-  addLinks: vi.fn(),
-  updateName: vi.fn(),
-  isRecording: vi.fn(() => true),
-  recordError: vi.fn(),
-  track: vi.fn(),
-  getBaggage: vi.fn(),
-  setBaggage: vi.fn(),
-  deleteBaggage: vi.fn(),
-  getAllBaggage: vi.fn(),
-  getTypedBaggage: vi.fn(),
-  setTypedBaggage: vi.fn(),
-  withBaggage: vi.fn(),
-};
-
-const logger = {
-  set: vi.fn(),
-  info: vi.fn(),
-  warn: vi.fn(),
-  error: vi.fn(),
-  getContext: vi.fn(() => ({})),
-  emitNow: vi.fn(() => ({
-    timestamp: new Date().toISOString(),
-    traceId: 'trace-1',
-    spanId: 'span-1',
-    correlationId: 'corr-1',
-    context: {},
-  })),
-  fork: vi.fn(),
-};
-
-vi.mock('autotel', () => ({
-  AUTOTEL_SAMPLING_TAIL_EVALUATED: 'autotel.sampling.tail.evaluated',
-  AUTOTEL_SAMPLING_TAIL_KEEP: 'autotel.sampling.tail.keep',
-  createCounter: vi.fn(() => ({ add: vi.fn() })),
-  REDACTOR_PATTERNS: {
-    sensitiveKey:
-      /^(password|passwd|pwd|secret|token|api[_-]?key|auth|credential|private[_-]?key|authorization)$/i,
-  },
-  getTraceContext: vi.fn(() => mockCtx),
-  getRequestLogger: vi.fn(() => logger),
-  getRequestLoggerSafe: vi.fn(() => logger),
-  createNoopRequestLogger: vi.fn(() => logger),
-  otelTrace: {
-    getActiveSpan: vi.fn(() => ({
-      setAttribute,
-      setAttributes,
-      spanContext: () => ({ traceId: 'trace-1', spanId: 'span-1' }),
-    })),
-  },
-}));
-
-describe('autotel-audit', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('forceKeepAuditEvent sets tail keep attributes', () => {
-    forceKeepAuditEvent(mockCtx as never);
-
-    expect(setAttribute).toHaveBeenCalledWith(
-      'autotel.sampling.tail.evaluated',
-      true,
-    );
-    expect(setAttribute).toHaveBeenCalledWith('autotel.sampling.tail.keep', true);
-    expect(setAttribute).toHaveBeenCalledWith('autotel.audit.force_keep', true);
-  });
-
-  it('setAuditAttributes writes audit.* attributes', () => {
-    const metadata: AuditMetadata = {
-      action: 'user.delete',
-      resource: 'account',
-      actorId: 'admin-1',
-    };
-
-    setAuditAttributes(metadata, mockCtx as never);
-
-    expect(setAttributes).toHaveBeenCalledWith(
-      expect.objectContaining({
-        'autotel.audit': true,
-        'audit.action': 'user.delete',
-        'audit.resource': 'account',
-        'audit.actorId': 'admin-1',
-      }),
-    );
-  });
-
-  it('withAudit marks success and optionally emits', async () => {
-    const result = await withAudit(
-      { action: 'permission.update', resource: 'role' },
-      async () => 'ok',
-      { emitNow: true },
-    );
-
-    expect(result).toBe('ok');
-    expect(logger.set).toHaveBeenCalled();
-    expect(setAttributes).toHaveBeenCalledWith(
-      expect.objectContaining({
-        'audit.outcome': 'success',
-      }),
-    );
-    expect(logger.emitNow).toHaveBeenCalledTimes(1);
-  });
-
-  it('withAudit marks failure and rethrows', async () => {
-    await expect(
-      withAudit({ action: 'secrets.read' }, async () => {
-        throw new Error('denied');
-      }),
-    ).rejects.toThrow('denied');
-
-    expect(setAttributes).toHaveBeenCalledWith(
-      expect.objectContaining({
-        'audit.outcome': 'failure',
-      }),
-    );
-    expect(logger.error).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe('autotel-audit best-effort (onMissingContext)', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('runs the handler un-audited and warns once by default when no context', async () => {
-    vi.mocked(otelTrace.getActiveSpan).mockReturnValueOnce(undefined as never);
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-
-    const result = await withAudit(
-      { action: 'missing.default' },
-      async () => 'ran',
-    );
-
-    expect(result).toBe('ran');
-    expect(warn).toHaveBeenCalledTimes(1);
-    expect(setAttributes).not.toHaveBeenCalled();
-    warn.mockRestore();
-  });
-
-  it('throws when onMissingContext is "throw"', async () => {
-    vi.mocked(otelTrace.getActiveSpan).mockReturnValueOnce(undefined as never);
-
-    await expect(
-      withAudit({ action: 'missing.throw' }, async () => 'x', {
-        onMissingContext: 'throw',
-      }),
-    ).rejects.toThrow('No active trace context');
-  });
-
-  it('runs silently when onMissingContext is "skip"', async () => {
-    vi.mocked(otelTrace.getActiveSpan).mockReturnValueOnce(undefined as never);
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-
-    const result = await withAudit(
-      { action: 'missing.skip' },
-      async () => 'ran',
-      { onMissingContext: 'skip' },
-    );
-
-    expect(result).toBe('ran');
-    expect(warn).not.toHaveBeenCalled();
-    warn.mockRestore();
-  });
-});

package/src/index.ts

@@ -1,153 +0,0 @@
-import {
-  AUTOTEL_SAMPLING_TAIL_EVALUATED,
-  AUTOTEL_SAMPLING_TAIL_KEEP,
-  createNoopRequestLogger,
-  getRequestLoggerSafe,
-} from 'autotel';
-import type { RequestLogger } from 'autotel';
-import {
-  MISSING_CONTEXT_MESSAGE,
-  noopAuditContext,
-  resolveContextSafe,
-  toAttributeValue,
-  warnMissingContextOnce,
-  warnMissingLoggerOnce,
-  type AuditContext,
-  type OnMissingContext,
-} from './context';
-
-export type { AuditContext, OnMissingContext } from './context';
-export * from './security';
-export * from './security-signals';
-export * from './security-heartbeat';
-
-export interface AuditMetadata {
-  action: string;
-  resource?: string;
-  actorId?: string;
-  category?: string;
-  outcome?: 'success' | 'failure' | (string & {});
-  [key: string]: unknown;
-}
-
-export interface WithAuditOptions {
-  ctx?: AuditContext;
-  emitNow?: boolean;
-  forceKeep?: boolean;
-  logger?: RequestLogger;
-  /**
-   * Behaviour when no trace context can be resolved. Defaults to `warn`
-   * (best-effort: run un-audited, warn once). See {@link OnMissingContext}.
-   */
-  onMissingContext?: OnMissingContext;
-}
-
-function flattenAuditAttributes(
-  metadata: AuditMetadata,
-): Record<string, string | number | boolean | string[] | number[] | boolean[]> {
-  const attributes: Record<
-    string,
-    string | number | boolean | string[] | number[] | boolean[]
-  > = {
-    'autotel.audit': true,
-  };
-
-  for (const [key, value] of Object.entries(metadata)) {
-    const attr = toAttributeValue(value);
-    if (attr !== undefined) {
-      attributes[`audit.${key}`] = attr;
-    }
-  }
-
-  return attributes;
-}
-
-export function forceKeepAuditEvent(ctx?: AuditContext): void {
-  const traceCtx = resolveContextSafe(ctx);
-  if (!traceCtx) return;
-  traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_EVALUATED, true);
-  traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_KEEP, true);
-  traceCtx.setAttribute('autotel.audit.force_keep', true);
-}
-
-export function setAuditAttributes(
-  metadata: AuditMetadata,
-  ctx?: AuditContext,
-): void {
-  const traceCtx = resolveContextSafe(ctx);
-  if (!traceCtx) return;
-  traceCtx.setAttributes(flattenAuditAttributes(metadata));
-}
-
-export async function withAudit<T>(
-  metadata: AuditMetadata,
-  fn: (ctx: AuditContext, logger: RequestLogger) => T | Promise<T>,
-  options: WithAuditOptions = {},
-): Promise<T> {
-  const traceCtx = resolveContextSafe(options.ctx);
-
-  // No trace context: degrade per onMissingContext instead of throwing into
-  // business logic. Audit is observability — it must never crash the caller.
-  if (!traceCtx) {
-    const mode = options.onMissingContext ?? 'warn';
-    if (mode === 'throw') {
-      throw new Error(MISSING_CONTEXT_MESSAGE);
-    }
-    if (mode === 'warn') {
-      warnMissingContextOnce(metadata.action);
-    }
-    return fn(noopAuditContext(), options.logger ?? createNoopRequestLogger());
-  }
-
-  if (options.forceKeep !== false) {
-    forceKeepAuditEvent(traceCtx);
-  }
-
-  setAuditAttributes(metadata, traceCtx);
-
-  // A trace context may exist (e.g. caller-supplied options.ctx) without a
-  // resolvable request logger. Record span attributes regardless and only skip
-  // the canonical log line — never throw.
-  let logger = options.logger ?? getRequestLoggerSafe() ?? undefined;
-  if (!logger) {
-    if ((options.onMissingContext ?? 'warn') === 'warn') {
-      warnMissingLoggerOnce(metadata.action);
-    }
-    logger = createNoopRequestLogger();
-  }
-  logger.set({
-    audit: {
-      ...metadata,
-      forceKeep: options.forceKeep !== false,
-    },
-  });
-
-  try {
-    const result = await fn(traceCtx, logger);
-
-    if (!metadata.outcome) {
-      setAuditAttributes({ ...metadata, outcome: 'success' }, traceCtx);
-    }
-
-    if (options.emitNow) {
-      logger.emitNow();
-    }
-
-    return result;
-  } catch (error) {
-    const asError = error instanceof Error ? error : new Error(String(error));
-    setAuditAttributes({ ...metadata, outcome: 'failure' }, traceCtx);
-    logger.error(asError, {
-      audit: {
-        action: metadata.action,
-        resource: metadata.resource,
-      },
-    });
-
-    if (options.emitNow) {
-      logger.emitNow();
-    }
-
-    throw asError;
-  }
-}

package/src/lazy-counter.ts

@@ -1,24 +0,0 @@
-import { createCounter } from 'autotel';
-
-export interface LazyCounter {
-  add(value: number, attributes?: Record<string, string | number | boolean>): void;
-}
-
-/**
- * Counter that is created on first use (the meter may not be configured
- * until `init()` completes) and whose failures are swallowed — metrics
- * must never break event emission or the span pipeline.
- */
-export function lazyCounter(name: string, description: string): LazyCounter {
-  let counter: ReturnType<typeof createCounter> | undefined;
-  return {
-    add(value, attributes) {
-      try {
-        counter ??= createCounter(name, { description });
-        counter.add(value, attributes);
-      } catch {
-        // Swallow — observability must never take the process down.
-      }
-    },
-  };
-}

package/src/security-heartbeat.test.ts

@@ -1,65 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { startSecurityHeartbeat } from './security-heartbeat';
-
-const counterAdd = vi.fn();
-
-vi.mock('autotel', () => ({
-  createCounter: vi.fn(() => ({ add: counterAdd })),
-}));
-
-describe('startSecurityHeartbeat', () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-    vi.clearAllMocks();
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it('beats immediately and then on every interval', () => {
-    const heartbeat = startSecurityHeartbeat({ intervalMs: 10_000 });
-
-    expect(counterAdd).toHaveBeenCalledTimes(1);
-
-    vi.advanceTimersByTime(30_000);
-    expect(counterAdd).toHaveBeenCalledTimes(4);
-
-    heartbeat.stop();
-  });
-
-  it('stops beating after stop()', () => {
-    const heartbeat = startSecurityHeartbeat({ intervalMs: 10_000 });
-    heartbeat.stop();
-
-    vi.advanceTimersByTime(60_000);
-    expect(counterAdd).toHaveBeenCalledTimes(1); // only the initial beat
-
-    heartbeat.stop(); // idempotent
-  });
-
-  it('attaches custom attributes to every beat', () => {
-    const heartbeat = startSecurityHeartbeat({
-      intervalMs: 10_000,
-      attributes: { component: 'payments' },
-    });
-
-    vi.advanceTimersByTime(10_000);
-    expect(counterAdd).toHaveBeenLastCalledWith(1, { component: 'payments' });
-
-    heartbeat.stop();
-  });
-
-  it('survives a broken meter', async () => {
-    const { createCounter } = vi.mocked(await import('autotel'));
-    createCounter.mockImplementation(() => {
-      throw new Error('meter not configured');
-    });
-
-    expect(() => {
-      const heartbeat = startSecurityHeartbeat({ intervalMs: 10_000 });
-      vi.advanceTimersByTime(20_000);
-      heartbeat.stop();
-    }).not.toThrow();
-  });
-});

package/src/security-heartbeat.ts

@@ -1,63 +0,0 @@
-import { SECURITY_METRICS } from 'autotel/security-schema';
-import { lazyCounter } from './lazy-counter';
-
-/**
- * Security-telemetry heartbeat.
- *
- * A silently-dead telemetry pipeline is itself a security failure (NIST
- * SP 800-92: systems must not keep operating without visibility into
- * security events). `startSecurityHeartbeat()` emits the
- * `autotel.security.heartbeat` counter on a fixed interval so security
- * teams can alert on the ABSENCE of telemetry from a service:
- *
- * ```promql
- * absent(rate(autotel_security_heartbeat_total{service_name="api"}[5m]))
- * ```
- *
- * ```typescript
- * const heartbeat = startSecurityHeartbeat();
- * // on shutdown:
- * heartbeat.stop();
- * ```
- */
-
-export interface SecurityHeartbeatOptions {
-  /** Beat interval in milliseconds. Default 60_000. */
-  intervalMs?: number;
-  /** Extra counter attributes (keep cardinality low — labels, not data). */
-  attributes?: Record<string, string | number | boolean>;
-}
-
-export interface SecurityHeartbeat {
-  stop(): void;
-}
-
-export function startSecurityHeartbeat(
-  options: SecurityHeartbeatOptions = {},
-): SecurityHeartbeat {
-  const intervalMs = options.intervalMs ?? 60_000;
-  const attributes = options.attributes ?? {};
-
-  const counter = lazyCounter(
-    SECURITY_METRICS.heartbeat,
-    'Security-telemetry liveness signal — alert on its absence',
-  );
-
-  function beat(): void {
-    counter.add(1, attributes);
-  }
-
-  beat(); // establish the series immediately, not one interval later
-  const timer = setInterval(beat, intervalMs);
-  // Never hold the process open just to beat.
-  timer.unref?.();
-
-  let stopped = false;
-  return {
-    stop() {
-      if (stopped) return;
-      stopped = true;
-      clearInterval(timer);
-    },
-  };
-}