pqcheck 0.5.0 → 0.7.0

package/bin/pqcheck.js

@@ -7,7 +7,7 @@
 // =============================================================================
 
 const API_BASE = process.env.PQCHECK_API_BASE || "https://quantapact.com";
-const VERSION = "0.5.0";
+const VERSION = "0.7.0";
 
 const ANSI = {
   reset:   "\x1b[0m",
@@ -34,15 +34,45 @@ async function main() {
     process.exit(0);
   }
 
-  // Subcommand dispatch — currently only "lock" (QXM artifact generator).
-  // Anything else is treated as the default scan command.
+  // Subcommand dispatch.
   if (args[0] === "lock") {
     return runLockCommand(args.slice(1));
   }
+  if (args[0] === "deps") {
+    return runDepsCommand(args.slice(1));
+  }
+  if (args[0] === "diff") {
+    return runDiffCommand(args.slice(1));
+  }
+  if (args[0] === "history") {
+    return runHistoryCommand(args.slice(1));
+  }
+  if (args[0] === "cert") {
+    return runCertCommand(args.slice(1));
+  }
+
+  // Multi-domain support: positional args are domains.
+  // --file reads additional domains from a newline-delimited file.
+  const fileFlagIdx = args.indexOf("--file");
+  let fileDomains = [];
+  if (fileFlagIdx >= 0) {
+    const filePath = args[fileFlagIdx + 1];
+    if (!filePath) {
+      console.error(color("red", "error: --file requires a path argument"));
+      process.exit(1);
+    }
+    try {
+      const fs = await import("node:fs/promises");
+      const raw = await fs.readFile(filePath, "utf8");
+      fileDomains = raw.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+    } catch (err) {
+      console.error(color("red", `error reading --file ${filePath}: ${err.message}`));
+      process.exit(1);
+    }
+  }
 
-  // Multi-domain support: any non-flag positional arg is a domain
   const positional = args.filter((a) => !a.startsWith("-") && !isFlagValue(args, a));
-  const domains = positional
+  const domains = [...positional, ...fileDomains]
     .map((a) => normalizeDomain(a))
     .filter((d) => !!d);
 
@@ -138,6 +168,10 @@ async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi
     printCsvRow(report);
   } else if (format === "markdown") {
     printMarkdown(report, multi);
+  } else if (format === "sarif") {
+    console.log(JSON.stringify(reportToSarif(report), null, 2));
+  } else if (format === "gh-action") {
+    printGitHubActionAnnotations(report);
   } else {
     if (multi) console.log(color("dim", `\n──── ${domain} ────`));
     printReport(report);
@@ -226,15 +260,18 @@ function isFlagValue(args, val) {
   const idx = args.indexOf(val);
   if (idx <= 0) return false;
   const prev = args[idx - 1];
-  return prev === "--threshold" || prev === "--format" || prev === "--watch" || prev === "--webhook";
+  return prev === "--threshold" || prev === "--format" || prev === "--watch" || prev === "--webhook" || prev === "--file" || prev === "-o" || prev === "--allowlist";
 }
 
 function parseFormat(args) {
   if (args.includes("--json")) return "json"; // back-compat alias
+  if (args.includes("--gh-action")) return "gh-action"; // GitHub Actions annotation format
   const i = args.indexOf("--format");
   if (i === -1) return "text";
   const v = (args[i + 1] || "").toLowerCase();
-  if (v === "json" || v === "csv" || v === "markdown" || v === "md") return v === "md" ? "markdown" : v;
+  if (v === "json" || v === "csv" || v === "markdown" || v === "md" || v === "sarif" || v === "gh-action") {
+    return v === "md" ? "markdown" : v;
+  }
   return "text";
 }
 
@@ -464,6 +501,7 @@ Public Surface Blast Radius — quantum-decryption risk for any domain.
 ${color("bold", "Usage:")}
   npx pqcheck <domain>                          Scan + print human-readable report
   npx pqcheck lock <domain>                     Generate quantapact.lock (QXM) for repo commit
+  npx pqcheck deps <domain>                     Scan third-party origins (supply-chain HNDL); --lock for committable manifest
   npx pqcheck a.com b.com c.com                 Multi-domain scan
   npx pqcheck <domain> --format json            Raw JSON
   npx pqcheck <domain> --format markdown        GitHub-issue / Slack-ready Markdown
@@ -739,6 +777,671 @@ function renderQxmMarkdown(m) {
   return lines.join("\n");
 }
 
+// =============================================================================
+// `pqcheck deps` — supply-chain HNDL scan for a target domain
+// =============================================================================
+// Fetches the public HTML of the target domain, extracts third-party origins
+// referenced via <script src>, <iframe src>, <link href>, <img src>, then runs
+// /api/scan against each unique third party. Outputs a sorted summary + an
+// optional committable lockfile (quantapact-deps.lock).
+//
+// Parallel to the browser extension's Dependencies tab, exposed as a CLI for
+// CI integration: gate PR builds on third-party crypto posture.
+//
+// Usage:
+//   npx pqcheck deps <domain>           Scan + print summary table
+//   npx pqcheck deps <domain> --json    JSON output (pipe to jq, etc.)
+//   npx pqcheck deps <domain> --lock    Also write quantapact-deps.lock + .md
+//   npx pqcheck deps <domain> -o dir/   Output directory for --lock files
+//   npx pqcheck deps <domain> --max=20  Cap on third parties scanned (default 20)
+// =============================================================================
+
+async function runDepsCommand(args) {
+  const fs = await import("node:fs/promises");
+  const path = await import("node:path");
+
+  const json = args.includes("--json");
+  const lock = args.includes("--lock");
+  const outIdx = args.indexOf("-o");
+  const outDir = outIdx >= 0 ? args[outIdx + 1] : ".";
+  const maxArg = args.find((a) => a.startsWith("--max="));
+  const maxThirdParties = maxArg ? Math.max(1, parseInt(maxArg.slice(6), 10) || 20) : 20;
+
+  // Allowlist support: --allowlist <path> reads newline-separated host patterns.
+  // If a third-party host is NOT in the allowlist, the scan exits non-zero with code 3.
+  // Useful as a CI gate for vendor-risk teams: "fail PR if any unapproved third-party appears."
+  const allowlistIdx = args.indexOf("--allowlist");
+  let allowlist = null;
+  if (allowlistIdx >= 0) {
+    const allowlistPath = args[allowlistIdx + 1];
+    try {
+      const fs2 = await import("node:fs/promises");
+      const raw = await fs2.readFile(allowlistPath, "utf8");
+      allowlist = new Set(raw.split(/\r?\n/).map(l => l.trim().toLowerCase()).filter(l => l && !l.startsWith("#")));
+    } catch (err) {
+      console.error(color("red", `error reading --allowlist: ${err.message}`));
+      process.exit(1);
+    }
+  }
+
+  const positional = args.filter((a) => !a.startsWith("-") && a !== outDir);
+  const domain = positional.length > 0 ? normalizeDomain(positional[0]) : null;
+  if (!domain || !isValidDomain(domain)) {
+    console.error(color("red", "error: pqcheck deps requires a valid domain"));
+    console.error(color("dim", "Usage: npx pqcheck deps <domain> [--json|--lock] [-o dir/] [--max=N]"));
+    process.exit(1);
+  }
+
+  if (!json) process.stderr.write(color("dim", `Fetching ${domain} HTML...`));
+  const html = await fetchPageHTML(domain);
+  if (!json) process.stderr.write("\r\x1b[K");
+  if (!html) {
+    console.error(color("red", `error: could not fetch https://${domain}/`));
+    process.exit(1);
+  }
+
+  const refs = extractThirdPartyRefs(html, domain);
+  if (refs.length === 0) {
+    if (json) {
+      console.log(JSON.stringify({ domain, scannedAt: new Date().toISOString(), thirdParties: [], summary: { uniqueOrigins: 0, totalReferences: 0 } }, null, 2));
+    } else {
+      console.log("");
+      console.log(`  ${color("violet", domain)} ${color("dim", "·")} ${color("bold", "no third-party origins detected")}`);
+      console.log(color("dim", "  (page is fully first-party, or HTML didn't load script/iframe/link refs)"));
+      console.log("");
+    }
+    return;
+  }
+
+  // Group by host, dedupe
+  const byHost = new Map();
+  for (const r of refs) {
+    if (!byHost.has(r.host)) byHost.set(r.host, { host: r.host, types: new Set(), occurrences: 0 });
+    const e = byHost.get(r.host);
+    e.types.add(r.type);
+    e.occurrences += 1;
+  }
+  const uniqueHosts = Array.from(byHost.values()).slice(0, maxThirdParties);
+
+  if (!json) process.stderr.write(color("dim", `Scanning ${uniqueHosts.length} third-party origins...`));
+
+  // Scan each host (parallel batches of 4 to avoid hammering the API)
+  const BATCH = 4;
+  const results = [];
+  for (let i = 0; i < uniqueHosts.length; i += BATCH) {
+    const batch = uniqueHosts.slice(i, i + BATCH);
+    const batchResults = await Promise.all(
+      batch.map(async (h) => {
+        try {
+          const r = await fetch(`${API_BASE}/api/scan?domain=${encodeURIComponent(h.host)}&source=cli-deps`, {
+            headers: { accept: "application/json", "user-agent": `pqcheck-cli/${VERSION} (deps)` },
+          });
+          if (!r.ok) return { ...h, types: Array.from(h.types), scan: null, error: `${r.status}` };
+          const body = await r.json();
+          return {
+            ...h,
+            types: Array.from(h.types),
+            scan: {
+              grade: body.grade,
+              score: body.score,
+              reachable: body.reachable,
+              hybridPQC: body.publicSurface?.hybridPQC ?? false,
+            },
+          };
+        } catch (e) {
+          return { ...h, types: Array.from(h.types), scan: null, error: e.message };
+        }
+      })
+    );
+    results.push(...batchResults);
+  }
+  if (!json) process.stderr.write("\r\x1b[K");
+
+  // Sort: F first (worst), then D, C, B, A; unreachable/error to bottom
+  const gradeRank = { F: 5, D: 4, C: 3, B: 2, A: 1 };
+  results.sort((a, b) => {
+    const ar = a.scan?.grade ? gradeRank[a.scan.grade] || 0 : -1;
+    const br = b.scan?.grade ? gradeRank[b.scan.grade] || 0 : -1;
+    return br - ar;
+  });
+
+  const summary = buildDepsSummary(results);
+
+  // Build manifest
+  const manifest = {
+    $schema: "https://quantapact.com/schemas/deps/v1",
+    schemaVersion: "1.0",
+    domain,
+    scannedAt: new Date().toISOString(),
+    tool: "pqcheck-cli",
+    toolVersion: VERSION,
+    summary,
+    thirdParties: results.map((r) => ({
+      host: r.host,
+      types: r.types,
+      occurrences: r.occurrences,
+      scan: r.scan,
+      error: r.error,
+    })),
+    evidence: {
+      methodology: `${API_BASE}/methodology/browser-extension`,
+      reportLink: `${API_BASE}/r/${domain}`,
+    },
+  };
+
+  if (json) {
+    console.log(JSON.stringify(manifest, null, 2));
+    return;
+  }
+
+  // Pretty terminal table
+  console.log("");
+  console.log(`  ${color("bold", "Supply-chain HNDL exposure")} for ${color("violet", domain)}`);
+  console.log(`  ${color("dim", `${summary.uniqueOrigins} unique third-party origins · ${summary.totalReferences} references · weakest: ${summary.weakestLink?.host ?? "—"} (${summary.weakestLink?.grade ?? "—"})`)}`);
+  console.log("");
+  console.log(`  ${color("dim", "GRADE  HOST                                          PQC  TYPES")}`);
+  console.log(`  ${color("dim", "─────  ─────────────────────────────────────────  ───  ─────")}`);
+  for (const r of results) {
+    const gradeStr = r.scan?.grade ?? "?";
+    const gradeColored = gradeStr === "A" ? color("green", gradeStr) : gradeStr === "F" || gradeStr === "D" ? color("red", gradeStr) : color("yellow", gradeStr);
+    const host = r.host.length > 41 ? r.host.slice(0, 40) + "…" : r.host.padEnd(41, " ");
+    const pqc = r.scan?.hybridPQC ? color("green", "yes") : color("dim", "no ");
+    const types = r.types.join(",");
+    console.log(`  ${gradeColored.padEnd(8, " ")}  ${host}  ${pqc}  ${color("dim", types)}`);
+  }
+  console.log("");
+  console.log(`  ${color("dim", "Each row scanned via")} ${color("violet", "/api/scan")}${color("dim", " · /methodology/browser-extension explains scoring")}`);
+  console.log("");
+
+  if (lock) {
+    const lockPath = path.join(outDir, "quantapact-deps.lock");
+    const mdPath = path.join(outDir, "quantapact-deps-report.md");
+    try {
+      await fs.mkdir(outDir, { recursive: true });
+      await fs.writeFile(lockPath, JSON.stringify(manifest, null, 2));
+      await fs.writeFile(mdPath, depsManifestToMarkdown(manifest));
+      console.log(`  ${color("bold", "Wrote")} ${color("violet", lockPath)} ${color("dim", "and")} ${color("violet", mdPath)}`);
+      console.log(`  ${color("dim", "Commit these to track third-party crypto posture changes in PR diffs.")}`);
+      console.log("");
+    } catch (err) {
+      console.error(color("red", `error writing lockfile: ${err.message}`));
+      process.exit(1);
+    }
+  }
+
+  // Allowlist gate: exit non-zero if any third-party host isn't in the allowlist.
+  if (allowlist) {
+    const violations = results.filter(r => !allowlist.has(r.host));
+    if (violations.length > 0) {
+      if (!json) {
+        console.error("");
+        console.error(color("red", `  ✗ Allowlist violation: ${violations.length} third-party origin(s) not in allowlist:`));
+        for (const v of violations) console.error(`    - ${v.host}`);
+        console.error("");
+      }
+      process.exit(3);
+    } else if (!json) {
+      console.log(`  ${color("green", "✓")} ${color("dim", "All third-party origins on allowlist.")}`);
+      console.log("");
+    }
+  }
+}
+
+async function fetchPageHTML(domain) {
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 8000);
+    const resp = await fetch(`https://${domain}/`, {
+      method: "GET",
+      redirect: "follow",
+      signal: ctrl.signal,
+      headers: { "User-Agent": `pqcheck-cli/${VERSION} (deps; +https://quantapact.com)` },
+    });
+    clearTimeout(t);
+    if (!resp.ok) return null;
+    return await resp.text();
+  } catch {
+    return null;
+  }
+}
+
+function extractThirdPartyRefs(html, targetDomain) {
+  const out = [];
+  // Patterns: <tag ... attr="..."> — non-greedy, single or double quoted
+  const patterns = [
+    { type: "script", re: /<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi },
+    { type: "iframe", re: /<iframe\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi },
+    { type: "link",   re: /<link\b[^>]*\bhref\s*=\s*["']([^"']+)["']/gi },
+    { type: "img",    re: /<img\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi },
+  ];
+  const targetRoot = registeredDomain(targetDomain);
+  for (const { type, re } of patterns) {
+    let m;
+    while ((m = re.exec(html)) !== null) {
+      try {
+        const u = new URL(m[1], `https://${targetDomain}`);
+        if (u.protocol !== "http:" && u.protocol !== "https:") continue;
+        const host = u.hostname.toLowerCase();
+        if (!host || host === targetDomain || registeredDomain(host) === targetRoot) continue;
+        out.push({ host, type });
+      } catch { /* relative URL or malformed */ }
+    }
+  }
+  return out;
+}
+
+// Cheap registered-domain helper — covers common 2-label TLDs (co.uk, com.au, etc.)
+function registeredDomain(host) {
+  const parts = host.split(".");
+  if (parts.length <= 2) return host;
+  const last2 = parts.slice(-2).join(".");
+  const doubleTLDs = new Set([
+    "co.uk", "co.jp", "co.nz", "co.za", "com.au", "com.br", "com.cn", "com.mx",
+    "com.tr", "ne.jp", "ac.uk", "gov.uk", "org.uk", "edu.au", "gov.au",
+  ]);
+  if (doubleTLDs.has(last2)) return parts.slice(-3).join(".");
+  return last2;
+}
+
+function buildDepsSummary(results) {
+  const byGrade = { A: 0, B: 0, C: 0, D: 0, F: 0, "?": 0 };
+  let totalRefs = 0;
+  let scoreSum = 0;
+  let scoreN = 0;
+  let pqcCount = 0;
+  let weakest = null;
+  for (const r of results) {
+    totalRefs += r.occurrences;
+    const g = r.scan?.grade ?? "?";
+    byGrade[g] = (byGrade[g] || 0) + 1;
+    if (typeof r.scan?.score === "number") {
+      scoreSum += r.scan.score;
+      scoreN += 1;
+      if (!weakest || r.scan.score > weakest.score) {
+        weakest = { host: r.host, grade: r.scan.grade, score: r.scan.score };
+      }
+    }
+    if (r.scan?.hybridPQC) pqcCount += 1;
+  }
+  return {
+    uniqueOrigins: results.length,
+    totalReferences: totalRefs,
+    byGrade,
+    averageScore: scoreN > 0 ? Math.round((scoreSum / scoreN) * 10) / 10 : null,
+    hybridPQCCount: pqcCount,
+    weakestLink: weakest,
+  };
+}
+
+function depsManifestToMarkdown(m) {
+  const lines = [];
+  lines.push(`# Supply-chain HNDL exposure: ${m.domain}`);
+  lines.push("");
+  lines.push(`Scanned at \`${m.scannedAt}\` by \`${m.tool}@${m.toolVersion}\`.`);
+  lines.push("");
+  lines.push("## Summary");
+  lines.push("");
+  lines.push(`- **Unique third-party origins:** ${m.summary.uniqueOrigins}`);
+  lines.push(`- **Total references:** ${m.summary.totalReferences}`);
+  lines.push(`- **Average HNDL score:** ${m.summary.averageScore ?? "—"} / 10`);
+  lines.push(`- **Hybrid-PQC origins:** ${m.summary.hybridPQCCount} / ${m.summary.uniqueOrigins}`);
+  if (m.summary.weakestLink) {
+    lines.push(`- **Weakest link:** \`${m.summary.weakestLink.host}\` — grade ${m.summary.weakestLink.grade}, score ${m.summary.weakestLink.score}`);
+  }
+  lines.push("");
+  lines.push("## Grade distribution");
+  lines.push("");
+  lines.push("| Grade | Count |");
+  lines.push("|---|---|");
+  for (const g of ["A", "B", "C", "D", "F", "?"]) {
+    if ((m.summary.byGrade[g] || 0) > 0) lines.push(`| ${g} | ${m.summary.byGrade[g]} |`);
+  }
+  lines.push("");
+  lines.push("## Third parties");
+  lines.push("");
+  lines.push("| Grade | Host | PQC | Types | Occurrences |");
+  lines.push("|---|---|---|---|---|");
+  for (const tp of m.thirdParties) {
+    const grade = tp.scan?.grade ?? "?";
+    const pqc = tp.scan?.hybridPQC ? "yes" : "no";
+    lines.push(`| ${grade} | \`${tp.host}\` | ${pqc} | ${tp.types.join(", ")} | ${tp.occurrences} |`);
+  }
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push("*Methodology: [/methodology/browser-extension](" + m.evidence.methodology + "). Re-run `npx pqcheck deps " + m.domain + " --lock` to refresh; commit the lockfile to track changes in pull requests.*");
+  lines.push("");
+  return lines.join("\n");
+}
+
+// =============================================================================
+// SARIF + GitHub Action output formats
+// =============================================================================
+
+function reportToSarif(report) {
+  // SARIF 2.1.0 minimal schema for security findings.
+  // Spec: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+  const findings = Array.isArray(report.findings) ? report.findings : [];
+  const sevMap = { critical: "error", high: "error", medium: "warning", low: "note" };
+  return {
+    $schema: "https://docs.oasis-open.org/sarif/sarif/v2.1.0/cos02/schemas/sarif-schema-2.1.0.json",
+    version: "2.1.0",
+    runs: [{
+      tool: {
+        driver: {
+          name: "pqcheck",
+          version: VERSION,
+          informationUri: "https://quantapact.com",
+          rules: findings.map((f, i) => ({
+            id: `pqcheck-${i + 1}`,
+            name: (f.title || "finding").replace(/[^A-Za-z0-9]/g, "_"),
+            shortDescription: { text: f.title || "finding" },
+            fullDescription: { text: f.detail || f.title || "finding" },
+            defaultConfiguration: { level: sevMap[f.severity] || "note" },
+          })),
+        },
+      },
+      results: findings.map((f, i) => ({
+        ruleId: `pqcheck-${i + 1}`,
+        level: sevMap[f.severity] || "note",
+        message: { text: `${f.title || "finding"}${f.detail ? ` — ${f.detail}` : ""}` },
+        locations: [{
+          physicalLocation: {
+            artifactLocation: { uri: `https://${report.domain || ""}` },
+          },
+        }],
+        properties: {
+          domain: report.domain,
+          score: report.score,
+          grade: report.grade,
+          severity: f.severity,
+        },
+      })),
+      properties: {
+        score: report.score,
+        grade: report.grade,
+        domain: report.domain,
+      },
+    }],
+  };
+}
+
+function printGitHubActionAnnotations(report) {
+  // GitHub Actions workflow command syntax: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+  const findings = Array.isArray(report.findings) ? report.findings : [];
+  const sevMap = { critical: "error", high: "error", medium: "warning", low: "notice" };
+  // Top-line score/grade as a notice
+  console.log(`::notice title=Quantapact: ${report.domain}::Grade ${report.grade || "?"} · score ${report.score ?? "?"} / 10`);
+  for (const f of findings) {
+    const cmd = sevMap[f.severity] || "notice";
+    const title = (f.title || "finding").replace(/[\r\n]/g, " ");
+    const msg = (f.detail || f.title || "").replace(/[\r\n]/g, " ").replace(/::/g, ":");
+    console.log(`::${cmd} title=${title}::${msg}`);
+  }
+}
+
+// =============================================================================
+// `pqcheck history` — show recent score history for a domain
+// =============================================================================
+
+async function runHistoryCommand(args) {
+  const json = args.includes("--json");
+  const positional = args.filter((a) => !a.startsWith("-"));
+  const domain = positional.length > 0 ? normalizeDomain(positional[0]) : null;
+  if (!domain || !isValidDomain(domain)) {
+    console.error(color("red", "error: pqcheck history requires a valid domain"));
+    console.error(color("dim", "Usage: npx pqcheck history <domain> [--json]"));
+    process.exit(1);
+  }
+  const days = (() => {
+    const i = args.indexOf("--days");
+    if (i === -1) return 90;
+    const n = parseInt(args[i + 1] || "90", 10);
+    return Number.isFinite(n) && n > 0 && n <= 365 ? n : 90;
+  })();
+
+  let h;
+  try {
+    const r = await fetch(`${API_BASE}/api/history?domain=${encodeURIComponent(domain)}&days=${days}`, {
+      headers: { accept: "application/json", "user-agent": `pqcheck-cli/${VERSION} (history)` },
+    });
+    if (!r.ok) {
+      console.error(color("red", `error: ${r.status} ${r.statusText}`));
+      process.exit(1);
+    }
+    h = await r.json();
+  } catch (err) {
+    console.error(color("red", `error: ${err.message}`));
+    process.exit(1);
+  }
+
+  if (json) {
+    console.log(JSON.stringify(h, null, 2));
+    return;
+  }
+
+  const points = Array.isArray(h?.points) ? h.points : [];
+  if (points.length === 0) {
+    console.log(`  ${color("violet", domain)} ${color("dim", "·")} no history found`);
+    console.log(color("dim", "  (need at least one previous scan; try `npx pqcheck " + domain + "` first)"));
+    return;
+  }
+  const sorted = points.slice().reverse(); // oldest → newest
+  const first = sorted[0].score;
+  const last = sorted[sorted.length - 1].score;
+  const delta = last - first;
+  const min = Math.min(...sorted.map(p => p.score));
+  const max = Math.max(...sorted.map(p => p.score));
+  const trend = Math.abs(delta) < 0.1 ? "→ flat" : delta > 0 ? `↑ +${delta.toFixed(1)} (worsened)` : `↓ ${delta.toFixed(1)} (improved)`;
+
+  console.log("");
+  console.log(`  ${color("bold", domain)} ${color("dim", "·")} score history (${days}d, ${sorted.length} samples)`);
+  console.log(`  ${color("dim", `range ${min.toFixed(1)} – ${max.toFixed(1)} · trend ${trend}`)}`);
+  console.log("");
+  // Compact ASCII sparkline
+  const range = Math.max(0.1, max - min);
+  const ramp = "▁▂▃▄▅▆▇█";
+  let bar = "";
+  for (const p of sorted) {
+    const idx = Math.min(ramp.length - 1, Math.floor(((p.score - min) / range) * (ramp.length - 1)));
+    bar += ramp[idx];
+  }
+  console.log(`  ${color("violet", bar)}`);
+  console.log("");
+  // Tail of recent samples
+  console.log(`  ${color("dim", "Recent samples (most-recent first):")}`);
+  for (const p of points.slice(0, 8)) {
+    const date = (p.scannedAt || p.date || "").slice(0, 10);
+    console.log(`    ${color("dim", date)}  score ${color("bold", p.score?.toFixed(1) ?? "?")}  grade ${p.grade ?? "?"}`);
+  }
+  console.log("");
+}
+
+// =============================================================================
+// `pqcheck diff` — diff two QXM lockfiles
+// =============================================================================
+
+async function runDiffCommand(args) {
+  const fs = await import("node:fs/promises");
+  const json = args.includes("--json");
+  const positional = args.filter((a) => !a.startsWith("-"));
+  if (positional.length !== 2) {
+    console.error(color("red", "error: pqcheck diff requires two lockfile paths"));
+    console.error(color("dim", "Usage: npx pqcheck diff old.lock new.lock [--json]"));
+    process.exit(1);
+  }
+  let oldLock, newLock;
+  try {
+    oldLock = JSON.parse(await fs.readFile(positional[0], "utf8"));
+    newLock = JSON.parse(await fs.readFile(positional[1], "utf8"));
+  } catch (err) {
+    console.error(color("red", `error reading lockfile: ${err.message}`));
+    process.exit(1);
+  }
+
+  const diff = computeLockDiff(oldLock, newLock);
+  if (json) {
+    console.log(JSON.stringify(diff, null, 2));
+    process.exit(diff.regressed ? 2 : 0);
+  }
+
+  console.log("");
+  console.log(`  ${color("bold", "Quantapact lockfile diff")}`);
+  console.log(`  ${color("dim", `${positional[0]} → ${positional[1]}`)}`);
+  console.log("");
+  if (diff.scoreChange !== null) {
+    const arrow = diff.scoreChange > 0 ? color("red", "↑") : diff.scoreChange < 0 ? color("green", "↓") : color("dim", "→");
+    const direction = diff.scoreChange > 0 ? "worsened" : diff.scoreChange < 0 ? "improved" : "unchanged";
+    console.log(`  Score: ${color("bold", diff.oldScore?.toFixed(1) ?? "?")} → ${color("bold", diff.newScore?.toFixed(1) ?? "?")} ${arrow} ${diff.scoreChange.toFixed(1)} (${direction})`);
+  }
+  if (diff.gradeChange) {
+    const colored = diff.regressed ? color("red", diff.newGrade) : color("green", diff.newGrade);
+    console.log(`  Grade: ${diff.oldGrade ?? "?"} → ${colored}`);
+  }
+  if (diff.componentChanges?.length > 0) {
+    console.log("");
+    console.log(`  ${color("dim", "Component changes:")}`);
+    for (const c of diff.componentChanges) {
+      const arrow = c.change > 0 ? color("red", "↑") : color("green", "↓");
+      console.log(`    ${c.name.padEnd(20, " ")} ${c.before?.toFixed(2) ?? "?"} → ${c.after?.toFixed(2) ?? "?"}  ${arrow} ${Math.abs(c.change).toFixed(2)}`);
+    }
+  }
+  if (diff.findingsAdded?.length > 0) {
+    console.log("");
+    console.log(`  ${color("red", "+ New findings:")}`);
+    for (const f of diff.findingsAdded) console.log(`    [${f.severity}] ${f.title}`);
+  }
+  if (diff.findingsResolved?.length > 0) {
+    console.log("");
+    console.log(`  ${color("green", "- Resolved findings:")}`);
+    for (const f of diff.findingsResolved) console.log(`    [${f.severity}] ${f.title}`);
+  }
+  console.log("");
+  process.exit(diff.regressed ? 2 : 0);
+}
+
+function computeLockDiff(oldLock, newLock) {
+  const oldScore = typeof oldLock?.score === "number" ? oldLock.score : oldLock?.summary?.score;
+  const newScore = typeof newLock?.score === "number" ? newLock.score : newLock?.summary?.score;
+  const oldGrade = oldLock?.grade || oldLock?.summary?.grade;
+  const newGrade = newLock?.grade || newLock?.summary?.grade;
+  const scoreChange = (typeof oldScore === "number" && typeof newScore === "number") ? Math.round((newScore - oldScore) * 100) / 100 : null;
+  const componentChanges = [];
+  const oldComp = oldLock?.components || {};
+  const newComp = newLock?.components || {};
+  for (const k of Object.keys({ ...oldComp, ...newComp })) {
+    const before = typeof oldComp[k]?.contribution === "number" ? oldComp[k].contribution : null;
+    const after = typeof newComp[k]?.contribution === "number" ? newComp[k].contribution : null;
+    if (before !== null && after !== null && Math.abs(after - before) >= 0.05) {
+      componentChanges.push({ name: k, before, after, change: Math.round((after - before) * 100) / 100 });
+    }
+  }
+  // Findings comparison by title
+  const oldFindings = Array.isArray(oldLock?.findings) ? oldLock.findings : [];
+  const newFindings = Array.isArray(newLock?.findings) ? newLock.findings : [];
+  const oldTitles = new Set(oldFindings.map(f => f.title));
+  const newTitles = new Set(newFindings.map(f => f.title));
+  const findingsAdded = newFindings.filter(f => !oldTitles.has(f.title));
+  const findingsResolved = oldFindings.filter(f => !newTitles.has(f.title));
+  const regressed = (typeof scoreChange === "number" && scoreChange > 0.1) || findingsAdded.some(f => f.severity === "high" || f.severity === "critical");
+  return {
+    oldScore, newScore, oldGrade, newGrade, scoreChange,
+    gradeChange: oldGrade !== newGrade,
+    componentChanges,
+    findingsAdded, findingsResolved,
+    regressed,
+  };
+}
+
+// =============================================================================
+// `pqcheck cert <pem-file>` — analyze a local cert file (offline)
+// =============================================================================
+
+async function runCertCommand(args) {
+  const fs = await import("node:fs/promises");
+  const crypto = await import("node:crypto");
+  const json = args.includes("--json");
+  const positional = args.filter((a) => !a.startsWith("-"));
+  if (positional.length === 0) {
+    console.error(color("red", "error: pqcheck cert requires a cert file path"));
+    console.error(color("dim", "Usage: npx pqcheck cert <path-to-pem-or-crt> [--json]"));
+    process.exit(1);
+  }
+
+  let pemData;
+  try {
+    pemData = await fs.readFile(positional[0], "utf8");
+  } catch (err) {
+    console.error(color("red", `error reading cert file: ${err.message}`));
+    process.exit(1);
+  }
+
+  let cert;
+  try {
+    cert = new crypto.X509Certificate(pemData);
+  } catch (err) {
+    console.error(color("red", `error parsing cert: ${err.message}`));
+    console.error(color("dim", "Expected a PEM-encoded X.509 cert (.pem, .crt, .cer)."));
+    process.exit(1);
+  }
+
+  const validFrom = new Date(cert.validFrom);
+  const validTo = new Date(cert.validTo);
+  const daysLeft = Math.round((validTo.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+  const sigAlg = (cert.publicKey?.asymmetricKeyType || "unknown").toUpperCase();
+  const keyBits = cert.publicKey?.asymmetricKeyDetails?.modulusLength || cert.publicKey?.asymmetricKeyDetails?.namedCurve || "?";
+  const sans = (cert.subjectAltName || "").split(",").map(s => s.trim()).filter(Boolean);
+  const isWildcard = sans.some(s => s.includes("*."));
+
+  // Quantum exposure assessment
+  let quantumNote;
+  if (sigAlg === "RSA" && Number(keyBits) >= 2048) {
+    quantumNote = "RSA-" + keyBits + " — broken by Shor's algorithm once a CRQC exists";
+  } else if (sigAlg === "EC" || sigAlg === "ECDSA") {
+    quantumNote = "ECDSA (" + keyBits + ") — broken by Shor's algorithm once a CRQC exists";
+  } else if (sigAlg === "ED25519") {
+    quantumNote = "Ed25519 — broken by Shor's algorithm once a CRQC exists";
+  } else {
+    quantumNote = sigAlg + " — quantum exposure unknown";
+  }
+
+  const result = {
+    file: positional[0],
+    subject: cert.subject,
+    issuer: cert.issuer,
+    serialNumber: cert.serialNumber,
+    validFrom: validFrom.toISOString(),
+    validTo: validTo.toISOString(),
+    daysUntilExpiry: daysLeft,
+    keyAlgorithm: sigAlg,
+    keyBits,
+    sans,
+    isWildcard,
+    isCA: cert.ca,
+    quantumExposure: quantumNote,
+  };
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log("");
+  console.log(`  ${color("bold", "Cert analysis")}: ${color("violet", positional[0])}`);
+  console.log("");
+  console.log(`  Subject:    ${cert.subject}`);
+  console.log(`  Issuer:     ${cert.issuer}`);
+  console.log(`  Valid:      ${validFrom.toISOString().slice(0, 10)} → ${validTo.toISOString().slice(0, 10)} (${daysLeft} days remaining)`);
+  console.log(`  Serial:     ${cert.serialNumber}`);
+  console.log(`  Key:        ${sigAlg}-${keyBits}`);
+  console.log(`  SANs (${sans.length}): ${sans.slice(0, 4).join(", ")}${sans.length > 4 ? ", ..." : ""}`);
+  console.log(`  Wildcard:   ${isWildcard ? "yes" : "no"}`);
+  console.log(`  CA cert:    ${cert.ca ? "yes" : "no"}`);
+  console.log("");
+  console.log(`  ${color("yellow", "Quantum exposure:")} ${quantumNote}`);
+  console.log("");
+}
+
 main().catch((err) => {
   console.error(color("red", `fatal: ${err.message}`));
   process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pqcheck",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Decryption Blast Radius scanner — find out how much of your data unlocks when quantum decryption arrives.",
   "keywords": [
     "post-quantum",