@langwatch/mcp-server 0.10.1 → 2.0.0

package/src/__tests__/documentation-fetch-security.integration.test.ts

@@ -0,0 +1,182 @@
+import { createServer, type Server } from "node:http";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { initConfig } from "../config.js";
+import { fetchDocumentation, resolveDocumentationUrl } from "../documentation-fetch.js";
+import { countingVerifier } from "./support/http-server-harness.js";
+
+const TEST_API_KEY = "security-regression-test";
+
+const MCP_HEADERS = {
+  Accept: "application/json, text/event-stream",
+  Authorization: `Bearer ${TEST_API_KEY}`,
+  "Content-Type": "application/json",
+};
+
+describe("MCP documentation fetch security", () => {
+  describe("URL validation", () => {
+    /** @scenario A documentation tool accepts its own trusted HTTPS pages */
+    it.each([
+      ["langwatch" as const, undefined, "https://langwatch.ai/docs/llms.txt"],
+      ["scenario" as const, undefined, "https://langwatch.ai/scenario/llms.txt"],
+      ["langwatch" as const, "observability/tracing", "https://langwatch.ai/docs/observability/tracing.md"],
+      ["scenario" as const, "/scenario/guides/quickstart", "https://langwatch.ai/scenario/guides/quickstart.md"],
+      [
+        "langwatch" as const,
+        "https://langwatch.ai/docs/llms.txt?format=raw",
+        "https://langwatch.ai/docs/llms.txt?format=raw",
+      ],
+    ])("resolves trusted %s documentation URL %s", (kind, input, expected) => {
+      expect(resolveDocumentationUrl(kind, input).toString()).toBe(expected);
+    });
+
+    /** @scenario A documentation tool rejects non-HTTPS and untrusted hosts */
+    /** @scenario A documentation tool rejects a trusted host outside its namespace */
+    it.each([
+      ["langwatch" as const, "http://169.254.169.254/latest/meta-data/"],
+      ["langwatch" as const, "https://langwatch.ai.attacker.example/docs/x"],
+      ["langwatch" as const, "https://langwatch.ai@127.0.0.1/docs/x"],
+      ["langwatch" as const, "https://langwatch.ai:444/docs/x"],
+      ["langwatch" as const, "file:///etc/passwd"],
+      ["langwatch" as const, "https://langwatch.ai/scenario/llms.txt"],
+      ["langwatch" as const, "https://langwatch.ai/docs-evil/page.md"],
+      ["scenario" as const, "https://langwatch.ai/docs/llms.txt"],
+      ["scenario" as const, "https://langwatch.ai/scenario-evil/page.md"],
+      ["langwatch" as const, "https://langwatch.ai/docs/../scenario/llms.txt"],
+    ])("rejects untrusted %s documentation URL %s", (kind, input) => {
+      expect(() => resolveDocumentationUrl(kind, input)).toThrow(/trusted LangWatch documentation URL/);
+    });
+  });
+
+  /** @scenario Documentation fetches do not follow redirects */
+  it("disables redirects and bounds trusted documentation fetches", async () => {
+    let receivedRedirectMode: RequestRedirect | undefined;
+    let receivedSignal: AbortSignal | null | undefined;
+    const fetchForTest: typeof fetch = async (_input, init) => {
+      receivedRedirectMode = init?.redirect;
+      receivedSignal = init?.signal;
+      return new Response("# documentation");
+    };
+
+    const text = await fetchDocumentation("langwatch", "https://langwatch.ai/docs/llms.txt", fetchForTest);
+
+    expect(text).toBe("# documentation");
+    expect(receivedRedirectMode).toBe("error");
+    expect(receivedSignal).toBeInstanceOf(AbortSignal);
+  });
+
+  it("rejects non-document responses from the trusted origin", async () => {
+    const fetchForTest: typeof fetch = async () =>
+      new Response("<html>unexpected</html>", {
+        headers: { "Content-Type": "text/html" },
+      });
+
+    await expect(fetchDocumentation("langwatch", "https://langwatch.ai/docs/llms.txt", fetchForTest)).rejects.toThrow(
+      /unexpected content type/
+    );
+  });
+
+  describe("HTTP tool transport", () => {
+    let mcpServer: Server;
+    let targetServer: Server;
+    let mcpPort: number;
+    let targetPort: number;
+    let sessionId: string;
+    let targetHits = 0;
+    let rpcId = 10;
+
+    beforeAll(async () => {
+      targetServer = createServer((_request, response) => {
+        targetHits += 1;
+        response.end("internal-only response");
+      });
+      await new Promise<void>((resolve) => {
+        targetServer.listen(0, "127.0.0.1", resolve);
+      });
+      const targetAddress = targetServer.address();
+      targetPort = typeof targetAddress === "object" && targetAddress ? targetAddress.port : 0;
+
+      initConfig({ endpoint: "https://app.langwatch.ai" });
+      const { startHttpServer } = await import("../http-server.js");
+      // These cases are about SSRF in the documentation tools, so the key check
+      // is stubbed to keep the test on its own subject.
+      const { verifier } = countingVerifier([TEST_API_KEY]);
+      const started = await startHttpServer({ port: 0, apiKeyVerifier: verifier });
+      mcpServer = started.server;
+      mcpPort = started.port;
+
+      const initializeResponse = await fetch(`http://127.0.0.1:${mcpPort}/mcp`, {
+        method: "POST",
+        headers: MCP_HEADERS,
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "initialize",
+          params: {
+            protocolVersion: "2025-03-26",
+            capabilities: {},
+            clientInfo: { name: "security-test", version: "1.0.0" },
+          },
+        }),
+      });
+      sessionId = initializeResponse.headers.get("mcp-session-id") ?? "";
+      expect(sessionId).not.toBe("");
+
+      await fetch(`http://127.0.0.1:${mcpPort}/mcp`, {
+        method: "POST",
+        headers: { ...MCP_HEADERS, "mcp-session-id": sessionId },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          method: "notifications/initialized",
+        }),
+      });
+    });
+
+    afterAll(async () => {
+      await Promise.all([
+        new Promise<void>((resolve, reject) => {
+          mcpServer.close((error) => (error ? reject(error) : resolve()));
+        }),
+        new Promise<void>((resolve, reject) => {
+          targetServer.close((error) => (error ? reject(error) : resolve()));
+        }),
+      ]);
+    });
+
+    async function callDocumentationTool(
+      name: "fetch_langwatch_docs" | "fetch_scenario_docs",
+      url: string
+    ): Promise<string> {
+      const response = await fetch(`http://127.0.0.1:${mcpPort}/mcp`, {
+        method: "POST",
+        headers: { ...MCP_HEADERS, "mcp-session-id": sessionId },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: rpcId++,
+          method: "tools/call",
+          params: { name, arguments: { url } },
+        }),
+      });
+
+      expect(response.status).toBe(200);
+      return response.text();
+    }
+
+    it.each(["fetch_langwatch_docs" as const, "fetch_scenario_docs" as const])(
+      "blocks %s from reaching a loopback HTTP server",
+      async (tool) => {
+        const hitsBefore = targetHits;
+        const body = await callDocumentationTool(tool, `http://127.0.0.1:${targetPort}/secrets`);
+
+        expect(body).toContain("trusted LangWatch documentation URL");
+        expect(targetHits).toBe(hitsBefore);
+      }
+    );
+
+    it("blocks cross-namespace fetches through the real MCP handler", async () => {
+      const body = await callDocumentationTool("fetch_langwatch_docs", "https://langwatch.ai/scenario/llms.txt");
+
+      expect(body).toContain("trusted LangWatch documentation URL");
+    });
+  });
+});

package/src/__tests__/feature-map-tool-drift.unit.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Drift guard between the MCP tools this server registers and the names
+ * `feature-map.json` tells agents to call.
+ *
+ * The feature map is the canonical information architecture: it is embedded
+ * into the CLI at codegen time and shipped inside the npx server package, so a
+ * name in it is a name an agent will try. Two entries pointed at
+ * `platform_run_evaluation` and `platform_evaluation_status`, which have never
+ * existed — the tools are `platform_run_experiment` and
+ * `platform_experiment_status`. An agent following the map for the experiments
+ * feature called two tools that were not there.
+ *
+ * Nothing compared the two lists, which is why it went unnoticed. This does.
+ *
+ * @see .claude/skills/feature-map/SKILL.md
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const REPO_ROOT = join(__dirname, "../../../..");
+
+/**
+ * Every tool name the feature map hands to an agent, from any depth: `mcp`
+ * arrays hang off surfaces nested several levels into the tree.
+ */
+function toolNamesInFeatureMap(): Set<string> {
+  const map: unknown = JSON.parse(
+    readFileSync(join(REPO_ROOT, "feature-map.json"), "utf-8")
+  );
+  const names = new Set<string>();
+
+  const walk = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item);
+      return;
+    }
+    if (node === null || typeof node !== "object") return;
+
+    const entry = node as Record<string, unknown>;
+    if (Array.isArray(entry.mcp)) {
+      for (const name of entry.mcp) {
+        if (typeof name === "string") names.add(name);
+      }
+    }
+    for (const value of Object.values(entry)) walk(value);
+  };
+
+  walk(map);
+  return names;
+}
+
+/**
+ * Every name passed as the first argument of a `server.tool(` registration.
+ *
+ * Read from the source rather than by constructing a server: building one
+ * needs config and credentials this test has no business holding, and the
+ * registration is a string literal in every case.
+ */
+function registeredToolNames(): Set<string> {
+  const source = readFileSync(
+    join(__dirname, "../create-mcp-server.ts"),
+    "utf-8"
+  );
+  const names = new Set<string>();
+  for (const match of source.matchAll(/server\.tool\(\s*"([^"]+)"/g)) {
+    names.add(match[1]!);
+  }
+  return names;
+}
+
+describe("feature map MCP tool names", () => {
+  describe("given the tools this server registers", () => {
+    it("names only tools that exist", () => {
+      const registered = registeredToolNames();
+      const missing = [...toolNamesInFeatureMap()]
+        .filter((name) => !registered.has(name))
+        .sort();
+
+      // Listed, not registered: an agent following the map calls a tool that
+      // is not there. Either rename the entry, or register the tool.
+      expect(missing).toEqual([]);
+    });
+
+    it("finds the registrations it is reading", () => {
+      // A regex that silently matched nothing would make the check above pass
+      // for the wrong reason.
+      const registered = registeredToolNames();
+      expect(registered.size).toBeGreaterThan(50);
+      expect(registered).toContain("platform_run_experiment");
+    });
+  });
+});

package/src/__tests__/http-security-origin.unit.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_BIND_HOST,
+  isLoopbackHost,
+  isOriginAllowed,
+  parseAllowedOrigins,
+} from "../http-security.js";
+
+describe("bind host", () => {
+  it("defaults to loopback", () => {
+    expect(DEFAULT_BIND_HOST).toBe("127.0.0.1");
+    expect(isLoopbackHost(DEFAULT_BIND_HOST)).toBe(true);
+  });
+
+  it.each(["127.0.0.1", "localhost", "::1", "[::1]", " LOCALHOST "])(
+    "recognises %s as loopback",
+    (host) => {
+      expect(isLoopbackHost(host)).toBe(true);
+    }
+  );
+
+  it.each(["0.0.0.0", "::", "192.168.1.10", "10.0.0.1", "example.com"])(
+    "does not treat %s as loopback",
+    (host) => {
+      expect(isLoopbackHost(host)).toBe(false);
+    }
+  );
+});
+
+describe("parseAllowedOrigins", () => {
+  it("returns an empty list when nothing is configured", () => {
+    expect(parseAllowedOrigins(undefined)).toEqual([]);
+    expect(parseAllowedOrigins("")).toEqual([]);
+  });
+
+  it("splits, trims, and normalizes entries", () => {
+    expect(
+      parseAllowedOrigins(" https://Example.com/ , https://app.test:8443 ")
+    ).toEqual(["https://example.com", "https://app.test:8443"]);
+  });
+
+  it("drops entries that are not usable origins", () => {
+    expect(parseAllowedOrigins("not-an-origin, https://ok.test")).toEqual([
+      "https://ok.test",
+    ]);
+  });
+
+  it("deduplicates equivalent origins", () => {
+    expect(parseAllowedOrigins("https://a.test,https://a.test/")).toEqual([
+      "https://a.test",
+    ]);
+  });
+});
+
+describe("isOriginAllowed", () => {
+  it.each([
+    "http://localhost:5173",
+    "http://127.0.0.1:3000",
+    "http://[::1]:3000",
+    "https://localhost",
+  ])("always allows the loopback origin %s", (origin) => {
+    expect(isOriginAllowed({ origin, allowedOrigins: [] })).toBe(true);
+  });
+
+  it("rejects an unlisted remote origin", () => {
+    expect(isOriginAllowed({ origin: "https://evil.test", allowedOrigins: [] })).toBe(false);
+  });
+
+  it("allows a configured remote origin", () => {
+    expect(isOriginAllowed({ origin: "https://app.test", allowedOrigins: ["https://app.test"] })).toBe(
+      true
+    );
+  });
+
+  it("matches on scheme, host and port together", () => {
+    const allowlist = ["https://app.test"];
+    expect(isOriginAllowed({ origin: "http://app.test", allowedOrigins: allowlist })).toBe(false);
+    expect(isOriginAllowed({ origin: "https://app.test:8443", allowedOrigins: allowlist })).toBe(false);
+    expect(isOriginAllowed({ origin: "https://other.test", allowedOrigins: allowlist })).toBe(false);
+  });
+
+  it("does not let a hostname that merely ends in localhost through", () => {
+    expect(isOriginAllowed({ origin: "https://notlocalhost", allowedOrigins: [] })).toBe(false);
+    expect(isOriginAllowed({ origin: "https://evil-localhost.test", allowedOrigins: [] })).toBe(false);
+  });
+
+  it("rejects the opaque null origin", () => {
+    expect(isOriginAllowed({ origin: "null", allowedOrigins: [] })).toBe(false);
+  });
+
+  it("treats a rebound attacker hostname as unlisted", () => {
+    // DNS rebinding points an attacker hostname at loopback, but the browser
+    // still sends the attacker hostname as the origin.
+    expect(isOriginAllowed({ origin: "http://rebind.attacker.test", allowedOrigins: [] })).toBe(false);
+  });
+});

package/src/__tests__/http-security-sessions.unit.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { admitOAuthToken, createSessionStore } from "../http-security.js";
+
+describe("createSessionStore", () => {
+  function makeStore(maxAgeMs = 60_000) {
+    const closed: string[] = [];
+    const store = createSessionStore<{ id: string }>({
+      maxAgeMs,
+      closeTransport: (transport) => closed.push(transport.id),
+    });
+    return { store, closed };
+  }
+
+  it("stores and returns sessions bound to their key", () => {
+    const { store } = makeStore();
+    store.add({ sessionId: "s1", transport: { id: "s1" }, apiKey: "sk-a" });
+
+    expect(store.get("s1")?.apiKey).toBe("sk-a");
+    expect(store.size).toBe(1);
+  });
+
+  it("counts live sessions per key without holding the raw key", () => {
+    const { store } = makeStore();
+    store.add({ sessionId: "s1", transport: { id: "s1" }, apiKey: "sk-a" });
+    store.add({ sessionId: "s2", transport: { id: "s2" }, apiKey: "sk-a" });
+    store.add({ sessionId: "s3", transport: { id: "s3" }, apiKey: "sk-b" });
+
+    expect(store.countForKey("sk-a")).toBe(2);
+    expect(store.countForKey("sk-b")).toBe(1);
+    expect(store.countForKey("sk-unknown")).toBe(0);
+  });
+
+  it("decrements the per-key count when a session is removed", () => {
+    const { store } = makeStore();
+    store.add({ sessionId: "s1", transport: { id: "s1" }, apiKey: "sk-a" });
+    store.add({ sessionId: "s2", transport: { id: "s2" }, apiKey: "sk-a" });
+
+    store.remove("s1");
+    expect(store.countForKey("sk-a")).toBe(1);
+
+    store.remove("s2");
+    expect(store.countForKey("sk-a")).toBe(0);
+  });
+
+  it("ignores removal of a session it does not hold", () => {
+    const { store } = makeStore();
+    store.add({ sessionId: "s1", transport: { id: "s1" }, apiKey: "sk-a" });
+
+    store.remove("never-existed");
+    store.remove("never-existed");
+
+    expect(store.countForKey("sk-a")).toBe(1);
+  });
+
+  it("closes and forgets sessions that have gone idle", () => {
+    vi.useFakeTimers();
+    try {
+      const { store, closed } = makeStore(1_000);
+      store.add({ sessionId: "idle", transport: { id: "idle" }, apiKey: "sk-a" });
+      store.add({ sessionId: "busy", transport: { id: "busy" }, apiKey: "sk-a" });
+
+      vi.advanceTimersByTime(900);
+      store.touch("busy");
+      vi.advanceTimersByTime(900);
+      store.sweep();
+
+      expect(closed).toEqual(["idle"]);
+      expect(store.get("idle")).toBeUndefined();
+      expect(store.get("busy")).toBeDefined();
+      expect(store.countForKey("sk-a")).toBe(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("closes everything on shutdown", () => {
+    const { store, closed } = makeStore();
+    store.add({ sessionId: "s1", transport: { id: "s1" }, apiKey: "sk-a" });
+    store.add({ sessionId: "s2", transport: { id: "s2" }, apiKey: "sk-b" });
+
+    store.closeAll();
+
+    expect(closed.sort()).toEqual(["s1", "s2"]);
+    expect(store.size).toBe(0);
+    expect(store.countForKey("sk-a")).toBe(0);
+  });
+
+  it("does not let a prototype-shaped session id reach the prototype chain", () => {
+    const { store } = makeStore();
+
+    expect(store.get("__proto__")).toBeUndefined();
+    expect(store.get("constructor")).toBeUndefined();
+
+    store.add({ sessionId: "__proto__", transport: { id: "weird" }, apiKey: "sk-a" });
+    expect(store.get("__proto__")?.transport.id).toBe("weird");
+    expect(store.size).toBe(1);
+  });
+});
+
+describe("session reservations", () => {
+  function makeStore() {
+    return createSessionStore<{ id: string }>({
+      maxAgeMs: 60_000,
+      closeTransport: () => undefined,
+    });
+  }
+
+  it("counts a reserved slot before any session exists", () => {
+    const store = makeStore();
+    store.reserve("sk-a");
+
+    // The point of the reservation: the cap sees the slot while the session is
+    // still being set up.
+    expect(store.countForKey("sk-a")).toBe(1);
+    expect(store.size).toBe(0);
+  });
+
+  it("hands the reserved slot to the session rather than counting twice", () => {
+    const store = makeStore();
+    store.reserve("sk-a").commit({ sessionId: "s1", transport: { id: "s1" } });
+
+    expect(store.countForKey("sk-a")).toBe(1);
+    expect(store.get("s1")?.apiKey).toBe("sk-a");
+  });
+
+  it("returns the slot when the session never came up", () => {
+    const store = makeStore();
+    const reservation = store.reserve("sk-a");
+    reservation.release();
+
+    expect(store.countForKey("sk-a")).toBe(0);
+  });
+
+  it("ignores a release once the slot was committed", () => {
+    const store = makeStore();
+    const reservation = store.reserve("sk-a");
+    reservation.commit({ sessionId: "s1", transport: { id: "s1" } });
+    reservation.release();
+
+    expect(store.countForKey("sk-a")).toBe(1);
+    expect(store.get("s1")).toBeDefined();
+  });
+
+  it("frees the slot when the committed session is removed", () => {
+    const store = makeStore();
+    store.reserve("sk-a").commit({ sessionId: "s1", transport: { id: "s1" } });
+    store.remove("s1");
+
+    expect(store.countForKey("sk-a")).toBe(0);
+  });
+});
+
+describe("admitOAuthToken", () => {
+  function entry(apiKey: string, expiresAt: number) {
+    return { apiKey, expiresAt };
+  }
+
+  it("evicts the oldest token for a key that is at the cap", () => {
+    const tokens = new Map([
+      ["t1", entry("sk-a", Date.now() + 1_000)],
+      ["t2", entry("sk-a", Date.now() + 2_000)],
+      ["t3", entry("sk-a", Date.now() + 3_000)],
+    ]);
+
+    admitOAuthToken({ apiKey: "sk-a", tokens, maxPerKey: 3 });
+
+    // Room for the caller's new token, and the longest-standing one went.
+    expect(tokens.has("t1")).toBe(false);
+    expect([...tokens.keys()]).toEqual(["t2", "t3"]);
+  });
+
+  it("leaves other keys alone", () => {
+    const tokens = new Map([
+      ["t1", entry("sk-a", Date.now() + 1_000)],
+      ["t2", entry("sk-b", Date.now() + 1_000)],
+      ["t3", entry("sk-b", Date.now() + 2_000)],
+    ]);
+
+    admitOAuthToken({ apiKey: "sk-a", tokens, maxPerKey: 1 });
+
+    expect(tokens.has("t1")).toBe(false);
+    expect(tokens.has("t2")).toBe(true);
+    expect(tokens.has("t3")).toBe(true);
+  });
+
+  it("keeps a key from growing the map without bound", () => {
+    const tokens = new Map<string, { apiKey: string; expiresAt: number }>();
+
+    for (let i = 0; i < 50; i += 1) {
+      admitOAuthToken({ apiKey: "sk-a", tokens, maxPerKey: 10 });
+      tokens.set(`t${i}`, entry("sk-a", Date.now() + 60_000 + i));
+    }
+
+    expect(tokens.size).toBe(10);
+  });
+
+  it("drops expired tokens for any key on the way past", () => {
+    const tokens = new Map([
+      ["stale", entry("sk-b", Date.now() - 1)],
+      ["live", entry("sk-b", Date.now() + 60_000)],
+    ]);
+
+    admitOAuthToken({ apiKey: "sk-a", tokens, maxPerKey: 10 });
+
+    expect(tokens.has("stale")).toBe(false);
+    expect(tokens.has("live")).toBe(true);
+  });
+});