@bractjs/bractjs 0.1.5 → 0.1.7

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

@@ -1,4 +1,7 @@
-import { resolve, join } from "node:path";
+import { resolve, join, sep } from "node:path";
+import { realpath } from "node:fs/promises";
+import { serverOnlyPlugin } from "../build/env-plugin.ts";
+import { useServerProxyPlugin } from "../build/directives.ts";
 
 /**
  * Dev-only HTTP handler for /_hmr/module?file=routes/about.tsx
@@ -17,19 +20,42 @@ export async function handleHmrModuleRequest(
     return new Response("Missing file param", { status: 400 });
   }
 
-  // Resolve and guard against path traversal
+  // SECURITY(high): restrict to JS/TS source files. Without this, /_hmr/module
+  // would build and ship the contents of any file inside appDir (e.g. .env,
+  // .json, .md) as JavaScript to the browser — useful only for compiling
+  // route modules, so allowlist their extensions.
+  if (!/\.(tsx?|jsx?)$/.test(file)) {
+    return new Response("Forbidden", { status: 403 });
+  }
+
+  // Resolve and guard against path traversal AND symlink escape.
   const rootDir = resolve(appDir);
-  const fullPath = resolve(join(rootDir, file));
-  if (!fullPath.startsWith(rootDir + "/") && fullPath !== rootDir) {
+  const candidate = resolve(join(rootDir, file));
+  if (!candidate.startsWith(rootDir + sep) && candidate !== rootDir) {
+    return new Response("Forbidden", { status: 403 });
+  }
+  let fullPath: string;
+  try {
+    fullPath = await realpath(candidate);
+  } catch {
+    return new Response("Not Found", { status: 404 });
+  }
+  if (!fullPath.startsWith(rootDir + sep) && fullPath !== rootDir) {
     return new Response("Forbidden", { status: 403 });
   }
 
-  // Build in-memory (no outdir → outputs held in memory, no disk write)
+  // SECURITY(high): apply the same client-bundle guard plugins the production
+  // build uses. Without these, a route module that imports `*.server.ts` or
+  // contains "use server" exports would have that server source compiled and
+  // shipped to the browser as JavaScript over /_hmr/module — leaking
+  // credentials, DB code, etc. The serverOnlyPlugin hard-fails such imports
+  // and useServerProxyPlugin rewrites "use server" exports to fetch stubs.
   const result = await Bun.build({
     entrypoints: [fullPath],
     target: "browser",
     minify: false,
     sourcemap: "inline",
+    plugins: [serverOnlyPlugin, useServerProxyPlugin],
   });
 
   if (!result.success || result.outputs.length === 0) {

package/src/dev/hmr-server.ts

@@ -18,6 +18,22 @@ export function createHmrServer(port = 3001): {
   const server = Bun.serve({
     port,
     fetch(req, srv) {
+      // SECURITY(medium): reject WebSocket upgrades that don't come from a
+      // loopback Origin. Without this, any website the developer visits could
+      // open a WS to ws://localhost:<port> and receive file paths from HMR
+      // broadcasts (a passive leak of project structure). Same-origin /
+      // missing Origin (curl, native ws clients) are allowed for dev DX.
+      const origin = req.headers.get("Origin");
+      if (origin) {
+        try {
+          const host = new URL(origin).hostname;
+          if (host !== "localhost" && host !== "127.0.0.1" && host !== "[::1]" && host !== "::1") {
+            return new Response("Forbidden", { status: 403 });
+          }
+        } catch {
+          return new Response("Forbidden", { status: 403 });
+        }
+      }
       if (srv.upgrade(req)) return undefined;
       return new Response("HMR WebSocket endpoint", { status: 426 });
     },

package/src/image/cache.ts

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { mkdir } from "node:fs/promises";
+import { mkdir, rename, unlink } from "node:fs/promises";
 import type { ImageTransformParams, TransformResult, ImageFormat } from "./types.ts";
 
 const MAX_MEM = 200;
@@ -50,10 +50,14 @@ export async function getFromDisk(
   const key = await cacheKey(src, params);
   const metaFile = Bun.file(join(dir, `${key}.json`));
   const dataFile = Bun.file(join(dir, `${key}.bin`));
-  if (!(await metaFile.exists()) || !(await dataFile.exists())) return null;
+  // No existence pre-check: it would create a TOCTOU race where the file is
+  // deleted between exists() and read(). Just attempt the reads and let either
+  // a missing file or invalid JSON fall through to MISS.
   try {
-    const meta = await metaFile.json() as { contentType: string; format: ImageFormat };
-    const data = await dataFile.arrayBuffer();
+    const [meta, data] = await Promise.all([
+      metaFile.json() as Promise<{ contentType: string; format: ImageFormat }>,
+      dataFile.arrayBuffer(),
+    ]);
     return { data, contentType: meta.contentType, format: meta.format };
   } catch {
     return null;
@@ -68,8 +72,24 @@ export async function setOnDisk(
 ): Promise<void> {
   await mkdir(dir, { recursive: true });
   const key = await cacheKey(src, params);
-  await Promise.all([
-    Bun.write(join(dir, `${key}.json`), JSON.stringify({ contentType: result.contentType, format: result.format })),
-    Bun.write(join(dir, `${key}.bin`), result.data),
-  ]);
+  const jsonFinal = join(dir, `${key}.json`);
+  const binFinal = join(dir, `${key}.bin`);
+  const jsonTmp = `${jsonFinal}.tmp`;
+  const binTmp = `${binFinal}.tmp`;
+  // Write both temp files, then atomically rename. Readers see either both
+  // files present or neither — never a half-written pair.
+  try {
+    await Promise.all([
+      Bun.write(jsonTmp, JSON.stringify({ contentType: result.contentType, format: result.format })),
+      Bun.write(binTmp, result.data),
+    ]);
+    await Promise.all([rename(jsonTmp, jsonFinal), rename(binTmp, binFinal)]);
+  } catch (err) {
+    // Best-effort cleanup so failed writes don't leak .tmp files indefinitely.
+    await Promise.all([
+      unlink(jsonTmp).catch(() => {}),
+      unlink(binTmp).catch(() => {}),
+    ]);
+    throw err;
+  }
 }

package/src/image/handler.ts

@@ -1,36 +1,54 @@
-import { join, resolve } from "node:path";
+import { join, resolve, sep } from "node:path";
+import { realpath } from "node:fs/promises";
 import type { ImageTransformParams, ImageFormat, ImageFit } from "./types.ts";
-import { QUALITY_DEFAULT, FORMAT_DEFAULT, FIT_DEFAULT, MIME } from "./types.ts";
+import { QUALITY_DEFAULT, FORMAT_DEFAULT, FIT_DEFAULT, MIME, ALLOWED_FITS } from "./types.ts";
 import { transformImage } from "./optimizer.ts";
 import { getFromMemory, setInMemory, getFromDisk, setOnDisk } from "./cache.ts";
 
-const MAX_DIM = 4096;
+const ALLOWED_DIMS = new Set([320, 640, 768, 1024, 1280, 1536, 1920, 3840]);
+const MAX_AREA = 4_000_000;
 const CACHE_CTRL = "public, max-age=31536000, immutable";
 
-function parseParams(
+async function parseParams(
   sp: URLSearchParams,
   publicDir: string,
-): { src: string; filePath: string; params: ImageTransformParams } | null {
+): Promise<{ src: string; filePath: string; params: ImageTransformParams } | null> {
   const src = sp.get("src");
-  // src must be a /public/ path with no traversal sequences
-  if (!src || !src.startsWith("/public/") || src.includes("..")) return null;
+  // src must be a /public/ path with no ".." path segment. We check segments
+  // (not substring) so filenames like "foo..bar.jpg" are still allowed —
+  // realpath()/prefix check below is the authoritative escape guard.
+  if (!src || !src.startsWith("/public/")) return null;
+  if (src.split("/").includes("..")) return null;
 
   const rel = src.slice("/public/".length);
   const root = resolve(publicDir);
-  const filePath = resolve(join(root, rel));
-  if (!filePath.startsWith(root + "/") && filePath !== root) return null;
+  const candidate = resolve(join(root, rel));
+  if (!candidate.startsWith(root + sep) && candidate !== root) return null;
+  // Re-check after symlink resolution. If the file doesn't exist yet, realpath
+  // throws — fall through and let the existence check below handle it.
+  let filePath = candidate;
+  try {
+    const real = await realpath(candidate);
+    if (!real.startsWith(root + sep) && real !== root) return null;
+    filePath = real;
+  } catch {
+    // missing file: defer to Bun.file(...).exists() below
+  }
 
   const wRaw = sp.get("w");
   const hRaw = sp.get("h");
   const w = wRaw ? parseInt(wRaw, 10) : undefined;
   const h = hRaw ? parseInt(hRaw, 10) : undefined;
-  if (w !== undefined && (isNaN(w) || w < 1 || w > MAX_DIM)) return null;
-  if (h !== undefined && (isNaN(h) || h < 1 || h > MAX_DIM)) return null;
+  if (w !== undefined && (isNaN(w) || !ALLOWED_DIMS.has(w))) return null;
+  if (h !== undefined && (isNaN(h) || !ALLOWED_DIMS.has(h))) return null;
+  if (w !== undefined && h !== undefined && w * h > MAX_AREA) return null;
 
   const q = Math.min(100, Math.max(1, parseInt(sp.get("q") ?? String(QUALITY_DEFAULT), 10)));
   const fmt = (sp.get("format") ?? FORMAT_DEFAULT) as ImageFormat;
-  const fit = (sp.get("fit") ?? FIT_DEFAULT) as ImageFit;
+  const fitRaw = sp.get("fit") ?? FIT_DEFAULT;
   if (!MIME[fmt]) return null;
+  if (!ALLOWED_FITS.has(fitRaw as ImageFit)) return null;
+  const fit = fitRaw as ImageFit;
 
   return { src, filePath, params: { w, h, q, format: fmt, fit } };
 }
@@ -53,7 +71,7 @@ export async function handleImageRequest(
   const url = new URL(request.url);
   if (url.pathname !== "/_image") return null;
 
-  const parsed = parseParams(url.searchParams, publicDir);
+  const parsed = await parseParams(url.searchParams, publicDir);
   if (!parsed) return new Response("Bad Request", { status: 400 });
 
   const { src, filePath, params } = parsed;

package/src/image/optimizer.ts

@@ -1,6 +1,30 @@
 import type { ImageTransformParams, TransformResult, ImageFormat } from "./types.ts";
 import { MIME } from "./types.ts";
 
+// In-process semaphore (DoS guard): cap concurrent ImageMagick spawns so a
+// burst of /_image requests can't fork-bomb the server.
+const MAX_CONCURRENT = 4;
+// Per-spawn timeout (ms). A pathological input must not hold a slot forever;
+// without this, four hung spawns wedge the whole image pipeline.
+const SPAWN_TIMEOUT_MS = 15_000;
+let inFlight = 0;
+const waiters: Array<() => void> = [];
+
+async function acquireSlot(): Promise<void> {
+  if (inFlight < MAX_CONCURRENT) {
+    inFlight++;
+    return;
+  }
+  await new Promise<void>((resolve) => waiters.push(resolve));
+  inFlight++;
+}
+
+function releaseSlot(): void {
+  inFlight--;
+  const next = waiters.shift();
+  if (next) next();
+}
+
 // Probe for an available ImageMagick binary once, then cache the result.
 let _binary: string | null | undefined;
 
@@ -33,9 +57,14 @@ function resizeArgs(params: ImageTransformParams): string[] {
 
 function buildArgs(binary: string, input: string, params: ImageTransformParams): string[] {
   const base = binary === "magick" ? ["magick", "convert"] : ["convert"];
+  // SECURITY(low): prefix the input with `file:` so ImageMagick treats it as
+  // a filesystem path even if it contains a coder prefix like `mvg:` or
+  // `https:` (e.g. an attacker who plants a file named "https:evil.txt"
+  // inside publicDir). Defense in depth — realpath() already constrains the
+  // path to publicDir, so this prevents the "format coder hijack" class only.
   return [
     ...base,
-    input,
+    `file:${input}`,
     ...resizeArgs(params),
     "-quality", String(params.q),
     "-strip",
@@ -57,20 +86,28 @@ export async function transformImage(
     return { data, contentType: MIME[fmt] ?? "image/jpeg", format: fmt };
   }
 
-  const proc = Bun.spawn(buildArgs(binary, filePath, params), {
-    stdout: "pipe",
-    stderr: "pipe",
-  });
+  await acquireSlot();
+  try {
+    const proc = Bun.spawn(buildArgs(binary, filePath, params), {
+      stdout: "pipe",
+      stderr: "ignore",
+      timeout: SPAWN_TIMEOUT_MS,
+      killSignal: "SIGKILL",
+    });
 
-  const [data, , exitCode] = await Promise.all([
-    new Response(proc.stdout!).arrayBuffer(),
-    new Response(proc.stderr!).arrayBuffer(),
-    proc.exited,
-  ]);
+    const [data, exitCode] = await Promise.all([
+      new Response(proc.stdout!).arrayBuffer(),
+      proc.exited,
+    ]);
 
-  if (exitCode !== 0) {
-    throw new Error(`[bractjs] ImageMagick exited ${exitCode} for ${filePath}`);
-  }
+    if (exitCode !== 0) {
+      // Non-zero exit covers normal failures AND timeout-induced SIGKILL,
+      // since Bun reports the signal as a non-zero exit code.
+      throw new Error(`[bractjs] ImageMagick exited ${exitCode} for ${filePath}`);
+    }
 
-  return { data, contentType: MIME[params.format], format: params.format };
+    return { data, contentType: MIME[params.format], format: params.format };
+  } finally {
+    releaseSlot();
+  }
 }

package/src/image/types.ts

@@ -25,3 +25,4 @@ export const MIME: Record<ImageFormat, string> = {
   jpeg: "image/jpeg",
   png:  "image/png",
 };
+export const ALLOWED_FITS: ReadonlySet<ImageFit> = new Set(["cover", "contain", "fill"]);

package/src/index.ts

@@ -1,5 +1,23 @@
 // Server
 export { createServer, renderRoute, redirect, json, error } from "./server/index.ts";
+export { buildFetchHandler } from "./server/serve.ts";
+export { defineContext } from "./server/context.ts";
+export type { ContextFactory } from "./server/context.ts";
+export { route } from "./server/api-route.ts";
+export type { ApiRouteDefinition, AppApiRoutes } from "./server/api-route.ts";
+export { validate } from "./server/validate.ts";
+export type { FieldErrors, ValidationError } from "./server/validate.ts";
+export type { BractAdapter } from "./server/adapter.ts";
+export { BunAdapter } from "./server/adapter.ts";
+
+// Adapters
+export { createCloudflareAdapter, makeCloudflareHandler } from "./adapters/cloudflare.ts";
+
+// Build plugins
+export { cssModulesPlugin, transformCssModule } from "./build/plugins/css-modules.ts";
+
+// Client RPC
+export { createClient } from "./client/rpc.ts";
 export type { BractJSConfig, RenderOptions, ServerManifest } from "./server/index.ts";
 
 // Shared types
@@ -49,3 +67,12 @@ export { useActionData } from "./client/hooks/useActionData.ts";
 export { useParams } from "./client/hooks/useParams.ts";
 export { useNavigation } from "./client/hooks/useNavigation.ts";
 export { useFetcher } from "./client/hooks/useFetcher.ts";
+export { useSearchParams } from "./client/hooks/useSearchParams.ts";
+export type { SearchParamsResult } from "./client/hooks/useSearchParams.ts";
+export { useBlocker } from "./client/hooks/useBlocker.ts";
+export { useLocale } from "./client/hooks/useLocale.ts";
+export { useLocalizedLink } from "./client/hooks/useLocalizedLink.ts";
+
+// i18n utilities (server-side)
+export { wrapRoutesWithLocale, stripLocale, localizedDataPath } from "./server/i18n.ts";
+export type { I18nConfig } from "./server/serve.ts";

package/src/middleware/cors.ts

@@ -3,25 +3,43 @@ import type { MiddlewareFn } from "../server/middleware.ts";
 export interface CorsOptions {
   origin: string | string[];
   methods?: string[];
+  credentials?: boolean;
 }
 
 /**
  * Sets CORS headers. Handles OPTIONS preflight with 204.
+ *
+ * Never reflects the Origin header when "*" is configured — emits literal "*".
+ * Refuses to combine credentials:true with "*" (browsers reject it anyway).
+ * Always sets `Vary: Origin` so caches don't serve a cross-origin response to
+ * the wrong site.
  */
 export function cors(options: CorsOptions): MiddlewareFn {
-  const allowedOrigins = Array.isArray(options.origin)
-    ? options.origin
-    : [options.origin];
+  const allowedOrigins = Array.isArray(options.origin) ? options.origin : [options.origin];
   const allowedMethods = options.methods?.join(", ") ?? "GET, POST, PUT, DELETE, PATCH, OPTIONS";
+  const wildcard = allowedOrigins.includes("*");
+  const credentials = options.credentials === true;
+  if (wildcard && credentials) {
+    throw new Error("cors: credentials=true cannot be combined with origin='*'");
+  }
 
   return async (ctx, next) => {
     const origin = ctx.request.headers.get("Origin") ?? "";
-    const allowed = allowedOrigins.includes("*") || allowedOrigins.includes(origin);
+    // SECURITY(high): Access-Control-Allow-Headers MUST NOT list
+    // `X-BractJS-Action`. That header is the CSRF gate in csrf.ts — its
+    // protection relies on browsers blocking non-allowlisted custom headers
+    // cross-origin. Adding it here would let any origin forge mutations.
     const corsHeaders: Record<string, string> = {
       "Access-Control-Allow-Methods": allowedMethods,
       "Access-Control-Allow-Headers": "Content-Type, Authorization",
+      "Vary": "Origin",
     };
-    if (allowed) corsHeaders["Access-Control-Allow-Origin"] = origin || "*";
+    if (wildcard) {
+      corsHeaders["Access-Control-Allow-Origin"] = "*";
+    } else if (origin && allowedOrigins.includes(origin)) {
+      corsHeaders["Access-Control-Allow-Origin"] = origin;
+    }
+    if (credentials) corsHeaders["Access-Control-Allow-Credentials"] = "true";
 
     // Preflight
     if (ctx.request.method === "OPTIONS") {
@@ -29,8 +47,10 @@ export function cors(options: CorsOptions): MiddlewareFn {
     }
 
     const response = await next();
-    const patched = new Response(response.body, response);
-    for (const [k, v] of Object.entries(corsHeaders)) patched.headers.set(k, v);
-    return patched;
+    // Mutate headers in place rather than wrapping body. Wrapping with
+    // `new Response(response.body, response)` makes the original Response
+    // unusable to anyone holding a reference (single-shot stream).
+    for (const [k, v] of Object.entries(corsHeaders)) response.headers.set(k, v);
+    return response;
   };
 }

package/src/middleware/requestLogger.ts

@@ -3,6 +3,10 @@ import type { MiddlewareFn } from "../server/middleware.ts";
 /**
  * Logs "[METHOD] /path → status in Xms" for every request.
  */
+// SECURITY(medium): only the pathname is logged — query string is intentionally
+// omitted because it may carry tokens (e.g. password-reset links, OAuth codes,
+// signed share URLs). Do not extend this to log searchParams without a redaction
+// allowlist.
 export function requestLogger(): MiddlewareFn {
   return async (ctx, next) => {
     const start = Date.now();

package/src/server/action-handler.ts

@@ -1,10 +1,29 @@
 import { resolveAction } from "./action-registry.ts";
 import { json } from "./response.ts";
+import { isAllowedMutation } from "./csrf.ts";
+
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+// Cap action JSON bodies. Anything over this looks like an abuse attempt;
+// FormData uploads (large files) take the multipart branch and bypass this.
+const MAX_JSON_BODY_BYTES = 1_048_576; // 1 MiB
+
+// Deep scan: nested objects can carry __proto__ pollution vectors too.
+function hasForbiddenKey(value: unknown, depth = 0): boolean {
+  if (depth > 20 || !value || typeof value !== "object") return false;
+  for (const key of Object.keys(value as Record<string, unknown>)) {
+    if (FORBIDDEN_KEYS.has(key)) return true;
+    if (hasForbiddenKey((value as Record<string, unknown>)[key], depth + 1)) return true;
+  }
+  return false;
+}
 
 export async function handleActionRequest(request: Request): Promise<Response | null> {
   const url = new URL(request.url);
-  if (!url.pathname.startsWith("/_action")) return null;
+  // SECURITY(medium): exact-match prevents URL confusion (e.g. "/_actionfoo"
+  // would otherwise also reach this handler).
+  if (url.pathname !== "/_action") return null;
   if (request.method !== "POST") return new Response("Method Not Allowed", { status: 405 });
+  if (!isAllowedMutation(request)) return new Response("Forbidden", { status: 403 });
 
   const id = url.searchParams.get("id");
   if (!id) return new Response("Bad Request: missing action id", { status: 400 });
@@ -18,8 +37,32 @@ export async function handleActionRequest(request: Request): Promise<Response |
     if (ct.includes("multipart/form-data") || ct.includes("application/x-www-form-urlencoded")) {
       args = [await request.formData()];
     } else {
+      // Cheap pre-check: trust Content-Length if the client sent one.
+      const clRaw = request.headers.get("Content-Length");
+      if (clRaw) {
+        const cl = Number(clRaw);
+        if (Number.isFinite(cl) && cl > MAX_JSON_BODY_BYTES) {
+          return new Response("Payload Too Large", { status: 413 });
+        }
+      }
       const text = await request.text();
-      args = text ? JSON.parse(text) as unknown[] : [];
+      // Defense in depth: clients can lie about Content-Length, so verify the
+      // actual decoded text length too.
+      if (text.length > MAX_JSON_BODY_BYTES) {
+        return new Response("Payload Too Large", { status: 413 });
+      }
+      if (!text) {
+        args = [];
+      } else {
+        const parsed: unknown = JSON.parse(text);
+        if (!Array.isArray(parsed)) {
+          return new Response("Bad Request: args must be array", { status: 400 });
+        }
+        if (parsed.some((v) => hasForbiddenKey(v))) {
+          return new Response("Bad Request: forbidden keys", { status: 400 });
+        }
+        args = parsed;
+      }
     }
   } catch {
     return new Response("Bad Request: invalid body", { status: 400 });

package/src/server/action-registry.ts

@@ -1,6 +1,9 @@
 import { join } from "node:path";
 
-const SERVER_RE = /^["']use server["']/m;
+// Anchored at start-of-file. Allow whitespace and line/block comments before
+// the "use server" string literal. This prevents false matches from a "use
+// server" found inside template literals or runtime strings.
+const SERVER_RE = /^(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*["']use server["']/;
 const registry = new Map<string, (...args: unknown[]) => Promise<unknown>>();
 
 async function computeId(filePath: string, name: string): Promise<string> {
@@ -16,9 +19,19 @@ export function resolveAction(id: string): ((...args: unknown[]) => Promise<unkn
   return registry.get(id) ?? null;
 }
 
+function isEligible(rel: string): boolean {
+  return (
+    rel.endsWith(".server.ts") ||
+    rel.endsWith(".server.tsx") ||
+    rel.startsWith("routes/") ||
+    rel.startsWith("routes\\")
+  );
+}
+
 export async function loadServerActions(appDir: string): Promise<void> {
   const glob = new Bun.Glob("**/*.{ts,tsx}");
   for await (const rel of glob.scan(appDir)) {
+    if (!isEligible(rel)) continue;
     const filePath = join(appDir, rel);
     let src: string;
     try { src = await Bun.file(filePath).text(); } catch { continue; }

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