@bractjs/bractjs 0.1.25 → 0.1.27

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

package/src/shared/meta-tags.tsx

@@ -0,0 +1,46 @@
+import { Fragment, createElement, type ReactElement } from "react";
+import type { MetaDescriptor } from "./route-types.ts";
+
+/**
+ * Renders route `meta()` descriptors as document-metadata elements.
+ *
+ * React 19 automatically hoists `<title>`, `<meta>`, and `<link>` rendered
+ * anywhere in the tree up into `<head>` — both during streaming SSR and on the
+ * client. We render the merged descriptors here (inside the SSR shell AND the
+ * ClientRouter tree) so:
+ *   - crawlers and no-JS clients see real <title>/<meta> tags in the SSR HTML,
+ *   - hydration matches the server tree (no mismatch warning),
+ *   - soft navigation updates the document head by re-rendering this component.
+ *
+ * Keys are derived from the descriptor identity (title / name / property) so a
+ * later route can override an earlier one without React duplicating the node.
+ */
+export function MetaTags({ meta }: { meta: MetaDescriptor[] }): ReactElement {
+  const children: ReactElement[] = [];
+
+  for (const d of meta) {
+    if ("title" in d && typeof (d as { title: unknown }).title === "string") {
+      const title = (d as { title: string }).title;
+      children.push(createElement("title", { key: "title" }, title));
+    } else if ("name" in d && "content" in d) {
+      const { name, content } = d as { name: string; content: string };
+      children.push(createElement("meta", { key: `name:${name}`, name, content }));
+    } else if ("property" in d && "content" in d) {
+      const { property, content } = d as { property: string; content: string };
+      children.push(createElement("meta", { key: `prop:${property}`, property, content }));
+    } else {
+      // Arbitrary descriptor: render each string field as a meta attribute set.
+      const entries = Object.entries(d).filter(
+        ([, v]) => typeof v === "string",
+      ) as Array<[string, string]>;
+      if (entries.length > 0) {
+        const props: Record<string, string> = {};
+        for (const [k, v] of entries) props[k] = v;
+        const key = entries.map(([k, v]) => `${k}=${v}`).join("&");
+        children.push(createElement("meta", { key: `raw:${key}`, ...props }));
+      }
+    }
+  }
+
+  return createElement(Fragment, null, ...children);
+}

package/types/index.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode, Context } from "react";
+import type { ReactNode, Context, CSSProperties } from "react";
 
 // ── Route types ───────────────────────────────────────────────────────────
 export type {
@@ -34,7 +34,8 @@ export interface LifecycleHooks {
 export declare function defineLifecycle(hooks: LifecycleHooks): LifecycleHooks;
 export declare function createServer(config?: Partial<BractJSConfig>): { stop(): void };
 export declare function renderRoute(options: RenderOptions): Promise<Response>;
-export declare function redirect(url: string, status?: number): Response;
+export interface RedirectOptions { allowExternal?: boolean; }
+export declare function redirect(url: string, status?: number, headers?: HeadersInit, options?: RedirectOptions): Response;
 export declare function json<T>(data: T, init?: ResponseInit): Response;
 export declare function error(message: string, status?: number): Response;
 
@@ -128,13 +129,49 @@ export declare function validate<T>(
   input: FormData | Record<string, unknown>,
 ): Promise<T>;
 
+// ── Typed-routing registration seam ───────────────────────────────────────
+// Mirror of src/client/registry.ts. Augment `Register` (done by `bractjs codegen`
+// in app/route-types.gen.ts) to make <Link>/useNavigate/useParams/useSearchParams
+// type-safe. Un-augmented, everything falls back to loose `string` / Record so
+// apps that never run codegen keep compiling. Keep in sync with registry.ts.
+export interface Register {}
+export interface RouteRegistry {
+  routes: string;
+  params: Record<string, Record<string, string>>;
+  search: Record<string, Record<string, string>>;
+}
+export interface RouteSearchParamsMap {}
+export interface RouteContextMap {}
+// Infer each member directly (NOT `infer R extends RouteRegistry` — a constrained
+// infer fails to match the generated registry and falls back to loose). Keep in
+// sync with src/client/registry.ts.
+export type RegisteredRoutes =
+  Register extends { routes: { routes: infer R } } ? R : string;
+export type RegisteredParamsMap =
+  Register extends { routes: { params: infer P } } ? P : Record<string, Record<string, string>>;
+export type RegisteredSearchMap =
+  Register extends { routes: { search: infer S } } ? S : Record<string, Record<string, string>>;
+export type ParamsFor<TTo> =
+  TTo extends keyof RegisteredParamsMap ? RegisteredParamsMap[TTo] : Record<string, string>;
+export type SearchFor<TTo> =
+  TTo extends keyof RegisteredSearchMap ? RegisteredSearchMap[TTo] : Record<string, string>;
+export declare function buildPath(pattern: string, params: Record<string, string | number>): string;
+
 // ── Client components ─────────────────────────────────────────────────────
 export declare function Scripts(): null;
 export declare function LiveReload(): ReactNode;
 export declare function Outlet(): ReactNode;
 
-export interface LinkProps { to: string; prefetch?: "hover" | "none"; viewTransition?: boolean; children?: ReactNode; className?: string; [key: string]: unknown; }
-export declare function Link(props: LinkProps): ReactNode;
+export type LinkProps<TTo extends RegisteredRoutes = RegisteredRoutes> = {
+  to: TTo | (string & {});
+  params?: ParamsFor<TTo>;
+  prefetch?: "hover" | "none";
+  viewTransition?: boolean;
+  children?: ReactNode;
+  className?: string;
+  [key: string]: unknown;
+};
+export declare function Link<TTo extends RegisteredRoutes = RegisteredRoutes>(props: LinkProps<TTo>): ReactNode;
 
 export interface FormProps { method?: "post" | "put" | "delete"; action?: string; children?: ReactNode; [key: string]: unknown; }
 export declare function Form(props: FormProps): ReactNode;
@@ -142,12 +179,36 @@ export declare function Form(props: FormProps): ReactNode;
 export interface AwaitProps<T> { resolve: Promise<T>; fallback: ReactNode; children: (data: T) => ReactNode; }
 export declare function Await<T>(props: AwaitProps<T>): ReactNode;
 
+export type ImageFormat = "webp" | "avif" | "jpeg" | "png";
+export type ImageFit = "cover" | "contain" | "fill";
+export interface ImageProps {
+  src: string;
+  alt: string;
+  width?: number;
+  height?: number;
+  quality?: number;
+  format?: ImageFormat;
+  fit?: ImageFit;
+  priority?: boolean;
+  sizes?: string;
+  className?: string;
+  style?: CSSProperties;
+}
+export declare function Image(props: ImageProps): ReactNode;
+
 // ── Client hooks ──────────────────────────────────────────────────────────
 export declare function useLoaderData<T = unknown>(): T;
 export declare function useActionData<T = unknown>(): T | null;
-export declare function useParams(): Record<string, string>;
+export declare function useParams<TTo extends string>(): ParamsFor<TTo>;
+export declare function useParams<T extends Record<string, string> = Record<string, string>>(): T;
 export type NavigationState = "idle" | "loading" | "submitting";
 export declare function useNavigation(): { state: NavigationState };
+
+export interface NavigateOptions<TTo extends RegisteredRoutes = RegisteredRoutes> { params?: ParamsFor<TTo>; }
+export interface NavigateFn {
+  <TTo extends RegisteredRoutes>(to: TTo | (string & {}), options?: NavigateOptions<TTo>): Promise<void>;
+}
+export declare function useNavigate(): NavigateFn;
 export interface FetcherResult {
   data: unknown;
   state: NavigationState;
@@ -166,6 +227,7 @@ export interface SearchParamsResult<T extends Record<string, string> = Record<st
   getParam<K extends keyof T & string>(key: K): T[K] | null;
   setSearchParams(updater: Record<string, string> | ((prev: URLSearchParams) => URLSearchParams)): void;
 }
+export declare function useSearchParams<TTo extends string>(): SearchParamsResult<SearchFor<TTo>>;
 export declare function useSearchParams<T extends Record<string, string> = Record<string, string>>(): SearchParamsResult<T>;
 
 // ── Typed route context ───────────────────────────────────────────────────