@nifrajs/cli 3.5.0 → 4.0.2

package/src/cdn-check.ts

@@ -0,0 +1,268 @@
+/**
+ * `nifra cdn-check <url>` - is a deployed page actually served by the CDN the way `withCdn` intends?
+ *
+ * Read-only: two GETs of the page and one shaped like a soft navigation (`x-nifra-data: 1`). It names
+ * the CDN from its status header, and fails when nifra's internal headers reach the visitor or when
+ * the CDN answers a navigation data request with the cached document (Cloudflare's zone cache ignores
+ * `Vary`, so it needs a rule that bypasses the cache for that header). CLI only: an agent-facing tool
+ * that fetches arbitrary URLs from this machine could reach its private network.
+ */
+import type { CommandSpec } from "./command-catalog.ts"
+
+export interface CdnCheckInput {
+  readonly url: string
+  readonly json?: boolean
+}
+
+export type CdnName = "cloudflare" | "vercel" | "fastly" | "unknown"
+
+export interface CdnCheckRequest {
+  readonly kind: "first" | "second" | "data"
+  readonly status: number
+  readonly cache?: string | undefined
+  readonly age?: string | undefined
+  readonly contentType?: string | undefined
+  readonly cacheControl?: string | undefined
+}
+
+export interface CdnCheckFinding {
+  readonly level: "fail" | "warn" | "info"
+  readonly code: string
+  readonly message: string
+}
+
+export interface CdnCheckOutput {
+  readonly url: string
+  readonly cdn: CdnName
+  readonly requests: readonly CdnCheckRequest[]
+  readonly findings: readonly CdnCheckFinding[]
+}
+
+const TIMEOUT_MS = 10_000
+const INTERNAL = ["x-nifra-isr-revalidate", "x-nifra-isr-tags"]
+const CDN_ONLY = [
+  "cache-tag",
+  "cloudflare-cdn-cache-control",
+  "vercel-cache-tag",
+  "vercel-cdn-cache-control",
+  "surrogate-key",
+  "surrogate-control",
+]
+
+const field = (from: unknown, name: string): unknown =>
+  typeof from === "object" && from !== null ? Reflect.get(from, name) : undefined
+
+function isCdnCheckOutput(value: unknown): value is CdnCheckOutput {
+  return (
+    typeof field(value, "url") === "string" &&
+    typeof field(value, "cdn") === "string" &&
+    Array.isArray(field(value, "requests")) &&
+    Array.isArray(field(value, "findings"))
+  )
+}
+
+function parseInput(value: unknown): CdnCheckInput {
+  const url = field(value, "url")
+  if (typeof url !== "string" || url === "") throw new TypeError("cdn-check needs a page URL")
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    throw new TypeError(`cdn-check: ${JSON.stringify(url)} is not a URL`)
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new TypeError("cdn-check: the URL must be http or https")
+  }
+  if (parsed.username !== "" || parsed.password !== "") {
+    throw new TypeError("cdn-check: leave credentials out of the URL")
+  }
+  return field(value, "json") === true ? { url: parsed.href, json: true } : { url: parsed.href }
+}
+
+/** The CDN a response came through, from the status header each one sets. */
+export function detectCdn(headers: Headers): CdnName {
+  if (headers.has("cf-cache-status") || headers.has("cf-ray")) return "cloudflare"
+  if (headers.has("x-vercel-cache") || headers.has("x-vercel-id")) return "vercel"
+  if (/\bcache-[a-z0-9]+/i.test(headers.get("x-served-by") ?? "")) return "fastly"
+  return "unknown"
+}
+
+function cacheStatus(cdn: CdnName, headers: Headers): string | undefined {
+  const value =
+    cdn === "cloudflare"
+      ? headers.get("cf-cache-status")
+      : cdn === "vercel"
+        ? headers.get("x-vercel-cache")
+        : headers.get("x-cache")
+  return value ?? undefined
+}
+
+const isHit = (status: string | undefined): boolean =>
+  status !== undefined && /\b(HIT|STALE|UPDATING|REVALIDATED)\b/i.test(status)
+
+async function get(
+  url: string,
+  extra: Record<string, string>,
+  signal: AbortSignal | undefined,
+): Promise<Response> {
+  const timeout = AbortSignal.timeout(TIMEOUT_MS)
+  return fetch(url, {
+    headers: { "user-agent": "nifra-cdn-check", ...extra },
+    redirect: "manual",
+    signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
+  })
+}
+
+export async function runCdnCheck(
+  input: CdnCheckInput,
+  ctx: { readonly signal?: AbortSignal } = {},
+): Promise<CdnCheckOutput> {
+  const findings: CdnCheckFinding[] = []
+  const requests: CdnCheckRequest[] = []
+  const record = async (extra: Record<string, string> = {}) => {
+    const res = await get(input.url, extra, ctx.signal)
+    await res.body?.cancel()
+    return res
+  }
+  const first = await record()
+  const cdn = detectCdn(first.headers)
+  const summarize = (kind: CdnCheckRequest["kind"], res: Response): CdnCheckRequest => ({
+    kind,
+    status: res.status,
+    cache: cacheStatus(cdn, res.headers),
+    age: res.headers.get("age") ?? undefined,
+    contentType: res.headers.get("content-type") ?? undefined,
+    cacheControl: res.headers.get("cache-control") ?? undefined,
+  })
+  requests.push(summarize("first", first))
+  if (first.status >= 300 && first.status < 400) {
+    findings.push({
+      level: "info",
+      code: "redirect",
+      message: `the URL redirects (${first.status}) to ${first.headers.get("location") ?? "?"}; check the page it lands on`,
+    })
+    return { url: input.url, cdn, requests, findings }
+  }
+  const second = await record()
+  requests.push(summarize("second", second))
+  const data = await record({ "x-nifra-data": "1" })
+  requests.push(summarize("data", data))
+
+  for (const res of [first, second, data]) {
+    const leaked = INTERNAL.filter((name) => res.headers.has(name))
+    if (leaked.length > 0) {
+      findings.push({
+        level: "fail",
+        code: "internal-headers",
+        message: `${leaked.join(", ")} reached the visitor: the app's cache channel is open without withISR or withCdn removing it`,
+      })
+      break
+    }
+  }
+  const cdnOnly = CDN_ONLY.filter((name) => second.headers.has(name))
+  if (cdnOnly.length > 0) {
+    findings.push({
+      level: "warn",
+      code: "cdn-headers-visible",
+      message: `${cdnOnly.join(", ")} reached the visitor: the response did not pass through the CDN these headers are for${cdn === "unknown" ? "" : `, or ${cdn} is not consuming them`}`,
+    })
+  }
+  if (cdn === "unknown") {
+    findings.push({
+      level: "warn",
+      code: "no-cdn",
+      message:
+        "no CDN status header (cf-cache-status, x-vercel-cache, x-served-by): the page does not seem to pass through Cloudflare, Vercel or Fastly",
+    })
+  } else if (!isHit(summarize("second", second).cache)) {
+    findings.push({
+      level: "warn",
+      code: "not-cached",
+      message:
+        cdn === "cloudflare"
+          ? `the second request was not served from cache (${second.headers.get("cf-cache-status") ?? "no status"}). Cloudflare caches HTML only under a Cache Rule that makes it eligible for cache`
+          : `the second request was not served from cache (${summarize("second", second).cache ?? "no status"}); a personalized or no-store page is expected to stay uncached`,
+    })
+  }
+  const browser = second.headers.get("cache-control") ?? ""
+  const maxAge = /(?:^|,)\s*max-age=(\d+)/i.exec(browser)?.[1]
+  if (
+    (second.headers.get("content-type") ?? "").includes("text/html") &&
+    maxAge !== undefined &&
+    Number(maxAge) > 0
+  ) {
+    findings.push({
+      level: "warn",
+      code: "browser-holds-html",
+      message: `browsers may keep this page for ${maxAge}s (cache-control: ${browser}); a CDN purge cannot reach them`,
+    })
+  }
+  const dataType = data.headers.get("content-type") ?? ""
+  if (dataType.includes("text/html") || isHit(cacheStatus(cdn, data.headers))) {
+    findings.push({
+      level: "fail",
+      code: "data-served-from-cache",
+      message:
+        cdn === "cloudflare"
+          ? "a soft navigation (x-nifra-data: 1) got the cached document. The zone cache ignores Vary: add a Cache Rule that bypasses the cache when the request has an x-nifra-data header"
+          : "a soft navigation (x-nifra-data: 1) got the cached document instead of the page data; the CDN is not honoring Vary: x-nifra-data",
+    })
+  }
+  return { url: input.url, cdn, requests, findings }
+}
+
+function renderCdnCheck(out: CdnCheckOutput): readonly string[] {
+  const lines = [`cdn-check ${out.url}  (cdn: ${out.cdn})`]
+  for (const r of out.requests) {
+    lines.push(
+      `  ${r.kind.padEnd(6)} ${r.status}  cache=${r.cache ?? "-"}  age=${r.age ?? "-"}  ${r.contentType ?? ""}`,
+    )
+  }
+  if (out.findings.length === 0) lines.push("ok - nothing to fix")
+  for (const f of out.findings) lines.push(`${f.level.toUpperCase()} ${f.code}: ${f.message}`)
+  return lines
+}
+
+export const cdnCheckSpec: CommandSpec<CdnCheckInput, CdnCheckOutput> = {
+  name: "cdn-check",
+  summary:
+    "Check a deployed page behind a CDN: is it served from cache, do internal or CDN-only headers reach the visitor, and does a soft navigation get page data rather than the cached document.",
+  input: {
+    jsonSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "The deployed page to check (http or https)." },
+        json: { type: "boolean" },
+      },
+      required: ["url"],
+    },
+    parse: parseInput,
+  },
+  output: {
+    version: 1,
+    jsonSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string" },
+        cdn: { type: "string", enum: ["cloudflare", "vercel", "fastly", "unknown"] },
+        requests: { type: "array" },
+        findings: { type: "array" },
+      },
+      required: ["url", "cdn", "requests", "findings"],
+    },
+    parse: (value) => {
+      if (isCdnCheckOutput(value)) return value
+      throw new TypeError("cdn-check output must carry url, cdn, requests and findings")
+    },
+  },
+  transports: ["cli"],
+  stability: "experimental",
+  argv: {
+    positionals: ["url"],
+    flags: [{ name: "json", field: "json", type: "boolean" }],
+  },
+  run: (input, ctx) => runCdnCheck(input, ctx),
+  render: renderCdnCheck,
+  exitCode: (out) => (out.findings.some((f) => f.level === "fail") ? 1 : 0),
+  json: (out) => out,
+}

package/src/check-diagnostics.ts

@@ -8,6 +8,7 @@
 import { existsSync } from "node:fs"
 import { join } from "node:path"
 import type { AssuranceConfig, AssuranceReport } from "@nifrajs/core/assurance"
+import type { CapabilityGap } from "@nifrajs/core/capabilities"
 import type { ProjectEvidenceSnapshot } from "@nifrajs/core/evidence"
 import type { CapabilityProjectReport } from "./capabilities-tool.ts"
 import {
@@ -19,12 +20,16 @@ import {
 import type { DuplicateInstallFinding } from "./doctor.ts"
 import type { PipelineReport } from "./pipeline-report.ts"
 import { freezeProjectFacts, type ProjectFactsSeed } from "./project-facts.ts"
+import { dataGuardRules } from "./rules/data-guard.ts"
 import { parseRulePacks, runRuleRegistry } from "./rules/index.ts"
 import { islandRules } from "./rules/islands.ts"
 import { LEGACY_RULE_CODES, LEGACY_RULE_ORDER, legacyRules } from "./rules/legacy.ts"
 import { nanoRules } from "./rules/nano.ts"
+import { pageRules } from "./rules/pages.ts"
 import { routeRules } from "./rules/routes.ts"
+import { secretRules } from "./rules/secrets.ts"
 import { securityRules } from "./rules/security.ts"
+import { zoneRules } from "./rules/zones.ts"
 
 /** A single machine-readable check failure - the unit an agent (or CI) acts on. */
 export interface CheckDiagnostic {
@@ -84,6 +89,9 @@ export interface CheckResult {
    * better-auth). Echoed here so `--json` / the MCP tool / the report can show what the typed-client scan
    * deliberately skipped - a suppressed prefix stays auditable instead of silently hiding real drift. */
   readonly externalMounts?: readonly string[]
+  /** Mounts declared `opaque` - outside capability assurance on purpose, each with its stated reason.
+   * Listed on every run so the report states its own boundary; never a failure. */
+  readonly knownGaps?: readonly CapabilityGap[]
   /** Active per-rule overrides from `nifra.check.json` `rules`, echoed verbatim so a retagged or
    * suppressed finding stays auditable in `--json`, the MCP tool, and the human report - config can
    * lower (or raise) the gate, but never invisibly. */
@@ -419,12 +427,19 @@ export async function collectCheckDiagnostics(
     root: cwd,
     sources: projectFacts.source,
     project: projectFacts,
+    ...(projectFacts.check.typescriptSession === undefined
+      ? {}
+      : { typescriptSession: projectFacts.check.typescriptSession }),
   }
 
   const builtInRules = [
     ...legacyRules,
     ...securityRules,
     ...routeRules,
+    ...pageRules,
+    ...zoneRules,
+    ...dataGuardRules,
+    ...secretRules,
     ...islandRules,
     ...nanoRules,
   ]
@@ -568,6 +583,7 @@ export async function collectCheckDiagnostics(
     shown.length < total ? shown.length + nonLegacyStructuredCount : finalStructured.length
 
   const doctor = projectFacts.packages.doctor
+  const knownGaps = projectFacts.policies.capability?.report.gaps ?? []
   const result: CheckResult = {
     ok: !finalDiagnostics.some((value) => value.severity === "error"),
     typecheck: projectFacts.check.typecheck.ran
@@ -593,6 +609,7 @@ export async function collectCheckDiagnostics(
     ...(checkConfig.externalMounts.length === 0
       ? {}
       : { externalMounts: checkConfig.externalMounts }),
+    ...(knownGaps.length === 0 ? {} : { knownGaps }),
     ...(Object.keys(checkConfig.rules).length === 0 ? {} : { ruleOverrides: checkConfig.rules }),
     ...(shown.length < total ? { truncated: { shown: shown.length, total } } : {}),
   }