residoo 0.4.0 → 0.4.1

package/README.md

@@ -122,10 +122,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.0 · find secrets your AI coding agent left
+  scanning starts (`residoo v0.4.1 · 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.0 · scanned 2026-01-01 12:00`; `--json`
+  it was run with (`residoo v0.4.1 · 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
@@ -312,6 +312,17 @@ with the way out:
   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.
+- **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
+  seen in a transcript, not just a bare fingerprint. "Last seen" is exactly
+  that: the most recent transcript occurrence residoo found, not proof a
+  credential is still live or that an older value was rotated. Most
+  credential formats (AWS access keys, vendor API tokens) carry no shared
+  identifier linking a rotated key to its predecessor, and residoo makes no
+  network calls to ask the provider, so two distinct pending values of the
+  same type are always shown as two separate lines, never collapsed on a
+  guess.
 - **Order matters, and the report says so when it does.** The ChainDrop
   campaign (Aug 2026) shipped a token monitor that fires an attacker payload
   the moment the stolen GitHub token is revoked. When one scan finds both
@@ -338,7 +349,7 @@ As a GitHub Action (this repository doubles as a composite action):
 ```yaml
 steps:
   - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.4.0
+  - uses: dandovdub/residoo@v0.4.1
 ```
 
 As a pre-commit hook:
@@ -346,7 +357,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.4.0
+    rev: v0.4.1
     hooks:
       - id: residoo
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.4.0",
+  "version": "0.4.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/report.js

@@ -155,30 +155,88 @@ function renderRotationSection(rotation, { noColor = false, showAdvisory = false
     push(`  ${paint(c.red + c.bold, "⚠  " + wrapped[0])}`);
     for (const l of wrapped.slice(1)) push(`  ${paint(c.red, l)}`);
   }
-  // Same anti-flood policy as the by-file table: a report is a summary, not a
-  // dump. Everything elided here is in --json in full.
-  const MAX_SHOWN = 12;
-  const shown = entries.slice(0, MAX_SHOWN);
+  // Grouped by rule, not one row per finding: with several distinct values
+  // of the same credential type pending, the old flat list repeated the
+  // exact same rotation URL once per finding, all noise, no signal.
+  // Guidance now prints once per credential TYPE; what actually differs
+  // between two findings of the same type is which value and where, so
+  // that's what each row shows: the redacted preview (the one piece of
+  // information that lets a reader tell "this looks like my prod key" from
+  // "this looks like the placeholder ending in HERE" without cross-checking
+  // anything else) and how many files it's in, with the fingerprint kept
+  // but de-emphasized, still there for `ack`/`dismiss` but no longer the
+  // only thing on the line.
+  const groups = new Map(); // ruleId -> { label, entries: [] }
+  for (const e of entries) {
+    if (!groups.has(e.ruleId)) groups.set(e.ruleId, { label: e.label, entries: [] });
+    groups.get(e.ruleId).entries.push(e);
+  }
+  // Group order: any group with at least one pending entry first (matches
+  // the report's own "what needs attention" priority throughout), fully
+  // resolved groups after, alphabetical by label within each tier.
+  const groupList = [...groups.values()].sort((a, b) => {
+    const aPending = a.entries.some((e) => e.status === "pending");
+    const bPending = b.entries.some((e) => e.status === "pending");
+    if (aPending !== bPending) return aPending ? -1 : 1;
+    return a.label < b.label ? -1 : 1;
+  });
+
   const STATUS_TAG = {
     pending: paint(c.yellow, "pending  "),
     acked: paint(c.green, "acked    "),
     dismissed: paint(c.dim, "dismissed"),
   };
-  for (const e of shown) {
-    push(`  ${STATUS_TAG[e.status]}  ${e.fingerprint}  ${e.label}`);
-    if (e.status === "acked") {
-      push(paint(c.dim, `           acknowledged ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""}`));
-    } else if (e.status === "dismissed") {
-      push(paint(c.dim, `           dismissed ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""} (not a real secret)`));
-    } else {
-      const g = e.guidance;
-      const where = g.rotateUrl ? `rotate: ${g.rotateUrl}` : `where: ${g.consolePath}`;
-      push(paint(c.dim, `           ${where}`));
+  // Same anti-flood policy as the by-file table: a report is a summary, not
+  // a dump. Everything elided here is in --json in full. Counted in
+  // individual findings, not groups, so the cap means the same thing here
+  // as it always has.
+  const MAX_SHOWN = 12;
+  let shownCount = 0;
+  let elided = 0;
+  for (const g of groupList) {
+    if (shownCount >= MAX_SHOWN) { elided += g.entries.length; continue; }
+    push();
+    const g0 = g.entries[0];
+    const where = g0.guidance.rotateUrl ? `rotate: ${g0.guidance.rotateUrl}` : `where: ${g0.guidance.consolePath}`;
+    push(`  ${paint(c.bold, g.label)}`);
+    push(paint(c.dim, `    ${where}`));
+    for (const e of g.entries) {
+      if (shownCount >= MAX_SHOWN) { elided++; continue; }
+      shownCount++;
+      // e.files always has exactly one entry: the fingerprint is derived
+      // from this same basename (see fingerprintFinding in rotation.js), so
+      // two findings only ever merge into one entry when they share it. Same
+      // discipline as the "By file:" table: a filename is attacker-
+      // controllable text (a hostile --project checkout picks its own
+      // names), so it goes through safeBasename before it ever reaches the
+      // terminal, control bytes stripped, invisible code points made visible.
+      const fileNote = safeBasename(e.files[0]);
+      // Last SEEN, not last used or last rotated: the most recent transcript
+      // occurrence residoo found, nothing more. There is no reliable way to
+      // tell from a local scan whether an older value of the same rule type
+      // was superseded by a newer one, both because most credential formats
+      // (AWS access keys, vendor API tokens) carry no shared identifier
+      // linking a rotated key to its predecessor, and because residoo makes
+      // no network calls to ask the provider. Two distinct pending values of
+      // 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;
+      push(`    ${STATUS_TAG[e.status]}  ${e.preview}  ${paint(c.dim, fileNote)}` +
+        (lastSeenNote ? `  ${paint(c.dim, lastSeenNote)}` : ""));
+      if (e.status === "acked") {
+        push(paint(c.dim, `               acknowledged ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""} · ${e.fingerprint}`));
+      } else if (e.status === "dismissed") {
+        push(paint(c.dim, `               dismissed ${e.ackedAt || "(no timestamp)"}${e.ackNote ? `: ${e.ackNote}` : ""} (not a real secret) · ${e.fingerprint}`));
+      } else {
+        push(paint(c.dim, `               ${e.fingerprint}`));
+      }
     }
   }
-  if (entries.length > shown.length) {
-    push(paint(c.dim, `  … and ${entries.length - shown.length} more; see --json for the full list`));
+  if (elided > 0) {
+    push();
+    push(paint(c.dim, `  … and ${elided} more; see --json for the full list`));
   }
+  push();
   push(paint(c.dim, `  Full runbook: residoo explain <rule-id> · rotated: residoo ack <fp> · not a secret: residoo dismiss <fp>`));
   return lines.join("\n");
 }

package/src/rotation.js

@@ -888,6 +888,7 @@ function renderRotation(findings, acks, dismissed = {}) {
         status: st.status,
         ackedAt: st.ackedAt,
         ackNote: st.ackNote,
+        lastSeenMs: null,
       };
       byFp.set(st.fingerprint, e);
     }
@@ -896,6 +897,14 @@ function renderRotation(findings, acks, dismissed = {}) {
     if (rel && !e.files.includes(rel)) e.files.push(rel);
     const src = f.source != null ? String(f.source) : null;
     if (src && !e.sources.includes(src)) e.sources.push(src);
+    // Most recent occurrence across all files this value showed up in: the
+    // 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.
+    if (typeof f.fileMTimeMs === "number" && (e.lastSeenMs === null || f.fileMTimeMs > e.lastSeenMs)) {
+      e.lastSeenMs = f.fileMTimeMs;
+    }
   }
 
   const entries = [...byFp.values()].sort((a, b) => {