pqcheck 0.16.12 → 0.16.13

package/README.md

@@ -1,12 +1,35 @@
 # pqcheck
 
-> **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.
+> **Type `npx pqcheck stripe.com`** (or any HTTPS domain) to scan its public posture in seconds — Decryption Blast Radius grade (0–10), letter (A–F), and findings ranked by severity. No signup, no API key, per-IP rate limited.
+>
+> **Or, for your own deploys:** wire `npx pqcheck deploy-check yourdomain.com --ai` into Claude Code / Cursor / Copilot. Your AI coder parses `ship_decision=pass|review|block` and decides whether to announce the deploy, ask you, or stop.
 
 [![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)
 
-> **Latest: v0.16.12** — README rewritten to lead with the AI deploy gate (drift between deploys) as the product; DBR repositioned as the severity model the gate uses. No CLI behavior changes. [Full changelog →](./CHANGELOG.md)
+> **Latest: v0.16.12** — ⚠️ **Existing GitHub Action users:** one-line fix required in `.github/workflows/cipherwake.yml` (`uses: cipherwakelabs/pqcheck@v3` → `cipherwakelabs/pqcheck/action@v3`). The old ref was broken since v0.15 and silently failed every CI run; today's end-to-end test caught it. Re-running `pqcheck onboard` also regenerates the workflow correctly. Plus: README rewritten to advertise both `pqcheck <domain>` and `pqcheck deploy-check --ai` equally, rate limits corrected. [Full changelog →](./CHANGELOG.md)
+
+## Two ways to use it
+
+### 1. Scan any domain — no signup, no API key, no per-account quota
+
+```bash
+npx pqcheck stripe.com
+```
+
+```
+◆ Cipherwake · stripe.com  DBR 2.3 B · 1 finding
+
+Top finding:
+  [MEDIUM] Intermediate cert uses RSA — quantum-vulnerable chain link
+
+Full report: https://cipherwake.io/r/stripe.com
+```
+
+Anonymous. Per-IP rate limited (120 scans/hour) for cost protection — that's it. Use it to spot-check a vendor before signing, audit a competitor's HTTPS posture, or just satisfy "I wonder how `<domain>` grades."
+
+### 2. Gate your own deploys with your AI coder
 
 ```bash
 npx pqcheck deploy-check yourdomain.com --ai
@@ -31,24 +54,35 @@ The last block — `CIPHERWAKE_AI_GUARD_RESULT` — is what your AI coding agent
 - **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.
+Zero install. Works in any terminal with Node 18+. Both modes are free — no signup, no API key required for first use of either.
 
 ## What pqcheck actually checks
 
-Each `pqcheck deploy-check <domain>` compares your site's public HTTPS surface *now* against your last scan and surfaces what changed:
+### Bare scan (`pqcheck <domain>`) — current-state posture grade
+
+Scans any public HTTPS surface and produces a **DBR score** (0–10), a **letter grade** (A–F), and a **findings list** ranked by severity. Same scanner that powers [cipherwake.io](https://cipherwake.io), the browser extension, and the GitHub Action — what it checks:
+
+- **TLS posture** — ciphersuite class, hybrid PQC key agreement (`X25519MLKEM768`), forward secrecy
+- **Certificate chain** — issuer, intermediate quality, key reuse across rotations (★ unique to pqcheck), wildcard / subdomain blast radius
+- **Security headers** — HSTS (preload + max-age), CSP, X-Frame-Options, Referrer-Policy, Permissions-Policy, COOP, CORP
+- **Email security** — SPF, DMARC, DKIM (~30 selectors probed including Resend/Mailgun/SES), BIMI
+- **Supply chain** — every third-party script loaded by the page, graded for quantum risk
+- **Subdomain takeover** — fingerprint scan against AWS S3, GitHub Pages, Heroku, Shopify, Fastly, etc.
+
+### Deploy gate (`pqcheck deploy-check --ai`) — drift since your last scan
+
+Compares your site's public HTTPS surface *now* against your last scan and surfaces what changed:
 
 - **New third-party scripts** loading on the page that weren't there before (the Polyfill.io-class supply-chain risk)
 - **Header regressions** — CSP weakened, HSTS shortened or removed, X-Frame-Options dropped, permissive tokens (`'unsafe-inline'`, `*`) introduced
 - **Certificate / SPKI changes** — unexpected rotations, key reuse across renewals, intermediate-chain changes
-- **TLS posture changes** — ciphersuite shifts, hybrid PQC key-agreement (`X25519MLKEM768`) added or removed
+- **TLS posture changes** — ciphersuite shifts, hybrid PQC key-agreement added or removed
 - **Vendor surface changes** — new email senders (SPF/DMARC), new CDN origins, new analytics endpoints
-- **Subdomain takeover exposure** — new dangling CNAMEs pointing at AWS S3 / GitHub Pages / Heroku / Fastly / etc.
-
-The gate routes each change through a severity model — the **Decryption Blast Radius** score (DBR, 0–10) — to decide `pass` / `review` / `block`. Cosmetic drift passes; high-severity drift (new script from an unknown origin, header regression that breaks defense-in-depth, cert SPKI change without a rotation event) triggers `review`; critical drift (expired cert served, takeover-vulnerable subdomain, malicious vendor injected) triggers `block`. DBR's full severity rubric is documented at [/methodology/decryption-blast-radius](https://cipherwake.io/methodology/decryption-blast-radius).
+- **Subdomain takeover exposure** — new dangling CNAMEs
 
-On **first use** (no prior scan to diff against), `deploy-check` falls back to absolute-posture grading: it scores the current state and surfaces the highest-severity findings so you start with a baseline. Every subsequent run is drift-relative to the previous scan.
+The gate routes each change through the same DBR severity model above to decide `pass` / `review` / `block`. Cosmetic drift passes; high-severity drift (new script from an unknown origin, header regression that breaks defense-in-depth, cert SPKI change without a rotation event) triggers `review`; critical drift (expired cert served, takeover-vulnerable subdomain, malicious vendor injected) triggers `block`. DBR's full severity rubric: [/methodology/decryption-blast-radius](https://cipherwake.io/methodology/decryption-blast-radius).
 
-You get the same scanner that powers [cipherwake.io](https://cipherwake.io), the browser extension, and the GitHub Action.
+On **first use** with no prior scan to diff against, `deploy-check` falls back to the bare scan's absolute-posture grading to give you a baseline. Every subsequent run is drift-relative to the previous scan.
 
 ---
 
@@ -420,7 +454,7 @@ curl -s "https://www.cipherwake.io/api/scan?domain=stripe.com" | jq '.grade, .sc
 
 Full API reference at [cipherwake.io/api](https://cipherwake.io/api).
 
-**Rate limits:** 300 scans per hour per IP, 20 `--fresh` (force-refresh) scans per hour per IP. No API key required. Returns HTTP 429 if exceeded — back off and retry, or [let us know via the feedback form](https://cipherwake.io/feedback) if you need higher limits (we're prioritizing the API tier based on real demand).
+**Rate limits:** 120 scans per hour per IP for anonymous CLI use, 20 `--fresh` (force-refresh) scans per hour per IP. **Authenticated paths bypass this:** GitHub Actions OIDC (Free = 100 calls/month per repo) and API key (Founder Pro = 5,000/month per account) each have their own per-account / per-repo quota with no per-IP cap. No API key required for the anonymous path. Returns HTTP 429 if exceeded — back off and retry, or [let us know via the feedback form](https://cipherwake.io/feedback) if you need higher limits.
 
 ## Methodology
 

package/bin/pqcheck.js

@@ -24,9 +24,9 @@
 })();
 
 const API_BASE = process.env.PQCHECK_API_BASE || "https://cipherwake.io";
-const VERSION = "0.16.11";
+const VERSION = "0.16.13";
 
-// API-key support — paid tiers (Starter $29 / Growth $79 / Scale $199) get
+// API-key support — paid tier (Founder Pro $19.99/mo launch pricing, locked while sub active) gets
 // per-account monthly quotas instead of the per-IP rate limit. Set via:
 //   export CIPHERWAKE_API_KEY=qpk_<32-hex>
 // Anonymous CLI use still works (no env var → falls back to IP rate limit).
@@ -95,6 +95,16 @@ async function main() {
     process.exit(0);
   }
 
+  // v0.16.13: opportunistic update-check banner. Reads cached registry
+  // result from disk and prints a one-line stderr banner if a newer
+  // version is published; refreshes the cache in the background for next
+  // time. Never blocks the command. See maybeShowVersionBanner() for the
+  // full rationale (TL;DR: prevents the npx-cached-stale-version trap
+  // that caused 0.7.0 to silently run for months on existing users).
+  // Awaited so the banner appears BEFORE the command output for visibility,
+  // but it only reads a tiny file (no network on hot path).
+  await maybeShowVersionBanner(args);
+
   // Subcommand dispatch.
   if (args[0] === "lock") {
     return runLockCommand(args.slice(1));
@@ -759,6 +769,169 @@ function formatAiFooterBlock(fields) {
   return color("dim", lines.join("\n"));
 }
 
+// v0.16.13 — fail-loud AI guard for fetch/quota/server errors during
+// deploy-check. Without this, a network blip during `pqcheck deploy-check
+// --ai` would print a red error to stderr and exit 3 — but the AI Coder
+// Protocol relies on the CIPHERWAKE_AI_GUARD_RESULT block. Missing block =
+// AI agent assumes "no signal" and may continue shipping. The fix: in AI
+// mode, always emit a block with ship_decision=review and a top_issue code
+// the agent can route on. Behaviour in non-AI text mode is unchanged.
+function emitAiGuardReviewAndExit(args, errorDetail) {
+  if (parseAiMode(args)) {
+    const positional = args.filter((a) => !a.startsWith("-"));
+    const domain = positional[0] || "";
+    const baseline = parseFlag(args, "--baseline") || "last-scan";
+    try {
+      console.log("");
+      console.log(formatBrandHeader(domain));
+      console.log("");
+      console.log(color("yellow", "  ⚠ REVIEW — Cipherwake deploy-check could not complete"));
+      console.log(color("dim",    `  ${errorDetail.message}`));
+      console.log(color("dim",    "  Treating as REVIEW per fail-safe policy. Do NOT announce the deploy until you manually verify or rerun the check successfully."));
+      console.log(formatAiFooterBlock({
+        status: "review",
+        domain,
+        kind: "trust-diff",
+        baseline,
+        verdict: "review",
+        delta_count: 0,
+        max_severity: "unknown",
+        ship_decision: "review",
+        top_issue: errorDetail.code,
+        top_issue_title: errorDetail.message,
+        dbr: "",
+        grade: "",
+        quota_used: "",
+        quota_limit: "",
+        scanned_at: new Date().toISOString(),
+        advisory_only: "true",
+        error: errorDetail.code,
+      }));
+      console.log("");
+      // Persist the review state so the IDE statusbar reflects the failure
+      // (otherwise the bar stays on the previous successful scan).
+      writeLastScanFile({
+        domain,
+        kind: "trust-diff",
+        score: null,
+        grade: null,
+        max_severity: "unknown",
+        ship_decision: "review",
+        baseline,
+        delta_count: 0,
+        top_issue: errorDetail.code,
+        error: errorDetail.code,
+      }).catch(() => { /* best-effort */ });
+    } catch {
+      // even error path must not throw — fall through to exit
+    }
+  }
+  process.exit(errorDetail.exitCode ?? 3);
+}
+
+// v0.16.13 — opportunistic version check. Reads a small cache file on cold
+// start; if a newer version is in cache AND we haven't already banner'd
+// today, prints a banner to stderr. Separately, if cache is >24h old, fires
+// off a background fetch (non-blocking) whose result lands for the NEXT
+// invocation. Zero network on hot path. Skipped in machine-readable formats
+// (JSON/SARIF/github) so it never pollutes scripted output. The banner
+// helps users who installed via `npx pqcheck` months ago and have a stale
+// version cached in ~/.npm/_npx/ that they don't know is stale.
+const VERSION_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+const VERSION_REGISTRY_URL = "https://registry.npmjs.org/pqcheck";
+
+async function maybeShowVersionBanner(args) {
+  // Skip in machine-parsed output formats.
+  const format = parseFlag(args, "--format");
+  if (format === "json" || format === "sarif" || format === "github") return;
+  // Skip if explicitly disabled (env opt-out).
+  if (process.env.PQCHECK_NO_UPDATE_CHECK === "1") return;
+
+  try {
+    const os = await import("node:os");
+    const path = await import("node:path");
+    const fs = await import("node:fs/promises");
+
+    const cacheDir = path.join(os.homedir(), ".config", "cipherwake");
+    const cachePath = path.join(cacheDir, "version-check.json");
+
+    let cached = null;
+    try {
+      cached = JSON.parse(await fs.readFile(cachePath, "utf8"));
+    } catch {
+      // first run or unreadable — fall through
+    }
+
+    const now = Date.now();
+    const stale = !cached || !cached.checked_at || (now - cached.checked_at) > VERSION_CHECK_TTL_MS;
+
+    // 1. If cache has a known-newer version, print banner now (synchronous,
+    //    cheap, no network).
+    if (cached && cached.latest && isNewerVersion(cached.latest, VERSION)) {
+      const lastShownAt = cached.last_shown_at || 0;
+      const showThrottleMs = 6 * 60 * 60 * 1000; // at most once per 6h
+      if (now - lastShownAt > showThrottleMs) {
+        process.stderr.write(
+          color("yellow", `\n  ⬆ pqcheck ${cached.latest} is available `) +
+          color("dim",    `(you have ${VERSION}) — run: `) +
+          color("bold",   "npm i -g pqcheck@latest") +
+          color("dim",    "  (or: rm -rf ~/.npm/_npx && npx pqcheck@latest ...)\n\n")
+        );
+        // Persist that we just shown the banner so we don't spam.
+        await fs.mkdir(cacheDir, { recursive: true });
+        await fs.writeFile(cachePath, JSON.stringify({ ...cached, last_shown_at: now }, null, 2));
+      }
+    }
+
+    // 2. If cache is stale, fire-and-forget a registry fetch so the NEXT
+    //    cold start has fresh data. Detached from the await chain so it
+    //    never delays exit.
+    if (stale) {
+      void refreshVersionCacheInBackground(cachePath);
+    }
+  } catch {
+    // best-effort — never break the CLI for an update check
+  }
+}
+
+async function refreshVersionCacheInBackground(cachePath) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 2500);
+    const resp = await fetch(VERSION_REGISTRY_URL, {
+      headers: { "Accept": "application/json", "User-Agent": `pqcheck-cli/${VERSION}` },
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+    if (!resp.ok) return;
+    const body = await resp.json();
+    const latest = body?.["dist-tags"]?.latest;
+    if (!latest) return;
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    await fs.mkdir(path.dirname(cachePath), { recursive: true });
+    // Preserve last_shown_at so we don't reset the throttle on every refresh.
+    let prior = {};
+    try { prior = JSON.parse(await fs.readFile(cachePath, "utf8")); } catch { /* none */ }
+    await fs.writeFile(cachePath, JSON.stringify({
+      ...prior,
+      latest,
+      checked_at: Date.now(),
+    }, null, 2));
+  } catch {
+    // best-effort
+  }
+}
+
+function isNewerVersion(remote, local) {
+  const parse = (v) => String(v).split(".").map((n) => parseInt(n, 10) || 0);
+  const [a, b, c] = parse(remote);
+  const [x, y, z] = parse(local);
+  if (a !== x) return a > x;
+  if (b !== y) return b > y;
+  return c > z;
+}
+
 // v0.16.0 — high-yield output formatters.
 //
 // Design (per user direction 2026-05-22): every scan should deliver
@@ -1291,7 +1464,7 @@ function printMarkdown(r, multi) {
   // not the old "watch free / weekly digest"). PR-comment context plants
   // team-invitation idea for the eventual Growth tier upgrade.
   lines.push(`📌 **Monitor ${r.domain} continuously?** ${API_BASE}/watch/${encodeURIComponent(r.domain)}`);
-  lines.push(`Cipherwake Starter $29/mo · 5 domains · daily scans + email alerts on cert/script/posture changes. Invite your team on Growth ($79/mo) when ready.`);
+  lines.push(`Cipherwake Founder Pro $19.99/mo (launch pricing, locked while subscription active) · 5 watched domains · daily scans · full CI Trust Gate · approved-vendor allowlist · webhook delivery (Slack incoming-webhook URLs work).`);
   if (multi) lines.push("\n---\n");
   console.log(lines.join("\n"));
 }
@@ -1421,7 +1594,7 @@ function printReport(r) {
   // 2026-05-14: copy must match current locked revenue plan ($29 Starter,
   // not the old "free 1-domain weekly digest").
   console.log(color("violet", `  📌 Monitor ${r.domain} daily: ${API_BASE}/watch/${encodeURIComponent(r.domain)}`));
-  console.log(color("dim",    `     Cipherwake Starter $29/mo · 5 watched domains · email alerts · cancel anytime`));
+  console.log(color("dim",    `     Cipherwake Founder Pro $19.99/mo · 5 watched domains · email alerts · launch pricing locked while subscription active · cancel anytime`));
   console.log("");
   console.log(color("dim",    `  → Full report: ${API_BASE}/?check=${encodeURIComponent(r.domain)}`));
   console.log(color("dim",    `  → Share this:  ${API_BASE}/r/${encodeURIComponent(r.domain)}`));
@@ -3040,19 +3213,33 @@ async function runTrustDiffCommand(args) {
     });
   } catch (err) {
     console.error(color("red", `error: network failure calling /api/trust-diff: ${err.message}`));
-    process.exit(3);
+    // v0.16.13: in AI mode, emit a ship_decision=review block so the
+    // calling agent doesn't silently treat a fetch failure as "no signal".
+    return emitAiGuardReviewAndExit(args, {
+      code: "deploy_check_fetch_failed",
+      message: `Network failure: ${err?.message || "fetch failed"}`,
+      exitCode: 3,
+    });
   }
 
   if (resp.status === 401 || resp.status === 403) {
     await handleAuthError(resp);
-    process.exit(3);
+    return emitAiGuardReviewAndExit(args, {
+      code: "deploy_check_auth_failed",
+      message: `Authorization failed (${resp.status}). Check CIPHERWAKE_API_KEY or hit /account#api-keys.`,
+      exitCode: 3,
+    });
   }
   if (resp.status === 429) {
     const body = await safeJSON(resp);
     console.error(color("red", "error: Trust Diff API quota exceeded"));
     if (body?.message) console.error(color("dim", body.message));
     console.error(color("dim", "Higher quota via free API key (no card): https://cipherwake.io/account#api-keys"));
-    process.exit(3);
+    return emitAiGuardReviewAndExit(args, {
+      code: "deploy_check_quota_exceeded",
+      message: body?.message || "Trust Diff monthly quota exceeded — upgrade or wait for monthly reset.",
+      exitCode: 3,
+    });
   }
   // R74-confirm friction fix #2 (GPT 2026-05-22): 404 on first-deploy is
   // expected — the domain has never been scanned, so there's no baseline to
@@ -3069,7 +3256,11 @@ async function runTrustDiffCommand(args) {
     console.error(color("red", `error: /api/trust-diff returned ${resp.status}`));
     if (body?.message) console.error(color("dim", body.message));
     if (body?.hint) console.error(color("dim", body.hint));
-    process.exit(3);
+    return emitAiGuardReviewAndExit(args, {
+      code: "deploy_check_server_error",
+      message: body?.message || `Cipherwake server returned ${resp.status}.`,
+      exitCode: 3,
+    });
   }
 
   const result = await resp.json();
@@ -4232,7 +4423,7 @@ function renderReleaseChecklist(domain, opts = {}) {
 // `pqcheck init` — interactive workflow scaffold (habit-loop #4, locked 2026-05-16)
 // =============================================================================
 // Writes a ready-to-commit .github/workflows/cipherwake.yml that calls
-// cipherwakelabs/pqcheck@v3 in trust-diff mode. Zero copy-paste docs friction.
+// cipherwakelabs/pqcheck/action@v3 in trust-diff mode. Zero copy-paste docs friction.
 //
 // Flags:
 //   --domain <d>       Skip the domain prompt
@@ -4409,7 +4600,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Run Cipherwake Trust Diff
-        uses: cipherwakelabs/pqcheck@v3
+        uses: cipherwakelabs/pqcheck/action@v3
         with:
           mode: trust-diff
           domain: ${domain}
@@ -4417,7 +4608,7 @@ jobs:
           fail-on: ${failOn}
         # No env/secrets needed for Free tier — the action uses the
         # workflow's id-token: write permission to fetch a GitHub-signed
-        # OIDC token and meters per repo (30 calls/mo, no setup).
+        # OIDC token and meters per repo (100 calls/mo, no setup).
         # If you want higher limits, link this repo to a paid Cipherwake
         # account at https://cipherwake.io/account → Linked repos.
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pqcheck",
-  "version": "0.16.12",
+  "version": "0.16.13",
   "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",