@artemiskit/core 0.1.2

package/src/redaction/redactor.test.ts

@@ -0,0 +1,258 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  Redactor,
+  createDefaultRedactor,
+  createNoOpRedactor,
+  hashText,
+  redactText,
+  redactWithHash,
+  resolvePatterns,
+} from './redactor';
+import { BUILTIN_PATTERNS, DEFAULT_REDACTION_PATTERNS } from './types';
+
+describe('redactText', () => {
+  it('should redact email addresses', () => {
+    const text = 'Contact me at john.doe@example.com for more info';
+    const patterns = [/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g];
+    const result = redactText(text, patterns);
+
+    expect(result.wasRedacted).toBe(true);
+    expect(result.redactionCount).toBe(1);
+    expect(result.text).toBe('Contact me at [REDACTED] for more info');
+  });
+
+  it('should redact multiple occurrences', () => {
+    const text = 'Email john@test.com or jane@test.com';
+    const patterns = [/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g];
+    const result = redactText(text, patterns);
+
+    expect(result.wasRedacted).toBe(true);
+    expect(result.redactionCount).toBe(2);
+    expect(result.text).toBe('Email [REDACTED] or [REDACTED]');
+  });
+
+  it('should use custom replacement', () => {
+    const text = 'Call me at 555-123-4567';
+    const patterns = [/\b\d{3}[-\s]?\d{3}[-\s]?\d{4}\b/g];
+    const result = redactText(text, patterns, '***');
+
+    expect(result.text).toBe('Call me at ***');
+  });
+
+  it('should return original text when no matches', () => {
+    const text = 'Hello world';
+    const patterns = [/\b\d{3}-\d{3}-\d{4}\b/g];
+    const result = redactText(text, patterns);
+
+    expect(result.wasRedacted).toBe(false);
+    expect(result.redactionCount).toBe(0);
+    expect(result.text).toBe('Hello world');
+  });
+
+  it('should handle empty text', () => {
+    const result = redactText('', [/test/g]);
+    expect(result.wasRedacted).toBe(false);
+    expect(result.text).toBe('');
+  });
+
+  it('should handle empty patterns', () => {
+    const result = redactText('some text', []);
+    expect(result.wasRedacted).toBe(false);
+    expect(result.text).toBe('some text');
+  });
+});
+
+describe('resolvePatterns', () => {
+  it('should resolve built-in pattern names', () => {
+    const patterns = resolvePatterns([BUILTIN_PATTERNS.EMAIL, BUILTIN_PATTERNS.PHONE]);
+    expect(patterns).toHaveLength(2);
+    expect(patterns[0].name).toBe('email');
+    expect(patterns[1].name).toBe('phone');
+  });
+
+  it('should handle custom regex strings', () => {
+    const patterns = resolvePatterns(['\\btest\\b', 'custom-pattern']);
+    expect(patterns).toHaveLength(2);
+    expect(patterns[0].name).toContain('custom:');
+  });
+
+  it('should filter out invalid regex', () => {
+    const patterns = resolvePatterns(['[invalid', 'valid']);
+    expect(patterns).toHaveLength(1);
+    expect(patterns[0].name).toContain('custom:');
+  });
+});
+
+describe('hashText', () => {
+  it('should generate consistent SHA-256 hash', () => {
+    const text = 'sensitive data';
+    const hash1 = hashText(text);
+    const hash2 = hashText(text);
+
+    expect(hash1).toBe(hash2);
+    expect(hash1).toHaveLength(64); // SHA-256 hex is 64 chars
+  });
+
+  it('should generate different hashes for different text', () => {
+    const hash1 = hashText('text1');
+    const hash2 = hashText('text2');
+
+    expect(hash1).not.toBe(hash2);
+  });
+});
+
+describe('redactWithHash', () => {
+  it('should return both redacted text and original hash', () => {
+    const original = 'Contact: test@email.com';
+    const patterns = [/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g];
+    const result = redactWithHash(original, patterns);
+
+    expect(result.wasRedacted).toBe(true);
+    expect(result.text).toBe('Contact: [REDACTED]');
+    expect(result.originalHash).toHaveLength(64);
+    expect(result.originalHash).toBe(hashText(original));
+  });
+});
+
+describe('Redactor class', () => {
+  it('should create with default patterns when enabled', () => {
+    const redactor = createDefaultRedactor();
+    expect(redactor.enabled).toBe(true);
+    expect(redactor.patternNames.length).toBeGreaterThan(0);
+  });
+
+  it('should create no-op redactor when disabled', () => {
+    const redactor = createNoOpRedactor();
+    expect(redactor.enabled).toBe(false);
+
+    const result = redactor.redact('test@email.com');
+    expect(result.wasRedacted).toBe(false);
+    expect(result.text).toBe('test@email.com');
+  });
+
+  it('should redact prompts when configured', () => {
+    const redactor = new Redactor({
+      enabled: true,
+      redactPrompts: true,
+      patterns: [BUILTIN_PATTERNS.EMAIL],
+    });
+
+    const result = redactor.redactPrompt('Send to user@test.com');
+    expect(result.wasRedacted).toBe(true);
+    expect(result.text).toBe('Send to [REDACTED]');
+  });
+
+  it('should not redact prompts when disabled', () => {
+    const redactor = new Redactor({
+      enabled: true,
+      redactPrompts: false,
+      patterns: [BUILTIN_PATTERNS.EMAIL],
+    });
+
+    const result = redactor.redactPrompt('Send to user@test.com');
+    expect(result.wasRedacted).toBe(false);
+    expect(result.text).toBe('Send to user@test.com');
+  });
+
+  it('should redact responses when configured', () => {
+    const redactor = new Redactor({
+      enabled: true,
+      redactResponses: true,
+      patterns: [BUILTIN_PATTERNS.PHONE],
+    });
+
+    const result = redactor.redactResponse('Call me at 555-123-4567');
+    expect(result.wasRedacted).toBe(true);
+    expect(result.text).toBe('Call me at [REDACTED]');
+  });
+
+  it('should use custom replacement string', () => {
+    const redactor = new Redactor({
+      enabled: true,
+      replacement: '<<HIDDEN>>',
+      patterns: [BUILTIN_PATTERNS.EMAIL],
+    });
+
+    const result = redactor.redact('test@example.com');
+    expect(result.text).toBe('<<HIDDEN>>');
+  });
+
+  it('should redact metadata when enabled', () => {
+    const redactor = new Redactor({
+      enabled: true,
+      redactMetadata: true,
+      patterns: [BUILTIN_PATTERNS.EMAIL],
+    });
+
+    const metadata = {
+      user: 'john@test.com',
+      action: 'login',
+    };
+
+    const result = redactor.redactMetadata(metadata);
+    expect(result.user).toBe('[REDACTED]');
+    expect(result.action).toBe('login');
+  });
+
+  it('should not redact metadata when disabled', () => {
+    const redactor = new Redactor({
+      enabled: true,
+      redactMetadata: false,
+      patterns: [BUILTIN_PATTERNS.EMAIL],
+    });
+
+    const metadata = { user: 'john@test.com' };
+    const result = redactor.redactMetadata(metadata);
+    expect(result.user).toBe('john@test.com');
+  });
+});
+
+describe('Built-in patterns', () => {
+  const createTestRedactor = (pattern: string) =>
+    new Redactor({ enabled: true, patterns: [pattern] });
+
+  it('should redact credit card numbers', () => {
+    const redactor = createTestRedactor(BUILTIN_PATTERNS.CREDIT_CARD);
+    const result = redactor.redact('Card: 4111-1111-1111-1111');
+    expect(result.wasRedacted).toBe(true);
+  });
+
+  it('should redact SSN', () => {
+    const redactor = createTestRedactor(BUILTIN_PATTERNS.SSN);
+    const result = redactor.redact('SSN: 123-45-6789');
+    expect(result.wasRedacted).toBe(true);
+  });
+
+  it('should redact API keys', () => {
+    const redactor = createTestRedactor(BUILTIN_PATTERNS.API_KEY);
+    // Using clearly fake test key pattern (not a real key format)
+    const result = redactor.redact('Key: sk_test_FAKE_KEY_FOR_TESTING_1234567890');
+    expect(result.wasRedacted).toBe(true);
+  });
+
+  it('should redact AWS keys', () => {
+    const redactor = createTestRedactor(BUILTIN_PATTERNS.AWS_KEY);
+    const result = redactor.redact('AWS: AKIAIOSFODNN7EXAMPLE');
+    expect(result.wasRedacted).toBe(true);
+  });
+
+  it('should redact secrets in assignments', () => {
+    const redactor = createTestRedactor(BUILTIN_PATTERNS.SECRETS);
+    const result = redactor.redact('password=mysecretpass123');
+    expect(result.wasRedacted).toBe(true);
+  });
+
+  it('should redact IPv4 addresses', () => {
+    const redactor = createTestRedactor(BUILTIN_PATTERNS.IPV4);
+    const result = redactor.redact('Server: 192.168.1.100');
+    expect(result.wasRedacted).toBe(true);
+  });
+
+  it('should redact JWT tokens', () => {
+    const redactor = createTestRedactor(BUILTIN_PATTERNS.JWT);
+    const jwt =
+      'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U';
+    const result = redactor.redact(`Token: ${jwt}`);
+    expect(result.wasRedacted).toBe(true);
+  });
+});

package/src/redaction/redactor.ts

@@ -0,0 +1,246 @@
+import { createHash } from 'node:crypto';
+import {
+  BUILTIN_REGEX_PATTERNS,
+  type BuiltinPatternName,
+  DEFAULT_REDACTION_PATTERNS,
+  type RedactionConfig,
+  type RedactionOptions,
+  type RedactionResult,
+} from './types';
+
+/**
+ * Resolve pattern strings to RegExp objects
+ * Supports built-in pattern names and custom regex strings
+ */
+export function resolvePatterns(patterns: string[]): { regex: RegExp; name: string }[] {
+  return patterns
+    .map((pattern) => {
+      // Check if it's a built-in pattern name
+      if (pattern in BUILTIN_REGEX_PATTERNS) {
+        const regex = BUILTIN_REGEX_PATTERNS[pattern as BuiltinPatternName];
+        return { regex: new RegExp(regex.source, regex.flags), name: pattern };
+      }
+
+      // Treat as custom regex
+      try {
+        return { regex: new RegExp(pattern, 'g'), name: `custom:${pattern.slice(0, 20)}` };
+      } catch {
+        // Invalid regex, skip it
+        console.warn(`Invalid redaction pattern: ${pattern}`);
+        return null;
+      }
+    })
+    .filter((p): p is { regex: RegExp; name: string } => p !== null);
+}
+
+/**
+ * Create RedactionOptions from RedactionConfig
+ */
+export function createRedactionOptions(config: RedactionConfig): RedactionOptions {
+  const patternNames = config.patterns?.length ? config.patterns : DEFAULT_REDACTION_PATTERNS;
+  const resolvedPatterns = resolvePatterns(patternNames);
+
+  return {
+    enabled: config.enabled,
+    patterns: resolvedPatterns.map((p) => p.regex),
+    redactPrompts: config.redactPrompts ?? true,
+    redactResponses: config.redactResponses ?? true,
+    redactMetadata: config.redactMetadata ?? false,
+    replacement: config.replacement ?? '[REDACTED]',
+  };
+}
+
+/**
+ * Apply redaction to a text string
+ */
+export function redactText(
+  text: string,
+  patterns: (string | RegExp)[],
+  replacement = '[REDACTED]'
+): RedactionResult {
+  if (!text || patterns.length === 0) {
+    return {
+      text,
+      wasRedacted: false,
+      redactionCount: 0,
+      matchedPatterns: [],
+    };
+  }
+
+  let result = text;
+  let totalCount = 0;
+  const matchedPatterns: string[] = [];
+
+  for (const pattern of patterns) {
+    const regex = typeof pattern === 'string' ? new RegExp(pattern, 'g') : pattern;
+    const matches = result.match(regex);
+
+    if (matches && matches.length > 0) {
+      totalCount += matches.length;
+      matchedPatterns.push(regex.source.slice(0, 30));
+      result = result.replace(regex, replacement);
+    }
+  }
+
+  return {
+    text: result,
+    wasRedacted: totalCount > 0,
+    redactionCount: totalCount,
+    matchedPatterns: [...new Set(matchedPatterns)],
+  };
+}
+
+/**
+ * Generate a SHA-256 hash of the original text
+ * Useful for audit trails where you need to verify content without storing it
+ */
+export function hashText(text: string): string {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+/**
+ * Redact text and return both redacted version and hash of original
+ */
+export function redactWithHash(
+  text: string,
+  patterns: (string | RegExp)[],
+  replacement = '[REDACTED]'
+): RedactionResult & { originalHash: string } {
+  const originalHash = hashText(text);
+  const result = redactText(text, patterns, replacement);
+  return { ...result, originalHash };
+}
+
+/**
+ * Main Redactor class for applying redaction with consistent configuration
+ */
+export class Redactor {
+  private options: RedactionOptions;
+  private resolvedPatterns: { regex: RegExp; name: string }[];
+
+  constructor(config: RedactionConfig) {
+    this.options = createRedactionOptions(config);
+    const patternNames = config.patterns?.length ? config.patterns : DEFAULT_REDACTION_PATTERNS;
+    this.resolvedPatterns = resolvePatterns(patternNames);
+  }
+
+  /**
+   * Check if redaction is enabled
+   */
+  get enabled(): boolean {
+    return this.options.enabled;
+  }
+
+  /**
+   * Get pattern names being used
+   */
+  get patternNames(): string[] {
+    return this.resolvedPatterns.map((p) => p.name);
+  }
+
+  /**
+   * Get the replacement string
+   */
+  get replacement(): string {
+    return this.options.replacement;
+  }
+
+  /**
+   * Redact a prompt string
+   */
+  redactPrompt(prompt: string): RedactionResult {
+    if (!this.options.enabled || !this.options.redactPrompts) {
+      return {
+        text: prompt,
+        wasRedacted: false,
+        redactionCount: 0,
+        matchedPatterns: [],
+      };
+    }
+    return redactText(prompt, this.options.patterns, this.options.replacement);
+  }
+
+  /**
+   * Redact a response string
+   */
+  redactResponse(response: string): RedactionResult {
+    if (!this.options.enabled || !this.options.redactResponses) {
+      return {
+        text: response,
+        wasRedacted: false,
+        redactionCount: 0,
+        matchedPatterns: [],
+      };
+    }
+    return redactText(response, this.options.patterns, this.options.replacement);
+  }
+
+  /**
+   * Redact metadata object values
+   */
+  redactMetadata<T extends Record<string, unknown>>(metadata: T): T {
+    if (!this.options.enabled || !this.options.redactMetadata) {
+      return metadata;
+    }
+
+    const redacted = { ...metadata } as T;
+    for (const key of Object.keys(redacted)) {
+      const value = redacted[key];
+      if (typeof value === 'string') {
+        const result = redactText(value, this.options.patterns, this.options.replacement);
+        (redacted as Record<string, unknown>)[key] = result.text;
+      }
+    }
+    return redacted;
+  }
+
+  /**
+   * Redact any text with current configuration
+   */
+  redact(text: string): RedactionResult {
+    if (!this.options.enabled) {
+      return {
+        text,
+        wasRedacted: false,
+        redactionCount: 0,
+        matchedPatterns: [],
+      };
+    }
+    return redactText(text, this.options.patterns, this.options.replacement);
+  }
+
+  /**
+   * Redact and get hash of original
+   */
+  redactAndHash(text: string): RedactionResult & { originalHash: string } {
+    const originalHash = hashText(text);
+    const result = this.redact(text);
+    return { ...result, originalHash };
+  }
+}
+
+/**
+ * Create a no-op redactor that doesn't redact anything
+ */
+export function createNoOpRedactor(): Redactor {
+  return new Redactor({
+    enabled: false,
+    redactPrompts: true,
+    redactResponses: true,
+    redactMetadata: false,
+    replacement: '[REDACTED]',
+  });
+}
+
+/**
+ * Create a redactor with default patterns
+ */
+export function createDefaultRedactor(): Redactor {
+  return new Redactor({
+    enabled: true,
+    redactPrompts: true,
+    redactResponses: true,
+    redactMetadata: false,
+    replacement: '[REDACTED]',
+  });
+}

package/src/redaction/types.ts

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+
+/**
+ * Built-in redaction pattern names
+ */
+export const BUILTIN_PATTERNS = {
+  /** Email addresses */
+  EMAIL: 'email',
+  /** Phone numbers (various formats) */
+  PHONE: 'phone',
+  /** Credit card numbers */
+  CREDIT_CARD: 'credit_card',
+  /** Social Security Numbers */
+  SSN: 'ssn',
+  /** API keys (common formats) */
+  API_KEY: 'api_key',
+  /** IPv4 addresses */
+  IPV4: 'ipv4',
+  /** JWT tokens */
+  JWT: 'jwt',
+  /** AWS access keys */
+  AWS_KEY: 'aws_key',
+  /** Generic secrets (password=, secret=, etc.) */
+  SECRETS: 'secrets',
+} as const;
+
+export type BuiltinPatternName = (typeof BUILTIN_PATTERNS)[keyof typeof BUILTIN_PATTERNS];
+
+/**
+ * Regex patterns for built-in redaction
+ */
+export const BUILTIN_REGEX_PATTERNS: Record<BuiltinPatternName, RegExp> = {
+  [BUILTIN_PATTERNS.EMAIL]: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+  [BUILTIN_PATTERNS.PHONE]: /\b(?:\+?1[-.\s]?)?(?:\(?\d{3}\)?[-.\s]?)?\d{3}[-.\s]?\d{4}\b/g,
+  [BUILTIN_PATTERNS.CREDIT_CARD]: /\b(?:\d{4}[-\s]?){3}\d{4}\b/g,
+  [BUILTIN_PATTERNS.SSN]: /\b\d{3}[-\s]?\d{2}[-\s]?\d{4}\b/g,
+  [BUILTIN_PATTERNS.API_KEY]:
+    /\b(?:sk|pk|api|key)[-_]?(?:[a-zA-Z0-9]+[-_]?){2,}[a-zA-Z0-9]{10,}\b/gi,
+  [BUILTIN_PATTERNS.IPV4]: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+  [BUILTIN_PATTERNS.JWT]: /\beyJ[A-Za-z0-9-_]+\.eyJ[A-Za-z0-9-_]+\.[A-Za-z0-9-_.+/=]*\b/g,
+  [BUILTIN_PATTERNS.AWS_KEY]: /\b(?:AKIA|ABIA|ACCA|ASIA)[A-Z0-9]{16}\b/g,
+  [BUILTIN_PATTERNS.SECRETS]:
+    /\b(?:password|secret|token|apikey|api_key|auth)[\s]*[=:]\s*['"]?[^\s'"]+['"]?/gi,
+};
+
+/**
+ * Default patterns to use when redaction is enabled without specific patterns
+ */
+export const DEFAULT_REDACTION_PATTERNS: BuiltinPatternName[] = [
+  BUILTIN_PATTERNS.EMAIL,
+  BUILTIN_PATTERNS.PHONE,
+  BUILTIN_PATTERNS.CREDIT_CARD,
+  BUILTIN_PATTERNS.SSN,
+  BUILTIN_PATTERNS.API_KEY,
+  BUILTIN_PATTERNS.AWS_KEY,
+  BUILTIN_PATTERNS.SECRETS,
+];
+
+/**
+ * Redaction configuration schema for scenarios
+ */
+export const RedactionConfigSchema = z.object({
+  /** Enable redaction */
+  enabled: z.boolean().default(false),
+  /** Built-in pattern names or custom regex patterns */
+  patterns: z.array(z.string()).optional(),
+  /** Redact prompt content */
+  redactPrompts: z.boolean().optional().default(true),
+  /** Redact response content */
+  redactResponses: z.boolean().optional().default(true),
+  /** Redact metadata fields */
+  redactMetadata: z.boolean().optional().default(false),
+  /** Custom replacement string */
+  replacement: z.string().optional().default('[REDACTED]'),
+});
+
+export type RedactionConfig = z.infer<typeof RedactionConfigSchema>;
+
+/**
+ * Redaction options used at runtime
+ */
+export interface RedactionOptions {
+  enabled: boolean;
+  patterns: (string | RegExp)[];
+  redactPrompts: boolean;
+  redactResponses: boolean;
+  redactMetadata: boolean;
+  replacement: string;
+}
+
+/**
+ * Result of a redaction operation
+ */
+export interface RedactionResult {
+  /** The redacted text */
+  text: string;
+  /** Whether any redaction was applied */
+  wasRedacted: boolean;
+  /** Count of redactions made */
+  redactionCount: number;
+  /** Types of patterns that matched */
+  matchedPatterns: string[];
+}
+
+/**
+ * Metadata about redaction in a manifest
+ */
+export interface RedactionMetadata {
+  /** Whether redaction was enabled */
+  enabled: boolean;
+  /** Patterns used (names only, not actual regex) */
+  patternsUsed: string[];
+  /** Replacement string used */
+  replacement: string;
+  /** Summary of what was redacted */
+  summary: {
+    promptsRedacted: number;
+    responsesRedacted: number;
+    totalRedactions: number;
+  };
+}
+
+/**
+ * Redaction details for a single case result
+ */
+export interface CaseRedactionDetails {
+  /** Whether this case had redaction applied */
+  redacted: boolean;
+  /** Whether prompt was redacted */
+  promptRedacted: boolean;
+  /** Whether response was redacted */
+  responseRedacted: boolean;
+  /** Number of redactions in this case */
+  redactionCount: number;
+}