create-ailk 0.24.0 → 0.25.1

package/templates/apps/mcp/src/http-transport.ts

@@ -1,564 +0,0 @@
-/**
- * MCP HTTP transport for @working-theory/mcp.
- *
- * Wraps the MCP SDK's StreamableHTTPServerTransport in a Fastify server with:
- *   - @fastify/cors  — open for reads, allowlist-by-config for writes
- *   - @fastify/rate-limit — 60/min reads, 10/min writes (env-overridable)
- *   - abuse heuristics — UA deny list, honeypot, email validation, daily cap
- *
- * Decision references:
- *   Decision 1 — same binary, env-var transport selection (apps/mcp/src/index.ts;
- *                the Vercel entry, apps/mcp/src/app.ts, serves HTTP only — #8070)
- *   Decision 2 — configurable path, default /mcp, standalone root-mounted
- *   Decision 3 — @fastify/rate-limit per-IP token bucket
- *   Decision 4 — in-process abuse heuristics for write tools
- *   Decision 5 — @fastify/cors open reads, allowlist writes
- *
- * Two modes, chosen by `config.stateless` (#8070 D1; the entries read it from
- * `MCP_HTTP_STATELESS` through `readStatelessEnv`, src/boot.ts):
- *   - stateful (the long-running entry's default): an `initialize` creates a
- *     StreamableHTTPServerTransport + McpServer pair kept in an in-memory map
- *     keyed by its Mcp-Session-Id. Sessions live in ONE process's memory and
- *     are not persisted across restarts, so this mode needs a single instance.
- *   - stateless (the Vercel entry's default): every POST gets a fresh
- *     transport + server and no session ID; GET and DELETE answer 400. Any
- *     instance can answer any request.
- *
- * The anonymous `config.path` never reads `Authorization`. Beside it,
- * `${config.path}/workspace` serves the signed-in workspace tools (#3591 D15):
- * POST only and always stateless, each request carrying an agent key that is
- * handed to that request's tools and nothing else — see
- * {@link registerWorkspaceRoute}.
- */
-
-import { randomUUID } from "node:crypto";
-import type { IncomingMessage } from "node:http";
-
-import cors from "@fastify/cors";
-import rateLimit from "@fastify/rate-limit";
-import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import Fastify, {
-  type FastifyInstance,
-  type FastifyReply,
-  type FastifyRequest,
-} from "fastify";
-
-import {
-  AbuseGuard,
-  AbuseReasonCode,
-  type AbuseConfig,
-} from "./abuse/index.js";
-import { trustedCallerAddress } from "./request-context.js";
-import { createMcpServer } from "./server.js";
-import { createWorkspaceMcpServer } from "./workspace-server.js";
-
-/**
- * HTTP status for each {@link AbuseReasonCode} an AbuseGuard refusal can
- * carry (#5994).
- *
- * A refusal of the CALLER — a denied User-Agent, an IP that has spent its
- * daily budget — is **403**: the input was fine, the caller is not allowed to
- * make the call right now. A refusal of the INPUT — a filled honeypot, a
- * malformed email — is **422**.
- *
- * Keying on the code rather than on the refusal prose is what this table is
- * for: the split used to be `reason.includes("daily cap")`, so a reworded
- * reason silently demoted a rate-limit refusal to 422 — and `capture_lead`'s
- * wording only matched by accident, because the tool's name begins with
- * "cap". Typing the record over the full union also means a new reason code
- * fails to compile here until it declares its status.
- */
-export const ABUSE_REFUSAL_STATUS: Record<AbuseReasonCode, 403 | 422> = {
-  [AbuseReasonCode.BLOCKED_USER_AGENT]: 403,
-  [AbuseReasonCode.DAILY_CAP_REACHED]: 403,
-  [AbuseReasonCode.HONEYPOT_FILLED]: 422,
-  [AbuseReasonCode.INVALID_EMAIL]: 422,
-};
-
-/**
- * MCP tool names that are write operations (subject to stricter CORS + rate
- * limits, and to the AbuseGuard).
- *
- * `start_purchase` joined in #5971: it has a side effect at Stripe and it is
- * worth money to abuse, so it takes the write branch — the origin allow-list,
- * the write CORS posture, and `abuseGuard.validate()` — rather than the read
- * branch's UA check alone.
- *
- * `create_booking` and `submit_flow_step` joined in #8071: each forwards
- * caller-chosen data to the hub — a real booking on the seller's calendar
- * that emails the attendee an invite, and a flow step whose completing call
- * can create a Lead — so they take the same branch, each on its own daily
- * cap. `__tests__/write-tool-guard.test.ts` fails when a catalog tool that
- * sends a non-GET request to the hub is missing from this set.
- */
-// Any name added here MUST be enforced through the batch-aware path in
-// writeToolCalls() below — a request body can be a JSON-RPC ARRAY, and a
-// per-request (rather than per-message) check lets N batched calls through on
-// one cap unit. See the #5971 security review and the batch regression tests
-// in __tests__/http-transport.test.ts.
-export const WRITE_TOOLS = new Set([
-  "capture_lead",
-  "subscribe_newsletter",
-  "request_callback",
-  "start_purchase",
-  "create_booking",
-  "submit_flow_step",
-]);
-
-export interface HttpTransportCorsConfig {
-  /**
-   * Origins allowed to call write tools.
-   * Empty array = no cross-origin writes (most restrictive; default).
-   * ["*"] = allow all origins for writes (use only in dev/testing).
-   */
-  writeAllowedOrigins: string[];
-}
-
-export interface HttpTransportRateLimits {
-  /** Max requests per minute per IP for read tools. Default 60. */
-  readPerMin: number;
-  /** Max requests per minute per IP for write tools. Default 10. */
-  writePerMin: number;
-}
-
-export interface HttpTransportConfig {
-  /** URL path to mount the MCP endpoint on. Default "/mcp". */
-  path?: string;
-  /** Rate limit configuration. */
-  rateLimits: HttpTransportRateLimits;
-  /** CORS configuration. */
-  cors: HttpTransportCorsConfig;
-  /** Abuse protection configuration. */
-  abuse: AbuseConfig;
-  /**
-   * When true, use stateless transport mode: no session IDs, every request
-   * creates a fresh McpServer + transport. Needed on a host that runs several
-   * instances (the Vercel entry), and used by tests.
-   * Default: false (stateful). The entries set it from `MCP_HTTP_STATELESS`
-   * (`readStatelessEnv`, src/boot.ts — #8070 D1).
-   */
-  stateless?: boolean;
-}
-
-/** One write-tool invocation found in a request body. */
-interface WriteToolCall {
-  toolName: string;
-  args: unknown;
-}
-
-/**
- * Every write-tool invocation carried by a request body, in order.
- *
- * JSON-RPC 2.0 allows a BATCH: an array of messages in one POST. The MCP SDK
- * honours it — `webStandardStreamableHttp.js` maps an array body to N parsed
- * messages and dispatches every one. So a body must be normalised to a LIST of
- * messages before any of them is classified; inspecting `body.method` on what
- * may be an array silently answers "not a write" for the whole batch, and the
- * request then takes the read branch: no write-origin check, and no
- * `AbuseGuard` cap unit consumed by ANY of the N calls it goes on to execute.
- *
- * That is a real bypass of the per-IP daily cap, and for `start_purchase` each
- * bypassed call creates a genuine Stripe Checkout Session on the seller's
- * account. It predates `start_purchase` — `capture_lead`,
- * `subscribe_newsletter` and `request_callback` have carried it since this
- * transport was written — and normalising here closes it for all four at once
- * (#5971 security review, High).
- *
- * Returns one entry PER matching message, so the caller can charge the guard
- * once per call rather than once per request.
- */
-function writeToolCalls(body: unknown): WriteToolCall[] {
-  const messages = Array.isArray(body) ? body : [body];
-  const calls: WriteToolCall[] = [];
-
-  for (const message of messages) {
-    if (!message || typeof message !== "object") continue;
-    const req = message as Record<string, unknown>;
-    if (req["method"] !== "tools/call") continue;
-    const params = req["params"] as Record<string, unknown> | undefined;
-    if (!params) continue;
-    const toolName = params["name"];
-    if (typeof toolName !== "string" || !WRITE_TOOLS.has(toolName)) continue;
-    calls.push({ toolName, args: params["arguments"] ?? {} });
-  }
-
-  return calls;
-}
-
-/**
- * Determine whether an Origin header is in the write allowlist.
- * ["*"] matches any origin. Empty list blocks all cross-origin writes.
- */
-function isOriginAllowedForWrite(
-  origin: string | undefined,
-  allowedOrigins: string[],
-): boolean {
-  if (!origin) return true; // Same-origin or non-browser clients have no Origin header
-  if (allowedOrigins.includes("*")) return true;
-  return allowedOrigins.includes(origin);
-}
-
-/**
- * The "retry in …" wording of the write bucket's refusal, matching what
- * @fastify/rate-limit's default error says for the same window — `format()`
- * from `@lukeed/ms` over whole seconds, which for a one-minute window is
- * "1 minute" or "N second(s)".
- */
-function retryIn(seconds: number): string {
-  if (seconds >= 60) return "1 minute";
-  return `${seconds} second${seconds === 1 ? "" : "s"}`;
-}
-
-/**
- * An agent key's shape (#3591 D2): `ailk_agt_` plus 32 random bytes in
- * base64url. apps/mcp checks only this; apps/api is where the key is checked.
- */
-const AGENT_BEARER = /^Bearer (ailk_agt_[A-Za-z0-9_-]{43})$/;
-
-/** The agent key an `Authorization` header carries, or null. */
-function agentKeyOf(header: string | string[] | undefined): string | null {
-  if (typeof header !== "string") return null;
-  return AGENT_BEARER.exec(header)?.[1] ?? null;
-}
-
-/**
- * The signed-in workspace surface (#3591 D15) at `path`: POST only, always
- * stateless — a fresh transport and `createWorkspaceMcpServer()` per request,
- * closed when the response ends, and no session map, so GET and DELETE are
- * 405. In order, a POST must:
- *
- *  1. carry `Authorization: Bearer ailk_agt_<43 base64url>` — else 401 in
- *     `onRequest`, before the body is read and before any tool runs. A
- *     personal token (`tok_…`) is refused here like any other shape;
- *  2. be one JSON-RPC message — a batch (array) body is 400;
- *  3. pass the abuse guard's User-Agent check.
- *
- * Rate limiting is apps/api's per-agent limiter, which every forwarded call
- * meets after the key is verified (D4); the app-wide per-IP limit still
- * applies here. The key is attached as the SDK's `req.auth` for this request
- * only, which the SDK hands each tool as `extra.authInfo`.
- */
-function registerWorkspaceRoute(
-  app: FastifyInstance,
-  path: string,
-  abuseGuard: AbuseGuard,
-): void {
-  const notAllowed = async (_request: FastifyRequest, reply: FastifyReply) =>
-    reply
-      .code(405)
-      .header("allow", "POST")
-      .send({ error: "method_not_allowed" });
-  app.get(path, notAllowed);
-  app.delete(path, notAllowed);
-
-  app.post(path, {
-    onRequest: async (request, reply) => {
-      if (agentKeyOf(request.headers["authorization"]) === null) {
-        return reply.code(401).send({ error: "unauthorized" });
-      }
-    },
-    preHandler: async (request, reply) => {
-      if (Array.isArray(request.body)) {
-        return reply.code(400).send({ error: "batch_not_supported" });
-      }
-      const ua = abuseGuard.validate("__read__", {}, request);
-      if (!ua.allowed) {
-        return reply.code(403).send({ error: ua.reason });
-      }
-    },
-    handler: async (request, reply) => {
-      const raw = request.raw as IncomingMessage & { auth?: AuthInfo };
-      raw.auth = {
-        token: agentKeyOf(request.headers["authorization"])!,
-        clientId: "ailk-agent",
-        scopes: [],
-      };
-      const transport = new StreamableHTTPServerTransport({
-        enableJsonResponse: true,
-      });
-      const server = createWorkspaceMcpServer();
-      try {
-        // The cast is the same exactOptionalPropertyTypes one the anonymous
-        // route carries.
-        await server.connect(transport as unknown as Transport);
-        await transport.handleRequest(raw, reply.raw, request.body);
-      } catch (err) {
-        if (!reply.sent) {
-          reply.code(500).send({
-            jsonrpc: "2.0",
-            error: { code: -32603, message: "Internal server error" },
-            id: null,
-          });
-        }
-        throw err;
-      } finally {
-        await transport.close().catch(() => undefined);
-        await server.close().catch(() => undefined);
-      }
-    },
-  });
-}
-
-/**
- * Register the MCP HTTP transport at `config.path` on an existing Fastify
- * instance: CORS, the per-IP rate limit, the abuse guard, the anonymous MCP
- * route and the signed-in workspace route (#8070 D2). The caller owns the
- * instance — and so its options, such as the Vercel entry's `trustProxy`
- * (src/serverless-app.ts).
- *
- * @param app - The Fastify instance to register on (not yet listening)
- * @param config - HTTP transport configuration
- */
-export async function registerHttpTransport(
-  app: FastifyInstance,
-  config: HttpTransportConfig,
-): Promise<void> {
-  const mcpPath = config.path ?? "/mcp";
-  const abuseGuard = new AbuseGuard(config.abuse);
-
-  // Active transports keyed by session ID (stateful mode only).
-  const transports = new Map<string, StreamableHTTPServerTransport>();
-
-  // ── CORS ──────────────────────────────────────────────────────────────────
-  // Read tools: open (origin: true — reflect the caller's Origin).
-  // Write tools: enforced per-request in the preHandler below.
-  // We register a permissive global CORS so browser preflight succeeds for
-  // reads; write-tool CORS is enforced by the preHandler, not this plugin.
-  await app.register(cors, {
-    origin: true,
-    methods: ["GET", "POST", "DELETE", "OPTIONS"],
-  });
-
-  // ── Rate limiting ─────────────────────────────────────────────────────────
-  // Global ceiling — readPerMin per IP, counted on every request (writes
-  // included) by the plugin's own onRequest hook.
-  await app.register(rateLimit, {
-    max: config.rateLimits.readPerMin,
-    timeWindow: "1 minute",
-    keyGenerator: (request: FastifyRequest) => request.ip,
-  });
-
-  // The write bucket — writePerMin per IP, charged in the POST preHandler
-  // below once per write-tool call, after the body is parsed and classified
-  // (#9251). `createRateLimit()` gives it its own in-memory store with the
-  // ceiling's key generator and window; it is the plugin's seam for a second
-  // limiter on a request the ceiling has already counted (a hook from
-  // `app.rateLimit()` would skip such a request as already limited).
-  const writeLimit = app.createRateLimit({
-    max: config.rateLimits.writePerMin,
-    timeWindow: "1 minute",
-  });
-
-  // ── MCP route ─────────────────────────────────────────────────────────────
-
-  // GET — SSE stream for an existing session
-  app.get(mcpPath, async (request, reply) => {
-    const sessionId = request.headers["mcp-session-id"] as string | undefined;
-    if (!sessionId || !transports.has(sessionId)) {
-      reply.code(400).send("Invalid or missing session ID");
-      return;
-    }
-    const transport = transports.get(sessionId)!;
-    await transport.handleRequest(request.raw, reply.raw);
-  });
-
-  // POST — new session initialize or existing session message
-  app.post(mcpPath, {
-    preHandler: async (request, reply) => {
-      const body = request.body as unknown;
-      const origin = request.headers["origin"] as string | undefined;
-
-      // A batch body counts as a write request when ANY of its messages names
-      // a write tool — see writeToolCalls().
-      const writeCalls = writeToolCalls(body);
-
-      // Write-tool CORS enforcement
-      if (writeCalls.length > 0) {
-        if (!isOriginAllowedForWrite(origin, config.cors.writeAllowedOrigins)) {
-          reply
-            .code(403)
-            .send({ error: "CORS: cross-origin write not allowed" });
-          return;
-        }
-
-        // Write-tool rate limit (#9251) — writePerMin per IP, tighter than
-        // the ceiling and counting write-tool calls only. Charged once per
-        // call, like the abuse guard below, so a batch of N spends N units.
-        // The refusal is the one the ceiling emits — the plugin's four
-        // headers and Fastify's 429 error body — so a caller sees one
-        // rate-limit shape whichever bucket ran out, never a tool-level
-        // error (see ABUSE_REFUSAL_STATUS on why that distinction matters).
-        for (const _call of writeCalls) {
-          const limit = await writeLimit(request);
-          if (limit.isAllowed || !limit.isExceeded) continue;
-          reply
-            .code(429)
-            .header("x-ratelimit-limit", limit.max)
-            .header("x-ratelimit-remaining", 0)
-            .header("x-ratelimit-reset", limit.ttlInSeconds)
-            .header("retry-after", limit.ttlInSeconds)
-            .send({
-              statusCode: 429,
-              error: "Too Many Requests",
-              message: `Rate limit exceeded, retry in ${retryIn(limit.ttlInSeconds)}`,
-            });
-          return;
-        }
-
-        // Abuse heuristics — charged ONCE PER CALL, not once per request, so a
-        // batch of N cannot spend one cap unit and execute N times. The whole
-        // request is refused on the first message that fails, before the SDK
-        // dispatches any of them.
-        for (const { toolName, args } of writeCalls) {
-          const abuseResult = abuseGuard.validate(toolName, args, request);
-          if (!abuseResult.allowed) {
-            reply
-              .code(ABUSE_REFUSAL_STATUS[abuseResult.code])
-              .send({ error: abuseResult.reason });
-            return;
-          }
-        }
-      } else {
-        // Read-tool or protocol message: check UA deny list only
-        const abuseGuardResult = abuseGuard.validate("__read__", {}, request);
-        if (!abuseGuardResult.allowed) {
-          reply.code(403).send({ error: abuseGuardResult.reason });
-          return;
-        }
-      }
-    },
-    handler: async (request, reply) =>
-      // The lead-write tools read this address (#8073) through
-      // `visitorForwardHeadersForThisCall()` while the SDK dispatches their
-      // call, somewhere inside `transport.handleRequest()` below — the whole
-      // handler body runs inside the store so every path reaches it.
-      trustedCallerAddress.run(request.ip, async () => {
-        const body = request.body as unknown;
-        const sessionId = request.headers["mcp-session-id"] as
-          | string
-          | undefined;
-
-        try {
-          let transport: StreamableHTTPServerTransport;
-
-          if (config.stateless) {
-            // Stateless mode: each request gets a fresh transport + server.
-            // enableJsonResponse: true ensures plain JSON responses (no SSE).
-            // sessionIdGenerator is intentionally omitted (stateless = no sessions).
-            transport = new StreamableHTTPServerTransport({
-              enableJsonResponse: true,
-            });
-            const server = createMcpServer();
-            // Cast needed: SDK's StreamableHTTPServerTransport.onclose is typed
-            // as `(() => void) | undefined`, which conflicts with Transport.onclose
-            // under exactOptionalPropertyTypes: true. The runtime behaviour is
-            // identical; the cast is safe.
-            await server.connect(transport as unknown as Transport);
-            try {
-              await transport.handleRequest(request.raw, reply.raw, body);
-            } finally {
-              // Close the per-request transport + server to release internal
-              // handles. Without this, the MCP SDK's transport leaves open
-              // sockets that surface as `socket.destroySoon is not a function`
-              // during Jest teardown on Node 20.x (@hono/node-server compat).
-              await transport.close().catch(() => undefined);
-              await server.close().catch(() => undefined);
-            }
-            return;
-          }
-
-          if (sessionId && transports.has(sessionId)) {
-            // Existing session — reuse transport
-            transport = transports.get(sessionId)!;
-          } else if (!sessionId && isInitializeRequest(body)) {
-            // New initialization — create a stateful transport + fresh server
-            transport = new StreamableHTTPServerTransport({
-              sessionIdGenerator: () => randomUUID(),
-              onsessioninitialized: (sid) => {
-                transports.set(sid, transport);
-              },
-            });
-
-            transport.onclose = () => {
-              const sid = transport.sessionId;
-              if (sid) transports.delete(sid);
-            };
-
-            const server = createMcpServer();
-            // Cast needed: SDK's StreamableHTTPServerTransport.onclose is typed
-            // as `(() => void) | undefined`, which conflicts with Transport.onclose
-            // under exactOptionalPropertyTypes: true. The runtime behaviour is
-            // identical; the cast is safe.
-            await server.connect(transport as unknown as Transport);
-          } else {
-            reply.code(400).send({
-              jsonrpc: "2.0",
-              error: {
-                code: -32000,
-                message: "Bad Request: no valid session",
-              },
-              id: null,
-            });
-            return;
-          }
-
-          await transport.handleRequest(request.raw, reply.raw, body);
-        } catch (err) {
-          if (!reply.sent) {
-            reply.code(500).send({
-              jsonrpc: "2.0",
-              error: { code: -32603, message: "Internal server error" },
-              id: null,
-            });
-          }
-          throw err;
-        }
-      }),
-  });
-
-  // DELETE — session termination
-  app.delete(mcpPath, async (request, reply) => {
-    const sessionId = request.headers["mcp-session-id"] as string | undefined;
-    if (!sessionId || !transports.has(sessionId)) {
-      reply.code(400).send("Invalid or missing session ID");
-      return;
-    }
-    const transport = transports.get(sessionId)!;
-    await transport.handleRequest(request.raw, reply.raw);
-  });
-
-  // ── Signed-in workspace route (#3591 D15) ─────────────────────────────────
-  registerWorkspaceRoute(app, `${mcpPath}/workspace`, abuseGuard);
-}
-
-/**
- * Build and return a configured Fastify instance that exposes the MCP HTTP
- * transport at `config.path`. The instance is not yet listening — callers
- * call `.listen()` or `.inject()` (tests). Sets no `trustProxy`, so
- * `request.ip` is the socket's address.
- *
- * @param config - HTTP transport configuration
- * @returns Configured Fastify instance (ready to listen or inject)
- */
-export async function buildHttpTransportApp(
-  config: HttpTransportConfig,
-): Promise<FastifyInstance> {
-  const app = Fastify({ logger: false });
-  await registerHttpTransport(app, config);
-  return app;
-}
-
-/**
- * Start the HTTP transport bound to the configured port.
- * Returns the listening Fastify instance.
- */
-export async function startHttpTransport(
-  config: HttpTransportConfig & { port: number },
-): Promise<FastifyInstance> {
-  const app = await buildHttpTransportApp(config);
-  await app.listen({ port: config.port, host: "0.0.0.0" });
-  return app;
-}