pqcheck 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,137 @@
+# pqcheck
+
+> **Public Surface Blast Radius scanner** — find out how much of your data unlocks when quantum decryption arrives.
+
+```bash
+npx pqcheck chase.com
+```
+
+That's it. No install. Works from any terminal with Node 18+.
+
+---
+
+## What it does
+
+`pqcheck` scans any HTTPS domain and computes its **Decryption Blast Radius Score** — the first continuous metric for harvest-now-decrypt-later (HNDL) risk. Every other TLS scanner answers "is post-quantum cryptography enabled?" with a yes/no. `pqcheck` answers the question that actually matters: *if an adversary harvests this traffic today and decrypts it in 2035, how much past + future data unlocks?*
+
+The score combines:
+- **Cipher-class probing** — does the server accept RSA fallback even if it prefers ECDHE?
+- **Certificate chain analysis** — including the intermediate cert (the chain's actual quantum failure point)
+- **Public-key reuse across rotations** — detects when the same private key has been live across multiple cert renewals (often 4+ years at large enterprises)
+- **Subject scale** — wildcard certs and subdomain count multiplying the blast radius
+
+## Example
+
+```
+$ npx pqcheck chase.com
+
+  chase.com
+  ─────────────────────────────────────
+  PUBLIC SURFACE BLAST RADIUS: 5.6 / 10 (MEDIUM)
+
+  Public surface signals:
+  • TLS:           TLSv1.3 (TLS_AES_128_GCM_SHA256)
+  • Hybrid PQC:    no
+  • Cert expires:  in 127 days
+  • HSTS:          not detected
+  • Subdomains:    47 (wildcard cert)
+
+  Findings:
+  [HIGH] Same RSA-2048 key reused for 4.2 years across 3 cert rotations
+  [HIGH] ECDHE-only — quantum-vulnerable key exchange
+  [MED]  Wildcard cert spans 47 subdomains
+
+  ⚠  This is the PUBLIC surface only.
+  Internal Blast Radius is typically 12–40× the public score.
+
+  Plain-English impact:
+  If quantum decryption arrives in 2030–2040, harvested traffic from
+  chase.com (US banks) would unlock 4.2 years of session data, across
+  47 subdomains under one wildcard cert.
+
+  → Full report: https://quantapact.com/?check=chase.com
+```
+
+## Usage
+
+```
+npx pqcheck <domain>                      Scan and print human-readable report
+npx pqcheck <domain> --format json        Output raw JSON for piping / scripting
+npx pqcheck <domain> --threshold 7        Exit 2 if score ≥ 7 (CI gate)
+npx pqcheck <domain> --quiet              Print only the numeric score
+npx pqcheck --help                        Show all options
+npx pqcheck --version                     Show version
+```
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success — score below threshold (or no threshold set) |
+| 1    | Usage / network / scan error |
+| 2    | Score met or exceeded `--threshold` |
+
+### CI integration
+
+The `--threshold` flag turns `pqcheck` into a quantum-risk gate for any pipeline:
+
+```yaml
+# .github/workflows/quantum-risk-gate.yml
+- name: Check public-surface quantum-decryption risk
+  run: npx pqcheck mycompany.com --threshold 7
+```
+
+If the score is 7.0 or higher, the step fails and the PR can't merge.
+
+For finer control, combine `--quiet` with shell logic:
+
+```bash
+SCORE=$(npx pqcheck mybank.com --quiet)
+echo "Public surface blast radius: $SCORE / 10"
+```
+
+Or grab the full JSON for richer analysis:
+
+```bash
+npx pqcheck mybank.com --format json | jq '.findings[] | select(.severity=="high")'
+```
+
+## Web version
+
+Same scanner, browser-friendly UI: **[quantapact.com](https://quantapact.com)**
+
+Shareable per-domain reports at `quantapact.com/r/<domain>` — the URL unfurls in Twitter / Slack / LinkedIn with a dynamically-generated card showing the grade.
+
+## Public leaderboard
+
+Sector rankings updated nightly across:
+
+- US Banks (20 peers)
+- US Healthcare Systems (20 peers)
+- Major SaaS / Cloud Platforms (30 peers)
+- US Federal Government (25 peers)
+- Major EU & UK Banks (25 peers)
+- US Defense Contractors (15 peers)
+- Global Automakers (15 peers)
+- Global News & Media (15 peers)
+- US Telecom & ISPs (15 peers)
+- US Airlines (10 peers)
+- UK Government & Public Services (15 peers)
+
+→ **[quantapact.com/leaderboard.html](https://quantapact.com/leaderboard.html)**
+
+## Methodology
+
+The Decryption Blast Radius scoring methodology is fully open and documented at **[quantapact.com/methodology](https://quantapact.com/methodology)**. Citable; methodology paper coming soon.
+
+## Privacy
+
+`pqcheck` sends the domain you scan to the Quantapact API (so the actual TLS handshake can be performed from the public internet). No other data is sent — no email, no IP-tied identifier, nothing client-side. The server-side `/api/scan` endpoint stores anonymous scan results in a 30-minute cache to avoid duplicate scans of the same domain. See [quantapact.com/privacy](https://quantapact.com/privacy) for full details.
+
+## License
+
+MIT. © 2026 Quantapact.
+
+## Disclaimer
+
+`pqcheck` measures only the **public** surface of a domain — what's observable from the open internet. Internal Blast Radius (east-west traffic, internal databases, VPN tunnels, backup pipelines) is typically 12–40× the public score depending on sector. A passing public-surface grade does **not** mean low internal exposure.

package/bin/pqcheck.js

@@ -7,7 +7,7 @@
 // =============================================================================
 
 const API_BASE = process.env.PQCHECK_API_BASE || "https://quantapact.com";
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 
 const ANSI = {
   reset:   "\x1b[0m",
@@ -41,16 +41,22 @@ async function main() {
     process.exit(1);
   }
 
-  const json = args.includes("--json");
+  const quiet = args.includes("--quiet") || args.includes("-q");
+  const format = parseFormat(args);
+  const threshold = parseThreshold(args);
+  if (threshold === "invalid") {
+    console.error(color("red", "error: --threshold requires a number 0-10"));
+    process.exit(1);
+  }
 
-  process.stderr.write(color("dim", `Scanning ${domain} ...`));
+  if (!quiet) process.stderr.write(color("dim", `Scanning ${domain} ...`));
   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}` },
     });
-    process.stderr.write("\r\x1b[K"); // clear "Scanning ..." line
+    if (!quiet) process.stderr.write("\r\x1b[K"); // clear "Scanning ..." line
     if (!resp.ok) {
       const errBody = await safeJSON(resp);
       console.error(color("red", `error: ${resp.status} ${errBody?.error || resp.statusText}`));
@@ -59,17 +65,45 @@ async function main() {
     }
     report = await resp.json();
   } catch (err) {
-    process.stderr.write("\r\x1b[K");
+    if (!quiet) process.stderr.write("\r\x1b[K");
     console.error(color("red", `error: ${err.message}`));
     process.exit(1);
   }
 
-  if (json) {
+  if (quiet) {
+    // Numeric score on stdout, nothing else. Suitable for piping.
+    console.log(typeof report.score === "number" ? report.score : "");
+  } else if (format === "json") {
     console.log(JSON.stringify(report, null, 2));
-    process.exit(0);
+  } else {
+    printReport(report);
   }
 
-  printReport(report);
+  // Threshold gating: exit 2 if score >= threshold (distinct from exit 1 = error)
+  if (threshold !== null && typeof report.score === "number" && report.score >= threshold) {
+    if (!quiet) {
+      console.error(color("red", `threshold breach: score ${report.score} >= ${threshold}`));
+    }
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+function parseFormat(args) {
+  if (args.includes("--json")) return "json"; // back-compat alias
+  const i = args.indexOf("--format");
+  if (i === -1) return "text";
+  const v = (args[i + 1] || "").toLowerCase();
+  return v === "json" ? "json" : "text";
+}
+
+function parseThreshold(args) {
+  const i = args.indexOf("--threshold");
+  if (i === -1) return null;
+  const raw = args[i + 1];
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0 || n > 10) return "invalid";
+  return n;
 }
 
 function printReport(r) {
@@ -137,6 +171,8 @@ function printReport(r) {
   }
 
   console.log(color("violet", `  → Full report: ${API_BASE}/?check=${encodeURIComponent(r.domain)}`));
+  console.log(color("dim",    `  → Share this:  ${API_BASE}/r/${encodeURIComponent(r.domain)}`));
+  console.log(color("dim",    `  → Compare two: ${API_BASE}/compare?a=${encodeURIComponent(r.domain)}&b=`));
   console.log("");
 }
 
@@ -161,17 +197,29 @@ ${color("bold", "pqcheck")} ${color("dim", `v${VERSION}`)}
 Public Surface Blast Radius — quantum-decryption risk for any domain.
 
 ${color("bold", "Usage:")}
-  npx pqcheck <domain>           Scan and print human-readable report
-  npx pqcheck <domain> --json    Output raw JSON
+  npx pqcheck <domain>                       Scan and print human-readable report
+  npx pqcheck <domain> --format json         Output raw JSON
+  npx pqcheck <domain> --threshold 7         Exit 2 if score ≥ 7 (CI-friendly)
+  npx pqcheck <domain> --quiet               Print just the score, nothing else
 
 ${color("bold", "Options:")}
-  -h, --help        Show this help
-  -v, --version     Show version
-  --json            Print raw JSON output
+  -h, --help                Show this help
+  -v, --version             Show version
+  --format <text|json>      Output format (default: text)
+  --json                    Alias for --format json
+  --threshold <0-10>        Exit code 2 if score meets/exceeds this value
+  -q, --quiet               Print only the numeric score (pipe-friendly)
+
+${color("bold", "Exit codes:")}
+  0   success
+  1   usage / network / scan error
+  2   score met or exceeded --threshold
 
 ${color("bold", "Examples:")}
   npx pqcheck chase.com
-  npx pqcheck quantapact.com --json
+  npx pqcheck quantapact.com --format json
+  npx pqcheck mybank.com --threshold 7      ${color("dim", "# fail CI if exposed")}
+  echo "score: $(npx pqcheck mybank.com -q)"
 
 Backed by the patented Decryption Blast Radius methodology.
 ${color("violet", "https://quantapact.com")}

package/package.json

@@ -1,20 +1,29 @@
 {
   "name": "pqcheck",
-  "version": "0.1.0",
-  "description": "Public Surface Blast Radius scanner — quantum-decryption risk in your terminal.",
+  "version": "0.2.0",
+  "description": "Decryption Blast Radius scanner — find out how much of your data unlocks when quantum decryption arrives.",
   "keywords": [
     "post-quantum",
     "cryptography",
     "security",
     "tls",
+    "ssl",
     "scanner",
     "harvest-now-decrypt-later",
     "hndl",
     "blast-radius",
-    "pqc"
+    "pqc",
+    "quantum",
+    "crypto-audit",
+    "crypto-inventory"
   ],
   "homepage": "https://quantapact.com",
   "bugs": "https://quantapact.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mzon7/quantapact.git",
+    "directory": "cli"
+  },
   "license": "MIT",
   "author": "Quantapact",
   "type": "module",
@@ -25,6 +34,7 @@
     "pqcheck": "./bin/pqcheck.js"
   },
   "files": [
-    "bin/"
+    "bin/",
+    "README.md"
   ]
 }