residoo 0.12.0 → 0.14.0

package/package.json

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

@@ -150,6 +150,14 @@ Scan options:
                           similar characters (0/O, Y/*) can be misread,
                           which breaks an exact-format match, so this is
                           best-effort additional coverage, not a guarantee.
+  --include-pii           also scan for PII: US Social Security Numbers
+                          (dashed format only), credit card numbers
+                          (Luhn-validated), and IBANs (checksum-validated).
+                          A different RISK CATEGORY, not a lower confidence
+                          bar -- residoo is deliberately credentials-only
+                          by default. Deliberately excludes bare email/
+                          phone (too common in ordinary text to meet this
+                          project's own high-confidence bar even opt-in).
 
 Watch:
   residoo watch            continuous scanning instead of one snapshot:
@@ -918,6 +926,12 @@ async function main(argv) {
   // exact confirmed image shape this looks for and its honest accuracy
   // limitations.
   const wantsOcr = args.includes("--ocr");
+  // --include-pii: a different RISK CATEGORY, not a lower confidence bar
+  // (see pii.js) -- residoo is deliberately credentials-only by default;
+  // this opts into three checksum-validated categories (SSN, Luhn-valid
+  // card numbers, IBAN) rather than the shape-only, much noisier
+  // categories (bare email, phone) some competitors also ship.
+  const wantsPii = args.includes("--include-pii");
 
   // --project [dir]: the dir is optional (CI passes ".", a bare --project
   // means the current directory). null means machine mode.
@@ -1029,7 +1043,7 @@ async function main(argv) {
 
   const progress = makeProgressReporter(noColor);
   const result = await scan({
-    sources, includeNoisy, includeSuppressed, verify, noColor, ocr: wantsOcr,
+    sources, includeNoisy, includeSuppressed, verify, noColor, ocr: wantsOcr, includePii: wantsPii,
     onProgress: progress.onProgress,
     // Clears the spinner's last frame before --verify's own stderr lines
     // print; without this the last spinner line sits uncleared on screen

package/src/guard.js

@@ -153,13 +153,14 @@ const GUARDED_TOOL_NAMES = new Set(["Bash", "Read"]);
  */
 function evaluateToolInput(toolName, toolInput) {
   if (!GUARDED_TOOL_NAMES.has(toolName) || !toolInput || typeof toolInput !== "object") {
-    return { block: false, reason: null };
+    return { block: false, label: null, reason: null };
   }
   const candidate = toolName === "Bash" ? toolInput.command : toolInput.file_path;
   const label = matchSensitivePath(candidate);
-  if (!label) return { block: false, reason: null };
+  if (!label) return { block: false, label: null, reason: null };
   return {
     block: true,
+    label,
     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.`,
   };
@@ -183,20 +184,44 @@ const PROMPT_GUARD_RULES = PATTERNS.filter((r) => r.confidence === "high");
  * evaluateToolInput above, not just a copy of the same bar.
  */
 function evaluatePromptText(promptText) {
-  if (typeof promptText !== "string" || !promptText) return { block: false, reason: null };
+  if (typeof promptText !== "string" || !promptText) return { block: false, label: null, preview: null, reason: null };
   for (const rule of PROMPT_GUARD_RULES) {
     rule.re.lastIndex = 0;
     const m = rule.re.exec(promptText);
     if (!m) continue;
     const value = m[0];
     if (VENDOR_EXAMPLE_VALUES.has(value) || zeroEntropyTail(value)) continue;
+    const preview = redact(value);
     return {
       block: true,
-      reason: `residoo guard: this prompt looks like it contains ${rule.label} (${redact(value)}). ` +
+      label: rule.label,
+      preview,
+      reason: `residoo guard: this prompt looks like it contains ${rule.label} (${preview}). ` +
         `Blocked before it could be sent. If this is a false positive, rephrase or remove it, or disable this hook in .claude/settings.json.`,
     };
   }
-  return { block: false, reason: null };
+  return { block: false, label: null, preview: null, reason: null };
+}
+
+/**
+ * Writes one structured audit line to stderr for a block decision --
+ * CONTRIBUTING.md's own hard rule (rule 3) names `~/.residoo/rotations.json`
+ * as "the only file residoo ever writes outside an explicit --seal...
+ * nothing else may claim this carve-out," so this is NOT a new file, the
+ * same choice `cred`'s own audit trail already made for the same reason
+ * (see src/credRun.js). Durability is the operator's choice: redirect the
+ * hook's own stderr at launch if you want it kept, same as `cred`.
+ * Never the raw matched value -- `preview` is already redact()'d by the
+ * caller (rule 4: no raw value in any log line, ever), and PreToolUse
+ * decisions carry no value at all, only a path-pattern label.
+ */
+function logAuditLine(errOutput, { event, label, preview, sessionId, cwd }) {
+  try {
+    errOutput.write(JSON.stringify({
+      ts: new Date().toISOString(), tool: "residoo guard", event, decision: "block",
+      label, ...(preview ? { preview } : {}), sessionId: sessionId || null, cwd: cwd || null,
+    }) + "\n");
+  } catch { /* stderr write failing is never a reason to fail the hook decision itself */ }
 }
 
 /**
@@ -207,9 +232,11 @@ function evaluatePromptText(promptText) {
  * 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.
+ * function in cli.js. Every BLOCK decision also gets one structured line
+ * on `errOutput` (default stderr) -- see logAuditLine's own docstring for
+ * why stderr, never a file.
  */
-async function runGuard({ input = process.stdin, output = process.stdout } = {}) {
+async function runGuard({ input = process.stdin, output = process.stdout, errOutput = process.stderr } = {}) {
   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");
@@ -231,6 +258,10 @@ async function runGuard({ input = process.stdin, output = process.stdout } = {})
   if (payload.hook_event_name === "UserPromptSubmit") {
     const decision = evaluatePromptText(payload.prompt);
     if (!decision.block) return 0;
+    logAuditLine(errOutput, {
+      event: "UserPromptSubmit", label: decision.label, preview: decision.preview,
+      sessionId: payload.session_id, cwd: payload.cwd,
+    });
     output.write(JSON.stringify({ decision: "block", reason: decision.reason }) + "\n");
     return 0;
   }
@@ -238,6 +269,10 @@ async function runGuard({ input = process.stdin, output = process.stdout } = {})
   const decision = evaluateToolInput(payload.tool_name, payload.tool_input);
   if (!decision.block) return 0;
 
+  logAuditLine(errOutput, {
+    event: "PreToolUse", label: decision.label,
+    sessionId: payload.session_id, cwd: payload.cwd,
+  });
   output.write(JSON.stringify({
     hookSpecificOutput: {
       hookEventName: "PreToolUse",

package/src/pii.js

@@ -0,0 +1,96 @@
+"use strict";
+
+/**
+ * Opt-in PII detection (--include-pii). Named directly by this session's
+ * own competitive research into funded AI-DLP vendors (Strac, Cyberhaven,
+ * Nightfall) as one of the few concrete, buildable things residoo could
+ * adopt without becoming a hosted service -- and independently
+ * corroborated by two direct competitors' own shipped detector lists
+ * (DidILeak, Medusa), both of which cover PII alongside credentials.
+ *
+ * Kept entirely separate from PATTERNS/NOISY_PATTERNS in patterns.js on
+ * purpose: residoo's stated identity elsewhere in this project is
+ * "deliberately credentials-only" (see docs/comparison.md's DidILeak
+ * section), and this module doesn't change that default -- it's a
+ * separate, explicitly opt-in category a user has to ask for, the same
+ * relationship NOISY_PATTERNS already has to the default rule set, just
+ * for a different reason (a different RISK CATEGORY, not a lower
+ * confidence bar).
+ *
+ * Only three detectors, deliberately: DidILeak's own shipped list also
+ * includes bare email addresses and phone numbers, but both are far too
+ * common in ordinary, non-sensitive text (a support email in a comment, a
+ * phone number in an error message) to meet this project's own
+ * "high-confidence only, a security tool that cries wolf gets
+ * uninstalled" bar, opt-in or not -- DidILeak itself rates them "low"/
+ * "info" severity for the same reason. The three included here all have a
+ * REAL mathematical validator, not just a shape match, which is what
+ * keeps false-positive risk low enough to ship even as an additive
+ * category: Luhn for card numbers, ISO 7064 MOD 97-10 for IBAN, and the
+ * Social Security Administration's own published invalid-range rules for
+ * SSNs (no checksum exists for SSNs, hence "medium" confidence there, not
+ * "high" -- disclosed, not smoothed over).
+ */
+
+/** Luhn checksum (ISO/IEC 7812-1): the standard validator for payment card numbers. `digits` must already be digits-only. */
+function luhnValid(digits) {
+  let sum = 0;
+  let alt = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = digits.charCodeAt(i) - 48;
+    if (alt) { d *= 2; if (d > 9) d -= 9; }
+    sum += d;
+    alt = !alt;
+  }
+  return sum % 10 === 0;
+}
+
+/**
+ * ISO 7064 MOD 97-10 (the IBAN checksum): move the first 4 characters to
+ * the end, map letters to numbers (A=10..Z=35), and the whole numeral must
+ * be congruent to 1 mod 97. Computed digit-by-digit since the numeral is
+ * far larger than any JS integer.
+ *
+ * Scope, disclosed rather than assumed complete: this checks the generic
+ * ISO 13616 structural rule and the checksum, not each of the ~70
+ * IBAN-issuing countries' own exact fixed length (a German IBAN is always
+ * 22 characters, a French one always 27) -- a real per-country length
+ * table would need to be built and kept current; the checksum alone
+ * already rejects the overwhelming majority of non-IBAN digit/letter runs.
+ */
+function ibanValid(iban) {
+  if (iban.length < 15 || iban.length > 34) return false;
+  const rearranged = iban.slice(4) + iban.slice(0, 4);
+  let mod = 0;
+  for (const ch of rearranged) {
+    const code = ch.charCodeAt(0);
+    const value = code >= 65 && code <= 90 ? code - 55 : code - 48; // A-Z -> 10-35, else digit
+    if (value < 0 || value > 35) return false;
+    const digits = value >= 10 ? String(value) : ch;
+    for (const d of digits) mod = (mod * 10 + (d.charCodeAt(0) - 48)) % 97;
+  }
+  return mod === 1;
+}
+
+const PII_PATTERNS = [
+  // Dashed format only -- a bare 9-digit run is indistinguishable from
+  // countless other numbers in a coding-agent transcript (ports, PIDs,
+  // timestamps) and would make this rule pure noise. Invalid-range
+  // exclusions are the Social Security Administration's own published
+  // rules: area 000, 666, and 900-999 were never issued; group 00 and
+  // serial 0000 are never valid within an otherwise-real-shaped number.
+  { id: "us_ssn", label: "US Social Security Number", confidence: "medium",
+    re: /\b(?!000|666|9\d{2})\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/g },
+  // Candidate digit runs (13-19 digits, ISO/IEC 7812's own real-world
+  // range, optionally space- or dash-separated the way a human actually
+  // types a card number) are Luhn-validated below before ever being
+  // reported -- the regex alone is not the detector.
+  { id: "credit_card_number", label: "Credit card number (Luhn-validated)", confidence: "high",
+    re: /\b\d(?:[ -]?\d){12,18}\b/g,
+    validate: (m) => { const d = m.replace(/[ -]/g, ""); return d.length >= 13 && d.length <= 19 && luhnValid(d); } },
+  { id: "iban", label: "IBAN (checksum-validated)", confidence: "high",
+    re: /\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b/g,
+    validate: (m) => ibanValid(m) },
+];
+
+module.exports = { PII_PATTERNS, luhnValid, ibanValid };

package/src/report.js

@@ -534,15 +534,18 @@ function renderJson(result, integrity = null, rotation = null) {
         rule: f.ruleId, label: f.label, confidence: f.confidence,
         source: f.source, file: f.relFile, line: f.line, preview: f.preview,
         fileMTimeMs: f.fileMTimeMs,
-        // Markers for the decode/reconstruct/OCR passes (absent on ordinary
-        // findings). `encoding` names how the value was wrapped ("base64" /
-        // "base64url"); `spanLines` names the adjacent line pair a split value
-        // was reconstructed across; `ocr` means the value was never plain
-        // text at all -- it was read out of a pasted or tool-returned image
-        // (see ocr.js).
+        // Markers for the decode/reconstruct/OCR/PII passes (absent on
+        // ordinary findings). `encoding` names how the value was wrapped
+        // ("base64" / "base64url"); `spanLines` names the adjacent line
+        // pair a split value was reconstructed across; `ocr` means the
+        // value was never plain text at all -- it was read out of a
+        // pasted or tool-returned image (see ocr.js); `pii` means this is
+        // a --include-pii finding, a different risk category from a
+        // credential, not a rule from the default set (see pii.js).
         ...(f.encoding ? { encoding: f.encoding } : {}),
         ...(f.spanLines ? { spanLines: f.spanLines } : {}),
         ...(f.ocr ? { ocr: true } : {}),
+        ...(f.pii ? { pii: true } : {}),
         fingerprint: fingerprintFinding(f),
         // Only present on an --include-suppressed run: says WHY this finding
         // is low-confidence, so a JSON consumer doesn't have to guess.

package/src/rotation.js

@@ -1146,6 +1146,42 @@ const ROTATION_GUIDANCE = {
     revokeNote: "Revocation is immediate; anything still using the old token starts failing authentication at once.",
   },
 
+  // ── PII (only reachable via --include-pii) ─────────────────────────────
+  // Framed deliberately differently from every entry above: PII has no
+  // issuer to revoke a credential with, no console to rotate it in. The
+  // real action is "should this data exist in this file at all" and, if it
+  // was genuinely exposed to someone who shouldn't have it, who to tell.
+  us_ssn: {
+    label: "US Social Security Number",
+    consolePath: "There is no vendor console for this -- an SSN can't be rotated the way a credential can.",
+    steps: [
+      "Confirm this is a real SSN and not a placeholder/test value (no checksum exists for SSNs, so this rule has no mathematical validator behind it, unlike the two below)",
+      "Remove it from the transcript file if it doesn't need to be there (residoo scan --seal quarantines the whole file without deleting anything, if you want a reversible first step)",
+      "If it was genuinely exposed to someone who shouldn't have it, that's an identity-theft exposure, not an account compromise -- the affected person (you, a customer, an employee) may want to consider a credit freeze or fraud alert with the credit bureaus, not \"rotate a key\"",
+    ],
+    revokeNote: "Unlike every credential rule in this file, there is no revoke/rotate action available at all -- the number itself doesn't change.",
+  },
+  credit_card_number: {
+    label: "Credit card number (Luhn-validated)",
+    consolePath: "The card issuer's own fraud/support line, or your payment processor's dashboard if this is a customer's card, not your own.",
+    steps: [
+      "If it's your own card, most issuers let you freeze or reissue it from their app without waiting for a physical replacement",
+      "If it's a customer's or someone else's card, tell them directly -- they need to contact their own issuer, you can't act on their behalf",
+      "Remove it from the transcript file if it doesn't need to be there",
+    ],
+    revokeNote: "This passed a real Luhn checksum, so it is very unlikely to be a random-looking placeholder -- treat it as a real card number until shown otherwise.",
+  },
+  iban: {
+    label: "IBAN (checksum-validated)",
+    consolePath: "The account holder's own bank.",
+    steps: [
+      "An IBAN alone (without the account holder's separate authentication, e.g. a SEPA mandate) can't usually initiate a transfer by itself, but it's still a real bank account identifier -- treat exposure as a privacy issue even where it isn't immediately a fraud one",
+      "If it's your own account and you're concerned, your bank can advise on IBAN-specific fraud monitoring",
+      "Remove it from the transcript file if it doesn't need to be there",
+    ],
+    revokeNote: "This passed the real ISO 7064 MOD 97-10 checksum every valid IBAN must satisfy, so it is very unlikely to be a random-looking placeholder.",
+  },
+
   // ── NOISY_PATTERNS (only reachable via --include-noisy) ───────────────
   generic_password_assignment: {
     label: "Password assignment (noisy rule)",

package/src/scan.js

@@ -4,6 +4,7 @@ const path = require("path");
 const { PATTERNS, NOISY_PATTERNS, redact } = require("./patterns");
 const { findDecodedMatches, findBoundaryMatches, contentProjection } = require("./decode");
 const { isTesseractAvailable, extractImageBlocks, ocrImageBase64 } = require("./ocr");
+const { PII_PATTERNS } = require("./pii");
 const { findPairedSecret, findNearbyCandidate } = require("./pairing");
 const { looksRandom } = require("./rarity");
 const { decodeJwtExpiryMs } = require("./jwtExpiry");
@@ -272,7 +273,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, verifyOnlyFingerprint = null, onBeforeVerify = null, noColor = false, ocr = false } = {}) {
+async function scan({ sources, includeNoisy = false, includeSuppressed = false, onProgress = null, verify = false, verifyOnlyFingerprint = null, onBeforeVerify = null, noColor = false, ocr = false, includePii = false } = {}) {
   const rules = includeNoisy ? PATTERNS.concat(NOISY_PATTERNS) : PATTERNS;
   // --ocr: checked once, not per line/image -- isTesseractAvailable shells
   // out, and this scan can touch thousands of lines. ocrRequestedButMissing
@@ -600,6 +601,34 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
     }
   };
 
+  // --include-pii: a completely separate pass from every rule above, on
+  // purpose -- PII (see pii.js) is a different RISK CATEGORY from a
+  // credential, not just a lower-confidence version of one, so it gets its
+  // own opt-in flag and its own pass rather than being folded into `rules`.
+  // None of matchLine's AWS-pairing/verification machinery applies to PII
+  // at all, so this mirrors decodeLine/ocrLine's simpler shape, not
+  // matchLine's. `validate` (Luhn, IBAN's MOD 97-10) runs before a
+  // candidate is even considered for suppression -- an invalid checksum
+  // is not a "placeholder," it's simply not a match.
+  const piiLine = (line, file, relFile, lineNo, mtimeMs) => {
+    if (!includePii) return;
+    for (const rule of PII_PATTERNS) {
+      rule.re.lastIndex = 0;
+      let m;
+      while ((m = rule.re.exec(line)) !== null) {
+        if (rule.validate && !rule.validate(m[0])) continue;
+        const before = line.slice(Math.max(0, m.index - CONTEXT_WINDOW), m.index);
+        const suppressedReason = suppressionReason(m[0], before, rule.id);
+        if (suppressedReason && !includeSuppressed) {
+          suppressedCount++;
+          continue;
+        }
+        record(rule, m[0], relFile, file, lineNo, mtimeMs,
+          suppressedReason ? "low" : rule.confidence, suppressedReason, { pii: true });
+      }
+    }
+  };
+
   // Feature 2: split-line boundary join. A finding here means one credential
   // was split across this line and the next and is contiguous on neither. It
   // is recorded against BOTH contributing lines (each holds a fragment of the
@@ -717,6 +746,13 @@ async function scan({ sources, includeNoisy = false, includeSuppressed = false,
               flagFailed();
             }
           }
+          if (includePii) {
+            try {
+              piiLine(line, file, relFile, i + 1, mtimeMs);
+            } catch (err) {
+              flagFailed();
+            }
+          }
           try {
             const content = contentProjection(line);
             // Boundary join with the previous line (2-way splits only; see