create-ailk 0.11.2 → 0.11.3

package/templates/apps/api/src/server.ts

@@ -32,7 +32,9 @@ import { authPreHandlerPlugin } from "./middleware/auth.js";
 import { defaultTenantPreHandlerPlugin } from "./middleware/default-tenant.js";
 import {
   rateLimitMiddleware,
+  buildTrustedKeyDigests,
   DEFAULT_PER_IP_PER_MINUTE_STRICT,
+  resolveRateLimitIdentity,
 } from "./middleware/rate-limit.js";
 import { openapiRoutes } from "./openapi/index.js";
 import {
@@ -615,6 +617,17 @@ export async function build() {
     trustProxy: true,
   });
 
+  // The hub's forwarding-key digests (#7394 DD-2), parsed once from
+  // AILK_VISITOR_FORWARD_KEYS and shared by the global ceiling and the leads
+  // scope below, so both limiters apply one identity rule. A keyed spoke's
+  // lead write is counted per visitor (`x-ailk-visitor-ip`); everything else
+  // keys on `req.ip`. Unset → `[]`, which believes no forwarded visitor. The
+  // parse warns by entry position only, never an entry's value.
+  const visitorForwardKeyDigests = buildTrustedKeyDigests(
+    process.env.AILK_VISITOR_FORWARD_KEYS,
+    (msg) => server.log.warn(msg),
+  );
+
   // Collect the route table this server registers (#5314).
   //
   // Installed here — after `Fastify()` and before the first `register()` — so
@@ -688,9 +701,16 @@ export async function build() {
   // limiter is in-memory by default, which suits a single Vercel function /
   // single-process dev server; multi-instance deployments will need a
   // Redis store, swappable here without changing route code.
+  //
+  // `keyGenerator` (#7394 DD-7): a keyed spoke's lead write counts against its
+  // visitor's own ceiling here too, or a spoke whose visitors share one
+  // egress IP would still be capped at this limit in total. For every other
+  // request it returns `req.ip`, the plugin's own default key.
   await server.register(rateLimit, {
     max: CONTENT_RATE_LIMIT_UNAUTH,
     timeWindow: CONTENT_RATE_LIMIT_WINDOW,
+    keyGenerator: (req) =>
+      resolveRateLimitIdentity(req, visitorForwardKeyDigests).identity,
   });
 
   // Health check
@@ -1189,9 +1209,17 @@ export async function build() {
   // default (10/min, pre-#4730) rather than inheriting the wider
   // flows-sized default (#5111, DEF-004 — #4730's shared-default bump was
   // never meant to loosen abuse protection here).
+  //
+  // `scope: "leads"` (#7394): this scope's buckets are its own, not shared
+  // with the other scopes' bare-IP count, and AILK_RATE_LIMIT_LEADS_PER_MINUTE
+  // (and ..._PER_KEY_PER_MINUTE, default 300) override the code values. With
+  // `trustedKeyDigests`, a keyed spoke's three lead writes are counted per
+  // forwarded visitor; the project-listing routes below still key on `req.ip`.
   await server.register(async (leadsScope) => {
     leadsScope.register(rateLimitMiddleware, {
       perIpPerMinute: DEFAULT_PER_IP_PER_MINUTE_STRICT,
+      scope: "leads",
+      trustedKeyDigests: visitorForwardKeyDigests,
     });
     await leadsScope.register(leadSubmitRoute);
     await leadsScope.register(leadSubscribeRoute);

package/templates/apps/api/src/services/__tests__/lead-accept-user.test.ts

@@ -0,0 +1,251 @@
+// oss: false
+/**
+ * @file lead-accept-user.test.ts
+ *
+ * The find-or-create behind accepting an inbox message (#7418 D1, D2, D7, D7a,
+ * D8): the lead's email resolves to ONE `auth.User` — an existing one is
+ * linked and left untouched, a missing one is created verified with the plain
+ * `user` role and no credential, membership or session.
+ *
+ * External dependency boundary mocked: `lib/prisma` — an inline factory with
+ * an in-memory `users` table that honours the case-insensitive `equals`
+ * filter and the byte-exact `@unique` email constraint (a duplicate create
+ * throws Prisma's `P2002`). `account`/`session`/`membership` carry `create`
+ * spies so AC-3 can assert none of them is ever written.
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../lib/prisma.js", () => ({
+  prisma: {
+    user: { findFirst: jest.fn(), create: jest.fn(), update: jest.fn() },
+    account: { create: jest.fn() },
+    session: { create: jest.fn() },
+    membership: { create: jest.fn() },
+  },
+}));
+
+import { prisma } from "../../lib/prisma.js";
+import { findOrCreateUserForLeadEmail } from "../lead-accept-user";
+
+type UserRow = {
+  id: string;
+  email: string;
+  name: string | null;
+  emailVerified: boolean;
+  role: string;
+  createdAt: Date;
+};
+
+type UserWhere = { email?: { equals: string; mode?: "insensitive" } };
+
+let USERS: UserRow[] = [];
+let nextUser = 1;
+
+function userId(n: number): string {
+  return `user_00000000-0000-7000-8000-${n.toString(16).padStart(12, "0")}`;
+}
+
+function uniqueViolation(): Error {
+  return Object.assign(new Error("Unique constraint failed on the fields: (`email`)"), {
+    code: "P2002",
+  });
+}
+
+/** Wires `prisma.user.findFirst`/`create` to a fresh in-memory table. */
+function seedUsers(rows: UserRow[]): UserRow[] {
+  USERS = rows.map((r) => ({ ...r }));
+  nextUser = 100;
+
+  (prisma.user.findFirst as jest.Mock).mockImplementation(
+    async ({ where }: { where: UserWhere }) => {
+      const filter = where.email;
+      const match = USERS.filter((u) =>
+        filter?.mode === "insensitive"
+          ? u.email.toLowerCase() === filter.equals.toLowerCase()
+          : u.email === filter?.equals,
+      ).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())[0];
+      return match ? { id: match.id, emailVerified: match.emailVerified } : null;
+    },
+  );
+  (prisma.user.create as jest.Mock).mockImplementation(
+    async ({ data }: { data: Partial<UserRow> & { email: string } }) => {
+      // Postgres `@unique` is byte-exact — the same constraint the real
+      // table carries.
+      if (USERS.some((u) => u.email === data.email)) throw uniqueViolation();
+      const row: UserRow = {
+        id: userId(nextUser++),
+        name: null,
+        emailVerified: false,
+        role: "user",
+        createdAt: new Date(),
+        ...data,
+      };
+      USERS.push(row);
+      return { id: row.id };
+    },
+  );
+  return USERS;
+}
+
+function existingUser(overrides: Partial<UserRow> & { email: string }): UserRow {
+  return {
+    id: userId(1),
+    name: "Existing Person",
+    emailVerified: false,
+    role: "admin",
+    createdAt: new Date("2026-01-01T00:00:00.000Z"),
+    ...overrides,
+  };
+}
+
+describe("findOrCreateUserForLeadEmail (#7418)", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("AC-3 / D1 — with no existing user, creates exactly one verified plain user with the lowercased email and no name, and no Account/Session/Membership", async () => {
+    const table = seedUsers([]);
+
+    const result = await findOrCreateUserForLeadEmail({
+      email: "  New.Person@Example.COM ",
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      value: { userId: table[0]?.id, created: true },
+    });
+    expect(table).toHaveLength(1);
+    expect(table[0]).toMatchObject({
+      email: "new.person@example.com",
+      emailVerified: true,
+      role: "user",
+      name: null,
+    });
+    expect(prisma.user.create).toHaveBeenCalledTimes(1);
+    const [{ data }] = (prisma.user.create as jest.Mock).mock.calls[0] as [
+      { data: Record<string, unknown> },
+    ];
+    // D7a — no name copied from the anonymous payload; nothing nested that
+    // would create a relation row.
+    expect(Object.keys(data).sort()).toEqual(["email", "emailVerified", "role"]);
+    expect(prisma.account.create).not.toHaveBeenCalled();
+    expect(prisma.session.create).not.toHaveBeenCalled();
+    expect(prisma.membership.create).not.toHaveBeenCalled();
+  });
+
+  it("AC-4 / D2 — with an existing user, links to it and changes none of its fields", async () => {
+    const before = existingUser({ email: "ada@example.com" });
+    const table = seedUsers([before]);
+
+    const result = await findOrCreateUserForLeadEmail({ email: "ada@example.com" });
+
+    expect(result).toEqual({
+      ok: true,
+      value: { userId: before.id, created: false },
+    });
+    expect(table).toEqual([before]);
+    expect(prisma.user.create).not.toHaveBeenCalled();
+    expect(prisma.user.update).not.toHaveBeenCalled();
+  });
+
+  it("AC-10 / D7 — an existing `Foo@Example.com` is linked from a lead email `foo@example.com`; no user is created", async () => {
+    const before = existingUser({ email: "Foo@Example.com" });
+    const table = seedUsers([before]);
+
+    const result = await findOrCreateUserForLeadEmail({ email: "foo@example.com" });
+
+    expect(result).toEqual({
+      ok: true,
+      value: { userId: before.id, created: false },
+    });
+    expect(table).toHaveLength(1);
+    expect(prisma.user.create).not.toHaveBeenCalled();
+    expect(prisma.user.findFirst).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { email: { equals: "foo@example.com", mode: "insensitive" } },
+        orderBy: { createdAt: "asc" },
+      }),
+    );
+  });
+
+  it("D7 — two case-variant rows for one mailbox link the OLDEST, with no distinct error", async () => {
+    const older = existingUser({
+      id: userId(2),
+      email: "foo@example.com",
+      createdAt: new Date("2026-01-01T00:00:00.000Z"),
+    });
+    const newer = existingUser({
+      id: userId(3),
+      email: "FOO@example.com",
+      createdAt: new Date("2026-02-01T00:00:00.000Z"),
+    });
+    seedUsers([newer, older]);
+
+    const result = await findOrCreateUserForLeadEmail({ email: "Foo@Example.com" });
+
+    expect(result).toEqual({
+      ok: true,
+      value: { userId: older.id, created: false },
+    });
+  });
+
+  it.each(["", "   ", "not-an-email", "ada@", "@example.com"])(
+    "D7 — a lead email that is not an address after trimming (%j) is invalid_email, and nothing is read or written",
+    async (email) => {
+      seedUsers([]);
+
+      const result = await findOrCreateUserForLeadEmail({ email });
+
+      expect(result).toEqual({ ok: false, error: { kind: "invalid_email" } });
+      expect(prisma.user.findFirst).not.toHaveBeenCalled();
+      expect(prisma.user.create).not.toHaveBeenCalled();
+    },
+  );
+
+  it("D8 — a create that loses a race (P2002) re-reads and links the winner with created: false", async () => {
+    const table = seedUsers([]);
+    // The concurrent winner lands between this call's read and its create.
+    (prisma.user.findFirst as jest.Mock).mockImplementationOnce(async () => {
+      table.push(existingUser({ id: userId(9), email: "race@example.com" }));
+      return null;
+    });
+
+    const result = await findOrCreateUserForLeadEmail({ email: "race@example.com" });
+
+    expect(result).toEqual({
+      ok: true,
+      value: { userId: userId(9), created: false },
+    });
+    expect(table).toHaveLength(1);
+    expect(prisma.user.create).toHaveBeenCalledTimes(1);
+  });
+
+  it("AC-8 — two concurrent calls for one email leave exactly one user, and both resolve to it", async () => {
+    const table = seedUsers([]);
+
+    const [a, b] = await Promise.all([
+      findOrCreateUserForLeadEmail({ email: "twice@example.com" }),
+      findOrCreateUserForLeadEmail({ email: "Twice@Example.com" }),
+    ]);
+
+    expect(table).toHaveLength(1);
+    // Both reached the create; the second hit P2002 and re-read (D8).
+    expect(prisma.user.create).toHaveBeenCalledTimes(2);
+    const id = table[0]?.id;
+    expect(a).toMatchObject({ ok: true, value: { userId: id } });
+    expect(b).toMatchObject({ ok: true, value: { userId: id } });
+    expect([a, b].filter((r) => r.ok && r.value.created)).toHaveLength(1);
+  });
+
+  it("SEC-006 — a Prisma failure is internal_error and never carries the Prisma message", async () => {
+    seedUsers([]);
+    (prisma.user.create as jest.Mock).mockRejectedValueOnce(
+      new Error("connection to db.internal:5432 failed for ada@example.com"),
+    );
+
+    const result = await findOrCreateUserForLeadEmail({ email: "ada@example.com" });
+
+    expect(result).toEqual({ ok: false, error: { kind: "internal_error" } });
+    expect(JSON.stringify(result)).not.toContain("ada@example.com");
+  });
+});

package/templates/apps/api/src/services/lead-accept-user.ts

@@ -0,0 +1,126 @@
+// oss: false
+/**
+ * @file lead-accept-user.ts
+ * @description The `auth.User` behind an accepted inbox message (#7418) —
+ * find the user whose email matches the lead's, or create one, so the person
+ * who wrote in can later sign in with that same address.
+ *
+ * ## What a created user is (D1, D7a)
+ *
+ * `emailVerified: true`, `role: "user"`, the lowercased address, no `name` —
+ * and NOTHING else: no `Account` (so no password and no linked provider), no
+ * `Session`, no `Membership`. Verified is the operator's ruling (2026-10-01),
+ * and it is safe only because the row holds no credential: reaching a session
+ * still needs the address owner to prove control of it (Google, which
+ * reports a verified email, or the password-reset mail). It is also what
+ * Better Auth needs to link that Google login at all — it refuses to link an
+ * OAuth account to an existing local user whose `emailVerified` is false.
+ * No name is copied: the lead payload is anonymous, unbounded text, and
+ * `User.name` is rendered elsewhere.
+ *
+ * ## What an existing user gets (D2)
+ *
+ * Nothing. It is linked by id and never written — no `emailVerified`, `role`
+ * or `name` change. An operator's click is not proof of address control for
+ * an account someone already holds.
+ *
+ * ## Email normalization (D7, D8)
+ *
+ * The lead's email is trimmed and must still be an address (else
+ * `invalid_email`, before any read). The lookup is case-insensitive and links
+ * the OLDEST match: case-variant rows are one mailbox, and a distinct error
+ * for them would reveal global account state. A create uses the lowercased
+ * form; one that loses a race to the same address (Prisma `P2002`) re-reads
+ * and links the winner.
+ *
+ * ## Why its own file (D3)
+ *
+ * `inbox-messages.ts` is co-owned by the `workspace` and `multi-tenant`
+ * slices and must build in either bundle alone, while `lead-promotion.ts`
+ * sits inside a paid-module import closure. This file imports only
+ * `lib/prisma.js` and `zod`, so it keeps both bundles buildable.
+ *
+ * It never returns, logs or rethrows a Prisma error message — a failure is
+ * the bare `internal_error` kind (SEC-006).
+ */
+
+import { z } from "zod";
+
+import { prisma } from "../lib/prisma.js";
+
+export type FindOrCreateUserResult =
+  | { ok: true; value: { userId: string; created: boolean } }
+  | { ok: false; error: { kind: "invalid_email" | "internal_error" } };
+
+const EMAIL_SHAPE = z.string().email();
+
+/**
+ * Prisma's unique-constraint violation, matched by code alone. A local copy
+ * of `default-tenant.ts`'s helper, deliberately: importing it would break
+ * this file's `lib/prisma.js` + `zod`-only import rule (D3).
+ */
+function isUniqueViolation(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as { code?: unknown }).code === "P2002"
+  );
+}
+
+/**
+ * The oldest user whose email equals `email`, ignoring case. `emailVerified`
+ * is selected though no decision here reads it: `tools/lint-email-authz.ts`
+ * requires it on every `User` read keyed by email, and this read only links
+ * an id — it never gates data on the address.
+ */
+function findUserByEmail(email: string) {
+  return prisma.user.findFirst({
+    where: { email: { equals: email, mode: "insensitive" } },
+    orderBy: { createdAt: "asc" },
+    select: { id: true, emailVerified: true },
+  });
+}
+
+/**
+ * Resolve the lead's email to one `auth.User` id — linked when one exists,
+ * created verified when none does.
+ *
+ * @param input.email the lead's stored email, untrimmed.
+ * @returns the user id and whether this call created it (`created` is for
+ *   the caller's audit line only — never for the wire, SEC-002).
+ */
+export async function findOrCreateUserForLeadEmail(input: {
+  email: string;
+}): Promise<FindOrCreateUserResult> {
+  const email = typeof input.email === "string" ? input.email.trim() : "";
+  if (!EMAIL_SHAPE.safeParse(email).success) {
+    return { ok: false, error: { kind: "invalid_email" } };
+  }
+
+  try {
+    const existing = await findUserByEmail(email);
+    if (existing) {
+      return { ok: true, value: { userId: existing.id, created: false } };
+    }
+
+    try {
+      const created = await prisma.user.create({
+        data: {
+          email: email.toLowerCase(),
+          emailVerified: true,
+          role: "user",
+        },
+        select: { id: true },
+      });
+      return { ok: true, value: { userId: created.id, created: true } };
+    } catch (err) {
+      if (!isUniqueViolation(err)) throw err;
+      // D8 — a concurrent accept created the same address first.
+      const winner = await findUserByEmail(email);
+      if (!winner) return { ok: false, error: { kind: "internal_error" } };
+      return { ok: true, value: { userId: winner.id, created: false } };
+    }
+  } catch {
+    return { ok: false, error: { kind: "internal_error" } };
+  }
+}

package/templates/apps/api/src/vercel-handler.ts

@@ -112,6 +112,27 @@ function getServer(): Promise<FastifyServer> {
   return attempt;
 }
 
+/**
+ * The request body exactly as the client sent it (#7440).
+ *
+ * Vercel's Node runtime reads the stream itself to back its lazily PARSED
+ * `req.body`, then replays the same bytes onto the request stream
+ * (`restoreBody` in @vercel/node's serverless-functions helpers), so they are
+ * still readable here — but ONLY through `on("data")`/`on("end")`, the two
+ * listeners that replay patches. `once`, `pipe` or `for await` would wait on
+ * the already-drained original stream and never settle.
+ */
+function readRawBody(req: VercelRequest): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer | string) => {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+
 /**
  * Vercel serverless function handler
  */
@@ -158,17 +179,42 @@ export default async function handler(
 
     const server = await getServer();
 
+    // Forward the RAW bytes, never the runtime's parsed `req.body` (#7440).
+    // A signed webhook — Stripe, Slack, Cal.com — is verified over the exact
+    // bytes the sender signed, and Fastify's raw-buffer parser on the
+    // webhooks scope only sees those bytes if they are what inject() is
+    // given: handing it the parsed object made light-my-request re-serialize
+    // it compactly, so a pretty-printed Stripe event could never verify.
+    // Every other route now parses the bytes with Fastify's own parser rather
+    // than Vercel's — the same value for any JSON object or array body — and
+    // answers exactly as the app does off Vercel: a route with a parser for a
+    // content type gets the bytes (one without answers 415), a top-level JSON
+    // scalar reaches the route, and `bodyLimit` measures the bytes as sent.
+    //
+    // An EMPTY body falls back to `req.body`, which keeps the runtime's
+    // answer for it — `{}` for a bodiless JSON POST, where Fastify's own JSON
+    // parser would refuse the empty string with a 400. So does a request with
+    // no content-type (the runtime forwarded no body for one, and Fastify has
+    // no parser to give it), and GET/HEAD, which carry no body to read.
+    const method = req.method || "GET";
+    const rawBody =
+      method === "GET" ||
+      method === "HEAD" ||
+      req.headers["content-type"] === undefined
+        ? undefined
+        : await readRawBody(req);
+    const body = rawBody && rawBody.length > 0 ? rawBody : req.body;
+
     // Strip content-length/content-encoding before forwarding. Both
-    // describe the ORIGINAL byte stream the client sent; req.body here is
-    // already the PARSED object, and light-my-request re-serializes it
-    // itself. It only computes a fresh content-length when the header is
-    // absent (`req.headers['content-length'] = req.headers['content-length']
-    // || ...`), so a stale header survives and Fastify's own content-length
-    // check rejects any body whose re-serialized length differs from the
-    // original — e.g. pretty-printed JSON or a trailing newline
-    // (FST_ERR_CTP_INVALID_CONTENT_LENGTH, #5168). Matched case-insensitively
-    // since header casing isn't guaranteed, even though Node lower-cases
-    // incoming header names in practice.
+    // describe the ORIGINAL byte stream the client sent, and light-my-request
+    // only computes a fresh content-length when the header is absent
+    // (`req.headers['content-length'] = req.headers['content-length'] ||
+    // ...`), so a stale header survives and Fastify's own content-length check
+    // rejects any forwarded body whose length differs from the original — as
+    // the re-serialized `req.body` fallback above does (an empty body becomes
+    // `{}`; FST_ERR_CTP_INVALID_CONTENT_LENGTH, #5168). Matched
+    // case-insensitively since header casing isn't guaranteed, even though
+    // Node lower-cases incoming header names in practice.
     const forwardedHeaders = { ...req.headers } as Record<string, string>;
     for (const key of Object.keys(forwardedHeaders)) {
       if (
@@ -180,10 +226,10 @@ export default async function handler(
     }
 
     const fastifyRequest = {
-      method: req.method || "GET",
+      method,
       url: pathname,
       headers: forwardedHeaders,
-      body: req.body,
+      body,
       query: req.query as Record<string, string>,
     };
 

package/templates/apps/mcp/__tests__/submit_lead.test.ts

@@ -9,6 +9,7 @@
  * 5. API 429 → { ok: false, error: { kind: 'api_error', status: 429 } }
  */
 
+import { LEAD_SITE_MARKER_KEY, leadSubmitSchema } from "@working-theory/validation";
 import { ailkCaptureLead } from "../src/tools/capture_lead.js";
 
 // Mock @working-theory/api-client before importing the handler
@@ -33,6 +34,8 @@ const VALID_INPUT = {
 
 beforeEach(() => {
   jest.clearAllMocks();
+  // The exact-body assertions below assume no spoke marker (#7397).
+  delete process.env.AILK_LEAD_SITE;
 });
 
 describe("ailkCaptureLead — input validation", () => {
@@ -163,3 +166,81 @@ describe("ailkCaptureLead — siteId override", () => {
     expect(call.siteId).toBe("site-abc");
   });
 });
+
+// #7397 — a spoke of a hub-and-spokes deployment is marked in the lead
+// PAYLOAD (`payload.site`); `source` stays "mcp" because
+// MESSAGE_LEAD_SOURCE_LIST is frozen. The marker comes from the MCP server's
+// own env, so an MCP-origin lead reaches the hub inbox attributed.
+describe("ailkCaptureLead — payload site marker (#7397)", () => {
+  afterEach(() => {
+    delete process.env.AILK_LEAD_SITE;
+  });
+
+  it("names the marker key 'site', the key the issue's hub-and-spokes design names", () => {
+    expect(LEAD_SITE_MARKER_KEY).toBe("site");
+  });
+
+  it("carries payload.site from AILK_LEAD_SITE, leaving source 'mcp'", async () => {
+    process.env.AILK_LEAD_SITE = "spoke-a.example";
+    apiClient.leads.submit.mockResolvedValueOnce({
+      ok: true,
+      body: { id: "lead_00000000-0000-7000-8000-0000000000d4", persisted: "db" },
+    });
+
+    await ailkCaptureLead(VALID_INPUT);
+
+    expect(apiClient.leads.submit).toHaveBeenCalledWith({
+      siteId: "default",
+      source: "mcp",
+      email: "jane@example.com",
+      payload: {
+        name: "Jane Smith",
+        message: "I am interested in your services.",
+        site: "spoke-a.example",
+      },
+    });
+  });
+
+  it("sends a marked body the API's submit schema accepts", async () => {
+    process.env.AILK_LEAD_SITE = "spoke-a.example";
+    apiClient.leads.submit.mockResolvedValueOnce({
+      ok: true,
+      body: { id: "lead_00000000-0000-7000-8000-0000000000d5", persisted: "db" },
+    });
+
+    await ailkCaptureLead(VALID_INPUT);
+
+    const body = apiClient.leads.submit.mock.calls[0][0] as Record<string, unknown>;
+    expect(leadSubmitSchema.safeParse({ kind: "submit", ...body }).success).toBe(true);
+  });
+
+  it.each([
+    ["unset", undefined],
+    ["empty", ""],
+    ["whitespace only", "   "],
+  ])("omits payload.site when AILK_LEAD_SITE is %s", async (_label, value) => {
+    if (value !== undefined) process.env.AILK_LEAD_SITE = value;
+    apiClient.leads.submit.mockResolvedValueOnce({
+      ok: true,
+      body: { id: "lead_00000000-0000-7000-8000-0000000000d6", persisted: "db" },
+    });
+
+    await ailkCaptureLead(VALID_INPUT);
+
+    const call = apiClient.leads.submit.mock.calls[0][0] as { payload: Record<string, unknown> };
+    expect(call.payload).not.toHaveProperty("site");
+  });
+
+  it("trims surrounding whitespace from AILK_LEAD_SITE", async () => {
+    process.env.AILK_LEAD_SITE = "  spoke-a.example\n";
+    apiClient.leads.submit.mockResolvedValueOnce({
+      ok: true,
+      body: { id: "lead_00000000-0000-7000-8000-0000000000d7", persisted: "db" },
+    });
+
+    await ailkCaptureLead(VALID_INPUT);
+
+    const call = apiClient.leads.submit.mock.calls[0][0] as { payload: Record<string, unknown> };
+    expect(call.payload["site"]).toBe("spoke-a.example");
+  });
+});

package/templates/apps/mcp/src/tools/capture_lead.ts

@@ -10,6 +10,7 @@
 
 import { apiClient } from "@working-theory/api-client";
 import {
+  LEAD_SITE_MARKER_KEY,
   submitLeadInputSchema,
   submitLeadOutputSchema,
   type SubmitLeadInput,
@@ -32,6 +33,8 @@ export async function ailkCaptureLead(
 
   const { name, email, message, phone } = parsed.data;
   const siteId = process.env.AILK_SITE_ID ?? "default";
+  // The spoke marker (#7397) — unset or blank leaves the payload unmarked.
+  const site = process.env.AILK_LEAD_SITE?.trim();
   const body = {
     siteId,
     source: "mcp",
@@ -40,6 +43,7 @@ export async function ailkCaptureLead(
       name,
       ...(message !== undefined && { message }),
       ...(phone !== undefined && { phone }),
+      ...(site && { [LEAD_SITE_MARKER_KEY]: site }),
     },
   };
 

package/templates/apps/mcp/src/tools/subscribe_newsletter.ts

@@ -34,7 +34,9 @@ export async function ailkSubscribeNewsletter(
 
   const { email } = parsed.data;
   // firstName is not part of the canonical subscribeSchema (no payload field);
-  // it is accepted by the MCP input but dropped here for now.
+  // it is accepted by the MCP input but dropped here for now. The #7397 spoke
+  // marker (LEAD_SITE_MARKER_KEY) is absent for the same reason: a Subscriber
+  // row has no payload column, so subscribe has nowhere to carry it.
   const siteId = process.env.AILK_SITE_ID ?? "default";
   const body = { siteId, email, source: "mcp" };
 

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

@@ -50,6 +50,10 @@ CONTENT_ADAPTER=mdx
 # — 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).
 # NEXT_PUBLIC_AILK_API_URL=http://localhost:3002
 
 # =============================================================================