@bractjs/bractjs 0.1.25 → 0.1.27

package/src/dev/devtools.ts

@@ -25,49 +25,68 @@ declare global {
 }
 
 const PANEL_ID = "bractjs-devtools-panel";
+const REFRESH_MS = 1000;
+
+function readState(): DevtoolsState {
+  return window.__BRACTJS_DEVTOOLS__ ?? {
+    route: null,
+    loaderData: {},
+    navState: "idle",
+    cacheEntries: [],
+    beforeLoadTrace: [],
+  };
+}
 
 class BractJSDevtools extends HTMLElement {
   private open = false;
   private panel: HTMLDivElement | null = null;
+  private refreshTimer: ReturnType<typeof setInterval> | null = null;
+  private readonly handleKeydown = (e: KeyboardEvent) => {
+    if (e.ctrlKey && e.shiftKey && e.key === "B") {
+      e.preventDefault();
+      this.togglePanel();
+    }
+  };
 
   connectedCallback() {
     this.style.cssText = "position:fixed;bottom:0;right:0;z-index:2147483647;font-family:monospace;";
 
-    const toggle = document.createElement("button");
-    toggle.textContent = "⚡ BractJS";
-    toggle.style.cssText =
-      "background:#1e1e1e;color:#61dafb;border:none;padding:4px 10px;cursor:pointer;font-size:12px;";
-    toggle.onclick = () => this.togglePanel();
-    this.appendChild(toggle);
-
-    // Keyboard shortcut
-    document.addEventListener("keydown", (e) => {
-      if (e.ctrlKey && e.shiftKey && e.key === "B") {
-        e.preventDefault();
-        this.togglePanel();
-      }
-    });
+    if (!this.querySelector("button")) {
+      const toggle = document.createElement("button");
+      toggle.textContent = "⚡ BractJS";
+      toggle.style.cssText =
+        "background:#1e1e1e;color:#61dafb;border:none;padding:4px 10px;cursor:pointer;font-size:12px;";
+      toggle.onclick = () => this.togglePanel();
+      this.appendChild(toggle);
+    }
+
+    document.addEventListener("keydown", this.handleKeydown);
+  }
+
+  disconnectedCallback() {
+    document.removeEventListener("keydown", this.handleKeydown);
+    this.stopRefresh();
   }
 
   private togglePanel() {
-    if (this.panel) {
-      this.panel.remove();
-      this.panel = null;
+    if (this.open) {
       this.open = false;
-    } else {
-      this.open = true;
-      this.renderPanel();
+      this.stopRefresh();
+      if (this.panel) {
+        this.panel.remove();
+        this.panel = null;
+      }
+      return;
     }
+
+    this.open = true;
+    this.ensurePanel();
+    this.renderPanel();
+    this.startRefresh();
   }
 
-  private renderPanel() {
-    const state = window.__BRACTJS_DEVTOOLS__ ?? {
-      route: null,
-      loaderData: {},
-      navState: "idle",
-      cacheEntries: [],
-      beforeLoadTrace: [],
-    };
+  private ensurePanel() {
+    if (this.panel) return;
 
     const panel = document.createElement("div");
     panel.id = PANEL_ID;
@@ -75,6 +94,31 @@ class BractJSDevtools extends HTMLElement {
       "background:#1e1e1e;color:#ccc;width:480px;max-height:60vh;overflow:auto;" +
       "border-top:2px solid #61dafb;border-left:2px solid #61dafb;padding:12px;font-size:11px;";
 
+    this.panel = panel;
+    this.appendChild(panel);
+  }
+
+  private startRefresh() {
+    this.stopRefresh();
+    this.refreshTimer = setInterval(() => {
+      if (!this.open || !this.panel) return;
+      this.renderPanel();
+    }, REFRESH_MS);
+  }
+
+  private stopRefresh() {
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+
+  private renderPanel() {
+    if (!this.panel) return;
+    const state = readState();
+    const panel = this.panel;
+    panel.replaceChildren();
+
     const header = document.createElement("div");
     header.style.cssText = "color:#61dafb;font-weight:bold;margin-bottom:8px;font-size:13px;";
     header.textContent = "BractJS DevTools";
@@ -94,17 +138,6 @@ class BractJSDevtools extends HTMLElement {
     if (state.beforeLoadTrace.length > 0) {
       this.section(panel, "beforeLoad trace", state.beforeLoadTrace.join("\n"));
     }
-
-    this.panel = panel;
-    this.appendChild(panel);
-
-    // Auto-refresh every second while open.
-    const timer = setInterval(() => {
-      if (!this.open) { clearInterval(timer); return; }
-      panel.remove();
-      this.panel = null;
-      this.renderPanel();
-    }, 1000);
   }
 
   private section(parent: HTMLElement, title: string, content: string) {

package/src/dev/hmr-module-handler.ts

@@ -1,6 +1,6 @@
 import { resolve, join, sep } from "node:path";
 import { realpath } from "node:fs/promises";
-import { serverOnlyPlugin } from "../build/env-plugin.ts";
+import { serverModuleStubPlugin } from "../build/env-plugin.ts";
 import { createUseServerProxyPlugin } from "../build/directives.ts";
 
 /**
@@ -48,14 +48,16 @@ export async function handleHmrModuleRequest(
   // build uses. Without these, a route module that imports `*.server.ts` or
   // contains "use server" exports would have that server source compiled and
   // shipped to the browser as JavaScript over /_hmr/module — leaking
-  // credentials, DB code, etc. The serverOnlyPlugin hard-fails such imports
-  // and useServerProxyPlugin rewrites "use server" exports to fetch stubs.
+  // credentials, DB code, etc. The serverModuleStubPlugin replaces every
+  // `*.server.ts` export with an inert stub (zero server source reaches the
+  // client) and useServerProxyPlugin rewrites "use server" exports to fetch
+  // stubs.
   const result = await Bun.build({
     entrypoints: [fullPath],
     target: "browser",
     minify: false,
     sourcemap: "inline",
-    plugins: [serverOnlyPlugin, createUseServerProxyPlugin(rootDir)],
+    plugins: [serverModuleStubPlugin, createUseServerProxyPlugin(rootDir)],
   });
 
   if (!result.success || result.outputs.length === 0) {

package/src/dev/rebuilder.ts

@@ -1,5 +1,8 @@
 import type { BractJSConfig } from "../server/serve.ts";
 import { createUseServerProxyPlugin } from "../build/directives.ts";
+import { serverModuleStubPlugin, clientEnvPlugin } from "../build/env-plugin.ts";
+import { cssModulesPlugin } from "../build/plugins/css-modules.ts";
+import { reactDedupePlugin } from "../build/react-dedupe.ts";
 import { scanRoutes } from "../server/scanner.ts";
 import { generateManifest, writeManifest } from "../build/manifest.ts";
 import { mkdir, rename, rm } from "node:fs/promises";
@@ -48,7 +51,19 @@ export async function rebuildClient(
       // structure. publicPath + ../ traversals produce wrong absolute URLs.
       minify: false,
       sourcemap: "inline",
-      plugins: [createUseServerProxyPlugin(appDir), ...(config?.plugins ?? [])],
+      // SECURITY: mirror the production client-bundle guard plugins
+      // (src/build/bundler.ts). Without `serverModuleStubPlugin` a route that
+      // imports a `*.server.ts` module would have that server source compiled
+      // and served to the browser over /build/client in dev; without
+      // `clientEnvPlugin` server env vars would leak the same way.
+      plugins: [
+        reactDedupePlugin(process.cwd()),
+        serverModuleStubPlugin,
+        createUseServerProxyPlugin(appDir),
+        clientEnvPlugin(config?.clientEnv ?? [], Bun.env as Record<string, string>),
+        cssModulesPlugin,
+        ...(config?.plugins ?? []),
+      ],
     });
   } finally {
     await rm(shimPath, { force: true });

package/src/dev/server.ts

@@ -34,6 +34,9 @@ export async function createDevServer(options?: DevServerOptions): Promise<DevSe
 
   const userConfig = options?.skipUserConfig ? {} : await loadUserConfig();
   const merged: Partial<BractJSConfig> = { ...userConfig, ...options?.config };
+  // Note: the `"use client"` SSR stub is installed by buildFetchHandler (it runs
+  // for any source-import path, dev or `bractjs start`), so no separate dev hook
+  // is needed here.
 
   const hmrPort = options?.hmrPort ?? 3001;
   const appPort = options?.port ?? merged.port ?? 3000;

package/src/index.ts

@@ -25,14 +25,22 @@ export { createCloudflareAdapter, makeCloudflareHandler } from "./adapters/cloud
 // - `createUseServerProxyPlugin(appDir)` (client bundle): replaces
 //   "use server" exports with fetch proxies. Without it, server-action
 //   bodies — including DB queries and secrets — ship inside the browser JS.
-// - `serverOnlyPlugin` (client bundle): hard-fails imports of `*.server.ts`
-//   files so server-only code can never be tree-walked into the client bundle.
+// - `serverModuleStubPlugin` (client bundle): replaces every export of a
+//   `*.server.ts` module with an inert stub. Because BractJS ships the whole
+//   route module (loader + action included) to the client, a route that imports
+//   a server module inside its loader pulls that module into the client graph;
+//   stubbing keeps the import resolvable while guaranteeing zero server source
+//   (DB drivers, secrets) reaches the browser. The stubs throw if ever used on
+//   the client. This is the plugin the dev and production client builds use.
+// - `serverOnlyPlugin` (client bundle, legacy): the stricter predecessor that
+//   *hard-fails* any `*.server.ts` import. Kept for back-compat / opt-in use
+//   when you want server-module imports to be a build error rather than a stub.
 // - `clientEnvPlugin(allowedKeys, env)` (client bundle): allowlists which
 //   `process.env.*` references survive into the browser bundle.
 // - `cssModulesPlugin` (client bundle): handles `*.module.css` imports.
 export { cssModulesPlugin, transformCssModule } from "./build/plugins/css-modules.ts";
 export { useClientStubPlugin, createUseServerProxyPlugin, useServerProxyPlugin } from "./build/directives.ts";
-export { serverOnlyPlugin, clientEnvPlugin } from "./build/env-plugin.ts";
+export { serverModuleStubPlugin, serverOnlyPlugin, clientEnvPlugin } from "./build/env-plugin.ts";
 
 // Module-registry codegen (drives `bun build --compile` workflow)
 export {
@@ -78,6 +86,8 @@ export { cors } from "./middleware/cors.ts";
 export type { CorsOptions } from "./middleware/cors.ts";
 export { authGuard } from "./middleware/authGuard.ts";
 export type { AuthGuardOptions, SessionStorageLike, SessionLike } from "./middleware/authGuard.ts";
+export { csp, getCspNonce, CSP_NONCE_KEY } from "./server/csp.ts";
+export type { CspOptions } from "./server/csp.ts";
 
 // Session
 export { createCookieSession } from "./server/session.ts";
@@ -98,6 +108,8 @@ export { useLoaderData } from "./client/hooks/useLoaderData.ts";
 export { useActionData } from "./client/hooks/useActionData.ts";
 export { useParams } from "./client/hooks/useParams.ts";
 export { useNavigation } from "./client/hooks/useNavigation.ts";
+export { useNavigate } from "./client/hooks/useNavigate.ts";
+export type { NavigateFn, NavigateOptions } from "./client/hooks/useNavigate.ts";
 export { useFetcher } from "./client/hooks/useFetcher.ts";
 export { useSearchParams } from "./client/hooks/useSearchParams.ts";
 export type { SearchParamsResult } from "./client/hooks/useSearchParams.ts";
@@ -105,6 +117,21 @@ export { useBlocker } from "./client/hooks/useBlocker.ts";
 export { useLocale } from "./client/hooks/useLocale.ts";
 export { useLocalizedLink } from "./client/hooks/useLocalizedLink.ts";
 
+// Typed-routing registration seam. Augment `Register` (done by `bractjs codegen`
+// in app/route-types.gen.ts) to make <Link>, useNavigate, useParams, and
+// useSearchParams type-safe. Augment RouteSearchParamsMap / RouteContextMap to
+// type a route's search params / context.
+export type {
+  Register,
+  RouteRegistry,
+  RegisteredRoutes,
+  ParamsFor,
+  SearchFor,
+  RouteSearchParamsMap,
+  RouteContextMap,
+} from "./client/registry.ts";
+export { buildPath } from "./client/build-path.ts";
+
 // i18n utilities (server-side)
 export { wrapRoutesWithLocale, stripLocale, localizedDataPath } from "./server/i18n.ts";
 export type { I18nConfig } from "./server/serve.ts";

package/src/server/csp.ts

@@ -0,0 +1,92 @@
+import type { MiddlewareFn } from "./middleware.ts";
+
+/**
+ * Context key under which the per-request CSP nonce is stored. The render
+ * pipeline reads this and applies it to the inline bootstrap script + the
+ * client entry module tags via `renderToReadableStream({ nonce })`, so the
+ * scripts BractJS injects satisfy a strict `script-src 'nonce-…'` policy.
+ */
+export const CSP_NONCE_KEY = "__bractCspNonce";
+
+export interface CspOptions {
+  /**
+   * Extra directives to merge into the default policy, keyed by directive name.
+   * Values are joined with spaces. A value of `null` removes a default
+   * directive entirely. Example:
+   *   { "img-src": "'self' https://cdn.example", "frame-ancestors": "'none'" }
+   */
+  directives?: Record<string, string | null>;
+  /**
+   * Emit `Content-Security-Policy-Report-Only` instead of the enforcing header.
+   * Useful for staging a policy before turning it on. Default: false.
+   */
+  reportOnly?: boolean;
+}
+
+/**
+ * Read the per-request CSP nonce a `csp()` middleware stored on the context.
+ * Returns undefined when no CSP middleware ran (CSP is opt-in).
+ */
+export function getCspNonce(context: Record<string, unknown>): string | undefined {
+  const v = context[CSP_NONCE_KEY];
+  return typeof v === "string" ? v : undefined;
+}
+
+function generateNonce(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return btoa(String.fromCharCode(...bytes)).replace(/=+$/, "");
+}
+
+/**
+ * Opt-in nonce-based Content-Security-Policy middleware.
+ *
+ * Generates a fresh random nonce per request, stashes it on `ctx.context` so
+ * the SSR render pipeline can attach it to the scripts BractJS injects, and
+ * sets the `Content-Security-Policy` response header. The default policy is a
+ * sensible strict baseline; override or extend it via `options.directives`.
+ *
+ *   import { pipeline, csp } from "@bractjs/bractjs";
+ *   pipeline.use(csp({ directives: { "img-src": "'self' data: https:" } }));
+ *
+ * SECURITY: only the inline bootstrap script and the client entry module —
+ * the scripts BractJS itself emits — are nonced. Any inline script an app adds
+ * to its own `root.tsx`/components must carry the same nonce (read it via the
+ * render context) or it will be blocked, which is the point of CSP.
+ */
+export function csp(options: CspOptions = {}): MiddlewareFn {
+  const reportOnly = options.reportOnly === true;
+  const headerName = reportOnly
+    ? "Content-Security-Policy-Report-Only"
+    : "Content-Security-Policy";
+
+  return async (ctx, next) => {
+    const nonce = generateNonce();
+    ctx.context[CSP_NONCE_KEY] = nonce;
+
+    const directives: Record<string, string | null> = {
+      "default-src": "'self'",
+      // 'strict-dynamic' lets the nonced bootstrap script load the chunks it
+      // imports without each chunk needing its own nonce. Falls back to 'self'
+      // in browsers that don't support it.
+      "script-src": `'self' 'nonce-${nonce}' 'strict-dynamic'`,
+      "style-src": "'self' 'unsafe-inline'",
+      "img-src": "'self' data: blob:",
+      "connect-src": "'self'",
+      "base-uri": "'self'",
+      "frame-ancestors": "'self'",
+      "object-src": "'none'",
+      ...(options.directives ?? {}),
+    };
+
+    const policy = Object.entries(directives)
+      .filter(([, v]) => v !== null)
+      .map(([k, v]) => `${k} ${v}`)
+      .join("; ");
+
+    const response = await next();
+    // Mutate headers in place so we don't break a single-shot streaming body.
+    response.headers.set(headerName, policy);
+    return response;
+  };
+}

package/src/server/csrf.ts

@@ -1,14 +1,52 @@
 /**
- * Cross-origin POST/PUT/DELETE/PATCH protection.
- * Allow when: request carries X-BractJS-Action header (client-issued, blocked
- * cross-origin by CORS for non-simple requests), OR the Origin header matches
- * the request URL's origin.
+ * Cross-origin mutation protection for state-changing requests
+ * (POST/PUT/DELETE/PATCH and the side-effecting /_action, /_stream endpoints).
+ *
+ * Defense in depth, in priority order:
+ *
+ * 1. `Sec-Fetch-Site` — set by the browser, NOT settable from JS (it's a
+ *    forbidden request header). When present it is authoritative: only
+ *    `same-origin` and `none` (direct navigation / address bar) are allowed;
+ *    `cross-site` and `same-site` are rejected. This catches cross-origin
+ *    forgeries even when the attacker controls the Origin header (non-browser
+ *    clients) — those won't carry a trustworthy Sec-Fetch-Site.
+ *
+ * 2. `X-BractJS-Action` — a custom header the client RPC layer sets on every
+ *    action call. Browsers block custom headers cross-origin without a CORS
+ *    preflight, so its presence implies a same-origin (or explicitly
+ *    CORS-allowed) caller.
+ *
+ * 3. `Origin` — must match the request URL's origin.
+ *
+ * A request is allowed only when Sec-Fetch-Site does not veto it AND at least
+ * one of (2) or (3) holds. Non-browser clients (curl, server-to-server) send
+ * none of these headers and are rejected by default — they must set
+ * `X-BractJS-Action` or a same-origin `Origin` to mutate.
  */
-// SECURITY(medium): X-BractJS-Action acts as a CSRF token by relying on CORS preflight blocking custom headers cross-origin. This is safe only while the server does NOT emit permissive Access-Control-Allow-Headers for this header. If CORS policy is ever loosened, add a cryptographic CSRF token instead.
+// SECURITY(medium): X-BractJS-Action acts as a CSRF token by relying on CORS
+// preflight blocking custom headers cross-origin. This is safe only while the
+// server does NOT emit a permissive Access-Control-Allow-Headers listing this
+// header. If CORS policy is ever loosened, Sec-Fetch-Site (1) remains as the
+// browser-enforced backstop, and apps that loosen CORS should add a
+// cryptographic double-submit token.
 export function isAllowedMutation(request: Request): boolean {
+  // (1) Browser-enforced signal. If present, it vetoes cross-origin requests
+  // regardless of what the Origin/custom headers claim.
+  const fetchSite = request.headers.get("Sec-Fetch-Site");
+  if (fetchSite && fetchSite !== "same-origin" && fetchSite !== "none") {
+    return false;
+  }
+
+  // (2) Client-issued custom header (blocked cross-origin by CORS preflight).
   if (request.headers.get("X-BractJS-Action")) return true;
+
+  // (3) Same-origin Origin header.
   const origin = request.headers.get("Origin");
-  if (!origin) return false;
+  if (!origin) {
+    // No Origin header. Allow only when the browser explicitly told us this is
+    // a same-origin / direct request via Sec-Fetch-Site; otherwise reject.
+    return fetchSite === "same-origin" || fetchSite === "none";
+  }
   try {
     return new URL(origin).origin === new URL(request.url).origin;
   } catch {

package/src/server/layout.ts

@@ -96,10 +96,16 @@ export async function importRouteModule(filePath: string): Promise<RouteModule>
     loader: mod.loader,
     action: mod.action,
     meta: mod.meta,
+    // SECURITY(high): beforeLoad is the auth/redirect gate and `context` is the
+    // per-route context factory. Both MUST be projected here — dropping them
+    // turns every beforeLoad() export into a silent no-op, bypassing auth on
+    // full-page GET, POST actions, and the /_data soft-nav endpoint alike.
+    beforeLoad: mod.beforeLoad,
+    context: mod.context,
     handle: mod.handle,
     ErrorBoundary: mod.ErrorBoundary,
     default: mod.default,
-  };
+  } as RouteModule;
 }
 
 /**
@@ -114,10 +120,14 @@ function pickRouteModule(mod: Record<string, unknown> | RouteModule | undefined)
     loader: m.loader as RouteModule["loader"],
     action: m.action as RouteModule["action"],
     meta: m.meta as RouteModule["meta"],
+    // SECURITY(high): keep beforeLoad + context in the projection — see the
+    // note in importRouteModule. The compiled-binary path goes through here.
+    beforeLoad: m.beforeLoad as RouteModule["beforeLoad"],
+    context: m.context as unknown,
     handle: m.handle as RouteModule["handle"],
     ErrorBoundary: m.ErrorBoundary as RouteModule["ErrorBoundary"],
     default: m.default as RouteModule["default"],
-  };
+  } as RouteModule;
 }
 
 // ── resolveRouteChain ──────────────────────────────────────────────────────

package/src/server/loader.ts

@@ -80,21 +80,19 @@ export async function runLoaders(
   args: LoaderArgs,
   onError?: OnErrorHook,
 ): Promise<LoaderResults> {
+  // Run every loader in the chain concurrently — root, all layouts, and the
+  // route loader. The route loader is usually the slowest and most important
+  // one, so it must not be serialized behind the layout wave.
   const layoutLoaders = chain.layouts.map((mod) =>
     safeRun(mod.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError)
   );
 
-  const [root, ...layoutResults] = await Promise.all([
+  const [root, route, ...layoutResults] = await Promise.all([
     safeRun(chain.root.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError),
+    safeRun(chain.route.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError),
     ...layoutLoaders,
   ]);
 
-  const route = await safeRun(
-    chain.route.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined,
-    args,
-    onError,
-  );
-
   return { root, layouts: layoutResults, route };
 }
 

package/src/server/render.ts

@@ -1,9 +1,10 @@
 import { renderToReadableStream } from "react-dom/server";
-import type { ReactNode } from "react";
+import { createElement, Fragment, type ReactNode } from "react";
 import type { MetaDescriptor } from "../shared/route-types.ts";
 import { safeStringify, isDevRuntime } from "./env.ts";
 import { errorOverlayScript } from "../dev/error-overlay.ts";
-import { mergeMeta, renderMetaTags } from "./meta.ts";
+import { mergeMeta } from "./meta.ts";
+import { MetaTags } from "../shared/meta-tags.tsx";
 
 export interface ServerManifest {
   clientEntry: string;
@@ -22,6 +23,8 @@ export interface RenderOptions {
   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;
+  /** Per-request CSP nonce (set by the opt-in `csp()` middleware). Applied to the inline bootstrap script + client entry module tags. */
+  nonce?: string;
 }
 
 export async function renderRoute(options: RenderOptions): Promise<Response> {
@@ -38,17 +41,32 @@ export async function renderRoute(options: RenderOptions): Promise<Response> {
   const devFlag = isDevRuntime() ? "window.__BRACT_DEV__=true;" : "";
   const devOverlay = isDevRuntime() ? devFlag + errorOverlayScript + "\n" : "";
   const mergedMeta = mergeMeta(options.meta ?? []);
-  // metaHtml is injected into <head> via React (the renderToReadableStream tree
-  // is expected to use it). The merged descriptor array is what the client
-  // reads — keep it shaped, not stringified HTML.
+  // 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, manifest, routeFile: options.routeFile, meta: mergedMeta })};`;
 
+  // Render <title>/<meta> elements alongside the app shell. React 19 hoists
+  // document-metadata elements into <head> during streaming SSR, so crawlers
+  // and no-JS clients receive real meta tags. The client renders the same
+  // <MetaTags> inside ClientRouter, so hydration matches and soft navigation
+  // re-renders the head.
+  const tree = createElement(
+    Fragment,
+    null,
+    createElement(MetaTags, { meta: mergedMeta }),
+    shell,
+  );
+
   let renderError: unknown;
 
-  const stream = await renderToReadableStream(shell, {
+  const stream = await renderToReadableStream(tree, {
     bootstrapScriptContent,
     bootstrapModules: [manifest.clientEntry],
+    // When the opt-in csp() middleware ran, React stamps this nonce onto the
+    // inline bootstrap script and the client entry <script type=module>, so
+    // they satisfy a strict `script-src 'nonce-…'` policy.
+    nonce: options.nonce,
     onError(error) {
       renderError = error;
       console.error("[bract] renderToReadableStream error:", error);
@@ -62,10 +80,11 @@ export async function renderRoute(options: RenderOptions): Promise<Response> {
     headers: {
       "Content-Type": "text/html; charset=utf-8",
       "Transfer-Encoding": "chunked",
-      // SECURITY(medium): baseline hardening headers. Apps that need a tighter
-      // CSP (e.g. with nonces for the inline bootstrap script) can override
-      // via middleware. We omit CSP here because the inline bootstrap script
-      // injected by safeStringify would require nonce wiring throughout.
+      // 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",

package/src/server/request-handler.ts

@@ -5,12 +5,13 @@ import { resolveRouteChain, type ModuleRegistry } from "./layout.ts";
 import { runLoaders, runAction, buildLoaderArgs, runRouteContext, runBeforeLoad } from "./loader.ts";
 import { renderRoute, type ServerManifest } from "./render.ts";
 import { resolveMeta } from "./meta.ts";
-import { json, error } from "./response.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 { BractJSProvider } from "../shared/context.ts";
 import { isAllowedMutation } from "./csrf.ts";
+import { getCspNonce } from "./csp.ts";
 import { fireOnError, type OnErrorHook } from "./lifecycle.ts";
 
 export interface HandlerConfig {
@@ -101,7 +102,7 @@ async function route(
       const results = await runLoaders(chain, args, onError);
       return json({ root: results.root, layouts: results.layouts, route: results.route, params: match.params });
     } catch (err) {
-      if (isRedirect(err)) return err as Response;
+      if (isRedirect(err)) return sanitizeRedirect(err as Response, request.url);
       if (isHttpError(err)) return json({ error: err.message }, { status: err.status });
       console.error("[bractjs] /_data error:", err);
       await fireOnError(onError, err, request);
@@ -145,13 +146,21 @@ async function route(
       const formData = isFormLike ? await request.formData() : new FormData();
       actionData = await runAction(chain.route, { ...args, formData });
     } catch (err) {
-      if (isRedirect(err)) return err as Response;
+      if (isRedirect(err)) return sanitizeRedirect(err as Response, request.url);
       if (isHttpError(err)) return error(err.message, err.status);
       await fireOnError(onError, err, request);
       if (isExplicitDev()) return error(err instanceof Error ? err.message : String(err), 500);
       return error("Internal Server Error", 500);
     }
 
+    // An action may *return* (not just throw) a redirect or any Response —
+    // the documented pattern is `return redirect("/")`. Propagate it verbatim
+    // so the browser/`<Form>` sees a real 3xx (and follows it) instead of a
+    // 200 with the Response serialized into a JSON body. sanitizeRedirect()
+    // neutralizes an off-origin Location that didn't go through redirect()'s
+    // allowExternal opt-in (e.g. a raw `new Response(…,{Location:"//evil"})`).
+    if (actionData instanceof Response) return sanitizeRedirect(actionData, request.url);
+
     // Client-side Form submits with this header — return JSON, not HTML.
     if (request.headers.get("X-BractJS-Action")) {
       return json(actionData ?? null);
@@ -163,7 +172,7 @@ async function route(
   try {
     loaderResults = await runLoaders(chain, args, onError);
   } catch (err) {
-    if (isRedirect(err)) return err as Response;
+    if (isRedirect(err)) return sanitizeRedirect(err as Response, request.url);
     if (isHttpError(err)) return error(err.message, err.status);
     await fireOnError(onError, err, request);
     if (isExplicitDev()) return error(err instanceof Error ? err.message : String(err), 500);
@@ -208,5 +217,7 @@ async function route(
     manifest,
     meta,
     routeFile: match.routeFile.filePath,
+    // Set by the opt-in csp() middleware; undefined otherwise.
+    nonce: getCspNonce(context),
   });
 }