@bractjs/bractjs 0.1.28 → 0.1.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "Production-grade SSR framework for Bun + React 19. File-based routing, streaming SSR, server actions, typed routes.",
   "license": "MIT",
   "homepage": "https://github.com/bractjs/bractjs#readme",
@@ -45,7 +45,8 @@
   "scripts": {
     "dev": "bun run src/dev/server.ts",
     "build": "bun run src/build/bundler.ts",
-    "test": "bun test"
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
   },
   "peerDependencies": {
     "react": "^19",

package/src/__tests__/fixtures/app/routes/features-demo.tsx

@@ -0,0 +1,28 @@
+// Fixture exercising the Phase 1/2/4 route exports end-to-end:
+//   - `headers`  → Cache-Control on the document + /_data response
+//   - `handle`   → surfaced via useMatches() (asserted from the payload)
+//   - `middleware` → sets context (read by the loader) and stamps a header
+import type { RouteMiddlewareFunction, HeadersArgs } from "../../../../shared/route-types.ts";
+
+const setUser: RouteMiddlewareFunction = async (ctx, next) => {
+  ctx.context.demoUser = "alice";
+  const res = await next();
+  res.headers.set("X-Demo-Mw", "1");
+  return res;
+};
+
+export const middleware = [setUser];
+
+export const handle = { breadcrumb: "Features" };
+
+export function loader({ context }: { context: Record<string, unknown> }) {
+  return { user: context.demoUser ?? null };
+}
+
+export function headers(_args: HeadersArgs) {
+  return { "Cache-Control": "public, max-age=120" };
+}
+
+export default function FeaturesDemo() {
+  return <p>features</p>;
+}

package/src/__tests__/headers.test.ts

@@ -0,0 +1,111 @@
+import { test, expect, describe } from "bun:test";
+import { resolveHeaders, applyRouteHeaders } from "../server/headers.ts";
+import type { LayoutChain } from "../server/layout.ts";
+import type { LoaderResults } from "../server/loader.ts";
+import type { HeadersFunction } from "../shared/route-types.ts";
+
+const params = {};
+const req = new Request("http://localhost/");
+
+function chain(parts: {
+  root?: HeadersFunction;
+  layouts?: (HeadersFunction | undefined)[];
+  route?: HeadersFunction;
+}): LayoutChain {
+  return {
+    root: parts.root ? { headers: parts.root } : {},
+    layouts: (parts.layouts ?? []).map((h) => (h ? { headers: h } : {})),
+    route: parts.route ? { headers: parts.route } : {},
+  };
+}
+
+function results(over: Partial<LoaderResults> = {}): LoaderResults {
+  return { root: null, layouts: [], route: null, ...over };
+}
+
+describe("resolveHeaders", () => {
+  test("returns null when no module exports headers", () => {
+    expect(resolveHeaders(chain({}), results(), params, req)).toBeNull();
+  });
+
+  test("collects a single route's headers", () => {
+    const merged = resolveHeaders(
+      chain({ route: () => ({ "Cache-Control": "max-age=60" }) }),
+      results(),
+      params,
+      req,
+    );
+    expect(merged?.get("Cache-Control")).toBe("max-age=60");
+  });
+
+  test("innermost route wins per key (route over root)", () => {
+    const merged = resolveHeaders(
+      chain({
+        root: () => ({ "Cache-Control": "max-age=0", Vary: "Cookie" }),
+        route: () => ({ "Cache-Control": "max-age=300" }),
+      }),
+      results(),
+      params,
+      req,
+    );
+    expect(merged?.get("Cache-Control")).toBe("max-age=300");
+    // Root-only key survives.
+    expect(merged?.get("Vary")).toBe("Cookie");
+  });
+
+  test("parentHeaders carries accumulated values to inner links", () => {
+    let seen: string | null = "unset";
+    const merged = resolveHeaders(
+      chain({
+        root: () => ({ "X-From-Root": "1" }),
+        route: ({ parentHeaders }) => {
+          seen = parentHeaders.get("X-From-Root");
+          return {};
+        },
+      }),
+      results(),
+      params,
+      req,
+    );
+    expect(seen).toBe("1");
+    expect(merged?.get("X-From-Root")).toBe("1");
+  });
+
+  test("passes the matching loaderData slice to each link", () => {
+    const merged = resolveHeaders(
+      chain({ route: ({ loaderData }) => ({ ETag: String((loaderData as { etag: string }).etag) }) }),
+      results({ route: { etag: "abc" } }),
+      params,
+      req,
+    );
+    expect(merged?.get("ETag")).toBe("abc");
+  });
+
+  test("layout headers merge between root and route", () => {
+    const merged = resolveHeaders(
+      chain({
+        root: () => ({ "Cache-Control": "max-age=0" }),
+        layouts: [() => ({ "Cache-Control": "max-age=10", Vary: "Accept" })],
+        route: () => ({ "Cache-Control": "max-age=60" }),
+      }),
+      results({ layouts: [null] }),
+      params,
+      req,
+    );
+    expect(merged?.get("Cache-Control")).toBe("max-age=60");
+    expect(merged?.get("Vary")).toBe("Accept");
+  });
+});
+
+describe("applyRouteHeaders", () => {
+  test("overrides same-key defaults and is a no-op for null", () => {
+    const base = new Headers({ "Cache-Control": "no-store", "X-Base": "1" });
+    applyRouteHeaders(base, new Headers({ "Cache-Control": "max-age=60" }));
+    expect(base.get("Cache-Control")).toBe("max-age=60");
+    expect(base.get("X-Base")).toBe("1");
+
+    const base2 = new Headers({ "X-Base": "1" });
+    applyRouteHeaders(base2, null);
+    expect(base2.get("X-Base")).toBe("1");
+  });
+});

package/src/__tests__/integration.test.ts

@@ -182,3 +182,37 @@ test("/_data of a beforeLoad-gated route is blocked and never leaks loader data"
   const body = await res.text();
   expect(body).not.toContain("TOP-SECRET-LOADER-DATA");
 });
+
+// ── Route headers / useMatches / nested middleware (Phases 1, 2, 4) ──────────
+
+test("route `headers` export sets Cache-Control on the document response", async () => {
+  const res = await fetch(`${BASE}/features-demo`);
+  expect(res.status).toBe(200);
+  expect(res.headers.get("Cache-Control")).toBe("public, max-age=120");
+  // Baseline hardening headers still present (not clobbered).
+  expect(res.headers.get("X-Content-Type-Options")).toBe("nosniff");
+});
+
+test("route `headers` export also applies to the /_data response", async () => {
+  const res = await fetch(`${BASE}/_data?path=/features-demo`);
+  expect(res.status).toBe(200);
+  expect(res.headers.get("Cache-Control")).toBe("public, max-age=120");
+  expect(res.headers.get("content-type")).toContain("application/json");
+});
+
+test("nested middleware runs (sets context read by the loader, stamps a header)", async () => {
+  const res = await fetch(`${BASE}/_data?path=/features-demo`);
+  expect(res.headers.get("X-Demo-Mw")).toBe("1");
+  const data = (await res.json()) as { route?: { user?: string } };
+  // The loader saw the context value the middleware set.
+  expect(data.route?.user).toBe("alice");
+});
+
+test("/_data payload carries the matched chain (useMatches) with handle", async () => {
+  const res = await fetch(`${BASE}/_data?path=/features-demo`);
+  const data = (await res.json()) as { matches?: Array<{ id: string; handle?: { breadcrumb?: string } }> };
+  expect(Array.isArray(data.matches)).toBe(true);
+  // Leaf route carries its handle export.
+  const leaf = data.matches!.at(-1)!;
+  expect(leaf.handle?.breadcrumb).toBe("Features");
+});

package/src/__tests__/layout-registry.test.ts

@@ -58,13 +58,17 @@ describe("resolveLayoutChainFromRegistry", () => {
     expect(r.layoutFiles).toEqual([]);
   });
 
-  test("matches sibling-dir layouts only when route is deeper", () => {
-    // urlPattern "blog" → layoutDirs returns [] (no ancestor)
+  test("wraps a folder index in that folder's layout", () => {
+    // routes/blog/_index.tsx (URL /blog) lives inside routes/blog/, so the
+    // sibling routes/blog/layout.tsx wraps it — matching Remix/RR/Next, where
+    // an index is nested under its directory's layout. Layout dirs are derived
+    // from the FILE path, so the `_index` → `blog` urlPattern collapse no
+    // longer hides the ancestor directory.
     const r = resolveLayoutChainFromRegistry(
       { filePath: "routes/blog/_index.tsx", urlPattern: "blog", segments: ["blog"] },
       registry,
     );
-    expect(r.layoutFiles).toEqual(["root.tsx"]);
+    expect(r.layoutFiles).toEqual(["root.tsx", "routes/blog/layout.tsx"]);
   });
 });
 

package/src/__tests__/matcher.test.ts

@@ -67,3 +67,32 @@ describe("matchRoute", () => {
     expect(r2?.params.id).toBe("123");
   });
 });
+
+describe("optional segments [[id]]", () => {
+  test("matches with the segment present (binds the param)", () => {
+    const trie = buildTrie([makeRoute("users/[[id]]")]);
+    const r = matchRoute("/users/42", trie);
+    expect(r).not.toBeNull();
+    expect(r?.params).toEqual({ id: "42" });
+  });
+
+  test("matches with the segment absent (param unset)", () => {
+    const trie = buildTrie([makeRoute("users/[[id]]")]);
+    const r = matchRoute("/users", trie);
+    expect(r).not.toBeNull();
+    expect(r?.params).toEqual({});
+  });
+
+  test("static sibling still wins over the optional param", () => {
+    const trie = buildTrie([makeRoute("users/[[id]]"), makeRoute("users/me")]);
+    const r = matchRoute("/users/me", trie);
+    expect(r?.routeFile.urlPattern).toBe("users/me");
+  });
+
+  test("does not over-consume — extra segment falls through to catch-all", () => {
+    const trie = buildTrie([makeRoute("users/[[id]]"), makeRoute("users/[...rest]")]);
+    const r = matchRoute("/users/1/2", trie);
+    expect(r?.routeFile.urlPattern).toBe("users/[...rest]");
+    expect(r?.params.rest).toBe("1/2");
+  });
+});

package/src/__tests__/module-registry.test.ts

@@ -18,9 +18,8 @@ beforeAll(async () => {
   await writeFile(join(TMP, "root.tsx"), `export default function Root() { return null; }\n`);
   await writeFile(join(TMP, "routes", "_index.tsx"), `export default function Home() { return null; }\n`);
   await writeFile(join(TMP, "routes", "blog", "layout.tsx"), `export default function L({ children }: any) { return children; }\n`);
-  // Nested route — `routes/blog/layout.tsx` only applies because there is a
-  // deeper route under /blog/. Layouts wrap children, not the leaf at the
-  // same path level (matches `layout.ts`'s `layoutDirs` resolution).
+  // Nested route under /blog/ — `routes/blog/layout.tsx` wraps everything in
+  // its directory (including a `blog/_index`), per `layoutDirsFromFilePath`.
   await writeFile(join(TMP, "routes", "blog", "[slug].tsx"), `export default function P() { return null; }\n`);
 
   await writeFile(

package/src/__tests__/route-lint.test.ts

@@ -58,6 +58,11 @@ describe("lintRouteModuleSource — miscased exports", () => {
       `export default () => null;\n` +
       `export function loader() { return {}; }\n` +
       `export function action() { return {}; }\n` +
+      `export const clientLoader = () => ({});\n` +
+      `export const clientAction = () => ({});\n` +
+      `export function headers() { return {}; }\n` +
+      `export const middleware = [];\n` +
+      `export const handle = {};\n` +
       `export const searchSchema = {};\n` +
       `export function Fallback() { return null; }\n` +
       `export const ssr = false;\n`;

package/src/__tests__/route-middleware.test.ts

@@ -0,0 +1,84 @@
+import { test, expect, describe } from "bun:test";
+import {
+  runRouteMiddleware,
+  collectRouteMiddleware,
+  type RouteMiddleware,
+} from "../server/middleware.ts";
+import type { MiddlewareContext } from "../server/middleware.ts";
+
+function makeCtx(): MiddlewareContext {
+  return { request: new Request("http://localhost/"), params: {}, context: {} };
+}
+
+const ok = async () => new Response("ok", { status: 200 });
+
+describe("collectRouteMiddleware", () => {
+  test("orders root → layouts → route and flattens arrays", () => {
+    const order: string[] = [];
+    const mk = (label: string): RouteMiddleware => async (_c, n) => { order.push(label); return n(); };
+    const chain = {
+      root: { middleware: mk("root") },
+      layouts: [{ middleware: [mk("l0a"), mk("l0b")] }, { middleware: mk("l1") }],
+      route: { middleware: mk("route") },
+    };
+    const fns = collectRouteMiddleware(chain);
+    expect(fns).toHaveLength(5);
+    return runRouteMiddleware(fns, makeCtx(), ok).then(() => {
+      expect(order).toEqual(["root", "l0a", "l0b", "l1", "route"]);
+    });
+  });
+
+  test("ignores modules without middleware and non-function entries", () => {
+    const chain = {
+      root: {},
+      layouts: [{ middleware: undefined }, { middleware: ["nope" as unknown] }],
+      route: { middleware: (async (_c: MiddlewareContext, n: () => Promise<Response>) => n()) },
+    };
+    expect(collectRouteMiddleware(chain)).toHaveLength(1);
+  });
+});
+
+describe("runRouteMiddleware", () => {
+  test("empty list calls handler directly", async () => {
+    const res = await runRouteMiddleware([], makeCtx(), ok);
+    expect(res.status).toBe(200);
+  });
+
+  test("a middleware can short-circuit by not calling next()", async () => {
+    let handlerRan = false;
+    const gate: RouteMiddleware = async () => new Response("denied", { status: 403 });
+    const res = await runRouteMiddleware([gate], makeCtx(), async () => {
+      handlerRan = true;
+      return ok();
+    });
+    expect(res.status).toBe(403);
+    expect(handlerRan).toBe(false);
+  });
+
+  test("shares a mutable context across the chain and into the handler", async () => {
+    const ctx = makeCtx();
+    const setUser: RouteMiddleware = async (c, n) => { c.context.user = "alice"; return n(); };
+    let seenInHandler: unknown;
+    await runRouteMiddleware([setUser], ctx, async () => {
+      seenInHandler = ctx.context.user;
+      return ok();
+    });
+    expect(seenInHandler).toBe("alice");
+  });
+
+  test("rejects if a middleware calls next() twice", async () => {
+    const bad: RouteMiddleware = async (_c, n) => { await n(); return n(); };
+    await expect(runRouteMiddleware([bad], makeCtx(), ok)).rejects.toThrow(/more than once/);
+  });
+
+  test("outer middleware can post-process the inner Response", async () => {
+    const stamp: RouteMiddleware = async (_c, n) => {
+      const res = await n();
+      const out = new Response(res.body, res);
+      out.headers.set("X-Stamped", "1");
+      return out;
+    };
+    const res = await runRouteMiddleware([stamp], makeCtx(), ok);
+    expect(res.headers.get("X-Stamped")).toBe("1");
+  });
+});

package/src/__tests__/scanner.test.ts

@@ -1,5 +1,10 @@
 import { test, expect, describe } from "bun:test";
-import { filePathToPattern, pathToSegments } from "../server/scanner.ts";
+import {
+  filePathToPattern,
+  pathToSegments,
+  layoutDirsFromFilePath,
+  isRouteGroupSegment,
+} from "../server/scanner.ts";
 
 describe("filePathToPattern", () => {
   test("_index maps to empty pattern (root index)", () => {
@@ -25,6 +30,42 @@ describe("filePathToPattern", () => {
   test("strips .ts extension too", () => {
     expect(filePathToPattern("routes/api/data.ts")).toBe("api/data");
   });
+
+  test("route group folder adds no URL segment", () => {
+    expect(filePathToPattern("routes/(marketing)/about.tsx")).toBe("about");
+  });
+
+  test("nested route group strips only the group segment", () => {
+    expect(filePathToPattern("routes/(marketing)/blog/[id].tsx")).toBe("blog/[id]");
+  });
+
+  test("group wrapping the index → root pattern", () => {
+    expect(filePathToPattern("routes/(marketing)/_index.tsx")).toBe("");
+  });
+
+  test("[[id]] optional kept in pattern string", () => {
+    expect(filePathToPattern("routes/users/[[id]].tsx")).toBe("users/[[id]]");
+  });
+});
+
+describe("route groups", () => {
+  test("isRouteGroupSegment detects (group) but not () or plain", () => {
+    expect(isRouteGroupSegment("(marketing)")).toBe(true);
+    expect(isRouteGroupSegment("()")).toBe(false);
+    expect(isRouteGroupSegment("about")).toBe(false);
+    expect(isRouteGroupSegment("[id]")).toBe(false);
+  });
+
+  test("layoutDirsFromFilePath includes group folders", () => {
+    expect(layoutDirsFromFilePath("routes/(marketing)/blog/[id].tsx")).toEqual([
+      "(marketing)",
+      "(marketing)/blog",
+    ]);
+  });
+
+  test("layoutDirsFromFilePath for a top-level route → empty", () => {
+    expect(layoutDirsFromFilePath("routes/about.tsx")).toEqual([]);
+  });
 });
 
 describe("pathToSegments", () => {
@@ -44,6 +85,10 @@ describe("pathToSegments", () => {
     expect(pathToSegments("docs/[...slug]")).toEqual(["docs", { catchAll: "slug" }]);
   });
 
+  test("[[id]] → optional segment", () => {
+    expect(pathToSegments("users/[[id]]")).toEqual(["users", { optional: "id" }]);
+  });
+
   test("nested static path", () => {
     expect(pathToSegments("a/b/c")).toEqual(["a", "b", "c"]);
   });

package/src/__tests__/security-fixes.test.ts

@@ -0,0 +1,201 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { createServer } from "../server/serve.ts";
+import { pipeline } from "../server/middleware.ts";
+import { route, handleApiRequest } from "../server/api-route.ts";
+import { csp } from "../server/csp.ts";
+import { hasForbiddenKey, nullProtoFromEntries } from "../server/proto-guard.ts";
+import { searchParamsToObject } from "../server/search.ts";
+import { validate } from "../server/validate.ts";
+import { resolve } from "node:path";
+
+const PORT = 3989;
+const BASE = `http://localhost:${PORT}`;
+const FIXTURE_APP = resolve(import.meta.dir, "fixtures/app");
+
+// A marker middleware on the GLOBAL pipeline + a CSP middleware, plus a couple
+// of API routes. Registered before the server starts; cleared afterwards so
+// these don't leak into other suites sharing the process.
+const MARKER = "X-Test-Global-MW";
+
+let handle: ReturnType<typeof createServer>;
+
+beforeAll(() => {
+  pipeline.clear();
+  pipeline.use(async (_ctx, next) => {
+    const res = await next();
+    res.headers.set(MARKER, "1");
+    return res;
+  });
+  pipeline.use(csp());
+
+  // Protected-by-default mutating route, an opted-out one, and a GET.
+  route("POST", "/api/secure", (input: unknown) => ({ ok: true, input }));
+  route("POST", "/api/public", (input: unknown) => ({ ok: true, input }), { csrf: false });
+  route("GET", "/api/ping", () => ({ pong: true }));
+
+  handle = createServer({
+    port: PORT,
+    appDir: FIXTURE_APP,
+    manifest: { clientEntry: "/build/client/client.js", routes: {} },
+  });
+});
+
+afterAll(() => {
+  handle.stop();
+  pipeline.clear();
+});
+
+// ── H-1 — global middleware now wraps the special endpoints ────────────────
+
+describe("H-1: global middleware covers special endpoints", () => {
+  test("marker + CSP applied to an /api response", async () => {
+    const res = await fetch(`${BASE}/api/ping`);
+    expect(res.headers.get(MARKER)).toBe("1");
+    expect(res.headers.get("Content-Security-Policy")).toContain("default-src 'self'");
+  });
+
+  test("marker applied to /_action (even on 404 unknown id)", async () => {
+    const res = await fetch(`${BASE}/_action?id=deadbeefdeadbeef`, {
+      method: "POST",
+      headers: { "X-BractJS-Action": "1", "Content-Type": "application/json" },
+      body: "[]",
+    });
+    // unknown id → 404, but it still passed through the global pipeline.
+    expect(res.headers.get(MARKER)).toBe("1");
+  });
+
+  test("marker applied to /_image (even on 400 bad request)", async () => {
+    const res = await fetch(`${BASE}/_image?src=/etc/passwd`);
+    expect(res.headers.get(MARKER)).toBe("1");
+  });
+
+  test("marker applied to a normal SSR document too (no double-run)", async () => {
+    const res = await fetch(`${BASE}/`);
+    expect(res.headers.get(MARKER)).toBe("1");
+    // CSP header present exactly once.
+    expect(res.headers.get("Content-Security-Policy")).toContain("script-src");
+  });
+});
+
+// ── H-2 — CSRF on typed /api routes ────────────────────────────────────────
+
+describe("H-2: /api CSRF protection", () => {
+  test("cross-site POST to a protected route → 403", async () => {
+    const res = await fetch(`${BASE}/api/secure`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Sec-Fetch-Site": "cross-site" },
+      body: JSON.stringify({ a: 1 }),
+    });
+    expect(res.status).toBe(403);
+  });
+
+  test("no-attribution POST (no Origin / no header / no Sec-Fetch-Site) → 403", async () => {
+    // Call the handler directly so no Origin is auto-added by fetch.
+    const req = new Request("http://localhost/api/secure", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ a: 1 }),
+    });
+    const res = await handleApiRequest(req);
+    expect(res?.status).toBe(403);
+  });
+
+  test("same-origin POST (X-BractJS-Action) to a protected route → 200", async () => {
+    const res = await fetch(`${BASE}/api/secure`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-BractJS-Action": "1" },
+      body: JSON.stringify({ a: 1 }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, input: { a: 1 } });
+  });
+
+  test("same-origin POST via Sec-Fetch-Site → 200 (no custom header needed)", async () => {
+    const res = await fetch(`${BASE}/api/secure`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Sec-Fetch-Site": "same-origin" },
+      body: JSON.stringify({ a: 2 }),
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("opted-out route (csrf:false) allows cross-site POST", async () => {
+    const res = await fetch(`${BASE}/api/public`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Sec-Fetch-Site": "cross-site" },
+      body: JSON.stringify({ a: 3 }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, input: { a: 3 } });
+  });
+
+  test("GET /api is never CSRF-gated", async () => {
+    const res = await fetch(`${BASE}/api/ping`, { headers: { "Sec-Fetch-Site": "cross-site" } });
+    expect(res.status).toBe(200);
+  });
+
+  test("forbidden-key JSON body to an /api route → 400", async () => {
+    const res = await fetch(`${BASE}/api/secure`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-BractJS-Action": "1" },
+      body: '{"__proto__":{"polluted":true}}',
+    });
+    expect(res.status).toBe(400);
+    // And Object.prototype was not polluted.
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+  });
+});
+
+// ── M-1 — CSP form-action ──────────────────────────────────────────────────
+
+describe("M-1: CSP defaults", () => {
+  test("default policy includes form-action 'self'", async () => {
+    const res = await fetch(`${BASE}/api/ping`);
+    expect(res.headers.get("Content-Security-Policy")).toContain("form-action 'self'");
+  });
+});
+
+// ── M-2 — prototype-pollution guards ───────────────────────────────────────
+
+describe("M-2: proto-guard", () => {
+  test("hasForbiddenKey detects buried __proto__", () => {
+    let v: unknown = JSON.parse('{"__proto__":{"x":1}}');
+    for (let i = 0; i < 5; i++) v = { a: v };
+    expect(hasForbiddenKey(v)).toBe(true);
+  });
+
+  test("hasForbiddenKey passes a clean object", () => {
+    expect(hasForbiddenKey({ a: { b: { c: 1 } } })).toBe(false);
+  });
+
+  test("hasForbiddenKey fails closed past the scan depth", () => {
+    let v: unknown = { value: "x" };
+    for (let i = 0; i < 250; i++) v = { a: v };
+    expect(hasForbiddenKey(v)).toBe(true);
+  });
+
+  test("searchParamsToObject yields a null-prototype object", () => {
+    const out = searchParamsToObject(new URLSearchParams("__proto__=evil&a=1"));
+    expect(Object.getPrototypeOf(out)).toBeNull();
+    // __proto__ lands as a real own key, not a prototype mutation.
+    expect(out["__proto__"]).toBe("evil");
+    expect(({} as Record<string, unknown>).evil).toBeUndefined();
+  });
+
+  test("validate() over FormData with a __proto__ field does not pollute", async () => {
+    const fd = new FormData();
+    fd.set("__proto__", "evil");
+    fd.set("name", "ok");
+    // Identity schema — just returns what it gets.
+    const schema = { parse: (x: unknown) => x };
+    const out = (await validate(schema, fd)) as Record<string, unknown>;
+    expect(({} as Record<string, unknown>).evil).toBeUndefined();
+    expect(out.name).toBe("ok");
+  });
+
+  test("nullProtoFromEntries builds a null-prototype object", () => {
+    const out = nullProtoFromEntries([["__proto__", 1], ["a", 2]]);
+    expect(Object.getPrototypeOf(out)).toBeNull();
+    expect(out["a"]).toBe(2);
+  });
+});