create-ailk 0.5.0 → 0.6.0

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

@@ -18,14 +18,32 @@
  * - Abuse rules reject invalid email on capture_lead
  * - Honeypot field rejection on capture_lead
  * - 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
  */
 
 import type { AddressInfo } from "node:net";
 
-import type { FastifyInstance } from "fastify";
-import { buildHttpTransportApp } from "../src/http-transport.js";
+import type { FastifyInstance, FastifyRequest } from "fastify";
+import { checkout } from "@working-theory/api-client";
+
+import {
+  __setMcpCommerceClaimForTest,
+  resetMcpCommerceClaim,
+} from "../src/lib/commerce-claim.js";
+import { AbuseGuard, AbuseReasonCode } from "../src/abuse/index.js";
+import {
+  ABUSE_REFUSAL_STATUS,
+  buildHttpTransportApp,
+  WRITE_TOOLS,
+} from "../src/http-transport.js";
 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() } };
+});
+
 /** Permissive JSON-RPC 2.0 envelope type for response body assertions. */
 type JsonRpcResponse = {
   jsonrpc?: string;
@@ -321,3 +339,524 @@ describe("Abuse rules", () => {
     }
   });
 });
+
+/**
+ * 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).
+ *
+ * The refusal happens in the POST preHandler, BEFORE the MCP handler runs, so
+ * `checkout.createSession` is the thing to count: it is called once per call
+ * that got through and never for the one that was refused.
+ *
+ * `start_purchase` takes the write branch only because #5971 added it to
+ * `WRITE_TOOLS`; on the read branch the AbuseGuard checks the UA deny list
+ * alone and the cap would never be consulted.
+ */
+describe("start_purchase — per-IP daily cap (#5971)", () => {
+  const CAP = 2;
+  const CAPPED_CONFIG = {
+    ...DEFAULT_CONFIG,
+    cors: { writeAllowedOrigins: ["*"] as string[] },
+    abuse: {
+      captureLeadDailyCapPerIp: 50,
+      startPurchaseDailyCapPerIp: CAP,
+      blockedUserAgents: "",
+    },
+  };
+
+  const createSession = checkout.createSession as jest.MockedFunction<
+    typeof checkout.createSession
+  >;
+
+  let app: FastifyInstance;
+  let port: number;
+
+  function purchasePayload(id: number) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      method: "tools/call",
+      params: {
+        name: "start_purchase",
+        arguments: { productCode: "pro-plan" },
+      },
+    };
+  }
+
+  beforeEach(async () => {
+    __setMcpCommerceClaimForTest("claimed");
+    createSession.mockResolvedValue({
+      ok: true,
+      body: {
+        sessionId: "cs_test_burst",
+        url: "https://checkout.stripe.com/c/pay/cs_test_burst",
+      },
+    });
+    app = await buildHttpTransportApp(CAPPED_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();
+    resetMcpCommerceClaim();
+  });
+
+  it("refuses the call past the cap with 403 and a 'daily cap' reason", async () => {
+    const first = await mcpPost(port, purchasePayload(30));
+    const second = await mcpPost(port, purchasePayload(31));
+    const third = await mcpPost(port, purchasePayload(32));
+
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(200);
+    expect(third.status).toBe(403);
+
+    const body = (await third.json()) as { error?: string };
+    expect(body.error).toContain("daily");
+    expect(body.error).toContain("cap");
+  });
+
+  it("creates no Checkout Session for the refused call", async () => {
+    await mcpPost(port, purchasePayload(33));
+    await mcpPost(port, purchasePayload(34));
+    await mcpPost(port, purchasePayload(35));
+
+    expect(createSession).toHaveBeenCalledTimes(CAP);
+  });
+
+  it("start_purchase takes the write branch, so the guard sees it at all", async () => {
+    const res = await mcpPost(port, purchasePayload(36), {
+      "user-agent": "curl/8.0",
+    });
+
+    // A built-in blocked UA is refused on the write branch; a read-branch
+    // tool would be too, but only the write branch consults the cap above.
+    expect(res.status).toBe(403);
+  });
+});
+
+/**
+ * JSON-RPC BATCH envelope — the write branch must survive it (#5971 security
+ * review, High).
+ *
+ * JSON-RPC 2.0 allows an ARRAY of messages in one POST, and the pinned MCP SDK
+ * dispatches every one of them. The write-tool guard used to read
+ * `body.method` on a body that may be an array: an array has no `.method`, so
+ * the whole batch was classified as a READ, skipping the write-origin
+ * allow-list and every AbuseGuard rule — including the per-IP daily cap. N
+ * batched `start_purchase` calls then executed on zero cap units, each one
+ * creating a real Stripe Checkout Session on the seller's account.
+ *
+ * These tests pin the envelope, not the tool: any future WRITE_TOOLS addition
+ * inherits them. The gap predated `start_purchase` and covered the three other
+ * write tools too, which is why the last case here is `capture_lead`.
+ */
+describe("JSON-RPC batch bodies take the write branch (#5971)", () => {
+  const CAP = 2;
+  const BATCH_CONFIG = {
+    ...DEFAULT_CONFIG,
+    cors: { writeAllowedOrigins: ["*"] as string[] },
+    abuse: {
+      captureLeadDailyCapPerIp: CAP,
+      startPurchaseDailyCapPerIp: CAP,
+      blockedUserAgents: "",
+    },
+  };
+
+  const createSession = checkout.createSession as jest.MockedFunction<
+    typeof checkout.createSession
+  >;
+
+  let app: FastifyInstance;
+  let port: number;
+
+  function purchaseMessage(id: number) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      method: "tools/call",
+      params: {
+        name: "start_purchase",
+        arguments: { productCode: "pro-plan" },
+      },
+    };
+  }
+
+  beforeEach(async () => {
+    __setMcpCommerceClaimForTest("claimed");
+    createSession.mockResolvedValue({
+      ok: true,
+      body: {
+        sessionId: "cs_test_batch",
+        url: "https://checkout.stripe.com/c/pay/cs_test_batch",
+      },
+    });
+    app = await buildHttpTransportApp(BATCH_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();
+    resetMcpCommerceClaim();
+  });
+
+  it("a batch of N write calls consumes N cap units, not one", async () => {
+    // One POST carrying CAP + 1 messages. Under the old per-request check this
+    // returned 200 and executed every one; the cap must refuse it outright.
+    const res = await mcpPost(port, [
+      purchaseMessage(40),
+      purchaseMessage(41),
+      purchaseMessage(42),
+    ]);
+
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error?: string };
+    expect(body.error).toContain("daily cap");
+  });
+
+  it("refuses the batch before the SDK dispatches any of its messages", async () => {
+    await mcpPost(port, [
+      purchaseMessage(43),
+      purchaseMessage(44),
+      purchaseMessage(45),
+    ]);
+
+    // Refused in the preHandler ⇒ no Checkout Session for ANY message.
+    expect(createSession).not.toHaveBeenCalled();
+  });
+
+  it("a batch within the cap still works, and charges one unit per message", async () => {
+    const res = await mcpPost(port, [purchaseMessage(46), purchaseMessage(47)]);
+    expect(res.status).toBe(200);
+
+    // Both units are now spent, so a single further call is refused.
+    const third = await mcpPost(port, purchaseMessage(48));
+    expect(third.status).toBe(403);
+  });
+
+  it("a batch is subject to the write-origin allow-list", async () => {
+    const strictApp = await buildHttpTransportApp({
+      ...BATCH_CONFIG,
+      cors: { writeAllowedOrigins: [] as string[] },
+    });
+    await strictApp.listen({ host: "127.0.0.1", port: 0 });
+    const strictPort = (strictApp.server.address() as AddressInfo).port;
+
+    try {
+      const res = await mcpPost(strictPort, [purchaseMessage(49)], {
+        origin: "https://evil.example",
+      });
+      expect(res.status).toBe(403);
+      const body = (await res.json()) as { error?: string };
+      expect(body.error).toContain("CORS");
+    } finally {
+      await strictApp.close();
+    }
+  });
+
+  it("the same protection covers the pre-existing write tools (capture_lead)", async () => {
+    const leadMessage = (id: number) => ({
+      jsonrpc: "2.0",
+      id,
+      method: "tools/call",
+      params: {
+        name: "capture_lead",
+        arguments: { name: "A", email: "a@example.com" },
+      },
+    });
+
+    const res = await mcpPost(port, [
+      leadMessage(50),
+      leadMessage(51),
+      leadMessage(52),
+    ]);
+
+    expect(res.status).toBe(403);
+  });
+
+  it("a batch of READ messages is unaffected", async () => {
+    const res = await mcpPost(port, [TOOLS_LIST_PAYLOAD]);
+    expect(res.status).toBe(200);
+  });
+});
+
+/**
+ * Guardrail — batch coverage is driven from WRITE_TOOLS itself (#5971 security
+ * review round 2), not from hand-picked names.
+ *
+ * The round-1 defect was invisible because every existing test used the
+ * single-message envelope. A comment on WRITE_TOOLS saying "enforce this
+ * batch-aware" is the weakest available remedy for a defect whose whole
+ * character was that nobody thought to send an array — so the inheritance is
+ * mechanical here: a tool added to WRITE_TOOLS without batch enforcement fails
+ * this suite on its first run.
+ *
+ * The assertion is the write-branch ORIGIN check rather than the cap, because
+ * it needs no per-tool arguments and no per-tool budget — only two of the four
+ * write tools carry a daily cap (see DAILY_CAPPED_TOOLS).
+ */
+describe.each([...WRITE_TOOLS])(
+  "a batch naming %s takes the write branch (#5971)",
+  (toolName) => {
+    let app: FastifyInstance;
+    let port: number;
+
+    beforeEach(async () => {
+      // Empty allow-list ⇒ a cross-origin write must be refused. On the read
+      // branch the origin is never consulted, so a 200 here means the batch
+      // was misclassified.
+      app = await buildHttpTransportApp({
+        ...DEFAULT_CONFIG,
+        cors: { writeAllowedOrigins: [] as string[] },
+      });
+      await app.listen({ host: "127.0.0.1", port: 0 });
+      port = (app.server.address() as AddressInfo).port;
+    });
+
+    afterEach(async () => {
+      await app.close();
+    });
+
+    it("is refused by the write-origin allow-list inside an array body", async () => {
+      const res = await mcpPost(
+        port,
+        [
+          {
+            jsonrpc: "2.0",
+            id: 60,
+            method: "tools/call",
+            params: { name: toolName, arguments: {} },
+          },
+        ],
+        { origin: "https://evil.example" },
+      );
+
+      expect(res.status).toBe(403);
+    });
+  },
+);
+
+/**
+ * Guardrail — a blank or malformed cap must not silently disable enforcement
+ * (#5971 security review round 2, Medium).
+ *
+ * `parseInt("")` is NaN, NaN survives every `??` guard, and `count >= NaN` is
+ * always false — so the cap stops refusing anything, with no log and no
+ * startup warning. A misconfigured deployment looks identical to a correct one
+ * at rest, which is why this is pinned rather than left to convention.
+ */
+describe("a non-finite daily cap falls back to the default, never to unlimited (#5971)", () => {
+  let app: FastifyInstance;
+  let port: number;
+
+  afterEach(async () => {
+    if (app) await app.close();
+    jest.clearAllMocks();
+    resetMcpCommerceClaim();
+  });
+
+  async function startWithCap(cap: number): Promise<void> {
+    __setMcpCommerceClaimForTest("claimed");
+    (
+      checkout.createSession as jest.MockedFunction<
+        typeof checkout.createSession
+      >
+    ).mockResolvedValue({
+      ok: true,
+      body: { sessionId: "cs_nan", url: "https://checkout.stripe.com/c/nan" },
+    });
+    app = await buildHttpTransportApp({
+      ...DEFAULT_CONFIG,
+      cors: { writeAllowedOrigins: ["*"] as string[] },
+      abuse: {
+        captureLeadDailyCapPerIp: 50,
+        startPurchaseDailyCapPerIp: cap,
+        blockedUserAgents: "",
+      },
+    });
+    await app.listen({ host: "127.0.0.1", port: 0 });
+    port = (app.server.address() as AddressInfo).port;
+  }
+
+  it("NaN does not disable the start_purchase cap", async () => {
+    // What `parseInt("")` on a blank MCP_ABUSE_START_PURCHASE_DAILY_CAP yields.
+    await startWithCap(Number.NaN);
+
+    // The default (20) must still bite. 21 calls ⇒ the last one is refused.
+    let lastStatus = 0;
+    for (let i = 0; i < 21; i += 1) {
+      const res = await mcpPost(port, {
+        jsonrpc: "2.0",
+        id: 70 + i,
+        method: "tools/call",
+        params: {
+          name: "start_purchase",
+          arguments: { productCode: "pro-plan" },
+        },
+      });
+      lastStatus = res.status;
+    }
+
+    expect(lastStatus).toBe(403);
+  });
+});
+
+/**
+ * #5994 — the 403-vs-422 split is keyed on a TYPED reason code, never on the
+ * wording of the refusal reason.
+ *
+ * The guard refuses for two different kinds of reason and the transport owes
+ * them different statuses: a refusal of the CALLER (blocked UA, per-IP daily
+ * cap) is 403, a refusal of the INPUT (honeypot, malformed email) is 422.
+ * Before this change the transport told them apart with
+ * `reason.includes("daily cap")`, so a reworded reason silently turned a
+ * rate-limit refusal into a 422 — and `capture_lead`'s wording carried the
+ * substring only by accident ("daily capture_lead cap" contains "daily cap"
+ * because the tool name starts with "cap").
+ *
+ * These tests pin the mapping from the code, and assert the two daily-capped
+ * tools — whose reason wordings differ — both reach 403 through it.
+ */
+describe("abuse refusal status is keyed on the typed reason code (#5994)", () => {
+  const CODE_KEYED_CONFIG = {
+    ...DEFAULT_CONFIG,
+    cors: { writeAllowedOrigins: ["*"] as string[] },
+    abuse: {
+      captureLeadDailyCapPerIp: 1,
+      startPurchaseDailyCapPerIp: 1,
+      blockedUserAgents: "",
+    },
+  };
+
+  const createSession = checkout.createSession as jest.MockedFunction<
+    typeof checkout.createSession
+  >;
+
+  let app: FastifyInstance;
+  let port: number;
+
+  beforeEach(async () => {
+    __setMcpCommerceClaimForTest("claimed");
+    createSession.mockResolvedValue({
+      ok: true,
+      body: {
+        sessionId: "cs_test_5994",
+        url: "https://checkout.stripe.com/c/pay/cs_test_5994",
+      },
+    });
+    app = await buildHttpTransportApp(CODE_KEYED_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();
+    resetMcpCommerceClaim();
+  });
+
+  function captureLeadPayload(id: number, args: Record<string, unknown>) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      method: "tools/call",
+      params: { name: "capture_lead", arguments: args },
+    };
+  }
+
+  it("maps a capture_lead daily-cap refusal to 403", async () => {
+    // The first call spends the IP's single cap unit. Whatever the handler
+    // then makes of it is irrelevant here — only the SECOND call, refused in
+    // the preHandler, is under test.
+    await mcpPost(
+      port,
+      captureLeadPayload(40, { name: "First", email: "first@example.com" }),
+    );
+
+    const capped = await mcpPost(
+      port,
+      captureLeadPayload(41, { name: "Second", email: "second@example.com" }),
+    );
+
+    expect(capped.status).toBe(403);
+  });
+
+  it("maps a start_purchase daily-cap refusal to 403", async () => {
+    const purchase = (id: number) => ({
+      jsonrpc: "2.0",
+      id,
+      method: "tools/call",
+      params: { name: "start_purchase", arguments: { productCode: "pro-plan" } },
+    });
+
+    const first = await mcpPost(port, purchase(42));
+    const capped = await mcpPost(port, purchase(43));
+
+    expect(first.status).toBe(200);
+    expect(capped.status).toBe(403);
+  });
+
+  it("maps a validation refusal to 422", async () => {
+    const res = await mcpPost(
+      port,
+      captureLeadPayload(44, { name: "Spammer", email: "not-an-email" }),
+    );
+
+    expect(res.status).toBe(422);
+  });
+
+  /**
+   * The AbuseGuard reads exactly two things off the request — the
+   * `user-agent` header and `ip`. The UA here is one the built-in deny list
+   * lets through, so Rule 4 (the cap) is what refuses these calls rather than
+   * Rule 1.
+   */
+  function makeGuardRequest(): FastifyRequest {
+    // @ts-expect-error: a stub carrying only the two members the guard reads;
+    // a full FastifyRequest cannot be constructed without a live server.
+    return {
+      headers: { "user-agent": "Mozilla/5.0 (compatible; TestAgent/1.0)" },
+      ip: "203.0.113.7",
+    };
+  }
+
+  it("derives the status from the code alone — the two daily-capped tools word their reasons differently yet both map to 403", () => {
+    const guard = new AbuseGuard({
+      captureLeadDailyCapPerIp: 1,
+      startPurchaseDailyCapPerIp: 1,
+      blockedUserAgents: "",
+    });
+    const request = makeGuardRequest();
+
+    // Spend each tool's single cap unit, then collect the refusal.
+    guard.validate("capture_lead", {}, request);
+    guard.validate("start_purchase", {}, request);
+    const lead = guard.validate("capture_lead", {}, request);
+    const purchase = guard.validate("start_purchase", {}, request);
+
+    expect(lead.allowed).toBe(false);
+    expect(purchase.allowed).toBe(false);
+    if (lead.allowed || purchase.allowed) return;
+
+    // Same code, different wording — the wording is prose for the caller, the
+    // code is what the transport reads.
+    expect(lead.code).toBe(AbuseReasonCode.DAILY_CAP_REACHED);
+    expect(purchase.code).toBe(AbuseReasonCode.DAILY_CAP_REACHED);
+    expect(lead.reason).not.toBe(purchase.reason);
+
+    expect(ABUSE_REFUSAL_STATUS[lead.code]).toBe(403);
+    expect(ABUSE_REFUSAL_STATUS[purchase.code]).toBe(403);
+  });
+
+  it("declares a status for every reason code the guard can return", () => {
+    expect(Object.keys(ABUSE_REFUSAL_STATUS).sort()).toEqual(
+      Object.values(AbuseReasonCode).sort(),
+    );
+    expect(ABUSE_REFUSAL_STATUS[AbuseReasonCode.BLOCKED_USER_AGENT]).toBe(403);
+    expect(ABUSE_REFUSAL_STATUS[AbuseReasonCode.HONEYPOT_FILLED]).toBe(422);
+    expect(ABUSE_REFUSAL_STATUS[AbuseReasonCode.INVALID_EMAIL]).toBe(422);
+  });
+});

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

@@ -0,0 +1,39 @@
+/**
+ * Structural ordering guard for apps/mcp's bootstrap (#5876 spec D4, AC-3).
+ *
+ * `apps/mcp/src/index.ts` has real side effects at import time (starts a
+ * transport, opens a stdio/HTTP listener) — it cannot safely be imported by
+ * a test. This reads its source text instead, mirroring the existing
+ * "architectural guard" pattern (`__tests__/read_content.test.ts`).
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+describe("apps/mcp/src/index.ts — bootstrap ordering", () => {
+  const src = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
+
+  it("awaits initMcpPublicWorkspace()", () => {
+    expect(src).toMatch(/await initMcpPublicWorkspace\(\)/);
+  });
+
+  it("awaits initMcpPublicWorkspace() before either transport branch", () => {
+    const initIdx = src.indexOf("await initMcpPublicWorkspace()");
+    const transportBranchIdx = src.indexOf('if (transport === "http")');
+
+    expect(initIdx).toBeGreaterThan(-1);
+    expect(transportBranchIdx).toBeGreaterThan(-1);
+    expect(initIdx).toBeLessThan(transportBranchIdx);
+  });
+
+  it("wraps the await in try/catch — a rejection (DB down at boot) must not crash the whole server (code review, #5876)", () => {
+    const tryIdx = src.indexOf("try {");
+    const initIdx = src.indexOf("await initMcpPublicWorkspace()");
+    const catchIdx = src.indexOf("} catch");
+
+    expect(tryIdx).toBeGreaterThan(-1);
+    expect(catchIdx).toBeGreaterThan(-1);
+    // The await sits strictly between its own try{ and the matching }catch.
+    expect(tryIdx).toBeLessThan(initIdx);
+    expect(initIdx).toBeLessThan(catchIdx);
+  });
+});