@bractjs/bractjs 0.1.28 → 0.2.0

package/src/server/middleware.ts

@@ -22,6 +22,13 @@ export class MiddlewarePipeline {
     return this;
   }
 
+  /** Remove all registered middleware. Useful for tests and for embedders that
+   * rebuild the pipeline (e.g. on a hot reload). */
+  clear(): this {
+    this.fns = [];
+    return this;
+  }
+
   /**
    * Compose all registered middleware into a single chain and execute it.
    * Each fn calls `next()` to invoke the next fn; the last `next()` calls `handler`.
@@ -49,3 +56,62 @@ export class MiddlewarePipeline {
 
 /** Module-level default pipeline — attach middleware here via pipeline.use(). */
 export const pipeline = new MiddlewarePipeline();
+
+// ── Per-route (nested) middleware ────────────────────────────────────────────
+
+/**
+ * A route/layout/root module's `middleware` entry. Same shape as the global
+ * {@link MiddlewareFn}: call `next()` to continue the chain, or return a
+ * `Response` to short-circuit (auth gate, redirect). The `ctx.context` object
+ * is shared and mutable — set fields on it and downstream middleware, loaders,
+ * and actions see them.
+ */
+export type RouteMiddleware = MiddlewareFn;
+
+/**
+ * Compose a route's nested middleware chain (root → layouts → route, in that
+ * order) around `handler` and run it. Mirrors {@link MiddlewarePipeline.run}
+ * but for an ad-hoc, per-request list rather than the module-level pipeline.
+ * An empty list calls `handler` directly (zero overhead for routes that don't
+ * use middleware).
+ */
+export function runRouteMiddleware(
+  fns: RouteMiddleware[],
+  ctx: MiddlewareContext,
+  handler: () => Promise<Response>,
+): Promise<Response> {
+  if (fns.length === 0) return handler();
+  let lastCalled = -1;
+  const dispatch = (i: number): Promise<Response> => {
+    if (i <= lastCalled) {
+      return Promise.reject(new Error("route middleware: next() called more than once"));
+    }
+    lastCalled = i;
+    if (i >= fns.length) return handler();
+    return fns[i](ctx, () => dispatch(i + 1));
+  };
+  return dispatch(0);
+}
+
+/**
+ * Flatten a route chain's `middleware` exports into a single ordered list:
+ * root first, then each layout outermost→innermost, then the leaf route. Each
+ * module may export `middleware` as a single fn or an array; both normalize
+ * here. Non-function entries are ignored defensively.
+ */
+export function collectRouteMiddleware(chain: {
+  root: { middleware?: unknown };
+  layouts: Array<{ middleware?: unknown }>;
+  route: { middleware?: unknown };
+}): RouteMiddleware[] {
+  const out: RouteMiddleware[] = [];
+  const add = (m: unknown) => {
+    if (!m) return;
+    const list = Array.isArray(m) ? m : [m];
+    for (const fn of list) if (typeof fn === "function") out.push(fn as RouteMiddleware);
+  };
+  add(chain.root.middleware);
+  for (const layout of chain.layouts) add(layout.middleware);
+  add(chain.route.middleware);
+  return out;
+}

package/src/server/proto-guard.ts

@@ -0,0 +1,56 @@
+/**
+ * Prototype-pollution guards, shared across every untrusted-object boundary
+ * (server actions, typed /api JSON, form/search → object conversions).
+ *
+ * Two strategies, used where each fits:
+ *
+ *  1. {@link hasForbiddenKey} — a deep scan that REJECTS a parsed JSON value
+ *     carrying a dangerous key. Used on /_action and /api JSON bodies, where a
+ *     400 is the right UX and the payload shape is the app's contract.
+ *
+ *  2. {@link nullProtoFromEntries} — builds a null-prototype object from
+ *     key/value pairs so a key literally named "__proto__" becomes an ordinary
+ *     own property that can never reach Object.prototype. Used for the
+ *     FormData / URLSearchParams → object conversions, which must accept
+ *     arbitrary field names without erroring.
+ */
+
+// `__proto__` is the actual pollution vector for own-keys produced by
+// JSON.parse. `constructor`/`prototype` are included defensively: a recursive
+// merge that walks `obj.constructor.prototype` can be steered by them too.
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+// Max nesting we will fully scan. Legitimate payloads are shallow; anything
+// deeper is treated as hostile and rejected (fail closed) — see hasForbiddenKey.
+const MAX_SCAN_DEPTH = 200;
+
+/**
+ * Deep scan for a forbidden key anywhere in a parsed JSON value.
+ *
+ * SECURITY(high): this is a security filter, so it FAILS CLOSED. A value nested
+ * past MAX_SCAN_DEPTH returns `true` (rejected) rather than being passed
+ * through — otherwise an attacker could bury `__proto__` below the cap to evade
+ * the check and reach a recursive-merge sink in handler code.
+ */
+export function hasForbiddenKey(value: unknown, depth = 0): boolean {
+  if (!value || typeof value !== "object") return false;
+  if (depth > MAX_SCAN_DEPTH) return true;
+  for (const key of Object.keys(value as Record<string, unknown>)) {
+    if (FORBIDDEN_KEYS.has(key)) return true;
+    if (hasForbiddenKey((value as Record<string, unknown>)[key], depth + 1)) return true;
+  }
+  return false;
+}
+
+/**
+ * Build a null-prototype object from [key, value] entries. A key named
+ * "__proto__" lands as a plain own property instead of mutating the prototype,
+ * so downstream spreads/merges of the result are pollution-safe.
+ */
+export function nullProtoFromEntries<V>(
+  entries: Iterable<readonly [string, V]>,
+): Record<string, V> {
+  const out = Object.create(null) as Record<string, V>;
+  for (const [k, v] of entries) out[k] = v;
+  return out;
+}

package/src/server/render.ts

@@ -1,6 +1,6 @@
 import { renderToReadableStream } from "react-dom/server";
 import { createElement, Fragment, type ReactNode } from "react";
-import type { MetaDescriptor } from "../shared/route-types.ts";
+import type { MetaDescriptor, RouteMatch } from "../shared/route-types.ts";
 import { safeStringify, isDevRuntime, getDevHmrPort } from "./env.ts";
 import { errorOverlayScript } from "../dev/error-overlay.ts";
 import { mergeMeta } from "./meta.ts";
@@ -22,6 +22,8 @@ export interface RenderOptions {
   search?: Record<string, unknown>;
   manifest: ServerManifest;
   meta: MetaDescriptor[];
+  /** The matched route chain (root → layouts → route) for `useMatches()`. */
+  matches?: RouteMatch[];
   status?: number;
   /** Path of the matched route file (e.g. "routes/_index.tsx"), used by the client to pre-import the module before hydration. */
   routeFile?: string;
@@ -34,6 +36,11 @@ export interface RenderOptions {
    * "spa": static shell, everything resolved client-side).
    */
   ssrMode?: "client-only" | "data-only" | "spa";
+  /**
+   * Resolved route `headers()` output (root → layout → route merged). Applied
+   * on top of the baseline document headers, overriding any same-key default.
+   */
+  headers?: Headers | null;
 }
 
 export async function renderRoute(options: RenderOptions): Promise<Response> {
@@ -59,7 +66,7 @@ export async function renderRoute(options: RenderOptions): Promise<Response> {
   // The merged descriptor array is what the client reads to keep the document
   // head in sync on soft navigation — keep it shaped, not stringified HTML.
   const bootstrapScriptContent =
-    devOverlay + `window.__BRACTJS_DATA__=${safeStringify({ loaderData, actionData, params, pathname, search: options.search, manifest, routeFile: options.routeFile, meta: mergedMeta, ssrMode: options.ssrMode })};`;
+    devOverlay + `window.__BRACTJS_DATA__=${safeStringify({ loaderData, actionData, params, pathname, search: options.search, manifest, routeFile: options.routeFile, meta: mergedMeta, matches: options.matches, ssrMode: options.ssrMode })};`;
 
   // Render <title>/<meta> elements alongside the app shell. React 19 hoists
   // document-metadata elements into <head> during streaming SSR, so crawlers
@@ -90,19 +97,30 @@ export async function renderRoute(options: RenderOptions): Promise<Response> {
 
   const responseStatus = renderError ? 500 : status;
 
-  return new Response(stream, {
-    status: responseStatus,
-    headers: {
-      "Content-Type": "text/html; charset=utf-8",
-      "Transfer-Encoding": "chunked",
-      // SECURITY(medium): baseline hardening headers. For a Content-Security-
-      // Policy, opt into the nonce-based `csp()` middleware — it generates a
-      // per-request nonce, applies it to the inline bootstrap script + client
-      // entry module here (via renderToReadableStream's `nonce` option), and
-      // sets the CSP response header.
-      "X-Content-Type-Options": "nosniff",
-      "X-Frame-Options": "SAMEORIGIN",
-      "Referrer-Policy": "strict-origin-when-cross-origin",
-    },
+  const headers = new Headers({
+    "Content-Type": "text/html; charset=utf-8",
+    "Transfer-Encoding": "chunked",
+    // SECURITY(medium): baseline hardening headers. For a Content-Security-
+    // Policy, opt into the nonce-based `csp()` middleware — it generates a
+    // per-request nonce, applies it to the inline bootstrap script + client
+    // entry module here (via renderToReadableStream's `nonce` option), and
+    // sets the CSP response header.
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "SAMEORIGIN",
+    "Referrer-Policy": "strict-origin-when-cross-origin",
   });
+
+  // Route `headers()` output (root → layout → route) overrides the baseline.
+  // Content-Type / Transfer-Encoding stay framework-owned: a route shouldn't
+  // be able to corrupt the streamed document envelope. Don't apply on render
+  // errors — that path serves a generic 500, not the route's cached document.
+  if (options.headers && !renderError) {
+    options.headers.forEach((value, key) => {
+      const k = key.toLowerCase();
+      if (k === "content-type" || k === "transfer-encoding") return;
+      headers.set(key, value);
+    });
+  }
+
+  return new Response(stream, { status: responseStatus, headers });
 }

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!);