blackbrake 0.1.0

package/src/cost/analyzer.mjs

@@ -0,0 +1,114 @@
+// Where the spend concentrates. Descriptive only: no savings estimates, no causal claims.
+//
+// Episode = one prompt written by the user plus all agent work until the next one. Subagent
+// work is attributed to the episode that was open in the parent session when it started.
+// Harness-injected messages (subagent hand-backs, skill bodies) do not open episodes.
+import { isHarnessText } from '../transcripts.mjs';
+import { priceFor, usageCost } from './prices.mjs';
+
+const userPromptText = (msg) => {
+  if (msg?.role !== 'user') return null;
+  const blocks = Array.isArray(msg.content) ? msg.content : [{ type: 'text', text: msg.content }];
+  if (blocks.some((b) => b?.type === 'tool_result')) return null;
+  const text = blocks.filter((b) => b?.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n').trim();
+  return text && !isHarnessText(text) ? text : null;
+};
+
+export function createCostAnalyzer() {
+  const sessions = new Map(); // session -> { project, episodes: [], turns, minInput, crSum, cost }
+  const subagentRuns = [];    // { session, startTs, cost, turns, tools }
+  const unknownModels = new Set();
+  let file = null;
+  let current = null;         // current file accumulator
+  let episode = null;
+
+  const session = (id, project) => {
+    if (!sessions.has(id)) sessions.set(id, { id, project, episodes: [], turns: 0, minInput: Infinity, crSum: 0, cost: 0 });
+    return sessions.get(id);
+  };
+
+  return {
+    onFile(info) {
+      file = info;
+      episode = null;
+      current = info.isSubagent ? { session: info.session, startTs: null, cost: 0, turns: 0, tools: 0 } : null;
+      if (current) subagentRuns.push(current);
+      else session(info.session, info.project);
+    },
+    onRecord(record) {
+      const msg = record.message;
+      if (!msg) return;
+      const ts = record.timestamp ? Date.parse(record.timestamp) : null;
+      if (current) {
+        if (current.startTs === null && ts) current.startTs = ts;
+        if (msg.role === 'assistant' && msg.usage) {
+          current.cost += usageCost(msg.usage, msg.model);
+          current.turns++;
+          current.tools += (Array.isArray(msg.content) ? msg.content : []).filter((b) => b?.type === 'tool_use').length;
+        }
+        return;
+      }
+      const s = session(file.session, file.project);
+      const prompt = userPromptText(msg);
+      if (prompt) {
+        episode = { session: s.id, project: s.project, start: ts, end: ts, cost: 0, turns: 0, tools: 0, subagents: 0 };
+        s.episodes.push(episode);
+        return;
+      }
+      if (msg.role !== 'assistant' || !msg.usage) return;
+      const u = msg.usage;
+      const p = priceFor(msg.model);
+      // "<synthetic>" marks messages generated locally by the harness; they carry no cost.
+      if (!p.known && msg.model && !msg.model.startsWith('<')) unknownModels.add(msg.model);
+      const c = usageCost(u, msg.model);
+      const input = (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0);
+      s.turns++;
+      s.cost += c;
+      s.crSum += p.cr;
+      if (input > 0 && input < s.minInput) s.minInput = input;
+      if (!episode) { episode = { session: s.id, project: s.project, start: ts, end: ts, cost: 0, turns: 0, tools: 0, subagents: 0 }; s.episodes.push(episode); }
+      episode.cost += c;
+      episode.turns++;
+      episode.end = ts ?? episode.end;
+      episode.tools += (Array.isArray(msg.content) ? msg.content : []).filter((b) => b?.type === 'tool_use').length;
+    },
+    finish() {
+      // Attribute each subagent run to the parent episode open when it started.
+      let unattributed = 0;
+      for (const run of subagentRuns) {
+        const eps = sessions.get(run.session)?.episodes ?? [];
+        const target = [...eps].reverse().find((e) => e.start !== null && run.startTs !== null && e.start <= run.startTs);
+        if (target) { target.cost += run.cost; target.tools += run.tools; target.subagents++; } else unattributed += run.cost;
+      }
+      const episodes = [...sessions.values()].flatMap((s) => s.episodes).filter((e) => e.turns > 0 || e.cost > 0);
+      const costs = episodes.map((e) => e.cost).sort((a, b) => a - b);
+      const total = costs.reduce((a, b) => a + b, 0) + unattributed;
+      const q = (p) => (costs.length ? costs[Math.min(costs.length - 1, Math.floor(p * costs.length))] : 0);
+      const topN = Math.max(1, Math.round(episodes.length * 0.1));
+      const topShare = total ? costs.slice(-topN).reduce((a, b) => a + b, 0) / total : 0;
+      const floors = [...sessions.values()].filter((s) => s.turns >= 3 && Number.isFinite(s.minInput));
+      const floorCost = floors.reduce((a, s) => a + (s.minInput * s.crSum) / 1e6, 0);
+      const mainCost = floors.reduce((a, s) => a + s.cost, 0);
+      const sortedFloors = floors.map((s) => s.minInput).sort((a, b) => a - b);
+      return {
+        total,
+        episodes: episodes.length,
+        p50: q(0.5),
+        p90: q(0.9),
+        topShare,
+        topN,
+        worst: [...episodes].sort((a, b) => b.cost - a.cost).slice(0, 3).map((e) => ({
+          cost: e.cost, turns: e.turns, tools: e.tools, subagents: e.subagents, project: e.project,
+          date: e.start ? new Date(e.start).toISOString().slice(0, 10) : null,
+          hours: e.start && e.end ? (e.end - e.start) / 3.6e6 : null,
+        })),
+        floor: {
+          sessions: floors.length,
+          medianTokens: sortedFloors.length ? sortedFloors[Math.floor(sortedFloors.length / 2)] : 0,
+          share: mainCost ? floorCost / mainCost : 0,
+        },
+        unknownModels: [...unknownModels],
+      };
+    },
+  };
+}

package/src/cost/prices.mjs

@@ -0,0 +1,26 @@
+// API list prices in USD per million tokens, from Anthropic's pricing page
+// (https://docs.anthropic.com/en/docs/about-claude/pricing), checked on the date below.
+// cw = 5-minute cache write. For subscription plans this is a common unit of effort, not a bill.
+export const PRICES_DATE = '2026-09-23';
+
+const TABLE = [
+  [/fable-5-1|mythos-5-1/i, { in: 10, cw: 12.5, cr: 0.25, out: 50 }],
+  [/fable-5|mythos-5/i, { in: 10, cw: 12.5, cr: 1, out: 50 }],
+  [/opus-4-1|opus-4-2025|opus-4-0|claude-opus-4$/i, { in: 15, cw: 18.75, cr: 1.5, out: 75 }],
+  [/opus/i, { in: 5, cw: 6.25, cr: 0.5, out: 25 }], // Opus 4.5 and later
+  [/sonnet-5/i, { in: 2, cw: 2.5, cr: 0.2, out: 10 }],
+  [/sonnet/i, { in: 3, cw: 3.75, cr: 0.3, out: 15 }],
+  [/haiku-3/i, { in: 0.8, cw: 1, cr: 0.08, out: 4 }],
+  [/haiku/i, { in: 1, cw: 1.25, cr: 0.1, out: 5 }],
+];
+
+export function priceFor(model = '') {
+  const hit = TABLE.find(([re]) => re.test(model));
+  return hit ? { ...hit[1], known: true } : { in: 3, cw: 3.75, cr: 0.3, out: 15, known: false };
+}
+
+export function usageCost(u, model) {
+  const p = priceFor(model);
+  return ((u.input_tokens || 0) * p.in + (u.output_tokens || 0) * p.out
+    + (u.cache_creation_input_tokens || 0) * p.cw + (u.cache_read_input_tokens || 0) * p.cr) / 1e6;
+}

package/src/load/inventory.mjs

@@ -0,0 +1,184 @@
+// What the agent loads: skills, agents, commands, plugins, hooks and MCP servers, how much of it
+// is paid for on every turn, how much is ever used, and static patterns worth a look.
+// Static only: nothing found here is ever executed (unlike scanners that start MCP servers).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const readJson = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
+const readText = (f, max = 256 * 1024) => {
+  try { const st = fs.statSync(f); if (!st.isFile() || st.size > max) return null; return fs.readFileSync(f, 'utf8'); } catch { return null; }
+};
+const listDir = (d) => { try { return fs.readdirSync(d, { withFileTypes: true }); } catch { return []; } };
+
+// Frontmatter "name" and "description" (single line, or folded/literal block).
+export function frontmatter(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text ?? '');
+  if (!m) return {};
+  const out = {};
+  const lines = m[1].split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const kv = /^([A-Za-z_-]+):\s*(.*)$/.exec(lines[i]);
+    if (!kv) continue;
+    let value = kv[2].trim();
+    if (/^[|>][-+]?$/.test(value)) {
+      const block = [];
+      while (i + 1 < lines.length && /^\s+/.test(lines[i + 1])) block.push(lines[++i].trim());
+      value = block.join(' ');
+    }
+    out[kv[1]] = value.replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+// Rough token estimate (~4 characters per token for English text).
+const tokens = (s) => Math.ceil((s ?? '').length / 4);
+
+function collectItems(dir, kind, source) {
+  const items = [];
+  for (const e of listDir(dir)) {
+    const full = path.join(dir, e.name);
+    if (kind === 'skill' && e.isDirectory()) {
+      const md = path.join(full, 'SKILL.md');
+      const text = readText(md);
+      if (text === null) continue;
+      const fm = frontmatter(text);
+      const name = fm.name ?? e.name;
+      items.push({ kind, source, name, dir: full, file: md, perTurnTokens: tokens(`${name}: ${fm.description ?? ''}`) });
+    } else if ((kind === 'agent' || kind === 'command') && e.isFile() && e.name.endsWith('.md')) {
+      const text = readText(full);
+      if (text === null) continue;
+      const fm = frontmatter(text);
+      const name = fm.name ?? e.name.replace(/\.md$/, '');
+      items.push({ kind, source, name, dir: null, file: full, perTurnTokens: kind === 'agent' ? tokens(`${name}: ${fm.description ?? ''}`) : 0 });
+    } else if (kind === 'command' && e.isDirectory()) {
+      items.push(...collectItems(full, kind, source));
+    }
+  }
+  return items;
+}
+
+function pluginInstalls(claudeDir, settings) {
+  const installed = readJson(path.join(claudeDir, 'plugins', 'installed_plugins.json'));
+  const enabled = settings?.enabledPlugins ?? {};
+  const out = [];
+  for (const [id, entries] of Object.entries(installed?.plugins ?? {})) {
+    const entry = Array.isArray(entries) ? entries[0] : entries;
+    if (!entry?.installPath) continue;
+    out.push({ id, path: entry.installPath, enabled: enabled[id] === true, version: entry.version ?? null });
+  }
+  return out;
+}
+
+function mcpServers(home, claudeJson, pluginList) {
+  const servers = [];
+  const add = (obj, source) => {
+    for (const [name, cfg] of Object.entries(obj ?? {})) servers.push({ name, source, command: [cfg?.command, ...(cfg?.args ?? [])].filter(Boolean).join(' ') || cfg?.url || '' });
+  };
+  add(claudeJson?.mcpServers, 'user');
+  for (const [proj, p] of Object.entries(claudeJson?.projects ?? {})) add(p?.mcpServers, `project:${path.basename(proj)}`);
+  for (const pl of pluginList.filter((p) => p.enabled)) add(readJson(path.join(pl.path, '.mcp.json'))?.mcpServers ?? readJson(path.join(pl.path, '.mcp.json')), `plugin:${pl.id}`);
+  return servers;
+}
+
+// ------------------------------------------------------------------------------------------------
+// Static patterns. A match is "worth a look", not a verdict: security skills legitimately describe
+// these patterns in their documentation. Matches in executable files and hooks weigh more than
+// matches in Markdown.
+const PATTERNS = [
+  { id: 'remote-exec', label: 'downloads and runs code', re: /\b(curl|wget)\b[^\n|]{0,200}\|\s*(sudo\s+)?(ba|z)?sh\b|\b(iwr|irm|Invoke-WebRequest|Invoke-RestMethod)\b[^\n|]{0,200}\|\s*(iex|Invoke-Expression)\b/i },
+  { id: 'instruction-override', label: 'tells the agent to ignore rules or hide actions', re: /ignore (all )?(previous|prior|above) instructions|do not (tell|inform|mention (this )?to) the user|without (asking|telling|notifying) the user|hide (this|it) from the user/i },
+  { id: 'permission-bypass', label: 'disables permission checks', re: /--dangerously-skip-permissions|bypassPermissions|skipDangerousModePermissionPrompt/ },
+  { id: 'credential-access', label: 'reads credential files', re: /~\/\.ssh\/|id_rsa\b|\.aws\/credentials|\.claude\/\.credentials\.json|\.git-credentials|\.npmrc\b/ },
+  { id: 'exfiltration', label: 'sends environment or secrets over the network', re: /\b(curl|wget|fetch|requests\.(post|put)|Invoke-WebRequest|Invoke-RestMethod)\b[^\n]{0,160}(\$\{?\w*(TOKEN|SECRET|KEY|PASSWORD)|process\.env|os\.environ|printenv|\benv\b\s*\|)/i },
+  { id: 'obfuscation', label: 'decodes and runs hidden content', re: /base64\s+(-d|--decode)[^\n]{0,80}\|\s*(ba)?sh|eval\s*\(\s*(atob|Buffer\.from)\s*\(|[A-Za-z0-9+/]{400,}={0,2}/ },
+];
+const CODE_EXT = /\.(sh|bash|zsh|ps1|py|js|mjs|cjs|ts|rb|json)$/i;
+const SCAN_EXT = /\.(md|sh|bash|zsh|ps1|py|js|mjs|cjs|ts|rb|json|toml|ya?ml)$/i;
+
+function scanFiles(files, owner) {
+  const findings = [];
+  for (const f of files) {
+    const text = readText(f);
+    if (text === null) continue;
+    for (const p of PATTERNS) {
+      if (p.re.test(text)) findings.push({ owner, patternId: p.id, label: p.label, file: f, inCode: CODE_EXT.test(f) });
+    }
+  }
+  return findings;
+}
+
+function filesUnder(dir, depth = 3) {
+  if (!dir || depth < 0) return [];
+  return listDir(dir).flatMap((e) => {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) return e.name === 'node_modules' || e.name.startsWith('.git') ? [] : filesUnder(full, depth - 1);
+    return SCAN_EXT.test(e.name) ? [full] : [];
+  });
+}
+
+export function inventory({ home = os.homedir() } = {}) {
+  const claudeDir = path.join(home, '.claude');
+  const settings = readJson(path.join(claudeDir, 'settings.json')) ?? {};
+  const claudeJson = readJson(path.join(home, '.claude.json')) ?? {};
+  const plugins = pluginInstalls(claudeDir, settings);
+
+  const items = [
+    ...collectItems(path.join(claudeDir, 'skills'), 'skill', 'user'),
+    ...collectItems(path.join(claudeDir, 'agents'), 'agent', 'user'),
+    ...collectItems(path.join(claudeDir, 'commands'), 'command', 'user'),
+  ];
+  for (const pl of plugins.filter((p) => p.enabled)) {
+    items.push(
+      ...collectItems(path.join(pl.path, 'skills'), 'skill', `plugin:${pl.id}`),
+      ...collectItems(path.join(pl.path, 'agents'), 'agent', `plugin:${pl.id}`),
+      ...collectItems(path.join(pl.path, 'commands'), 'command', `plugin:${pl.id}`),
+    );
+  }
+
+  // The same skill or agent can be installed twice (e.g. copied to ~/.claude and bundled in a
+  // plugin). Count each name once; report how many duplicates were found.
+  const seen = new Set();
+  const unique = [];
+  let duplicates = 0;
+  for (const i of items) {
+    const key = `${i.kind}:${i.name.toLowerCase()}`;
+    if (seen.has(key)) { duplicates++; continue; }
+    seen.add(key);
+    unique.push(i);
+  }
+
+  const usage = claudeJson.skillUsage ?? null;
+  const usedNames = new Set(Object.entries(usage ?? {}).filter(([, v]) => (v?.usageCount ?? 0) > 0).flatMap(([k]) => [k, k.split(':').pop()]));
+  const skills = unique.filter((i) => i.kind === 'skill');
+  const usedSkills = usage ? skills.filter((s) => usedNames.has(s.name) || usedNames.has(path.basename(s.dir))).length : null;
+
+  const risks = [
+    ...unique.flatMap((i) => scanFiles(i.dir ? filesUnder(i.dir) : [i.file], `${i.kind}:${i.name}`)),
+    ...plugins.filter((p) => p.enabled).flatMap((p) => scanFiles(filesUnder(path.join(p.path, 'hooks')), `plugin-hooks:${p.id}`)),
+  ];
+
+  const hookEvents = Object.keys(settings.hooks ?? {});
+  return {
+    counts: {
+      skills: skills.length,
+      agents: unique.filter((i) => i.kind === 'agent').length,
+      commands: unique.filter((i) => i.kind === 'command').length,
+      pluginsEnabled: plugins.filter((p) => p.enabled).length,
+      pluginsInstalled: plugins.length,
+      duplicates,
+    },
+    perTurnTokens: {
+      skills: skills.reduce((a, s) => a + s.perTurnTokens, 0),
+      agents: unique.filter((i) => i.kind === 'agent').reduce((a, s) => a + s.perTurnTokens, 0),
+    },
+    usedSkills,
+    mcp: mcpServers(home, claudeJson, plugins),
+    posture: {
+      dangerousModePromptSkipped: settings.skipDangerousModePermissionPrompt === true,
+      defaultModeBypass: settings.permissions?.defaultMode === 'bypassPermissions',
+      hookEvents,
+    },
+    risks,
+  };
+}

package/src/run.mjs

@@ -0,0 +1,13 @@
+// Reads every transcript once and feeds each record to all analyzers.
+import { describeFile, readTranscript } from './transcripts.mjs';
+
+export async function runAnalyzers({ root, files, analyzers }) {
+  for (const file of files) {
+    const info = { file, ...describeFile(root, file) };
+    for (const a of analyzers) a.onFile(info);
+    for await (const { record } of readTranscript(file)) {
+      for (const a of analyzers) a.onRecord(record);
+    }
+  }
+  return analyzers.map((a) => a.finish());
+}

package/src/secrets/audit.mjs

@@ -0,0 +1,86 @@
+// Exposure audit: which secrets are in the transcripts, how many copies each one has, where the
+// copies live and how the secret first got in. Values are never kept in the report: only a hash,
+// the rule id and a masked shape.
+import crypto from 'node:crypto';
+import { fragmentsOf } from '../transcripts.mjs';
+import { classifyOccurrence, classifySecret, isTestPath } from './context.mjs';
+import { scanText } from './engine.mjs';
+
+export const mask = (s) => `${s.slice(0, 4)}…(${s.length})`;
+const hash = (s) => crypto.createHash('sha256').update(s).digest('hex').slice(0, 12);
+
+const ORIGIN = {
+  user: 'pasted by you',
+  'tool-output:Read': 'read from a file by the agent',
+  'tool-output:Bash': 'printed by a command',
+  'tool-output:PowerShell': 'printed by a command',
+  'tool-output': 'returned by a tool',
+  'tool-input': 'written by the agent',
+  assistant: 'written by the agent',
+  snapshot: 'file snapshot',
+  harness: 'injected by the harness',
+  other: 'transcript metadata',
+};
+const originOf = (kind, tool) => ORIGIN[`${kind}:${tool}`] ?? ORIGIN[kind] ?? kind;
+
+// Streaming analyzer: onFile() for each transcript, onRecord() for each line, finish() at the end.
+export function createSecretsAnalyzer(rules) {
+  const secrets = new Map();
+  let file = null;
+  let toolCalls = new Map();
+
+  return {
+    onFile(info) { file = info; toolCalls = new Map(); },
+    onRecord(record) {
+      // Claude Code mirrors tool results inside the same record. Identical strings are scanned
+      // once per record; their copies are still counted.
+      const scanned = new Map();
+      for (const frag of fragmentsOf(record, toolCalls)) {
+        let found = scanned.get(frag.text);
+        if (!found) { found = scanText(rules, frag.text); scanned.set(frag.text, found); }
+        for (const f of found) {
+          const key = hash(f.secret);
+          let s = secrets.get(key);
+          if (!s) {
+            s = { key, ruleId: f.ruleId, shape: mask(f.secret), copies: 0, where: {}, sessions: new Set(), projects: new Set(), subagentCopies: 0, first: null, classes: [], seenInTestFile: false };
+            secrets.set(key, s);
+          }
+          s.copies++;
+          const place = frag.kind === 'tool-output' || frag.kind === 'tool-input' ? `${frag.kind}${frag.tool ? `:${frag.tool}` : ''}` : frag.kind;
+          s.where[place] = (s.where[place] ?? 0) + 1;
+          s.sessions.add(file.session);
+          s.projects.add(file.project);
+          if (file.isSubagent) s.subagentCopies++;
+          if (isTestPath(frag.filePath)) s.seenInTestFile = true;
+          // Mirror copies stored in record metadata carry no context of their own: they count as
+          // copies but do not vote on whether the value is real.
+          if (frag.kind !== 'other') s.classes.push(classifyOccurrence({ secret: f.secret, text: frag.text, index: f.index, filePath: frag.filePath }));
+          const ts = frag.ts ? Date.parse(frag.ts) : Number.POSITIVE_INFINITY;
+          if (!s.first || ts < s.first.ts) s.first = { ts, origin: originOf(frag.kind, frag.tool) };
+        }
+      }
+    },
+    finish() {
+      return [...secrets.values()].map((s) => ({
+        key: s.key,
+        ruleId: s.ruleId,
+        shape: s.shape,
+        classification: classifySecret(s.classes, { seenInTestFile: s.seenInTestFile }),
+        copies: s.copies,
+        subagentCopies: s.subagentCopies,
+        sessions: s.sessions.size,
+        projects: [...s.projects],
+        where: s.where,
+        firstSeen: Number.isFinite(s.first.ts) ? new Date(s.first.ts).toISOString() : null,
+        origin: s.first.origin,
+      })).sort((a, b) => b.copies - a.copies);
+    },
+  };
+}
+
+// Convenience wrapper: run the secrets analyzer alone over a list of transcript files.
+export async function auditSecrets({ root, files, rules }) {
+  const { runAnalyzers } = await import('../run.mjs');
+  const [secrets] = await runAnalyzers({ root, files, analyzers: [createSecretsAnalyzer(rules)] });
+  return secrets;
+}

package/src/secrets/context.mjs

@@ -0,0 +1,59 @@
+// Decides whether a detected secret looks real, or looks like a test fixture, an example or a
+// local-development value. Without this step, a scanner confidently tells people to rotate keys
+// that never existed (it happened on the author's own transcripts: 12 "real" secrets, 0 real).
+
+// Publicly documented example credentials that appear in docs and tests everywhere. Assembled
+// from parts so that this file does not itself trip secret scanners.
+const KNOWN_EXAMPLES = new Set([
+  'AKIA' + 'IOSFODNN7EXAMPLE',
+  'wJalrXUtnFEMI/K7MDENG/' + 'bPxRfiCYEXAMPLEKEY',
+  'AKIA' + 'ABCDEFGHIJKLMNOP',
+]);
+
+const EXAMPLE_WORDS = /\b(fake|falso|falsa|dummy|example|ejemplo|sample|placeholder|mock(ed)?|fixture|lorem|not[- ]a[- ]real|for testing|de prueba|test(ing)?[-_ ]?(key|token|secret)|sk_test_|pk_test_)\b/i;
+const EXAMPLE_PATHS = /(^|[\\/])(tests?|__tests__|spec|specs|fixtures?|examples?|samples?|docs?|testdata|mocks?)([\\/]|$)|\.(example|sample|template|dist)(\b|$)|\.(test|spec)\.[a-z]+\b/i;
+const LOCAL_HOSTS = /\b(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])\b/i;
+// Test code around the value: assertions and test declarations.
+const TEST_CODE = /\b(assert\w*|expect|describe|it|test)\s*\(/;
+// The "secret" is itself source code (an expression), not a value.
+const CODE_EXPRESSION = /\?\.|\|\||&&|=>|\(\)|\bprocess\.env\b|\$\{/;
+
+export const isTestPath = (p) => Boolean(p) && EXAMPLE_PATHS.test(p);
+const WINDOW = 200;
+
+export const CLASSES = {
+  real: 'likely-real',
+  example: 'example-or-test',
+  local: 'local-dev',
+};
+
+// Classifies one occurrence using the text around it and, when known, the file the agent was
+// reading or writing.
+export function classifyOccurrence({ secret, text, index, filePath }) {
+  if (KNOWN_EXAMPLES.has(secret)) return CLASSES.example;
+  if (/^(sk|pk|rk)_test_/.test(secret)) return CLASSES.example;
+  if (CODE_EXPRESSION.test(secret)) return CLASSES.example;
+  // A short value made only of letters ("password", "changeme", "secret") is a word, not a key.
+  if (/^["'`]?[A-Za-z_-]{1,16}["'`]?$/.test(secret)) return CLASSES.example;
+  const around = text.slice(Math.max(0, index - WINDOW), Math.min(text.length, index + secret.length + WINDOW));
+  if (EXAMPLE_WORDS.test(around) || TEST_CODE.test(around)) return CLASSES.example;
+  if ((filePath && EXAMPLE_PATHS.test(filePath)) || EXAMPLE_PATHS.test(around)) return CLASSES.example;
+  if (LOCAL_HOSTS.test(around)) return CLASSES.local;
+  return CLASSES.real;
+}
+
+// A secret is only reported as likely real if most of its occurrences look real. A single
+// example-looking mention is not enough to dismiss a key the user pasted; a single real-looking
+// copy of a fixture that is labelled "fake" everywhere else is not enough to raise an alarm.
+// A value that was ever written into, or read from, a test/fixture/example file is treated as a
+// fixture: real credentials do not normally live in test files, and when they do, the scanner the
+// project already runs on its repository is the right place to catch them.
+export function classifySecret(occurrenceClasses, { seenInTestFile = false } = {}) {
+  if (seenInTestFile) return CLASSES.example;
+  const n = occurrenceClasses.length;
+  if (n === 0) return CLASSES.real;
+  const count = (c) => occurrenceClasses.filter((x) => x === c).length;
+  if (count(CLASSES.example) / n >= 1 / 3) return CLASSES.example;
+  if (count(CLASSES.local) / n >= 1 / 2) return CLASSES.local;
+  return CLASSES.real;
+}

package/src/secrets/engine.mjs

@@ -0,0 +1,121 @@
+// Secret detection using the gitleaks default rule set (vendored, MIT). Semantics follow
+// gitleaks: keyword prefilter, first capture group (or secretGroup) as the secret, Shannon
+// entropy threshold, per-rule and global allowlists and stopwords.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const RULES_FILE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../vendor/gitleaks.rules.json');
+
+export function loadRules(file = RULES_FILE) {
+  const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const compile = (r) => new RegExp(r.source, r.flags.includes('g') ? r.flags : r.flags + 'g');
+  const compileTest = (r) => new RegExp(r.source, r.flags.replace('g', ''));
+  // One combined, case-insensitive search for every rule keyword. A fragment is only tested
+  // against the rules whose keywords it contains (gitleaks' own prefilter, done in one pass).
+  const byKeyword = new Map();
+  const alwaysRun = [];
+  data.rules.forEach((r, i) => {
+    if (!r.keywords.length) alwaysRun.push(i);
+    for (const k of r.keywords) (byKeyword.get(k) ?? byKeyword.set(k, []).get(k)).push(i);
+  });
+  const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const keywordRe = new RegExp([...byKeyword.keys()].sort((a, b) => b.length - a.length).map(escape).join('|'), 'gi');
+  return {
+    keywordRe,
+    byKeyword,
+    alwaysRun,
+    meta: { upstreamCommit: data.upstreamCommit, generated: data.generated, count: data.rules.length },
+    global: {
+      regexes: data.globalAllowlist.regexes.map(compileTest),
+      stopwords: data.globalAllowlist.stopwords,
+    },
+    rules: data.rules.map((r) => ({
+      id: r.id,
+      re: compile(r.regex),
+      keywords: r.keywords,
+      entropy: r.entropy,
+      secretGroup: r.secretGroup,
+      allowlists: r.allowlists.map((a) => ({
+        condition: a.condition,
+        target: a.regexTarget,
+        regexes: a.regexes.map(compileTest),
+        stopwords: a.stopwords,
+      })),
+    })),
+  };
+}
+
+export function shannon(s) {
+  if (!s) return 0;
+  const counts = new Map();
+  for (const ch of s) counts.set(ch, (counts.get(ch) ?? 0) + 1);
+  let h = 0;
+  for (const n of counts.values()) { const p = n / s.length; h -= p * Math.log2(p); }
+  return h;
+}
+
+function allowed(al, secret, match, line) {
+  const target = al.target === 'match' ? match : al.target === 'line' ? line : secret;
+  const hitRe = al.regexes.length > 0 && al.regexes.some((re) => re.test(target));
+  const lower = secret.toLowerCase();
+  const hitStop = al.stopwords.length > 0 && al.stopwords.some((w) => lower.includes(w));
+  if (al.condition === 'AND') {
+    const checks = [];
+    if (al.regexes.length) checks.push(hitRe);
+    if (al.stopwords.length) checks.push(hitStop);
+    return checks.length > 0 && checks.every(Boolean);
+  }
+  return hitRe || hitStop;
+}
+
+const lineAround = (text, index, len) => {
+  const start = text.lastIndexOf('\n', index) + 1;
+  const endNl = text.indexOf('\n', index + len);
+  return text.slice(start, endNl === -1 ? text.length : endNl);
+};
+
+// Returns [{ ruleId, secret, index, length }]
+function candidateRules(rules, text) {
+  const idx = new Set(rules.alwaysRun);
+  rules.keywordRe.lastIndex = 0;
+  let m;
+  while ((m = rules.keywordRe.exec(text)) !== null) {
+    for (const i of rules.byKeyword.get(m[0].toLowerCase()) ?? []) idx.add(i);
+  }
+  return [...idx].sort((a, b) => a - b).map((i) => rules.rules[i]);
+}
+
+export function scanText(rules, text) {
+  const out = [];
+  for (const rule of candidateRules(rules, text)) {
+    rule.re.lastIndex = 0;
+    let m;
+    while ((m = rule.re.exec(text)) !== null) {
+      if (m[0].length === 0) { rule.re.lastIndex++; continue; }
+      const group = rule.secretGroup ?? (m.length > 1 ? m.findIndex((g, i) => i > 0 && g !== undefined) : 0);
+      const secret = (group > 0 ? m[group] : m[0]) ?? m[0];
+      if (!secret) continue;
+      if (rule.entropy !== null && shannon(secret) < rule.entropy) continue;
+      if (rules.global.regexes.some((re) => re.test(secret))) continue;
+      const lowerSecret = secret.toLowerCase();
+      if (rules.global.stopwords.some((w) => lowerSecret.includes(w))) continue;
+      const line = lineAround(text, m.index, m[0].length);
+      if (rule.allowlists.some((al) => allowed(al, secret, m[0], line))) continue;
+      out.push({ ruleId: rule.id, secret, index: m.index + Math.max(0, m[0].indexOf(secret)), length: secret.length });
+    }
+  }
+  return dedupeOverlaps(out);
+}
+
+// When two rules match the same span (e.g. a specific rule and generic-api-key), keep one.
+function dedupeOverlaps(findings) {
+  findings.sort((a, b) => a.index - b.index || (a.ruleId === 'generic-api-key') - (b.ruleId === 'generic-api-key'));
+  const kept = [];
+  for (const f of findings) {
+    const prev = kept.at(-1);
+    if (prev && f.index < prev.index + prev.length && f.secret.includes(prev.secret.slice(0, 8))) continue;
+    kept.push(f);
+  }
+  return kept;
+}