@occasiolabs/occasio 0.8.1

package/src/adapters/computer-use-cli.js

@@ -0,0 +1,198 @@
+'use strict';
+
+/**
+ * computer-use-cli.js — `occasio computer-use` (dry-run demo).
+ *
+ * Reads a JSONL file of synthetic tool_use blocks (or stdin), applies a
+ * computer-use policy file, and prints what the engine would decide for
+ * each one. Lets us demo the governance story for Anthropic Computer Use
+ * without yet wiring up the live proxy adapter.
+ *
+ * Usage:
+ *   occasio computer-use --dry-run --from <jsonl>   [--policy <yml>]
+ *   occasio computer-use --example                  # built-in sample
+ *
+ * Live mode (intercept a real Computer-Use session through the proxy) is
+ * a follow-up that requires:
+ *   - extending the proxy SSE parser to recognise computer-use tool-use
+ *     blocks (currently only the Claude Code shape is parsed)
+ *   - injecting BLOCK results back as tool_result blocks (mirroring what
+ *     the Claude Code adapter does)
+ *   - end-to-end validation against the actual Anthropic API
+ *
+ * That work is deferred until at least one design partner is on it. The
+ * adapter logic in src/adapters/computer-use.js is the half that can be
+ * built and unit-tested without an API key.
+ */
+
+const fs = require('fs');
+
+const { normalizeToolUse, evaluate } = require('./computer-use');
+
+const C = {
+  r: s => `\x1b[31m${s}\x1b[0m`,
+  g: s => `\x1b[32m${s}\x1b[0m`,
+  y: s => `\x1b[33m${s}\x1b[0m`,
+  d: s => `\x1b[2m${s}\x1b[0m`,
+  b: s => `\x1b[1m${s}\x1b[0m`,
+};
+
+// Minimal inline YAML reader for the dry-run CLI — just enough to parse the
+// example policies we ship. Real users wire up `policy.yml` through the
+// full policy/loader.js path; this CLI is a demo.
+function parsePolicyYaml(text) {
+  const out = {};
+  let currentArray = null;
+  let currentKey = null;
+  for (const line of text.split('\n')) {
+    const clean = line.replace(/#.*$/, '').replace(/\r$/, '');
+    if (!clean.trim()) continue;
+    const top = clean.match(/^([a-z_]+)\s*:\s*(.*)$/i);
+    if (top) {
+      currentKey = top[1];
+      const value = top[2].trim();
+      if (!value) { out[currentKey] = []; currentArray = out[currentKey]; }
+      else        { out[currentKey] = parseScalar(value); currentArray = null; }
+      continue;
+    }
+    if (currentArray && /^\s*-\s+/.test(clean)) {
+      currentArray.push(parseScalar(clean.replace(/^\s*-\s+/, '')));
+    }
+  }
+  return out;
+}
+
+function parseScalar(s) {
+  s = s.trim();
+  if ((s.startsWith("'") && s.endsWith("'")) || (s.startsWith('"') && s.endsWith('"'))) {
+    return s.slice(1, -1);
+  }
+  if (/^\d+$/.test(s)) return parseInt(s, 10);
+  if (s === 'true')  return true;
+  if (s === 'false') return false;
+  return s;
+}
+
+const EXAMPLE_TRAFFIC = [
+  { type: 'tool_use', name: 'computer', input: { action: 'screenshot' } },
+  { type: 'tool_use', name: 'computer', input: { action: 'mouse_move', coordinate: [400, 300] } },
+  { type: 'tool_use', name: 'computer', input: { action: 'left_click', coordinate: [400, 300] } },
+  { type: 'tool_use', name: 'computer', input: { action: 'type', text: 'Hello world' } },
+  { type: 'tool_use', name: 'computer', input: { action: 'type', text: 'password: hunter2sekret' } },
+  { type: 'tool_use', name: 'bash',     input: { command: 'ls -la' } },
+  { type: 'tool_use', name: 'bash',     input: { command: 'sudo rm -rf /tmp/x' } },
+  { type: 'tool_use', name: 'bash',     input: { command: 'curl https://github.com/some/repo' } },
+];
+
+const EXAMPLE_POLICY = {
+  deny_keyboard_patterns: [
+    { pattern: '(?i)password\\s*[:=]\\s*\\S+', reason: 'keyboard-secret-pattern' },
+    { pattern: '(?i)secret\\s*[:=]\\s*\\S+',   reason: 'keyboard-secret-pattern' },
+    '(?i)(sk-ant-|ghp_|AKIA)[A-Za-z0-9]{16,}',
+  ],
+  deny_command_patterns: [
+    '\\bcurl\\b.*\\b(api\\.|admin\\.|prod\\.)',  // exfil patterns
+  ],
+};
+
+function flag(args, name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+function bool(args, name) { return args.indexOf(name) >= 0; }
+
+function runComputerUseCli(args = []) {
+  if (bool(args, '--help') || bool(args, '-h')) {
+    process.stdout.write(
+      'Usage:\n' +
+      '  occasio computer-use --dry-run --from <jsonl> [--policy <yml>]\n' +
+      '  occasio computer-use --example\n\n' +
+      'Apply a computer-use policy to a JSONL of synthetic tool_use blocks\n' +
+      'and report each decision. Live proxy interception is not yet wired —\n' +
+      'this is the adapter\'s policy-engine half, validated in isolation.\n'
+    );
+    return 0;
+  }
+
+  const example = bool(args, '--example');
+  const dryRun  = bool(args, '--dry-run') || example;
+  if (!dryRun) {
+    process.stderr.write(`${C.r('error')}: pass --dry-run (live interception not yet wired)\n`);
+    return 2;
+  }
+
+  let traffic;
+  let policy;
+
+  if (example) {
+    traffic = EXAMPLE_TRAFFIC.slice();
+    policy  = EXAMPLE_POLICY;
+    process.stdout.write(C.d('[example mode: built-in synthetic traffic + sample policy]\n\n'));
+  } else {
+    const fromPath = flag(args, '--from');
+    if (!fromPath) {
+      process.stderr.write(`${C.r('error')}: --from <jsonl> required (or use --example)\n`);
+      return 2;
+    }
+    try {
+      traffic = fs.readFileSync(fromPath, 'utf8')
+        .split('\n').filter(Boolean)
+        .map(line => JSON.parse(line));
+    } catch (e) {
+      process.stderr.write(`${C.r('error')}: cannot read traffic file: ${e.message}\n`);
+      return 2;
+    }
+    const polPath = flag(args, '--policy');
+    if (polPath) {
+      try { policy = parsePolicyYaml(fs.readFileSync(polPath, 'utf8')); }
+      catch (e) {
+        process.stderr.write(`${C.r('error')}: cannot read policy: ${e.message}\n`);
+        return 2;
+      }
+    } else {
+      policy = EXAMPLE_POLICY;
+      process.stdout.write(C.d('[no --policy given; using built-in sample policy]\n\n'));
+    }
+  }
+
+  let blocked = 0, allowed = 0;
+  for (const raw of traffic) {
+    const tool     = normalizeToolUse(raw);
+    const decision = evaluate(tool, policy);
+    if (decision.decision === 'BLOCK') blocked++; else allowed++;
+    renderDecision(raw, decision);
+  }
+
+  process.stdout.write(
+    `\n${C.b('Summary')}: ${C.g(allowed + ' allowed')} · ${C.r(blocked + ' blocked')} ` +
+    `· ${traffic.length} total\n`);
+  return blocked > 0 ? 1 : 0;
+}
+
+function renderDecision(raw, dec) {
+  const name = raw.name || 'unknown';
+  const sub  = raw.input?.action || '';
+  const tag  = sub ? `${name}.${sub}` : name;
+  const valuePreview = previewInput(raw);
+  if (dec.decision === 'BLOCK') {
+    process.stdout.write(`  ${C.r('✗ BLOCK')}  ${C.b(tag.padEnd(28))} ${C.d(valuePreview)}\n`);
+    process.stdout.write(`           ${C.d('reason: ' + dec.reason + (dec.detail ? ' (' + dec.detail + ')' : ''))}\n`);
+  } else {
+    process.stdout.write(`  ${C.g('✓ ALLOW')}  ${C.b(tag.padEnd(28))} ${C.d(valuePreview)}\n`);
+  }
+}
+
+function previewInput(raw) {
+  const inp = raw.input || {};
+  if (inp.text) return JSON.stringify(inp.text).slice(0, 60);
+  if (inp.command) return inp.command.slice(0, 60);
+  if (inp.coordinate) return `[${inp.coordinate.join(',')}]`;
+  return '';
+}
+
+module.exports = {
+  runComputerUseCli,
+  EXAMPLE_TRAFFIC,
+  EXAMPLE_POLICY,
+  _parsePolicyYaml: parsePolicyYaml,
+};

package/src/adapters/computer-use.js

@@ -0,0 +1,227 @@
+'use strict';
+
+/**
+ * adapters/computer-use.js — policy + decision engine for Anthropic Computer
+ * Use traffic.
+ *
+ * Status: tech-demo scaffold. This module defines the tool schemas,
+ * normalises raw tool-use blocks into a stable internal shape, and applies
+ * a small set of computer-use-specific deny directives. It is intentionally
+ * decoupled from the live proxy adapter — wiring it into the request path
+ * (so a real Computer-Use session is policed in real time) requires an
+ * Anthropic API key for validation and lives behind the `occasio
+ * computer-use` CLI as a dry-run demo until then.
+ *
+ * Why a separate adapter at all
+ *   Coding agents touch files. Computer-use agents touch the whole
+ *   operating system: screen pixels, keyboard, mouse, browser. The blast
+ *   radius is qualitatively larger. The same governance primitives (deny,
+ *   redact, audit, attest) need a different rule vocabulary:
+ *     - "this URL pattern is forbidden navigation"
+ *     - "the keyboard input must not match a known-secret pattern"
+ *     - "the screenshot must not contain region X" (stub — pixel work
+ *       is deferred until we have a real session to validate against)
+ *
+ * Tool inventory (Anthropic Computer Use API, v20241022 / v20250124)
+ *   computer.screenshot              → no inputs
+ *   computer.mouse_move              → { coordinate: [x, y] }
+ *   computer.left_click              → { coordinate? }
+ *   computer.right_click             → { coordinate? }
+ *   computer.middle_click            → { coordinate? }
+ *   computer.double_click            → { coordinate? }
+ *   computer.left_click_drag         → { start_coordinate, coordinate }
+ *   computer.type                    → { text }
+ *   computer.key                     → { text }   (keysym)
+ *   computer.cursor_position         → no inputs
+ *   bash                             → { command }   (shell)
+ *   str_replace_editor               → file editing (out of scope here;
+ *                                       handled by existing Read/Edit path)
+ *
+ * Decision codes match the rest of Occasio: ALLOW | BLOCK | TRANSFORM.
+ *
+ * NOT YET DONE (explicit deferrals — track at the call sites):
+ *   - Live proxy adapter wiring (needs `x-occasio-agent: computer-use`
+ *     header routing and tool-result injection back into the SSE stream).
+ *     Today the proxy only knows Claude Code; the Cline adapter is
+ *     synthetic; computer-use will be the third live adapter.
+ *   - Pixel-region deny rules. Requires lifting screenshot tensors and
+ *     either OCR or fixed-region template matching. Deferred until at
+ *     least one paying customer asks.
+ *   - URL extraction from screenshots / browser state. We can intercept
+ *     `bash` calls that issue `curl`/`wget` etc. via existing rules, but
+ *     mouse-driven browser navigation will need a hook into the agent's
+ *     screen-state stream — likely an MCP-style "browser state" tool.
+ */
+
+// ── Tool registry ────────────────────────────────────────────────────────────
+
+const COMPUTER_ACTIONS = new Set([
+  'screenshot', 'mouse_move',
+  'left_click', 'right_click', 'middle_click', 'double_click',
+  'left_click_drag',
+  'type', 'key', 'cursor_position',
+]);
+
+const KNOWN_TOOL_NAMES = new Set([
+  'computer', 'bash', 'str_replace_editor',
+]);
+
+/**
+ * Normalise a raw tool_use block (as it appears in Anthropic messages
+ * API responses) into a stable `{ kind, action, ... }` shape that the
+ * policy engine consumes.
+ *
+ * Returns null for unrecognised inputs so callers can decide whether
+ * an unknown tool is itself a policy violation.
+ */
+function normalizeToolUse(block) {
+  if (!block || typeof block !== 'object') return null;
+  if (block.type && block.type !== 'tool_use') return null;
+  const name = String(block.name || '').toLowerCase();
+  if (!KNOWN_TOOL_NAMES.has(name)) return null;
+  const input = (block.input && typeof block.input === 'object') ? block.input : {};
+
+  if (name === 'computer') {
+    const action = String(input.action || '').toLowerCase();
+    if (!COMPUTER_ACTIONS.has(action)) return null;
+    return {
+      kind:        'computer',
+      action,
+      coordinate:       Array.isArray(input.coordinate)       ? input.coordinate.slice(0, 2) : null,
+      start_coordinate: Array.isArray(input.start_coordinate) ? input.start_coordinate.slice(0, 2) : null,
+      text:        typeof input.text === 'string' ? input.text : null,
+      raw:         block,
+    };
+  }
+  if (name === 'bash') {
+    return {
+      kind:    'bash',
+      command: typeof input.command === 'string' ? input.command : null,
+      raw:     block,
+    };
+  }
+  if (name === 'str_replace_editor') {
+    return { kind: 'str_replace_editor', raw: block };
+  }
+  return null;
+}
+
+// ── Policy rules ─────────────────────────────────────────────────────────────
+
+/**
+ * A computer-use policy is a plain object — same flavour as policy.yml.
+ * Recognised directives (extensions to the existing engine):
+ *
+ *   deny_keyboard_patterns:
+ *     - pattern: '(?i)password\\s*[:=]\\s*\\S+'
+ *       reason:  'keyboard-secret-pattern'
+ *
+ *   deny_command_patterns:        # bash commands
+ *     - '(?i)\\bsudo\\b'
+ *
+ *   deny_screen_regions:          # stub: pixel work deferred
+ *     - { x: 0, y: 0, w: 1920, h: 100, reason: 'top-bar-banner-info' }
+ *
+ *   max_clicks_per_minute: 30     # rate-limit click bursts
+ *   allow_browser_hosts:          # if non-empty, anything else denied
+ *     - 'github.com'
+ *     - 'docs.anthropic.com'
+ *
+ * Missing directives → no constraint from that directive (additive).
+ */
+
+const RESERVED_SHELL_BLACKLIST = [
+  /\bsudo\b/i, /\bsu\b/i,
+  /\brm\s+-rf\s+\//i,
+  /\bmkfs\b/i, /\bdd\s+if=/i,
+  /:\(\)\s*\{\s*:\|:\&/,   // fork bomb
+];
+
+// Compile a policy pattern string into a JS RegExp. PCRE/RE2-style inline
+// flag prefixes `(?i)` and `(?m)` are not native to JS — translate them to
+// the corresponding RegExp flags so policy authors can write the syntax
+// they already know. Returns null on malformed input (caller treats as
+// skip-not-fail to keep one bad rule from disarming the rest of policy).
+function compilePolicyPattern(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  let body = raw;
+  let flags = '';
+  const inlineFlagMatch = body.match(/^\(\?([imsux]+)\)/);
+  if (inlineFlagMatch) {
+    for (const ch of inlineFlagMatch[1]) {
+      if ('ims'.includes(ch) && !flags.includes(ch)) flags += ch;
+    }
+    body = body.slice(inlineFlagMatch[0].length);
+  }
+  try { return new RegExp(body, flags); }
+  catch { return null; }
+}
+
+function evaluate(tool, policy = {}) {
+  if (!tool) {
+    return { decision: 'BLOCK', reason: 'unrecognised-tool-use', tool: null };
+  }
+
+  if (tool.kind === 'computer') {
+    if (tool.action === 'type' || tool.action === 'key') {
+      const txt = tool.text || '';
+      const pats = (policy.deny_keyboard_patterns || []).map(p =>
+        typeof p === 'string' ? { pattern: p, reason: 'keyboard-pattern' }
+                              : { pattern: p.pattern, reason: p.reason || 'keyboard-pattern' });
+      for (const { pattern, reason } of pats) {
+        const re = compilePolicyPattern(pattern);
+        if (!re) continue;             // malformed → skip, not fatal
+        if (re.test(txt)) {
+          return {
+            decision: 'BLOCK', reason, tool,
+            detail: 'keyboard input matches deny pattern',
+          };
+        }
+      }
+    }
+    // mouse / screenshot / cursor: pass-through under current policy set.
+    // Pixel-region rules and rate limits land here when implemented.
+    return { decision: 'ALLOW', reason: 'pass-through', tool };
+  }
+
+  if (tool.kind === 'bash') {
+    const cmd = tool.command || '';
+    if (!cmd) return { decision: 'BLOCK', reason: 'empty-command', tool };
+
+    // Built-in lethal-command blacklist — always on, not configurable.
+    // Computer-Use agents can invoke shell with little oversight; we
+    // refuse the most dangerous one-liners even if policy is permissive.
+    for (const re of RESERVED_SHELL_BLACKLIST) {
+      if (re.test(cmd)) {
+        return { decision: 'BLOCK', reason: 'reserved-blacklist', tool, detail: re.source };
+      }
+    }
+    const customPats = policy.deny_command_patterns || [];
+    for (const raw of customPats) {
+      const re = compilePolicyPattern(raw);
+      if (!re) continue;               // malformed → skip, not fatal
+      if (re.test(cmd)) {
+        return { decision: 'BLOCK', reason: 'command-pattern', tool, detail: raw };
+      }
+    }
+    return { decision: 'ALLOW', reason: 'pass-through', tool };
+  }
+
+  if (tool.kind === 'str_replace_editor') {
+    // File-editor calls flow through the existing Read/Write/Edit path;
+    // we forward unchanged here.
+    return { decision: 'ALLOW', reason: 'delegated-to-editor-adapter', tool };
+  }
+
+  return { decision: 'BLOCK', reason: 'unrecognised-tool-kind', tool };
+}
+
+module.exports = {
+  normalizeToolUse,
+  evaluate,
+  COMPUTER_ACTIONS,
+  KNOWN_TOOL_NAMES,
+  // Exposed for tests + custom policy linters.
+  _RESERVED_SHELL_BLACKLIST: RESERVED_SHELL_BLACKLIST,
+  _compilePolicyPattern:     compilePolicyPattern,
+};

package/src/analyzer.js

@@ -0,0 +1,170 @@
+'use strict';
+
+/** Flatten a message content block to plain text. */
+function flattenContent(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) return content.map(b => (typeof b === 'string' ? b : b.text || '')).join('\n');
+  return '';
+}
+
+/** Rough token estimate: ~4 chars per token (Anthropic approximation). */
+function estimateTokens(text) {
+  return Math.ceil((text || '').length / 4);
+}
+
+// ── Level 1: File-level token accounting ──────────────────────────────────────
+
+/**
+ * Parses messages for Read tool results and returns [{name, tokens}] sorted
+ * by token count descending (max 20 files).
+ *
+ * Modern Claude Code sends structured tool_use / tool_result blocks:
+ *   assistant: [{type:"tool_use", id:"toolu_01", name:"Read", input:{file_path:"src/foo.ts"}}]
+ *   user:      [{type:"tool_result", tool_use_id:"toolu_01", content:"<file text>"}]
+ *
+ * We walk the full message history to build a map of
+ *   tool_use_id → file_path   (from tool_use blocks where name === "Read")
+ * then match tool_result blocks by tool_use_id to estimate content tokens.
+ *
+ * Falls back to the old `--- path ---` delimiter format for legacy sessions.
+ */
+function parseFileTokens(messages) {
+  const fileMap = new Map();
+  const msgs = messages || [];
+
+  // Pass 1: collect Read tool_use blocks: id → file_path
+  const readIdToPath = new Map();
+  for (const msg of msgs) {
+    if (!Array.isArray(msg.content)) continue;
+    for (const block of msg.content) {
+      if (block.type === 'tool_use' && block.name === 'Read' && block.id && block.input?.file_path) {
+        readIdToPath.set(block.id, String(block.input.file_path));
+      }
+    }
+  }
+
+  // Pass 2: match tool_result content to file_path via tool_use_id
+  if (readIdToPath.size > 0) {
+    for (const msg of msgs) {
+      if (!Array.isArray(msg.content)) continue;
+      for (const block of msg.content) {
+        if (block.type !== 'tool_result' || !block.tool_use_id) continue;
+        const filePath = readIdToPath.get(block.tool_use_id);
+        if (!filePath) continue;
+        // content can be a string or an array of content blocks
+        let text = '';
+        if (typeof block.content === 'string') {
+          text = block.content;
+        } else if (Array.isArray(block.content)) {
+          text = block.content.map(b => (typeof b === 'string' ? b : b.text || '')).join('\n');
+        }
+        fileMap.set(filePath, (fileMap.get(filePath) || 0) + estimateTokens(text));
+      }
+    }
+  }
+
+  // Fallback: legacy `--- path ---` delimiter format
+  if (fileMap.size === 0) {
+    for (const msg of msgs) {
+      const text = flattenContent(msg.content);
+      const delimRe = /^---[ \t]+(\S+\.[a-zA-Z0-9]\S*)[ \t]+---\r?\n([\s\S]*?)(?=^---[ \t]+\S+\.[\w]\S*[ \t]+---|$(?![\s\S]))/gm;
+      for (const m of text.matchAll(delimRe)) {
+        const name = m[1].trim();
+        fileMap.set(name, (fileMap.get(name) || 0) + estimateTokens(m[2]));
+      }
+    }
+  }
+
+  return [...fileMap.entries()]
+    .map(([name, tokens]) => ({ name, tokens }))
+    .sort((a, b) => b.tokens - a.tokens)
+    .slice(0, 20);
+}
+
+// ── Level 2: Secret scanning with line context ────────────────────────────────
+
+const SECRET_PATTERNS = [
+  // High-confidence structural patterns — match regardless of surrounding context
+  { re: /sk-ant-api03-[A-Za-z0-9_-]{40,}/,                            label: 'anthropic-key'  },
+  { re: /ghp_[A-Za-z0-9]{36}/,                                        label: 'github-pat'     },
+  { re: /AKIA[0-9A-Z]{16}/,                                           label: 'aws-access-key' },
+  { re: /-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY/,                 label: 'private-key'    },
+  { re: /(postgres|mysql|mongodb):\/\/[^:]+:[^@]+@/,                  label: 'db-url'         },
+  // Generic patterns — require direct assignment (key=value) to reduce false positives.
+  // Original broad regexes matched mid-word (apiKeyValidator) and indirect context
+  // (TOKEN anywhere then = anywhere on same line). These tightened forms require the
+  // keyword immediately before the separator with no intervening tokens.
+  { re: /api[_-]?key\s*[:=]\s*['"]?\S{16,}/i,                        label: 'api-key'        },
+  { re: /password\s*[:=]\s*['"]?\S{8,}/i,                            label: 'password'       },
+  { re: /(?:access|bearer|auth)[_-]?token\s*[:=]\s*['"]?\S{16,}/i,   label: 'token'          },
+];
+
+/** Keep line structure, mask alphanumeric chars for safe logging. */
+function redactLine(line) {
+  const truncated = line.slice(0, 80) + (line.length > 80 ? '…' : '');
+  return truncated.replace(/[A-Za-z0-9]/g, '*');
+}
+
+/**
+ * Scans text line-by-line for known secret patterns plus any caller-supplied extras.
+ *
+ * @param {string} text
+ * @param {object} [opts]
+ * @param {Array<{label:string, regex:RegExp}>} [opts.extraPatterns]  Custom compiled patterns
+ * Returns [{label, line, snippet}] — deduplicated by pattern+line.
+ */
+function scanSecrets(text, opts) {
+  const extra  = (opts && Array.isArray(opts.extraPatterns)) ? opts.extraPatterns : [];
+  const patterns = extra.length
+    ? SECRET_PATTERNS.concat(extra.map(p => ({ re: p.regex, label: p.label })))
+    : SECRET_PATTERNS;
+
+  const lines = text.split('\n');
+  const hits  = [];
+  const seen  = new Set();
+
+  for (let i = 0; i < lines.length; i++) {
+    for (const { re, label } of patterns) {
+      if (re.test(lines[i])) {
+        const key = `${label}:${i}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          hits.push({ label, line: i + 1, snippet: redactLine(lines[i]) });
+        }
+        break;
+      }
+    }
+  }
+
+  return hits;
+}
+
+/**
+ * Replace matched secret patterns in text with [REDACTED:label] tokens.
+ * Scan runs before replacement so line numbers in hits are accurate.
+ * Returns the redacted string (input is not mutated).
+ *
+ * @param {string} text
+ * @param {object} [opts]
+ * @param {Array<{label:string, regex:RegExp}>} [opts.extraPatterns]
+ */
+function redactSecrets(text, opts) {
+  if (typeof text !== 'string') return text;
+  const extra  = (opts && Array.isArray(opts.extraPatterns)) ? opts.extraPatterns : [];
+  const patterns = extra.length
+    ? SECRET_PATTERNS.concat(extra.map(p => ({ re: p.regex, label: p.label })))
+    : SECRET_PATTERNS;
+
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    for (const { re, label } of patterns) {
+      if (re.test(lines[i])) {
+        lines[i] = lines[i].replace(re, `[REDACTED:${label}]`);
+        break;
+      }
+    }
+  }
+  return lines.join('\n');
+}
+
+module.exports = { flattenContent, estimateTokens, parseFileTokens, SECRET_PATTERNS, redactLine, scanSecrets, redactSecrets };