autotel-edge 3.17.0 → 3.17.2

package/src/api/redact.ts

@@ -1,402 +0,0 @@
-/**
- * Redaction utility for structured log output
- *
- * Inspired by pino's redaction — zero-dependency, edge-compatible.
- * Supports deep paths, wildcards, and custom censor values.
- *
- * @example
- * ```typescript
- * const redactor = createRedactor({
- *   paths: ['password', 'user.email', 'headers.authorization'],
- * })
- * const safe = redactor({ password: 'secret', user: { email: 'a@b.com' } })
- * // { password: '[Redacted]', user: { email: '[Redacted]' } }
- * ```
- */
-
-const DEFAULT_CENSOR = '[Redacted]';
-
-/**
- * Validate and parse a dot/bracket path string into segments.
- *
- * Valid: "user.email", "users[*].name", "headers.*", "[0].secret"
- * Invalid: "user..email", "user[", "foo.]bar", ""
- */
-function parsePath(path: string): string[] {
-  if (typeof path !== 'string' || path.length === 0) {
-    throw new Error(
-      `redact path must be a non-empty string, got: ${JSON.stringify(path)}`,
-    );
-  }
-
-  // Reject obviously malformed paths
-  if (path.includes('..')) {
-    throw new Error(
-      `redact path contains empty segment: ${JSON.stringify(path)}`,
-    );
-  }
-  // Unmatched brackets: "[" with no "]" or vice versa
-  const openBracket = path.indexOf('[');
-  const closeBracket = path.indexOf(']');
-  if (
-    (openBracket !== -1 && closeBracket === -1) ||
-    (closeBracket !== -1 && openBracket === -1)
-  ) {
-    throw new Error(
-      `redact path has unclosed bracket: ${JSON.stringify(path)}`,
-    );
-  }
-  if (openBracket !== -1 && closeBracket < openBracket) {
-    throw new Error(
-      `redact path has bracket close before open: ${JSON.stringify(path)}`,
-    );
-  }
-  if (/\[\s*\]$/.test(path)) {
-    throw new Error(
-      `redact path has unclosed bracket: ${JSON.stringify(path)}`,
-    );
-  }
-  if (/\][^.[\]]/.test(path) && !/\]\[/.test(path)) {
-    // e.g. "foo.]bar" — closing bracket not followed by dot, bracket, or end
-    const afterClose = path.match(/\]([^.[\]]+)/);
-    if (afterClose) {
-      throw new Error(
-        `redact path has invalid characters after ']': ${JSON.stringify(path)}`,
-      );
-    }
-  }
-
-  const segments: string[] = [];
-  const rx = /[^.[\]]+|\[(\d+|\*)\]/g;
-  let match: RegExpExecArray | null;
-  let lastIndex = 0;
-  while ((match = rx.exec(path)) !== null) {
-    segments.push(match[1] ?? match[0]);
-    lastIndex = rx.lastIndex;
-  }
-
-  // If the regex didn't consume the whole string, something is malformed
-  if (lastIndex < path.length) {
-    throw new Error(
-      `redact path has unexpected trailing content: ${JSON.stringify(path)}`,
-    );
-  }
-
-  if (segments.length === 0) {
-    throw new Error(
-      `redact path produced no segments: ${JSON.stringify(path)}`,
-    );
-  }
-
-  return segments;
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  if (value === null || typeof value !== 'object') return false;
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
-}
-
-/**
- * Deep clone plain objects and arrays only.
- * Non-plain objects (Date, Map, Set, class instances) are returned by reference.
- */
-function deepClone<T>(value: T): T {
-  if (value === null || typeof value !== 'object') return value;
-  if (Array.isArray(value)) return value.map((v) => deepClone(v)) as T;
-  if (!isPlainObject(value)) return value;
-  const result: Record<string, unknown> = {};
-  for (const key of Object.keys(value)) {
-    result[key] = deepClone((value as Record<string, unknown>)[key]);
-  }
-  return result as T;
-}
-
-/**
- * A node in the compiled path tree.
- *
- * Unlike a simple PathTree | null representation, a node can be both
- * a redact target AND a parent for deeper paths. This correctly handles
- * overlapping paths like ['user', 'user.email'].
- */
-interface PathNode {
-  redact?: boolean;
-  children?: Record<string, PathNode>;
-}
-
-/**
- * Insert a parsed path into the tree.
- *
- * buildPathTree([['user'], ['user', 'email']]) produces:
- * { user: { redact: true, children: { email: { redact: true } } } }
- */
-function buildPathTree(paths: string[][]): PathNode {
-  const root: PathNode = {};
-  for (const segments of paths) {
-    let node = root;
-    for (let i = 0; i < segments.length; i++) {
-      const seg = segments[i];
-      const isLast = i === segments.length - 1;
-
-      if (!node.children) node.children = {};
-      if (!node.children[seg]) node.children[seg] = {};
-
-      if (isLast) {
-        node.children[seg].redact = true;
-      }
-      node = node.children[seg];
-    }
-  }
-  return root;
-}
-
-/**
- * Walk a compiled path tree and redact matching values in `obj`.
- * Mutates `obj` in place (caller should clone before calling).
- */
-function redactWithTree(
-  obj: Record<string, any>,
-  node: PathNode,
-  censor: Censor,
-  remove: boolean,
-  path: string[] = [],
-): void {
-  if (!node.children) return;
-
-  const applyCensor = (target: Record<string, any>, k: string, currentPath: string[]) => {
-    if (remove) {
-      delete target[k];
-    } else {
-      target[k] = typeof censor === 'function' ? censor(target[k], currentPath) : censor;
-    }
-  };
-
-  for (const [key, childNode] of Object.entries(node.children)) {
-    if (key === '*') {
-      for (const k of Object.keys(obj)) {
-        const wildcardPath = [...path, k];
-        if (childNode.redact && !childNode.children) {
-          applyCensor(obj, k, wildcardPath);
-        } else if (childNode.redact && childNode.children) {
-          const child = obj[k];
-          if (
-            child != null &&
-            typeof child === 'object' &&
-            !Array.isArray(child)
-          ) {
-            redactWithTree(child, childNode, censor, remove, wildcardPath);
-          } else {
-            applyCensor(obj, k, wildcardPath);
-          }
-        } else if (childNode.children) {
-          const child = obj[k];
-          if (child != null && typeof child === 'object') {
-            redactWithTree(child, childNode, censor, remove, wildcardPath);
-          }
-        }
-      }
-      continue;
-    }
-
-    if (!Object.prototype.hasOwnProperty.call(obj, key)) continue;
-
-    const val = obj[key];
-    const currentPath = [...path, key];
-
-    if (childNode.redact && !childNode.children) {
-      applyCensor(obj, key, currentPath);
-    } else if (childNode.redact && childNode.children) {
-      if (val != null && typeof val === 'object') {
-        redactWithTree(val, childNode, censor, remove, currentPath);
-      }
-    } else if (childNode.children && val != null && typeof val === 'object') {
-      redactWithTree(val, childNode, censor, remove, currentPath);
-    }
-  }
-}
-
-export type Censor = string | ((value: unknown, path: string[]) => unknown);
-
-export interface RedactorOptions {
-  paths: string[];
-  censor?: Censor;
-  remove?: boolean;
-}
-
-/**
- * Preset name or explicit options
- */
-export type RedactorConfig = RedactorOptions | RedactorPreset;
-
-export type RedactorPreset = 'default' | 'strict' | 'pci-dss';
-
-/**
- * Paths that match the main autotel package's `sensitiveKey` pattern:
- * `/^(password|passwd|pwd|secret|token|api[_-]?key|auth|credential|private[_-]?key|authorization)$/i`
- *
- * Copied here so the edge logger stays zero-dependency.
- */
-const SENSITIVE_KEY_PATHS = [
-  'password',
-  'passwd',
-  'pwd',
-  'secret',
-  'token',
-  'apiKey',
-  'api_key',
-  'auth',
-  'credential',
-  'privateKey',
-  'private_key',
-  'authorization',
-];
-
-/**
- * Common request header paths that often carry secrets.
- */
-const SENSITIVE_HEADER_PATHS = [
-  'req.headers.authorization',
-  'req.headers.cookie',
-  'headers.authorization',
-  'headers.cookie',
-  'request.headers.authorization',
-  'request.headers.cookie',
-];
-
-/**
- * Built-in redactor presets.
- *
- * - `default` — sensitive keys + request headers (passwords, tokens, secrets, auth headers)
- * - `strict` — default + bearer/jwt/api-key patterns nested at any depth
- * - `pci-dss` — credit card and payment-related fields
- */
-export const REDACT_PRESETS: Record<RedactorPreset, RedactorOptions> = {
-  /**
-   * Default: covers the same sensitive-key names as the main autotel package's
-   * `sensitiveKey` pattern, plus common request header paths.
-   *
-   * Redacted keys: password, passwd, pwd, secret, token, apiKey, auth,
-   *                credential, privateKey, authorization
-   * Redacted headers: req.headers.authorization, req.headers.cookie, etc.
-   */
-  default: {
-    paths: [...SENSITIVE_KEY_PATHS, ...SENSITIVE_HEADER_PATHS],
-  },
-
-  /**
-   * Strict: everything in default, plus nested paths for bearer tokens,
-   * JWT fields, and API key fields at common depths.
-   */
-  strict: {
-    paths: [
-      ...SENSITIVE_KEY_PATHS,
-      ...SENSITIVE_HEADER_PATHS,
-      // Common nested auth shapes
-      'bearer',
-      'jwt',
-      'apiSecret',
-      'api_secret',
-      'accessToken',
-      'access_token',
-      'refreshToken',
-      'refresh_token',
-      'clientSecret',
-      'client_secret',
-    ],
-  },
-
-  /**
-   * PCI-DSS: credit card and payment-related fields.
-   */
-  'pci-dss': {
-    paths: [
-      'card',
-      'cardNumber',
-      'card_number',
-      'ccn',
-      'pan',
-      'cvv',
-      'cvc',
-      'expirationDate',
-      'expiration_date',
-      'exp',
-      'payment.card',
-      'payment.cardNumber',
-      'payment.cvv',
-    ],
-  },
-};
-
-/**
- * Resolve a preset name or explicit options into RedactorOptions.
- */
-function resolveConfig(config: RedactorConfig): RedactorOptions {
-  if (typeof config === 'string') {
-    const preset = REDACT_PRESETS[config];
-    if (!preset) {
-      throw new Error(
-        `Unknown redactor preset: "${config}". Available: ${Object.keys(REDACT_PRESETS).join(', ')}`,
-      );
-    }
-    return preset;
-  }
-  return config;
-}
-
-/**
- * Create a redactor function from a list of paths.
- *
- * Paths use dot notation for nested fields and `[*]` or `*` for wildcards:
- * - `"password"` — top-level key
- * - `"user.email"` — nested field
- * - `"users[*].password"` or `"users.*.password"` — all items in array/object
- * - `"headers.authorization"` — nested header
- * - `"[*].secret"` — wildcard at root
- *
- * Overlapping paths are supported — e.g. `['user', 'user.email']` will
- * redact `user` as a whole while still recursing into `user.email`.
- *
- * The returned function clones plain objects/arrays before mutating,
- * so the original is never modified. Non-plain objects (Date, Map, etc.)
- * are passed through by reference.
- *
- * @example
- * ```typescript
- * // Using a preset
- * const redactor = createRedactor('default')
- *
- * // Using explicit paths
- * const redactor = createRedactor({
- *   paths: ['password', 'token', 'user.email', 'users[*].ssn'],
- *   censor: '[Filtered]',       // optional, default '[Redacted]'
- * })
- *
- * redactor({ password: 's3cret', user: { email: 'a@b.com' } })
- * // → { password: '[Filtered]', user: { email: '[Filtered]' } }
- *
- * // Custom censor function:
- * const mask = createRedactor({
- *   paths: ['ccn'],
- *   censor: (val) => '****' + String(val).slice(-4),
- * })
- * ```
- */
-export function createRedactor(config: RedactorConfig): <T>(obj: T) => T {
-  const { paths, censor = DEFAULT_CENSOR, remove = false } = resolveConfig(config);
-
-  if (paths.length === 0) {
-    return <T>(obj: T): T => obj;
-  }
-
-  const parsed = paths.map((p) => parsePath(p));
-  const tree = buildPathTree(parsed);
-
-  return function redactor<T>(obj: T): T {
-    if (obj == null || typeof obj !== 'object') return obj;
-
-    // Clone so we don't mutate the original log entry
-    const clone = deepClone(obj) as Record<string, any>;
-    redactWithTree(clone, tree, censor, remove);
-    return clone as T;
-  };
-}

package/src/compose.ts

@@ -1,243 +0,0 @@
-/**
- * Composition utilities for autotel-edge
- *
- * Helper functions for composing instrumentation and middleware.
- *
- * @example
- * ```typescript
- * import { compose } from 'autotel-edge/api/compose'
- * import { instrumentGlobalFetch, instrumentGlobalCache } from 'autotel-edge/instrumentation'
- *
- * const setupInstrumentation = compose(
- *   instrumentGlobalFetch,
- *   instrumentGlobalCache
- * )
- *
- * setupInstrumentation({ enabled: true })
- * ```
- */
-
-/**
- * Compose multiple setup functions into one
- *
- * Takes multiple instrumentation functions and returns a single function
- * that calls them all in order with the same config.
- *
- * @example
- * ```typescript
- * const setup = compose(
- *   instrumentGlobalFetch,
- *   instrumentGlobalCache
- * )
- *
- * setup({ enabled: true })
- * ```
- */
-export function compose<TConfig = unknown>(
-  ...fns: Array<(config?: TConfig) => void>
-): (config?: TConfig) => void {
-  return (config?: TConfig) => {
-    for (const fn of fns) {
-      fn(config);
-    }
-  };
-}
-
-/**
- * Compose multiple async setup functions into one
- *
- * Like `compose` but for async functions.
- *
- * @example
- * ```typescript
- * const setup = composeAsync(
- *   async (config) => { await initTracing(config) },
- *   async (config) => { await initMetrics(config) }
- * )
- *
- * await setup({ endpoint: 'https://...' })
- * ```
- */
-export function composeAsync<TConfig = unknown>(
-  ...fns: Array<(config?: TConfig) => Promise<void>>
-): (config?: TConfig) => Promise<void> {
-  return async (config?: TConfig) => {
-    for (const fn of fns) {
-      await fn(config);
-    }
-  };
-}
-
-/**
- * Pipe - compose functions from left to right
- *
- * Unlike `compose` which is right-to-left, pipe is left-to-right
- * which matches the execution order visually.
- *
- * @example
- * ```typescript
- * const setup = pipe(
- *   (config) => ({ ...config, tracing: true }),
- *   (config) => ({ ...config, metrics: true }),
- *   (config) => initObservability(config)
- * )
- *
- * setup({ service: 'my-worker' })
- * ```
- */
-export function pipe<TInput, TOutput>(
-  ...fns: Array<(input: any) => any>
-): (input: TInput) => TOutput {
-  return (input: TInput) => {
-    return fns.reduce((acc, fn) => fn(acc), input as any) as TOutput;
-  };
-}
-
-/**
- * Create a conditional instrumentation function
- *
- * Only runs the instrumentation if the predicate returns true.
- *
- * @example
- * ```typescript
- * const setupFetch = when(
- *   (env) => env.ENABLE_FETCH_TRACING === 'true',
- *   instrumentGlobalFetch
- * )
- *
- * setupFetch(env)
- * ```
- */
-export function when<TConfig = unknown>(
-  predicate: (config?: TConfig) => boolean,
-  fn: (config?: TConfig) => void
-): (config?: TConfig) => void {
-  return (config?: TConfig) => {
-    if (predicate(config)) {
-      fn(config);
-    }
-  };
-}
-
-/**
- * Create a conditional async instrumentation function
- *
- * @example
- * ```typescript
- * const setupCache = whenAsync(
- *   async (env) => await featureEnabled('cache-tracing'),
- *   instrumentGlobalCache
- * )
- *
- * await setupCache(env)
- * ```
- */
-export function whenAsync<TConfig = unknown>(
-  predicate: (config?: TConfig) => Promise<boolean> | boolean,
-  fn: (config?: TConfig) => Promise<void>
-): (config?: TConfig) => Promise<void> {
-  return async (config?: TConfig) => {
-    if (await predicate(config)) {
-      await fn(config);
-    }
-  };
-}
-
-/**
- * Tap - run a side effect and return the original value
- *
- * Useful for logging or debugging in a pipe.
- *
- * @example
- * ```typescript
- * const setup = pipe(
- *   tap((config) => console.log('Initial config:', config)),
- *   (config) => ({ ...config, tracing: true }),
- *   tap((config) => console.log('After tracing:', config)),
- *   (config) => initObservability(config)
- * )
- * ```
- */
-export function tap<T>(fn: (value: T) => void): (value: T) => T {
-  return (value: T) => {
-    fn(value);
-    return value;
-  };
-}
-
-/**
- * Memoize - cache the result of a function
- *
- * Useful for expensive initialization functions that should only run once.
- *
- * @example
- * ```typescript
- * const setup = memoize(() => {
- *   console.log('Setting up (expensive)...')
- *   instrumentGlobalFetch()
- *   instrumentGlobalCache()
- * })
- *
- * setup() // Logs "Setting up (expensive)..."
- * setup() // Does nothing (cached)
- * setup() // Does nothing (cached)
- * ```
- */
-export function memoize<TArgs extends any[], TReturn>(
-  fn: (...args: TArgs) => TReturn
-): (...args: TArgs) => TReturn {
-  const cached: { hasValue: boolean; value: TReturn } = { hasValue: false, value: undefined as any };
-
-  return (...args: TArgs) => {
-    if (!cached.hasValue) {
-      cached.value = fn(...args);
-      cached.hasValue = true;
-    }
-    return cached.value;
-  };
-}
-
-/**
- * Retry - retry a function on failure
- *
- * @example
- * ```typescript
- * const setupWithRetry = retry(
- *   async () => {
- *     await fetch('https://api.example.com/init')
- *   },
- *   { maxAttempts: 3, delayMs: 1000 }
- * )
- *
- * await setupWithRetry()
- * ```
- */
-export function retry<TArgs extends any[], TReturn>(
-  fn: (...args: TArgs) => Promise<TReturn>,
-  options: {
-    maxAttempts?: number;
-    delayMs?: number;
-    onRetry?: (attempt: number, error: Error) => void;
-  } = {}
-): (...args: TArgs) => Promise<TReturn> {
-  const { maxAttempts = 3, delayMs = 1000, onRetry } = options;
-
-  return async (...args: TArgs) => {
-    let lastError: Error | undefined;
-
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-      try {
-        return await fn(...args);
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        if (attempt < maxAttempts) {
-          onRetry?.(attempt, lastError);
-          await new Promise(resolve => setTimeout(resolve, delayMs));
-        }
-      }
-    }
-
-    throw lastError;
-  };
-}