create-ailk 0.19.0 → 0.20.0

package/templates/apps/web/lib/__tests__/consent-visitor.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Tests for consent-visitor.ts (the `ailk-vid` cookie helpers) and for
+ * `acceptCookiesAction`/`declineCookiesAction` (#8438 D12,
+ * `app/[locale]/consent.actions.ts`) — the banner's one write path.
+ */
+import {
+  consentVisitorHeader,
+  ensureConsentVisitor,
+  isValidConsentVisitorId,
+  readConsentVisitor,
+  readConsentVisitorFromCookieHeader,
+} from "../consent-visitor";
+
+const VALID_ID = "11111111-2222-4333-8444-555555555555";
+
+describe("isValidConsentVisitorId", () => {
+  it.each([VALID_ID, "aaaaaaaa-bbbb-4ccc-9ddd-eeeeeeeeeeee"])("%s is a valid v4 UUID", (id) => {
+    expect(isValidConsentVisitorId(id)).toBe(true);
+  });
+
+  it.each([
+    "",
+    "not-a-uuid",
+    "11111111-2222-3333-8444-555555555555", // version nibble is 3, not 4
+    "11111111-2222-4333-c444-555555555555", // variant nibble is c, not 8/9/a/b
+    `${VALID_ID} `,
+  ])("%j is not", (value) => {
+    expect(isValidConsentVisitorId(value)).toBe(false);
+  });
+});
+
+describe("readConsentVisitor", () => {
+  it("returns the cookie's value when it is a valid id", () => {
+    const cookies = { get: () => ({ value: VALID_ID }) };
+    expect(readConsentVisitor(cookies)).toBe(VALID_ID);
+  });
+
+  it("returns undefined with no cookie, or an invalid value", () => {
+    expect(readConsentVisitor({ get: () => undefined })).toBeUndefined();
+    expect(readConsentVisitor({ get: () => ({ value: "nope" }) })).toBeUndefined();
+  });
+});
+
+describe("ensureConsentVisitor", () => {
+  it("keeps an existing valid id and sets nothing", () => {
+    const set = jest.fn();
+    const cookies = { get: () => ({ value: VALID_ID }), set };
+    expect(ensureConsentVisitor(cookies)).toBe(VALID_ID);
+    expect(set).not.toHaveBeenCalled();
+  });
+
+  it("mints and sets a fresh v4 UUID when absent", () => {
+    const set = jest.fn();
+    const cookies = { get: () => undefined, set };
+    const id = ensureConsentVisitor(cookies);
+    expect(isValidConsentVisitorId(id)).toBe(true);
+    expect(set).toHaveBeenCalledTimes(1);
+    const [name, value, options] = set.mock.calls[0] as [string, string, Record<string, unknown>];
+    expect(name).toBe("ailk-vid");
+    expect(value).toBe(id);
+    expect(options).toMatchObject({ httpOnly: true, sameSite: "lax", path: "/" });
+  });
+
+  it("mints a fresh id when the stored value fails the UUID shape", () => {
+    const set = jest.fn();
+    const cookies = { get: () => ({ value: "garbage" }), set };
+    const id = ensureConsentVisitor(cookies);
+    expect(id).not.toBe("garbage");
+    expect(set).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("consentVisitorHeader", () => {
+  it("returns the one header, exactly", () => {
+    expect(consentVisitorHeader(VALID_ID)).toEqual({ "x-ailk-consent-visitor": VALID_ID });
+  });
+});
+
+describe("readConsentVisitorFromCookieHeader", () => {
+  it("reads the id out of a raw Cookie header", () => {
+    expect(readConsentVisitorFromCookieHeader(`ailk-vid=${VALID_ID}`)).toBe(VALID_ID);
+    expect(readConsentVisitorFromCookieHeader(`session=abc; ailk-vid=${VALID_ID}; other=1`)).toBe(VALID_ID);
+  });
+
+  it("returns undefined with no header, no matching cookie, or an invalid value", () => {
+    expect(readConsentVisitorFromCookieHeader(null)).toBeUndefined();
+    expect(readConsentVisitorFromCookieHeader(undefined)).toBeUndefined();
+    expect(readConsentVisitorFromCookieHeader("session=abc")).toBeUndefined();
+    expect(readConsentVisitorFromCookieHeader("ailk-vid=garbage")).toBeUndefined();
+  });
+});
+
+// ── acceptCookiesAction / declineCookiesAction (D12) ──────────────────────
+
+const mockRecordCookieChoice = jest.fn();
+jest.mock("@working-theory/api-client", () => ({
+  __esModule: true,
+  consent: { recordCookieChoice: (...args: unknown[]) => mockRecordCookieChoice(...args) },
+  visitorForwardHeaders: () => undefined,
+}));
+
+const mockCookieGet = jest.fn();
+const mockCookieSet = jest.fn();
+jest.mock("next/headers", () => ({
+  __esModule: true,
+  cookies: jest.fn().mockImplementation(async () => ({
+    get: (...args: unknown[]) => mockCookieGet(...args),
+    set: (...args: unknown[]) => mockCookieSet(...args),
+  })),
+  headers: jest.fn().mockResolvedValue(new Headers()),
+}));
+
+jest.mock("next-intl/server", () => ({
+  __esModule: true,
+  getLocale: jest.fn().mockResolvedValue("en"),
+}));
+
+describe("acceptCookiesAction / declineCookiesAction", () => {
+  beforeEach(() => {
+    mockRecordCookieChoice.mockReset().mockResolvedValue({ ok: true, body: { recorded: true } });
+    mockCookieGet.mockReset().mockReturnValue(undefined);
+    mockCookieSet.mockReset();
+  });
+
+  it("mints a visitor id when absent and calls recordCookieChoice once, accepted", async () => {
+    const { acceptCookiesAction } = await import("../../app/[locale]/consent.actions");
+    await acceptCookiesAction();
+    expect(mockCookieSet).toHaveBeenCalledTimes(1);
+    expect(mockRecordCookieChoice).toHaveBeenCalledTimes(1);
+    const [body] = mockRecordCookieChoice.mock.calls[0] as [{ visitorId: string; choice: string; locale: string }];
+    expect(isValidConsentVisitorId(body.visitorId)).toBe(true);
+    expect(body.choice).toBe("accepted");
+    expect(body.locale).toBe("en");
+  });
+
+  it("keeps an existing visitor id and declines", async () => {
+    mockCookieGet.mockReturnValue({ value: VALID_ID });
+    const { declineCookiesAction } = await import("../../app/[locale]/consent.actions");
+    await declineCookiesAction();
+    expect(mockCookieSet).not.toHaveBeenCalled();
+    const [body] = mockRecordCookieChoice.mock.calls[0] as [{ visitorId: string; choice: string }];
+    expect(body.visitorId).toBe(VALID_ID);
+    expect(body.choice).toBe("declined");
+  });
+
+  it("resolves even when the client rejects", async () => {
+    mockRecordCookieChoice.mockRejectedValue(new TypeError("fetch failed"));
+    const { acceptCookiesAction } = await import("../../app/[locale]/consent.actions");
+    await expect(acceptCookiesAction()).resolves.toBeUndefined();
+  });
+
+  it("resolves even when the write is refused", async () => {
+    mockRecordCookieChoice.mockResolvedValue({ ok: false, status: 503, body: null });
+    const { acceptCookiesAction } = await import("../../app/[locale]/consent.actions");
+    await expect(acceptCookiesAction()).resolves.toBeUndefined();
+  });
+
+  it("never writes the ailk-consent cookie", async () => {
+    const { acceptCookiesAction } = await import("../../app/[locale]/consent.actions");
+    await acceptCookiesAction();
+    expect(mockCookieSet).not.toHaveBeenCalledWith("ailk-consent", expect.anything(), expect.anything());
+  });
+});

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

@@ -456,6 +456,55 @@ describe("AC-4 — the visitor, unchanged; a cross-site post, refused", () => {
   });
 });
 
+describe("the banner's visitor id (#8438 D12)", () => {
+  const VALID_ID = "11111111-2222-4333-8444-555555555555";
+  const LEAD_PATHS = ["/v1/leads/submit", "/v1/leads/subscribe", "/v1/leads/callback"];
+
+  it.each(LEAD_PATHS)(
+    "%s carries x-ailk-consent-visitor from the request's own ailk-vid cookie",
+    async (path) => {
+      await handleRelay(relayRequest(path, { headers: { cookie: `ailk-vid=${VALID_ID}` } }));
+      expect(sent().headers.get("x-ailk-consent-visitor")).toBe(VALID_ID);
+    },
+  );
+
+  it("sends no header when the request carries no ailk-vid cookie", async () => {
+    await handleRelay(relayRequest("/v1/leads/submit"));
+    expect(sent().headers.get("x-ailk-consent-visitor")).toBeNull();
+  });
+
+  it("sends no header when the cookie value fails the UUID shape", async () => {
+    await handleRelay(relayRequest("/v1/leads/submit", { headers: { cookie: "ailk-vid=not-a-uuid" } }));
+    expect(sent().headers.get("x-ailk-consent-visitor")).toBeNull();
+  });
+
+  it("the schedule route carries no consent-visitor header", async () => {
+    await handleRelay(
+      relayRequest("/v1/schedule/availability", {
+        method: "GET",
+        headers: { cookie: `ailk-vid=${VALID_ID}` },
+      }),
+    );
+    expect(sent().headers.get("x-ailk-consent-visitor")).toBeNull();
+  });
+
+  it("the session route carries no consent-visitor header", async () => {
+    await handleRelay(
+      relayRequest("/v1/commerce/invoices", { headers: { cookie: `ailk-vid=${VALID_ID}` } }),
+    );
+    expect(sent().headers.get("x-ailk-consent-visitor")).toBeNull();
+  });
+
+  it("a client-sent x-ailk-consent-visitor header is stripped — only the cookie counts", async () => {
+    await handleRelay(
+      relayRequest("/v1/leads/submit", {
+        headers: { "x-ailk-consent-visitor": "22222222-2222-4222-8222-222222222222" },
+      }),
+    );
+    expect(sent().headers.get("x-ailk-consent-visitor")).toBeNull();
+  });
+});
+
 describe("hardening — what the site serves, and a missing hub address", () => {
   const mediaType = (res: Response) =>
     res.headers.get("content-type")?.split(";")[0]?.trim();

package/templates/apps/web/lib/__tests__/structured-data.test.tsx

@@ -295,10 +295,25 @@ describe("structured data — every content page builds valid JSON-LD", () => {
  * exempt route whose page.tsx does render through `renderPage` fails too,
  * because the reason given for it is false.
  */
+// Literal, not imported: apps/web does not depend on create-ailk (the import
+// boundary). Mirrors packages/create-ailk/src/spoke-checkout.ts's
+// SPOKE_CHECKOUT_PAGE_MARKER; packages/create-ailk/__tests__/
+// spoke-checkout.test.ts pins the two in sync (#8513 AC-5).
+const CHECKOUT_PAGE_MARKER = "GENERATED by create-ailk (#7838)";
+const CHECKOUT_PAGE_NOINDEX_LINE = "robots: { index: false, follow: false }";
+
 const NO_STRUCTURED_DATA_ROUTES: ReadonlyArray<{
   route: string;
   reason: string;
   subtree?: true;
+  /**
+   * Strings the page file must carry for this entry to apply (#8513 D1). An
+   * entry naming no strings applies to its route unconditionally, as every
+   * entry did before. Keys the exemption on the file, not the topology seam:
+   * a spoke can carry a hand-written page at this route, and a site can
+   * edit the generated one — either is checked like any other route.
+   */
+  requires?: readonly string[];
 }> = [
   // Fumadocs routes: JSON-LD is emitted by @working-theory/fumadocs-schema
   // from the fumadocs `.source` collection, which is not built in this
@@ -349,6 +364,10 @@ const NO_STRUCTURED_DATA_ROUTES: ReadonlyArray<{
     subtree: true,
   },
   { route: "meet", reason: "booking surface, API-backed", subtree: true },
+  {
+    route: "unsubscribe",
+    reason: "app-shaped landing, API-backed; no content page behind it",
+  },
   // #6084 — both purchase return pages read a Checkout Session (or read
   // nothing, for cancel) and render via SectionRenderer directly; neither
   // is a content-adapter page, and the paid render's own schema.org node
@@ -367,6 +386,23 @@ const NO_STRUCTURED_DATA_ROUTES: ReadonlyArray<{
     reason: "auth surfaces, not content pages",
     subtree: true,
   },
+  // #8513 — a spoke carrying commerce gets two generated checkout return
+  // pages (create-ailk #7838): noindex, rendered through SectionRenderer
+  // directly, no JSON-LD. Exempt only when the page on disk still carries
+  // both the generated marker and the noindex line (see `requires` above) —
+  // a hand-written or edited page at either route is checked like any other.
+  {
+    route: "checkout/thank-you",
+    reason:
+      "spoke checkout return page (create-ailk #7838) — noindex, renders sections only, no JSON-LD",
+    requires: [CHECKOUT_PAGE_MARKER, CHECKOUT_PAGE_NOINDEX_LINE],
+  },
+  {
+    route: "checkout/unavailable",
+    reason:
+      "spoke checkout return page (create-ailk #7838) — noindex, renders sections only, no JSON-LD",
+    requires: [CHECKOUT_PAGE_MARKER, CHECKOUT_PAGE_NOINDEX_LINE],
+  },
 ];
 
 interface RouteEntry {
@@ -392,12 +428,20 @@ function walkRoutes(dir: string, out: RouteEntry[] = []): RouteEntry[] {
   return out;
 }
 
-function exemption(route: string): string | undefined {
-  return NO_STRUCTURED_DATA_ROUTES.find(
+function exemption(route: string, src: string): string | undefined {
+  const entry = NO_STRUCTURED_DATA_ROUTES.find(
     (e) =>
       route === e.route ||
       (e.subtree === true && route.startsWith(e.route + "/")),
-  )?.reason;
+  );
+  if (entry === undefined) return undefined;
+  if (
+    entry.requires !== undefined &&
+    !entry.requires.every((s) => src.includes(s))
+  ) {
+    return undefined;
+  }
+  return entry.reason;
 }
 
 // The page identity a route renders — the three shapes
@@ -432,9 +476,8 @@ const RENDER_PAGE_DYNAMIC_RE =
 const GET_MDX_SOURCE_RE = /getMdxSource\s*\(\s*["']([A-Za-z]+)["']/s;
 
 function routeIdentity(
-  file: string,
+  src: string,
 ): { type: string; slug: string | null } | null {
-  const src = readFileSync(file, "utf8");
   const exact = RENDER_PAGE_EXACT_RE.exec(src);
   if (exact) return { type: exact[1] as string, slug: exact[2] as string };
   const dynamic = RENDER_PAGE_DYNAMIC_RE.exec(src);
@@ -487,8 +530,9 @@ describe("structured data — every route emits a valid JSON-LD script", () => {
 
   it.each(routes)("$route", async ({ route, file }) => {
     const label = `/${DEFAULT_LOCALE}${route === "" ? "" : "/" + route}`;
-    const exempt = exemption(route);
-    const identity = routeIdentity(file);
+    const src = readFileSync(file, "utf8");
+    const exempt = exemption(route, src);
+    const identity = routeIdentity(src);
     if (exempt !== undefined) {
       // Declared, with a reason, in NO_STRUCTURED_DATA_ROUTES above. The
       // reason is false for a route that does render through renderPage —
@@ -570,6 +614,51 @@ describe("structured data — every route emits a valid JSON-LD script", () => {
   });
 });
 
+// ── 2a. exemption(route, src) — the generated-checkout routes (#8513) ──────
+//
+// Proof that the two conditional entries above key on the FILE, not the
+// route alone, and that every pre-existing entry is unaffected. The
+// monorepo's own app/[locale]/ has no checkout route (§1 of the spec), so
+// the route walk above never meets one — these cases are what exercise D1 on
+// every PR.
+
+describe("structured data — exemption(route, src) keys the generated checkout routes on the file (#8513)", () => {
+  const GENERATED_SRC = `// The checkout thank-you page — ${CHECKOUT_PAGE_MARKER}.\nexport async function generateMetadata() {\n  return { ${CHECKOUT_PAGE_NOINDEX_LINE} };\n}\n`;
+  const NO_MARKER_SRC = `// hand-written\nexport async function generateMetadata() {\n  return { ${CHECKOUT_PAGE_NOINDEX_LINE} };\n}\n`;
+  const NO_NOINDEX_SRC = `// The checkout thank-you page — ${CHECKOUT_PAGE_MARKER}.\nexport async function generateMetadata() {\n  return {};\n}\n`;
+
+  it("exempts checkout/thank-you only when the file carries both the marker and the noindex line", () => {
+    expect(exemption("checkout/thank-you", GENERATED_SRC)).toContain(
+      "noindex",
+    );
+    expect(exemption("checkout/thank-you", NO_MARKER_SRC)).toBeUndefined();
+    expect(exemption("checkout/thank-you", NO_NOINDEX_SRC)).toBeUndefined();
+  });
+
+  it("exempts checkout/unavailable only when the file carries both the marker and the noindex line", () => {
+    expect(exemption("checkout/unavailable", GENERATED_SRC)).toContain(
+      "noindex",
+    );
+    expect(exemption("checkout/unavailable", NO_MARKER_SRC)).toBeUndefined();
+    expect(exemption("checkout/unavailable", NO_NOINDEX_SRC)).toBeUndefined();
+  });
+
+  it("does not exempt a neighboring checkout route or an unrelated route", () => {
+    expect(exemption("checkout/other", GENERATED_SRC)).toBeUndefined();
+    expect(exemption("about", GENERATED_SRC)).toBeUndefined();
+  });
+
+  it("every pre-existing entry still returns its reason for its own route with any src, subtree entries included", () => {
+    for (const entry of NO_STRUCTURED_DATA_ROUTES) {
+      if (entry.requires !== undefined) continue; // the two conditional entries above, checked above
+      expect(exemption(entry.route, "")).toBe(entry.reason);
+      if (entry.subtree === true) {
+        expect(exemption(`${entry.route}/child`, "")).toBe(entry.reason);
+      }
+    }
+  });
+});
+
 // ── 3. The two defect shapes that shipped, pinned ───────────────────────────
 //
 // These prove the checks above reach the validator rule that rejects each

package/templates/apps/web/lib/account-config.ts

@@ -48,7 +48,9 @@
 //     (`GET /v1/member/messages`) — rows of All. A message with a file has a
 //     file action to this site's own member file read,
 //     `account/inbox/message/[id]/file`, which re-serves the bytes — the
-//     browser holds no hub credential.
+//     browser holds no hub credential. A message whose `action` is
+//     `onboarding` (#8515 D6) has an Open onboarding action to this site's
+//     own `/account/onboarding`.
 //   - For-you source `piece-needs-client` — each piece waiting on the client,
 //     with an Open action to its Inbox row. It shares the pieces read.
 //
@@ -283,23 +285,36 @@ const message: AccountInboxKind<MemberMessage> = {
     }));
   },
   renderDetail({ data }, { locale, t }) {
+    // An onboarding message (#8515 D6) links to this site's own onboarding
+    // page, before the file action when both apply; the body stays plain text.
+    const actions = [
+      ...(data.action === "onboarding"
+        ? [
+            {
+              key: "onboarding",
+              label: t("messages.openOnboarding"),
+              variant: "default" as const,
+              href: localeHref(locale, "/account/onboarding"),
+            },
+          ]
+        : []),
+      ...(data.file
+        ? [
+            {
+              key: "file",
+              label: t("messages.download", { filename: data.file.filename }),
+              variant: "default" as const,
+              href: localeHref(
+                locale,
+                `/account/inbox/message/${encodeURIComponent(data.id)}/file`,
+              ),
+            },
+          ]
+        : []),
+    ];
     return {
       lead: data.body,
-      ...(data.file
-        ? {
-            actions: [
-              {
-                key: "file",
-                label: t("messages.download", { filename: data.file.filename }),
-                variant: "default" as const,
-                href: localeHref(
-                  locale,
-                  `/account/inbox/message/${encodeURIComponent(data.id)}/file`,
-                ),
-              },
-            ],
-          }
-        : {}),
+      ...(actions.length > 0 ? { actions } : {}),
       fields: {
         heading: t("messages.heading"),
         items: [

package/templates/apps/web/lib/auth-email.ts

@@ -200,6 +200,12 @@ async function dispatch(
 
 export interface ResetPasswordDeps extends DispatchDeps {
   prisma: AuthEmailPrisma;
+  /**
+   * The id of the person signed in on `request`, or `null` (#8431 D4). Set,
+   * it lets a signed-in person ask for their OWN first password — the
+   * Security tab's Set password. Unset, the § D14 guard is unchanged.
+   */
+  sessionUserId?: (request: Request | undefined) => Promise<string | null>;
 }
 
 /**
@@ -217,17 +223,29 @@ export interface ResetPasswordDeps extends DispatchDeps {
  * address does not exist": the second is the enumeration AC-1 forbids and the
  * first is nearly as useful to an attacker, since it maps a site's users to
  * their identity provider.
+ *
+ * THE ONE CARVE-OUT (#8431 D4). A person with no password who is SIGNED IN
+ * may set one from their Security tab, by the same emailed link: the mail
+ * goes out when `deps.sessionUserId(request)` is that same person's id. The
+ * concern above is an ANONYMOUS request adding a password path around
+ * someone's identity provider; a request carrying that person's own live
+ * session is that person. The anonymous path is unchanged and silent, the
+ * link still goes only to the account's own address, and a failed session
+ * lookup counts as no session.
  */
 export function makeSendResetPassword(deps: ResetPasswordDeps) {
   const { prisma, send } = deps;
   const log = deps.log ?? defaultLog;
-  return async function sendResetPassword({
-    user,
-    url,
-  }: {
-    user: { id: string; email: string };
-    url: string;
-  }): Promise<void> {
+  return async function sendResetPassword(
+    {
+      user,
+      url,
+    }: {
+      user: { id: string; email: string };
+      url: string;
+    },
+    request?: Request,
+  ): Promise<void> {
     let hasPassword: { id: string } | null;
     try {
       hasPassword = await prisma.account.findFirst({
@@ -245,12 +263,29 @@ export function makeSendResetPassword(deps: ResetPasswordDeps) {
     }
 
     if (!hasPassword) {
-      log.warn({
+      let sessionUserId: string | null = null;
+      let lookupFailed = false;
+      if (deps.sessionUserId) {
+        try {
+          sessionUserId = await deps.sessionUserId(request);
+        } catch {
+          lookupFailed = true;
+        }
+      }
+      if (sessionUserId !== user.id) {
+        log.warn({
+          userId: user.id,
+          kind: "password-reset",
+          reason: "no_credential_account",
+          ...(lookupFailed ? { errorKind: "session_lookup_failed" } : {}),
+        });
+        return; // no send; the endpoint's 200 body is unchanged
+      }
+      log.info({
         userId: user.id,
         kind: "password-reset",
-        reason: "no_credential_account",
+        reason: "self_service_set",
       });
-      return; // no send; the endpoint's 200 body is unchanged
     }
 
     await dispatch(

package/templates/apps/web/lib/consent-visitor.ts

@@ -0,0 +1,103 @@
+/**
+ * consent-visitor.ts — the banner's visitor id (#8438 D12, spec
+ * docs/specs/8438-consent-registry-and-ledger-step-spec.md).
+ *
+ * Owns `ailk-vid`, a random version-4 UUID the site's own server mints for a
+ * visitor who has not signed in — it is the subject a cookie-banner choice is
+ * logged against (`POST /v1/consent/cookie`), and it is NEVER the cookie that
+ * gates anything (`ailk-consent`, §1.4/C3 of the spec, stays the operative
+ * switch; this id only lets a later form or sign-in link the two).
+ *
+ * httpOnly, `Secure` in production, `SameSite=Lax`, path `/`, one year — a
+ * Server Action can read and mint it; client script never sees its value.
+ */
+
+const CONSENT_VISITOR_COOKIE_NAME = "ailk-vid";
+const ONE_YEAR_SECONDS = 60 * 60 * 24 * 365;
+
+const V4_UUID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+/** Whether `value` is a well-formed version-4 UUID. */
+export function isValidConsentVisitorId(value: string): boolean {
+  return V4_UUID.test(value);
+}
+
+/** The subset of Next's `cookies()` jar a read needs. */
+export interface ConsentVisitorCookieReader {
+  get(name: string): { value: string } | undefined;
+}
+
+/** The cookie attributes `ensureConsentVisitor` sets — a subset of Next's `ResponseCookie`. */
+export interface ConsentVisitorCookieOptions {
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "lax" | "strict" | "none";
+  path?: string;
+  maxAge?: number;
+}
+
+/**
+ * The subset of Next's `cookies()` jar `ensureConsentVisitor` needs. The
+ * options type is narrow (not `Record<string, unknown>`) on purpose: Next's
+ * real `cookies().set` is itself a rest-tuple overload
+ * (`ResponseCookies.set`), and TypeScript checks a rest-tuple signature's
+ * parameters contravariantly with no method-bivariance leniency — a wider
+ * options type here fails that check even though every real call site passes
+ * only these five attributes.
+ */
+export interface ConsentVisitorCookieWriter extends ConsentVisitorCookieReader {
+  set(name: string, value: string, options: ConsentVisitorCookieOptions): void;
+}
+
+/** The existing visitor id, or `undefined` with none set or an invalid value. */
+export function readConsentVisitor(
+  cookies: ConsentVisitorCookieReader,
+): string | undefined {
+  const value = cookies.get(CONSENT_VISITOR_COOKIE_NAME)?.value;
+  return value !== undefined && isValidConsentVisitorId(value) ? value : undefined;
+}
+
+/**
+ * The visitor id, minting and setting a fresh one when absent or invalid.
+ * Server Actions only — Next refuses a cookie write outside one (the same
+ * posture `hub-session/reseal.ts` documents).
+ */
+export function ensureConsentVisitor(cookies: ConsentVisitorCookieWriter): string {
+  const existing = readConsentVisitor(cookies);
+  if (existing !== undefined) return existing;
+  const id = crypto.randomUUID();
+  cookies.set(CONSENT_VISITOR_COOKIE_NAME, id, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/",
+    maxAge: ONE_YEAR_SECONDS,
+  });
+  return id;
+}
+
+/** The one header a visitor-id-bearing request carries (D11). */
+export function consentVisitorHeader(id: string): Record<string, string> {
+  return { "x-ailk-consent-visitor": id };
+}
+
+/**
+ * The visitor id out of a raw `Cookie:` header string (the relay's own
+ * `Request`, which carries no Next `cookies()` jar). `undefined` with no
+ * header, no matching cookie, or a value that fails the UUID shape.
+ */
+export function readConsentVisitorFromCookieHeader(
+  header: string | null | undefined,
+): string | undefined {
+  if (!header) return undefined;
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const name = part.slice(0, eq).trim();
+    if (name !== CONSENT_VISITOR_COOKIE_NAME) continue;
+    const value = part.slice(eq + 1).trim();
+    return isValidConsentVisitorId(value) ? value : undefined;
+  }
+  return undefined;
+}

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

@@ -43,6 +43,7 @@ import { isIP } from "node:net";
 import { relayToApi, visitorForwardHeaders } from "@working-theory/api-client";
 
 import { browserApiOrigin } from "./api-origin.generated";
+import { readConsentVisitorFromCookieHeader } from "./consent-visitor";
 
 type RelayMethod = "GET" | "POST";
 
@@ -77,6 +78,16 @@ export const RELAY_ROUTES: readonly RelayRoute[] = Object.freeze([
   SESSION_ROUTE,
 ]);
 
+/**
+ * The three lead routes (#8438 D11, D12): a visitor's banner choice is
+ * linked to a Person only through these — a booking has no consent writer.
+ */
+const LEAD_ROUTE_PATHS = new Set([
+  "/v1/leads/submit",
+  "/v1/leads/subscribe",
+  "/v1/leads/callback",
+]);
+
 /** Fastify's default `bodyLimit`; the hub sets none (NFR4). */
 const RELAY_BODY_LIMIT = 1_048_576;
 
@@ -395,6 +406,15 @@ function relayHeaders(
       out,
       visitorForwardHeaders(incoming, process.env.AILK_VISITOR_FORWARD_KEY),
     );
+    // #8438 D12 — the banner's visitor id, read from THIS request's own
+    // `ailk-vid` cookie, never from a client-sent `x-ailk-*` header (the
+    // allow-list above already strips those). Only the three lead routes:
+    // the link between a banner choice and a client record is made there
+    // (D11), and the schedule routes have no consent writer to link.
+    if (LEAD_ROUTE_PATHS.has(entry.path)) {
+      const visitorId = readConsentVisitorFromCookieHeader(incoming.get("cookie"));
+      if (visitorId) out["x-ailk-consent-visitor"] = visitorId;
+    }
   }
   return out;
 }