dsh-vet 0.1.0

package/lib/index.mjs

@@ -0,0 +1,1741 @@
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { parse } from "acorn";
+import { spawn } from "node:child_process";
+import { homedir, tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+import { parseArgs } from "node:util";
+//#region src/contract.ts
+/**
+* The `dsh-vet/v1` report contract: a machine-readable, implementation-
+* agnostic audit report for DeepSeek Harness (DSH) plugins. Any scanner may
+* emit it; any marketplace, CI job, or UI may consume it. See
+* `docs/dsh-vet-v1.md` for the normative spec.
+*
+* Two design rules are encoded here, not just documented:
+* - Findings are signals, not verdicts: a finding with `low` confidence never
+*   lowers a grade, and `info` severity never does either.
+* - Reports are deterministic: findings are sorted, and the summary is always
+*   derived, never asserted by the emitter.
+*
+* @module dsh-vet/contract
+*/
+/** Literal `schema` value every dsh-vet/v1 report carries. */
+const SCHEMA_ID = "dsh-vet/v1";
+const SEVERITY_RANK = {
+	critical: 0,
+	high: 1,
+	medium: 2,
+	low: 3,
+	info: 4
+};
+/**
+* Rule ids are two or more dot-separated lowercase segments
+* (`perm.broad-fs-write`, `acme.eval-detect`). Deliberately open-ended about
+* segment count so vendor-prefixed rule sets work — a closed single-segment
+* pattern is how the dsh-doctor contract initially broke third-party ids.
+*/
+const RULE_ID_PATTERN = /^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/;
+/** True when a finding participates in grading: not `info`, not low-confidence. */
+function isGraded(finding) {
+	return finding.severity !== "info" && finding.confidence !== "low";
+}
+/** Per-severity finding totals. */
+function countFindings(findings) {
+	const counts = {
+		critical: 0,
+		high: 0,
+		medium: 0,
+		low: 0,
+		info: 0
+	};
+	for (const finding of findings) counts[finding.severity] += 1;
+	return counts;
+}
+/**
+* Derive the grade from graded findings only: worst severity decides.
+* `low`-confidence and `info` findings are reported but never lower a grade.
+*/
+function gradeFor(findings) {
+	let worst;
+	for (const finding of findings) {
+		if (!isGraded(finding)) continue;
+		if (worst === void 0 || SEVERITY_RANK[finding.severity] < SEVERITY_RANK[worst]) worst = finding.severity;
+	}
+	switch (worst) {
+		case void 0:
+		case "info": return "A";
+		case "low": return "B";
+		case "medium": return "C";
+		case "high": return "D";
+		case "critical": return "F";
+	}
+}
+/**
+* Build a normalized report: validates rule ids, sorts findings
+* deterministically (worst severity first, then id ascending), and derives
+* the summary. Emitters must go through this instead of assembling a report
+* by hand — it is what keeps two runs over the same artifact identical.
+*/
+function createReport(input) {
+	for (const finding of input.findings) if (!RULE_ID_PATTERN.test(finding.id)) throw new Error(`invalid dsh-vet/v1 rule id: ${JSON.stringify(finding.id)}`);
+	const findings = [...input.findings].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || a.id.localeCompare(b.id));
+	return {
+		schema: SCHEMA_ID,
+		target: input.target,
+		scanner: input.scanner,
+		summary: {
+			grade: gradeFor(findings),
+			counts: countFindings(findings)
+		},
+		findings
+	};
+}
+//#endregion
+//#region src/analyze.ts
+/**
+* Analysis engine (ROADMAP T2): parse shipped JS with acorn, build the static
+* module graph, and classify the capability surface each file touches.
+*
+* Everything here is best-effort static analysis (ROADMAP D2): call arguments
+* that depend on runtime values are recorded without interpretation, and the
+* rules decide how much confidence that earns.
+*/
+const BUILTIN_BASE = {
+	fs: ["fs"],
+	"node:fs": ["fs"],
+	"fs/promises": ["fs"],
+	"node:fs/promises": ["fs"],
+	"node:child_process": ["shell"],
+	child_process: ["shell"],
+	net: ["net"],
+	"node:net": ["net"],
+	http: ["net"],
+	"node:http": ["net"],
+	https: ["net"],
+	"node:https": ["net"],
+	http2: ["net"],
+	"node:http2": ["net"],
+	tls: ["net"],
+	"node:tls": ["net"],
+	dgram: ["net"],
+	"node:dgram": ["net"],
+	dns: ["net"],
+	"node:dns": ["net"],
+	"node:worker_threads": ["workers"],
+	worker_threads: ["workers"],
+	"node:crypto": ["crypto"],
+	crypto: ["crypto"]
+};
+const FS_WRITE_METHODS = /* @__PURE__ */ new Set([
+	"writeFile",
+	"appendFile",
+	"rm",
+	"unlink",
+	"rmdir",
+	"truncate",
+	"rename",
+	"cp",
+	"createWriteStream",
+	"chmod",
+	"chown",
+	"writev"
+]);
+for (const m of [...FS_WRITE_METHODS]) FS_WRITE_METHODS.add(`${m}Sync`);
+const FS_READ_METHODS = /* @__PURE__ */ new Set([
+	"readFile",
+	"readdir",
+	"createReadStream",
+	"stat",
+	"lstat",
+	"exists",
+	"open",
+	"access"
+]);
+for (const m of [...FS_READ_METHODS]) FS_READ_METHODS.add(`${m}Sync`);
+const SHELL_METHODS = /* @__PURE__ */ new Set([
+	"spawn",
+	"exec",
+	"execFile",
+	"fork",
+	"spawnSync",
+	"execSync",
+	"execFileSync"
+]);
+const NET_METHODS = /* @__PURE__ */ new Set([
+	"request",
+	"get",
+	"connect",
+	"createConnection",
+	"createSocket",
+	"lookup",
+	"resolve"
+]);
+const HOMEDIR_METHODS = /* @__PURE__ */ new Set(["homedir", "userInfo"]);
+const CREDENTIAL_PATH_RE = /(?:^|[/\\])(?:\.env[^/\\]*|\.dsh|credentials|auth\.json|token|secret|\.npmrc|\.netrc|\.aws|\.ssh|\.gitconfig)(?:$|[/\\])/i;
+function toPosix(p) {
+	return p.split("\\").join("/");
+}
+function snippetAt(code, line) {
+	return (code.split("\n")[line - 1] ?? "").trim().slice(0, 120);
+}
+function listJsFiles(rootDir) {
+	const out = [];
+	const walk = (dir) => {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			if (entry.name === "node_modules" || entry.name === ".git" || entry.name.startsWith(".DS")) continue;
+			const abs = join(dir, entry.name);
+			if (entry.isDirectory()) walk(abs);
+			else if (/\.(?:js|mjs|cjs)$/.test(entry.name)) out.push(abs);
+			else if (!entry.name.includes(".")) {
+				const head = readFileSync(abs, "utf8").slice(0, 64);
+				if (/^#![^\n]*\bnode\b/.test(head)) out.push(abs);
+			}
+		}
+	};
+	walk(rootDir);
+	return out.sort();
+}
+function parseSource(path, code) {
+	const options = {
+		ecmaVersion: "latest",
+		locations: true
+	};
+	try {
+		return {
+			ast: parse(code, {
+				...options,
+				sourceType: "module"
+			}),
+			sourceType: "module",
+			parseError: null
+		};
+	} catch (moduleError) {
+		try {
+			return {
+				ast: parse(code, {
+					...options,
+					sourceType: "script",
+					allowReturnOutsideFunction: true
+				}),
+				sourceType: "script",
+				parseError: null
+			};
+		} catch {
+			return {
+				ast: null,
+				sourceType: null,
+				parseError: moduleError.message
+			};
+		}
+	}
+}
+function argLiterals(args) {
+	const out = [];
+	for (const arg of args) {
+		if (arg.type === "Literal" && typeof arg.value === "string") out.push(arg.value);
+		if (arg.type === "TemplateLiteral" && arg.expressions.length === 0) out.push(arg.quasis[0]?.value.raw ?? "");
+	}
+	return out;
+}
+/** Best-effort static string evaluation for require()/import() arguments. */
+function staticString(node) {
+	if (!node) return null;
+	if (node.type === "Literal" && typeof node.value === "string") return node.value;
+	if (node.type === "TemplateLiteral" && node.expressions.length === 0) return node.quasis[0]?.value.raw ?? "";
+	if (node.type === "BinaryExpression" && node.operator === "+") {
+		const left = staticString(node.left);
+		const right = staticString(node.right);
+		return left !== null && right !== null ? left + right : null;
+	}
+	return null;
+}
+function isProcessEnv(node) {
+	return node.type === "MemberExpression" && !node.computed && node.object.type === "Identifier" && node.object.name === "process" && node.property.type === "Identifier" && node.property.name === "env";
+}
+function classifyMethodUse(file, module, method) {
+	const api = `${module}.${method}`;
+	if (module === "fs" || module === "node:fs" || module === "fs/promises" || module === "node:fs/promises") {
+		if (FS_WRITE_METHODS.has(method)) return {
+			caps: ["fs", "fs-write"],
+			api
+		};
+		if (FS_READ_METHODS.has(method)) return {
+			caps: ["fs"],
+			api
+		};
+		return {
+			caps: [],
+			api
+		};
+	}
+	if (module === "child_process" || module === "node:child_process") {
+		if (SHELL_METHODS.has(method)) return {
+			caps: ["shell"],
+			api
+		};
+		return {
+			caps: [],
+			api
+		};
+	}
+	if (module === "os" || module === "node:os") {
+		if (HOMEDIR_METHODS.has(method)) return {
+			caps: ["homedir"],
+			api
+		};
+		return {
+			caps: [],
+			api
+		};
+	}
+	if (BUILTIN_BASE[module]?.includes("net")) {
+		if (NET_METHODS.has(method)) return {
+			caps: ["net"],
+			api
+		};
+		return {
+			caps: [],
+			api
+		};
+	}
+	return {
+		caps: [],
+		api
+	};
+}
+/**
+* Walk one parsed file, collecting imports, capability uses, and obfuscation
+* signals into the shared analysis arrays.
+*/
+function inspectFile(analysis, file, ast) {
+	const bindings = /* @__PURE__ */ new Map();
+	const seenLines = /* @__PURE__ */ new Set();
+	const pushCap = (cap, line, api, literals, snippet) => {
+		const key = `${file.path}:${line}:${api}:${cap}`;
+		if (seenLines.has(key)) return;
+		seenLines.add(key);
+		analysis.capUses.push({
+			cap,
+			file: file.path,
+			line,
+			api,
+			literals,
+			snippet
+		});
+	};
+	const visit = (node) => {
+		if (!node || typeof node !== "object") return;
+		const n = node;
+		const here = node;
+		const line = here.loc?.start.line ?? 0;
+		switch (here.type) {
+			case "ImportDeclaration":
+			case "ExportNamedDeclaration":
+			case "ExportAllDeclaration": {
+				const source = n.source;
+				if (source?.value) {
+					file.imports.push({
+						specifier: source.value,
+						line
+					});
+					if (!source.value.startsWith(".")) file.externals.push(source.value);
+					const spec = source.value.replace(/^node:/, "");
+					if (here.type === "ImportDeclaration") {
+						for (const spec2 of n.specifiers ?? []) if (spec2.type === "ImportDefaultSpecifier" || spec2.type === "ImportNamespaceSpecifier") bindings.set(spec2.local.name, { module: spec });
+						else if (spec2.type === "ImportSpecifier") bindings.set(spec2.local.name, {
+							module: spec,
+							imported: spec2.imported.name
+						});
+					}
+				}
+				break;
+			}
+			case "VariableDeclarator": {
+				const init = n.init;
+				if (n.id?.type === "Identifier" && init?.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "require") {
+					const arg = staticString(init.arguments[0]);
+					if (arg !== null) {
+						file.imports.push({
+							specifier: arg,
+							line
+						});
+						if (!arg.startsWith(".")) file.externals.push(arg);
+						bindings.set(n.id.name, { module: arg.replace(/^node:/, "") });
+					}
+				}
+				if (n.id?.type === "ObjectPattern" && init?.type === "CallExpression") {
+					const arg = staticString(init.arguments[0]);
+					if (arg !== null && init.callee.type === "Identifier" && init.callee.name === "require") {
+						for (const prop of n.id.properties ?? []) if (prop.type === "Property" && prop.value.type === "Identifier" && prop.key.type === "Identifier") bindings.set(prop.value.name, {
+							module: arg.replace(/^node:/, ""),
+							imported: prop.key.name
+						});
+					}
+				}
+				break;
+			}
+			case "MemberExpression":
+				if (isProcessEnv(here) || isProcessEnv(n.object)) pushCap("env", line, "process.env", [], snippetAt(file.code, line));
+				break;
+			case "CallExpression":
+			case "NewExpression": {
+				const callee = n.callee;
+				const args = n.arguments ?? [];
+				const literals = argLiterals(args);
+				const snippet = snippetAt(file.code, line);
+				const isNew = here.type === "NewExpression";
+				if (callee.type === "Identifier") {
+					const name = callee.name;
+					const binding = bindings.get(name);
+					if (name === "eval") analysis.evalUses.push({
+						file: file.path,
+						line,
+						kind: "eval",
+						literal: literals.length > 0,
+						snippet
+					});
+					else if (name === "Function" && isNew) analysis.evalUses.push({
+						file: file.path,
+						line,
+						kind: "Function",
+						literal: literals.length > 0,
+						snippet
+					});
+					else if (name === "fetch" || name === "WebSocket") {
+						analysis.netUses.push({
+							file: file.path,
+							line,
+							api: name,
+							literals,
+							snippet
+						});
+						pushCap("net", line, name, literals, snippet);
+					} else if (name === "require" && !isNew) {
+						const arg = args[0];
+						const value = staticString(arg);
+						if (arg?.type === "Literal" && value !== null) {
+							file.imports.push({
+								specifier: value,
+								line
+							});
+							if (!value.startsWith(".")) file.externals.push(value);
+						} else if (value !== null) {
+							file.imports.push({
+								specifier: value,
+								line
+							});
+							if (!value.startsWith(".")) file.externals.push(value);
+							analysis.dynamicImports.push({
+								file: file.path,
+								line,
+								kind: "require",
+								literals: [value],
+								snippet
+							});
+						} else analysis.dynamicImports.push({
+							file: file.path,
+							line,
+							kind: "require",
+							literals: null,
+							snippet
+						});
+					} else if (name === "Worker" && binding?.module === "worker_threads") pushCap("workers", line, "worker_threads.Worker", literals, snippet);
+					else if (binding) {
+						if ("imported" in binding) {
+							const { caps, api } = classifyMethodUse(file, binding.module, binding.imported);
+							for (const cap of caps) pushCap(cap, line, api, literals, snippet);
+							if (BUILTIN_BASE[binding.module]?.includes("net") && NET_METHODS.has(binding.imported)) analysis.netUses.push({
+								file: file.path,
+								line,
+								api,
+								literals,
+								snippet
+							});
+						} else if (BUILTIN_BASE[binding.module]) for (const cap of BUILTIN_BASE[binding.module]) pushCap(cap, line, binding.module, literals, snippet);
+					}
+				} else if (callee.type === "MemberExpression") {
+					const object = callee.object;
+					const property = callee.property;
+					const propName = property.type === "Identifier" && !callee.computed ? property.name : null;
+					if (object.type === "Identifier") {
+						const binding = bindings.get(object.name);
+						if (binding && propName) {
+							const method = "imported" in binding ? binding.imported : propName;
+							const module = binding.module;
+							const { caps, api } = classifyMethodUse(file, module, method);
+							for (const cap of caps) {
+								const enriched = cap === "fs" && FS_READ_METHODS.has(method) && literals.some((l) => CREDENTIAL_PATH_RE.test(l)) ? [cap, "secret-read"] : [cap];
+								for (const c of enriched) pushCap(c, line, api, literals, snippet);
+							}
+							if (BUILTIN_BASE[module]?.includes("net") && NET_METHODS.has(method)) analysis.netUses.push({
+								file: file.path,
+								line,
+								api,
+								literals,
+								snippet
+							});
+						} else if (object.name === "String" && propName === "fromCharCode") {
+							const nums = args.filter((a) => a.type === "Literal" && typeof a.value === "number");
+							if (nums.length >= 8) analysis.charcodeCalls.push({
+								file: file.path,
+								line,
+								chars: String.fromCharCode(...nums.map((a) => a.value)).slice(0, 48)
+							});
+						} else if (object.name === "http" || object.name === "https" || object.name === "net") {
+							if (NET_METHODS.has(propName ?? "")) {
+								analysis.netUses.push({
+									file: file.path,
+									line,
+									api: `${object.name}.${propName}`,
+									literals,
+									snippet
+								});
+								pushCap("net", line, `${object.name}.${propName}`, literals, snippet);
+							}
+						}
+					} else if (object.type === "MemberExpression" && isProcessEnv(object)) pushCap("env", line, "process.env", [], snippet);
+				}
+				break;
+			}
+			case "ImportExpression": {
+				const source = n.source;
+				const value = staticString(source);
+				const snippet = snippetAt(file.code, line);
+				if (source?.type === "Literal" && value !== null) {
+					file.imports.push({
+						specifier: value,
+						line
+					});
+					if (!value.startsWith(".")) file.externals.push(value);
+				} else if (value !== null) {
+					file.imports.push({
+						specifier: value,
+						line
+					});
+					if (!value.startsWith(".")) file.externals.push(value);
+					analysis.dynamicImports.push({
+						file: file.path,
+						line,
+						kind: "import",
+						literals: [value],
+						snippet
+					});
+				} else analysis.dynamicImports.push({
+					file: file.path,
+					line,
+					kind: "import",
+					literals: null,
+					snippet
+				});
+				break;
+			}
+			case "Literal": {
+				const value = n.value;
+				if (typeof value === "string" && value.length >= 48 && !/\s/.test(value)) {
+					if (/^[A-Za-z0-9+/=]+$/.test(value) && /\d/.test(value) && /[A-Z]/.test(value)) analysis.encodedLiterals.push({
+						file: file.path,
+						line,
+						value,
+						charset: "base64"
+					});
+					else if (/^[0-9a-fA-F]+$/.test(value)) {
+						if (new Set(value).size >= 8) analysis.encodedLiterals.push({
+							file: file.path,
+							line,
+							value,
+							charset: "hex"
+						});
+					}
+				}
+				break;
+			}
+		}
+		for (const [key, value] of Object.entries(n)) {
+			if (key === "loc" || key === "start" || key === "end" || key === "range") continue;
+			if (Array.isArray(value)) for (const child of value) visit(child);
+			else if (value && typeof value === "object" && "type" in value) visit(value);
+		}
+	};
+	visit(ast);
+}
+function resolveRelative(rootDir, fromFile, spec) {
+	const base = resolve(rootDir, dirname(fromFile), spec);
+	const candidates = [
+		base,
+		`${base}.js`,
+		`${base}.cjs`,
+		`${base}.mjs`,
+		`${base}.json`,
+		join(base, "index.js"),
+		join(base, "index.cjs"),
+		join(base, "index.mjs")
+	];
+	for (const candidate of candidates) try {
+		readFileSync(candidate);
+		return toPosix(relative(rootDir, candidate));
+	} catch {}
+	return null;
+}
+function flattenExports(node, out) {
+	if (typeof node === "string") out.push(node);
+	else if (node && typeof node === "object") for (const value of Object.values(node)) flattenExports(value, out);
+}
+function entryHints(pkg) {
+	const hints = /* @__PURE__ */ new Set();
+	if (pkg.raw["main"] && typeof pkg.raw["main"] === "string") hints.add(pkg.raw["main"]);
+	if (pkg.raw["module"] && typeof pkg.raw["module"] === "string") hints.add(pkg.raw["module"]);
+	const exports = pkg.raw["exports"];
+	if (exports && typeof exports === "object") {
+		const flattened = [];
+		flattenExports(exports, flattened);
+		for (const f of flattened) hints.add(f);
+	}
+	const bin = pkg.raw["bin"];
+	if (typeof bin === "string") hints.add(bin);
+	else if (bin && typeof bin === "object") {
+		for (const value of Object.values(bin)) if (typeof value === "string") hints.add(value);
+	}
+	if (hints.size === 0) hints.add("index.js");
+	return [...hints];
+}
+function readPkg(rootDir) {
+	try {
+		const raw = JSON.parse(readFileSync(join(rootDir, "package.json"), "utf8"));
+		const asRecord = (value) => value && typeof value === "object" ? value : {};
+		const dsh = raw["dsh"];
+		const seams = Array.isArray(dsh?.["seams"]) ? dsh["seams"] : null;
+		const pkg = {
+			raw,
+			name: typeof raw["name"] === "string" ? raw["name"] : "",
+			version: typeof raw["version"] === "string" ? raw["version"] : "",
+			scripts: asRecord(raw["scripts"]),
+			dependencies: asRecord(raw["dependencies"]),
+			devDependencies: asRecord(raw["devDependencies"]),
+			seams,
+			entryHints: []
+		};
+		pkg.entryHints = entryHints(pkg);
+		return pkg;
+	} catch {
+		return null;
+	}
+}
+const byFileLine = (a, b) => a.file.localeCompare(b.file) || a.line - b.line;
+/** Analyze a package directory: parse, walk, and build the module graph. */
+function analyze(rootDir) {
+	const pkg = readPkg(rootDir);
+	const analysis = {
+		rootDir,
+		pkg,
+		files: [],
+		fileByPath: /* @__PURE__ */ new Map(),
+		entries: [],
+		reachable: /* @__PURE__ */ new Set(),
+		unreachable: [],
+		edges: /* @__PURE__ */ new Map(),
+		capUses: [],
+		netUses: [],
+		evalUses: [],
+		dynamicImports: [],
+		encodedLiterals: [],
+		charcodeCalls: []
+	};
+	for (const abs of listJsFiles(rootDir)) {
+		const path = toPosix(relative(rootDir, abs));
+		const code = readFileSync(abs, "utf8");
+		const parsed = parseSource(path, code);
+		const file = {
+			path,
+			code,
+			sourceType: parsed.sourceType,
+			parseError: parsed.parseError,
+			ast: parsed.ast,
+			imports: [],
+			externals: []
+		};
+		analysis.files.push(file);
+		analysis.fileByPath.set(path, file);
+	}
+	for (const file of analysis.files) {
+		if (file.ast) inspectFile(analysis, file, file.ast);
+		file.imports.sort((a, b) => a.specifier.localeCompare(b.specifier) || a.line - b.line);
+		file.externals = [...new Set(file.externals)].sort();
+	}
+	const entries = /* @__PURE__ */ new Set();
+	for (const hint of pkg?.entryHints ?? ["index.js"]) {
+		const rel = resolveRelative(rootDir, "package.json", hint);
+		if (rel && analysis.fileByPath.has(rel)) entries.add(rel);
+	}
+	const queue = [...entries].sort();
+	const edges = /* @__PURE__ */ new Map();
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (analysis.reachable.has(current)) continue;
+		analysis.reachable.add(current);
+		const file = analysis.fileByPath.get(current);
+		if (!file) continue;
+		const targets = [];
+		for (const ref of file.imports) {
+			if (!ref.specifier.startsWith(".")) continue;
+			const rel = resolveRelative(rootDir, current, ref.specifier);
+			if (rel && analysis.fileByPath.has(rel)) {
+				targets.push(rel);
+				if (!analysis.reachable.has(rel)) queue.push(rel);
+			}
+		}
+		edges.set(current, [...new Set(targets)].sort());
+	}
+	analysis.edges = edges;
+	analysis.entries = [...entries].sort();
+	analysis.unreachable = analysis.files.map((f) => f.path).filter((p) => !analysis.reachable.has(p));
+	analysis.capUses.sort((a, b) => byFileLine(a, b) || a.api.localeCompare(b.api) || a.cap.localeCompare(b.cap));
+	analysis.netUses.sort(byFileLine);
+	analysis.evalUses.sort(byFileLine);
+	analysis.dynamicImports.sort(byFileLine);
+	analysis.encodedLiterals.sort(byFileLine);
+	analysis.charcodeCalls.sort(byFileLine);
+	return analysis;
+}
+/** All files statically reachable from `path` (excluding the path itself). */
+function reachableFrom(analysis, path) {
+	const seen = /* @__PURE__ */ new Set();
+	const queue = [path];
+	while (queue.length > 0) {
+		const current = queue.shift();
+		for (const next of analysis.edges.get(current) ?? []) if (!seen.has(next)) {
+			seen.add(next);
+			queue.push(next);
+		}
+	}
+	return seen;
+}
+//#endregion
+//#region src/tar.ts
+/**
+* Minimal tar reader for npm pack tarballs (ustar + PAX + GNU longname).
+*
+* Hand-rolled on purpose: it keeps `acorn` the only runtime dependency that is
+* not Node itself (ROADMAP D4), and npm tarballs need only a small, well-
+* understood subset of the format. Hardlinks and symlinks are never
+* materialized — they are reported back as skipped so the scanner can surface
+* them instead of silently following them.
+*/
+const BLOCK = 512;
+function str(buf, off, len) {
+	return buf.subarray(off, off + len).toString("utf8").replace(/\0.*$/, "").trim();
+}
+/** Header numeric field: NUL-padded octal, or GNU base-256 for large sizes. */
+function numeric(buf, off, len) {
+	if (buf[off] & 128) {
+		let value = buf[off] & 127;
+		for (let i = off + 1; i < off + len; i += 1) value = value * 256 + buf[i];
+		return value;
+	}
+	return parseInt(str(buf, off, len), 8) || 0;
+}
+/** PAX extended header records: `<len> <key>=<value>\n`. */
+function paxRecords(data) {
+	const records = /* @__PURE__ */ new Map();
+	let pos = 0;
+	while (pos < data.length) {
+		const space = data.indexOf(" ", pos);
+		if (space < 0) break;
+		const len = parseInt(data.subarray(pos, space).toString("utf8"), 10);
+		if (!Number.isFinite(len) || len <= 0 || pos + len > data.length) break;
+		const record = data.subarray(space + 1, pos + len).toString("utf8");
+		const eq = record.indexOf("=");
+		if (eq > 0) records.set(record.slice(0, eq), record.slice(eq + 1).replace(/\n$/, ""));
+		pos += len;
+	}
+	return records;
+}
+function stripPackagePrefix(name) {
+	let p = name;
+	if (p.startsWith("./")) p = p.slice(2);
+	const slash = p.indexOf("/");
+	if (p.startsWith("package/")) p = p.slice(8);
+	else if (slash === -1 && p === "package") p = "";
+	return p;
+}
+/**
+* Extract a (possibly gzipped) tar buffer into `destDir`. Entry paths must
+* stay inside `destDir`; anything that escapes — `..`, absolute paths — is a
+* malformed or hostile archive and throws rather than being written.
+*/
+function extractTarball(tarball, destDir) {
+	const buf = tarball[0] === 31 && tarball[1] === 139 ? gunzipSync(tarball) : tarball;
+	const root = resolve(destDir);
+	const files = [];
+	const skipped = [];
+	let pendingPath;
+	let globalPax = /* @__PURE__ */ new Map();
+	let pos = 0;
+	while (pos + BLOCK <= buf.length) {
+		const header = buf.subarray(pos, pos + BLOCK);
+		if (header.every((byte) => byte === 0)) break;
+		pos += BLOCK;
+		const size = numeric(header, 124, 12);
+		const typeflag = String.fromCharCode(header[156]);
+		const data = buf.subarray(pos, pos + size);
+		pos += size + (BLOCK - size % BLOCK) % BLOCK;
+		if (typeflag === "x" || typeflag === "X") {
+			pendingPath = paxRecords(data).get("path");
+			continue;
+		}
+		if (typeflag === "g") {
+			globalPax = paxRecords(data);
+			continue;
+		}
+		if (typeflag === "L") {
+			pendingPath = data.toString("utf8").replace(/\0.*$/, "").trim();
+			continue;
+		}
+		let name = pendingPath ?? globalPax.get("path") ?? str(header, 345, 155) + str(header, 0, 100);
+		pendingPath = void 0;
+		name = stripPackagePrefix(name);
+		if (!name || name === "." || name === "./") continue;
+		if (typeflag === "1" || typeflag === "2") {
+			skipped.push({
+				path: name,
+				type: typeflag === "1" ? "hardlink" : "symlink",
+				target: str(header, 157, 100)
+			});
+			continue;
+		}
+		if (typeflag === "5") {
+			mkdirSync(join(root, name), { recursive: true });
+			continue;
+		}
+		if (typeflag !== "0" && typeflag !== "\0" && typeflag !== "7") continue;
+		const parts = name.split("/");
+		if (name.startsWith("/") || parts.includes("..")) throw new Error(`tarball entry escapes destination: ${name}`);
+		const abs = resolve(root, name);
+		if (abs !== root && !abs.startsWith(root + sep)) throw new Error(`tarball entry escapes destination: ${name}`);
+		mkdirSync(dirname(abs), { recursive: true });
+		writeFileSync(abs, data);
+		const mode = numeric(header, 100, 8);
+		if (mode & 73) chmodSync(abs, mode);
+		files.push(name);
+	}
+	return {
+		files: files.sort(),
+		skipped
+	};
+}
+//#endregion
+//#region src/resolve.ts
+/**
+* Target resolution (ROADMAP T1): turn a CLI specifier into a local directory
+* ready for analysis, plus the `VetTarget` metadata the report carries.
+*
+* - npm packages are fetched through registry metadata only (packument →
+*   dist.tarball), and the downloaded tarball must match `dist.integrity`
+*   before anything is extracted.
+* - local paths never touch the network.
+* - git repos are cloned with `git clone --depth 1`; cloning runs no package
+*   code (no lifecycle scripts), unlike an install.
+*/
+var VetError = class extends Error {};
+const GIT_RE = /^(?:git\+)?(?:ssh:\/\/|https?:\/\/|git@)[^\s]+$|^(?:github|gitlab|bitbucket):[^\s]+$/;
+/** Classify a specifier without any network access. */
+function classifySpecifier(specifier, exists = existsSync) {
+	const s = specifier.trim();
+	if (s.startsWith("./") || s.startsWith("../") || s.startsWith("/") || s.startsWith("~")) return "local-path";
+	if (GIT_RE.test(s)) return "git-repo";
+	if (exists(s)) return "local-path";
+	if (/^@[^/\s]+\/[^@\s]+(?:@[^@\s]+)?$/.test(s) || /^[^@\s][^/\s]*$/.test(s)) return "npm-package";
+	throw new VetError(`cannot classify specifier: ${specifier}`);
+}
+/** Split `name`, `name@version`, `@scope/name`, `@scope/name@tag|version`. */
+function parseNpmSpecifier(specifier) {
+	const scoped = specifier.startsWith("@");
+	const base = scoped ? specifier.slice(1) : specifier;
+	const at = base.lastIndexOf("@");
+	if (at < 0) return { name: specifier };
+	const name = (scoped ? "@" : "") + base.slice(0, at);
+	const spec = base.slice(at + 1);
+	if (!name || !spec) return { name: specifier };
+	return {
+		name,
+		spec
+	};
+}
+function registryPath(name) {
+	return name.startsWith("@") ? name.replace("/", "%2F") : name;
+}
+async function fetchJson(url, opts) {
+	const res = await (opts.fetchImpl ?? ((u) => fetch(u)))(url);
+	if (!res.ok) throw new VetError(`registry request failed (${res.status}) for ${url}`);
+	return res.json();
+}
+async function fetchBuffer(url, opts) {
+	const res = await (opts.fetchImpl ?? ((u) => fetch(u)))(url);
+	if (!res.ok) throw new VetError(`tarball request failed (${res.status}) for ${url}`);
+	return Buffer.from(await res.arrayBuffer());
+}
+function verifyIntegrity(tarball, integrity, shasum) {
+	if (integrity) {
+		const match = /^sha(512|384|256|1)-([A-Za-z0-9+/=]+)$/.exec(integrity);
+		if (!match) throw new VetError(`unsupported integrity format: ${integrity}`);
+		const [, bits, expected] = match;
+		const actual = createHash(`sha${bits}`).update(tarball).digest("base64");
+		if (actual !== expected) throw new VetError(`integrity mismatch for downloaded tarball (expected ${integrity}, got sha${bits}-${actual})`);
+		return;
+	}
+	if (shasum) {
+		if (createHash("sha1").update(tarball).digest("hex") !== shasum) throw new VetError(`shasum mismatch for downloaded tarball`);
+	}
+}
+function tmpWorkspace() {
+	return mkdtempSync(join(tmpdir(), "dsh-vet-"));
+}
+function cleanupDir(dir) {
+	rmSync(dir, {
+		recursive: true,
+		force: true
+	});
+}
+async function resolveNpm(specifier, opts) {
+	const registry = (opts.registry ?? "https://registry.npmjs.org").replace(/\/$/, "");
+	const { name, spec } = parseNpmSpecifier(specifier);
+	const packument = await fetchJson(`${registry}/${registryPath(name)}`, opts);
+	const versions = packument?.versions ?? {};
+	const distTags = packument?.["dist-tags"] ?? {};
+	const version = spec ? versions[spec]?.version ?? distTags[spec] : distTags["latest"] ?? Object.keys(versions).at(-1);
+	if (!version || !versions[version]) throw new VetError(`no matching version for ${specifier} (resolved candidate: ${version ?? "none"})`);
+	const dist = versions[version]?.dist ?? {};
+	if (!dist.tarball) throw new VetError(`registry metadata for ${name}@${version} has no tarball URL`);
+	const tarball = await fetchBuffer(dist.tarball, opts);
+	verifyIntegrity(tarball, dist.integrity, dist.shasum);
+	const work = tmpWorkspace();
+	try {
+		const extracted = extractTarball(tarball, work);
+		return {
+			target: {
+				kind: "npm-package",
+				specifier,
+				resolved: {
+					version,
+					integrity: dist.integrity
+				}
+			},
+			rootDir: work,
+			files: extracted.files,
+			skippedLinks: extracted.skipped,
+			cleanup: () => cleanupDir(work)
+		};
+	} catch (err) {
+		cleanupDir(work);
+		throw err;
+	}
+}
+function runGit(args) {
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn("git", args, { stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		] });
+		let stdout = "";
+		let stderr = "";
+		child.stdout.on("data", (chunk) => stdout += chunk);
+		child.stderr.on("data", (chunk) => stderr += chunk);
+		child.on("error", (err) => reject(new VetError(`git is not available: ${err.message}`)));
+		child.on("close", (code) => code === 0 ? resolvePromise({
+			stdout,
+			stderr
+		}) : reject(new VetError(`git ${args[0]} failed (${code}): ${stderr.trim()}`)));
+	});
+}
+async function resolveGit(specifier) {
+	const url = specifier.replace(/^git\+/, "");
+	const work = tmpWorkspace();
+	try {
+		await runGit([
+			"clone",
+			"--depth",
+			"1",
+			"--quiet",
+			url,
+			work
+		]);
+		const { stdout } = await runGit([
+			"-C",
+			work,
+			"rev-parse",
+			"HEAD"
+		]);
+		return {
+			target: {
+				kind: "git-repo",
+				specifier: url,
+				resolved: { commit: stdout.trim() }
+			},
+			rootDir: work,
+			cleanup: () => cleanupDir(work)
+		};
+	} catch (err) {
+		cleanupDir(work);
+		throw err;
+	}
+}
+function resolveLocal(specifier) {
+	const dir = specifier.startsWith("~/") ? resolve(homedir(), specifier.slice(2)) : resolve(specifier);
+	if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new VetError(`local path is not a directory: ${specifier}`);
+	return {
+		target: {
+			kind: "local-path",
+			specifier: dir
+		},
+		rootDir: dir,
+		cleanup: () => {}
+	};
+}
+/** Resolve any accepted specifier into a scannable local directory. */
+async function resolveTarget(specifier, opts = {}) {
+	switch (classifySpecifier(specifier)) {
+		case "npm-package": return resolveNpm(specifier, opts);
+		case "git-repo": return resolveGit(specifier);
+		case "local-path": return resolveLocal(specifier);
+	}
+}
+//#endregion
+//#region src/rule.ts
+/** Build a finding from a rule, applying its defaults. */
+function finding(rule, init) {
+	return {
+		id: rule.id,
+		title: init.title ?? rule.title,
+		severity: init.severity ?? rule.defaultSeverity,
+		confidence: init.confidence ?? rule.defaultConfidence,
+		evidence: init.evidence,
+		remediation: init.remediation,
+		references: init.references
+	};
+}
+/** Evidence list capped at `max`, with a trailing note counting the rest. */
+function capEvidence(evidence, max = 10) {
+	if (evidence.length <= max) return evidence;
+	return [...evidence.slice(0, max), {
+		file: ".",
+		note: `…and ${evidence.length - max} more`
+	}];
+}
+function usesOfCap(analysis, cap) {
+	return analysis.capUses.filter((use) => use.cap === cap);
+}
+/** Case-insensitive seam membership; null means "no declaration made". */
+function declaresSeam(analysis, seam) {
+	if (!analysis.pkg?.seams) return null;
+	return analysis.pkg.seams.some((s) => s.toLowerCase() === seam.toLowerCase());
+}
+/** Bounded Levenshtein distance: returns `max + 1` once exceeded. */
+function editDistance(a, b, max = 2) {
+	if (Math.abs(a.length - b.length) > max) return max + 1;
+	const prev = new Array(b.length + 1);
+	const curr = new Array(b.length + 1);
+	for (let j = 0; j <= b.length; j += 1) prev[j] = j;
+	for (let i = 1; i <= a.length; i += 1) {
+		curr[0] = i;
+		let rowMin = curr[0];
+		for (let j = 1; j <= b.length; j += 1) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+			if (curr[j] < rowMin) rowMin = curr[j];
+		}
+		if (rowMin > max) return max + 1;
+		for (let j = 0; j <= b.length; j += 1) prev[j] = curr[j];
+	}
+	return prev[b.length];
+}
+//#endregion
+//#region src/rules/dep.ts
+const LIFECYCLE_SCRIPTS = [
+	"preinstall",
+	"install",
+	"postinstall"
+];
+const installScripts = {
+	id: "dep.install-scripts",
+	title: "Runs code at install time",
+	defaultSeverity: "medium",
+	defaultConfidence: "high",
+	check({ analysis }) {
+		const scripts = analysis.pkg?.scripts ?? {};
+		const present = LIFECYCLE_SCRIPTS.filter((name) => typeof scripts[name] === "string" && scripts[name] !== "");
+		if (present.length === 0) return [];
+		return [finding(this, {
+			evidence: present.map((name) => ({
+				file: "package.json",
+				snippet: scripts[name],
+				note: `${name} script runs when the package is installed`
+			})),
+			remediation: "Remove the lifecycle script, or move the work to a prepublish/build step and document why install-time execution is required.",
+			references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/dep.install-scripts.md"]
+		})];
+	}
+};
+const FLOATING = /* @__PURE__ */ new Set([
+	"",
+	"*",
+	"latest",
+	"x",
+	"X"
+]);
+const floatingRange = {
+	id: "dep.floating-range",
+	title: "Runtime dependencies resolve to whatever the registry serves",
+	defaultSeverity: "medium",
+	defaultConfidence: "high",
+	check({ analysis }) {
+		const deps = analysis.pkg?.dependencies ?? {};
+		const floating = Object.entries(deps).filter(([, spec]) => FLOATING.has(spec.trim()));
+		if (floating.length === 0) return [];
+		return [finding(this, {
+			evidence: floating.map(([name, spec]) => ({
+				file: "package.json",
+				note: `"${name}": "${spec}" — any future version satisfies this`
+			})),
+			remediation: "Pin to a exact version or a narrow range.",
+			references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/dep.floating-range.md"]
+		})];
+	}
+};
+/**
+* Popular `dsh-*` names worth impersonating. Every entry is verified to exist
+* on npm (checked during the v0.1 calibration sweep,
+* docs/calibration-v0.1.md); a name that cannot be installed cannot be
+* typosquatted. Extend as adoption grows.
+*/
+const POPULAR_NAMES = [
+	"dsh-doctor",
+	"dsh-plugin-audit",
+	"dsh-plugin-vetting",
+	"dsh-audit",
+	"dsh-searxng",
+	"dsh-vault",
+	"dsh-zcf",
+	"dsh-wechat",
+	"dsh-better-sidebar",
+	"dsh-find-plugin"
+];
+const depRules = [
+	installScripts,
+	floatingRange,
+	{
+		id: "dep.typosquat-proximity",
+		title: "Dependency name is one or two edits from a popular dsh-* package",
+		defaultSeverity: "high",
+		defaultConfidence: "medium",
+		check({ analysis }) {
+			const deps = Object.keys(analysis.pkg?.dependencies ?? {});
+			const hits = [];
+			for (const dep of deps) {
+				if (POPULAR_NAMES.includes(dep)) continue;
+				for (const popular of POPULAR_NAMES) {
+					const distance = editDistance(dep, popular, 2);
+					if (distance <= 2) hits.push({
+						dep,
+						near: popular,
+						distance
+					});
+				}
+			}
+			if (hits.length === 0) return [];
+			hits.sort((a, b) => a.distance - b.distance || a.dep.localeCompare(b.dep));
+			const worst = hits[0].distance;
+			return [finding(this, {
+				severity: worst === 1 ? "high" : "low",
+				evidence: hits.slice(0, 10).map((hit) => ({
+					file: "package.json",
+					note: `"${hit.dep}" is ${hit.distance} edit${hit.distance === 1 ? "" : "s"} from "${hit.near}"`
+				})),
+				remediation: "Verify the dependency is the package you mean — exact spelling, real repository, real publisher.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/dep.typosquat-proximity.md"]
+			})];
+		}
+	}
+];
+//#endregion
+//#region src/rules/egress.ts
+/**
+* `egress.*` — data egress (ROADMAP T3): outbound endpoint inventory, and
+* endpoints reachable from code that reads secrets or the DSH home directory.
+*/
+function endpointOf(literal) {
+	try {
+		return new URL(literal).host;
+	} catch {
+		return literal;
+	}
+}
+const outboundEndpoints = {
+	id: "egress.outbound-endpoints",
+	title: "Outbound endpoints the code can contact",
+	defaultSeverity: "info",
+	defaultConfidence: "high",
+	check({ analysis }) {
+		const byEndpoint = /* @__PURE__ */ new Map();
+		for (const use of analysis.netUses) for (const literal of use.literals) {
+			const endpoint = endpointOf(literal);
+			if (!endpoint) continue;
+			if (!byEndpoint.has(endpoint)) byEndpoint.set(endpoint, {
+				file: use.file,
+				line: use.line,
+				snippet: use.snippet
+			});
+		}
+		if (byEndpoint.size === 0) return [];
+		const endpoints = [...byEndpoint.keys()].sort();
+		return [finding(this, {
+			evidence: endpoints.map((endpoint) => ({
+				...byEndpoint.get(endpoint),
+				note: `endpoint ${endpoint}`
+			})),
+			remediation: "Document each endpoint in the README; every host here is a data-flow decision you own.",
+			references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/egress.outbound-endpoints.md"]
+		})];
+	}
+};
+const SECRET_CAPS = /* @__PURE__ */ new Set([
+	"env",
+	"homedir",
+	"secret-read"
+]);
+const egressRules = [outboundEndpoints, {
+	id: "egress.secret-adjacent",
+	title: "Network calls reachable from code that reads secrets",
+	defaultSeverity: "high",
+	defaultConfidence: "low",
+	check({ analysis }) {
+		const secretFiles = new Set(analysis.capUses.filter((u) => SECRET_CAPS.has(u.cap)).map((u) => u.file));
+		const evidence = [];
+		let sameFileLiteral = false;
+		for (const file of [...secretFiles].sort()) {
+			const reads = analysis.capUses.filter((u) => SECRET_CAPS.has(u.cap) && u.file === file);
+			const netScope = [file, ...reachableFrom(analysis, file)];
+			const nets = analysis.netUses.filter((u) => netScope.includes(u.file));
+			for (const net of nets) {
+				if (net.file === file && net.literals.length > 0) sameFileLiteral = true;
+				for (const read of reads.slice(0, 2)) evidence.push({
+					file,
+					line: read.line,
+					snippet: read.snippet,
+					note: `reads ${read.cap === "env" ? "process.env" : read.cap === "homedir" ? "the user home directory" : "a credential-like file"}; ${net.api} in ${net.file}:${net.line} is statically reachable from here`
+				});
+			}
+		}
+		if (evidence.length === 0) return [];
+		return [finding(this, {
+			confidence: sameFileLiteral ? "medium" : "low",
+			evidence: capEvidence(evidence, 6),
+			remediation: "Keep secret reads and network clients in separate modules, or document the intended data flow for each endpoint.",
+			references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/egress.secret-adjacent.md"]
+		})];
+	}
+}];
+const obfRules = [
+	{
+		id: "obf.eval-detect",
+		title: "Evaluates dynamically built code",
+		defaultSeverity: "medium",
+		defaultConfidence: "medium",
+		check({ analysis }) {
+			const uses = analysis.evalUses;
+			if (uses.length === 0) return [];
+			const nonLiteral = uses.filter((use) => !use.literal);
+			const literal = uses.filter((use) => use.literal);
+			const findings = [];
+			if (nonLiteral.length > 0) findings.push(finding(this, {
+				evidence: capEvidence(nonLiteral.map((use) => ({
+					file: use.file,
+					line: use.line,
+					snippet: use.snippet,
+					note: `${use.kind} of a non-literal argument`
+				}))),
+				remediation: "Replace eval/new Function with direct code; dynamic evaluation defeats static audit.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/obf.eval-detect.md"]
+			}));
+			if (literal.length > 0) findings.push(finding(this, {
+				title: "Evaluates a literal string as code",
+				severity: "info",
+				confidence: "high",
+				evidence: literal.map((use) => ({
+					file: use.file,
+					line: use.line,
+					snippet: use.snippet,
+					note: `${use.kind} of a constant string — inert but still eval`
+				})),
+				remediation: "Move the code out of the string literal.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/obf.eval-detect.md"]
+			}));
+			return findings;
+		}
+	},
+	{
+		id: "obf.dynamic-require",
+		title: "Loads modules through a computed specifier",
+		defaultSeverity: "medium",
+		defaultConfidence: "low",
+		check({ analysis }) {
+			const recoverable = analysis.dynamicImports.filter((use) => use.literals !== null);
+			const opaque = analysis.dynamicImports.filter((use) => use.literals === null);
+			const findings = [];
+			if (recoverable.length > 0) findings.push(finding(this, {
+				confidence: "medium",
+				evidence: recoverable.map((use) => ({
+					file: use.file,
+					line: use.line,
+					snippet: use.snippet,
+					note: `${use.kind} of a concatenation that statically resolves to "${use.literals[0]}"`
+				})),
+				remediation: "Use the plain specifier; concatenated module names hide the dependency from review.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/obf.dynamic-require.md"]
+			}));
+			if (opaque.length > 0) findings.push(finding(this, {
+				evidence: capEvidence(opaque.map((use) => ({
+					file: use.file,
+					line: use.line,
+					snippet: use.snippet,
+					note: `${use.kind} of a runtime value — the loaded module cannot be determined statically`
+				}))),
+				remediation: "Use plain specifiers so the module graph stays auditable.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/obf.dynamic-require.md"]
+			}));
+			return findings;
+		}
+	},
+	{
+		id: "obf.encoded-payload",
+		title: "Long base64/hex string literals in shipped code",
+		defaultSeverity: "medium",
+		defaultConfidence: "low",
+		check({ analysis }) {
+			const literals = analysis.encodedLiterals;
+			if (literals.length === 0) return [];
+			return [finding(this, {
+				evidence: capEvidence(literals.map((lit) => ({
+					file: lit.file,
+					line: lit.line,
+					snippet: lit.value.slice(0, 80),
+					note: `${lit.charset} literal, ${lit.value.length} chars`
+				}))),
+				remediation: "Decode payloads to plain assets, or ship them as files a reviewer can open.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/obf.encoded-payload.md"]
+			})];
+		}
+	},
+	{
+		id: "obf.charcode-chain",
+		title: "Builds strings from character codes",
+		defaultSeverity: "medium",
+		defaultConfidence: "medium",
+		check({ analysis }) {
+			const calls = analysis.charcodeCalls;
+			if (calls.length === 0) return [];
+			return [finding(this, {
+				evidence: calls.map((call) => ({
+					file: call.file,
+					line: call.line,
+					note: `decodes to "${call.chars}…"`
+				})),
+				remediation: "Write the string literal directly.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/obf.charcode-chain.md"]
+			})];
+		}
+	},
+	{
+		id: "obf.unparseable",
+		title: "Shipped JS files that no standard parser accepts",
+		defaultSeverity: "medium",
+		defaultConfidence: "high",
+		check({ analysis }) {
+			const broken = analysis.files.filter((f) => f.parseError !== null);
+			if (broken.length === 0) return [];
+			return [finding(this, {
+				evidence: broken.slice(0, 10).map((f) => ({
+					file: f.path,
+					note: `parse error: ${f.parseError?.slice(0, 120)}`
+				})),
+				remediation: "Ship parseable source, or source maps that let tooling see the real code.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/obf.unparseable.md"]
+			})];
+		}
+	}
+];
+//#endregion
+//#region src/rules/perm.ts
+/**
+* `perm.*` — capability surface vs declared seams (ROADMAP T3).
+*
+* Seams are declared in package.json `dsh.seams` (e.g. `["fs","web"]`). The
+* vocabulary maps detected capabilities to seams: fs/fs-write → `fs`,
+* child_process → `shell`, net → `web`, worker_threads → `workers`. When no
+* declaration exists the mismatch rule stays silent — only the per-capability
+* rules speak, conservatively.
+*/
+const SEAM_FOR_CAP = {
+	fs: "fs",
+	"fs-write": "fs",
+	shell: "shell",
+	net: "web",
+	workers: "workers"
+};
+const seamMismatch = {
+	id: "perm.seam-mismatch",
+	title: "Capability used but not declared in dsh.seams",
+	defaultSeverity: "medium",
+	defaultConfidence: "medium",
+	check({ analysis }) {
+		const declared = analysis.pkg?.seams;
+		if (!declared) return [];
+		const lower = new Set(declared.map((s) => s.toLowerCase()));
+		const evidence = [];
+		for (const [cap, seam] of Object.entries(SEAM_FOR_CAP)) {
+			if (lower.has(seam)) continue;
+			const use = usesOfCap(analysis, cap)[0];
+			if (!use) continue;
+			evidence.push({
+				file: use.file,
+				line: use.line,
+				snippet: use.snippet,
+				note: `${cap} capability used; seam '${seam}' is not among the declared [${declared.join(", ")}]`
+			});
+		}
+		if (evidence.length === 0) return [];
+		return [finding(this, {
+			evidence,
+			remediation: "Add the seam to dsh.seams, or drop the capability if it is not needed.",
+			references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/perm.seam-mismatch.md"]
+		})];
+	}
+};
+const DESTRUCTIVE_FS = /* @__PURE__ */ new Set([
+	"fs.rm",
+	"fs.rmSync",
+	"fs.unlink",
+	"fs.unlinkSync",
+	"fs.rmdir",
+	"fs.rmdirSync",
+	"fs.truncate",
+	"fs.truncateSync",
+	"fs/promises.rm",
+	"fs/promises.unlink",
+	"fs/promises.rmdir",
+	"fs/promises.truncate"
+]);
+/** Literal absolute paths that count as inside a plugin's plausible scope. */
+function inScopeLiteral(path) {
+	return [
+		tmpdir(),
+		`${homedir()}/.dsh`,
+		`${homedir()}/.config/dsh`,
+		`${homedir()}/.cache/dsh`
+	].some((root) => path === root || path.startsWith(`${root}/`));
+}
+const undeclaredFsWrite = {
+	id: "perm.undeclared-fs-write",
+	title: "Writes or deletes files outside any plausible plugin scope",
+	defaultSeverity: "high",
+	defaultConfidence: "medium",
+	check({ analysis }) {
+		const uses = usesOfCap(analysis, "fs-write");
+		if (uses.length === 0) return [];
+		const outOfScope = uses.filter((use) => use.literals.some((l) => l.startsWith("/") && !inScopeLiteral(l)));
+		const dynamic = uses.filter((use) => use.literals.length === 0);
+		const findings = [];
+		if (outOfScope.length > 0) {
+			const destructive = outOfScope.some((use) => DESTRUCTIVE_FS.has(use.api));
+			findings.push(finding(this, {
+				title: destructive ? "Destructive filesystem operations outside any plausible plugin scope" : this.title,
+				severity: destructive ? "critical" : "high",
+				confidence: "high",
+				evidence: capEvidence(outOfScope.map((use) => ({
+					file: use.file,
+					line: use.line,
+					snippet: use.snippet,
+					note: `${use.api} with literal path ${use.literals.find((l) => l.startsWith("/") && !inScopeLiteral(l))}`
+				}))),
+				remediation: "Keep writes inside the workspace or the DSH home directory; derive paths from config, not literals.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/perm.undeclared-fs-write.md"]
+			}));
+		}
+		if (dynamic.length > 0) findings.push(finding(this, {
+			severity: "medium",
+			confidence: "low",
+			evidence: capEvidence(dynamic.map((use) => ({
+				file: use.file,
+				line: use.line,
+				snippet: use.snippet
+			})), 5),
+			remediation: "Use fixed, reviewable paths; runtime-computed write targets cannot be audited statically.",
+			references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/perm.undeclared-fs-write.md"]
+		}));
+		return findings;
+	}
+};
+const NET_IMPORT_RE = /^(?:node:)?(?:net|http|https|http2|tls|dgram|dns|undici)$/;
+const permRules = [
+	seamMismatch,
+	undeclaredFsWrite,
+	{
+		id: "perm.subprocess-spawn",
+		title: "Spawns subprocesses",
+		defaultSeverity: "medium",
+		defaultConfidence: "high",
+		check({ analysis }) {
+			const declared = declaresSeam(analysis, "shell");
+			const uses = usesOfCap(analysis, "shell");
+			const findings = [];
+			if (uses.length > 0) findings.push(finding(this, {
+				severity: declared === true ? "info" : "medium",
+				confidence: "high",
+				evidence: capEvidence(uses.map((use) => ({
+					file: use.file,
+					line: use.line,
+					snippet: use.snippet,
+					note: declared === true ? "seam \"shell\" is declared" : "no \"shell\" seam declared"
+				})), 5),
+				remediation: "Declare the shell seam in dsh.seams, or avoid spawning processes.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/perm.subprocess-spawn.md"]
+			}));
+			const importOnly = analysis.files.filter((f) => f.externals.some((e) => /^(?:node:)?child_process$/.test(e)) && !uses.some((u) => u.file === f.path));
+			if (importOnly.length > 0) findings.push(finding(this, {
+				title: "Imports child_process without spawning anything",
+				severity: "info",
+				confidence: "high",
+				evidence: importOnly.slice(0, 5).map((f) => ({
+					file: f.path,
+					note: "import present, no spawn/exec call site found"
+				})),
+				remediation: "Remove the unused import.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/perm.subprocess-spawn.md"]
+			}));
+			return findings;
+		}
+	},
+	{
+		id: "perm.network-client",
+		title: "Opens network connections",
+		defaultSeverity: "medium",
+		defaultConfidence: "high",
+		check({ analysis }) {
+			const declared = declaresSeam(analysis, "web");
+			const findings = [];
+			if (analysis.netUses.length > 0) findings.push(finding(this, {
+				severity: declared === true ? "info" : "medium",
+				confidence: "high",
+				evidence: capEvidence(analysis.netUses.map((use) => ({
+					file: use.file,
+					line: use.line,
+					snippet: use.snippet,
+					note: declared === true ? "seam \"web\" is declared" : `no "web" seam declared (${use.literals.join(", ") || "target not statically known"})`
+				})), 5),
+				remediation: "Declare the web seam in dsh.seams, or drop the network access.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/perm.network-client.md"]
+			}));
+			const importOnly = analysis.files.filter((f) => f.externals.some((e) => NET_IMPORT_RE.test(e)) && !analysis.netUses.some((u) => u.file === f.path));
+			if (importOnly.length > 0) findings.push(finding(this, {
+				title: "Imports network modules without an observable client call",
+				severity: "info",
+				confidence: "high",
+				evidence: importOnly.slice(0, 5).map((f) => ({
+					file: f.path,
+					note: "import present, no client call site"
+				})),
+				remediation: "Remove the unused import.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/perm.network-client.md"]
+			}));
+			return findings;
+		}
+	},
+	{
+		id: "perm.unreachable-files",
+		title: "Shipped files not reachable from any declared entry point",
+		defaultSeverity: "info",
+		defaultConfidence: "high",
+		check({ analysis }) {
+			if (analysis.unreachable.length === 0) return [];
+			return [finding(this, {
+				evidence: analysis.unreachable.slice(0, 10).map((path) => ({
+					file: path,
+					note: "no static import path from any entry point reaches this file"
+				})),
+				remediation: "Dead files still ship and can be required dynamically; delete them or wire them into the graph.",
+				references: ["https://github.com/rogerdigital/dsh-vet/blob/main/docs/rules/perm.unreachable-files.md"]
+			})];
+		}
+	}
+];
+//#endregion
+//#region src/rules/index.ts
+const RULES = [
+	...depRules,
+	...egressRules,
+	...obfRules,
+	...permRules
+].sort((a, b) => a.id.localeCompare(b.id));
+function ruleIds() {
+	return RULES.map((rule) => rule.id);
+}
+/** Run all rules, or the subset named in `only` (unknown ids throw). */
+function runRules(analysis, only) {
+	let selected = RULES;
+	if (only && only.length > 0) {
+		const known = new Set(RULES.map((r) => r.id));
+		const unknown = only.filter((id) => !known.has(id));
+		if (unknown.length > 0) throw new Error(`unknown rule id(s): ${unknown.join(", ")}`);
+		selected = RULES.filter((rule) => only.includes(rule.id));
+	}
+	const findings = [];
+	for (const rule of selected) findings.push(...rule.check({ analysis }));
+	return findings;
+}
+//#endregion
+//#region src/scanner.ts
+/**
+* Scanner orchestration: resolve → analyze → rules → report. The only ambient
+* state in a report is `scanner.ranAt`; everything else is derived, so two runs
+* over the same artifact with the same version are identical.
+*/
+/** Kept in lockstep with package.json; a test asserts they match. */
+const SCANNER_VERSION = "0.1.0";
+async function scanDirectory(dir, options = {}) {
+	const analysis = analyze(dir);
+	return createReport({
+		target: {
+			kind: "local-path",
+			specifier: dir
+		},
+		scanner: {
+			name: "dsh-vet",
+			version: SCANNER_VERSION,
+			ranAt: options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString()
+		},
+		findings: options.rules ? runRules(analysis, options.rules) : runRules(analysis)
+	});
+}
+async function scan(specifier, options = {}) {
+	const resolved = await resolveTarget(specifier, options);
+	try {
+		const analysis = analyze(resolved.rootDir);
+		return createReport({
+			target: resolved.target,
+			scanner: {
+				name: "dsh-vet",
+				version: SCANNER_VERSION,
+				ranAt: options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString()
+			},
+			findings: options.rules ? runRules(analysis, options.rules) : runRules(analysis)
+		});
+	} finally {
+		resolved.cleanup();
+	}
+}
+//#endregion
+//#region src/cli.ts
+/**
+* CLI (ROADMAP T4). Exit semantics per the dsh-vet/v1 spec: `0` for any
+* completed report (even a graded-F one), non-zero for scanner failure;
+* `--strict`/`--fail-on` turn threshold breaches into exit code 1.
+*/
+const USAGE = `usage: dsh-vet <specifier> [options]
+
+  specifier            npm package (name[@version]), git URL, or local path
+
+  --json               emit a dsh-vet/v1 report as JSON
+  --strict             exit 1 when findings >= high with confidence >= medium
+  --fail-on <sev>      override the --strict threshold (critical|high|medium|low)
+  --rules <ids>        comma-separated rule ids to run
+  --version            print version
+  --help               this text`;
+const SEVERITY_ORDER = [
+	"critical",
+	"high",
+	"medium",
+	"low",
+	"info"
+];
+function thresholdBreach(report, threshold) {
+	const limit = SEVERITY_ORDER.indexOf(threshold);
+	return report.findings.some((f) => isGraded(f) && SEVERITY_ORDER.indexOf(f.severity) <= limit);
+}
+function humanSummary(report) {
+	const lines = [];
+	const resolved = report.target.resolved;
+	const what = report.target.kind === "npm-package" ? `${report.target.specifier}${resolved?.version ? ` (resolved ${resolved.version})` : ""}` : report.target.specifier;
+	lines.push(`dsh-vet ${SCANNER_VERSION} · ${report.target.kind} · ${what}`);
+	lines.push(`grade: ${report.summary.grade}`);
+	const c = report.summary.counts;
+	lines.push(`findings: ${c.critical} critical · ${c.high} high · ${c.medium} medium · ${c.low} low · ${c.info} info`);
+	if (report.findings.length > 0) lines.push("");
+	for (const f of report.findings) {
+		lines.push(`[${f.severity[0].toUpperCase()}] ${f.id} — ${f.title} (${f.confidence} confidence)`);
+		for (const e of f.evidence) {
+			const where = e.line ? `${e.file}:${e.line}` : e.file;
+			lines.push(`    ${where}${e.snippet ? `  ${e.snippet}` : ""}`);
+			if (e.note) lines.push(`      ${e.note}`);
+		}
+		if (f.remediation) lines.push(`    fix: ${f.remediation}`);
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+/** Parse and run; returns the process exit code. */
+async function runCli(argv, io) {
+	let args;
+	try {
+		args = parseArgs({
+			args: argv,
+			options: {
+				json: { type: "boolean" },
+				strict: { type: "boolean" },
+				"fail-on": { type: "string" },
+				rules: { type: "string" },
+				version: { type: "boolean" },
+				help: { type: "boolean" }
+			},
+			allowPositionals: true
+		});
+	} catch (err) {
+		io.stderr(`${err.message}\n\n${USAGE}`);
+		return 2;
+	}
+	if (args.values.version) {
+		io.stdout(SCANNER_VERSION);
+		return 0;
+	}
+	if (args.values.help) {
+		io.stdout(USAGE);
+		return 0;
+	}
+	const specifier = args.positionals[0];
+	if (!specifier || args.positionals.length > 1) {
+		io.stderr(`expected exactly one specifier\n\n${USAGE}`);
+		return 2;
+	}
+	const failOn = args.values["fail-on"] ?? (args.values.strict ? "high" : null);
+	if (failOn !== null && !SEVERITY_ORDER.includes(failOn)) {
+		io.stderr(`invalid --fail-on severity: ${failOn}\n\n${USAGE}`);
+		return 2;
+	}
+	const rulesArg = args.values.rules;
+	const rules = typeof rulesArg === "string" ? rulesArg.split(",").map((r) => r.trim()).filter(Boolean) : void 0;
+	try {
+		const report = classifySpecifier(specifier) === "local-path" && existsSync(specifier) ? await scanDirectory(specifier, { rules }) : await scan(specifier, { rules });
+		if (args.values.json) io.stdout(JSON.stringify(report, null, 2));
+		else io.stdout(humanSummary(report));
+		if (failOn !== null && thresholdBreach(report, failOn)) {
+			io.stderr(`threshold breached: findings at or above ${failOn} (confidence >= medium)`);
+			return 1;
+		}
+		return 0;
+	} catch (err) {
+		io.stderr(`dsh-vet: ${err.message}`);
+		return 2;
+	}
+}
+//#endregion
+export { RULES, RULE_ID_PATTERN, SCANNER_VERSION, SCHEMA_ID, VetError, analyze, classifySpecifier, countFindings, createReport, gradeFor, isGraded, parseNpmSpecifier, reachableFrom, resolveTarget, ruleIds, runCli, runRules, scan, scanDirectory };