residoo 0.7.1 → 0.8.0

package/README.md

@@ -10,6 +10,7 @@
 
 [![npm version](https://img.shields.io/npm/v/residoo)](https://www.npmjs.com/package/residoo)
 [![CI](https://github.com/dandovdub/residoo/actions/workflows/ci.yml/badge.svg)](https://github.com/dandovdub/residoo/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/dandovdub/residoo/badge)](https://scorecard.dev/viewer/?uri=github.com/dandovdub/residoo)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 [![node >=18](https://img.shields.io/badge/node-%3E%3D18-339933)](package.json)
 [![runtime dependencies: 0](https://img.shields.io/badge/runtime_dependencies-0-brightgreen)](package.json)
@@ -60,13 +61,33 @@ 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.4.14:
+most recently v0.8.0:
 
 | | residoo | best of the rest |
 |---|---|---|
@@ -310,7 +331,7 @@ As a GitHub Action (this repo doubles as a composite action):
 ```yaml
 steps:
   - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.7.1
+  - uses: dandovdub/residoo@v0.8.0
 ```
 
 As a pre-commit hook:
@@ -318,7 +339,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.7.1
+    rev: v0.8.0
     hooks:
       - id: residoo
 ```
@@ -451,6 +472,10 @@ you running the CLI in a terminal:
 claude mcp add residoo -- residoo mcp
 ```
 
+or run `scripts/install-mcp.sh` (also in this repo), which installs residoo
+itself first if it isn't already, then registers it and verifies the
+connection.
+
 or add it directly to `.mcp.json`:
 
 ```json
@@ -473,11 +498,27 @@ 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.
 
+A seventh tool, `residoo_verify_finding`, is genuinely different from the
+other six: it asks a credential's own vendor, live, whether it's still
+active (the same mechanism as `scan --verify`, scoped to exactly one
+credential per call). This is the one MCP tool that makes a real network
+call, so it does not exist at all unless you set
+`RESIDOO_MCP_ALLOW_VERIFY=1` in the environment `residoo mcp` runs in — a
+default install stays true to "zero network calls" without a caveat.
+Once enabled, pass a `fingerprint` from a prior `residoo_scan`; you get
+back `active`, `invalid`, or `unknown`, never the raw value. Paired
+credentials (AWS access key + secret, PlanetScale, MongoDB Atlas) aren't
+supported yet — use `residoo scan --verify` from a terminal for those.
+
 ## Cred: run commands with injected credentials
 
-`residoo cred` stores a live, reusable credential in the OS keychain and
-runs one allow-listed command with it injected as environment variables:
-Claude never sees the raw value, before, during, or after:
+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
@@ -540,6 +581,41 @@ Storage is macOS (`security`) or Linux (`secret-tool`) only, matching
 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.
 
+## Guard: block a sensitive read before it happens
+
+Everything above finds a leak after it's already written to disk. `residoo
+guard` is the one piece of residoo that tries to stop one from happening in
+the first place — a Claude Code `PreToolUse` hook that blocks an obviously-
+sensitive file read (`.env`, `id_rsa`, `.aws/credentials`, and similar)
+before the command runs at all.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Bash|Read", "hooks": [{ "type": "command", "command": "residoo guard" }] }
+    ]
+  }
+}
+```
+in `.claude/settings.json`. It reads one hook payload from stdin and writes
+a deny decision to stdout only when the proposed command or file path
+matches; anything it doesn't recognize falls through untouched, with zero
+output, exit 0.
+
+This is narrower than it might sound, and the gap is worth stating
+plainly rather than implying more than it does: Claude Code's hooks API
+lets a `PreToolUse` hook see the proposed tool INPUT (a Bash command
+string, a Read file path) before it runs, but there is no documented
+mechanism for a hook to see or redact a tool's OUTPUT — by the time a
+`PostToolUse` hook fires, that output is already committed to the
+transcript. So this can only block on the shape of the request, never
+clean up what a command already printed. It will not catch a secret typed
+directly into a prompt, or one arriving in the output of an otherwise
+unremarkable command (`curl`, a build log). `residoo scan` / `watch` /
+`mcp` remain the actual safety net; this is a best-effort tripwire on top
+of them, not a replacement.
+
 ## Sources supported today
 
 43 sources: 42 transcript stores plus the agent-config source above, in two

package/SECURITY.md

@@ -83,7 +83,16 @@ the kind of thing worth impersonating.
   built it; check the provenance badge on the npm page. One honest
   exception, stated rather than hidden: the very first release (v0.1.0)
   was a manual upload to claim the name, so provenance starts at the first
-  CI-published version after it.
+  CI-published version after it. Concretely, this is npm's own [Trusted
+  Publishing](https://docs.npmjs.com/trusted-publishers): no stored token
+  anywhere, GitHub mints a short-lived, workflow-scoped OIDC credential per
+  release, and the resulting provenance statement is signed and published
+  to the public [Sigstore transparency log](https://search.sigstore.dev/),
+  independently checkable by anyone, not just trusted on residoo's word.
+  In [SLSA](https://slsa.dev/) terms that's Build Level 2 (a hosted,
+  authenticated build platform generates non-forgeable provenance); Level
+  3 (fully hermetic, isolated builds) isn't implemented yet, stated
+  plainly rather than implied.
 - The only PyPI package is **`residoo`**: a thin official launcher whose
   entire job is running the npm CLI via `npx`. Its source lives in this
   repository under `pypi/`. It exists partly so nobody else can hold the

package/package.json

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

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/decode.js

@@ -306,6 +306,25 @@ function findDecodedMatches(line, rules) {
 const BOUNDARY_WINDOW = 300;   // chars taken from each side of the seam
 const BOUNDARY_MIN_CONTENT = 24; // shorter "longest string" is treated as non-content
 
+// Minimum characters EACH side of the seam must contribute to a straddling
+// match for it to be trusted as a genuine split, not coincidence. Found via
+// this project's own benchmark stress-testing (2026-09-03), not hypothetical:
+// a variable-length rule (bearer_header, {16,1000}) can sit ONE character
+// short of its own minimum at the end of a line (a near-miss, not a complete
+// match — the existing greedy-extension guard above only recognizes COMPLETE
+// tail-alone matches, so it never sees this case), and if the very next
+// line's content happens to start with even one or two more characters the
+// pattern's class allows, the straddle pass stitches two entirely unrelated,
+// benign lines into a fabricated value that exists in neither. Existing
+// legitimate-split tests (tests/smoke.js) cut real secrets 9-11 characters
+// from each end, comfortably clear of this floor; a genuine chunked-
+// streaming boundary landing with less than this on one side, while
+// possible, is far rarer than the coincidental-concatenation failure mode
+// this exists to close, and the fragment still gets caught by the raw,
+// single-line pass once enough of it lands on either side to satisfy the
+// rule outright.
+const BOUNDARY_MIN_CONTRIBUTION = 4;
+
 /**
  * Escape-aware list of JSON string-literal CONTENTS on a line. Field names
  * are included (this walker does not distinguish keys from values); the
@@ -395,8 +414,15 @@ function findBoundaryMatches(contentA, contentB, rules) {
       const start = m.index;
       const end = m.index + m[0].length;
       // Straddle-only: the match must cross the seam, else it lay wholly in
-      // one line and the single-line pass already reported it.
-      if (start < seam && end > seam) straddles.push({ start, end, value: m[0] });
+      // one line and the single-line pass already reported it. Each side
+      // must also contribute a real fragment (BOUNDARY_MIN_CONTRIBUTION,
+      // see its own doc comment) -- otherwise this is a near-miss single-
+      // line match that unrelated adjacent content happened to push over a
+      // length-quantifier's minimum, not a genuine split.
+      if (start < seam && end > seam &&
+          (seam - start) >= BOUNDARY_MIN_CONTRIBUTION && (end - seam) >= BOUNDARY_MIN_CONTRIBUTION) {
+        straddles.push({ start, end, value: m[0] });
+      }
       if (m.index === rule.re.lastIndex) rule.re.lastIndex++;
     }
     let flush = null;

package/src/guard.js

@@ -0,0 +1,128 @@
+"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).
+const SEP = "(?:^|[\\s'\"`;|&(<>\\\\/])";
+const pat = (body) => new RegExp(SEP + body + BOUNDARY, "i");
+
+const SENSITIVE_PATH_PATTERNS = [
+  // dotenv files, including staged/numbered variants (.env.local, .env.1)
+  { re: pat("\\.env(?:\\.[\\w.-]+)?"), label: "a .env file" },
+  // SSH private keys: the conventional default names, and any *.pem/*.key
+  { re: pat("id_(?:rsa|dsa|ecdsa|ed25519)(?:\\.pub)?"), label: "an SSH private key" },
+  { re: new RegExp(SEP + "\\.ssh[\\\\/]", "i"), label: "the SSH directory" },
+  { re: pat("[\\w.-]+\\.pem"), label: "a .pem key file" },
+  { re: pat("[\\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" },
+  { re: pat("service[_-]?account[\\w.-]*\\.json"), 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 };