@bractjs/bractjs 0.1.6 → 0.1.7

package/src/server/adapter.ts

@@ -0,0 +1,57 @@
+// ── BractAdapter ──────────────────────────────────────────────────────────
+
+/**
+ * Minimal interface that adapters must implement.
+ *
+ * `fetch` is the standard WinterCG-compatible fetch handler — it receives a
+ * Request and returns a Response.  The server core calls this for every
+ * incoming HTTP request after routing special endpoints.
+ *
+ * `listen` starts the adapter's underlying server on the given port.
+ * It is optional for environments that do not control port binding (e.g.
+ * Cloudflare Workers).
+ */
+export interface BractAdapter {
+  fetch(request: Request): Promise<Response>;
+  listen?(port: number): void;
+}
+
+// ── BunAdapter ────────────────────────────────────────────────────────────
+
+/**
+ * Default adapter — wraps `Bun.serve()`.
+ * Created internally by `createServer()` when no adapter is provided.
+ */
+export class BunAdapter implements BractAdapter {
+  private server: ReturnType<typeof Bun.serve> | null = null;
+  private handler: ((request: Request) => Promise<Response>) | null = null;
+
+  setHandler(handler: (request: Request) => Promise<Response>): void {
+    this.handler = handler;
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    if (!this.handler) throw new Error("BunAdapter: handler not set");
+    return this.handler(request);
+  }
+
+  listen(port: number): void {
+    if (!this.handler) throw new Error("BunAdapter: handler not set before listen()");
+    const handler = this.handler;
+    this.server = Bun.serve({
+      port,
+      fetch: handler,
+      error(err: Error) {
+        console.error("[bractjs] unhandled server error:", err);
+        return new Response(JSON.stringify({ error: err.message }), {
+          status: 500,
+          headers: { "Content-Type": "application/json; charset=utf-8" },
+        });
+      },
+    });
+  }
+
+  stop(): void {
+    this.server?.stop();
+  }
+}

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

@@ -4,6 +4,7 @@
  * 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");

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) {

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/render.ts

@@ -62,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

@@ -2,12 +2,12 @@ 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, isHttpError } from "../shared/errors.ts";
-import { isDev } from "./env.ts";
+import { isExplicitDev } from "./env.ts";
 import { pipeline, type MiddlewareContext } from "./middleware.ts";
 import { BractJSProvider } from "../shared/context.ts";
 import { isAllowedMutation } from "./csrf.ts";
@@ -20,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,
@@ -45,17 +50,51 @@ async function route(
   const { pathname, searchParams } = url;
 
   // ── /_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 });
     }
@@ -66,12 +105,31 @@ 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 ct = request.headers.get("Content-Type") ?? "";
       const isFormLike = ct.includes("multipart/form-data") || ct.includes("application/x-www-form-urlencoded");
@@ -80,7 +138,7 @@ async function route(
     } catch (err) {
       if (isRedirect(err)) return err as Response;
       if (isHttpError(err)) return error(err.message, err.status);
-      if (isDev()) return error(err instanceof Error ? err.message : String(err), 500);
+      if (isExplicitDev()) return error(err instanceof Error ? err.message : String(err), 500);
       return error("Internal Server Error", 500);
     }
 
@@ -97,7 +155,7 @@ async function route(
   } catch (err) {
     if (isRedirect(err)) return err as Response;
     if (isHttpError(err)) return error(err.message, err.status);
-    if (isDev()) return error(err instanceof Error ? err.message : String(err), 500);
+    if (isExplicitDev()) return error(err instanceof Error ? err.message : String(err), 500);
     return error("Internal Server Error", 500);
   }