cc-scrub 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "cc-scrub",
+  "description": "Find, redact, and prevent secrets leaking into local Claude Code session transcripts.",
+  "version": "0.1.0",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Read|Bash|Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/hooks/post-tool-use-redact.js\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cc-scrub contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# cc-scrub
+
+Find, redact, and prevent secrets leaking into local Claude Code session transcripts.
+
+Claude Code stores every session as a `.jsonl` file under `~/.claude/projects/`. If you ever pasted an API key, token, or credential into a session — or Claude read a file/ran a command that echoed one back — it's sitting in that transcript in plaintext. `cc-scrub` finds it, lets you redact it in place without breaking Claude Code's ability to resume the session, and can install a live hook that catches secrets before they ever land in context.
+
+## Quick Start
+
+```bash
+npx cc-scrub scan          # scan every local session for secrets
+npx cc-scrub clean <id>    # preview redactions for one session
+npx cc-scrub clean <id> --yes   # redact in place (writes a .bak first)
+npx cc-scrub protect       # install a live redaction hook going forward
+```
+
+No required external dependencies. If [gitleaks](https://github.com/gitleaks/gitleaks#installing) is on your `PATH`, `cc-scrub` uses it; otherwise it automatically falls back to a bundled in-process ruleset (see "Detection engines" below). Run `cc-scrub doctor` to see which one is active.
+
+## Usage
+
+| Command | What it does |
+|---|---|
+| `cc-scrub list` | List local sessions, newest first |
+| `cc-scrub scan [session-id]` | Scan one session, or all of them if omitted. Exit code `1` if anything is found |
+| `cc-scrub clean <session-id>` | Dry run — show what would be redacted |
+| `cc-scrub clean <session-id> --yes` | Redact in place. Always backs up to `<session>.jsonl.bak` first, never overwrites an existing backup |
+| `cc-scrub doctor` | Show which detection engine is active and how many rules loaded |
+| `cc-scrub protect` | Add a `PostToolUse` hook to `~/.claude/settings.json` that redacts secrets from tool output before Claude sees it |
+| `cc-scrub unprotect` | Remove that hook |
+
+Add `--engine auto\|gitleaks\|local` to `scan`/`clean` to control which engine runs (default `auto`: gitleaks binary if installed, else the bundled ruleset). Flag values can be passed as `--engine local` or `--engine=local`.
+
+## Install as a plugin
+
+If you install `cc-scrub` via the Claude Code plugin system instead of npm, the bundled `.claude-plugin/plugin.json` registers the same `PostToolUse` redaction hook automatically — no need to run `protect` separately.
+
+## Detection engines
+
+`cc-scrub` ships two interchangeable engines rather than committing to just one:
+
+- **`gitleaks` (binary)** — shells out to the real [gitleaks](https://github.com/gitleaks/gitleaks) CLI when it's on `PATH`. Full fidelity: this is the actual upstream engine, regex dialect and all.
+- **`local` (bundled, in-process)** — `vendor/gitleaks.toml` is gitleaks' own public MIT-licensed ruleset (pinned to the version this package was built against), vendored directly into the repo. `src/rules.ts` parses it and `src/localDetect.ts` runs it line-by-line in plain TypeScript: keyword pre-filtering, regex matching, Shannon-entropy thresholding, and per-rule/global allowlist filtering — no subprocess, no temp files, no external binary required. `cc-scrub doctor` reports how many rules loaded (221 of 222 at last check; the one skip is a path-only rule with no content regex, correctly inapplicable here).
+
+`--engine auto` (the default) prefers the gitleaks binary when present and falls back to `local` otherwise — including inside the live `protect` hook, which no longer goes fully silent just because gitleaks isn't installed.
+
+**Why not just ship `local` as the only engine?** Two RE2-to-JS regex dialect differences had to be translated (Go/Python-style named groups `(?P<name>...)` → JS's `(?<name>...)`, and RE2's scoped inline case-insensitivity toggle `(?i)`/`(?i:...)`, which JS has no equivalent for — approximated by making the whole pattern case-insensitive instead of just the scoped portion). That's a real, if small, parity gap against the actual gitleaks binary, so `auto` prefers the binary when it's available and treats `local` as the (very close, but not byte-for-byte identical) fallback.
+
+RE2 also guarantees linear-time matching by construction; JS's backtracking regex engine doesn't. Since the vendored ruleset was written for RE2, `local` caps scanned lines at 10,000 characters (real secrets are always far shorter) to bound worst-case regex cost on adversarial input — this is checked, not theoretical (see `test/localDetect.test.ts`), and skipped lines are reported to stderr rather than silently dropped.
+
+## How it works
+
+- **Retroactive clean**: scans a session file with the selected engine, groups findings by line, and replaces only the exact matched secret substring with `[REDACTED:<rule-id>]` — line count and per-line JSON validity are verified before and after every write. If a redaction would corrupt a line's JSON, `cc-scrub` refuses to write anything and tells you which line.
+- **Live hook**: on `PostToolUse` for `Read`/`Bash`/`Grep`/`Glob`, scans the tool's output with the same `auto` engine selection and, if it finds anything, replaces the output via the hook's `updatedToolOutput` field before Claude ever sees it.
+
+## Limitations
+
+- **`local` engine gaps vs. the real gitleaks binary**: line-by-line matching only (no multi-line secrets, e.g. PEM key blocks spanning several lines), and the regex-dialect approximations noted above. See "Detection engines."
+- **Doesn't scan `settings.json`.** Only session transcripts are covered. Secrets embedded in your Bash permission allowlist or other config are out of scope.
+- **Structured tool output is flattened.** If a tool's response is a structured object rather than a plain string, the live hook normalizes it to a JSON string before scanning/redacting — Claude receives a redacted string instead of the original shape.
+- **Already-sent data can't be recalled.** This is local cleanup only. If a secret was already sent to a model provider's API, `cc-scrub` cannot undo that — rotate the credential.
+
+## Roadmap
+
+Keeping `vendor/gitleaks.toml` in sync with upstream gitleaks releases is currently a manual re-pin (bump the version in the download step and re-verify against `test/localDetect.test.ts`) — automating that check is a natural next step. Closing the remaining regex-dialect gaps (proper scoped case-insensitivity, multi-line matching) would bring `local` to full parity with the binary, but isn't blocking anything today since `auto` already prefers the binary whenever it's present.
+
+## Development
+
+```bash
+npm install
+npm run build   # tsc -> dist/
+npm test        # tsx test/*.test.ts — degrades gracefully if gitleaks isn't installed
+```
+
+## License
+
+MIT

package/dist/clean.js

@@ -0,0 +1,51 @@
+import { constants, copyFileSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { detectFile } from "./detect.js";
+import { groupFindingsByLine, redactLines } from "./redact.js";
+import { readSessionLines } from "./sessions.js";
+export function backupPathFor(sessionPath) {
+    return `${sessionPath}.bak`;
+}
+export function ensureBackup(sessionPath) {
+    const path = backupPathFor(sessionPath);
+    try {
+        copyFileSync(sessionPath, path, constants.COPYFILE_EXCL);
+        return { created: true, path };
+    }
+    catch {
+        return { created: false, path };
+    }
+}
+export function planClean(session, engine = "auto") {
+    const { findings, engineUsed } = detectFile(session.path, engine);
+    const lines = readSessionLines(session);
+    const { lines: redactedLines, redactedCount, failures } = redactLines(lines, groupFindingsByLine(findings));
+    return { lines: redactedLines, redactedCount, failures, findings, engineUsed };
+}
+export function applyClean(session, opts) {
+    const plan = planClean(session, opts.engine ?? "auto");
+    if (!opts.yes || plan.redactedCount === 0 || plan.failures.length > 0) {
+        return { ...plan, written: false };
+    }
+    const originalLines = readSessionLines(session);
+    if (plan.lines.length !== originalLines.length) {
+        throw new Error(`refusing to write ${session.path}: redacted line count (${plan.lines.length}) != original (${originalLines.length})`);
+    }
+    const { created, path: backupPath } = ensureBackup(session.path);
+    void created;
+    const raw = readFileSync(session.path, "utf8");
+    const hadTrailingNewline = raw.endsWith("\n");
+    const output = plan.lines.join("\n") + (hadTrailingNewline ? "\n" : "");
+    const tmpPath = `${session.path}.tmp`;
+    writeFileSync(tmpPath, output, "utf8");
+    renameSync(tmpPath, session.path);
+    const verifyLines = readSessionLines(session);
+    if (verifyLines.length !== originalLines.length) {
+        throw new Error(`post-write verification failed for ${session.path}: line count changed after write`);
+    }
+    for (const line of verifyLines) {
+        if (!line)
+            continue;
+        JSON.parse(line);
+    }
+    return { ...plan, written: true, backupPath };
+}

package/dist/cli.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { applyClean, planClean } from "./clean.js";
+import { detectFile } from "./detect.js";
+import { GitleaksNotFoundError, isGitleaksAvailable } from "./gitleaks.js";
+import { loadRuleSet } from "./rules.js";
+import { addHook, readSettings, removeHook, settingsPath, writeSettings } from "./protect.js";
+import { findSession, listSessions } from "./sessions.js";
+import { banner, confirmRedaction, printFindings, printNoFindings, withSpinner } from "./ui.js";
+const VALUE_FLAGS = new Set(["engine"]);
+function parseArgs(argv) {
+    const [command = "", ...rest] = argv;
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (!arg.startsWith("--")) {
+            positional.push(arg);
+            continue;
+        }
+        const [key, inlineValue] = arg.slice(2).split("=");
+        if (inlineValue !== undefined) {
+            flags[key] = inlineValue;
+        }
+        else if (VALUE_FLAGS.has(key) && rest[i + 1] && !rest[i + 1].startsWith("--")) {
+            flags[key] = rest[i + 1];
+            i += 1;
+        }
+        else {
+            flags[key] = true;
+        }
+    }
+    return { command, positional, flags };
+}
+function engineFromFlags(flags) {
+    const value = flags.engine;
+    if (value === "local" || value === "gitleaks")
+        return value;
+    return "auto";
+}
+function usage() {
+    return `cc-scrub — find and remove exposed secrets from Claude Code sessions
+
+Usage:
+  cc-scrub list                     list local sessions (newest first)
+  cc-scrub scan [session-id]        scan one session, or all sessions if omitted
+  cc-scrub clean <session-id>       preview redactions (dry run)
+  cc-scrub clean <session-id> --yes redact in place (writes a .bak backup first)
+  cc-scrub protect                  install a live PostToolUse redaction hook
+  cc-scrub unprotect                remove the hook
+  cc-scrub doctor                   check detection engine status
+
+  --engine auto|gitleaks|local      auto (default): gitleaks binary if installed, else the
+                                     bundled in-process ruleset. Force one explicitly with
+                                     --engine gitleaks or --engine local.`;
+}
+async function main() {
+    const { command, positional, flags } = parseArgs(process.argv.slice(2));
+    const engine = engineFromFlags(flags);
+    try {
+        switch (command) {
+            case "list": {
+                const sessions = listSessions();
+                if (sessions.length === 0) {
+                    console.log("No sessions found.");
+                    break;
+                }
+                for (const s of sessions) {
+                    console.log(`${s.sessionId}  (${s.projectKey})`);
+                }
+                break;
+            }
+            case "scan": {
+                const target = positional[0];
+                const sessions = target ? [findSession(target)].filter((s) => s !== undefined) : listSessions();
+                if (sessions.length === 0) {
+                    console.log("No matching sessions.");
+                    break;
+                }
+                banner("intro", `cc-scrub: scanning ${sessions.length} session(s)`);
+                let anyFound = false;
+                let usedEngine;
+                for (const session of sessions) {
+                    const { findings, engineUsed } = withSpinner(session.sessionId, () => detectFile(session.path, engine));
+                    usedEngine = engineUsed;
+                    if (findings.length === 0) {
+                        printNoFindings();
+                    }
+                    else {
+                        anyFound = true;
+                        printFindings(findings);
+                    }
+                }
+                banner("outro", (anyFound ? "Findings above — run `cc-scrub clean <session-id>`." : "All clear.") +
+                    (usedEngine ? ` (engine: ${usedEngine})` : ""));
+                process.exitCode = anyFound ? 1 : 0;
+                break;
+            }
+            case "clean": {
+                const sessionId = positional[0];
+                if (!sessionId) {
+                    console.error("Usage: cc-scrub clean <session-id> [--yes] [--engine auto|gitleaks|local]");
+                    process.exitCode = 1;
+                    break;
+                }
+                const session = findSession(sessionId);
+                if (!session) {
+                    console.error(`No session found matching "${sessionId}"`);
+                    process.exitCode = 1;
+                    break;
+                }
+                banner("intro", `cc-scrub: cleaning ${session.sessionId}`);
+                const plan = withSpinner("scanning", () => planClean(session, engine));
+                if (plan.redactedCount === 0) {
+                    printNoFindings();
+                    banner("outro", `Nothing to do. (engine: ${plan.engineUsed})`);
+                    break;
+                }
+                printFindings(plan.findings);
+                for (const failure of plan.failures) {
+                    console.error(`  line ${failure.lineNumber}: ${failure.reason}`);
+                }
+                if (plan.failures.length > 0) {
+                    banner("outro", "Refusing to write — some lines failed the JSON safety check above.");
+                    process.exitCode = 1;
+                    break;
+                }
+                const yes = flags.yes === true || (await confirmRedaction(plan.redactedCount));
+                if (!yes) {
+                    banner("outro", "Dry run only. Re-run with --yes to write changes.");
+                    break;
+                }
+                const result = applyClean(session, { yes: true, engine });
+                banner("outro", result.written
+                    ? `Redacted ${result.redactedCount} finding(s) (engine: ${result.engineUsed}). Backup: ${result.backupPath}`
+                    : "No changes written.");
+                break;
+            }
+            case "doctor": {
+                if (isGitleaksAvailable()) {
+                    console.log("gitleaks binary: found (preferred engine when --engine=auto)");
+                }
+                else {
+                    console.log("gitleaks binary: NOT found. Install: https://github.com/gitleaks/gitleaks#installing");
+                }
+                const { rules, skipped } = loadRuleSet();
+                console.log(`local ruleset:   ${rules.length} rule(s) loaded, ${skipped.length} skipped (vendor/gitleaks.toml)`);
+                console.log(isGitleaksAvailable()
+                    ? "protect: will use gitleaks; falls back to the local ruleset automatically if gitleaks is ever removed."
+                    : "protect: will use the local ruleset (gitleaks not installed).");
+                break;
+            }
+            case "protect": {
+                const settings = addHook(readSettings());
+                writeSettings(settings);
+                console.log(`Live redaction hook installed in ${settingsPath()}`);
+                break;
+            }
+            case "unprotect": {
+                const settings = removeHook(readSettings());
+                writeSettings(settings);
+                console.log(`Live redaction hook removed from ${settingsPath()}`);
+                break;
+            }
+            default:
+                console.log(usage());
+                process.exitCode = command ? 1 : 0;
+        }
+    }
+    catch (err) {
+        if (err instanceof GitleaksNotFoundError) {
+            console.error(err.message);
+            process.exitCode = 2;
+            return;
+        }
+        throw err;
+    }
+}
+main();

package/dist/detect.js

@@ -0,0 +1,18 @@
+import { GitleaksNotFoundError, isGitleaksAvailable, scanFile, scanText } from "./gitleaks.js";
+import { scanFileLocal, scanTextLocal } from "./localDetect.js";
+export function detectFile(filePath, engine = "auto") {
+    if (engine !== "local" && isGitleaksAvailable()) {
+        return { findings: scanFile(filePath), engineUsed: "gitleaks" };
+    }
+    if (engine === "gitleaks")
+        throw new GitleaksNotFoundError();
+    return { findings: scanFileLocal(filePath), engineUsed: "local" };
+}
+export function detectText(text, engine = "auto") {
+    if (engine !== "local" && isGitleaksAvailable()) {
+        return { findings: scanText(text), engineUsed: "gitleaks" };
+    }
+    if (engine === "gitleaks")
+        throw new GitleaksNotFoundError();
+    return { findings: scanTextLocal(text), engineUsed: "local" };
+}

package/dist/gitleaks.js

@@ -0,0 +1,71 @@
+import { randomUUID } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export class GitleaksNotFoundError extends Error {
+    constructor() {
+        super("gitleaks not found on PATH. Install: https://github.com/gitleaks/gitleaks#installing");
+        this.name = "GitleaksNotFoundError";
+    }
+}
+export function isGitleaksAvailable() {
+    const probe = spawnSync("gitleaks", ["version"]);
+    return !probe.error;
+}
+export function parseGitleaksReport(json) {
+    if (!Array.isArray(json))
+        return [];
+    return json.map((f) => ({
+        ruleId: f.RuleID,
+        secret: f.Secret,
+        startLine: f.StartLine,
+        endLine: f.EndLine,
+        description: f.Description,
+    }));
+}
+function reportPath() {
+    return join(tmpdir(), `cc-scrub-${randomUUID()}.json`);
+}
+function readAndCleanupReport(path) {
+    if (!existsSync(path))
+        return [];
+    const raw = readFileSync(path, "utf8").trim();
+    unlinkSync(path);
+    if (!raw)
+        return [];
+    return parseGitleaksReport(JSON.parse(raw));
+}
+export function scanFile(filePath) {
+    const outPath = reportPath();
+    const result = spawnSync("gitleaks", [
+        "detect",
+        "--no-git",
+        "--source",
+        filePath,
+        "--report-format",
+        "json",
+        "--report-path",
+        outPath,
+        "--exit-code",
+        "0",
+    ]);
+    if (result.error) {
+        if (result.error.code === "ENOENT") {
+            throw new GitleaksNotFoundError();
+        }
+        throw result.error;
+    }
+    return readAndCleanupReport(outPath);
+}
+export function scanText(text) {
+    const outPath = reportPath();
+    const result = spawnSync("gitleaks", ["stdin", "--report-format", "json", "--report-path", outPath, "--exit-code", "0"], { input: text });
+    if (result.error) {
+        if (result.error.code === "ENOENT") {
+            throw new GitleaksNotFoundError();
+        }
+        throw result.error;
+    }
+    return readAndCleanupReport(outPath);
+}

package/dist/hooks/post-tool-use-redact.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { detectText } from "../detect.js";
+function extractText(toolResponse) {
+    return typeof toolResponse === "string" ? toolResponse : JSON.stringify(toolResponse);
+}
+function main() {
+    try {
+        const raw = readFileSync(0, "utf8");
+        const payload = JSON.parse(raw);
+        const text = extractText(payload.tool_response);
+        // "auto": prefers the gitleaks binary when installed, otherwise falls back to the
+        // bundled in-process ruleset — this hook no longer goes fully silent just because
+        // gitleaks isn't on PATH.
+        const { findings } = detectText(text, "auto");
+        if (findings.length === 0) {
+            process.exit(0);
+        }
+        let redacted = text;
+        for (const finding of findings) {
+            if (!finding.secret)
+                continue;
+            redacted = redacted.split(finding.secret).join(`[REDACTED:${finding.ruleId}]`);
+        }
+        process.stdout.write(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PostToolUse",
+                updatedToolOutput: redacted,
+            },
+        }));
+        process.exit(0);
+    }
+    catch {
+        // never break the tool call on a hook bug — fail open, silently
+        process.exit(0);
+    }
+}
+main();

package/dist/localDetect.js

@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs";
+import { loadRuleSet, shannonEntropy } from "./rules.js";
+function passesAllowlist(secret, ruleAllowlist, globalAllowlist, globalStopwords) {
+    const lower = secret.toLowerCase();
+    for (const word of globalStopwords) {
+        if (lower.includes(word))
+            return false;
+    }
+    for (const re of ruleAllowlist) {
+        re.lastIndex = 0;
+        if (re.test(secret))
+            return false;
+    }
+    for (const re of globalAllowlist) {
+        re.lastIndex = 0;
+        if (re.test(secret))
+            return false;
+    }
+    return true;
+}
+// Gitleaks' regexes are authored for RE2 (Go), which guarantees linear-time
+// matching by construction. JS RegExp uses backtracking, so some of these
+// patterns could in principle be coaxed into catastrophic backtracking on a
+// pathological line — and the live hook runs this on every Read/Bash/Grep/
+// Glob result. Real secrets are always far shorter than this, so capping
+// line length bounds worst-case cost regardless of which rule is at risk.
+const MAX_LINE_LENGTH = 10_000;
+/**
+ * In-process alternative to shelling out to the gitleaks binary. Runs the
+ * vendored gitleaks ruleset (vendor/gitleaks.toml) against text line by
+ * line. Known parity gaps vs. the real binary: line-scoped matching only
+ * (no multi-line secrets like PEM blocks), lines over MAX_LINE_LENGTH are
+ * skipped (see above), and a handful of rules using RE2 scoped inline-flag
+ * groups are translated approximately (see rules.ts).
+ */
+export function scanTextLocal(text) {
+    const { rules, globalAllowlistRegexes, globalStopwords } = loadRuleSet();
+    const lines = text.split("\n");
+    const findings = [];
+    lines.forEach((line, idx) => {
+        const lineNumber = idx + 1;
+        if (line.length > MAX_LINE_LENGTH) {
+            console.error(`cc-scrub: skipping line ${lineNumber} (${line.length} chars) for local-engine scanning — exceeds ${MAX_LINE_LENGTH} char cap`);
+            return;
+        }
+        const lowerLine = line.toLowerCase();
+        for (const rule of rules) {
+            if (rule.keywords.length > 0 && !rule.keywords.some((k) => lowerLine.includes(k))) {
+                continue;
+            }
+            rule.regex.lastIndex = 0;
+            let match;
+            while ((match = rule.regex.exec(line))) {
+                const secret = match[1] ?? match[0];
+                const passesEntropy = rule.entropy === undefined || shannonEntropy(secret) >= rule.entropy;
+                const passesAllow = passesAllowlist(secret, rule.allowlistRegexes, globalAllowlistRegexes, globalStopwords);
+                if (passesEntropy && passesAllow) {
+                    findings.push({
+                        ruleId: rule.id,
+                        secret,
+                        startLine: lineNumber,
+                        endLine: lineNumber,
+                        description: rule.description,
+                    });
+                }
+                if (match.index === rule.regex.lastIndex)
+                    rule.regex.lastIndex += 1; // guard zero-length match loop
+            }
+        }
+    });
+    return findings;
+}
+export function scanFileLocal(filePath) {
+    return scanTextLocal(readFileSync(filePath, "utf8"));
+}

package/dist/protect.js

@@ -0,0 +1,67 @@
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+const HOOK_MARKER = "post-tool-use-redact.js";
+export function settingsPath() {
+    return join(homedir(), ".claude", "settings.json");
+}
+export function hookScriptPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, "hooks", "post-tool-use-redact.js");
+}
+export function hookCommand() {
+    return `node "${hookScriptPath()}"`;
+}
+export function readSettings() {
+    const path = settingsPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        // Do NOT fall back to {} here: writeSettings() would then overwrite the
+        // user's real settings.json with just our hook entry, destroying
+        // everything else in it. Fail loudly instead.
+        throw new Error(`refusing to modify ${path}: it exists but failed to parse as JSON (${err.message}). Fix or back it up before retrying.`);
+    }
+}
+function isOurHook(entry) {
+    return Boolean(entry?.hooks?.some((h) => String(h.command).includes(HOOK_MARKER)));
+}
+export function addHook(settings) {
+    const next = { ...settings };
+    next.hooks = { ...(next.hooks ?? {}) };
+    const existing = next.hooks.PostToolUse ?? [];
+    if (existing.some(isOurHook)) {
+        next.hooks.PostToolUse = existing;
+        return next;
+    }
+    next.hooks.PostToolUse = [
+        ...existing,
+        {
+            matcher: "Read|Bash|Grep|Glob",
+            hooks: [{ type: "command", command: hookCommand() }],
+        },
+    ];
+    return next;
+}
+export function removeHook(settings) {
+    if (!settings.hooks?.PostToolUse)
+        return settings;
+    const next = { ...settings, hooks: { ...settings.hooks } };
+    const filtered = next.hooks.PostToolUse.filter((entry) => !isOurHook(entry));
+    if (filtered.length > 0) {
+        next.hooks.PostToolUse = filtered;
+    }
+    else {
+        delete next.hooks.PostToolUse;
+        if (Object.keys(next.hooks).length === 0)
+            delete next.hooks;
+    }
+    return next;
+}
+export function writeSettings(settings) {
+    writeFileSync(settingsPath(), JSON.stringify(settings, null, 2) + "\n", "utf8");
+}

package/dist/redact.js

@@ -0,0 +1,54 @@
+export function maskPreview(secret) {
+    if (secret.length <= 4)
+        return "*".repeat(secret.length);
+    const stars = Math.min(secret.length - 4, 20);
+    return secret.slice(0, 4) + "*".repeat(stars);
+}
+export function groupFindingsByLine(findings) {
+    const byLine = new Map();
+    for (const finding of findings) {
+        const list = byLine.get(finding.startLine) ?? [];
+        list.push(finding);
+        byLine.set(finding.startLine, list);
+    }
+    return byLine;
+}
+export function redactLine(line, findings) {
+    let candidate = line;
+    for (const finding of findings) {
+        if (!finding.secret || !candidate.includes(finding.secret))
+            continue;
+        candidate = candidate.split(finding.secret).join(`[REDACTED:${finding.ruleId}]`);
+    }
+    if (candidate === line)
+        return { line, changed: false };
+    try {
+        JSON.parse(line);
+        JSON.parse(candidate);
+    }
+    catch {
+        return {
+            line,
+            changed: false,
+            error: "redaction would produce invalid JSON — refusing to modify this line",
+        };
+    }
+    return { line: candidate, changed: true };
+}
+export function redactLines(lines, findingsByLine) {
+    const failures = [];
+    let redactedCount = 0;
+    const result = lines.map((line, idx) => {
+        const lineNumber = idx + 1;
+        const findings = findingsByLine.get(lineNumber);
+        if (!findings || !line)
+            return line;
+        const { line: outLine, changed, error } = redactLine(line, findings);
+        if (error)
+            failures.push({ lineNumber, reason: error });
+        if (changed)
+            redactedCount += findings.length;
+        return outLine;
+    });
+    return { lines: result, redactedCount, failures };
+}