pqcheck 0.14.0 → 0.14.2

package/README.md

@@ -2,6 +2,10 @@
 
 > **Decryption Blast Radius scanner** — find out how much of your data unlocks when quantum decryption arrives.
 
+[![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
 ```
@@ -12,6 +16,20 @@ The same scanner that powers [cipherwake.io](https://cipherwake.io), the browser
 
 ---
 
+## What it does
+
+| 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 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. |
+
+Free tier covers all of the above within 100 Trust Diff calls/month per repo (paid lifts to 1K / 10K / 50K). Single-domain scans (`npx pqcheck <domain>`) are unmetered.
+
+---
+
 ## Get started in 60 seconds
 
 Wire Cipherwake into your CI so every PR gets a Trust Diff comment when your domain's public trust posture changes.
@@ -47,34 +65,90 @@ That's it. The scaffolded workflow includes `permissions: id-token: write`, so t
 
 ---
 
-## What's new in 0.12.0
+## Features
 
-**Developer habit-loop bundle (locked 2026-05-16).** Five new subcommands that put Cipherwake where developers already work: PRs, CI, release notes, vendor allowlists. Free tier covers all of them within the 100 Trust Diff calls/month per repo quota.
+For the per-release version history see [CHANGELOG.md](./CHANGELOG.md).
 
-- `pqcheck init` — interactive scaffold for `.github/workflows/cipherwake.yml`. Prompts for domain, fail-on severity, baseline. No copy-paste from docs required.
-- `pqcheck deploy-check <domain>` — pre-deploy Trust Diff gate with deploy-friendly framing. Uses last-scan as default baseline. Same exit semantics as `trust-diff`.
-- `pqcheck release-checklist [domain]` — markdown checklist for release notes. Offline, no API call.
-- `pqcheck vendors export <domain>` — write `cipherwake.vendors.json` from currently observed third-party origins. Like `package-lock.json` for vendor scripts.
-- `pqcheck vendors check <domain>` — CI gate; exits **4** when new origins appear that aren't in the lockfile.
-- `pqcheck vendors sync <domain>` — Starter+ only; pulls your dashboard-managed approved-vendor allowlist into the lockfile.
+### Trust Diff — CI gate for posture regressions
 
-Plus: the GitHub Action v3.1 now posts a **sticky PR comment** with Trust Diff results when `comment-on-pr: true` is set, and `/r/<domain>` has a "Copy as GitHub issue" button on every finding.
+```bash
+npx pqcheck trust-diff mycompany.com --baseline last-week --fail-on high
+```
 
-## What's new in 0.11.0
+Compares today's public trust posture against a configured baseline (`last-week`, `last-month`, or a saved per-branch baseline). Surfaces cert / SPKI / HSTS / CSP / DMARC / vendor-script drift since the baseline and gates the PR by severity. SARIF output uploads to GitHub Code Scanning. Pair with the [GitHub Action](https://github.com/cipherwakelabs/pqcheck/tree/main/action) `mode: trust-diff` for one-line CI integration.
 
-**Trust Diff subcommand** — `npx pqcheck trust-diff <domain>` calls `/api/trust-diff` and gates CI on regression severity vs a configured baseline. SARIF output uploads to GitHub's Code Scanning. Pair with `cipherwakelabs/pqcheck@v3` action `mode: trust-diff` for one-line CI integration.
+Exit codes: `0` pass · `1` warn · `2` fail · `3` error. Free tier (100 calls/repo/mo via GitHub Actions OIDC, no API key required) silently downgrades fail → report; Starter+ honors `--fail-on` for real CI gating.
 
-## What's new in 0.7.9
+### Preview Trust Diff — PR-time URL-vs-URL comparison
 
-**CSP verdict + vendor labels on `pqcheck deps`.** The supply-chain table now shows a friendly vendor label (`New Relic · errors` / `Cloudflare · cdn` / `Adobe Fonts · fonts`) per host instead of raw `bam.nr-data.net`-style hostnames, plus a one-line site-wide CSP verdict above the table (`✗ No CSP enforcement` / `⚠ CSP is permissive` / `✓ Strict CSP enforced`). Same data shape ships on `/r/<domain>` and in the browser extension — cross-surface parity for the supply-chain story. See [CHANGELOG.md](./CHANGELOG.md).
+```bash
+npx pqcheck preview-diff \
+  --preview https://feature-x-abc123.vercel.app \
+  --production https://example.com
+```
+
+Compares a preview-deployment URL to a production URL and surfaces application-surface changes (new third-party scripts, header regressions, DBR score drops) *inside the PR review, before merge*. SSRF-pinned scan path keeps preview-URL hostnames out of Cipherwake's moat tables — feature-branch names stay private.
 
-## What's new in 0.7.8
+Sample output:
+
+```
+  Cipherwake Preview Trust Diff
+  preview=https://feature-x-abc123.vercel.app
+  production=https://example.com
+
+  Application surface:
+    + New third-party script: widget.intercom.io
+    - Content-Security-Policy [script-src] added permissive token(s): 'unsafe-inline'
+    ~ Strict-Transport-Security weakened: max-age=31536000 → max-age=3600
+
+  Transport: preview is edge-hosted (Let's Encrypt) — informational only.
+
+  Verdict: WARN (max severity: high)
+  Tier: free · policy: report
+```
 
-**Supply-chain change detection in CI** — `pqcheck deps <domain> --baseline file.json` compares the current third-party host list to a stored baseline. New hosts since the last accepted state are flagged `*NEW*` in the pretty table and `"isNew": true` in JSON. Add `--fail-on-new` to exit `4` if anything new appeared — the Polyfill.io-style CI gate that fails PRs introducing third-party scripts until you deliberately accept them with `--write-baseline`. Each row also shows an `SRI` column (on/off/n/a) so you can see which scripts allow silent vendor-side content swaps. See [CHANGELOG.md](./CHANGELOG.md).
+Flags: `--preview <URL>` · `--production <URL>` · `--compare-transport` · `--fail-on <severity>` (default `high`; `none` for report-only) · `--format pretty|json`. CSP weakening detection diffs `script-src` / `default-src` / `object-src` / `frame-ancestors` / `base-uri` / `style-src` for newly-permissive tokens (`*`, `'unsafe-inline'`, `'unsafe-eval'`, `data:`, `blob:`).
+
+**Diffing a local dev build against prod?** Cipherwake runs the comparison server-side, so `--preview http://localhost:3000` is rejected (we'd be reaching for *our* loopback, not yours). Expose your dev build via a public tunnel:
+
+```bash
+# Vercel/Netlify preview deploys — automatic per PR, free, the design target
+--preview https://feature-x-abc123.vercel.app
+
+# ngrok — ad-hoc, one command
+ngrok http 3000
+--preview https://9b1f-203-0-113-7.ngrok-free.app
+
+# Cloudflare Tunnel — zero-auth quick tunnel
+cloudflared tunnel --url http://localhost:3000
+--preview https://random-words-1234.trycloudflare.com
+```
+
+### Vendor lockfile — `cipherwake.vendors.json`
+
+Like `package-lock.json`, but for the third-party scripts that load on your domain. Capture currently observed vendor origins, commit the lockfile, and CI fails when a PR introduces a new vendor.
+
+```bash
+npx pqcheck vendors export mycompany.com    # write cipherwake.vendors.json
+npx pqcheck vendors check mycompany.com     # CI gate; exit 4 on new origins
+npx pqcheck vendors sync mycompany.com      # Starter+ — pull dashboard allowlist
+```
+
+`pqcheck deps` also surfaces a one-line site-wide **CSP verdict** above the supply-chain table (`✗ No CSP enforcement` / `⚠ CSP is permissive` / `✓ Strict CSP enforced`) and friendly vendor labels (`New Relic · errors` / `Cloudflare · cdn` / `Adobe Fonts · fonts`) instead of raw hostnames. Same data shape ships on `/r/<domain>` and in the browser extension.
+
+### Developer habit-loop subcommands
+
+```bash
+npx pqcheck init                # interactive scaffold for .github/workflows/cipherwake.yml
+npx pqcheck deploy-check        # pre-deploy gate (Trust Diff alias, last-scan baseline)
+npx pqcheck release-checklist   # markdown trust checklist for release notes (offline)
+```
+
+The GitHub Action posts a **sticky PR comment** with results when `comment-on-pr: true` is set on `pull_request` events. Comment auto-edits on subsequent pushes — no spam.
 
 ---
 
-## What it does
+## How DBR scoring works
 
 `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 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?*
 
@@ -100,7 +174,8 @@ npx pqcheck diff <old.lock> <new.lock>        Compare two QXM lockfiles; exit 2
 npx pqcheck history <domain>                  Show 90-day score history (sparkline + samples)
 npx pqcheck changes <domain>                  Summarize public attack-surface changes in last 14 days
 npx pqcheck cert <file.pem>                   Analyze a local PEM/CRT cert file (offline, no network)
-npx pqcheck trust-diff <domain>               Trust Diff vs configured baseline; CI gate (Free: 30/mo)
+npx pqcheck trust-diff <domain>               Trust Diff vs configured baseline; CI gate (Free: 100/repo/mo)
+npx pqcheck preview-diff --preview U --production U  Preview-URL vs production-URL diff; new scripts + header regressions + score drops (NEW in 0.14.0)
 npx pqcheck deploy-check <domain>             Pre-deploy gate (Trust Diff alias with last-scan baseline)
 npx pqcheck onboard <domain>                  One-command setup wizard (scan + init + vendors + checklist)
 npx pqcheck init                              Interactive scaffold for .github/workflows/cipherwake.yml
@@ -248,9 +323,8 @@ This CLI is one of four ways to consume the [Decryption Blast Radius API](https:
 | Surface | Where |
 |---|---|
 | **CLI** (this package) | `npx pqcheck` |
-| **Browser extension** | Chrome Web Store / Firefox AMO / Edge — toolbar badge per tab + dependency analysis |
+| **Browser extension** | [Chrome Web Store](https://chromewebstore.google.com/) — toolbar badge per tab + dependency analysis. Runs on any Chromium-based browser (Edge, Brave, Arc) via sideload. |
 | **GitHub Action** | [`cipherwakelabs/pqcheck/action@main`](https://github.com/cipherwakelabs/pqcheck/tree/main/action) — PR comments, SARIF upload, lockfile generation |
-| **Slack `/pqcheck`** | [Install on workspace](https://cipherwake.io/install-slack) |
 | **Web** | [cipherwake.io](https://cipherwake.io) — share-friendly URLs at `/r/<domain>` |
 
 ## Public API

package/bin/pqcheck.js

@@ -7,7 +7,7 @@
 // =============================================================================
 
 const API_BASE = process.env.PQCHECK_API_BASE || "https://cipherwake.io";
-const VERSION = "0.12.0";
+const VERSION = "0.14.2";
 
 // 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:
@@ -2076,6 +2076,7 @@ async function runTrustDiffCommand(args) {
     const body = await safeJSON(resp);
     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);
   }
 
@@ -2213,6 +2214,10 @@ async function runPreviewDiffCommand(args) {
     const body = await safeJSON(resp);
     console.error(color("red", `error: /api/preview-diff returned ${resp.status}`));
     if (body?.message) console.error(color("dim", body.message));
+    // Server-side may return a `hint` field on rejected inputs (e.g. localhost
+    // / private-IP URLs surface the tunnel-options hint). Print it so the
+    // user knows what to do next instead of just seeing the rejection.
+    if (body?.hint) console.error(color("dim", body.hint));
     process.exit(3);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pqcheck",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "HTTPS posture scanner with Preview Deploy Trust Diff for PRs, Trust Diff for CI, vendor lockfile + drift alerts, cross-tenant key map, and HNDL/quantum-decryption risk scoring. Free, no signup.",
   "keywords": [
     "post-quantum",