mcp-proxy 5.8.0 → 5.9.0

package/jsr.json

@@ -3,5 +3,5 @@
   "include": ["src/index.ts", "src/bin/mcp-proxy.ts"],
   "license": "MIT",
   "name": "@punkpeye/mcp-proxy",
-  "version": "5.8.0"
+  "version": "5.9.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-proxy",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "main": "dist/index.js",
   "scripts": {
     "build": "tsdown",

package/src/authentication.test.ts

@@ -103,15 +103,90 @@ describe("AuthenticationMiddleware", () => {
       expect(body.id).toBe(null);
     });
 
-    it("should have consistent format regardless of configuration", () => {
+    it("should have consistent body format regardless of configuration", () => {
       const middleware1 = new AuthenticationMiddleware({});
       const middleware2 = new AuthenticationMiddleware({ apiKey: "test" });
 
       const response1 = middleware1.getUnauthorizedResponse();
       const response2 = middleware2.getUnauthorizedResponse();
 
-      expect(response1.headers).toEqual(response2.headers);
       expect(response1.body).toEqual(response2.body);
     });
+
+    it("should not include WWW-Authenticate header without OAuth config", () => {
+      const middleware = new AuthenticationMiddleware({ apiKey: "test" });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toBeUndefined();
+    });
+
+    it("should include WWW-Authenticate header with OAuth config", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          protectedResource: {
+            resource: "https://example.com",
+          },
+        },
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toBe(
+        'Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"',
+      );
+    });
+
+    it("should handle OAuth config with trailing slash in resource URL", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          protectedResource: {
+            resource: "https://example.com/",
+          },
+        },
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toBe(
+        'Bearer resource_metadata="https://example.com//.well-known/oauth-protected-resource"',
+      );
+    });
+
+    it("should not include WWW-Authenticate header when OAuth config is empty", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {},
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toBeUndefined();
+    });
+
+    it("should not include WWW-Authenticate header when protectedResource is empty", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          protectedResource: {},
+        },
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toBeUndefined();
+    });
+
+    it("should include WWW-Authenticate header with OAuth config but no apiKey", () => {
+      const middleware = new AuthenticationMiddleware({
+        oauth: {
+          protectedResource: {
+            resource: "https://example.com",
+          },
+        },
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toBe(
+        'Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"',
+      );
+    });
   });
 });

package/src/authentication.ts

@@ -2,12 +2,26 @@ import type { IncomingMessage } from "http";
 
 export interface AuthConfig {
   apiKey?: string;
+  oauth?: {
+    protectedResource?: {
+      resource?: string;
+    };
+  };
 }
 
 export class AuthenticationMiddleware {
   constructor(private config: AuthConfig = {}) {}
 
-  getUnauthorizedResponse() {
+  getUnauthorizedResponse(): { body: string; headers: Record<string, string> } {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    // Add WWW-Authenticate header if OAuth config is available
+    if (this.config.oauth?.protectedResource?.resource) {
+      headers["WWW-Authenticate"] = `Bearer resource_metadata="${this.config.oauth.protectedResource.resource}/.well-known/oauth-protected-resource"`;
+    }
+
     return {
       body: JSON.stringify({
         error: {
@@ -17,9 +31,7 @@ export class AuthenticationMiddleware {
         id: null,
         jsonrpc: "2.0",
       }),
-      headers: {
-        "Content-Type": "application/json",
-      },
+      headers,
     };
   }
 

package/src/index.ts

@@ -1,3 +1,5 @@
+export type { AuthConfig } from "./authentication.js";
+export { AuthenticationMiddleware } from "./authentication.js";
 export { InMemoryEventStore } from "./InMemoryEventStore.js";
 export { proxyServer } from "./proxyServer.js";
 export { startHTTPServer } from "./startHTTPServer.js";

package/src/startHTTPServer.test.ts

@@ -1181,3 +1181,497 @@ it("includes Authorization in CORS allowed headers", async () => {
 
   await httpServer.close();
 });
+
+// Tests for FastMCP-style authentication with { authenticated: false } pattern
+
+it("returns 401 when authenticate callback returns { authenticated: false } in stateless mode", async () => {
+  const stdioTransport = new StdioClientTransport({
+    args: ["src/fixtures/simple-stdio-server.ts"],
+    command: "tsx",
+  });
+
+  const stdioClient = new Client(
+    {
+      name: "mcp-proxy",
+      version: "1.0.0",
+    },
+    {
+      capabilities: {},
+    },
+  );
+
+  await stdioClient.connect(stdioTransport);
+
+  const serverVersion = stdioClient.getServerVersion() as {
+    name: string;
+    version: string;
+  };
+
+  const serverCapabilities = stdioClient.getServerCapabilities() as {
+    capabilities: Record<string, unknown>;
+  };
+
+  const port = await getRandomPort();
+
+  // Mock authenticate callback that returns { authenticated: false }
+  const authenticate = vi.fn().mockResolvedValue({
+    authenticated: false,
+    error: "Invalid JWT token",
+  });
+
+  const httpServer = await startHTTPServer({
+    authenticate,
+    createServer: async () => {
+      const mcpServer = new Server(serverVersion, {
+        capabilities: serverCapabilities,
+      });
+
+      await proxyServer({
+        client: stdioClient,
+        server: mcpServer,
+        serverCapabilities,
+      });
+
+      return mcpServer;
+    },
+    port,
+    stateless: true,
+  });
+
+  // Create client with invalid Bearer token
+  const streamTransport = new StreamableHTTPClientTransport(
+    new URL(`http://localhost:${port}/mcp`),
+    {
+      requestInit: {
+        headers: {
+          Authorization: "Bearer invalid-jwt-token",
+        },
+      },
+    },
+  );
+
+  const streamClient = new Client(
+    {
+      name: "stream-client-auth-false",
+      version: "1.0.0",
+    },
+    {
+      capabilities: {},
+    },
+  );
+
+  // Connection should fail due to authentication returning false
+  await expect(streamClient.connect(streamTransport)).rejects.toThrow();
+
+  // Verify authenticate callback was called
+  expect(authenticate).toHaveBeenCalled();
+
+  await httpServer.close();
+  await stdioClient.close();
+});
+
+it("returns 401 with custom error message when { authenticated: false, error: '...' }", async () => {
+  const stdioTransport = new StdioClientTransport({
+    args: ["src/fixtures/simple-stdio-server.ts"],
+    command: "tsx",
+  });
+
+  const stdioClient = new Client(
+    {
+      name: "mcp-proxy",
+      version: "1.0.0",
+    },
+    {
+      capabilities: {},
+    },
+  );
+
+  await stdioClient.connect(stdioTransport);
+
+  const serverVersion = stdioClient.getServerVersion() as {
+    name: string;
+    version: string;
+  };
+
+  const serverCapabilities = stdioClient.getServerCapabilities() as {
+    capabilities: Record<string, unknown>;
+  };
+
+  const port = await getRandomPort();
+
+  const customErrorMessage = "Token expired at 2025-10-06T12:00:00Z";
+
+  // Mock authenticate callback with custom error message
+  const authenticate = vi.fn().mockResolvedValue({
+    authenticated: false,
+    error: customErrorMessage,
+  });
+
+  const httpServer = await startHTTPServer({
+    authenticate,
+    createServer: async () => {
+      const mcpServer = new Server(serverVersion, {
+        capabilities: serverCapabilities,
+      });
+
+      await proxyServer({
+        client: stdioClient,
+        server: mcpServer,
+        serverCapabilities,
+      });
+
+      return mcpServer;
+    },
+    port,
+    stateless: true,
+  });
+
+  // Make request directly with fetch to check error message
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    body: JSON.stringify({
+      id: 1,
+      jsonrpc: "2.0",
+      method: "initialize",
+      params: {
+        capabilities: {},
+        clientInfo: { name: "test", version: "1.0.0" },
+        protocolVersion: "2024-11-05",
+      },
+    }),
+    headers: {
+      "Accept": "application/json, text/event-stream",
+      "Authorization": "Bearer expired-token",
+      "Content-Type": "application/json",
+    },
+    method: "POST",
+  });
+
+  expect(response.status).toBe(401);
+
+  const errorResponse = (await response.json()) as {
+    error: { code: number; message: string };
+    id: null | number;
+    jsonrpc: string;
+  };
+  expect(errorResponse.error.message).toBe(customErrorMessage);
+
+  await httpServer.close();
+  await stdioClient.close();
+});
+
+it("returns 401 when createServer throws authentication error", async () => {
+  const stdioTransport = new StdioClientTransport({
+    args: ["src/fixtures/simple-stdio-server.ts"],
+    command: "tsx",
+  });
+
+  const stdioClient = new Client(
+    {
+      name: "mcp-proxy",
+      version: "1.0.0",
+    },
+    {
+      capabilities: {},
+    },
+  );
+
+  await stdioClient.connect(stdioTransport);
+
+  const port = await getRandomPort();
+
+  // Mock authenticate that passes, but createServer throws auth error
+  const authenticate = vi.fn().mockResolvedValue({
+    authenticated: true,
+    session: { userId: "test" },
+  });
+
+  const httpServer = await startHTTPServer({
+    authenticate,
+    createServer: async () => {
+      // Simulate FastMCP throwing error for authenticated: false
+      throw new Error("Authentication failed: Invalid JWT payload");
+    },
+    port,
+    stateless: true,
+  });
+
+  // Make request
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    body: JSON.stringify({
+      id: 1,
+      jsonrpc: "2.0",
+      method: "initialize",
+      params: {
+        capabilities: {},
+        clientInfo: { name: "test", version: "1.0.0" },
+        protocolVersion: "2024-11-05",
+      },
+    }),
+    headers: {
+      "Accept": "application/json, text/event-stream",
+      "Authorization": "Bearer test-token",
+      "Content-Type": "application/json",
+    },
+    method: "POST",
+  });
+
+  expect(response.status).toBe(401);
+
+  const errorResponse = (await response.json()) as {
+    error: { code: number; message: string };
+    id: null | number;
+    jsonrpc: string;
+  };
+  expect(errorResponse.error.message).toContain("Authentication failed");
+
+  await httpServer.close();
+  await stdioClient.close();
+});
+
+it("returns 401 when createServer throws JWT-related error", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    createServer: async () => {
+      throw new Error("Invalid JWT signature");
+    },
+    port,
+    stateless: true,
+  });
+
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    body: JSON.stringify({
+      id: 1,
+      jsonrpc: "2.0",
+      method: "initialize",
+      params: {
+        capabilities: {},
+        clientInfo: { name: "test", version: "1.0.0" },
+        protocolVersion: "2024-11-05",
+      },
+    }),
+    headers: {
+      "Accept": "application/json, text/event-stream",
+      "Content-Type": "application/json",
+    },
+    method: "POST",
+  });
+
+  expect(response.status).toBe(401);
+
+  const errorResponse = (await response.json()) as {
+    error: { code: number; message: string };
+    id: null | number;
+    jsonrpc: string;
+  };
+  expect(errorResponse.error.message).toContain("Invalid JWT");
+
+  await httpServer.close();
+});
+
+it("returns 401 when createServer throws Token-related error", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    createServer: async () => {
+      throw new Error("Token has been revoked");
+    },
+    port,
+    stateless: true,
+  });
+
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    body: JSON.stringify({
+      id: 1,
+      jsonrpc: "2.0",
+      method: "initialize",
+      params: {
+        capabilities: {},
+        clientInfo: { name: "test", version: "1.0.0" },
+        protocolVersion: "2024-11-05",
+      },
+    }),
+    headers: {
+      "Accept": "application/json, text/event-stream",
+      "Content-Type": "application/json",
+    },
+    method: "POST",
+  });
+
+  expect(response.status).toBe(401);
+
+  const errorResponse = (await response.json()) as {
+    error: { code: number; message: string };
+    id: null | number;
+    jsonrpc: string;
+  };
+  expect(errorResponse.error.message).toContain("Token");
+
+  await httpServer.close();
+});
+
+it("returns 401 when createServer throws Unauthorized error", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    createServer: async () => {
+      throw new Error("Unauthorized access");
+    },
+    port,
+    stateless: true,
+  });
+
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    body: JSON.stringify({
+      id: 1,
+      jsonrpc: "2.0",
+      method: "initialize",
+      params: {
+        capabilities: {},
+        clientInfo: { name: "test", version: "1.0.0" },
+        protocolVersion: "2024-11-05",
+      },
+    }),
+    headers: {
+      "Accept": "application/json, text/event-stream",
+      "Content-Type": "application/json",
+    },
+    method: "POST",
+  });
+
+  expect(response.status).toBe(401);
+
+  const errorResponse = (await response.json()) as {
+    error: { code: number; message: string };
+    id: null | number;
+    jsonrpc: string;
+  };
+  expect(errorResponse.error.message).toContain("Unauthorized");
+
+  await httpServer.close();
+});
+
+it("returns 500 when createServer throws non-auth error", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    createServer: async () => {
+      throw new Error("Database connection failed");
+    },
+    port,
+    stateless: true,
+  });
+
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    body: JSON.stringify({
+      id: 1,
+      jsonrpc: "2.0",
+      method: "initialize",
+      params: {
+        capabilities: {},
+        clientInfo: { name: "test", version: "1.0.0" },
+        protocolVersion: "2024-11-05",
+      },
+    }),
+    headers: {
+      "Accept": "application/json, text/event-stream",
+      "Content-Type": "application/json",
+    },
+    method: "POST",
+  });
+
+  expect(response.status).toBe(500);
+
+  await httpServer.close();
+});
+
+it("succeeds when authenticate returns { authenticated: true } in stateless mode", async () => {
+  const stdioTransport = new StdioClientTransport({
+    args: ["src/fixtures/simple-stdio-server.ts"],
+    command: "tsx",
+  });
+
+  const stdioClient = new Client(
+    {
+      name: "mcp-proxy",
+      version: "1.0.0",
+    },
+    {
+      capabilities: {},
+    },
+  );
+
+  await stdioClient.connect(stdioTransport);
+
+  const serverVersion = stdioClient.getServerVersion() as {
+    name: string;
+    version: string;
+  };
+
+  const serverCapabilities = stdioClient.getServerCapabilities() as {
+    capabilities: Record<string, unknown>;
+  };
+
+  const port = await getRandomPort();
+
+  // Mock authenticate callback that returns { authenticated: true }
+  const authenticate = vi.fn().mockResolvedValue({
+    authenticated: true,
+    session: { email: "test@example.com", userId: "user123" },
+  });
+
+  const httpServer = await startHTTPServer({
+    authenticate,
+    createServer: async () => {
+      const mcpServer = new Server(serverVersion, {
+        capabilities: serverCapabilities,
+      });
+
+      await proxyServer({
+        client: stdioClient,
+        server: mcpServer,
+        serverCapabilities,
+      });
+
+      return mcpServer;
+    },
+    port,
+    stateless: true,
+  });
+
+  // Create client with valid Bearer token
+  const streamTransport = new StreamableHTTPClientTransport(
+    new URL(`http://localhost:${port}/mcp`),
+    {
+      requestInit: {
+        headers: {
+          Authorization: "Bearer valid-jwt-token",
+        },
+      },
+    },
+  );
+
+  const streamClient = new Client(
+    {
+      name: "stream-client-auth-true",
+      version: "1.0.0",
+    },
+    {
+      capabilities: {},
+    },
+  );
+
+  // Should connect successfully
+  await streamClient.connect(streamTransport);
+
+  // Should be able to make requests
+  const result = await streamClient.listResources();
+  expect(result.resources).toBeDefined();
+
+  // Verify authenticate callback was called
+  expect(authenticate).toHaveBeenCalled();
+
+  await streamClient.close();
+  await httpServer.close();
+  await stdioClient.close();
+});