residoo 0.17.0 → 0.19.0

package/README.md

@@ -72,14 +72,24 @@ observed, not just documented. All 8, not just the closest one:
 | tool | distinct credentials found | precision | egress during the scan |
 |---|---|---|---|
 | **residoo** | **45/45 (100%)** | **100%** | **none-observed** |
-| agentsweep | 33/42 (79%) | 100% | none-observed |
+| agentsweep | 33/42 (79%) | 89% | none-observed |
 | gitleaks | 32/45 (71%) | 100% | none-observed |
-| betterleaks | 32/45 (71%) | 100% | none-observed |
+| betterleaks | 32/45 (71%) | 95% | none-observed |
 | whatileaked | 28/42 (67%) | 100% | none-observed |
-| kingfisher | 29/45 (64%) | 100% | attempts calls in default mode |
+| kingfisher | 29/45 (64%) | 97% | attempts calls in default mode |
 | trufflehog | 29/45 (64%) | 97% | attempts calls in default mode |
 | detect-secrets | 25/45 (56%) | 2% | attempts calls in default mode |
 
+Precision here counts a flagged vendor-documented example key (a real,
+deliberate suppress-placeholder in the corpus) as a false positive, the
+stricter of the two measures `bench/RESULTS.md` reports throughout —
+several tools above score better on the looser "excluding suppress flags"
+measure (e.g. agentsweep and betterleaks both reach 100% there), but this
+is the one that matches what a user actually experiences: a tool that
+flags AWS's own published example key on every run trains people to
+ignore its output. residoo and gitleaks are the only two tools that hit
+100% either way.
+
 "none-observed" is a measured result, not a default assumption: every run
 sits under a live proxy trap and process-tree polling, and a deliberate
 canary connection is fired and confirmed caught *before* each real
@@ -165,6 +175,13 @@ gap, none catches every case, and all are re-includable with
 certainty — true of every tool in this category, including the well-
 established ones.
 
+- **No mobile app.** Researched, not assumed: residoo's file-scanning
+  approach cannot port to stock iOS under Apple's own sandboxing model,
+  and every alternative mechanism checked (a keyboard extension, a local
+  VPN content filter) has a specific, disqualifying problem. See
+  [docs/platform-scope.md](docs/platform-scope.md) for the full technical
+  verdict and what would change it.
+
 ## Install
 
 ```bash

package/package.json

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

@@ -2,6 +2,7 @@
 
 const path = require("path");
 const fs = require("fs");
+const os = require("os");
 const crypto = require("crypto");
 const { availableSources, ALL_SOURCES } = require("./sources");
 const { scan, emptyResult } = require("./scan");
@@ -13,7 +14,7 @@ const {
 const { startWatch, isTailable } = require("./watch");
 const { startMcpServer } = require("./mcp");
 const { buildTools } = require("./mcpTools");
-const { runGuard: runGuardEngine } = require("./guard");
+const { runGuard: runGuardEngine, buildHookConfig } = require("./guard");
 
 /**
  * A source is unavailable for the ordinary reason (not installed — nothing
@@ -183,6 +184,15 @@ Watch:
                           never to one already seen
   --include-noisy, --include-suppressed, --include-pii, --no-color
                           same meaning as scan
+  --no-notify             skip the OS desktop notification watch fires for
+                          each genuinely new finding (macOS via osascript,
+                          Linux via notify-send if installed; no built-in
+                          mechanism on Windows -- disclosed, not attempted).
+                          On by default in human-readable mode: watch's own
+                          purpose is alerting you, and a background process
+                          nobody is watching a terminal for needs more than
+                          a printed line. Never fires for a re-exposure of
+                          something already seen, and never in --json mode.
   Ctrl+C stops cleanly and prints a session summary (skipped with --json,
   where the same information is one final NDJSON event).
 
@@ -207,7 +217,15 @@ MCP:
 Cred:
   residoo cred set <name> --env <ENV_VAR_NAME> [--env <ENV_VAR_NAME_2> ...]
                           store a live credential in the OS keychain
-                          (macOS/Linux only), one or more env-var names
+                          (macOS/Linux only -- genuinely unsupported on
+                          Windows, not just undone yet: this needs a NAMED
+                          store you can write once and read back later,
+                          and Windows has none reachable without an extra
+                          dependency. Different from --seal --keychain
+                          below, which Windows DOES support via DPAPI --
+                          that one only ever needs to wrap/unwrap a key
+                          living inside its own vault directory, never a
+                          named lookup), one or more env-var names
                           mapped to hidden-typed values. Interactive TTY
                           only, no scripted entry: a live credential is
                           more sensitive than a vault passphrase and
@@ -292,6 +310,19 @@ Guard:
                                 "hooks":[{"type":"command",
                                 "command":"residoo guard"}]}]}}
 
+  residoo guard --print-config
+                          print that same merged JSON to stdout instead of
+                          hand-writing it -- reads your existing
+                          ~/.claude/settings.json if present, adds
+                          whatever residoo guard hooks are missing (never
+                          duplicates one already there), and prints the
+                          result. Writes NOTHING to disk: residoo never
+                          writes any file but its own rotation ledger and
+                          an explicit --seal vault, so save it yourself:
+                            residoo guard --print-config > ~/.claude/settings.json
+                          --project targets ./.claude/settings.json (the
+                          repo-local config) instead of the home-level one.
+
 Rotation:
   residoo explain <rule-id>     full rotation runbook for one detection rule
                                 (where to revoke, steps, what revocation does)
@@ -315,10 +346,19 @@ Seal options (used with scan):
                           in the OS keychain instead of a typed passphrase.
                           Nothing to remember, and the key's strength no longer
                           depends on passphrase choice. macOS today; Linux when
-                          secret-tool (libsecret) is installed. TRADEOFF: a
-                          keychain-backed vault lives on THIS machine/account
+                          secret-tool (libsecret) is installed; Windows via
+                          DPAPI (a different mechanism, not a Windows Credential
+                          Manager entry -- cmdkey.exe is confirmed write-only,
+                          it can never read a stored password back out). TRADEOFF:
+                          a keychain-backed vault lives on THIS machine/account
                           only, unlike a passphrase, it is not portable to
-                          another machine.
+                          another machine. On Windows specifically, the DPAPI-
+                          wrapped key travels INSIDE the vault directory itself
+                          (there's no separate OS-level store to put it in,
+                          unlike macOS/Linux) -- still undecryptable without
+                          being logged in as the same Windows user on the same
+                          machine, but a real, disclosed difference from macOS/
+                          Linux's fully separate keychain entry.
   --vault-dir <dir>       where to create the vault (default: ./residoo-vault-<stamp>)
   --upload-cloudroam      ALSO upload the sealed vault to CloudRoam. One of two
                           opt-in features that touch the network (--verify
@@ -379,31 +419,70 @@ async function getPassphrase({ confirmNew }) {
  * sealFindings/deriveKey path a typed passphrase would use — scrypt on a
  * full 256-bit-entropy input is harmless extra defense, and reusing that
  * already-tested path means no change to sealcrypto.js/sealvault.js at all.
+ *
+ * `winKeyBlob` is Windows' equivalent of `vaultId`: there is no OS-level
+ * named credential store on Windows (see keychain.js's own
+ * wrapVaultKeyWindows docstring for exactly why, and why this is a
+ * DIFFERENT mechanism from `vaultId`'s macOS/Linux keychain.store(), not a
+ * Windows branch inside it), so instead of a lookup id, the caller gets
+ * back the actual DPAPI-wrapped key blob to persist itself once the vault
+ * directory exists — the one place on Windows with a rule-compliant
+ * reason to write it.
  */
 async function resolveSealSecret(args) {
   if (!args.includes("--keychain")) {
-    return { passphrase: await getPassphrase({ confirmNew: true }), vaultId: null };
+    return { passphrase: await getPassphrase({ confirmNew: true }), vaultId: null, winKeyBlob: null };
   }
+  const passphrase = crypto.randomBytes(32).toString("base64");
   const keychain = require("./keychain");
+  if (process.platform === "win32") {
+    if (!keychain.isVaultKeySupported()) throw new Error("--keychain: DPAPI is not available on this system.");
+    return { passphrase, vaultId: null, winKeyBlob: keychain.wrapVaultKeyWindows(passphrase) };
+  }
   if (!keychain.isSupported()) throw new Error(`--keychain: ${keychain.unsupportedReason()}`);
   const vaultId = crypto.randomUUID();
-  const passphrase = crypto.randomBytes(32).toString("base64");
   keychain.store(vaultId, passphrase);
-  return { passphrase, vaultId };
+  return { passphrase, vaultId, winKeyBlob: null };
 }
 
-/** The unsealing secret for `unseal`: a keychain-retrieved key, or a typed passphrase. */
+/**
+ * The unsealing secret for `unseal`: a keychain-retrieved key, or a typed
+ * passphrase. Checked by which MARKER FILE is actually present in the
+ * vault directory, not by the current machine's platform — a vault sealed
+ * on Windows carries `.keychain-key-win`, one sealed on macOS/Linux
+ * carries `.keychain-id`, and trying to unseal one on the wrong kind of
+ * machine should say so clearly rather than silently mis-routing.
+ */
 async function resolveUnsealSecret(args, vaultDir) {
   if (!args.includes("--keychain")) return getPassphrase({ confirmNew: false });
   const keychain = require("./keychain");
-  if (!keychain.isSupported()) throw new Error(`--keychain: ${keychain.unsupportedReason()}`);
+  const winKeyPath = path.join(vaultDir, ".keychain-key-win");
   const idPath = path.join(vaultDir, ".keychain-id");
+
+  if (fs.existsSync(winKeyPath)) {
+    if (!keychain.isVaultKeySupported()) {
+      throw new Error(
+        `This vault was sealed with --keychain on Windows (DPAPI-backed). DPAPI keys are tied to that ` +
+        `Windows user account and cannot be unwrapped on ${process.platform} — unseal it on that same Windows machine.`
+      );
+    }
+    try {
+      return keychain.unwrapVaultKeyWindows(fs.readFileSync(winKeyPath, "utf-8").trim());
+    } catch {
+      throw new Error(
+        "Could not decrypt this vault's key via Windows DPAPI. It may have been sealed under a different " +
+        "Windows user account or moved to a different machine — a keychain-backed vault is not portable."
+      );
+    }
+  }
+
   if (!fs.existsSync(idPath)) {
     throw new Error(
-      `No .keychain-id marker in ${vaultDir}: this vault was not sealed with --keychain, ` +
+      `No .keychain-id or .keychain-key-win marker in ${vaultDir}: this vault was not sealed with --keychain, ` +
       `or the marker file was moved separately from the vault. Try unsealing without --keychain.`
     );
   }
+  if (!keychain.isSupported()) throw new Error(`--keychain: ${keychain.unsupportedReason()}`);
   const vaultId = fs.readFileSync(idPath, "utf-8").trim();
   try {
     return keychain.retrieve(vaultId);
@@ -444,7 +523,7 @@ async function runSeal(result, args) {
 
   const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
   const vaultDir = argValue(args, "--vault-dir") || path.resolve(`residoo-vault-${stamp}`);
-  const { passphrase, vaultId } = await resolveSealSecret(args);
+  const { passphrase, vaultId, winKeyBlob } = await resolveSealSecret(args);
 
   process.stdout.write(`\nSealing ${filesWithFindings.length} file(s) with findings into ${vaultDir}\n`);
   const { entries } = await sealFindings({
@@ -456,6 +535,13 @@ async function runSeal(result, args) {
   // keychain lookup, never the key itself and never anything about what the
   // vault contains.
   if (vaultId) fs.writeFileSync(path.join(vaultDir, ".keychain-id"), vaultId, { mode: 0o600 });
+  // Windows' equivalent marker -- unlike .keychain-id, this DOES hold
+  // sensitive material (the DPAPI-wrapped key itself, not a lookup id),
+  // which is exactly the disclosed security-property trade-off
+  // keychain.js's wrapVaultKeyWindows docstring names: on Windows the
+  // wrapped key travels with the vault, decryptable only by the same
+  // Windows user account, rather than living in a fully separate store.
+  if (winKeyBlob) fs.writeFileSync(path.join(vaultDir, ".keychain-key-win"), winKeyBlob, { mode: 0o600 });
   const totalPlain = entries.reduce((s, e) => s + e.plainBytes, 0);
   const totalSealed = entries.reduce((s, e) => s + e.sealedBytes, 0);
   process.stdout.write(
@@ -688,6 +774,7 @@ async function runWatch(args) {
   const verify = args.includes("--verify");
   const noColor = args.includes("--no-color");
   const includePii = args.includes("--include-pii");
+  const noNotify = args.includes("--no-notify");
 
   let intervalSeconds = 5;
   const intervalArg = argValue(args, "--interval");
@@ -713,7 +800,7 @@ async function runWatch(args) {
 
   const { promise, stop } = startWatch({
     sources,
-    options: { includeNoisy, includeSuppressed, verify, noColor, includePii, json: wantsJson, pollMs: intervalSeconds * 1000 },
+    options: { includeNoisy, includeSuppressed, verify, noColor, includePii, noNotify, json: wantsJson, pollMs: intervalSeconds * 1000 },
   });
 
   const printFinalSummary = (stats) => {
@@ -743,6 +830,57 @@ async function runWatch(args) {
   return 0;
 }
 
+/**
+ * `residoo guard --print-config`: print the merged .claude/settings.json
+ * a user would need to register all three guard hooks, without ever
+ * writing it -- see guard.js's own buildHookConfig docstring for why this
+ * is print-only rather than an auto-installer. Reads the existing file
+ * (home-level by default, `--project` for the repo-local one) if present,
+ * merges in whatever hook groups are missing, and writes the result to
+ * STDOUT ONLY -- every instructional line goes to stderr, so
+ * `residoo guard --print-config > ~/.claude/settings.json` redirects
+ * exactly the JSON and nothing else.
+ */
+function runGuardPrintConfig(args) {
+  const wantsProject = args.includes("--project");
+  const targetPath = wantsProject
+    ? path.join(process.cwd(), ".claude", "settings.json")
+    : path.join(os.homedir(), ".claude", "settings.json");
+
+  let existing = {};
+  let existedAlready = false;
+  try {
+    const raw = fs.readFileSync(targetPath, "utf-8");
+    existedAlready = true;
+    try { existing = JSON.parse(raw); }
+    catch {
+      process.stderr.write(
+        `residoo guard --print-config: ${targetPath} exists but is not valid JSON. ` +
+        `Fix it first -- printing a merge against unparseable JSON would risk losing whatever is already there.\n`
+      );
+      return 1;
+    }
+  } catch (err) {
+    if (!(err && err.code === "ENOENT")) {
+      process.stderr.write(`residoo guard --print-config: could not read ${targetPath}: ${err.message}\n`);
+      return 1;
+    }
+  }
+
+  const merged = buildHookConfig(existing);
+  process.stderr.write(
+    (existedAlready
+      ? `residoo guard --print-config: merged residoo's three hooks into your existing ${targetPath} below.\n`
+      : `residoo guard --print-config: ${targetPath} doesn't exist yet -- here's a new one with residoo's three hooks.\n`) +
+    `Nothing was written to disk -- residoo never writes any file but its own rotation ledger and an explicit ` +
+    `--seal vault. Save this yourself, e.g.:\n` +
+    `  residoo guard --print-config${wantsProject ? " --project" : ""} > ${targetPath}\n` +
+    (wantsProject ? "" : "(add --project to target ./.claude/settings.json instead of the home-level one)\n")
+  );
+  process.stdout.write(JSON.stringify(merged, null, 2) + "\n");
+  return 0;
+}
+
 /**
  * `residoo mcp`: run residoo as an MCP server over stdio. See src/mcp.js
  * for the protocol engine and src/mcpTools.js for the tool catalog; this
@@ -925,7 +1063,10 @@ async function main(argv) {
   if (cmd === "watch") return runWatch(args);
   if (cmd === "mcp") return runMcp(args);
   if (cmd === "cred") return runCred(args);
-  if (cmd === "guard") return runGuardEngine();
+  if (cmd === "guard") {
+    if (args.includes("--print-config")) return runGuardPrintConfig(args.slice(1));
+    return runGuardEngine();
+  }
   if (cmd !== "scan") {
     process.stderr.write(`Unknown command "${cmd}". Try "residoo --help".\n`);
     return 2;
@@ -1110,4 +1251,10 @@ async function main(argv) {
   return failOnFind && (secretGate || integrityWarnCount(integrity) > 0) ? 1 : 0;
 }
 
-module.exports = { main };
+// resolveSealSecret/resolveUnsealSecret are exported alongside `main`
+// specifically so tests/smoke.js can exercise their Windows (DPAPI) branch
+// directly: a spawned subprocess (this file's usual CLI-testing precedent)
+// always runs on the REAL host platform, so it can never exercise
+// win32-only logic on a non-Windows build machine -- calling these two
+// in-process, with process.platform mocked, is the only way to.
+module.exports = { main, resolveSealSecret, resolveUnsealSecret };

package/src/guard.js

@@ -70,6 +70,56 @@
 const { PATTERNS, redact } = require("./patterns");
 const { VENDOR_EXAMPLE_VALUES, zeroEntropyTail } = require("./scan");
 
+const GUARD_COMMAND = "residoo guard";
+
+// matcher: null means Claude Code's own hook-config schema omits the field
+// entirely for an event with no matcher support (UserPromptSubmit) --
+// distinct from an empty string, which would mean "match everything" for
+// an event that DOES support matchers.
+const HOOK_EVENT_SPECS = [
+  { event: "PreToolUse", matcher: "Bash|Read" },
+  { event: "UserPromptSubmit", matcher: null },
+  { event: "PostToolUse", matcher: "Bash" },
+];
+
+/**
+ * Pure function: given a parsed Claude Code settings.json object (or `{}`
+ * for a fresh one), returns a NEW object with a "residoo guard" hook group
+ * appended to each of PreToolUse/UserPromptSubmit/PostToolUse's hook
+ * arrays -- unless a "residoo guard" command already exists ANYWHERE in
+ * that event's groups, in which case that event is left untouched
+ * (idempotent: running this against its own prior output changes
+ * nothing). Never mutates `existing`; every other key, every other tool's
+ * hook, every unrelated setting is carried through byte-for-byte.
+ *
+ * This function only COMPUTES a value -- it never touches a file, on
+ * purpose. 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."
+ * An auto-installing `guard --install` that edited `.claude/settings.json`
+ * directly would violate that rule outright, so the CLI wraps this in
+ * `--print-config` instead (see cli.js's runGuardPrintConfig): print the
+ * merged JSON to stdout, let the human decide whether and where to save it.
+ */
+function buildHookConfig(existing) {
+  const settings = existing && typeof existing === "object" && !Array.isArray(existing)
+    ? JSON.parse(JSON.stringify(existing)) : {};
+  if (!settings.hooks || typeof settings.hooks !== "object" || Array.isArray(settings.hooks)) settings.hooks = {};
+
+  for (const { event, matcher } of HOOK_EVENT_SPECS) {
+    const groups = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    const alreadyPresent = groups.some((g) =>
+      g && typeof g === "object" && Array.isArray(g.hooks) &&
+      g.hooks.some((h) => h && typeof h === "object" && h.type === "command" && h.command === GUARD_COMMAND));
+    if (alreadyPresent) { settings.hooks[event] = groups; continue; }
+    const newGroup = matcher
+      ? { matcher, hooks: [{ type: "command", command: GUARD_COMMAND }] }
+      : { hooks: [{ type: "command", command: GUARD_COMMAND }] };
+    settings.hooks[event] = [...groups, newGroup];
+  }
+  return settings;
+}
+
 // 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
@@ -402,5 +452,5 @@ async function runGuard({ input = process.stdin, output = process.stdout, errOut
 
 module.exports = {
   evaluateToolInput, matchSensitivePath, evaluatePromptText, evaluatePostToolUse,
-  runGuard, SENSITIVE_PATH_PATTERNS,
+  runGuard, buildHookConfig, SENSITIVE_PATH_PATTERNS,
 };

package/src/integrity.js

@@ -3,6 +3,12 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+// Not destructured: kept as `cp.execFileSync(...)` at every call site so a
+// test can monkey-patch `require("child_process").execFileSync` (the same
+// shared module object) the way tests/smoke.js's notify.js tests already
+// do -- a destructured `const { execFileSync } = ...` would copy the
+// reference at import time and never see a later patch.
+const cp = require("child_process");
 const { PATTERNS, redact } = require("./patterns");
 
 /**
@@ -677,7 +683,59 @@ function checkIntegrity({ home = os.homedir(), cwd = process.cwd(), projectMode
     }
   }
 
-  // ---- 5. credential-vault file permissions (HOME only, POSIX only) ------
+  // Windows NTFS ACL check for one credential-vault file, the win32
+  // counterpart to the POSIX `stat.mode` check below -- Node's fs.Stats.mode
+  // on Windows does not reflect NTFS ACLs at all, so this shells out to
+  // PowerShell's Get-Acl instead, the same "invoke the OS's own tool"
+  // pattern keychain.js already uses for macOS's `security` and Linux's
+  // `secret-tool`. Verified against Microsoft's own Get-Acl documentation
+  // (learn.microsoft.com/powershell/module/microsoft.powershell.security/get-acl)
+  // and cross-checked against independent write-ups, not live-tested
+  // against a real Windows install -- disclosed the same way copilot-cli.js's
+  // own header discloses "corroborated but unverified against a real
+  // install" for a source built without one available. icacls was
+  // considered and rejected: research found it has no `/findsid` switch
+  // and its text output is not reliably parseable, unlike Get-Acl's typed
+  // object model.
+  //
+  // Every field is projected through an explicit PSCustomObject (never the
+  // raw IdentityReference/FileSystemRights/AccessControlType objects) so
+  // JSON serialization is forced to plain strings regardless of how those
+  // .NET types would otherwise serialize -- and the result is wrapped in an
+  // array via `-InputObject` (not piped) specifically because ConvertTo-Json
+  // collapses a single-item collection into a bare object rather than a
+  // one-element array when piped, a well-known PowerShell gotcha that would
+  // otherwise break parsing on the (common) case of a file with exactly one
+  // relevant ACE.
+  //
+  // English-locale principal names only (Everyone, BUILTIN\Users, NT
+  // AUTHORITY\Authenticated Users) -- a disclosed, not silent, gap: a
+  // non-English Windows install localizes these names (e.g. "Jeder" for
+  // Everyone in German) and would not match here, the same kind of named
+  // scope limit ibanValid's per-country-length gap and the OCR module's
+  // English-only wordlist already carry elsewhere in this project.
+  function checkWindowsCredentialAcl(file) {
+    const escaped = file.replace(/'/g, "''");
+    const script =
+      "$ErrorActionPreference='Stop'; " +
+      `$acl = Get-Acl -LiteralPath '${escaped}'; ` +
+      "$rules = @($acl.Access | ForEach-Object { [PSCustomObject]@{ " +
+      "Identity = $_.IdentityReference.Value; Rights = $_.FileSystemRights.ToString(); Type = $_.AccessControlType.ToString() } }); " +
+      "ConvertTo-Json -InputObject $rules -Compress";
+    const out = cp.execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { encoding: "utf-8" });
+    let rules;
+    try { rules = JSON.parse(out); } catch { return null; }
+    if (!Array.isArray(rules)) rules = [rules];
+    const BROAD_PRINCIPAL = /^(everyone|builtin\\users|nt authority\\authenticated users|users)$/i;
+    const READ_CAPABLE_RIGHTS = /fullcontrol|modify|read/i;
+    const hits = rules.filter((r) =>
+      r && typeof r.Identity === "string" && typeof r.Type === "string" && typeof r.Rights === "string" &&
+      r.Type === "Allow" && BROAD_PRINCIPAL.test(r.Identity.trim()) && READ_CAPABLE_RIGHTS.test(r.Rights));
+    if (hits.length === 0) return { tooOpen: false };
+    return { tooOpen: true, detail: hits.map((h) => `${h.Identity} (${h.Rights})`).join(", ") };
+  }
+
+  // ---- 5. credential-vault file permissions (HOME only, POSIX and win32) -
   // GitGuardian's "State of Secrets Sprawl 2026" (blog.gitguardian.com,
   // published 2026-03-17) found 24,008 unique secrets in MCP-related config
   // files on public GitHub, 8.8% of them still live -- these files
@@ -700,13 +758,14 @@ function checkIntegrity({ home = os.homedir(), cwd = process.cwd(), projectMode
   // naive backup restore, or a shared-volume container mount can each
   // silently widen a file's mode without the tool that wrote it ever
   // knowing, the same way SSH itself checks id_rsa's permissions rather
-  // than trusting whoever created it. Windows is skipped entirely, not
-  // approximated: Node's fs.Stats.mode on Windows does not reflect NTFS
-  // ACLs, so a POSIX-style bit check there would be meaningless rather than
-  // merely imprecise. Project mode is skipped too -- none of these are ever
+  // than trusting whoever created it. Windows gets its own NTFS-ACL-based
+  // check (checkWindowsCredentialAcl above), not a POSIX-bit approximation
+  // -- Node's fs.Stats.mode on Windows does not reflect NTFS ACLs at all,
+  // so pretending otherwise would be meaningless, not merely imprecise.
+  // Project mode is skipped on every platform -- none of these are ever
   // project-scoped files by any vendor's own design, so there is no
   // project-relative equivalent to check.
-  if (!projectMode && process.platform !== "win32") {
+  if (!projectMode) {
     const geminiDir = process.env.GEMINI_CLI_HOME
       ? path.join(process.env.GEMINI_CLI_HOME, ".gemini")
       : path.join(home, ".gemini");
@@ -739,6 +798,24 @@ function checkIntegrity({ home = os.homedir(), cwd = process.cwd(), projectMode
         }
         continue;
       }
+
+      if (process.platform === "win32") {
+        let acl = null;
+        try { acl = checkWindowsCredentialAcl(file); } catch { acl = null; }
+        if (!acl) {
+          mark(file, "unreadable");
+          add("warn", "unreadable-config", file, "credential file exists but its NTFS permissions could not be checked (Get-Acl failed): unverified, not clean");
+          continue;
+        }
+        mark(file, "checked");
+        if (acl.tooOpen) {
+          const shown = display(file);
+          add("warn", "insecure-credential-permissions", file,
+            `${note}; NTFS permissions grant ${acl.detail} access to a live credential on this machine. Fix: right-click "${shown}" > Properties > Security > Advanced, and remove any group other than your own account and the system/administrators.`);
+        }
+        continue;
+      }
+
       mark(file, "checked");
       const openBits = stat.mode & 0o077;
       if (openBits !== 0) {

package/src/keychain.js

@@ -1,6 +1,11 @@
 "use strict";
 
-const { execFileSync } = require("child_process");
+// Not destructured: kept as `cp.execFileSync(...)` at every call site so a
+// test can monkey-patch `require("child_process").execFileSync` (the same
+// shared module object) the way tests/smoke.js's Windows-path tests do for
+// both this file and integrity.js -- a destructured `const { execFileSync
+// } = ...` would copy the reference at import time and never see a patch.
+const cp = require("child_process");
 
 /**
  * OS-native secure credential storage for `scan --seal --keychain` and
@@ -64,7 +69,7 @@ function isSupported() {
   if (process.platform === "darwin") return true;
   if (process.platform === "linux") {
     try {
-      execFileSync("which", ["secret-tool"], { stdio: "ignore" });
+      cp.execFileSync("which", ["secret-tool"], { stdio: "ignore" });
       return true;
     } catch {
       return false;
@@ -78,9 +83,108 @@ function unsupportedReason() {
   if (process.platform === "linux") {
     return "secret-tool (libsecret) is not installed. Install it (e.g. \"apt install libsecret-tools\" or \"dnf install libsecret\") or omit --keychain to use a passphrase instead.";
   }
+  if (process.platform === "win32") {
+    // Specifically about THIS by-name store/retrieve/remove API (residoo
+    // cred's only use of it) -- `--seal --keychain` works on Windows via a
+    // different, vault-relative mechanism (wrapVaultKeyWindows/
+    // unwrapVaultKeyWindows below), so this message must not read as "no
+    // --keychain support at all on Windows," which would be wrong.
+    return "residoo cred needs a named credential store, and Windows has none reachable without an extra dependency " +
+      "(cmdkey.exe can store a credential but never reads its password back -- confirmed against Microsoft's own docs). " +
+      "--seal --keychain works on Windows through a different mechanism; this specific store is what's unavailable.";
+  }
   return `--keychain is not supported on ${process.platform} yet. Omit --keychain to use a passphrase instead.`;
 }
 
+/**
+ * True when wrapVaultKeyWindows/unwrapVaultKeyWindows (below) can run --
+ * Windows only, since DPAPI is a Windows-specific API. Deliberately
+ * SEPARATE from isSupported() above: that function is about the by-name
+ * store()/retrieve()/remove() API (false on Windows -- no OS-level named
+ * credential store is reachable there without an extra dependency, since
+ * cmdkey.exe is confirmed write/list-only, never returning a stored
+ * password). This one is about the vault-relative wrap/unwrap pair, which
+ * exists only because `--seal --keychain` has a legitimate place (the
+ * vault directory itself) to put a DPAPI-wrapped blob -- `residoo cred`
+ * has no such place and does not use this.
+ */
+function isVaultKeySupported() {
+  return process.platform === "win32";
+}
+
+/**
+ * Windows-only DPAPI (Data Protection API) wrap/unwrap for `--seal
+ * --keychain`'s vault key, via a PowerShell shell-out -- the same
+ * "invoke the OS's own tool" pattern as macOS's `security` and Linux's
+ * `secret-tool` above, but a materially different SHAPE, and why these
+ * two functions exist separately from store()/retrieve() rather than as a
+ * Windows branch inside them.
+ *
+ * Windows has no OS-level "store this under a name, fetch it back by that
+ * name later" service the way macOS Keychain/secret-tool do. Verified
+ * directly, not assumed: `cmdkey.exe` (Windows Credential Manager's own
+ * CLI) can WRITE a generic credential but Microsoft's own documentation
+ * states plainly "Passwords are not displayed after they're stored," and
+ * `/list` only ever surfaces target names and usernames -- cmdkey is
+ * write/list-only, and cannot serve a store-then-retrieve flow at all.
+ * DPAPI (`System.Security.Cryptography.ProtectedData`, confirmed reachable
+ * from stock PowerShell 5.1 via `Add-Type -AssemblyName System.Security`
+ * with zero extra installs -- learn.microsoft.com/dotnet/standard/security/
+ * how-to-use-data-protection) is the real built-in alternative, but it is
+ * a stateless encrypt/decrypt PRIMITIVE, not a named registry: something
+ * still has to decide where the encrypted bytes are persisted.
+ *
+ * That is why wrapVaultKeyWindows only WRAPS a secret and hands the
+ * encrypted blob straight back to its caller -- this module never decides
+ * where it lives. `--seal --keychain` (cli.js's resolveSealSecret/
+ * resolveUnsealSecret) is the one caller with a rule-compliant place to
+ * put it: the vault directory itself, already within `--seal`'s own
+ * carve-out under CONTRIBUTING.md's hard rule (residoo writes nothing
+ * outside `~/.residoo/rotations.json` and an explicit `--seal`). `residoo
+ * cred` stores a long-lived credential with no vault of its own, so there
+ * is no rule-compliant place to write a DPAPI blob for it -- it remains
+ * genuinely unsupported on Windows (isSupported() above, unchanged), not
+ * worked around by squeezing it through this pair too.
+ *
+ * Disclosed security-property difference, not glossed over: on macOS/
+ * Linux, the key lives in a genuinely separate OS-managed store, entirely
+ * absent from the vault directory -- copying just the vault gets an
+ * attacker nothing at all. On Windows, the wrapped blob travels WITH the
+ * vault directory (inside it), so copying the whole vault also copies the
+ * blob. DPAPI's CurrentUser-scope encryption still means that blob is
+ * only decryptable by the same Windows user account on the same Windows
+ * installation -- not portable, the same end-user guarantee --keychain
+ * already documents -- but a threat model where an attacker can read the
+ * vault directory's files without being able to run code as that same
+ * user gets less protection here than macOS/Linux's physically-separate
+ * store provides. Verified against Microsoft's own DPAPI documentation;
+ * not live-tested against a real Windows install.
+ */
+function wrapVaultKeyWindows(secret) {
+  if (process.platform !== "win32") throw new Error("wrapVaultKeyWindows is Windows-only.");
+  const escaped = String(secret).replace(/'/g, "''");
+  const script =
+    "$ErrorActionPreference='Stop'; " +
+    "Add-Type -AssemblyName System.Security; " +
+    `$bytes = [System.Text.Encoding]::UTF8.GetBytes('${escaped}'); ` +
+    "$enc = [Security.Cryptography.ProtectedData]::Protect($bytes, $null, [Security.Cryptography.DataProtectionScope]::CurrentUser); " +
+    "[Convert]::ToBase64String($enc)";
+  return cp.execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { encoding: "utf-8" }).trim();
+}
+
+/** The other half of wrapVaultKeyWindows -- see its docstring for the full design. */
+function unwrapVaultKeyWindows(blob) {
+  if (process.platform !== "win32") throw new Error("unwrapVaultKeyWindows is Windows-only.");
+  const escaped = String(blob).replace(/'/g, "''");
+  const script =
+    "$ErrorActionPreference='Stop'; " +
+    "Add-Type -AssemblyName System.Security; " +
+    `$enc = [Convert]::FromBase64String('${escaped}'); ` +
+    "$dec = [Security.Cryptography.ProtectedData]::Unprotect($enc, $null, [Security.Cryptography.DataProtectionScope]::CurrentUser); " +
+    "[System.Text.Encoding]::UTF8.GetString($dec)";
+  return cp.execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { encoding: "utf-8" }).trim();
+}
+
 /**
  * Store `secret` (a string) under `account` in the OS keychain, for later
  * retrieve(account). `keychainFile`, macOS only, is an escape hatch used
@@ -97,13 +201,13 @@ function store(account, secret, keychainFile, service = SERVICE) {
     const kf = keychainFile || testKeychainFile();
     const args = ["add-generic-password", "-a", account, "-s", service, "-w", secret, "-U"];
     if (kf) args.push(kf);
-    execFileSync("security", args, { stdio: "ignore" });
+    cp.execFileSync("security", args, { stdio: "ignore" });
     return;
   }
   if (process.platform === "linux") {
     // secret-tool reads the secret from stdin, never a CLI argument, so it
     // never appears in a process listing or shell history.
-    execFileSync("secret-tool", [
+    cp.execFileSync("secret-tool", [
       "store", "--label", "residoo sealed vault key", "service", service, "account", account,
     ], { input: secret, stdio: ["pipe", "ignore", "ignore"] });
     return;
@@ -120,10 +224,10 @@ function retrieve(account, keychainFile, service = SERVICE) {
     const kf = keychainFile || testKeychainFile();
     const args = ["find-generic-password", "-a", account, "-s", service, "-w"];
     if (kf) args.push(kf);
-    return execFileSync("security", args, { encoding: "utf8" }).trim();
+    return cp.execFileSync("security", args, { encoding: "utf8" }).trim();
   }
   if (process.platform === "linux") {
-    return execFileSync("secret-tool", [
+    return cp.execFileSync("secret-tool", [
       "lookup", "service", service, "account", account,
     ], { encoding: "utf8" }).trim();
   }
@@ -142,14 +246,17 @@ function remove(account, keychainFile, service = SERVICE) {
     const kf = keychainFile || testKeychainFile();
     const args = ["delete-generic-password", "-a", account, "-s", service];
     if (kf) args.push(kf);
-    execFileSync("security", args, { stdio: "ignore" });
+    cp.execFileSync("security", args, { stdio: "ignore" });
     return;
   }
   if (process.platform === "linux") {
-    execFileSync("secret-tool", ["clear", "service", service, "account", account], { stdio: "ignore" });
+    cp.execFileSync("secret-tool", ["clear", "service", service, "account", account], { stdio: "ignore" });
     return;
   }
   throw new Error(unsupportedReason());
 }
 
-module.exports = { isSupported, unsupportedReason, store, retrieve, remove, CRED_SERVICE };
+module.exports = {
+  isSupported, unsupportedReason, store, retrieve, remove, CRED_SERVICE,
+  isVaultKeySupported, wrapVaultKeyWindows, unwrapVaultKeyWindows,
+};

package/src/notify.js

@@ -0,0 +1,53 @@
+"use strict";
+
+const cp = require("child_process");
+
+/**
+ * Best-effort OS desktop notification for `residoo watch`. macOS via
+ * `osascript` (always present, no new dependency -- the same shell-out
+ * precedent `keychain.js`'s `security` and `ocr.js`'s `tesseract` already
+ * set), Linux via `notify-send` (commonly present on a desktop session,
+ * NOT guaranteed -- `watch` also runs on headless/server machines with no
+ * notification daemon at all).
+ *
+ * Windows: no built-in, dependency-free mechanism was found that doesn't
+ * either need an external module (BurntToast) or pop a blocking, modal
+ * MessageBox in front of a background process -- a disclosed scope limit,
+ * not silently assumed covered, the same posture `keychain.js` already
+ * takes for its own Windows refusal.
+ *
+ * Decoration, never the report itself: `watch`'s own `emit()` already
+ * writes every finding to stdout/stderr before this is ever called, so a
+ * missing binary, no display server, or a spawn error here must never
+ * throw, block, or affect the caller in any way -- it can only make an
+ * already-reported finding easier to notice sooner.
+ *
+ * `cp.spawn` (not destructured at module load) so a test can monkey-patch
+ * `require("child_process").spawn` directly and restore it after, without
+ * this module needing its own injectable-dependency parameter.
+ */
+function notifyDesktop(title, message) {
+  try {
+    if (process.platform === "darwin") {
+      // osascript's -e takes one AppleScript source string; spawn (no
+      // shell:true) passes it as a single argv entry, so there is no shell
+      // to inject into -- but the string still has to be valid AppleScript
+      // source, so its own quote/backslash characters need escaping or a
+      // stray one just breaks the script into a harmless no-op.
+      const esc = (s) => String(s).replace(/[\\"]/g, "\\$&");
+      const script = `display notification "${esc(message)}" with title "${esc(title)}"`;
+      const child = cp.spawn("osascript", ["-e", script], { stdio: "ignore" });
+      child.on("error", () => {}); // binary missing or spawn failed: never throw
+      child.unref();
+    } else if (process.platform === "linux") {
+      const child = cp.spawn("notify-send", [String(title), String(message)], { stdio: "ignore" });
+      child.on("error", () => {});
+      child.unref();
+    }
+    // Windows and anything else: no-op, disclosed above, not attempted.
+  } catch {
+    // Never let a notification failure affect the caller.
+  }
+}
+
+module.exports = { notifyDesktop };

package/src/watch.js

@@ -6,6 +6,7 @@ const crypto = require("crypto");
 const { scan } = require("./scan");
 const { guidanceFor, fingerprintFinding, loadAcks, loadDismissed, statePath } = require("./rotation");
 const { c, makePaint } = require("./color");
+const { notifyDesktop } = require("./notify");
 
 /**
  * `residoo watch`: continuous, near-real-time scanning of the same
@@ -563,7 +564,7 @@ function reloadLedgerIfChanged(prev) {
  * backstop and nothing riding on top of it. `options.fsWatch` is accepted
  * and ignored, reserved for when a future version adds real hints.
  */
-function startWatch({ sources, options = {}, out = process.stdout, errOut = process.stderr } = {}) {
+function startWatch({ sources, options = {}, out = process.stdout, errOut = process.stderr, notify = notifyDesktop } = {}) {
   const paint = makePaint(options.noColor, out);
   const tracked = new Map();
   const seen = new Map();
@@ -582,6 +583,17 @@ function startWatch({ sources, options = {}, out = process.stdout, errOut = proc
     }
     const line = renderHumanLine(event, paint);
     if (line !== null) out.write(line + "\n");
+    // Desktop notification is decoration on top of the line just written
+    // above, never a substitute for it -- JSON mode is for programmatic
+    // consumption (a pipe, a log shipper), not a human sitting in front of
+    // the terminal, so it's excluded the same way `options.noColor` only
+    // applies to the human-line path. Only a genuinely NEW finding notifies
+    // -- a `reexposure` (the same secret seen again) or a `watch-error`
+    // would otherwise turn a quiet, healthy watch into a notification
+    // spamming machine.
+    if (event.type === "finding" && !options.json && !options.noNotify) {
+      notify("residoo: new secret found", `${event.label} in ${event.relFile}:${event.line} (${event.preview})`);
+    }
   }
 
   async function tick() {