@nifrajs/web 5.0.0 → 5.1.0

package/src/internal/render-document.ts

@@ -6,15 +6,12 @@ import { DEFERRED_ERROR_CODE, DEFERRED_RUNTIME, prepareDeferred } from "../defer
 import { ISR_REVALIDATE_HEADER, ISR_REVALIDATE_TAGS_HEADER, serializeISRTags } from "../isr.ts"
 import type {
   Loader as LayoutLoader,
-  LinkDescriptor,
   Meta,
-  MetaDescriptor,
   MetaInput,
   RouteModule,
-  ScriptDescriptor,
   UnsafeScriptDescriptor,
 } from "../manifest.ts"
-import type { MatchChain, RenderAdapter, RenderProps } from "../render-seam.ts"
+import type { DocumentParts, MatchChain, RenderAdapter, RenderProps } from "../render-seam.ts"
 import {
   ACTION_GLOBAL,
   BOUNDARY_GLOBAL,
@@ -201,8 +198,10 @@ export interface RenderPageOptions {
 export interface RenderAssemblyCache {
   /** Shell up to (not including) the deferred-runtime insertion point. */
   shellPre?: string
-  /** Shell from after the deferred-runtime insertion point through the open `#root` container. */
+  /** Shell from after the deferred-runtime insertion point through `<body>`. */
   shellPost?: string
+  /** The open `#root` container. */
+  rootOpen?: string
   /** Tail opener: the handover script open tag + the data member's key. */
   tailPre?: string
   /** Tail from after the per-request handover members (the route id, prerendered paths, the handover
@@ -423,7 +422,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
       ? `<link rel="modulepreload" href="${escapeAttr(clientEntry ?? "")}">${preloadLinks}`
       : ""
     slot.shellPre = `<!doctype html><html${htmlAttrs}><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">${hydrationGuard}<title>${escapeHtml(head?.title ?? title)}</title>${headTags(head, nonce)}${styleLinks}${entryPreloads}`
-    slot.shellPost = `${islandPreloads}${hydrationHead}</head><body><div id="${escapeAttr(rootId)}"${rootMarker}>`
+    slot.shellPost = `${islandPreloads}${hydrationHead}</head><body>`
+    slot.rootOpen = `<div id="${escapeAttr(rootId)}"${rootMarker}>`
     // Island bundles load regardless of `hydrate` - a static page (hydrate:false) ships no framework
     // client but can still mount no-framework islands (`@nifrajs/web/islands`).
     let islandTags = ""
@@ -441,7 +441,13 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // The deferred runtime rides only on a hydrating page (a static page has no client takeover), and
   // only when something actually deferred - matching the pre-cache emission exactly.
   const runtimeSeam = hydrate && allDeferred.length > 0 ? deferredRuntime : ""
-  const shellHtml = `${slot.shellPre}${runtimeSeam}${slot.shellPost}`
+  const shellHtml = `${slot.shellPre}${runtimeSeam}${slot.shellPost}${slot.rootOpen}`
+  const parts: DocumentParts | undefined =
+    adapter.documentParts === true ? { head: "", body: "" } : undefined
+  const shellOf = (): string =>
+    parts === undefined || (parts.head === "" && parts.body === "")
+      ? shellHtml
+      : `${slot.shellPre}${runtimeSeam}${parts.head}${slot.shellPost}${parts.body}${slot.rootOpen}`
   // Closes the hydration container; deferred resolve scripts go AFTER it (outside `#root`) so they
   // aren't part of the adapter's hydrated tree (an inline script inside it breaks hydration).
   const closeRootHtml = "</div>"
@@ -504,13 +510,22 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
   // gets an automatic Content-Length. A render throw surfaces here exactly as the streaming path's
   // shell-readiness `await` does, so the `_error` boundary still maps it to a status.
   if (allDeferred.length === 0 && adapter.renderToString !== undefined) {
-    const out = adapter.renderToString(chain, renderProps)
+    const out =
+      parts !== undefined
+        ? adapter.renderToString(
+            chain,
+            renderProps,
+            nonce === undefined ? { parts } : { nonce, parts },
+          )
+        : nonce === undefined
+          ? adapter.renderToString(chain, renderProps)
+          : adapter.renderToString(chain, renderProps, { nonce })
     return typeof out === "string"
-      ? new BufferedRenderedPage(shellHtml + out + closeRootHtml + tailHtml, status, headers)
+      ? new BufferedRenderedPage(shellOf() + out + closeRootHtml + tailHtml, status, headers)
       : out.then(
           (bodyHtml) =>
             new BufferedRenderedPage(
-              shellHtml + bodyHtml + closeRootHtml + tailHtml,
+              shellOf() + bodyHtml + closeRootHtml + tailHtml,
               status,
               headers,
             ),
@@ -521,7 +536,8 @@ export function renderPageResult(options: RenderPageInput): MaybePromise<Rendere
     adapter,
     chain,
     renderProps,
-    shellHtml,
+    shellOf,
+    parts,
     closeRootHtml,
     allDeferred,
     tailHtml,
@@ -536,7 +552,8 @@ async function renderStreamedPage(
   adapter: RenderAdapter,
   chain: readonly unknown[],
   renderProps: RenderProps,
-  shellHtml: string,
+  shellOf: () => string,
+  parts: DocumentParts | undefined,
   closeRootHtml: string,
   allDeferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>,
   tailHtml: string,
@@ -550,13 +567,20 @@ async function renderStreamedPage(
   // (React: on-shell-ready; Solid: synchronously), so a shell-render throw surfaces before any byte is
   // sent. A *mid*-stream failure errors the body instead.
   const enc = TEXT_ENCODER
-  const shell = enc.encode(shellHtml)
   const closeRoot = enc.encode(closeRootHtml)
   const tail = enc.encode(tailHtml)
   const appStream =
-    nonce === undefined
-      ? await adapter.renderToStream(chain, renderProps)
-      : await adapter.renderToStream(chain, renderProps, { nonce })
+    parts !== undefined
+      ? await adapter.renderToStream(
+          chain,
+          renderProps,
+          nonce === undefined ? { parts } : { nonce, parts },
+        )
+      : nonce === undefined
+        ? await adapter.renderToStream(chain, renderProps)
+        : await adapter.renderToStream(chain, renderProps, { nonce })
+  // After the render: an adapter fills its document parts before handing back the stream.
+  const shell = enc.encode(shellOf())
   const body = streamDocument(shell, appStream, closeRoot, allDeferred, tail, enc, nonceAttr)
   return new Response(body, { status, headers })
 }
@@ -1123,68 +1147,6 @@ function headTags(head: Meta | undefined, documentNonce?: string): string {
   return out
 }
 
-/**
- * A `<link rel="canonical">` descriptor for a route's `meta.link`. The canonical URL tells search
- * engines which URL is authoritative for a page (deduping query-string / tracking variants).
- *
- * ```ts
- * export const meta = (a) => ({ link: [canonical(`https://site.com/posts/${a.params.slug}`)] })
- * ```
- */
-export function canonical(href: string): LinkDescriptor {
-  return { rel: "canonical", href }
-}
-
-/** Inputs for {@link openGraph} - the common Open Graph properties. All optional; only the provided
- * ones become tags. `type` defaults to `"website"`. */
-export interface OpenGraphInput {
-  readonly title?: string
-  readonly description?: string
-  /** Absolute URL of the share image (`og:image`). */
-  readonly image?: string
-  /** Canonical URL of the page (`og:url`). */
-  readonly url?: string
-  /** Object type (`og:type`) - `"website"`, `"article"`, … Default `"website"`. */
-  readonly type?: string
-}
-
-/**
- * Build the Open Graph `<meta property="og:*">` entries for a route's `meta.meta`. Returns only the
- * properties you supplied (plus `og:type`, defaulting to `"website"`), so it composes with other meta.
- *
- * ```ts
- * export const meta = { meta: [...openGraph({ title: "Nifra", image: "https://site.com/og.png" })] }
- * ```
- */
-export function openGraph(input: OpenGraphInput): MetaDescriptor[] {
-  const tags: MetaDescriptor[] = []
-  const add = (property: string, content: string | undefined): void => {
-    if (content !== undefined) tags.push({ property, content })
-  }
-  add("og:title", input.title)
-  add("og:description", input.description)
-  add("og:image", input.image)
-  add("og:url", input.url)
-  // `og:type` always present (the spec's required property) - default "website" when unset.
-  tags.push({ property: "og:type", content: input.type ?? "website" })
-  return tags
-}
-
-/**
- * Build a JSON-LD `<script type="application/ld+json">` entry for a route's `meta.script` from a plain
- * object. `JSON.stringify` produces the body; the head renderer breakout-escapes it (see
- * `escapeScriptContent`), so a string field containing `</script>` is embedded safely.
- *
- * ```ts
- * export const meta = {
- *   script: [jsonLd({ "@context": "https://schema.org", "@type": "Article", headline: "Hi" })],
- * }
- * ```
- */
-export function jsonLd(data: Record<string, unknown>): ScriptDescriptor {
-  return { type: "application/ld+json", content: JSON.stringify(data) }
-}
-
 /**
  * Deliberately unsafe escape hatch for executable inline code. The required nonce keeps the result
  * compatible with a strict CSP and makes the security-sensitive choice visible at the call site.

package/src/internal/route-path.ts

@@ -6,3 +6,19 @@
  */
 export const requestPattern = (pattern: string): string =>
   pattern.normalize("NFC").replace(/[^!-~]/gu, encodeURIComponent)
+
+// This module also compiles without the DOM lib; at runtime the name is the browser's own global.
+declare const location: { readonly origin: string } | undefined
+
+/**
+ * An app path as a URL `fetch`, `history` and `location` resolve on this document's own origin. A path
+ * starting `//` or `/\` is the path of a page here (`https://shop.example//evil.example/x`), but resolved
+ * as written it is a protocol-relative URL to another host, so it is anchored to this origin.
+ */
+export const appUrl = (path: string): string =>
+  path.charCodeAt(0) === 47 /* / */ &&
+  (path.charCodeAt(1) === 47 || path.charCodeAt(1) === 92) /* / or \ */ &&
+  typeof location !== "undefined" &&
+  location.origin !== "null"
+    ? location.origin + path
+    : path

package/src/internal/secret-scan.ts

@@ -293,6 +293,98 @@ function formatMatches(text: string): Match[] {
   return matches
 }
 
+/** Words that mark a whole `_`/`-` segment of a value as a stand-in: `your_signing_secret`. */
+const PLACEHOLDER_SEGMENT =
+  /^(?:your|example|placeholder|sample|dummy|changeme|replace|generated|x{3,})$/
+
+const placeholderSegments = (value: string): boolean =>
+  value
+    .toLowerCase()
+    .split(/[_-]/)
+    .some((segment) => PLACEHOLDER_SEGMENT.test(segment))
+
+/** A word-cased label: letters and marks, hyphen-joined words, an acronym. No digits, no runs of
+ * mixed case, no credential punctuation. */
+const LABEL = /^(?:\p{Lu}{1,4}|\p{Lu}?[\p{Ll}\p{M}]+)(?:-(?:\p{Lu}{1,4}|\p{Lu}?[\p{Ll}\p{M}]+))*$/u
+
+/** How many string values a catalog holds at least, and the share of them that is prose. */
+const CATALOG_VALUES = 10
+
+/** Where a `/` starts a regular expression: after anything but a value's end. */
+const VALUE_END = /[\w$)\]}"'`]/
+
+/**
+ * The spans of top-level object literals that read as message catalogs: at least
+ * {@link CATALOG_VALUES} string property values, most of them prose with whitespace. A lexer, not a
+ * parser, so a build scans without TypeScript; strings, comments and regular expressions are skipped.
+ */
+function catalogSpans(text: string): Array<readonly [number, number]> {
+  const spans: Array<readonly [number, number]> = []
+  let depth = 0
+  let start = 0
+  let values = 0
+  let prose = 0
+  // Whether the open top-level brace starts an object literal, not a block such as a function body.
+  let literal = false
+  let last = ""
+  let i = 0
+  while (i < text.length) {
+    const c = text.charAt(i)
+    if (c === "/" && text[i + 1] === "/") {
+      const end = text.indexOf("\n", i)
+      i = end === -1 ? text.length : end
+      continue
+    }
+    if (c === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2)
+      i = end === -1 ? text.length : end + 2
+      continue
+    }
+    if (c === '"' || c === "'" || c === "`" || (c === "/" && !VALUE_END.test(last))) {
+      let j = i + 1
+      let inClass = false
+      for (; j < text.length; j++) {
+        const d = text[j]
+        if (d === "\\") {
+          j++
+          continue
+        }
+        if (c !== "`" && d === "\n") break
+        if (c !== "/") {
+          if (d === c) break
+          continue
+        }
+        if (d === "[") inClass = true
+        else if (d === "]") inClass = false
+        else if (d === "/" && !inClass) break
+      }
+      // A string after `:` is a property's value.
+      if (depth > 0 && c !== "/" && c !== "`" && last === ":") {
+        values++
+        if (/\s/.test(text.slice(i + 1, j))) prose++
+      }
+      last = c
+      i = j + 1
+      continue
+    }
+    if (c === "{") {
+      if (depth === 0) {
+        start = i
+        values = 0
+        prose = 0
+        const word = /([\w$]+)\s*$/.exec(text.slice(Math.max(0, i - 16), i))?.[1]
+        literal = last === "" || "=(,:[?".includes(last) || word === "default"
+      }
+      depth++
+    } else if (c === "}" && depth > 0 && --depth === 0) {
+      if (literal && values >= CATALOG_VALUES && prose * 2 > values) spans.push([start, i + 1])
+    }
+    if (!/\s/.test(c)) last = c
+    i++
+  }
+  return spans
+}
+
 /** The credential a literal given to `name` carries, when the name is secret-like and the literal
  * looks random. */
 function credentialOf(name: string, value: string): string | undefined {
@@ -304,6 +396,7 @@ function credentialOf(name: string, value: string): string | undefined {
     secret === undefined ||
     PUBLIC_VALUE.test(secret) ||
     PLACEHOLDER.test(secret) ||
+    placeholderSegments(secret) ||
     !looksRandom(secret, 16)
   )
     return undefined
@@ -312,9 +405,16 @@ function credentialOf(name: string, value: string): string | undefined {
 
 function assignedMatches(text: string): Match[] {
   const matches: Match[] = []
+  let catalogs: ReadonlyArray<readonly [number, number]> | undefined
+  /** A label in a message catalog: `password: "Lykilorð"` names the field in another language. */
+  const catalogLabel = (value: string, valueAt: number): boolean => {
+    if (!LABEL.test(value)) return false
+    catalogs ??= catalogSpans(text)
+    return catalogs.some(([start, end]) => valueAt > start && valueAt < end)
+  }
   const add = (name: string, value: string, valueAt: number): void => {
     const secret = credentialOf(name, value)
-    if (secret === undefined) return
+    if (secret === undefined || catalogLabel(value, valueAt)) return
     matches.push({
       rule: "assigned-secret",
       // The credential is the value's tail: a header value's scheme is not part of it.

package/src/internal/web-app.ts

@@ -199,8 +199,10 @@ export interface CreateWebAppOptions<Env = unknown> {
    * team - unreleased feature names, internal hostnames, and "don't touch X yet" notes live there
    * routinely. Turn it on only for a repo whose guidelines you would publish as a page. */
   readonly publishLocalGuidelines?: boolean
-  /** Serve `/llms.txt` and `/llms-full.txt` (default `true`): the page routes, and the backend routes
-   * when the backend is mounted over HTTP at {@link apiPrefix}. `false` registers neither path. */
+  /** Serve `/llms.txt` and `/llms-full.txt`: the page routes, and the backend routes when the backend
+   * is mounted over HTTP at {@link apiPrefix}, with their request and response schemas in the full
+   * text. **Off by default**: both are public and unauthenticated, and they list every route, admin
+   * and internal ones included. Turn it on for an app whose whole surface you would publish. */
   readonly llmsTxt?: boolean
   /** SSG: per dynamic route pattern, its `getStaticPaths` `fallback` (from `enumerateStaticRoutes` or
    * the build's `prerendered.json`). A route mapped to `"404"` rejects any path NOT in
@@ -458,8 +460,10 @@ export function createWebApp<Env = unknown>(
     cacheChannel,
   })
 
+  let ownsRootCatchAll = false
   for (const route of manifest.routes) {
     const pattern = requestPattern(route.pattern)
+    if (pattern.startsWith("/*")) ownsRootCatchAll = true
     app.register(
       "GET",
       pattern,
@@ -473,7 +477,7 @@ export function createWebApp<Env = unknown>(
   // llms.txt & llms-full.txt describe what a visitor can reach: the pages, and the backend only when it
   // is served over HTTP - a backend the loaders call in-process has no public surface to describe. An
   // app route at either path takes precedence, and each text is built once per app.
-  if (options.llmsTxt !== false) {
+  if (options.llmsTxt === true) {
     const llmsOptions = {
       includeLocalGuidelines: options.publishLocalGuidelines === true,
       apiPathPrefix: apiStrip ? mountPathPrefix(apiPrefix) : "",
@@ -518,8 +522,9 @@ export function createWebApp<Env = unknown>(
   }
 
   // Wildcard catch-all: unmatched paths render the nearest `_404` (404), or a plain text 404 if
-  // absent.
-  app.register("GET", "/*", undefined, pageExecutor.fallback)
+  // absent. A root catch-all page (`[...slug].tsx`) already answers every path, the root included,
+  // and the router refuses a second `/*` under another param name.
+  if (!ownsRootCatchAll) app.register("GET", "/*", undefined, pageExecutor.fallback)
 
   const evidenceProvider: ComposedEvidenceProvider = async (passed) => {
     const { traverseEvidence } = await import("./evidence-traversal.ts")

package/src/internal/without-query.ts

@@ -0,0 +1,8 @@
+/** A module id or specifier up to its first `?` or `#`. An index scan, since `/[?#].*$/` retries
+ * from every `#` and runs in quadratic time on a long run of them before a line break. */
+export function withoutQuery(value: string): string {
+  const query = value.indexOf("?")
+  const hash = value.indexOf("#")
+  const cut = query === -1 ? hash : hash === -1 ? query : Math.min(query, hash)
+  return cut === -1 ? value : value.slice(0, cut)
+}

package/src/internal/zone-graph.ts

@@ -19,6 +19,7 @@ import {
 } from "../zones.ts"
 import { codeUnitOrder } from "./code-unit-order.ts"
 import { isBareNodeBuiltin } from "./node-builtins.ts"
+import { withoutQuery } from "./without-query.ts"
 
 /** What a graph module id names. */
 export type ModuleSource =
@@ -30,9 +31,8 @@ export type ModuleSource =
 
 /** A namespace prefix needs two characters, so a Windows drive letter still reads as a path. */
 const NAMESPACED = /^([a-z][\w.+-]+):(.*)$/i
-const stripQuery = (id: string): string => id.replace(/[?#].*$/, "")
 const virtualOf = (rest: string): ModuleSource => {
-  const file = stripQuery(rest)
+  const file = withoutQuery(rest)
   return isAbsolute(file) && existsSync(file) ? { kind: "virtual", file } : { kind: "virtual" }
 }
 
@@ -42,7 +42,7 @@ export function bunModuleSource(cwd: string): (id: string) => ModuleSource {
     if (id.startsWith("node:") || id.startsWith("bun:")) return { kind: "builtin" }
     const namespaced = NAMESPACED.exec(id)
     if (namespaced !== null && namespaced[1] !== "file") return virtualOf(namespaced[2] ?? "")
-    return { kind: "file", file: resolve(cwd, stripQuery(namespaced?.[2] ?? id)) }
+    return { kind: "file", file: resolve(cwd, withoutQuery(namespaced?.[2] ?? id)) }
   }
 }
 
@@ -50,7 +50,7 @@ export function bunModuleSource(cwd: string): (id: string) => ModuleSource {
 export function rollupModuleSource(id: string): ModuleSource {
   if (id.startsWith("node:") || id.includes("__vite-browser-external")) return { kind: "builtin" }
   if (id.startsWith("\0")) return virtualOf(id.slice(1).replace(/^[\w-]+:/, ""))
-  const file = stripQuery(id)
+  const file = withoutQuery(id)
   return isAbsolute(file) ? { kind: "file", file } : { kind: "virtual" }
 }
 
@@ -233,7 +233,9 @@ export function verifyClientGraph(
     if (file === undefined) continue
     const classification = classifier.classify(file)
     let reason = browserDenial(classification)
-    for (const spec of specifiers.get(id) ?? []) reason ??= browserDenial(classification, spec)
+    // An import that names a package entry is judged by that entry's own declared side.
+    for (const spec of specifiers.get(id) ?? [])
+      reason ??= browserDenial(classifier.classify(file, spec), spec)
     if (reason === undefined && BROWSER_CODE.has(classification.zone))
       reason = options.privateEnv?.(file)
     if (reason !== undefined) denied.set(id, reason)
@@ -406,7 +408,18 @@ export function verifyServerGraph(
       const target = resolveEdge(im)
       if (target === undefined) continue
       out.push({ to: target, label: im.original ?? labelOf(target) })
-      const to = classOf(target)
+      const targetFile = fileOf(target)
+      const to =
+        im.original === undefined || targetFile === undefined
+          ? classOf(target)
+          : classifier.classify(targetFile, im.original)
+      if (to?.zone === "error" && to.entry !== undefined)
+        found.push({
+          at: id,
+          module: labelOf(target),
+          reason: to.reason,
+          tail: im.original ?? labelOf(target),
+        })
       if (from === undefined || to === undefined || from.zone === "error" || to.zone === "error")
         continue
       const componentBridge =

package/src/isr.ts

@@ -7,6 +7,7 @@
  * This module is the store primitive; the SWR wrapper (`withISR`) builds on it next.
  */
 import { isAuthenticatedRequest, writableResponse } from "@nifrajs/core/server"
+import { readBoundedBytes, TransportCodecError } from "@nifrajs/core/transport-codec"
 import { isDraftEnabled } from "./draft.ts"
 import { assertTokenSecret, timingSafeEqual } from "./internal/timing-safe-equal.ts"
 
@@ -1139,6 +1140,8 @@ export interface CdnPurgeTarget {
 /** Most paths and tags one revalidation request may name, so a leaked token cannot fan out. */
 export const MAX_REVALIDATE_PATHS = 100
 export const MAX_REVALIDATE_TAGS = MAX_ISR_TAGS
+// Room for a full batch of long paths; a purge body past it is refused before it is buffered.
+const MAX_REVALIDATE_BODY_BYTES = 1024 * 1024
 
 export interface RevalidateEndpointOptions {
   readonly store: CacheStore
@@ -1180,7 +1183,7 @@ const stringList = (value: unknown): string[] | null | undefined => {
  * `?path=/blog/x`, `?tag=products`, a JSON `{ "path": "/blog/x" }` / `{ "tag": "products" }` body, or a
  * batch `{ "paths": [...], "tags": [...] }` of at most 100 paths and 32 tags.
  * The token is checked in **constant time** (wrong/missing → `401`); malformed targets → `400`;
- * non-POST → `405`. A store without tag support returns `501` for tag requests. Mount it on a nifra route, e.g.
+ * a JSON body over 1 MiB → `413`; non-POST → `405`. A store without tag support returns `501` for tag requests. Mount it on a nifra route, e.g.
  * `app.post("/__nifra/revalidate", (c) => handler(c.req))`.
  */
 export function revalidateEndpoint(
@@ -1205,7 +1208,15 @@ export function revalidateEndpoint(
     let tag = url.searchParams.get("tag")
     let batch: { paths: string[]; tags: string[] } | undefined
     if (path === null && tag === null) {
-      const body: unknown = await req.json().catch(() => null)
+      let body: unknown = null
+      try {
+        const bytes = await readBoundedBytes(new Response(req.body, { headers: req.headers }), {
+          maxBytes: MAX_REVALIDATE_BODY_BYTES,
+        })
+        body = JSON.parse(new TextDecoder().decode(bytes))
+      } catch (error) {
+        if (error instanceof TransportCodecError) return jsonError(413, "body_too_large")
+      }
       if (typeof body === "object" && body !== null) {
         const candidate = body as { path?: unknown; tag?: unknown; paths?: unknown; tags?: unknown }
         if (candidate.paths !== undefined || candidate.tags !== undefined) {

package/src/manifest.ts

@@ -337,6 +337,15 @@ export interface RouteModule {
   /** Layout loader that must run before actions and is not retained across the action's render. */
   readonly gate?: boolean
   readonly action?: Action
+  /**
+   * Backend half only: which browser origins may POST to {@link action}. When omitted, a request
+   * whose `Origin` is another site's is refused with 403 before middleware, gates or the action run;
+   * requests without an `Origin` (non-browser clients) pass. An array allows exactly those origins
+   * (and refuses a request without one); a function decides, receiving `null` when there is none.
+   * Use it for a callback a third party posts to, such as an identity provider's `form_post`.
+   * `Origin` is browser-enforced, not authentication: keep the action's own auth checks.
+   */
+  readonly allowedOrigins?: ReadonlyArray<string> | ((origin: string | null) => boolean)
   /**
    * Backend half only: the schema of what {@link loader} sends to the browser. Required whenever the
    * loader returns data. Keys it does not declare are dropped before the page renders; a declared
@@ -642,6 +651,7 @@ export const BACKEND_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "middleware",
   "gate",
   "shouldRevalidate",
+  "allowedOrigins",
 ])
 
 const routeError = (message: string): Error => new Error(`[nifra/web] ${message}`)