@bractjs/bractjs 0.1.5 → 0.1.7

package/src/server/api-route.ts

@@ -0,0 +1,127 @@
+import { isExplicitDev } from "./env.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+// SECURITY(high): cap request bodies for typed API routes so a single client
+// cannot exhaust memory. Same 1 MiB ceiling used by /_action JSON.
+const MAX_BODY_BYTES = 1_048_576;
+
+export interface ApiRouteDefinition<
+  TMethod extends HttpMethod,
+  TPath extends string,
+  TInput,
+  TOutput,
+> {
+  method: TMethod;
+  path: TPath;
+  handler: (input: TInput, request: Request) => TOutput | Promise<TOutput>;
+  _types: { input: TInput; output: TOutput };
+}
+
+// Collect all registered routes into a union type.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const routeRegistry: ApiRouteDefinition<HttpMethod, string, any, any>[] = [];
+
+/**
+ * Define a typed API route.
+ *
+ * Usage in app/api/users.ts:
+ *   export const getUsers = bract.route("GET", "/api/users", async () => db.users.findAll());
+ */
+export function route<
+  TMethod extends HttpMethod,
+  TPath extends string,
+  TInput,
+  TOutput,
+>(
+  method: TMethod,
+  path: TPath,
+  handler: (input: TInput, request: Request) => TOutput | Promise<TOutput>,
+): ApiRouteDefinition<TMethod, TPath, TInput, TOutput> {
+  const def: ApiRouteDefinition<TMethod, TPath, TInput, TOutput> = {
+    method,
+    path,
+    handler,
+    _types: {} as { input: TInput; output: TOutput },
+  };
+  routeRegistry.push(def);
+  return def;
+}
+
+// ── Runtime dispatch ───────────────────────────────────────────────────────
+
+/**
+ * Attempt to handle the request by matching against registered API routes.
+ * Returns null if no route matches so the caller can fall through.
+ */
+export async function handleApiRequest(request: Request): Promise<Response | null> {
+  const url = new URL(request.url);
+  for (const def of routeRegistry) {
+    if (def.method !== request.method) continue;
+    if (!pathMatches(def.path, url.pathname)) continue;
+
+    let input: unknown = undefined;
+    if (request.method !== "GET" && request.method !== "DELETE") {
+      // Trust an advertised Content-Length up front so oversized payloads
+      // are rejected before we buffer them.
+      const clRaw = request.headers.get("Content-Length");
+      if (clRaw) {
+        const cl = Number(clRaw);
+        if (Number.isFinite(cl) && cl > MAX_BODY_BYTES) {
+          return new Response("Payload Too Large", { status: 413 });
+        }
+      }
+
+      const ct = request.headers.get("Content-Type") ?? "";
+      if (ct.includes("application/json")) {
+        const text = await request.text();
+        // Defense in depth: clients can lie about Content-Length.
+        if (text.length > MAX_BODY_BYTES) {
+          return new Response("Payload Too Large", { status: 413 });
+        }
+        try {
+          input = text ? JSON.parse(text) : undefined;
+        } catch {
+          return new Response("Bad Request: invalid JSON", { status: 400 });
+        }
+      } else if (ct.includes("application/x-www-form-urlencoded") || ct.includes("multipart/form-data")) {
+        input = await request.formData();
+      }
+    }
+
+    try {
+      const result = await def.handler(input, request);
+      return Response.json(result);
+    } catch (err) {
+      if (err instanceof Response) return err;
+      // SECURITY(high): never leak internal error details in production.
+      // Dev mode keeps the message for DX; prod returns a generic 500.
+      console.error("[bractjs] api route error:", err);
+      const msg = isExplicitDev()
+        ? (err instanceof Error ? err.message : String(err))
+        : "Internal Server Error";
+      return Response.json({ error: msg }, { status: 500 });
+    }
+  }
+  return null;
+}
+
+function pathMatches(pattern: string, pathname: string): boolean {
+  const pSegs = pattern.split("/").filter(Boolean);
+  const rSegs = pathname.split("/").filter(Boolean);
+  if (pSegs.length !== rSegs.length) return false;
+  // SECURITY(medium): `:param` segments accept any non-empty string but are
+  // not currently passed to the handler — handlers must read params from
+  // `request.url` themselves and validate (especially against ".." or
+  // path-traversal-shaped values) before using them in file system or SQL ops.
+  return pSegs.every((seg, i) => seg.startsWith(":") || seg === rSegs[i]);
+}
+
+// ── AppRoutes type extraction ─────────────────────────────────────────────
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AppApiRoutes = (typeof routeRegistry)[number] extends ApiRouteDefinition<infer M, infer P, infer I, infer O>
+  ? { method: M; path: P; input: I; output: O }
+  : never;

package/src/server/context.ts

@@ -0,0 +1,22 @@
+// ── ContextFactory ─────────────────────────────────────────────────────────
+
+export interface ContextFactory<T> {
+  _factory: (args: { request: Request; params: Record<string, string> }) => T | Promise<T>;
+}
+
+/**
+ * Define a per-route context factory.
+ *
+ * Route files export `export const context = defineContext(async ({ request, params }) => { ... })`
+ * The result is merged into the `context` arg received by all loaders and actions on that route.
+ *
+ * Example:
+ *   export const context = defineContext(async ({ request }) => ({
+ *     user: await getUser(request),
+ *   }));
+ */
+export function defineContext<T>(
+  factory: (args: { request: Request; params: Record<string, string> }) => T | Promise<T>,
+): ContextFactory<T> {
+  return { _factory: factory };
+}

package/src/server/csrf.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+// 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.
+export function isAllowedMutation(request: Request): boolean {
+  if (request.headers.get("X-BractJS-Action")) return true;
+  const origin = request.headers.get("Origin");
+  if (!origin) return false;
+  try {
+    return new URL(origin).origin === new URL(request.url).origin;
+  } catch {
+    return false;
+  }
+}

package/src/server/env.ts

@@ -2,6 +2,22 @@ export function isDev(): boolean {
   return Bun.env.NODE_ENV !== "production";
 }
 
+/**
+ * Strict "is development?" check used to gate sensitive output (error
+ * messages, stack traces) that would otherwise leak in production.
+ *
+ * Unlike isDev(), this returns true ONLY when NODE_ENV is explicitly set
+ * to "development". An unset/empty NODE_ENV is treated as production so an
+ * operator who forgets to set it never leaks internals.
+ *
+ * SECURITY(high): always use this for guarding info-disclosure code paths
+ * (server errors → response bodies) rather than isDev().
+ */
+export function isExplicitDev(): boolean {
+  const v = Bun.env.NODE_ENV;
+  return v === "development" || v === "dev";
+}
+
 export function requireEnv(key: string): string {
   const value = Bun.env[key];
   if (!value) {
@@ -10,6 +26,11 @@ export function requireEnv(key: string): string {
   return value;
 }
 
+// Build LS/PS at runtime so the source contains no raw U+2028/U+2029
+// (which would break JS parsing as LineTerminators).
+const LS = String.fromCharCode(0x2028);
+const PS = String.fromCharCode(0x2029);
+
 export function safeStringify(data: unknown): string {
   const seen = new WeakSet();
   const json = JSON.stringify(data, (_key, value) => {
@@ -19,11 +40,12 @@ export function safeStringify(data: unknown): string {
     }
     return value;
   });
-  // Escape HTML-sensitive characters so this JSON is safe to embed inside a
-  // <script> tag.  \u003c / \u003e / \u0026 are valid JSON unicode escapes —
-  // JSON.parse on the client decodes them transparently.
+  // Escape HTML-sensitive chars + JS LineTerminators (U+2028 / U+2029) so this
+  // JSON is safe to embed inside a <script> tag.
   return json
     .replace(/</g, "\\u003c")
     .replace(/>/g, "\\u003e")
-    .replace(/&/g, "\\u0026");
+    .replace(/&/g, "\\u0026")
+    .replaceAll(LS, "\\u2028")
+    .replaceAll(PS, "\\u2029");
 }

package/src/server/i18n.ts

@@ -0,0 +1,63 @@
+import type { RouteFile } from "./scanner.ts";
+
+export interface I18nConfig {
+  locales: string[];
+  defaultLocale: string;
+}
+
+/**
+ * Given a list of route files, return augmented copies that include a
+ * `/:locale` prefix in their URL pattern.
+ *
+ * The original routes are preserved so the framework still works without
+ * a locale prefix (SSR with the default locale).
+ */
+export function wrapRoutesWithLocale(routes: RouteFile[], i18n: I18nConfig): RouteFile[] {
+  const prefix = i18n.locales.map((l) => l.replace(/[^A-Za-z0-9_-]/g, "")).join("|");
+  if (!prefix) return routes;
+
+  const localized: RouteFile[] = [];
+  for (const route of routes) {
+    // Prepend the locale param segment to the URL pattern.
+    const localizedPattern = route.urlPattern === "" || route.urlPattern === "/"
+      ? `[locale]`
+      : `[locale]/${route.urlPattern}`;
+
+    localized.push({
+      ...route,
+      urlPattern: localizedPattern,
+      segments: [{ param: "locale" }, ...route.segments],
+    });
+  }
+
+  // Return both original (for default locale without prefix) and localized routes.
+  return [...routes, ...localized];
+}
+
+/**
+ * Strip a locale prefix from the beginning of a pathname.
+ * Returns `{ locale, strippedPathname }` — locale is null when not present.
+ */
+export function stripLocale(
+  pathname: string,
+  locales: string[],
+): { locale: string | null; strippedPathname: string } {
+  const segs = pathname.replace(/^\//, "").split("/");
+  const first = segs[0];
+  if (first && locales.includes(first)) {
+    return {
+      locale: first,
+      strippedPathname: "/" + segs.slice(1).join("/") || "/",
+    };
+  }
+  return { locale: null, strippedPathname: pathname };
+}
+
+/**
+ * Build a locale-aware variant of the `/_data` path query string.
+ * Injects the locale into params so loaders can read it from context.
+ */
+export function localizedDataPath(pathname: string, locale: string | null): string {
+  if (!locale) return pathname;
+  return `/${locale}${pathname === "/" ? "" : pathname}`;
+}

package/src/server/loader.ts

@@ -1,6 +1,8 @@
 import type { LoaderArgs, ActionArgs, RouteModule } from "../shared/route-types.ts";
 import type { LayoutChain } from "./layout.ts";
 import { isRedirect, isHttpError } from "../shared/errors.ts";
+import { isExplicitDev } from "./env.ts";
+import type { ContextFactory } from "./context.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -25,10 +27,49 @@ export async function safeRun<T>(
   } catch (err) {
     // Re-throw redirects and HTTP errors — caller handles them
     if (isRedirect(err) || isHttpError(err)) throw err;
-    return { __error: err };
+    // SECURITY(high): `__error` is serialized into the SSR HTML via
+    // safeStringify and reaches the browser. A custom Error subclass with
+    // public fields (db query text, file paths, internal IDs, raw user data)
+    // would leak them. In production we expose only a generic message; in
+    // dev we surface the real message + stack for DX. Routes wanting to
+    // surface structured user-facing errors should throw an HttpError, not
+    // a custom Error subclass.
+    console.error("[bractjs] loader error:", err);
+    const safe = isExplicitDev()
+      ? {
+          message: err instanceof Error ? err.message : String(err),
+          stack: err instanceof Error ? err.stack : undefined,
+        }
+      : { message: "Internal Server Error" };
+    return { __error: safe };
   }
 }
 
+// ── runBeforeLoad ──────────────────────────────────────────────────────────
+
+/**
+ * Run the route module's optional `beforeLoad()` export.
+ * Returns a Response if beforeLoad wants to short-circuit (redirect / 403),
+ * or null to continue normally.
+ */
+export async function runBeforeLoad(
+  routeModule: RouteModule,
+  args: LoaderArgs,
+): Promise<Response | null> {
+  const fn = routeModule.beforeLoad as
+    | ((a: { params: Record<string,string>; context: Record<string,unknown>; location: { pathname: string; search: string } }) => unknown)
+    | undefined;
+  if (!fn) return null;
+  const url = new URL(args.request.url);
+  const result = await fn({
+    params: args.params,
+    context: args.context,
+    location: { pathname: url.pathname, search: url.search },
+  });
+  if (result instanceof Response) return result;
+  return null;
+}
+
 // ── runLoaders ─────────────────────────────────────────────────────────────
 
 export async function runLoaders(
@@ -78,3 +119,22 @@ export function buildLoaderArgs(
 ): LoaderArgs {
   return { request, params, context };
 }
+
+// ── runRouteContext ────────────────────────────────────────────────────────
+
+/**
+ * If the route module exports a `context` ContextFactory, run its factory and
+ * merge the result into a new context object.  Returns the base context as-is
+ * if no factory is present.
+ */
+export async function runRouteContext(
+  routeModule: RouteModule & { context?: ContextFactory<unknown> },
+  request: Request,
+  params: Record<string, string>,
+  baseContext: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const factory = routeModule.context;
+  if (!factory || typeof factory._factory !== "function") return baseContext;
+  const extra = await factory._factory({ request, params });
+  return { ...baseContext, ...(extra as Record<string, unknown>) };
+}

package/src/server/middleware.ts

@@ -30,16 +30,20 @@ export class MiddlewarePipeline {
     ctx: MiddlewareContext,
     handler: () => Promise<Response>,
   ): Promise<Response> {
-    let index = 0;
     const fns = this.fns;
-
-    const dispatch = (): Promise<Response> => {
-      if (index >= fns.length) return handler();
-      const fn = fns[index++];
-      return fn(ctx, dispatch);
+    let lastCalled = -1;
+
+    const dispatch = (i: number): Promise<Response> => {
+      if (i <= lastCalled) {
+        return Promise.reject(new Error("middleware: next() called more than once"));
+      }
+      lastCalled = i;
+      if (i >= fns.length) return handler();
+      const fn = fns[i];
+      return fn(ctx, () => dispatch(i + 1));
     };
 
-    return dispatch();
+    return dispatch(0);
   }
 }
 

package/src/server/render.ts

@@ -35,12 +35,14 @@ export async function renderRoute(options: RenderOptions): Promise<Response> {
     status = 200,
   } = options;
 
-  const devOverlay = isDev() ? errorOverlayScript + "\n" : "";
-  const metaHtml = renderMetaTags(mergeMeta(options.meta ?? []));
-  // Include manifest + routeFile so the client can pre-import the route module
-  // before hydrateRoot(), preventing the SSR/client tree mismatch.
+  const devFlag = isDev() ? "window.__BRACT_DEV__=true;" : "";
+  const devOverlay = isDev() ? 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.
   const bootstrapScriptContent =
-    devOverlay + `window.__BRACTJS_DATA__=${safeStringify({ loaderData, actionData, params, pathname, manifest, routeFile: options.routeFile, meta: metaHtml })};`;
+    devOverlay + `window.__BRACTJS_DATA__=${safeStringify({ loaderData, actionData, params, pathname, manifest, routeFile: options.routeFile, meta: mergedMeta })};`;
 
   let renderError: unknown;
 
@@ -60,6 +62,13 @@ 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.
+      "X-Content-Type-Options": "nosniff",
+      "X-Frame-Options": "SAMEORIGIN",
+      "Referrer-Policy": "strict-origin-when-cross-origin",
     },
   });
 }

package/src/server/request-handler.ts

@@ -1,15 +1,16 @@
-import { join } from "node:path";
 import { createElement } from "react";
 import type { TrieNode } from "./matcher.ts";
 import { matchRoute } from "./matcher.ts";
 import { resolveRouteChain } from "./layout.ts";
-import { runLoaders, runAction, buildLoaderArgs } from "./loader.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 { isRedirect } from "../shared/errors.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";
 
 export interface HandlerConfig {
   appDir: string;
@@ -19,6 +20,11 @@ export interface HandlerConfig {
 
 const MUTATING_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
 
+// SECURITY(medium): cap form/multipart bodies for route mutations so a
+// single client cannot exhaust memory. Multipart uploads of legitimate
+// large files should use a dedicated upload endpoint configured separately.
+const MAX_FORM_BYTES = 10 * 1_048_576; // 10 MiB
+
 export async function handleRequest(
   request: Request,
   trie: TrieNode,
@@ -39,29 +45,56 @@ async function route(
   config: HandlerConfig,
   context: Record<string, unknown>,
 ): Promise<Response> {
-  const { appDir, publicDir, manifest } = config;
+  const { appDir, manifest } = config;
   const url = new URL(request.url);
   const { pathname, searchParams } = url;
 
-  // ── Static public assets ──────────────────────────────────────────────
-  if (pathname.startsWith("/public/")) {
-    const file = Bun.file(join(publicDir, pathname.slice("/public/".length)));
-    if (await file.exists()) return new Response(file);
-    return error("Not Found", 404);
-  }
-
   // ── /_data soft-nav JSON endpoint ─────────────────────────────────────
-  if (pathname.startsWith("/_data")) {
+  // Exact-match: "/_data" only. "/_dataXYZ" must not reach here.
+  if (pathname === "/_data") {
+    // SECURITY(high): /_data must be GET-only. It runs loaders for the
+    // target path; allowing POST/PUT/DELETE would bypass the CSRF gate that
+    // protects route mutations and could trigger non-idempotent loader code.
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      return error("Method Not Allowed", 405);
+    }
+    // SECURITY(medium): `path` param is user-controlled and used to reconstruct a URL. matchRoute only matches registered routes (trie), so unmapped paths return 404 rather than accidentally proxying. Ensure the trie stays the single source of truth for what paths are reachable.
     const targetPath = searchParams.get("path") ?? "/";
-    const match = matchRoute(targetPath, trie);
+    // Reject pathologically long path params to bound trie matching + URL parsing cost.
+    if (targetPath.length > 2048) return json({ error: "Bad Request" }, { status: 400 });
+    // Strip query string from path param so matching works on the pathname only.
+    const [targetPathname, targetSearch] = targetPath.split("?");
+    const match = matchRoute(targetPathname, trie);
     if (!match) return json({ error: "Not Found" }, { status: 404 });
 
     try {
       const chain = await resolveRouteChain(match.routeFile, appDir);
-      const args = buildLoaderArgs(request, match.params, {});
+      // Reconstruct a Request that carries the original search params so loaders
+      // can access them via request.url / new URL(request.url).searchParams.
+      const targetUrl = new URL(request.url);
+      targetUrl.pathname = targetPathname;
+      targetUrl.search = targetSearch ? "?" + targetSearch : "";
+      const loaderRequest = new Request(targetUrl.toString(), {
+        headers: request.headers,
+        method: "GET",
+      });
+      // 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);
+      const beforeLoadResponse = await runBeforeLoad(chain.route, args);
+      if (beforeLoadResponse) return beforeLoadResponse;
       const results = await runLoaders(chain, args);
       return json({ root: results.root, layouts: results.layouts, route: results.route, params: match.params });
     } catch (err) {
+      if (isRedirect(err)) return err as Response;
+      if (isHttpError(err)) return json({ error: err.message }, { status: err.status });
       console.error("[bractjs] /_data error:", err);
       return json({ error: "Internal Server Error" }, { status: 500 });
     }
@@ -72,17 +105,41 @@ async function route(
   if (!match) return error("Not Found", 404);
 
   const chain = await resolveRouteChain(match.routeFile, appDir);
-  const args = buildLoaderArgs(request, match.params, context);
+  // Run per-route context factory (defineContext export) before loaders.
+  const routeContext = await runRouteContext(
+    chain.route as Parameters<typeof runRouteContext>[0],
+    request,
+    match.params,
+    context,
+  );
+  const args = buildLoaderArgs(request, match.params, routeContext);
+
+  // ── beforeLoad ────────────────────────────────────────────────────────
+  const beforeLoadResponse = await runBeforeLoad(chain.route, args);
+  if (beforeLoadResponse) return beforeLoadResponse;
 
   // ── Action (mutating methods) ─────────────────────────────────────────
   let actionData: unknown = null;
   if (MUTATING_METHODS.has(request.method)) {
+    if (!isAllowedMutation(request)) return error("Forbidden", 403);
+    // Reject up front if the client advertises an oversized body.
+    const clRaw = request.headers.get("Content-Length");
+    if (clRaw) {
+      const cl = Number(clRaw);
+      if (Number.isFinite(cl) && cl > MAX_FORM_BYTES) {
+        return error("Payload Too Large", 413);
+      }
+    }
     try {
-      const formData = await request.formData();
+      const ct = request.headers.get("Content-Type") ?? "";
+      const isFormLike = ct.includes("multipart/form-data") || ct.includes("application/x-www-form-urlencoded");
+      const formData = isFormLike ? await request.formData() : new FormData();
       actionData = await runAction(chain.route, { ...args, formData });
     } catch (err) {
       if (isRedirect(err)) return err as Response;
-      throw err;
+      if (isHttpError(err)) return error(err.message, err.status);
+      if (isExplicitDev()) return error(err instanceof Error ? err.message : String(err), 500);
+      return error("Internal Server Error", 500);
     }
 
     // Client-side Form submits with this header — return JSON, not HTML.
@@ -97,7 +154,9 @@ async function route(
     loaderResults = await runLoaders(chain, args);
   } catch (err) {
     if (isRedirect(err)) return err as Response;
-    throw err;
+    if (isHttpError(err)) return error(err.message, err.status);
+    if (isExplicitDev()) return error(err instanceof Error ? err.message : String(err), 500);
+    return error("Internal Server Error", 500);
   }
 
   const loaderData = {

package/src/server/response.ts

@@ -1,8 +1,32 @@
-export function redirect(url: string, status: number = 302): Response {
-  return new Response(null, {
-    status,
-    headers: { Location: url },
-  });
+export interface RedirectOptions {
+  /** Allow absolute URLs to other origins. Default false. */
+  allowExternal?: boolean;
+}
+
+function isSafeInternalRedirect(url: string): boolean {
+  // Must be path-only: single leading "/" not followed by "/" or "\".
+  // Rejects: "//evil.com", "/\\evil.com", "https://...", "javascript:...", "".
+  if (url.length === 0) return false;
+  if (url[0] !== "/") return false;
+  if (url[1] === "/" || url[1] === "\\") return false;
+  return true;
+}
+
+export function redirect(
+  url: string,
+  status: number = 302,
+  headers?: HeadersInit,
+  options?: RedirectOptions,
+): Response {
+  if (!options?.allowExternal && !isSafeInternalRedirect(url)) {
+    throw new Error(
+      `[bractjs] redirect: unsafe Location "${url}". ` +
+        `Pass { allowExternal: true } to redirect off-origin.`,
+    );
+  }
+  const h = new Headers(headers);
+  h.set("Location", url);
+  return new Response(null, { status, headers: h });
 }
 
 export function json<T>(data: T, init?: ResponseInit): Response {

package/src/server/scanner.ts

@@ -1,3 +1,5 @@
+import { basename } from "node:path";
+
 // ── Types ──────────────────────────────────────────────────────────────────
 
 export type Segment = string | { param: string } | { catchAll: string };
@@ -54,8 +56,10 @@ export async function scanRoutes(appDir: string): Promise<RouteFile[]> {
   const routes: RouteFile[] = [];
 
   for await (const filePath of glob.scan(appDir)) {
-    // Skip layout files — handled separately
-    if (filePath.endsWith("/layout.tsx") || filePath.endsWith("/layout.ts")) {
+    // Skip layout files — handled separately. Use basename so this also
+    // skips top-level "routes/layout.tsx" on any OS.
+    const base = basename(filePath);
+    if (base === "layout.tsx" || base === "layout.ts") {
       continue;
     }