create-ailk 0.4.0 → 0.6.0

package/templates/apps/mcp/src/abuse/index.ts

@@ -1,14 +1,17 @@
 /**
  * Abuse rule orchestrator for MCP write tools.
  *
- * Runs all in-process heuristics for the three anonymous write tools:
- * capture_lead, subscribe_newsletter, request_callback.
+ * Runs all in-process heuristics for the anonymous write tools:
+ * capture_lead, subscribe_newsletter, request_callback, and — since #5971 —
+ * start_purchase.
  *
  * Rules applied (in order):
  *   1. User-Agent deny list (applies to all write tools)
  *   2. Honeypot field check (applies to all write tools)
  *   3. Email format validation (capture_lead, subscribe_newsletter)
- *   4. Per-IP daily cap (capture_lead only)
+ *   4. Per-IP daily cap (capture_lead and start_purchase, each on its OWN
+ *      tracker — sharing one would let purchase attempts consume the lead
+ *      budget and vice versa, a silent cross-tool denial of service)
  *
  * The paid layer (lead-routing.ts) extends with real abuse-protection
  * services. OSS gets basic heuristics that stop obvious bots.
@@ -24,28 +27,142 @@ import { buildDenyList, isUserAgentBlocked } from "./user-agent-deny.js";
 /** Tools that require email format validation on their input. */
 const EMAIL_VALIDATED_TOOLS = new Set(["capture_lead", "subscribe_newsletter"]);
 
-/** Tools that apply the per-IP daily cap. */
-const DAILY_CAPPED_TOOLS = new Set(["capture_lead"]);
+/** The per-tool daily-cap budgets, keyed by MCP tool name. */
+type DailyCapKey = "captureLead" | "startPurchase";
+
+/**
+ * The typed reason codes an {@link AbuseResult} refusal can carry.
+ *
+ * The code — not the prose in `reason` — is the contract between this module
+ * and its callers. `http-transport.ts` maps each code to an HTTP status
+ * (`ABUSE_REFUSAL_STATUS`), so a reworded refusal reason can never move a
+ * refusal between statuses, and a NEW code fails to compile until the
+ * transport declares a status for it (#5994).
+ */
+export const AbuseReasonCode = {
+  /** The caller's User-Agent is on the deny list. */
+  BLOCKED_USER_AGENT: "blocked_user_agent",
+  /** The submitted input filled a honeypot field. */
+  HONEYPOT_FILLED: "honeypot_filled",
+  /** The submitted input carried a malformed email address. */
+  INVALID_EMAIL: "invalid_email",
+  /** The caller's IP has spent this tool's per-IP daily budget. */
+  DAILY_CAP_REACHED: "daily_cap_reached",
+} as const;
+
+export type AbuseReasonCode =
+  (typeof AbuseReasonCode)[keyof typeof AbuseReasonCode];
+
+/**
+ * Tools that apply a per-IP daily cap, each mapped to the tracker that budgets
+ * it and the refusal reason it answers with. One tracker per entry — never
+ * shared across tools, since a shared budget would let purchase attempts
+ * consume the lead allowance and vice versa.
+ *
+ * The reason strings here are prose for the caller and nothing more: every
+ * entry refuses with {@link AbuseReasonCode.DAILY_CAP_REACHED}, and that code
+ * is what decides the HTTP status. Reword either one freely.
+ */
+const DAILY_CAPPED_TOOLS = new Map<
+  string,
+  { tracker: DailyCapKey; reason: string }
+>([
+  [
+    "capture_lead",
+    {
+      tracker: "captureLead",
+      reason: "daily capture_lead cap reached for this IP",
+    },
+  ],
+  [
+    "start_purchase",
+    {
+      tracker: "startPurchase",
+      reason: "daily cap reached for start_purchase from this IP",
+    },
+  ],
+]);
 
 export interface AbuseConfig {
   /** Per-IP daily cap for capture_lead. Default 50. */
   captureLeadDailyCapPerIp: number;
+  /**
+   * Per-IP daily cap for start_purchase (#5971). Default 20 — lower than
+   * capture_lead's, because each call creates a real Stripe Checkout Session.
+   * Optional so existing callers that construct an AbuseConfig without it
+   * keep compiling; omitted falls back to the default.
+   */
+  startPurchaseDailyCapPerIp?: number;
   /** Comma-separated extra UA substrings to block. */
   blockedUserAgents: string;
 }
 
-export interface AbuseResult {
-  allowed: boolean;
-  reason?: string;
+/** Default per-IP daily cap for start_purchase when none is configured. */
+export const DEFAULT_START_PURCHASE_DAILY_CAP = 20;
+
+/** Default per-IP daily cap for capture_lead when none is configured. */
+export const DEFAULT_CAPTURE_LEAD_DAILY_CAP = 50;
+
+/**
+ * Reads a positive-integer env var, falling back to `fallback` for anything
+ * that is not one.
+ *
+ * `parseInt(process.env[X] ?? "20", 10)` is NOT enough, and the gap is a
+ * silent fail-OPEN on a security threshold (#5971 security review round 2):
+ * `?? "20"` fires only when the var is UNSET, so a var that is present but
+ * BLANK — the shape `.env.example` itself teaches for three neighbouring
+ * vars — reaches `parseInt("")` and yields `NaN`. `NaN` then survives every
+ * downstream `??` guard (nullish coalescing catches null/undefined, not NaN),
+ * and `count >= NaN` is always false, so the cap silently stops refusing
+ * anything. A misconfigured deployment looks identical to a correct one at
+ * rest, which is exactly why this needs a guard rather than a convention.
+ */
+export function readPositiveIntEnv(name: string, fallback: number): number {
+  const parsed = Number.parseInt(process.env[name] ?? "", 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+/** Coerces a configured cap to a usable one, defaulting anything non-finite
+ * or non-positive. The in-process twin of {@link readPositiveIntEnv}, for a
+ * cap that arrives through {@link AbuseConfig} rather than the environment. */
+function usableCap(value: number | undefined, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? value
+    : fallback;
 }
 
+/** A refusal: always carries both the typed code and its caller-facing prose. */
+export interface AbuseRefusal {
+  allowed: false;
+  /** What kind of refusal this is — the machine-readable half. */
+  code: AbuseReasonCode;
+  /** Caller-facing prose. Free to reword; nothing keys control flow on it. */
+  reason: string;
+}
+
+/** The verdict of {@link AbuseGuard.validate}. */
+export type AbuseResult = { allowed: true } | AbuseRefusal;
+
 export class AbuseGuard {
   private readonly denyList: RegExp[];
-  private readonly captureLeadCap: DailyCapTracker;
+  private readonly caps: Record<DailyCapKey, DailyCapTracker>;
 
   constructor(config: AbuseConfig) {
     this.denyList = buildDenyList(config.blockedUserAgents);
-    this.captureLeadCap = new DailyCapTracker(config.captureLeadDailyCapPerIp);
+    this.caps = {
+      captureLead: new DailyCapTracker(
+        usableCap(
+          config.captureLeadDailyCapPerIp,
+          DEFAULT_CAPTURE_LEAD_DAILY_CAP,
+        ),
+      ),
+      startPurchase: new DailyCapTracker(
+        usableCap(
+          config.startPurchaseDailyCapPerIp,
+          DEFAULT_START_PURCHASE_DAILY_CAP,
+        ),
+      ),
+    };
   }
 
   /**
@@ -65,12 +182,20 @@ export class AbuseGuard {
 
     // Rule 1: User-Agent deny list
     if (isUserAgentBlocked(ua, this.denyList)) {
-      return { allowed: false, reason: "blocked user agent" };
+      return {
+        allowed: false,
+        code: AbuseReasonCode.BLOCKED_USER_AGENT,
+        reason: "blocked user agent",
+      };
     }
 
     // Rule 2: Honeypot
     if (isHoneypotTripped(input)) {
-      return { allowed: false, reason: "honeypot field filled" };
+      return {
+        allowed: false,
+        code: AbuseReasonCode.HONEYPOT_FILLED,
+        reason: "honeypot field filled",
+      };
     }
 
     // Rule 3: Email format validation
@@ -78,33 +203,43 @@ export class AbuseGuard {
       const rec = input as Record<string, unknown>;
       const email = rec["email"];
       if (typeof email === "string" && !isValidEmail(email)) {
-        return { allowed: false, reason: "invalid email format" };
-      }
-    }
-
-    // Rule 4: Per-IP daily cap
-    if (DAILY_CAPPED_TOOLS.has(toolName)) {
-      if (!this.captureLeadCap.isAllowed(ip)) {
         return {
           allowed: false,
-          reason: "daily capture_lead cap reached for this IP",
+          code: AbuseReasonCode.INVALID_EMAIL,
+          reason: "invalid email format",
         };
       }
     }
 
+    // Rule 4: Per-IP daily cap, on the tool's OWN tracker and with the
+    // tool's OWN refusal prose — one shared code, see DAILY_CAPPED_TOOLS.
+    const cap = DAILY_CAPPED_TOOLS.get(toolName);
+    if (cap !== undefined && !this.caps[cap.tracker].isAllowed(ip)) {
+      return {
+        allowed: false,
+        code: AbuseReasonCode.DAILY_CAP_REACHED,
+        reason: cap.reason,
+      };
+    }
+
     return { allowed: true };
   }
 }
 
 /**
  * Convenience function for constructing an AbuseGuard from env vars.
- * Reads MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP and MCP_ABUSE_BLOCKED_USER_AGENTS.
+ * Reads MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP,
+ * MCP_ABUSE_START_PURCHASE_DAILY_CAP and MCP_ABUSE_BLOCKED_USER_AGENTS.
  */
 export function createAbuseGuardFromEnv(): AbuseGuard {
   return new AbuseGuard({
-    captureLeadDailyCapPerIp: parseInt(
-      process.env["MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP"] ?? "50",
-      10,
+    captureLeadDailyCapPerIp: readPositiveIntEnv(
+      "MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP",
+      DEFAULT_CAPTURE_LEAD_DAILY_CAP,
+    ),
+    startPurchaseDailyCapPerIp: readPositiveIntEnv(
+      "MCP_ABUSE_START_PURCHASE_DAILY_CAP",
+      DEFAULT_START_PURCHASE_DAILY_CAP,
     ),
     blockedUserAgents: process.env["MCP_ABUSE_BLOCKED_USER_AGENTS"] ?? "",
   });

package/templates/apps/mcp/src/config/modules.ts

@@ -14,11 +14,16 @@
  * Recognized module keys: `docs`, `multi-tenant`, `scheduling`,
  * `signal-collectors` (the `ModuleName` vocabulary
  * `packages/create-ailk/src/module-architecture.ts` already models via
- * `MODULE_SLICES`) plus `content-write` — the Pro
- * content-write surface (`create_page`/`update_page`/`delete_page`).
- * `content-write` is intentionally NOT a `MODULE_SLICES` entry: it is not
- * (yet) a create-ailk `--modules` selector, so it stays a local flag here
- * rather than widening the create-ailk module vocabulary.
+ * `MODULE_SLICES`) plus `content-write` — the Pro content-write surface,
+ * which owns NO MCP tool since #5853: `create_page`/`update_page`/`delete_page`
+ * were retired by deletion along with their untenanted HTTP twins, and their
+ * replacement is identity-bound, which the identity-blind MCP surface cannot
+ * carry (D7, D15; the authed MCP surface is #3591). The flag is read here only
+ * because this reader is shared with `apps/api`, where it still gates the
+ * tenant-guarded editor routes. `content-write` is intentionally NOT a
+ * `MODULE_SLICES` entry: it is not (yet) a create-ailk `--modules` selector,
+ * so it stays a local flag here rather than widening the create-ailk module
+ * vocabulary.
  */
 
 function enabledModules(): Set<string> {

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

@@ -27,14 +27,55 @@ import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import Fastify, { type FastifyInstance, type FastifyRequest } from "fastify";
 
-import { AbuseGuard, type AbuseConfig } from "./abuse/index.js";
+import {
+  AbuseGuard,
+  AbuseReasonCode,
+  type AbuseConfig,
+} from "./abuse/index.js";
 import { createMcpServer } from "./server.js";
 
-/** MCP tool names that are write operations (subject to stricter CORS + rate limits). */
-const WRITE_TOOLS = new Set([
+/**
+ * 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.
+ */
+// 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",
 ]);
 
 export interface HttpTransportCorsConfig {
@@ -71,17 +112,49 @@ export interface HttpTransportConfig {
   stateless?: boolean;
 }
 
+/** One write-tool invocation found in a request body. */
+interface WriteToolCall {
+  toolName: string;
+  args: unknown;
+}
+
 /**
- * Determine whether a tools/call payload targets a write tool.
- * Returns false for any other method (tools/list, initialize, etc.).
+ * 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 isWriteToolCall(body: unknown): boolean {
-  if (!body || typeof body !== "object") return false;
-  const req = body as Record<string, unknown>;
-  if (req["method"] !== "tools/call") return false;
-  const params = req["params"] as Record<string, unknown> | undefined;
-  if (!params) return false;
-  return WRITE_TOOLS.has(params["name"] as string);
+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;
 }
 
 /**
@@ -154,8 +227,12 @@ export async function buildHttpTransportApp(
       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 (isWriteToolCall(body)) {
+      if (writeCalls.length > 0) {
         if (!isOriginAllowedForWrite(origin, config.cors.writeAllowedOrigins)) {
           reply
             .code(403)
@@ -171,22 +248,18 @@ export async function buildHttpTransportApp(
         // TODO: per-tool write rate limit when @fastify/rate-limit v11 lands
         // a per-route override API compatible with our stateless route design.
 
-        // Abuse heuristics
-        const params = (body as Record<string, unknown>)["params"] as
-          | Record<string, unknown>
-          | undefined;
-        const toolName = (params?.["name"] as string) ?? "";
-        const args = params?.["arguments"] ?? {};
-
-        const abuseResult = abuseGuard.validate(toolName, args, request);
-        if (!abuseResult.allowed) {
-          const statusCode =
-            abuseResult.reason === "blocked user agent" ||
-            abuseResult.reason?.includes("daily cap")
-              ? 403
-              : 422;
-          reply.code(statusCode).send({ error: abuseResult.reason });
-          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

package/templates/apps/mcp/src/index.ts

@@ -13,11 +13,59 @@
  *   MCP_RATE_LIMIT_WRITE_PER_MIN=10
  *   MCP_CORS_WRITE_ALLOWED_ORIGINS=   (empty = no cross-origin writes)
  *   MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP=50
+ *   MCP_ABUSE_START_PURCHASE_DAILY_CAP=20
  *   MCP_ABUSE_BLOCKED_USER_AGENTS=    (comma-separated substrings)
+ *
+ * Content adapter (all optional; `CONTENT_ADAPTER` default: mdx):
+ *   CONTENT_ADAPTER=mdx|projection|database
+ *   DATABASE_URL=  (required only when CONTENT_ADAPTER=database)
  */
 
-// Required to mark this file as an ES module (needed for top-level await).
-export {};
+import { initMcpCommerceClaim } from "./lib/commerce-claim.js";
+import { initMcpPublicWorkspace } from "./lib/public-workspace.js";
+
+// Resolves the MCP server's own workspace ONCE, before either transport
+// branch below — a no-op unless CONTENT_ADAPTER=database (#5876 spec D4/D6).
+// This is the one `await` that covers both arms: `getMcpContentAdapter()`
+// (content-adapter.ts) stays synchronous and reads the memoised result.
+//
+// A REJECTION here (a transient DB error — unreachable at boot, a migration
+// in progress, a bad DATABASE_URL) is caught rather than left to crash the
+// process: every OTHER tool (lead capture, scheduling, …) has nothing to do
+// with the content adapter and must keep serving. The module's un-resolved
+// `{ kind: "not-required" }` state is left in place on a caught failure —
+// the SAME fail-closed shape an ambiguous workspace count already produces
+// (D5) — so content tools serve their empty/not-found shape rather than the
+// whole server going dark over one adapter's connectivity.
+try {
+  await initMcpPublicWorkspace();
+} catch (err) {
+  console.error(
+    "[mcp] initMcpPublicWorkspace() failed — content tools will serve their " +
+      "fail-closed empty shape under CONTENT_ADAPTER=database until this " +
+      "resolves; every other tool is unaffected:",
+    err,
+  );
+}
+
+// Resolves the deployment's `commerce` add-on claim ONCE, before either
+// transport branch — the sibling of the workspace resolution above and the
+// same #5876 idiom (#5971 spec D2). Without this await the memoised claim is
+// never resolved and `start_purchase` is invisible on a KEYED site too.
+//
+// A REJECTION is caught for the same reason: a licence read that fails must
+// not take the other 19 tools down. `initMcpCommerceClaim()` already resolves
+// to the fail-closed "unclaimed" internally, so this catch is belt-and-braces
+// for anything thrown outside its own try.
+try {
+  await initMcpCommerceClaim();
+} catch (err) {
+  console.error(
+    "[mcp] initMcpCommerceClaim() failed — start_purchase stays unregistered " +
+      "(fail-closed) until this resolves; every other tool is unaffected:",
+    err,
+  );
+}
 
 const transport = process.env["MCP_TRANSPORT"] ?? "stdio";
 
@@ -38,27 +86,41 @@ if (transport === "http") {
   const writeAllowedOrigins = writeOriginsRaw
     ? writeOriginsRaw.split(",").map((o) => o.trim())
     : [];
-  const captureLeadDailyCapPerIp = parseInt(
-    process.env["MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP"] ?? "50",
-    10,
+  // Both caps go through readPositiveIntEnv rather than a bare parseInt: a
+  // BLANK env var would otherwise yield NaN and silently disable the cap
+  // (#5971 security review round 2).
+  const {
+    readPositiveIntEnv,
+    DEFAULT_CAPTURE_LEAD_DAILY_CAP,
+    DEFAULT_START_PURCHASE_DAILY_CAP,
+  } = await import("./abuse/index.js");
+  const captureLeadDailyCapPerIp = readPositiveIntEnv(
+    "MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP",
+    DEFAULT_CAPTURE_LEAD_DAILY_CAP,
   );
-  const blockedUserAgents =
-    process.env["MCP_ABUSE_BLOCKED_USER_AGENTS"] ?? "";
+  const startPurchaseDailyCapPerIp = readPositiveIntEnv(
+    "MCP_ABUSE_START_PURCHASE_DAILY_CAP",
+    DEFAULT_START_PURCHASE_DAILY_CAP,
+  );
+  const blockedUserAgents = process.env["MCP_ABUSE_BLOCKED_USER_AGENTS"] ?? "";
 
   await startHttpTransport({
     port,
     path,
     rateLimits: { readPerMin, writePerMin },
     cors: { writeAllowedOrigins },
-    abuse: { captureLeadDailyCapPerIp, blockedUserAgents },
+    abuse: {
+      captureLeadDailyCapPerIp,
+      startPurchaseDailyCapPerIp,
+      blockedUserAgents,
+    },
   });
 
   console.log(`MCP HTTP transport listening on port ${port} at ${path}`);
 } else {
   // Default: stdio transport
-  const { StdioServerTransport } = await import(
-    "@modelcontextprotocol/sdk/server/stdio.js"
-  );
+  const { StdioServerTransport } =
+    await import("@modelcontextprotocol/sdk/server/stdio.js");
   const { createMcpServer } = await import("./server.js");
 
   const server = createMcpServer();