pqcheck 0.4.0 → 0.5.0

package/README.md

@@ -61,13 +61,41 @@ $ npx pqcheck chase.com
 
 ```
 npx pqcheck <domain>                      Scan and print human-readable report
+npx pqcheck lock <domain>                 Generate quantapact.lock (QXM artifact for repos)
 npx pqcheck <domain> --format json        Output raw JSON for piping / scripting
+npx pqcheck <domain> --format markdown    Output GitHub-issue / Slack-ready Markdown
 npx pqcheck <domain> --threshold 7        Exit 2 if score ≥ 7 (CI gate)
 npx pqcheck <domain> --quiet              Print only the numeric score
+npx pqcheck <domain> --watch [seconds]    Continuously poll and report changes
+npx pqcheck <domain> --webhook <url>      POST results to a URL on each scan
 npx pqcheck --help                        Show all options
 npx pqcheck --version                     Show version
 ```
 
+### QXM — Quantum Exposure Manifest (commit-able to your repo)
+
+Like SBOM, `package-lock.json`, or `cargo audit` outputs — track quantum exposure as a versioned artifact in your repo. Diffs surface real changes in pull requests.
+
+```bash
+npx pqcheck lock yourcompany.com
+# Writes:
+#   quantapact.lock          — stable JSON manifest
+#   quantapact-report.md     — human-readable summary (renders on GitHub)
+```
+
+Commit both files. Re-run `npx pqcheck lock` whenever you want to refresh; the diff in the next PR shows what changed (score, findings, key-reuse window).
+
+**In CI:**
+
+```yaml
+- name: Refresh QXM lockfile
+  run: npx pqcheck@latest lock yourcompany.com
+- name: Fail if score regressed
+  run: npx pqcheck@latest yourcompany.com --threshold 7
+```
+
+The lockfile schema is documented at [quantapact.com/schemas/qxm/v1](https://quantapact.com/methodology) and is intended to be stable across CLI versions.
+
 ### Exit codes
 
 | Code | Meaning |

package/bin/pqcheck.js

@@ -7,7 +7,7 @@
 // =============================================================================
 
 const API_BASE = process.env.PQCHECK_API_BASE || "https://quantapact.com";
-const VERSION = "0.4.0";
+const VERSION = "0.5.0";
 
 const ANSI = {
   reset:   "\x1b[0m",
@@ -34,6 +34,12 @@ async function main() {
     process.exit(0);
   }
 
+  // Subcommand dispatch — currently only "lock" (QXM artifact generator).
+  // Anything else is treated as the default scan command.
+  if (args[0] === "lock") {
+    return runLockCommand(args.slice(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
@@ -440,6 +446,11 @@ function normalizeDomain(raw) {
     .split(":")[0];
 }
 
+function isValidDomain(d) {
+  if (!d || d.length < 4 || d.length > 253) return false;
+  return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/.test(d);
+}
+
 async function safeJSON(resp) {
   try { return await resp.json(); } catch { return null; }
 }
@@ -452,6 +463,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 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
@@ -489,6 +501,244 @@ ${color("violet", "https://quantapact.com")}
 `);
 }
 
+// =============================================================================
+// `pqcheck lock` — QXM (Quantum Exposure Manifest) generator
+// =============================================================================
+// Generates two files committable to a git repo:
+//   quantapact.lock          — stable JSON manifest (machine-readable)
+//   quantapact-report.md     — human-readable summary (renders on GitHub)
+//
+// Like SBOM / package-lock.json / cargo audit / snyk test outputs — devs commit
+// these to track quantum exposure as a first-class technical concern.
+//
+// Usage:
+//   npx pqcheck lock <domain>           Write to ./quantapact.lock + .md
+//   npx pqcheck lock <domain> -o dir/   Write into a specific directory
+//   npx pqcheck lock <domain> --stdout  Print JSON to stdout (no files)
+//   npx pqcheck lock                    Read domain from existing
+//                                       quantapact.lock if present, else error
+// =============================================================================
+
+async function runLockCommand(args) {
+  const fs = await import("node:fs/promises");
+  const path = await import("node:path");
+  const crypto = await import("node:crypto");
+
+  const stdout = args.includes("--stdout");
+  const outIdx = args.indexOf("-o");
+  const outDir = outIdx >= 0 ? args[outIdx + 1] : ".";
+
+  // Find the domain — either positional arg, or read from existing lockfile
+  const positional = args.filter((a) => !a.startsWith("-") && a !== outDir);
+  let domain = positional.length > 0 ? normalizeDomain(positional[0]) : null;
+
+  if (!domain) {
+    try {
+      const existing = await fs.readFile(path.join(outDir, "quantapact.lock"), "utf8");
+      const parsed = JSON.parse(existing);
+      domain = parsed.domain;
+      if (!stdout) {
+        console.error(color("dim", `Re-locking from existing quantapact.lock (domain: ${domain})`));
+      }
+    } catch {
+      console.error(color("red", "error: no domain provided and no existing quantapact.lock found"));
+      console.error(color("dim", "Usage: npx pqcheck lock <domain>"));
+      process.exit(1);
+    }
+  }
+
+  if (!isValidDomain(domain)) {
+    console.error(color("red", `error: invalid domain '${domain}'`));
+    process.exit(1);
+  }
+
+  if (!stdout) process.stderr.write(color("dim", `Scanning ${domain} for QXM lockfile...`));
+
+  let report;
+  try {
+    const resp = await fetch(`${API_BASE}/api/scan?domain=${encodeURIComponent(domain)}`, {
+      method: "GET",
+      headers: { accept: "application/json", "user-agent": `pqcheck-cli/${VERSION} (lock)` },
+    });
+    if (!stdout) process.stderr.write("\r\x1b[K");
+    if (!resp.ok) {
+      const errBody = await safeJSON(resp);
+      console.error(color("red", `error: ${resp.status} ${errBody?.error || resp.statusText}`));
+      process.exit(1);
+    }
+    report = await resp.json();
+  } catch (err) {
+    if (!stdout) process.stderr.write("\r\x1b[K");
+    console.error(color("red", `error: ${err.message}`));
+    process.exit(1);
+  }
+
+  const manifest = buildQxmManifest(report, crypto);
+  const json = JSON.stringify(manifest, null, 2) + "\n";
+
+  if (stdout) {
+    console.log(json);
+    return;
+  }
+
+  // Write both files
+  const lockPath = path.join(outDir, "quantapact.lock");
+  const mdPath = path.join(outDir, "quantapact-report.md");
+  const md = renderQxmMarkdown(manifest);
+
+  try {
+    await fs.mkdir(outDir, { recursive: true });
+    await fs.writeFile(lockPath, json);
+    await fs.writeFile(mdPath, md);
+  } catch (err) {
+    console.error(color("red", `error writing files: ${err.message}`));
+    process.exit(1);
+  }
+
+  console.log("");
+  console.log(`  ${color("bold", "QXM lockfile written")} for ${color("violet", domain)}:`);
+  console.log("");
+  console.log(`  ${color("green", "✓")} ${lockPath}`);
+  console.log(`  ${color("green", "✓")} ${mdPath}`);
+  console.log("");
+  console.log(`  ${color("dim", "Decryption Blast Radius:")} ${color("bold", manifest.score + " / 10")} (Grade ${manifest.grade}, ${manifest.scoreLabel})`);
+  console.log(`  ${color("dim", "Findings:")} ${manifest.findings.length} (${manifest.findings.filter((f) => f.severity === "high" || f.severity === "critical").length} high/critical)`);
+  console.log("");
+  console.log(color("dim", "  Commit these to your repo to track quantum exposure as a versioned artifact."));
+  console.log(color("dim", "  Re-run `npx pqcheck lock` to refresh; diffs surface real changes in PRs."));
+  console.log("");
+  console.log(color("violet", `  → Verify online: ${API_BASE}/r/${encodeURIComponent(domain)}`));
+  console.log("");
+  process.exit(0);
+}
+
+function buildQxmManifest(report, crypto) {
+  // Stable hash of the underlying scan, useful for dedup + change detection in CI
+  const hashInput = JSON.stringify({
+    domain: report.domain,
+    score: report.score,
+    grade: report.grade,
+    findings: (report.findings || []).map((f) => ({ s: f.severity, t: f.title })),
+    publicSurface: report.publicSurface,
+  });
+  const evidenceHash = crypto.createHash("sha256").update(hashInput).digest("hex").slice(0, 32);
+
+  // Tessera recommendation classification (waitlist-shape; SDK not yet shipped)
+  const tesseraNeeded = (report.findings || []).some((f) =>
+    /key reused?|reused for|key persist|rsa fallback|chain weakest|hybrid pqc/i.test(f.title || ""),
+  );
+
+  return {
+    schema: "https://quantapact.com/schemas/qxm/v1",
+    schemaVersion: 1,
+    generator: `pqcheck-cli/${VERSION}`,
+    generatedAt: report.generatedAt || new Date().toISOString(),
+    domain: report.domain,
+    reachable: !!report.reachable,
+    score: report.score,
+    grade: report.grade,
+    scoreLabel: report.scoreLabel,
+    publicSurface: report.publicSurface || null,
+    findings: (report.findings || []).map((f) => ({
+      severity: f.severity,
+      title: f.title,
+      detail: f.detail,
+    })),
+    impact: report.impact || null,
+    sectorRanking: report.sectorRanking || null,
+    components: report.components || null,
+    evidence: {
+      evidenceHash,
+      methodology: "https://quantapact.com/methodology",
+      shareableReport: `https://quantapact.com/r/${encodeURIComponent(report.domain)}`,
+      badge: `https://quantapact.com/badge/${encodeURIComponent(report.domain)}.svg`,
+    },
+    remediation: {
+      tessera: tesseraNeeded ? "join-waitlist" : "not-needed",
+      tesseraWaitlist: "https://quantapact.com/feedback?source=qxm-tessera-interest",
+      notes: tesseraNeeded
+        ? "Findings include cryptographic exposure that Tessera SDK is being designed to remediate. Tessera is in development; join the waitlist to be notified when ready."
+        : "No quantum-decryption-relevant findings requiring Tessera remediation at this time.",
+    },
+  };
+}
+
+function renderQxmMarkdown(m) {
+  const lines = [];
+  lines.push(`# Quantum Exposure Manifest — \`${m.domain}\``);
+  lines.push("");
+  lines.push(`> **Decryption Blast Radius:** ${m.score} / 10 (Grade ${m.grade}, ${m.scoreLabel})`);
+  lines.push(`> Generated by [pqcheck](https://quantapact.com) at ${m.generatedAt}`);
+  lines.push("");
+  if (!m.reachable) {
+    lines.push(`*${m.domain} was not reachable at scan time.*`);
+    lines.push("");
+    return lines.join("\n");
+  }
+
+  lines.push("## Public-surface signals");
+  lines.push("");
+  lines.push("| Signal | Value |");
+  lines.push("|---|---|");
+  const ps = m.publicSurface || {};
+  lines.push(`| TLS version | ${ps.tlsVersion ?? "?"}${ps.cipher ? ` (${ps.cipher})` : ""} |`);
+  lines.push(`| Hybrid PQC | ${ps.hybridPQC ? "yes" : "no"} |`);
+  lines.push(`| Cert expires in | ${ps.daysUntilCertExpiry ?? "?"} days |`);
+  lines.push(`| HSTS | ${ps.hsts ? "enabled" : "not detected"} |`);
+  lines.push(`| Subdomains | ${ps.subdomainCount ?? 0}${ps.wildcardCert ? " (wildcard cert)" : ""} |`);
+  if (ps.keyReuseLongestYears) {
+    lines.push(`| **Key reuse window** | **${ps.keyReuseLongestYears} years** across ${ps.keyReuseCertsObserved ?? "?"} cert rotations |`);
+  }
+  lines.push("");
+
+  if (m.findings && m.findings.length) {
+    lines.push("## Findings");
+    lines.push("");
+    for (const f of m.findings) {
+      lines.push(`### \`[${f.severity.toUpperCase()}]\` ${f.title}`);
+      lines.push("");
+      lines.push(f.detail);
+      lines.push("");
+    }
+  }
+
+  if (m.impact && m.impact.headline) {
+    lines.push("## Plain-English impact");
+    lines.push("");
+    lines.push(`> ${m.impact.headline}`);
+    lines.push("");
+  }
+
+  if (m.sectorRanking && m.sectorRanking.available) {
+    lines.push("## Sector ranking");
+    lines.push("");
+    lines.push(`Among ${m.sectorRanking.sectorLabel}: **${m.sectorRanking.rank} of ${m.sectorRanking.total}** (worse than ${m.sectorRanking.betterThanCount} peers measured).`);
+    lines.push("");
+  }
+
+  lines.push("## Remediation");
+  lines.push("");
+  lines.push(`- **Tessera SDK status for this domain:** \`${m.remediation.tessera}\``);
+  lines.push(`- ${m.remediation.notes}`);
+  lines.push(`- [Join Tessera remediation waitlist](${m.remediation.tesseraWaitlist})`);
+  lines.push("");
+
+  lines.push("## Evidence");
+  lines.push("");
+  lines.push("| | |");
+  lines.push("|---|---|");
+  lines.push(`| Methodology | ${m.evidence.methodology} |`);
+  lines.push(`| Shareable report | ${m.evidence.shareableReport} |`);
+  lines.push(`| Embeddable badge | \`${m.evidence.badge}\` |`);
+  lines.push(`| Evidence hash | \`${m.evidence.evidenceHash}\` |`);
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push("*Public-surface measurements only. Internal Blast Radius (east-west traffic, internal databases, VPN tunnels, backup pipelines) is typically 12–40× this score. Re-run `npx pqcheck lock` to refresh; commit the result to your repo to surface changes in pull requests.*");
+  lines.push("");
+  return lines.join("\n");
+}
+
 main().catch((err) => {
   console.error(color("red", `fatal: ${err.message}`));
   process.exit(2);

package/package.json

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