superdev-cli 0.1.0

package/scripts/privacy/scan-history.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * Complete-history confidentiality scanner. Where scan.mjs covers the working
+ * tree and the git index, this covers ALL of git history: every reachable object
+ * (blob, commit, annotated tag), every historical path a blob ever had, commit
+ * and tag MESSAGES, and symlink target blobs (a symlink is a blob whose content
+ * is its target string, so byte-scanning every blob covers it).
+ *
+ * Guarantees:
+ *  - Never silently skips: an unreadable/oversize object yields a SCAN-UNREADABLE
+ *    P0 finding (fail closed), never a silent pass.
+ *  - Reuses the exact scanner rules and external denylist (no policy drift).
+ *  - Byte-scans binary blobs (denylist / abs-home path / non-allowlisted email /
+ *    key markers survive an embedded NUL); text blobs get the full content scan.
+ *  - History is immutable: a historical binary-in-a-text-extension blob (e.g. the
+ *    pre-fix ingest.mjs) is STILL byte-scanned; only its BIN-TEXT *classification*
+ *    finding may be suppressed via an exact (object-id, path) exception, which is
+ *    documented and never suppresses a denylist/path/email/key result.
+ *  - Denylist values are never echoed.
+ *
+ * Exit codes: 0 clean, 1 findings, 2 usage/environment error.
+ */
+import { parseArgs } from "node:util";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { classifyExtension, bufferIsBinary, loadDenylist, scanBytes, scanContent, redactText, loadAllowBinary } from "./scan.mjs";
+
+const USAGE = `Usage: node scan-history.mjs --root <repo> [--denylist <file>] [--allow-binary <file>] [--history-allow <file>] [--json] [--out <file>]
+  Scans every reachable git object, path, and commit/tag message across ALL history.`;
+const MAX_BLOB = 512 * 1024 * 1024; // bounded read; overflow fails closed, never silently skips
+
+function git(root, args, opts = {}) {
+  return execFileSync("git", ["-C", root, ...args], { maxBuffer: MAX_BLOB, ...opts });
+}
+
+/** Load the (oid, path) BIN-TEXT exceptions: one "oid path" per line, # comments. */
+export function loadHistoryAllow(file) {
+  if (!file || !fs.existsSync(file)) return new Set();
+  return new Set(
+    fs.readFileSync(file, "utf8").split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith("#"))
+  );
+}
+
+/** Map every blob oid to the set of historical paths it ever appeared under. */
+function blobPaths(root) {
+  const out = git(root, ["rev-list", "--all", "--objects"], { encoding: "utf8" });
+  const map = new Map();
+  for (const line of out.split("\n")) {
+    if (!line) continue;
+    const sp = line.indexOf(" ");
+    if (sp === -1) continue; // commits/tags have no path
+    const oid = line.slice(0, sp), p = line.slice(sp + 1);
+    if (!map.has(oid)) map.set(oid, new Set());
+    map.get(oid).add(p);
+  }
+  return map;
+}
+
+/** The set of REACHABLE object ids (from all refs, including annotated tag
+ *  objects). Dangling/unreachable objects - e.g. a transient staged blob that was
+ *  edited before commit and will be garbage-collected - are not part of the
+ *  history that can be published, so they are out of scope. */
+function reachableOids(root) {
+  const set = new Set();
+  for (const line of git(root, ["rev-list", "--all", "--objects"], { encoding: "utf8" }).split("\n")) {
+    if (line) set.add(line.split(" ")[0]);
+  }
+  for (const line of git(root, ["for-each-ref", "--format=%(objecttype) %(objectname)", "refs/tags"], { encoding: "utf8" }).split("\n")) {
+    if (line.startsWith("tag ")) set.add(line.slice(4).trim()); // annotated tag objects carry a message
+  }
+  return set;
+}
+
+/** Every REACHABLE object, with type. */
+function allObjects(root) {
+  const reachable = reachableOids(root);
+  const out = git(root, ["cat-file", "--batch-all-objects", "--unordered", "--batch-check=%(objecttype) %(objectname)"], { encoding: "utf8" });
+  return out.split("\n").filter(Boolean).map((l) => { const [type, oid] = l.split(" "); return { type, oid }; }).filter((o) => reachable.has(o.oid));
+}
+
+/** Message body of a commit/tag object (everything after the first blank line). */
+function objectMessage(root, oid) {
+  const raw = git(root, ["cat-file", oid.startsWith("tag:") ? "tag" : "commit", oid.replace(/^tag:/, "")], { encoding: "utf8" });
+  const blank = raw.indexOf("\n\n");
+  return blank === -1 ? "" : raw.slice(blank + 2);
+}
+
+export function runScanHistory({ root, denylistPath, allowBinaryPath, historyAllowPath, allowBinary }) {
+  // Confirm this is a git repository up front; a non-repo is an environment error.
+  try { git(root, ["rev-parse", "--git-dir"], { encoding: "utf8" }); }
+  catch { throw new Error("not a git repository (or git unavailable)"); }
+
+  const denylist = denylistPath ? loadDenylist(denylistPath) : [];
+  const allow = allowBinary ?? loadAllowBinary(allowBinaryPath);
+  const historyAllow = loadHistoryAllow(historyAllowPath);
+  const findings = [];
+  const paths = blobPaths(root);
+  const objects = allObjects(root);
+  let blobs = 0, commits = 0, tags = 0;
+
+  for (const { type, oid } of objects) {
+    if (type === "commit") {
+      commits++;
+      // Author/committer emails live in the header (not the message body) and are
+      // scanned as ordinary allowlisted emails; the message body is scanned for
+      // denylist entries, absolute home paths, non-allowlisted emails, and keys.
+      let msg;
+      try { msg = objectMessage(root, oid); }
+      catch (e) { findings.push({ ruleId: "SCAN-UNREADABLE", severity: "P0", file: `commit:${oid}`, line: 0, detail: `commit unreadable (${e.code ?? "err"}) - fail closed` }); continue; }
+      findings.push(...scanBytes(`commit-message:${oid}`, Buffer.from(msg, "utf8"), denylist));
+    } else if (type === "tag") {
+      tags++;
+      let msg;
+      try { msg = objectMessage(root, `tag:${oid}`); }
+      catch (e) { findings.push({ ruleId: "SCAN-UNREADABLE", severity: "P0", file: `tag:${oid}`, line: 0, detail: `tag unreadable (${e.code ?? "err"}) - fail closed` }); continue; }
+      findings.push(...scanBytes(`tag-message:${oid}`, Buffer.from(msg, "utf8"), denylist));
+    } else if (type === "blob") {
+      blobs++;
+      let buf;
+      try { buf = git(root, ["cat-file", "blob", oid]); }
+      catch (e) { findings.push({ ruleId: "SCAN-UNREADABLE", severity: "P0", file: `blob:${oid}`, line: 0, detail: `blob unscannable (${e.code ?? "err"}) - fail closed` }); continue; }
+      const names = [...(paths.get(oid) ?? [`blob:${oid}`])];
+      const label = names[0];
+      const binary = bufferIsBinary(buf);
+      // Content scan once per blob (same bytes regardless of path).
+      if (binary) findings.push(...scanBytes(label, buf, denylist).map((f) => ({ ...f, oid })));
+      else findings.push(...scanContent(label, buf.toString("utf8"), denylist).map((f) => ({ ...f, oid })));
+      // Classification per historical path (extension depends on the name).
+      if (binary) for (const name of names) {
+        const cls = classifyExtension(name.split(path.sep).join("/"));
+        if (cls === "text") {
+          if (!historyAllow.has(`${oid} ${name}`)) // documented, object-scoped exception; content still byte-scanned above
+            findings.push({ ruleId: "BIN-TEXT", severity: "P0", file: name, line: 0, oid, detail: "historical text-expected file is binary (leak-scan blind spot)" });
+        } else if (cls === "unknown" && !allow.has(name)) {
+          findings.push({ ruleId: "BIN-UNCLASSIFIED", severity: "P0", file: name, line: 0, oid, detail: "historical unclassified binary" });
+        }
+      }
+    }
+  }
+
+  const safe = findings.map((f) => ({ ...f, file: redactText(f.file, denylist) }));
+  const counts = { P0: findings.filter((f) => f.severity === "P0").length, P1: findings.filter((f) => f.severity === "P1").length };
+  return { version: 1, mode: "history", root: redactText(path.resolve(root), denylist), stats: { objects: objects.length, blobs, commits, tags }, rulesLoaded: { denylist: denylist.length }, counts, findings: safe };
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs({ options: { root: { type: "string", default: "." }, denylist: { type: "string" }, "allow-binary": { type: "string" }, "history-allow": { type: "string" }, json: { type: "boolean", default: false }, out: { type: "string" }, help: { type: "boolean", default: false } } }).values;
+  } catch (e) { console.error(String(e.message ?? e)); console.error(USAGE); process.exit(2); }
+  if (args.help) { console.log(USAGE); process.exit(0); }
+  let report;
+  try {
+    report = runScanHistory({ root: args.root, denylistPath: args.denylist, allowBinaryPath: args["allow-binary"], historyAllowPath: args["history-allow"] });
+  } catch (e) { console.error(String(e.message ?? e)); process.exit(2); }
+  if (args.json) console.log(JSON.stringify(report, null, 2));
+  else console.log(`history scan - ${report.findings.length} finding(s), P0=${report.counts.P0} P1=${report.counts.P1} over ${report.stats.objects} objects (${report.stats.blobs} blobs, ${report.stats.commits} commits, ${report.stats.tags} tags)` + report.findings.map((f) => `\n  [${f.severity}] ${f.ruleId} ${f.file}${f.oid ? ` @${f.oid.slice(0, 10)}` : ""}`).join(""));
+  if (args.out) fs.writeFileSync(args.out, JSON.stringify(report, null, 2) + "\n");
+  process.exit(report.counts.P0 + report.counts.P1 > 0 ? 1 : 0);
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${fs.realpathSync(process.argv[1])}`).href) main();

package/scripts/privacy/scan.mjs

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+/**
+ * Privacy/leak scanner. See references/confidentiality.md for the policy.
+ *
+ * Contract:
+ *  - reads only; writes nothing unless --out is explicitly provided
+ *  - denylist entries are NEVER echoed into output (findings carry rule ids only)
+ *  - machine-readable JSON on stdout with --json
+ *  - exit 0 clean, 1 findings, 2 usage error
+ *
+ * Binary policy (fail-closed): binary files are NEVER silently skipped.
+ *  - A file with a text-expected extension that is binary is a P0 finding
+ *    (BIN-TEXT) - this closes the NUL-byte blind spot.
+ *  - Every binary file (whatever its extension) is byte-scanned for denylist
+ *    entries and byte-searchable P0 rules (paths/emails/keys), matched over a
+ *    latin1 decode so ASCII byte sequences are found across embedded NULs.
+ *  - A binary file that is neither text-expected nor a known/allowlisted asset
+ *    is a P0 finding (BIN-UNCLASSIFIED). Legitimate binary assets pass only via
+ *    a known-binary extension or the documented allowlist file.
+ */
+import { parseArgs } from "node:util";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const USAGE = `Usage: node scan.mjs [options]
+  --denylist <path>  external denylist file (one case-insensitive substring per line, # comments)
+  --root <path>      directory to scan (default: current directory)
+  --staged           scan only files staged in git (contents from the index)
+  --allow-binary <p> newline list of repo-relative legitimate binary asset paths
+  --json             machine-readable JSON on stdout
+  --out <path>       also write the report to this exact path (never writes otherwise)
+  --help             show this help`;
+
+const SKIP_DIRS = new Set([
+  ".git", "node_modules", ".impeccable", ".superdev",
+  ".next", ".turbo", ".cache", "coverage",
+]);
+// Extensions whose files MUST be text - a binary one is a P0 leak-vector (BIN-TEXT).
+export const TEXT_EXTENSIONS = new Set([
+  ".mjs", ".cjs", ".js", ".ts", ".mts", ".cts", ".jsx", ".tsx", ".vue", ".svelte",
+  ".json", ".jsonc", ".md", ".markdown", ".yaml", ".yml", ".sh", ".bash", ".txt",
+  ".html", ".css", ".xml", ".toml", ".ini", ".cfg", ".conf", ".env", ".gitignore",
+  ".editorconfig", ".sql", ".py", ".rb", ".go", ".rs", ".java", ".c", ".h", ".cpp",
+]);
+// Extensions that are legitimately binary assets - still byte-scanned, never BIN-TEXT.
+export const KNOWN_BINARY_EXTENSIONS = new Set([
+  ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".pdf", ".woff", ".woff2", ".ttf",
+  ".otf", ".eot", ".zip", ".gz", ".tar", ".wasm", ".mp3", ".mp4", ".mov", ".bin",
+]);
+export function classifyExtension(relPosix) {
+  const ext = relPosix.slice(relPosix.lastIndexOf("."));
+  if (TEXT_EXTENSIONS.has(ext)) return "text";
+  if (KNOWN_BINARY_EXTENSIONS.has(ext)) return "known-binary";
+  return "unknown";
+}
+export function bufferIsBinary(buf) {
+  const n = Math.min(buf.length, 8000);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+const EMAIL_ALLOWED = /@(?:[a-z0-9.-]*\.)?(?:example\.(?:com|org|net)|anthropic\.com)$|\.(?:invalid|test|example|localhost)$/i;
+const RULES = {
+  ABS_HOME: { id: "ABS-HOME", severity: "P0", re: /\/(?:Users|home)\/[A-Za-z0-9_-]+\//g },
+  EMAIL: { id: "EMAIL", severity: "P0", re: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g },
+  KEY: { id: "KEY", severity: "P0", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+  HIENT: { id: "HIENT", severity: "P1", re: /[A-Za-z0-9+/=_-]{40,}/g },
+};
+
+// Integrity hashes are the purpose of dependency lockfiles. Treating every
+// registry checksum as a possible secret makes the scanner unusable on a real
+// brownfield project (a normal pnpm lockfile can produce hundreds of findings).
+// Only the HIENT heuristic is skipped: denylist matches, absolute paths, emails,
+// private-key markers, binary classification, and env-file rules still apply.
+const DEPENDENCY_LOCKFILES = new Set([
+  "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "pnpm-lock.yml",
+  "yarn.lock", "bun.lock", "composer.lock", "Cargo.lock", "Gemfile.lock",
+  "poetry.lock", "Pipfile.lock", "uv.lock", "go.sum", "mix.lock", "Podfile.lock",
+  "Package.resolved",
+]);
+
+/**
+ * The compiled control center, skipped for the same reason and no broader one.
+ * It is minified build output, so it is one enormous line of mangled
+ * identifiers that trips an entropy heuristic by construction, and its source
+ * under `ui/` is scanned in full. Skipping the heuristic here keeps the release
+ * gate meaningful; a scanner that always reports one finding is one people stop
+ * reading.
+ *
+ * As with the lockfiles above, only HIENT is skipped. The denylist, absolute
+ * paths, emails, private-key markers and binary classification still judge this
+ * file, because minification would carry a real leak through unchanged.
+ */
+const DERIVED_BUNDLES = new Set(["src/service/assets/control-center.html"]);
+
+export function highEntropyHeuristicApplies(relFile) {
+  const posix = relFile.replaceAll("\\", "/");
+  if (DERIVED_BUNDLES.has(posix)) return false;
+  return !DEPENDENCY_LOCKFILES.has(path.posix.basename(posix));
+}
+
+export function loadDenylist(file) {
+  const lines = fs.readFileSync(file, "utf8").split(/\r?\n/);
+  return lines
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith("#"))
+    .map((pattern, i) => ({ id: `DL-${i + 1}`, pattern: pattern.toLowerCase() }));
+}
+
+function shannonEntropy(s) {
+  const freq = {};
+  for (const ch of s) freq[ch] = (freq[ch] ?? 0) + 1;
+  return -Object.values(freq).reduce((acc, n) => {
+    const p = n / s.length;
+    return acc + p * Math.log2(p);
+  }, 0);
+}
+
+function isBinary(buf) {
+  const n = Math.min(buf.length, 8000);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+/** Byte-searchable P0 rules over a latin1 decode (1:1 byte↔char for ASCII), so
+ *  denylist entries, paths, emails, and key markers are caught even inside a
+ *  binary blob or after an embedded NUL. Never echoes matched values. */
+export function scanBytes(relFile, buf, denylist) {
+  const findings = [];
+  const latin1 = buf.toString("latin1");
+  const lower = latin1.toLowerCase();
+  for (const { id, pattern } of denylist) {
+    if (lower.includes(pattern)) findings.push({ ruleId: id, severity: "P0", file: relFile, line: 0 });
+  }
+  if (RULES.ABS_HOME.re.test(latin1)) findings.push({ ruleId: RULES.ABS_HOME.id, severity: "P0", file: relFile, line: 0 });
+  RULES.ABS_HOME.re.lastIndex = 0;
+  for (const m of latin1.matchAll(RULES.EMAIL.re)) {
+    if (!EMAIL_ALLOWED.test(m[0])) findings.push({ ruleId: RULES.EMAIL.id, severity: "P0", file: relFile, line: 0 });
+  }
+  if (RULES.KEY.re.test(latin1)) findings.push({ ruleId: RULES.KEY.id, severity: "P0", file: relFile, line: 0 });
+  RULES.KEY.re.lastIndex = 0;
+  return findings;
+}
+
+export function scanContent(relFile, text, denylist) {
+  const findings = [];
+  const lines = text.split("\n");
+  const lowerLines = lines.map((l) => l.toLowerCase());
+  const scanHighEntropy = highEntropyHeuristicApplies(relFile);
+
+  for (const { id, pattern } of denylist) {
+    lowerLines.forEach((l, i) => {
+      if (l.includes(pattern)) findings.push({ ruleId: id, severity: "P0", file: relFile, line: i + 1 });
+    });
+    if (relFile.toLowerCase().includes(pattern))
+      findings.push({ ruleId: id, severity: "P0", file: relFile, line: 0 });
+  }
+
+  lines.forEach((l, i) => {
+    if (RULES.ABS_HOME.re.test(l)) findings.push({ ruleId: RULES.ABS_HOME.id, severity: "P0", file: relFile, line: i + 1 });
+    RULES.ABS_HOME.re.lastIndex = 0;
+
+    for (const m of l.matchAll(RULES.EMAIL.re)) {
+      if (!EMAIL_ALLOWED.test(m[0])) findings.push({ ruleId: RULES.EMAIL.id, severity: "P0", file: relFile, line: i + 1 });
+    }
+
+    if (RULES.KEY.re.test(l)) findings.push({ ruleId: RULES.KEY.id, severity: "P0", file: relFile, line: i + 1 });
+    RULES.KEY.re.lastIndex = 0;
+
+    if (scanHighEntropy) {
+      for (const m of l.matchAll(RULES.HIENT.re)) {
+        // Entropy heuristic; thresholds change only alongside fixture updates proving the change.
+        if (m[0].length >= 40 && shannonEntropy(m[0]) > 4.5 && /[A-Z]/.test(m[0]) && /[a-z]/.test(m[0]) && /[0-9]/.test(m[0])) {
+          findings.push({ ruleId: RULES.HIENT.id, severity: "P1", file: relFile, line: i + 1 });
+        }
+      }
+    }
+  });
+
+  if (/(^|\/)\.env(\.|rc$|$)/.test(relFile)) findings.push({ ruleId: "ENVFILE", severity: "P0", file: relFile, line: 0 });
+
+  return findings;
+}
+
+function* walk(dir, root) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) {
+      // Never skip silently: a symlink target can carry an absolute home path,
+      // username, or internal host. Yield it so its target is scanned.
+      yield { rel: path.relative(root, full), symlink: true };
+      continue;
+    }
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) yield* walk(full, root);
+    } else if (entry.isFile()) {
+      yield path.relative(root, full);
+    }
+  }
+}
+
+function stagedFiles(root) {
+  const out = execFileSync("git", ["-C", root, "diff", "--cached", "--name-only", "-z", "--diff-filter=ACMR"], { encoding: "utf8" });
+  return out.split("\0").filter(Boolean);
+}
+
+/**
+ * A repository scan covers exactly what can enter version control: tracked and
+ * non-ignored untracked files. Build caches contain machine paths, integrity
+ * hashes, compiled third-party code, and binary archives; walking them produces
+ * noise while saying nothing about what the repository can publish.
+ *
+ * Fall back to the conservative filesystem walk for non-git directories and
+ * subdirectory roots, which keeps standalone fixture/scaffold scanning useful.
+ */
+function treeEntries(root) {
+  try {
+    const quietGit = { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] };
+    const top = execFileSync("git", ["-C", root, "rev-parse", "--show-toplevel"], quietGit).trim();
+    if (fs.realpathSync(top) !== fs.realpathSync(root)) throw new Error("root is not repository top");
+    const out = execFileSync("git", ["-C", root, "ls-files", "--cached", "--others", "--exclude-standard", "-z"], quietGit);
+    return out.split("\0").filter(Boolean).flatMap((rel) => {
+      const full = path.join(root, rel);
+      if (!fs.existsSync(full)) return []; // deleted tracked content cannot leak from the tree
+      return [{ rel, symlink: fs.lstatSync(full).isSymbolicLink() }];
+    });
+  } catch {
+    return [...walk(root, root)].map((e) => (typeof e === "string" ? { rel: e } : e));
+  }
+}
+
+/** Denylist entries must never appear in output - including inside file paths.
+ *  Uses a write cursor so an inserted `[DL-n]` marker is never re-scanned
+ *  (a denylist entry like "dl" could otherwise match its own marker and loop). */
+export function redactText(text, denylist) {
+  let out = text;
+  for (const { id, pattern } of denylist) {
+    let result = "";
+    let from = 0;
+    const lower = out.toLowerCase();
+    let idx;
+    while ((idx = lower.indexOf(pattern, from)) !== -1) {
+      result += out.slice(from, idx) + `[${id}]`;
+      from = idx + pattern.length;
+    }
+    out = result + out.slice(from);
+  }
+  return out;
+}
+
+export function loadAllowBinary(file) {
+  if (!file) return new Set();
+  return new Set(
+    fs.readFileSync(file, "utf8").split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith("#"))
+  );
+}
+
+export function runScan({ root, staged, denylistPath, allowBinaryPath, allowBinary }) {
+  const denylist = denylistPath ? loadDenylist(denylistPath) : [];
+  const allow = allowBinary ?? loadAllowBinary(allowBinaryPath);
+  const entries = staged ? stagedFiles(root).map((rel) => ({ rel })) : treeEntries(root);
+  const findings = [];
+  for (const entry of entries) {
+    const rel = entry.rel;
+    const relPosix = rel.split(path.sep).join("/");
+    const full = path.join(root, rel);
+
+    // Symlinks (tree mode): scan the target STRING for leaks, never follow.
+    if (entry.symlink) {
+      let target = "";
+      try {
+        target = fs.readlinkSync(full);
+      } catch {
+        findings.push({ ruleId: "SCAN-UNREADABLE", severity: "P0", file: relPosix, line: 0, detail: "symlink unreadable - fail closed" });
+        continue;
+      }
+      findings.push(...scanBytes(relPosix, Buffer.from(target, "utf8"), denylist));
+      continue;
+    }
+
+    let buf;
+    try {
+      buf = staged
+        ? execFileSync("git", ["-C", root, "show", `:${rel}`], { maxBuffer: 512 * 1024 * 1024 })
+        : fs.readFileSync(full);
+    } catch (e) {
+      // Fail closed: an unreadable/oversize file blocks the gate instead of
+      // being silently skipped (the pre-commit staged mode especially).
+      findings.push({ ruleId: "SCAN-UNREADABLE", severity: "P0", file: relPosix, line: 0, detail: `unscannable (${e.code ?? "read error"}) - fail closed` });
+      continue;
+    }
+    if (isBinary(buf)) {
+      // Never silently skip: byte-scan for leaks, and classify the binary.
+      findings.push(...scanBytes(relPosix, buf, denylist));
+      const cls = classifyExtension(relPosix);
+      if (cls === "text")
+        findings.push({ ruleId: "BIN-TEXT", severity: "P0", file: relPosix, line: 0, detail: "text-expected file is binary (leak-scan blind spot)" });
+      else if (cls === "unknown" && !allow.has(relPosix))
+        findings.push({ ruleId: "BIN-UNCLASSIFIED", severity: "P0", file: relPosix, line: 0, detail: "unclassified binary; add to --allow-binary if a legitimate asset" });
+      continue;
+    }
+    findings.push(...scanContent(relPosix, buf.toString("utf8"), denylist));
+  }
+  const safeFindings = findings.map((f) => ({ ...f, file: redactText(f.file, denylist) }));
+  const counts = { P0: findings.filter((f) => f.severity === "P0").length, P1: findings.filter((f) => f.severity === "P1").length };
+  return { version: 1, root: redactText(path.resolve(root), denylist), mode: staged ? "staged" : "tree", rulesLoaded: { denylist: denylist.length, builtin: Object.keys(RULES).length + 2 }, counts, findings: safeFindings };
+}
+
+function formatHuman(report) {
+  const lines = [`privacy scan (${report.mode}) - ${report.findings.length} finding(s), P0=${report.counts.P0} P1=${report.counts.P1}`];
+  for (const f of report.findings) lines.push(`  [${f.severity}] ${f.ruleId} ${f.file}${f.line ? ":" + f.line : ""}`);
+  if (!report.findings.length) lines.push("  clean");
+  return lines.join("\n");
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs({
+      options: {
+        denylist: { type: "string" },
+        root: { type: "string", default: "." },
+        staged: { type: "boolean", default: false },
+        "allow-binary": { type: "string" },
+        json: { type: "boolean", default: false },
+        out: { type: "string" },
+        help: { type: "boolean", default: false },
+      },
+      allowPositionals: false,
+    }).values;
+  } catch (err) {
+    console.error(String(err.message ?? err));
+    console.error(USAGE);
+    process.exit(2);
+  }
+  if (args.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  if (!fs.existsSync(args.root) || !fs.statSync(args.root).isDirectory()) {
+    console.error(`root is not a directory: ${args.root}`);
+    process.exit(2);
+  }
+  if (args.denylist && !fs.existsSync(args.denylist)) {
+    console.error(`denylist file not found`);
+    process.exit(2);
+  }
+  if (args["allow-binary"] && !fs.existsSync(args["allow-binary"])) {
+    console.error(`allow-binary file not found`);
+    process.exit(2);
+  }
+  const report = runScan({ root: args.root, staged: args.staged, denylistPath: args.denylist, allowBinaryPath: args["allow-binary"] });
+  const output = args.json ? JSON.stringify(report, null, 2) : formatHuman(report);
+  console.log(output);
+  if (args.out) {
+    const outDir = path.dirname(path.resolve(args.out));
+    const tmpOut = path.join(outDir, `.tmp-report-${process.pid}`);
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(tmpOut, JSON.stringify(report, null, 2) + "\n");
+    fs.renameSync(tmpOut, path.resolve(args.out));
+  }
+  process.exit(report.findings.length ? 1 : 0);
+}
+
+// Main-module guard: realpath both sides - Node resolves symlinks (e.g. /tmp
+// on macOS) when building import.meta.url for the entry module.
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) main();

package/scripts/validate/README.md

@@ -0,0 +1,94 @@
+# Deterministic validators
+
+**The rule that separates a validator from a test.** A validator inspects an
+artifact that exists in the repository, or one it constructs deterministically
+in a temp directory within the same run and deletes afterwards. It has no
+committed fixtures, no test framework, no phase labels, and no simulated
+product. It must FAIL rather than skip when its input is absent.
+
+That last sentence is the whole point. A gate that turns itself off when the
+thing it guards goes missing is worse than no gate, because it reports success
+while checking nothing.
+
+This repository ships no automated test suite for the plugin itself. Quality is
+proven here, against real artifacts, and by building a real product with the
+tool. Products built with Superdev do get tests; Superdev does not test a
+simulated copy of itself. `no-tests.mjs` is the guard that stops the suite
+growing back.
+
+## Running
+
+```sh
+npm run validate                       # the repository in the working directory
+node scripts/validate/validate-all.mjs --root <path>
+node scripts/validate/validate-all.mjs --only migrations,imports
+node scripts/validate/validate-all.mjs --json --out report.json
+```
+
+Exit codes: `0` no findings, `1` findings, `2` usage error.
+
+`--out` writes exactly the machine-readable report, atomically, and nothing is
+written without it.
+
+## Interface
+
+Every validator is a standalone module exporting `run(root)`:
+
+```js
+{ name: "migrations", findings: [{ code, severity, path, message }] }
+```
+
+- `code` is stable and greppable (`MG-007`), so a finding can be referred to.
+- `severity` is `error` or `warning`. Both are findings and both exit non-zero;
+  the distinction says how urgent it is, not whether it counts.
+- `path` is repo-relative with forward slashes, optionally `:line` or
+  `:line:column`. An absolute machine path never appears in output.
+- `message` says what is wrong and, where it is not obvious, what to do.
+
+A validator that throws is reported as a `VA-001` finding against itself. A
+broken validator never reads as a passing run.
+
+## The validators
+
+| Module | Checks | Fails when its input is absent |
+|---|---|---|
+| `manifests.mjs` | Claude, Codex and marketplace manifests plus `hooks.json`: valid JSON, required fields, kebab name, no absolute or escaping paths | a manifest is missing |
+| `skills.mjs` | `skills/*/SKILL.md`: frontmatter parses, name matches directory, description present and under 1024 characters, body under 500 lines, no working-directory-dependent commands, every named file resolves | `skills/` is missing or empty |
+| `docs-templates.mjs` | Docs templates and fragments stay neutral: no vendor, latency, cloud region, compliance regime or concrete environment variable | the templates or fragments directory is missing |
+| `migrations.mjs` | Builds a throwaway database in a temp directory, applies the full ordered set forward, runs integrity and foreign key checks, asserts the applied list equals the checked-in files, proves the task mapping constraint and the append-only triggers fire and that a mapped task still passes, then deletes it | no migration files are found |
+| `markdown.mjs` | Generated Markdown under `talks/` carries a generation marker, its body still hashes to the recorded hash, and every relative link resolves | `talks/` is missing or holds no Markdown |
+| `style.mjs` | No em dash character and no emoji in project-owned content | there are no project-owned text files |
+| `privacy.mjs` | No absolute home paths, no secret-shaped strings, no private project identifiers | there are no project-owned text files |
+| `imports.mjs` | Every module under `src/` and `scripts/` imports only node builtins, relative paths, or the one allowlisted runtime dependency, which only `src/db/connect.mjs` may import | neither directory exists |
+| `dependencies.mjs` | `package.json` declares only allowlisted runtime dependencies, pins them exactly, declares the Node floor, and carries no dev toolchain | `package.json` is missing |
+| `no-tests.mjs` | No `*.test.mjs`, no test or fixture tree, no test runner script or framework dependency | never; a missing root is itself the finding |
+| `footprint.mjs` | No file-per-record operational tracking: no file named after a task, subtask, assignment, transition, evidence item, activity event, session, agent, branch, memory entry, sync cursor or conflict, and no directory named after one that has filled with data documents | never; an empty root is itself the finding |
+
+## Private identifiers
+
+The denylist of private project identifiers lives outside this repository by
+design and is supplied at run time:
+
+```sh
+SUPERDEV_DENYLIST=<path outside the repo> npm run validate
+```
+
+Entries are never echoed into output. Findings carry a rule id and a location
+only, because printing the matched value would be the leak the scan exists to
+prevent. When the variable points at a file that does not exist, `privacy.mjs`
+reports it rather than passing: a check that silently did not run must not read
+as a check that passed.
+
+The screening rules themselves come from `src/model/screening.mjs`, the same
+module the storage boundary uses, so a string the database would refuse cannot
+arrive through a file instead.
+
+## Adding one
+
+Write `scripts/validate/<name>.mjs` exporting `name` and `run(root)`, then add
+it to `VALIDATORS` in `validate-all.mjs`. Declaration order is report order.
+
+Before adding it, check it against the rule at the top of this file. If it needs
+a fixture, it is a test. If it simulates product behavior, it is a test. If it
+passes quietly when the artifact it inspects is not there, it is worse than a
+test.