autotel 2.26.0 → 2.26.2

package/src/attribute-redacting-processor.ts

@@ -46,6 +46,11 @@ export type AttributeRedactorFn = (
  */
 export type AttributeRedactorPreset = 'default' | 'strict' | 'pci-dss';
 
+/**
+ * Masker function type - receives the matched string and returns a masked version
+ */
+export type MaskFn = (match: string) => string;
+
 /**
  * Value pattern configuration
  */
@@ -56,8 +61,15 @@ export interface ValuePatternConfig {
   pattern: RegExp;
   /** Custom replacement (default: uses global replacement) */
   replacement?: string;
+  /** Mask function for smart partial masking (overrides replacement) */
+  mask?: MaskFn;
 }
 
+/**
+ * Built-in PII pattern names
+ */
+export type BuiltinPatternName = keyof typeof builtinPatterns;
+
 /**
  * Attribute redactor configuration
  */
@@ -68,6 +80,15 @@ export interface AttributeRedactorConfig {
   /** Patterns to match against attribute values (redacts matched portion) */
   valuePatterns?: ValuePatternConfig[];
 
+  /** Dot-notation paths to redact (e.g. 'user.password', 'payment.card') */
+  paths?: string[];
+
+  /** Built-in PII patterns to enable. `true` enables all, `false` disables all, array selects specific ones. */
+  builtins?: boolean | BuiltinPatternName[];
+
+  /** Custom RegExp patterns for string-level redaction */
+  patterns?: RegExp[];
+
   /** Default replacement string (default: '[REDACTED]') */
   replacement?: string;
 
@@ -100,14 +121,112 @@ export const REDACTOR_PATTERNS = {
     /^(password|passwd|pwd|secret|token|api[_-]?key|auth|credential|private[_-]?key|authorization)$/i,
 } as const;
 
+/**
+ * Built-in PII detection patterns with smart masking.
+ * Each builtin preserves just enough signal for debugging while scrubbing PII.
+ */
+export const builtinPatterns = {
+  /** Credit card numbers → ****1111 (PCI DSS: last 4 allowed) */
+  creditCard: {
+    pattern: /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g,
+    mask: (m: string) => `****${m.replace(/[\s-]/g, '').slice(-4)}`,
+  },
+  /** Email addresses → a***@***.com */
+  email: {
+    pattern: /[\w.+-]+@[\w-]+\.[\w.]+/g,
+    mask: (m: string) => {
+      const at = m.indexOf('@');
+      if (at < 1) return '***@***';
+      const tld = m.slice(m.lastIndexOf('.'));
+      return `${m[0]}***@***${tld}`;
+    },
+  },
+  /** IPv4 addresses → ***.***.***.100 (last octet only) */
+  ipv4: {
+    pattern:
+      /\b(?!0\.0\.0\.0\b)(?!127\.0\.0\.1\b)\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/g,
+    mask: (m: string) => `***.***.***.${m.split('.').pop()}`,
+  },
+  /** International phone numbers → +33******78 (country code + last 2 digits) */
+  phone: {
+    pattern:
+      /(?:\+\d{1,3}[\s.-]?)?\(?\d{1,4}\)?[\s.-]?\d{2,4}[\s.-]?\d{2,4}[\s.-]?\d{2,4}\b/g,
+    mask: (m: string) => {
+      const digits = m.replace(/[^\d]/g, '');
+      const hasPlus = m.startsWith('+');
+      if (hasPlus && digits.length > 4) {
+        const ccMatch = m.match(/^\+\d{1,3}/);
+        const cc = ccMatch ? ccMatch[0] : '+';
+        return `${cc}******${digits.slice(-2)}`;
+      }
+      if (digits.length > 2) {
+        return `${'*'.repeat(digits.length - 2)}${digits.slice(-2)}`;
+      }
+      return '***';
+    },
+  },
+  /** JWT tokens → eyJ***.*** */
+  jwt: {
+    pattern: /\beyJ[\w-]*\.[\w-]*\.[\w-]*\b/g,
+    mask: () => 'eyJ***.***',
+  },
+  /** Bearer tokens → Bearer *** */
+  bearer: {
+    pattern: /\bBearer\s+[\w\-.~+/]{8,}=*/gi,
+    mask: () => 'Bearer ***',
+  },
+  /** IBAN → FR76****189 (country + check digits + last 3) */
+  iban: {
+    pattern:
+      /\b[A-Z]{2}\d{2}[\s-]?[\dA-Z]{4}[\s-]?[\dA-Z]{4}[\s-]?[\dA-Z]{4}[\s-]?[\dA-Z]{0,4}[\s-]?[\dA-Z]{0,4}[\s-]?[\dA-Z]{0,4}\b/g,
+    mask: (m: string) => {
+      const clean = m.replace(/[\s-]/g, '');
+      return `${clean.slice(0, 4)}****${clean.slice(-3)}`;
+    },
+  },
+} as const;
+
+function cloneRegex(re: RegExp): RegExp {
+  return new RegExp(re.source, re.flags);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function toRegExp(value: unknown): RegExp | undefined {
+  if (value instanceof RegExp) return value;
+  if (typeof value === 'string') return new RegExp(value, 'g');
+  if (isPlainObject(value) && typeof value.source === 'string') {
+    const flags = typeof value.flags === 'string' ? value.flags : 'g';
+    return new RegExp(value.source, flags);
+  }
+  return undefined;
+}
+
+function toRegExpArray(value: unknown): RegExp[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out: RegExp[] = [];
+  for (const item of value) {
+    const re = toRegExp(item);
+    if (re) out.push(re);
+  }
+  return out.length > 0 ? out : [];
+}
+
+function builtinToValuePattern(name: BuiltinPatternName): ValuePatternConfig {
+  const b = builtinPatterns[name];
+  return { name, pattern: cloneRegex(b.pattern), mask: b.mask };
+}
+
 /**
  * Default value patterns for the 'default' preset
  */
 const DEFAULT_VALUE_PATTERNS: ValuePatternConfig[] = [
-  { name: 'email', pattern: REDACTOR_PATTERNS.email },
-  { name: 'phone', pattern: REDACTOR_PATTERNS.phone },
+  builtinToValuePattern('email'),
+  builtinToValuePattern('phone'),
   { name: 'ssn', pattern: REDACTOR_PATTERNS.ssn },
-  { name: 'creditCard', pattern: REDACTOR_PATTERNS.creditCard },
+  builtinToValuePattern('creditCard'),
 ];
 
 /**
@@ -118,61 +237,158 @@ export const REDACTOR_PRESETS: Record<
   AttributeRedactorConfig
 > = {
   /**
-   * Default preset - covers common PII patterns
-   * Detects: emails, phone numbers, SSNs, credit cards
+   * Default preset - covers common PII patterns with smart masking
+   * Detects: emails (a***@***.com), phone numbers, SSNs, credit cards (****1111)
    * Redacts keys: password, secret, token, apiKey, auth, credential
    */
   default: {
     keyPatterns: [REDACTOR_PATTERNS.sensitiveKey],
     valuePatterns: DEFAULT_VALUE_PATTERNS,
+    builtins: true,
     replacement: '[REDACTED]',
   },
 
   /**
    * Strict preset - more aggressive redaction for high-security environments
-   * Includes everything in default plus: Bearer tokens, JWTs, API keys in values
+   * Includes everything in default plus: Bearer tokens, JWTs, IBAN, API keys in values
    */
   strict: {
     keyPatterns: [REDACTOR_PATTERNS.sensitiveKey, /bearer/i, /jwt/i],
     valuePatterns: [
       ...DEFAULT_VALUE_PATTERNS,
-      { name: 'bearerToken', pattern: REDACTOR_PATTERNS.bearerToken },
+      builtinToValuePattern('jwt'),
+      builtinToValuePattern('bearer'),
+      builtinToValuePattern('iban'),
       { name: 'apiKeyInValue', pattern: REDACTOR_PATTERNS.apiKeyInValue },
-      { name: 'jwt', pattern: REDACTOR_PATTERNS.jwt },
     ],
+    builtins: true,
     replacement: '[REDACTED]',
   },
 
   /**
    * PCI-DSS preset - focused on payment card industry compliance
-   * Redacts: credit card numbers, CVV-like patterns, card-related keys
+   * Redacts: credit card numbers (****1111), CVV-like patterns, card-related keys
    */
   'pci-dss': {
     keyPatterns: [/card/i, /cvv/i, /cvc/i, /pan/i, /expir/i, /ccn/i],
-    valuePatterns: [
-      { name: 'creditCard', pattern: REDACTOR_PATTERNS.creditCard },
-    ],
+    valuePatterns: [builtinToValuePattern('creditCard')],
+    builtins: ['creditCard'],
     replacement: '[REDACTED]',
   },
 };
 
+/**
+ * Normalize redactor config that may have been deserialized from JSON/YAML.
+ * Converts regex-like values back to RegExp instances.
+ */
+export function normalizeAttributeRedactorConfig(
+  raw: AttributeRedactorConfig | AttributeRedactorPreset | unknown,
+): AttributeRedactorConfig | AttributeRedactorPreset | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw === 'string') return raw as AttributeRedactorPreset;
+  if (!isPlainObject(raw)) return undefined;
+
+  const config: AttributeRedactorConfig = {};
+
+  if (Array.isArray(raw.paths)) {
+    config.paths = raw.paths.filter(
+      (value): value is string => typeof value === 'string',
+    );
+  }
+
+  if (typeof raw.replacement === 'string') {
+    config.replacement = raw.replacement;
+  }
+
+  if (typeof raw.builtins === 'boolean') {
+    config.builtins = raw.builtins;
+  } else if (Array.isArray(raw.builtins)) {
+    config.builtins = raw.builtins.filter(
+      (name): name is BuiltinPatternName => typeof name === 'string',
+    );
+  }
+
+  if (typeof raw.redactor === 'function') {
+    config.redactor = raw.redactor as AttributeRedactorFn;
+  }
+
+  const keyPatterns = toRegExpArray(raw.keyPatterns);
+  if (keyPatterns) config.keyPatterns = keyPatterns;
+
+  const patterns = toRegExpArray(raw.patterns);
+  if (patterns) config.patterns = patterns;
+
+  if (Array.isArray(raw.valuePatterns)) {
+    const valuePatterns: ValuePatternConfig[] = [];
+    for (const item of raw.valuePatterns) {
+      if (!isPlainObject(item) || typeof item.name !== 'string') continue;
+      const pattern = toRegExp(item.pattern);
+      if (!pattern) continue;
+      valuePatterns.push({
+        name: item.name,
+        pattern,
+        replacement:
+          typeof item.replacement === 'string' ? item.replacement : undefined,
+        mask:
+          typeof item.mask === 'function' ? (item.mask as MaskFn) : undefined,
+      });
+    }
+    config.valuePatterns = valuePatterns;
+  }
+
+  return config;
+}
+
 /**
  * Resolve config to a normalized form
  */
 function resolveConfig(
   config: AttributeRedactorConfig | AttributeRedactorPreset,
 ): AttributeRedactorConfig {
-  if (typeof config === 'string') {
-    const preset = REDACTOR_PRESETS[config];
+  const normalized = normalizeAttributeRedactorConfig(config);
+  if (!normalized) {
+    throw new Error('Invalid attribute redactor config');
+  }
+
+  if (typeof normalized === 'string') {
+    const preset = REDACTOR_PRESETS[normalized];
     if (!preset) {
       throw new Error(
-        `Unknown attribute redactor preset: "${config}". ` +
+        `Unknown attribute redactor preset: "${normalized}". ` +
           `Available presets: ${Object.keys(REDACTOR_PRESETS).join(', ')}`,
       );
     }
     return preset;
   }
-  return config;
+
+  const resolvedConfig: AttributeRedactorConfig = {
+    ...normalized,
+    keyPatterns: normalized.keyPatterns
+      ? [...normalized.keyPatterns]
+      : undefined,
+    valuePatterns: normalized.valuePatterns
+      ? [...normalized.valuePatterns]
+      : undefined,
+    paths: normalized.paths ? [...normalized.paths] : undefined,
+    patterns: normalized.patterns ? [...normalized.patterns] : undefined,
+  };
+
+  // Merge built-in patterns if enabled
+  if (resolvedConfig.builtins !== false) {
+    const builtinNames = Array.isArray(resolvedConfig.builtins)
+      ? resolvedConfig.builtins
+      : (Object.keys(builtinPatterns) as BuiltinPatternName[]);
+    const builtinValuePatterns = builtinNames
+      .filter((name) => name in builtinPatterns)
+      .map(builtinToValuePattern);
+
+    resolvedConfig.valuePatterns = [
+      ...(resolvedConfig.valuePatterns ?? []),
+      ...builtinValuePatterns,
+    ];
+  }
+
+  return resolvedConfig;
 }
 
 /**
@@ -188,27 +404,40 @@ function createRedactorFromConfig(
 
   const keyPatterns = config.keyPatterns ?? [];
   const valuePatterns = config.valuePatterns ?? [];
+  const paths = config.paths ?? [];
+  const pathSet = new Set(paths);
+  const customPatterns = config.patterns ?? [];
   const defaultReplacement = config.replacement ?? '[REDACTED]';
 
+  // Build masker list from valuePatterns that have mask functions
+  const maskers: [RegExp, MaskFn][] = valuePatterns
+    .filter((vp) => vp.mask)
+    .map((vp) => [cloneRegex(vp.pattern), vp.mask!]);
+
   return (key: string, value: AttributeValue): AttributeValue => {
     // Check if key matches any sensitive key pattern
     for (const pattern of keyPatterns) {
-      // Reset lastIndex for global regexes
       pattern.lastIndex = 0;
       if (pattern.test(key)) {
         return defaultReplacement;
       }
     }
 
-    // For non-string values, return as-is (can't pattern match)
+    // Check if key matches any path-based redaction
+    if (pathSet.has(key)) {
+      return defaultReplacement;
+    }
+
+    // For non-string values, return as-is
     if (typeof value !== 'string') {
-      // Handle arrays of strings
       if (Array.isArray(value)) {
         return value.map((item) => {
           if (typeof item === 'string') {
             return redactStringValue(
               item,
               valuePatterns,
+              maskers,
+              customPatterns,
               defaultReplacement,
             ) as string;
           }
@@ -218,25 +447,50 @@ function createRedactorFromConfig(
       return value;
     }
 
-    // Apply value patterns to string values
-    return redactStringValue(value, valuePatterns, defaultReplacement);
+    // Three-tier strategy: path-based → masker-based → pattern-based
+    return redactStringValue(
+      value,
+      valuePatterns,
+      maskers,
+      customPatterns,
+      defaultReplacement,
+    );
   };
 }
 
 /**
- * Apply value patterns to a string
+ * Apply three-tier redaction strategy to a string
+ * 1. Masker-based: built-in patterns with smart partial masking
+ * 2. Pattern-based: custom RegExp patterns replaced with replacement
  */
 function redactStringValue(
   value: string,
   patterns: ValuePatternConfig[],
+  maskers: [RegExp, MaskFn][],
+  customPatterns: RegExp[],
   defaultReplacement: string,
 ): string {
   let result = value;
-  for (const { pattern, replacement } of patterns) {
-    // Reset lastIndex for global regexes
+
+  // Tier 1: Apply maskers (smart partial masking)
+  for (const [pattern, mask] of maskers) {
+    pattern.lastIndex = 0;
+    result = result.replace(pattern, mask);
+  }
+
+  // Tier 2: Apply value patterns without mask (full replacement)
+  for (const { pattern, replacement, mask } of patterns) {
+    if (mask) continue; // Already handled by maskers
     pattern.lastIndex = 0;
     result = result.replaceAll(pattern, replacement ?? defaultReplacement);
   }
+
+  // Tier 3: Apply custom patterns
+  for (const pattern of customPatterns) {
+    pattern.lastIndex = 0;
+    result = result.replaceAll(pattern, defaultReplacement);
+  }
+
   return result;
 }
 

package/src/autotel-logger.ts

@@ -232,7 +232,7 @@ export function createBuiltinLogger(
           log(level, extraOrMessage, message as Record<string, unknown>);
         } else {
           // Pure string-only call: logger.info('message')
-          log(level, extraOrMessage, undefined);
+          log(level, extraOrMessage);
         }
       } else {
         // Pino style: logger.info({ extra }, 'message')
@@ -303,7 +303,7 @@ export function createBuiltinLogger(
         }
 
         // Pure string-only call: logger.error('message')
-        log('error', extraOrMessage, undefined);
+        log('error', extraOrMessage);
         return;
       }
 

package/src/gen-ai-events.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest';
+import type { TraceContext } from './trace-context';
+import {
+  recordPromptSent,
+  recordResponseReceived,
+  recordRetry,
+  recordStreamFirstToken,
+  recordToolCall,
+} from './gen-ai-events';
+
+type CapturedEvent = { name: string; attrs?: Record<string, unknown> };
+
+function captureCtx(): {
+  ctx: TraceContext;
+  events: CapturedEvent[];
+} {
+  const events: CapturedEvent[] = [];
+  const ctx = {
+    addEvent: (name: string, attrs?: Record<string, unknown>) => {
+      events.push({ name, attrs });
+    },
+    setAttribute: () => {},
+    setAttributes: () => {},
+    setStatus: () => {},
+    recordException: () => {},
+    addLink: () => {},
+    addLinks: () => {},
+    updateName: () => {},
+    isRecording: () => true,
+    end: () => {},
+  } as unknown as TraceContext;
+  return { ctx, events };
+}
+
+describe('GenAI span event helpers', () => {
+  it('recordPromptSent emits gen_ai.prompt.sent with canonical attrs', () => {
+    const { ctx, events } = captureCtx();
+    recordPromptSent(ctx, {
+      model: 'gpt-4o',
+      promptTokens: 1200,
+      messageCount: 3,
+      operation: 'chat',
+    });
+    expect(events).toHaveLength(1);
+    expect(events[0]).toEqual({
+      name: 'gen_ai.prompt.sent',
+      attrs: {
+        'gen_ai.request.model': 'gpt-4o',
+        'gen_ai.usage.input_tokens': 1200,
+        'gen_ai.request.message_count': 3,
+        'gen_ai.operation.name': 'chat',
+      },
+    });
+  });
+
+  it('recordPromptSent omits unset fields rather than writing undefined', () => {
+    const { ctx, events } = captureCtx();
+    recordPromptSent(ctx);
+    expect(events[0]?.attrs).toEqual({});
+  });
+
+  it('recordResponseReceived joins finish reasons into a CSV for attribute compat', () => {
+    const { ctx, events } = captureCtx();
+    recordResponseReceived(ctx, {
+      model: 'gpt-4o-2024-11-20',
+      promptTokens: 1200,
+      completionTokens: 400,
+      totalTokens: 1600,
+      finishReasons: ['stop', 'tool_calls'],
+    });
+    expect(events[0]).toEqual({
+      name: 'gen_ai.response.received',
+      attrs: {
+        'gen_ai.response.model': 'gpt-4o-2024-11-20',
+        'gen_ai.usage.input_tokens': 1200,
+        'gen_ai.usage.output_tokens': 400,
+        'gen_ai.usage.total_tokens': 1600,
+        'gen_ai.response.finish_reasons': 'stop,tool_calls',
+      },
+    });
+  });
+
+  it('recordResponseReceived omits finish_reasons when empty', () => {
+    const { ctx, events } = captureCtx();
+    recordResponseReceived(ctx, { model: 'claude-sonnet-4-6' });
+    expect(events[0]?.attrs).not.toHaveProperty(
+      'gen_ai.response.finish_reasons',
+    );
+  });
+
+  it('recordRetry captures attempt, reason, delay, and status code', () => {
+    const { ctx, events } = captureCtx();
+    recordRetry(ctx, {
+      attempt: 2,
+      reason: 'rate_limit',
+      delayMs: 1000,
+      statusCode: 429,
+    });
+    expect(events[0]).toEqual({
+      name: 'gen_ai.retry',
+      attrs: {
+        'retry.attempt': 2,
+        'retry.reason': 'rate_limit',
+        'retry.delay_ms': 1000,
+        'http.response.status_code': 429,
+      },
+    });
+  });
+
+  it('recordToolCall writes canonical gen_ai.tool.* keys', () => {
+    const { ctx, events } = captureCtx();
+    recordToolCall(ctx, {
+      toolName: 'search_traces',
+      toolCallId: 'call-123',
+      arguments: '{"serviceName":"api"}',
+    });
+    expect(events[0]).toEqual({
+      name: 'gen_ai.tool.call',
+      attrs: {
+        'gen_ai.tool.name': 'search_traces',
+        'gen_ai.tool.call.id': 'call-123',
+        'gen_ai.tool.arguments': '{"serviceName":"api"}',
+      },
+    });
+  });
+
+  it('recordStreamFirstToken is the bare marker for TTFT', () => {
+    const { ctx, events } = captureCtx();
+    recordStreamFirstToken(ctx, { tokensSoFar: 1 });
+    expect(events[0]).toEqual({
+      name: 'gen_ai.stream.first_token',
+      attrs: { 'gen_ai.stream.tokens_so_far': 1 },
+    });
+  });
+});