autotel-audit 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,475 +1,529 @@
-import { createCounter, AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, getRequestLogger, getTraceContext, otelTrace, REDACTOR_PATTERNS } from 'autotel';
-import { createHash } from 'crypto';
-import { SECURITY_ATTR, SECURITY_METRICS, escalateSecuritySeverity, SECURITY_DENIED_STATUSES, HTTP_STATUS_ATTRIBUTES } from 'autotel/security-schema';
+import { AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, REDACTOR_PATTERNS, createCounter, createNoopRequestLogger, getRequestLoggerSafe, getTraceContext, otelTrace } from "autotel";
+import { createHash } from "node:crypto";
+import { HTTP_STATUS_ATTRIBUTES, SECURITY_ATTR, SECURITY_DENIED_STATUSES, SECURITY_METRICS, escalateSecuritySeverity } from "autotel/security-schema";
 
-// src/index.ts
-function resolveContext(ctx) {
-  if (ctx) return ctx;
-  const ids = getTraceContext();
-  const span = otelTrace.getActiveSpan();
-  if (ids && span) {
-    return {
-      traceId: ids.traceId,
-      spanId: ids.spanId,
-      correlationId: ids.correlationId,
-      setAttribute: (key, value) => span.setAttribute(key, value),
-      setAttributes: (attrs) => span.setAttributes(attrs)
-    };
-  }
-  throw new Error(
-    "[autotel-audit] No active trace context. Wrap your handler with trace() or pass options.ctx."
-  );
+//#region src/context.ts
+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";
+function resolveContextSafe(ctx) {
+	if (ctx) return ctx;
+	const span = otelTrace.getActiveSpan();
+	if (!span) return null;
+	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)
+	};
+}
+/** A no-op {@link AuditContext} whose attribute setters do nothing. */
+function noopAuditContext() {
+	return {
+		traceId: "",
+		spanId: "",
+		correlationId: "",
+		setAttribute() {},
+		setAttributes() {}
+	};
+}
+const warnedMissingContext = /* @__PURE__ */ new Set();
+const warnedMissingLogger = /* @__PURE__ */ new Set();
+/** Warn (once per action) that instrumentation is running without a trace context. */
+function warnMissingContextOnce(action) {
+	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. */
+function warnMissingLoggerOnce(action) {
+	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().`);
 }
 function toAttributeValue(value) {
-  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 === void 0) {
-    return void 0;
-  }
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return "<serialization-failed>";
-  }
+	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 === void 0) return;
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return "<serialization-failed>";
+	}
 }
+
+//#endregion
+//#region src/lazy-counter.ts
+/**
+* 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.
+*/
 function lazyCounter(name, description) {
-  let counter;
-  return {
-    add(value, attributes) {
-      try {
-        counter ??= createCounter(name, { description });
-        counter.add(value, attributes);
-      } catch {
-      }
-    }
-  };
+	let counter;
+	return { add(value, attributes) {
+		try {
+			counter ??= createCounter(name, { description });
+			counter.add(value, attributes);
+		} catch {}
+	} };
 }
 
-// src/security.ts
-var FIELD_ATTRIBUTES = {
-  name: SECURITY_ATTR.event,
-  category: SECURITY_ATTR.category,
-  outcome: SECURITY_ATTR.outcome,
-  severity: SECURITY_ATTR.severity,
-  actorId: SECURITY_ATTR.actorId,
-  targetType: SECURITY_ATTR.targetType,
-  targetId: SECURITY_ATTR.targetId,
-  tenantId: SECURITY_ATTR.tenantId,
-  reason: SECURITY_ATTR.reason
+//#endregion
+//#region src/security.ts
+/**
+* Standard metadata fields and the schema attribute each maps to.
+* Drives both standard-field emission and the reserved-key check for the
+* custom-attribute loop — adding a field here is the whole change.
+*/
+const FIELD_ATTRIBUTES = {
+	name: SECURITY_ATTR.event,
+	category: SECURITY_ATTR.category,
+	outcome: SECURITY_ATTR.outcome,
+	severity: SECURITY_ATTR.severity,
+	actorId: SECURITY_ATTR.actorId,
+	targetType: SECURITY_ATTR.targetType,
+	targetId: SECURITY_ATTR.targetId,
+	tenantId: SECURITY_ATTR.tenantId,
+	reason: SECURITY_ATTR.reason
 };
 function flattenSecurityAttributes(metadata) {
-  const attributes = {
-    [SECURITY_ATTR.marker]: true,
-    [SECURITY_ATTR.severity]: metadata.severity ?? "info"
-  };
-  const droppedKeys = [];
-  for (const [key, value] of Object.entries(metadata)) {
-    const standardAttribute = FIELD_ATTRIBUTES[key];
-    if (standardAttribute === void 0 && REDACTOR_PATTERNS.sensitiveKey.test(key)) {
-      droppedKeys.push(key);
-      continue;
-    }
-    const attr = toAttributeValue(value);
-    if (attr !== void 0) {
-      attributes[standardAttribute ?? `security.${key}`] = attr;
-    }
-  }
-  if (droppedKeys.length > 0) {
-    attributes[SECURITY_ATTR.droppedKeys] = droppedKeys;
-  }
-  return attributes;
+	const attributes = {
+		[SECURITY_ATTR.marker]: true,
+		[SECURITY_ATTR.severity]: metadata.severity ?? "info"
+	};
+	const droppedKeys = [];
+	for (const [key, value] of Object.entries(metadata)) {
+		const standardAttribute = FIELD_ATTRIBUTES[key];
+		if (standardAttribute === void 0 && REDACTOR_PATTERNS.sensitiveKey.test(key)) {
+			droppedKeys.push(key);
+			continue;
+		}
+		const attr = toAttributeValue(value);
+		if (attr !== void 0) attributes[standardAttribute ?? `security.${key}`] = attr;
+	}
+	if (droppedKeys.length > 0) attributes[SECURITY_ATTR.droppedKeys] = droppedKeys;
+	return attributes;
 }
-var eventsCounter = lazyCounter(
-  SECURITY_METRICS.events,
-  "Security events by name, category, outcome, and severity"
-);
+const eventsCounter = lazyCounter(SECURITY_METRICS.events, "Security events by name, category, outcome, and severity");
 function countSecurityEvent(metadata) {
-  eventsCounter.add(1, {
-    event: metadata.name,
-    category: metadata.category,
-    outcome: metadata.outcome,
-    severity: metadata.severity ?? "info"
-  });
+	eventsCounter.add(1, {
+		event: metadata.name,
+		category: metadata.category,
+		outcome: metadata.outcome,
+		severity: metadata.severity ?? "info"
+	});
 }
+/**
+* Record a security event on the active trace and request logger.
+*
+* Events are force-kept through tail sampling by default and carry
+* `security.*` attributes (`security.event`, `security.category`,
+* `security.outcome`, `security.severity`) so backends can build
+* detection rules and dashboards from a stable schema.
+*
+* ```typescript
+* securityEvent({
+*   name: 'auth.login.failed',
+*   category: 'authentication',
+*   outcome: 'failure',
+*   severity: 'warning',
+*   actorId: hashIdentifier(email),
+*   reason: 'invalid_password',
+* });
+* ```
+*/
 function securityEvent(metadata, options = {}) {
-  const traceCtx = resolveContext(options.ctx);
-  if (options.forceKeep !== false) {
-    traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_EVALUATED, true);
-    traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_KEEP, true);
-    traceCtx.setAttribute(SECURITY_ATTR.forceKeep, true);
-  }
-  traceCtx.setAttributes(flattenSecurityAttributes(metadata));
-  if (options.metrics !== false) {
-    countSecurityEvent(metadata);
-  }
-  const logger = options.logger ?? getRequestLogger();
-  logger.set({
-    security: {
-      name: metadata.name,
-      category: metadata.category,
-      outcome: metadata.outcome,
-      severity: metadata.severity ?? "info",
-      ...metadata.reason !== void 0 && { reason: metadata.reason },
-      forceKeep: options.forceKeep !== false
-    }
-  });
-  if (options.emitNow) {
-    logger.emitNow();
-  }
+	const traceCtx = resolveContextSafe(options.ctx);
+	if (options.metrics !== false) countSecurityEvent(metadata);
+	if (!traceCtx) {
+		const mode = options.onMissingContext ?? "warn";
+		if (mode === "throw") throw new Error(MISSING_CONTEXT_MESSAGE);
+		if (mode === "warn") warnMissingContextOnce(metadata.name);
+		return;
+	}
+	if (options.forceKeep !== false) {
+		traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_EVALUATED, true);
+		traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_KEEP, true);
+		traceCtx.setAttribute(SECURITY_ATTR.forceKeep, true);
+	}
+	traceCtx.setAttributes(flattenSecurityAttributes(metadata));
+	const logger = options.logger ?? getRequestLoggerSafe() ?? createNoopRequestLogger();
+	logger.set({ security: {
+		name: metadata.name,
+		category: metadata.category,
+		outcome: metadata.outcome,
+		severity: metadata.severity ?? "info",
+		...metadata.reason !== void 0 && { reason: metadata.reason },
+		forceKeep: options.forceKeep !== false
+	} });
+	if (options.emitNow) logger.emitNow();
 }
+/**
+* Wrap a security-sensitive operation. On success the event outcome is
+* recorded as given (default `success`); a thrown error records
+* `outcome: 'error'`, escalates the severity to at least `error`, and
+* rethrows.
+*
+* ```typescript
+* await withSecurity(
+*   { name: 'api_key.created', category: 'secrets', outcome: 'success', actorId: userId },
+*   async () => createApiKey(userId),
+* );
+* ```
+*/
 async function withSecurity(metadata, fn, options = {}) {
-  const traceCtx = resolveContext(options.ctx);
-  const logger = options.logger ?? getRequestLogger();
-  try {
-    const result = await fn(traceCtx, logger);
-    securityEvent(metadata, { ...options, ctx: traceCtx, logger });
-    return result;
-  } catch (error) {
-    const asError = error instanceof Error ? error : new Error(String(error));
-    securityEvent(
-      {
-        ...metadata,
-        outcome: "error",
-        // A failed security-sensitive operation is never less than an error,
-        // but an explicit `critical` stays critical.
-        severity: escalateSecuritySeverity(metadata.severity ?? "info", "error")
-      },
-      { ...options, ctx: traceCtx, logger }
-    );
-    logger.error(asError, {
-      security: {
-        name: metadata.name,
-        category: metadata.category
-      }
-    });
-    throw asError;
-  }
+	const traceCtx = resolveContextSafe(options.ctx);
+	const logger = options.logger ?? getRequestLoggerSafe() ?? createNoopRequestLogger();
+	const ctx = traceCtx ?? noopAuditContext();
+	try {
+		const result = await fn(ctx, logger);
+		securityEvent(metadata, {
+			...options,
+			ctx: traceCtx ?? void 0,
+			logger
+		});
+		return result;
+	} catch (error) {
+		const asError = error instanceof Error ? error : new Error(String(error));
+		securityEvent({
+			...metadata,
+			outcome: "error",
+			severity: escalateSecuritySeverity(metadata.severity ?? "info", "error")
+		}, {
+			...options,
+			ctx: traceCtx ?? void 0,
+			logger
+		});
+		logger.error(asError, { security: {
+			name: metadata.name,
+			category: metadata.category
+		} });
+		throw asError;
+	}
 }
+/**
+* Stable one-way digest for correlating PII-bearing identifiers
+* (emails, IPs) across events WITHOUT logging the raw value.
+*
+* NOT for secrets — never log secrets in any form, hashed or not.
+*/
 function hashIdentifier(value, options = {}) {
-  const length = options.length ?? 16;
-  return createHash("sha256").update(options.salt ? `${options.salt}:${value}` : value).digest("hex").slice(0, length);
+	const length = options.length ?? 16;
+	return createHash("sha256").update(options.salt ? `${options.salt}:${value}` : value).digest("hex").slice(0, length);
 }
-var SUSPICIOUS_REQUEST_PATTERNS = {
-  path_traversal: /(\.\.[/\\]|%2e%2e(%2f|%5c|\/)|\.\.%2f|%252e%252e)/i,
-  sensitive_file_probe: /(\/\.env\b|\/\.git\b|\/etc\/passwd|\/wp-admin\b|\/\.aws\b|\/id_rsa\b)/i,
-  sqli_probe: /(\bunion\b[\s+%20]+(all[\s+%20]+)?select\b|'[\s+%20]*or[\s+%20]*'?1'?[\s+%20]*=[\s+%20]*'?1)/i,
-  xss_probe: /(<script\b|%3cscript)/i,
-  null_byte: /%00/
+
+//#endregion
+//#region src/security-signals.ts
+/**
+* Conservative request-target patterns. Tuned for scanner/probe traffic —
+* high signal, low false-positive — not as a WAF. Extend via `extraPatterns`.
+*/
+const SUSPICIOUS_REQUEST_PATTERNS = {
+	path_traversal: /(\.\.[/\\]|%2e%2e(%2f|%5c|\/)|\.\.%2f|%252e%252e)/i,
+	sensitive_file_probe: /(\/\.env\b|\/\.git\b|\/etc\/passwd|\/wp-admin\b|\/\.aws\b|\/id_rsa\b)/i,
+	sqli_probe: /(\bunion\b[\s+%20]+(all[\s+%20]+)?select\b|'[\s+%20]*or[\s+%20]*'?1'?[\s+%20]*=[\s+%20]*'?1)/i,
+	xss_probe: /(<script\b|%3cscript)/i,
+	null_byte: /%00/
 };
-var TARGET_ATTRIBUTES = [
-  "url.path",
-  "url.full",
-  "http.target",
-  "http.url"
+const TARGET_ATTRIBUTES = [
+	"url.path",
+	"url.full",
+	"http.target",
+	"http.url"
 ];
 function readAttribute(attributes, keys) {
-  for (const key of keys) {
-    const value = attributes[key];
-    if (value !== void 0) return value;
-  }
-  return void 0;
+	for (const key of keys) {
+		const value = attributes[key];
+		if (value !== void 0) return value;
+	}
 }
+/**
+* Weighted sliding-window counter with bounded key cardinality.
+* Weight 1 per hit counts occurrences; token counts as weights sum usage.
+*/
 var SlidingWindow = class {
-  constructor(windowMs, maxKeys) {
-    this.windowMs = windowMs;
-    this.maxKeys = maxKeys;
-  }
-  windowMs;
-  maxKeys;
-  hits = /* @__PURE__ */ new Map();
-  /**
-   * Record a hit; returns the totals inside the window before and after it,
-   * so callers can signal exactly once on a threshold crossing.
-   */
-  record(key, now, weight = 1) {
-    let entries = this.hits.get(key);
-    if (!entries) {
-      if (this.hits.size >= this.maxKeys) {
-        const oldest = this.hits.keys().next().value;
-        if (oldest !== void 0) this.hits.delete(oldest);
-      }
-      entries = [];
-      this.hits.set(key, entries);
-    }
-    const cutoff = now - this.windowMs;
-    while (entries.length > 0 && entries[0][0] < cutoff) {
-      entries.shift();
-    }
-    let before = 0;
-    for (const [, w] of entries) before += w;
-    entries.push([now, weight]);
-    return { before, after: before + weight };
-  }
+	windowMs;
+	maxKeys;
+	hits = /* @__PURE__ */ new Map();
+	constructor(windowMs, maxKeys) {
+		this.windowMs = windowMs;
+		this.maxKeys = maxKeys;
+	}
+	/**
+	* Record a hit; returns the totals inside the window before and after it,
+	* so callers can signal exactly once on a threshold crossing.
+	*/
+	record(key, now, weight = 1) {
+		let entries = this.hits.get(key);
+		if (!entries) {
+			if (this.hits.size >= this.maxKeys) {
+				const oldest = this.hits.keys().next().value;
+				if (oldest !== void 0) this.hits.delete(oldest);
+			}
+			entries = [];
+			this.hits.set(key, entries);
+		}
+		const cutoff = now - this.windowMs;
+		while (entries.length > 0 && entries[0][0] < cutoff) entries.shift();
+		let before = 0;
+		for (const [, w] of entries) before += w;
+		entries.push([now, weight]);
+		return {
+			before,
+			after: before + weight
+		};
+	}
 };
 function resolveBurstConfig(option) {
-  if (option === false) return void 0;
-  const opts = option ?? {};
-  const windowMs = opts.windowMs ?? 6e4;
-  return {
-    statuses: new Set(opts.statuses ?? [401, 403]),
-    threshold: opts.threshold ?? 10,
-    windowMs,
-    keyAttribute: opts.keyAttribute ?? "client.address",
-    window: new SlidingWindow(windowMs, opts.maxKeys ?? 1e4)
-  };
+	if (option === false) return void 0;
+	const opts = option ?? {};
+	const windowMs = opts.windowMs ?? 6e4;
+	return {
+		statuses: new Set(opts.statuses ?? [401, 403]),
+		threshold: opts.threshold ?? 10,
+		windowMs,
+		keyAttribute: opts.keyAttribute ?? "client.address",
+		window: new SlidingWindow(windowMs, opts.maxKeys ?? 1e4)
+	};
 }
 function resolveLlmConfig(option) {
-  if (option === false) return void 0;
-  const opts = option ?? {};
-  const tokenBudget = opts.tokenBudget;
-  const windowMs = tokenBudget?.windowMs ?? 3e5;
-  return {
-    maxTokensPerCall: opts.maxTokensPerCall === false ? void 0 : opts.maxTokensPerCall ?? 1e5,
-    budget: tokenBudget && {
-      budget: tokenBudget.budget,
-      windowMs,
-      keyAttribute: tokenBudget.keyAttribute ?? "enduser.id",
-      window: new SlidingWindow(windowMs, tokenBudget.maxKeys ?? 1e4)
-    }
-  };
+	if (option === false) return void 0;
+	const opts = option ?? {};
+	const tokenBudget = opts.tokenBudget;
+	const windowMs = tokenBudget?.windowMs ?? 3e5;
+	return {
+		maxTokensPerCall: opts.maxTokensPerCall === false ? void 0 : opts.maxTokensPerCall ?? 1e5,
+		budget: tokenBudget && {
+			budget: tokenBudget.budget,
+			windowMs,
+			keyAttribute: tokenBudget.keyAttribute ?? "enduser.id",
+			window: new SlidingWindow(windowMs, tokenBudget.maxKeys ?? 1e4)
+		}
+	};
 }
 function createSecuritySignalProcessor(options = {}) {
-  const detect = options.detectSuspiciousRequests !== false;
-  const forceKeep = options.forceKeepSuspicious !== false;
-  const metricsEnabled = options.metrics !== false;
-  const deniedStatuses = new Set(
-    options.deniedStatuses ?? SECURITY_DENIED_STATUSES
-  );
-  const now = options.now ?? Date.now;
-  const patterns = {
-    ...SUSPICIOUS_REQUEST_PATTERNS,
-    ...options.extraPatterns
-  };
-  const burst = resolveBurstConfig(options.burst);
-  const llm = resolveLlmConfig(options.llm);
-  const counters = {
-    suspicious: lazyCounter(
-      SECURITY_METRICS.httpSuspicious,
-      "Requests matching suspicious-path patterns"
-    ),
-    denied: lazyCounter(
-      SECURITY_METRICS.httpDenied,
-      "HTTP responses with denied status codes (401/403/429)"
-    ),
-    anomaly: lazyCounter(
-      SECURITY_METRICS.anomaly,
-      "Security anomaly signals (e.g. auth-failure bursts)"
-    )
-  };
-  function count(which, attributes) {
-    if (!metricsEnabled) return;
-    counters[which].add(1, attributes);
-  }
-  function emit(signal) {
-    try {
-      options.onSignal?.(signal);
-    } catch {
-    }
-  }
-  function checkDeniedResponse(span) {
-    const status = readAttribute(span.attributes, HTTP_STATUS_ATTRIBUTES);
-    if (typeof status !== "number" || !deniedStatuses.has(status)) return;
-    count("denied", { status });
-    if (!burst || !burst.statuses.has(status)) return;
-    const key = readAttribute(span.attributes, [
-      burst.keyAttribute,
-      "http.client_ip"
-    ]);
-    if (typeof key !== "string" || key.length === 0) return;
-    const { before, after } = burst.window.record(key, now());
-    if (before < burst.threshold && after >= burst.threshold) {
-      count("anomaly", { signal: "auth_failure_burst", status });
-      emit({
-        signal: "auth_failure_burst",
-        key,
-        count: after,
-        windowMs: burst.windowMs,
-        status
-      });
-    }
-  }
-  function checkLlmConsumption(span) {
-    if (!llm) return;
-    const total = readAttribute(span.attributes, ["gen_ai.usage.total_tokens"]);
-    let tokens;
-    if (typeof total === "number") {
-      tokens = total;
-    } else {
-      const input = readAttribute(span.attributes, ["gen_ai.usage.input_tokens"]);
-      const output = readAttribute(span.attributes, [
-        "gen_ai.usage.output_tokens"
-      ]);
-      if (typeof input === "number" || typeof output === "number") {
-        tokens = (typeof input === "number" ? input : 0) + (typeof output === "number" ? output : 0);
-      }
-    }
-    if (tokens === void 0 || tokens <= 0) return;
-    if (llm.maxTokensPerCall !== void 0 && tokens > llm.maxTokensPerCall) {
-      const model = readAttribute(span.attributes, [
-        "gen_ai.response.model",
-        "gen_ai.request.model"
-      ]);
-      count("anomaly", { signal: "llm_excessive_tokens" });
-      emit({
-        signal: "llm_excessive_tokens",
-        tokens,
-        maxTokens: llm.maxTokensPerCall,
-        ...typeof model === "string" && { model }
-      });
-    }
-    const budget = llm.budget;
-    if (!budget) return;
-    const key = readAttribute(span.attributes, [
-      budget.keyAttribute,
-      "client.address"
-    ]);
-    if (typeof key !== "string" || key.length === 0) return;
-    const { before, after } = budget.window.record(key, now(), tokens);
-    if (before < budget.budget && after >= budget.budget) {
-      count("anomaly", { signal: "llm_token_budget_exceeded" });
-      emit({
-        signal: "llm_token_budget_exceeded",
-        key,
-        tokens: after,
-        budget: budget.budget,
-        windowMs: budget.windowMs
-      });
-    }
-  }
-  return {
-    onStart(span) {
-      if (!detect) return;
-      const target = readAttribute(span.attributes, TARGET_ATTRIBUTES);
-      if (typeof target !== "string" || target.length === 0) return;
-      for (const [name, pattern] of Object.entries(patterns)) {
-        if (!pattern.test(target)) continue;
-        span.setAttribute(SECURITY_ATTR.suspiciousRequest, true);
-        span.setAttribute(SECURITY_ATTR.signal, name);
-        if (forceKeep) {
-          span.setAttribute(AUTOTEL_SAMPLING_TAIL_EVALUATED, true);
-          span.setAttribute(AUTOTEL_SAMPLING_TAIL_KEEP, true);
-        }
-        count("suspicious", { pattern: name });
-        emit({ signal: "suspicious_request", pattern: name, target });
-        return;
-      }
-    },
-    onEnd(span) {
-      checkDeniedResponse(span);
-      checkLlmConsumption(span);
-    },
-    shutdown() {
-      return Promise.resolve();
-    },
-    forceFlush() {
-      return Promise.resolve();
-    }
-  };
+	const detect = options.detectSuspiciousRequests !== false;
+	const forceKeep = options.forceKeepSuspicious !== false;
+	const metricsEnabled = options.metrics !== false;
+	const deniedStatuses = new Set(options.deniedStatuses ?? SECURITY_DENIED_STATUSES);
+	const now = options.now ?? Date.now;
+	const patterns = {
+		...SUSPICIOUS_REQUEST_PATTERNS,
+		...options.extraPatterns
+	};
+	const burst = resolveBurstConfig(options.burst);
+	const llm = resolveLlmConfig(options.llm);
+	const counters = {
+		suspicious: lazyCounter(SECURITY_METRICS.httpSuspicious, "Requests matching suspicious-path patterns"),
+		denied: lazyCounter(SECURITY_METRICS.httpDenied, "HTTP responses with denied status codes (401/403/429)"),
+		anomaly: lazyCounter(SECURITY_METRICS.anomaly, "Security anomaly signals (e.g. auth-failure bursts)")
+	};
+	function count(which, attributes) {
+		if (!metricsEnabled) return;
+		counters[which].add(1, attributes);
+	}
+	function emit(signal) {
+		try {
+			options.onSignal?.(signal);
+		} catch {}
+	}
+	function checkDeniedResponse(span) {
+		const status = readAttribute(span.attributes, HTTP_STATUS_ATTRIBUTES);
+		if (typeof status !== "number" || !deniedStatuses.has(status)) return;
+		count("denied", { status });
+		if (!burst || !burst.statuses.has(status)) return;
+		const key = readAttribute(span.attributes, [burst.keyAttribute, "http.client_ip"]);
+		if (typeof key !== "string" || key.length === 0) return;
+		const { before, after } = burst.window.record(key, now());
+		if (before < burst.threshold && after >= burst.threshold) {
+			count("anomaly", {
+				signal: "auth_failure_burst",
+				status
+			});
+			emit({
+				signal: "auth_failure_burst",
+				key,
+				count: after,
+				windowMs: burst.windowMs,
+				status
+			});
+		}
+	}
+	function checkLlmConsumption(span) {
+		if (!llm) return;
+		const total = readAttribute(span.attributes, ["gen_ai.usage.total_tokens"]);
+		let tokens;
+		if (typeof total === "number") tokens = total;
+		else {
+			const input = readAttribute(span.attributes, ["gen_ai.usage.input_tokens"]);
+			const output = readAttribute(span.attributes, ["gen_ai.usage.output_tokens"]);
+			if (typeof input === "number" || typeof output === "number") tokens = (typeof input === "number" ? input : 0) + (typeof output === "number" ? output : 0);
+		}
+		if (tokens === void 0 || tokens <= 0) return;
+		if (llm.maxTokensPerCall !== void 0 && tokens > llm.maxTokensPerCall) {
+			const model = readAttribute(span.attributes, ["gen_ai.response.model", "gen_ai.request.model"]);
+			count("anomaly", { signal: "llm_excessive_tokens" });
+			emit({
+				signal: "llm_excessive_tokens",
+				tokens,
+				maxTokens: llm.maxTokensPerCall,
+				...typeof model === "string" && { model }
+			});
+		}
+		const budget = llm.budget;
+		if (!budget) return;
+		const key = readAttribute(span.attributes, [budget.keyAttribute, "client.address"]);
+		if (typeof key !== "string" || key.length === 0) return;
+		const { before, after } = budget.window.record(key, now(), tokens);
+		if (before < budget.budget && after >= budget.budget) {
+			count("anomaly", { signal: "llm_token_budget_exceeded" });
+			emit({
+				signal: "llm_token_budget_exceeded",
+				key,
+				tokens: after,
+				budget: budget.budget,
+				windowMs: budget.windowMs
+			});
+		}
+	}
+	return {
+		onStart(span) {
+			if (!detect) return;
+			const target = readAttribute(span.attributes, TARGET_ATTRIBUTES);
+			if (typeof target !== "string" || target.length === 0) return;
+			for (const [name, pattern] of Object.entries(patterns)) {
+				if (!pattern.test(target)) continue;
+				span.setAttribute(SECURITY_ATTR.suspiciousRequest, true);
+				span.setAttribute(SECURITY_ATTR.signal, name);
+				if (forceKeep) {
+					span.setAttribute(AUTOTEL_SAMPLING_TAIL_EVALUATED, true);
+					span.setAttribute(AUTOTEL_SAMPLING_TAIL_KEEP, true);
+				}
+				count("suspicious", { pattern: name });
+				emit({
+					signal: "suspicious_request",
+					pattern: name,
+					target
+				});
+				return;
+			}
+		},
+		onEnd(span) {
+			checkDeniedResponse(span);
+			checkLlmConsumption(span);
+		},
+		shutdown() {
+			return Promise.resolve();
+		},
+		forceFlush() {
+			return Promise.resolve();
+		}
+	};
 }
+
+//#endregion
+//#region src/security-heartbeat.ts
 function startSecurityHeartbeat(options = {}) {
-  const intervalMs = options.intervalMs ?? 6e4;
-  const attributes = options.attributes ?? {};
-  const counter = lazyCounter(
-    SECURITY_METRICS.heartbeat,
-    "Security-telemetry liveness signal \u2014 alert on its absence"
-  );
-  function beat() {
-    counter.add(1, attributes);
-  }
-  beat();
-  const timer = setInterval(beat, intervalMs);
-  timer.unref?.();
-  let stopped = false;
-  return {
-    stop() {
-      if (stopped) return;
-      stopped = true;
-      clearInterval(timer);
-    }
-  };
+	const intervalMs = options.intervalMs ?? 6e4;
+	const attributes = options.attributes ?? {};
+	const counter = lazyCounter(SECURITY_METRICS.heartbeat, "Security-telemetry liveness signal — alert on its absence");
+	function beat() {
+		counter.add(1, attributes);
+	}
+	beat();
+	const timer = setInterval(beat, intervalMs);
+	timer.unref?.();
+	let stopped = false;
+	return { stop() {
+		if (stopped) return;
+		stopped = true;
+		clearInterval(timer);
+	} };
 }
 
-// src/index.ts
+//#endregion
+//#region src/index.ts
 function flattenAuditAttributes(metadata) {
-  const attributes = {
-    "autotel.audit": true
-  };
-  for (const [key, value] of Object.entries(metadata)) {
-    const attr = toAttributeValue(value);
-    if (attr !== void 0) {
-      attributes[`audit.${key}`] = attr;
-    }
-  }
-  return attributes;
+	const attributes = { "autotel.audit": true };
+	for (const [key, value] of Object.entries(metadata)) {
+		const attr = toAttributeValue(value);
+		if (attr !== void 0) attributes[`audit.${key}`] = attr;
+	}
+	return attributes;
 }
 function forceKeepAuditEvent(ctx) {
-  const traceCtx = resolveContext(ctx);
-  traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_EVALUATED, true);
-  traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_KEEP, true);
-  traceCtx.setAttribute("autotel.audit.force_keep", true);
+	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);
 }
 function setAuditAttributes(metadata, ctx) {
-  const traceCtx = resolveContext(ctx);
-  traceCtx.setAttributes(flattenAuditAttributes(metadata));
+	const traceCtx = resolveContextSafe(ctx);
+	if (!traceCtx) return;
+	traceCtx.setAttributes(flattenAuditAttributes(metadata));
 }
 async function withAudit(metadata, fn, options = {}) {
-  const traceCtx = resolveContext(options.ctx);
-  if (options.forceKeep !== false) {
-    forceKeepAuditEvent(traceCtx);
-  }
-  setAuditAttributes(metadata, traceCtx);
-  const logger = options.logger ?? getRequestLogger();
-  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;
-  }
+	const traceCtx = resolveContextSafe(options.ctx);
+	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);
+	let logger = options.logger ?? getRequestLoggerSafe() ?? void 0;
+	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;
+	}
 }
 
+//#endregion
 export { SUSPICIOUS_REQUEST_PATTERNS, createSecuritySignalProcessor, forceKeepAuditEvent, hashIdentifier, securityEvent, setAuditAttributes, startSecurityHeartbeat, withAudit, withSecurity };
-//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map