create-ailk 0.12.1 → 0.13.0

package/templates/apps/web/.env.example

@@ -25,35 +25,71 @@ CONTENT_ADAPTER=mdx
 # CONTENT_REVALIDATE_SECRET=
 
 # =============================================================================
-# apps/api base URL (browser-side lead-capture forms) — #3965
-# =============================================================================
-# apps/web and apps/api are separate origins in every deployment shape that
-# doesn't front them with a rewrite/proxy. A browser-side block (e.g.
-# NewsletterFormInline, packages/ui/src/blocks/NewsletterFormInline.tsx)
-# posting a root-relative action (e.g. /v1/leads/subscribe) resolves it
-# against apps/web's OWN origin -- not apps/api's -- unless this is set.
-# Same convention as apps/workspace/lib/client-api.ts's identically-named var.
-# Should be apps/api's origin with NO trailing slash (a single trailing
-# slash is stripped before joining, but keep this clean regardless).
-#
-# THIS IS THE ONE BROWSER-SIDE NAME (#5397). All three browser readers of the
-# apps/api origin resolve it from this variable: resolveSubmitUrl
-# (packages/ui, the form blocks above), apps/workspace's client-api, and
+# The same-origin relay, and the browser-side apps/api name — #7644, #5397
+# =============================================================================
+# THIS SITE'S OWN FORMS NEVER CALL apps/api FROM THE BROWSER (#7644). Lead
+# capture, newsletter signup, step-flow submits, booking and the commerce
+# invoice form post to THIS site's own /v1/... address; app/v1/[...path]/route.ts
+# forwards each server-side to apps/api at AILK_API_URL, attaching this site's
+# AILK_SPOKE_KEY when it is set and none when it is not (a single-site install
+# takes the same path). next.config.mjs sets NEXT_PUBLIC_AILK_SAME_ORIGIN_RELAY
+# for that — it is part of the source, not a variable to set here. The relay
+# forwards exactly these, and refuses every other /v1 path with a 404:
+#
+#   POST /v1/leads/submit          POST /v1/leads/subscribe
+#   POST /v1/leads/callback        GET  /v1/schedule/availability
+#   POST /v1/schedule/book         POST /v1/commerce/invoices
+#
+# An authored form `action` must name one of them. Adding one is a reviewed
+# change to RELAY_ROUTES in lib/relay.ts and to this list. The visitor's
+# x-forwarded-for and user-agent reach the hub as received (and the keyed
+# visitor IP, with AILK_VISITOR_FORWARD_KEY — server-side only, never
+# NEXT_PUBLIC_; see the repo-root .env.example, #7394). A cross-site post is
+# refused before the hub is called.
+#
+# EDGE PRECONDITION: the relay forwards x-forwarded-for exactly as this site
+# received it, so run the site behind an edge that OVERWRITES the client-address
+# headers (as Vercel does), not one that appends to them. Otherwise a caller
+# can choose its own rate-limit identity at the hub (spec SEC-7644-6). And when
+# the HUB's edge overwrites x-forwarded-for with the address it saw (this
+# site's server), set AILK_VISITOR_FORWARD_KEY here and on the hub: without it
+# every visitor of this site shares one rate limit on the hub's lead routes.
+#
+# AILK_SPOKE_KEY ON A HUB WITH SPOKES (#7633). A hub whose spoke registry holds
+# a row refuses every public call without a key by default, so EVERY site of it
+# sets its own key — the hub's own site too, registered against the operator's
+# own workspace. The relay above carries it on the browser's calls; the site's
+# server-side reads (meeting types, the /meet pages, Server Actions) send it
+# themselves. It is sent only when AILK_API_URL is https: or loopback.
+# AILK_SPOKE_KEY=
+#
+# UPGRADE ORDER for a hub with spokes. 1) Redeploy every site on this release,
+# the hub's own site included — a site still on the previous release keeps
+# posting to the hub directly, and keeps working, until then. 2) Register a key
+# for every site (the #7532 runbook) and set it as AILK_SPOKE_KEY. 3) Only then
+# upgrade the hub to the release that refuses keyless callers (#7633; the
+# runbook's "Before you upgrade a hub"). After that a spoke's origin can
+# come off the hub's AILK_TRUSTED_ORIGINS — unless the site uses the commerce
+# invoice form, a cookie-authenticated owner write whose Origin the hub still
+# checks against that list.
+#
+# NEXT_PUBLIC_AILK_API_URL is still THE ONE BROWSER-SIDE NAME of apps/api's
+# origin (#5397) for the two browser readers the relay does not cover:
 # @working-theory/api-client's getApiBase() — which runs in the browser
 # wherever a "use client" component binds it, e.g. the founder application's
-# ListingApplicationClient. getApiBase() previously read NEXT_PUBLIC_API_URL,
-# a name this file never documented, so a site configured exactly per these
-# docs sent its browser traffic to http://localhost:3001. That name is still
-# honoured as a deprecated fallback; do not set it in a new deployment.
+# ListingApplicationClient — and the report reader's download link. It is also
+# what packages/ui's resolveSubmitUrl falls back to in a build WITHOUT the
+# relay (an older scaffold that upgrades @working-theory/ui alone). Should be
+# apps/api's origin with NO trailing slash. getApiBase() previously read
+# NEXT_PUBLIC_API_URL, a name this file never documented, so a site configured
+# exactly per these docs sent its browser traffic to http://localhost:3001.
+# That name is still honoured as a deprecated fallback; do not set it in a new
+# deployment.
 #
 # The server-side counterpart is AILK_API_URL (see the repo-root .env.example)
 # — deliberately NOT NEXT_PUBLIC_, and it still wins over this one when both
-# are set, so an RSC/Server-Action call can target an internal origin the
-# browser never sees.
-#
-# A spoke calling a hub API server-to-server forwards its visitors for the
-# hub's per-visitor lead limit with AILK_VISITOR_FORWARD_KEY — server-side
-# only, never NEXT_PUBLIC_ (see the repo-root .env.example, #7394).
+# are set, so an RSC/Server-Action call and the relay can target an internal
+# origin the browser never sees.
 # NEXT_PUBLIC_AILK_API_URL=http://localhost:3002
 
 # =============================================================================
@@ -188,16 +224,7 @@ CONTENT_ADAPTER=mdx
 # boundary checkable rather than merely intended.
 # SCHEDULING_CAL_LINK=owner/event-slug
 #
-# SPLIT-ORIGIN DEPLOYS NEED A CSP EXTENSION. The booker calls this site's
-# /v1/schedule/* routes from the browser, resolved through
-# NEXT_PUBLIC_AILK_API_URL. Set that variable and the calls become
-# cross-origin, but the baseline CSP in security-headers.config.ts is
-# `connect-src 'self' https://api.stripe.com` — so the browser blocks them and
-# the booker shows its generic unavailable state with no explanation. Pass the
-# API origin through the customer extension `buildHeaders` accepts:
-#
-#   buildHeaders({ csp: { "connect-src": ["'self'", "<your apps/api origin>"] } })
-#
-# Deploying apps/web and apps/api on one origin (leaving
-# NEXT_PUBLIC_AILK_API_URL unset) needs no extension — the calls stay
-# same-origin and 'self' already covers them.
+# The booker's /v1/schedule/* calls go through this site's same-origin relay
+# (see the relay block above, #7644), so the baseline CSP's
+# `connect-src 'self'` already covers them — no CSP extension is needed for
+# them, whatever NEXT_PUBLIC_AILK_API_URL is set to.

package/templates/apps/web/app/v1/[...path]/route.ts

@@ -0,0 +1,16 @@
+/**
+ * The same-origin relay's route (#7644 D1). Every `/v1/...` request to this
+ * site lands here and is answered by `handleRelay` (lib/relay.ts): forwarded
+ * to the hub when it is one of the fixed relayed routes, refused otherwise.
+ * Next answers any other method with 405 itself.
+ *
+ * `/v1` is exempt from next-intl's locale rewrite in middleware.ts, as `/api`
+ * is; a static `v1` segment wins over `[locale]`, so no page is shadowed.
+ */
+import { handleRelay } from "../../../lib/relay";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export const GET = handleRelay;
+export const POST = handleRelay;

package/templates/apps/web/lib/__tests__/relay.test.ts

@@ -0,0 +1,515 @@
+/**
+ * @jest-environment node
+ */
+// The same-origin relay (#7644): the site serves the root-relative /v1 paths
+// its own browser forms post to and forwards each, server-side, to the hub.
+//
+// Drives `handleRelay` with real `Request` objects through the real
+// `relayToApi` (jest maps @working-theory/api-client to source), with the
+// global `fetch` — the hub — stubbed.
+//
+// Spec: docs/specs/7644-the-browser-talks-only-to-spec.md §5.1 AC-1 to AC-4.
+
+import { handleRelay, RELAY_ROUTES } from "../relay";
+
+const HUB = "https://hub.example";
+const SITE = "https://spoke.example";
+const K1 = "K1";
+const FORWARD_KEY = "FWD";
+const BODY = '{"siteId":"x","email":"a@b.example"}';
+const QUERY = "?calLink=acme/intro&start=2026-10-05";
+
+const ENV_KEYS = [
+  "AILK_API_URL",
+  "NEXT_PUBLIC_AILK_API_URL",
+  "NEXT_PUBLIC_API_URL",
+  "AILK_SPOKE_KEY",
+  "AILK_VISITOR_FORWARD_KEY",
+] as const;
+const priorEnv = new Map<string, string | undefined>(
+  ENV_KEYS.map((name) => [name, process.env[name]]),
+);
+
+function hubAnswer(
+  status = 201,
+  body = '{"id":"lead_1","persisted":"db"}',
+  headers: Record<string, string> = { "content-type": "application/json" },
+): Response {
+  return new Response(body, { status, headers });
+}
+
+const fetchMock = jest.fn(async (_url: string, _init: RequestInit) =>
+  hubAnswer(),
+);
+const priorFetch = global.fetch;
+
+/** The `(url, init)` of the one hub call. */
+function sent(): { url: string; init: RequestInit; headers: Headers } {
+  expect(fetchMock).toHaveBeenCalledTimes(1);
+  const call = fetchMock.mock.calls[0];
+  if (!call) throw new Error("the hub was not called");
+  const [url, init] = call;
+  return { url, init, headers: new Headers(init.headers) };
+}
+
+const SAME_ORIGIN = {
+  origin: SITE,
+  "sec-fetch-site": "same-origin",
+};
+
+/**
+ * A request to the relay at `path`. A same-origin browser POST by default:
+ * `host: spoke.example`, its own `Origin`, `Sec-Fetch-Site: same-origin`
+ * and a JSON body. `headers` overrides; a `null` value removes the header.
+ */
+function relayRequest(
+  path: string,
+  {
+    method = "POST",
+    headers = {},
+    body = BODY,
+  }: {
+    method?: string;
+    headers?: Record<string, string | null>;
+    body?: string;
+  } = {},
+): Request {
+  const merged: Record<string, string | null> = {
+    host: "spoke.example",
+    ...SAME_ORIGIN,
+    ...(method === "POST" ? { "content-type": "application/json" } : {}),
+    ...headers,
+  };
+  const init: RequestInit = {
+    method,
+    headers: Object.fromEntries(
+      Object.entries(merged).filter(
+        (entry): entry is [string, string] => entry[1] !== null,
+      ),
+    ),
+  };
+  if (method === "POST") init.body = body;
+  return new Request(`${SITE}${path}`, init);
+}
+
+async function errorCode(res: Response): Promise<string | undefined> {
+  const json = (await res.json()) as { ok?: boolean; error?: { code?: string } };
+  expect(json.ok).toBe(false);
+  return json.error?.code;
+}
+
+const ENTRIES: ReadonlyArray<{ method: "GET" | "POST"; path: string }> = [
+  { method: "POST", path: "/v1/leads/submit" },
+  { method: "POST", path: "/v1/leads/subscribe" },
+  { method: "POST", path: "/v1/leads/callback" },
+  { method: "GET", path: "/v1/schedule/availability" },
+  { method: "POST", path: "/v1/schedule/book" },
+  { method: "POST", path: "/v1/commerce/invoices" },
+];
+const VISITOR_ENTRIES = ENTRIES.filter(
+  (e) => e.path !== "/v1/commerce/invoices",
+);
+
+/** The relay request for one D2 entry, with the GET's query string. */
+function entryRequest(
+  entry: { method: string; path: string },
+  headers: Record<string, string | null> = {},
+): Request {
+  return relayRequest(
+    entry.method === "GET" ? `${entry.path}${QUERY}` : entry.path,
+    { method: entry.method, headers },
+  );
+}
+
+let errorSpy: jest.SpyInstance;
+
+beforeEach(() => {
+  fetchMock.mockClear();
+  fetchMock.mockImplementation(async () => hubAnswer());
+  global.fetch = fetchMock as jest.Mock;
+  for (const name of ENV_KEYS) delete process.env[name];
+  process.env.AILK_API_URL = HUB;
+  process.env.AILK_SPOKE_KEY = K1;
+  errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  errorSpy.mockRestore();
+});
+
+afterAll(() => {
+  global.fetch = priorFetch;
+  for (const [name, value] of priorEnv) {
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+});
+
+describe("AC-1 — forwarding, one entry each", () => {
+  it.each(ENTRIES)(
+    "$method $path is forwarded once, unchanged, and its answer passed back",
+    async (entry) => {
+      const res = await handleRelay(entryRequest(entry));
+
+      const { url, init } = sent();
+      expect(url).toBe(
+        `${HUB}${entry.path}${entry.method === "GET" ? QUERY : ""}`,
+      );
+      expect(init.method).toBe(entry.method);
+      if (entry.method === "POST") expect(init.body).toBe(BODY);
+      else expect(init.body).toBeUndefined();
+
+      expect(res.status).toBe(201);
+      expect(await res.text()).toBe('{"id":"lead_1","persisted":"db"}');
+      expect(res.headers.get("content-type")).toBe("application/json");
+      expect(res.headers.get("cache-control")).toBe("no-store");
+    },
+  );
+
+  it("forwards the body byte-for-byte, never re-serialised", async () => {
+    const body = '{ "b":1,\n  "a" : [2, 1] }';
+    await handleRelay(relayRequest("/v1/leads/submit", { body }));
+    expect(sent().init.body).toBe(body);
+  });
+
+  it("drops a query string on a POST entry", async () => {
+    await handleRelay(relayRequest("/v1/leads/submit?x=1"));
+    expect(sent().url).toBe(`${HUB}/v1/leads/submit`);
+  });
+
+  it("passes the hub's 429 and retry-after through", async () => {
+    fetchMock.mockImplementation(async () =>
+      hubAnswer(429, '{"ok":false}', {
+        "content-type": "application/json",
+        "retry-after": "30",
+      }),
+    );
+    const res = await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(res.status).toBe(429);
+    expect(res.headers.get("retry-after")).toBe("30");
+    expect(await res.text()).toBe('{"ok":false}');
+  });
+
+  it("answers 502 relay_unreachable when the hub cannot be reached", async () => {
+    fetchMock.mockImplementation(async () => {
+      throw new TypeError("fetch failed");
+    });
+    const res = await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(res.status).toBe(502);
+    expect(await errorCode(res)).toBe("relay_unreachable");
+  });
+});
+
+describe("AC-2 — only the list", () => {
+  it.each([
+    ["POST", "/v1/workspaces"],
+    ["GET", "/v1/schedule/meeting-types"],
+    ["POST", "/v1/flows/x/steps"],
+    ["GET", "/v1/leads/submit"],
+    ["POST", "/v1/leads/submit/"],
+    ["POST", "/v1/leads/submit/extra"],
+    ["POST", "/v1/Leads/submit"],
+  ])("%s %s answers 404 not_found and calls no hub", async (method, path) => {
+    const res = await handleRelay(relayRequest(path, { method }));
+    expect(res.status).toBe(404);
+    expect(await errorCode(res)).toBe("not_found");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("RELAY_ROUTES is exactly the six D2 pairs, and frozen", () => {
+    expect(RELAY_ROUTES).toEqual(ENTRIES);
+    expect(Object.isFrozen(RELAY_ROUTES)).toBe(true);
+    for (const route of RELAY_ROUTES) expect(Object.isFrozen(route)).toBe(true);
+  });
+});
+
+describe("AC-3 — the key, and only the site's key", () => {
+  it.each(ENTRIES)(
+    "$method $path carries the site's key and refuses redirects",
+    async (entry) => {
+      await handleRelay(entryRequest(entry));
+      const { init, headers } = sent();
+      expect(headers.get("x-ailk-spoke-key")).toBe(K1);
+      expect(init.redirect).toBe("error");
+    },
+  );
+
+  it.each(ENTRIES)(
+    "$method $path without a site key carries none and still works (the single-site path)",
+    async (entry) => {
+      delete process.env.AILK_SPOKE_KEY;
+      const res = await handleRelay(entryRequest(entry));
+      const { init, headers } = sent();
+      expect(headers.get("x-ailk-spoke-key")).toBeNull();
+      expect(init.redirect).toBe("error");
+      expect(res.status).toBe(201);
+    },
+  );
+
+  const CLIENT_SENT = {
+    "x-ailk-spoke-key": "EVIL",
+    "x-ailk-visitor-forward-key": "EVIL",
+    "x-ailk-workspace-id": "wksp_x",
+    authorization: "Bearer t",
+  };
+
+  it("a client-sent key, forward key, workspace header and authorization never reach the hub", async () => {
+    await handleRelay(relayRequest("/v1/leads/submit", { headers: CLIENT_SENT }));
+    const { headers } = sent();
+    expect(headers.get("x-ailk-spoke-key")).toBe(K1);
+    expect(headers.get("x-ailk-visitor-forward-key")).toBeNull();
+    expect(headers.get("x-ailk-workspace-id")).toBeNull();
+    expect(headers.get("authorization")).toBeNull();
+  });
+
+  it("with no site key, a client-sent key still never reaches the hub", async () => {
+    delete process.env.AILK_SPOKE_KEY;
+    await handleRelay(relayRequest("/v1/leads/submit", { headers: CLIENT_SENT }));
+    expect(sent().headers.get("x-ailk-spoke-key")).toBeNull();
+  });
+});
+
+describe("AC-4 — the visitor, unchanged; a cross-site post, refused", () => {
+  it("forwards x-forwarded-for and user-agent exactly as received", async () => {
+    await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: {
+          "x-forwarded-for": "203.0.113.5, 10.0.0.1",
+          "user-agent": "UA/1",
+        },
+      }),
+    );
+    const { headers } = sent();
+    expect(headers.get("x-forwarded-for")).toBe("203.0.113.5, 10.0.0.1");
+    expect(headers.get("user-agent")).toBe("UA/1");
+  });
+
+  it("sends x-real-ip as x-forwarded-for when that is all it has", async () => {
+    await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { "x-real-ip": "203.0.113.9" },
+      }),
+    );
+    expect(sent().headers.get("x-forwarded-for")).toBe("203.0.113.9");
+  });
+
+  it("sends no x-forwarded-for when it has neither", async () => {
+    await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(sent().headers.get("x-forwarded-for")).toBeNull();
+  });
+
+  it.each(VISITOR_ENTRIES)(
+    "$method $path carries the keyed visitor IP when the site has a forward key",
+    async (entry) => {
+      process.env.AILK_VISITOR_FORWARD_KEY = FORWARD_KEY;
+      await handleRelay(
+        entryRequest(entry, { "x-forwarded-for": "203.0.113.5, 10.0.0.1" }),
+      );
+      const { headers } = sent();
+      expect(headers.get("x-ailk-visitor-ip")).toBe("203.0.113.5");
+      expect(headers.get("x-ailk-visitor-forward-key")).toBe(FORWARD_KEY);
+    },
+  );
+
+  it("POST /v1/commerce/invoices carries no keyed visitor IP", async () => {
+    process.env.AILK_VISITOR_FORWARD_KEY = FORWARD_KEY;
+    await handleRelay(
+      relayRequest("/v1/commerce/invoices", {
+        headers: { "x-forwarded-for": "203.0.113.5" },
+      }),
+    );
+    const { headers } = sent();
+    expect(headers.get("x-ailk-visitor-ip")).toBeNull();
+    expect(headers.get("x-ailk-visitor-forward-key")).toBeNull();
+  });
+
+  it("forwards cookie and origin on /v1/commerce/invoices", async () => {
+    await handleRelay(
+      relayRequest("/v1/commerce/invoices", { headers: { cookie: "s=1" } }),
+    );
+    const { headers } = sent();
+    expect(headers.get("cookie")).toBe("s=1");
+    expect(headers.get("origin")).toBe(SITE);
+  });
+
+  it.each(VISITOR_ENTRIES)(
+    "$method $path forwards neither cookie nor origin",
+    async (entry) => {
+      await handleRelay(entryRequest(entry, { cookie: "s=1" }));
+      const { headers } = sent();
+      expect(headers.get("cookie")).toBeNull();
+      expect(headers.get("origin")).toBeNull();
+    },
+  );
+
+  it.each<[string, Record<string, string | null>]>([
+    ["a foreign origin", { origin: "https://evil.example" }],
+    ["origin: null", { origin: "null" }],
+    ["the same host on another port", { origin: "https://spoke.example:8443" }],
+    [
+      "sec-fetch-site: cross-site with a same-host origin",
+      { "sec-fetch-site": "cross-site" },
+    ],
+    ["sec-fetch-site: same-site", { "sec-fetch-site": "same-site" }],
+  ])("%s answers 403 cross_site and calls no hub", async (_label, headers) => {
+    const res = await handleRelay(relayRequest("/v1/leads/submit", { headers }));
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("cross_site");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("admits an origin that matches the forwarded host behind a proxy", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: {
+          host: "internal:3000",
+          "x-forwarded-host": "spoke.example, proxy",
+        },
+      }),
+    );
+    expect(res.status).toBe(201);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("admits a JSON POST that carries neither origin nor sec-fetch-site (a non-browser caller)", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { origin: null, "sec-fetch-site": null },
+      }),
+    );
+    expect(res.status).toBe(201);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("the forwarded host wins over a matching host header", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { host: "spoke.example", "x-forwarded-host": "proxy.example" },
+      }),
+    );
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("cross_site");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("a POST that is not JSON answers 415", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { "content-type": "text/plain" },
+      }),
+    );
+    expect(res.status).toBe(415);
+    expect(await errorCode(res)).toBe("unsupported_media_type");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("admits a JSON content-type with parameters, in any case", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { "content-type": "Application/JSON; charset=utf-8" },
+      }),
+    );
+    expect(res.status).toBe(201);
+  });
+
+  it("a body over 1 MiB answers 413", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", { body: "x".repeat(1_048_577) }),
+    );
+    expect(res.status).toBe(413);
+    expect(await errorCode(res)).toBe("payload_too_large");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("a body of exactly 1 MiB is forwarded", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", { body: "x".repeat(1_048_576) }),
+    );
+    expect(res.status).toBe(201);
+  });
+
+  it("a request already relayed answers 508 relay_loop", async () => {
+    const res = await handleRelay(
+      relayRequest("/v1/leads/submit", { headers: { "x-ailk-relayed": "1" } }),
+    );
+    expect(res.status).toBe(508);
+    expect(await errorCode(res)).toBe("relay_loop");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("marks every forwarded call so a self-pointing hub address cannot loop", async () => {
+    await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(sent().headers.get("x-ailk-relayed")).toBe("1");
+  });
+
+  it("forwards nothing outside its allow-list", async () => {
+    await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { "x-custom": "1", "accept-language": "en" },
+      }),
+    );
+    const names = [...sent().headers.keys()].sort();
+    expect(names).toEqual(["content-type", "x-ailk-relayed", "x-ailk-spoke-key"]);
+  });
+});
+
+describe("hardening — what the site serves, and a missing hub address", () => {
+  const mediaType = (res: Response) =>
+    res.headers.get("content-type")?.split(";")[0]?.trim();
+
+  it("passes a JSON content-type through as the hub sent it", async () => {
+    fetchMock.mockImplementation(async () =>
+      hubAnswer(201, "{}", { "content-type": "application/json; charset=utf-8" }),
+    );
+    const res = await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(res.headers.get("content-type")).toBe(
+      "application/json; charset=utf-8",
+    );
+  });
+
+  it.each([
+    ["an HTML error page", { "content-type": "text/html" }],
+    ["no content-type at all", {}],
+  ])("serves %s from the hub as text/plain, never as markup", async (_label, headers) => {
+    fetchMock.mockImplementation(async () =>
+      hubAnswer(502, "<p>bad gateway</p>", headers),
+    );
+    const res = await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(res.status).toBe(502);
+    expect(mediaType(res)).toBe("text/plain");
+    expect(await res.text()).toBe("<p>bad gateway</p>");
+  });
+
+  it("marks every relayed answer and every refusal nosniff", async () => {
+    const relayed = await handleRelay(relayRequest("/v1/leads/submit"));
+    const refused = await handleRelay(relayRequest("/v1/nope"));
+    expect(relayed.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(refused.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(mediaType(refused)).toBe("application/json");
+  });
+
+  describe("in production", () => {
+    const env = process.env as Record<string, string | undefined>;
+    const priorNodeEnv = env.NODE_ENV;
+    beforeEach(() => {
+      env.NODE_ENV = "production";
+    });
+    afterEach(() => {
+      env.NODE_ENV = priorNodeEnv;
+    });
+
+    it("answers 502 relay_unreachable and calls nothing when no hub address is set", async () => {
+      delete process.env.AILK_API_URL;
+      const res = await handleRelay(relayRequest("/v1/leads/submit"));
+      expect(res.status).toBe(502);
+      expect(await errorCode(res)).toBe("relay_unreachable");
+      expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it("forwards as usual when a hub address is set", async () => {
+      const res = await handleRelay(relayRequest("/v1/leads/submit"));
+      expect(res.status).toBe(201);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+  });
+});