@bractjs/bractjs 0.1.24 → 0.1.26

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";

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),
   });
 }

package/src/server/response.ts

@@ -3,12 +3,32 @@ export interface RedirectOptions {
   allowExternal?: boolean;
 }
 
-function isSafeInternalRedirect(url: string): boolean {
-  // Must be path-only: single leading "/" not followed by "/" or "\".
-  // Rejects: "//evil.com", "/\\evil.com", "https://...", "javascript:...", "".
+// Brand stamped onto redirect Responses the app explicitly opted into sending
+// off-origin via `redirect(url, …, { allowExternal: true })`. sanitizeRedirect()
+// (below) lets branded Responses through untouched but neutralizes any *other*
+// 3xx whose Location escapes the request origin — e.g. a loader/action that
+// throws a raw `new Response(null,{status:302,headers:{Location:"//evil"}})`,
+// which would otherwise bypass this helper's guard entirely.
+const ALLOW_EXTERNAL = Symbol.for("bractjs.redirect.allowExternal");
+
+export function isSafeInternalRedirect(url: string): boolean {
+  // Must be path-only: a single leading "/" that does not begin an authority
+  // ("//host", "/\\host") or a scheme. Rejects, raw OR percent-encoded:
+  //   "//evil.com", "/\\evil.com", "/%2f%2fevil.com", "/%5cevil.com",
+  //   "https://…", "javascript:…", "" — plus any control/whitespace char that
+  //   browsers strip or normalize ("/\t//evil", "/\n/evil") before resolving.
   if (url.length === 0) return false;
+  // Reject any C0 control char, space, or DEL — browsers strip/normalize these
+  // and can turn "/\t//evil" into a protocol-relative escape. Checked via char
+  // code (not a regex with control-char literals) to keep the source portable.
+  for (let i = 0; i < url.length; i++) {
+    const c = url.charCodeAt(i);
+    if (c <= 0x20 || c === 0x7f) return false;
+  }
   if (url[0] !== "/") return false;
-  if (url[1] === "/" || url[1] === "\\") return false;
+  const rest = url.slice(1).toLowerCase();
+  if (rest.startsWith("/") || rest.startsWith("\\")) return false;
+  if (rest.startsWith("%2f") || rest.startsWith("%5c")) return false;
   return true;
 }
 
@@ -26,7 +46,40 @@ export function redirect(
   }
   const h = new Headers(headers);
   h.set("Location", url);
-  return new Response(null, { status, headers: h });
+  const res = new Response(null, { status, headers: h });
+  // Brand opt-in external redirects so the global sanitizer trusts them.
+  if (options?.allowExternal) (res as { [ALLOW_EXTERNAL]?: true })[ALLOW_EXTERNAL] = true;
+  return res;
+}
+
+/**
+ * Last-line guard applied to every redirect Response the request handler is
+ * about to emit. Returns the Response untouched unless it is a 3xx whose
+ * `Location` escapes `requestUrl`'s origin AND it was not produced by
+ * `redirect(..., { allowExternal: true })`. In that case the off-origin
+ * Location is treated as an open-redirect attempt: it is logged and replaced
+ * with a 500 so the client never follows it.
+ */
+export function sanitizeRedirect(res: Response, requestUrl: string): Response {
+  if (res.status < 300 || res.status >= 400) return res;
+  if ((res as { [ALLOW_EXTERNAL]?: true })[ALLOW_EXTERNAL]) return res;
+  const loc = res.headers.get("Location");
+  if (loc === null) return res;
+  // Same-origin absolute Locations are fine; reduce to a path and re-check.
+  let safe = isSafeInternalRedirect(loc);
+  if (!safe) {
+    try {
+      safe = new URL(loc, requestUrl).origin === new URL(requestUrl).origin;
+    } catch {
+      safe = false;
+    }
+  }
+  if (safe) return res;
+  console.error(
+    `[bractjs] blocked off-origin redirect Location "${loc}". ` +
+      `Use redirect(url, status, headers, { allowExternal: true }) to opt in.`,
+  );
+  return error("Internal Server Error", 500);
 }
 
 export function json<T>(data: T, init?: ResponseInit): Response {

package/src/server/serve.ts

@@ -12,6 +12,7 @@ import { BunAdapter, type BractAdapter } from "./adapter.ts";
 import type { ModuleRegistry } from "./layout.ts";
 import { resolve, join } from "node:path";
 import { fireOnError, type OnErrorHook } from "./lifecycle.ts";
+import { installUseClientServerStub } from "./use-client-runtime.ts";
 
 export interface I18nConfig {
   locales: string[];
@@ -107,6 +108,15 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
       }))
     : Promise.resolve(config.manifest ?? DEFAULT_MANIFEST);
 
+  // When routes are imported from SOURCE at runtime (dev server AND
+  // `bractjs start`, which fall back to scanRoutes + dynamic import rather than
+  // a pre-stubbed compiled bundle), a `"use client"` route component would
+  // execute during SSR and crash on browser-only hooks. Install the runtime
+  // stub that null-renders such modules on the server — parity with the
+  // compiled bundle's useClientStubPlugin. Skipped on the compiled path, which
+  // supplies a pre-built moduleRegistry.
+  if (!config.moduleRegistry) installUseClientServerStub(appDir);
+
   // Codegen / compiled-binary path: when the caller supplies pre-scanned
   // routes, skip the runtime `Bun.Glob` scan that `bun build --compile`
   // can't satisfy (the routes/ directory isn't on the filesystem in a

package/src/server/static.ts

@@ -1,9 +1,19 @@
 import { join, resolve, sep } from "node:path";
 import { realpath } from "node:fs/promises";
+import { isDevRuntime } from "./env.ts";
 
 const IMMUTABLE = "public, max-age=31536000, immutable";
 const NO_CACHE = "no-cache";
 
+// Hashed client chunks are safe to cache forever in production (a content change
+// yields a new filename). In DEV, however, the dev rebuilder can reuse a chunk
+// filename across rebuilds while its contents change, so marking them immutable
+// makes the browser pin stale JS (e.g. an old route matcher) for a year. Serve
+// them no-cache in dev so each rebuild is picked up.
+function clientAssetCacheControl(): string {
+  return isDevRuntime() ? NO_CACHE : IMMUTABLE;
+}
+
 /**
  * Resolve to a canonical path that follows symlinks, with a fallback for
  * `bun build --compile` binaries.
@@ -66,7 +76,7 @@ export async function serveStatic(
     if (!full) return null;
     const file = Bun.file(full);
     if (!(await file.exists())) return null;
-    return new Response(file, { headers: { "Cache-Control": IMMUTABLE } });
+    return new Response(file, { headers: { "Cache-Control": clientAssetCacheControl() } });
   }
 
   if (pathname.startsWith("/public/")) {

package/src/server/stream-handler.ts

@@ -1,6 +1,5 @@
 import { resolveAction } from "./action-registry.ts";
 import { isExplicitDev } from "./env.ts";
-import { isAllowedMutation } from "./csrf.ts";
 
 // ── SSE helpers ────────────────────────────────────────────────────────────
 
@@ -24,12 +23,14 @@ export async function handleStreamRequest(request: Request): Promise<Response |
   // SECURITY(medium): exact-match prevents URL confusion.
   if (url.pathname !== "/_stream") return null;
 
-  // SECURITY(high): server actions can have side effects. A cross-origin
-  // <script>/<img>/<link rel=prefetch> pointing at /_stream?id=… would
-  // otherwise invoke any registered action with the user's cookies. Require
-  // the same gate as /_action: either a same-origin Origin header, or the
-  // client-issued X-BractJS-Action header (blocked cross-origin by CORS).
-  if (!isAllowedMutation(request)) {
+  // SECURITY(high): /_stream invokes side-effecting server actions over GET.
+  // GET can't carry a body and browsers issue cross-origin GETs from
+  // <script>/<img>/<link rel=prefetch> *without* an Origin header, so a bare
+  // same-origin-Origin gate is not enough here. Require the client-issued
+  // X-BractJS-Action header outright: it's a custom header, so browsers block
+  // it cross-origin without a CORS preflight, and the real client (useFetcher)
+  // always sends it. This is strictly tighter than the /_action gate.
+  if (!request.headers.get("X-BractJS-Action")) {
     return new Response(sseChunk("error", { message: "Forbidden" }), {
       status: 403,
       headers: {

package/src/server/use-client-runtime.ts

@@ -0,0 +1,62 @@
+import { resolve } from "node:path";
+import { hasClientDirective, extractExports } from "../build/directives.ts";
+
+/**
+ * Runtime stubbing of `"use client"` modules during SSR, for the source-import
+ * code path.
+ *
+ * The compiled server bundle (`bun build --compile`) applies
+ * `useClientStubPlugin`, replacing every `"use client"` export with a
+ * `() => null` component so SSR never calls browser-only hooks/APIs. But both
+ * the dev server AND `bractjs start` render route modules via a raw `import()`
+ * of the SOURCE (they fall back to `scanRoutes` + dynamic import rather than the
+ * pre-stubbed bundle). Without this, a `"use client"` route component executes
+ * on the server and crashes on `useState`/`useRef` ("Invalid hook call").
+ *
+ * Registering this `Bun.plugin` makes the server process apply the same
+ * transform at module-load time. It only affects this process's `import()`
+ * (SSR) — the separately bundled client still ships the real component, so
+ * hydration restores interactivity in the browser.
+ *
+ * The filter is scoped to source files UNDER appDir (never node_modules): a
+ * runtime onLoad must always return an object, so any matched non-client file is
+ * passed through verbatim, and we must not re-transpile third-party packages
+ * (doing so breaks CJS interop shapes such as react/jsx-dev-runtime).
+ *
+ * Idempotent: safe to call more than once per process.
+ */
+let installed = false;
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function installUseClientServerStub(appDir = "./app"): void {
+  if (installed) return;
+  installed = true;
+
+  const absAppDir = resolve(appDir);
+  const filter = new RegExp(`^${escapeRegExp(absAppDir)}.*\\.(tsx?|jsx?)$`);
+
+  Bun.plugin({
+    name: "bractjs:use-client-server-stub",
+    setup(build) {
+      build.onLoad({ filter }, async ({ path }) => {
+        const src = await Bun.file(path).text();
+        const loader = path.endsWith(".tsx") ? "tsx" : path.endsWith(".jsx") ? "jsx" : path.endsWith(".ts") ? "ts" : "js";
+        if (!hasClientDirective(src)) {
+          // Runtime onLoad must return an object; pass app source through. Bun
+          // transpiles app TS/TSX anyway, so this is a no-op in practice.
+          return { contents: src, loader };
+        }
+        const names = extractExports(src).filter((n) => n !== "default");
+        const stubs = names.map((n) => `export const ${n} = () => null;`);
+        // Always provide a null default — a "use client" module rendered on the
+        // server should yield nothing, regardless of how default is declared
+        // (which `extractExports` can't always detect, e.g. `export default X`).
+        stubs.push("export default () => null;");
+        return { contents: stubs.join("\n"), loader: "ts" };
+      });
+    },
+  });
+}