pqcheck 0.16.23 → 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.23** — Closes the silent-no-op flag class. `--strict` now aliases `--strict-posture` in scan / deploy-check / trust-diff (audit caught the typo silently degrading to drift-only). And unknown flags now reject loudly with a closest-match suggestion + non-zero exit — `--stict-posture` (typo) → `error: did you mean --strict-posture?` instead of silently no-op'ing. Same principle applied to ourselves that Cipherwake exists to enforce for customers: a security tool can never silently proceed with weaker behaviour on an unrecognized signal. [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

@@ -907,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
@@ -3519,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}`));
@@ -3656,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,
@@ -3676,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));
     }
@@ -3693,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

package/package.json

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