@nifrajs/web 3.3.0 → 3.5.0

package/src/isr.ts

@@ -439,12 +439,21 @@ const requestCarriesPrivateState = (req: Request): boolean =>
 const responseIsExplicitlyPublic = (res: Response): boolean =>
   cacheControlHas(res.headers, ["public"])
 
+const responseDeclaresVary = (res: Response): boolean => {
+  const value = res.headers.get("vary")
+  return value !== null && value.trim() !== ""
+}
+
 const isCacheablePage = (req: Request, res: Response): boolean => {
   if (req.method !== "GET") return false
   if (req.headers.get("x-nifra-data") !== null) return false
   if (res.status !== 200) return false
   if (!(res.headers.get("content-type") ?? "").includes("text/html")) return false
   if (hasSetCookie(res.headers)) return false
+  // The default ISR key is URL-only. A response that varies on request headers must either use a
+  // caller-supplied key that includes those headers or bypass ISR; otherwise one language/tenant
+  // representation can be served to every request for the URL.
+  if (responseDeclaresVary(res)) return false
   if (cacheControlHas(res.headers, ["private", "no-store"])) return false
   // Cookie/Authorization requests often personalize HTML without setting a new cookie. Cache them only
   // when the route explicitly declares the response public.
@@ -452,22 +461,45 @@ const isCacheablePage = (req: Request, res: Response): boolean => {
   return true
 }
 
+// Keep representation and security policy headers, plus `Vary` for legacy entries. Transport,
+// request-specific, framework-control, and unknown internal headers stay out of the shared cache.
 const CACHEABLE_RESPONSE_HEADERS = new Set([
   "cache-control",
   "content-language",
+  "content-security-policy",
   "content-type",
+  "cross-origin-embedder-policy",
+  "cross-origin-opener-policy",
+  "cross-origin-resource-policy",
   "etag",
   "last-modified",
   "link",
+  "origin-agent-cluster",
+  "permissions-policy",
+  "referrer-policy",
+  "strict-transport-security",
+  "vary",
+  "x-content-type-options",
+  "x-frame-options",
 ])
 
+const isCacheableResponseHeader = (key: string): boolean => {
+  const normalized = key.toLowerCase()
+  return (
+    CACHEABLE_RESPONSE_HEADERS.has(normalized) ||
+    normalized.startsWith("content-security-policy-") ||
+    normalized.startsWith("cross-origin-") ||
+    normalized.startsWith("permissions-policy-")
+  )
+}
+
 const tagsOf = (res: Response): readonly string[] =>
   tagsFromHeader(res.headers.get(ISR_REVALIDATE_TAGS_HEADER))
 
 const headersOf = (res: Response): Record<string, string> => {
   const out: Record<string, string> = {}
   res.headers.forEach((value, key) => {
-    if (CACHEABLE_RESPONSE_HEADERS.has(key)) out[key] = value
+    if (isCacheableResponseHeader(key)) out[key] = value
   })
   return out
 }
@@ -481,12 +513,14 @@ const responseFrom = (entry: CachedResponse, status: "hit" | "stale"): Response
 function sanitizeCachedHeaders(headers: Readonly<Record<string, string>>): Record<string, string> {
   const out: Record<string, string> = {}
   for (const [key, value] of Object.entries(headers)) {
-    const normalized = key.toLowerCase()
-    if (CACHEABLE_RESPONSE_HEADERS.has(normalized)) out[normalized] = value
+    if (isCacheableResponseHeader(key)) out[key.toLowerCase()] = value
   }
   return out
 }
 
+const isInvalidationResponse = (res: Response): boolean =>
+  res.status === 404 || res.status === 410 || (res.status >= 300 && res.status < 400)
+
 /**
  * Wrap a nifra app with **Incremental Static Regeneration**: a cacheable page is served from
  * {@link CacheStore} when fresh, served **stale while a fresh copy regenerates in the background**
@@ -561,6 +595,11 @@ export function withISR(
           revalidate: ttlMs(res),
           ...(tags.length === 0 ? {} : { tags }),
         })
+      } else if (isInvalidationResponse(res)) {
+        // A successful deletion or redirect is authoritative. Keeping the old entry would make a
+        // withdrawn page stay publicly visible forever because every stale request would retry the same
+        // non-cacheable response while continuing to serve the old body.
+        await store.delete(key)
       } else {
         await res.body?.cancel()
       }

package/src/llms-txt.ts

@@ -1,4 +1,8 @@
-import { reflectRoutes } from "@nifrajs/core/reflection"
+import {
+  type ProjectEvidenceSnapshot,
+  reflectedRoutesFromEvidence,
+  snapshotProjectEvidence,
+} from "@nifrajs/core/evidence"
 
 const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
@@ -102,7 +106,11 @@ export async function generateLlmsTxt(
   full: boolean,
   pageRoutes: ReadonlyArray<{ readonly pattern: string; readonly id: string }>,
   backend: unknown,
-  options: { readonly includeLocalGuidelines?: boolean } = {},
+  options: {
+    readonly includeLocalGuidelines?: boolean
+    /** Reuse the project's canonical route-evidence pass when one is already available. */
+    readonly evidence?: ProjectEvidenceSnapshot
+  } = {},
 ): Promise<string> {
   let output = ""
   output += `# Nifra App Context\n\n`
@@ -127,7 +135,9 @@ export async function generateLlmsTxt(
 
   // 3. API Routes
   output += `## API Routes\n\n`
-  const apiRoutes = reflectRoutes(backend)
+  const apiRoutes = reflectedRoutesFromEvidence(
+    options.evidence ?? snapshotProjectEvidence(backend),
+  )
 
   if (apiRoutes.length === 0) {
     output += `No API routes registered.\n`
@@ -151,7 +161,9 @@ export async function generateLlmsTxt(
           output += `  - Response Schema: \`${tsTypeOf(responseSchema)}\`\n`
         }
         if (s?.errors) {
-          for (const [status, errorSchema] of Object.entries(s.errors)) {
+          for (const status of Object.keys(s.errors)) {
+            const errorSchema = s.errors[status]
+            if (errorSchema === undefined) continue
             const errJson = errorSchema.jsonSchema
             if (errJson !== undefined) {
               output += `  - Error ${status} Schema: \`${tsTypeOf(errJson)}\`\n`

package/src/manifest.ts

@@ -66,7 +66,7 @@ export interface ClientActionResult {
 /** A client-only action wrapper; it never replaces the server action. */
 export type ClientAction = (
   args: ClientActionArgs,
-) => ClientActionResult | void | Promise<ClientActionResult | void>
+) => ClientActionResult | undefined | Promise<ClientActionResult | undefined>
 
 /** Client hooks populated by the generated route entry after a route chunk loads. */
 export interface ClientRouteHooks {

package/src/public-dir.ts

@@ -12,8 +12,10 @@
  * Distinct from `publicPath` in `build.ts`, which is the URL prefix for content-hashed bundle chunks.
  * The names collide and the concepts do not: `publicPath` never covers user-authored files.
  */
-import { realpath } from "node:fs/promises"
+import { constants as FS } from "node:fs"
+import { open, realpath } from "node:fs/promises"
 import { normalize, resolve, sep } from "node:path"
+import { Readable } from "node:stream"
 import { parseByteRange } from "@nifrajs/core/range"
 import { pathnameOf } from "@nifrajs/core/server"
 
@@ -129,54 +131,77 @@ export function servePublicDir(
     ) {
       return undefined
     }
-    const file = Bun.file(resolvedFile)
-    if (!(await file.exists())) return undefined
-    const size = file.size
-    const headers = new Headers({
-      "cache-control": pathname.startsWith(hashedPrefix) ? hashed : assets,
-      // Advertised unconditionally: a client that never sees `accept-ranges` will not attempt a seek,
-      // so a video or audio file under `public/` is scrubbable only once this header is present.
-      "accept-ranges": "bytes",
-    })
-    // `new Response(file)` used to infer the media type, which meant HEAD - built from a null body -
-    // silently lost it. Setting it here is what makes the two methods agree.
-    if (file.type !== "") headers.set("content-type", file.type)
-    const lastModified =
-      Number.isFinite(file.lastModified) && file.lastModified > 0 ? file.lastModified : undefined
-    if (lastModified !== undefined) {
-      headers.set("last-modified", new Date(lastModified).toUTCString())
-    }
-    const head = request.method === "HEAD"
+    // Open the canonical path once and stream from that descriptor. Reopening the pathname after
+    // realpath containment checks would let a writable public tree swap a symlink between validation
+    // and the actual read. O_NOFOLLOW also rejects a final-component symlink if one appears before
+    // the open; the descriptor then pins the bytes for the lifetime of the response.
+    let handle: Awaited<ReturnType<typeof open>> | undefined
+    try {
+      handle = await open(resolvedFile, FS.O_RDONLY | FS.O_NOFOLLOW)
+      const stat = await handle.stat()
+      if (!stat.isFile()) return undefined
+      const size = stat.size
+      const file = Bun.file(resolvedFile)
+      const headers = new Headers({
+        "cache-control": pathname.startsWith(hashedPrefix) ? hashed : assets,
+        // Advertised unconditionally: a client that never sees `accept-ranges` will not attempt a seek,
+        // so a video or audio file under `public/` is scrubbable only once this header is present.
+        "accept-ranges": "bytes",
+      })
+      // `new Response(file)` used to infer the media type, which meant HEAD - built from a null body -
+      // silently lost it. Setting it here is what makes the two methods agree.
+      if (file.type !== "") headers.set("content-type", file.type)
+      const lastModified =
+        Number.isFinite(stat.mtimeMs) && stat.mtimeMs > 0 ? stat.mtimeMs : undefined
+      if (lastModified !== undefined) {
+        headers.set("last-modified", new Date(lastModified).toUTCString())
+      }
+      const head = request.method === "HEAD"
 
-    if (isNotModified(request, lastModified)) {
-      headers.delete("content-type")
-      return new Response(null, { status: 304, headers })
-    }
+      if (isNotModified(request, lastModified)) {
+        headers.delete("content-type")
+        return new Response(null, { status: 304, headers })
+      }
 
-    const rangeHeader = request.headers.get("range")
-    const range =
-      rangeHeader !== null && ifRangeMatches(request.headers.get("if-range"), lastModified)
-        ? parseByteRange(rangeHeader, size)
-        : ({ kind: "none" } as const)
+      const rangeHeader = request.headers.get("range")
+      const range =
+        rangeHeader !== null && ifRangeMatches(request.headers.get("if-range"), lastModified)
+          ? parseByteRange(rangeHeader, size)
+          : ({ kind: "none" } as const)
 
-    if (range.kind === "unsatisfiable") {
-      headers.delete("content-type")
-      headers.set("content-range", `bytes */${size}`)
-      return new Response(null, { status: 416, headers })
-    }
+      if (range.kind === "unsatisfiable") {
+        headers.delete("content-type")
+        headers.set("content-range", `bytes */${size}`)
+        return new Response(null, { status: 416, headers })
+      }
 
-    if (range.kind === "satisfiable" && range.ranges.length === 1) {
-      const { start, end } = range.ranges[0]!
-      headers.set("content-range", `bytes ${start}-${end}/${size}`)
-      headers.set("content-length", String(end - start + 1))
-      // `slice` keeps the read lazy: only the selected window is ever pulled off disk.
-      return new Response(head ? null : file.slice(start, end + 1), { status: 206, headers })
-    }
+      const body = (start?: number, end?: number): ReadableStream<Uint8Array> => {
+        const stream = handle!.createReadStream({ start, end })
+        // FileHandle.createReadStream owns closing the descriptor after EOF/abort.
+        handle = undefined
+        return Readable.toWeb(stream) as unknown as ReadableStream<Uint8Array>
+      }
+
+      if (range.kind === "satisfiable" && range.ranges.length === 1) {
+        const { start, end } = range.ranges[0]!
+        headers.set("content-range", `bytes ${start}-${end}/${size}`)
+        headers.set("content-length", String(end - start + 1))
+        return new Response(head ? null : body(start, end), { status: 206, headers })
+      }
 
-    // Multiple ranges would require assembling `multipart/byteranges`, and doing that for a file on
-    // disk means buffering the whole representation to serve a request that asked for less of it.
-    // RFC 9110 lets a server ignore Range entirely, so the full body is the conformant answer here.
-    if (head) headers.set("content-length", String(size))
-    return new Response(head ? null : file, { headers })
+      // Multiple ranges would require assembling `multipart/byteranges`, and doing that for a file on
+      // disk means buffering the whole representation to serve a request that asked for less of it.
+      // RFC 9110 lets a server ignore Range entirely, so the full body is the conformant answer here.
+      headers.set("content-length", String(size))
+      return new Response(head ? null : body(), { headers })
+    } finally {
+      if (handle !== undefined) {
+        try {
+          await handle.close()
+        } catch {
+          // Closing a descriptor is best-effort after the response decision is made.
+        }
+      }
+    }
   }
 }

package/src/trusted-html.ts

@@ -0,0 +1,44 @@
+/**
+ * A framework-neutral trust boundary for the small set of adapters that intentionally inject HTML.
+ *
+ * `TrustedHtml` is a type-level brand, not a sanitizer. Callers must sanitize untrusted input with a
+ * well-reviewed allowlist sanitizer before calling {@link trustHtml}; build-time markdown and
+ * application-owned templates may use it directly after review. Keeping the constructor explicit
+ * makes every raw-HTML sink audit-greppable and prevents an ordinary string from type-checking by
+ * accident.
+ */
+
+declare const TRUSTED_HTML_BRAND: unique symbol
+declare const SANITIZED_HTML_BRAND: unique symbol
+
+export type TrustedHtml = string & { readonly [TRUSTED_HTML_BRAND]: "trusted-html" }
+
+/** HTML returned by an explicit, caller-supplied sanitizer. It is also trusted by the adapters. */
+export type SanitizedHtml = TrustedHtml & { readonly [SANITIZED_HTML_BRAND]: "sanitized-html" }
+
+/** The only contract a project-specific, allowlist-based HTML sanitizer must satisfy. */
+export type HtmlSanitizer = (value: string) => string
+
+/** Mark already-sanitized or application-owned HTML for an intentional raw-HTML adapter sink. */
+export function trustHtml(value: string): TrustedHtml {
+  if (typeof value !== "string") throw new TypeError("trusted HTML must be a string")
+  return value as TrustedHtml
+}
+
+/**
+ * Run untrusted markup through an explicit sanitizer before it reaches a raw-HTML adapter.
+ *
+ * Nifra deliberately does not bundle a sanitizer: applications choose the maintained allowlist
+ * appropriate to their runtime and content policy. Requiring the sanitizer as an argument prevents
+ * `sanitizedHtml(value)` from silently becoming an alias for the unsafe trust operation.
+ */
+export function sanitizeHtml(value: string, sanitizer: HtmlSanitizer): SanitizedHtml {
+  if (typeof value !== "string") throw new TypeError("HTML to sanitize must be a string")
+  if (typeof sanitizer !== "function") throw new TypeError("an HTML sanitizer is required")
+  const sanitized = sanitizer(value)
+  if (typeof sanitized !== "string") throw new TypeError("HTML sanitizer must return a string")
+  return sanitized as SanitizedHtml
+}
+
+/** Explicit sanitized-content vocabulary for callers and security audits. */
+export const sanitizedHtml = sanitizeHtml