@nifrajs/web 3.3.0 → 4.0.0

package/src/plugins/vite-zone-guard.ts

@@ -0,0 +1,263 @@
+/**
+ * The zone guard for Vite's dev server. A dev server serves source by URL, so the guard has to hold
+ * before any byte is sent, whatever the URL form:
+ *
+ * - a middleware ahead of Vite's own answers 403 for any request that maps to a file the browser may
+ *   not have: a direct path, `/@fs/`, `?raw`, `?url`, `?import`, a `.map`, a pre-bundled dependency;
+ * - `resolveId` refuses a browser import of backend code at the importer, so the overlay names the line
+ *   instead of the browser hitting a bare 403;
+ * - `transform` refuses whatever reaches the client environment by another route.
+ *
+ * The SSR environment loads the same files legitimately and is never checked here.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs"
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { dirname, isAbsolute, join, relative, resolve } from "node:path"
+import { privateEnvDenial } from "../internal/private-env.ts"
+import {
+  browserDenial,
+  type Classification,
+  createZoneClassifier,
+  SERVER_PACKAGES,
+  specifierPackage,
+} from "../zones.ts"
+
+export interface ViteZoneGuardOptions {
+  /** The app root: the directory holding `routes/`, `frontend/`, `backend/` and `shared/`. */
+  readonly appRoot: string
+  /** The routes directory (default `<appRoot>/routes`). */
+  readonly routesDir?: string
+  /** Generated client modules (the dev entry). */
+  readonly generatedFiles?: readonly string[]
+  /** The public-env prefix browser code may read (default `"PUBLIC_"`). */
+  readonly publicEnvPrefix?: string
+}
+
+/** Zones whose code runs in a browser, so may read only public environment variables. */
+const BROWSER_CODE = new Set<string>(["route-frontend", "frontend", "shared"])
+
+type Next = (error?: unknown) => void
+type Middleware = (req: IncomingMessage, res: ServerResponse, next: Next) => void
+
+interface PluginContext {
+  readonly environment?: { readonly name?: string }
+  error(error: Error | string): never
+  resolve(
+    source: string,
+    importer: string | undefined,
+    options: { readonly skipSelf: boolean } & Record<string, unknown>,
+  ): Promise<{ readonly id: string; readonly external?: boolean | string } | null>
+}
+
+/** The slice of a Vite plugin this returns. Structural, so `vite` stays an optional peer. */
+export interface ViteZoneGuardPlugin {
+  readonly name: string
+  readonly enforce: "pre"
+  config(): { optimizeDeps: { exclude: string[] } }
+  configResolved(config: { readonly root: string }): void
+  configureServer(server: { readonly middlewares: { use(middleware: Middleware): void } }): void
+  resolveId(
+    this: PluginContext,
+    source: string,
+    importer: string | undefined,
+    options?: { readonly ssr?: boolean; readonly scan?: boolean },
+  ): Promise<null>
+  transform(
+    this: PluginContext,
+    code: string,
+    id: string,
+    options?: { readonly ssr?: boolean },
+  ): null
+  /**
+   * Why the module a request URL names failed to serve, when the guard refused one of its imports.
+   * Vite in middleware mode reports a transform error to the overlay and then passes the request on
+   * instead of answering it; the dev server answers with this.
+   */
+  refusalFor(url: string): string | undefined
+  /** The source file a request URL names, when it names one. */
+  fileForUrl(url: string): string | undefined
+}
+
+const stripQuery = (id: string): string => id.replace(/[?#].*$/, "")
+/** Query forms that hand a module's source, or a URL to it, to the browser untransformed. */
+const RAW_QUERY = /(?:^|&)(?:raw|url|inline)(?:[&=]|$)/
+
+const isFile = (path: string): boolean => {
+  try {
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+export function viteZoneGuard(options: ViteZoneGuardOptions): ViteZoneGuardPlugin {
+  const classifier = createZoneClassifier(options)
+  let root = resolve(options.appRoot)
+  const display = (file: string): string => {
+    const rel = relative(classifier.appRoot, file).replaceAll("\\", "/")
+    return rel.startsWith("..") || isAbsolute(rel) ? file : rel
+  }
+  const isClient = (context: PluginContext, ssr: boolean | undefined): boolean =>
+    ssr !== true && (context.environment?.name ?? "client") === "client"
+
+  /** What a pre-bundled dependency file was built from, per Vite's `_metadata.json`. */
+  const depsSources = new Map<string, { mtime: number; sources: Map<string, string> }>()
+  const depSource = (file: string): string | undefined => {
+    const dir = dirname(file)
+    const metadata = join(dir, "_metadata.json")
+    let mtime: number
+    try {
+      mtime = statSync(metadata).mtimeMs
+    } catch {
+      return undefined
+    }
+    let cached = depsSources.get(dir)
+    if (cached === undefined || cached.mtime !== mtime) {
+      const sources = new Map<string, string>()
+      try {
+        const parsed = JSON.parse(readFileSync(metadata, "utf8")) as {
+          optimized?: Record<string, { src?: string; file?: string }>
+        }
+        for (const dep of Object.values(parsed.optimized ?? {})) {
+          if (dep.src !== undefined && dep.file !== undefined) {
+            sources.set(resolve(dir, dep.file), resolve(dir, dep.src))
+          }
+        }
+      } catch {
+        // An unreadable metadata file maps nothing; the request then classifies as the cache file.
+      }
+      cached = { mtime, sources }
+      depsSources.set(dir, cached)
+    }
+    return cached.sources.get(file)
+  }
+
+  /** The file a request URL serves, or `undefined` when it names none (an app route, a Vite internal). */
+  const fileForUrl = (url: string): string | undefined => {
+    let path: string
+    try {
+      path = decodeURIComponent(stripQuery(url))
+    } catch {
+      return undefined
+    }
+    let file: string
+    if (path.startsWith("/@fs/")) file = path.slice("/@fs".length).replace(/^\/([a-zA-Z]:)/, "$1")
+    else if (path.startsWith("/@id/")) {
+      const id = path.slice("/@id/".length)
+      if (!isAbsolute(id)) return undefined
+      file = id
+    } else if (path.startsWith("/@")) return undefined
+    else file = join(root, path)
+    for (const candidate of [file, file.replace(/\.map$/, "")]) {
+      // One spelling per file: Vite names it `C:/app/x.ts` on Windows, `join` names it `C:\app\x.ts`.
+      if (isFile(candidate)) return resolve(candidate)
+    }
+    return undefined
+  }
+
+  const middleware: Middleware = (req, res, next) => {
+    const url = req.url ?? "/"
+    const file = fileForUrl(url)
+    if (file === undefined) return next()
+    const source = file.replaceAll("\\", "/").includes("/node_modules/.vite/")
+      ? (depSource(file) ?? file)
+      : file
+    const classification = classifier.classify(source)
+    let reason = browserDenial(classification)
+    const query = url.includes("?") ? url.slice(url.indexOf("?") + 1) : ""
+    if (reason === undefined && classification.zone === "fn" && RAW_QUERY.test(query)) {
+      reason = "a server-function module reaches the browser only as its generated stub"
+    }
+    if (reason === undefined) return next()
+    res.statusCode = 403
+    res.setHeader("content-type", "text/plain; charset=utf-8")
+    res.setHeader("cache-control", "no-store")
+    res.end(`[nifra] ${display(source)} may not reach the browser: ${reason}\n`)
+  }
+
+  const refusals = new Map<string, string>()
+  const refuse = (
+    context: PluginContext,
+    file: string,
+    reason: string,
+    importer?: string,
+  ): never => {
+    const message = `[nifra/web] ${display(file)} may not reach the browser${importer === undefined ? "" : ` (imported by ${display(importer)})`}: ${reason}`
+    refusals.set(resolve(importer ?? file), message)
+    return context.error(new Error(message))
+  }
+
+  /** A bare specifier's package, classified through its manifest so a workspace link is first-party. */
+  const packageClassification = (name: string, importer: string): Classification => {
+    let dir = dirname(importer)
+    for (;;) {
+      const manifest = join(dir, "node_modules", name, "package.json")
+      if (existsSync(manifest)) return classifier.classify(manifest)
+      const parent = dirname(dir)
+      if (parent === dir) return { zone: "library", packageName: name }
+      dir = parent
+    }
+  }
+
+  return {
+    name: "nifra:zone-guard",
+    enforce: "pre",
+    refusalFor(url) {
+      const file = fileForUrl(url)
+      return file === undefined ? undefined : refusals.get(file)
+    },
+    fileForUrl,
+    // A pre-bundled copy would serve a server package under `.vite/deps/` instead of its own path.
+    config: () => ({ optimizeDeps: { exclude: [...SERVER_PACKAGES] } }),
+    configResolved(config) {
+      root = config.root
+    },
+    configureServer(server) {
+      // Registered directly (not in a returned post hook), so it runs ahead of Vite's own middlewares.
+      server.middlewares.use(middleware)
+    },
+    async resolveId(source, importer, resolveOptions) {
+      if (importer === undefined || resolveOptions?.scan === true) return null
+      if (!isClient(this, resolveOptions?.ssr)) return null
+      const importerFile = stripQuery(importer)
+      if (!isAbsolute(importerFile)) return null
+      if (source.startsWith(".")) {
+        const target = resolve(dirname(importerFile), stripQuery(source))
+        if (isFile(target)) {
+          const reason = browserDenial(classifier.classify(target))
+          if (reason !== undefined) refuse(this, target, reason, importerFile)
+        }
+        return null
+      }
+      const name = specifierPackage(source)
+      if (name !== undefined) {
+        const reason = browserDenial(packageClassification(name, importerFile), source)
+        if (reason !== undefined) refuse(this, source, reason, importerFile)
+      }
+      // An alias, a tsconfig path or a package export: what the specifier resolves to decides.
+      const resolved = await this.resolve(source, importer, { ...resolveOptions, skipSelf: true })
+      const target = resolved === null || resolved.external ? undefined : stripQuery(resolved.id)
+      if (target !== undefined && isAbsolute(target) && isFile(target)) {
+        const reason = browserDenial(classifier.classify(target), source)
+        if (reason !== undefined) refuse(this, target, reason, importerFile)
+      }
+      return null
+    },
+    transform(code, id, transformOptions) {
+      if (!isClient(this, transformOptions?.ssr)) return null
+      const file = stripQuery(id)
+      if (!isAbsolute(file) || !isFile(file)) return null
+      // A fresh transform re-resolves every import, so an earlier refusal is stale until it recurs.
+      refusals.delete(resolve(file))
+      const classification = classifier.classify(file)
+      // A `pre` transform sees the file as written, so the env check reads the source the author wrote.
+      const reason =
+        browserDenial(classification) ??
+        (BROWSER_CODE.has(classification.zone) && id === file
+          ? privateEnvDenial(file, code, options.publicEnvPrefix ?? "PUBLIC_")
+          : undefined)
+      if (reason !== undefined) refuse(this, file, reason)
+      return null
+    },
+  }
+}

package/src/plugins/zone-guard.ts

@@ -0,0 +1,110 @@
+/**
+ * The zone guard for Bun's bundler: every file the browser bundle loads is classified, and one that may
+ * not reach a browser stops the build (or the dev request) before its code is bundled.
+ *
+ * The client build runs it in `record` mode and reports every refusal together with its import chain,
+ * read from the finished graph; the dev server runs it in `throw` mode, where there is no finished graph
+ * and the refusal must stop the response.
+ */
+
+import { dirname, isAbsolute, relative, resolve } from "node:path"
+import type { BunPlugin } from "bun"
+import { privateEnvDenial } from "../internal/private-env.ts"
+import {
+  BACKEND_ONLY_MARKER,
+  browserDenial,
+  createZoneClassifier,
+  type ZoneClassifier,
+} from "../zones.ts"
+
+const SOURCE_EXTENSIONS =
+  "[cm]?[jt]sx?|svelte|vue|mdx|astro|css|scss|sass|less|json|jsonc|toml|ya?ml|txt|md"
+/** Source files Bun loads through a loader that tolerates a declining `onLoad`. Every other file
+ * (images, fonts, wasm, and a `.pem` or `.sql` imported `with { type: "text" }`) goes through
+ * `onResolve`: a file-loader asset panics Bun 1.4 on a declining `onLoad`. */
+const SOURCE_FILE = new RegExp(`\\.(?:${SOURCE_EXTENSIONS})$`)
+/**
+ * A relative or absolute import whose last segment has an extension, other than a source file.
+ * Source files are excluded by the FILTER, not declined by the handler: on Bun's dev server a filter
+ * match alone changes how the import resolves, even when the handler declines (see
+ * `internal/dev-reserved.ts`), and a source file is the onLoad hook's to judge anyway.
+ */
+const NON_SOURCE_PATH = new RegExp(
+  `^(?:\\.|\\/|[A-Za-z]:[\\\\/])(?![^?#]*\\.(?:${SOURCE_EXTENSIONS})(?:[?#]|$)).*\\.[^./\\\\?#]+(?:[?#].*)?$`,
+)
+
+export interface ZoneGuardOptions {
+  /** The app root: the directory holding `routes/`, `frontend/`, `backend/` and `shared/`. */
+  readonly appRoot: string
+  /** The routes directory (default `<appRoot>/routes`). */
+  readonly routesDir?: string
+  /** The build's own generated entry modules. */
+  readonly generatedFiles?: readonly string[]
+  /** Collect refusals instead of throwing; the caller reports them with chains after the build. */
+  readonly onDenied?: (file: string, reason: string) => void
+  /** Share a classifier with post-build verification. */
+  readonly classifier?: ZoneClassifier
+  /** The public-env prefix browser code may read (default `"PUBLIC_"`). Checked here only in throw
+   * mode; a build checks the finished graph instead. */
+  readonly publicEnvPrefix?: string
+}
+
+/** Zones whose code runs in a browser, so may read only public environment variables. */
+const BROWSER_CODE = new Set<string>(["route-frontend", "frontend", "shared"])
+
+export function zoneGuardPlugin(options: ZoneGuardOptions): BunPlugin {
+  const classifier = options.classifier ?? createZoneClassifier(options)
+  const display = (file: string): string => {
+    const rel = relative(classifier.appRoot, file).replaceAll("\\", "/")
+    return rel.startsWith("..") || isAbsolute(rel) ? file : rel
+  }
+  const refuse = (file: string, reason: string, importer?: string): undefined => {
+    if (options.onDenied !== undefined) {
+      options.onDenied(file, reason)
+      return undefined
+    }
+    const via =
+      importer === undefined || importer === "" ? "" : ` (imported by ${display(importer)})`
+    throw new Error(`[nifra/web] ${display(file)} may not reach the browser${via}: ${reason}`)
+  }
+  return {
+    name: "nifra-zone-guard",
+    setup(build) {
+      build.onLoad({ filter: SOURCE_FILE }, async (args) => {
+        if (args.namespace !== "file") return undefined
+        const classification = classifier.classify(args.path)
+        let reason = browserDenial(classification)
+        if (
+          reason === undefined &&
+          options.onDenied === undefined &&
+          BROWSER_CODE.has(classification.zone)
+        ) {
+          const source = await Bun.file(args.path).text()
+          reason = privateEnvDenial(args.path, source, options.publicEnvPrefix ?? "PUBLIC_")
+        }
+        return reason === undefined ? undefined : refuse(args.path, reason)
+      })
+      build.onResolve({ filter: NON_SOURCE_PATH }, (args) => {
+        // An entry point (a dev server's HTML page) is the build's own choice, not an import.
+        if (args.importer === "") return undefined
+        const file = resolve(dirname(args.importer), args.path.replace(/[?#].*$/, ""))
+        const reason = browserDenial(classifier.classify(file))
+        return reason === undefined ? undefined : refuse(file, reason, args.importer)
+      })
+      // In record mode the finished graph reports these, with chains; only the dev server needs them here.
+      if (options.onDenied !== undefined) return
+      build.onResolve({ filter: /^(?:node|bun):/ }, (args) =>
+        refuse(
+          args.path,
+          "Node and Bun built-ins run on the server only; use them in a route's backend half or under backend/",
+          args.importer,
+        ),
+      )
+      build.onResolve(
+        { filter: new RegExp(`^${BACKEND_ONLY_MARKER.replaceAll("/", "\\/")}$`) },
+        (args) =>
+          refuse(args.importer, `it imports "${BACKEND_ONLY_MARKER}", which marks it backend-only`),
+      )
+    },
+  }
+}

package/src/prerender.ts

@@ -10,8 +10,9 @@
  */
 import { mkdirSync, writeFileSync } from "node:fs"
 import { dirname, resolve, sep } from "node:path"
+import { assertNoSecrets, buildEnvironment, type SecretExemption } from "./internal/secret-scan.ts"
 import { fillRoutePattern, type RouteEntry } from "./manifest.ts"
-import { DATA_HEADER } from "./router.ts"
+import { DATA_HEADER, PRERENDERED_GLOBAL, PRERENDERED_LIST_PATH } from "./router.ts"
 
 /** Minimal app surface the driver needs - just a fetch handler (a built `createWebApp`). */
 export interface PrerenderApp {
@@ -30,6 +31,15 @@ export interface PrerenderOptions {
   /** Origin for the synthetic request URL. Default `http://localhost`. Only the path is meaningful;
    * loaders see this as `request.url`, so set it if a loader builds absolute URLs from the origin. */
   readonly origin?: string
+  /** The secret scan every page and `_data.json` passes before it is written: what looks like a
+   * credential, or the value of a non-public build environment variable, fails the prerender. */
+  readonly secrets?: {
+    /** Default: the build environment (`Bun.env`, else `process.env`). */
+    readonly env?: Readonly<Record<string, string | undefined>>
+    /** Default `"PUBLIC_"`. */
+    readonly publicEnvPrefix?: string
+    readonly exemptions?: readonly SecretExemption[]
+  }
 }
 
 export interface PrerenderEntry {
@@ -66,6 +76,11 @@ export function htmlFileFor(pattern: string): string {
   return trimmed === "" ? "index.html" : `${trimmed}/index.html`
 }
 
+// The handover of a page whose prerendered set is served as a list rather than inlined.
+const PRERENDERED_LIST_URL = new RegExp(
+  `"${PRERENDERED_GLOBAL}":"(${PRERENDERED_LIST_PATH.replaceAll(".", "\\.")}\\?v=[0-9a-f]+)"`,
+)
+
 /** The static loader-data file next to a route's `index.html`: `/` → `_data.json`, `/a/b` →
  * `a/b/_data.json`. The client fetches it on soft-nav into a prerendered route (no worker). */
 export function dataFileFor(pattern: string): string {
@@ -90,9 +105,19 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
   const skipped: { path: string; reason: string }[] = []
   const fallbacks: Record<string, "ssr" | "404"> = {}
   const outRoot = resolve(options.outDir)
+  let listUrl: string | undefined
+
+  const secretScan = {
+    env: options.secrets?.env ?? buildEnvironment(),
+    publicEnvPrefix: options.secrets?.publicEnvPrefix ?? "PUBLIC_",
+    ...(options.secrets?.exemptions ? { exemptions: options.secrets.exemptions } : {}),
+  }
+  const assertClean = (name: string, text: string): void =>
+    assertNoSecrets({ ...secretScan, artifacts: [{ name, text }] })
 
   // Render one concrete path → drain the streamed document to bytes → write its index.html. Shared by
-  // static (one path) and dynamic (one path per getStaticPaths entry) routes; never throws.
+  // static (one path) and dynamic (one path per getStaticPaths entry) routes. A failed render is a skip;
+  // a credential in the output fails the whole prerender.
   const renderPath = async (path: string): Promise<void> => {
     const res = await options.app.fetch(new Request(`${origin}${path}`))
     if (!res.ok) {
@@ -101,12 +126,14 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
       return
     }
     const html = await res.text()
+    listUrl ??= PRERENDERED_LIST_URL.exec(html)?.[1]
     const file = htmlFileFor(path)
     const abs = outputPath(outRoot, file)
     if (abs === undefined) {
       skipped.push({ path, reason: "unsafe output path" })
       return
     }
+    assertClean(file, html)
     mkdirSync(dirname(abs), { recursive: true })
     writeFileSync(abs, html)
 
@@ -128,7 +155,9 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
         await dataRes.body?.cancel()
         dataFile = undefined
       } else {
-        writeFileSync(dataAbs, await dataRes.text())
+        const data = await dataRes.text()
+        assertClean(dataFile, data)
+        writeFileSync(dataAbs, data)
       }
     } else {
       await dataRes.body?.cancel() // not emitting (non-OK or NDJSON) - release the stream
@@ -177,6 +206,23 @@ export async function prerenderRoutes(options: PrerenderOptions): Promise<Preren
     await renderPath(route.pattern)
   }
 
+  // A set too large to inline is handed over as the URL of a list the app serves; the static output
+  // has to carry the file those pages fetch.
+  if (listUrl !== undefined) {
+    const listRes = await options.app.fetch(new Request(`${origin}${listUrl}`))
+    const listFile = PRERENDERED_LIST_PATH.slice(1)
+    const listAbs = outputPath(outRoot, listFile)
+    if (listRes.ok && listAbs !== undefined) {
+      const text = await listRes.text()
+      assertClean(listFile, text)
+      mkdirSync(dirname(listAbs), { recursive: true })
+      writeFileSync(listAbs, text)
+    } else {
+      await listRes.body?.cancel()
+      skipped.push({ path: PRERENDERED_LIST_PATH, reason: `list returned HTTP ${listRes.status}` })
+    }
+  }
+
   return { prerendered, skipped, fallbacks }
 }