create-ailk 0.27.0 → 0.28.0

package/templates/apps/web/app/llms.txt/route.ts

@@ -19,14 +19,30 @@
  * `getBlogPages` deps — tests inject stubs, and the module's variant of this
  * route supplies the real `blogSource` reader. The exported `GET` is
  * unchanged either way.
+ *
+ * Docs (#10041 D8): listed after the blog at the site's docs path. Under the
+ * database adapter the adapter's `DocsList` / `DocsDetail` rows are listed at
+ * the docs path; otherwise those rows are skipped (the MDX docs route never
+ * serves them) and the docs directory is listed (`getDocsPages`, default
+ * `listDocsPages`).
  */
 
-import { SCHEMA_ORG_TYPES } from "@working-theory/content-adapters";
+import {
+  SCHEMA_ORG_TYPES,
+  resolvedAdapterKind,
+} from "@working-theory/content-adapters";
 import type { ContentAdapter, SchemaOrgType } from "@working-theory/content-adapters";
 import { getContentAdapter as defaultGetContentAdapter } from "@working-theory/page-renderer";
 
+import {
+  adapterDocsUrl,
+  isDocsType,
+  listDocsPages,
+  type DocsIndexPage,
+} from "../../lib/docs-index";
+import { PUBLIC_PAGES } from "../../lib/modules.generated";
 import { SITE_NAME } from "../../lib/site-brand";
-import { resolveBaseUrl, slugToPath } from "../../src/lib/routes";
+import { pagePathFor, resolveBaseUrl } from "../../src/lib/routes";
 
 export interface LlmsHandlerDeps {
   /**
@@ -40,6 +56,8 @@ export interface LlmsHandlerDeps {
    * Override in tests to inject stub pages.
    */
   getBlogPages?: () => Array<{ url: string; data: { title: string; description?: string } }>;
+  /** The docs pages (#10041). Defaults to `listDocsPages` over this app's docs directory. */
+  getDocsPages?: () => DocsIndexPage[];
 }
 
 /**
@@ -49,8 +67,11 @@ export interface LlmsHandlerDeps {
 export function createLlmsHandler(deps: LlmsHandlerDeps = {}) {
   const resolveAdapter = deps.getContentAdapter ?? defaultGetContentAdapter;
   const resolveBlogPages = deps.getBlogPages ?? (() => []);
+  const resolveDocsPages = deps.getDocsPages ?? listDocsPages;
 
   return async function llmsGET(): Promise<Response> {
+    // #10040 decision 7 — no public page, no content index: 404 before the adapter.
+    if (!PUBLIC_PAGES) return new Response(null, { status: 404 });
     const adapter = resolveAdapter();
     const baseUrl = resolveBaseUrl();
     const lines: string[] = [`# ${SITE_NAME} — content index`, ""];
@@ -66,9 +87,13 @@ export function createLlmsHandler(deps: LlmsHandlerDeps = {}) {
       types.map((type) => adapter.listPages(type, defaultLocale)),
     );
 
+    const databaseDocs = resolvedAdapterKind() === "database";
     for (const pages of pageLists) {
       for (const page of pages) {
-        const path = slugToPath(page.type, page.slug);
+        if (isDocsType(page.type) && !databaseDocs) continue;
+        const path = isDocsType(page.type)
+          ? adapterDocsUrl(page.type, page.slug)
+          : pagePathFor(page);
         const url = `${baseUrl}${path}`;
         lines.push(`- Title: ${page.title}`);
         lines.push(`  URL: ${url}`);
@@ -92,6 +117,19 @@ export function createLlmsHandler(deps: LlmsHandlerDeps = {}) {
       lines.push("");
     }
 
+    // The docs directory (#10041 D8) — not under the database adapter, whose
+    // docs rows are listed above.
+    if (!databaseDocs) {
+      for (const doc of resolveDocsPages()) {
+        lines.push(`- Title: ${doc.title}`);
+        lines.push(`  URL: ${baseUrl}${doc.url}`);
+        if (doc.description) {
+          lines.push(`  Description: ${doc.description}`);
+        }
+        lines.push("");
+      }
+    }
+
     return new Response(lines.join("\n"), {
       status: 200,
       headers: {

package/templates/apps/web/app/robots.txt/route.ts

@@ -15,12 +15,16 @@
 
 import { parseStealth } from "@working-theory/web-i18n/stealth";
 
+import { PUBLIC_PAGES } from "../../lib/modules.generated";
 import { resolveBaseUrl } from "../../src/lib/routes";
 
 export function GET(): Response {
   const baseUrl = resolveBaseUrl();
   const disallowEnv = process.env["AILK_ROBOTS_DISALLOW"] ?? "";
-  const stealth = parseStealth(process.env["STEALTH"]);
+  // #10040 decision 7 — a site with neither marketing nor docs-blog (a hub)
+  // has no public page to crawl: the same disallow-all, no-Sitemap shape as
+  // STEALTH, read from the module list, never from a setting.
+  const stealth = parseStealth(process.env["STEALTH"]) || !PUBLIC_PAGES;
 
   const disallowPaths = stealth
     ? ["/"]

package/templates/apps/web/app/sitemap.xml/route.ts

@@ -28,13 +28,30 @@
  * DI note: `createSitemapHandler` accepts an optional `getContentAdapter` dep
  * for testing — tests inject a stub adapter to avoid mocking the internal module.
  * The exported `GET` uses the real implementation.
+ *
+ * Docs (#10041 D8): the docs are listed at the site's docs path, default
+ * locale only, with no alternates (they exist in one locale). Under the
+ * database adapter the docs route reads the adapter's `DocsList` /
+ * `DocsDetail` rows, so those rows are listed at the docs path; otherwise
+ * those rows are skipped (the MDX docs route never serves them) and the docs
+ * directory is listed instead (`getDocsPages`, default `listDocsPages`).
  */
 
-import { SCHEMA_ORG_TYPES } from "@working-theory/content-adapters";
+import {
+  SCHEMA_ORG_TYPES,
+  resolvedAdapterKind,
+} from "@working-theory/content-adapters";
 import type { ContentAdapter, SchemaOrgType } from "@working-theory/content-adapters";
 import { getContentAdapter as defaultGetContentAdapter } from "@working-theory/page-renderer";
 
-import { resolveBaseUrl, slugToPath } from "../../src/lib/routes";
+import {
+  adapterDocsUrl,
+  isDocsType,
+  listDocsPages,
+  type DocsIndexPage,
+} from "../../lib/docs-index";
+import { PUBLIC_PAGES } from "../../lib/modules.generated";
+import { pagePathFor, resolveBaseUrl } from "../../src/lib/routes";
 
 export interface SitemapHandlerDeps {
   /**
@@ -42,6 +59,8 @@ export interface SitemapHandlerDeps {
    * Override in tests to inject a stub adapter without mocking the internal module.
    */
   getContentAdapter?: () => ContentAdapter;
+  /** The docs pages (#10041). Defaults to `listDocsPages` over this app's docs directory. */
+  getDocsPages?: () => DocsIndexPage[];
 }
 
 function escapeXml(value: string): string {
@@ -76,7 +95,10 @@ function buildLocaleUrl(
  */
 export function createSitemapHandler(deps: SitemapHandlerDeps = {}) {
   const resolveAdapter = deps.getContentAdapter ?? defaultGetContentAdapter;
+  const resolveDocsPages = deps.getDocsPages ?? listDocsPages;
   return async function sitemapGET(): Promise<Response> {
+    // #10040 decision 7 — no public page, no sitemap: 404 before the adapter.
+    if (!PUBLIC_PAGES) return new Response(null, { status: 404 });
     const adapter = resolveAdapter();
     const baseUrl = resolveBaseUrl();
     const today = new Date().toISOString().slice(0, 10);
@@ -87,6 +109,13 @@ export function createSitemapHandler(deps: SitemapHandlerDeps = {}) {
     const defaultLocale = process.env.NEXT_PUBLIC_DEFAULT_LOCALE ?? "en";
 
     const urlEntries: string[] = [];
+    // A docs entry: one locale, so no alternates (#10041 D8).
+    const pushDocsEntry = (url: string, lastmod: string): void => {
+      urlEntries.push(
+        `  <url>\n    <loc>${escapeXml(`${baseUrl}${url}`)}</loc>\n    <lastmod>${lastmod}</lastmod>\n  </url>`,
+      );
+    };
+    const databaseDocs = resolvedAdapterKind() === "database";
 
     const types = SCHEMA_ORG_TYPES as readonly SchemaOrgType[];
 
@@ -104,7 +133,16 @@ export function createSitemapHandler(deps: SitemapHandlerDeps = {}) {
     for (let i = 0; i < tuples.length; i++) {
       const { locale } = tuples[i]!;
       for (const page of lists[i]!) {
-        const path = slugToPath(page.type, page.slug);
+        if (isDocsType(page.type)) {
+          if (databaseDocs && locale === defaultLocale) {
+            pushDocsEntry(
+              adapterDocsUrl(page.type, page.slug),
+              page.publishedAt ?? today,
+            );
+          }
+          continue;
+        }
+        const path = pagePathFor(page);
         const lastmod = page.publishedAt ?? today;
 
         const defaultUrl = `${baseUrl}${path}`;
@@ -126,6 +164,10 @@ export function createSitemapHandler(deps: SitemapHandlerDeps = {}) {
       }
     }
 
+    if (!databaseDocs) {
+      for (const doc of resolveDocsPages()) pushDocsEntry(doc.url, today);
+    }
+
     const xml = [
       '<?xml version="1.0" encoding="UTF-8"?>',
       '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">',

package/templates/apps/web/auth.ts

@@ -43,6 +43,7 @@ import {
   isSignUpOpen,
   resetSendConfigured,
 } from "./lib/auth-env";
+import { resolveSecret } from "./lib/auth-secret";
 import {
   signUpAgreementHooks,
   signUpAgreementsPlugin,
@@ -181,55 +182,102 @@ function buildSocialProviders(): SocialProviders {
   return providers;
 }
 
+// `resolveSecret()` lives in `lib/auth-secret.ts` (#8556) so the consent
+// visitor id can be signed without loading Better Auth; re-exported here for
+// every caller that already imports it from this module.
+export { resolveSecret };
+
+/** A loopback host, where `http:` is the only scheme a local site has. */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
 /**
- * Resolve the secret used to sign session cookies AND — since #5962 § D9 — the
- * email-verification JWTs.
- *
- * THROWS in production when BETTER_AUTH_SECRET is unset (§ D16). Better Auth's
- * own `validateSecret` throws only when the secret equals ITS default; this
- * repo's literal is a different string, so it cleared that check and produced
- * nothing but a low-entropy warning — while sitting in a repository whose
- * `oss`-tier tree ships publicly. Anyone who can read this file could forge
- * both a session cookie and a verification token on any deployment that
- * omitted the variable.
- *
- * This changes boot behaviour: a production deployment with no
- * BETTER_AUTH_SECRET boots today and does not after this. That is the correct
- * failure — a site signing sessions with a published string is not usefully
- * "up" — and `apps/web/.env.example` has always documented the variable as
- * REQUIRED in production. The change makes the file honest rather than adding
- * a requirement.
+ * Resolve Better Auth's `baseURL` — and so the one trusted origin — from
+ * BETTER_AUTH_URL (#8620, #9965 D10), modelled on `resolveSecret()`.
  *
- * Exported (#8146 D5) so the hub's sign-in continuation seals its ref under the
- * same resolved secret instead of re-reading the variable: the second consumer
- * after `betterAuth({ secret })`.
+ * Unset, Better Auth derives the base URL from each REQUEST's own host (the
+ * § D13 account-takeover chain), so a production process that is about to
+ * answer requests THROWS without one, as it does without the secret. There
+ * the value must be an `https:` URL, or `http:` on a loopback host; anything
+ * else counts as unset. The build phase and development read it as before —
+ * as set, or `undefined` — so `resetSendConfigured()`'s raw read still
+ * agrees with it. create-ailk writes a loopback value beside the secret, so a
+ * fresh scaffold's `next start` boots; a production process serving on one
+ * WARNS, because an `http:` base URL also drops the session cookie's
+ * `Secure` flag and points every emailed link at this machine.
  */
-export function resolveSecret(): string {
-  const configured = process.env.BETTER_AUTH_SECRET;
-  if (configured) return configured;
-
-  // SERVING, not BUILDING. `next build` collects page data with
-  // NODE_ENV=production, and that evaluates `app/api/auth/[...all]/route.ts`,
-  // which resolves the lazy `auth` proxy — so an unqualified production throw
-  // fails the BUILD of any tree that has not set the variable. That is much
-  // broader than the risk: a build produces an artifact, it does not serve a
-  // session, and it would break CI, preview builds, and `pnpm build` on a
-  // freshly scaffolded site that has not configured auth at all.
-  //
-  // Next sets NEXT_PHASE to PHASE_PRODUCTION_BUILD ("phase-production-build")
-  // for the duration of the build, so excluding that phase keeps the guard
-  // exactly where it was aimed: a production process that is about to answer
-  // requests. Such a process still throws on the first access to `auth`, which
-  // is the intended failure — a site signing sessions with a string published
-  // in this repository is not usefully "up".
+function resolveBaseURL(): string | undefined {
+  const configured = process.env.BETTER_AUTH_URL;
   const isBuildPhase = process.env.NEXT_PHASE === "phase-production-build";
-  if (process.env.NODE_ENV === "production" && !isBuildPhase) {
-    throw new Error(
-      "BETTER_AUTH_SECRET is required in production: it signs session cookies and email-verification tokens, and the development fallback is published in this repository.",
-    );
+  const serving = process.env.NODE_ENV === "production" && !isBuildPhase;
+  const url = configured ? trustableBaseURL(configured) : undefined;
+  if (url) {
+    if (serving && url.protocol === "http:") {
+      console.warn(
+        `BETTER_AUTH_URL is the loopback ${url.origin} in production: session cookies are not Secure and emailed links point at this machine. Set it to the site's public https: origin.`,
+      );
+    }
+    return configured;
   }
 
-  return "ailk-dev-fallback-secret-published-in-this-repo-never-use-in-production";
+  if (!serving) return configured || undefined;
+  throw new Error(
+    "BETTER_AUTH_URL is required in production: it is the origin Better Auth builds callbacks and emailed links on, and must be an https: URL (http: only on a loopback host).",
+  );
+}
+
+/** `value` parsed, when it is `https:` or `http:` on a loopback host. */
+function trustableBaseURL(value: string): URL | undefined {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return undefined;
+  }
+  const trustable = url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname));
+  return trustable ? url : undefined;
+}
+
+/**
+ * The user-write hook (#8602, #9965 D6): a non-empty `image` must be an
+ * `http:` or `https:` URL, whatever the client checked. The users table is
+ * shared with the Admin's Better Auth, which applies the same rule, so a
+ * `javascript:` or `data:` value never reaches an `<img>` or a link. The
+ * refusal is code-shaped — no English string reaches a page.
+ */
+async function rejectNonHttpImage(user: { image?: unknown }): Promise<void> {
+  const { image } = user;
+  if (typeof image !== "string" || image === "") return;
+  let protocol: string | undefined;
+  try {
+    protocol = new URL(image).protocol;
+  } catch {
+    protocol = undefined;
+  }
+  if (protocol === "https:" || protocol === "http:") return;
+  const { APIError } = await import("better-auth/api");
+  throw new APIError("BAD_REQUEST", { code: "INVALID_IMAGE_URL", message: "INVALID_IMAGE_URL" });
+}
+
+/**
+ * The sign-up hooks, with the image check on every user write: on update, and
+ * on create (the sign-up endpoint accepts `image` too) ahead of the agreement
+ * hook.
+ */
+function databaseHooks(): ReturnType<typeof signUpAgreementHooks> {
+  const hooks = signUpAgreementHooks();
+  const createBefore = hooks.user?.create?.before;
+  return {
+    ...hooks,
+    user: {
+      create: {
+        before: async (user, context) => {
+          await rejectNonHttpImage(user);
+          return createBefore?.(user, context);
+        },
+      },
+      update: { before: rejectNonHttpImage },
+    },
+  };
 }
 
 /**
@@ -313,6 +361,11 @@ export function createAuth(deps: CreateAuthDeps = {}) {
    */
   const resetConfigured = resetSendConfigured();
 
+  // Resolved in this order so a production process missing both names the
+  // secret first, as it always has.
+  const secret = resolveSecret();
+  const baseURL = resolveBaseURL();
+
   /**
    * The emailed sign-in link (#7435 § D1). The SAME predicate `/sign-in` and
    * the `(authed)` gate read, so the form renders iff the endpoint exists.
@@ -461,11 +514,12 @@ export function createAuth(deps: CreateAuthDeps = {}) {
      * user carries agreements, the account hook writes them on the captured
      * transaction client. A magic-link sign-up creates no Account, so the
      * session hook writes its grants, in their own transaction, before the
-     * session exists (#9667 D5). No other database hook is installed.
+     * session exists (#9667 D5). The one other database hook refuses a
+     * non-http(s) image on user create and update (#9965 D6).
      */
-    databaseHooks: signUpAgreementHooks(),
-    secret: resolveSecret(),
-    baseURL: process.env.BETTER_AUTH_URL,
+    databaseHooks: databaseHooks(),
+    secret,
+    baseURL,
     socialProviders: buildSocialProviders(),
     /**
      * The emitted reset link's host and the `redirectTo` allow-list are
@@ -483,9 +537,7 @@ export function createAuth(deps: CreateAuthDeps = {}) {
      * `BETTER_AUTH_URL` is also a conjunct of `resetSendConfigured()`, so a
      * deployment that has not pinned its origin never offers reset at all.
      */
-    ...(process.env.BETTER_AUTH_URL
-      ? { trustedOrigins: [process.env.BETTER_AUTH_URL] }
-      : {}),
+    ...(baseURL ? { trustedOrigins: [baseURL] } : {}),
     emailAndPassword: {
       enabled: passwordMethodActive,
       // Turning the password method on also opens POST /sign-up/email —

package/templates/apps/web/components/signed-in-nav.tsx

@@ -23,11 +23,18 @@
 import { Nav, type NavProps } from "@working-theory/ui/chrome";
 import type { ReactElement } from "react";
 
+import { withPublicDocsPaths } from "../lib/docs-path";
 import { navItems } from "../lib/nav-config";
+import { withPublicServicesPaths } from "../lib/services-path";
 import { siteChrome } from "../lib/site-chrome";
 
 import { SignOutTrigger } from "./sign-out-trigger";
 
+// #10041 D10 — nav paths at `/docs` render at the site's docs path.
+// `docs-path.ts` imports nothing, so it is safe on this side of the boundary.
+// #10043 D9 — likewise nav paths at `/services`, from `services-path.ts`.
+const publicNavItems = withPublicServicesPaths(withPublicDocsPaths(navItems));
+
 /** Nav's props minus every function-typed one — this type IS the boundary. */
 export type SignedInNavProps = Omit<
   NavProps,
@@ -48,7 +55,7 @@ export function SignedInNav({
   return (
     <Nav
       {...props}
-      navItems={siteChrome.nav === "mark-only" ? [] : navItems}
+      navItems={siteChrome.nav === "mark-only" ? [] : publicNavItems}
       // Both signed-in actions are flows with no lightbox: Sign out becomes a
       // SignOutTrigger, the account action a non-navigating name label.
       renderFlowTrigger={(action, trigger) =>

package/templates/apps/web/lib/__tests__/bot-check.test.ts

@@ -0,0 +1,254 @@
+/**
+ * @jest-environment node
+ */
+// The spoke edge's one bot check (#9255, spec
+// docs/specs/9255-an-edge-bot-challenge-in-spec.md §5.1 AC-1, AC-4): the
+// shared verdict rule, its timeout, both switches and BotID's client list.
+
+import { BOT_CLIENT_PROTECT, botCheckOn, runBotCheck } from "../bot-check";
+
+// `checkBotId` reads Vercel's request context, which jest has none of, so
+// every case decides the verdict here.
+const checkBotIdMock = jest.fn();
+jest.mock("botid/server", () => ({
+  checkBotId: (...args: unknown[]) => checkBotIdMock(...args),
+}));
+
+const BOT = {
+  isHuman: false,
+  isBot: true,
+  isVerifiedBot: false,
+  bypassed: false,
+};
+const HUMAN = { ...BOT, isHuman: true, isBot: false };
+
+const ENV_KEYS = [
+  "VERCEL",
+  "AILK_BOT_CHECK",
+  "AILK_BOOKING_BOT_CHECK",
+] as const;
+const priorEnv = new Map<string, string | undefined>(
+  ENV_KEYS.map((name) => [name, process.env[name]]),
+);
+
+const CHECK = {
+  source: "bot-check",
+  target: "testAction",
+  scope: "write",
+} as const;
+
+let errorSpy: jest.SpyInstance;
+let warnSpy: jest.SpyInstance;
+
+beforeEach(() => {
+  checkBotIdMock.mockReset();
+  for (const name of ENV_KEYS) delete process.env[name];
+  process.env.VERCEL = "1";
+  errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+  warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  errorSpy.mockRestore();
+  warnSpy.mockRestore();
+});
+
+afterAll(() => {
+  for (const [name, value] of priorEnv) {
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+});
+
+describe("AC-1 — runBotCheck's verdict (#9889 D3, one rule for every write)", () => {
+  it("a human passes", async () => {
+    checkBotIdMock.mockResolvedValue(HUMAN);
+    expect(await runBotCheck(CHECK)).toBe("pass");
+    expect(checkBotIdMock).toHaveBeenCalledTimes(1);
+    expect(errorSpy).not.toHaveBeenCalled();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["a bot", BOT],
+    ["a verified bot", { ...BOT, isVerifiedBot: true }],
+  ])(
+    "%s is bot, logged with the target and no detail",
+    async (_label, verdict) => {
+      checkBotIdMock.mockResolvedValue(verdict);
+      expect(await runBotCheck(CHECK)).toBe("bot");
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledWith("[bot-check] bot refused", {
+        path: "testAction",
+        outcome: "bot-detected",
+      });
+    },
+  );
+
+  function expectUnavailableLog(error: string): void {
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    expect(errorSpy).toHaveBeenCalledWith("[bot-check] bot check failed", {
+      path: "testAction",
+      outcome: "bot-check-failed",
+      error,
+    });
+  }
+
+  it("a throw is unavailable, logging the error's name, never its message", async () => {
+    checkBotIdMock.mockRejectedValue(new Error("token abc"));
+    expect(await runBotCheck(CHECK)).toBe("unavailable");
+    expectUnavailableLog("Error");
+    expect(JSON.stringify(errorSpy.mock.calls)).not.toContain("token abc");
+  });
+
+  it.each([
+    ["an empty verdict", {}],
+    ["a non-boolean isBot", { ...HUMAN, isBot: "false" }],
+  ])("%s is unavailable (InvalidVerdictError)", async (_label, verdict) => {
+    checkBotIdMock.mockResolvedValue(verdict);
+    expect(await runBotCheck(CHECK)).toBe("unavailable");
+    expectUnavailableLog("InvalidVerdictError");
+  });
+
+  describe("with fake timers", () => {
+    beforeEach(() => {
+      jest.useFakeTimers({
+        doNotFake: ["nextTick", "queueMicrotask", "setImmediate"],
+      });
+    });
+    afterEach(() => {
+      jest.useRealTimers();
+    });
+
+    it("no verdict within 5 000 ms is unavailable (TimeoutError)", async () => {
+      checkBotIdMock.mockReturnValue(new Promise(() => {}));
+      const pending = runBotCheck(CHECK);
+      await jest.advanceTimersByTimeAsync(5_000);
+      expect(await pending).toBe("unavailable");
+      expectUnavailableLog("TimeoutError");
+    });
+
+    it("a verdict in time leaves no timer pending", async () => {
+      checkBotIdMock.mockResolvedValue(BOT);
+      expect(await runBotCheck(CHECK)).toBe("bot");
+      expect(jest.getTimerCount()).toBe(0);
+    });
+  });
+
+  it("off Vercel it passes without asking BotID", async () => {
+    delete process.env.VERCEL;
+    checkBotIdMock.mockResolvedValue(BOT);
+    expect(await runBotCheck(CHECK)).toBe("pass");
+    expect(checkBotIdMock).not.toHaveBeenCalled();
+  });
+
+  it("AILK_BOT_CHECK=off passes the booking too, without asking BotID", async () => {
+    process.env.AILK_BOT_CHECK = "off";
+    checkBotIdMock.mockResolvedValue(BOT);
+    expect(await runBotCheck({ ...CHECK, scope: "booking" })).toBe("pass");
+    expect(checkBotIdMock).not.toHaveBeenCalled();
+  });
+
+  describe("in production, off Vercel", () => {
+    const env = process.env as Record<string, string | undefined>;
+    const priorNodeEnv = env.NODE_ENV;
+    beforeEach(() => {
+      env.NODE_ENV = "production";
+      delete process.env.VERCEL;
+    });
+    afterEach(() => {
+      env.NODE_ENV = priorNodeEnv;
+    });
+
+    async function twoChecks(scope: "write" | "booking"): Promise<void> {
+      await jest.isolateModulesAsync(async () => {
+        const fresh = await import("../bot-check");
+        for (let i = 0; i < 2; i++) {
+          expect(await fresh.runBotCheck({ ...CHECK, scope })).toBe("pass");
+        }
+      });
+    }
+
+    it("warns once per process that the check is not running", async () => {
+      await twoChecks("write");
+      expect(checkBotIdMock).not.toHaveBeenCalled();
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[relay] booking bot check inactive",
+        { outcome: "not-on-vercel" },
+      );
+    });
+
+    it("with AILK_BOT_CHECK=off, warns nothing", async () => {
+      process.env.AILK_BOT_CHECK = "off";
+      await twoChecks("write");
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it("with AILK_BOOKING_BOT_CHECK=off, the booking warns nothing", async () => {
+      process.env.AILK_BOOKING_BOT_CHECK = "off";
+      await twoChecks("booking");
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+  });
+});
+
+describe("AC-4 — the switches and BotID's client list", () => {
+  it.each(["off", " OFF "])(
+    "AILK_BOT_CHECK=%j turns every check off",
+    (value) => {
+      process.env.AILK_BOT_CHECK = value;
+      expect(botCheckOn("write")).toBe(false);
+      expect(botCheckOn("booking")).toBe(false);
+    },
+  );
+
+  it("AILK_BOOKING_BOT_CHECK=off turns the booking's alone off", () => {
+    process.env.AILK_BOOKING_BOT_CHECK = "off";
+    expect(botCheckOn("write")).toBe(true);
+    expect(botCheckOn("booking")).toBe(false);
+  });
+
+  it.each([
+    ["AILK_BOT_CHECK", "on"],
+    ["AILK_BOT_CHECK", "0"],
+    ["AILK_BOOKING_BOT_CHECK", "on"],
+    ["AILK_BOOKING_BOT_CHECK", "0"],
+  ])("%s=%s leaves both on", (name, value) => {
+    process.env[name] = value;
+    expect(botCheckOn("write")).toBe(true);
+    expect(botCheckOn("booking")).toBe(true);
+  });
+
+  it("off Vercel both are off", () => {
+    delete process.env.VERCEL;
+    expect(botCheckOn("write")).toBe(false);
+    expect(botCheckOn("booking")).toBe(false);
+  });
+
+  it("BOT_CLIENT_PROTECT is every same-origin POST, frozen", () => {
+    expect(BOT_CLIENT_PROTECT).toEqual([{ path: "/*", method: "POST" }]);
+    expect(Object.isFrozen(BOT_CLIENT_PROTECT)).toBe(true);
+  });
+
+  // `botid/client/core`'s own rule: escape the regex characters, `*` → `.*`,
+  // anchored.
+  function compileBotIdPath(path: string): RegExp {
+    const body = path
+      .replace(/[.?+^$[\]\\(){}|-]/g, "\\$&")
+      .split("*")
+      .join(".*");
+    return new RegExp(`^${body}$`);
+  }
+
+  it.each([
+    "/",
+    "/contact",
+    "/fr/flows/quiz/results/abc",
+    "/v1/leads/submit",
+    "/v1/schedule/book",
+  ])("its path matches %s", (pathname) => {
+    const [entry] = BOT_CLIENT_PROTECT;
+    expect(compileBotIdPath(entry?.path ?? "").test(pathname)).toBe(true);
+  });
+});