residoo 0.4.3 → 0.4.5

package/README.md

@@ -117,6 +117,28 @@ won't be built into the tool that writes it.
   demonstrated usable credential and sorted to the top of its group in the
   Rotation section, ahead of the ones that are, on their own, not yet proven
   exploitable.
+- Decodes a JWT-shaped token's own `exp` claim locally (no network call: the
+  claim is inside the signed payload, so it cannot be altered without
+  breaking the signature) and reports "valid until" or "expired" next to it
+  in the Rotation section, instead of just "last seen." Only `exp` is ever
+  read; every other claim in the payload is decoded transiently and
+  discarded. See `src/jwtExpiry.js`.
+- **`--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. Five vendors today: **AWS** (an access key id found paired with
+  its secret, checked via `sts:get-caller-identity`, the same free,
+  read-only, permission-less call the AWS CLI and tools like aws-vault use
+  for exactly this; shells out to your own `aws` CLI rather than
+  reimplementing AWS request signing, since residoo ships zero runtime
+  dependencies and a subtly wrong signing implementation would silently
+  report real keys as invalid, worse than not checking), and **Slack,
+  OpenAI, Anthropic, GitHub** (a direct API call to each vendor's own free
+  "list what I can see" endpoint, no CLI needed, no request signing to get
+  wrong). A verified-active credential is escalated to "rotate immediately";
+  a verified-invalid one is reported as already dead, no action needed, and
+  sorted out of the way. Off by default; every environment variable the
+  `aws` CLI reads is built from scratch, never inherited, so it can never
+  fall back to your own real AWS profile. See `src/verify.js`.
 - With `--include-noisy`, filters the broad generic-secret rules by how
   machine-random the matched value actually looks (a lightweight, offline
   approximation of BPE-tokenization rarity checks): ordinary English, a
@@ -128,10 +150,10 @@ won't be built into the tool that writes it.
   preview, never the real value, including in `--json` mode. A decoded or
   rejoined secret is redacted exactly like a plain one.
 - On an interactive terminal, prints who it is and where it lives before
-  scanning starts (`residoo v0.4.3 · find secrets your AI coding agent left
+  scanning starts (`residoo v0.4.5 · find secrets your AI coding agent left
   on disk` plus the repo URL), then a live spinner naming the current file
   as it scans. Every report also opens with the exact version and timestamp
-  it was run with (`residoo v0.4.3 · scanned 2026-01-01 12:00`; `--json`
+  it was run with (`residoo v0.4.5 · scanned 2026-01-01 12:00`; `--json`
   carries the same as `residooVersion`/`scannedAt`), so a report pasted or
   screenshotted later never leaves you guessing which build produced it.
   When there are findings, the report closes with a "Next steps" pointer to
@@ -317,7 +339,14 @@ with the way out:
   versus how many are already resolved. A machine with a lot of history can
   report hundreds of raw findings that are really a handful of distinct
   values echoed repeatedly; the summary is built around what's actually left
-  to triage, not the raw count.
+  to triage, not the raw count. A value `--verify` confirmed dead, or a JWT
+  whose own signed `exp` claim is already past, is subtracted from "needs
+  review" the same way an acked or dismissed one is, since residoo already
+  knows it needs no action, not just that nobody has said so yet. This is a
+  strictly per-VALUE fact: it is never rolled up into a whole rule's
+  confidence tag in the breakdown below, since `--verify` only ever checks
+  the specific values it can (a paired AWS credential, a bearer token), and
+  a rule's other, unchecked findings say nothing either way.
 - **The rotation list is grouped by credential type**, so the rotation URL
   prints once per type instead of once per finding. Each distinct value's own
   line shows its redacted preview, which file it's in, and when it was last
@@ -355,7 +384,7 @@ As a GitHub Action (this repository doubles as a composite action):
 ```yaml
 steps:
   - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.4.3
+  - uses: dandovdub/residoo@v0.4.5
 ```
 
 As a pre-commit hook:
@@ -363,7 +392,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.4.3
+    rev: v0.4.5
     hooks:
       - id: residoo
 ```
@@ -378,10 +407,16 @@ documented in [docs/ci.md](docs/ci.md).
 ## What it does not do
 
 - **No network calls in the default path, and none at all unless you
-  explicitly pass `--upload-cloudroam`.** A secret scanner that phones home is
-  not a tool you should trust with your secrets. Verify this yourself: the one
-  `fetch` call in the codebase is in `src/sealvault.js`, reachable only behind
-  that flag, and sends only encrypted bytes.
+  explicitly pass `--upload-cloudroam` or `--verify`.** A secret scanner that
+  phones home is not a tool you should trust with your secrets. Verify this
+  yourself: every network-capable call in the codebase lives behind one of
+  those two flags. `src/sealvault.js` holds the one `fetch` call reachable
+  from `--upload-cloudroam`, and sends only encrypted bytes. `src/verify.js`
+  holds everything reachable from `--verify`: a `fetch` call per vendor
+  (Slack, OpenAI, Anthropic, GitHub), each sending nothing but the exact
+  credential a scan found to that credential's own vendor, plus a subprocess
+  call to your own `aws` CLI for AWS credentials, never a `fetch`. Neither
+  file's code runs unless you pass the matching flag.
 - **Nothing destructive, ever.** Scanning is read-only. Sealing creates *new*
   files and modifies or deletes nothing, not even the plaintext it just
   encrypted a copy of. That last step is deliberately left to a human.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "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

@@ -54,9 +54,12 @@ const HELP = `residoo: find secrets leaking through your AI agent's session hist
   Both are recorded in ~/.residoo/rotations.json, the only file residoo
   ever writes outside an explicit --seal.
 
-  Scanning makes NO network calls and changes nothing on disk. Findings are
-  redacted in every output format. Sealing (--seal) writes NEW encrypted
-  files only. It never modifies or deletes anything that already exists.
+  Scanning makes NO network calls by default and changes nothing on disk.
+  Findings are redacted in every output format. The one opt-in exception is
+  --verify, which asks a credential's own vendor whether it still
+  authenticates (AWS, Slack, OpenAI, Anthropic, GitHub today); see below.
+  Sealing (--seal) writes NEW encrypted files only. It never modifies or
+  deletes anything that already exists.
 
 Usage:
   residoo scan [options]
@@ -96,6 +99,24 @@ Scan options:
   --no-integrity          skip the integrity checks (planted hooks, dropper
                           files, auto-run tasks, hidden Unicode)
   --no-color              disable ANSI colour
+  --verify                ask the credential's own vendor whether it still
+                          authenticates, using the exact value found in
+                          your transcript. THIS MAKES A REAL NETWORK CALL.
+                          Off by default. Five vendors today:
+                            AWS: every access key id found paired with its
+                            secret (see Rotation below) is checked via
+                            sts:get-caller-identity. Needs the aws CLI on
+                            PATH; residoo shells out to it rather than
+                            reimplementing AWS request signing.
+                            Slack: every token via auth.test.
+                            OpenAI, Anthropic, GitHub: every key/token via
+                            that vendor's own models/user listing endpoint.
+                          All four non-AWS vendors are a direct, dependency-
+                          free API call, no CLI needed. A verified-invalid
+                          credential is reported as already dead, not as
+                          something to rotate; a JWT's own signed exp claim
+                          is checked locally with no network call at all,
+                          on by default, not part of --verify.
 
 Rotation:
   residoo explain <rule-id>     full rotation runbook for one detection rule
@@ -125,10 +146,11 @@ Seal options (used with scan):
                           only, unlike a passphrase, it is not portable to
                           another machine.
   --vault-dir <dir>       where to create the vault (default: ./residoo-vault-<stamp>)
-  --upload-cloudroam      ALSO upload the sealed vault to CloudRoam. This is the
-                          only residoo feature that touches the network, it is
-                          off unless you pass it, and only ciphertext is sent.
-                          Needs CLOUDROAM_API_KEY (env) plus:
+  --upload-cloudroam      ALSO upload the sealed vault to CloudRoam. One of two
+                          opt-in features that touch the network (--verify
+                          above is the other); off unless you pass it, and
+                          only ciphertext is sent. Needs CLOUDROAM_API_KEY
+                          (env) plus:
   --connector <id>        CloudRoam connector id for the destination
   --bucket <name>         destination bucket
   --prefix <p>            optional key prefix inside the bucket
@@ -434,6 +456,13 @@ async function main(argv) {
   const includeSuppressed = args.includes("--include-suppressed");
   const failOnFind = args.includes("--fail-on-find");
   const allowAcked = args.includes("--allow-acked");
+  // The one flag that makes residoo do something other than read local
+  // files: --verify asks the credential's own vendor whether it still
+  // authenticates, for every vendor residoo knows how to check today (AWS
+  // access key + paired secret via the aws CLI, Slack tokens via a direct
+  // API call; see verify.js). Off by default; every other flag here only
+  // changes what is READ or how it is DISPLAYED.
+  const verify = args.includes("--verify");
 
   // --project [dir]: the dir is optional (CI passes ".", a bare --project
   // means the current directory). null means machine mode.
@@ -543,7 +572,7 @@ async function main(argv) {
   }
 
   const progress = makeProgressReporter(noColor);
-  const result = await scan({ sources, includeNoisy, includeSuppressed, onProgress: progress.onProgress });
+  const result = await scan({ sources, includeNoisy, includeSuppressed, onProgress: progress.onProgress, verify });
   progress.stop();
   const integrity = wantsIntegrity ? runIntegrity() : null;
   const rotation = renderRotation(result.findings, acks, dismissed);

package/src/jwtExpiry.js

@@ -0,0 +1,48 @@
+"use strict";
+
+/**
+ * Local, offline JWT expiry decoding.
+ *
+ * Unlike an AWS or vendor API key, a JWT's own payload can carry an `exp`
+ * claim, and that claim is inside the signed part of the token: it cannot
+ * be altered without invalidating the signature, so decoding it locally is
+ * a trustworthy answer to "is this still valid," not a guess, PROVIDED the
+ * token is actually validated (signature + expiry) by whatever service
+ * accepts it. residoo does not check the signature (it does not know the
+ * issuer's key, and would need a network call to ask), so this only ever
+ * reports the claimed expiry, never that a token is genuinely live.
+ *
+ * No network call, no dependency, no vendor to ask: this is the free,
+ * zero-risk half of "is this credential still valid" (see verify.js for
+ * the opt-in, network-calling AWS half of that same question).
+ */
+
+function base64UrlDecode(segment) {
+  const padded = segment.replace(/-/g, "+").replace(/_/g, "/");
+  return Buffer.from(padded, "base64").toString("utf-8");
+}
+
+/**
+ * Returns the token's `exp` claim as milliseconds since epoch, or null when
+ * the token is not decodable as a JWT or carries no `exp` claim. Only the
+ * `exp` field is ever read out of the payload; every other claim (sub,
+ * email, scopes, whatever an issuer put in there) is decoded transiently
+ * and discarded, never stored or reported, so a JWT's expiry can be shown
+ * without also handling the rest of its payload as sensitive data.
+ */
+function decodeJwtExpiryMs(token) {
+  if (typeof token !== "string") return null;
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  let payload;
+  try {
+    payload = JSON.parse(base64UrlDecode(parts[1]));
+  } catch {
+    return null;
+  }
+  const exp = payload && payload.exp;
+  if (typeof exp !== "number" || !Number.isFinite(exp)) return null;
+  return exp * 1000;
+}
+
+module.exports = { decodeJwtExpiryMs };

package/src/report.js

@@ -143,9 +143,15 @@ function renderRotationSection(rotation, { noColor = false, showAdvisory = false
   // raw values, while these entries dedupe fingerprints (which include the
   // basename, so one value in two differently-named files is two rotations to
   // track). Two counts under one word would read as a contradiction.
+  // "pending" keeps its literal ledger meaning here (not yet acked or
+  // dismissed): every entry below tagged pending really is, status-wise.
+  // confirmedDead is folded into this note, not into the count itself, so
+  // this line explains rather than contradicts "Recommended actions"
+  // above, which DOES subtract it from what still needs a look.
   const resolvedNote = [
     counts.acked > 0 ? `${counts.acked} acknowledged` : null,
     counts.dismissed > 0 ? `${counts.dismissed} dismissed` : null,
+    counts.confirmedDead > 0 ? `${counts.confirmedDead} confirmed inactive` : null,
   ].filter(Boolean).join(", ");
   push(paint(c.bold, "Rotation:") +
     ` ${counts.pending} of ${counts.distinct} rotation${counts.distinct === 1 ? "" : "s"} pending` +
@@ -229,8 +235,19 @@ function renderRotationSection(rotation, { noColor = false, showAdvisory = false
       // the same type are shown as two separate lines on purpose, not
       // collapsed on a guess.
       const lastSeenNote = typeof e.lastSeenMs === "number" ? `last seen ~${ageDays(e.lastSeenMs)}d ago` : null;
+      // The one credential type residoo can say "still valid" about with
+      // zero network calls: a JWT's own exp claim, inside its signature
+      // (see jwtExpiry.js). Not proof it is accepted anywhere (residoo
+      // never checks the signature), only that the token's own claimed
+      // window has or has not passed.
+      const jwtExpiryNote = typeof e.jwtExpiresAtMs === "number"
+        ? (e.jwtExpiresAtMs < Date.now()
+            ? `expired ${new Date(e.jwtExpiresAtMs).toISOString().slice(0, 10)}`
+            : `valid until ${new Date(e.jwtExpiresAtMs).toISOString().slice(0, 10)}`)
+        : null;
       push(`    ${STATUS_TAG[e.status]}  ${e.preview}  ${paint(c.dim, fileNote)}` +
-        (lastSeenNote ? `  ${paint(c.dim, lastSeenNote)}` : ""));
+        (lastSeenNote ? `  ${paint(c.dim, lastSeenNote)}` : "") +
+        (jwtExpiryNote ? `  ${paint(c.dim, jwtExpiryNote)}` : ""));
       // An access key id and its AWS secret are each meaningless alone (see
       // pairing.js): the id names WHICH key, the secret authenticates it,
       // and an attacker needs both. Called out in red/bold, the same
@@ -238,11 +255,25 @@ function renderRotationSection(rotation, { noColor = false, showAdvisory = false
       // line under it is a demonstrated full working credential, not just a
       // shape that matched a pattern; a plain access-key-id or secret finding
       // with NO pairing note is still worth checking, but nothing here
-      // proves it is actually exploitable on its own.
-      if (e.pairedSecretPreview) {
-        push(paint(c.red + c.bold, `               ⚠ paired with secret ${e.pairedSecretPreview} · full working credential, rotate this one first`));
-      } else if (e.pairedAccessKeyPreview) {
-        push(paint(c.red + c.bold, `               ⚠ paired with access key ${e.pairedAccessKeyPreview} · full working credential`));
+      // proves it is actually exploitable on its own. --verify (see
+      // verify.js) can strengthen this to an outright confirmation, or
+      // downgrade it to "already dead": both come from a real answer from
+      // AWS, not a guess, so they get their own wording rather than folding
+      // into the generic pairing line.
+      if (e.pairedSecretPreview || e.pairedAccessKeyPreview) {
+        const otherHalf = e.pairedSecretPreview
+          ? `paired with secret ${e.pairedSecretPreview}`
+          : `paired with access key ${e.pairedAccessKeyPreview}`;
+        if (e.awsVerified === "active") {
+          push(paint(c.red + c.bold, `               ⚠ ${otherHalf} · VERIFIED ACTIVE: AWS accepted these credentials moments ago, rotate immediately`));
+        } else if (e.awsVerified === "invalid") {
+          push(paint(c.green, `               ✓ ${otherHalf} · already inactive: AWS rejected these credentials, no rotation needed`));
+        } else if (e.awsVerified === "error") {
+          push(paint(c.red + c.bold, `               ⚠ ${otherHalf} · full working credential, rotate this one first`) +
+            paint(c.dim, ` (could not verify: ${e.awsVerifiedDetail || "unknown error"})`));
+        } else {
+          push(paint(c.red + c.bold, `               ⚠ ${otherHalf} · full working credential, rotate this one first`));
+        }
       }
       if (e.status === "acked") {
         push(paint(c.dim, `               acknowledged ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""} · ${e.fingerprint}`));
@@ -386,17 +417,26 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
   // everything else is either already handled or a re-exposure of a value
   // already accounted for.
   if (rotation && rotation.counts.distinct > 0) {
-    const { pending, distinct, acked, dismissed } = rotation.counts;
+    const { pending, distinct, acked, dismissed, confirmedDead } = rotation.counts;
+    // confirmedDead is a PER-VALUE fact (a real --verify rejection, or a
+    // JWT's own signed exp claim already past), never an aggregate guess
+    // about a whole rule (see the Rotation section note: a rule's other,
+    // unverified findings say nothing either way). Subtracted here, not
+    // folded into `pending` itself, so --fail-on-find/--allow-acked and
+    // every other consumer of pending's original meaning are unaffected;
+    // this only changes what this one summary line tells a human to do.
+    const needsReview = pending - confirmedDead;
     push();
     push(paint(c.bold, "Recommended actions:"));
-    if (pending > 0) {
-      push(`  ${paint(c.yellow, "→")} ${pending} of ${distinct} distinct value${distinct === 1 ? "" : "s"} ${pending === 1 ? "needs" : "need"} review: rotate the real ones (residoo ack), dismiss the rest (residoo dismiss)`);
+    if (needsReview > 0) {
+      push(`  ${paint(c.yellow, "→")} ${needsReview} of ${distinct} distinct value${distinct === 1 ? "" : "s"} ${needsReview === 1 ? "needs" : "need"} review: rotate the real ones (residoo ack), dismiss the rest (residoo dismiss)`);
     } else {
       push(`  ${paint(c.green, "✓")} Nothing new to review; every distinct value here has already been triaged`);
     }
     const resolvedParts = [
       acked > 0 ? `${acked} acknowledged` : null,
       dismissed > 0 ? `${dismissed} dismissed` : null,
+      confirmedDead > 0 ? `${confirmedDead} confirmed inactive (verified rejected, or expired)` : null,
     ].filter(Boolean);
     if (resolvedParts.length > 0) {
       push(paint(c.dim, `    ${resolvedParts.join(", ")} already, no action needed (see Rotation below for which)`));

package/src/rotation.js

@@ -897,6 +897,19 @@ function renderRotation(findings, acks, dismissed = {}) {
         // usable credential pair, not just that a secret exists somewhere.
         pairedSecretPreview: null,
         pairedAccessKeyPreview: null,
+        // A JWT's own `exp` claim, decoded locally (see jwtExpiry.js): the
+        // one credential type residoo can say "still valid" or "expired"
+        // about with zero network calls, since expiry is inside the signed
+        // payload. null for every non-JWT finding, and for a JWT that
+        // failed to decode or carries no exp claim.
+        jwtExpiresAtMs: null,
+        // --verify only (see verify.js): whether the credential's own
+        // vendor (AWS, Slack) still accepts it. null unless the scan was
+        // run with --verify AND this value is one residoo knows how to
+        // check; residoo makes no network calls otherwise. Same two fields
+        // regardless of vendor: the ruleId already says which one answered.
+        verified: null,
+        verifiedDetail: null,
       };
       byFp.set(st.fingerprint, e);
     }
@@ -909,7 +922,9 @@ function renderRotation(findings, acks, dismissed = {}) {
     // honest, locally-derivable signal for "how stale is this." NOT proof a
     // credential was rotated or revoked, only that residoo hasn't seen it
     // paste anywhere more recently than this. residoo makes no network
-    // calls, so it never checks a provider for whether a key is still live.
+    // calls in the default path, so this alone never checks a provider for
+    // whether a key is still live (see verified above for the opt-in
+    // exception, and jwtExpiresAtMs for the zero-network JWT case).
     if (typeof f.fileMTimeMs === "number" && (e.lastSeenMs === null || f.fileMTimeMs > e.lastSeenMs)) {
       e.lastSeenMs = f.fileMTimeMs;
     }
@@ -923,24 +938,54 @@ function renderRotation(findings, acks, dismissed = {}) {
     if (e.pairedAccessKeyPreview === null && typeof f.pairedAccessKeyPreview === "string") {
       e.pairedAccessKeyPreview = f.pairedAccessKeyPreview;
     }
+    if (e.jwtExpiresAtMs === null && typeof f.jwtExpiresAtMs === "number") {
+      e.jwtExpiresAtMs = f.jwtExpiresAtMs;
+    }
+    if (e.verified === null && typeof f.verified === "string") {
+      e.verified = f.verified;
+      e.verifiedDetail = typeof f.verifiedDetail === "string" ? f.verifiedDetail : null;
+    }
   }
 
-  // A paired entry is a DEMONSTRATED usable credential (see pairing.js); an
-  // unpaired access-key-id or secret finding of the same rule and status is
-  // only a shape that matched a pattern. Sorted first within its status tier
-  // so a real pair is never the one the display cap (see renderRotationSection)
-  // pushes into "N more"; the report's own priority order (see the group
-  // sort just below in renderRotationSection) already applies the same
-  // "what needs attention most" logic one level up.
-  const isPaired = (e) => e.pairedSecretPreview !== null || e.pairedAccessKeyPreview !== null;
+  // Within a status tier, order by how demonstrated-urgent an entry is, not
+  // just its rule id: a real pair (see pairing.js) is a DEMONSTRATED usable
+  // credential, and --verify confirming the vendor still accepts it is
+  // stronger evidence still; either way this entry must never be the one
+  // the display cap (see renderRotationSection) pushes into "N more."
+  //
+  // isConfirmedDead is the other direction, PROOF rather than a guess:
+  // --verify got a real "no" from the vendor, or a JWT's own signed exp
+  // claim is already in the past (decoded locally, no network call, always
+  // attempted; see jwtExpiry.js). Deliberately NOT "unverified" or "no
+  // pairing found": those mean residoo doesn't know, a weaker claim than
+  // residoo knows this one specific value needs no action. Sorts LOWER
+  // than an ordinary finding within its tier, and (see confirmedDead below)
+  // is subtracted from what the report tells a human still needs a look.
+  const isConfirmedDead = (e) => e.verified === "invalid" || (e.jwtExpiresAtMs !== null && e.jwtExpiresAtMs < Date.now());
+  const priorityScore = (e) => {
+    if (e.verified === "active") return -2;
+    if (e.pairedSecretPreview !== null || e.pairedAccessKeyPreview !== null) return -1;
+    if (isConfirmedDead(e)) return 1;
+    return 0;
+  };
   const entries = [...byFp.values()].sort((a, b) => {
     if (a.status !== b.status) return STATUS_ORDER[a.status] - STATUS_ORDER[b.status];
-    if (isPaired(a) !== isPaired(b)) return isPaired(a) ? -1 : 1;
+    const pa = priorityScore(a), pb = priorityScore(b);
+    if (pa !== pb) return pa - pb;
     if (a.ruleId !== b.ruleId) return a.ruleId < b.ruleId ? -1 : 1;
     return a.fingerprint < b.fingerprint ? -1 : 1;
   });
 
-  return { counts, entries };
+  // A per-VALUE fact, never rolled up into a per-RULE label: only the
+  // specific values residoo actually checked (or that carry their own
+  // signed exp claim) ever count here, so this can never overstate what was
+  // proven about the rest of a rule's unverified findings. Counted only
+  // among PENDING entries: one already acked or dismissed is excluded from
+  // "needs review" for its own reason already, and double-subtracting would
+  // make the arithmetic in the report not add up.
+  const confirmedDead = entries.filter((e) => e.status === "pending" && isConfirmedDead(e)).length;
+
+  return { counts: { ...counts, confirmedDead }, entries };
 }
 
 module.exports = {

package/src/scan.js

@@ -5,6 +5,33 @@ const { PATTERNS, NOISY_PATTERNS, redact } = require("./patterns");
 const { findDecodedMatches, findBoundaryMatches, contentProjection } = require("./decode");
 const { findPairedSecret } = require("./pairing");
 const { looksRandom } = require("./rarity");
+const { decodeJwtExpiryMs } = require("./jwtExpiry");
+const {
+  isAwsCliAvailable, verifyAwsCredential,
+  verifySlackToken, verifyOpenAiKey, verifyAnthropicKey, verifyGithubToken,
+} = require("./verify");
+
+// Never verify more than this many distinct credentials of ONE vendor in a
+// single scan: a pathological transcript with dozens of distinct
+// credentials should not turn --verify into a long burst of outbound calls.
+// Real scans see 0-2 per vendor; this is a backstop, not the expected path.
+const MAX_VERIFICATIONS_PER_VENDOR = 10;
+
+// Every vendor whose credential is a single, unpaired bearer token: no
+// AWS-style "two halves make one credential" pairing step, so these all
+// share one collection/verification path below (see pendingSimpleVerifications).
+const SIMPLE_VERIFY_FNS = {
+  slack_token: verifySlackToken,
+  openai_key: verifyOpenAiKey,
+  anthropic_key: verifyAnthropicKey,
+  github_pat: verifyGithubToken,
+};
+const SIMPLE_VERIFY_VENDOR_LABEL = {
+  slack_token: "Slack's auth.test",
+  openai_key: "OpenAI's models endpoint",
+  anthropic_key: "Anthropic's models endpoint",
+  github_pat: "GitHub's user endpoint",
+};
 
 // Rule ids that findPairedSecret's window search applies to (see pairing.js):
 // AWS access key ids and STS session tokens both pair with the same shape
@@ -127,7 +154,7 @@ function safeName(file) { return path.basename(file); }
  * 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 } = {}) {
+async function scan({ sources, includeNoisy = false, includeSuppressed = false, onProgress = null, verify = 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
@@ -146,11 +173,30 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
   // browser-testing run is one leak, not ten) — never written to a report,
   // never leaves this function.
   const distinctByRule = new Map();
+  // --verify only (see verify.js): accessKeyValue -> { secretValue, refs }.
+  // Keyed by the RAW access key so the map itself dedupes distinct
+  // credentials for the AWS call (one call per key, no matter how many
+  // times it was echoed) while `refs` accumulates EVERY occurrence's
+  // finding-object pair, so the result reaches all of them, not only the
+  // first: an access key re-echoed across several lines gets several
+  // finding objects, and every one of them needs the same answer. Like
+  // distinctByRule above, this lives only for the duration of this scan()
+  // call; nothing in it is ever written to a finding until verification has
+  // REPLACED the raw values with a status string.
+  const pendingAwsVerifications = new Map();
+  // --verify only (see verify.js): ruleId -> (token value -> { refs }), for
+  // every SIMPLE_VERIFY_FNS vendor. Unlike AWS, none of these need pairing
+  // (the token itself is the complete credential), so this is simpler: one
+  // entry per distinct value per rule, `refs` accumulating every finding
+  // object that value produced.
+  const pendingSimpleVerifications = new Map();
 
   // One place raw matched text turns into a recorded finding: counts the
   // distinct value and pushes the redacted record. `extra` carries the
   // encoding / split markers for the decode and boundary passes; the raw pass
-  // passes none.
+  // passes none. Returns the finding object itself so a caller (the pairing
+  // and --verify logic) can attach more fields onto it later, after the
+  // fields that need real work (an AWS API round-trip) finish.
   const record = (rule, value, relFile, file, lineNo, mtimeMs, confidence, suppressedReason, extra) => {
     if (!distinctByRule.has(rule.id)) distinctByRule.set(rule.id, new Set());
     distinctByRule.get(rule.id).add(value);
@@ -166,6 +212,7 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
       fileMTimeMs: mtimeMs,
       ...(extra || {}),
     });
+    return findings[findings.length - 1];
   };
 
   // One suppression policy for all three passes (raw, decoded, boundary).
@@ -221,6 +268,8 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
           // next to it in the transcript, not just that a secret exists
           // somewhere in the scan.
           let pairedSecretPreview = null;
+          let secretFinding = null;
+          let rawPairedSecret = null;
           if (!suppressedReason && AWS_PAIR_RULE_IDS.has(rule.id)) {
             const paired = findPairedSecret(line, m[0], m.index);
             if (paired) {
@@ -229,18 +278,60 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
                 suppressedCount++;
               } else {
                 pairedSecretPreview = redact(paired);
-                record({ id: "aws_secret_access_key_paired", label: "AWS Secret Access Key (paired with access key id)" },
+                rawPairedSecret = paired;
+                secretFinding = record({ id: "aws_secret_access_key_paired", label: "AWS Secret Access Key (paired with access key id)" },
                   paired, relFile, file, lineNo, mtimeMs,
                   pairedSuppressedReason ? "low" : "high", pairedSuppressedReason,
                   { paired: true, pairedAccessKeyPreview: redact(m[0]) });
               }
             }
           }
-          record(rule, m[0], relFile, file, lineNo,
+          // Local, offline JWT expiry (see jwtExpiry.js): only ever reads
+          // the `exp` claim out of the decoded payload, nothing else, and
+          // only for the unsuppressed default `jwt` rule, since a
+          // suppressed placeholder/example match is not worth decoding.
+          const jwtExtra = (!suppressedReason && rule.id === "jwt")
+            ? { jwtExpiresAtMs: decodeJwtExpiryMs(m[0]) }
+            : null;
+          const primaryFinding = record(rule, m[0], relFile, file, lineNo,
             mtimeMs,
             resolveConfidence(rule.id, m[0], rule.confidence, suppressedReason),
             suppressedReason,
-            pairedSecretPreview ? { pairedSecretPreview } : undefined);
+            { ...(pairedSecretPreview ? { pairedSecretPreview } : {}), ...(jwtExtra || {}) });
+
+          // --verify only, and only for a DEMONSTRATED pair (both halves
+          // present, neither suppressed): queue it for the verification pass
+          // that runs once, after every file has been scanned (see below).
+          // The Map key dedupes the actual AWS call to one per distinct
+          // credential; `refs` still grows on every occurrence, so a key
+          // 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) {
+            if (!pendingAwsVerifications.has(m[0]) && pendingAwsVerifications.size < MAX_VERIFICATIONS_PER_VENDOR) {
+              pendingAwsVerifications.set(m[0], { secretValue: rawPairedSecret, refs: [] });
+            }
+            const entry = pendingAwsVerifications.get(m[0]);
+            if (entry) entry.refs.push({ akiaFinding: primaryFinding, secretFinding });
+          }
+          // --verify, single-token vendors (Slack, OpenAI, Anthropic,
+          // GitHub): none of these need pairing (the value IS the complete
+          // credential), so queue every unsuppressed match directly, same
+          // 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]) {
+            let byValue = pendingSimpleVerifications.get(rule.id);
+            if (!byValue) {
+              byValue = new Map();
+              pendingSimpleVerifications.set(rule.id, byValue);
+            }
+            if (!byValue.has(m[0]) && byValue.size < MAX_VERIFICATIONS_PER_VENDOR) {
+              byValue.set(m[0], { refs: [] });
+            }
+            const entry = byValue.get(m[0]);
+            if (entry) entry.refs.push(primaryFinding);
+          }
         }
         if (m.index === rule.re.lastIndex) rule.re.lastIndex++; // guard zero-width matches
       }
@@ -396,6 +487,62 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
     if (sourceScannedAnything) sourcesScanned.push(source.id());
   }
 
+  // --verify: runs once, here, after every file has been scanned, never
+  // interleaved with the matching pass above. A real network call per
+  // distinct credential, one at a time (not concurrent), so this is the one
+  // place a scan's wall-clock time depends on something other than disk
+  // I/O; that tradeoff only exists when a caller explicitly asked for it.
+  // Same field names (verified/verifiedDetail) regardless of which vendor
+  // produced the result: rotation.js and report.js render them identically,
+  // and the finding's own ruleId already says which vendor answered.
+  const applyVerifyResult = (refs, result) => {
+    for (const ref of refs) {
+      ref.verified = result.status;
+      ref.verifiedDetail = result.detail;
+    }
+  };
+  if (verify && pendingAwsVerifications.size > 0) {
+    const applyPair = (refs, result) => {
+      for (const ref of refs) {
+        applyVerifyResult([ref.akiaFinding, ref.secretFinding], result);
+      }
+    };
+    if (!isAwsCliAvailable()) {
+      process.stderr.write(
+        "residoo --verify: the aws CLI was not found on PATH, so the " +
+        `${pendingAwsVerifications.size} AWS credential(s) found in this scan could not be checked. ` +
+        "Install it (https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to use --verify.\n"
+      );
+      const result = { status: "error", detail: "aws CLI not found on PATH" };
+      for (const { refs } of pendingAwsVerifications.values()) applyPair(refs, result);
+    } else {
+      process.stderr.write(
+        `residoo --verify: calling AWS sts:get-caller-identity for ${pendingAwsVerifications.size} ` +
+        "credential(s) found in this scan. This is a real network request to AWS, using the exact " +
+        "credential found in your transcript, one at a time.\n"
+      );
+      for (const [accessKeyValue, { secretValue, refs }] of pendingAwsVerifications) {
+        const result = verifyAwsCredential(accessKeyValue, secretValue);
+        applyPair(refs, result);
+      }
+    }
+  }
+  if (verify) {
+    for (const [ruleId, byValue] of pendingSimpleVerifications) {
+      if (byValue.size === 0) continue;
+      const verifyFn = SIMPLE_VERIFY_FNS[ruleId];
+      process.stderr.write(
+        `residoo --verify: calling ${SIMPLE_VERIFY_VENDOR_LABEL[ruleId]} for ${byValue.size} ` +
+        "token(s) found in this scan. This is a real network request, using the exact " +
+        "token found in your transcript, one at a time.\n"
+      );
+      for (const [value, { refs }] of byValue) {
+        const result = await verifyFn(value);
+        applyVerifyResult(refs, result);
+      }
+    }
+  }
+
   const distinctCounts = {};
   for (const [ruleId, set] of distinctByRule) distinctCounts[ruleId] = set.size;
   return { findings, filesScanned, sourcesScanned, bytesScanned, suppressedCount, distinctCounts, unreadableFiles };

package/src/verify.js

@@ -0,0 +1,266 @@
+"use strict";
+
+/**
+ * Opt-in live credential verification (--verify).
+ *
+ * Everything else in residoo is detection only: a shape matched a pattern,
+ * nothing more, zero network calls, by design (see README's "What it does
+ * not do"). This module is the one deliberate exception, and only when a
+ * user explicitly passes --verify: it asks the credential's own vendor
+ * whether it still authenticates, via whatever free, read-only check that
+ * vendor documents for exactly this "is this still alive" question.
+ *
+ * Two different implementation strategies live in this one file, chosen
+ * per vendor by how risky it would be to get wrong:
+ *
+ * AWS (verifyAwsCredential) shells out to the user's own `aws` CLI rather
+ * than hand-rolling AWS SigV4 request signing. Two reasons, not one: first,
+ * residoo ships zero runtime dependencies, and a correct SigV4
+ * implementation is real, easy-to-get-subtly-wrong cryptographic code this
+ * project cannot verify against a live AWS account in CI; a signing bug
+ * here would silently report every real key as "invalid," which is actively
+ * worse than not verifying at all. Second, the AWS CLI is exactly the
+ * client AWS itself maintains and tests against its own service. Every
+ * environment variable the aws CLI reads is built from scratch, never
+ * inherited from process.env: AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY are
+ * set to the exact values found in the scan, and AWS_CONFIG_FILE/
+ * AWS_SHARED_CREDENTIALS_FILE point at /dev/null so the CLI cannot fall
+ * back to the user's own real default profile if the found credential is
+ * malformed in some way that would otherwise trigger a fallback.
+ *
+ * Slack (verifySlackToken) calls the API directly with the built-in fetch
+ * instead: unlike AWS, Slack's auth check (auth.test) is a single bearer-
+ * token HTTP call with no request signing at all, so there is no signing
+ * bug to be worried about, and no CLI most residoo users would already
+ * have installed the way they'd have the aws CLI. Direct fetch is both
+ * simpler and more portable here; shelling out to a hypothetical "slack
+ * CLI" would add a dependency for no safety benefit. This is the pattern
+ * for any future vendor: shell out to that vendor's own official CLI only
+ * when the auth scheme itself is complex enough to be worth not
+ * reimplementing (AWS's SigV4); call directly for a plain bearer token.
+ *
+ * OpenAI, Anthropic, and GitHub (verifyOpenAiKey, verifyAnthropicKey,
+ * verifyGithubToken) share one implementation (verifyByStatusCode): each is
+ * a plain GET to a free, side-effect-free, already-authenticated endpoint
+ * (that vendor's own "list what I can see" call), where the HTTP status
+ * code alone says whether the credential authenticated. Slack needed its
+ * own function because auth.test always returns HTTP 200 and signals
+ * failure inside the JSON body instead of the status code.
+ */
+
+const { spawnSync } = require("child_process");
+
+const DEFAULT_TIMEOUT_MS = 8000;
+
+/**
+ * Test-only escape hatch: when RESIDOO_TEST_AWS_CLI is set, every spawnSync
+ * call below runs that path instead of "aws" on PATH. Same pattern as
+ * keychain.js's RESIDOO_TEST_KEYCHAIN_FILE — crosses a spawned child
+ * process boundary (this project's own CLI e2e tests) via env var, so a
+ * test can point at a small fixture script and exercise the real spawnSync
+ * + argv + env + exit-code + stdout/stderr plumbing without ever spawning
+ * the real aws CLI or touching the network. Not a documented flag: no real
+ * user has a reason to set this.
+ */
+function awsBinary() {
+  return process.env.RESIDOO_TEST_AWS_CLI || "aws";
+}
+
+/** Strip control bytes and cap length: any text here may echo an AWS error message to a terminal. */
+function sanitizeDetail(s) {
+  return String(s || "").replace(/[\x00-\x1f\x7f]/g, "").slice(0, 200);
+}
+
+/**
+ * True if an `aws` binary is reachable on PATH and runs. Checked once per
+ * scan (not once per credential) so a missing CLI produces one clear
+ * message instead of N identical failures.
+ */
+function isAwsCliAvailable(spawnFn = spawnSync) {
+  try {
+    const r = spawnFn(awsBinary(), ["--version"], {
+      timeout: 5000,
+      env: { PATH: process.env.PATH || "" },
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+    return !r.error && r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ask AWS whether this exact access key id / secret access key pair still
+ * authenticates. Returns { status, detail } where status is one of:
+ *   "active"    AWS accepted the credentials (sts:get-caller-identity
+ *               succeeded, or failed only on a follow-up permission check,
+ *               which still proves authentication succeeded)
+ *   "invalid"   AWS rejected the credentials outright (revoked, deleted,
+ *               or never valid)
+ *   "error"     could not determine either way (CLI missing, timeout,
+ *               network failure, or an AWS error this function does not
+ *               recognize) — never conflated with "invalid": an inability
+ *               to check is not evidence the credential is dead.
+ * Synchronous: spawnSync itself is synchronous, and calling this from a
+ * plain loop (not Promise.all) means verifications run one at a time, not
+ * as a burst of concurrent requests against one account.
+ */
+function verifyAwsCredential(accessKeyId, secretAccessKey, { spawnFn = spawnSync, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  let r;
+  try {
+    r = spawnFn(awsBinary(), ["sts", "get-caller-identity", "--output", "json"], {
+      timeout: timeoutMs,
+      encoding: "utf-8",
+      env: {
+        PATH: process.env.PATH || "",
+        AWS_ACCESS_KEY_ID: accessKeyId,
+        AWS_SECRET_ACCESS_KEY: secretAccessKey,
+        AWS_DEFAULT_REGION: "us-east-1",
+        AWS_EC2_METADATA_DISABLED: "true",
+        AWS_CONFIG_FILE: "/dev/null",
+        AWS_SHARED_CREDENTIALS_FILE: "/dev/null",
+      },
+    });
+  } catch (e) {
+    return { status: "error", detail: `aws CLI failed to run (${sanitizeDetail(e && e.message)})` };
+  }
+  if (r.error) {
+    if (r.error.code === "ENOENT") return { status: "error", detail: "aws CLI not found on PATH" };
+    return { status: "error", detail: `aws CLI failed to run (${sanitizeDetail(r.error.code || r.error.message)})` };
+  }
+  if (r.status === 0) {
+    return { status: "active", detail: "AWS accepted these credentials (sts:get-caller-identity)" };
+  }
+  const stderr = String(r.stderr || "");
+  if (/InvalidClientTokenId|SignatureDoesNotMatch|UnrecognizedClientException/.test(stderr)) {
+    return { status: "invalid", detail: "AWS rejected these credentials" };
+  }
+  if (/AccessDenied/.test(stderr)) {
+    // GetCallerIdentity needs no IAM permissions at all; an AccessDenied
+    // here (rare — e.g. an explicit deny policy) still means the
+    // credentials themselves authenticated before that policy was checked.
+    return { status: "active", detail: "AWS accepted these credentials (denied only on a follow-up permission check)" };
+  }
+  return { status: "error", detail: `could not verify: ${sanitizeDetail(stderr).slice(0, 120) || `aws exited ${r.status}`}` };
+}
+
+/**
+ * Test-only escape hatch, same purpose as RESIDOO_TEST_AWS_CLI above but for
+ * an HTTP call instead of a subprocess: when RESIDOO_TEST_SLACK_API_URL is
+ * set, verifySlackToken calls that URL instead of Slack's real API, so a
+ * test can point at a small local HTTP server and exercise the real fetch +
+ * header + JSON-parsing plumbing without ever reaching slack.com.
+ */
+function slackAuthTestUrl() {
+  return process.env.RESIDOO_TEST_SLACK_API_URL || "https://slack.com/api/auth.test";
+}
+
+// Slack's own documented error codes for auth.test that mean the token
+// itself is dead (revoked, expired, or never valid), not merely rate
+// limited or a transient server problem.
+const SLACK_DEAD_TOKEN_ERRORS = new Set([
+  "invalid_auth", "not_authed", "token_revoked", "token_expired", "account_inactive",
+]);
+
+/**
+ * Ask Slack whether this exact token still authenticates, via auth.test
+ * (api.slack.com/methods/auth.test): a bearer-token-only call Slack's own
+ * docs recommend for checking token validity, needing no scope of its own.
+ * Same three-way { status, detail } contract as verifyAwsCredential.
+ */
+async function verifySlackToken(token, { fetchFn = fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  let res;
+  try {
+    res = await fetchFn(slackAuthTestUrl(), {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (e) {
+    return { status: "error", detail: `could not reach Slack (${sanitizeDetail(e && e.message)})` };
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch (e) {
+    return { status: "error", detail: `Slack returned a non-JSON response (HTTP ${res.status})` };
+  }
+  if (body && body.ok === true) {
+    return { status: "active", detail: "Slack accepted this token (auth.test)" };
+  }
+  const err = body && typeof body.error === "string" ? body.error : null;
+  if (err && SLACK_DEAD_TOKEN_ERRORS.has(err)) {
+    return { status: "invalid", detail: `Slack rejected this token (${sanitizeDetail(err)})` };
+  }
+  return { status: "error", detail: `could not verify: ${sanitizeDetail(err) || `HTTP ${res.status}`}` };
+}
+
+/**
+ * Shared implementation for every vendor below Slack: a plain GET to a
+ * free, side-effect-free, already-authenticated endpoint (each vendor's own
+ * "list what I can see" call), where the HTTP status code alone says
+ * whether the credential authenticated. 200 is active; 401/403 is a real
+ * rejection; anything else (429 rate limited, 5xx, a network failure) is
+ * inconclusive, never guessed as either active or invalid. Slack needed its
+ * own function above because its auth.test always returns HTTP 200 and
+ * signals failure inside the JSON body instead.
+ */
+async function verifyByStatusCode(vendorName, url, buildHeaders, { fetchFn = fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  let res;
+  try {
+    res = await fetchFn(url, {
+      method: "GET",
+      headers: buildHeaders(),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (e) {
+    return { status: "error", detail: `could not reach ${vendorName} (${sanitizeDetail(e && e.message)})` };
+  }
+  if (res.status === 200) {
+    return { status: "active", detail: `${vendorName} accepted this key` };
+  }
+  if (res.status === 401 || res.status === 403) {
+    return { status: "invalid", detail: `${vendorName} rejected this key (HTTP ${res.status})` };
+  }
+  return { status: "error", detail: `could not verify: HTTP ${res.status} from ${vendorName}` };
+}
+
+// Test-only escape hatches, same purpose and pattern as
+// RESIDOO_TEST_SLACK_API_URL above: when set, the matching verify function
+// calls that URL instead of the vendor's real one.
+function openAiModelsUrl() {
+  return process.env.RESIDOO_TEST_OPENAI_API_URL || "https://api.openai.com/v1/models";
+}
+function anthropicModelsUrl() {
+  return process.env.RESIDOO_TEST_ANTHROPIC_API_URL || "https://api.anthropic.com/v1/models";
+}
+function githubUserUrl() {
+  return process.env.RESIDOO_TEST_GITHUB_API_URL || "https://api.github.com/user";
+}
+
+/** OpenAI: GET /v1/models, a free, read-only call that needs only a valid key, no usage cost. */
+function verifyOpenAiKey(key, opts) {
+  return verifyByStatusCode("OpenAI", openAiModelsUrl(), () => ({ Authorization: `Bearer ${key}` }), opts);
+}
+
+/**
+ * Anthropic: GET /v1/models. Two headers, not one, and NOT an Authorization
+ * Bearer header: Anthropic's API takes the key as x-api-key, and every
+ * request needs an anthropic-version header regardless of endpoint.
+ */
+function verifyAnthropicKey(key, opts) {
+  return verifyByStatusCode("Anthropic", anthropicModelsUrl(), () => ({
+    "x-api-key": key,
+    "anthropic-version": "2023-06-01",
+  }), opts);
+}
+
+/** GitHub: GET /user with the token, a free, read-only call that needs no scopes. */
+function verifyGithubToken(token, opts) {
+  return verifyByStatusCode("GitHub", githubUserUrl(), () => ({ Authorization: `Bearer ${token}` }), opts);
+}
+
+module.exports = {
+  isAwsCliAvailable, verifyAwsCredential, verifySlackToken,
+  verifyOpenAiKey, verifyAnthropicKey, verifyGithubToken,
+};