@langwatch/mcp-server 2.1.0 → 3.0.0

package/src/documentation-fetch.ts

@@ -5,20 +5,21 @@ const MAX_DOCUMENTATION_BYTES = 2 * 1024 * 1024;
 const DOCUMENTATION_TIMEOUT_MS = 30_000;
 const DOCUMENTATION_CONTENT_TYPES = new Set(["text/markdown", "text/plain"]);
 
-const DOCUMENTATION_CONFIG: Record<DocumentationKind, { defaultPath: string; namespace: string }> = {
-  langwatch: {
-    defaultPath: "/docs/llms.txt",
-    namespace: "/docs",
-  },
-  scenario: {
-    defaultPath: "/scenario/llms.txt",
-    namespace: "/scenario",
-  },
-};
+const DOCUMENTATION_CONFIG: Record<DocumentationKind, { defaultPath: string; namespace: string }> =
+  {
+    langwatch: {
+      defaultPath: "/docs/llms.txt",
+      namespace: "/docs",
+    },
+    scenario: {
+      defaultPath: "/scenario/llms.txt",
+      namespace: "/scenario",
+    },
+  };
 
 function documentationUrlError(namespace: string): Error {
   return new Error(
-    `Only a trusted LangWatch documentation URL under ${TRUSTED_DOCUMENTATION_ORIGIN}${namespace}/ may be fetched`
+    `Only a trusted LangWatch documentation URL under ${TRUSTED_DOCUMENTATION_ORIGIN}${namespace}/ may be fetched`,
   );
 }
 
@@ -45,14 +46,14 @@ export function resolveDocumentationUrl(kind: DocumentationKind, input?: string)
     throw documentationUrlError(namespace);
   }
 
-  if (
-    url.protocol !== "https:" ||
-    url.hostname !== "langwatch.ai" ||
-    url.port !== "" ||
-    url.username !== "" ||
-    url.password !== "" ||
-    !url.pathname.startsWith(`${namespace}/`)
-  ) {
+  const isTrustedDocumentationUrl =
+    url.protocol === "https:" &&
+    url.hostname === "langwatch.ai" &&
+    url.port === "" &&
+    url.username === "" &&
+    url.password === "" &&
+    url.pathname.startsWith(`${namespace}/`);
+  if (!isTrustedDocumentationUrl) {
     throw documentationUrlError(namespace);
   }
 
@@ -67,7 +68,7 @@ export function resolveDocumentationUrl(kind: DocumentationKind, input?: string)
 export async function fetchDocumentation(
   kind: DocumentationKind,
   input?: string,
-  fetchImplementation: typeof fetch = fetch
+  fetchImplementation: typeof fetch = fetch,
 ): Promise<string> {
   const url = resolveDocumentationUrl(kind, input);
   const response = await fetchImplementation(url, {

package/src/http-security.ts

@@ -1,12 +1,7 @@
 /**
- * Security primitives for the standalone MCP HTTP server.
- *
- * The standalone server runs on developer machines and inside clusters with no
- * database of its own, so it cannot look an API key up locally the way the
- * in-app handler does. These helpers give it the same guarantees over HTTP:
- * an origin allowlist, API key verification against the LangWatch API with a
- * short-lived cache, per-IP rate limiting of failed authentication, and a
- * session store that expires idle sessions and caps concurrency per key.
+ * Security primitives for the standalone MCP HTTP server. The standalone server runs on
+ * developer machines and inside clusters with no database of its own, so it cannot look an API
+ * key up locally the way the in-app handler does.
  */
 
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
@@ -38,25 +33,18 @@ export function isLoopbackHost(host: string): boolean {
 // ---------------------------------------------------------------------------
 
 /**
- * Origins accepted without configuration.
- *
- * A DNS rebinding attack reaches the server through an attacker-controlled
- * hostname that resolves to a loopback address, so the browser sends that
- * attacker hostname in the Origin header. It can never send a loopback origin
- * for a page it did not actually load from this machine, which is the case the
- * server exists to serve.
+ * Origins accepted without configuration. A DNS rebinding attack reaches the server through an
+ * attacker-controlled hostname that resolves to a loopback address, so the browser sends that
+ * attacker hostname in the Origin header.
  */
 const ALWAYS_ALLOWED_ORIGIN_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
 
 /**
- * Reduces an origin to `scheme://host[:port]` so comparisons ignore trailing
- * slashes, paths, and case differences. Returns null for anything that is not
- * a usable origin, including the opaque `null` origin sent by sandboxed frames
- * and `file://` pages.
+ * Reduces an origin to `scheme://host[:port]` so comparisons ignore trailing slashes, paths,
+ * and case differences. Returns null for anything that is not a usable origin, including the
+ * opaque `null` origin sent by sandboxed frames and `file://` pages.
  */
-function normalizeOrigin(
-  origin: string
-): { origin: string; hostname: string } | null {
+function normalizeOrigin(origin: string): { origin: string; hostname: string } | null {
   let parsed: URL;
   try {
     parsed = new URL(origin.trim());
@@ -105,21 +93,15 @@ export function isOriginAllowed({
 // ---------------------------------------------------------------------------
 
 /**
- * Per-process key for deriving identifiers from API keys.
- *
- * Regenerated on every start. The derived values only index in-memory maps and
- * are only compared within one process, so they never need to be reproducible
- * across restarts. Keying the digest means that anything which exposes those
- * maps, a heap dump or debug output, still does not let a list of candidate
- * keys be confirmed offline the way a bare digest would.
+ * Per-process key for deriving identifiers from API keys. Regenerated on every start. The
+ * derived values only index in-memory maps and are only compared within one process, so they
+ * never need to be reproducible across restarts.
  */
 const KEY_DERIVATION_SECRET = randomBytes(32);
 
 /** Derives an opaque identifier from an API key, for use as a map key. */
 export function hashApiKey(apiKey: string): string {
-  return createHmac("sha256", KEY_DERIVATION_SECRET)
-    .update(apiKey)
-    .digest("hex");
+  return createHmac("sha256", KEY_DERIVATION_SECRET).update(apiKey).digest("hex");
 }
 
 /** Constant-time API key comparison over fixed-length digests. */
@@ -130,20 +112,14 @@ export function apiKeysMatch({
   presentedKey: string;
   expectedKey: string;
 }): boolean {
-  const presented = createHmac("sha256", KEY_DERIVATION_SECRET)
-    .update(presentedKey)
-    .digest();
-  const expected = createHmac("sha256", KEY_DERIVATION_SECRET)
-    .update(expectedKey)
-    .digest();
+  const presented = createHmac("sha256", KEY_DERIVATION_SECRET).update(presentedKey).digest();
+  const expected = createHmac("sha256", KEY_DERIVATION_SECRET).update(expectedKey).digest();
   return timingSafeEqual(presented, expected);
 }
 
-// ---------------------------------------------------------------------------
-// Rate limiter (fixed window per client address)
-//
-// Counts reset in whole windows rather than sliding, so a burst straddling a
-// window boundary can reach twice maxRequests. That is acceptable for the
+// --------------------------------------------------------------------------- Rate limiter
+// (fixed window per client address) Counts reset in whole windows rather than sliding, so a
+// burst straddling a window boundary can reach twice maxRequests. That is acceptable for the
 // failed-authentication and OAuth limits this backs.
 // ---------------------------------------------------------------------------
 
@@ -203,7 +179,7 @@ export function createRateLimiter({
  * project API key and returns only the identity of the project behind it, so
  * it answers "is this key real" without granting or costing anything else.
  */
-const VERIFY_PATH = "/api/me/project";
+const VERIFY_PATH = "/api/v1/me/project";
 
 export interface ApiKeyVerifier {
   /** True when the LangWatch API recognises this key. */
@@ -214,6 +190,75 @@ export interface ApiKeyVerifier {
   clear(): void;
 }
 
+type VerdictCache = Map<string, { valid: boolean; expiresAt: number }>;
+
+function sweepVerdicts(cache: VerdictCache): void {
+  const now = Date.now();
+  for (const [key, entry] of cache) {
+    if (now >= entry.expiresAt) cache.delete(key);
+  }
+}
+
+function rememberVerdict({
+  cache,
+  hashed,
+  valid,
+  maxEntries,
+  ttlMs,
+}: {
+  cache: VerdictCache;
+  hashed: string;
+  valid: boolean;
+  maxEntries: number;
+  ttlMs: number;
+}): void {
+  if (cache.size >= maxEntries) {
+    sweepVerdicts(cache);
+    // Map iteration is insertion ordered, so the first key is the oldest.
+    while (cache.size >= maxEntries) {
+      const oldest = cache.keys().next();
+      if (oldest.done) break;
+      cache.delete(oldest.value);
+    }
+  }
+  cache.set(hashed, { valid, expiresAt: Date.now() + ttlMs });
+}
+
+/** The API's verdict on a key: true, false on 401/403, null when it could not answer. */
+async function askVerifyEndpoint({
+  endpoint,
+  apiKey,
+  fetchImpl,
+  requestTimeoutMs,
+}: {
+  endpoint: string;
+  apiKey: string;
+  fetchImpl: typeof fetch;
+  requestTimeoutMs: number;
+}): Promise<boolean | null> {
+  let response: Response;
+  try {
+    response = await fetchImpl(`${endpoint}${VERIFY_PATH}`, {
+      method: "GET",
+      headers: { "X-Auth-Token": apiKey },
+      // An upstream that accepts the connection and never answers would
+      // otherwise leave the in-flight promise unsettled, parking every
+      // request for this key behind it until the socket dies.
+      signal: AbortSignal.timeout(requestTimeoutMs),
+    });
+  } catch {
+    return null;
+  }
+
+  // Only the status matters. Releasing the body returns the socket to the
+  // pool instead of holding it until garbage collection.
+  await response.body?.cancel().catch(() => undefined);
+
+  if (response.ok) return true;
+  if (response.status === 401 || response.status === 403) return false;
+  return null;
+}
+
 export function createApiKeyVerifier({
   endpoint,
   positiveTtlMs = 60_000,
@@ -229,55 +274,20 @@ export function createApiKeyVerifier({
   requestTimeoutMs?: number;
   fetchImpl?: typeof fetch;
 }): ApiKeyVerifier {
-  const cache = new Map<string, { valid: boolean; expiresAt: number }>();
+  const cache: VerdictCache = new Map();
   const inFlight = new Map<string, Promise<boolean>>();
 
-  function sweep(): void {
-    const now = Date.now();
-    for (const [key, entry] of cache) {
-      if (now >= entry.expiresAt) cache.delete(key);
-    }
-  }
-
-  function remember(hashed: string, valid: boolean): void {
-    if (cache.size >= maxEntries) {
-      sweep();
-      // Map iteration is insertion ordered, so the first key is the oldest.
-      while (cache.size >= maxEntries) {
-        const oldest = cache.keys().next();
-        if (oldest.done) break;
-        cache.delete(oldest.value);
-      }
-    }
-    cache.set(hashed, {
+  const sweep = (): void => sweepVerdicts(cache);
+  const remember = (hashed: string, valid: boolean): void =>
+    rememberVerdict({
+      cache,
+      hashed,
       valid,
-      expiresAt: Date.now() + (valid ? positiveTtlMs : negativeTtlMs),
+      maxEntries,
+      ttlMs: valid ? positiveTtlMs : negativeTtlMs,
     });
-  }
-
-  async function askApi(apiKey: string): Promise<boolean | null> {
-    let response: Response;
-    try {
-      response = await fetchImpl(`${endpoint}${VERIFY_PATH}`, {
-        method: "GET",
-        headers: { "X-Auth-Token": apiKey },
-        // An upstream that accepts the connection and never answers would
-        // otherwise leave the in-flight promise unsettled, parking every
-        // request for this key behind it until the socket dies.
-        signal: AbortSignal.timeout(requestTimeoutMs),
-      });
-    } catch {
-      return null;
-    }
-
-    // Only the status matters. Releasing the body returns the socket to the
-    // pool instead of holding it until garbage collection.
-    await response.body?.cancel().catch(() => undefined);
-
-    if (response.ok) return true;
-    if (response.status === 401 || response.status === 403) return false;
-    return null;
-  }
+  const askApi = (apiKey: string) =>
+    askVerifyEndpoint({ endpoint, apiKey, fetchImpl, requestTimeoutMs });
 
   return {
     async verify(apiKey) {
@@ -355,6 +365,67 @@ export interface SessionStore<TTransport> {
   readonly size: number;
 }
 
+/** What a session store holds: the live sessions and how many each hashed key owns. */
+interface SessionTable<TTransport> {
+  sessions: Map<string, SessionRecord<TTransport>>;
+  countByKey: Map<string, number>;
+}
+
+function releaseSlot({ countByKey }: { countByKey: Map<string, number> }, apiKey: string): void {
+  const hashed = hashApiKey(apiKey);
+  const next = (countByKey.get(hashed) ?? 1) - 1;
+  if (next <= 0) countByKey.delete(hashed);
+  else countByKey.set(hashed, next);
+}
+
+function dropSession<TTransport>({
+  table,
+  sessionId,
+  record,
+}: {
+  table: SessionTable<TTransport>;
+  sessionId: string;
+  record: SessionRecord<TTransport>;
+}): void {
+  table.sessions.delete(sessionId);
+  releaseSlot(table, record.apiKey);
+}
+
+/** Counts a slot for the key now; the session lands on commit, or the slot is given back. */
+function reserveSlot<TTransport>({
+  table,
+  apiKey,
+}: {
+  table: SessionTable<TTransport>;
+  apiKey: string;
+}): SessionReservation<TTransport> {
+  const hashed = hashApiKey(apiKey);
+  table.countByKey.set(hashed, (table.countByKey.get(hashed) ?? 0) + 1);
+  let settled = false;
+
+  return {
+    commit({ sessionId, transport }) {
+      if (settled) return;
+      settled = true;
+
+      const existing = table.sessions.get(sessionId);
+      if (existing) dropSession({ table, sessionId, record: existing });
+
+      // The count already carries this slot from the reservation.
+      table.sessions.set(sessionId, {
+        transport,
+        apiKey,
+        lastActivityAt: Date.now(),
+      });
+    },
+    release() {
+      if (settled) return;
+      settled = true;
+      releaseSlot(table, apiKey);
+    },
+  };
+}
+
 export function createSessionStore<TTransport>({
   maxAgeMs,
   closeTransport,
@@ -367,45 +438,10 @@ export function createSessionStore<TTransport>({
   const sessions = new Map<string, SessionRecord<TTransport>>();
   const countByKey = new Map<string, number>();
 
-  function decrement(apiKey: string): void {
-    const hashed = hashApiKey(apiKey);
-    const next = (countByKey.get(hashed) ?? 1) - 1;
-    if (next <= 0) countByKey.delete(hashed);
-    else countByKey.set(hashed, next);
-  }
-
-  function drop(sessionId: string, record: SessionRecord<TTransport>): void {
-    sessions.delete(sessionId);
-    decrement(record.apiKey);
-  }
-
-  function reserve(apiKey: string): SessionReservation<TTransport> {
-    const hashed = hashApiKey(apiKey);
-    countByKey.set(hashed, (countByKey.get(hashed) ?? 0) + 1);
-    let settled = false;
-
-    return {
-      commit({ sessionId, transport }) {
-        if (settled) return;
-        settled = true;
-
-        const existing = sessions.get(sessionId);
-        if (existing) drop(sessionId, existing);
-
-        // The count already carries this slot from the reservation.
-        sessions.set(sessionId, {
-          transport,
-          apiKey,
-          lastActivityAt: Date.now(),
-        });
-      },
-      release() {
-        if (settled) return;
-        settled = true;
-        decrement(apiKey);
-      },
-    };
-  }
+  const table: SessionTable<TTransport> = { sessions, countByKey };
+  const reserve = (apiKey: string) => reserveSlot({ table, apiKey });
+  const drop = (sessionId: string, record: SessionRecord<TTransport>) =>
+    dropSession({ table, sessionId, record });
 
   return {
     get(sessionId) {
@@ -454,13 +490,8 @@ export interface OAuthTokenEntry {
 }
 
 /**
- * Makes room for one more token before it is issued.
- *
- * Tokens outlive the requests that created them, so a key asking for them in a
- * loop would otherwise retain entries until each expired. The per-address rate
- * limit does not bound this on its own, because one key can be presented from
- * many addresses. Expired entries anywhere in the map are dropped on the way
- * past.
+ * Makes room for one more token before it is issued. Tokens outlive the requests that created
+ * them, so a key asking for them in a loop would otherwise retain entries until each expired.
  */
 export function admitOAuthToken({
   apiKey,