pkgxray 0.7.0 → 0.8.1

package/bin/audit.js

@@ -51,6 +51,9 @@ function parseArgs(argv) {
       options.vulnerabilityCheck = false;
     } else if (arg === "--no-github") {
       options.githubMetadata = false;
+      options.githubDiff = false;
+    } else if (arg === "--no-github-diff") {
+      options.githubDiff = false;
     } else {
       throw new Error(`Unknown argument: ${arg}`);
     }

package/bin/mcp-server.js

@@ -107,6 +107,11 @@ function guardToolDefinition() {
           default: true,
           description: "Set false to skip the GitHub provenance cross-check."
         },
+        githubDiff: {
+          type: "boolean",
+          default: true,
+          description: "Set false to skip the npm-vs-GitHub source diff (saves a tarball download)."
+        },
         outputFormat: {
           type: "string",
           enum: ["markdown", "json"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pkgxray",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Zero-dep local CLI and MCP server that scans npm packages for supply-chain risk. OSV vuln pre-check, sandboxed quarantine, tarball-integrity verification, calibrated static heuristics, GitHub provenance cross-check.",
   "license": "MIT",
   "author": "Jack Adams-Lovell",

package/src/auditor.js

@@ -157,7 +157,8 @@ function normalizeEvidence(input) {
       evidence.knownVulnerabilities || evidence.vulnerabilities || evidence.osvVulnerabilities || [],
     sourceFiles: normalizeSourceFiles(
       evidence.sourceFiles || evidence.SOURCE_FILES || evidence.files || {}
-    )
+    ),
+    npmVsGithubDiff: evidence.npmVsGithubDiff || null
   };
 }
 
@@ -243,7 +244,9 @@ const BAND_DEFINITIONS = [
   { band: "github-archived", label: "github-archived", categories: ["github-archived"], rationale: "Linked repository is archived or disabled — no maintenance, security issues will not be fixed." },
   { band: "github-young", label: "github-young", categories: ["github-young"], rationale: "Linked repository was created within the last 30 days — common slopsquat shape." },
   { band: "github-lonely", label: "github-lonely", categories: ["github-lonely"], rationale: "0 stars + 0 forks + low watcher count on a young repo. Low community signal." },
-  { band: "github-stale", label: "github-stale", categories: ["github-stale"], rationale: "Repository hasn't been pushed to in over two years and isn't formally archived." }
+  { band: "github-stale", label: "github-stale", categories: ["github-stale"], rationale: "Repository hasn't been pushed to in over two years and isn't formally archived." },
+  { band: "npm-vs-github-divergence", label: "npm-vs-github-divergence", categories: ["npm-vs-github-divergence"], rationale: "Published npm tarball contains source files that aren't in (or differ from) the linked GitHub repo at the matching ref. Strong account-takeover / build-tampering signal." },
+  { band: "npm-vs-github-clean", label: "npm-vs-github-clean", categories: ["npm-vs-github-clean"], rationale: "npm tarball matches the linked GitHub repo at the published version." }
 ];
 
 const SEVERITY_RANK = { info: 0, low: 1, medium: 2, high: 3 };
@@ -291,6 +294,54 @@ function auditMetadata(evidence, findings) {
   inspectMetadataObject("NPM_METADATA", evidence.npmMetadata, findings);
   inspectGithubMetadata(evidence, findings);
   inspectKnownVulnerabilities(evidence.knownVulnerabilities, findings);
+  inspectNpmVsGithubDiff(evidence, findings);
+}
+
+function inspectNpmVsGithubDiff(evidence, findings) {
+  const diff = evidence.npmVsGithubDiff;
+  if (!diff || !diff.compared) {
+    // Not gating — silent skip. Common reasons: no github repo,
+    // ref not found, github fetch failed.
+    return;
+  }
+  const c = diff.counts || {};
+  if (c.extraSource > 0) {
+    const examples = (diff.suspiciousExtras || [])
+      .filter((f) => f.category === "extra-source")
+      .slice(0, 5)
+      .map((f) => f.path);
+    findings.push({
+      severity: "high",
+      category: "npm-vs-github-divergence",
+      file: "NPM_VS_GITHUB",
+      snippet: `npm tarball contains ${c.extraSource} source file(s) not in the linked GitHub repo @${diff.githubRef}: ${examples.join(", ")}`,
+      rationale:
+        "Source files present in the published tarball but absent from the matching GitHub ref. Classic account-takeover / build-server-compromise signal."
+    });
+  }
+  if (c.mismatchedSource > 0) {
+    const examples = (diff.suspiciousMismatches || [])
+      .filter((f) => f.category === "content-mismatch-source")
+      .slice(0, 5)
+      .map((f) => f.path);
+    findings.push({
+      severity: "high",
+      category: "npm-vs-github-divergence",
+      file: "NPM_VS_GITHUB",
+      snippet: `${c.mismatchedSource} source file(s) differ between npm tarball and GitHub repo @${diff.githubRef}: ${examples.join(", ")}`,
+      rationale:
+        "Source files with the same path but different SHA256 in the published tarball vs the linked GitHub repo at the matching ref. Strong tampering signal."
+    });
+  }
+  if (c.extraSource === 0 && c.mismatchedSource === 0 && (c.matched > 0 || c.npmFiles > 0)) {
+    findings.push({
+      severity: "info",
+      category: "npm-vs-github-clean",
+      file: "NPM_VS_GITHUB",
+      snippet: `${c.matched}/${c.npmFiles} files match GitHub @${diff.githubRef}`,
+      rationale: "npm tarball source files match the linked GitHub repo at the matching ref."
+    });
+  }
 }
 
 const YOUNG_REPO_DAYS = 30;

package/src/diff.js

@@ -0,0 +1,298 @@
+"use strict";
+
+const fs = require("node:fs");
+const fsp = require("node:fs/promises");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const SKIP_DIRS = new Set([
+  ".git",
+  "node_modules",
+  ".github",
+  ".vscode",
+  ".idea",
+  "coverage",
+  "__pycache__"
+]);
+
+// File patterns that are expected to differ — never used to drive findings.
+const ALWAYS_IGNORE = [
+  /(?:^|\/)package\.json$/,
+  /(?:^|\/)package-lock\.json$/,
+  /(?:^|\/)yarn\.lock$/,
+  /(?:^|\/)pnpm-lock\.yaml$/,
+  /(?:^|\/)\.npmignore$/,
+  /(?:^|\/)\.gitignore$/,
+  /(?:^|\/)\.gitattributes$/,
+  /(?:^|\/)CHANGELOG(?:\.md)?$/i,
+  /(?:^|\/)CONTRIBUTING(?:\.md)?$/i,
+  /(?:^|\/)\.npmrc$/
+];
+
+// Patterns that mean "this is build output" — only flagged if no build script
+// exists. With a prepare/prepack script, extras here are expected.
+const BUILD_OUTPUT_PATTERNS = [
+  /(?:^|\/)dist\//,
+  /(?:^|\/)build\//,
+  /(?:^|\/)lib\//,
+  /(?:^|\/)es\//,
+  /(?:^|\/)esm\//,
+  /(?:^|\/)cjs\//,
+  /(?:^|\/)umd\//,
+  /\.min\.js$/,
+  /\.min\.mjs$/,
+  /\.min\.css$/,
+  /\.d\.ts$/,
+  /\.d\.cts$/,
+  /\.d\.mts$/,
+  /\.js\.map$/,
+  /\.css\.map$/
+];
+
+// Source extensions whose contents we care about most. Mismatches or extras
+// here are the strongest ATO signal.
+const SOURCE_EXTENSIONS = new Set([
+  ".js", ".cjs", ".mjs", ".jsx",
+  ".ts", ".tsx",
+  ".vue", ".svelte",
+  ".py", ".rb", ".go", ".rs", ".java", ".cs", ".php",
+  ".sh", ".ps1", ".bash",
+  ".json", ".toml", ".yaml", ".yml"
+]);
+
+function isAlwaysIgnored(relPath) {
+  return ALWAYS_IGNORE.some((re) => re.test(relPath));
+}
+
+function isBuildOutput(relPath) {
+  return BUILD_OUTPUT_PATTERNS.some((re) => re.test(relPath));
+}
+
+function isSourceFile(relPath) {
+  const ext = path.extname(relPath).toLowerCase();
+  return SOURCE_EXTENSIONS.has(ext);
+}
+
+async function hashTree(root, subdir, limits) {
+  const baseDir = subdir ? path.join(root, subdir) : root;
+  try {
+    await fsp.access(baseDir);
+  } catch {
+    return null;
+  }
+  const result = new Map();
+  const queue = [""];
+  let totalBytes = 0;
+  let totalFiles = 0;
+  const maxFiles = limits.maxFiles || 5000;
+  const maxBytes = limits.maxBytes || 50 * 1024 * 1024;
+  const maxFileBytes = limits.maxFileBytes || 1024 * 1024;
+
+  while (queue.length > 0 && totalFiles < maxFiles && totalBytes < maxBytes) {
+    const rel = queue.shift();
+    const full = path.join(baseDir, rel);
+    let entries;
+    try {
+      entries = await fsp.readdir(full, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        queue.push(childRel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const childFull = path.join(baseDir, childRel);
+      let stat;
+      try {
+        stat = await fsp.stat(childFull);
+      } catch {
+        continue;
+      }
+      if (stat.size > maxFileBytes) {
+        result.set(childRel, { size: stat.size, sha256: "skipped:too-large" });
+        continue;
+      }
+      if (totalBytes + stat.size > maxBytes) {
+        // soft cap — record presence without hash
+        result.set(childRel, { size: stat.size, sha256: "skipped:tree-budget" });
+        continue;
+      }
+      const hash = await hashFile(childFull);
+      result.set(childRel, { size: stat.size, sha256: hash });
+      totalBytes += stat.size;
+      totalFiles += 1;
+      if (totalFiles >= maxFiles) break;
+    }
+  }
+  return result;
+}
+
+function hashFile(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash("sha256");
+    fs.createReadStream(filePath)
+      .on("data", (chunk) => hash.update(chunk))
+      .on("error", reject)
+      .on("end", () => resolve(hash.digest("hex")));
+  });
+}
+
+// Compare a staged npm package against the matching GitHub repo subtree.
+// Returns null if the comparison wasn't possible.
+async function diffNpmVsGithub({ npmStagedPath, githubStagedPath, subdir, hasBuildScript }) {
+  const limits = { maxFiles: 5000, maxBytes: 50 * 1024 * 1024 };
+  const [npmTree, ghTree] = await Promise.all([
+    hashTree(npmStagedPath, "", limits),
+    hashTree(githubStagedPath, subdir || "", limits)
+  ]);
+  if (!npmTree || !ghTree) {
+    return {
+      compared: false,
+      reason: !ghTree ? "github-subdir-missing" : "npm-tree-missing"
+    };
+  }
+
+  // Pre-compute the set of directories that EXIST in github. We use this to
+  // decide whether an extra file is in a "real source dir" (sibling source
+  // files exist in github) or in a path github doesn't have at all (more
+  // likely build output).
+  const ghDirs = new Set();
+  for (const ghPath of ghTree.keys()) {
+    const parts = ghPath.split("/");
+    for (let i = 1; i < parts.length; i += 1) {
+      ghDirs.add(parts.slice(0, i).join("/"));
+    }
+  }
+
+  const extraInNpm = [];
+  const mismatched = [];
+  const matched = [];
+
+  for (const [rel, npmEntry] of npmTree.entries()) {
+    if (isAlwaysIgnored(rel)) continue;
+    const ghEntry = ghTree.get(rel);
+    if (!ghEntry) {
+      const parentDir = rel.includes("/") ? rel.split("/").slice(0, -1).join("/") : "";
+      const parentExistsInGh = parentDir === "" || ghDirs.has(parentDir);
+      // An extra file inside a directory that exists in github is the strong
+      // ATO signal — github has the dir, the attacker just dropped one more
+      // file in it. An extra file at a path github doesn't have at all is
+      // more likely build output the repo never committed.
+      const inLikelySourceDir = /^(?:src|tests?|scripts|spec)\//.test(rel);
+      let category;
+      if (parentExistsInGh && isSourceFile(rel)) {
+        category = "extra-source";
+      } else if (isBuildOutput(rel)) {
+        category = hasBuildScript ? "expected-build-output" : "extra-build-output";
+      } else if (isSourceFile(rel)) {
+        category = hasBuildScript && !inLikelySourceDir
+          ? "expected-build-output"
+          : "extra-source";
+      } else {
+        category = "extra-other";
+      }
+      extraInNpm.push({ path: rel, category, size: npmEntry.size });
+      continue;
+    }
+    if (npmEntry.sha256 !== ghEntry.sha256) {
+      // skipped hashes don't count as a mismatch
+      if (npmEntry.sha256.startsWith("skipped") || ghEntry.sha256.startsWith("skipped")) {
+        continue;
+      }
+      const inLikelySourceDir = /^(?:src|tests?|scripts|spec)\//.test(rel);
+      const category = isBuildOutput(rel)
+        ? hasBuildScript ? "expected-build-output" : "content-mismatch-build"
+        : isSourceFile(rel)
+          ? hasBuildScript && !inLikelySourceDir
+            ? "expected-build-output"
+            : "content-mismatch-source"
+          : "content-mismatch-other";
+      mismatched.push({ path: rel, category, npmSize: npmEntry.size, ghSize: ghEntry.size });
+    } else {
+      matched.push(rel);
+    }
+  }
+
+  const extraSource = extraInNpm.filter((f) => f.category === "extra-source");
+  const extraBuild = extraInNpm.filter((f) => f.category === "extra-build-output");
+  const mismatchedSource = mismatched.filter((f) => f.category === "content-mismatch-source");
+
+  // Tree-overlap sanity check. Many real packages don't publish a 1:1 mirror
+  // of their repo (lodash publishes flat per-function modules, react bundles
+  // src/ to root, monorepos publish a subtree). If the npm tarball and the
+  // github tree have very little overlap at matching paths, comparing them
+  // produces mostly noise. Bail out with an honest "no-overlap" reason rather
+  // than firing HIGH on legit packages.
+  const consideredFiles = npmTree.size; // already excludes node_modules etc.
+  const overlapRatio = consideredFiles > 0 ? (matched.length + mismatched.length) / consideredFiles : 0;
+  const MIN_OVERLAP_RATIO = 0.3;
+
+  if (overlapRatio < MIN_OVERLAP_RATIO && extraSource.length > 20) {
+    return {
+      compared: false,
+      reason: "tree-layout-differs",
+      hasBuildScript,
+      subdir: subdir || null,
+      overlapRatio: Number(overlapRatio.toFixed(2)),
+      counts: {
+        npmFiles: npmTree.size,
+        ghFiles: ghTree.size,
+        matched: matched.length,
+        mismatched: mismatched.length,
+        extraInNpm: extraInNpm.length
+      },
+      note:
+        "npm tarball and GitHub tree have very little overlap at matching paths — the package is likely built / bundled before publish. Diff would be unreliable; skipping."
+    };
+  }
+
+  // Second skip case: of the files that DO exist at matching paths, most
+  // mismatch. That means the published artifacts are generated from the repo
+  // source (typical of `prepublish` / `release-please` / `changesets` build
+  // flows that minify or transform entry files). Diff is unreliable here.
+  const overlapCount = matched.length + mismatched.length;
+  if (overlapCount >= 5 && mismatched.length > matched.length * 2) {
+    return {
+      compared: false,
+      reason: "tree-mostly-generated",
+      hasBuildScript,
+      subdir: subdir || null,
+      overlapRatio: Number(overlapRatio.toFixed(2)),
+      counts: {
+        npmFiles: npmTree.size,
+        ghFiles: ghTree.size,
+        matched: matched.length,
+        mismatched: mismatched.length,
+        extraInNpm: extraInNpm.length
+      },
+      note:
+        "Most overlapping files differ in content — published artifacts are likely generated from the repo source (e.g. bundling, transpilation). Diff would be unreliable; skipping."
+    };
+  }
+
+  return {
+    compared: true,
+    hasBuildScript,
+    subdir: subdir || null,
+    overlapRatio: Number(overlapRatio.toFixed(2)),
+    counts: {
+      npmFiles: npmTree.size,
+      ghFiles: ghTree.size,
+      matched: matched.length,
+      mismatched: mismatched.length,
+      extraInNpm: extraInNpm.length,
+      extraSource: extraSource.length,
+      mismatchedSource: mismatchedSource.length
+    },
+    suspiciousExtras: extraSource.concat(extraBuild).slice(0, 25),
+    suspiciousMismatches: mismatchedSource.concat(
+      mismatched.filter((f) => f.category === "content-mismatch-build")
+    ).slice(0, 25)
+  };
+}
+
+module.exports = { diffNpmVsGithub };

package/src/github.js

@@ -1,9 +1,12 @@
 "use strict";
 
+const fs = require("node:fs");
 const fsp = require("node:fs/promises");
 const os = require("node:os");
 const path = require("node:path");
 const https = require("node:https");
+const crypto = require("node:crypto");
+const { spawn } = require("node:child_process");
 
 const USER_AGENT = "pkgxray/0.6.0";
 const CACHE_DIR = path.join(os.homedir(), ".cache", "pkgxray", "github");
@@ -46,7 +49,9 @@ function parseGithubRepo(repository) {
     /^github:([^/]+)\/(.+)$/,
     /^(?:https?|git):\/\/github\.com\/([^/]+)\/([^/?#]+)/,
     /^git@github\.com:([^/]+)\/([^/?#]+)/,
-    /^ssh:\/\/git@github\.com\/([^/]+)\/([^/?#]+)/
+    /^ssh:\/\/git@github\.com\/([^/]+)\/([^/?#]+)/,
+    // npm shorthand: bare "owner/repo" defaults to GitHub
+    /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/
   ];
   for (const pattern of patterns) {
     const match = cleaned.match(pattern);
@@ -160,7 +165,135 @@ async function fetchRepoMetadata(repository, options = {}) {
   }
 }
 
+// ---- Tarball download + ref resolution ----
+
+const TARBALL_CACHE_DIR = path.join(os.homedir(), ".cache", "pkgxray", "tarballs");
+const TARBALL_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const TARBALL_TIMEOUT_MS = 15000;
+const MAX_TARBALL_BYTES = 100 * 1024 * 1024; // 100MB
+
+function tarballCachePath(owner, repo, ref) {
+  const key = crypto
+    .createHash("sha1")
+    .update(`${owner}/${repo}@${ref}`)
+    .digest("hex");
+  return path.join(TARBALL_CACHE_DIR, `${key}.tgz`);
+}
+
+async function downloadCodeload(url, destination) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(destination, { mode: 0o600 });
+    let written = 0;
+    let cleanedUp = false;
+    const cleanup = (err) => {
+      if (cleanedUp) return;
+      cleanedUp = true;
+      file.destroy();
+      fs.unlink(destination, () => reject(err));
+    };
+    const get = (currentUrl, hops) => {
+      if (hops > 5) return cleanup(new Error("Too many redirects"));
+      const parsed = new URL(currentUrl);
+      const request = https.get(
+        {
+          hostname: parsed.hostname,
+          path: parsed.pathname + parsed.search,
+          headers: { "user-agent": USER_AGENT },
+          timeout: TARBALL_TIMEOUT_MS
+        },
+        (response) => {
+          if ([301, 302, 303, 307, 308].includes(response.statusCode) && response.headers.location) {
+            response.resume();
+            return get(new URL(response.headers.location, currentUrl).toString(), hops + 1);
+          }
+          if (response.statusCode === 404) {
+            response.resume();
+            const err = new Error(`GitHub codeload 404: ${currentUrl}`);
+            err.statusCode = 404;
+            return cleanup(err);
+          }
+          if (response.statusCode < 200 || response.statusCode >= 300) {
+            response.resume();
+            return cleanup(new Error(`Codeload HTTP ${response.statusCode}`));
+          }
+          response.on("data", (chunk) => {
+            written += chunk.length;
+            if (written > MAX_TARBALL_BYTES) {
+              response.destroy();
+              cleanup(new Error(`Codeload exceeded ${MAX_TARBALL_BYTES} bytes`));
+            }
+          });
+          response.pipe(file);
+          file.on("finish", () => file.close(() => resolve()));
+        }
+      );
+      request.on("error", cleanup);
+      request.on("timeout", () => request.destroy(new Error("Codeload request timed out")));
+    };
+    get(url, 0);
+  });
+}
+
+function run(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${command} exited with ${code}: ${stderr.trim()}`));
+    });
+  });
+}
+
+async function extractTarball(archivePath, destination) {
+  await fsp.mkdir(destination, { recursive: true, mode: 0o700 });
+  return run("tar", [
+    "-xzf", archivePath,
+    "-C", destination,
+    "--strip-components", "1",
+    "--no-same-owner", "--no-same-permissions"
+  ]);
+}
+
+// Try refs in order until one downloads. Caches the first successful one.
+async function fetchRepoTarballForVersion(owner, repo, version, defaultBranch) {
+  await fsp.mkdir(TARBALL_CACHE_DIR, { recursive: true, mode: 0o700 });
+  const candidates = [];
+  if (version) {
+    candidates.push(`v${version}`);
+    candidates.push(version);
+  }
+  if (defaultBranch) candidates.push(defaultBranch);
+
+  for (const ref of candidates) {
+    const cachePath = tarballCachePath(owner, repo, ref);
+    try {
+      const stat = await fsp.stat(cachePath);
+      if (Date.now() - stat.mtimeMs < TARBALL_TTL_MS) {
+        return { ref, archivePath: cachePath, fromCache: true };
+      }
+    } catch {
+      // not cached, fall through to download
+    }
+    const url = `https://codeload.github.com/${owner}/${repo}/tar.gz/${encodeURIComponent(ref)}`;
+    try {
+      await downloadCodeload(url, cachePath);
+      return { ref, archivePath: cachePath, fromCache: false };
+    } catch (error) {
+      if (error.statusCode === 404) continue;
+      throw error;
+    }
+  }
+  return null;
+}
+
 module.exports = {
   parseGithubRepo,
-  fetchRepoMetadata
+  fetchRepoMetadata,
+  fetchRepoTarballForVersion,
+  extractTarball
 };

package/src/quarantine.js

@@ -8,7 +8,8 @@ const os = require("node:os");
 const path = require("node:path");
 const { spawn } = require("node:child_process");
 const { auditEvidence } = require("./auditor");
-const { fetchRepoMetadata } = require("./github");
+const { fetchRepoMetadata, fetchRepoTarballForVersion, extractTarball: extractTarballGh } = require("./github");
+const { diffNpmVsGithub } = require("./diff");
 
 const DEFAULT_MAX_FILE_BYTES = 256 * 1024;
 const DEFAULT_MAX_FILES = 600;
@@ -104,13 +105,41 @@ async function guardExtension(reference, options = {}) {
   const githubMetadata = await githubMetadataPromise;
   timings.githubMetadataMs = elapsed(githubStart);
 
+  // npm vs GitHub diff (Phase 3) — only for npm packages where we have repo
+  // metadata. Runs serially after we have both trees; tarballs are cached so
+  // re-runs are fast.
+  let npmVsGithubDiff = null;
+  if (
+    options.githubDiff !== false &&
+    (resolved.type === "npm" || resolved.type === "local") &&
+    githubMetadata && githubMetadata.found &&
+    vulnerabilities.length === 0 &&
+    Object.keys(sourceFiles).length > 0
+  ) {
+    const diffStart = now();
+    try {
+      npmVsGithubDiff = await runNpmVsGithubDiff({
+        resolved,
+        npmStagedPath: stagedPath,
+        githubMetadata,
+        workspace
+      });
+    } catch (error) {
+      npmVsGithubDiff = { compared: false, reason: "diff-error", message: error.message };
+    }
+    timings.diffMs = elapsed(diffStart);
+  } else {
+    timings.diffMs = 0;
+  }
+
   const evidence = {
     packageName: resolved.packageName || reference,
     npmMetadata: resolved.npmMetadata || null,
     githubMetadata,
     webPresence: null,
     knownVulnerabilities: vulnerabilities,
-    sourceFiles
+    sourceFiles,
+    npmVsGithubDiff
   };
   const auditStart = now();
   const report = auditEvidence(evidence);
@@ -123,6 +152,7 @@ async function guardExtension(reference, options = {}) {
     resolved,
     sourceFiles,
     githubMetadata,
+    npmVsGithubDiff,
     vulnerabilityPrecheck: {
       enabled: options.vulnerabilityCheck !== false,
       database: "OSV",
@@ -143,14 +173,84 @@ async function guardExtension(reference, options = {}) {
   return result;
 }
 
+async function runNpmVsGithubDiff({ resolved, npmStagedPath, githubMetadata, workspace }) {
+  const version = resolved.version;
+  const tarball = await fetchRepoTarballForVersion(
+    githubMetadata.owner,
+    githubMetadata.repo,
+    version,
+    githubMetadata.default_branch
+  );
+  if (!tarball) {
+    return { compared: false, reason: "no-matching-ref", versionTried: version };
+  }
+
+  const ghStagePath = path.join(workspace, "github-tree");
+  await extractTarballGh(tarball.archivePath, ghStagePath);
+
+  // package.json may set repository.directory for monorepos — narrow the
+  // comparison to that subpath if present.
+  const pkgRepo = resolved.npmMetadata && resolved.npmMetadata.repository;
+  const subdir = pkgRepo && typeof pkgRepo === "object" ? pkgRepo.directory || null : null;
+
+  // Detect a publish-time build script (means built artifacts ≠ repo is normal)
+  const scripts = await readScripts(npmStagedPath);
+  const hasBuildScript = Boolean(scripts.prepare || scripts.prepack || scripts.build);
+
+  const diff = await diffNpmVsGithub({
+    npmStagedPath,
+    githubStagedPath: ghStagePath,
+    subdir,
+    hasBuildScript
+  });
+
+  return {
+    ...diff,
+    githubRef: tarball.ref,
+    tarballFromCache: tarball.fromCache
+  };
+}
+
+async function readScripts(stagedPath) {
+  try {
+    const pkg = JSON.parse(await fsp.readFile(path.join(stagedPath, "package.json"), "utf8"));
+    return pkg.scripts || {};
+  } catch {
+    return {};
+  }
+}
+
 async function stageReference(reference, stagedPath, options) {
   const parsed = parseReference(reference);
   if (parsed.type === "local") {
     await copyLocalPath(parsed.path, stagedPath);
+    // Populate npmMetadata from the staged package.json so downstream phases
+    // (github metadata cross-check, npm-vs-github diff) can work on local
+    // packages too.
+    let npmMetadata = null;
+    let packageName = path.basename(parsed.path);
+    let version = null;
+    try {
+      const pkg = JSON.parse(await fsp.readFile(path.join(stagedPath, "package.json"), "utf8"));
+      packageName = pkg.name || packageName;
+      version = pkg.version || null;
+      if (pkg.repository) {
+        npmMetadata = {
+          name: pkg.name || packageName,
+          version: pkg.version || null,
+          repository: pkg.repository,
+          maintainers: []
+        };
+      }
+    } catch {
+      // no package.json or unparseable — fine, just no metadata
+    }
     return {
       type: "local",
       source: parsed.path,
-      packageName: path.basename(parsed.path)
+      packageName,
+      version,
+      npmMetadata
     };
   }