pkgxray 0.6.0 → 0.8.0

package/bin/audit.js

@@ -12,7 +12,7 @@ function printUsage() {
       "  pkgxray < evidence.json",
       "  pkgxray --format json < evidence.json",
       "  pkgxray --file evidence.json --format markdown",
-      "  pkgxray guard <npm-package|npm:name@version|./path> [--promote-to dir] [--no-source-scan]",
+      "  pkgxray guard <npm-package|npm:name@version|github:owner/repo[#ref]|./path> [--promote-to dir] [--no-source-scan]",
       "",
       "Evidence JSON fields:",
       "  packageName, npmMetadata, githubMetadata, webPresence, sourceFiles",
@@ -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.6.0",
+  "version": "0.8.0",
   "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

@@ -13,25 +13,24 @@ const SEVERITY_ORDER = {
   high: 3
 };
 
+// Suspicious credential / wallet read targets. Each entry is a regex that
+// requires a path or quote boundary so we don't match identifiers like
+// `process.env` or `someObj.ledger`.
 const SUSPICIOUS_READ_TARGETS = [
-  "~/.ssh",
-  ".ssh/",
-  "id_rsa",
-  "id_dsa",
-  "id_ecdsa",
-  "id_ed25519",
-  "~/.aws",
-  ".aws/credentials",
-  ".npmrc",
-  ".env",
-  "keychain",
-  "login.keychain",
-  "cookies.sqlite",
-  "local state",
-  "metamask",
-  "electrum",
-  "exodus",
-  "ledger"
+  { re: /['"`\/\\]\.?ssh\/(?:id_(?:rsa|dsa|ecdsa|ed25519)|authorized_keys)/i, label: "ssh-private-key" },
+  { re: /['"`\/\\]id_(?:rsa|dsa|ecdsa|ed25519)\b/i, label: "ssh-key-file" },
+  { re: /['"`\/\\]\.ssh(?:\/|['"`])/, label: ".ssh-dir" },
+  { re: /['"`\/\\]\.aws\/credentials\b/, label: ".aws/credentials" },
+  { re: /['"`\/\\]\.aws\/(?:config|credentials)\b/, label: ".aws-files" },
+  { re: /['"`\/\\]\.npmrc(?:['"`]|\s|$)/, label: ".npmrc" },
+  { re: /['"`\/\\]\.env(?:\.[a-z]+)?(?:['"`]|\s|$)/i, label: ".env-file" },
+  { re: /['"`]login\.keychain(?:-db)?['"`]/i, label: "macOS keychain" },
+  { re: /\bsecurity\s+find-(?:generic|internet)-password\b/, label: "macOS security CLI" },
+  { re: /['"`]\/?(?:Cookies|Login Data|Web Data|cookies\.sqlite)['"`]/i, label: "browser-creds" },
+  { re: /['"`]Local State['"`]/, label: "browser local-state" },
+  { re: /\bkeytar\.[a-z]+Password\(/i, label: "keytar API" },
+  { re: /\bmetamask['"`\s\/]/i, label: "metamask wallet" },
+  { re: /\b(?:electrum|exodus|ledger live|atomic wallet)\b/i, label: "crypto wallet" }
 ];
 
 // Persistence destinations. Each pattern requires a quote/slash boundary
@@ -158,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
   };
 }
 
@@ -244,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 };
@@ -292,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;
@@ -607,16 +657,16 @@ const BULK_ENV_REGEXES = [
 
 function inspectCredentialAccess(file, content, lower, findings) {
   for (const target of SUSPICIOUS_READ_TARGETS) {
-    const index = lower.indexOf(target.toLowerCase());
-    if (index === -1) continue;
-    if (!looksLikeCredentialRead(content, lower, index)) continue;
+    const match = target.re.exec(content);
+    if (!match) continue;
+    if (!looksLikeCredentialRead(content, lower, match.index)) continue;
     findings.push({
       severity: "high",
       category: "credential-access",
       file: file.path,
-      snippet: clipAround(file.content, index),
+      snippet: clipAround(file.content, match.index),
       rationale:
-        "Package reads (or constructs a path to) a credential / wallet / key store in proximity to a filesystem read primitive."
+        `Reads or references ${target.label} near a filesystem read primitive.`
     });
     return;
   }

package/src/diff.js

@@ -0,0 +1,281 @@
+"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"
+    };
+  }
+
+  const extraInNpm = [];
+  const mismatched = [];
+  const matched = [];
+
+  for (const [rel, npmEntry] of npmTree.entries()) {
+    if (isAlwaysIgnored(rel)) continue;
+    const ghEntry = ghTree.get(rel);
+    if (!ghEntry) {
+      // Files in the npm tarball but NOT in the github repo at the matching
+      // ref. If the package has a build script, root-level JS at non-source
+      // paths is probably bundled / generated and we can't reliably catch
+      // tampering there — demote to silent. We DO still surface extras in
+      // paths that look like source trees (`src/`, `lib/`, `tests/`,
+      // `scripts/`) since those should be 1:1 even with a build step.
+      const inLikelySourceDir = /^(?:src|tests?|scripts|spec)\//.test(rel);
+      const category = isBuildOutput(rel)
+        ? hasBuildScript ? "expected-build-output" : "extra-build-output"
+        : isSourceFile(rel)
+          ? hasBuildScript && !inLikelySourceDir
+            ? "expected-build-output"
+            : "extra-source"
+          : "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");
@@ -160,7 +163,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" &&
+    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,6 +173,53 @@ 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") {
@@ -158,6 +235,10 @@ async function stageReference(reference, stagedPath, options) {
     return resolveNpmPackage(parsed.specifier, options);
   }
 
+  if (parsed.type === "github") {
+    return resolveGithubRepo(parsed, options);
+  }
+
   throw new Error(`Unsupported reference type: ${reference}`);
 }
 
@@ -170,6 +251,21 @@ function parseReference(reference) {
     return { type: "local", path: path.resolve(reference.slice("file:".length)) };
   }
 
+  if (reference.startsWith("github:")) {
+    return parseGithubReference(reference.slice("github:".length));
+  }
+
+  // github.com URLs as a convenience shorthand
+  const ghMatch = reference.match(/^https?:\/\/github\.com\/([^/]+)\/([^/?#]+?)(?:\.git)?(?:#(.+))?$/);
+  if (ghMatch) {
+    return {
+      type: "github",
+      owner: ghMatch[1],
+      repo: ghMatch[2],
+      ref: ghMatch[3] || null
+    };
+  }
+
   if (
     reference.startsWith(".") ||
     reference.startsWith("/") ||
@@ -184,6 +280,62 @@ function parseReference(reference) {
   return { type: "npm", specifier: reference };
 }
 
+function parseGithubReference(spec) {
+  // Supports owner/repo[#ref] and owner/repo[@ref]
+  const match = spec.match(/^([^/#@]+)\/([^/#@]+?)(?:[#@](.+))?$/);
+  if (!match) throw new Error(`Invalid github reference: github:${spec}`);
+  return {
+    type: "github",
+    owner: match[1],
+    repo: match[2].replace(/\.git$/, ""),
+    ref: match[3] || null
+  };
+}
+
+async function resolveGithubRepo(parsed, options) {
+  // Resolve default branch if no ref pinned. Uses the existing GitHub metadata
+  // helper which is already cached + parallel-safe.
+  const { fetchRepoMetadata } = require("./github");
+  let ref = parsed.ref;
+  let resolvedMeta = null;
+  if (!ref) {
+    const meta = await fetchRepoMetadata(`https://github.com/${parsed.owner}/${parsed.repo}`).catch(() => null);
+    if (meta && meta.found === false && meta.reason === "not-found") {
+      throw new Error(`GitHub repository not found: ${parsed.owner}/${parsed.repo}`);
+    }
+    if (meta && meta.found) {
+      ref = meta.default_branch || "HEAD";
+      resolvedMeta = meta;
+    } else {
+      ref = "HEAD";
+    }
+  }
+
+  // GitHub's "codeload" endpoint returns a .tar.gz of the repo at the given
+  // ref. Works for branch names, tags, and commit SHAs.
+  const tarballUrl = `https://codeload.github.com/${parsed.owner}/${parsed.repo}/tar.gz/${encodeURIComponent(ref)}`;
+
+  return {
+    type: "github",
+    owner: parsed.owner,
+    repo: parsed.repo,
+    ref,
+    needsDownload: true,
+    tarballUrl,
+    packageName: `${parsed.owner}/${parsed.repo}`,
+    githubArchive: true,
+    npmMetadata: resolvedMeta
+      ? {
+          // Synthetic shape so the downstream auditor still sees a repository
+          // URL and the github cross-check finds the same data we already have.
+          name: parsed.repo,
+          repository: { url: resolvedMeta.html_url, type: "git" },
+          maintainers: []
+        }
+      : null
+  };
+}
+
 async function copyLocalPath(sourcePath, stagedPath) {
   const stat = await fsp.stat(sourcePath);
   if (!stat.isDirectory()) {