@bractjs/bractjs 0.1.28 → 0.1.29

package/src/server/request-handler.ts

@@ -6,10 +6,12 @@ import { runLoaders, runAction, buildLoaderArgs, runRouteContext, runBeforeLoad
 import { validateSearch } from "./search.ts";
 import { renderRoute, type ServerManifest } from "./render.ts";
 import { resolveMeta, mergeMeta } from "./meta.ts";
+import { resolveHeaders } from "./headers.ts";
+import { buildMatches } from "./matches.ts";
 import { json, error, sanitizeRedirect } from "./response.ts";
 import { isRedirect, isHttpError } from "../shared/errors.ts";
 import { isExplicitDev } from "./env.ts";
-import { pipeline, type MiddlewareContext } from "./middleware.ts";
+import { runRouteMiddleware, collectRouteMiddleware, type MiddlewareContext } from "./middleware.ts";
 import { BractJSProvider } from "../shared/context.ts";
 import { isAllowedMutation, csrfForbiddenResponse } from "./csrf.ts";
 import { getCspNonce } from "./csp.ts";
@@ -38,15 +40,15 @@ const MAX_FORM_BYTES = 10 * 1_048_576; // 10 MiB
 export async function handleRequest(
   request: Request,
   trie: TrieNode,
-  config: HandlerConfig
+  config: HandlerConfig,
+  context: Record<string, unknown> = {},
 ): Promise<Response> {
-  const ctx: MiddlewareContext = {
-    request,
-    params: {},
-    context: {},
-  };
-
-  return pipeline.run(ctx, () => route(request, trie, config, ctx.context));
+  // The global pipeline is run once by buildFetchHandler around the whole
+  // dispatch (so it also covers /api, /_action, /_stream, /_image, static).
+  // We receive the shared, already-running `context` here and only run the
+  // per-route (nested) middleware chain — running the global pipeline again
+  // would double-invoke cors()/csp()/etc. for SSR documents.
+  return route(request, trie, config, context);
 }
 
 async function route(
@@ -92,24 +94,42 @@ async function route(
       // never see unvalidated input, and a 400 here is cheaper than a wasted
       // context-factory/loader run. The thrown 400 Response propagates below.
       const search = await validateSearch(chain.route.searchSchema, targetUrl);
+
       // SECURITY(high): /_data must run the same auth/redirect gates as a full
       // page request — otherwise a SPA-style soft navigation to a protected
-      // route would bypass beforeLoad() / defineContext() and leak loader data.
-      const routeContext = await runRouteContext(
-        chain.route as Parameters<typeof runRouteContext>[0],
-        loaderRequest,
-        match.params,
-        context,
-      );
-      const args = buildLoaderArgs(loaderRequest, match.params, routeContext, search);
-      const beforeLoadResponse = await runBeforeLoad(chain.route, args);
-      if (beforeLoadResponse) return beforeLoadResponse;
-      const results = await runLoaders(chain, args, onError);
-      // Merged meta must ride along: ClientRouter re-renders the document head
-      // from this payload on soft navigation, and the initial __BRACTJS_DATA__
-      // already carries the merged shape.
-      const meta = mergeMeta(resolveMeta(chain, results, match.params));
-      return json({ root: results.root, layouts: results.layouts, route: results.route, params: match.params, meta, search });
+      // route would bypass nested middleware / beforeLoad() / defineContext()
+      // and leak loader data. Run the route middleware chain around the work,
+      // sharing the same mutable `context` so a gate can set/clear fields.
+      const mwCtx: MiddlewareContext = { request: loaderRequest, params: match.params, context };
+      return runRouteMiddleware(collectRouteMiddleware(chain), mwCtx, async () => {
+        const routeContext = await runRouteContext(
+          chain.route as Parameters<typeof runRouteContext>[0],
+          loaderRequest,
+          match.params,
+          mwCtx.context,
+        );
+        const args = buildLoaderArgs(loaderRequest, match.params, routeContext, search);
+        const beforeLoadResponse = await runBeforeLoad(chain.route, args);
+        if (beforeLoadResponse) return beforeLoadResponse;
+        const results = await runLoaders(chain, args, onError);
+        // Merged meta must ride along: ClientRouter re-renders the document head
+        // from this payload on soft navigation, and the initial __BRACTJS_DATA__
+        // already carries the merged shape.
+        const meta = mergeMeta(resolveMeta(chain, results, match.params));
+        const matches = buildMatches(chain, results, match.params, targetPathname);
+        const dataRes = json({ root: results.root, layouts: results.layouts, route: results.route, params: match.params, meta, search, matches });
+        // Apply the route `headers()` chain so a soft navigation gets the same
+        // Cache-Control/ETag/Vary as the full document load (renderRoute applies
+        // them there). Content-Type stays application/json.
+        const dataHeaders = resolveHeaders(chain, results, match.params, loaderRequest);
+        if (dataHeaders) {
+          dataHeaders.forEach((value, key) => {
+            if (key.toLowerCase() === "content-type") return;
+            dataRes.headers.set(key, value);
+          });
+        }
+        return dataRes;
+      });
     } catch (err) {
       if (isRedirect(err)) return sanitizeRedirect(err as Response, request.url);
       // A non-redirect Response (e.g. the 400 thrown by search validation)
@@ -138,12 +158,19 @@ async function route(
     throw err;
   }
 
+  // Nested route middleware (root → layout → route) wraps the action, loaders,
+  // and render. It shares the same mutable `context` object, runs *inside* the
+  // global pipeline, and can short-circuit (auth gate / redirect) by returning
+  // a Response. Empty chains call the work directly (no overhead).
+  const mwCtx: MiddlewareContext = { request, params: match.params, context };
+  return runRouteMiddleware(collectRouteMiddleware(chain), mwCtx, async () => {
+
   // Run per-route context factory (defineContext export) before loaders.
   const routeContext = await runRouteContext(
     chain.route as Parameters<typeof runRouteContext>[0],
     request,
     match.params,
-    context,
+    mwCtx.context,
   );
   const args = buildLoaderArgs(request, match.params, routeContext, search);
 
@@ -227,6 +254,10 @@ async function route(
   const RouteComponent = routeSsr === true ? chain.route.default : chain.route.Fallback;
   const ssrMode = routeSsr === true ? undefined : routeSsr === false ? "client-only" as const : "data-only" as const;
 
+  // useMatches() payload — the chain's handle + data, for breadcrumbs etc.
+  // Built from loaderChain so the loader slices line up with what ran.
+  const matches = buildMatches(loaderChain, loaderResults, match.params, pathname);
+
   // Wrap root in BractJSProvider so <Outlet> can render the route component
   // server-side without needing a ClientRouter.
   const shell = createElement(
@@ -241,12 +272,17 @@ async function route(
         RouteComponent,
         location: { pathname, search: url.search, hash: "", state: null, key: "default" },
         search,
+        matches,
       },
       children: createElement(RootComponent),
     },
   );
 
   const meta = resolveMeta(chain, loaderResults, match.params);
+  // Route `headers()` chain (Cache-Control/ETag/Vary/…), applied on top of the
+  // baseline document headers in renderRoute. Uses the loaders that actually
+  // ran (loaderChain) so a selective-SSR route's headers() sees the same data.
+  const routeHeaders = resolveHeaders(loaderChain, loaderResults, match.params, request);
 
   return renderRoute({
     shell,
@@ -257,9 +293,13 @@ async function route(
     search,
     manifest,
     meta,
+    matches,
+    headers: routeHeaders,
     routeFile: match.routeFile.filePath,
     // Set by the opt-in csp() middleware; undefined otherwise.
-    nonce: getCspNonce(context),
+    nonce: getCspNonce(mwCtx.context),
     ssrMode,
   });
+
+  });
 }

package/src/server/scanner.ts

@@ -2,7 +2,11 @@ import { basename } from "node:path";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
-export type Segment = string | { param: string } | { catchAll: string };
+export type Segment =
+  | string
+  | { param: string }
+  | { optional: string }
+  | { catchAll: string };
 
 export interface RouteFile {
   filePath: string;
@@ -12,12 +16,22 @@ export interface RouteFile {
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
+/** A path segment that is a route group: `(marketing)`. Contributes a layout
+ *  folder but no URL segment. */
+export function isRouteGroupSegment(seg: string): boolean {
+  return seg.startsWith("(") && seg.endsWith(")") && seg.length > 2;
+}
+
 export function pathToSegments(pattern: string): Segment[] {
   if (pattern === "") return [];
   return pattern.split("/").map((seg) => {
     if (seg.startsWith("[...") && seg.endsWith("]")) {
       return { catchAll: seg.slice(4, -1) };
     }
+    // Optional param: [[id]] → matches with or without the segment present.
+    if (seg.startsWith("[[") && seg.endsWith("]]")) {
+      return { optional: seg.slice(2, -2) };
+    }
     if (seg.startsWith("[") && seg.endsWith("]")) {
       return { param: seg.slice(1, -1) };
     }
@@ -29,20 +43,48 @@ export function filePathToPattern(filePath: string): string {
   // Strip "routes/" prefix and file extension
   let path = filePath.replace(/^routes\//, "").replace(/\.(tsx|ts)$/, "");
 
+  // Drop route-group segments — `(marketing)/about` → `about`. They group
+  // files (and their layout.tsx) without adding a URL segment.
+  path = path
+    .split("/")
+    .filter((seg) => !isRouteGroupSegment(seg))
+    .join("/");
+
   // Handle nested _index (e.g. blog/_index → blog)
   path = path.replace(/\/_index$/, "");
 
   // Handle root _index
   if (path === "_index" || path === "") return "";
 
-  // Convert [param] and [...catchAll] segments — keep as-is for pattern string
+  // Convert [param], [[optional]], and [...catchAll] segments — keep as-is for
+  // the pattern string.
   return path;
 }
 
+/**
+ * Ancestor directory chain (relative to `routes/`) for a route file, outermost
+ * → innermost, used to locate nesting `layout.tsx` files. Derived from the FILE
+ * path (not the URL pattern) so route-group folders like `(marketing)` are
+ * included — their layout wraps children even though they add no URL segment.
+ *
+ * `routes/(marketing)/blog/[id].tsx` → `["(marketing)", "(marketing)/blog"]`.
+ */
+export function layoutDirsFromFilePath(filePath: string): string[] {
+  const rel = filePath.replace(/^routes\//, "").replace(/\.(tsx|ts)$/, "");
+  const parts = rel.split("/");
+  parts.pop(); // drop the file's own basename — only ancestor dirs hold layouts
+  const dirs: string[] = [];
+  for (let i = 1; i <= parts.length; i++) {
+    dirs.push(parts.slice(0, i).join("/"));
+  }
+  return dirs;
+}
+
 function segmentScore(seg: Segment): number {
   if (typeof seg === "string") return 0;       // static
   if ("param" in seg) return 1;                // dynamic
-  return 2;                                    // catch-all
+  if ("optional" in seg) return 2;             // optional dynamic
+  return 3;                                    // catch-all
 }
 
 function routeScore(route: RouteFile): number {

package/src/server/search.ts

@@ -8,7 +8,11 @@ import { runSchema, type Schema } from "./validate.ts";
  * flattens FormData.
  */
 export function searchParamsToObject(sp: URLSearchParams): Record<string, string | string[]> {
-  const out: Record<string, string | string[]> = {};
+  // Null-prototype so a query param named "__proto__" (?__proto__=x) can't
+  // pollute Object.prototype when the result is later spread/merged. Using a
+  // plain {} here would make `out["__proto__"] = …` a no-op AND, for nested
+  // merges downstream, a pollution vector. SECURITY: see proto-guard.ts.
+  const out = Object.create(null) as Record<string, string | string[]>;
   for (const [key, value] of sp.entries()) {
     const existing = out[key];
     if (existing === undefined) out[key] = value;

package/src/server/serve.ts

@@ -1,6 +1,7 @@
 import { scanRoutes, type RouteFile } from "./scanner.ts";
 import { buildTrie, matchRoute } from "./matcher.ts";
 import { handleRequest, type HandlerConfig } from "./request-handler.ts";
+import { pipeline, type MiddlewareContext } from "./middleware.ts";
 import { renderSpaShell } from "./spa.ts";
 import { type ServerManifest } from "./render.ts";
 import { isDevRuntime, isExplicitDev } from "./env.ts";
@@ -52,6 +53,14 @@ export interface BractJSConfig {
   buildDir?: string;
   /** Directory for transformed image cache. Defaults to .bract-image-cache */
   imageCacheDir?: string;
+  /**
+   * Hard ceiling (bytes) on the size of any incoming request body, enforced by
+   * the Bun adapter regardless of the advertised Content-Length. Defaults to
+   * 16 MiB — above the 10 MiB route-form cap so normal requests pass while a
+   * single client can't stream an unbounded body into memory. Raise it for a
+   * dedicated large-upload endpoint. Only applies to the default Bun adapter.
+   */
+  maxRequestBodySize?: number;
   /** Called once after the server starts listening. Use to open DB connections, warm caches, etc. */
   onStart?: () => Promise<void> | void;
   /** Called before the process exits (any signal or uncaught error). Use to close DB connections, flush queues, etc. */
@@ -169,7 +178,13 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
     return Bun.file(join(buildDir, "client", "_prerender", relHtmlOrJson));
   }
 
-  return async function fetch(request: Request): Promise<Response> {
+  // The full per-request dispatch: special endpoints (API, actions, stream,
+  // image, static, prerender) first, then the SSR route handler. Runs INSIDE
+  // the global middleware pipeline (see the returned `fetch` below), so
+  // `pipeline.use(cors()/csp()/auth/…)` governs every response — not just SSR
+  // documents. `context` is the shared mutable object threaded through the
+  // pipeline; route-level middleware and getCspNonce() read the same object.
+  async function dispatch(request: Request, context: Record<string, unknown>): Promise<Response> {
     const url = new URL(request.url);
     const { pathname } = url;
 
@@ -285,7 +300,17 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
 
     const manifest = isDevRuntime() ? await readDevManifest(buildDir) : await manifestReady;
     const handlerConfig: HandlerConfig = { appDir, publicDir, manifest, onError, moduleRegistry };
-    return handleRequest(request, trie, handlerConfig);
+    return handleRequest(request, trie, handlerConfig, context);
+  }
+
+  return async function fetch(request: Request): Promise<Response> {
+    // Run the global middleware pipeline around the ENTIRE dispatch so
+    // cors()/csp()/logging/auth attached via `pipeline.use(...)` apply to
+    // API routes, server actions, /_stream, /_image and static assets — not
+    // only SSR documents. The per-route (nested) middleware chain still runs
+    // inside handleRequest for SSR/_data, sharing this same `context` object.
+    const ctx: MiddlewareContext = { request, params: {}, context: {} };
+    return pipeline.run(ctx, () => dispatch(request, ctx.context));
   };
 }
 
@@ -330,7 +355,7 @@ export function createServer(config?: Partial<BractJSConfig>): {
   const fetchHandler = buildFetchHandler(config ?? {});
 
   // Use provided adapter or fall back to the default Bun adapter.
-  const adapter = config?.adapter ?? new BunAdapter();
+  const adapter = config?.adapter ?? new BunAdapter(config?.maxRequestBodySize);
 
   if (adapter instanceof BunAdapter) {
     adapter.setHandler(fetchHandler);

package/src/server/session.ts

@@ -1,3 +1,5 @@
+import { hasForbiddenKey } from "./proto-guard.ts";
+
 export type SessionData = Record<string, unknown>;
 
 export interface Session {
@@ -37,7 +39,16 @@ function encode(data: SessionData): string {
 
 function decode(encoded: string): SessionData {
   const pad = "=".repeat((4 - (encoded.length % 4)) % 4);
-  return JSON.parse(atob(encoded.replace(/-/g, "+").replace(/_/g, "/") + pad)) as SessionData;
+  const parsed = JSON.parse(
+    atob(encoded.replace(/-/g, "+").replace(/_/g, "/") + pad),
+  ) as SessionData;
+  // Defense-in-depth: the payload is HMAC-verified before we get here, so this
+  // only matters if a signing secret leaks — but a session blob carrying a
+  // "__proto__" key must never pollute Object.prototype when read/spread.
+  if (hasForbiddenKey(parsed)) {
+    throw new Error("session: forbidden key in payload");
+  }
+  return parsed;
 }
 
 async function sign(data: string, secret: string): Promise<string> {

package/src/server/validate.ts

@@ -33,7 +33,10 @@ export class ValidationError extends Error {
 
 function toPlainObject(input: FormData | Record<string, unknown>): Record<string, unknown> {
   if (input instanceof FormData) {
-    const out: Record<string, unknown> = {};
+    // Null-prototype: a form field literally named "__proto__" becomes a plain
+    // own key here instead of mutating Object.prototype when the result is
+    // later spread/merged. SECURITY: see src/server/proto-guard.ts.
+    const out = Object.create(null) as Record<string, unknown>;
     for (const [key, value] of input.entries()) {
       if (key in out) {
         const existing = out[key];

package/src/shared/context.ts

@@ -1,5 +1,5 @@
 import { createContext, useContext, createElement, type ComponentType, type ReactNode } from "react";
-import type { RouterLocation } from "./route-types.ts";
+import type { RouterLocation, RouteMatch } from "./route-types.ts";
 
 export interface RouteManifest {
   [routeId: string]: {
@@ -20,6 +20,8 @@ export interface BractJSContextValue {
   location?: RouterLocation;
   /** Validated search params (route `searchSchema` output), so `useSearch()` works during SSR. */
   search?: Record<string, unknown>;
+  /** The matched route chain (root → layouts → route) for `useMatches()`. */
+  matches?: RouteMatch[];
 }
 
 export const BractJSContext = createContext<BractJSContextValue>(null!);

package/src/shared/route-types.ts

@@ -75,6 +75,41 @@ export type MetaFunction<T = unknown> = (
   args: MetaArgs<T>
 ) => MetaDescriptor[];
 
+export interface HeadersArgs<T = unknown> {
+  /** This route's loader data (the route slice, already awaited). */
+  loaderData: T;
+  params: Record<string, string>;
+  request: Request;
+  /**
+   * The merged headers contributed by ancestors in the chain (root → layout →
+   * this route). Spread these to inherit, or override individual keys. Each
+   * `headers()` in the chain runs in order and sees what came before it.
+   */
+  parentHeaders: Headers;
+}
+
+/**
+ * A route/layout/root module's optional `headers` export, used to set
+ * response headers (e.g. `Cache-Control`, `ETag`, `Vary`) on the document and
+ * `/_data` responses. Runs in chain order (root → layout → route); the
+ * innermost value wins per key. Returns a `HeadersInit` (object, array of
+ * tuples, or `Headers`).
+ */
+export type HeadersFunction<T = unknown> = (
+  args: HeadersArgs<T>
+) => HeadersInit;
+
+/**
+ * A nested route-middleware function. Runs on the server in chain order
+ * (root → layout → route) before `beforeLoad`, the action, and loaders. Call
+ * `next()` to continue, or return a `Response` to short-circuit. The `context`
+ * object is shared and mutable across the whole chain (and into loaders).
+ */
+export type RouteMiddlewareFunction = (
+  ctx: { request: Request; params: Record<string, string>; context: Record<string, unknown> },
+  next: () => Promise<Response>,
+) => Promise<Response>;
+
 export interface BeforeLoadArgs {
   params: Record<string, string>;
   context: Record<string, unknown>;
@@ -105,10 +140,64 @@ export interface ShouldRevalidateArgs {
 
 export type ShouldRevalidateFunction = (args: ShouldRevalidateArgs) => boolean;
 
+/**
+ * A route's optional client loader (RR7-style). Runs in the browser on
+ * navigation to the route instead of just fetching the server loader. Call
+ * `serverLoader()` to get this route's server loader data (the `/_data`
+ * payload's route slice). Set `clientLoader.hydrate = true` to also run it
+ * during the initial hydration of an SSR'd document.
+ *
+ * Whatever it resolves to becomes the route's `useLoaderData()` value.
+ */
+export interface ClientLoaderFunction<T = unknown> {
+  (args: {
+    request: Request;
+    params: Record<string, string>;
+    search: Record<string, unknown>;
+    /** Fetch this route's server loader data (the `/_data` route slice). */
+    serverLoader: () => Promise<unknown>;
+  }): Promise<T> | T;
+  /** Run on initial hydration too (default: only on client navigation). */
+  hydrate?: boolean;
+}
+
+/**
+ * A route's optional client action (RR7-style). Runs in the browser on a
+ * `<Form>`/fetcher submission to the route instead of POSTing directly. Call
+ * `serverAction()` to invoke the server action and get its data. Whatever it
+ * resolves to becomes the route's `useActionData()` value.
+ */
+export type ClientActionFunction<T = unknown> = (args: {
+  request: Request;
+  params: Record<string, string>;
+  formData: FormData;
+  /** Invoke this route's server action and get its returned data. */
+  serverAction: () => Promise<unknown>;
+}) => Promise<T> | T;
+
 export interface RouteModule<TLoader = unknown, TAction = unknown> {
   loader?: LoaderFunction<TLoader>;
   action?: ActionFunction<TAction>;
+  /** Browser-side loader; see {@link ClientLoaderFunction}. */
+  clientLoader?: ClientLoaderFunction<TLoader>;
+  /** Browser-side action; see {@link ClientActionFunction}. */
+  clientAction?: ClientActionFunction<TAction>;
   meta?: MetaFunction<TLoader>;
+  /**
+   * Set response headers (`Cache-Control`, `ETag`, `Vary`, CDN hints, …) for
+   * this route's document and `/_data` responses. Runs in chain order
+   * (root → layout → route); innermost wins per key, and each call receives the
+   * `parentHeaders` accumulated so far. Skipped for mutations and error responses.
+   */
+  headers?: HeadersFunction<TLoader>;
+  /**
+   * Nested middleware for this route/layout/root. Runs on the server in chain
+   * order (root → layout → route) before `beforeLoad`/action/loaders, with a
+   * shared mutable `context`. A single function or an array. Return a
+   * `Response` to short-circuit; call `next()` to continue. Runs *inside* the
+   * global `pipeline` middleware.
+   */
+  middleware?: RouteMiddlewareFunction | RouteMiddlewareFunction[];
   beforeLoad?: BeforeLoadFunction;
   shouldRevalidate?: ShouldRevalidateFunction;
   /**
@@ -141,3 +230,22 @@ export interface RouteDefinition {
   parentId?: string;
   index?: boolean;
 }
+
+/**
+ * One entry in the matched route chain, as returned by `useMatches()`. The
+ * array runs outermost → innermost: root, then each layout, then the leaf
+ * route. Use it for breadcrumbs and conditional chrome driven by each route's
+ * `handle` export.
+ */
+export interface RouteMatch<TData = unknown, THandle = Record<string, unknown>> {
+  /** Stable id of the matched module — its appDir-relative file path (e.g. "routes/blog/[id].tsx", "root.tsx"). */
+  id: string;
+  /** The active URL pathname (same for every entry — they all share the matched location). */
+  pathname: string;
+  /** The matched route params (shared across the chain). */
+  params: Record<string, string>;
+  /** This module's loader data slice (root / the matching layout / the route). */
+  data: TData;
+  /** This module's static `handle` export, or `undefined` if none. */
+  handle: THandle | undefined;
+}

package/types/config.d.ts

@@ -23,6 +23,9 @@ export interface BractJSConfig {
   plugins?: BunPlugin[];
   /** Directory for the transformed-image cache. Default: ".bract-image-cache". */
   imageCacheDir?: string;
+  /** Hard ceiling (bytes) on any incoming request body, enforced by the Bun
+   *  adapter regardless of advertised Content-Length. Default 16 MiB. */
+  maxRequestBodySize?: number;
   /** WebSocket port for dev HMR (used by `bractjs dev` only). Default 3001. */
   hmrPort?: number;
   /** Custom server adapter (Cloudflare Workers, Deno, Node, etc.). Defaults to Bun.serve(). */

package/types/index.d.ts

@@ -93,6 +93,7 @@ import type { MiddlewareFn, MiddlewareContext } from "./middleware.d.ts";
 
 export declare class MiddlewarePipeline {
   use(fn: MiddlewareFn): this;
+  clear(): this;
   run(ctx: MiddlewareContext, handler: () => Promise<Response>): Promise<Response>;
 }
 export declare const pipeline: MiddlewarePipeline;
@@ -106,16 +107,24 @@ export declare function authGuard(options: AuthGuardOptions): MiddlewareFn;
 
 // ── API routes (C1) ───────────────────────────────────────────────────────
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface ApiRouteOptions {
+  /** CSRF protection for this route. Default `true` for mutating methods
+   *  (POST/PUT/PATCH/DELETE). Set `false` only for endpoints that don't trust
+   *  ambient credentials (webhooks, token-authenticated/public APIs). */
+  csrf?: boolean;
+}
 export interface ApiRouteDefinition<TMethod extends HttpMethod, TPath extends string, TInput, TOutput> {
   method: TMethod;
   path: TPath;
   handler: (input: TInput, request: Request) => TOutput | Promise<TOutput>;
+  csrf: boolean;
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export declare function route<TMethod extends HttpMethod, TPath extends string, TInput, TOutput>(
   method: TMethod,
   path: TPath,
   handler: (input: TInput, request: Request) => TOutput | Promise<TOutput>,
+  options?: ApiRouteOptions,
 ): ApiRouteDefinition<TMethod, TPath, TInput, TOutput>;
 export type AppApiRoutes = never; // users extend this via codegen
 
@@ -163,6 +172,14 @@ export declare function formText(formData: FormData, key: string): string;
 /** Collect string fields from FormData (all, or a named subset). */
 export declare function formValues(formData: FormData, keys?: string[]): Record<string, string>;
 
+// ── Prototype-pollution guards ────────────────────────────────────────────
+/** Deep-scan a parsed JSON value for `__proto__`/`constructor`/`prototype`
+ *  keys. Fails closed past an internal depth cap. Returns true if found. */
+export declare function hasForbiddenKey(value: unknown, depth?: number): boolean;
+/** Build a null-prototype object from entries, so a key named `__proto__`
+ *  lands as a plain own property instead of mutating the prototype. */
+export declare function nullProtoFromEntries<V>(entries: Iterable<readonly [string, V]>): Record<string, V>;
+
 // ── Search-param validation ───────────────────────────────────────────────
 /** URLSearchParams → plain object; repeated keys collapse into arrays. */
 export declare function searchParamsToObject(sp: URLSearchParams): Record<string, string | string[]>;