create-ailk 0.17.0 → 0.19.0

package/templates/apps/mcp/__tests__/audit-single-page.test.ts

@@ -231,10 +231,22 @@ describe("buildSinglePageAuditInput — sitewide identity (#6597 AC-7)", () => {
     expect(evidenceOf(report, "schema-coverage")?.pass).toBe(true);
   });
 
-  it("the monorepo home finds the identity: Identity (organization) ✓", async () => {
+  // The content root's own _site.mdx names the site's identity kind: the monorepo's is
+  // Organization, a person-service scaffold's is Person. Read it, don't hard-code it (#8419).
+  const siteKind = (): "Organization" | "Person" => {
+    const site = readFileSync(join(CONTENT_ROOT, "_site.mdx"), "utf-8");
+    const kind = /^siteIdentity:\s*\n(?:[ \t]+.*\n)*?[ \t]+kind:\s*["']?(\w+)["']?\s*$/m.exec(site)?.[1];
+    if (kind !== "Organization" && kind !== "Person") {
+      throw new Error(`content/_site.mdx siteIdentity.kind is not Organization or Person: ${String(kind)}`);
+    }
+    return kind;
+  };
+
+  it("the content root's home finds the identity its _site.mdx names", async () => {
+    const kind = siteKind();
     const report = await auditOf({ slug: "home" }, CONTENT_ROOT);
     expect(evidenceOf(report, "entity-markup")?.evidence).toContain(
-      "Identity (organization) ✓",
+      `Identity (${kind.toLowerCase()}) ✓`,
     );
   });
 
@@ -243,7 +255,7 @@ describe("buildSinglePageAuditInput — sitewide identity (#6597 AC-7)", () => {
     const nodes = input.jsonLdByPage["AboutPage/about"] as Array<Record<string, unknown>>;
     expect(nodes[0]!["@type"]).toBe("AboutPage");
     expect(nodes.map((n) => n["@type"])).toEqual(
-      expect.arrayContaining(["Organization", "WebSite"]),
+      expect.arrayContaining([siteKind(), "WebSite"]),
     );
   });
 

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

@@ -0,0 +1,280 @@
+/**
+ * The shared boot module (#8070 D1, D2): `readStatelessEnv` and
+ * `httpTransportConfigFromEnv`, which both entrypoints read the environment
+ * through.
+ *
+ * Acceptance criteria verified here (spec docs/specs/8070-spoke-mcp-vercel-backend-spec.md):
+ * - AC-1: MCP_HTTP_STATELESS=true selects the stateless transport — a
+ *   session-less tools/list answers 200 and lists list_pages.
+ * - AC-2: each entry's default, and the accepted spellings.
+ * - AC-3: a bad value throws naming the variable; a blank per-minute rate
+ *   falls back to its default rather than disabling the limit.
+ *
+ * And from spec docs/specs/8071-mcp-write-guard-spec.md:
+ * - AC-5: a blank or non-numeric MCP_ABUSE_CREATE_BOOKING_DAILY_CAP /
+ *   MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP yields the default cap through the
+ *   env reader both entries share, never an unlimited one.
+ *
+ * Real sockets on port 0, the pattern of `http-transport.test.ts`.
+ */
+
+import type { AddressInfo } from "node:net";
+
+import type { FastifyInstance, FastifyRequest } from "fastify";
+
+import {
+  AbuseGuard,
+  DEFAULT_CREATE_BOOKING_DAILY_CAP,
+  DEFAULT_SUBMIT_FLOW_STEP_DAILY_CAP,
+} from "../src/abuse/index.js";
+import { httpTransportConfigFromEnv, readStatelessEnv } from "../src/boot.js";
+import { buildHttpTransportApp } from "../src/http-transport.js";
+
+const VARS = [
+  "MCP_HTTP_STATELESS",
+  "MCP_HTTP_PORT",
+  "MCP_HTTP_PATH",
+  "MCP_RATE_LIMIT_READ_PER_MIN",
+  "MCP_RATE_LIMIT_WRITE_PER_MIN",
+  "MCP_CORS_WRITE_ALLOWED_ORIGINS",
+  "MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP",
+  "MCP_ABUSE_START_PURCHASE_DAILY_CAP",
+  "MCP_ABUSE_CREATE_BOOKING_DAILY_CAP",
+  "MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP",
+  "MCP_ABUSE_BLOCKED_USER_AGENTS",
+] as const;
+
+const saved: Partial<Record<(typeof VARS)[number], string | undefined>> = {};
+
+beforeEach(() => {
+  for (const name of VARS) {
+    saved[name] = process.env[name];
+    delete process.env[name];
+  }
+});
+
+afterEach(() => {
+  for (const name of VARS) {
+    const value = saved[name];
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+});
+
+/** A stub carrying only the two members the guard reads. */
+function requestFrom(ip: string): FastifyRequest {
+  // @ts-expect-error: a full FastifyRequest cannot be built without a server.
+  return {
+    headers: { "user-agent": "Mozilla/5.0 (compatible; TestAgent/1.0)" },
+    ip,
+  };
+}
+
+const TOOLS_LIST = { jsonrpc: "2.0", id: 1, method: "tools/list", params: {} };
+
+async function listen(app: FastifyInstance): Promise<number> {
+  await app.listen({ host: "127.0.0.1", port: 0 });
+  return (app.server.address() as AddressInfo).port;
+}
+
+async function postToolsList(port: number): Promise<Response> {
+  return fetch(`http://127.0.0.1:${port}/mcp`, {
+    method: "POST",
+    body: JSON.stringify(TOOLS_LIST),
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+    },
+  });
+}
+
+/** The app the long-running entry builds, from the environment as it stands. */
+async function appFromEnv(defaultStateless: boolean): Promise<FastifyInstance> {
+  const { port: _port, ...config } = httpTransportConfigFromEnv();
+  return buildHttpTransportApp({
+    ...config,
+    stateless: readStatelessEnv(defaultStateless),
+  });
+}
+
+describe("AC-1 — MCP_HTTP_STATELESS=true selects the stateless transport", () => {
+  let app: FastifyInstance | undefined;
+
+  afterEach(async () => {
+    await app?.close();
+    app = undefined;
+  });
+
+  it("answers a tools/list with no Mcp-Session-Id with 200, listing list_pages", async () => {
+    process.env["MCP_HTTP_STATELESS"] = "true";
+    app = await appFromEnv(false);
+    const port = await listen(app);
+
+    const res = await postToolsList(port);
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      result?: { tools?: Array<{ name: string }> };
+    };
+    const names = (body.result?.tools ?? []).map((tool) => tool.name);
+    expect(names).toContain("list_pages");
+  });
+});
+
+describe("AC-2 — each entry's default, and the accepted spellings", () => {
+  let app: FastifyInstance | undefined;
+
+  afterEach(async () => {
+    await app?.close();
+    app = undefined;
+  });
+
+  it("unset, the long-running default is false — and a session-less tools/list is 400 (today's stateful behaviour)", async () => {
+    expect(readStatelessEnv(false)).toBe(false);
+
+    app = await appFromEnv(false);
+    const port = await listen(app);
+
+    const res = await postToolsList(port);
+    expect(res.status).toBe(400);
+  });
+
+  it("unset, the serverless default is true", () => {
+    expect(readStatelessEnv(true)).toBe(true);
+  });
+
+  it("an empty value takes the default", () => {
+    process.env["MCP_HTTP_STATELESS"] = "";
+    expect(readStatelessEnv(true)).toBe(true);
+    expect(readStatelessEnv(false)).toBe(false);
+  });
+
+  it.each(["false", "0", "FALSE"])("%s reads as false", (value) => {
+    process.env["MCP_HTTP_STATELESS"] = value;
+    expect(readStatelessEnv(true)).toBe(false);
+  });
+
+  it.each(["1", "True"])("%s reads as true", (value) => {
+    process.env["MCP_HTTP_STATELESS"] = value;
+    expect(readStatelessEnv(false)).toBe(true);
+  });
+
+  it("surrounding whitespace is trimmed", () => {
+    process.env["MCP_HTTP_STATELESS"] = "  true ";
+    expect(readStatelessEnv(false)).toBe(true);
+  });
+});
+
+describe("AC-3 — a bad value fails the boot; a blank rate does not disable the limit", () => {
+  it("a value outside the four spellings throws an Error naming MCP_HTTP_STATELESS", () => {
+    process.env["MCP_HTTP_STATELESS"] = "yes";
+    expect(() => readStatelessEnv(true)).toThrow(Error);
+    expect(() => readStatelessEnv(true)).toThrow(/MCP_HTTP_STATELESS/);
+  });
+
+  it("MCP_RATE_LIMIT_READ_PER_MIN='' yields the default 60, never NaN", () => {
+    process.env["MCP_RATE_LIMIT_READ_PER_MIN"] = "";
+    expect(httpTransportConfigFromEnv().rateLimits.readPerMin).toBe(60);
+  });
+
+  it("MCP_RATE_LIMIT_WRITE_PER_MIN='' yields the default 10, never NaN", () => {
+    process.env["MCP_RATE_LIMIT_WRITE_PER_MIN"] = "";
+    expect(httpTransportConfigFromEnv().rateLimits.writePerMin).toBe(10);
+  });
+});
+
+describe("httpTransportConfigFromEnv — today's reading of every other variable", () => {
+  it("unset, it returns today's defaults", () => {
+    expect(httpTransportConfigFromEnv()).toEqual({
+      port: 8080,
+      path: "/mcp",
+      rateLimits: { readPerMin: 60, writePerMin: 10 },
+      cors: { writeAllowedOrigins: [] },
+      abuse: {
+        captureLeadDailyCapPerIp: 50,
+        startPurchaseDailyCapPerIp: 20,
+        createBookingDailyCapPerIp: 20,
+        submitFlowStepDailyCapPerIp: 50,
+        blockedUserAgents: "",
+      },
+    });
+  });
+
+  it("set, it reads each variable as src/index.ts did", () => {
+    process.env["MCP_HTTP_PORT"] = "9090";
+    process.env["MCP_HTTP_PATH"] = "/agents";
+    process.env["MCP_RATE_LIMIT_READ_PER_MIN"] = "120";
+    process.env["MCP_RATE_LIMIT_WRITE_PER_MIN"] = "5";
+    process.env["MCP_CORS_WRITE_ALLOWED_ORIGINS"] =
+      "https://a.example, https://b.example";
+    process.env["MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP"] = "3";
+    process.env["MCP_ABUSE_START_PURCHASE_DAILY_CAP"] = "2";
+    process.env["MCP_ABUSE_CREATE_BOOKING_DAILY_CAP"] = "4";
+    process.env["MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP"] = "5";
+    process.env["MCP_ABUSE_BLOCKED_USER_AGENTS"] = "BadBot";
+
+    expect(httpTransportConfigFromEnv()).toEqual({
+      port: 9090,
+      path: "/agents",
+      rateLimits: { readPerMin: 120, writePerMin: 5 },
+      cors: { writeAllowedOrigins: ["https://a.example", "https://b.example"] },
+      abuse: {
+        captureLeadDailyCapPerIp: 3,
+        startPurchaseDailyCapPerIp: 2,
+        createBookingDailyCapPerIp: 4,
+        submitFlowStepDailyCapPerIp: 5,
+        blockedUserAgents: "BadBot",
+      },
+    });
+  });
+});
+
+// #8071 AC-5, through the wiring both entries use: the env value reaches the
+// AbuseGuard the HTTP transport builds from `config.abuse`
+// (http-transport.ts). A guard built straight from AbuseConfig cannot show
+// this — it defaults an absent cap on its own — so each case also pins the
+// value httpTransportConfigFromEnv() returns.
+describe("#8071 AC-5 — the booking and flow-step caps reach the guard both entries build", () => {
+  const CASES = [
+    {
+      toolName: "create_booking",
+      envVar: "MCP_ABUSE_CREATE_BOOKING_DAILY_CAP",
+      field: "createBookingDailyCapPerIp",
+      defaultCap: DEFAULT_CREATE_BOOKING_DAILY_CAP,
+    },
+    {
+      toolName: "submit_flow_step",
+      envVar: "MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP",
+      field: "submitFlowStepDailyCapPerIp",
+      defaultCap: DEFAULT_SUBMIT_FLOW_STEP_DAILY_CAP,
+    },
+  ] as const;
+
+  /** Calls `toolName` until refused; returns how many calls were allowed. */
+  function allowedCalls(toolName: string, limit: number): number {
+    const guard = new AbuseGuard(httpTransportConfigFromEnv().abuse);
+    const request = requestFrom("198.51.100.7");
+    let allowed = 0;
+    while (allowed <= limit && guard.validate(toolName, {}, request).allowed) {
+      allowed += 1;
+    }
+    return allowed;
+  }
+
+  describe.each(CASES)("$envVar", ({ toolName, envVar, field, defaultCap }) => {
+    it.each(["", "abc"])(
+      "set to %p yields the default cap, refusing the call at default + 1",
+      (raw) => {
+        process.env[envVar] = raw;
+        expect(httpTransportConfigFromEnv().abuse[field]).toBe(defaultCap);
+        expect(allowedCalls(toolName, defaultCap)).toBe(defaultCap);
+      },
+    );
+
+    it("set to a positive integer, the guard refuses the call past that cap", () => {
+      process.env[envVar] = "3";
+      expect(httpTransportConfigFromEnv().abuse[field]).toBe(3);
+      expect(allowedCalls(toolName, defaultCap)).toBe(3);
+    });
+  });
+});

package/templates/apps/mcp/__tests__/http-transport.test.ts

@@ -20,12 +20,20 @@
  * - Blocked UA returns 403
  * - #5971: a start_purchase burst past the per-IP daily cap is refused with
  *   the rate-limit error, and no Checkout Session is created
+ * - #8071: create_booking and submit_flow_step take the same write branch —
+ *   the origin allow-list, each tool's own daily cap (no hub call for a
+ *   refused one), one cap unit per batched call, and for create_booking an
+ *   attendee.email format check
+ * - #8073: a capture_lead call forwards the socket address the transport
+ *   trusted (never a caller-forged X-Forwarded-For) plus
+ *   AILK_VISITOR_FORWARD_KEY as the two visitor-forwarding headers, and sends
+ *   neither when the key is unset
  */
 
 import type { AddressInfo } from "node:net";
 
 import type { FastifyInstance, FastifyRequest } from "fastify";
-import { checkout } from "@working-theory/api-client";
+import { apiClient, checkout } from "@working-theory/api-client";
 
 import {
   __setMcpCommerceClaimForTest,
@@ -41,7 +49,17 @@ import { listRegisteredTools } from "../src/server.js";
 
 jest.mock("@working-theory/api-client", () => {
   const actual = jest.requireActual("@working-theory/api-client");
-  return { ...actual, checkout: { createSession: jest.fn() } };
+  // The hub stubs for the two #8071 write tools: every other surface stays
+  // real, so a tool these tests do not name behaves exactly as before.
+  return {
+    ...actual,
+    checkout: { createSession: jest.fn() },
+    apiClient: {
+      ...actual.apiClient,
+      schedule: { ...actual.apiClient.schedule, book: jest.fn() },
+      flows: { ...actual.apiClient.flows, submitStep: jest.fn() },
+    },
+  };
 });
 
 /** Permissive JSON-RPC 2.0 envelope type for response body assertions. */
@@ -340,6 +358,70 @@ describe("Abuse rules", () => {
   });
 });
 
+/**
+ * #8073 — the lead-write tools forward the address the transport TRUSTED
+ * (`request.ip`), not a caller-supplied `X-Forwarded-For` value. The
+ * long-running entry (`buildHttpTransportApp`, used throughout this file)
+ * sets no `trustProxy`, so `request.ip` is always the real socket address —
+ * 127.0.0.1 here — exactly the D5 guarantee a forged header cannot move.
+ */
+describe("capture_lead forwards the trusted caller address (#8073)", () => {
+  let app: FastifyInstance;
+  let port: number;
+  let submitSpy: jest.SpiedFunction<typeof apiClient.leads.submit>;
+
+  beforeEach(async () => {
+    submitSpy = jest
+      .spyOn(apiClient.leads, "submit")
+      .mockResolvedValue({ ok: true, body: { id: "lead_1", persisted: "db" } });
+    app = await buildHttpTransportApp(DEFAULT_CONFIG);
+    await app.listen({ host: "127.0.0.1", port: 0 });
+    port = (app.server.address() as AddressInfo).port;
+  });
+
+  afterEach(async () => {
+    await app.close();
+    submitSpy.mockRestore();
+    delete process.env.AILK_VISITOR_FORWARD_KEY;
+  });
+
+  function capturePayload(id: number, email: string) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      method: "tools/call",
+      params: { name: "capture_lead", arguments: { name: "Jane", email } },
+    };
+  }
+
+  it("sends the socket address and the forward key as the two visitor headers", async () => {
+    process.env.AILK_VISITOR_FORWARD_KEY = "spoke-key";
+
+    const res = await mcpPost(port, capturePayload(40, "jane@example.com"), {
+      // A caller-forged hop: D5 says this must not move the key.
+      "x-forwarded-for": "203.0.113.7",
+    });
+
+    expect(res.status).toBe(200);
+    expect(submitSpy).toHaveBeenCalledTimes(1);
+    const init = submitSpy.mock.calls[0]?.[1];
+    expect(init?.headers).toEqual({
+      "x-ailk-visitor-ip": "127.0.0.1",
+      "x-ailk-visitor-forward-key": "spoke-key",
+    });
+  });
+
+  it("sends no visitor headers (and no second argument) when the key is unset", async () => {
+    delete process.env.AILK_VISITOR_FORWARD_KEY;
+
+    const res = await mcpPost(port, capturePayload(41, "jane2@example.com"));
+
+    expect(res.status).toBe(200);
+    expect(submitSpy).toHaveBeenCalledTimes(1);
+    expect(submitSpy.mock.calls[0]).toHaveLength(1);
+  });
+});
+
 /**
  * AC-3 — a `start_purchase` burst beyond the AbuseGuard per-IP cap is refused
  * with the rate-limit error and creates no Checkout Session (#5971 D6).
@@ -860,3 +942,210 @@ describe("abuse refusal status is keyed on the typed reason code (#5994)", () =>
     expect(ABUSE_REFUSAL_STATUS[AbuseReasonCode.INVALID_EMAIL]).toBe(422);
   });
 });
+
+/**
+ * #8071 — `create_booking` and `submit_flow_step` send caller-chosen data to
+ * the hub, so they take the same write branch as `capture_lead`: the
+ * write-origin allow-list, then the AbuseGuard once per call — each on its OWN
+ * daily-cap tracker.
+ *
+ * Every assertion here is a refusal the preHandler makes, so the suite holds
+ * in a scaffold that does not register the tool (no `scheduling` or
+ * `signal-collectors` module): the hub stub is checked for "no request for the
+ * refused call", never for a count the handler would have to produce.
+ */
+const HUB_WRITE_TOOLS = [
+  {
+    toolName: "create_booking",
+    capField: "createBookingDailyCapPerIp",
+    hubStub: () => apiClient.schedule.book as jest.Mock,
+    args: () => ({
+      calLink: "acme/intro",
+      start: "2030-01-07T15:00:00.000Z",
+      attendee: { name: "Ada", email: "ada@example.com" },
+    }),
+  },
+  {
+    toolName: "submit_flow_step",
+    capField: "submitFlowStepDailyCapPerIp",
+    hubStub: () => apiClient.flows.submitStep as jest.Mock,
+    args: () => ({
+      slug: "intake",
+      stepKey: "contact",
+      values: { company: "Acme" },
+    }),
+  },
+] as const;
+
+describe.each(HUB_WRITE_TOOLS)(
+  "$toolName takes the write branch of the HTTP guard (#8071)",
+  ({ toolName, capField, hubStub, args }) => {
+    const CAP = 2;
+    const config = {
+      ...DEFAULT_CONFIG,
+      cors: { writeAllowedOrigins: ["https://allowed.example"] as string[] },
+      abuse: {
+        captureLeadDailyCapPerIp: 50,
+        startPurchaseDailyCapPerIp: 20,
+        [capField]: CAP,
+        blockedUserAgents: "",
+      },
+    };
+
+    let app: FastifyInstance;
+    let port: number;
+
+    function call(id: number, callArgs: object = args()) {
+      return {
+        jsonrpc: "2.0",
+        id,
+        method: "tools/call",
+        params: { name: toolName, arguments: callArgs },
+      };
+    }
+
+    beforeEach(async () => {
+      hubStub().mockResolvedValue({ ok: false, status: 503, body: {} });
+      app = await buildHttpTransportApp(config);
+      await app.listen({ host: "127.0.0.1", port: 0 });
+      port = (app.server.address() as AddressInfo).port;
+    });
+
+    afterEach(async () => {
+      await app.close();
+      jest.clearAllMocks();
+    });
+
+    it("is a member of WRITE_TOOLS", () => {
+      expect(WRITE_TOOLS.has(toolName)).toBe(true);
+    });
+
+    it("refuses a call from an origin not on writeAllowedOrigins with 403", async () => {
+      const res = await mcpPost(port, call(80), {
+        origin: "https://evil.example",
+      });
+
+      expect(res.status).toBe(403);
+      const body = (await res.json()) as { error?: string };
+      expect(body.error).toContain("CORS");
+      expect(hubStub()).not.toHaveBeenCalled();
+    });
+
+    it("refuses the call past its daily cap with 403, and the hub gets no request for it", async () => {
+      for (let i = 0; i < CAP; i += 1) {
+        const res = await mcpPost(port, call(81 + i));
+        expect(res.status).toBe(200);
+      }
+      const hubCallsBefore = hubStub().mock.calls.length;
+
+      const capped = await mcpPost(port, call(90));
+
+      expect(capped.status).toBe(403);
+      const body = (await capped.json()) as { error?: string };
+      expect(body.error).toContain(toolName);
+      expect(hubStub().mock.calls.length).toBe(hubCallsBefore);
+    });
+
+    it("a batch of N calls charges N cap units", async () => {
+      const res = await mcpPost(port, [call(91), call(92), call(93)]);
+
+      expect(res.status).toBe(403);
+      expect(hubStub()).not.toHaveBeenCalled();
+    });
+
+    it("its cap is its own — spending it leaves capture_lead callable", async () => {
+      for (let i = 0; i < CAP; i += 1) await mcpPost(port, call(94 + i));
+      expect((await mcpPost(port, call(97))).status).toBe(403);
+
+      const lead = await mcpPost(port, {
+        jsonrpc: "2.0",
+        id: 98,
+        method: "tools/call",
+        params: {
+          name: "capture_lead",
+          arguments: { name: "Ada", email: "ada@example.com" },
+        },
+      });
+      expect(lead.status).not.toBe(403);
+    });
+
+    it("a refusal maps through the typed code: past the cap is DAILY_CAP_REACHED", () => {
+      const guard = new AbuseGuard({
+        captureLeadDailyCapPerIp: 50,
+        [capField]: 1,
+        blockedUserAgents: "",
+      });
+      // @ts-expect-error: a stub carrying only the two members the guard reads.
+      const request: FastifyRequest = {
+        headers: { "user-agent": "Mozilla/5.0 (compatible; TestAgent/1.0)" },
+        ip: "203.0.113.9",
+      };
+
+      expect(guard.validate(toolName, args(), request).allowed).toBe(true);
+      const refused = guard.validate(toolName, args(), request);
+
+      expect(refused.allowed).toBe(false);
+      if (refused.allowed) return;
+      expect(refused.code).toBe(AbuseReasonCode.DAILY_CAP_REACHED);
+      expect(ABUSE_REFUSAL_STATUS[refused.code]).toBe(403);
+    });
+  },
+);
+
+describe("create_booking — attendee.email is format-checked before the hub (#8071)", () => {
+  let app: FastifyInstance;
+  let port: number;
+
+  const book = () => apiClient.schedule.book as jest.Mock;
+
+  function booking(id: number, attendee: unknown) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      method: "tools/call",
+      params: {
+        name: "create_booking",
+        arguments: {
+          calLink: "acme/intro",
+          start: "2030-01-07T15:00:00.000Z",
+          attendee,
+        },
+      },
+    };
+  }
+
+  beforeEach(async () => {
+    book().mockResolvedValue({ ok: false, status: 503, body: {} });
+    app = await buildHttpTransportApp(DEFAULT_CONFIG);
+    await app.listen({ host: "127.0.0.1", port: 0 });
+    port = (app.server.address() as AddressInfo).port;
+  });
+
+  afterEach(async () => {
+    await app.close();
+    jest.clearAllMocks();
+  });
+
+  it("refuses a malformed attendee.email with 422 and leaves the hub stub untouched", async () => {
+    const res = await mcpPost(
+      port,
+      booking(100, { name: "Spammer", email: "not-an-email" }),
+    );
+
+    expect(res.status).toBe(422);
+    const body = (await res.json()) as { error?: string };
+    expect(body.error).toContain("email");
+    expect(book()).not.toHaveBeenCalled();
+  });
+
+  it.each([null, "ada@example.com", ["ada@example.com"], 42])(
+    "a non-object attendee (%p) is not a guard refusal and never a 500",
+    async (attendee) => {
+      const res = await mcpPost(port, booking(101, attendee));
+
+      // The handler's own Zod schema is the authority on the shape.
+      expect(res.status).toBe(200);
+      expect(book()).not.toHaveBeenCalled();
+    },
+  );
+});