evlog 2.12.0 → 2.14.0

package/dist/audit-mUutdf6A.d.mts

@@ -0,0 +1,1130 @@
+//#region src/types.d.ts
+declare module 'nitropack/types' {
+  interface NitroRuntimeHooks {
+    /**
+     * Tail sampling hook - called before emitting a log.
+     * Set `ctx.shouldKeep = true` to force-keep the log regardless of head sampling.
+     *
+     * @example
+     * ```ts
+     * nitroApp.hooks.hook('evlog:emit:keep', (ctx) => {
+     *   if (ctx.context.user?.premium) {
+     *     ctx.shouldKeep = true
+     *   }
+     * })
+     * ```
+     */
+    'evlog:emit:keep': (ctx: TailSamplingContext) => void | Promise<void>;
+    /**
+     * Enrichment hook - called after emit, before drain.
+     * Use this to enrich the event with derived context (e.g. geo, user agent).
+     *
+     * @example
+     * ```ts
+     * nitroApp.hooks.hook('evlog:enrich', (ctx) => {
+     *   ctx.event.deploymentId = process.env.DEPLOYMENT_ID
+     * })
+     * ```
+     */
+    'evlog:enrich': (ctx: EnrichContext) => void | Promise<void>;
+    /**
+     * Drain hook - called after emitting a log (fire-and-forget).
+     * Use this to send logs to external services like Axiom, Loki, or custom endpoints.
+     * Errors are logged but never block the request.
+     *
+     * @example
+     * ```ts
+     * nitroApp.hooks.hook('evlog:drain', async (ctx) => {
+     *   await fetch('https://api.axiom.co/v1/datasets/logs/ingest', {
+     *     method: 'POST',
+     *     headers: { Authorization: `Bearer ${process.env.AXIOM_TOKEN}` },
+     *     body: JSON.stringify([ctx.event])
+     *   })
+     * })
+     * ```
+     */
+    'evlog:drain': (ctx: DrainContext) => void | Promise<void>;
+  }
+}
+declare module 'nitro/types' {
+  interface NitroRuntimeHooks {
+    'evlog:emit:keep': (ctx: TailSamplingContext) => void | Promise<void>;
+    'evlog:enrich': (ctx: EnrichContext) => void | Promise<void>;
+    'evlog:drain': (ctx: DrainContext) => void | Promise<void>;
+  }
+}
+/**
+ * Transport configuration for sending client logs to the server
+ */
+interface TransportConfig {
+  /**
+   * Enable sending logs to the server API
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * API endpoint for log ingestion
+   * @default '/api/_evlog/ingest'
+   */
+  endpoint?: string;
+  /**
+   * Fetch credentials mode
+   * @default 'same-origin'
+   */
+  credentials?: RequestCredentials;
+}
+/**
+ * Payload sent from client to server for log ingestion
+ */
+interface IngestPayload {
+  timestamp: string;
+  level: 'info' | 'error' | 'warn' | 'debug';
+  [key: string]: unknown;
+}
+/**
+ * Auto-redaction configuration for PII protection.
+ * Scrubs sensitive data from wide events before console output and draining.
+ *
+ * Built-in patterns are included by default. Opt out with `builtins: false`
+ * or select specific ones with `builtins: ['email', 'creditCard']`.
+ */
+interface RedactConfig {
+  /** Dot-notation paths to redact (e.g., 'user.email', 'headers.x-forwarded-for') */
+  paths?: string[];
+  /** Additional regex patterns to match and replace string values anywhere in the event */
+  patterns?: RegExp[];
+  /**
+   * Control built-in PII patterns.
+   * - `undefined` / omitted → all built-ins enabled (default)
+   * - `false` → no built-ins, only custom `paths`/`patterns`
+   * - `['email', 'creditCard', ...]` → only the listed built-ins
+   *
+   * Available: `'creditCard'`, `'email'`, `'ipv4'`, `'phone'`, `'jwt'`, `'bearer'`, `'iban'`
+   */
+  builtins?: false | Array<'creditCard' | 'email' | 'ipv4' | 'phone' | 'jwt' | 'bearer' | 'iban'>;
+  /**
+   * Replacement string used for path-based and custom pattern redaction.
+   * Built-in patterns use smart partial masking instead (e.g. `****1111` for credit cards).
+   * @default '[REDACTED]'
+   */
+  replacement?: string;
+  /** @internal Resolved masker functions from built-in patterns. Not user-facing. */
+  _maskers?: Array<[RegExp, (match: string) => string]>;
+}
+/**
+ * Sampling rates per log level (0-100 percentage)
+ */
+interface SamplingRates {
+  /** Percentage of info logs to keep (0-100). Default: 100 */
+  info?: number;
+  /** Percentage of warn logs to keep (0-100). Default: 100 */
+  warn?: number;
+  /** Percentage of debug logs to keep (0-100). Default: 100 */
+  debug?: number;
+  /** Percentage of error logs to keep (0-100). Default: 100 */
+  error?: number;
+}
+/**
+ * Tail sampling condition for forcing log retention based on request outcome.
+ * All conditions use >= comparison (e.g., status: 400 means status >= 400).
+ */
+interface TailSamplingCondition {
+  /** Keep if HTTP status >= this value (e.g., 400 for all errors) */
+  status?: number;
+  /** Keep if request duration >= this value in milliseconds */
+  duration?: number;
+  /** Keep if path matches this glob pattern (e.g., '/api/critical/**') */
+  path?: string;
+}
+/**
+ * Context passed to tail sampling evaluation and hooks.
+ * Contains request outcome information for sampling decisions.
+ */
+interface TailSamplingContext {
+  /** HTTP response status code */
+  status?: number;
+  /** Request duration in milliseconds (raw number) */
+  duration?: number;
+  /** Request path */
+  path?: string;
+  /** HTTP method */
+  method?: string;
+  /** Full accumulated context from the request logger */
+  context: Record<string, unknown>;
+  /**
+   * Set to true in evlog:emit:keep hook to force keep this log.
+   * Multiple hooks can set this - if any sets it to true, the log is kept.
+   */
+  shouldKeep?: boolean;
+}
+/**
+ * Context passed to the evlog:enrich hook.
+ * Called after emit, before drain.
+ */
+interface EnrichContext {
+  /** The emitted wide event (mutable). */
+  event: WideEvent;
+  /** Request metadata (if available) */
+  request?: {
+    method?: string;
+    path: string;
+    requestId?: string;
+  };
+  /** Safe HTTP request headers (sensitive headers filtered out) */
+  headers?: Record<string, string>;
+  /** Optional response metadata */
+  response?: {
+    status?: number;
+    headers?: Record<string, string>;
+  };
+}
+/**
+ * Context passed to the evlog:drain hook.
+ * Contains the complete wide event and request metadata for external transport.
+ */
+interface DrainContext {
+  /** The complete wide event to drain */
+  event: WideEvent;
+  /** Request metadata (if available) */
+  request?: {
+    method?: string;
+    path?: string;
+    requestId?: string;
+  };
+  /** HTTP headers from the original request (useful for correlation with external services) */
+  headers?: Record<string, string>;
+}
+/**
+ * Sampling configuration for filtering logs
+ */
+interface SamplingConfig {
+  /**
+   * Sampling rates per log level (head sampling).
+   * Values are percentages from 0 to 100.
+   * Default: 100 for all levels (log everything).
+   * Error defaults to 100 even if not specified.
+   *
+   * @example
+   * ```ts
+   * sampling: {
+   *   rates: {
+   *     info: 10,    // Keep 10% of info logs
+   *     warn: 50,    // Keep 50% of warning logs
+   *     debug: 5,    // Keep 5% of debug logs
+   *     error: 100,  // Always keep errors (default)
+   *   }
+   * }
+   * ```
+   */
+  rates?: SamplingRates;
+  /**
+   * Tail sampling conditions for forcing log retention (OR logic).
+   * If ANY condition matches, the log is kept regardless of head sampling.
+   * Use the `evlog:emit:keep` Nitro hook for custom conditions.
+   *
+   * @example
+   * ```ts
+   * sampling: {
+   *   rates: { info: 10 },  // Head sampling: keep 10% of info logs
+   *   keep: [
+   *     { status: 400 },     // Always keep if status >= 400
+   *     { duration: 1000 },  // Always keep if duration >= 1000ms
+   *     { path: '/api/critical/**' },  // Always keep critical paths
+   *   ]
+   * }
+   * ```
+   */
+  keep?: TailSamplingCondition[];
+}
+/**
+ * Route-based service configuration
+ */
+interface RouteConfig {
+  /** Service name to use for routes matching this pattern */
+  service: string;
+}
+/**
+ * Environment context automatically included in every log event
+ */
+interface EnvironmentContext {
+  /** Service name (auto-detected from package.json or configurable) */
+  service: string;
+  /** Environment: 'development', 'production', 'test', etc. */
+  environment: 'development' | 'production' | 'test' | string;
+  /** Application version (auto-detected from package.json) */
+  version?: string;
+  /** Git commit hash (auto-detected from CI/CD env vars) */
+  commitHash?: string;
+  /** Deployment region (auto-detected from cloud provider env vars) */
+  region?: string;
+}
+/**
+ * Logger configuration options
+ */
+interface LoggerConfig {
+  /**
+   * Enable or disable all logging globally.
+   * When false, all emits, tagged logs, and request logger operations become no-ops.
+   * @default true
+   */
+  enabled?: boolean;
+  /** Environment context overrides */
+  env?: Partial<EnvironmentContext>;
+  /** Enable pretty printing (auto-detected: true in dev, false in prod) */
+  pretty?: boolean;
+  /** Sampling configuration for filtering logs */
+  sampling?: SamplingConfig;
+  /**
+   * Minimum severity for the global `log` API (tagged and object form).
+   * Does not apply to `createLogger().emit()` / request wide events (use `sampling` for volume).
+   * Order: debug < info < warn < error.
+   * @default 'debug' (all levels)
+   */
+  minLevel?: LogLevel;
+  /**
+   * When pretty is disabled, emit JSON strings (default) or raw objects.
+   * Set to false for environments like Cloudflare Workers that expect objects.
+   * @default true
+   */
+  stringify?: boolean;
+  /**
+   * Suppress built-in console output.
+   * When true, events are still built, sampled, and passed to drains,
+   * but nothing is written to console. Use when drains own the output
+   * channel (e.g., stdout-based platforms like GCP Cloud Run, AWS Lambda).
+   * @default false
+   */
+  silent?: boolean;
+  /**
+   * Auto-redaction configuration for PII protection.
+   * Scrubs sensitive data from wide events before console output and before any drain.
+   *
+   * - `true` → enable with all built-in patterns (email, credit card, IPv4, phone, JWT, Bearer, IBAN)
+   * - `{ paths, patterns, builtins }` → fine-grained control
+   * - `false` → explicitly disable redaction
+   *
+   * @default true in production, false in development
+   *
+   * @example
+   * ```ts
+   * // Disable in production
+   * initLogger({ redact: false })
+   *
+   * // With custom paths on top of built-ins
+   * initLogger({
+   *   redact: {
+   *     paths: ['user.password', 'headers.authorization'],
+   *   },
+   * })
+   *
+   * // Only specific built-ins + custom patterns
+   * initLogger({
+   *   redact: {
+   *     builtins: ['email', 'creditCard'],
+   *     patterns: [/SECRET_\w+/g],
+   *   },
+   * })
+   * ```
+   */
+  redact?: boolean | RedactConfig;
+  /**
+   * Drain callback called with every emitted event (fire-and-forget).
+   * Use this to send logs to external services outside of Nitro.
+   * Compatible with drain adapters (`createAxiomDrain()`) and pipeline-wrapped drains.
+   *
+   * @example
+   * ```ts
+   * import { initLogger, log } from 'evlog'
+   * import { createAxiomDrain } from 'evlog/axiom'
+   *
+   * initLogger({
+   *   drain: createAxiomDrain({ dataset: 'logs', token: '...' }),
+   * })
+   *
+   * log.info({ action: 'user_login' }) // automatically drained
+   * ```
+   *
+   * @example
+   * ```ts
+   * // With pipeline for batching and retry
+   * import { createDrainPipeline } from 'evlog/pipeline'
+   *
+   * const pipeline = createDrainPipeline({ batch: { size: 25 } })
+   * const drain = pipeline(createAxiomDrain({ dataset: 'logs', token: '...' }))
+   *
+   * initLogger({ drain })
+   *
+   * // Flush on shutdown
+   * process.on('beforeExit', () => drain.flush())
+   * ```
+   */
+  drain?: (ctx: DrainContext) => void | Promise<void>;
+  /** @internal Suppress the "silent without drain" warning (used by hook-based frameworks like Nitro/Nuxt) */
+  _suppressDrainWarning?: boolean;
+}
+/**
+ * Audit actor — who initiated the action.
+ *
+ * `type` covers the most common actor families. `id` is required and should be
+ * a stable identifier (user id, service name, API key id, agent id). `model`,
+ * `tools`, `reason`, and `promptId` are filled when `type === 'agent'` and
+ * mirror the AI SDK fields already used by `evlog/ai`.
+ */
+interface AuditActor {
+  type: 'user' | 'system' | 'api' | 'agent';
+  id: string;
+  displayName?: string;
+  email?: string;
+  model?: string;
+  tools?: string[];
+  reason?: string;
+  promptId?: string;
+}
+/**
+ * Audit target — the resource the action was performed on.
+ *
+ * `type` is a free-form string (e.g. `'invoice'`, `'user'`, `'subscription'`)
+ * narrowed by {@link defineAuditAction}. Additional fields are allowed for
+ * resource-specific metadata (e.g. `tenantId`, `path`, `previousOwnerId`).
+ */
+interface AuditTarget {
+  type: string;
+  id: string;
+  [key: string]: unknown;
+}
+/**
+ * Reserved audit fields on the wide event.
+ *
+ * Set via `log.audit({ ... })`, `log.set({ audit: { ... } })`, or the
+ * standalone `audit({ ... })` helper. Downstream filters on `audit IS NOT NULL`.
+ *
+ * - `outcome` — `'success' | 'failure' | 'denied'`. `'denied'` records an
+ *   AuthZ-denied action (often forgotten but exactly what auditors want).
+ * - `changes.before/after` — the diff for mutating actions. Use
+ *   {@link auditDiff} to produce a redact-aware compact JSON Patch.
+ * - `causationId` / `correlationId` — chain related actions (admin action →
+ *   system reactions). Set by callers, propagated by `auditEnricher` when
+ *   available on the request.
+ * - `signature` / `prevHash` — populated by the {@link signed} drain wrapper.
+ *   Never set by application code.
+ * - `idempotencyKey` — derived deterministically by `log.audit()` so retries
+ *   across drains are safe.
+ * - `context` — request/runtime context auto-populated by {@link auditEnricher}
+ *   (`requestId`, `traceId`, `ip`, `userAgent`, `tenantId`).
+ */
+interface AuditFields {
+  /** Action name. Convention: `'<resource>.<verb>'`, e.g. `'invoice.refund'`. */
+  action: string;
+  actor: AuditActor;
+  target?: AuditTarget;
+  outcome: 'success' | 'failure' | 'denied';
+  /** Human-readable explanation, especially required for `outcome: 'denied'`. */
+  reason?: string;
+  /** Before/after snapshots for mutating actions. */
+  changes?: {
+    before?: unknown;
+    after?: unknown;
+  };
+  /** ID of the action that caused this one. */
+  causationId?: string;
+  /** ID shared by every action in the same logical operation. */
+  correlationId?: string;
+  /** Schema version of the audit envelope. Defaults to `1` when omitted by the caller. */
+  version?: number;
+  /** Set by `log.audit()` as a stable hash for safe retries across drains. */
+  idempotencyKey?: string;
+  /** Request/runtime context — populated by `auditEnricher`. */
+  context?: {
+    requestId?: string;
+    traceId?: string;
+    ip?: string;
+    userAgent?: string;
+    tenantId?: string;
+    [key: string]: unknown;
+  };
+  /** HMAC signature of the event when wrapped with `signed({ strategy: 'hmac' })`. */
+  signature?: string;
+  /** Previous event hash when wrapped with `signed({ strategy: 'hash-chain' })`. */
+  prevHash?: string;
+  /** Hash of the current event when wrapped with `signed({ strategy: 'hash-chain' })`. */
+  hash?: string;
+}
+/**
+ * Base structure for all wide events.
+ *
+ * Augment via `declare module 'evlog'` to add app-specific top-level fields.
+ * `audit` is reserved for {@link AuditFields}.
+ */
+interface BaseWideEvent {
+  timestamp: string;
+  level: 'info' | 'error' | 'warn' | 'debug';
+  service: string;
+  environment: string;
+  version?: string;
+  commitHash?: string;
+  region?: string;
+  audit?: AuditFields;
+}
+/**
+ * Wide event with arbitrary additional fields
+ */
+type WideEvent = BaseWideEvent & Record<string, unknown>;
+/**
+ * Recursively makes all properties optional.
+ * Arrays are kept as-is (not deeply partial).
+ */
+type DeepPartial<T> = T extends Array<unknown> ? T : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
+/**
+ * Fields set internally by the evlog plugin (status, service, etc.).
+ * These are always accepted by `set()` regardless of the user-defined field type.
+ */
+interface InternalFields {
+  status?: number;
+  service?: string;
+  requestLogs?: RequestLogEntry[];
+  /** Label for a forked background wide event (child operation name). */
+  operation?: string;
+  /** Parent request's `requestId` when this event was produced by `log.fork()`. */
+  _parentRequestId?: string;
+}
+/**
+ * Request-scoped log entry captured during a request lifecycle.
+ */
+interface RequestLogEntry {
+  level: 'info' | 'warn';
+  message: string;
+  timestamp: string;
+}
+/**
+ * Resolved context type for logger methods.
+ * User fields are deeply partial (matching deep merge behavior) with internal
+ * field keys omitted to avoid intersection conflicts, then internal fields
+ * are added back with their canonical types.
+ */
+type FieldContext<T extends object = Record<string, unknown>> = DeepPartial<Omit<T, keyof InternalFields>> & InternalFields;
+/**
+ * Request-scoped logger for building wide events
+ *
+ * After {@link RequestLogger.emit} runs (including when head sampling drops the event),
+ * the logger is **sealed**: further `set`, `error`, `info`, and `warn` calls log a
+ * console warning and do not mutate the wide event. A second `emit` is ignored with
+ * a warning. Use {@link RequestLogger.fork} on supported integrations for intentional
+ * background work that needs its own wide event.
+ *
+ * `fork` is only present on request loggers from integrations that attach it (not on
+ * standalone `createLogger()` instances).
+ *
+ * @example
+ * ```ts
+ * const logger = useLogger(event)
+ * logger.set({ user: { id: '123' } })
+ * logger.set({ cart: { items: 3 } })
+ * // emit() is called automatically by the plugin
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With typed fields for compile-time safety
+ * interface MyFields {
+ *   user: { id: string; plan: string }
+ *   action: string
+ * }
+ * const logger = useLogger<MyFields>(event)
+ * logger.set({ user: { id: '123', plan: 'pro' } }) // OK
+ * logger.set({ user: { id: '123' } })               // OK (deep partial)
+ * logger.set({ action: 'checkout' })                 // OK
+ * logger.set({ status: 200 })                        // OK (internal field)
+ * logger.set({ account: '...' })                     // TS error
+ * ```
+ */
+interface RequestLogger<T extends object = Record<string, unknown>> {
+  /**
+   * Add context to the wide event. Plain objects are merged recursively.
+   * When both the existing and incoming values for a key are arrays, elements are
+   * concatenated (existing order preserved, new elements appended). Otherwise the
+   * new value replaces the old one (including when only one side is an array).
+   *
+   * No-ops with a console warning after the wide event has been emitted.
+   */
+  set: (context: FieldContext<T>) => void;
+  /**
+   * Log an error and capture its details.
+   *
+   * No-ops with a console warning after the wide event has been emitted.
+   */
+  error: (error: Error | string, context?: FieldContext<T>) => void;
+  /**
+   * Capture an informational message inside the request wide event.
+   *
+   * No-ops with a console warning after the wide event has been emitted.
+   */
+  info: (message: string, context?: FieldContext<T>) => void;
+  /**
+   * Capture a warning message inside the request wide event.
+   *
+   * No-ops with a console warning after the wide event has been emitted.
+   */
+  warn: (message: string, context?: FieldContext<T>) => void;
+  /**
+   * Emit the final wide event with all accumulated context.
+   * Returns the emitted WideEvent, or null if the log was sampled out.
+   *
+   * Seals the logger: after this returns (including when the return value is `null`
+   * due to sampling), further mutations are ignored with warnings.
+   */
+  emit: (overrides?: FieldContext<T> & {
+    _forceKeep?: boolean;
+  }) => WideEvent | null;
+  /**
+   * Get the current accumulated context
+   */
+  getContext: () => FieldContext<T> & Record<string, unknown>;
+  /**
+   * Run async (or sync) work in a **child** request logger scope so `useLogger()`
+   * resolves to the child logger while `fn` runs. The child emits its own wide event
+   * when `fn` settles, with `operation` and `_parentRequestId` set for correlation.
+   * Only available on integrations that attach this method (Express, Fastify, NestJS,
+   * SvelteKit, React Router, Next.js `withEvlog`, Elysia — see docs).
+   *
+   * @param label - Value stored as `operation` on the child wide event.
+   * @param fn - Function to run; may return a Promise. Errors are captured on the
+   *   child logger and emitted.
+   *
+   * @example
+   * ```ts
+   * log.fork('process_order', async () => {
+   *   const log = useLogger()
+   *   log.set({ step: 'charged' })
+   * })
+   * ```
+   */
+  fork?: (label: string, fn: () => void | Promise<void>) => void;
+  /**
+   * Record an audit event on this wide event. Strictly equivalent to
+   * `log.set({ audit: { ... } })` plus tail-sample force-keep.
+   *
+   * Use `log.audit.deny(reason, fields)` for AuthZ-denied actions — most teams
+   * forget to log denials but they are exactly what auditors and security teams
+   * ask for.
+   *
+   * Available on every logger returned by `createLogger()` / `createRequestLogger()`
+   * and on framework loggers exposed via `useLogger()` / `c.get('log')` etc.
+   *
+   * @example
+   * ```ts
+   * log.audit({
+   *   action: 'invoice.refund',
+   *   actor: { type: 'user', id: user.id, email: user.email },
+   *   target: { type: 'invoice', id: 'inv_889' },
+   *   outcome: 'success',
+   *   reason: 'Customer requested refund',
+   * })
+   * ```
+   */
+  audit?: AuditLoggerMethod;
+}
+/** @internal Forward-declaration to avoid a circular import with `audit.ts`. */
+interface AuditLoggerMethod {
+  (input: AuditInput): void;
+  deny: (reason: string, input: Omit<AuditInput, 'outcome' | 'reason'>) => void;
+}
+/**
+ * Log level type
+ */
+type LogLevel = 'info' | 'error' | 'warn' | 'debug';
+/**
+ * Simple logging API - as easy as console.log
+ *
+ * @example
+ * ```ts
+ * log.info('auth', 'User logged in')
+ * log.error({ action: 'payment', error: 'failed' })
+ * ```
+ */
+interface Log {
+  /**
+   * Log an info message or wide event
+   * @example log.info('auth', 'User logged in')
+   * @example log.info({ action: 'login', userId: '123' })
+   */
+  info(tag: string, message: string): void;
+  info(event: Record<string, unknown>): void;
+  /**
+   * Log an error message or wide event
+   * @example log.error('payment', 'Payment failed')
+   * @example log.error({ action: 'payment', error: 'declined' })
+   */
+  error(tag: string, message: string): void;
+  error(event: Record<string, unknown>): void;
+  /**
+   * Log a warning message or wide event
+   * @example log.warn('api', 'Rate limit approaching')
+   * @example log.warn({ action: 'api', remaining: 10 })
+   */
+  warn(tag: string, message: string): void;
+  warn(event: Record<string, unknown>): void;
+  /**
+   * Log a debug message or wide event
+   * @example log.debug('cache', 'Cache miss')
+   * @example log.debug({ action: 'cache', key: 'user_123' })
+   */
+  debug(tag: string, message: string): void;
+  debug(event: Record<string, unknown>): void;
+}
+/**
+ * Error options for creating structured errors
+ */
+interface ErrorOptions {
+  /** What actually happened */
+  message: string;
+  /** HTTP status code (default: 500) */
+  status?: number;
+  /** Why this error occurred */
+  why?: string;
+  /** How to fix this issue */
+  fix?: string;
+  /** Link to documentation or more information */
+  link?: string;
+  /** The original error that caused this */
+  cause?: Error;
+  /**
+   * Backend-only diagnostic context (auditing, support, debugging).
+   * Never included in HTTP responses or `EvlogError#toJSON`; included in wide events when the error is passed to `log.error()`.
+   */
+  internal?: Record<string, unknown>;
+}
+/**
+ * Options for creating a request logger
+ */
+interface RequestLoggerOptions {
+  method?: string;
+  path?: string;
+  requestId?: string;
+}
+/**
+ * H3 event context with evlog logger attached
+ */
+interface H3EventContext {
+  log?: RequestLogger;
+  requestId?: string;
+  status?: number;
+  /** Internal: start time for duration calculation in tail sampling */
+  _evlogStartTime?: number;
+  /** Internal: flag to prevent double emission on errors */
+  _evlogEmitted?: boolean;
+  /** Internal: whether the route matched shouldLog filtering (emit-time guard) */
+  _evlogShouldEmit?: boolean;
+  [key: string]: unknown;
+}
+/**
+ * Server event type for Nitro/h3 handlers
+ */
+interface ServerEvent {
+  method: string;
+  path: string;
+  context: H3EventContext & {
+    /** Cloudflare Workers context (available when deployed to CF Workers) */cloudflare?: {
+      context: {
+        waitUntil: (promise: Promise<unknown>) => void;
+      };
+    }; /** Vercel Edge context (available when deployed to Vercel Edge) */
+    waitUntil?: (promise: Promise<unknown>) => void;
+  };
+  node?: {
+    res?: {
+      statusCode?: number;
+    };
+  };
+  response?: Response;
+}
+/**
+ * Parsed evlog error with all fields at the top level
+ */
+interface ParsedError {
+  message: string;
+  status: number;
+  why?: string;
+  fix?: string;
+  link?: string;
+  raw: unknown;
+}
+//#endregion
+//#region src/audit.d.ts
+/**
+ * Current version of the audit envelope. Bumped when `AuditFields` evolves
+ * in a backward-incompatible way so downstream pipelines can branch on it.
+ */
+declare const AUDIT_SCHEMA_VERSION = 1;
+/**
+ * Input accepted by `log.audit()`, `audit()`, and `withAudit()`.
+ *
+ * `outcome` defaults to `'success'`. Internal fields populated by the audit
+ * pipeline (`idempotencyKey`, `context`, `signature`, `prevHash`, `hash`) are
+ * stripped — pass them through `log.set({ audit })` if you really need to.
+ */
+interface AuditInput {
+  action: string;
+  actor: AuditActor;
+  target?: AuditTarget;
+  outcome?: AuditFields['outcome'];
+  reason?: string;
+  changes?: AuditFields['changes'];
+  causationId?: string;
+  correlationId?: string;
+  version?: number;
+}
+/**
+ * Build a normalised {@link AuditFields} from caller input. Defaults:
+ * - `outcome` → `'success'`
+ * - `version` → {@link AUDIT_SCHEMA_VERSION}
+ *
+ * `idempotencyKey` is filled at emit time with the event timestamp so retries
+ * stay deterministic.
+ */
+declare function buildAuditFields(input: AuditInput): AuditFields;
+/**
+ * Add audit semantics to an existing {@link RequestLogger}.
+ *
+ * Mutates the logger in place by adding an `audit` method (with a `.deny()`
+ * sub-method). Strictly equivalent to calling `log.set({ audit: ... })` plus
+ * `_forceKeep` on emit. Idempotent: calling twice on the same logger only
+ * attaches the methods once.
+ *
+ * @example
+ * ```ts
+ * const log = withAuditMethods(createLogger())
+ * log.audit({
+ *   action: 'invoice.refund',
+ *   actor: { type: 'user', id: user.id },
+ *   target: { type: 'invoice', id: 'inv_889' },
+ * })
+ * ```
+ */
+declare function withAuditMethods<T extends object = Record<string, unknown>>(logger: RequestLogger<T>): AuditableLogger<T>;
+/**
+ * Logger augmented with `.audit()` / `.audit.deny()` helpers.
+ */
+type AuditableLogger<T extends object = Record<string, unknown>> = RequestLogger<T> & {
+  audit: AuditMethod<T>;
+};
+/** Method shape attached to {@link AuditableLogger}. */
+interface AuditMethod<T extends object = Record<string, unknown>> {
+  (input: AuditInput): void;
+  /**
+   * Record an AuthZ-denied action. Forces `outcome: 'denied'` and requires
+   * a human-readable `reason`. Most teams forget to log denials — they are
+   * exactly what auditors and security teams ask for.
+   */
+  deny: (reason: string, input: Omit<AuditInput, 'outcome' | 'reason'>) => void;
+}
+/**
+ * Standalone audit emitter for non-request contexts (jobs, scripts, CLIs).
+ *
+ * Creates a one-shot logger, sets the audit fields, and emits immediately.
+ * The event is force-kept past tail sampling. Returns the emitted wide event,
+ * or `null` if logging is globally disabled.
+ *
+ * @example
+ * ```ts
+ * import { audit } from 'evlog'
+ *
+ * audit({
+ *   action: 'cron.cleanup',
+ *   actor: { type: 'system', id: 'cron' },
+ *   target: { type: 'job', id: 'cleanup-stale-sessions' },
+ *   outcome: 'success',
+ * })
+ * ```
+ */
+declare function audit(input: AuditInput): WideEvent | null;
+/**
+ * Wrap a function so its outcome (success / failure / denied) is automatically
+ * audited.
+ *
+ * Behaviour:
+ * - If `fn` resolves, an audit event with `outcome: 'success'` is emitted.
+ * - If `fn` throws an `EvlogError` (or any error) with `status === 403`, the
+ *   audit event is recorded as `'denied'` with the error message as `reason`.
+ * - Any other thrown error produces `outcome: 'failure'` and re-throws.
+ *
+ * Use {@link AuditDeniedError} to signal denial without an HTTP status.
+ *
+ * @example
+ * ```ts
+ * const refundInvoice = withAudit(
+ *   { action: 'invoice.refund', target: (input) => ({ type: 'invoice', id: input.id }) },
+ *   async (input: { id: string }, ctx: { actor: AuditActor }) => {
+ *     await db.invoices.refund(input.id)
+ *   }
+ * )
+ *
+ * await refundInvoice({ id: 'inv_889' }, { actor: { type: 'user', id: user.id } })
+ * ```
+ */
+declare function withAudit<TInput, TOutput>(options: WithAuditOptions<TInput>, fn: (input: TInput, ctx: WithAuditContext) => Promise<TOutput> | TOutput): (input: TInput, ctx: WithAuditContext) => Promise<TOutput>;
+/**
+ * Throw inside a {@link withAudit} body to mark the action as `outcome: 'denied'`
+ * regardless of the underlying HTTP status. The constructor message becomes the
+ * audit `reason`.
+ */
+declare class AuditDeniedError extends Error {
+  constructor(reason: string);
+}
+/** Options for {@link withAudit}. `target` may be derived from the input. */
+interface WithAuditOptions<TInput> {
+  action: string;
+  target?: AuditTarget | ((input: TInput) => AuditTarget | undefined);
+}
+/**
+ * Runtime context required by a {@link withAudit}-wrapped function.
+ * The actor is always required; correlation IDs are optional.
+ */
+interface WithAuditContext {
+  actor: AuditActor;
+  causationId?: string;
+  correlationId?: string;
+}
+/**
+ * Compute a compact, redact-aware diff between two objects for the
+ * `changes` field. Output is a JSON Patch-style array (RFC 6902 subset:
+ * `add`, `remove`, `replace`) — small enough to ship over the wire.
+ *
+ * Object keys whose name matches one of the `redactPaths` (dot-notation, e.g.
+ * `'user.password'`, `'card.cvv'`) are replaced with `'[REDACTED]'` so PII
+ * never leaks through the diff.
+ *
+ * @example
+ * ```ts
+ * log.audit({
+ *   action: 'user.update',
+ *   actor: { type: 'user', id: user.id },
+ *   target: { type: 'user', id: 'usr_42' },
+ *   changes: auditDiff(before, after, { redactPaths: ['password'] }),
+ * })
+ * ```
+ */
+declare function auditDiff(before: unknown, after: unknown, options?: AuditDiffOptions): {
+  before?: unknown;
+  after?: unknown;
+  patch: AuditPatchOp[];
+};
+/** Single JSON Patch operation produced by {@link auditDiff}. */
+interface AuditPatchOp {
+  op: 'add' | 'remove' | 'replace';
+  path: string;
+  value?: unknown;
+}
+/** Options for {@link auditDiff}. */
+interface AuditDiffOptions {
+  /** Object keys (dot-notation) whose values should be replaced with `[REDACTED]`. */
+  redactPaths?: string[];
+  /** Custom replacement string. @default '[REDACTED]' */
+  replacement?: string;
+  /** Include the full redacted `before` snapshot alongside the patch. */
+  includeBefore?: boolean;
+  /** Include the full redacted `after` snapshot alongside the patch. */
+  includeAfter?: boolean;
+}
+/**
+ * Define a typed audit action with an optional fixed target type.
+ *
+ * Returns a curried helper that fills in the action name (and target shape
+ * if provided) so call sites stay terse and the action set is discoverable
+ * in one place.
+ *
+ * @example
+ * ```ts
+ * const refund = defineAuditAction('invoice.refund', { target: 'invoice' })
+ *
+ * log.audit(refund({
+ *   actor: { type: 'user', id: user.id },
+ *   target: { id: 'inv_889' }, // type inferred as 'invoice'
+ *   outcome: 'success',
+ * }))
+ * ```
+ */
+declare function defineAuditAction<TTargetType extends string | undefined = undefined>(action: string, options?: {
+  target?: TTargetType;
+}): DefinedAuditAction<TTargetType>;
+/**
+ * Return type of {@link defineAuditAction}. Accepts a partial input (no
+ * `action`, target type pre-filled when provided).
+ */
+type DefinedAuditAction<TTargetType extends string | undefined> = (input: TTargetType extends string ? Omit<AuditInput, 'action' | 'target'> & {
+  target?: Omit<AuditTarget, 'type'> & {
+    type?: TTargetType;
+  };
+} : Omit<AuditInput, 'action'>) => AuditInput;
+/**
+ * Test helper that captures every audit event emitted while it is active.
+ *
+ * Returns `{ events, restore, expect }`:
+ * - `events` — live array of captured `AuditFields`, populated as audits fire.
+ * - `restore()` — uninstall the collector. Call from `afterEach()`.
+ * - `expect.toIncludeAuditOf(matcher)` — assertion helper used inside `expect`
+ *   blocks, returns `true` if at least one captured event matches.
+ *
+ * Only captures audits going through `log.audit()` and the standalone
+ * `audit()` function. Events emitted via raw `log.set({ audit })` skip the
+ * collector by design — wrap them with `log.audit()` to make them visible to
+ * tests.
+ *
+ * @example
+ * ```ts
+ * const captured = mockAudit()
+ * await refundInvoice('inv_889')
+ * expect(captured.events).toHaveLength(1)
+ * expect(captured.toIncludeAuditOf({ action: 'invoice.refund' })).toBe(true)
+ * captured.restore()
+ * ```
+ */
+declare function mockAudit(): MockAudit;
+/** Result of {@link mockAudit}. */
+interface MockAudit {
+  events: AuditFields[];
+  restore: () => void;
+  toIncludeAuditOf: (matcher: AuditMatcher) => boolean;
+}
+/** Partial structural matcher for {@link MockAudit.toIncludeAuditOf}. */
+interface AuditMatcher {
+  action?: string | RegExp;
+  outcome?: AuditFields['outcome'];
+  actor?: Partial<AuditActor>;
+  target?: Partial<AuditTarget>;
+}
+/** Shape of the optional better-auth bridge for the audit enricher. */
+interface AuditEnricherBetterAuthBridge {
+  /** Read the current authenticated session for this request, if any. */
+  getSession: (ctx: EnrichContext) => Promise<AuditActor | null | undefined> | AuditActor | null | undefined;
+}
+/** Options for {@link auditEnricher}. */
+interface AuditEnricherOptions {
+  /**
+   * Resolve the tenant id for the current request. The result is stored at
+   * `event.audit.context.tenantId`. Multi-tenant SaaS gets isolation by default.
+   */
+  tenantId?: (ctx: EnrichContext) => string | undefined;
+  /**
+   * Bridge to populate `event.audit.actor` from the authenticated session.
+   * Only used when the application has not already filled `actor`.
+   */
+  bridge?: AuditEnricherBetterAuthBridge;
+  /** When true, overwrite existing context fields. @default false */
+  overwrite?: boolean;
+}
+/**
+ * Enrich audit-bearing wide events with request, runtime, and tenant context.
+ *
+ * Runs only when `event.audit` is present — every other event passes through
+ * untouched. Populates:
+ * - `event.audit.context.requestId` from `ctx.request.requestId`
+ * - `event.audit.context.traceId`   from `event.traceId`
+ * - `event.audit.context.ip`        from `x-forwarded-for` / `x-real-ip`
+ * - `event.audit.context.userAgent` from `user-agent`
+ * - `event.audit.context.tenantId`  from `options.tenantId(ctx)`
+ *
+ * Optionally fills `event.audit.actor` from the better-auth bridge when the
+ * caller did not provide one. Anything else (custom actor strategies,
+ * extra context) belongs in a custom enricher — replace this one entirely.
+ */
+declare function auditEnricher(options?: AuditEnricherOptions): (ctx: EnrichContext) => void | Promise<void>;
+/** Options accepted by {@link auditOnly}. */
+interface AuditOnlyOptions {
+  /**
+   * When true, the wrapper awaits the wrapped drain so the event is flushed
+   * before the request resolves. Use for crash-safe audit storage.
+   * @default false
+   */
+  await?: boolean;
+}
+/** Drain function signature accepted by all wrappers. Matches `LoggerConfig['drain']`. */
+type DrainFn = (ctx: DrainContext) => void | Promise<void>;
+/**
+ * Wrap any drain so it only receives events that carry an `audit` field.
+ *
+ * Use to route audit events to dedicated storage (separate Axiom dataset,
+ * append-only Postgres table, FS journal) without affecting your main drain.
+ *
+ * Per-sink failure isolation comes from `initLogger({ drain: [...] })`: each
+ * drain in the array is invoked independently, so a crashed Axiom call never
+ * blocks the FS audit drain.
+ *
+ * @example
+ * ```ts
+ * import { initLogger, auditOnly } from 'evlog'
+ * import { createAxiomDrain } from 'evlog/axiom'
+ * import { createFsDrain } from 'evlog/fs'
+ *
+ * initLogger({
+ *   drain: [
+ *     createAxiomDrain({ dataset: 'logs' }),
+ *     auditOnly(createFsDrain({ dir: '.audit' }), { await: true }),
+ *   ],
+ * })
+ * ```
+ */
+declare function auditOnly(drain: DrainFn, options?: AuditOnlyOptions): DrainFn;
+/** Pluggable persistence for the hash-chain state. */
+interface SignedChainState {
+  /** Load the previous hash from durable storage, or `null` on first run. */
+  load: () => Promise<string | null> | string | null;
+  /** Persist the latest hash so the chain survives process restarts. */
+  save: (hash: string) => Promise<void> | void;
+}
+/** Options for {@link signed}. Pick a strategy at construction time. */
+type SignedOptions = {
+  strategy: 'hmac';
+  secret: string;
+  algorithm?: 'sha256' | 'sha512';
+} | {
+  strategy: 'hash-chain';
+  state?: SignedChainState;
+  algorithm?: 'sha256' | 'sha512';
+};
+/**
+ * Wrap a drain so every event passing through gains tamper-evident integrity.
+ *
+ * - `'hmac'` — adds `event.audit.signature` (HMAC of the canonical event).
+ * - `'hash-chain'` — adds `event.audit.prevHash` and `event.audit.hash` so the
+ *   sequence of events forms a verifiable chain. State persists in memory
+ *   by default; pass a `state: { load, save }` for cross-process / durable
+ *   chains (Redis, file, Postgres).
+ *
+ * The signature is computed before the event is forwarded to the wrapped
+ * drain — combine with {@link auditOnly} when you only want integrity for
+ * audit events.
+ *
+ * @example
+ * ```ts
+ * import { initLogger, auditOnly, signed } from 'evlog'
+ * import { createFsDrain } from 'evlog/fs'
+ *
+ * initLogger({
+ *   drain: auditOnly(
+ *     signed(createFsDrain({ dir: '.audit' }), { strategy: 'hash-chain' }),
+ *     { await: true },
+ *   ),
+ * })
+ * ```
+ */
+declare function signed(drain: DrainFn, options: SignedOptions): DrainFn;
+/**
+ * Strict redact preset for audit events.
+ *
+ * Combine with the user's existing redact configuration via spread:
+ * `initLogger({ redact: { paths: [...auditRedactPreset.paths!, ...mine] } })`.
+ *
+ * Hardens PII handling:
+ * - Drops `Authorization` and `Cookie` headers anywhere they appear.
+ * - Drops common credential field names (`password`, `passwordHash`, `token`,
+ *   `apiKey`, `secret`, `accessToken`, `refreshToken`, `cardNumber`, `cvv`,
+ *   `ssn`).
+ *
+ * Built-in pattern maskers (email, credit card, …) keep their default
+ * behaviour — partial masking, not full redaction — so audit trails retain
+ * enough signal to be useful.
+ */
+declare const auditRedactPreset: RedactConfig;
+//#endregion
+export { SamplingRates as $, AuditFields as A, H3EventContext as B, buildAuditFields as C, withAudit as D, signed as E, DrainContext as F, LoggerConfig as G, InternalFields as H, EnrichContext as I, RequestLogEntry as J, ParsedError as K, EnvironmentContext as L, AuditTarget as M, BaseWideEvent as N, withAuditMethods as O, DeepPartial as P, SamplingConfig as Q, ErrorOptions as R, auditRedactPreset as S, mockAudit as T, Log as U, IngestPayload as V, LogLevel as W, RequestLoggerOptions as X, RequestLogger as Y, RouteConfig as Z, WithAuditOptions as _, AuditInput as a, auditEnricher as b, AuditOnlyOptions as c, DefinedAuditAction as d, ServerEvent as et, DrainFn as f, WithAuditContext as g, SignedOptions as h, AuditEnricherOptions as i, WideEvent as it, AuditLoggerMethod as j, AuditActor as k, AuditPatchOp as l, SignedChainState as m, AuditDeniedError as n, TailSamplingContext as nt, AuditMatcher as o, MockAudit as p, RedactConfig as q, AuditDiffOptions as r, TransportConfig as rt, AuditMethod as s, AUDIT_SCHEMA_VERSION as t, TailSamplingCondition as tt, AuditableLogger as u, audit as v, defineAuditAction as w, auditOnly as x, auditDiff as y, FieldContext as z };
+//# sourceMappingURL=audit-mUutdf6A.d.mts.map