pqcheck 0.16.23 → 0.16.28

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.28** — Cipherwake is now the independent gate that fires on every deploy. Catches: broken deploys (5xx / framework error / blank / landmark missing), leaked secrets (AWS / GitHub / Stripe / OpenAI / Supabase service-role JWTs with FP-discrimination that ignores `NEXT_PUBLIC_` / `pk_*` / anon JWTs), dropped cookie flags (HttpOnly / Secure / SameSite), missing required HTTP headers, sensitive-file leaks (`.env` / `.git/config` / `/api/debug`), **new public routes since last deploy** (AI accidentally shipped `/api/internal`), **new third-party scripts** (supply-chain alert), and **TLS cert expiring soon**. Blocks the deploy before the AI announces it. Local stats (`pqcheck stats`) — your results stay on your machine, no telemetry. All in-lane: public surface, no credentials, provider-neutral. [Full changelog →](./CHANGELOG.md)
 
 ## Two ways to use it
 

package/bin/pqcheck.js

@@ -188,6 +188,17 @@ async function main() {
   if (args[0] === "init") {
     return runInitCommand(args.slice(1));
   }
+  // R89.LOCAL — local-only stats commands. Read/write .cipherwake/stats.json
+  // in the repo root. ZERO network requests. Privacy-by-design.
+  if (args[0] === "stats") {
+    return runStatsCommand(args.slice(1));
+  }
+  if (args[0] === "dismiss") {
+    return runDismissCommand(args.slice(1));
+  }
+  if (args[0] === "confirm") {
+    return runConfirmCommand(args.slice(1));
+  }
   if (args[0] === "deploy-check") {
     return runDeployCheckCommand(args.slice(1));
   }
@@ -907,6 +918,271 @@ 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;
+          }
+          // R87.6 — validate bodyContains / bodyAbsent if present.
+          if (a.bodyContains !== undefined && typeof a.bodyContains !== "string" && !(Array.isArray(a.bodyContains) && a.bodyContains.every((s) => typeof s === "string"))) {
+            _warnConfigIssue(`assertion #${idx + 1} (path "${normPath}") has invalid "bodyContains" — must be a string or array of strings. Body check disabled for this assertion.`);
+            delete a.bodyContains;
+          }
+          if (a.bodyAbsent !== undefined && typeof a.bodyAbsent !== "string" && !(Array.isArray(a.bodyAbsent) && a.bodyAbsent.every((s) => typeof s === "string"))) {
+            _warnConfigIssue(`assertion #${idx + 1} (path "${normPath}") has invalid "bodyAbsent" — must be a string or array of strings. Body check disabled for this assertion.`);
+            delete a.bodyAbsent;
+          }
+          if ((a.bodyContains !== undefined || a.bodyAbsent !== undefined) && a.expect !== "protected") {
+            _warnConfigIssue(`assertion #${idx + 1} (path "${normPath}") has body assertions but expect=${JSON.stringify(a.expect)}. Body checks only run on expect=protected.`);
+          }
+          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`.
+// R89.G (2026-06-05) — narrative line for every scan. The reason "drift-only"
+// feels not-worth-paying-for is the silent-on-pass UX. A one-liner narrative
+// on every scan ("Public surface since last deploy: 0 routes changed, 0
+// headers regressed, deploy healthy") makes the gate FEEL alive even when
+// it's green. The AI coder reads this in the response and can surface it
+// to the user in plain English.
+function buildTrustDiffNarrative({ deltaCount, assertionsFailedCount, assertionsCriticalCount, deployStatus, secretsCriticalCount, secretsFindingsTotal, cookieFailedCount, headerFailedCount, posture }) {
+  const bits = [];
+  // Lead with the catastrophic items first
+  if (secretsCriticalCount > 0) bits.push(`${secretsCriticalCount} leaked secret${secretsCriticalCount === 1 ? "" : "s"} in JS bundle`);
+  if (deployStatus && deployStatus !== "healthy" && deployStatus !== "unreachable") {
+    bits.push(`deploy ${deployStatus.replace(/_/g, " ")}`);
+  }
+  if (assertionsCriticalCount > 0) bits.push(`${assertionsCriticalCount} declared route${assertionsCriticalCount === 1 ? "" : "s"} regressed`);
+  if (cookieFailedCount > 0) bits.push(`${cookieFailedCount} cookie flag${cookieFailedCount === 1 ? "" : "s"} weakened`);
+  if (headerFailedCount > 0) bits.push(`${headerFailedCount} required header${headerFailedCount === 1 ? "" : "s"} missing`);
+  if (deltaCount > 0) bits.push(`${deltaCount} trust-surface change${deltaCount === 1 ? "" : "s"} since baseline`);
+  if (assertionsFailedCount > 0 && assertionsCriticalCount === 0) bits.push(`${assertionsFailedCount} route assertion${assertionsFailedCount === 1 ? "" : "s"} for review`);
+  if (secretsFindingsTotal > secretsCriticalCount) bits.push(`${secretsFindingsTotal - secretsCriticalCount} non-critical secret finding${(secretsFindingsTotal - secretsCriticalCount) === 1 ? "" : "s"}`);
+  if (bits.length === 0) {
+    return `Public surface since last deploy: no drift, all declared invariants pass${deployStatus === "healthy" ? ", deploy healthy" : ""}${posture ? `, posture ${posture}` : ""}.`;
+  }
+  return `Public surface since last deploy: ${bits.join("; ")}${deployStatus === "healthy" ? " (homepage healthy)" : ""}.`;
+}
+
+function shipDecisionFromAssertions(summary) {
+  if (!summary) return null;
+  // R89/R88 wave 2 + R90 — fold in deploy health + secrets + cookies + headers + TLS.
+  // Critical case auto-blocks; any non-critical failure promotes to review.
+  const deployBroken = summary.deployHealth && summary.deployHealth.status !== "healthy" && summary.deployHealth.status !== "unreachable";
+  const secretsLeaked = summary.secrets && summary.secrets.criticalCount > 0;
+  const cookieCritical = (summary.cookieCriticalFailures || 0) > 0;
+  const tlsCritical = summary.tlsExpiry && !summary.tlsExpiry.passed && summary.tlsExpiry.severity === "critical";
+  if ((summary.criticalFailures && summary.criticalFailures.length > 0) ||
+      (summary.headerCriticalFailures && summary.headerCriticalFailures.length > 0) ||
+      deployBroken || secretsLeaked || cookieCritical || tlsCritical) {
+    return "block";
+  }
+  const headerFailed = (summary.headerResults || []).filter((r) => !r.passed).length;
+  const cookieFailed = (summary.cookieResults || []).filter((r) => !r.passed).length;
+  const secretsFound = summary.secrets && summary.secrets.findings && summary.secrets.findings.length > 0;
+  const tlsFailed = summary.tlsExpiry && !summary.tlsExpiry.passed;
+  if (summary.failed > 0 || headerFailed > 0 || cookieFailed > 0 || secretsFound || tlsFailed) 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}`);
+  lines.push(`sources_dismissed=${summary.sources.dismissed || 0}`);
+  // R88 — header invariants block alongside route assertions
+  if (Array.isArray(summary.headerResults) && summary.headerResults.length > 0) {
+    lines.push("--- HEADER INVARIANTS ---");
+    lines.push(`header_total=${summary.headerResults.length}`);
+    lines.push(`header_passed=${summary.headerResults.filter((r) => r.passed).length}`);
+    lines.push(`header_failed=${summary.headerResults.filter((r) => !r.passed).length}`);
+    lines.push(`header_critical_failures=${(summary.headerCriticalFailures || []).length}`);
+    for (const h of summary.headerResults) {
+      const status = h.passed ? "PASS" : "FAIL";
+      const sev = h.passed ? "info" : h.severity;
+      const wantVal = h.expectedValue ? `="${h.expectedValue}"` : "";
+      const gotVal = h.actualValue !== null && h.actualValue !== undefined ? `, got "${String(h.actualValue).slice(0, 80)}"` : ", got <absent>";
+      const why = h.why ? ` — ${h.why}` : "";
+      lines.push(`${status} [${sev}] header:${h.header} expect=${h.expect}${wantVal}${gotVal}${why}`);
+    }
+  }
+  // R89 — deploy-health check
+  if (summary.deployHealth) {
+    const dh = summary.deployHealth;
+    lines.push("--- DEPLOY HEALTH ---");
+    lines.push(`deploy_status=${dh.status}`);
+    lines.push(`deploy_http_status=${dh.httpStatus === null ? "?" : dh.httpStatus}`);
+    lines.push(`deploy_body_bytes=${dh.bodyBytes}`);
+    if (dh.matchedErrorMarker) lines.push(`deploy_matched_error_marker=${dh.matchedErrorMarker}`);
+    if (dh.missingLandmark) lines.push(`deploy_missing_landmark=${dh.missingLandmark}`);
+    if (dh.errorReason) lines.push(`deploy_error_reason=${dh.errorReason}`);
+    lines.push(`deploy_summary=${dh.summary}`);
+  }
+  // R88 wave 2 — secret scanner
+  if (summary.secrets) {
+    const s = summary.secrets;
+    lines.push("--- SECRET SCAN ---");
+    lines.push(`secrets_scanned=${s.scanned}`);
+    lines.push(`secrets_bundles_fetched=${s.bundlesFetched}`);
+    lines.push(`secrets_findings_total=${s.findings.length}`);
+    lines.push(`secrets_critical_count=${s.criticalCount}`);
+    for (const f of s.findings) {
+      lines.push(`FAIL [${f.severity}] secret:${f.patternId} source=${f.source} redacted=${f.redactedSample} — ${f.name}`);
+    }
+  }
+  // R90 — TLS cert expiry invariant
+  if (summary.tlsExpiry) {
+    const t = summary.tlsExpiry;
+    lines.push("--- TLS EXPIRY ---");
+    lines.push(`tls_checked=${t.checked}`);
+    lines.push(`tls_days_remaining=${t.daysRemaining === null ? "?" : t.daysRemaining}`);
+    lines.push(`tls_min_required=${t.minRequired}`);
+    lines.push(`tls_passed=${t.passed}`);
+    lines.push(`tls_summary=${t.summary}`);
+  }
+  // R88 wave 2 — cookie invariants
+  if (Array.isArray(summary.cookieResults) && summary.cookieResults.length > 0) {
+    lines.push("--- COOKIE INVARIANTS ---");
+    lines.push(`cookie_total=${summary.cookieResults.length}`);
+    lines.push(`cookie_passed=${summary.cookieResults.filter((r) => r.passed).length}`);
+    lines.push(`cookie_failed=${summary.cookieResults.filter((r) => !r.passed).length}`);
+    lines.push(`cookie_critical_failures=${summary.cookieCriticalFailures || 0}`);
+    for (const c of summary.cookieResults) {
+      const status = c.passed ? "PASS" : "FAIL";
+      const sev = c.passed ? "info" : c.severity;
+      const matched = c.matchedCookies.length > 0 ? c.matchedCookies.join(",") : "<no matching cookies>";
+      const why = c.why ? ` — ${c.why}` : "";
+      if (c.failures.length === 0) {
+        lines.push(`${status} [${sev}] cookie:${c.namePattern} matched=${matched}${why}`);
+      } else {
+        for (const f of c.failures) {
+          lines.push(`FAIL [${sev}] cookie:${c.namePattern} cookie=${f.cookieName} reason=${f.reason}${why}`);
+        }
+      }
+    }
+  }
+  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}` : "";
+    const bodyTag = r.bodyCheck && r.bodyCheck !== "body_check_skipped" ? ` body=${r.bodyCheck}` : "";
+    lines.push(`${status} [${sev}] ${r.source}:${r.path} expected=${r.expected} actual=${r.actual} status=${r.status === null ? "?" : r.status}${errReason}${bodyTag}${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 +3795,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 +3933,67 @@ 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;
+    // R88 wave 2 + R89 — fold in deploy health, secrets, cookies.
+    const dh = routeAssertions?.deployHealth || null;
+    const sc = routeAssertions?.secrets || null;
+    const cr2 = routeAssertions?.cookieResults || null;
+    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},dismissed=${routeAssertions.sources.dismissed || 0}`,
+      assertion_top_failure: routeAssertions.criticalFailures[0]
+        ? `${routeAssertions.criticalFailures[0].path}: expected ${routeAssertions.criticalFailures[0].expected}, got ${routeAssertions.criticalFailures[0].actual}`
+        : undefined,
+      // Deploy health
+      deploy_status: dh?.status,
+      deploy_http_status: dh?.httpStatus,
+      deploy_summary: dh?.summary?.slice(0, 200),
+      ship_decision_health: dh && dh.status !== "healthy" && dh.status !== "unreachable" ? "block" : (dh ? "pass" : undefined),
+      // Secret scanner
+      secrets_scanned: sc?.scanned,
+      secrets_findings_total: sc?.findings?.length,
+      secrets_critical_count: sc?.criticalCount,
+      ship_decision_secrets: sc && sc.criticalCount > 0 ? "block" : (sc && sc.findings.length > 0 ? "review" : (sc ? "pass" : undefined)),
+      // Cookie invariants
+      cookie_failed: cr2 ? cr2.filter((c) => !c.passed).length : undefined,
+      cookie_critical_failures: routeAssertions.cookieCriticalFailures || 0,
+      ship_decision_cookies: cr2 && cr2.length > 0
+        ? (routeAssertions.cookieCriticalFailures > 0 ? "block" : (cr2.filter((c) => !c.passed).length > 0 ? "review" : "pass"))
+        : undefined,
+      // R90 — TLS expiry
+      tls_days_remaining: routeAssertions.tlsExpiry?.daysRemaining,
+      tls_passed: routeAssertions.tlsExpiry?.passed,
+      ship_decision_tls: routeAssertions.tlsExpiry?.checked
+        ? (routeAssertions.tlsExpiry.passed ? "pass" : (routeAssertions.tlsExpiry.severity === "critical" ? "block" : "review"))
+        : 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 +4003,64 @@ 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_plus_health" : "trust_surface_drift_plus_route_assertions_plus_health",
+      scope_note: "ship_decision = worst-of(drift, route_assertions, deploy_health, secret_scan, cookie_invariants" + (strictPosture ? ", absolute_posture)" : ")") + ". Cipherwake checked the public trust surface independently of what your AI coder claims; this is the gate that should fire before the AI announces a deploy. Cipherwake does NOT verify app functionality.",
+      narrative: routeAssertions
+        ? buildTrustDiffNarrative({
+            deltaCount: deltas.length,
+            assertionsFailedCount: routeAssertions.failed,
+            assertionsCriticalCount: routeAssertions.criticalFailures.length,
+            deployStatus: routeAssertions.deployHealth?.status,
+            secretsCriticalCount: routeAssertions.secrets?.criticalCount || 0,
+            secretsFindingsTotal: routeAssertions.secrets?.findings?.length || 0,
+            cookieFailedCount: (routeAssertions.cookieResults || []).filter((c) => !c.passed).length,
+            headerFailedCount: (routeAssertions.headerResults || []).filter((r) => !r.passed).length,
+            posture: posture?.grade,
+          })
+        : undefined,
+      ...assertionFields,
       ...postureFields,
     }));
+    if (routeAssertions) {
+      console.log(formatRouteAssertionsBlock(routeAssertions));
+      // R89.LOCAL — persist local stats. ZERO network requests.
+      // R90 — also record surface snapshot for B/C (new-routes / new-scripts diff)
+      try {
+        const { recordResults, recordSurfaceSnapshot } = await import(new URL("./statsTracker.js", import.meta.url).href);
+        await recordResults(extractStatsEntries(routeAssertions));
+        // Extract publicRoutes + thirdPartyHosts from the report for snapshot
+        const publicRoutes = Array.isArray(currentReport?.publicRoutes?.paths)
+          ? currentReport.publicRoutes.paths.filter((p) => p.classification === "public").map((p) => p.path)
+          : [];
+        const thirdPartyHosts = Array.isArray(currentReport?.publicDeps?.thirdParties)
+          ? [...new Set(currentReport.publicDeps.thirdParties.map((t) => t.host).filter(Boolean))]
+          : [];
+        const certDaysToExpiry = typeof currentReport?.publicSurface?.daysUntilCertExpiry === "number"
+          ? currentReport.publicSurface.daysUntilCertExpiry
+          : null;
+        const surfaceDiff = await recordSurfaceSnapshot({ domain, publicRoutes, thirdPartyHosts, certDaysToExpiry });
+        if (surfaceDiff && (surfaceDiff.newRoutes.length > 0 || surfaceDiff.newHosts.length > 0 || surfaceDiff.removedRoutes.length > 0 || surfaceDiff.removedHosts.length > 0)) {
+          console.log("");
+          console.log(color("dim", "CIPHERWAKE_SURFACE_DIFF"));
+          console.log(color("dim", `prev_snapshot_at=${surfaceDiff.prevSnapshotAt}`));
+          for (const r of surfaceDiff.newRoutes) {
+            console.log(color("yellow", `NEW_PUBLIC_ROUTE: ${r}  — was not publicly reachable in last deploy. Review intent.`));
+          }
+          for (const r of surfaceDiff.removedRoutes) {
+            console.log(color("dim", `REMOVED_PUBLIC_ROUTE: ${r}  — was publicly reachable in last deploy.`));
+          }
+          for (const h of surfaceDiff.newHosts) {
+            console.log(color("red", `NEW_THIRD_PARTY_SCRIPT: ${h}  — supply-chain alert: a new third-party script appeared on your homepage since last deploy. Verify intent (vendor add) or investigate (injection / compromise).`));
+          }
+          for (const h of surfaceDiff.removedHosts) {
+            console.log(color("dim", `REMOVED_THIRD_PARTY_SCRIPT: ${h}  — third-party script removed since last deploy.`));
+          }
+          console.log(color("dim", "END_CIPHERWAKE_SURFACE_DIFF"));
+        }
+      } catch {
+        // never block on stats failures
+      }
+    }
     if (posture && Array.isArray(posture.fixes) && posture.fixes.length > 0) {
       console.log(formatPostureFixesBlock(posture.fixes));
     }
@@ -3693,13 +4072,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
@@ -4789,6 +5168,132 @@ function renderReleaseChecklist(domain, opts = {}) {
 const VALID_FAIL_ON = ["any", "low", "medium", "high", "critical"];
 const VALID_BASELINES = ["last-week", "last-month", "last-scan"];
 
+// R89.LOCAL — `pqcheck stats` reads .cipherwake/stats.json + prints
+// per-check stats. ZERO network requests. Privacy-by-design.
+async function runStatsCommand(args) {
+  const { loadStats, formatStatsTable } = await import(new URL("./statsTracker.js", import.meta.url).href);
+  const stats = await loadStats();
+  console.log(formatStatsTable(stats));
+  console.log("");
+  console.log(color("dim", "Stats are local-only. They never leave your machine. Add .cipherwake/ to .gitignore if you don't want to commit them."));
+}
+
+async function runDismissCommand(args) {
+  const id = args[0];
+  if (!id) {
+    console.error(color("red", "error: pqcheck dismiss requires a check id"));
+    console.error(color("dim", "Usage: pqcheck dismiss route:/admin/ideas    OR    pqcheck dismiss header:Strict-Transport-Security"));
+    process.exit(3);
+  }
+  const { markDismissed } = await import(new URL("./statsTracker.js", import.meta.url).href);
+  const path = await markDismissed(id);
+  if (path) {
+    console.log(color("green", `✓ Marked "${id}" as dismissed-intentional in ${path}`));
+  } else {
+    console.error(color("red", `error: could not persist dismissal for "${id}"`));
+    process.exit(1);
+  }
+}
+
+async function runConfirmCommand(args) {
+  const id = args[0];
+  if (!id) {
+    console.error(color("red", "error: pqcheck confirm requires a check id"));
+    console.error(color("dim", "Usage: pqcheck confirm route:/admin/ideas   — marks as a confirmed real catch (a regression was fixed)"));
+    process.exit(3);
+  }
+  const { markConfirmed } = await import(new URL("./statsTracker.js", import.meta.url).href);
+  const path = await markConfirmed(id);
+  if (path) {
+    console.log(color("green", `✓ Marked "${id}" as confirmed-real in ${path}`));
+  } else {
+    console.error(color("red", `error: could not persist confirmation for "${id}"`));
+    process.exit(1);
+  }
+}
+
+// R89.LOCAL — extract per-check entries from a trust-diff response for
+// stats recording. Records ZERO network requests beyond what the probe
+// already made.
+function extractStatsEntries(routeAssertions) {
+  const entries = [];
+  if (!routeAssertions) return entries;
+  // Route assertions
+  for (const r of routeAssertions.results || []) {
+    entries.push({
+      id: `route:${r.path}`,
+      result: r.passed ? "pass" : "fail",
+      status: r.status,
+      severity: r.severity,
+      source: r.source,
+    });
+  }
+  // Header invariants
+  for (const h of routeAssertions.headerResults || []) {
+    entries.push({
+      id: `header:${h.header}`,
+      result: h.passed ? "pass" : "fail",
+      status: null,
+      severity: h.severity,
+      source: "customer",
+    });
+  }
+  // Cookie invariants
+  for (const c of routeAssertions.cookieResults || []) {
+    entries.push({
+      id: `cookie:${c.namePattern}`,
+      result: c.passed ? "pass" : "fail",
+      status: null,
+      severity: c.severity,
+      source: "customer",
+    });
+  }
+  // Secret scanner findings (each finding is its own check)
+  if (routeAssertions.secrets) {
+    if (routeAssertions.secrets.findings.length === 0 && routeAssertions.secrets.scanned) {
+      entries.push({
+        id: "secret:scan",
+        result: "pass",
+        status: null,
+        severity: "info",
+        source: "secret",
+      });
+    } else {
+      for (const f of routeAssertions.secrets.findings) {
+        entries.push({
+          id: `secret:${f.patternId}`,
+          result: "fail",
+          status: null,
+          severity: f.severity,
+          source: "secret",
+        });
+      }
+    }
+  }
+  // Deploy health
+  if (routeAssertions.deployHealth) {
+    const dh = routeAssertions.deployHealth;
+    entries.push({
+      id: "health:homepage",
+      result: dh.status === "healthy" ? "pass" : "fail",
+      status: dh.httpStatus,
+      severity: dh.status === "healthy" ? "info" : "critical",
+      source: "health",
+    });
+  }
+  // R90 — TLS expiry
+  if (routeAssertions.tlsExpiry && routeAssertions.tlsExpiry.checked) {
+    entries.push({
+      id: "tls:expiry",
+      result: routeAssertions.tlsExpiry.passed ? "pass" : "fail",
+      status: routeAssertions.tlsExpiry.daysRemaining,
+      severity: routeAssertions.tlsExpiry.severity,
+      source: "tls",
+    });
+  }
+  return entries;
+}
+
 async function runInitCommand(args) {
   const fs = await import("node:fs/promises");
   const path = await import("node:path");

package/bin/statsTracker.js

@@ -0,0 +1,257 @@
+// =============================================================================
+// Local-only check stats (R89.LOCAL — 2026-06-05)
+// =============================================================================
+// Persists per-assertion / per-check stats to .cipherwake/stats.json in the
+// customer's repo. Records every result the CIPHERWAKE_* blocks already
+// print to stdout — pass/fail, status, severity, source, timestamp — so the
+// customer can later see (via `pqcheck stats`) which checks actually
+// catch real things vs. sit silent or false-flag.
+//
+// HARD RULE — privacy guarantee:
+//   This module emits ZERO network requests. It only writes to a local file.
+//   No telemetry, no analytics, no cross-repo aggregation. The customer's
+//   results stay on their machine. This matches Cipherwake's "no credentials"
+//   stance — "no credentials and now no data exhaust either."
+//
+// Cross-repo aggregation is a SEPARATE opt-in feature (paid tier hosted
+// analytics) that requires explicit account configuration. That path is
+// not implemented in this CLI module.
+// =============================================================================
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+const STATS_DIR = ".cipherwake";
+const STATS_FILE = "stats.json";
+
+/**
+ * Stats entry shape per check id. Check ids follow a stable scheme:
+ *   route:<path>            — route assertion
+ *   header:<header-name>    — header invariant
+ *   cookie:<name-pattern>   — cookie invariant
+ *   secret:<pattern-id>     — secret scanner finding
+ *   deployHealth            — deploy-not-broken
+ *
+ * @typedef {Object} CheckStats
+ * @property {number} runs
+ * @property {number} passed
+ * @property {number} failed
+ * @property {number} confirmedReal      — incremented when a previously-failing check now passes (inferred fix)
+ * @property {number} dismissedIntentional — incremented when the customer marks the failure as intentional
+ * @property {"pass"|"fail"|"unknown"} lastResult
+ * @property {number|null} lastStatus
+ * @property {string} lastSeenAt   — ISO timestamp
+ * @property {string} severity     — last severity seen
+ * @property {string} source       — "customer" | "default" | "auto" | "health" | "secret"
+ */
+
+/**
+ * Walk up from cwd to find the nearest repo root (.cipherwake.json or .git).
+ * Stats file lives in <repo-root>/.cipherwake/stats.json.
+ */
+async function findStatsDir() {
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, ".cipherwake.json")) || existsSync(join(dir, ".git"))) {
+      return join(dir, STATS_DIR);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // Fallback: write to cwd
+  return join(process.cwd(), STATS_DIR);
+}
+
+/**
+ * Load stats.json from disk. Returns empty stats object if missing or
+ * malformed (we never crash the deploy-check on stats issues).
+ */
+export async function loadStats() {
+  try {
+    const statsDir = await findStatsDir();
+    const path = join(statsDir, STATS_FILE);
+    if (!existsSync(path)) return { version: 1, checks: {} };
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || !parsed.checks) return { version: 1, checks: {} };
+    return parsed;
+  } catch {
+    return { version: 1, checks: {} };
+  }
+}
+
+/**
+ * Persist stats.json. Creates .cipherwake/ if missing.
+ */
+async function persistStats(stats) {
+  try {
+    const statsDir = await findStatsDir();
+    if (!existsSync(statsDir)) {
+      await mkdir(statsDir, { recursive: true });
+    }
+    const path = join(statsDir, STATS_FILE);
+    await writeFile(path, JSON.stringify(stats, null, 2), "utf8");
+    return path;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Apply a batch of check outcomes from a single deploy-check run. Each entry:
+ *   { id, result: "pass"|"fail", status, severity, source }
+ *
+ * Inferred confirmedReal: when the previous lastResult was "fail" and the
+ * new result is "pass", increment confirmedReal. This catches the "I fixed
+ * the regression Cipherwake flagged" event.
+ */
+export async function recordResults(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  const stats = await loadStats();
+  const now = new Date().toISOString();
+  for (const e of entries) {
+    if (!e || typeof e.id !== "string") continue;
+    const cur = stats.checks[e.id] || {
+      runs: 0,
+      passed: 0,
+      failed: 0,
+      confirmedReal: 0,
+      dismissedIntentional: 0,
+      lastResult: "unknown",
+      lastStatus: null,
+      lastSeenAt: now,
+      severity: e.severity || "low",
+      source: e.source || "default",
+    };
+    cur.runs += 1;
+    if (e.result === "pass") {
+      cur.passed += 1;
+      if (cur.lastResult === "fail") cur.confirmedReal += 1;
+      cur.lastResult = "pass";
+    } else if (e.result === "fail") {
+      cur.failed += 1;
+      cur.lastResult = "fail";
+    }
+    cur.lastStatus = (typeof e.status === "number" || e.status === null) ? e.status : cur.lastStatus;
+    cur.lastSeenAt = now;
+    cur.severity = e.severity || cur.severity;
+    cur.source = e.source || cur.source;
+    stats.checks[e.id] = cur;
+  }
+  return await persistStats(stats);
+}
+
+/**
+ * Mark a check as dismissed-intentional. Customer ran `pqcheck dismiss <id>`
+ * after reviewing it as a false positive / intentional state.
+ */
+export async function markDismissed(id) {
+  if (typeof id !== "string" || !id) return null;
+  const stats = await loadStats();
+  const cur = stats.checks[id] || { runs: 0, passed: 0, failed: 0, confirmedReal: 0, dismissedIntentional: 0, lastResult: "unknown", lastStatus: null, lastSeenAt: new Date().toISOString(), severity: "low", source: "customer" };
+  cur.dismissedIntentional += 1;
+  cur.lastSeenAt = new Date().toISOString();
+  stats.checks[id] = cur;
+  return await persistStats(stats);
+}
+
+/**
+ * Mark a check as a confirmed real catch (used by `pqcheck confirm <id>`
+ * when the customer wants to record it explicitly rather than relying on
+ * the inferred-from-fix mechanism).
+ */
+export async function markConfirmed(id) {
+  if (typeof id !== "string" || !id) return null;
+  const stats = await loadStats();
+  const cur = stats.checks[id] || { runs: 0, passed: 0, failed: 0, confirmedReal: 0, dismissedIntentional: 0, lastResult: "unknown", lastStatus: null, lastSeenAt: new Date().toISOString(), severity: "low", source: "customer" };
+  cur.confirmedReal += 1;
+  cur.lastSeenAt = new Date().toISOString();
+  stats.checks[id] = cur;
+  return await persistStats(stats);
+}
+
+/**
+ * R90 (2026-06-05) — record snapshot of "what's on the public surface" so
+ * the next deploy-check can diff it. Captures:
+ *   - publicRoutes: list of /privacy, /terms, etc. paths returning 200
+ *   - thirdPartyHosts: list of third-party script hosts loaded by the homepage
+ *   - certDaysToExpiry: TLS cert remaining days
+ *
+ * Compared against the prior snapshot at next-deploy time to emit
+ * "new since last deploy" diffs (B and C in the final build brief).
+ * Snapshots live in .cipherwake/stats.json (local, no transmission).
+ *
+ * Returns the diff vs the prior snapshot (or null if this is the first run).
+ */
+export async function recordSurfaceSnapshot(snapshot) {
+  try {
+    const stats = await loadStats();
+    if (!stats.surfaceSnapshots) stats.surfaceSnapshots = {};
+    const now = new Date().toISOString();
+    const prev = stats.surfaceSnapshots[snapshot.domain] || null;
+    const diff = computeSurfaceDiff(prev, snapshot);
+    stats.surfaceSnapshots[snapshot.domain] = {
+      capturedAt: now,
+      publicRoutes: snapshot.publicRoutes || [],
+      thirdPartyHosts: snapshot.thirdPartyHosts || [],
+      certDaysToExpiry: snapshot.certDaysToExpiry ?? null,
+    };
+    await persistStats(stats);
+    return diff;
+  } catch {
+    return null;
+  }
+}
+
+function computeSurfaceDiff(prev, current) {
+  if (!prev) return null;
+  const prevRoutes = new Set(prev.publicRoutes || []);
+  const currRoutes = new Set(current.publicRoutes || []);
+  const prevHosts = new Set(prev.thirdPartyHosts || []);
+  const currHosts = new Set(current.thirdPartyHosts || []);
+  return {
+    newRoutes: [...currRoutes].filter((r) => !prevRoutes.has(r)),
+    removedRoutes: [...prevRoutes].filter((r) => !currRoutes.has(r)),
+    newHosts: [...currHosts].filter((h) => !prevHosts.has(h)),
+    removedHosts: [...prevHosts].filter((h) => !currHosts.has(h)),
+    prevSnapshotAt: prev.capturedAt,
+  };
+}
+
+/**
+ * Format stats as a human-readable table for `pqcheck stats`.
+ */
+export function formatStatsTable(stats) {
+  const ids = Object.keys(stats.checks || {}).sort();
+  if (ids.length === 0) return "No check results recorded yet. Run `pqcheck deploy-check` to start.";
+  const lines = [];
+  lines.push("Cipherwake check stats (local, never transmitted)");
+  lines.push("=" .repeat(96));
+  lines.push("CHECK".padEnd(40) + " RUNS  PASS  FAIL  CONFIRMED  DISMISSED  LAST  SEVERITY");
+  lines.push("-" .repeat(96));
+  for (const id of ids) {
+    const s = stats.checks[id];
+    const last = s.lastResult || "?";
+    lines.push(
+      id.slice(0, 39).padEnd(40) +
+      String(s.runs).padStart(5) +
+      String(s.passed).padStart(6) +
+      String(s.failed).padStart(6) +
+      String(s.confirmedReal).padStart(11) +
+      String(s.dismissedIntentional).padStart(11) +
+      " " + last.padEnd(5) +
+      " " + (s.severity || "?")
+    );
+  }
+  lines.push("-" .repeat(96));
+  const totalRuns = ids.reduce((a, id) => a + (stats.checks[id].runs || 0), 0);
+  const totalFailed = ids.reduce((a, id) => a + (stats.checks[id].failed || 0), 0);
+  const totalConfirmed = ids.reduce((a, id) => a + (stats.checks[id].confirmedReal || 0), 0);
+  const totalDismissed = ids.reduce((a, id) => a + (stats.checks[id].dismissedIntentional || 0), 0);
+  const catchRate = totalFailed > 0 ? ((totalConfirmed / totalFailed) * 100).toFixed(0) : "—";
+  lines.push(`TOTAL: ${ids.length} checks tracked, ${totalRuns} runs, ${totalFailed} failures, ${totalConfirmed} confirmed real, ${totalDismissed} dismissed.`);
+  lines.push(`Confirmed-catch rate: ${catchRate}% of failures were confirmed real (a fix landed afterward).`);
+  return lines.join("\n");
+}

package/package.json

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