pqcheck 0.15.2 → 0.15.3

package/README.md

@@ -1,27 +1,54 @@
 # pqcheck
 
-> **Decryption Blast Radius scanner** — find out how much of your data unlocks when quantum decryption arrives.
+> **A deploy gate for AI coding agents.** Tell Claude Code / Cursor / Copilot whether the site you just deployed is safe to announce — or whether your AI coworker should pause and ask you first.
 
 [![npm version](https://img.shields.io/npm/v/pqcheck.svg?style=flat-square&color=06b6d4)](https://www.npmjs.com/package/pqcheck)
 [![npm downloads](https://img.shields.io/npm/dm/pqcheck.svg?style=flat-square&color=06b6d4)](https://www.npmjs.com/package/pqcheck)
 [![license](https://img.shields.io/npm/l/pqcheck.svg?style=flat-square&color=06b6d4)](./LICENSE)
 
 ```bash
-npx pqcheck stripe.com
+npx pqcheck deploy-check yourdomain.com --ai
+```
+
 ```
+◆ Cipherwake · yourdomain.com ⚠ REVIEW · DBR 4.1 C · HIGH
+
+Top finding:
+  [HIGH] ECDHE-only — quantum-vulnerable key exchange
+
+CIPHERWAKE_AI_GUARD_RESULT
+ship_decision=review
+top_issue=tls.ecdhe_only_quantum_vulnerable
+END_CIPHERWAKE_AI_GUARD_RESULT
+```
+
+The last block — `CIPHERWAKE_AI_GUARD_RESULT` — is what your AI coding agent parses. It contains a single field, `ship_decision=pass|review|block`, that tells the agent whether to:
+
+- **pass** — go ahead and announce the deploy is shipped
+- **review** — stop and ask you what to do (your HTTPS posture drifted vs. last scan)
+- **block** — refuse to announce until you investigate (something critical changed)
+
+Zero install. Works in any terminal with Node 18+. Free, no signup, no API key required for first deploys.
+
+## What pqcheck actually checks
+
+Each `pqcheck <domain>` scans your site's public HTTPS surface and produces:
 
-Zero install. Works in any terminal with Node 18+. Free, no signup, no API key.
+- a **DBR score** (Decryption Blast Radius, 0–10) — how much of today's traffic would be readable to an attacker who's storing it now and waiting for quantum computers to break today's encryption (the "harvest-now, decrypt-later" risk, typically 5–10 years out per NIST timelines)
+- a **letter grade** (A–F)
+- a **findings list** ranked by severity — TLS cipher suites, certificate quality, security headers (CSP / HSTS / etc.), third-party scripts loaded by the page, key reuse across subdomains, and more
 
-The same scanner that powers [cipherwake.io](https://cipherwake.io), the browser extension, and the GitHub Action.
+You get the same scanner that powers [cipherwake.io](https://cipherwake.io), the browser extension, and the GitHub Action.
 
 ---
 
-## What it does
+## Commands at a glance
 
 | Command | What it gives you |
 |---|---|
-| `npx pqcheck <domain>` | One-shot DBR scan + grade. The original surface. |
-| `npx pqcheck trust-diff <domain>` | Compare today's public trust posture vs a baseline (last-week, last-month, or a saved CI baseline). For CI gates + release checklists. |
+| `npx pqcheck <domain>` | The basic scan. Returns DBR score (0–10), letter grade (A–F), and a list of findings ranked by severity. The fastest way to ask "is my site's HTTPS posture healthy today?" |
+| `npx pqcheck deploy-check <domain> --ai` | The flagship command. Wraps the scan with `ship_decision=pass\|review\|block` for your AI coding agent to gate the deploy announcement. Works anonymously on first use; subsequent runs compare against the previous scan. |
+| `npx pqcheck trust-diff <domain>` | Compare today's HTTPS surface against a saved baseline (last week / last month / a saved CI baseline). For CI gates and release checklists. |
 | `npx pqcheck preview-diff --preview <URL> --production <URL>` | Compare a Vercel/Netlify preview deployment URL to production. Surfaces new third-party scripts, header regressions, and DBR score drops *inside the PR*, before merge. |
 | `npx pqcheck vendors export/check/sync <domain>` | Vendor lockfile (`cipherwake.vendors.json`) + CI gate that exits non-zero when a new third-party origin appears. Like `package-lock.json` for vendor scripts. |
 | `npx pqcheck onboard <domain>` | One command: scan → scaffold the GitHub Action → capture a vendor lockfile → set a baseline → commit + push. Zero copy-paste from docs. |
@@ -45,7 +72,7 @@ npx pqcheck cipherwake.io --ai
 Output:
 
 ```
-◆ cipherwake · scan · ⚠ REVIEW · cipherwake.io · DBR 4.1 C · HIGH · ship_decision=review
+◆ Cipherwake · cipherwake.io ⚠ REVIEW · DBR 4.1 C · HIGH
 
 Top finding:
   [HIGH] ECDHE-only — quantum-vulnerable key exchange

package/bin/pqcheck.js

@@ -24,7 +24,7 @@
 })();
 
 const API_BASE = process.env.PQCHECK_API_BASE || "https://cipherwake.io";
-const VERSION = "0.15.2";
+const VERSION = "0.15.3";
 
 // API-key support — paid tiers (Starter $29 / Growth $79 / Scale $199) get
 // per-account monthly quotas instead of the per-IP rate limit. Set via:
@@ -263,13 +263,34 @@ async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi,
     if (!quiet && format === "text") process.stderr.write("\r\x1b[K");
     if (!resp.ok) {
       const errBody = await safeJSON(resp);
-      console.error(color("red", `error scanning ${domain}: ${resp.status} ${errBody?.error || resp.statusText}`));
-      if (errBody?.detail) console.error(color("dim", errBody.detail));
-      // Surface the 429 upsell hint if present — tells users how to ask for
-      // higher limits via the feedback form. Same demand signal we capture
-      // on the homepage.
-      if (resp.status === 429 && errBody?.need_more?.feedback_url) {
-        console.error(color("dim", `${errBody.need_more.message} → ${errBody.need_more.feedback_url}`));
+      // Friendly per-status messages so customers see actionable guidance
+      // instead of "error scanning X: 429 rate_limit_exceeded" raw HTTP
+      // verbiage. Batch users scripting many scans in a row hit this hardest
+      // — surface what they should do (wait + retry, or upgrade) rather than
+      // leaving them to guess.
+      if (resp.status === 429) {
+        const retryAfter = resp.headers.get("retry-after");
+        const waitMsg = retryAfter ? `Wait ${retryAfter}s then retry.` : "Wait ~60s then retry.";
+        console.error(color("yellow", `⚠ Rate limit hit on ${domain} — too many scans from this IP in the current window.`));
+        console.error(color("dim", `  ${waitMsg} For higher limits, get an account: ${API_BASE}/account`));
+        if (errBody?.need_more?.feedback_url) {
+          console.error(color("dim", `  Need much higher throughput? ${errBody.need_more.feedback_url}`));
+        }
+      } else if (resp.status >= 500) {
+        console.error(color("red", `error scanning ${domain}: Cipherwake's scanner hit a transient issue (HTTP ${resp.status}).`));
+        console.error(color("dim", `  Retry in ~1 minute. If it keeps happening, report at ${API_BASE}/feedback (include the domain + timestamp).`));
+        if (errBody?.detail) console.error(color("dim", `  Detail: ${errBody.detail}`));
+      } else if (resp.status === 400) {
+        // Most 400s on /api/scan are "invalid domain" — typically the
+        // customer typed a URL with a path or used localhost. The
+        // server already returns a clear message; just present it
+        // without raw HTTP noise.
+        console.error(color("red", `error scanning ${domain}: ${errBody?.error || resp.statusText}`));
+        if (errBody?.detail) console.error(color("dim", `  ${errBody.detail}`));
+        console.error(color("dim", `  Cipherwake only scans public domains. URLs with paths, IPs, and \`localhost\` aren't supported.`));
+      } else {
+        console.error(color("red", `error scanning ${domain}: ${resp.status} ${errBody?.error || resp.statusText}`));
+        if (errBody?.detail) console.error(color("dim", errBody.detail));
       }
       return 1;
     }
@@ -314,12 +335,17 @@ async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi,
   // the unreachability was expected (e.g., they know DNS is still
   // propagating) or fixes the deploy. This matches the protocol's "STOP,
   // wait for explicit override" routing.
-  // Only treat literal "reachable === false" as unreachable. _meta.degraded
-  // is too broad — it also fires for fingerprint disagreement / cache
-  // fallback / mid-scan state changes on reachable domains (e.g. stripe.com
-  // mid-deploy), and those scans returned a real score we shouldn't hide
-  // behind an UNREACHABLE label.
-  const unreachable = report?.reachable === false;
+  // Treat as "cannot evaluate" — and route through the UNREACHABLE label —
+  // when either:
+  //   • reachable === false  (no TCP/TLS handshake at all)
+  //   • scanAvailable === false  (TCP/TLS up, but scan couldn't produce a
+  //     coherent fingerprint — e.g. medium.com churning vendor scripts
+  //     faster than our dual-fingerprint check)
+  //
+  // _meta.degraded alone is too broad (fires on cache fallback + mid-scan
+  // state changes on otherwise-scoreable domains like stripe.com), so we
+  // narrow to the structured failure signals the server emits.
+  const unreachable = report?.reachable === false || report?.scanAvailable === false;
   if (unreachable) {
     shipDecision = "block";
   }
@@ -347,14 +373,24 @@ async function runOneScan({ domain, format, quiet, threshold, webhookUrl, multi,
   if (aiMode) {
     let topIssue, whyMatters, nextActions;
     if (unreachable) {
-      topIssue = "[REACHABILITY] Domain unreachable — TLS probe failed or DNS unresolved";
-      whyMatters = report?._meta?.degradedReason || "The scanner couldn't reach the domain on port 443. Either DNS hasn't propagated, the deploy hasn't completed, or this domain isn't deployed at the address we expected.";
-      nextActions = [
-        `Check the domain is correct (typo?): ${domain}`,
-        `Verify DNS: dig +short ${domain}`,
-        `Verify deploy completed and TLS is live on https://${domain}`,
-        `Re-run after fix: npx pqcheck deploy-check ${domain} --ai`,
-      ];
+      const isUnstable = report?.reason === "scan_unstable";
+      topIssue = isUnstable
+        ? "[REACHABILITY] Scan unstable — site changing faster than we can scan it"
+        : "[REACHABILITY] Domain unreachable — TLS probe failed or DNS unresolved";
+      whyMatters = report?.userMessage || report?._meta?.degradedReason || (isUnstable
+        ? "The scanner reached the site but couldn't produce a coherent fingerprint — rolling deploy, rapid A/B variation, or fast vendor-script rotation. Retry usually succeeds once the site settles."
+        : "The scanner couldn't reach the domain on port 443. Either DNS hasn't propagated, the deploy hasn't completed, or this domain isn't deployed at the address we expected.");
+      nextActions = isUnstable
+        ? [
+            `Wait ~1 minute then retry: npx pqcheck deploy-check ${domain} --ai`,
+            `View full report (last successful scan): ${API_BASE}/r/${domain}`,
+          ]
+        : [
+            `Check the domain is correct (typo?): ${domain}`,
+            `Verify DNS: dig +short ${domain}`,
+            `Verify deploy completed and TLS is live on https://${domain}`,
+            `Re-run after fix: npx pqcheck deploy-check ${domain} --ai`,
+          ];
     } else {
       topIssue = topFinding
         ? `[${String(topFinding.severity || "").toUpperCase()}] ${topFinding.title || topFinding.detail || "finding"}`
@@ -2402,26 +2438,41 @@ async function runScanBasedDeployCheck(domain, args) {
   // field travels in the state file + structured block so statusline /
   // VS Code ext / chat-hook can render "UNREACHABLE" instead of generic
   // "BLOCK" — semantically clearer for this specific failure mode.
-  // Only treat literal "reachable === false" as unreachable. _meta.degraded
-  // is too broad — it also fires for fingerprint disagreement / cache
-  // fallback / mid-scan state changes on reachable domains (e.g. stripe.com
-  // mid-deploy), and those scans returned a real score we shouldn't hide
-  // behind an UNREACHABLE label.
-  const unreachable = report?.reachable === false;
+  // Treat as "cannot evaluate" — and route through the UNREACHABLE label —
+  // when either:
+  //   • reachable === false  (no TCP/TLS handshake at all)
+  //   • scanAvailable === false  (TCP/TLS up, but scan couldn't produce a
+  //     coherent fingerprint — e.g. medium.com churning vendor scripts
+  //     faster than our dual-fingerprint check)
+  //
+  // _meta.degraded alone is too broad (fires on cache fallback + mid-scan
+  // state changes on otherwise-scoreable domains like stripe.com), so we
+  // narrow to the structured failure signals the server emits.
+  const unreachable = report?.reachable === false || report?.scanAvailable === false;
   if (unreachable) {
     shipDecision = "block";
   }
 
   let topIssue, whyMatters, nextActions;
   if (unreachable) {
-    topIssue = "[REACHABILITY] Domain unreachable — TLS probe failed or DNS unresolved";
-    whyMatters = report?._meta?.degradedReason || "The scanner couldn't reach the domain on port 443. Either DNS hasn't propagated, the deploy hasn't completed, or this domain isn't deployed at the address we expected.";
-    nextActions = [
-      `Check the domain is correct (typo?): ${domain}`,
-      `Verify DNS: dig +short ${domain}`,
-      `Verify deploy completed and TLS is live on https://${domain}`,
-      `Re-run after fix: npx pqcheck deploy-check ${domain} --ai`,
-    ];
+    const isUnstable = report?.reason === "scan_unstable";
+    topIssue = isUnstable
+      ? "[REACHABILITY] Scan unstable — site changing faster than we can scan it"
+      : "[REACHABILITY] Domain unreachable — TLS probe failed or DNS unresolved";
+    whyMatters = report?.userMessage || report?._meta?.degradedReason || (isUnstable
+      ? "The scanner reached the site but couldn't produce a coherent fingerprint — rolling deploy, rapid A/B variation, or fast vendor-script rotation. Retry usually succeeds once the site settles."
+      : "The scanner couldn't reach the domain on port 443. Either DNS hasn't propagated, the deploy hasn't completed, or this domain isn't deployed at the address we expected.");
+    nextActions = isUnstable
+      ? [
+          `Wait ~1 minute then retry: npx pqcheck deploy-check ${domain} --ai`,
+          `View full report (last successful scan): ${API_BASE}/r/${domain}`,
+        ]
+      : [
+          `Check the domain is correct (typo?): ${domain}`,
+          `Verify DNS: dig +short ${domain}`,
+          `Verify deploy completed and TLS is live on https://${domain}`,
+          `Re-run after fix: npx pqcheck deploy-check ${domain} --ai`,
+        ];
   } else {
     topIssue = topFinding
       ? `[${String(topFinding.severity || "").toUpperCase()}] ${topFinding.title || topFinding.detail || "finding"}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pqcheck",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "description": "Deploy gate for AI-coded web apps. `pqcheck deploy-check --ai` returns ship_decision=pass|review|block for Claude Code / Cursor / Copilot / Aider to gate deploys before they ship. Anonymous, no signup, free for first use.",
   "keywords": [
     "ai-coder",