autotel-audit 1.1.5 → 1.2.0

package/README.md

@@ -54,6 +54,21 @@ Wraps an async operation with audit metadata and handles success/failure outcome
   - `forceKeep?: boolean`: Force event through tail-sampling (default: true)
   - `ctx?: AuditContext`: Provide custom audit context (auto-resolved from trace if omitted)
   - `logger?: RequestLogger`: Override the request logger instance
+  - `onMissingContext?: 'throw' | 'warn' | 'skip'`: What to do when no trace context is active (see below)
+
+**Without an active trace context**, `withAudit` and `securityEvent` run your handler un-audited. `onMissingContext` sets how they report it:
+
+- `skip` is the default when telemetry is off: autotel `init()` has not run and no OpenTelemetry tracer provider is registered. Tests and local runs without a backend stay quiet.
+- `warn` is the default when telemetry is on and the call runs outside a span. You get one warning per action; wrap the call in `trace()`/`instrument()` or pass `ctx`.
+- `throw` fails fast. An explicit `onMissingContext` takes precedence over both defaults.
+
+Set a process-wide default with `configureAudit`. A per-call option overrides it:
+
+```ts
+import { configureAudit } from 'autotel-audit';
+
+configureAudit({ onMissingContext: 'throw' });
+```
 
 **Example with custom context:**
 

package/dist/index.cjs

@@ -26,6 +26,18 @@ function resolveContextSafe(ctx) {
 		setAttributes: (attrs) => span.setAttributes(attrs)
 	};
 }
+let defaultOnMissingContext;
+/**
+* Process-wide defaults. A per-call `onMissingContext` still wins; pass
+* `undefined` to restore the built-in default.
+*/
+function configureAudit(options) {
+	defaultOnMissingContext = options.onMissingContext;
+}
+/** Per-call option, then configureAudit(), then skip-if-telemetry-off-else-warn. */
+function resolveOnMissingContext(explicit) {
+	return explicit ?? defaultOnMissingContext ?? ((0, autotel.isInitialized)() || (0, autotel.hasTracerProvider)() ? "warn" : "skip");
+}
 /** A no-op {@link AuditContext} whose attribute setters do nothing. */
 function noopAuditContext() {
 	return {
@@ -166,7 +178,7 @@ function securityEvent(metadata, options = {}) {
 	const traceCtx = resolveContextSafe(options.ctx);
 	if (options.metrics !== false) countSecurityEvent(metadata);
 	if (!traceCtx) {
-		const mode = options.onMissingContext ?? "warn";
+		const mode = resolveOnMissingContext(options.onMissingContext);
 		if (mode === "throw") throw new Error(MISSING_CONTEXT_MESSAGE);
 		if (mode === "warn") warnMissingContextOnce(metadata.name);
 		return;
@@ -598,7 +610,7 @@ function setAuditAttributes(metadata, ctx) {
 async function withAudit(metadata, fn, options = {}) {
 	const traceCtx = resolveContextSafe(options.ctx);
 	if (!traceCtx) {
-		const mode = options.onMissingContext ?? "warn";
+		const mode = resolveOnMissingContext(options.onMissingContext);
 		if (mode === "throw") throw new Error(MISSING_CONTEXT_MESSAGE);
 		if (mode === "warn") warnMissingContextOnce(metadata.action);
 		return fn(noopAuditContext(), options.logger ?? (0, autotel.createNoopRequestLogger)());
@@ -607,7 +619,7 @@ async function withAudit(metadata, fn, options = {}) {
 	setAuditAttributes(metadata, traceCtx);
 	let logger = options.logger ?? (0, autotel.getRequestLoggerSafe)() ?? void 0;
 	if (!logger) {
-		if ((options.onMissingContext ?? "warn") === "warn") warnMissingLoggerOnce(metadata.action);
+		if (resolveOnMissingContext(options.onMissingContext) === "warn") warnMissingLoggerOnce(metadata.action);
 		logger = (0, autotel.createNoopRequestLogger)();
 	}
 	logger.set({ audit: {
@@ -640,6 +652,7 @@ async function withAudit(metadata, fn, options = {}) {
 //#endregion
 exports.SUSPICIOUS_REQUEST_PATTERNS = SUSPICIOUS_REQUEST_PATTERNS;
 exports.applySecurityEventAttributes = applySecurityEventAttributes;
+exports.configureAudit = configureAudit;
 exports.createMcpSecurityEventBridge = createMcpSecurityEventBridge;
 exports.createSecuritySignalProcessor = createSecuritySignalProcessor;
 exports.forceKeepAuditEvent = forceKeepAuditEvent;

package/dist/index.d.cts

@@ -12,29 +12,38 @@ interface AuditContext {
  * 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).
+ * - `warn` — run the wrapped handler un-audited and log one warning per action.
  * - `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`).
+ * logic it wraps, so the default is best-effort: `skip` when telemetry is off
+ * (no autotel init(), no tracer provider: nothing could be recorded anyway),
+ * `warn` otherwise.
  */
 type OnMissingContext = 'throw' | 'warn' | 'skip';
+/**
+ * Process-wide defaults. A per-call `onMissingContext` still wins; pass
+ * `undefined` to restore the built-in default.
+ */
+export declare function configureAudit(options: {
+  onMissingContext?: OnMissingContext;
+}): void;
 //#endregion
 //#region src/security.d.ts
 /**
  * Security event categories, aligned with OWASP A09:2025
  * (Security Logging & Alerting Failures) and ASVS V7.
  */
-type SecurityEventCategory = 'authentication' | 'authorization' | 'data_access' | 'admin_action' | 'configuration' | 'secrets' | 'rate_limit' | 'validation' | 'supply_chain' | 'llm';
-type SecurityOutcome = 'success' | 'failure' | 'denied' | 'blocked' | 'error';
+export type SecurityEventCategory = 'authentication' | 'authorization' | 'data_access' | 'admin_action' | 'configuration' | 'secrets' | 'rate_limit' | 'validation' | 'supply_chain' | 'llm';
+export type SecurityOutcome = 'success' | 'failure' | 'denied' | 'blocked' | 'error';
 /**
  * Well-known security event names. Free-form names are allowed —
  * this union exists for autocomplete and consistency across services.
  */
-type SuggestedSecurityEventName = 'auth.login.success' | 'auth.login.failed' | 'auth.mfa.failed' | 'auth.session.revoked' | 'auth.password.reset' | 'auth.account.locked' | 'access.denied' | 'access.role.changed' | 'access.permission.changed' | 'access.tenant.violation' | 'admin.action' | 'config.changed' | 'secret.accessed' | 'secret.rotation.failed' | 'api_key.created' | 'api_key.revoked' | 'rate_limit.exceeded' | 'validation.failed' | 'webhook.signature.failed' | 'dependency.scan.failed' | 'llm.prompt_injection.detected' | 'llm.tool_call.denied' | 'llm.output.blocked' | 'llm.output.budget_exceeded' | 'llm.guard.triggered' | 'llm.action_chain.suspicious' | 'llm.manifest.suspicious' | 'llm.plan.risk.elevated';
+export type SuggestedSecurityEventName = 'auth.login.success' | 'auth.login.failed' | 'auth.mfa.failed' | 'auth.session.revoked' | 'auth.password.reset' | 'auth.account.locked' | 'access.denied' | 'access.role.changed' | 'access.permission.changed' | 'access.tenant.violation' | 'admin.action' | 'config.changed' | 'secret.accessed' | 'secret.rotation.failed' | 'api_key.created' | 'api_key.revoked' | 'rate_limit.exceeded' | 'validation.failed' | 'webhook.signature.failed' | 'dependency.scan.failed' | 'llm.prompt_injection.detected' | 'llm.tool_call.denied' | 'llm.output.blocked' | 'llm.output.budget_exceeded' | 'llm.guard.triggered' | 'llm.action_chain.suspicious' | 'llm.manifest.suspicious' | 'llm.plan.risk.elevated';
 /** An attribute value, as OpenTelemetry allows one on a span. */
-type SecurityAttributeValue = string | number | boolean | string[] | number[] | boolean[];
-interface SecurityEventMetadata {
+export type SecurityAttributeValue = string | number | boolean | string[] | number[] | boolean[];
+export interface SecurityEventMetadata {
   /** Stable, dot-separated event name, e.g. `auth.login.failed`. */
   name: SuggestedSecurityEventName | (string & {});
   category: SecurityEventCategory;
@@ -51,7 +60,7 @@ interface SecurityEventMetadata {
   /** Extra fields ride along as span attributes; see AuditMetadataValue. */
   [key: string]: AuditMetadataValue;
 }
-interface SecurityEventOptions {
+export interface SecurityEventOptions {
   ctx?: AuditContext;
   /**
    * Security events are exempt from tail sampling by default —
@@ -71,17 +80,17 @@ interface SecurityEventOptions {
    */
   metrics?: boolean;
   /**
-   * Behaviour when no trace context can be resolved. Defaults to `warn`
-   * (best-effort: record nothing, warn once). A dropped security event is still
-   * better than a crashed request — but the warning makes the gap visible.
+   * Behaviour when no trace context can be resolved. Defaults to the
+   * configureAudit() value, else `skip` when telemetry is off and `warn`
+   * (once per event) otherwise. See {@link OnMissingContext}.
    */
   onMissingContext?: OnMissingContext;
 }
-type WithSecurityOptions = SecurityEventOptions;
+export type WithSecurityOptions = SecurityEventOptions;
 interface SecurityAttributeSink {
   setAttribute(key: string, value: SecurityAttributeValue): void;
 }
-declare function applySecurityEventAttributes(sink: SecurityAttributeSink, metadata: SecurityEventMetadata, options?: Pick<SecurityEventOptions, 'forceKeep' | 'metrics'>): void;
+export declare function applySecurityEventAttributes(sink: SecurityAttributeSink, metadata: SecurityEventMetadata, options?: Pick<SecurityEventOptions, 'forceKeep' | 'metrics'>): void;
 /**
  * Record a security event on the active trace and request logger.
  *
@@ -101,7 +110,7 @@ declare function applySecurityEventAttributes(sink: SecurityAttributeSink, metad
  * });
  * ```
  */
-declare function securityEvent(metadata: SecurityEventMetadata, options?: SecurityEventOptions): void;
+export declare function securityEvent(metadata: SecurityEventMetadata, options?: SecurityEventOptions): void;
 /**
  * Wrap a security-sensitive operation. On success the event outcome is
  * recorded as given (default `success`); a thrown error records
@@ -115,8 +124,8 @@ declare function securityEvent(metadata: SecurityEventMetadata, options?: Securi
  * );
  * ```
  */
-declare function withSecurity<T>(metadata: SecurityEventMetadata, fn: (ctx: AuditContext, logger: RequestLogger) => T | Promise<T>, options?: WithSecurityOptions): Promise<T>;
-interface HashIdentifierOptions {
+export declare function withSecurity<T>(metadata: SecurityEventMetadata, fn: (ctx: AuditContext, logger: RequestLogger) => T | Promise<T>, options?: WithSecurityOptions): Promise<T>;
+export interface HashIdentifierOptions {
   /** Optional salt; use one stable per-deployment salt to defeat rainbow lookups. */
   salt?: string;
   /** Digest length in hex chars (default 16). */
@@ -128,7 +137,7 @@ interface HashIdentifierOptions {
  *
  * NOT for secrets — never log secrets in any form, hashed or not.
  */
-declare function hashIdentifier(value: string, options?: HashIdentifierOptions): string;
+export declare function hashIdentifier(value: string, options?: HashIdentifierOptions): string;
 //#endregion
 //#region src/security-signals.d.ts
 /**
@@ -155,13 +164,13 @@ declare function hashIdentifier(value: string, options?: HashIdentifierOptions):
  * observability backend — this processor's job is to make the signals
  * exist, survive sampling, and stay queryable under a stable schema.
  */
-type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
+export type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
 /** The parent context OTel hands a processor. This package never reads it. */
-interface SpanParentContext {
+export interface SpanParentContext {
   getValue?: (key: symbol) => ContextValue;
 }
 /** Whatever OTel stored under a context key. This package never reads one. */
-type ContextValue = object | string | number | boolean | undefined;
+export type ContextValue = object | string | number | boolean | undefined;
 interface MutableSpanLike {
   attributes: Record<string, AttributeValue | undefined>;
   spanContext?: {
@@ -175,20 +184,20 @@ interface ReadableSpanLike {
     traceId: string;
   };
 }
-interface SecuritySignalProcessor {
+export interface SecuritySignalProcessor {
   onStart(span: MutableSpanLike, parentContext?: SpanParentContext): void;
   onEnd(span: ReadableSpanLike): void;
   shutdown(): Promise<void>;
   forceFlush(): Promise<void>;
 }
-interface SuspiciousRequestSignal {
+export interface SuspiciousRequestSignal {
   signal: 'suspicious_request';
   /** Which pattern matched, e.g. `path_traversal`. */
   pattern: string;
   /** The matched request path/URL (as found on the span). */
   target: string;
 }
-interface AuthFailureBurstSignal {
+export interface AuthFailureBurstSignal {
   signal: 'auth_failure_burst';
   /** Value of the configured key attribute (e.g. client address). */
   key: string;
@@ -197,14 +206,14 @@ interface AuthFailureBurstSignal {
   windowMs: number;
   status: number;
 }
-interface LlmExcessiveTokensSignal {
+export interface LlmExcessiveTokensSignal {
   signal: 'llm_excessive_tokens';
   /** Total tokens consumed by the single LLM call. */
   tokens: number;
   maxTokens: number;
   model?: string;
 }
-interface LlmTokenBudgetSignal {
+export interface LlmTokenBudgetSignal {
   signal: 'llm_token_budget_exceeded';
   /** Value of the configured key attribute (e.g. end-user id). */
   key: string;
@@ -213,7 +222,7 @@ interface LlmTokenBudgetSignal {
   budget: number;
   windowMs: number;
 }
-interface LlmActionChainSuspiciousSignal {
+export interface LlmActionChainSuspiciousSignal {
   signal: 'llm_action_chain_suspicious';
   /** Trace where the suspicious chain was observed. */
   traceId: string;
@@ -223,8 +232,8 @@ interface LlmActionChainSuspiciousSignal {
   elapsedMs: number;
   untrustedTool?: string;
 }
-type SecuritySignal = SuspiciousRequestSignal | AuthFailureBurstSignal | LlmExcessiveTokensSignal | LlmTokenBudgetSignal | LlmActionChainSuspiciousSignal;
-interface BurstOptions {
+export type SecuritySignal = SuspiciousRequestSignal | AuthFailureBurstSignal | LlmExcessiveTokensSignal | LlmTokenBudgetSignal | LlmActionChainSuspiciousSignal;
+export interface BurstOptions {
   /** HTTP statuses counted toward a burst. Default `[401, 403]`. */
   statuses?: number[];
   /** Denied responses within the window that trigger a signal. Default 10. */
@@ -239,7 +248,7 @@ interface BurstOptions {
   /** Max distinct clients tracked (oldest evicted). Default 10_000. */
   maxKeys?: number;
 }
-interface LlmSignalOptions {
+export interface LlmSignalOptions {
   /**
    * Single-call token ceiling (`gen_ai.usage.total_tokens`, or input+output).
    * Default 100_000. Pass `false` to disable the per-call check.
@@ -263,7 +272,7 @@ interface LlmSignalOptions {
     maxKeys?: number;
   };
 }
-interface SecuritySignalProcessorOptions {
+export interface SecuritySignalProcessorOptions {
   /** Flag suspicious request paths on span start. Default true. */
   detectSuspiciousRequests?: boolean;
   /** Additional name → pattern pairs checked against the request target. */
@@ -298,14 +307,14 @@ interface SecuritySignalProcessorOptions {
  * Conservative request-target patterns. Tuned for scanner/probe traffic —
  * high signal, low false-positive — not as a WAF. Extend via `extraPatterns`.
  */
-declare const SUSPICIOUS_REQUEST_PATTERNS: {
+export declare const SUSPICIOUS_REQUEST_PATTERNS: {
   path_traversal: RegExp;
   sensitive_file_probe: RegExp;
   sqli_probe: RegExp;
   xss_probe: RegExp;
   null_byte: RegExp;
 };
-declare function createSecuritySignalProcessor(options?: SecuritySignalProcessorOptions): SecuritySignalProcessor;
+export declare function createSecuritySignalProcessor(options?: SecuritySignalProcessorOptions): SecuritySignalProcessor;
 //#endregion
 //#region src/security-heartbeat.d.ts
 /**
@@ -327,16 +336,16 @@ declare function createSecuritySignalProcessor(options?: SecuritySignalProcessor
  * heartbeat.stop();
  * ```
  */
-interface SecurityHeartbeatOptions {
+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>;
 }
-interface SecurityHeartbeat {
+export interface SecurityHeartbeat {
   stop(): void;
 }
-declare function startSecurityHeartbeat(options?: SecurityHeartbeatOptions): SecurityHeartbeat;
+export declare function startSecurityHeartbeat(options?: SecurityHeartbeatOptions): SecurityHeartbeat;
 //#endregion
 //#region src/mcp-bridge.d.ts
 /**
@@ -344,7 +353,7 @@ declare function startSecurityHeartbeat(options?: SecurityHeartbeatOptions): Sec
  * unified `security.*` schema. Used by `autotel-mcp-instrumentation` when
  * `bridgeSecurityEvents` is enabled.
  */
-interface McpBridgedSecurityEvent {
+export interface McpBridgedSecurityEvent {
   name: SecurityEventMetadata['name'];
   category: 'llm';
   outcome: SecurityEventMetadata['outcome'];
@@ -356,7 +365,7 @@ interface McpBridgedSecurityEvent {
   /** Extra fields ride along as span attributes; see AuditMetadataValue. */
   [key: string]: AuditMetadataValue;
 }
-interface McpSecurityEventBridgeOptions extends SecurityEventOptions {
+export interface McpSecurityEventBridgeOptions extends SecurityEventOptions {
   /** Optional fixed audit context for bridged events. */
   ctx?: AuditContext;
 }
@@ -375,10 +384,10 @@ interface McpSecurityEventBridgeOptions extends SecurityEventOptions {
  * });
  * ```
  */
-declare function createMcpSecurityEventBridge(options?: McpSecurityEventBridgeOptions): (metadata: McpBridgedSecurityEvent) => void;
+export declare function createMcpSecurityEventBridge(options?: McpSecurityEventBridgeOptions): (metadata: McpBridgedSecurityEvent) => void;
 //#endregion
 //#region src/index.d.ts
-interface AuditMetadata {
+export interface AuditMetadata {
   action: string;
   resource?: string;
   actorId?: string;
@@ -392,22 +401,23 @@ interface AuditMetadata {
  * span. Scalars and scalar arrays pass through; a Date becomes an ISO string;
  * anything else nested is JSON-serialized.
  */
-type AuditMetadataValue = string | number | boolean | null | undefined | Date | Array<AuditMetadataValue> | {
+export type AuditMetadataValue = string | number | boolean | null | undefined | Date | Array<AuditMetadataValue> | {
   [key: string]: AuditMetadataValue;
 };
-interface WithAuditOptions {
+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}.
+   * Behaviour when no trace context can be resolved. Defaults to the
+   * configureAudit() value, else `skip` when telemetry is off and `warn`
+   * otherwise. See {@link OnMissingContext}.
    */
   onMissingContext?: OnMissingContext;
 }
-declare function forceKeepAuditEvent(ctx?: AuditContext): void;
-declare function setAuditAttributes(metadata: AuditMetadata, ctx?: AuditContext): void;
-declare function withAudit<T>(metadata: AuditMetadata, fn: (ctx: AuditContext, logger: RequestLogger) => T | Promise<T>, options?: WithAuditOptions): Promise<T>;
+export declare function forceKeepAuditEvent(ctx?: AuditContext): void;
+export declare function setAuditAttributes(metadata: AuditMetadata, ctx?: AuditContext): void;
+export declare function withAudit<T>(metadata: AuditMetadata, fn: (ctx: AuditContext, logger: RequestLogger) => T | Promise<T>, options?: WithAuditOptions): Promise<T>;
 //#endregion
-export { AttributeValue, type AuditContext, AuditMetadata, AuditMetadataValue, AuthFailureBurstSignal, BurstOptions, ContextValue, HashIdentifierOptions, LlmActionChainSuspiciousSignal, LlmExcessiveTokensSignal, LlmSignalOptions, LlmTokenBudgetSignal, McpBridgedSecurityEvent, McpSecurityEventBridgeOptions, type OnMissingContext, SUSPICIOUS_REQUEST_PATTERNS, SecurityAttributeValue, SecurityEventCategory, SecurityEventMetadata, SecurityEventOptions, SecurityHeartbeat, SecurityHeartbeatOptions, SecurityOutcome, type SecuritySeverity, SecuritySignal, SecuritySignalProcessor, SecuritySignalProcessorOptions, SpanParentContext, SuggestedSecurityEventName, SuspiciousRequestSignal, WithAuditOptions, WithSecurityOptions, applySecurityEventAttributes, createMcpSecurityEventBridge, createSecuritySignalProcessor, forceKeepAuditEvent, hashIdentifier, securityEvent, setAuditAttributes, startSecurityHeartbeat, withAudit, withSecurity };
+export type { AuditContext, OnMissingContext, SecuritySeverity };

package/dist/index.d.ts

@@ -12,29 +12,38 @@ interface AuditContext {
  * 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).
+ * - `warn` — run the wrapped handler un-audited and log one warning per action.
  * - `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`).
+ * logic it wraps, so the default is best-effort: `skip` when telemetry is off
+ * (no autotel init(), no tracer provider: nothing could be recorded anyway),
+ * `warn` otherwise.
  */
 type OnMissingContext = 'throw' | 'warn' | 'skip';
+/**
+ * Process-wide defaults. A per-call `onMissingContext` still wins; pass
+ * `undefined` to restore the built-in default.
+ */
+export declare function configureAudit(options: {
+  onMissingContext?: OnMissingContext;
+}): void;
 //#endregion
 //#region src/security.d.ts
 /**
  * Security event categories, aligned with OWASP A09:2025
  * (Security Logging & Alerting Failures) and ASVS V7.
  */
-type SecurityEventCategory = 'authentication' | 'authorization' | 'data_access' | 'admin_action' | 'configuration' | 'secrets' | 'rate_limit' | 'validation' | 'supply_chain' | 'llm';
-type SecurityOutcome = 'success' | 'failure' | 'denied' | 'blocked' | 'error';
+export type SecurityEventCategory = 'authentication' | 'authorization' | 'data_access' | 'admin_action' | 'configuration' | 'secrets' | 'rate_limit' | 'validation' | 'supply_chain' | 'llm';
+export type SecurityOutcome = 'success' | 'failure' | 'denied' | 'blocked' | 'error';
 /**
  * Well-known security event names. Free-form names are allowed —
  * this union exists for autocomplete and consistency across services.
  */
-type SuggestedSecurityEventName = 'auth.login.success' | 'auth.login.failed' | 'auth.mfa.failed' | 'auth.session.revoked' | 'auth.password.reset' | 'auth.account.locked' | 'access.denied' | 'access.role.changed' | 'access.permission.changed' | 'access.tenant.violation' | 'admin.action' | 'config.changed' | 'secret.accessed' | 'secret.rotation.failed' | 'api_key.created' | 'api_key.revoked' | 'rate_limit.exceeded' | 'validation.failed' | 'webhook.signature.failed' | 'dependency.scan.failed' | 'llm.prompt_injection.detected' | 'llm.tool_call.denied' | 'llm.output.blocked' | 'llm.output.budget_exceeded' | 'llm.guard.triggered' | 'llm.action_chain.suspicious' | 'llm.manifest.suspicious' | 'llm.plan.risk.elevated';
+export type SuggestedSecurityEventName = 'auth.login.success' | 'auth.login.failed' | 'auth.mfa.failed' | 'auth.session.revoked' | 'auth.password.reset' | 'auth.account.locked' | 'access.denied' | 'access.role.changed' | 'access.permission.changed' | 'access.tenant.violation' | 'admin.action' | 'config.changed' | 'secret.accessed' | 'secret.rotation.failed' | 'api_key.created' | 'api_key.revoked' | 'rate_limit.exceeded' | 'validation.failed' | 'webhook.signature.failed' | 'dependency.scan.failed' | 'llm.prompt_injection.detected' | 'llm.tool_call.denied' | 'llm.output.blocked' | 'llm.output.budget_exceeded' | 'llm.guard.triggered' | 'llm.action_chain.suspicious' | 'llm.manifest.suspicious' | 'llm.plan.risk.elevated';
 /** An attribute value, as OpenTelemetry allows one on a span. */
-type SecurityAttributeValue = string | number | boolean | string[] | number[] | boolean[];
-interface SecurityEventMetadata {
+export type SecurityAttributeValue = string | number | boolean | string[] | number[] | boolean[];
+export interface SecurityEventMetadata {
   /** Stable, dot-separated event name, e.g. `auth.login.failed`. */
   name: SuggestedSecurityEventName | (string & {});
   category: SecurityEventCategory;
@@ -51,7 +60,7 @@ interface SecurityEventMetadata {
   /** Extra fields ride along as span attributes; see AuditMetadataValue. */
   [key: string]: AuditMetadataValue;
 }
-interface SecurityEventOptions {
+export interface SecurityEventOptions {
   ctx?: AuditContext;
   /**
    * Security events are exempt from tail sampling by default —
@@ -71,17 +80,17 @@ interface SecurityEventOptions {
    */
   metrics?: boolean;
   /**
-   * Behaviour when no trace context can be resolved. Defaults to `warn`
-   * (best-effort: record nothing, warn once). A dropped security event is still
-   * better than a crashed request — but the warning makes the gap visible.
+   * Behaviour when no trace context can be resolved. Defaults to the
+   * configureAudit() value, else `skip` when telemetry is off and `warn`
+   * (once per event) otherwise. See {@link OnMissingContext}.
    */
   onMissingContext?: OnMissingContext;
 }
-type WithSecurityOptions = SecurityEventOptions;
+export type WithSecurityOptions = SecurityEventOptions;
 interface SecurityAttributeSink {
   setAttribute(key: string, value: SecurityAttributeValue): void;
 }
-declare function applySecurityEventAttributes(sink: SecurityAttributeSink, metadata: SecurityEventMetadata, options?: Pick<SecurityEventOptions, 'forceKeep' | 'metrics'>): void;
+export declare function applySecurityEventAttributes(sink: SecurityAttributeSink, metadata: SecurityEventMetadata, options?: Pick<SecurityEventOptions, 'forceKeep' | 'metrics'>): void;
 /**
  * Record a security event on the active trace and request logger.
  *
@@ -101,7 +110,7 @@ declare function applySecurityEventAttributes(sink: SecurityAttributeSink, metad
  * });
  * ```
  */
-declare function securityEvent(metadata: SecurityEventMetadata, options?: SecurityEventOptions): void;
+export declare function securityEvent(metadata: SecurityEventMetadata, options?: SecurityEventOptions): void;
 /**
  * Wrap a security-sensitive operation. On success the event outcome is
  * recorded as given (default `success`); a thrown error records
@@ -115,8 +124,8 @@ declare function securityEvent(metadata: SecurityEventMetadata, options?: Securi
  * );
  * ```
  */
-declare function withSecurity<T>(metadata: SecurityEventMetadata, fn: (ctx: AuditContext, logger: RequestLogger) => T | Promise<T>, options?: WithSecurityOptions): Promise<T>;
-interface HashIdentifierOptions {
+export declare function withSecurity<T>(metadata: SecurityEventMetadata, fn: (ctx: AuditContext, logger: RequestLogger) => T | Promise<T>, options?: WithSecurityOptions): Promise<T>;
+export interface HashIdentifierOptions {
   /** Optional salt; use one stable per-deployment salt to defeat rainbow lookups. */
   salt?: string;
   /** Digest length in hex chars (default 16). */
@@ -128,7 +137,7 @@ interface HashIdentifierOptions {
  *
  * NOT for secrets — never log secrets in any form, hashed or not.
  */
-declare function hashIdentifier(value: string, options?: HashIdentifierOptions): string;
+export declare function hashIdentifier(value: string, options?: HashIdentifierOptions): string;
 //#endregion
 //#region src/security-signals.d.ts
 /**
@@ -155,13 +164,13 @@ declare function hashIdentifier(value: string, options?: HashIdentifierOptions):
  * observability backend — this processor's job is to make the signals
  * exist, survive sampling, and stay queryable under a stable schema.
  */
-type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
+export type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
 /** The parent context OTel hands a processor. This package never reads it. */
-interface SpanParentContext {
+export interface SpanParentContext {
   getValue?: (key: symbol) => ContextValue;
 }
 /** Whatever OTel stored under a context key. This package never reads one. */
-type ContextValue = object | string | number | boolean | undefined;
+export type ContextValue = object | string | number | boolean | undefined;
 interface MutableSpanLike {
   attributes: Record<string, AttributeValue | undefined>;
   spanContext?: {
@@ -175,20 +184,20 @@ interface ReadableSpanLike {
     traceId: string;
   };
 }
-interface SecuritySignalProcessor {
+export interface SecuritySignalProcessor {
   onStart(span: MutableSpanLike, parentContext?: SpanParentContext): void;
   onEnd(span: ReadableSpanLike): void;
   shutdown(): Promise<void>;
   forceFlush(): Promise<void>;
 }
-interface SuspiciousRequestSignal {
+export interface SuspiciousRequestSignal {
   signal: 'suspicious_request';
   /** Which pattern matched, e.g. `path_traversal`. */
   pattern: string;
   /** The matched request path/URL (as found on the span). */
   target: string;
 }
-interface AuthFailureBurstSignal {
+export interface AuthFailureBurstSignal {
   signal: 'auth_failure_burst';
   /** Value of the configured key attribute (e.g. client address). */
   key: string;
@@ -197,14 +206,14 @@ interface AuthFailureBurstSignal {
   windowMs: number;
   status: number;
 }
-interface LlmExcessiveTokensSignal {
+export interface LlmExcessiveTokensSignal {
   signal: 'llm_excessive_tokens';
   /** Total tokens consumed by the single LLM call. */
   tokens: number;
   maxTokens: number;
   model?: string;
 }
-interface LlmTokenBudgetSignal {
+export interface LlmTokenBudgetSignal {
   signal: 'llm_token_budget_exceeded';
   /** Value of the configured key attribute (e.g. end-user id). */
   key: string;
@@ -213,7 +222,7 @@ interface LlmTokenBudgetSignal {
   budget: number;
   windowMs: number;
 }
-interface LlmActionChainSuspiciousSignal {
+export interface LlmActionChainSuspiciousSignal {
   signal: 'llm_action_chain_suspicious';
   /** Trace where the suspicious chain was observed. */
   traceId: string;
@@ -223,8 +232,8 @@ interface LlmActionChainSuspiciousSignal {
   elapsedMs: number;
   untrustedTool?: string;
 }
-type SecuritySignal = SuspiciousRequestSignal | AuthFailureBurstSignal | LlmExcessiveTokensSignal | LlmTokenBudgetSignal | LlmActionChainSuspiciousSignal;
-interface BurstOptions {
+export type SecuritySignal = SuspiciousRequestSignal | AuthFailureBurstSignal | LlmExcessiveTokensSignal | LlmTokenBudgetSignal | LlmActionChainSuspiciousSignal;
+export interface BurstOptions {
   /** HTTP statuses counted toward a burst. Default `[401, 403]`. */
   statuses?: number[];
   /** Denied responses within the window that trigger a signal. Default 10. */
@@ -239,7 +248,7 @@ interface BurstOptions {
   /** Max distinct clients tracked (oldest evicted). Default 10_000. */
   maxKeys?: number;
 }
-interface LlmSignalOptions {
+export interface LlmSignalOptions {
   /**
    * Single-call token ceiling (`gen_ai.usage.total_tokens`, or input+output).
    * Default 100_000. Pass `false` to disable the per-call check.
@@ -263,7 +272,7 @@ interface LlmSignalOptions {
     maxKeys?: number;
   };
 }
-interface SecuritySignalProcessorOptions {
+export interface SecuritySignalProcessorOptions {
   /** Flag suspicious request paths on span start. Default true. */
   detectSuspiciousRequests?: boolean;
   /** Additional name → pattern pairs checked against the request target. */
@@ -298,14 +307,14 @@ interface SecuritySignalProcessorOptions {
  * Conservative request-target patterns. Tuned for scanner/probe traffic —
  * high signal, low false-positive — not as a WAF. Extend via `extraPatterns`.
  */
-declare const SUSPICIOUS_REQUEST_PATTERNS: {
+export declare const SUSPICIOUS_REQUEST_PATTERNS: {
   path_traversal: RegExp;
   sensitive_file_probe: RegExp;
   sqli_probe: RegExp;
   xss_probe: RegExp;
   null_byte: RegExp;
 };
-declare function createSecuritySignalProcessor(options?: SecuritySignalProcessorOptions): SecuritySignalProcessor;
+export declare function createSecuritySignalProcessor(options?: SecuritySignalProcessorOptions): SecuritySignalProcessor;
 //#endregion
 //#region src/security-heartbeat.d.ts
 /**
@@ -327,16 +336,16 @@ declare function createSecuritySignalProcessor(options?: SecuritySignalProcessor
  * heartbeat.stop();
  * ```
  */
-interface SecurityHeartbeatOptions {
+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>;
 }
-interface SecurityHeartbeat {
+export interface SecurityHeartbeat {
   stop(): void;
 }
-declare function startSecurityHeartbeat(options?: SecurityHeartbeatOptions): SecurityHeartbeat;
+export declare function startSecurityHeartbeat(options?: SecurityHeartbeatOptions): SecurityHeartbeat;
 //#endregion
 //#region src/mcp-bridge.d.ts
 /**
@@ -344,7 +353,7 @@ declare function startSecurityHeartbeat(options?: SecurityHeartbeatOptions): Sec
  * unified `security.*` schema. Used by `autotel-mcp-instrumentation` when
  * `bridgeSecurityEvents` is enabled.
  */
-interface McpBridgedSecurityEvent {
+export interface McpBridgedSecurityEvent {
   name: SecurityEventMetadata['name'];
   category: 'llm';
   outcome: SecurityEventMetadata['outcome'];
@@ -356,7 +365,7 @@ interface McpBridgedSecurityEvent {
   /** Extra fields ride along as span attributes; see AuditMetadataValue. */
   [key: string]: AuditMetadataValue;
 }
-interface McpSecurityEventBridgeOptions extends SecurityEventOptions {
+export interface McpSecurityEventBridgeOptions extends SecurityEventOptions {
   /** Optional fixed audit context for bridged events. */
   ctx?: AuditContext;
 }
@@ -375,10 +384,10 @@ interface McpSecurityEventBridgeOptions extends SecurityEventOptions {
  * });
  * ```
  */
-declare function createMcpSecurityEventBridge(options?: McpSecurityEventBridgeOptions): (metadata: McpBridgedSecurityEvent) => void;
+export declare function createMcpSecurityEventBridge(options?: McpSecurityEventBridgeOptions): (metadata: McpBridgedSecurityEvent) => void;
 //#endregion
 //#region src/index.d.ts
-interface AuditMetadata {
+export interface AuditMetadata {
   action: string;
   resource?: string;
   actorId?: string;
@@ -392,22 +401,23 @@ interface AuditMetadata {
  * span. Scalars and scalar arrays pass through; a Date becomes an ISO string;
  * anything else nested is JSON-serialized.
  */
-type AuditMetadataValue = string | number | boolean | null | undefined | Date | Array<AuditMetadataValue> | {
+export type AuditMetadataValue = string | number | boolean | null | undefined | Date | Array<AuditMetadataValue> | {
   [key: string]: AuditMetadataValue;
 };
-interface WithAuditOptions {
+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}.
+   * Behaviour when no trace context can be resolved. Defaults to the
+   * configureAudit() value, else `skip` when telemetry is off and `warn`
+   * otherwise. See {@link OnMissingContext}.
    */
   onMissingContext?: OnMissingContext;
 }
-declare function forceKeepAuditEvent(ctx?: AuditContext): void;
-declare function setAuditAttributes(metadata: AuditMetadata, ctx?: AuditContext): void;
-declare function withAudit<T>(metadata: AuditMetadata, fn: (ctx: AuditContext, logger: RequestLogger) => T | Promise<T>, options?: WithAuditOptions): Promise<T>;
+export declare function forceKeepAuditEvent(ctx?: AuditContext): void;
+export declare function setAuditAttributes(metadata: AuditMetadata, ctx?: AuditContext): void;
+export declare function withAudit<T>(metadata: AuditMetadata, fn: (ctx: AuditContext, logger: RequestLogger) => T | Promise<T>, options?: WithAuditOptions): Promise<T>;
 //#endregion
-export { AttributeValue, type AuditContext, AuditMetadata, AuditMetadataValue, AuthFailureBurstSignal, BurstOptions, ContextValue, HashIdentifierOptions, LlmActionChainSuspiciousSignal, LlmExcessiveTokensSignal, LlmSignalOptions, LlmTokenBudgetSignal, McpBridgedSecurityEvent, McpSecurityEventBridgeOptions, type OnMissingContext, SUSPICIOUS_REQUEST_PATTERNS, SecurityAttributeValue, SecurityEventCategory, SecurityEventMetadata, SecurityEventOptions, SecurityHeartbeat, SecurityHeartbeatOptions, SecurityOutcome, type SecuritySeverity, SecuritySignal, SecuritySignalProcessor, SecuritySignalProcessorOptions, SpanParentContext, SuggestedSecurityEventName, SuspiciousRequestSignal, WithAuditOptions, WithSecurityOptions, applySecurityEventAttributes, createMcpSecurityEventBridge, createSecuritySignalProcessor, forceKeepAuditEvent, hashIdentifier, securityEvent, setAuditAttributes, startSecurityHeartbeat, withAudit, withSecurity };
+export type { AuditContext, OnMissingContext, SecuritySeverity };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, REDACTOR_PATTERNS, createCounter, createNoopRequestLogger, forceKeep, getRequestLoggerSafe, getTraceContext, otelTrace } from "autotel";
+import { AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, REDACTOR_PATTERNS, createCounter, createNoopRequestLogger, forceKeep, getRequestLoggerSafe, getTraceContext, hasTracerProvider, isInitialized, otelTrace } from "autotel";
 import { createHash } from "node:crypto";
 import { HTTP_STATUS_ATTRIBUTES, SECURITY_ATTR, SECURITY_DENIED_STATUSES, SECURITY_METRICS, escalateSecuritySeverity } from "autotel/security-schema";
 
@@ -25,6 +25,18 @@ function resolveContextSafe(ctx) {
 		setAttributes: (attrs) => span.setAttributes(attrs)
 	};
 }
+let defaultOnMissingContext;
+/**
+* Process-wide defaults. A per-call `onMissingContext` still wins; pass
+* `undefined` to restore the built-in default.
+*/
+function configureAudit(options) {
+	defaultOnMissingContext = options.onMissingContext;
+}
+/** Per-call option, then configureAudit(), then skip-if-telemetry-off-else-warn. */
+function resolveOnMissingContext(explicit) {
+	return explicit ?? defaultOnMissingContext ?? (isInitialized() || hasTracerProvider() ? "warn" : "skip");
+}
 /** A no-op {@link AuditContext} whose attribute setters do nothing. */
 function noopAuditContext() {
 	return {
@@ -165,7 +177,7 @@ function securityEvent(metadata, options = {}) {
 	const traceCtx = resolveContextSafe(options.ctx);
 	if (options.metrics !== false) countSecurityEvent(metadata);
 	if (!traceCtx) {
-		const mode = options.onMissingContext ?? "warn";
+		const mode = resolveOnMissingContext(options.onMissingContext);
 		if (mode === "throw") throw new Error(MISSING_CONTEXT_MESSAGE);
 		if (mode === "warn") warnMissingContextOnce(metadata.name);
 		return;
@@ -597,7 +609,7 @@ function setAuditAttributes(metadata, ctx) {
 async function withAudit(metadata, fn, options = {}) {
 	const traceCtx = resolveContextSafe(options.ctx);
 	if (!traceCtx) {
-		const mode = options.onMissingContext ?? "warn";
+		const mode = resolveOnMissingContext(options.onMissingContext);
 		if (mode === "throw") throw new Error(MISSING_CONTEXT_MESSAGE);
 		if (mode === "warn") warnMissingContextOnce(metadata.action);
 		return fn(noopAuditContext(), options.logger ?? createNoopRequestLogger());
@@ -606,7 +618,7 @@ async function withAudit(metadata, fn, options = {}) {
 	setAuditAttributes(metadata, traceCtx);
 	let logger = options.logger ?? getRequestLoggerSafe() ?? void 0;
 	if (!logger) {
-		if ((options.onMissingContext ?? "warn") === "warn") warnMissingLoggerOnce(metadata.action);
+		if (resolveOnMissingContext(options.onMissingContext) === "warn") warnMissingLoggerOnce(metadata.action);
 		logger = createNoopRequestLogger();
 	}
 	logger.set({ audit: {
@@ -637,4 +649,4 @@ async function withAudit(metadata, fn, options = {}) {
 }
 
 //#endregion
-export { SUSPICIOUS_REQUEST_PATTERNS, applySecurityEventAttributes, createMcpSecurityEventBridge, createSecuritySignalProcessor, forceKeepAuditEvent, hashIdentifier, securityEvent, setAuditAttributes, startSecurityHeartbeat, withAudit, withSecurity };
+export { SUSPICIOUS_REQUEST_PATTERNS, applySecurityEventAttributes, configureAudit, createMcpSecurityEventBridge, createSecuritySignalProcessor, forceKeepAuditEvent, hashIdentifier, securityEvent, setAuditAttributes, startSecurityHeartbeat, withAudit, withSecurity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel-audit",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "Audit-focused helpers for Autotel (force-keep + structured audit instrumentation)",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,18 +29,13 @@
   "author": "Jag Reehal <jag@jagreehal.com> (https://jagreehal.com)",
   "license": "Apache-2.0",
   "dependencies": {
-    "autotel": "7.8.0"
+    "autotel": "7.10.0"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
-    "@typescript-eslint/eslint-plugin": "^8.65.0",
-    "@typescript-eslint/parser": "^8.65.0",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-unicorn": "^64.0.0",
-    "tsdown": "^0.22.14",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "^8.65.0",
-    "vitest": "^4.1.10"
+    "@types/node": "^26.6.3",
+    "tsdown": "^0.23.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.2"
   },
   "repository": {
     "type": "git",
@@ -54,7 +49,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "lint": "eslint src/**/*.ts",
+    "lint": "oxlint -c oxlint.json --disable-nested-config src",
     "type-check": "tsc --noEmit",
     "test": "vitest run"
   }