autotel-audit 0.1.0

package/README.md

@@ -0,0 +1,223 @@
+# autotel-audit
+
+Audit-focused helpers for `autotel`. Provides structured audit logging with automatic tail-sampling bypass and OpenTelemetry attribute normalization.
+
+## What it provides
+
+- **`withAudit(...)`** — Wraps an operation with audit metadata, automatic outcome tagging (success/failure), and optional immediate emit
+- **`forceKeepAuditEvent(...)`** — Marks the current trace to bypass tail-drop sampling for compliance/audit trails
+- **`setAuditAttributes(...)`** — Writes normalized `audit.*` attributes on the active span with automatic type conversion
+
+## Features
+
+- **Structured Metadata** — Enforce consistent audit schemas with `AuditMetadata` interface
+- **Automatic Outcome Tagging** — Operations auto-tagged as `success` or `failure` (override with explicit `outcome` field)
+- **Sampling Bypass** — Force critical audit events through tail-sampling with `forceKeepAuditEvent()` or `options.forceKeep`
+- **Type-Safe Attributes** — Automatic serialization of complex types (Objects, Dates, Arrays) to OpenTelemetry-compatible values
+- **Request Context Integration** — Propagates actor ID, resource, and action across structured logs
+- **Compliance Ready** — Emit audit events immediately (`emitNow: true`) for real-time compliance systems
+
+## Quick Start
+
+```ts
+import { trace } from 'autotel';
+import { withAudit } from 'autotel-audit';
+
+export const deleteUser = trace(async () => {
+  return withAudit(
+    { action: 'user.delete', resource: 'user', actorId: 'admin-42' },
+    async (_ctx, log) => {
+      // business logic
+      log.info('User deleted successfully');
+      return { ok: true };
+    },
+    { emitNow: true },
+  );
+});
+```
+
+## API Reference
+
+### `withAudit<T>(metadata, fn, options?)`
+
+Wraps an async operation with audit metadata and handles success/failure outcomes.
+
+**Parameters:**
+
+- `metadata: AuditMetadata` — Audit event metadata (action, resource, actor, etc.)
+- `fn: (ctx, logger) => Promise<T>` — Async function receiving audit context and request logger
+- `options?: WithAuditOptions` — Optional configuration:
+  - `emitNow?: boolean` — Immediately emit the audit event (default: false)
+  - `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
+
+**Example with custom context:**
+
+```ts
+const ctx = {
+  traceId: 'abc-123',
+  spanId: 'def-456',
+  correlationId: 'xyz-789',
+  setAttribute: (k, v) => span.setAttribute(k, v),
+  setAttributes: (attrs) => span.setAttributes(attrs),
+};
+
+await withAudit({ action: 'data.export' }, fn, { ctx, emitNow: true });
+```
+
+### `setAuditAttributes(metadata, ctx?)`
+
+Write audit metadata as normalized `audit.*` span attributes without wrapping an operation.
+
+```ts
+import { setAuditAttributes } from 'autotel-audit';
+
+setAuditAttributes({
+  action: 'config.update',
+  resource: 'settings',
+  actorId: 'user-123',
+  category: 'admin',
+});
+// Sets: audit.action, audit.resource, audit.actorId, audit.category, autotel.audit=true
+```
+
+### `forceKeepAuditEvent(ctx?)`
+
+Mark the active trace to bypass tail-drop sampling. Called automatically by `withAudit` unless `forceKeep: false`.
+
+```ts
+import { trace } from 'autotel';
+import { forceKeepAuditEvent } from 'autotel-audit';
+
+export const readSecrets = trace(async (req) => {
+  if (req.user.role !== 'admin') {
+    forceKeepAuditEvent(); // Keep sensitive access attempts
+    throw new Error('Unauthorized');
+  }
+  // ...
+});
+```
+
+## Type-Safe Metadata
+
+Define audit schemas for different operations:
+
+```ts
+import type { AuditMetadata } from 'autotel-audit';
+
+interface DeleteUserAudit extends AuditMetadata {
+  action: 'user.delete';
+  resource: 'user';
+  actorId: string;
+  reason?: string;
+}
+
+interface PermissionUpdate extends AuditMetadata {
+  action: 'permission.update';
+  resource: 'role';
+  oldValue?: Record<string, boolean>;
+  newValue?: Record<string, boolean>;
+  actorId: string;
+}
+```
+
+## Common Patterns
+
+### Emit audit events only on errors
+
+```ts
+await withAudit(
+  { action: 'account.suspend', resource: 'account', actorId: 'admin-1' },
+  async (ctx, log) => {
+    try {
+      await suspendAccount();
+    } catch (err) {
+      log.error(err); // Auto-tagged with outcome: failure
+      throw;
+    }
+  },
+  { emitNow: true },
+);
+```
+
+### Track sensitive operations with context
+
+```ts
+await withAudit(
+  {
+    action: 'secret.access',
+    resource: 'api-key',
+    actorId: user.id,
+    secretType: 'api-key',
+    env: 'prod',
+  },
+  async () => {
+    // Fetch secret...
+  },
+  { emitNow: true, forceKeep: true },
+);
+```
+
+### Nested audit context in complex flows
+
+```ts
+export const transferFunds = trace(async (transfer) => {
+  return withAudit(
+    {
+      action: 'transfer.execute',
+      resource: 'transaction',
+      actorId: transfer.initiator,
+      amount: transfer.amount,
+      fromAccount: transfer.from,
+      toAccount: transfer.to,
+    },
+    async (ctx, log) => {
+      const debitResult = await debitAccount(transfer.from, transfer.amount);
+      const creditResult = await creditAccount(transfer.to, transfer.amount);
+
+      log.info('Transfer completed', {
+        transactionId: debitResult.txId,
+        debitStatus: debitResult.status,
+        creditStatus: creditResult.status,
+      });
+
+      return { success: true, txId: debitResult.txId };
+    },
+    { emitNow: true },
+  );
+});
+```
+
+## Compliance & Sampling
+
+### Why force-keep audit events?
+
+Tail-sampling decisions are made after spans complete. Critical audit trails need guaranteed export regardless of sampling rate. `forceKeepAuditEvent()` marks spans as keeper-worthy, ensuring they bypass statistical sampling.
+
+```ts
+// Default: force-keep is enabled (critical for audit)
+await withAudit(metadata, fn);
+
+// Disable if audit backend has separate retention
+await withAudit(metadata, fn, { forceKeep: false });
+
+// Manual control for hybrid scenarios
+if (isPrivilegedOperation) {
+  forceKeepAuditEvent();
+}
+```
+
+## Integration with Observability Backends
+
+Audit attributes are standard OpenTelemetry span attributes and work with any OTLP-compatible backend (Datadog, New Relic, Jaeger, etc.).
+
+- Attributes are stored as `audit.action`, `audit.resource`, `audit.actorId`, etc.
+- Root span contains `autotel.audit: true` for filtering
+- Use backend span filters to create audit dashboards and alerts
+
+## See Also
+
+- **[Advanced Features](/advanced)** — Trace helpers, metadata flattening, isolated tracer providers
+- **[Request Logging](/integrations/logging)** — Structured request context and event emission
+- **[Autotel Core](/)** — `trace()`, `span()`, and request context patterns

package/dist/index.cjs

@@ -0,0 +1,119 @@
+'use strict';
+
+var autotel = require('autotel');
+
+// src/index.ts
+function resolveContext(ctx) {
+  if (ctx) return ctx;
+  const ids = autotel.getTraceContext();
+  const span = autotel.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."
+  );
+}
+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>";
+  }
+}
+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;
+}
+function forceKeepAuditEvent(ctx) {
+  const traceCtx = resolveContext(ctx);
+  traceCtx.setAttribute(autotel.AUTOTEL_SAMPLING_TAIL_EVALUATED, true);
+  traceCtx.setAttribute(autotel.AUTOTEL_SAMPLING_TAIL_KEEP, true);
+  traceCtx.setAttribute("autotel.audit.force_keep", true);
+}
+function setAuditAttributes(metadata, ctx) {
+  const traceCtx = resolveContext(ctx);
+  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 ?? autotel.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;
+  }
+}
+
+exports.forceKeepAuditEvent = forceKeepAuditEvent;
+exports.setAuditAttributes = setAuditAttributes;
+exports.withAudit = withAudit;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["getTraceContext","otelTrace","AUTOTEL_SAMPLING_TAIL_EVALUATED","AUTOTEL_SAMPLING_TAIL_KEEP","getRequestLogger"],"mappings":"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","file":"index.cjs","sourcesContent":["import {\n  AUTOTEL_SAMPLING_TAIL_EVALUATED,\n  AUTOTEL_SAMPLING_TAIL_KEEP,\n  getRequestLogger,\n  getTraceContext,\n  otelTrace,\n} from 'autotel';\nimport type { RequestLogger } from 'autotel';\n\nexport interface AuditMetadata {\n  action: string;\n  resource?: string;\n  actorId?: string;\n  category?: string;\n  outcome?: 'success' | 'failure' | (string & {});\n  [key: string]: unknown;\n}\n\nexport interface WithAuditOptions {\n  ctx?: AuditContext;\n  emitNow?: boolean;\n  forceKeep?: boolean;\n  logger?: RequestLogger;\n}\n\nexport interface AuditContext {\n  traceId: string;\n  spanId: string;\n  correlationId: string;\n  setAttribute(key: string, value: string | number | boolean): void;\n  setAttributes(\n    attrs: Record<string, string | number | boolean | string[] | number[] | boolean[]>,\n  ): void;\n}\n\nfunction resolveContext(ctx?: AuditContext): AuditContext {\n  if (ctx) return ctx;\n\n  const ids = getTraceContext();\n  const span = otelTrace.getActiveSpan();\n  if (ids && span) {\n    return {\n      traceId: ids.traceId,\n      spanId: ids.spanId,\n      correlationId: ids.correlationId,\n      setAttribute: (key, value) => span.setAttribute(key, value),\n      setAttributes: (attrs) => span.setAttributes(attrs),\n    };\n  }\n\n  throw new Error(\n    '[autotel-audit] No active trace context. Wrap your handler with trace() or pass options.ctx.',\n  );\n}\n\nfunction toAttributeValue(\n  value: unknown,\n): string | number | boolean | string[] | number[] | boolean[] | undefined {\n  if (\n    typeof value === 'string' ||\n    typeof value === 'number' ||\n    typeof value === 'boolean'\n  ) {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    if (value.every((entry) => typeof entry === 'string')) {\n      return value;\n    }\n\n    if (value.every((entry) => typeof entry === 'number')) {\n      return value;\n    }\n\n    if (value.every((entry) => typeof entry === 'boolean')) {\n      return value;\n    }\n\n    try {\n      return JSON.stringify(value);\n    } catch {\n      return '<serialization-failed>';\n    }\n  }\n\n  if (value instanceof Date) {\n    return value.toISOString();\n  }\n\n  if (value === null || value === undefined) {\n    return undefined;\n  }\n\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return '<serialization-failed>';\n  }\n}\n\nfunction flattenAuditAttributes(\n  metadata: AuditMetadata,\n): Record<string, string | number | boolean | string[] | number[] | boolean[]> {\n  const attributes: Record<\n    string,\n    string | number | boolean | string[] | number[] | boolean[]\n  > = {\n    'autotel.audit': true,\n  };\n\n  for (const [key, value] of Object.entries(metadata)) {\n    const attr = toAttributeValue(value);\n    if (attr !== undefined) {\n      attributes[`audit.${key}`] = attr;\n    }\n  }\n\n  return attributes;\n}\n\nexport function forceKeepAuditEvent(ctx?: AuditContext): void {\n  const traceCtx = resolveContext(ctx);\n  traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_EVALUATED, true);\n  traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_KEEP, true);\n  traceCtx.setAttribute('autotel.audit.force_keep', true);\n}\n\nexport function setAuditAttributes(\n  metadata: AuditMetadata,\n  ctx?: AuditContext,\n): void {\n  const traceCtx = resolveContext(ctx);\n  traceCtx.setAttributes(flattenAuditAttributes(metadata));\n}\n\nexport async function withAudit<T>(\n  metadata: AuditMetadata,\n  fn: (ctx: AuditContext, logger: RequestLogger) => T | Promise<T>,\n  options: WithAuditOptions = {},\n): Promise<T> {\n  const traceCtx = resolveContext(options.ctx);\n\n  if (options.forceKeep !== false) {\n    forceKeepAuditEvent(traceCtx);\n  }\n\n  setAuditAttributes(metadata, traceCtx);\n\n  const logger = options.logger ?? getRequestLogger();\n  logger.set({\n    audit: {\n      ...metadata,\n      forceKeep: options.forceKeep !== false,\n    },\n  });\n\n  try {\n    const result = await fn(traceCtx, logger);\n\n    if (!metadata.outcome) {\n      setAuditAttributes({ ...metadata, outcome: 'success' }, traceCtx);\n    }\n\n    if (options.emitNow) {\n      logger.emitNow();\n    }\n\n    return result;\n  } catch (error) {\n    const asError = error instanceof Error ? error : new Error(String(error));\n    setAuditAttributes({ ...metadata, outcome: 'failure' }, traceCtx);\n    logger.error(asError, {\n      audit: {\n        action: metadata.action,\n        resource: metadata.resource,\n      },\n    });\n\n    if (options.emitNow) {\n      logger.emitNow();\n    }\n\n    throw asError;\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,28 @@
+import { RequestLogger } from 'autotel';
+
+interface AuditMetadata {
+    action: string;
+    resource?: string;
+    actorId?: string;
+    category?: string;
+    outcome?: 'success' | 'failure' | (string & {});
+    [key: string]: unknown;
+}
+interface WithAuditOptions {
+    ctx?: AuditContext;
+    emitNow?: boolean;
+    forceKeep?: boolean;
+    logger?: RequestLogger;
+}
+interface AuditContext {
+    traceId: string;
+    spanId: string;
+    correlationId: string;
+    setAttribute(key: string, value: string | number | boolean): void;
+    setAttributes(attrs: Record<string, string | number | boolean | string[] | number[] | boolean[]>): void;
+}
+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 { type AuditContext, type AuditMetadata, type WithAuditOptions, forceKeepAuditEvent, setAuditAttributes, withAudit };

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { RequestLogger } from 'autotel';
+
+interface AuditMetadata {
+    action: string;
+    resource?: string;
+    actorId?: string;
+    category?: string;
+    outcome?: 'success' | 'failure' | (string & {});
+    [key: string]: unknown;
+}
+interface WithAuditOptions {
+    ctx?: AuditContext;
+    emitNow?: boolean;
+    forceKeep?: boolean;
+    logger?: RequestLogger;
+}
+interface AuditContext {
+    traceId: string;
+    spanId: string;
+    correlationId: string;
+    setAttribute(key: string, value: string | number | boolean): void;
+    setAttributes(attrs: Record<string, string | number | boolean | string[] | number[] | boolean[]>): void;
+}
+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 { type AuditContext, type AuditMetadata, type WithAuditOptions, forceKeepAuditEvent, setAuditAttributes, withAudit };

package/dist/index.js

@@ -0,0 +1,115 @@
+import { AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, getRequestLogger, getTraceContext, otelTrace } from 'autotel';
+
+// 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."
+  );
+}
+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>";
+  }
+}
+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;
+}
+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);
+}
+function setAuditAttributes(metadata, ctx) {
+  const traceCtx = resolveContext(ctx);
+  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;
+  }
+}
+
+export { forceKeepAuditEvent, setAuditAttributes, withAudit };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import {\n  AUTOTEL_SAMPLING_TAIL_EVALUATED,\n  AUTOTEL_SAMPLING_TAIL_KEEP,\n  getRequestLogger,\n  getTraceContext,\n  otelTrace,\n} from 'autotel';\nimport type { RequestLogger } from 'autotel';\n\nexport interface AuditMetadata {\n  action: string;\n  resource?: string;\n  actorId?: string;\n  category?: string;\n  outcome?: 'success' | 'failure' | (string & {});\n  [key: string]: unknown;\n}\n\nexport interface WithAuditOptions {\n  ctx?: AuditContext;\n  emitNow?: boolean;\n  forceKeep?: boolean;\n  logger?: RequestLogger;\n}\n\nexport interface AuditContext {\n  traceId: string;\n  spanId: string;\n  correlationId: string;\n  setAttribute(key: string, value: string | number | boolean): void;\n  setAttributes(\n    attrs: Record<string, string | number | boolean | string[] | number[] | boolean[]>,\n  ): void;\n}\n\nfunction resolveContext(ctx?: AuditContext): AuditContext {\n  if (ctx) return ctx;\n\n  const ids = getTraceContext();\n  const span = otelTrace.getActiveSpan();\n  if (ids && span) {\n    return {\n      traceId: ids.traceId,\n      spanId: ids.spanId,\n      correlationId: ids.correlationId,\n      setAttribute: (key, value) => span.setAttribute(key, value),\n      setAttributes: (attrs) => span.setAttributes(attrs),\n    };\n  }\n\n  throw new Error(\n    '[autotel-audit] No active trace context. Wrap your handler with trace() or pass options.ctx.',\n  );\n}\n\nfunction toAttributeValue(\n  value: unknown,\n): string | number | boolean | string[] | number[] | boolean[] | undefined {\n  if (\n    typeof value === 'string' ||\n    typeof value === 'number' ||\n    typeof value === 'boolean'\n  ) {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    if (value.every((entry) => typeof entry === 'string')) {\n      return value;\n    }\n\n    if (value.every((entry) => typeof entry === 'number')) {\n      return value;\n    }\n\n    if (value.every((entry) => typeof entry === 'boolean')) {\n      return value;\n    }\n\n    try {\n      return JSON.stringify(value);\n    } catch {\n      return '<serialization-failed>';\n    }\n  }\n\n  if (value instanceof Date) {\n    return value.toISOString();\n  }\n\n  if (value === null || value === undefined) {\n    return undefined;\n  }\n\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return '<serialization-failed>';\n  }\n}\n\nfunction flattenAuditAttributes(\n  metadata: AuditMetadata,\n): Record<string, string | number | boolean | string[] | number[] | boolean[]> {\n  const attributes: Record<\n    string,\n    string | number | boolean | string[] | number[] | boolean[]\n  > = {\n    'autotel.audit': true,\n  };\n\n  for (const [key, value] of Object.entries(metadata)) {\n    const attr = toAttributeValue(value);\n    if (attr !== undefined) {\n      attributes[`audit.${key}`] = attr;\n    }\n  }\n\n  return attributes;\n}\n\nexport function forceKeepAuditEvent(ctx?: AuditContext): void {\n  const traceCtx = resolveContext(ctx);\n  traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_EVALUATED, true);\n  traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_KEEP, true);\n  traceCtx.setAttribute('autotel.audit.force_keep', true);\n}\n\nexport function setAuditAttributes(\n  metadata: AuditMetadata,\n  ctx?: AuditContext,\n): void {\n  const traceCtx = resolveContext(ctx);\n  traceCtx.setAttributes(flattenAuditAttributes(metadata));\n}\n\nexport async function withAudit<T>(\n  metadata: AuditMetadata,\n  fn: (ctx: AuditContext, logger: RequestLogger) => T | Promise<T>,\n  options: WithAuditOptions = {},\n): Promise<T> {\n  const traceCtx = resolveContext(options.ctx);\n\n  if (options.forceKeep !== false) {\n    forceKeepAuditEvent(traceCtx);\n  }\n\n  setAuditAttributes(metadata, traceCtx);\n\n  const logger = options.logger ?? getRequestLogger();\n  logger.set({\n    audit: {\n      ...metadata,\n      forceKeep: options.forceKeep !== false,\n    },\n  });\n\n  try {\n    const result = await fn(traceCtx, logger);\n\n    if (!metadata.outcome) {\n      setAuditAttributes({ ...metadata, outcome: 'success' }, traceCtx);\n    }\n\n    if (options.emitNow) {\n      logger.emitNow();\n    }\n\n    return result;\n  } catch (error) {\n    const asError = error instanceof Error ? error : new Error(String(error));\n    setAuditAttributes({ ...metadata, outcome: 'failure' }, traceCtx);\n    logger.error(asError, {\n      audit: {\n        action: metadata.action,\n        resource: metadata.resource,\n      },\n    });\n\n    if (options.emitNow) {\n      logger.emitNow();\n    }\n\n    throw asError;\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "autotel-audit",
+  "version": "0.1.0",
+  "description": "Audit-focused helpers for Autotel (force-keep + structured audit instrumentation)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/**/*.ts",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "autotel",
+    "audit",
+    "compliance",
+    "opentelemetry",
+    "tail-sampling"
+  ],
+  "author": "Jag Reehal <jag@jagreehal.com> (https://jagreehal.com)",
+  "license": "MIT",
+  "dependencies": {
+    "autotel": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.1",
+    "@typescript-eslint/parser": "^8.59.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-unicorn": "^64.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.1",
+    "vitest": "^4.1.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jagreehal/autotel",
+    "directory": "packages/autotel-audit"
+  },
+  "bugs": {
+    "url": "https://github.com/jagreehal/autotel/issues"
+  },
+  "homepage": "https://github.com/jagreehal/autotel#readme"
+}

package/src/index.test.ts

@@ -0,0 +1,128 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  forceKeepAuditEvent,
+  setAuditAttributes,
+  withAudit,
+  type AuditMetadata,
+} from './index';
+
+const setAttribute = vi.fn();
+const setAttributes = vi.fn();
+const mockCtx = {
+  traceId: 'trace-1',
+  spanId: 'span-1',
+  correlationId: 'corr-1',
+  setAttribute,
+  setAttributes,
+  setStatus: vi.fn(),
+  addLink: vi.fn(),
+  addLinks: vi.fn(),
+  updateName: vi.fn(),
+  isRecording: vi.fn(() => true),
+  recordError: vi.fn(),
+  track: vi.fn(),
+  getBaggage: vi.fn(),
+  setBaggage: vi.fn(),
+  deleteBaggage: vi.fn(),
+  getAllBaggage: vi.fn(),
+  getTypedBaggage: vi.fn(),
+  setTypedBaggage: vi.fn(),
+  withBaggage: vi.fn(),
+};
+
+const logger = {
+  set: vi.fn(),
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  getContext: vi.fn(() => ({})),
+  emitNow: vi.fn(() => ({
+    timestamp: new Date().toISOString(),
+    traceId: 'trace-1',
+    spanId: 'span-1',
+    correlationId: 'corr-1',
+    context: {},
+  })),
+  fork: vi.fn(),
+};
+
+vi.mock('autotel', () => ({
+  AUTOTEL_SAMPLING_TAIL_EVALUATED: 'autotel.sampling.tail.evaluated',
+  AUTOTEL_SAMPLING_TAIL_KEEP: 'autotel.sampling.tail.keep',
+  getTraceContext: vi.fn(() => mockCtx),
+  getRequestLogger: vi.fn(() => logger),
+  otelTrace: {
+    getActiveSpan: vi.fn(() => ({
+      setAttribute,
+      setAttributes,
+    })),
+  },
+}));
+
+describe('autotel-audit', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('forceKeepAuditEvent sets tail keep attributes', () => {
+    forceKeepAuditEvent(mockCtx as never);
+
+    expect(setAttribute).toHaveBeenCalledWith(
+      'autotel.sampling.tail.evaluated',
+      true,
+    );
+    expect(setAttribute).toHaveBeenCalledWith('autotel.sampling.tail.keep', true);
+    expect(setAttribute).toHaveBeenCalledWith('autotel.audit.force_keep', true);
+  });
+
+  it('setAuditAttributes writes audit.* attributes', () => {
+    const metadata: AuditMetadata = {
+      action: 'user.delete',
+      resource: 'account',
+      actorId: 'admin-1',
+    };
+
+    setAuditAttributes(metadata, mockCtx as never);
+
+    expect(setAttributes).toHaveBeenCalledWith(
+      expect.objectContaining({
+        'autotel.audit': true,
+        'audit.action': 'user.delete',
+        'audit.resource': 'account',
+        'audit.actorId': 'admin-1',
+      }),
+    );
+  });
+
+  it('withAudit marks success and optionally emits', async () => {
+    const result = await withAudit(
+      { action: 'permission.update', resource: 'role' },
+      async () => 'ok',
+      { emitNow: true },
+    );
+
+    expect(result).toBe('ok');
+    expect(logger.set).toHaveBeenCalled();
+    expect(setAttributes).toHaveBeenCalledWith(
+      expect.objectContaining({
+        'audit.outcome': 'success',
+      }),
+    );
+    expect(logger.emitNow).toHaveBeenCalledTimes(1);
+  });
+
+  it('withAudit marks failure and rethrows', async () => {
+    await expect(
+      withAudit({ action: 'secrets.read' }, async () => {
+        throw new Error('denied');
+      }),
+    ).rejects.toThrow('denied');
+
+    expect(setAttributes).toHaveBeenCalledWith(
+      expect.objectContaining({
+        'audit.outcome': 'failure',
+      }),
+    );
+    expect(logger.error).toHaveBeenCalledTimes(1);
+  });
+});

package/src/index.ts

@@ -0,0 +1,186 @@
+import {
+  AUTOTEL_SAMPLING_TAIL_EVALUATED,
+  AUTOTEL_SAMPLING_TAIL_KEEP,
+  getRequestLogger,
+  getTraceContext,
+  otelTrace,
+} from 'autotel';
+import type { RequestLogger } from 'autotel';
+
+export interface AuditMetadata {
+  action: string;
+  resource?: string;
+  actorId?: string;
+  category?: string;
+  outcome?: 'success' | 'failure' | (string & {});
+  [key: string]: unknown;
+}
+
+export interface WithAuditOptions {
+  ctx?: AuditContext;
+  emitNow?: boolean;
+  forceKeep?: boolean;
+  logger?: RequestLogger;
+}
+
+export interface AuditContext {
+  traceId: string;
+  spanId: string;
+  correlationId: string;
+  setAttribute(key: string, value: string | number | boolean): void;
+  setAttributes(
+    attrs: Record<string, string | number | boolean | string[] | number[] | boolean[]>,
+  ): void;
+}
+
+function resolveContext(ctx?: AuditContext): AuditContext {
+  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.',
+  );
+}
+
+function toAttributeValue(
+  value: unknown,
+): string | number | boolean | string[] | number[] | boolean[] | undefined {
+  if (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    if (value.every((entry) => typeof entry === 'string')) {
+      return value;
+    }
+
+    if (value.every((entry) => typeof entry === 'number')) {
+      return value;
+    }
+
+    if (value.every((entry) => typeof entry === 'boolean')) {
+      return value;
+    }
+
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return '<serialization-failed>';
+    }
+  }
+
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  if (value === null || value === undefined) {
+    return undefined;
+  }
+
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return '<serialization-failed>';
+  }
+}
+
+function flattenAuditAttributes(
+  metadata: AuditMetadata,
+): Record<string, string | number | boolean | string[] | number[] | boolean[]> {
+  const attributes: Record<
+    string,
+    string | number | boolean | string[] | number[] | boolean[]
+  > = {
+    'autotel.audit': true,
+  };
+
+  for (const [key, value] of Object.entries(metadata)) {
+    const attr = toAttributeValue(value);
+    if (attr !== undefined) {
+      attributes[`audit.${key}`] = attr;
+    }
+  }
+
+  return attributes;
+}
+
+export function forceKeepAuditEvent(ctx?: AuditContext): void {
+  const traceCtx = resolveContext(ctx);
+  traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_EVALUATED, true);
+  traceCtx.setAttribute(AUTOTEL_SAMPLING_TAIL_KEEP, true);
+  traceCtx.setAttribute('autotel.audit.force_keep', true);
+}
+
+export function setAuditAttributes(
+  metadata: AuditMetadata,
+  ctx?: AuditContext,
+): void {
+  const traceCtx = resolveContext(ctx);
+  traceCtx.setAttributes(flattenAuditAttributes(metadata));
+}
+
+export async function withAudit<T>(
+  metadata: AuditMetadata,
+  fn: (ctx: AuditContext, logger: RequestLogger) => T | Promise<T>,
+  options: WithAuditOptions = {},
+): Promise<T> {
+  const traceCtx = 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;
+  }
+}