residoo 0.10.0 → 0.12.0

package/README.md

@@ -51,8 +51,10 @@ into the conversation at all — which also means a long session compacting
 away the exact value you pasted days ago can't force you to paste it
 again, since there's nothing to lose. `residoo guard` blocks an obviously
 sensitive file read before it happens (100% recall, 0% false positives on
-its own [scored 81-case corpus](bench/guard/RESULTS.md)). All four are
-covered in [docs/features.md](docs/features.md).
+its own [scored 81-case corpus](bench/guard/RESULTS.md)) and, via a second
+hook, a secret typed directly into the prompt itself — confirmed against
+Claude Code's own docs to block before the model ever processes it. All
+four are covered in [docs/features.md](docs/features.md).
 
 > [!NOTE]
 > gitleaks and trufflehog scan **commits**. residoo scans the **conversation
@@ -97,7 +99,7 @@ while losing rows, then fixed in public against the classes it was losing
 
 ## What it does
 
-- Scans your local AI-agent session transcripts for 79 high-confidence
+- Scans your local AI-agent session transcripts for 84 high-confidence
   secret patterns: cloud provider keys, private key blocks, OAuth/API
   tokens, database connection strings, and more. See
   [`src/patterns.js`](src/patterns.js).
@@ -138,7 +140,8 @@ while losing rows, then fixed in public against the classes it was losing
   for CI and pre-commit. See [docs/ci.md](docs/ci.md).
 - `residoo watch` / `residoo mcp` / `residoo cred` / `residoo guard`:
   continuous scanning, conversational queries, credential injection
-  without pasting, and pre-read blocking. See [docs/features.md](docs/features.md).
+  without pasting, and blocking a sensitive file read or a sensitive
+  prompt before either happens. See [docs/features.md](docs/features.md).
 
 ## What it does not do
 

package/package.json

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

@@ -218,24 +218,47 @@ 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
+  residoo guard             one binary, two Claude Code hooks, dispatched on
+                          the payload's own hook_event_name:
+
+                          PreToolUse blocks an obviously-sensitive file read
+                          (.env, id_rsa, .aws/credentials, and similar)
+                          before it can be written to the session
+                          transcript at all. 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 alone cannot catch
+                          a secret typed into a prompt or one arriving
+                          through an unrelated command's output.
+
+                          UserPromptSubmit closes exactly that gap: it
+                          checks the user's own typed prompt against
+                          residoo's 79 high-confidence rules (never
+                          --verify, never --ocr -- this hook has no matcher
+                          and fires on every single prompt, so it must stay
+                          fast) and can block it before Claude processes it
+                          at all -- confirmed directly against Claude
+                          Code's own docs, not assumed. A block ERASES the
+                          user's whole typed message, so this path is
+                          extra-conservative: a documented vendor-example
+                          key or an obvious placeholder is suppressed, same
+                          as residoo scan itself. Best-effort, not a
+                          guarantee: per Claude Code's own docs, a slow
+                          hook here fails OPEN (the prompt goes through
+                          unscanned) rather than stalling the session,
+                          consistent with this hook never blocking on
+                          anything it doesn't recognize.
+
+                          scan/watch/mcp remain the real safety net either
+                          way -- this is prevention on top of detection,
+                          not a replacement for it. Add both to
                           .claude/settings.json:
-                            {"hooks":{"PreToolUse":[{"matcher":"Bash|Read",
-                            "hooks":[{"type":"command",
-                            "command":"residoo guard"}]}]}}
+                            {"hooks":{
+                              "PreToolUse":[{"matcher":"Bash|Read",
+                                "hooks":[{"type":"command",
+                                "command":"residoo guard"}]}],
+                              "UserPromptSubmit":[{"hooks":[{"type":"command",
+                                "command":"residoo guard"}]}]}}
 
 Rotation:
   residoo explain <rule-id>     full rotation runbook for one detection rule

package/src/guard.js

@@ -1,9 +1,11 @@
 "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.
+ * `residoo guard`: two Claude Code hooks in one binary, dispatched on the
+ * payload's own `hook_event_name` field.
+ *
+ * PreToolUse 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
@@ -17,17 +19,53 @@
  * 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.
+ *
+ * UserPromptSubmit closes exactly the "typed directly into a prompt" gap
+ * named above: Claude Code's own docs (code.claude.com/docs/en/hooks,
+ * fetched and read directly, not summarized secondhand) confirm this hook
+ * "runs before every prompt and blocks model processing until it
+ * completes" -- a real prevention point, not an after-the-fact alert.
+ * Verified precisely, not assumed: the payload's `prompt` field carries the
+ * exact submitted text (the field is `prompt`, NOT `user_prompt` -- a
+ * specific claim to the contrary did not survive this session's own
+ * adversarial verification pass), and a JSON response with
+ * `"decision": "block"` "prevents the prompt from being processed and
+ * erases it from context." Checked against residoo's existing 79
+ * high-confidence PATTERNS.js rules ONLY -- never NOISY_PATTERNS, never
+ * --verify (a network call), never --ocr (tesseract, and irrelevant to a
+ * text prompt anyway) -- because this hook has NO matcher support (it
+ * fires on every single prompt in every session, confirmed in the same
+ * docs) and must stay fast: Claude Code's own default timeout for this
+ * event's command hooks is 30s, down from 600s elsewhere, specifically
+ * because "a stuck hook stalls the session." A false positive here also
+ * costs more than a PreToolUse block: it erases the user's entire typed
+ * message, not one denied tool call, which is why this path additionally
+ * runs the same vendor-example/placeholder suppression `residoo scan`
+ * itself uses (see scan.js's VENDOR_EXAMPLE_VALUES/zeroEntropyTail) before
+ * ever blocking -- a documented AWS example key or an obvious placeholder
+ * must never eat a real prompt.
+ *
+ * Same fail-open timeout reality as scan.js's whole 30-vendor --verify
+ * surface, disclosed rather than hidden: per Claude Code's own docs, a
+ * command/http/mcp_tool hook (this one) that times out on UserPromptSubmit
+ * has its output discarded and "the prompt still reaches Claude" unblocked
+ * -- a genuinely slow scan cannot stall the session, but that also means
+ * this is best-effort, additive coverage, not an absolute guarantee, the
+ * same honesty already applied to --ocr.
  *
  * 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.
+ * is silently hang or crash the agent's turn over a tool call -- or a
+ * prompt -- that was always going to be fine. `residoo scan`/`watch`/`mcp`
+ * remain the actual safety net; this is a narrower, best-effort tripwire on
+ * top, not a replacement for them.
  */
 
+const { PATTERNS, redact } = require("./patterns");
+const { VENDOR_EXAMPLE_VALUES, zeroEntropyTail } = require("./scan");
+
 // 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
@@ -127,12 +165,49 @@ function evaluateToolInput(toolName, toolInput) {
   };
 }
 
+// High-confidence only, computed once at module load (PATTERNS is a static
+// array): never NOISY_PATTERNS, matching the same elevated bar decodeLine/
+// ocrLine already use in scan.js for content one step removed from a plain
+// file line -- a user's own live-typed prompt deserves at least that same
+// bar, arguably a higher one given what a wrong block costs here (see this
+// file's own docstring).
+const PROMPT_GUARD_RULES = PATTERNS.filter((r) => r.confidence === "high");
+
+/**
+ * Pure decision function: given a UserPromptSubmit hook payload's raw
+ * `prompt` string, decide whether to block. No I/O, fully unit-testable.
+ * Suppresses the same way `residoo scan` does (a documented vendor-example
+ * key, or an obviously-placeholder zero-entropy tail) before ever blocking
+ * -- a false positive here erases the user's entire typed message, not one
+ * denied tool call, so this path is deliberately more conservative than
+ * evaluateToolInput above, not just a copy of the same bar.
+ */
+function evaluatePromptText(promptText) {
+  if (typeof promptText !== "string" || !promptText) return { block: false, 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;
+    return {
+      block: true,
+      reason: `residoo guard: this prompt looks like it contains ${rule.label} (${redact(value)}). ` +
+        `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 };
+}
+
 /**
- * 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.
+ * Reads one PreToolUse OR UserPromptSubmit hook payload from `input`
+ * (default stdin) -- distinguished by the payload's own `hook_event_name`
+ * common field, a single binary handling both the way Claude Code's own
+ * hook registration allows -- 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 = [];
@@ -146,6 +221,20 @@ async function runGuard({ input = process.stdin, output = process.stdout } = {})
     return 0; // malformed payload: fail open, never block on something we can't parse
   }
 
+  // hook_event_name is a documented COMMON field present on every hook
+  // event's payload (code.claude.com/docs/en/hooks), not specific to one
+  // event -- checked first so a UserPromptSubmit payload (which has no
+  // tool_name/tool_input at all) never falls through to evaluateToolInput
+  // and is instead routed to its own decision function and its own
+  // response shape (decision:"block", not hookSpecificOutput.
+  // permissionDecision -- the two events do not share a response schema).
+  if (payload.hook_event_name === "UserPromptSubmit") {
+    const decision = evaluatePromptText(payload.prompt);
+    if (!decision.block) return 0;
+    output.write(JSON.stringify({ decision: "block", reason: decision.reason }) + "\n");
+    return 0;
+  }
+
   const decision = evaluateToolInput(payload.tool_name, payload.tool_input);
   if (!decision.block) return 0;
 
@@ -159,4 +248,4 @@ async function runGuard({ input = process.stdin, output = process.stdout } = {})
   return 0;
 }
 
-module.exports = { evaluateToolInput, matchSensitivePath, runGuard, SENSITIVE_PATH_PATTERNS };
+module.exports = { evaluateToolInput, matchSensitivePath, evaluatePromptText, runGuard, SENSITIVE_PATH_PATTERNS };

package/src/patterns.js

@@ -539,6 +539,49 @@ const PATTERNS = [
   // same bare/opaque shape already excluded elsewhere in this file.
   { id: "akamai_edgegrid_token", label: "Akamai EdgeGrid token", confidence: "high",
     re: /\bakab-[a-z0-9]{16,32}-[a-z0-9]{6,32}\b/g },
+  // Doppler: seven distinct token kinds, all sharing the same dp.<tag>.
+  // structure. Confirmed via Doppler's own docs
+  // (docs.doppler.com/reference/auth-token-formats), which state plainly
+  // that "each token type uses a distinct prefix to enable identification
+  // during secret scanning operations" -- a format designed to be
+  // regex-detected, not inferred. Service tokens (dp.st.) alone carry an
+  // optional environment segment between the tag and the body; every other
+  // kind goes straight from the tag to the 40-44-char body.
+  { id: "doppler_token", label: "Doppler token", confidence: "high",
+    re: /\bdp\.(?:ct|pt|sa|said|scim|audit)\.[A-Za-z0-9]{40,44}\b|\bdp\.st\.(?:[a-z0-9_-]{2,35}\.)?[A-Za-z0-9]{40,44}\b/g },
+  // Postman API key. Postman's own docs describe how to generate one but
+  // not its literal format; sourced instead from gitleaks' own
+  // production-tested rule (config/gitleaks.toml, id "postman-api-token"),
+  // same tier as azure_ad_client_secret's sourcing earlier in this file.
+  { id: "postman_token", label: "Postman API key", confidence: "high",
+    re: /\bPMAK-[a-f0-9]{24}-[a-f0-9]{34}\b/gi },
+  // Figma personal access token. Figma's own docs don't publish the
+  // format either; sourced from trufflehog's own shipped detectors, which
+  // track two real, distinct generations: figd_ (the long-established
+  // form, trufflehog's v2 detector) and figp_ (a newer form, trufflehog's
+  // v3 detector, no keyword-proximity needed unlike v1's bare UUID shape,
+  // which is NOT included here for the same reason Bitbucket's keyword-
+  // dependent Client ID/Secret rules were declined -- no distinctive
+  // standalone prefix).
+  { id: "figma_token", label: "Figma personal access token", confidence: "high",
+    re: /\bfig[dp]_[A-Za-z0-9_=-]{40,54}\b/g },
+  // Bitbucket App Password (distinct from Bitbucket's Client ID/Secret,
+  // declined elsewhere in this file's history for being keyword-dependent
+  // with no standalone prefix). Confirmed via an Atlassian staff reply on
+  // Atlassian's own community forum naming ATBB as the current App
+  // Password prefix -- the same source already used for atlassian_api_token.
+  { id: "bitbucket_app_password", label: "Bitbucket App Password", confidence: "high",
+    re: /\bATBB[a-zA-Z0-9]{32}\b/g },
+  // SonarQube/SonarCloud token. gitleaks' own rule needs "sonar" keyword
+  // proximity because its body class also has to catch a bare unprefixed
+  // 40-char fallback -- unsafe as a standalone rule, so only the three
+  // confirmed literal prefixes are used here, which need no such context.
+  // squ_/sqp_/sqa_ confirmed real and current via SonarSource's own docs
+  // (docs.sonarsource.com), whose own worked example (sqp_ followed by
+  // 1aa323...8a1d13) is added to VENDOR_EXAMPLE_VALUES in scan.js as a
+  // documented example, not a findable secret.
+  { id: "sonarqube_token", label: "SonarQube/SonarCloud token", confidence: "high",
+    re: /\b(?:squ|sqp|sqa)_[a-z0-9=_-]{40}\b/g },
 ];
 
 /**

package/src/rotation.js

@@ -1093,6 +1093,58 @@ const ROTATION_GUIDANCE = {
     ],
     revokeNote: "Deactivation is immediate; anything still using the old credential starts failing authentication at once.",
   },
+  // docs.doppler.com/reference/auth-token-formats confirms the prefix
+  // table; the tokens page itself is login-walled.
+  doppler_token: {
+    label: "Doppler token",
+    consolePath: "dashboard.doppler.com > the relevant project/workplace > Access > Tokens (or Service Tokens / Service Accounts, matching which prefix leaked)",
+    steps: [
+      "Identify which token kind leaked from its prefix (dp.pt. personal, dp.st. service, dp.sa. service account, dp.scim. SCIM, dp.audit. audit log)",
+      "Revoke it from that kind's own settings page",
+      "Create a replacement and update whatever used the old one",
+    ],
+    revokeNote: "A dp.sa. (Service Account) or dp.st. (Service Token) leak can reach every secret in its assigned project/config -- treat it as broader than a personal token leak.",
+  },
+  postman_token: {
+    label: "Postman API key",
+    consolePath: "Postman > Settings (gear icon) > API keys",
+    steps: [
+      "Open API keys under your account settings",
+      "Delete the leaked key",
+      "Generate a replacement and update whatever used the old one",
+    ],
+    revokeNote: "Deletion is immediate; anything still using the old key starts failing authentication at once.",
+  },
+  figma_token: {
+    label: "Figma personal access token",
+    consolePath: "Figma > account Settings > Personal access tokens",
+    steps: [
+      "Open Personal access tokens under account Settings",
+      "Revoke the leaked token",
+      "Create a replacement and update whatever used the old one",
+    ],
+    revokeNote: "Revocation is immediate; anything still using the old token starts failing authentication at once.",
+  },
+  bitbucket_app_password: {
+    label: "Bitbucket App Password",
+    consolePath: "id.atlassian.com > Security > App passwords",
+    steps: [
+      "Open App passwords under account Security settings",
+      "Delete the leaked app password",
+      "Create a replacement with the narrowest scopes it needs",
+    ],
+    revokeNote: "Atlassian is steering users toward API tokens/Access tokens instead of App Passwords -- consider migrating rather than just replacing like-for-like.",
+  },
+  sonarqube_token: {
+    label: "SonarQube/SonarCloud token",
+    consolePath: "SonarQube/SonarCloud > My Account > Security",
+    steps: [
+      "Open the Security tab under My Account",
+      "Revoke the leaked token",
+      "Generate a replacement and update whatever used the old one",
+    ],
+    revokeNote: "Revocation is immediate; anything still using the old token starts failing authentication at once.",
+  },
 
   // ── NOISY_PATTERNS (only reachable via --include-noisy) ───────────────
   generic_password_assignment: {

package/src/scan.js

@@ -217,6 +217,11 @@ function zeroEntropyTail(value) {
 const VENDOR_EXAMPLE_VALUES = new Set([
   "AKIAIOSFODNN7EXAMPLE",
   "AKIAI44QH8DHBEXAMPLE",
+  // SonarSource's own worked example, repeated across its docs.sonarsource.com
+  // documentation (an API-key usage snippet, not a "this is our example
+  // secret" callout page, but used identically and repeatedly the same way
+  // AWS's own documented example key is).
+  "sqp_" + "1aa323ae0689cd4a1abd062a2ad0a224ae8a1d13",
   "ghp_16C7e42F292c6912E7710c838347Ae178B4a",
   "gho_16C7e42F292c6912E7710c838347Ae178B4a",
   "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
@@ -943,4 +948,4 @@ function emptyResult() {
 // 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 };
+module.exports = { scan, emptyResult, VENDOR_EXAMPLE_VALUES, VERIFIABLE_RULE_IDS, zeroEntropyTail };