pqcheck 0.16.22 → 0.16.24

package/README.md

@@ -8,7 +8,7 @@
 [![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.22** — Drift gates, posture advises. Default `ship_decision` reverts to drift-only (the right per-deploy regression gate); posture grade is surfaced as a one-line advisory + ready-to-paste fix snippets, NOT as an auto-block. A site that's been D-posture for months hasn't regressed on today's deploy; gating it every time trains people to ignore the gate. Once your site reaches A/B posture, pass `--strict-posture` as the "lock it in, prevent backsliding" gate. New `ship_decision_drift` / `ship_decision_posture` / `ship_decision_mode` fields make both signals visible. [Full changelog →](./CHANGELOG.md)
+> **Latest: v0.16.24** — **Route Assertions (R87).** Closes the gap that left Cipherwake silent on backend/admin-heavy deploys. Declare your private routes in `.cipherwake.json` and Cipherwake asserts they're still gated on every deploy. Any critical failure (declared `protected`, actually `exposed`) blocks the deploy unconditionally — the catastrophic "/admin became public" case. Three sources merge: customer config + nearly-universal defaults + auto-detected from `robots.txt` and homepage. New `/methodology/route-assertions` documents the feature; `/methodology/why-not-authenticated-crawling` explains the design decision to never hold customer credentials. [Full changelog →](./CHANGELOG.md)
 
 ## Two ways to use it
 

package/bin/pqcheck.js

@@ -248,6 +248,14 @@ async function main() {
     }
   }
 
+  // R86.7 — reject unknown flags loudly. Catches typo'd safety-critical
+  // flags like `--strict` (was intended --strict-posture) that previously
+  // silently no-op'd, leaving customers with a false sense of security.
+  const unknown = assertKnownFlags(args, "pqcheck <domain>");
+  if (unknown) {
+    process.exit(3);
+  }
+
   const positional = args.filter((a) => !a.startsWith("-") && !isFlagValue(args, a));
   const domains = [...positional, ...fileDomains]
     .map((a) => normalizeDomain(a))
@@ -295,7 +303,13 @@ async function main() {
   // absolute posture grade into ship_decision. Recommended ONLY after a
   // site reaches A/B posture — opting in earlier produces cry-wolf gating
   // on every deploy since most AI-coded sites grade D/F out of the box.
-  const strictPosture = args.includes("--strict-posture");
+  // Accept both `--strict-posture` (explicit) and `--strict` (short alias).
+  // Audit caught a footgun where customers typed `--strict` expecting the
+  // posture gate to fire and got silent drift-only mode instead. The
+  // `onboard` subcommand uses `--strict` for a different purpose (gate exit
+  // code on step failure) but that's a separate command — the alias is
+  // scoped to scan / deploy-check / trust-diff only.
+  const strictPosture = args.includes("--strict-posture") || args.includes("--strict");
 
   // One-shot scan(s)
   let worstExit = 0;
@@ -747,6 +761,100 @@ function parseAiMode(args) {
   return args.includes("--ai") || args.includes("--agent");
 }
 
+// R86.7 (2026-06-04) — close the "silent no-op on unrecognized flag" class
+// of footguns. Audit caught --strict (intended --strict-posture) silently
+// degrading to drift-only mode without warning — the user believed they had
+// the hard posture gate on. Same family as false-green pins: looks like it's
+// doing something, silently isn't. The fix: validate every --foo token in
+// args against a known-flags whitelist and reject loudly on unknown flags
+// with a closest-match suggestion. For a security gate, "unknown flag →
+// silently proceed with weaker behaviour" must never happen.
+//
+// Scope: universal whitelist applied at scan / deploy-check / trust-diff /
+// preview-diff entry points. False acceptance of cross-command flags (e.g.
+// passing --preview to deploy-check) is the SAME failure mode as today
+// (silent ignore) — typo detection is the win. Per-command whitelists
+// would be more correct but the universal list covers the audit footgun.
+const KNOWN_FLAGS = new Set([
+  // Global / output mode
+  "--ai", "--agent", "--verbose", "--quiet", "--help", "--version", "--debug-network",
+  // Multi-domain
+  "--file", "--watch",
+  // Scan behaviour
+  "--fresh", "--force", "--threshold", "--webhook", "--json", "--csv", "--markdown",
+  "--sarif", "--gh-action", "--multi", "--lock", "--explain", "--plan", "--stdout",
+  // Posture gating (the audit catch)
+  "--strict", "--strict-posture",
+  // Format / output format
+  "--format",
+  // Trust-diff / deploy-check / preview-diff
+  "--baseline", "--fail-on", "--fail-on-new", "--guards", "--compare-transport",
+  "--write-baseline", "--preview", "--production",
+  // Setup / onboard / install consent
+  "--auto", "--manual", "--yes", "--no-open", "--domain", "--invoked-by",
+  "--consent-phrase", "--scope",
+  "--skip-checklist", "--skip-hook", "--skip-protocol", "--skip-scan",
+  "--skip-statusline", "--skip-vendors", "--skip-vscode", "--skip-workflow",
+]);
+
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  const m = a.length, n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  const row = new Array(m + 1);
+  for (let i = 0; i <= m; i++) row[i] = i;
+  for (let j = 1; j <= n; j++) {
+    let prev = row[0];
+    row[0] = j;
+    for (let i = 1; i <= m; i++) {
+      const tmp = row[i];
+      row[i] = a[i - 1] === b[j - 1]
+        ? prev
+        : 1 + Math.min(prev, row[i], row[i - 1]);
+      prev = tmp;
+    }
+  }
+  return row[m];
+}
+
+function suggestFlag(unknown) {
+  let best = null, bestDist = Infinity;
+  for (const known of KNOWN_FLAGS) {
+    const d = levenshtein(unknown, known);
+    if (d < bestDist) { bestDist = d; best = known; }
+  }
+  // Only suggest if reasonably close (≤ 3 edits or ≤ half the unknown's length)
+  const threshold = Math.max(3, Math.floor(unknown.length / 2));
+  return bestDist <= threshold ? best : null;
+}
+
+function assertKnownFlags(args, cmdName) {
+  const unknown = [];
+  for (const tok of args) {
+    if (typeof tok !== "string" || !tok.startsWith("--") || tok === "--") continue;
+    // Strip `--foo=bar` → `--foo` so equals-value forms validate against the bare flag
+    const flag = tok.includes("=") ? tok.slice(0, tok.indexOf("=")) : tok;
+    if (!KNOWN_FLAGS.has(flag)) unknown.push(flag);
+  }
+  if (unknown.length === 0) return null;
+  // Emit error to stderr with closest-match suggestion, return non-null
+  // sentinel so the caller can exit non-zero. We do NOT process.exit here
+  // because the AI-mode caller needs to emit a structured guard block
+  // before exiting (so AI agents parsing the block don't see a missing
+  // CIPHERWAKE_AI_GUARD_RESULT and fall through to a different error path).
+  for (const u of unknown) {
+    const sug = suggestFlag(u);
+    process.stderr.write(color("red", `error: unknown flag ${u} for ${cmdName}\n`));
+    if (sug) {
+      process.stderr.write(color("yellow", `       did you mean ${sug}?\n`));
+    } else {
+      process.stderr.write(color("dim", `       run \`npx pqcheck --help\` for the flag list.\n`));
+    }
+  }
+  return unknown;
+}
+
 function severityRank(s) {
   const map = { critical: 4, high: 3, medium: 2, low: 1, info: 0, none: -1 };
   return map[String(s || "none").toLowerCase()] ?? 0;
@@ -799,6 +907,147 @@ function combineShipDecision(driftDecision, postureDecision, { strict = false }
   return a >= b ? driftDecision : postureDecision;
 }
 
+// R87 (2026-06-05) — read .cipherwake.json from cwd OR a path the customer
+// pointed us at. Returns the parsed routeAssertions config or null.
+//
+// Customer-declared assertions are the wedge that makes Cipherwake fire on
+// EVERY deploy of a backend/admin-heavy app — even when the public landing
+// page doesn't drift. The CLI reads this file once + forwards it as the
+// `routeAssertionsConfig` field in the trust-diff/scan request body.
+//
+// We DO NOT read credentials or sensitive headers from this file. Just
+// route paths + expected classification. See /methodology/route-assertions
+// for the schema + /methodology/why-not-authenticated-crawling for the
+// strategic reasoning behind keeping this credential-free.
+// R87.4 (2026-06-05) — surface a clear warning when .cipherwake.json has
+// malformed JSON, an invalid shape, or an obviously-wrong path declaration.
+// Without these warnings, the CLI silently dropped the config and the user
+// saw `sources_customer=0` with no explanation. Wrong-shape configs are
+// the second-most-common UX failure after typo'd flags.
+function _warnConfigIssue(msg) {
+  process.stderr.write(color("yellow", `⚠ .cipherwake.json: ${msg}\n`));
+}
+
+async function readRouteAssertionsConfig() {
+  try {
+    const { readFileSync, existsSync } = await import("node:fs");
+    const { join, dirname } = await import("node:path");
+    const cwd = process.cwd();
+    // Walk up from cwd looking for .cipherwake.json — supports running
+    // from any subdirectory of the repo. Cap at 5 levels to bound IO.
+    let dir = cwd;
+    for (let i = 0; i < 5; i++) {
+      const candidate = join(dir, ".cipherwake.json");
+      if (existsSync(candidate)) {
+        const body = readFileSync(candidate, "utf8");
+        let parsed;
+        try {
+          parsed = JSON.parse(body);
+        } catch (e) {
+          _warnConfigIssue(`malformed JSON in ${candidate} (${e.message}). Customer assertions will not be sent.`);
+          return null;
+        }
+        // Tolerant shape: either { routeAssertions: {...} } or { assertions: [...] }
+        // at the top level. Both forms are documented in the methodology page.
+        const cfg = parsed?.routeAssertions || (Array.isArray(parsed?.assertions) ? { assertions: parsed.assertions, replace_defaults: parsed.replace_defaults } : null);
+        if (!cfg) {
+          _warnConfigIssue(`${candidate} found but missing required field "routeAssertions.assertions" (or top-level "assertions" array). See https://cipherwake.io/methodology/route-assertions for the schema.`);
+          return null;
+        }
+        if (!Array.isArray(cfg.assertions)) {
+          _warnConfigIssue(`"assertions" must be an array of {path, expect, ...} objects.`);
+          return null;
+        }
+        // R87.4 — normalize + validate each assertion. Catch common typos:
+        // missing leading slash, unknown `expect` value, duplicate paths.
+        const seen = new Set();
+        const cleaned = [];
+        for (let idx = 0; idx < cfg.assertions.length; idx++) {
+          const a = cfg.assertions[idx];
+          if (!a || typeof a !== "object") {
+            _warnConfigIssue(`assertion #${idx + 1} is not an object — skipped.`);
+            continue;
+          }
+          if (typeof a.path !== "string" || !a.path) {
+            _warnConfigIssue(`assertion #${idx + 1} missing "path" field — skipped.`);
+            continue;
+          }
+          // Normalize leading slash
+          let normPath = a.path.trim();
+          if (!normPath.startsWith("/")) {
+            _warnConfigIssue(`assertion path "${a.path}" missing leading "/" — auto-normalized to "/${normPath}".`);
+            normPath = "/" + normPath;
+          }
+          if (normPath.includes("?")) {
+            _warnConfigIssue(`assertion path "${normPath}" contains "?" — query strings are not supported in route assertions. Path probed without query.`);
+            normPath = normPath.split("?")[0];
+          }
+          const validExpects = ["protected", "exposed", "missing"];
+          if (!validExpects.includes(a.expect)) {
+            _warnConfigIssue(`assertion #${idx + 1} (path "${normPath}") has invalid "expect": ${JSON.stringify(a.expect)}. Must be one of: ${validExpects.join(", ")}. Skipped.`);
+            continue;
+          }
+          if (seen.has(normPath)) {
+            _warnConfigIssue(`duplicate path "${normPath}" in assertions — second occurrence ignored.`);
+            continue;
+          }
+          seen.add(normPath);
+          cleaned.push({ ...a, path: normPath });
+        }
+        if (cleaned.length === 0) {
+          _warnConfigIssue(`no valid assertions found after validation — customer config will not be sent.`);
+          return null;
+        }
+        return { ...cfg, assertions: cleaned };
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    return null;
+  } catch (e) {
+    _warnConfigIssue(`unexpected error reading config: ${e.message}`);
+    return null;
+  }
+}
+
+// R87 — fold customer route-assertion failures into ship_decision. Any
+// CRITICAL failure (declared `protected` route that is now `exposed`) blocks
+// the deploy unconditionally — this is the catastrophic "admin became
+// public" case the feature exists to catch. High/medium failures promote
+// to `review`.
+function shipDecisionFromAssertions(summary) {
+  if (!summary) return null;
+  if (summary.criticalFailures && summary.criticalFailures.length > 0) return "block";
+  if (summary.failed > 0) return "review";
+  return "pass";
+}
+
+// R87 — emit per-assertion outcomes in a parseable block. Stable format so
+// AI coders can route on the data; one line per assertion with
+// expected/actual + path so failures are obvious at a glance.
+function formatRouteAssertionsBlock(summary) {
+  if (!summary || !Array.isArray(summary.results) || summary.results.length === 0) return "";
+  const lines = ["", "CIPHERWAKE_ROUTE_ASSERTIONS"];
+  lines.push(`total=${summary.total}`);
+  lines.push(`passed=${summary.passed}`);
+  lines.push(`failed=${summary.failed}`);
+  lines.push(`critical_failures=${summary.criticalFailures.length}`);
+  lines.push(`sources_customer=${summary.sources.customer}`);
+  lines.push(`sources_default=${summary.sources.default}`);
+  lines.push(`sources_auto=${summary.sources.auto}`);
+  lines.push(`sources_auto_suppressed=${summary.sources.autoSuppressed || 0}`);
+  for (const r of summary.results) {
+    const status = r.passed ? "PASS" : "FAIL";
+    const sev = r.passed ? "info" : r.severity;
+    const why = r.why ? ` — ${r.why}` : "";
+    const errReason = r.errorReason ? ` reason=${r.errorReason}` : "";
+    lines.push(`${status} [${sev}] ${r.source}:${r.path} expected=${r.expected} actual=${r.actual} status=${r.status === null ? "?" : r.status}${errReason}${why}`);
+  }
+  lines.push("END_CIPHERWAKE_ROUTE_ASSERTIONS");
+  return color("dim", lines.join("\n"));
+}
+
 // R86.3 (2026-06-03) — emit per-finding fix snippets in a separate parseable
 // block after the AI guard block. The guard block stays compact key=value;
 // fixes are multi-line code so they get their own block with explicit
@@ -3365,10 +3614,16 @@ async function runScanBasedDeployCheck(domain, args) {
 }
 
 async function runTrustDiffCommand(args) {
+  // R86.7 — reject unknown flags before any other parsing. Same rationale
+  // as the bare-scan path: typo'd safety-critical flags must fail loud,
+  // not silently degrade.
+  if (assertKnownFlags(args, "pqcheck trust-diff")) {
+    process.exit(3);
+  }
   const positional = args.filter((a) => !a.startsWith("-") && !isFlagValue(args, a));
   if (positional.length === 0) {
     console.error(color("red", "error: pqcheck trust-diff requires a domain"));
-    console.error(color("dim", "Usage: npx pqcheck trust-diff <domain> [--baseline last-week] [--fail-on high] [--format pretty|json|sarif|github]"));
+    console.error(color("dim", "Usage: npx pqcheck trust-diff <domain> [--baseline last-week] [--fail-on high] [--format pretty|json|sarif|github] [--strict-posture]"));
     process.exit(3);
   }
   const domain = normalizeDomain(positional[0]);
@@ -3384,7 +3639,13 @@ async function runTrustDiffCommand(args) {
   // is drift-only (per-deploy regression gate); --strict-posture opts into
   // worst-of(drift, posture). Recommended only after a site reaches A/B
   // posture to lock that in.
-  const strictPosture = args.includes("--strict-posture");
+  // Accept both `--strict-posture` (explicit) and `--strict` (short alias).
+  // Audit caught a footgun where customers typed `--strict` expecting the
+  // posture gate to fire and got silent drift-only mode instead. The
+  // `onboard` subcommand uses `--strict` for a different purpose (gate exit
+  // code on step failure) but that's a separate command — the alias is
+  // scoped to scan / deploy-check / trust-diff only.
+  const strictPosture = args.includes("--strict-posture") || args.includes("--strict");
 
   // Build headers conditionally — Authorization is set ONLY if the user has
   // an API key. Without it, the server's applyRepoQuota falls through to the
@@ -3399,10 +3660,11 @@ async function runTrustDiffCommand(args) {
 
   let resp;
   try {
+    const _routeCfg = await readRouteAssertionsConfig();
     resp = await fetch(`${API_BASE}/api/trust-diff`, {
       method: "POST",
       headers,
-      body: JSON.stringify({ domain, baseline, fail_on: failOn }),
+      body: JSON.stringify({ domain, baseline, fail_on: failOn, routeAssertionsConfig: _routeCfg }),
     });
   } catch (err) {
     console.error(color("red", `error: network failure calling /api/trust-diff: ${err.message}`));
@@ -3536,17 +3798,41 @@ async function runTrustDiffCommand(args) {
     // R86.5 — surface posture advisory line in default (non-strict) mode.
     const postureAdvisory = formatPostureAdvisoryLine(posture, strictPosture);
     if (postureAdvisory) console.log(postureAdvisory);
+    // R87 (2026-06-05) — fold route-assertion failures into ship_decision.
+    // Customer-declared assertions are surfaced regardless; their critical
+    // failures (declared `protected` route that's now `exposed`) ALWAYS
+    // promote ship_decision to block — this is the catastrophic case the
+    // feature exists to catch ("admin went public") and it does not require
+    // --strict-posture or any opt-in. Default + auto-detected assertions
+    // follow the same gating rules.
+    const routeAssertions = currentReport?.routeAssertions || null;
+    const assertionShipImpact = shipDecisionFromAssertions(routeAssertions);
+    const effectiveShipWithAssertions = assertionShipImpact
+      ? (SHIP_DECISION_RANK[assertionShipImpact] > SHIP_DECISION_RANK[effectiveShip] ? assertionShipImpact : effectiveShip)
+      : effectiveShip;
+    const assertionFields = routeAssertions ? {
+      assertions_total: routeAssertions.total,
+      assertions_passed: routeAssertions.passed,
+      assertions_failed: routeAssertions.failed,
+      assertions_critical_failures: routeAssertions.criticalFailures.length,
+      assertions_sources: `customer=${routeAssertions.sources.customer},default=${routeAssertions.sources.default},auto=${routeAssertions.sources.auto},auto_suppressed=${routeAssertions.sources.autoSuppressed || 0}`,
+      assertion_top_failure: routeAssertions.criticalFailures[0]
+        ? `${routeAssertions.criticalFailures[0].path}: expected ${routeAssertions.criticalFailures[0].expected}, got ${routeAssertions.criticalFailures[0].actual}`
+        : undefined,
+    } : {};
+
     console.log(formatAiFooterBlock({
-      status: effectiveShip,
+      status: effectiveShipWithAssertions,
       domain,
       kind: "trust-diff",
       baseline,
       verdict,
       delta_count: deltas.length,
       max_severity: maxSev,
-      ship_decision: effectiveShip,
+      ship_decision: effectiveShipWithAssertions,
       ship_decision_drift: shipDecision,
       ship_decision_posture: posture?.decision,
+      ship_decision_assertions: assertionShipImpact,
       ship_decision_mode: strictPosture ? "strict_posture" : "drift_only",
       top_issue: topDelta?.id || topDelta?.type || "none",
       top_issue_title: topDelta?.title || undefined,
@@ -3556,12 +3842,14 @@ async function runTrustDiffCommand(args) {
       quota_limit: result.quota?.monthly_limit ?? undefined,
       scanned_at: new Date().toISOString(),
       advisory_only: "true",
-      scope: strictPosture ? "trust_surface_drift_plus_absolute_posture" : "trust_surface_drift",
-      scope_note: strictPosture
-        ? "ship_decision = worst-of(drift, absolute posture) because --strict-posture is set. pass means BOTH no drift AND posture grade A+/A. ship_decision_drift and ship_decision_posture expose the two inputs separately. Cipherwake does NOT verify app functionality — pair with Playwright e2e for full deploy safety."
-        : "ship_decision reflects DRIFT only by default (per-deploy regression gate). Posture grade is surfaced via posture_decision / ship_decision_posture as advisory — D/F posture does NOT auto-block. Once your site reaches A/B posture, pass --strict-posture to lock that in. Cipherwake does NOT verify app functionality.",
+      scope: strictPosture ? "trust_surface_drift_plus_absolute_posture_plus_route_assertions" : "trust_surface_drift_plus_route_assertions",
+      scope_note: "ship_decision = worst-of(drift, route_assertions" + (strictPosture ? ", absolute_posture)" : ")") + ". Route assertions verify your declared private routes (e.g. /api/admin) are still gated; any critical failure (protected route now exposed) blocks the deploy unconditionally. Posture is " + (strictPosture ? "also gated due to --strict-posture." : "advisory unless --strict-posture is set.") + " Cipherwake does NOT verify app functionality.",
+      ...assertionFields,
       ...postureFields,
     }));
+    if (routeAssertions) {
+      console.log(formatRouteAssertionsBlock(routeAssertions));
+    }
     if (posture && Array.isArray(posture.fixes) && posture.fixes.length > 0) {
       console.log(formatPostureFixesBlock(posture.fixes));
     }
@@ -3573,13 +3861,13 @@ async function runTrustDiffCommand(args) {
       score: typeof result.current_score === "number" ? result.current_score : null,
       grade: result.current_grade || null,
       max_severity: maxSev,
-      ship_decision: effectiveShip,
+      ship_decision: effectiveShipWithAssertions,
       baseline,
       delta_count: deltas.length,
       top_issue: topDelta?.id || topDelta?.title || null,
     });
 
-    process.exit(shipDecisionExitCode(effectiveShip));
+    process.exit(shipDecisionExitCode(effectiveShipWithAssertions));
   }
 
   // Format output
@@ -3881,6 +4169,11 @@ async function runGuardsRunCommand(args) {
 }
 
 async function runPreviewDiffCommand(args) {
+  // R86.7 — reject unknown flags before parsing. Closes the silent-no-op
+  // class of footguns for the preview-diff command too.
+  if (assertKnownFlags(args, "pqcheck preview-diff")) {
+    process.exit(3);
+  }
   const previewUrl = parseFlag(args, "--preview");
   const productionUrl = parseFlag(args, "--production");
   if (!previewUrl || !productionUrl) {

package/package.json

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