pqcheck 0.14.2 → 0.15.0

package/README.md

@@ -25,8 +25,49 @@ The same scanner that powers [cipherwake.io](https://cipherwake.io), the browser
 | `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. |
+| **`npx pqcheck guard --domain <D> -- <cmd>`** 🆕 | **Deploy guard wrapper.** Wraps any deploy command. Runs `deploy-check` first; conditionally runs `<cmd>` based on `ship_decision`. Modes: `--gate-mode balanced` (default) / `advisory` / `strict`. ONE command instead of two — the strongest single artifact for AI-coder workflows because the AI never has to remember to chain check + deploy. |
+| **`npx pqcheck protocol install`** 🆕 | **Opt-in installer** for the AI Coder Protocol — appends the pre-deploy verification rule to your `CLAUDE.md` / `.cursorrules` / `.aider.conf.yml` with explicit consent (Rule 17). One upfront question (auto / manual / no). Never silent writes. |
+| **`npx pqcheck setup --auto --domain <D>`** 🆕 | **One-command full setup for every AI coder.** Installs (idempotently): GitHub Action workflow, AI Coder Protocol across all detected rules files (Claude / Cursor / Copilot / Aider / Windsurf / Continue / Cline / AGENTS.md) using fenced markers (`<!-- CIPHERWAKE_AI_CODER_PROTOCOL_START/END -->`), git pre-push hook, Claude Code statusLine + chat-hook (PostToolUse Bash). Skip flags available. Backups taken before any `~/.claude/settings.json` write. Audit trail at `~/.config/cipherwake/install-prefs.json`; install manifest at `~/.config/cipherwake/install-manifest.json`. |
+| **`npx pqcheck setup --plan --domain <D>`** 🆕 | **Dry-run mode.** Prints every file change `--auto` would make (target paths + operation type: create / append-markered / deep-merge / backup-first) without writing anything. Run this first when you're not sure what `--auto` will touch. |
+| **`npx pqcheck debug-network`** 🆕 | **Connectivity diagnostic.** Probes cipherwake.io API, homepage, crt.sh upstream, and the direct Vercel URL (bypassing Cloudflare). Reports HTTP status + timing per hop. Use when "scan hung" / "command not found" / corporate proxy issues come up — surfaces the actual broken hop with an actionable cause list. |
+| **`--ai` flag** (any of the above) | **AI Coder Mode** (0.15.0). Three-layer output (banner / body / structured `CIPHERWAKE_AI_GUARD_RESULT` block) tuned for Claude Code / Cursor / Aider / Zed. Includes a `ship_decision=pass\|review\|block` field your AI coworker parses to decide whether to announce the deploy, ask you, or revert. See [/methodology/ai-coder-mode](https://cipherwake.io/methodology/ai-coder-mode). |
 
-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.
+Free tier covers all of the above within 100 Trust Diff calls/month per repo via OIDC. **Founder Pro** ($19.99/mo, locked while subscription active) raises that to 5,000 calls/month + unlocks custom thresholds, vendor lockfile, CI fail rules, and 5 watched domains. Single-domain scans (`npx pqcheck <domain>`) are anonymous + rate-limited per IP — no account or key needed. `npx pqcheck deploy-check <domain> --ai` also works fully anonymously for first-deploy gating.
+
+### AI Coder Mode in 30 seconds
+
+```bash
+npx pqcheck cipherwake.io --ai
+```
+
+Output:
+
+```
+◆ cipherwake · scan · ⚠ REVIEW · cipherwake.io · DBR 4.1 C · HIGH · ship_decision=review
+
+Top finding:
+  [HIGH] ECDHE-only — quantum-vulnerable key exchange
+
+Why it matters:
+  Forward-secret against classical attackers. Shor's algorithm decrypts
+  recorded handshakes once a CRQC exists.
+
+Recommended next action:
+  Review finding above and decide if it was intentional.
+  View full report: https://cipherwake.io/r/cipherwake.io
+  Re-scan with --fresh after fix: npx pqcheck cipherwake.io --fresh --ai
+
+CIPHERWAKE_AI_GUARD_RESULT
+status=review
+domain=cipherwake.io
+ship_decision=review
+max_severity=high
+top_issue=tls.ecdhe_only_quantum_vulnerable
+advisory_only=true
+END_CIPHERWAKE_AI_GUARD_RESULT
+```
+
+The structured block is what your AI coworker (Claude / Cursor / Aider / Zed) parses to decide whether to announce the deploy, ask you, or revert. Exit code in `--ai` mode reflects `ship_decision`: `0` pass · `1` review · `2` block.
 
 ---
 
@@ -56,7 +97,7 @@ git push
 
 That's it. The scaffolded workflow includes `permissions: id-token: write`, so the runner mints a signed OIDC token on each run and Cipherwake meters per repo — no secret to manage. Open a PR and Cipherwake comments inline when cert / SPKI / HSTS / CSP / DMARC / vendor scripts drift since your baseline.
 
-**Need higher limits?** Paid tiers (Starter $29/mo · Growth $79/mo · Scale $199/mo) lift the per-repo quota to 1,000 / 10,000 / 50,000 calls/month. Generate an API key at [/account#api-keys](https://cipherwake.io/account#api-keys), then add it as the repo secret `CIPHERWAKE_API_KEY`. The Action uses the secret when present and falls back to OIDC when not — no code change needed to upgrade.
+**Need higher limits?** **Founder Pro ($19.99/mo)** lifts the per-repo quota to 5,000 calls/month and unlocks custom thresholds, the approved-vendor allowlist, vendor lockfile, CI fail rules, and 5 watched domains. Generate an API key at [/account#api-keys](https://cipherwake.io/account#api-keys), then add it as the repo secret `CIPHERWAKE_API_KEY`. The Action uses the secret when present and falls back to OIDC when not — no code change needed to upgrade. *Founder pricing is locked while your subscription remains active.*
 
 **Want more?**
 - Pre-commit hook: `npx pqcheck deploy-check <domain>` before every deploy
@@ -77,7 +118,7 @@ npx pqcheck trust-diff mycompany.com --baseline last-week --fail-on high
 
 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.
 
-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.
+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; **Founder Pro** honors `--fail-on` for real CI gating.
 
 ### Preview Trust Diff — PR-time URL-vs-URL comparison
 
@@ -131,7 +172,7 @@ Like `package-lock.json`, but for the third-party scripts that load on your doma
 ```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
+npx pqcheck vendors sync mycompany.com      # Founder Pro — 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.
@@ -182,8 +223,14 @@ npx pqcheck init                              Interactive scaffold for .github/w
 npx pqcheck release-checklist [domain]        Pre-release trust checklist (markdown, offline)
 npx pqcheck vendors export <domain>           Write cipherwake.vendors.json from observed third-party scripts
 npx pqcheck vendors check <domain>            CI gate; exit 4 on new origins not in lockfile
-npx pqcheck vendors sync <domain>             Pull dashboard allowlist into lockfile (Starter+, needs API key)
+npx pqcheck vendors sync <domain>             Pull dashboard allowlist into lockfile (Founder Pro, needs API key)
 npx pqcheck watch <domain>                    Add domain to your watched list (needs CIPHERWAKE_API_KEY)
+npx pqcheck guard --domain <D> -- <cmd>       AI Coder Mode (0.15.0) — wrap any deploy command with a Trust Diff gate
+npx pqcheck deploy-check <D> --ai             AI Coder Mode (0.15.0) — frictionless first-deploy, anonymous, emits CIPHERWAKE_AI_GUARD_RESULT block
+npx pqcheck setup --auto --domain <D>         AI Coder Mode (0.15.0) — one-command install across CLAUDE.md/.cursorrules/.github + git pre-push hook + statusline
+npx pqcheck setup --plan --domain <D>         AI Coder Mode (0.15.0) — dry-run: print every file change before --auto writes anything
+npx pqcheck protocol install --auto           AI Coder Mode (0.15.0) — append AI Coder Protocol to detected rules files (idempotent, fenced markers)
+npx pqcheck debug-network                     Probe upstream connectivity (cipherwake.io / crt.sh / Vercel) — for "scan hung" diagnosis
 ```
 
 ### Multi-domain

package/bin/cipherwake-chat-hook.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// =============================================================================
+// cipherwake-chat-hook — Claude Code PostToolUse hook
+// =============================================================================
+// Reads stdin (tool event JSON from Claude Code), checks if the tool was a
+// pqcheck-related Bash command, reads the latest scan state, emits a
+// systemMessage to Claude Code chat.
+//
+// Wire it up by adding to ~/.claude/settings.json:
+//
+//   "hooks": {
+//     "PostToolUse": [{
+//       "matcher": "Bash",
+//       "hooks": [{
+//         "type": "command",
+//         "command": "npx cipherwake-chat-hook"
+//       }]
+//     }]
+//   }
+//
+// `pqcheck setup --auto` does this for you (idempotently, merging with any
+// existing hook configs per CLAUDE.md Rule 17).
+//
+// Behavior:
+//   * Only emits a message if the tool was Bash + the command invoked pqcheck
+//   * Only emits if last-scan.json was updated within the last 60s (i.e. this
+//     pqcheck invocation actually changed state) — avoids spamming chat for
+//     stale state
+//   * Single line output for status-bar-style readability
+// =============================================================================
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// Hooks receive event JSON on stdin. If missing / malformed, exit silently.
+let toolEvent;
+try {
+  toolEvent = JSON.parse(readFileSync(0, "utf8"));
+} catch {
+  process.exit(0);
+}
+
+// Only react to Bash tool uses that invoked pqcheck or cipherwake-statusline.
+if (toolEvent?.tool_name !== "Bash") {
+  process.exit(0);
+}
+const command = String(toolEvent.tool_input?.command || "");
+const isPqcheck =
+  /\bpqcheck\b/.test(command) ||
+  /\bcipherwake-statusline\b/.test(command);
+if (!isPqcheck) {
+  process.exit(0);
+}
+
+// Read the last-scan state. If missing, exit silently.
+let state;
+try {
+  state = JSON.parse(
+    readFileSync(join(homedir(), ".config", "cipherwake", "last-scan.json"), "utf8"),
+  );
+} catch {
+  process.exit(0);
+}
+
+// Only emit if the state was updated recently (<60s). Otherwise we'd narrate
+// stale state on every unrelated Bash command, which would be obnoxious.
+const writtenAt = new Date(state.written_at).getTime();
+if (!Number.isFinite(writtenAt)) process.exit(0);
+if (Date.now() - writtenAt > 60_000) process.exit(0);
+
+const sd = state.ship_decision || "—";
+const emoji = sd === "pass" ? "✓" : sd === "block" ? "✗" : "⚠";
+
+const parts = [`◆ Cipherwake: ${emoji} ${state.domain} ship_decision=${sd}`];
+if (typeof state.score === "number") parts.push(`DBR ${state.score.toFixed(1)}${state.grade ? " " + state.grade : ""}`);
+if (state.max_severity && state.max_severity !== "none") parts.push(String(state.max_severity).toUpperCase());
+if (state.top_issue && state.top_issue !== "none") parts.push(`top: ${state.top_issue}`);
+
+const message = parts.join(" · ");
+
+// Output JSON to stdout — Claude Code reads the `systemMessage` field and
+// displays it to the user in the chat scrollback.
+process.stdout.write(
+  JSON.stringify({
+    systemMessage: message,
+    suppressOutput: true,
+  }),
+);
+process.exit(0);

package/bin/cipherwake-statusline.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// =============================================================================
+// cipherwake-statusline — reads ~/.config/cipherwake/last-scan.json and outputs
+// a single-line summary for AI-coder status surfaces.
+// =============================================================================
+// Designed for Claude Code's `statusLine` setting (a config-level hook that
+// runs any shell command and renders its stdout in the persistent status line).
+// One-line install:
+//
+//   add to ~/.claude/settings.json:
+//   { "statusLine": { "type": "command", "command": "npx cipherwake-statusline" } }
+//
+// Cipherwake never modifies your settings.json — paste the line yourself per
+// CLAUDE.md Rule 17 (consolidated consent for any change outside our own
+// config dir).
+//
+// The script is dependency-free + fast (<50ms on cold start) because Claude
+// Code calls it on every turn. Reads a single file, formats one line, exits.
+// =============================================================================
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const STATE_FILE = join(homedir(), ".config", "cipherwake", "last-scan.json");
+const STALE_THRESHOLD_HOURS = 24;
+
+const C = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  cyan: "\x1b[36m",
+};
+
+function formatAge(iso) {
+  if (!iso) return "—";
+  const ms = Date.now() - new Date(iso).getTime();
+  if (ms < 0) return "just now";
+  if (ms < 60_000) return "just now";
+  const min = Math.floor(ms / 60_000);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  const d = Math.floor(hr / 24);
+  return `${d}d ago`;
+}
+
+function ageHours(iso) {
+  if (!iso) return Infinity;
+  return (Date.now() - new Date(iso).getTime()) / (60 * 60 * 1000);
+}
+
+// --no-color / NO_COLOR support per https://no-color.org
+const noColor = process.argv.includes("--no-color") || process.env.NO_COLOR;
+function c(color, str) {
+  if (noColor) return str;
+  return `${color}${str}${C.reset}`;
+}
+
+let state;
+try {
+  state = JSON.parse(readFileSync(STATE_FILE, "utf8"));
+} catch {
+  // No scan yet — render an onboarding hint so first-time users learn the
+  // command. Use the dim color so it doesn't dominate the status line.
+  process.stdout.write(
+    c(C.dim, "◆ cipherwake · no scan yet · ") + c(C.cyan, "npx pqcheck <domain> --ai")
+  );
+  process.exit(0);
+}
+
+const { domain, score, grade, ship_decision, written_at, max_severity, kind } = state;
+const age = ageHours(written_at);
+
+if (age > STALE_THRESHOLD_HOURS) {
+  const stalePart = c(C.dim, `◆ ${domain || "cipherwake"} · stale (${formatAge(written_at)})`);
+  const hintPart = c(C.cyan, `npx pqcheck ${domain || "<domain>"} --ai`);
+  process.stdout.write(`${stalePart} · ${hintPart}`);
+  process.exit(0);
+}
+
+const symbolByDecision = { pass: "✓", review: "⚠", block: "✗" };
+const colorByDecision = { pass: C.green, review: C.yellow, block: C.red };
+const symbol = symbolByDecision[ship_decision] || "·";
+const cdec = colorByDecision[ship_decision] || C.dim;
+
+const dbrStr = typeof score === "number" ? `DBR ${score.toFixed(1)}` : "";
+const gradeStr = grade ? grade : "";
+const sevStr = max_severity && max_severity !== "none"
+  ? `· ${String(max_severity).toUpperCase()}`
+  : "";
+const kindStr = kind && kind !== "scan" ? `· ${kind}` : "";
+
+// Final layout (color-coded; ANSI stripped under --no-color / NO_COLOR=1):
+//   ◆ <domain> ✓|⚠|✗ ship_decision · DBR X.X grade · SEVERITY · kind · age
+process.stdout.write(
+  c(cdec, "◆") +
+    " " +
+    c(C.bold, domain || "cipherwake") +
+    " " +
+    c(cdec, `${symbol} ${(ship_decision || "—").toUpperCase()}`) +
+    " " +
+    c(C.dim, `· ${dbrStr}${gradeStr ? " " + gradeStr : ""} ${sevStr} ${kindStr} · ${formatAge(written_at)}`)
+);