residoo 0.7.2 → 0.8.1

package/README.md

@@ -43,16 +43,16 @@ scanned here left your machine; residoo makes no network calls.
 
 That's one snapshot. `residoo watch` runs the same engine continuously and
 alerts the moment a new secret lands, instead of waiting for you to
-remember to scan again; no other tool in the field has anything like it
-(see [Watch: continuous scanning](#watch-continuous-scanning)):
-
-```
-$ residoo watch
-watching 43 sources, 118 files · polling every 5s
-
-2026-09-03 14:02:11  [high]  AWS Access Key ID  AKIA****ABCD
-  claude-code · session-9f2c.jsonl:214 · rf1-8a3e91  Rotate: https://.../access_keys
-```
+remember to scan again. `residoo mcp` lets Claude Code query findings
+conversationally. `residoo cred` removes the reason a credential gets
+pasted into chat in the first place: store it once in your OS keychain,
+run a command with it injected as an environment variable, never typed
+into the conversation at all — which also means a long session compacting
+away the exact value you pasted days ago can't force you to paste it
+again, since there's nothing to lose. `residoo guard` blocks an obviously
+sensitive file read before it happens (100% recall, 0% false positives on
+its own [scored 81-case corpus](bench/guard/RESULTS.md)). All four are
+covered in [docs/features.md](docs/features.md).
 
 > [!NOTE]
 > gitleaks and trufflehog scan **commits**. residoo scans the **conversation
@@ -61,45 +61,21 @@ watching 43 sources, 118 files · polling every 5s
 > trufflehog/betterleaks' verification postures, in
 > [docs/comparison.md](docs/comparison.md).
 
-Scan and watch tell you what already leaked. The most common way a NEW
-leak happens is pasting a key into the chat so Claude can use it, which
-then sits in that conversation's transcript forever, the exact thing scan
-exists to catch in the first place. `residoo cred` closes that loop: store
-a credential once in your OS keychain, then let Claude run a command with
-it injected as an environment variable, never pasted into the chat, never
-written into a script (see
-[Cred: run commands with injected credentials](#cred-run-commands-with-injected-credentials)):
-
-```
-$ residoo cred set aws-prod --env AWS_ACCESS_KEY_ID --env AWS_SECRET_ACCESS_KEY
-Value for AWS_ACCESS_KEY_ID (input hidden):
-Value for AWS_SECRET_ACCESS_KEY (input hidden):
-Stored credential "aws-prod" (2 env vars: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY).
-
-$ residoo cred run aws-prod -- aws s3 ls
-exit 0 (succeeded). stdout: 3 line(s), stderr: 0 line(s).
-Command output is never shown by design, only exit status and line counts.
-```
-
 ## Benchmark: measured, not claimed
 
-A reproducible benchmark against 8 real competing tools, on a synthetic-but-
-pattern-true corpus (72 Claude Code sessions, 45 planted credentials, zero
-real secrets), with live egress monitoring so "no network calls" is
-observed, not just documented. Re-run against every meaningful release,
-most recently v0.7.2:
+Scored #1 of 8 real competing tools on a reproducible, synthetic-but-
+pattern-true corpus, with live egress monitoring so "no network calls" is
+observed, not just documented:
 
 | | residoo | best of the rest |
 |---|---|---|
 | Distinct credentials found (all claimed classes) | **45/45 (100%)** | agentsweep 33/42 (79%) |
 | Precision (false positives) | **100%** (0 of 55 flags wrong) | gitleaks, whatileaked, trufflehog also 100% |
-| Network egress during the scan | **none-observed** | 3 of 8 tools attempt real outbound calls in their *default* mode (trufflehog: 50 connection attempts to github.com, slack.com, api.anthropic.com, gitlab.com, npmjs.org) |
+| Network egress during the scan | **none-observed** | 3 of 8 tools attempt real outbound calls in their *default* mode |
 
-No single blended score, on purpose: a blend would hide exactly the class-
-level differences (base64-wrapped, split-across-lines, JSON-nested) the
-benchmark exists to measure. Full per-class breakdown, fairness rules, and
-reproduction steps: [bench/](bench/). Self-run, pending independent
-reproduction; everything needed to rerun it ships in this repo.
+Published while losing rows, then fixed in public against the classes it
+was losing — full methodology, every dated rerun, and how to reproduce it
+yourself: [docs/benchmark.md](docs/benchmark.md).
 
 ## What it does
 
@@ -109,245 +85,34 @@ reproduction; everything needed to rerun it ships in this repo.
   [`src/patterns.js`](src/patterns.js).
 - Sees through two transcript-specific disguises: a credential dumped only
   as base64 on a line, or split across two adjacent streaming records, is
-  decoded/rejoined and rescanned, then reported as `base64-wrapped` or
-  `split across lines` so you know it was hidden. See
-  [`src/decode.js`](src/decode.js).
-- Pairs an AWS secret access key (no vendor prefix of its own) with a
-  nearby confirmed access key id and reports both at high confidence: the
-  *pairing* is the signal, not the shape alone. Ambiguous pairings are
-  reported as nothing rather than a guess. Same mechanism now also covers
-  PlanetScale and MongoDB Atlas Service Account credentials. See
-  [`src/pairing.js`](src/pairing.js).
-- Decodes a JWT's own `exp` claim locally (no network call, since the
-  claim is inside the signed payload) and reports "valid until" or
-  "expired" instead of just "last seen." See
-  [`src/jwtExpiry.js`](src/jwtExpiry.js).
+  decoded/rejoined and rescanned. See [`src/decode.js`](src/decode.js).
+- Pairs an AWS secret access key with a nearby confirmed access key id
+  (also PlanetScale and MongoDB Atlas Service Account credentials) and
+  reports both at high confidence; ambiguous pairings are reported as
+  nothing rather than a guess. See [`src/pairing.js`](src/pairing.js).
+- Decodes a JWT's own `exp` claim locally and reports "valid until" or
+  "expired" instead of just "last seen."
 - **`--verify`** (opt-in, makes a real network call): asks a credential's
-  own vendor whether it still authenticates, using the exact value found in
-  your transcript. 35 vendors today, off by default. See
-  [Verifying credentials are still live](#verifying-credentials-are-still-live)
-  below.
-- With `--include-noisy`, filters broad generic-secret rules by how
-  machine-random the matched value looks; never applied to the default
-  rules. See [`src/rarity.js`](src/rarity.js).
+  own vendor whether it still authenticates. 35 vendors today, off by
+  default. See [docs/architecture.md](docs/architecture.md#verifying-credentials-are-still-live).
 - Redacts everything in its own output, including `--json`: you get a
   shape and a first/last-4 preview, never the real value.
-- `--sarif` emits SARIF 2.1.0 for GitHub code scanning; `--json` carries
-  the full picture (findings, integrity, rotation) together.
-- `--seal --keychain` stores the vault key in the OS's own credential store
-  instead of a typed passphrase. See [Sealing](#sealing-what-it-finds).
+- `--sarif` emits SARIF 2.1.0 for GitHub code scanning.
+- `--seal --keychain` encrypts every transcript with a finding into a
+  local vault. See [docs/architecture.md](docs/architecture.md#sealing-what-it-finds).
 - 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 separately from real findings,
-  rather than hiding them or inflating the count.
 - Also scans agent **config files** and checks for **planted persistence**
-  (hooks, droppers, invisible Unicode); see the next section.
+  (hooks, droppers, invisible Unicode) — a different, better-documented
+  leak surface. See [docs/architecture.md](docs/architecture.md#beyond-transcripts-configs-and-planted-persistence).
 - Attaches a **rotation runbook** to every finding, plus a local
-  acknowledgement ledger. See [Rotation](#rotation-from-found-to-closed).
-- `--project <dir>` scans a repository checkout instead of the machine, for
-  CI and pre-commit. See [CI and pre-commit](#ci-and-pre-commit).
-- **`residoo watch`**: continuous scanning instead of one snapshot, alerting
-  the moment a new secret lands in a transcript. See
-  [Watch: continuous scanning](#watch-continuous-scanning) below.
-- **`residoo mcp`**: query findings and manage rotation from inside Claude
-  Code itself, over a hand-rolled MCP server. See
-  [MCP: query findings from inside Claude Code](#mcp-query-findings-from-inside-claude-code)
-  below.
-- **`residoo cred`**: store a live credential in the OS keychain and run
-  one allow-listed command with it injected as an environment variable,
-  never seen by the caller. See
-  [Cred: run commands with injected credentials](#cred-run-commands-with-injected-credentials)
-  below.
-
-## Beyond transcripts: configs and planted persistence
-
-Transcripts leak what your agent *saw*. Config files leak what it was
-*configured with*, and that's the better-measured problem: GitGuardian
-counted 24,008 secrets inside MCP config files on public GitHub (2,117
-still valid), and Lakera found live credentials inside
-`.claude/settings.local.json` shipped in ~30 published npm packages. So
-`residoo scan` also covers the home-level config files of Claude Code,
-Claude Desktop, Cursor, Gemini CLI, Codex, and Kiro, plus project-level
-Claude Code configs (`.mcp.json`, `.claude/settings*.json`) resolved from
-project roots the agent itself recorded, never by guessing directories.
-
-Those same files are where 2026's supply-chain campaigns (Mini Shai-Hulud,
-Miasma, the keyv/ChainDrop wave, TrapDoor) planted hooks, dropper scripts,
-and zero-width-Unicode prompt injection. Every scan now also runs
-**integrity checks** over those exact locations:
-
-- Every auto-executing hook is listed; only a published campaign IOC or
-  campaign-shaped behavior (piping a download into a shell, base64-decode-
-  then-execute) escalates to a warning.
-- Loose scripts in `.claude/` and known planted filenames are flagged by
-  name.
-- `CLAUDE.md`, `.cursorrules`, and `.cursor/rules/*` are checked for
-  zero-width Unicode.
-- `.vscode/tasks.json` is parsed for folder-open auto-run tasks.
-
-Read-only like everything else. `--no-integrity` skips it entirely. A
-config that can't be read is reported as unverified, never silently
-counted clean.
-
-## How it works
-
-```
-                    YOUR MACHINE · no network calls
-  ┌───────────────────────────────────────────────────────────────┐
-  │                                                               │
-  │   42 transcript sources           agent config files          │
-  │   ~/.claude, Cursor, Codex…       settings · MCP · memory     │
-  │   (--project <dir>: a repo checkout instead of the machine)   │
-  │            │                              │                   │
-  │            ├──────────────┬───────────────┤                   │
-  │            ▼              │               ▼                   │
-  │   stream + match          │        integrity checks           │
-  │   50 verified rules       │        hooks · droppers ·         │
-  │            │              │        zero-width unicode         │
-  │            ▼              ▼               │                   │
-  │        redacted report (first/last 4 chars only) ◀────────────┤
-  │            │                                                  │
-  │            ├─▶ rotation hints per finding · explain / ack     │
-  │            │   ledger: ~/.residoo/rotations.json              │
-  │            │                                                  │
-  │            ▼  --seal (only if you ask)                        │
-  │        AES-256-GCM vault · scrypt key · encrypted manifest    │
-  │            │                              │                   │
-  │            ▼  unseal --restore            ▼  --upload-cloudroam
-  │        SHA-256 verified copy          ciphertext only ┄┄┄┄┄┄┄┄┄▶
-  │                                                               │
-  └───────────────────────────────────────────────────────────────┘
-```
-
-The `--seal` and `--upload-cloudroam` legs never run unless you pass their
-flag. Nothing in the diagram ever modifies or deletes an existing file. The
-one exception, stated in the open: `residoo ack` writes residoo's own
-rotation ledger at `~/.residoo/rotations.json` (atomic, redacted, never a
-user file).
-
-## Sealing what it finds
-
-Finding a leaked key raises the obvious next question: *now what?*
-
-```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 so an 800MB transcript never touches memory whole. The vault's own
-manifest is encrypted too, so it doesn't advertise what's inside even by
-name. **Originals are never touched.** Once you've verified a restore works
-(`residoo unseal <vault> --restore 0001.sealed --out /tmp/check`, checked
-byte-identical via a recorded SHA-256), deleting the plaintext is your
-decision, made by you.
-
-Optionally, `--upload-cloudroam` (with `CLOUDROAM_API_KEY`, `--connector`,
-`--bucket`) copies the sealed vault to [CloudRoam](https://cloudroam.io) for
-durable, cross-cloud storage.
-
-> [!IMPORTANT]
-> `--upload-cloudroam` is the *only* feature in residoo that touches the
-> network to send your data anywhere. It never runs unless you pass the
-> flag, and only ciphertext is transmitted: the vault is sealed before any
-> upload code executes.
-
-## Verifying credentials are still live
-
-`--verify` asks a credential's own vendor whether it still authenticates,
-using the exact value found in your transcript. Off by default, one real
-network call per distinct credential.
-
-Three vendors need a paired id+secret: **AWS** (via `sts:get-caller-identity`,
-shelling out to your own `aws` CLI rather than reimplementing request
-signing), **PlanetScale**, and **MongoDB Atlas** (Service Account
-credentials only, the legacy Public/Private Key pair has no distinguishing
-prefix and isn't detected at all). The other 32 are a single credential
-each, one direct API call:
-
-Slack · OpenAI · Anthropic · GitHub · Hugging Face · Replicate ·
-DigitalOcean · Pinecone · SendGrid · Groq · xAI · OpenRouter · Stripe · npm ·
-Notion · GitLab · Supabase · ElevenLabs · CircleCI · Airtable · Cloudflare ·
-Heroku · Netlify · Linear · Telegram · Discord webhooks · Vercel · Cerebras ·
-Render · Neon · PostHog · Fly.io
-
-Every vendor clears the same two-stage bar before being wired up:
-independent research against that vendor's own current docs, then a
-separate, adversarial pass that tries to refute the first before it's
-trusted. A real, sourced reason (no free endpoint, needs context the
-credential doesn't carry, or a format not confirmed specifically enough to
-detect safely) is why some detected credential types aren't wired to
-`--verify` at all, not an oversight (Fly.io's `fm1a_`/`fm1r_`/`fm2_`
-"macaroon" tokens are the clearest example: real-machine testing produced a
-measured false-positive rate, so that family is detected nowhere in
-residoo). A verified-active credential is escalated to "rotate
-immediately"; a verified-invalid one is reported already dead, no action
-needed. See [`src/verify.js`](src/verify.js).
-
-## Rotation: from found to closed
-
-Detection without rotation is theater: 64% of secrets leaked publicly in
-2022 were still valid years later, 88% of re-verified leaked AWS keys still
-authenticated, and the median time to remediate a GitHub-leaked secret is
-94 days. Every finding in a residoo report comes with the way out:
-
-- **A rotation hint per finding**, from a guidance map covering all 50
-  detection rules. Where shown, a rotation URL was fetched and confirmed to
-  document revoking that exact credential type.
-- **`residoo explain <rule-id>`** prints the full runbook: where to revoke,
-  the steps, what revocation does. `residoo explain --list` shows the whole
-  catalogue.
-- **`residoo ack <fingerprint>`** records that you rotated a finding.
-  **`residoo dismiss <fingerprint>`** records that it was never a real
-  secret. Both live in `~/.residoo/rotations.json`, residoo's own ledger,
-  written atomically, redacted through the same pipeline as previews.
-- **"Recommended actions" leads the report**: how many *distinct* values
-  still need a decision, versus how many are already resolved (acked,
-  dismissed, or `--verify`-confirmed dead).
-- **The rotation list groups by credential type**, so the URL prints once
-  per type. Each value's own line shows its redacted preview, file, and
-  when it was last seen.
-- **Order matters, and the report says so.** The ChainDrop campaign (Aug
-  2026) shipped a token monitor that fires an attacker payload the moment a
-  stolen GitHub token is revoked. When a scan finds both integrity warnings
-  and leaked credentials, the report tells you to remove the planted
-  persistence first, rotate second.
-
-Acks and dismissals change what the report *says*, never what CI *does*:
-`--fail-on-find` fails on every finding, resolved or not, unless you pass
-`--allow-acked` (integrity warnings always fail either way).
-
-## CI and pre-commit
-
-`residoo scan --project <dir>` scans a repository checkout instead of the
-machine it runs on: committed transcripts, agent configs, root `.env`
-files, plus integrity checks anchored at that directory. It never touches
-the machine's home-level sources, so a clean CI run means the checkout is
-clean and claims nothing about anyone's laptop.
-
-As a GitHub Action (this repo doubles as a composite action):
-
-```yaml
-steps:
-  - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.7.2
-```
-
-As a pre-commit hook:
-
-```yaml
-repos:
-  - repo: https://github.com/dandovdub/residoo
-    rev: v0.7.2
-    hooks:
-      - id: residoo
-```
-
-Or with no integration at all:
-`npm install -g residoo && residoo scan --project . --fail-on-find`.
-Exit codes and exactly what project mode does and doesn't see are in
-[docs/ci.md](docs/ci.md).
+  acknowledgement ledger. See [docs/architecture.md](docs/architecture.md#rotation-from-found-to-closed).
+- `--project <dir>` scans a repository checkout instead of the machine,
+  for CI and pre-commit. See [docs/ci.md](docs/ci.md).
+- `residoo watch` / `residoo mcp` / `residoo cred` / `residoo guard`:
+  continuous scanning, conversational queries, credential injection
+  without pasting, and pre-read blocking. See [docs/features.md](docs/features.md).
 
 ## What it does not do
 
@@ -364,6 +129,13 @@ Exit codes and exactly what project mode does and doesn't see are in
   just encrypted a copy of.
 - **No telemetry, no analytics, no update-check ping.**
 
+Shape-based detection also can't tell a real secret from a realistic-
+looking example in a fetched web page. Three suppression layers narrow the
+gap, none catches every case, and all are re-includable with
+`--include-suppressed`. Treat every finding as a lead to check, not a
+certainty — true of every tool in this category, including the well-
+established ones.
+
 ## Install
 
 ```bash
@@ -385,9 +157,10 @@ brew install residoo
 The Homebrew formula installs the exact tarball published to npm (sha256
 verified): same bits, not a second build.
 
-Requires Node.js 18+ (22.5+ for the SQLite-backed sources listed below;
-residoo still runs fine without it). Zero runtime dependencies: check
-`package.json` rather than take that on faith.
+Requires Node.js 18+ (22.5+ for the SQLite-backed sources listed in
+[docs/sources.md](docs/sources.md); residoo still runs fine without it).
+Zero runtime dependencies: check `package.json` rather than take that on
+faith.
 
 ## Usage
 
@@ -406,7 +179,7 @@ residoo scan [options]
   --no-integrity          skip the integrity checks
   --no-color              disable ANSI colour
   --verify                ask each credential's own vendor if it still authenticates
-                          (real network call; see "Verifying credentials are still live")
+                          (real network call; see docs/architecture.md)
 
   --seal                  encrypt every transcript with findings into a local vault
   --vault-dir <dir>       vault location (default ./residoo-vault-<stamp>)
@@ -420,216 +193,18 @@ residoo ack <fingerprint> [--note <text>]           mark one finding rotated
 residoo unseal <vault-dir>                          list a vault's contents
 residoo unseal <vault-dir> --restore <n> --out <p>  restore one file, hash-verified
 
-residoo watch [options]
-
-  --interval <seconds>    how often to check for new content (default 5, minimum 1)
-  --json                  NDJSON events on stdout, one line per finding/re-exposure
-  --verify                same opt-in vendor check as scan --verify, applied to
-                          each newly found credential once
-  --include-noisy, --include-suppressed, --no-color   same meaning as scan
+residoo watch / mcp / cred / guard                  see docs/features.md
 ```
 
 The vault passphrase comes from `RESIDOO_PASSPHRASE` or a hidden interactive
 prompt. There is no recovery if you lose it, so pick one you keep.
 
-## Watch: continuous scanning
-
-`residoo scan` is a snapshot. `residoo watch` is the same engine run
-continuously: it polls every source `scan` already covers, and the moment a
-new secret lands in a transcript, prints an alert with the redacted value,
-the rule, the file, and the same rotation runbook a scan finding carries,
-instead of waiting for you to remember to run `scan` again.
-
-```
-$ residoo watch
-watching 43 sources, 118 files (61 tailed, 57 rescanned on change)
-polling every 5s; fs.watch is not used, every alert comes from polling
-
-2026-09-03 14:02:11  [high]  AWS Access Key ID  AKIA****ABCD
-  claude-code · session-9f2c.jsonl:214 · rf1-8a3e91  Rotate: https://.../access_keys
-```
-
-It is watch-from-**now**: run `residoo scan` first for anything already on
-disk, since a fresh `residoo watch` baselines whatever it finds on its first
-sweep silently and only alerts on content written after it starts. A finding
-already acknowledged or dismissed (`residoo ack` / `residoo dismiss`) stays
-suppressed, checked against the same `~/.residoo/rotations.json` ledger, and
-a ledger change made mid-watch takes effect within one poll interval, no
-restart needed. A findings-free sweep prints nothing at all, including to
-its own watched Claude Code session, by design: no other tool in this
-project's own benchmark ([`bench/`](bench/)) has a continuous mode at all,
-verified directly against each one's own `--help` output rather than
-assumed; see [docs/comparison.md](docs/comparison.md) for how the one
-adjacent thing, GitGuardian's `ggshield` AI hook, works differently.
-
-## MCP: query findings from inside Claude Code
-
-`residoo mcp` runs residoo as an MCP server over stdio, so Claude Code can
-query findings and manage the rotation ledger conversationally instead of
-you running the CLI in a terminal:
-
-```bash
-claude mcp add residoo -- residoo mcp
-```
-
-or add it directly to `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "residoo": { "type": "stdio", "command": "residoo", "args": ["mcp"] }
-  }
-}
-```
-
-Five read-only tools, mirroring the CLI exactly: `residoo_scan` (a fresh
-scan, merged with rotation status), `residoo_check` (only what's new
-since the last check in this conversation, backed by the same engine as
-`watch`), `residoo_explain` (a rule's rotation runbook), and
-`residoo_ack` / `residoo_dismiss` (append to the local ledger). Every
-value returned is redacted the same way the CLI's own output is; nothing
-here makes a network call or touches the transcript files themselves.
-Like the rest of residoo, this is hand-rolled against the MCP spec
-directly, not built on `@modelcontextprotocol/sdk`: zero runtime
-dependencies stays true here too. A sixth, opt-in tool exists for
-injected-credential execution, covered below.
-
-## Cred: run commands with injected credentials
-
-The usual way an AI coding agent ends up able to use a real credential is
-you pasting it into the chat, which puts it in that conversation's
-transcript forever, indistinguishable from any other leak `residoo scan`
-finds. `residoo cred` is the alternative: store the credential once in
-your OS keychain, then let Claude run one allow-listed command with it
-injected as environment variables. Claude never sees the raw value,
-before, during, or after, and it's never written into a script either.
-
-```bash
-residoo cred set aws-prod --env AWS_ACCESS_KEY_ID --env AWS_SECRET_ACCESS_KEY
-# hidden-typed input, once per --env flag; interactive TTY only, no
-# scripted entry, since a live credential is more sensitive than a vault
-# passphrase and should never be typeable into a script or env var.
-
-RESIDOO_CRED_ALLOWED_COMMANDS="aws=/usr/local/bin/aws" residoo mcp
-# now residoo_run_with_cred exists as an MCP tool; it does not exist at
-# all (won't appear in the tool list) until this is set.
-
-residoo cred run aws-prod -- aws s3 ls
-# same operation from a terminal, for testing without an MCP client.
-```
-
-**Why this is safer than it looks, stated precisely, not just asserted:**
-
-- `RESIDOO_CRED_ALLOWED_COMMANDS` (`name=/absolute/path,...`) is an
-  environment variable the operator sets outside any conversation, read
-  fresh on every single invocation. Empty or unset means **nothing may
-  run, by design**: this is the actual, sole security boundary.
-- The `command` a caller (human or model) supplies is used **only as a
-  lookup key** into that map, never as a path, never resolved via
-  `PATH`. This was not always true: a first draft matched by binary
-  *name* alone (checked fresh every call, but only verifying the name the
-  caller claimed, not the binary that actually ran), and an adversarial
-  review found two concrete ways around that: a caller-supplied path
-  smuggled straight past the check, and a same-named malicious binary
-  planted earlier on the server process's own inherited `PATH`. Both are
-  closed structurally now: `command` cannot cause any file other than the
-  operator-pinned absolute path to execute, full stop.
-- Arguments are always a structured list, never a shell string, so no
-  shell metacharacter ever gets interpreted.
-- The executed command's own stdout/stderr content is **never returned**,
-  only exit status and line counts, because that output is itself a
-  channel the injected secret could leak through in ways no redaction
-  pass can guarantee to catch (an echoed variable, a stack trace).
-- A hung command is killed after 30 seconds, not configurable by the
-  caller (letting a model choose its own timeout has no legitimate use
-  and only helps an attacker keep a process alive longer).
-- One line goes to `residoo mcp`'s own **stderr** per credential use
-  (timestamp, credential name, command, exit code, never the value or
-  the arguments). This is **not durable by default**: redirect the MCP
-  server's stderr at launch (`residoo mcp 2>> ~/.residoo-cred-audit.log`,
-  or your MCP client's equivalent) if you want a persistent trail.
-
-**Only ever allow-list narrow, single-purpose CLIs**, never a tool that
-can itself run arbitrary third-party code as part of normal operation
-(`npm`, `npx`, `pip`, `make`, `cargo`, any build tool). Watch out even for
-a seemingly narrow tool with its own plugin system: an allow-listed `gh`
-still receives the injected credential as an inherited environment
-variable in whatever `gh extension exec` or `gh alias` runs, which is
-untrusted the moment it's a third-party extension. This is a residual
-risk allow-listing alone doesn't remove, so narrow the tools you allow-list
-accordingly, and prefer credentials scoped as tightly as the vendor
-allows.
-
-Storage is macOS (`security`) or Linux (`secret-tool`) only, matching
-`--seal --keychain`'s own existing platform support; Windows is refused
-with a clear message rather than half-built. There is no `residoo cred
-list` in v1: you need to already know the name you set.
-
 ## Sources supported today
 
-43 sources: 42 transcript stores plus the agent-config source above, in two
-honestly-distinct tiers. `--project` adds one more, opt-in source that
-scans a checkout instead of the machine.
-
-**Real-install-verified**: run against an actual, populated installation
-and confirmed to find real content: **Claude Code**
-(`~/.claude/projects/**/*.jsonl`) and **agent config files** for its
-Claude-family paths.
-
-**Multi-source-corroborated-but-unverified**: backed by 2+ independent,
-credible sources but not checked against a real install on any machine this
-project was built on. Still built to fail loudly rather than silently
-report "all clear":
-
-Cursor, Codex CLI, OpenCode, Aider, Cline, Roo Code, Kilo Code, Windsurf,
-PearAI, Trae, Void, Gemini CLI, Qwen Code, Continue, Open Interpreter,
-Goose, GitHub Copilot Chat/CLI, `llm`, Codebuff, Mentat, Hermes, OpenClaw,
-Warp, Crush, Grok Build, Kiro CLI/IDE, Zed, JetBrains Junie/AI Assistant,
-Sourcegraph Cody, Amazon Q Developer, Qodo Gen, OpenHands, Factory Droid
-CLI, Devin CLI, Pi, Google Antigravity, Kimi Code, and `fx`.
-
-A few are SQLite-backed (Cursor, Crush, Cody, Devin CLI, Hermes, Kiro CLI,
-`llm`, Trae, Void, Warp, Zed) and need Node.js 22.5+ for the built-in
-`node:sqlite` module. On an older Node, each reports as detected-but-not-
-scanned rather than silently dropping.
-
-**Investigated and deliberately not included:** Plandex (client-server,
-nothing local to scan), CodeGPT and Augment Code (account/cloud-based, no
-local transcript file), Replit Agent (cloud-only). Tabby, Tabnine,
-Zencoder, Tongyi Lingma, and Berd didn't clear the 2-independent-source bar
-in the time available. A verified adapter for any of these is a welcome PR.
-
-See [`src/sources/index.js`](src/sources/index.js) for the full list, and
-each source file's own header for exactly what was and wasn't checked.
-
-## Adding a source
-
-A source is a small object with four methods: `id()`, `label()`,
-`available()`, `files()`, `readLines(file)`.
-[`src/sources/claude-code.js`](src/sources/claude-code.js) is the reference
-implementation: copy it, point it at your tool's real local storage path,
-open a PR. Two contracts worth getting right:
-
-- **`files()`** yields `{ file, mtimeMs, sizeBytes, broken }`. Set
-  `broken: true` for an entry that looked scannable but wasn't (a dangling
-  symlink); don't just skip past it silently.
-- **`readLines(file)`** is `async`, returning `{ lines, status, bytesRead }`
-  with `status` one of `"complete"`, `"partial"`, `"too-large"`, `"failed"`.
-  Whatever's in `lines` for a non-`"complete"` status still gets scanned.
-
-Please verify the path actually exists and holds real content before
-submitting.
-
-## 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 documentation your agent read back to
-you. Three suppression layers narrow the gap (known vendor-documented
-example values, placeholder bodies built from one repeated character, and
-placeholder-looking surrounding context), but none catches every case, and
-all are re-includable with `--include-suppressed`. 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.
+43 sources, real-install-verified for Claude Code and its config family,
+multi-source-corroborated for the rest (Cursor, Codex CLI, Cline, Windsurf,
+Gemini CLI, Copilot, and 30+ more). Full list, what "corroborated" means,
+and how to add one: [docs/sources.md](docs/sources.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "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)",

package/src/cli.js

@@ -13,6 +13,7 @@ const {
 const { startWatch, isTailable } = require("./watch");
 const { startMcpServer } = require("./mcp");
 const { buildTools } = require("./mcpTools");
+const { runGuard: runGuardEngine } = require("./guard");
 
 /**
  * A source is unavailable for the ordinary reason (not installed — nothing
@@ -162,6 +163,10 @@ MCP:
                           with "claude mcp add residoo -- residoo mcp".
                           Zero runtime dependencies: the protocol is hand-
                           rolled, not the official SDK.
+  A 7th tool, residoo_verify_finding, asks a credential's own vendor, live,
+  whether it's still active -- the one MCP tool that makes a real network
+  call, so it does not exist unless RESIDOO_MCP_ALLOW_VERIFY=1 is set in the
+  server's own environment. See the README for the full scope and limits.
 
 Cred:
   residoo cred set <name> --env <ENV_VAR_NAME> [--env <ENV_VAR_NAME_2> ...]
@@ -191,6 +196,26 @@ Cred:
   residoo mcp exposes the same operation as the residoo_run_with_cred
   tool, present only when RESIDOO_CRED_ALLOWED_COMMANDS is configured.
 
+Guard:
+  residoo guard             a Claude Code PreToolUse hook that blocks an
+                          obviously-sensitive file read (.env, id_rsa,
+                          .aws/credentials, and similar) before it can be
+                          written to the session transcript at all --
+                          prevention, not just detection. Reads one hook
+                          payload from stdin, writes a deny decision to
+                          stdout only when it matches; never blocks on
+                          anything it doesn't recognize. This is narrower
+                          than it sounds: Claude Code's hooks API can see a
+                          proposed Bash command or Read path before it
+                          runs, but never the command's OUTPUT, so this
+                          cannot catch a secret typed into a prompt or one
+                          arriving through an unrelated command's output --
+                          scan/watch/mcp remain the real safety net. Add to
+                          .claude/settings.json:
+                            {"hooks":{"PreToolUse":[{"matcher":"Bash|Read",
+                            "hooks":[{"type":"command",
+                            "command":"residoo guard"}]}]}}
+
 Rotation:
   residoo explain <rule-id>     full rotation runbook for one detection rule
                                 (where to revoke, steps, what revocation does)
@@ -806,6 +831,7 @@ async function main(argv) {
   if (cmd === "watch") return runWatch(args);
   if (cmd === "mcp") return runMcp(args);
   if (cmd === "cred") return runCred(args);
+  if (cmd === "guard") return runGuardEngine();
   if (cmd !== "scan") {
     process.stderr.write(`Unknown command "${cmd}". Try "residoo --help".\n`);
     return 2;

package/src/guard.js

@@ -0,0 +1,162 @@
+"use strict";
+
+/**
+ * `residoo guard`: a Claude Code PreToolUse hook that blocks an obviously-
+ * sensitive file read before it happens, instead of finding the leak in the
+ * transcript afterward.
+ *
+ * Scope, stated plainly because it is much narrower than "prevent secrets
+ * from leaking": Claude Code's hooks API gives a PreToolUse hook the
+ * PROPOSED tool input (a Bash command string, a Read file_path) before the
+ * tool runs, and lets it deny the call outright -- but it never sees the
+ * tool's OUTPUT, and by the time a PostToolUse hook fires, that output is
+ * already committed to the transcript and can no longer be redacted. There
+ * is no documented hook mechanism for "let the read happen, but strip the
+ * secret out of what the model sees." So this can only block INPUT that
+ * matches a known-sensitive file path pattern (.env, id_rsa, .aws/credentials,
+ * and similar) -- it cannot catch a secret typed directly into a prompt, a
+ * secret arriving in the output of an otherwise-unremarkable command
+ * (curl, a build log), or any file path this pattern list does not name.
+ * `residoo scan`/`watch`/`mcp` remain the actual safety net; this is a
+ * narrower, best-effort tripwire on top, not a replacement for them.
+ *
+ * Fails safe in the direction of NOT blocking on any uncertainty: a
+ * malformed hook payload, an unrecognized tool name, or a parse error all
+ * fall through to "allow" (no stdout, exit 0) rather than denying a call
+ * this module does not understand. The one thing this module must never do
+ * is silently hang or crash the agent's turn over a tool call that was
+ * always going to be fine.
+ */
+
+// A matched path fragment must be preceded by a path separator or the start
+// of the string, and followed by either the end of the string (the common
+// case for Read's file_path) or a shell metacharacter/whitespace (the case
+// for a Bash command string, where the path is one argument among several,
+// e.g. "cat .env && echo done"). Applying this uniformly, rather than a
+// bespoke `$`-anchor per pattern, is what makes every entry below work
+// identically for both tool_input shapes.
+const BOUNDARY = "(?:$|[\\s'\"`;|&)<>])";
+// Left boundary: start of string, a path separator (mid-path, e.g.
+// "/foo/.env"), OR whitespace/a shell metacharacter (the path is one
+// argument in a longer command, e.g. "cat .env && echo done" -- ".env" is
+// preceded by a space, not a separator). Deliberately NOT a hyphen: an
+// earlier version added one (to catch "gcp-service-account-prod.json",
+// see the dedicated pattern below instead) and it broke the public.pem/
+// public.key exclusions below -- a negative lookahead only guards its own
+// anchor position, and a hyphen boundary let the regex engine start
+// matching again from a LATER position inside the same filename (e.g.
+// right after "public-" in "public-key.pem"), silently walking around the
+// exclusion. Kept narrow and per-pattern instead of widening this shared
+// primitive for one case.
+const SEP = "(?:^|[\\s'\"`;|&(<>\\\\/])";
+const pat = (body) => new RegExp(SEP + body + BOUNDARY, "i");
+
+// Suffixes that make a .env-shaped path a committed, secret-free template
+// rather than the real thing: never planted with live credentials by
+// convention, and reading one is completely routine (checking which vars
+// a project needs). Found by testing this guard against realistic dev
+// commands, not assumed: cat .env.example was blocked before this existed.
+const ENV_SAFE_SUFFIX = "example|sample|template|dist|default|schema";
+
+const SENSITIVE_PATH_PATTERNS = [
+  // dotenv files, including staged/numbered variants (.env.local, .env.1),
+  // but not a known-safe template suffix (see ENV_SAFE_SUFFIX above).
+  { re: pat(`\\.env(?:\\.(?!(?:${ENV_SAFE_SUFFIX})(?:$|[\\s'"\`;|&)<>.]))[\\w.-]+)?`), label: "a .env file" },
+  // SSH private keys: the conventional default names. Deliberately NOT
+  // *.pub -- a public key is, by definition, meant to be shared (it's
+  // what you paste into GitHub's own SSH keys page); blocking its read
+  // protects nothing and was a real false positive found the same way.
+  { re: pat("id_(?:rsa|dsa|ecdsa|ed25519)"), label: "an SSH private key" },
+  // The whole .ssh directory, EXCEPT its own *.pub files and known_hosts
+  // (host key fingerprints, not credentials -- reading it can't expose
+  // anything) -- same public-key/not-actually-sensitive principle as the
+  // id_/*.pem/*.key exclusions above, applied to a directory match.
+  { re: new RegExp(SEP + "\\.ssh[\\\\/](?!(?:[\\w.-]+\\.pub|known_hosts(?:\\.old)?)(?:$|[\\s'\"`;|&)<>]))", "i"), label: "the SSH directory" },
+  // *.pem/*.key, except a filename that itself says "public": a real
+  // private key is never conventionally named that way, and "public.pem"/
+  // "public-key.pem" naming a non-sensitive cert is common enough that
+  // blocking it is pure noise, not protection.
+  { re: pat("(?!public[-_.])[\\w.-]+\\.pem"), label: "a .pem key file" },
+  { re: pat("(?!public[-_.])[\\w.-]+\\.key"), label: "a .key file" },
+  // cloud / vendor credential files with a fixed, well-known name
+  { re: pat("\\.aws[\\\\/](?:credentials|config)"), label: "the AWS credentials file" },
+  { re: pat("\\.netrc"), label: "the .netrc file" },
+  { re: pat("\\.npmrc"), label: "the .npmrc file (may hold a publish token)" },
+  { re: pat("\\.git-credentials"), label: "the git-credentials file" },
+  { re: pat("\\.docker[\\\\/]config\\.json"), label: "the Docker config (may hold registry auth)" },
+  { re: pat("\\.kube[\\\\/]config"), label: "the kubeconfig file" },
+  { re: pat("application_default_credentials\\.json"), label: "gcloud application-default credentials" },
+  { re: pat("credentials\\.json"), label: "a credentials.json file" },
+  // No SEP prefix here, on purpose: a real, common naming convention
+  // prefixes this with a project/company name and a hyphen (e.g.
+  // "gcp-service-account-prod.json"), which the standard SEP boundary
+  // (start/whitespace/separator, deliberately not a hyphen -- see SEP's
+  // own comment) would miss entirely. "service[_-]?account" is specific
+  // enough as a token that not requiring a left boundary here is a safe,
+  // narrow exception rather than a reason to widen SEP itself.
+  { re: new RegExp("service[_-]?account[\\w.-]*\\.json" + BOUNDARY, "i"), label: "a GCP service-account key file" },
+  { re: pat("secrets?\\.(?:json|ya?ml)"), label: "a secrets file" },
+];
+
+/** True if `text` (a file path, or a whole shell command string) contains a recognizable sensitive-path match. Returns the matched label or null. */
+function matchSensitivePath(text) {
+  if (typeof text !== "string" || !text) return null;
+  for (const { re, label } of SENSITIVE_PATH_PATTERNS) {
+    if (re.test(text)) return label;
+  }
+  return null;
+}
+
+const GUARDED_TOOL_NAMES = new Set(["Bash", "Read"]);
+
+/**
+ * Pure decision function: given a PreToolUse hook payload's tool_name and
+ * tool_input, decide whether to block. No I/O, fully unit-testable.
+ */
+function evaluateToolInput(toolName, toolInput) {
+  if (!GUARDED_TOOL_NAMES.has(toolName) || !toolInput || typeof toolInput !== "object") {
+    return { block: false, reason: null };
+  }
+  const candidate = toolName === "Bash" ? toolInput.command : toolInput.file_path;
+  const label = matchSensitivePath(candidate);
+  if (!label) return { block: false, reason: null };
+  return {
+    block: true,
+    reason: `residoo guard: this looks like a read of ${label}. Blocked before it could be written to the session transcript. ` +
+      `If this is intentional and safe, ask the human to read it themselves, or disable this hook in .claude/settings.json.`,
+  };
+}
+
+/**
+ * Reads one PreToolUse hook payload from `input` (default stdin), decides,
+ * and writes the hook's own JSON response protocol to `output` (default
+ * stdout) -- exit code is the caller's job (bin/residoo.js), this returns
+ * the intended process exit code instead of calling process.exit itself,
+ * matching every other run* function in cli.js.
+ */
+async function runGuard({ input = process.stdin, output = process.stdout } = {}) {
+  const chunks = [];
+  for await (const chunk of input) chunks.push(chunk);
+  const raw = Buffer.concat(chunks.map((c) => (Buffer.isBuffer(c) ? c : Buffer.from(c)))).toString("utf-8");
+
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return 0; // malformed payload: fail open, never block on something we can't parse
+  }
+
+  const decision = evaluateToolInput(payload.tool_name, payload.tool_input);
+  if (!decision.block) return 0;
+
+  output.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: decision.reason,
+    },
+  }) + "\n");
+  return 0;
+}
+
+module.exports = { evaluateToolInput, matchSensitivePath, runGuard, SENSITIVE_PATH_PATTERNS };

package/src/mcpTools.js

@@ -1,7 +1,7 @@
 "use strict";
 
 const path = require("path");
-const { scan } = require("./scan");
+const { scan, VERIFIABLE_RULE_IDS } = require("./scan");
 const {
   ROTATION_GUIDANCE, guidanceFor, loadAcks, loadDismissed,
   ackFinding, dismissFinding, renderRotation,
@@ -20,13 +20,17 @@ const keychain = require("./keychain");
  * human-facing presenters), and this file's whole job is to never let a
  * byte reach stdout except through mcp.js's own `send()`.
  *
- * `verify` is not exposed as a parameter on ANY tool here, on purpose: a
- * human typing `--verify` at a terminal is a deliberate, legible act; an
- * autonomous model choosing a network-triggering parameter mid-
- * conversation is a different trust boundary, and a generic tool-approval
- * prompt may not surface that a given call also makes a live vendor API
- * request with a real secret. Every `scan()`/`sweepOnce()` call below
- * hardcodes `verify: false`.
+ * `verify` is not exposed as a parameter on residoo_scan/residoo_check, on
+ * purpose: a human typing `--verify` at a terminal is a deliberate, legible
+ * act; an autonomous model choosing a network-triggering parameter
+ * mid-conversation is a different trust boundary, and a generic
+ * tool-approval prompt may not surface that a given call also makes a live
+ * vendor API request with a real secret. Both hardcode `verify: false`. Live
+ * verification instead gets its own narrowly-scoped tool, residoo_verify_finding
+ * (one credential per call, gated behind RESIDOO_MCP_ALLOW_VERIFY so it does
+ * not exist at all unless an operator deliberately opts in) -- see its own
+ * comment below for why that is a materially different, honestly-labeled
+ * trust boundary rather than the same one wearing a different name.
  */
 
 const FINGERPRINT_PATTERN = /^rf1-[0-9a-f]{32}$/;
@@ -283,6 +287,62 @@ function buildTools({ sources }) {
     });
   }
 
+  async function handleVerifyFinding(args) {
+    const errs = rejectUnknownKeys(args, new Set(["fingerprint"]));
+    if (typeof args.fingerprint !== "string") {
+      errs.push("fingerprint is required and must be a string");
+    } else if (!FINGERPRINT_PATTERN.test(args.fingerprint)) {
+      errs.push("fingerprint must match ^rf1-[0-9a-f]{32}$ -- copy it verbatim from a prior residoo_scan/residoo_check result, never construct or guess one");
+    }
+    if (errs.length) return errorResult(`Invalid arguments: ${errs.join("; ")}`);
+
+    const findEntry = async () => {
+      const result = await scan({ sources, includeNoisy: true, includeSuppressed: true, verify: false, noColor: true });
+      const rotation = renderRotation(result.findings, loadAcks(), loadDismissed());
+      return rotation.entries.find((e) => e.fingerprint === args.fingerprint) || null;
+    };
+
+    const before = await findEntry();
+    if (!before) {
+      return textResult({
+        fingerprint: args.fingerprint, found: false, verifiable: null, verified: null,
+        summary: "No finding with this fingerprint is currently on disk. It may have been resolved, the source file may have changed since it was last seen, or you may need to call residoo_scan first to see current fingerprints.",
+      });
+    }
+    if (!VERIFIABLE_RULE_IDS.has(before.ruleId)) {
+      return textResult({
+        fingerprint: args.fingerprint, found: true, ruleId: before.ruleId, verifiable: false, verified: null,
+        summary: `residoo cannot live-verify a ${before.ruleId} credential yet. Paired credentials (AWS, PlanetScale, MongoDB Atlas) and credential types with no vendor whoami-style endpoint (JWTs, private keys, bearer tokens of unknown origin, connection strings) are not supported by this tool. Run "residoo scan --project <dir> --verify" from a terminal for AWS/PlanetScale/MongoDB Atlas pairs.`,
+      });
+    }
+
+    // The actual network call: scoped so ONLY this one fingerprint's
+    // credential is ever queued for verification inside scan() (see
+    // verifyOnlyFingerprint in src/scan.js), regardless of how many other
+    // verifiable credentials exist on this machine. This is the whole reason
+    // this tool takes one fingerprint and not a list.
+    const result = await scan({ sources, includeNoisy: true, includeSuppressed: true, verify: true, verifyOnlyFingerprint: args.fingerprint, noColor: true });
+    const rotation = renderRotation(result.findings, loadAcks(), loadDismissed());
+    const after = rotation.entries.find((e) => e.fingerprint === args.fingerprint);
+    const checkedAt = new Date().toISOString();
+    if (!after || after.verified == null) {
+      return textResult({
+        fingerprint: args.fingerprint, found: true, ruleId: before.ruleId, verifiable: true, verified: "unknown",
+        checkedAt, summary: "The vendor check could not be completed (network error, timeout, or unexpected response). This does not mean the credential is inactive -- treat it as unverified, not as safe.",
+      });
+    }
+    const verified = after.verified === "active" ? "active" : after.verified === "invalid" ? "invalid" : "unknown";
+    const summary = verified === "active"
+      ? `ACTIVE: this is a real, working credential. Rotate it. Checked ${checkedAt}.`
+      : verified === "invalid"
+        ? `Inactive: the vendor rejected it. Checked ${checkedAt}.`
+        : `Could not verify${after.verifiedDetail ? `: ${after.verifiedDetail}` : ""}. Treat as unverified, not as safe. Checked ${checkedAt}.`;
+    return textResult({
+      fingerprint: args.fingerprint, found: true, ruleId: before.ruleId, verifiable: true, verified,
+      verifiedDetail: after.verifiedDetail || null, checkedAt, summary,
+    });
+  }
+
   const tools = new Map();
   tools.set("residoo_scan", {
     name: "residoo_scan",
@@ -391,6 +451,39 @@ function buildTools({ sources }) {
     });
   }
 
+  // Genuinely different from residoo_scan/residoo_check even though it also
+  // only reads local disk first: its SECOND step makes a real outbound
+  // network request to the credential's own vendor, using the actual secret
+  // value, to ask whether it still works. Nothing else in this file ever
+  // leaves the machine. Dynamically OMITTED from this Map (same pattern as
+  // residoo_run_with_cred above) unless RESIDOO_MCP_ALLOW_VERIFY is set to
+  // "1" or "true" -- an operator must deliberately opt in, outside the
+  // conversation, before this tool exists at all, so a default `residoo mcp`
+  // install stays true to "zero network calls" without qualification. This
+  // is a STRICTER gate than residoo_scan/residoo_check need, because giving
+  // this its own clearly-named, clearly-described tool (rather than a
+  // boolean flag buried on residoo_scan) only solves the discovery/approval-
+  // prompt-legibility problem the original MCP design flagged -- it does not
+  // by itself decide whether an autonomous model should ever be allowed to
+  // trigger a real vendor API call with a real secret. That is the
+  // operator's call, made once, outside any conversation.
+  const mcpAllowVerify = process.env.RESIDOO_MCP_ALLOW_VERIFY === "1" || process.env.RESIDOO_MCP_ALLOW_VERIFY === "true";
+  if (mcpAllowVerify) {
+    tools.set("residoo_verify_finding", {
+      name: "residoo_verify_finding",
+      description: "Ask ONE credential's own vendor, live, whether it is still active -- unlike every other residoo tool, this makes a real outbound network request (e.g. to Slack's auth.test, GitHub's user endpoint) using the actual secret value found on disk. The raw value itself is still never returned to you, only the vendor's answer: active (a real, working credential -- rotate it), invalid (the vendor already rejected it), or unknown (the check failed or timed out -- treat this the same as active, not as reassurance). fingerprint MUST be copied verbatim from a fingerprint field returned by a prior residoo_scan or residoo_check call in this conversation -- never construct or guess one. Only single-token credential types are supported (Slack, GitHub, OpenAI, Anthropic, Stripe, and similar) -- paired credentials (AWS access key + secret, PlanetScale, MongoDB Atlas) return verifiable:false; use `residoo scan --verify` from a terminal for those. This tool only exists because an operator deliberately enabled it outside this conversation (RESIDOO_MCP_ALLOW_VERIFY) -- never ask a human to paste a raw credential value to use it; it already reads the value residoo found on disk.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          fingerprint: { type: "string", pattern: "^rf1-[0-9a-f]{32}$", description: "Exact fingerprint string from a prior scan/check finding. Never invent one." },
+        },
+        required: ["fingerprint"],
+        additionalProperties: false,
+      },
+      handler: handleVerifyFinding,
+    });
+  }
+
   return tools;
 }
 

package/src/scan.js

@@ -18,6 +18,7 @@ const {
   verifyFlyioBearerToken, verifyMongoDbAtlasCredential, verifyNeonKey, verifyPostHogKey,
 } = require("./verify");
 const { c, makePaint } = require("./color");
+const { fingerprintFinding } = require("./rotation");
 
 // PlanetScale's id half: 12 lowercase alphanumeric characters, no prefix —
 // confirmed via planetscale.com/docs/api/reference/service-tokens. Searched
@@ -265,7 +266,7 @@ function localTimestamp(d) {
  * absolute path can itself carry a username or a project name the rest of
  * this report is careful never to print.
  */
-async function scan({ sources, includeNoisy = false, includeSuppressed = false, onProgress = null, verify = false, onBeforeVerify = null, noColor = false } = {}) {
+async function scan({ sources, includeNoisy = false, includeSuppressed = false, onProgress = null, verify = false, verifyOnlyFingerprint = null, onBeforeVerify = null, noColor = false } = {}) {
   const rules = includeNoisy ? PATTERNS.concat(NOISY_PATTERNS) : PATTERNS;
   // The decode pass (see decode.js) only applies high-confidence, vendor-
   // prefixed rules to decoded bytes: random binary that decodes to printable
@@ -481,7 +482,18 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
           // re-echoed across several lines gets several finding objects, and
           // the eventual result is applied to every one of them, not only
           // the first.
-          if (verify && secretFinding && rawPairedSecret) {
+          //
+          // verifyOnlyFingerprint (residoo_verify_finding, src/mcpTools.js):
+          // when set, this scan still WALKS every file as normal, but only
+          // the one finding whose fingerprint matches is ever queued for a
+          // real network call -- every other eligible credential on the
+          // machine is silently skipped, matching that MCP tool's own
+          // documented "one credential per call" promise exactly. Computed
+          // from primaryFinding, not secretFinding/idFinding, because the
+          // fingerprint a caller holds always names the record they saw in
+          // a prior scan/check result, which is always the primary one.
+          const matchesTarget = !verifyOnlyFingerprint || fingerprintFinding(primaryFinding) === verifyOnlyFingerprint;
+          if (verify && matchesTarget && secretFinding && rawPairedSecret) {
             if (!pendingAwsVerifications.has(m[0]) && pendingAwsVerifications.size < MAX_VERIFICATIONS_PER_VENDOR) {
               pendingAwsVerifications.set(m[0], { secretValue: rawPairedSecret, refs: [] });
             }
@@ -490,7 +502,7 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
           }
           // --verify, PlanetScale: same dedup-by-anchor-value shape as AWS
           // above, keyed by the secret (the confirmed anchor) this time.
-          if (verify && planetScaleIdFinding && rawPlanetScaleId) {
+          if (verify && matchesTarget && planetScaleIdFinding && rawPlanetScaleId) {
             if (!pendingPlanetScaleVerifications.has(m[0]) && pendingPlanetScaleVerifications.size < MAX_VERIFICATIONS_PER_VENDOR) {
               pendingPlanetScaleVerifications.set(m[0], { idValue: rawPlanetScaleId, refs: [] });
             }
@@ -499,7 +511,7 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
           }
           // --verify, MongoDB Atlas: same dedup-by-anchor-value shape as
           // AWS/PlanetScale above, keyed by the secret this time.
-          if (verify && mongoDbIdFinding && rawMongoDbId) {
+          if (verify && matchesTarget && mongoDbIdFinding && rawMongoDbId) {
             if (!pendingMongoDbAtlasVerifications.has(m[0]) && pendingMongoDbAtlasVerifications.size < MAX_VERIFICATIONS_PER_VENDOR) {
               pendingMongoDbAtlasVerifications.set(m[0], { idValue: rawMongoDbId, refs: [] });
             }
@@ -512,7 +524,7 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
           // dedup-by-value / accumulate-all-refs shape as the AWS map above,
           // just one level deeper (keyed by rule id too, since several
           // vendors share this path).
-          if (verify && !suppressedReason && SIMPLE_VERIFY_FNS[rule.id]) {
+          if (verify && matchesTarget && !suppressedReason && SIMPLE_VERIFY_FNS[rule.id]) {
             let byValue = pendingSimpleVerifications.get(rule.id);
             if (!byValue) {
               byValue = new Map();
@@ -879,4 +891,13 @@ function emptyResult() {
 // VENDOR_EXAMPLE_VALUES is exported for the smoke tests, which assert every
 // literal in it is still matched IN FULL by some detection rule — a literal
 // no rule can produce as a whole match is dead weight that suppresses nothing.
-module.exports = { scan, emptyResult, VENDOR_EXAMPLE_VALUES };
+// Rule ids `scan({verify: true})` knows how to check live, for callers (the
+// residoo_verify_finding MCP tool) that need to tell a caller upfront
+// whether a given finding's ruleId is even eligible, without attempting a
+// scan first. AWS/PlanetScale/MongoDB Atlas pairs are deliberately excluded
+// here even though `scan()` itself does verify them: each needs BOTH halves
+// of a pair in hand at once, which a single fingerprint alone can't express,
+// so residoo_verify_finding's v1 only supports the single-token vendors below.
+const VERIFIABLE_RULE_IDS = new Set(Object.keys(SIMPLE_VERIFY_FNS));
+
+module.exports = { scan, emptyResult, VENDOR_EXAMPLE_VALUES, VERIFIABLE_RULE_IDS };