@langwatch/mcp-server 1.0.0 → 2.1.0

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

@@ -0,0 +1,248 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  apiKeysMatch,
+  createApiKeyVerifier,
+  createRateLimiter,
+  hashApiKey,
+} from "../http-security.js";
+
+describe("apiKeysMatch", () => {
+  it("matches identical keys", () => {
+    expect(apiKeysMatch({ presentedKey: "sk-abc", expectedKey: "sk-abc" })).toBe(true);
+  });
+
+  it("rejects different keys, including different lengths", () => {
+    expect(apiKeysMatch({ presentedKey: "sk-abc", expectedKey: "sk-abd" })).toBe(false);
+    expect(apiKeysMatch({ presentedKey: "sk-abc", expectedKey: "sk-abc-longer" })).toBe(false);
+    expect(apiKeysMatch({ presentedKey: "", expectedKey: "sk-abc" })).toBe(false);
+  });
+});
+
+describe("hashApiKey", () => {
+  it("never returns the raw key", () => {
+    expect(hashApiKey("sk-secret")).not.toContain("sk-secret");
+  });
+
+  it("is stable and distinct per key", () => {
+    expect(hashApiKey("a")).toBe(hashApiKey("a"));
+    expect(hashApiKey("a")).not.toBe(hashApiKey("b"));
+  });
+});
+
+describe("createRateLimiter", () => {
+  it("blocks only after the limit is exceeded", () => {
+    const limiter = createRateLimiter({ windowMs: 60_000, maxRequests: 3 });
+
+    expect(limiter.isBlocked("1.2.3.4")).toBe(false);
+    limiter.track("1.2.3.4");
+    limiter.track("1.2.3.4");
+    expect(limiter.isBlocked("1.2.3.4")).toBe(false);
+    limiter.track("1.2.3.4");
+    expect(limiter.isBlocked("1.2.3.4")).toBe(true);
+  });
+
+  it("tracks each IP separately", () => {
+    const limiter = createRateLimiter({ windowMs: 60_000, maxRequests: 1 });
+
+    limiter.track("1.1.1.1");
+    expect(limiter.isBlocked("1.1.1.1")).toBe(true);
+    expect(limiter.isBlocked("2.2.2.2")).toBe(false);
+  });
+
+  it("forgets an IP once its window has passed", () => {
+    vi.useFakeTimers();
+    try {
+      const limiter = createRateLimiter({ windowMs: 1_000, maxRequests: 1 });
+      limiter.track("1.1.1.1");
+      expect(limiter.isBlocked("1.1.1.1")).toBe(true);
+
+      vi.advanceTimersByTime(1_500);
+      expect(limiter.isBlocked("1.1.1.1")).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+function jsonResponse(status: number): Response {
+  return new Response(status === 200 ? "{}" : "", { status });
+}
+
+/** A fetch double that records the URL and init it was called with. */
+function fetchStub(respond: () => Promise<Response>) {
+  return vi.fn(async (_url: string, _init?: RequestInit) => respond());
+}
+
+describe("createApiKeyVerifier", () => {
+  it("asks the LangWatch identity endpoint with the key in a header", async () => {
+    const fetchImpl = fetchStub(async () => jsonResponse(200));
+    const verifier = createApiKeyVerifier({
+      endpoint: "https://app.langwatch.ai",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    await expect(verifier.verify("sk-real")).resolves.toBe(true);
+
+    expect(fetchImpl).toHaveBeenCalledWith(
+      "https://app.langwatch.ai/api/me/project",
+      expect.objectContaining({
+        method: "GET",
+        headers: { "X-Auth-Token": "sk-real" },
+      })
+    );
+  });
+
+  it("never puts the key in the URL", async () => {
+    const fetchImpl = fetchStub(async () => jsonResponse(200));
+    const verifier = createApiKeyVerifier({
+      endpoint: "https://app.langwatch.ai",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    await verifier.verify("sk-real");
+
+    expect(fetchImpl.mock.calls[0]?.[0]).not.toContain("sk-real");
+  });
+
+  it.each([401, 403])("rejects a key the API answers %i for", async (status) => {
+    const verifier = createApiKeyVerifier({
+      endpoint: "https://app.langwatch.ai",
+      fetchImpl: (async () => jsonResponse(status)) as unknown as typeof fetch,
+    });
+
+    await expect(verifier.verify("sk-fake")).resolves.toBe(false);
+  });
+
+  it("caches a positive answer instead of asking again", async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse(200));
+    const verifier = createApiKeyVerifier({
+      endpoint: "https://app.langwatch.ai",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    await verifier.verify("sk-real");
+    await verifier.verify("sk-real");
+    await verifier.verify("sk-real");
+
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it("caches a negative answer so key spraying does not reach the API", async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse(401));
+    const verifier = createApiKeyVerifier({
+      endpoint: "https://app.langwatch.ai",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    await verifier.verify("sk-fake");
+    await verifier.verify("sk-fake");
+
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-asks once the cache entry has expired", async () => {
+    vi.useFakeTimers();
+    try {
+      const fetchImpl = fetchStub(async () => jsonResponse(200));
+      const verifier = createApiKeyVerifier({
+        endpoint: "https://app.langwatch.ai",
+        positiveTtlMs: 1_000,
+        fetchImpl: fetchImpl as unknown as typeof fetch,
+      });
+
+      await verifier.verify("sk-real");
+      vi.advanceTimersByTime(1_500);
+      await verifier.verify("sk-real");
+
+      expect(fetchImpl).toHaveBeenCalledTimes(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("collapses concurrent checks of the same key into one request", async () => {
+    const fetchImpl = vi.fn(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      return jsonResponse(200);
+    });
+    const verifier = createApiKeyVerifier({
+      endpoint: "https://app.langwatch.ai",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    const results = await Promise.all(
+      Array.from({ length: 25 }, () => verifier.verify("sk-real"))
+    );
+
+    expect(results.every((result) => result === true)).toBe(true);
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it("fails closed when the API cannot answer, without caching the failure", async () => {
+    let status = 503;
+    const fetchImpl = vi.fn(async () => jsonResponse(status));
+    const verifier = createApiKeyVerifier({
+      endpoint: "https://app.langwatch.ai",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    await expect(verifier.verify("sk-real")).resolves.toBe(false);
+
+    status = 200;
+    await expect(verifier.verify("sk-real")).resolves.toBe(true);
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+  });
+
+  it("gives up on an upstream that never answers", async () => {
+    // Without a timeout the in-flight promise never settles and every request
+    // for this key parks behind it until the socket dies.
+    const verifier = createApiKeyVerifier({
+      endpoint: "https://app.langwatch.ai",
+      requestTimeoutMs: 20,
+      fetchImpl: ((_url: string, init?: RequestInit) =>
+        new Promise((_resolve, reject) => {
+          init?.signal?.addEventListener("abort", () =>
+            reject(new Error("aborted"))
+          );
+        })) as unknown as typeof fetch,
+    });
+
+    await expect(verifier.verify("sk-real")).resolves.toBe(false);
+  });
+
+  it("fails closed when the request throws", async () => {
+    const verifier = createApiKeyVerifier({
+      endpoint: "https://app.langwatch.ai",
+      fetchImpl: (async () => {
+        throw new Error("connection refused");
+      }) as unknown as typeof fetch,
+    });
+
+    await expect(verifier.verify("sk-real")).resolves.toBe(false);
+  });
+
+  it("evicts old entries rather than growing once maxEntries is reached", async () => {
+    const fetchImpl = fetchStub(async () => jsonResponse(401));
+    const verifier = createApiKeyVerifier({
+      endpoint: "https://app.langwatch.ai",
+      maxEntries: 5,
+      negativeTtlMs: 60_000,
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    for (let i = 0; i < 20; i++) {
+      await verifier.verify(`sk-spray-${i}`);
+    }
+    expect(fetchImpl).toHaveBeenCalledTimes(20);
+
+    // The newest key is still cached, so it costs nothing to re-check.
+    await verifier.verify("sk-spray-19");
+    expect(fetchImpl).toHaveBeenCalledTimes(20);
+
+    // The oldest was evicted to keep the map bounded, so it has to be asked
+    // again even though its negative TTL has not passed.
+    await verifier.verify("sk-spray-0");
+    expect(fetchImpl).toHaveBeenCalledTimes(21);
+  });
+});

package/src/__tests__/http-server-allocation.integration.test.ts

@@ -0,0 +1,279 @@
+/**
+ * Nothing is allocated for a key the LangWatch API has not confirmed, and the
+ * per-key and per-address limits bound what one caller can consume.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { AddressInfo } from "node:net";
+import { createServer, type Server as HttpServer } from "node:http";
+
+import { initConfig } from "../config.js";
+import { createApiKeyVerifier } from "../http-security.js";
+import {
+  countingVerifier,
+  initializeBody,
+  MCP_POST_HEADERS,
+  openSession,
+  requestUntilThrottled,
+  startHarness,
+  VALID_KEY,
+} from "./support/http-server-harness.js";
+
+/** Mirrors MAX_SESSIONS_PER_KEY in http-server.ts. */
+const MAX_SESSIONS_PER_KEY = 20;
+
+beforeEach(() => {
+  initConfig({ endpoint: "https://app.langwatch.ai" });
+});
+
+describe("Key verification before allocation", () => {
+  it("rejects an unverified bearer without creating a session", async () => {
+    const { verifier, verify } = countingVerifier([VALID_KEY]);
+    const harness = await startHarness({ port: 0, apiKeyVerifier: verifier });
+
+    try {
+      const response = await fetch(`${harness.baseUrl}/mcp`, {
+        method: "POST",
+        headers: {
+          ...MCP_POST_HEADERS,
+          Authorization: "Bearer totally-not-a-real-key",
+        },
+        body: initializeBody(),
+      });
+
+      expect(response.status).toBe(401);
+      expect(response.headers.get("mcp-session-id")).toBeNull();
+      expect(verify).toHaveBeenCalledWith("totally-not-a-real-key");
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it("verifies the key before the first byte of session state exists", async () => {
+    const { verifier, verify } = countingVerifier([VALID_KEY]);
+    const harness = await startHarness({ port: 0, apiKeyVerifier: verifier });
+
+    try {
+      await fetch(`${harness.baseUrl}/mcp`, {
+        method: "POST",
+        headers: { ...MCP_POST_HEADERS, Authorization: "Bearer nope" },
+        body: initializeBody(),
+      });
+
+      // A rejected initialize leaves nothing behind, so a later valid
+      // initialize is the first session this key gets.
+      const sessionId = await openSession({ baseUrl: harness.baseUrl });
+      expect(sessionId).toBeTruthy();
+      expect(verify).toHaveBeenCalledTimes(2);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it("refuses to mint an OAuth token for an unverified client_secret", async () => {
+    const { verifier } = countingVerifier([VALID_KEY]);
+    const harness = await startHarness({ port: 0, apiKeyVerifier: verifier });
+
+    try {
+      const response = await fetch(`${harness.baseUrl}/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: "grant_type=client_credentials&client_secret=totally-not-a-real-key",
+      });
+
+      expect(response.status).toBe(401);
+      const body = await response.json();
+      expect(body.error).toBe("invalid_client");
+    } finally {
+      await harness.close();
+    }
+  });
+});
+
+describe("Limits", () => {
+  it("rate limits repeated authentication failures from one address", async () => {
+    const { verifier } = countingVerifier([VALID_KEY]);
+    const harness = await startHarness({ port: 0, apiKeyVerifier: verifier });
+
+    try {
+      const { rejected } = await requestUntilThrottled({
+        request: (attempt) =>
+          fetch(`${harness.baseUrl}/mcp`, {
+            method: "POST",
+            headers: {
+              ...MCP_POST_HEADERS,
+              Authorization: `Bearer wrong-key-${attempt}`,
+            },
+            body: initializeBody(),
+          }),
+      });
+
+      expect(rejected).toBeDefined();
+      await expect(rejected!.json()).resolves.toEqual({
+        error: "Too many requests",
+      });
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it("ignores forwarded client addresses when the proxy is not trusted", async () => {
+    const previous = process.env.LANGWATCH_MCP_TRUST_PROXY;
+    delete process.env.LANGWATCH_MCP_TRUST_PROXY;
+
+    const { verifier } = countingVerifier([VALID_KEY]);
+    const harness = await startHarness({ port: 0, apiKeyVerifier: verifier });
+
+    try {
+      // Every attempt claims a different client address. Untrusted, these are
+      // ignored, so they all count against the one real address.
+      const { rejected } = await requestUntilThrottled({
+        request: (attempt) =>
+          fetch(`${harness.baseUrl}/mcp`, {
+            method: "POST",
+            headers: {
+              ...MCP_POST_HEADERS,
+              Authorization: `Bearer wrong-key-${attempt}`,
+              "X-Forwarded-For": `203.0.113.${attempt}`,
+            },
+            body: initializeBody(),
+          }),
+      });
+
+      expect(rejected).toBeDefined();
+    } finally {
+      await harness.close();
+      if (previous !== undefined) {
+        process.env.LANGWATCH_MCP_TRUST_PROXY = previous;
+      }
+    }
+  });
+
+  it("holds the cap when initialize requests arrive together", async () => {
+    const { verifier } = countingVerifier([VALID_KEY]);
+    const harness = await startHarness({ port: 0, apiKeyVerifier: verifier });
+
+    try {
+      // The cap has to hold when the requests overlap, not just in sequence.
+      // Admission reserves the slot before initialize is awaited, so this does
+      // not depend on when the transport reports the session as initialized.
+      const responses = await Promise.all(
+        Array.from({ length: 40 }, () =>
+          fetch(`${harness.baseUrl}/mcp`, {
+            method: "POST",
+            headers: {
+              ...MCP_POST_HEADERS,
+              Authorization: `Bearer ${VALID_KEY}`,
+            },
+            body: initializeBody(),
+          })
+        )
+      );
+
+      const opened = responses.filter((response) => response.status === 200);
+      const refused = responses.filter((response) => response.status === 429);
+      await Promise.all(responses.map((response) => response.text()));
+
+      expect(opened.length).toBeLessThanOrEqual(MAX_SESSIONS_PER_KEY);
+      expect(opened.length).toBeGreaterThan(0);
+      expect(refused.length).toBe(responses.length - opened.length);
+    } finally {
+      await harness.close();
+    }
+  });
+
+  it("caps concurrent sessions for a single key", async () => {
+    const { verifier } = countingVerifier([VALID_KEY]);
+    const harness = await startHarness({ port: 0, apiKeyVerifier: verifier });
+
+    try {
+      const { rejected } = await requestUntilThrottled({
+        request: () =>
+          fetch(`${harness.baseUrl}/mcp`, {
+            method: "POST",
+            headers: {
+              ...MCP_POST_HEADERS,
+              Authorization: `Bearer ${VALID_KEY}`,
+            },
+            body: initializeBody(),
+          }),
+      });
+
+      expect(rejected).toBeDefined();
+      // Asserting the body, not just the status, so this pins the session cap
+      // rather than any 429 the server might grow later.
+      const body = await rejected!.json();
+      expect(body.error).toContain("Too many concurrent sessions");
+    } finally {
+      await harness.close();
+    }
+  });
+});
+
+describe("Verification against the LangWatch API", () => {
+  let upstream: HttpServer;
+  let upstreamUrl: string;
+  let seenAuthHeaders: (string | undefined)[];
+  let seenUrls: string[];
+
+  beforeEach(async () => {
+    seenAuthHeaders = [];
+    seenUrls = [];
+    upstream = createServer((req, res) => {
+      seenUrls.push(req.url ?? "");
+      const token = req.headers["x-auth-token"];
+      seenAuthHeaders.push(typeof token === "string" ? token : undefined);
+
+      if (token === VALID_KEY) {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ id: "p1", name: "Test", slug: "test" }));
+        return;
+      }
+      res.writeHead(401).end();
+    });
+
+    await new Promise<void>((resolve) =>
+      upstream.listen(0, "127.0.0.1", resolve)
+    );
+    upstreamUrl = `http://127.0.0.1:${(upstream.address() as AddressInfo).port}`;
+  });
+
+  afterEach(async () => {
+    await new Promise<void>((resolve) => upstream.close(() => resolve()));
+  });
+
+  it("checks a key against GET /api/me/project with the key in a header", async () => {
+    const verifier = createApiKeyVerifier({ endpoint: upstreamUrl });
+
+    await expect(verifier.verify(VALID_KEY)).resolves.toBe(true);
+    await expect(verifier.verify("sk-lw-fake")).resolves.toBe(false);
+
+    expect(seenUrls).toEqual(["/api/me/project", "/api/me/project"]);
+    expect(seenAuthHeaders).toEqual([VALID_KEY, "sk-lw-fake"]);
+  });
+
+  it("end to end, only the key the API recognises gets a session", async () => {
+    initConfig({ endpoint: upstreamUrl });
+    const harness = await startHarness({ port: 0 });
+
+    try {
+      const rejected = await fetch(`${harness.baseUrl}/mcp`, {
+        method: "POST",
+        headers: { ...MCP_POST_HEADERS, Authorization: "Bearer sk-lw-fake" },
+        body: initializeBody(),
+      });
+      expect(rejected.status).toBe(401);
+
+      const accepted = await fetch(`${harness.baseUrl}/mcp`, {
+        method: "POST",
+        headers: { ...MCP_POST_HEADERS, Authorization: `Bearer ${VALID_KEY}` },
+        body: initializeBody(),
+      });
+      expect(accepted.status).toBe(200);
+      expect(accepted.headers.get("mcp-session-id")).toBeTruthy();
+      await accepted.text();
+    } finally {
+      await harness.close();
+    }
+  });
+});

package/src/__tests__/http-server-origin.integration.test.ts

@@ -0,0 +1,169 @@
+/**
+ * Origin validation and bind address for the standalone MCP HTTP server.
+ *
+ * The MCP transport specification requires servers to validate Origin on every
+ * incoming connection and to bind loopback when running locally.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { AddressInfo } from "node:net";
+
+import { initConfig } from "../config.js";
+import { startHttpServer } from "../http-server.js";
+import {
+  countingVerifier,
+  initializeBody,
+  MCP_POST_HEADERS,
+  startHarness,
+  VALID_KEY,
+  type Harness,
+} from "./support/http-server-harness.js";
+
+beforeEach(() => {
+  initConfig({ endpoint: "https://app.langwatch.ai" });
+});
+
+describe("Origin validation", () => {
+  let harness: Harness;
+
+  beforeEach(async () => {
+    const { verifier } = countingVerifier([VALID_KEY]);
+    harness = await startHarness({
+      port: 0,
+      allowedOrigins: ["https://console.example.com"],
+      apiKeyVerifier: verifier,
+    });
+  });
+
+  afterEach(async () => {
+    await harness.close();
+  });
+
+  it("rejects a request from an origin that is not on the allowlist", async () => {
+    const response = await fetch(`${harness.baseUrl}/mcp`, {
+      method: "POST",
+      headers: {
+        ...MCP_POST_HEADERS,
+        Authorization: `Bearer ${VALID_KEY}`,
+        Origin: "https://attacker.example",
+      },
+      body: initializeBody(),
+    });
+
+    expect(response.status).toBe(403);
+    await expect(response.json()).resolves.toEqual({
+      error: "Origin not allowed",
+    });
+  });
+
+  it("rejects an unlisted origin even on the unauthenticated health endpoint", async () => {
+    const response = await fetch(`${harness.baseUrl}/health`, {
+      headers: { Origin: "https://attacker.example" },
+    });
+
+    expect(response.status).toBe(403);
+  });
+
+  it("rejects a rebound hostname pointing at loopback", async () => {
+    // The Origin is what the browser sends, and DNS rebinding cannot change it.
+    const response = await fetch(`${harness.baseUrl}/health`, {
+      headers: { Origin: "http://rebind.attacker.example" },
+    });
+
+    expect(response.status).toBe(403);
+  });
+
+  it("accepts a loopback origin without configuration", async () => {
+    const response = await fetch(`${harness.baseUrl}/health`, {
+      headers: { Origin: "http://localhost:5173" },
+    });
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("access-control-allow-origin")).toBe(
+      "http://localhost:5173"
+    );
+  });
+
+  it("accepts a configured origin", async () => {
+    const response = await fetch(`${harness.baseUrl}/health`, {
+      headers: { Origin: "https://console.example.com" },
+    });
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("access-control-allow-origin")).toBe(
+      "https://console.example.com"
+    );
+  });
+
+  it("never answers with a wildcard origin", async () => {
+    for (const origin of [
+      undefined,
+      "http://localhost:5173",
+      "https://console.example.com",
+    ]) {
+      const response = await fetch(`${harness.baseUrl}/health`, {
+        headers: origin ? { Origin: origin } : {},
+      });
+      expect(response.headers.get("access-control-allow-origin")).not.toBe("*");
+    }
+  });
+
+  it("exposes the session id header so an allowed browser origin can read it", async () => {
+    const response = await fetch(`${harness.baseUrl}/health`, {
+      headers: { Origin: "https://console.example.com" },
+    });
+
+    expect(
+      response.headers.get("access-control-expose-headers")?.toLowerCase()
+    ).toContain("mcp-session-id");
+  });
+
+  it("sets the sniffing and framing headers a browser-reachable server needs", async () => {
+    const response = await fetch(`${harness.baseUrl}/health`);
+
+    expect(response.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(response.headers.get("x-frame-options")).toBe("DENY");
+  });
+
+  it("rejects the preflight for an unlisted origin", async () => {
+    const response = await fetch(`${harness.baseUrl}/mcp`, {
+      method: "OPTIONS",
+      headers: { Origin: "https://attacker.example" },
+    });
+
+    expect(response.status).toBe(403);
+  });
+});
+
+describe("Bind address", () => {
+  it("binds loopback by default", async () => {
+    const { verifier } = countingVerifier([VALID_KEY]);
+    const { server, host } = await startHttpServer({
+      port: 0,
+      apiKeyVerifier: verifier,
+    });
+
+    try {
+      expect(host).toBe("127.0.0.1");
+      expect((server.address() as AddressInfo).address).toBe("127.0.0.1");
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
+  it("binds every interface only when asked to", async () => {
+    const { verifier } = countingVerifier([VALID_KEY]);
+    const { server, host } = await startHttpServer({
+      port: 0,
+      host: "0.0.0.0",
+      apiKeyVerifier: verifier,
+    });
+
+    try {
+      expect(host).toBe("0.0.0.0");
+      expect((server.address() as AddressInfo).address).toBe("0.0.0.0");
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+});