create-ailk 0.14.0 → 0.15.0

package/templates/apps/web/app/openapi.json/__tests__/route.test.ts

@@ -15,13 +15,29 @@
 
 import { GET } from "../route";
 
+// The generated topology seam (#7426 D5), mocked so each case picks its
+// topology: the hub cases below run against `"hub"`, exactly as before; the
+// spoke cases (D12) flip it. Mocked rather than imported because the hub
+// render imports `../auth`, which this route never touches.
+const mockTopology: { value: "hub" | "spoke" } = { value: "hub" };
+// eslint-disable-next-line no-restricted-syntax -- #507: the topology is a generated constant (#7426 D5), not a runtime input; the seam IS the boundary between a hub and a spoke build, and there is no env or HTTP surface that selects it.
+jest.mock("../../../lib/topology.generated", () => ({
+  get TOPOLOGY() {
+    return mockTopology.value;
+  },
+}));
+
 const SPEC = {
   openapi: "3.1.0",
   info: { title: "Example API", version: "1.0.0" },
   paths: { "/v1/content/search": {} },
 };
 
-const API_ENV = ["AILK_API_URL", "NEXT_PUBLIC_AILK_API_URL"] as const;
+const API_ENV = [
+  "AILK_API_URL",
+  "NEXT_PUBLIC_AILK_API_URL",
+  "NEXT_PUBLIC_BASE_URL",
+] as const;
 const saved: Record<string, string | undefined> = {};
 let fetchSpy: jest.SpyInstance;
 
@@ -34,6 +50,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
+  mockTopology.value = "hub";
   for (const name of API_ENV) {
     if (saved[name] === undefined) delete process.env[name];
     else process.env[name] = saved[name];
@@ -174,3 +191,74 @@ describe("GET /openapi.json", () => {
     expect(await response.text()).not.toContain("api.internal");
   });
 });
+
+describe("GET /openapi.json on a spoke (#7426 D12)", () => {
+  const HUB_SPEC = {
+    openapi: "3.1.0",
+    info: { title: "Hub API", version: "1.0.0" },
+    servers: [{ url: "https://hub.example.com", description: "The hub" }],
+    paths: {
+      "/v1/leads/submit": {
+        post: { summary: "Submit a lead" },
+        get: { summary: "Not relayed" },
+      },
+      "/v1/schedule/availability": {
+        get: {
+          summary: "Availability",
+          servers: [{ url: "https://hub.example.com/schedule" }],
+        },
+      },
+      "/v1/content/search": { get: { summary: "Hub-only search" } },
+      "/v1/admin/sites": { post: { summary: "Hub-only admin" } },
+    },
+  };
+
+  beforeEach(() => {
+    mockTopology.value = "spoke";
+    process.env["AILK_API_URL"] = "https://hub.example.com";
+    process.env["NEXT_PUBLIC_BASE_URL"] = "https://spoke.example.com";
+  });
+
+  it("names only this spoke's own origin in servers[]", async () => {
+    apiAnswers(200, JSON.stringify(HUB_SPEC));
+
+    const response = await GET();
+    const body = (await response.json()) as { servers: unknown };
+
+    expect(response.status).toBe(200);
+    expect(body.servers).toEqual([{ url: "https://spoke.example.com" }]);
+    expect(JSON.stringify(body)).not.toContain("hub.example.com");
+  });
+
+  it("keeps only the paths and methods the relay forwards", async () => {
+    apiAnswers(200, JSON.stringify(HUB_SPEC));
+
+    const body = (await (await GET()).json()) as {
+      paths: Record<string, Record<string, unknown>>;
+    };
+
+    expect(body.paths).toEqual({
+      "/v1/leads/submit": { post: { summary: "Submit a lead" } },
+      "/v1/schedule/availability": { get: { summary: "Availability" } },
+    });
+  });
+
+  it("still reads the hub's document at AILK_API_URL", async () => {
+    apiAnswers(200, JSON.stringify(HUB_SPEC));
+
+    await GET();
+
+    expect(requestedUrl()).toBe("https://hub.example.com/v1/openapi.json");
+  });
+
+  it("on a hub, leaves servers[] and paths as the API declared them", async () => {
+    mockTopology.value = "hub";
+    apiAnswers(200, JSON.stringify(HUB_SPEC));
+
+    const body = (await (await GET()).json()) as typeof HUB_SPEC;
+
+    expect(body.servers).toEqual(HUB_SPEC.servers);
+    expect(body.paths).toEqual(HUB_SPEC.paths);
+    expect(JSON.stringify(body)).toContain("hub.example.com");
+  });
+});

package/templates/apps/web/app/openapi.json/route.ts

@@ -15,8 +15,18 @@
  * When the API cannot be reached, or answers anything but an OpenAPI
  * document with a 200, this route answers 502 with a JSON error that names no
  * upstream origin, and is never cached.
+ *
+ * On a spoke (#7426 D12) the API is the hub's, so the document is rewritten
+ * to describe THIS host only: `servers[]` becomes this site's own origin, and
+ * `paths` keeps only the (path, method) pairs the same-origin relay forwards
+ * (`RELAY_ROUTES`, lib/relay.ts) — an agent reading it never learns the hub's
+ * host, and never calls a path this site would answer 404.
  */
 
+import { RELAY_ROUTES } from "../../lib/relay";
+import { TOPOLOGY } from "../../lib/topology.generated";
+import { resolveBaseUrl } from "../../src/lib/routes";
+
 // Read per request: the document is the running API's, and `next build` has
 // no API to read it from.
 export const dynamic = "force-dynamic";
@@ -58,6 +68,7 @@ function stripSlash(url: string): string {
 interface OpenApiDocument {
   openapi: string;
   servers?: Array<{ url?: unknown; description?: unknown }>;
+  paths?: Record<string, unknown>;
 }
 
 function isOpenApiDocument(value: unknown): value is OpenApiDocument {
@@ -86,6 +97,61 @@ function withAbsoluteServers(spec: OpenApiDocument): OpenApiDocument {
   };
 }
 
+/** The operation keys an OpenAPI path item may carry (OpenAPI 3.1 § 4.8.9). */
+const OPERATION_KEYS = new Set([
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+]);
+
+/**
+ * The document as a spoke serves it (#7426 D12): this host's own origin as
+ * the only server, and only the relayed (path, method) pairs. A path item's
+ * non-operation keys (`summary`, `parameters`, ...) ride along with a kept
+ * operation; a `servers` list — on the path item or on a kept operation —
+ * never does: it would name the hub.
+ */
+function withoutServers(operation: unknown): unknown {
+  if (typeof operation !== "object" || operation === null) return operation;
+  const { servers: _servers, ...rest } = operation as Record<string, unknown>;
+  return rest;
+}
+
+function asSpokeDocument(spec: OpenApiDocument): OpenApiDocument {
+  const relayed = new Map<string, Set<string>>();
+  for (const { method, path } of RELAY_ROUTES) {
+    const methods = relayed.get(path) ?? new Set<string>();
+    methods.add(method.toLowerCase());
+    relayed.set(path, methods);
+  }
+  const paths: Record<string, unknown> = {};
+  for (const [path, item] of Object.entries(spec.paths ?? {})) {
+    const methods = relayed.get(path);
+    if (methods === undefined || typeof item !== "object" || item === null) {
+      continue;
+    }
+    const kept = Object.fromEntries(
+      Object.entries(item)
+        .filter(([key]) =>
+          OPERATION_KEYS.has(key) ? methods.has(key) : key !== "servers",
+        )
+        .map(([key, value]) => [
+          key,
+          OPERATION_KEYS.has(key) ? withoutServers(value) : value,
+        ]),
+    );
+    if (Object.keys(kept).some((key) => OPERATION_KEYS.has(key))) {
+      paths[path] = kept;
+    }
+  }
+  return { ...spec, servers: [{ url: stripSlash(resolveBaseUrl()) }], paths };
+}
+
 function badGateway(message: string): Response {
   return Response.json(
     { error: { code: "upstream_unavailable", message } },
@@ -120,7 +186,9 @@ export async function GET(): Promise<Response> {
     return badGateway("The API answered JSON that is not an OpenAPI document.");
   }
 
-  return Response.json(withAbsoluteServers(spec), {
+  const served =
+    TOPOLOGY === "spoke" ? asSpokeDocument(spec) : withAbsoluteServers(spec);
+  return Response.json(served, {
     status: 200,
     headers: { "cache-control": "public, max-age=3600" },
   });

package/templates/apps/web/instrumentation.ts

@@ -2,13 +2,16 @@
  * Next.js instrumentation hook — runs once per server instance at boot.
  *
  * Registers the durable home of a renewed licence key (#6677 DD-6) before any
- * request resolves the licence. Node runtime only: the store reaches the
- * database through Prisma, which the Edge runtime cannot load.
+ * request resolves the licence, through the generated topology seam (#7426
+ * D5): a hub registers the database-backed store; a spoke has no database,
+ * so its render registers nothing. Node runtime only: the store reaches the
+ * database through Prisma, which the Edge runtime cannot load — the import
+ * stays inside the runtime check so the Edge bundle never carries it.
  */
 
 export async function register(): Promise<void> {
   if (process.env.NEXT_RUNTIME === "nodejs") {
-    const { registerLicenseKeyStore } = await import("./lib/license-key-store");
-    await registerLicenseKeyStore();
+    const { registerSiteStores } = await import("./lib/topology.generated");
+    await registerSiteStores();
   }
 }

package/templates/apps/web/lib/__tests__/closing-footer-path.test.ts

@@ -0,0 +1,96 @@
+import {
+  isClosingFooterPath,
+  normalizeRoutePath,
+} from "../closing-footer-path";
+
+const LOCALES = ["en", "es"];
+
+describe("normalizeRoutePath (#7797)", () => {
+  it.each([
+    ["/about", "/about"],
+    ["/about/", "/about"],
+    ["/about//", "/about"],
+    ["/es/about", "/about"],
+    ["/es/about/", "/about"],
+    ["/about?x=1", "/about"],
+    ["/about#team", "/about"],
+    ["/services/first-engagement/", "/services/first-engagement"],
+    ["/", "/"],
+    ["", "/"],
+    ["/es", "/"],
+    ["/es/", "/"],
+  ])("%s → %s", (input, expected) => {
+    expect(normalizeRoutePath(input, LOCALES)).toBe(expected);
+  });
+
+  it("strips only a whole leading locale segment", () => {
+    expect(normalizeRoutePath("/espresso", LOCALES)).toBe("/espresso");
+    expect(normalizeRoutePath("/about/es", LOCALES)).toBe("/about/es");
+  });
+
+  it("strips no prefix when no locale is enabled", () => {
+    expect(normalizeRoutePath("/es/about", [])).toBe("/es/about");
+  });
+});
+
+describe("isClosingFooterPath (#7797)", () => {
+  const paths = ["/about", "/services/first-engagement/"];
+
+  it.each([
+    "/about",
+    "/about/",
+    "/es/about",
+    "/es/about/",
+    "/services/first-engagement",
+  ])("%s is a listed page", (pathname) => {
+    expect(isClosingFooterPath({ pathname, paths, locales: LOCALES })).toBe(
+      true,
+    );
+  });
+
+  it.each(["/services", "/about/team", "/aboutus", "/privacy", "/es/contact"])(
+    "%s is not a listed page",
+    (pathname) => {
+      expect(isClosingFooterPath({ pathname, paths, locales: LOCALES })).toBe(
+        false,
+      );
+    },
+  );
+
+  it("matches a listed path spelled with a locale prefix or a trailing slash", () => {
+    expect(
+      isClosingFooterPath({
+        pathname: "/about",
+        paths: ["/es/about/"],
+        locales: LOCALES,
+      }),
+    ).toBe(true);
+  });
+
+  it("is false with no list, an empty list, or no pathname", () => {
+    expect(
+      isClosingFooterPath({
+        pathname: "/about",
+        paths: undefined,
+        locales: LOCALES,
+      }),
+    ).toBe(false);
+    expect(
+      isClosingFooterPath({ pathname: "/about", paths: [], locales: LOCALES }),
+    ).toBe(false);
+    expect(
+      isClosingFooterPath({ pathname: null, paths, locales: LOCALES }),
+    ).toBe(false);
+    expect(isClosingFooterPath({ pathname: "", paths, locales: LOCALES })).toBe(
+      false,
+    );
+  });
+
+  it("never selects the home, even when it is listed", () => {
+    for (const pathname of ["/", "/es", "/es/"]) {
+      expect(
+        isClosingFooterPath({ pathname, paths: ["/"], locales: LOCALES }),
+      ).toBe(false);
+    }
+  });
+});

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

@@ -11,6 +11,7 @@
 // Spec: docs/specs/7644-the-browser-talks-only-to-spec.md §5.1 AC-1 to AC-4.
 
 import { handleRelay, RELAY_ROUTES } from "../relay";
+import { __resetRelayRateLimit, __relayRateLimitBucketCount } from "../relay";
 
 const HUB = "https://hub.example";
 const SITE = "https://spoke.example";
@@ -124,6 +125,7 @@ function entryRequest(
 let errorSpy: jest.SpyInstance;
 
 beforeEach(() => {
+  __resetRelayRateLimit();
   fetchMock.mockClear();
   fetchMock.mockImplementation(async () => hubAnswer());
   global.fetch = fetchMock as jest.Mock;
@@ -513,3 +515,291 @@ describe("hardening — what the site serves, and a missing hub address", () =>
     });
   });
 });
+
+// The relay's own per-visitor rate limit (#7707, spec
+// docs/specs/7707-relay-rate-limit-spec.md §5.1 AC-1 to AC-9).
+describe("the per-visitor rate limit (#7707)", () => {
+  const VISITOR = { "x-forwarded-for": "203.0.113.7" };
+
+  /** Spends the first visitor's 8-call visitor budget, then clears fetchMock. */
+  async function spendVisitorBudget(
+    headers: Record<string, string | null> = VISITOR,
+  ): Promise<void> {
+    for (let i = 0; i < 8; i++) {
+      await handleRelay(relayRequest("/v1/leads/submit", { headers }));
+    }
+    fetchMock.mockClear();
+  }
+
+  describe("AC-1 — 8 forwarded, the 9th refused, on each visitor route", () => {
+    it.each(VISITOR_ENTRIES)(
+      "$method $path: first 8 calls forwarded, the 9th refused",
+      async (entry) => {
+        for (let i = 0; i < 8; i++) {
+          const res = await handleRelay(entryRequest(entry, VISITOR));
+          expect(res.status).not.toBe(429);
+        }
+        fetchMock.mockClear();
+
+        const res = await handleRelay(entryRequest(entry, VISITOR));
+        expect(res.status).toBe(429);
+        expect(await errorCode(res)).toBe("rate_limited");
+        expect(res.headers.get("retry-after")).toBe("600");
+        expect(res.headers.get("cache-control")).toBe("no-store");
+        expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+        expect(fetchMock).not.toHaveBeenCalled();
+      },
+    );
+  });
+
+  describe("AC-2 — the budget is shared across the five visitor routes", () => {
+    it("2 calls each to submit/subscribe/callback/availability, then book is refused", async () => {
+      const shared = VISITOR_ENTRIES.slice(0, 4);
+      for (const entry of shared) {
+        for (let i = 0; i < 2; i++) {
+          const res = await handleRelay(entryRequest(entry, VISITOR));
+          expect(res.status).not.toBe(429);
+        }
+      }
+      const book = VISITOR_ENTRIES[4];
+      if (!book) throw new Error("expected a fifth visitor entry");
+      const res = await handleRelay(entryRequest(book, VISITOR));
+      expect(res.status).toBe(429);
+    });
+  });
+
+  describe("AC-3 — the budget applies with and without AILK_VISITOR_FORWARD_KEY", () => {
+    const FORWARD_KEY_32 = "f".repeat(32);
+
+    it.each([
+      ["unset", undefined],
+      ["set", FORWARD_KEY_32],
+    ])("forward key %s: still 8 forwarded then refused", async (_label, key) => {
+      if (key) process.env.AILK_VISITOR_FORWARD_KEY = key;
+      else delete process.env.AILK_VISITOR_FORWARD_KEY;
+
+      await spendVisitorBudget();
+      const res = await handleRelay(relayRequest("/v1/leads/submit", { headers: VISITOR }));
+      expect(res.status).toBe(429);
+      expect(fetchMock).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("AC-4 — identity", () => {
+    it("a different visitor IP is forwarded", async () => {
+      await spendVisitorBudget();
+      const res = await handleRelay(
+        relayRequest("/v1/leads/submit", {
+          headers: { "x-forwarded-for": "198.51.100.9" },
+        }),
+      );
+      expect(res.status).not.toBe(429);
+    });
+
+    it("the first value of a multi-hop x-forwarded-for is the identity", async () => {
+      await spendVisitorBudget();
+      const res = await handleRelay(
+        relayRequest("/v1/leads/submit", {
+          headers: { "x-forwarded-for": "203.0.113.7, 10.0.0.1" },
+        }),
+      );
+      expect(res.status).toBe(429);
+    });
+
+    it("an IPv4-mapped IPv6 address maps to its IPv4 identity", async () => {
+      await spendVisitorBudget();
+      const res = await handleRelay(
+        relayRequest("/v1/leads/submit", {
+          headers: { "x-forwarded-for": "::ffff:203.0.113.7" },
+        }),
+      );
+      expect(res.status).toBe(429);
+    });
+
+    it("x-real-ip alone resolves to the same identity as x-forwarded-for", async () => {
+      await spendVisitorBudget();
+      const res = await handleRelay(
+        relayRequest("/v1/leads/submit", {
+          headers: { "x-forwarded-for": null, "x-real-ip": "203.0.113.7" },
+        }),
+      );
+      expect(res.status).toBe(429);
+    });
+
+    it("an IPv6 /64 prefix is one identity", async () => {
+      await spendVisitorBudget({ "x-forwarded-for": "2001:db8:0:0::1" });
+
+      const blocked = await handleRelay(
+        relayRequest("/v1/leads/submit", {
+          headers: { "x-forwarded-for": "2001:db8::2" },
+        }),
+      );
+      expect(blocked.status).toBe(429);
+
+      const forwarded = await handleRelay(
+        relayRequest("/v1/leads/submit", {
+          headers: { "x-forwarded-for": "2001:db8:0:1::1" },
+        }),
+      );
+      expect(forwarded.status).not.toBe(429);
+    });
+
+    it("an unparseable address shares the unknown identity with no address at all", async () => {
+      await spendVisitorBudget({ "x-forwarded-for": null, "x-real-ip": null });
+      const res = await handleRelay(
+        relayRequest("/v1/leads/submit", {
+          headers: { "x-forwarded-for": "not-an-ip" },
+        }),
+      );
+      expect(res.status).toBe(429);
+    });
+  });
+
+  describe("AC-5 — the window resets after windowMs", () => {
+    it("refused just before the window ends, forwarded once it does", async () => {
+      const T0 = Date.now();
+      const nowSpy = jest.spyOn(Date, "now").mockReturnValue(T0);
+
+      await spendVisitorBudget();
+      const stillBlocked = await handleRelay(
+        relayRequest("/v1/leads/submit", { headers: VISITOR }),
+      );
+      expect(stillBlocked.status).toBe(429);
+
+      nowSpy.mockReturnValue(T0 + 599_000);
+      const almostThere = await handleRelay(
+        relayRequest("/v1/leads/submit", { headers: VISITOR }),
+      );
+      expect(almostThere.status).toBe(429);
+      expect(almostThere.headers.get("retry-after")).toBe("1");
+
+      nowSpy.mockReturnValue(T0 + 600_000);
+      const freshWindow = await handleRelay(
+        relayRequest("/v1/leads/submit", { headers: VISITOR }),
+      );
+      expect(freshWindow.status).not.toBe(429);
+
+      nowSpy.mockRestore();
+    });
+  });
+
+  describe("AC-6 — refusals before the budget check spend nothing", () => {
+    it("403s, 404s and 508s before the budget check don't consume it", async () => {
+      for (let i = 0; i < 12; i++) {
+        const res = await handleRelay(
+          relayRequest("/v1/leads/submit", {
+            headers: { ...VISITOR, "sec-fetch-site": "cross-site" },
+          }),
+        );
+        expect(res.status).toBe(403);
+      }
+      for (let i = 0; i < 12; i++) {
+        const res = await handleRelay(
+          relayRequest("/v1/workspaces", { method: "POST", headers: VISITOR }),
+        );
+        expect(res.status).toBe(404);
+      }
+      for (let i = 0; i < 12; i++) {
+        const res = await handleRelay(
+          relayRequest("/v1/leads/submit", {
+            headers: { ...VISITOR, "x-ailk-relayed": "1" },
+          }),
+        );
+        expect(res.status).toBe(508);
+      }
+
+      fetchMock.mockClear();
+      for (let i = 0; i < 8; i++) {
+        const res = await handleRelay(
+          relayRequest("/v1/leads/submit", { headers: VISITOR }),
+        );
+        expect(res.status).not.toBe(429);
+      }
+      expect(fetchMock).toHaveBeenCalledTimes(8);
+    });
+  });
+
+  describe("AC-7 — the budget check precedes content-type and body-size checks", () => {
+    it("a 9th call with a bad content-type gets 429, not 415", async () => {
+      await spendVisitorBudget();
+      const res = await handleRelay(
+        relayRequest("/v1/leads/submit", {
+          headers: { ...VISITOR, "content-type": "text/plain" },
+        }),
+      );
+      expect(res.status).toBe(429);
+    });
+
+    it("a 9th call with an oversized body gets 429, not 413", async () => {
+      await spendVisitorBudget();
+      const res = await handleRelay(
+        relayRequest("/v1/leads/submit", {
+          headers: VISITOR,
+          body: "x".repeat(1_048_577),
+        }),
+      );
+      expect(res.status).toBe(429);
+    });
+  });
+
+  describe("AC-8 — the session route has its own, wider, independent budget", () => {
+    it("30 forwarded, the 31st refused; the visitor budget is untouched", async () => {
+      for (let i = 0; i < 30; i++) {
+        const res = await handleRelay(
+          relayRequest("/v1/commerce/invoices", { headers: VISITOR }),
+        );
+        expect(res.status).not.toBe(429);
+      }
+      fetchMock.mockClear();
+
+      const refused = await handleRelay(
+        relayRequest("/v1/commerce/invoices", { headers: VISITOR }),
+      );
+      expect(refused.status).toBe(429);
+      expect(refused.headers.get("retry-after")).toBe("600");
+      expect(fetchMock).not.toHaveBeenCalled();
+
+      const stillVisitor = await handleRelay(
+        relayRequest("/v1/leads/submit", { headers: VISITOR }),
+      );
+      expect(stillVisitor.status).not.toBe(429);
+    });
+
+    it("a fresh visitor's visitor budget doesn't touch the session budget", async () => {
+      const OTHER = { "x-forwarded-for": "198.51.100.42" };
+      for (let i = 0; i < 8; i++) {
+        await handleRelay(relayRequest("/v1/leads/submit", { headers: OTHER }));
+      }
+      const res = await handleRelay(
+        relayRequest("/v1/commerce/invoices", { headers: OTHER }),
+      );
+      expect(res.status).not.toBe(429);
+    });
+  });
+
+  describe("AC-9 — the store is capped and evicts the oldest entry first", () => {
+    it(
+      "the first visitor's bucket is evicted at capacity, so its next call opens a fresh window",
+      async () => {
+        await spendVisitorBudget();
+        for (let i = 0; i < 10_000; i++) {
+          const ip = `10.${(i >> 16) & 0xff}.${(i >> 8) & 0xff}.${i & 0xff}`;
+          await handleRelay(
+            relayRequest("/v1/leads/submit", {
+              headers: { "x-forwarded-for": ip },
+            }),
+          );
+        }
+        expect(__relayRateLimitBucketCount()).toBe(10_000);
+
+        fetchMock.mockClear();
+        const res = await handleRelay(
+          relayRequest("/v1/leads/submit", { headers: VISITOR }),
+        );
+        expect(res.status).not.toBe(429);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+      },
+      30_000,
+    );
+  });
+});