residoo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 residoo 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,185 @@
+# residoo
+
+**Find secrets leaking through your AI coding agent's session history.**
+
+Every time Claude Code, Cursor, or a similar tool reads a file, runs a command, or
+browses a page on your behalf, it writes a transcript of the whole session to disk —
+including the contents of whatever it touched. If that ever included a `.env` file,
+a config with a real key in it, or a login token captured during testing, that
+credential is now sitting in plaintext, indefinitely, in a place almost nobody
+thinks to check.
+
+residoo scans those transcripts and tells you what's in them.
+
+```
+$ residoo scan
+
+⚠  17 potential secrets found across 3 files
+   87 files scanned (1.2 GB) · sources: claude-code
+   oldest match ~8d old · most recent ~0d old
+
+    16  [high]  AWS Access Key ID   (1 distinct value, re-exposed 15× across tool output)
+     1  [high]  Private key block
+
+Values are redacted in this report — first/last 4 characters only. Nothing scanned
+here left your machine; residoo makes no network calls.
+```
+
+## Why this, and not a git secret scanner
+
+Tools like `gitleaks` and `trufflehog` are excellent at what they do — and what
+they do is scan **commits**. That's a different, well-covered space. Nobody was
+looking at the **conversation transcripts** these agents leave behind, which
+contain a superset of everything a commit does: not just code, but file
+contents, terminal output, and whatever got pasted into a prompt.
+
+## What it does
+
+- Scans your local AI-agent session transcripts for high-confidence secret
+  patterns (cloud provider keys, private key blocks, OAuth/API tokens,
+  database connection strings, and more — see `src/patterns.js`).
+- Redacts everything in its own output. You get a shape and a first/last-4
+  preview, never the real value — including in `--json` mode.
+- Tells you how many **distinct** secrets it found versus how many times one
+  got echoed back across tool calls, so the headline number reflects real
+  exposure, not repetition.
+- Flags likely placeholder/example matches (an HTML form's
+  `placeholder="AKIA..."` hint, a doc's example key) separately from real
+  findings, rather than either hiding them or inflating the count with them.
+
+## Sealing what it finds
+
+Finding a leaked key in a transcript raises the obvious next question: *now
+what?* `--seal` is the answer:
+
+```bash
+residoo scan --seal
+```
+
+Every transcript that carried a finding is encrypted into a local vault
+directory — AES-256-GCM, key derived from your passphrase with scrypt, streamed
+(an 800MB transcript never touches memory whole). The vault's manifest — the
+mapping from numbered blobs back to real paths — is itself encrypted, so the
+vault doesn't advertise what's inside it even by name. **Originals are never
+touched**: once you've verified a restore works (`residoo unseal <vault> --restore
+0001.sealed --out /tmp/check` — verified byte-identical via a recorded SHA-256),
+deleting the plaintext is your decision, made by you, not by this tool.
+
+Optionally, `--upload-cloudroam` (with `CLOUDROAM_API_KEY`, `--connector`,
+`--bucket`) copies the sealed vault to [CloudRoam](https://cloudroam.io) for
+durable, cross-cloud storage. **This is the only feature in residoo that touches
+the network, it never runs unless you pass the flag, and only ciphertext is
+transmitted** — the vault is sealed before upload code ever executes.
+
+## What it does not do
+
+- **No network calls in the default path — and none at all unless you
+  explicitly pass `--upload-cloudroam`.** A secret scanner that phones home is
+  not a tool you should trust with your secrets. Verify this yourself: the one
+  `fetch` call in the codebase is in `src/sealvault.js`, reachable only behind
+  that flag, and sends only encrypted bytes.
+- **Nothing destructive, ever.** Scanning is read-only. Sealing creates *new*
+  files and modifies or deletes nothing — not even the plaintext it just
+  encrypted a copy of. That last step is deliberately left to a human.
+- **No telemetry, no analytics, no update-check ping.**
+
+## Install
+
+```bash
+npx residoo scan
+```
+
+or install it properly:
+
+```bash
+npm install -g residoo
+residoo scan
+```
+
+Requires Node.js 18+. Zero runtime dependencies — check `package.json`.
+
+## Usage
+
+```
+residoo scan [options]
+
+  --json                  machine-readable output (full detail, still redacted)
+  --include-noisy         also run broad, false-positive-prone rules
+  --include-suppressed    also show matches that looked like placeholder/example text
+  --fail-on-find          exit code 1 if anything is found (for CI)
+  --no-color              disable ANSI colour
+
+  --seal                  encrypt every transcript with findings into a local vault
+  --vault-dir <dir>       vault location (default ./residoo-vault-<stamp>)
+  --upload-cloudroam      also upload the sealed vault (needs CLOUDROAM_API_KEY,
+                          --connector <id>, --bucket <name>; ciphertext only)
+
+residoo unseal <vault-dir>                          list a vault's contents
+residoo unseal <vault-dir> --restore <n> --out <p>  restore one file, hash-verified
+```
+
+The vault passphrase comes from `RESIDOO_PASSPHRASE` or a hidden interactive
+prompt. There is no recovery if you lose it — that is the point of the design,
+so pick one you keep.
+
+## Sources supported today
+
+**Claude Code** (`~/.claude/projects/**/*.jsonl`) — verified against real,
+populated transcript directories while building this.
+
+Cursor, GitHub Copilot, and Windsurf all keep local session history too, and
+support for them is very much wanted — but shipping a scanner that checks a
+guessed path and reports "all clear" when it simply didn't know where to
+look is worse than not supporting a tool at all. If you use one of these and
+want to add a verified adapter, see below — it's a small, self-contained
+file.
+
+## Adding a source
+
+A source is a small object with four methods: `id()`, `label()`,
+`available()`, `files()`, and `readLines(file)`. `src/sources/claude-code.js`
+is the reference implementation — copy it, point it at the real local
+storage path for your tool, and open a PR. Two contracts scan.js actually
+depends on, worth getting right rather than guessing from a quick skim:
+
+- **`files()`** is a generator yielding `{ file, mtimeMs, sizeBytes, broken }`.
+  Set `broken: true` (other fields can be omitted) for an entry that looked
+  like it should be scannable but wasn't — a dangling symlink is the main
+  case. Don't just `continue` past it inside the generator: an early version
+  of the Claude Code source did exactly that, and a real, non-hypothetical
+  case (a project directory relocated via a symlink whose target no longer
+  exists) went completely invisible — not in the scan count, not in any
+  warning, nothing. Surfacing it as `broken` is what lets scan.js report it
+  instead.
+- **`readLines(file)`** is `async`, returning `{ lines, status, bytesRead }`.
+  `status` is `"complete"`, `"partial"` (some real lines WERE read before a
+  failure partway through — return them, don't discard real content because
+  the rest of the file didn't finish cleanly), `"too-large"`, or `"failed"`.
+  Whatever you return in `lines` for a non-"complete" status still gets
+  scanned normally.
+
+Please verify the path actually exists and holds real content before
+submitting — see the note above on why
+that matters here specifically.
+
+## A known limitation, stated plainly
+
+Shape-based detection can't tell a real secret from a realistic-looking
+example in a fetched web page or a piece of documentation your agent read
+aloud back to you. The `--include-suppressed`/placeholder-context heuristic
+catches the common UI-hint case, not every case. Treat every finding as a
+lead to check, not a certainty — the same is true of every tool in this
+category, including the well-established ones.
+
+## License
+
+MIT. See `LICENSE`.
+
+---
+
+Built and maintained by the team behind [CloudRoam](https://cloudroam.io) —
+client-side encrypted, cross-cloud backup. residoo has no dependency on
+CloudRoam and never will need one to be useful; if a scan turns up something
+you want stored somewhere durable and encrypted going forward, that's the
+kind of problem CloudRoam solves, but it's an entirely separate choice from
+running this tool.

package/SECURITY.md

@@ -0,0 +1,75 @@
+# Security policy
+
+## Reporting a vulnerability
+
+If you find a security issue in residoo — including "this finding shouldn't
+have been suppressed," "this output leaked more than it should have," or
+anything in the redaction logic — please report it privately rather than as
+a public issue. Open a [GitHub Security Advisory](../../security/advisories/new)
+on this repository, or email the maintainer listed in `package.json`.
+
+Please include:
+- What you ran and what you expected vs. what happened
+- Whether real secret material was involved (if so, a redacted/synthetic
+  reproduction is preferred over the real value)
+
+You'll get an acknowledgment within a few days. There's no bug bounty —
+this is a small open-source tool, not a funded program — but every report
+gets read and taken seriously, and credited in the fix unless you'd rather
+stay anonymous.
+
+## What's already been checked, and how
+
+This isn't a claim taken on faith. Every property below was tested, not
+just asserted — see the git history for the actual commands run:
+
+- **No network calls in the scan path.** Grepped for every network-capable
+  primitive (`http`, `https`, `fetch`, `child_process`, etc.) across the
+  scanning code. The codebase's single `fetch` lives in `src/sealvault.js`,
+  is reachable only behind the explicit `--upload-cloudroam` flag, and
+  transmits ciphertext only — the vault is fully sealed before that code
+  can run.
+- **Scanning is read-only.** Grepped for every filesystem write/delete
+  primitive in the scan path. Sealing (`--seal`) writes NEW files into a
+  vault directory it creates; nothing in the codebase modifies or deletes
+  an existing file, including the plaintext originals a seal just encrypted —
+  removing those is deliberately left to the human.
+- **Output can't leak more than it shows.** The one raw matched value is
+  used in exactly two places: an in-memory dedup count (never serialized)
+  and the redaction function. Verified with a crafted input containing a
+  raw ANSI escape sequence that a real terminal would execute — confirmed
+  it rendered live (a working clear-screen) before the fix, confirmed it
+  doesn't after.
+- **Not vulnerable to regex denial-of-service.** Every pattern checked
+  against the nested-quantifier shape behind real, dated CVEs in adjacent
+  tooling (e.g. CVE-2026-0621, a ReDoS in Anthropic's own MCP SDK from
+  catastrophic backtracking on an exploded template pattern). Also stress-
+  tested directly against multi-megabyte adversarial inputs.
+- **No supply-chain surface.** Zero runtime dependencies, zero
+  pre/post-install lifecycle scripts — check `package.json` yourself,
+  there's nothing to hide behind a `postinstall` hook.
+
+## Verifying you have the real thing
+
+Fake clones of security tools are a real, active pattern — not a
+hypothetical. In the last year alone: a self-propagating npm worm that
+typosquatted common package names and injected malicious config into AI
+coding tools' own settings files; a fake installer for a well-known AI
+agent tuned to rank highly in AI-assisted search results; and a campaign
+that cloned roughly 10,000 GitHub repositories with fabricated commit
+history to smuggle malware behind a README download link. A tool whose
+entire premise is "trust me with what I find in your secrets" is exactly
+the kind of thing worth impersonating.
+
+- The only npm package is **`residoo`**, published from **this** GitHub
+  repository via CI, not uploaded by hand from a maintainer's laptop.
+- The canonical repository is **`github.com/dandovdub/residoo`** — the one
+  named in this package's own `repository` field, which npm's provenance
+  attestation cryptographically ties each release to. A GitHub account named
+  "residoo" exists and is NOT this project. If you found residoo through a
+  link, a blog post, or a search result rather than directly on npm, check
+  the provenance badge on the npm page — it names the exact repo and
+  workflow that built the release.
+- Nothing here needs a postinstall script, a config change to another
+  tool, or elevated permissions. If a "residoo" you found asks for any of
+  those, it isn't this project.

package/bin/residoo.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+"use strict";
+
+const { main } = require("../src/cli");
+
+main(process.argv).then(
+  (code) => { process.exitCode = code; },
+  (err) => {
+    // Reaching here means a genuine bug, not an expected failure mode — every
+    // expected failure (an unreadable file, no sources, bad args) is caught
+    // inside main()/scan() and turned into a result or an exit code, never a
+    // throw. This is the backstop for whatever that didn't anticipate.
+    //
+    // err isn't guaranteed to be an Error instance — `err && err.message`
+    // silently prints "undefined" for a bare string/object rejection, which
+    // would defeat the one job this handler has. String(err) works for both.
+    process.stderr.write(`residoo crashed unexpectedly: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+  }
+);

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "residoo",
+  "version": "0.1.0",
+  "description": "Find secrets leaking through your AI coding agent's session history. Zero network calls in the scan path, zero dependencies.",
+  "license": "MIT",
+  "author": "CloudRoam (https://cloudroam.io)",
+  "repository": { "type": "git", "url": "git+https://github.com/dandovdub/residoo.git" },
+  "homepage": "https://github.com/dandovdub/residoo#readme",
+  "bugs": { "url": "https://github.com/dandovdub/residoo/issues" },
+  "bin": { "residoo": "bin/residoo.js" },
+  "main": "src/cli.js",
+  "engines": { "node": ">=18" },
+  "scripts": { "test": "node tests/smoke.js" },
+  "files": ["bin", "src", "README.md", "SECURITY.md", "LICENSE"],
+  "keywords": [
+    "security", "secrets", "secret-scanning", "ai-agent", "claude-code",
+    "cursor", "copilot", "mcp", "privacy", "cli", "encryption"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,211 @@
+"use strict";
+
+const path = require("path");
+const { availableSources, ALL_SOURCES } = require("./sources");
+const { scan, emptyResult } = require("./scan");
+const { render, renderJson } = require("./report");
+
+const HELP = `residoo — find secrets leaking through your AI agent's session history
+
+  Coding agents (Claude Code, Cursor, Copilot, ...) write everything you do
+  to a local transcript, including file contents your prompts touch — which
+  means real credentials sitting in plaintext on disk, indefinitely, in a
+  place nobody thinks to check. residoo scans those transcripts for them.
+
+  Scanning makes NO network calls and changes nothing on disk. Findings are
+  redacted in every output format. Sealing (--seal) writes NEW encrypted
+  files only — it never modifies or deletes anything that already exists.
+
+Usage:
+  residoo scan [options]
+  residoo unseal <vault-dir> [--restore <n> --out <path>]
+
+Scan options:
+  --json                  machine-readable output (full detail, still redacted)
+  --include-noisy         also run broad, false-positive-prone rules
+  --include-suppressed    also show matches that looked like placeholder/example text
+  --fail-on-find          exit code 1 if anything is found (for CI)
+  --no-color              disable ANSI colour
+
+Seal options (used with scan):
+  --seal                  after scanning, encrypt every transcript that carried a
+                          finding into a local vault directory (AES-256-GCM,
+                          passphrase-derived key; originals are left untouched)
+  --vault-dir <dir>       where to create the vault (default: ./residoo-vault-<stamp>)
+  --upload-cloudroam      ALSO upload the sealed vault to CloudRoam. This is the
+                          only residoo feature that touches the network, it is
+                          off unless you pass it, and only ciphertext is sent.
+                          Needs CLOUDROAM_API_KEY (env) plus:
+  --connector <id>        CloudRoam connector id for the destination
+  --bucket <name>         destination bucket
+  --prefix <p>            optional key prefix inside the bucket
+
+Unseal:
+  residoo unseal <vault-dir>                      list the vault's contents
+  residoo unseal <vault-dir> --restore 0001.sealed --out file.jsonl
+                                                  restore one entry, verified
+                                                  byte-identical via its
+                                                  recorded SHA-256
+
+The passphrase is read from RESIDOO_PASSPHRASE, or prompted (hidden) on a TTY.
+
+Sources checked on this machine: ${ALL_SOURCES.map((s) => s.label()).join(", ")}
+`;
+
+function argValue(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 && i + 1 < args.length ? args[i + 1] : null;
+}
+
+async function getPassphrase({ confirmNew }) {
+  const { promptHidden } = require("./prompt");
+  const p1 = await promptHidden("Vault passphrase (input hidden): ");
+  if (!p1 || p1.length < 8) throw new Error("Passphrase must be at least 8 characters.");
+  if (confirmNew && !process.env.RESIDOO_PASSPHRASE) {
+    const p2 = await promptHidden("Repeat passphrase: ");
+    if (p1 !== p2) throw new Error("Passphrases did not match.");
+  }
+  return p1;
+}
+
+async function runSeal(result, args) {
+  const { sealFindings, uploadVaultToCloudRoam } = require("./sealvault");
+
+  const filesWithFindings = [...new Set(result.findings.map((f) => f.file))];
+  if (filesWithFindings.length === 0) {
+    process.stdout.write("Nothing to seal — no findings.\n");
+    return 0;
+  }
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  const vaultDir = argValue(args, "--vault-dir") || path.resolve(`residoo-vault-${stamp}`);
+  const passphrase = await getPassphrase({ confirmNew: true });
+
+  process.stdout.write(`\nSealing ${filesWithFindings.length} file(s) with findings into ${vaultDir}\n`);
+  const { entries } = await sealFindings({
+    files: filesWithFindings, vaultDir, passphrase,
+    log: (s) => process.stdout.write(s + "\n"),
+  });
+  const totalPlain = entries.reduce((s, e) => s + e.plainBytes, 0);
+  const totalSealed = entries.reduce((s, e) => s + e.sealedBytes, 0);
+  process.stdout.write(
+    `\nSealed ${entries.length} file(s): ${(totalPlain / 1024 / 1024).toFixed(1)}MB plain -> ` +
+    `${(totalSealed / 1024 / 1024).toFixed(1)}MB encrypted.\n` +
+    `Originals were NOT touched. Once you've verified a restore works\n` +
+    `(residoo unseal ${path.basename(vaultDir)} --restore 0001.sealed --out /tmp/check), removing the\n` +
+    `plaintext originals is your call — residoo never deletes anything itself.\n`
+  );
+
+  if (args.includes("--upload-cloudroam")) {
+    const apiKey = process.env.CLOUDROAM_API_KEY;
+    const connectorId = argValue(args, "--connector");
+    const bucket = argValue(args, "--bucket");
+    if (!apiKey || !connectorId || !bucket) {
+      process.stderr.write("--upload-cloudroam needs CLOUDROAM_API_KEY (env), --connector and --bucket.\n");
+      return 2;
+    }
+    process.stdout.write(`\nUploading sealed vault to CloudRoam (${bucket}) — ciphertext only:\n`);
+    const uploaded = await uploadVaultToCloudRoam({
+      vaultDir,
+      baseUrl: process.env.CLOUDROAM_BASE_URL || "https://cloudroam.io",
+      apiKey, connectorId, bucket,
+      prefix: argValue(args, "--prefix") || "",
+      log: (s) => process.stdout.write(s + "\n"),
+    });
+    process.stdout.write(`Uploaded ${uploaded.length} object(s). The local vault remains at ${vaultDir}.\n`);
+  }
+  return 0;
+}
+
+async function runUnseal(args) {
+  const { openManifest, restoreEntry } = require("./sealvault");
+  const vaultDir = args[1];
+  if (!vaultDir) { process.stderr.write("usage: residoo unseal <vault-dir> [--restore <n> --out <path>]\n"); return 2; }
+
+  const passphrase = await getPassphrase({ confirmNew: false });
+  let manifest;
+  try {
+    manifest = openManifest(vaultDir, passphrase);
+  } catch {
+    process.stderr.write("Could not open vault — wrong passphrase, or the vault is corrupted.\n");
+    return 1;
+  }
+
+  const restoreName = argValue(args, "--restore");
+  if (!restoreName) {
+    process.stdout.write(`Vault contents (${manifest.entries.length} sealed file(s)):\n`);
+    for (const e of manifest.entries) {
+      process.stdout.write(`  ${e.n}  ${(e.plainBytes / 1024 / 1024).toFixed(1).padStart(8)}MB  ${e.origPath}\n`);
+    }
+    return 0;
+  }
+
+  const entry = manifest.entries.find((e) => e.n === restoreName);
+  if (!entry) { process.stderr.write(`No entry "${restoreName}" in this vault.\n`); return 2; }
+  const out = argValue(args, "--out");
+  if (!out) { process.stderr.write("--restore needs --out <path>.\n"); return 2; }
+
+  const { ok, plainBytes } = await restoreEntry(vaultDir, entry, out, passphrase);
+  if (ok) {
+    process.stdout.write(`Restored ${entry.n} -> ${out} (${(plainBytes / 1024 / 1024).toFixed(1)}MB), ` +
+      `verified byte-identical to the original (SHA-256 match).\n`);
+    return 0;
+  }
+  process.stderr.write(`Restored, but verification FAILED — content does not match what was sealed. Do not trust this copy.\n`);
+  return 1;
+}
+
+async function main(argv) {
+  const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help") || args.length === 0) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  const cmd = args[0];
+  if (cmd === "unseal") return runUnseal(args);
+  if (cmd !== "scan") {
+    process.stderr.write(`Unknown command "${cmd}". Try "residoo --help".\n`);
+    return 2;
+  }
+
+  const wantsJson = args.includes("--json");
+  const includeNoisy = args.includes("--include-noisy");
+  const includeSuppressed = args.includes("--include-suppressed");
+  const failOnFind = args.includes("--fail-on-find");
+  // Passed through explicitly to render() rather than mutating
+  // process.env.NO_COLOR — main() is an exported function a host process can
+  // legitimately call more than once (a wrapper CLI, a test runner), and a
+  // mutated env var would leak past this one invocation and silently kill
+  // color for a later call that never asked for that.
+  const noColor = args.includes("--no-color");
+
+  const sources = availableSources();
+  if (sources.length === 0) {
+    const empty = emptyResult();
+    if (wantsJson) {
+      // A --json caller (CI, a script piping into jq) must always get valid JSON
+      // on stdout, even on the "nothing to scan" path — a plain-text message on
+      // stderr with exit 0 silently breaks that contract.
+      process.stdout.write(renderJson(empty) + "\n");
+    } else {
+      process.stderr.write(
+        "No known transcript sources found on this machine.\n" +
+        `Checked: ${ALL_SOURCES.map((s) => s.label()).join(", ")}.\n`
+      );
+    }
+    return 0;
+  }
+
+  const result = await scan({ sources, includeNoisy, includeSuppressed });
+  process.stdout.write((wantsJson ? renderJson(result) : render(result, { noColor })) + "\n");
+
+  if (args.includes("--seal")) {
+    const sealExit = await runSeal(result, args);
+    if (sealExit !== 0) return sealExit;
+  }
+
+  return failOnFind && result.findings.length > 0 ? 1 : 0;
+}
+
+module.exports = { main };

package/src/patterns.js

@@ -0,0 +1,109 @@
+"use strict";
+
+/**
+ * Detection rules for residoo.
+ *
+ * Every rule is high-confidence by design: a security tool that cries wolf gets
+ * uninstalled. Broad, noisy patterns (bare "password=" style matches) are
+ * deliberately left out of the default set rather than included and caveated —
+ * see NOISY_PATTERNS below if you want them anyway via --include-noisy.
+ *
+ * `confidence: "high"` = the shape is specific enough that a match is almost
+ * certainly real (a vendor-prefixed token format). `confidence: "medium"` =
+ * shape-based, occasionally a placeholder or test fixture.
+ */
+
+const PATTERNS = [
+  { id: "aws_access_key_id", label: "AWS Access Key ID", confidence: "high",
+    re: /\bAKIA[0-9A-Z]{16}\b/g },
+  { id: "aws_session_token", label: "AWS Temporary Access Key ID", confidence: "high",
+    re: /\bASIA[0-9A-Z]{16}\b/g },
+  { id: "private_key_block", label: "Private key block", confidence: "high",
+    re: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/g },
+  { id: "github_pat", label: "GitHub personal access token", confidence: "high",
+    re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g },
+  { id: "gitlab_pat", label: "GitLab personal access token", confidence: "high",
+    re: /\bglpat-[A-Za-z0-9_-]{20,}\b/g },
+  { id: "slack_token", label: "Slack token", confidence: "high",
+    re: /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/g },
+  { id: "stripe_key", label: "Stripe API key", confidence: "high",
+    re: /\b(sk|rk)_live_[A-Za-z0-9]{20,}\b/g },
+  // The negative lookahead keeps this rule and anthropic_key mutually exclusive —
+  // without it, "sk-ant-..." matches BOTH patterns and gets reported twice under
+  // two different (one wrong) provider labels. Verified: both regexes independently
+  // matched a synthetic sk-ant- key before this fix.
+  { id: "openai_key", label: "OpenAI API key", confidence: "high",
+    re: /\bsk-(?!ant-)(proj-)?[A-Za-z0-9_-]{20,}\b/g },
+  { id: "anthropic_key", label: "Anthropic API key", confidence: "high",
+    re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
+  { id: "google_api_key", label: "Google / Firebase API key", confidence: "high",
+    re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { id: "npm_token", label: "npm access token", confidence: "high",
+    re: /\bnpm_[A-Za-z0-9]{36}\b/g },
+  { id: "sendgrid_key", label: "SendGrid API key", confidence: "high",
+    re: /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b/g },
+  { id: "twilio_key", label: "Twilio API key", confidence: "high",
+    re: /\bSK[a-f0-9]{32}\b/g },
+  { id: "jwt", label: "JWT-shaped token", confidence: "medium",
+    re: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g },
+  { id: "connection_string_with_password", label: "Database connection string with embedded password", confidence: "high",
+    re: /\b(postgres(?:ql)?|mysql|mongodb(?:\+srv)?):\/\/[^\s:@\/]+:[^\s@\/]{3,}@[^\s\/]+/g },
+  { id: "bearer_header", label: "Authorization: Bearer header with a real-looking token", confidence: "medium",
+    re: /\bauthorization["']?\s*[:=]\s*["']?bearer\s+[A-Za-z0-9._-]{16,}/gi },
+  { id: "refresh_token_field", label: "refresh_token field", confidence: "medium",
+    re: /"refresh_token"\s*:\s*"[^"\s]{20,}"/gi },
+  { id: "access_token_field", label: "access_token field", confidence: "medium",
+    re: /"access_token"\s*:\s*"[^"\s]{20,}"/gi },
+];
+
+/**
+ * Broader, shape-based patterns that catch more but false-positive more often —
+ * a bare `password = "..."` line is frequently a placeholder, a variable name,
+ * or documentation. Opt-in only, never part of the headline count.
+ */
+const NOISY_PATTERNS = [
+  { id: "generic_password_assignment", label: "password / pwd assignment", confidence: "low",
+    re: /\b(password|passwd|pwd)\s*[:=]\s*["']?[^\s"']{6,}["']?/gi },
+  { id: "generic_secret_assignment", label: "generic secret / apikey assignment", confidence: "low",
+    re: /\b(api[_-]?key|secret)\s*[:=]\s*["']?[A-Za-z0-9_\-\/+=]{12,}["']?/gi },
+];
+
+/**
+ * Strip C0 control characters (0x00-0x1F) and DEL (0x7F) — this is where ANSI
+ * escape sequences live. Two of the rules above (connection strings, the
+ * *_token_field rules) match against a negated character class that excludes
+ * whitespace and quotes but NOT control bytes, so a crafted or malformed
+ * transcript line could otherwise put a raw terminal-control sequence into
+ * this tool's own report output. Verified: an unsanitized preview containing
+ * "\x1b[2J" actually clears the screen when printed. Applied here, at the
+ * one place raw matched text turns into displayable text, rather than left
+ * to every call site to remember.
+ */
+// A plain regex, not a manual code-point loop: control characters (0x00-0x1F,
+// 0x7F) are single UTF-16 units that never overlap a surrogate-pair half
+// (those live at 0xD800-0xDFFF), so stripping them by regex can't split or
+// corrupt a multi-unit character — no code-point-aware iteration needed here.
+function stripControlChars(s) { return s.replace(/[\x00-\x1f\x7f]/g, ""); }
+
+/** Mask a matched value for display: never print secret material to a terminal. */
+function redact(value) {
+  const v = stripControlChars(String(value));
+  // Split by code point (Array.from, not .slice/.length) — several rules
+  // match via a negated character class that doesn't exclude non-ASCII, so a
+  // matched value CAN contain an astral character (surrogate pair)
+  // straddling a UTF-16 cut point. .slice(0,4) on the raw string can then
+  // return one half of a pair, rendering as a broken glyph.
+  const cps = Array.from(v);
+  // Every number in this function's OUTPUT — the count included — must come
+  // from the same stripped, code-point-split value the preview itself is
+  // built from. An earlier version reported String(value).length (the raw,
+  // pre-strip, UTF-16-unit count) here: whenever a match actually contained
+  // stripped control bytes, or an astral character, the parenthetical count
+  // visibly didn't match what the preview showed — the exact kind of
+  // internal inconsistency this function exists to avoid.
+  if (cps.length === 0) return "";
+  if (cps.length <= 10) return "*".repeat(cps.length);
+  return cps.slice(0, 4).join("") + "…" + cps.slice(-4).join("") + `  (${cps.length} chars)`;
+}
+
+module.exports = { PATTERNS, NOISY_PATTERNS, redact };