penthera 1.1.1 → 1.4.0

package/lib/fix/util.js

@@ -0,0 +1,231 @@
+/**
+ * Shared helpers for fix recipes: framework detection, file discovery, and the
+ * small, anchor-based text edits recipes are built from. No AST: every edit
+ * keys off a line the recipe can recognise exactly, and gives up otherwise.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { detectFramework as detectSourceFramework } from "../whitebox/frameworks.js";
+import { createPatch } from "./diff.js";
+
+const SKIP = new Set(["node_modules", ".git", "dist", "build", ".next", "coverage", "vendor", "reports", ".security-results"]);
+const CODE_EXT = /\.(js|ts|mjs|cjs|jsx|tsx)$/;
+const MAX_FILES = 2000;
+
+export const ENTRY_CANDIDATES = [
+  "server.js", "server.ts", "server.mjs", "app.js", "app.ts", "app.mjs",
+  "index.js", "index.ts", "index.mjs", "main.js", "main.ts",
+  "src/server.js", "src/server.ts", "src/app.js", "src/app.ts",
+  "src/index.js", "src/index.ts", "src/main.js", "src/main.ts",
+];
+
+export function readText(repoPath, rel) {
+  try {
+    return readFileSync(join(repoPath, rel), "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+export function readPackageJson(repoPath) {
+  const text = readText(repoPath, "package.json");
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+export function hasDep(repoPath, name) {
+  const pkg = readPackageJson(repoPath);
+  return Boolean(pkg && (pkg.dependencies?.[name] || pkg.devDependencies?.[name]));
+}
+
+/**
+ * The web framework a repo uses: "next" | "hono" | "fastify" | "express" | null.
+ * package.json decides; source imports (via the white-box route scanner's
+ * detector) are the fallback for repos without one.
+ */
+export function detectFramework(repoPath) {
+  for (const fw of ["next", "hono", "fastify", "express"]) if (hasDep(repoPath, fw)) return fw;
+  if (["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"].some((f) => existsSync(join(repoPath, f)))) return "next";
+  for (const rel of ENTRY_CANDIDATES) {
+    const source = readText(repoPath, rel);
+    if (!source) continue;
+    const fw = detectSourceFramework(source);
+    if (fw !== "node") return fw;
+  }
+  return null;
+}
+
+/** Repo-relative paths of JS/TS source files, skipping dependencies and build output. */
+export function walkCodeFiles(repoPath) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort()) {
+      if (out.length >= MAX_FILES) return;
+      if (SKIP.has(entry)) continue;
+      const full = join(dir, entry);
+      let st;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) walk(full);
+      else if (CODE_EXT.test(entry) && !/\.(test|spec)\.|\.d\.ts$|\.min\.js$/.test(entry)) out.push(relative(repoPath, full));
+    }
+  };
+  walk(repoPath);
+  return out;
+}
+
+/** First entry-candidate file whose source matches `anchor`. */
+export function findEntryFile(repoPath, anchor) {
+  const candidates = [...ENTRY_CANDIDATES];
+  const main = readPackageJson(repoPath)?.main;
+  if (typeof main === "string") candidates.unshift(main.replace(/^\.\//, ""));
+  for (const rel of candidates) {
+    const source = readText(repoPath, rel);
+    if (source && anchor.test(source)) return { file: rel, source };
+  }
+  return null;
+}
+
+export const isTypeScript = (file) => /\.tsx?$/.test(file);
+
+export function moduleStyle(source) {
+  if (/^\s*import\s[^;]*?from\s+['"]|^\s*import\s+['"]|^\s*export\s/m.test(source)) return "esm";
+  if (/\brequire\s*\(/.test(source)) return "cjs";
+  return "esm";
+}
+
+/** Index of the line after the last top-level import/require statement. */
+function importBlockEnd(lines) {
+  let end = 0;
+  let open = false;
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (open) {
+      if (/\bfrom\s+['"][^'"]+['"];?\s*$/.test(l)) { open = false; end = i + 1; }
+      continue;
+    }
+    if (/^import\s.*\bfrom\s+['"][^'"]+['"];?\s*$/.test(l) || /^import\s+['"][^'"]+['"];?\s*$/.test(l)) end = i + 1;
+    else if (/^import\s+(?:type\s+)?\{[^}]*$/.test(l)) open = true;
+    else if (/^(?:const|let|var)\s+[\w{}\s,:]+=\s*require\(\s*['"][^'"]+['"]\s*\)[\w.]*;?\s*$/.test(l)) end = i + 1;
+    else if (i === 0 && /^#!/.test(l)) end = 1;
+    else if (/^['"]use (strict|client|server)['"];?\s*$/.test(l)) end = Math.max(end, i + 1);
+  }
+  return end;
+}
+
+/** Insert `block` (lines) after the import block, separated by a blank line. */
+export function insertAfterImports(source, block) {
+  const lines = source.split("\n");
+  const at = importBlockEnd(lines);
+  const insert = [...block];
+  if (at > 0 && lines[at - 1].trim() !== "") insert.unshift("");
+  if (lines[at] !== undefined && lines[at].trim() !== "") insert.push("");
+  lines.splice(at, 0, ...insert);
+  return lines.join("\n");
+}
+
+/** Add an import (ESM or CommonJS, matching the file) unless the module is already imported. */
+export function addImport(source, { name, module, named = false }) {
+  const escaped = module.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+  if (new RegExp(`from\\s+['"]${escaped}['"]|require\\(\\s*['"]${escaped}['"]\\s*\\)`).test(source)) return source;
+  const line = moduleStyle(source) === "cjs"
+    ? `const ${named ? `{ ${name} }` : name} = require("${module}");`
+    : `import ${named ? `{ ${name} }` : name} from "${module}";`;
+  const lines = source.split("\n");
+  const at = importBlockEnd(lines);
+  lines.splice(at, 0, line);
+  return lines.join("\n");
+}
+
+/** Insert lines right after line `index`, matching that line's indentation. */
+export function insertAfterLine(source, index, block) {
+  const lines = source.split("\n");
+  const indent = lines[index].match(/^\s*/)[0];
+  lines.splice(index + 1, 0, ...block.map((l) => (l ? indent + l : l)));
+  return lines.join("\n");
+}
+
+/** Index of the first line matching re, or -1. */
+export function findLine(source, re) {
+  return source.split("\n").findIndex((l) => re.test(l));
+}
+
+/**
+ * Split a call's arguments starting at the "(" at `open`, on one line only.
+ * Returns { args: [{ text, start, end }], close } with absolute offsets, or
+ * null if the call does not close before the end of the line.
+ */
+export function splitCallArgs(text, open) {
+  const args = [];
+  let depth = 0;
+  let quote = null;
+  let argStart = open + 1;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\n" && !quote) return null;
+    if (quote) {
+      if (ch === "\\") i++;
+      else if (ch === quote) quote = null;
+      else if (ch === "\n") return null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+    else if (ch === "(" || ch === "[" || ch === "{") depth++;
+    else if (ch === ")" || ch === "]" || ch === "}") {
+      depth--;
+      if (depth === 0) {
+        if (text.slice(argStart, i).trim()) args.push({ text: text.slice(argStart, i).trim(), start: argStart, end: i });
+        return { args, close: i };
+      }
+    } else if (ch === "," && depth === 1) {
+      args.push({ text: text.slice(argStart, i).trim(), start: argStart, end: i });
+      argStart = i + 1;
+    }
+  }
+  return null;
+}
+
+/** Add `NAME=value` to .env.example (creating it) unless NAME is already listed. */
+export function envExampleChange(repoPath, name, value = "", comment = null) {
+  const before = readText(repoPath, ".env.example");
+  if (before != null && new RegExp(`^\\s*${name}\\s*=`, "m").test(before)) return null;
+  const add = [...(comment ? [`# ${comment}`] : []), `${name}=${value}`].join("\n") + "\n";
+  const after = before == null ? add : before + (before.endsWith("\n") || before === "" ? "" : "\n") + add;
+  return { file: ".env.example", before, after };
+}
+
+/** Turn [{ file, before, after }] into { diff, files }, dropping no-op changes. */
+export function toDiff(changes) {
+  const parts = [];
+  const files = [];
+  for (const c of changes.filter(Boolean)) {
+    const patch = createPatch(c.file, c.before, c.after);
+    if (!patch) continue;
+    parts.push(patch);
+    files.push(c.file);
+  }
+  if (parts.length === 0) return null;
+  return { diff: parts.join(""), files };
+}
+
+/** "sessionSecret" / "api-key" -> "SESSION_SECRET" / "API_KEY". */
+export function toEnvName(key) {
+  return String(key)
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toUpperCase();
+}

package/lib/fuzzer.js

@@ -8,8 +8,17 @@
  *   - Schemathesis, property-based testing from API schemas
  *   - RESTler, stateful fuzzing with dependency inference
  *   - fast-check, shrinkable random generators
+ *
+ * What this file is, for anyone reviewing the package:
+ *   The values below are edge-case test inputs (type confusion, oversized
+ *   strings, well-known injection probes). Penthera never executes them. They
+ *   are sent as JSON request bodies to the user's own target, and only when
+ *   the user opts in with --fuzz (or the deep profile), to see whether the API
+ *   validates its input. Nothing runs on the machine running Penthera.
  */
 
+import { request } from "../src/utils/http.js";
+
 // ── Payload Generators ────────────────────────────────────────────────────
 
 /** Generate fuzz values for a given field name (heuristic-based) */
@@ -176,15 +185,14 @@ export async function fuzzEndpoint(baseUrl, path, validBody, opts = {}) {
       continue; // can't serialize (e.g., circular)
     }
 
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeout);
-
     try {
-      const res = await fetch(`${baseUrl}${path}`, {
+      const res = await request(`${baseUrl}${path}`, {
         method,
         headers,
         body,
-        signal: controller.signal,
+        timeout,
+        probe: "api-fuzzing",
+        redirect: "follow",
       });
 
       const text = await res.text().catch(() => "");
@@ -223,9 +231,7 @@ export async function fuzzEndpoint(baseUrl, path, validBody, opts = {}) {
         findings.push(result);
       }
     } catch {
-      // timeout or network error, skip
-    } finally {
-      clearTimeout(timer);
+      // timeout or network error: recorded in result.errors by the HTTP client
     }
   }
 

package/lib/injections.js

@@ -14,28 +14,26 @@
  *   - Nuclei, pattern-based detection
  *   - Burp Suite, time-based blind SQLi
  *
- * WARNING: These probes send attack payloads to the target.
+ * What this file is, for anyone reviewing the package:
+ *   The strings below are test inputs, the same well-known probes found in
+ *   OWASP testing guides and scanners like sqlmap, Burp and Nuclei. Penthera
+ *   never executes them. They are sent as request parameters to the one target
+ *   URL the user names, and only when the user opts in with --deep (or the
+ *   deep profile). Detection happens by reading that target's responses.
+ *   Nothing here runs on, or reaches out from, the machine running Penthera;
+ *   the HTTP client in src/utils/http.js refuses other hosts under --offline.
+ *
  * Only use against targets you have permission to test.
  */
 
 import { redirectsToHost } from "../src/utils/url.js";
+import { fetchText } from "../src/utils/http.js";
 
 const INJECT_TIMEOUT = 10_000;
 
-async function safeFetch(url, opts = {}) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), opts.timeout || INJECT_TIMEOUT);
-  const start = Date.now();
-  try {
-    const res = await fetch(url, { ...opts, signal: controller.signal, redirect: "manual" });
-    const elapsed = Date.now() - start;
-    const body = await res.text().catch(() => "");
-    return { status: res.status, body, headers: Object.fromEntries(res.headers.entries()), elapsed, ok: true };
-  } catch {
-    return { status: 0, body: "", headers: {}, elapsed: Date.now() - start, ok: false };
-  } finally {
-    clearTimeout(timeout);
-  }
+/** A fetch bound to one probe name, so failures are attributed in result.errors. */
+function clientFor(probe) {
+  return (url, opts = {}) => fetchText(url, { timeout: INJECT_TIMEOUT, probe, ...opts });
 }
 
 // ── Timing-based detection helpers ───────────────────────────────────────
@@ -125,6 +123,7 @@ const SQLI_PAYLOADS = [
  * @returns {object[]} Findings
  */
 export async function probeSqli(baseUrl, path, opts = {}) {
+  const safeFetch = clientFor("sqli");
   const findings = [];
   const method = opts.method || "GET";
 
@@ -253,6 +252,7 @@ export function sstiEvaluated(body, payload, expr, product) {
  * Test an endpoint for SSTI.
  */
 export async function probeSsti(baseUrl, path, opts = {}) {
+  const safeFetch = clientFor("ssti");
   const findings = [];
   const { probes, expr, product } = buildSstiProbes();
 
@@ -316,6 +316,7 @@ const SSRF_TARGETS = [
  * Test an endpoint for SSRF via URL parameters.
  */
 export async function probeSsrf(baseUrl, path, opts = {}) {
+  const safeFetch = clientFor("ssrf");
   const findings = [];
 
   // Identify URL-like parameters in the path or common parameter names
@@ -373,6 +374,7 @@ const REDIRECT_PAYLOADS = [
  * Test an endpoint for open redirect.
  */
 export async function probeOpenRedirect(baseUrl, path, opts = {}) {
+  const safeFetch = clientFor("open-redirect");
   const findings = [];
   const redirectParams = ["redirect", "redirect_uri", "return", "return_to", "next", "url", "callback", "redir", "destination", "go"];
 
@@ -421,6 +423,7 @@ const CMDI_PAYLOADS = [
  * Test an endpoint for OS command injection.
  */
 export async function probeCmdi(baseUrl, path, opts = {}) {
+  const safeFetch = clientFor("cmdi");
   const findings = [];
   const method = opts.method || "POST";
 
@@ -512,6 +515,7 @@ export function isHtmlResponse(res) {
  *   5. Verify the payload is reflected unescaped
  */
 export async function probeXss(baseUrl, path, opts = {}) {
+  const safeFetch = clientFor("xss");
   const findings = [];
   const CANARY = makeCanary();
   const inputParams = ["q", "search", "query", "name", "input", "text", "value", "msg", "error", "redirect", "url", "id"];

package/lib/install/index.js

@@ -0,0 +1,271 @@
+/**
+ * `penthera install`: an install firewall on top of the `penthera deps` engine.
+ *
+ *   1. Resolve. `npm install --package-lock-only --ignore-scripts [pkg...]` runs
+ *      in a temporary copy of package.json / package-lock.json / .npmrc. Not in
+ *      place: npm rewrites node_modules/.package-lock.json even in lock-only
+ *      mode, and an abort must leave the project byte for byte as it was.
+ *   2. Fetch. `npm cache add` puts each new tarball in npm's cache; nothing is
+ *      unpacked into node_modules and no package code runs. The deps engine
+ *      reads tarballs back from the cache only after verifying them against
+ *      the proposed lockfile's integrity (lib/deps/source.js).
+ *   3. Diff. lib/deps scans the proposed tree against the current lockfile:
+ *      new packages, capabilities gained, install scripts, typosquats.
+ *   4. Decide. lib/install/policy.js turns that into deny / needs-approval.
+ *   5. Apply (only when allowed). The vetted package.json and lockfile are
+ *      written into the project and `npm install` installs exactly that tree,
+ *      with `--ignore-scripts` unless the new install scripts were approved.
+ *
+ * Penthera makes no network calls here. npm talks to its configured registry
+ * (resolve and fetch); that is the one expected egress.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, mkdtempSync, readFileSync, writeFileSync, copyFileSync, rmSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { scanDeps } from "../deps/index.js";
+import { parseLockfile } from "../deps/lockfile.js";
+import { sourceFromNpmCache, npmCacheDir } from "../deps/source.js";
+import { evaluatePolicy, normalizePolicy } from "./policy.js";
+
+const run = promisify(execFile);
+const NPM = process.platform === "win32" ? "npm.cmd" : "npm";
+const LOCKFILES = ["package-lock.json", "npm-shrinkwrap.json"];
+const COPY = ["package.json", ...LOCKFILES, ".npmrc"];
+const QUIET = ["--no-audit", "--no-fund", "--no-update-notifier"];
+const LOCAL_SPEC = /^(file:|link:|portal:|\.{1,2}\/|\/)/;
+
+async function npm(args, opts) {
+  try {
+    return await run(NPM, args, { maxBuffer: 64 * 1024 * 1024, shell: process.platform === "win32", ...opts });
+  } catch (e) {
+    const msg = String(e.stderr || e.message).trim().split("\n").filter((l) => !/^npm (verbose|silly|timing)/.test(l)).slice(-8).join("\n");
+    throw new Error(`npm ${args[0]} failed:\n${msg}`);
+  }
+}
+
+/** npm's version and registry, as npm sees them from the project. */
+export async function npmInfo(root, env = process.env) {
+  const [version, registry] = await Promise.all([
+    npm(["--version"], { cwd: root, env }).then((r) => r.stdout.trim()),
+    npm(["config", "get", "registry"], { cwd: root, env }).then((r) => r.stdout.trim(), () => "the configured npm registry"),
+  ]);
+  const major = parseInt(version, 10) || 0;
+  // npm 12 blocks dependency install scripts unless package.json allowScripts lists them.
+  return { version, major, registry, allowScriptsPolicy: major >= 12 };
+}
+
+const key = (p) => `${p.path}@${p.version}#${p.integrity || ""}`;
+const scriptsOf = (s) => (s && Object.keys(s).length ? s : null);
+
+/** The rule ids a change raises (see lib/install/policy.js). */
+function flagsFor(caps, { newScripts, typosquat, unscanned }) {
+  const flags = [...(caps || [])].filter((id) => id !== "install-scripts");
+  if (newScripts) flags.unshift("install-scripts");
+  if (typosquat) flags.push("typosquat");
+  if (unscanned) flags.push("unscanned");
+  return flags;
+}
+
+/**
+ * Turn the deps diff into one change per new or upgraded package.
+ * `packages` is result.deps.packages, for the capabilities of an upgrade whose
+ * old version could not be read.
+ */
+export function changesFromDiff(diff, typosquats = [], packages = []) {
+  const typo = new Map(typosquats.map((t) => [t.name, t]));
+  const capsOf = (name, version) => {
+    const c = packages.find((p) => p.name === name && p.version === version)?.capabilities;
+    return c ? Object.keys(c) : null;
+  };
+  const out = [];
+  for (const a of diff.added) {
+    const scripts = scriptsOf(a.installScripts);
+    out.push({
+      change: "added",
+      name: a.name,
+      version: a.version,
+      capabilities: a.capabilities || [],
+      installScripts: scripts,
+      typosquatOf: typo.get(a.name)?.target || null,
+      flags: flagsFor(a.capabilities, { newScripts: !!scripts, typosquat: typo.has(a.name), unscanned: a.capabilities === null }),
+    });
+  }
+  for (const u of diff.upgraded) {
+    const scripts = scriptsOf(u.installScripts);
+    const before = scriptsOf(u.previousInstallScripts);
+    // A hook that is new, or whose command changed, is new code at install time.
+    const newScripts = !!scripts && JSON.stringify(scripts) !== JSON.stringify(before);
+    // Old version unreadable: judge the new version on everything it can do.
+    const gained = u.gained ?? (u.unavailable === "old" ? capsOf(u.name, u.to) : null);
+    out.push({
+      change: "upgraded",
+      name: u.name,
+      version: u.to,
+      from: u.from,
+      capabilities: gained || [],
+      installScripts: scripts,
+      previousInstallScripts: before,
+      compared: u.unavailable == null,
+      typosquatOf: null,
+      flags: flagsFor(gained, { newScripts, typosquat: false, unscanned: u.unavailable === "new" }),
+    });
+  }
+  return out;
+}
+
+function readIfExists(p) {
+  return existsSync(p) ? readFileSync(p) : null;
+}
+
+function checkProject(root, pkgJson) {
+  if (pkgJson.workspaces) throw new Error("npm workspaces are not supported by `penthera install` yet. Run `npm install --package-lock-only --ignore-scripts` and review with `penthera deps --base HEAD`.");
+  const local = Object.entries({ ...pkgJson.dependencies, ...pkgJson.devDependencies, ...pkgJson.optionalDependencies })
+    .filter(([, spec]) => LOCAL_SPEC.test(String(spec)));
+  if (local.length) throw new Error(`Local path dependencies (${local.map(([n]) => n).join(", ")}) cannot be resolved from a temporary copy. Run \`npm install --package-lock-only --ignore-scripts\` and review with \`penthera deps --base HEAD\`.`);
+}
+
+/**
+ * Work out what `npm install [specs]` would change, without running any
+ * package code and without writing to the project.
+ * @param {string} root project folder (has package.json)
+ * @param {string[]} specs packages as npm accepts them (name, name@range, ...)
+ * @param {{ policy?: object, saveDev?: boolean, saveExact?: boolean, offline?: boolean,
+ *           env?: object, onPhase?: Function, info?: object }} opts
+ */
+export async function planInstall(root, specs, opts = {}) {
+  root = resolve(root);
+  const env = opts.env || process.env;
+  const onPhase = opts.onPhase || (() => {});
+  const pkgPath = join(root, "package.json");
+  if (!existsSync(pkgPath)) throw new Error(`No package.json in ${root}`);
+  checkProject(root, JSON.parse(readFileSync(pkgPath, "utf-8")));
+  const bad = specs.filter((s) => s.startsWith("-") || LOCAL_SPEC.test(s));
+  if (bad.length) throw new Error(`Unsupported package spec(s): ${bad.join(", ")}. Pass registry names (name, name@version, name@range).`);
+
+  const info = opts.info || await npmInfo(root, env);
+  const original = Object.fromEntries(COPY.map((f) => [f, readIfExists(join(root, f))]));
+  const lockName = LOCKFILES.find((f) => original[f]) || "package-lock.json";
+
+  const tmp = mkdtempSync(join(tmpdir(), "penthera-install-"));
+  try {
+    const work = join(tmp, "project");
+    mkdirSync(work);
+    for (const f of COPY) if (original[f]) copyFileSync(join(root, f), join(work, f));
+
+    const flags = [...(opts.saveDev ? ["--save-dev"] : []), ...(opts.saveExact ? ["--save-exact"] : []), ...(opts.offline ? ["--offline"] : [])];
+    onPhase(`Resolving in a temporary copy: npm install --package-lock-only --ignore-scripts${specs.length ? ` ${specs.join(" ")}` : ""}`);
+    await npm(["install", "--package-lock-only", "--ignore-scripts", ...QUIET, ...flags, ...specs], { cwd: work, env });
+
+    const proposedLockPath = join(work, lockName);
+    if (!existsSync(proposedLockPath)) throw new Error("npm did not write a lockfile");
+    const proposedLock = JSON.parse(readFileSync(proposedLockPath, "utf-8"));
+
+    // Base: the project's current lockfile, or an empty tree for a first install.
+    let baseLockPath = original[lockName] ? join(root, lockName) : null;
+    if (!baseLockPath) {
+      mkdirSync(join(tmp, "base"));
+      baseLockPath = join(tmp, "base", "package-lock.json");
+      writeFileSync(baseLockPath, JSON.stringify({ lockfileVersion: 3, packages: { "": {} } }));
+    }
+    const oldKeys = new Set(parseLockfile(JSON.parse(readFileSync(baseLockPath, "utf-8"))).map(key));
+    const fresh = parseLockfile(proposedLock).filter((p) => !p.link && p.version && !oldKeys.has(key(p)));
+
+    // New tarballs go into a private npm cache (npm cache add): nothing is
+    // unpacked or run. Private because npm will not reliably say where its own
+    // cache is (`npm config get cache` refuses some paths), and because the
+    // scan must not depend on what else that cache holds.
+    const userCache = npmCacheDir(env);
+    const fetchCache = join(tmp, "cache");
+    const toFetch = fresh.filter((p) => !p.integrity || !sourceFromNpmCache(p.integrity, userCache));
+    if (toFetch.length) {
+      onPhase(`Fetching ${toFetch.length} tarball(s) with npm cache add (nothing is unpacked or run)`);
+      const fetchSpecs = [...new Set(toFetch.map((p) => (p.resolved && !/^https?:/.test(p.resolved) ? p.resolved : `${p.name}@${p.version}`)))];
+      await npm(["cache", "add", "--cache", fetchCache, ...(opts.offline ? ["--offline"] : []), ...fetchSpecs], { cwd: tmp, env });
+    }
+
+    onPhase("Comparing capabilities with the current tree (offline, integrity-verified)");
+    const result = await scanDeps(work, { diff: baseLockPath, treeRoot: root, cacheDir: [fetchCache, userCache] });
+    const changes = changesFromDiff(result.deps.diff, result.deps.typosquats, result.deps.packages);
+    const verdict = evaluatePolicy(changes, opts.policy || normalizePolicy({}));
+
+    return {
+      root,
+      specs,
+      npm: info,
+      lockName,
+      original,
+      proposed: {
+        "package.json": readFileSync(join(work, "package.json")),
+        [lockName]: readFileSync(proposedLockPath),
+      },
+      changes,
+      removed: result.deps.diff.removed,
+      verdict,
+      findings: result.findings,
+      typosquats: result.deps.typosquats,
+      evidence: result.deps.diff.evidence,
+    };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+/** Packages whose new or changed install scripts would run. */
+export const scriptChanges = (plan) => plan.verdict.items.filter((i) => i.flags.includes("install-scripts"));
+
+/**
+ * Pin approved packages in package.json allowScripts (npm >= 12 runs a
+ * dependency's install scripts only when listed there). Returns new bytes.
+ */
+export function withAllowScripts(pkgJsonBuf, items) {
+  const text = pkgJsonBuf.toString("utf-8");
+  const pkg = JSON.parse(text);
+  const allow = { ...(pkg.allowScripts || {}) };
+  for (const i of items) {
+    if (allow[i.name] === false) continue; // an explicit denial in the project wins
+    allow[`${i.name}@${i.version}`] = true;
+  }
+  pkg.allowScripts = Object.fromEntries(Object.entries(allow).sort((a, b) => a[0].localeCompare(b[0])));
+  const indent = text.match(/^\{\r?\n([ \t]+)"/)?.[1] || "  ";
+  return Buffer.from(JSON.stringify(pkg, null, indent) + (text.endsWith("\n") ? "\n" : ""));
+}
+
+function restore(root, original) {
+  for (const [f, buf] of Object.entries(original)) {
+    const p = join(root, f);
+    if (buf) writeFileSync(p, buf);
+    else rmSync(p, { force: true });
+  }
+}
+
+/**
+ * Install the vetted tree. Writes the proposed package.json and lockfile,
+ * then runs `npm install` with no package arguments, so npm installs exactly
+ * the lockfile that was reviewed. Restores both files if npm fails.
+ * @param {{ runScripts: boolean, env?: object, stdio?: string, offline?: boolean }} opts
+ */
+export async function applyInstall(plan, opts) {
+  const { root, original } = plan;
+  const env = opts.env || process.env;
+  let pkgJson = plan.proposed["package.json"];
+  const approved = scriptChanges(plan);
+  if (opts.runScripts && plan.npm.allowScriptsPolicy && approved.length) pkgJson = withAllowScripts(pkgJson, approved);
+
+  writeFileSync(join(root, "package.json"), pkgJson);
+  writeFileSync(join(root, plan.lockName), plan.proposed[plan.lockName]);
+  const args = ["install", ...QUIET, ...(opts.runScripts ? [] : ["--ignore-scripts"]), ...(opts.offline ? ["--offline"] : [])];
+  try {
+    await npm(args, { cwd: root, env });
+  } catch (e) {
+    restore(root, original);
+    throw new Error(`${e.message}\npackage.json and ${plan.lockName} were restored; node_modules may be partly updated (run \`npm ci\` to reset it).`);
+  }
+
+  // npm should have installed the reviewed lockfile as is.
+  const want = new Set(parseLockfile(JSON.parse(plan.proposed[plan.lockName])).map(key));
+  const got = parseLockfile(JSON.parse(readFileSync(join(root, plan.lockName), "utf-8"))).map(key);
+  const drift = got.filter((k) => !want.has(k));
+  return { args, scriptsRan: opts.runScripts, allowScriptsAdded: pkgJson !== plan.proposed["package.json"] ? approved.map((i) => `${i.name}@${i.version}`) : [], drift };
+}