feat(lib): add structured session logger and secret redaction utility

Add two new library modules:

1. src/lib/redact.ts — Secret redaction utility
   - Built-in patterns for API keys (sk-*), bearer tokens, URL
     passwords, AWS keys, GitHub tokens, and hex secrets
   - Customizable via createRedactor() for project-specific patterns
   - Idempotent — safe to run multiple times on the same input
   - URL password redaction preserves URL structure

2. src/lib/session-logger.ts — Structured session logger
   - Correlation IDs (auto-minted UUID or explicit) for tracing
   - ISO 8601 timestamps on every entry
   - Four log levels: debug, info, warn, error
   - Two output formats: human-readable text and machine-readable JSONL
   - Automatic secret redaction on all messages and data values
   - Deep redaction of nested objects and arrays in structured data
   - Child loggers for scoping sub-operations within a session
   - Injectable writer, clock, and redaction patterns for testing
   - Runtime level adjustment via setLevel()

Test coverage: 45 tests (23 redact + 22 logger)
Zero new production dependencies

Author: bagusardin25

src/lib/redact.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest';
+import { createRedactor, redactSecrets } from './redact.js';
+
+describe('redactSecrets', () => {
+  describe('API keys (sk- prefix)', () => {
+    it('redacts TestSprite API keys', () => {
+      const input = 'Using key sk-abcdef1234567890abcdef';
+      expect(redactSecrets(input)).toBe('Using key [REDACTED:api-key]');
+    });
+
+    it('redacts API keys embedded in config lines', () => {
+      const input = 'api_key = sk-abcdef1234567890abcdef1234';
+      expect(redactSecrets(input)).toBe('api_key = [REDACTED:api-key]');
+    });
+
+    it('does not redact short sk- prefixes (< 20 chars)', () => {
+      const input = 'sk-short';
+      expect(redactSecrets(input)).toBe('sk-short');
+    });
+
+    it('redacts multiple keys in one string', () => {
+      const input = 'key1=sk-aaaabbbbccccddddeeeeffffgggg key2=sk-11112222333344445555666677778888';
+      const result = redactSecrets(input);
+      expect(result).not.toContain('sk-aaaa');
+      expect(result).not.toContain('sk-1111');
+      expect(result.match(/\[REDACTED:api-key\]/g)).toHaveLength(2);
+    });
+  });
+
+  describe('bearer tokens', () => {
+    it('redacts Bearer authorization headers', () => {
+      const input = 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.payload.signature';
+      expect(redactSecrets(input)).toBe('Authorization: [REDACTED:bearer-token]');
+    });
+
+    it('is case-insensitive for bearer keyword', () => {
+      const input = 'bearer abcdefghijklmnopqrstuvwxyz1234';
+      expect(redactSecrets(input)).toBe('[REDACTED:bearer-token]');
+    });
+  });
+
+  describe('token patterns', () => {
+    it('redacts token= assignments', () => {
+      const input = 'token=abc123def456ghi789jkl012mno345';
+      expect(redactSecrets(input)).toBe('[REDACTED:token]');
+    });
+
+    it('redacts access_token values', () => {
+      const input = 'access_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"';
+      expect(redactSecrets(input)).toBe('[REDACTED:token]');
+    });
+
+    it('redacts refresh_token values', () => {
+      const input = "refresh_token='abc123def456ghi789jkl012mno345pqr'";
+      expect(redactSecrets(input)).toBe('[REDACTED:token]');
+    });
+  });
+
+  describe('URL passwords', () => {
+    it('redacts password in URL while preserving structure', () => {
+      const input = 'https://admin:supersecretpassword@db.example.com:5432/mydb';
+      const result = redactSecrets(input);
+      expect(result).toContain('admin');
+      expect(result).toContain('[REDACTED:url-password]');
+      expect(result).toContain('db.example.com');
+      expect(result).not.toContain('supersecretpassword');
+    });
+
+    it('redacts password in multiple URLs', () => {
+      const input = 'db=postgres://user:pass123@host1 cache=redis://app:secret456@host2';
+      const result = redactSecrets(input);
+      expect(result).not.toContain('pass123');
+      expect(result).not.toContain('secret456');
+    });
+  });
+
+  describe('AWS keys', () => {
+    it('redacts AWS access key IDs', () => {
+      const input = 'AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE';
+      expect(redactSecrets(input)).toBe('AWS_ACCESS_KEY_ID=[REDACTED:aws-key]');
+    });
+  });
+
+  describe('GitHub tokens', () => {
+    it('redacts ghp_ personal access tokens', () => {
+      const input = 'GITHUB_TOKEN=ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn';
+      expect(redactSecrets(input)).toBe('GITHUB_TOKEN=[REDACTED:github-token]');
+    });
+
+    it('redacts gho_ OAuth tokens', () => {
+      const input = 'token=gho_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn';
+      // token= pattern may match first, but the key point is no token leaks
+      const result = redactSecrets(input);
+      expect(result).not.toContain('gho_ABCDEF');
+    });
+  });
+
+  describe('hex secrets', () => {
+    it('redacts 32+ char hex strings', () => {
+      const input = 'hash=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4';
+      expect(redactSecrets(input)).toContain('[REDACTED:hex-secret]');
+    });
+
+    it('does not redact short hex strings', () => {
+      const input = 'short=abcdef123456';
+      expect(redactSecrets(input)).toBe('short=abcdef123456');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('returns empty string unchanged', () => {
+      expect(redactSecrets('')).toBe('');
+    });
+
+    it('returns non-secret text unchanged', () => {
+      const input = 'Running test suite for project checkout-flow...';
+      expect(redactSecrets(input)).toBe(input);
+    });
+
+    it('is idempotent — redacting twice gives the same result', () => {
+      const input = 'key=sk-abcdef1234567890abcdef';
+      const once = redactSecrets(input);
+      const twice = redactSecrets(once);
+      expect(twice).toBe(once);
+    });
+
+    it('handles multiline input', () => {
+      const input = [
+        'config loaded',
+        'api_key = sk-abcdef1234567890abcdef',
+        'endpoint = https://api.testsprite.com',
+      ].join('\n');
+      const result = redactSecrets(input);
+      expect(result).toContain('[REDACTED:api-key]');
+      expect(result).toContain('https://api.testsprite.com');
+    });
+  });
+});
+
+describe('createRedactor', () => {
+  it('applies custom patterns before defaults', () => {
+    const redact = createRedactor([{ name: 'internal-key', regex: /\bINT-[A-Za-z0-9]{24,}\b/g }]);
+    const input = 'key=INT-abcdefghijklmnopqrstuvwx';
+    expect(redact(input)).toBe('key=[REDACTED:internal-key]');
+  });
+
+  it('still applies default patterns', () => {
+    const redact = createRedactor([]);
+    const input = 'key=sk-abcdef1234567890abcdef';
+    expect(redact(input)).toBe('key=[REDACTED:api-key]');
+  });
+
+  it('custom patterns take priority over defaults', () => {
+    const redact = createRedactor([{ name: 'custom-sk', regex: /\bsk-[A-Za-z0-9]+\b/g }]);
+    // Custom runs first and catches the key
+    const input = 'key=sk-abcdef1234567890abcdef';
+    expect(redact(input)).toBe('key=[REDACTED:custom-sk]');
+  });
+});

src/lib/redact.ts

@@ -0,0 +1,138 @@
+/**
+ * Secret-redaction utility for CLI output, logs, and future TTS content.
+ *
+ * Scans strings for patterns that look like secrets — API keys, bearer
+ * tokens, passwords in URLs, and generic high-entropy hex/base64 strings
+ * — and replaces them with a fixed placeholder so they never appear in
+ * terminal output, persisted logs, checkpoints, or spoken announcements.
+ *
+ * Design notes:
+ *   - Patterns are intentionally broad rather than precise. A false
+ *     positive (redacting a harmless string) is always preferable to a
+ *     false negative (leaking a real secret).
+ *   - The replacement placeholder includes the pattern name so an
+ *     operator can tell *which* kind of value was removed without
+ *     seeing the value itself.
+ *   - `redactSecrets` is idempotent — running it twice on already-
+ *     redacted text produces the same output.
+ *   - Custom patterns can be added via `createRedactor` for project-
+ *     specific secret formats.
+ *   - This module has zero external dependencies.
+ */
+
+/** Default placeholder template. `{name}` is replaced by the pattern label. */
+const DEFAULT_PLACEHOLDER = '[REDACTED:{name}]';
+
+/**
+ * A named pattern that matches secret-shaped text.
+ *
+ * @param name   Human-readable label included in the placeholder
+ *               (e.g. `"api-key"`, `"bearer-token"`).
+ * @param regex  Pattern to match. Must use the global flag (`g`) so
+ *               `String.replace` replaces every occurrence.
+ */
+export interface RedactionPattern {
+  name: string;
+  regex: RegExp;
+}
+
+/**
+ * Built-in patterns covering the most common secret shapes seen in
+ * CLI / API environments. Ordered from most-specific to most-generic
+ * so specific labels win when patterns overlap.
+ */
+export const DEFAULT_PATTERNS: readonly RedactionPattern[] = [
+  // TestSprite API keys: `sk-` followed by 20+ alphanumeric chars
+  { name: 'api-key', regex: /\bsk-[A-Za-z0-9]{20,}\b/g },
+
+  // Bearer / token authorization header values
+  { name: 'bearer-token', regex: /\b[Bb]earer\s+[A-Za-z0-9._~+/=-]{20,}\b/g },
+
+  // Generic `token=<value>` or `token: <value>` in logs/config
+  {
+    name: 'token',
+    regex: /\b(?:token|access_token|refresh_token)[=:]\s*['"]?[A-Za-z0-9._~+/=-]{16,}['"]?/gi,
+  },
+
+  // Password in URLs: `://user:password@host`
+  { name: 'url-password', regex: /:\/\/[^@/\s]+:([^@/\s]+)@/g },
+
+  // AWS-style keys: AKIA followed by 16 uppercase alphanumeric
+  { name: 'aws-key', regex: /\bAKIA[A-Z0-9]{16}\b/g },
+
+  // GitHub tokens: ghp_, gho_, ghu_, ghs_, ghr_ prefix
+  { name: 'github-token', regex: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g },
+
+  // Generic hex secrets: 32+ consecutive hex chars (SHA-256, API keys, etc.)
+  // Only matches lowercase or mixed-case to reduce false positives on UUIDs.
+  { name: 'hex-secret', regex: /\b[0-9a-f]{32,}\b/g },
+];
+
+/**
+ * Redact secrets from a string using the default built-in patterns.
+ *
+ * @param input  The string to scan and redact.
+ * @returns A new string with every matched secret replaced by a
+ *   `[REDACTED:<pattern-name>]` placeholder.
+ *
+ * @example
+ *   redactSecrets('key=sk-abc123def456ghi789jkl012')
+ *   // → 'key=[REDACTED:api-key]'
+ *
+ *   redactSecrets('Authorization: Bearer eyJhbGciOiJIUzI...')
+ *   // → 'Authorization: [REDACTED:bearer-token]'
+ */
+export function redactSecrets(input: string): string {
+  return redactWithPatterns(input, DEFAULT_PATTERNS);
+}
+
+/**
+ * Create a custom redactor with additional project-specific patterns
+ * prepended to the built-in defaults. Custom patterns take precedence
+ * because they run first.
+ *
+ * @param extraPatterns  Additional patterns to match before the defaults.
+ * @returns A redaction function with the same signature as `redactSecrets`.
+ *
+ * @example
+ *   const redact = createRedactor([
+ *     { name: 'internal-key', regex: /\bINT-[A-Za-z0-9]{24}\b/g },
+ *   ]);
+ *   redact('token REDACTED key=INT-abc123...')
+ */
+export function createRedactor(
+  extraPatterns: readonly RedactionPattern[],
+): (input: string) => string {
+  const allPatterns = [...extraPatterns, ...DEFAULT_PATTERNS];
+  return (input: string) => redactWithPatterns(input, allPatterns);
+}
+
+/**
+ * Internal: apply an ordered list of patterns to a string, replacing
+ * every match with a labelled placeholder.
+ *
+ * Each pattern's regex is cloned via `new RegExp` so the shared global
+ * regex's `lastIndex` is reset on every call — without this, consecutive
+ * calls to `redactSecrets` on different strings would skip matches
+ * because `RegExp.prototype[Symbol.replace]` with a `g` flag mutates
+ * `lastIndex`.
+ */
+function redactWithPatterns(input: string, patterns: readonly RedactionPattern[]): string {
+  let result = input;
+  for (const pattern of patterns) {
+    const placeholder = DEFAULT_PLACEHOLDER.replace('{name}', pattern.name);
+    // Clone to reset lastIndex — global regexes are stateful.
+    const freshRegex = new RegExp(pattern.regex.source, pattern.regex.flags);
+
+    if (pattern.name === 'url-password') {
+      // Special handling: only redact the password capture group, not the
+      // entire URL structure. Replace `://user:PASSWORD@` with `://user:[REDACTED]@`.
+      result = result.replace(freshRegex, (match, password: string) =>
+        match.replace(password, placeholder),
+      );
+    } else {
+      result = result.replace(freshRegex, placeholder);
+    }
+  }
+  return result;
+}