penthera 1.1.1 → 1.4.0

package/lib/deps/index.js

@@ -0,0 +1,416 @@
+/**
+ * `penthera deps`: offline, deterministic dependency risk scanning for npm.
+ *
+ * Reads package-lock.json, statically scans every installed package for what
+ * it can do (lib/deps/capabilities.js), checks names for typosquats against a
+ * vendored list, and, with --diff / --base, reports packages that are new or
+ * that gained capabilities in an upgrade. Results are ordinary Penthera
+ * findings (category "dependency-risk", source "deps-scan"), so the terminal,
+ * Markdown, JSON and SARIF outputs all work unchanged.
+ *
+ * Offline by default. Old versions for the diff come from the base tree's
+ * node_modules or npm's local content cache, verified against the lockfile
+ * integrity. `--online` is the only network use (lib/deps/online.js).
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, dirname, relative, resolve, basename } from "node:path";
+import { findLockfile, readLockfile, parseLockfile, directDependencies, readLockfileAtRef } from "./lockfile.js";
+import { DirSource, sourceFromNpmCache, npmCacheDir } from "./source.js";
+import { scanPackage, CAPABILITIES, CAPABILITY_ORDER, maxSeverity } from "./capabilities.js";
+import { diffTrees } from "./diff.js";
+import { findTyposquats, loadPopular } from "./typosquat.js";
+
+const SOURCE = "deps-scan";
+const CATEGORY = "dependency-risk";
+const KNOWN_BAD = ["ai-config-write", "ai-cli-invoke", "token-harvest"];
+// Owners of these scopes legitimately manage their own AI tool config.
+const KNOWN_BAD_EXEMPT = { "ai-config-write": [/^@anthropic-ai\//], "ai-cli-invoke": [/^@anthropic-ai\//] };
+
+// ── Resolving package contents ────────────────────────────────────────────
+
+function installedVersion(dir) {
+  try {
+    return JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")).version || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find a package's files offline: the tree's node_modules (when the installed
+ * version matches the lockfile), else npm's cache by integrity.
+ */
+function resolveSource(pkg, treeRoot, cacheDirs) {
+  if (treeRoot) {
+    const dir = join(treeRoot, pkg.path);
+    if (existsSync(dir) && installedVersion(dir) === pkg.version) return new DirSource(dir);
+  }
+  if (!pkg.integrity) return null;
+  for (const d of cacheDirs) {
+    const src = sourceFromNpmCache(pkg.integrity, d);
+    if (src) return src;
+  }
+  return null;
+}
+
+/** Scan a list of lockfile packages. Results cached by name@version+integrity. */
+function scanTree(pkgs, treeRoot, ctx) {
+  return pkgs.map((p) => {
+    const key = `${p.name}@${p.version}#${p.integrity || ""}`;
+    if (!ctx.cache.has(key)) {
+      const src = resolveSource(p, treeRoot, ctx.cacheDirs);
+      ctx.cache.set(key, src ? { ...scanPackage(src, { prefix: `${p.path}/` }), source: src.kind } : null);
+    }
+    const r = ctx.cache.get(key);
+    return {
+      ...p,
+      source: r?.source || null,
+      capabilities: r ? r.capabilities : null,
+      installScripts: r?.installScripts || {},
+      installRisk: r?.installRisk || [],
+      exfil: r?.exfil || [],
+      filesScanned: r?.filesScanned || 0,
+    };
+  });
+}
+
+// ── Findings ──────────────────────────────────────────────────────────────
+
+const capList = (ids) => ids.map((id) => CAPABILITIES[id]?.label || id).join(", ");
+
+function evidenceText(caps, ids) {
+  const lines = [];
+  for (const id of ids) {
+    for (const e of (caps?.[id]?.evidence || []).slice(0, 2)) {
+      lines.push(`${CAPABILITIES[id].label}: ${e.file}:${e.line} \`${e.snippet}\``);
+    }
+  }
+  return lines.join("; ");
+}
+
+function firstEvidence(caps, ids) {
+  for (const id of ids) {
+    const e = caps?.[id]?.evidence?.[0];
+    if (e) return e;
+  }
+  return null;
+}
+
+function finding({ title, severity, confidence, method, description, pkg, ev, capabilities, extra = {} }) {
+  return {
+    title,
+    severity,
+    category: CATEGORY,
+    source: SOURCE,
+    method,
+    confidence,
+    description,
+    url: ev?.file || pkg.path,
+    line: ev?.line || undefined,
+    package: pkg.name,
+    version: pkg.version,
+    capabilities,
+    ...extra,
+  };
+}
+
+/** Risk findings that stand on their own, without a diff. */
+function riskFindings(pkg) {
+  const out = [];
+  const caps = pkg.capabilities;
+  if (!caps) return out;
+  const at = `${pkg.name}@${pkg.version}`;
+
+  for (const id of KNOWN_BAD) {
+    if (!caps[id]) continue;
+    if ((KNOWN_BAD_EXEMPT[id] || []).some((re) => re.test(pkg.name))) continue;
+    const ev = caps[id].evidence[0];
+    out.push(finding({
+      title: `${at}: ${CAPABILITIES[id].label}`,
+      severity: "critical",
+      confidence: CAPABILITIES[id].confidence,
+      method: "deps-capability-scan",
+      description: `${CAPABILITIES[id].why} Evidence: ${evidenceText(caps, [id])}`,
+      pkg, ev, capabilities: [id],
+    }));
+  }
+  if (caps.obfuscated) {
+    const ev = caps.obfuscated.evidence[0];
+    out.push(finding({
+      title: `${at}: obfuscated code`,
+      severity: "high",
+      confidence: "potential",
+      method: "deps-capability-scan",
+      description: `${CAPABILITIES.obfuscated.why} Signals at ${ev.file}:${ev.line}: ${ev.snippet}. Read the file before trusting it; minified code alone does not trigger this.`,
+      pkg, ev, capabilities: ["obfuscated"],
+    }));
+  }
+  if (pkg.exfil?.length) {
+    const ev = pkg.exfil[0];
+    out.push(finding({
+      title: `${at}: serialises the whole environment next to network code`,
+      severity: "high",
+      confidence: "likely",
+      method: "deps-capability-scan",
+      description: `process.env (tokens, keys, CI secrets) is serialised within a few lines of a network call, the shape of credential exfiltration. Evidence: ${ev.file}:${ev.line} \`${ev.snippet}\`. ${evidenceText(caps, ["network"])}`,
+      pkg, ev, capabilities: ["env-bulk", "network"],
+    }));
+  }
+  if (caps["install-scripts"]) {
+    const ev = caps["install-scripts"].evidence[0];
+    const hooks = Object.entries(pkg.installScripts).map(([h, cmd]) => `${h}: \`${cmd.slice(0, 100)}\``).join("; ");
+    const risky = pkg.installRisk.length > 0;
+    out.push(finding({
+      title: `${at}: runs ${risky ? "a risky " : ""}install script`,
+      severity: risky ? "medium" : "low",
+      confidence: "confirmed",
+      method: "deps-capability-scan",
+      description: `${CAPABILITIES["install-scripts"].why} ${hooks}.${risky ? ` Why it stands out: ${pkg.installRisk.join("; ")}.` : ""} Install with \`npm ci --ignore-scripts\` if the package works without it.`,
+      pkg, ev, capabilities: ["install-scripts"],
+    }));
+  }
+  return out;
+}
+
+// Capabilities that riskFindings already reports on their own.
+const OWN_FINDING = new Set([...KNOWN_BAD, "obfuscated", "install-scripts"]);
+
+function diffFindings(diff) {
+  const out = [];
+  for (const a of diff.added) {
+    const ids = a.capabilities || [];
+    const notable = ids.filter((id) => id !== "env" && id !== "dynamic-require" && !OWN_FINDING.has(id));
+    if (notable.length === 0) continue;
+    out.push(finding({
+      title: `New dependency ${a.name}@${a.version}: ${capList(notable)}`,
+      severity: maxSeverity(notable.map((id) => CAPABILITIES[id].severity)),
+      confidence: "likely",
+      method: "deps-capability-diff",
+      description: `A package that was not in the base tree. It can: ${notable.map((id) => CAPABILITIES[id].why).join(" ")} Evidence: ${evidenceText(a.pkg.capabilities, notable)}`,
+      pkg: a.pkg, ev: firstEvidence(a.pkg.capabilities, notable), capabilities: notable,
+      extra: { change: "added" },
+    }));
+  }
+  for (const u of diff.upgraded) {
+    if (!u.gained || u.gained.length === 0) continue;
+    const sev = maxSeverity(u.gained.map((id) => CAPABILITIES[id].severity));
+    out.push(finding({
+      title: `${u.name} ${u.from} → ${u.to} gained ${capList(u.gained)}`,
+      severity: sev,
+      confidence: u.gained.some((id) => CAPABILITIES[id].confidence === "potential") && u.gained.length === 1 ? "potential" : "likely",
+      method: "deps-capability-diff",
+      description: `This upgrade can do things the previous version could not. ${u.gained.map((id) => CAPABILITIES[id].why).join(" ")} Evidence: ${evidenceText(u.pkg.capabilities, u.gained)}`,
+      pkg: u.pkg, ev: firstEvidence(u.pkg.capabilities, u.gained), capabilities: u.gained,
+      extra: { change: "upgraded", from: u.from },
+    }));
+  }
+  const missing = diff.upgraded.filter((u) => u.unavailable);
+  if (missing.length) {
+    out.push({
+      title: `${missing.length} upgraded package(s) not compared: old version not available offline`,
+      severity: "info",
+      category: CATEGORY,
+      source: SOURCE,
+      method: "deps-capability-diff",
+      confidence: "confirmed",
+      description: `No local copy to compare against for: ${missing.map((u) => `${u.name} ${u.from} → ${u.to}`).join(", ")}. Install the base tree (\`npm ci --ignore-scripts\` in a checkout of the base) and pass that folder to --diff, or rerun with --online to fetch the old tarballs from the registry.`,
+      url: "package-lock.json",
+    });
+  }
+  return out;
+}
+
+function typosquatFindings(hits, pkgByName, direct) {
+  return hits.map((h) => {
+    const pkg = pkgByName.get(h.name) || { name: h.name, version: null, path: "package-lock.json" };
+    const isDirect = direct.has(h.name);
+    return finding({
+      title: `${h.name} looks like ${h.target} (${h.kind})`,
+      severity: isDirect ? "medium" : "low",
+      confidence: "potential",
+      method: "deps-typosquat",
+      description: `\`${h.name}\` is ${h.distance} edit(s) from \`${h.target}\` (#${h.rank} in the vendored popular-package list) and is not itself on that list. Typosquats and AI-hallucinated names (slopsquatting) look exactly like this. Check it is the package you meant to install${isDirect ? "" : ` and why a dependency pulls it in`}.`,
+      pkg, ev: { file: pkg.path, line: undefined }, capabilities: [],
+      extra: { typosquatOf: h.target, direct: isDirect },
+    });
+  });
+}
+
+function registryFindings(results, pkgByKey) {
+  const out = [];
+  for (const [key, r] of [...results].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const pkg = pkgByKey.get(key);
+    if (!pkg) continue;
+    for (const s of r.signals) {
+      out.push(finding({
+        title: `${key}: ${s.text}`,
+        severity: s.severity,
+        confidence: "confirmed",
+        method: "deps-registry",
+        description: `From npm registry metadata (--online). ${s.id === "publisher-change" ? "A new publisher on an established package is how account takeovers ship malware; check the release notes and diff." : s.id === "new-package" ? "Brand-new packages are where typosquats and slopsquats (names AI assistants hallucinate) live." : s.id === "fresh-version" ? "Most malicious versions are caught and pulled within days; waiting out a short cooldown on new releases avoids them." : ""}`,
+        pkg, ev: { file: pkg.path }, capabilities: [],
+        extra: { registrySignal: s.id },
+      }));
+    }
+  }
+  return out;
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────
+
+function summarize(tree) {
+  const counts = {};
+  for (const id of CAPABILITY_ORDER) counts[id] = 0;
+  for (const p of tree) for (const id of Object.keys(p.capabilities || {})) counts[id]++;
+  return counts;
+}
+
+/** Load the old tree for --diff (lockfile path or project folder) or --base (git ref). */
+function loadBase(root, opts) {
+  if (opts.base) {
+    return { lock: readLockfileAtRef(root, opts.base), treeRoot: null, label: opts.base };
+  }
+  const p = resolve(opts.diff);
+  if (!existsSync(p)) throw new Error(`--diff path not found: ${opts.diff}`);
+  const isDir = statSync(p).isDirectory();
+  const lockPath = isDir ? findLockfile(p) : p;
+  if (!lockPath) throw new Error(`No package-lock.json in ${opts.diff}`);
+  const treeRoot = dirname(lockPath);
+  // A lockfile beside the project's own node_modules describes another tree;
+  // only trust node_modules that sit next to the old lockfile.
+  return { lock: readLockfile(lockPath), treeRoot: treeRoot === resolve(root) ? null : treeRoot, label: opts.diff };
+}
+
+/**
+ * Scan a project's dependencies.
+ * @param {string} root project folder containing package-lock.json
+ * @param {{ diff?: string, base?: string, online?: boolean, prod?: boolean,
+ *           onPhase?: Function, cacheDir?: string|string[], now?: number, fetchImpl?: Function,
+ *           treeRoot?: string }} opts treeRoot: where installed packages live, when
+ *           the lockfile describes a tree that is not installed beside it (penthera install)
+ */
+export async function scanDeps(root, opts = {}) {
+  const started = Date.now();
+  const onPhase = opts.onPhase || (() => {});
+  const lockPath = findLockfile(root);
+  if (!lockPath) throw new Error(`No package-lock.json in ${root}. penthera deps reads the lockfile; run \`npm install --package-lock-only\` first.`);
+  const lock = readLockfile(lockPath);
+  const ctx = { cache: new Map(), cacheDirs: [].concat(opts.cacheDir || npmCacheDir()) };
+  const keep = (p) => !p.link && p.version && (!opts.prod || !p.dev);
+
+  const pkgs = parseLockfile(lock).filter(keep);
+  onPhase(`Scanning ${pkgs.length} packages from ${basename(lockPath)} (offline)`);
+  const tree = scanTree(pkgs, opts.treeRoot || root, ctx);
+  const direct = new Set(directDependencies(lock));
+
+  let diff = null;
+  let base = null;
+  if (opts.diff || opts.base) {
+    base = loadBase(root, opts);
+    const oldPkgs = parseLockfile(base.lock).filter(keep);
+    const byVersion = new Map(tree.map((p) => [`${p.name}@${p.version}`, p]));
+    const newNames = new Set(tree.map((p) => p.name));
+    // Only old versions that are gone but whose name remains need inspecting:
+    // a version present in both trees has the same contents (same lockfile
+    // integrity), and a removed name is not compared.
+    const needOld = oldPkgs.filter((p) => !byVersion.has(`${p.name}@${p.version}`) && newNames.has(p.name));
+    onPhase(`Comparing against ${base.label}: ${needOld.length} replaced version(s) to inspect`);
+    const oldScanned = new Map(scanTree(needOld, base.treeRoot, ctx).map((p) => [p.path, p]));
+    const oldTree = oldPkgs.map((p) => oldScanned.get(p.path)
+      || { ...p, capabilities: byVersion.get(`${p.name}@${p.version}`)?.capabilities || {}, installScripts: byVersion.get(`${p.name}@${p.version}`)?.installScripts || {} });
+    diff = diffTrees(oldTree, tree);
+  }
+
+  // --online: registry metadata, and old tarballs the cache did not have.
+  let online = null;
+  const findings = [];
+  if (opts.online) {
+    const { checkRegistry, fetchTarballSource } = await import("./online.js");
+    const changed = diff ? [...diff.added.map((a) => a.pkg), ...diff.upgraded.map((u) => ({ ...u.pkg, previous: u.from }))] : [];
+    const items = diff ? changed : tree.filter((p) => direct.has(p.name));
+    onPhase(`--online: fetching registry metadata for ${items.length} package(s) (the only network use)`);
+    const results = await checkRegistry(items.map((p) => ({ name: p.name, version: p.version, previous: p.previous })), { fetchImpl: opts.fetchImpl, now: opts.now });
+    online = { checked: items.length, unreachable: [...results.values()].filter((r) => !r.reachable).length, fetchedTarballs: 0 };
+    if (diff) {
+      const oldPkgs = parseLockfile(base.lock);
+      for (const u of diff.upgraded.filter((x) => x.unavailable === "old")) {
+        const oldPkg = oldPkgs.find((p) => p.name === u.name && p.version === u.from);
+        // Verified against the base lockfile's integrity before anything is read.
+        const src = await fetchTarballSource(oldPkg?.resolved, oldPkg?.integrity, { fetchImpl: opts.fetchImpl });
+        if (!src) continue;
+        online.fetchedTarballs++;
+        const o = new Set(Object.keys(scanPackage(src, { prefix: `${oldPkg.path}/` }).capabilities));
+        const n = new Set(Object.keys(u.pkg.capabilities || {}));
+        u.gained = CAPABILITY_ORDER.filter((id) => n.has(id) && !o.has(id));
+        u.lost = CAPABILITY_ORDER.filter((id) => o.has(id) && !n.has(id));
+        u.unavailable = null;
+      }
+    }
+    findings.push(...registryFindings(results, new Map(tree.map((p) => [`${p.name}@${p.version}`, p]))));
+  }
+
+  // In diff mode, report on what changed; otherwise on the whole tree.
+  const inScope = diff
+    ? new Set([...diff.added.map((a) => a.pkg), ...diff.upgraded.map((u) => u.pkg)])
+    : new Set(tree);
+  for (const p of tree) if (inScope.has(p)) findings.push(...riskFindings(p));
+  if (diff) findings.push(...diffFindings(diff));
+
+  // Names you chose (direct deps), or names that are new in this change. A
+  // transitive dependency of an unchanged tree was picked by its parent's
+  // maintainers long ago; flagging those is mostly noise.
+  const nameScope = diff ? diff.added.map((a) => a.name) : tree.filter((p) => direct.has(p.name)).map((p) => p.name);
+  const typos = findTyposquats(nameScope);
+  findings.push(...typosquatFindings(typos, new Map(tree.map((p) => [p.name, p])), direct));
+
+  // Optional packages for other platforms (esbuild-style binaries) are expected to be absent.
+  const unavailable = tree.filter((p) => !p.capabilities && !p.optional);
+  const skippedOptional = tree.filter((p) => !p.capabilities && p.optional).length;
+  const rel = (p) => {
+    const r = relative(process.cwd(), p);
+    return r === "" ? "." : r.startsWith("..") ? p : r;
+  };
+  return {
+    target: rel(root),
+    mode: "deps",
+    local: true,
+    reachable: true,
+    timestamp: new Date(started).toISOString(),
+    duration: Date.now() - started,
+    deps: {
+      lockfile: rel(lockPath),
+      lockfileVersion: lock.lockfileVersion || 1,
+      prod: !!opts.prod,
+      network: opts.online ? "online (registry metadata only)" : "offline",
+      total: tree.length,
+      scanned: tree.filter((p) => p.capabilities).length,
+      skippedOptional,
+      direct: [...direct],
+      notInstalled: unavailable.map((p) => `${p.name}@${p.version}`),
+      capabilityCounts: summarize(tree),
+      popularList: loadPopular().source,
+      packages: tree.map((p) => ({
+        name: p.name,
+        version: p.version,
+        path: p.path,
+        dev: p.dev,
+        direct: direct.has(p.name),
+        source: p.source,
+        capabilities: p.capabilities,
+      })),
+      typosquats: typos,
+      online,
+      diff: diff ? {
+        base: base.label,
+        added: diff.added.map(({ pkg, ...a }) => ({ ...a, installScripts: pkg.installScripts })),
+        upgraded: diff.upgraded.map(({ pkg, prev, ...u }) => ({ ...u, installScripts: pkg.installScripts, previousInstallScripts: prev?.installScripts || null })),
+        removed: diff.removed,
+        evidence: Object.fromEntries([...diff.added, ...diff.upgraded].map((x) => {
+          const ids = x.gained || x.capabilities || [];
+          return [`${x.name}@${x.version || x.to}`, Object.fromEntries(ids.map((id) => [id, x.pkg.capabilities?.[id]?.evidence || []]))];
+        })),
+      } : null,
+    },
+    findings,
+  };
+}

package/lib/deps/lockfile.js

@@ -0,0 +1,106 @@
+/**
+ * package-lock.json reader for `penthera deps`.
+ *
+ * Turns a lockfile (v1, v2 or v3) into a flat, sorted list of installed
+ * packages with the fields the capability scanner and the diff need: where the
+ * package lives in node_modules, its exact version, and its integrity hash (the
+ * key into npm's offline content cache).
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+
+/** Package name from a lockfile v2/v3 key like node_modules/a/node_modules/@s/b. */
+export function nameFromLockPath(key) {
+  const i = key.lastIndexOf("node_modules/");
+  return i === -1 ? key : key.slice(i + "node_modules/".length);
+}
+
+/**
+ * Parse lockfile JSON into packages.
+ * @returns {{ name, version, path, integrity, resolved, dev, optional, hasInstallScript, link }[]}
+ */
+export function parseLockfile(lock) {
+  const out = [];
+  if (lock && lock.packages) {
+    for (const [key, v] of Object.entries(lock.packages)) {
+      if (key === "" || !v) continue;
+      // Workspace members appear twice: a link entry under node_modules and the
+      // real folder. Keep the node_modules view, skip the source folder entry.
+      if (!key.includes("node_modules/")) continue;
+      const name = v.name || nameFromLockPath(key);
+      out.push({
+        name,
+        version: v.version || null,
+        path: key,
+        integrity: v.integrity || null,
+        resolved: v.resolved || null,
+        dev: !!v.dev,
+        optional: !!(v.optional || v.devOptional),
+        hasInstallScript: !!v.hasInstallScript,
+        link: !!v.link,
+      });
+    }
+  } else if (lock && lock.dependencies) {
+    const walk = (deps, prefix) => {
+      for (const [name, v] of Object.entries(deps)) {
+        if (!v) continue;
+        const path = `${prefix}node_modules/${name}`;
+        out.push({
+          name,
+          version: v.version || null,
+          path,
+          integrity: v.integrity || null,
+          resolved: v.resolved || null,
+          dev: !!v.dev,
+          optional: !!v.optional,
+          hasInstallScript: false,
+          link: String(v.version || "").startsWith("file:"),
+        });
+        if (v.dependencies) walk(v.dependencies, `${path}/`);
+      }
+    };
+    walk(lock.dependencies, "");
+  }
+  return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/** Direct dependency names declared by the root project (from the lockfile root entry). */
+export function directDependencies(lock) {
+  const root = lock?.packages?.[""] || {};
+  const names = new Set([
+    ...Object.keys(root.dependencies || {}),
+    ...Object.keys(root.devDependencies || {}),
+    ...Object.keys(root.optionalDependencies || {}),
+  ]);
+  return [...names].sort();
+}
+
+/** Read and parse a lockfile from disk. */
+export function readLockfile(path) {
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+/** Locate package-lock.json (or npm-shrinkwrap.json) in a project directory. */
+export function findLockfile(dir) {
+  for (const f of ["package-lock.json", "npm-shrinkwrap.json"]) {
+    const p = join(dir, f);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Read the lockfile as it was at a git ref (for `--base <ref>`).
+ * Only runs `git show`; no fetch, no checkout.
+ */
+export function readLockfileAtRef(dir, ref) {
+  const git = (args) => execFileSync("git", args, { cwd: dir, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+  const prefix = git(["rev-parse", "--show-prefix"]).trim();
+  for (const f of ["package-lock.json", "npm-shrinkwrap.json"]) {
+    try {
+      return JSON.parse(git(["show", `${ref}:${prefix}${f}`]));
+    } catch { /* try the next name */ }
+  }
+  throw new Error(`No package-lock.json at ${ref} in ${dir}`);
+}

package/lib/deps/online.js

@@ -0,0 +1,132 @@
+/**
+ * `penthera deps --online`: registry metadata checks.
+ *
+ * THE ONLY NETWORK USE IN `penthera deps`, and it is off by default. When the
+ * flag is set it makes plain GET requests to the public npm registry
+ * (registry.npmjs.org, or npm_config_registry) for package metadata, and, in
+ * diff mode, for old tarballs that are not in the local npm cache. Nothing
+ * about your project is sent: the requests name public packages only.
+ *
+ * Signals:
+ *   - version published under 30 days ago (fresh releases are where hijacks land),
+ *   - package created under 30 days ago (slopsquat / brand-new name),
+ *   - publisher changed from the previous version to someone who was not a maintainer,
+ *   - version deprecated.
+ */
+import { sourceFromTarball } from "./source.js";
+import { request } from "../../src/utils/http.js";
+
+// Registry calls go through the shared client: same User-Agent, same egress
+// accounting (and refusal under --offline) as every other request.
+const registryFetch = (url, opts) => request(url, { ...opts, redirect: "follow", probe: "deps-online" });
+
+const DAY_MS = 24 * 3600 * 1000;
+export const FRESH_DAYS = 30;
+
+export function registryUrl(env = process.env) {
+  return String(env.npm_config_registry || env.NPM_CONFIG_REGISTRY || "https://registry.npmjs.org/").replace(/\/?$/, "/");
+}
+
+/** Fetch a packument. Returns parsed JSON or null. */
+export async function fetchPackument(name, { fetchImpl = registryFetch, registry = registryUrl(), timeout = 15000 } = {}) {
+  // Registry form: "@scope%2fname". Encoding the whole name also keeps a hostile
+  // lockfile entry from adding path segments or a query to the request.
+  const url = registry + encodeURIComponent(name).replace(/^%40/, "@");
+  try {
+    const res = await fetchImpl(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(timeout) });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+/** Version published right before `version`, by publish time. */
+function previousVersion(doc, version) {
+  const times = Object.entries(doc.time || {})
+    .filter(([v]) => v !== "created" && v !== "modified" && doc.versions?.[v])
+    .sort((a, b) => Date.parse(a[1]) - Date.parse(b[1]));
+  const i = times.findIndex(([v]) => v === version);
+  return i > 0 ? times[i - 1][0] : null;
+}
+
+const publisher = (v) => v?._npmUser?.name || null;
+const maintainers = (v) => (v?.maintainers || []).map((m) => (typeof m === "string" ? m : m.name)).filter(Boolean);
+
+/**
+ * Metadata signals for one name@version.
+ * @param {object} doc packument
+ * @param {string} version
+ * @param {{ previous?: string, now?: number }} opts previous = version this one replaces (diff mode)
+ */
+export function registrySignals(doc, version, { previous = null, now = Date.now() } = {}) {
+  const signals = [];
+  if (!doc || !doc.versions) return signals;
+  const v = doc.versions[version];
+  if (!v) {
+    signals.push({ id: "missing-version", severity: "high", text: `${version} is not on the registry (unpublished or never published)` });
+    return signals;
+  }
+  if (v.deprecated) signals.push({ id: "deprecated", severity: "low", text: `deprecated: ${String(v.deprecated).slice(0, 160)}` });
+
+  const published = Date.parse(doc.time?.[version] || "");
+  if (published && now - published < FRESH_DAYS * DAY_MS) {
+    const days = Math.max(0, Math.floor((now - published) / DAY_MS));
+    signals.push({ id: "fresh-version", severity: "low", text: `published ${days} day(s) ago` });
+  }
+  const created = Date.parse(doc.time?.created || "");
+  if (created && now - created < FRESH_DAYS * DAY_MS) {
+    const days = Math.max(0, Math.floor((now - created) / DAY_MS));
+    signals.push({ id: "new-package", severity: "medium", text: `package created ${days} day(s) ago` });
+  }
+
+  const prev = previous && doc.versions[previous] ? previous : previousVersion(doc, version);
+  if (prev) {
+    const before = doc.versions[prev];
+    const was = publisher(before);
+    const now_ = publisher(v);
+    if (was && now_ && was !== now_ && !maintainers(before).includes(now_)) {
+      signals.push({ id: "publisher-change", severity: "medium", text: `published by ${now_}; ${prev} was published by ${was}, and ${now_} was not a maintainer then` });
+    }
+  }
+  return signals;
+}
+
+/**
+ * Look up registry signals for a set of packages.
+ * @param {{ name, version, previous? }[]} items
+ * @returns {Promise<Map<string, { signals, doc }>>} keyed by name@version
+ */
+export async function checkRegistry(items, opts = {}) {
+  const concurrency = opts.concurrency || 8;
+  const docs = new Map();
+  const names = [...new Set(items.map((i) => i.name))].sort();
+  for (let i = 0; i < names.length; i += concurrency) {
+    const batch = names.slice(i, i + concurrency);
+    const got = await Promise.all(batch.map((n) => fetchPackument(n, opts)));
+    batch.forEach((n, k) => docs.set(n, got[k]));
+  }
+  const out = new Map();
+  for (const it of items) {
+    const doc = docs.get(it.name);
+    out.set(`${it.name}@${it.version}`, {
+      reachable: !!doc,
+      signals: doc ? registrySignals(doc, it.version, { previous: it.previous, now: opts.now }) : [],
+      tarball: doc?.versions?.[it.version]?.dist?.tarball || null,
+    });
+  }
+  return out;
+}
+
+/** Download a tarball and verify it against the lockfile integrity. */
+export async function fetchTarballSource(url, integrity, { fetchImpl = registryFetch, timeout = 30000 } = {}) {
+  if (!url || !/^https:\/\//.test(url) || !integrity) return null;
+  try {
+    const res = await fetchImpl(url, { signal: AbortSignal.timeout(timeout) });
+    if (!res.ok) return null;
+    const buf = Buffer.from(await res.arrayBuffer());
+    return sourceFromTarball(buf, integrity, "registry");
+  } catch {
+    return null;
+  }
+}