feature(auth): DelegatedAuthClientProvider

An optional provider that can be passed to the SSE and StreamableHttp client transports in order to completely delegate the authentication to an external system.

Author: m-paternostro

src/client/auth.ts

@@ -83,6 +83,42 @@ export interface OAuthClientProvider {
   validateResourceURL?(serverUrl: string | URL, resource?: string): Promise<URL | undefined>;
 }
 
+/**
+ * A provider that delegates authentication to an external system.
+ *
+ * This interface allows for custom authentication mechanisms that are
+ * either already implemented on a specific platform or handled outside the
+ * standard OAuth flow, such as API keys, custom tokens, or integration with external
+ * authentication services.
+ */
+export interface DelegatedAuthClientProvider {
+  /**
+   * Returns authentication headers to be included in requests.
+   *
+   * These headers will be added to all HTTP requests made by the transport.
+   * Common examples include Authorization headers, API keys, or custom
+   * authentication tokens.
+   *
+   * @returns Headers to include in requests, or undefined if no authentication is available
+   */
+  headers(): HeadersInit | undefined | Promise<HeadersInit | undefined>;
+
+  /**
+   * Performs authentication when a 401 Unauthorized response is received.
+   *
+   * This method is called when the server responds with a 401 status code,
+   * indicating that the current authentication is invalid or expired.
+   * The implementation should attempt to refresh or re-establish authentication.
+   *
+   * @param context Authentication context providing server and resource information
+   * @param context.serverUrl The URL of the MCP server being authenticated against
+   * @param context.resourceMetadataUrl Optional URL for resource metadata, if available
+   * @returns Promise that resolves to true if authentication was successful,
+   *          false if authentication failed
+   */
+  authorize(context: { serverUrl: string | URL; resourceMetadataUrl?: URL }): boolean | Promise<boolean>;
+}
+
 export type AuthResult = "AUTHORIZED" | "REDIRECT";
 
 export class UnauthorizedError extends Error {

src/client/sse.test.ts

@@ -2,7 +2,7 @@ import { createServer, type IncomingMessage, type Server } from "http";
 import { AddressInfo } from "net";
 import { JSONRPCMessage } from "../types.js";
 import { SSEClientTransport } from "./sse.js";
-import { OAuthClientProvider, UnauthorizedError } from "./auth.js";
+import { DelegatedAuthClientProvider, OAuthClientProvider, UnauthorizedError } from "./auth.js";
 import { OAuthTokens } from "../shared/auth.js";
 
 describe("SSEClientTransport", () => {
@@ -880,4 +880,206 @@ describe("SSEClientTransport", () => {
       expect(mockAuthProvider.redirectToAuthorization).toHaveBeenCalled();
     });
   });
+
+  describe("delegated authentication", () => {
+    let mockDelegatedAuthProvider: jest.Mocked<DelegatedAuthClientProvider>;
+
+    beforeEach(() => {
+      mockDelegatedAuthProvider = {
+        headers: jest.fn(),
+        authorize: jest.fn(),
+      };
+    });
+
+    it("includes delegated auth headers in requests", async () => {
+      mockDelegatedAuthProvider.headers.mockResolvedValue({
+        "Authorization": "Bearer delegated-token",
+        "X-API-Key": "api-key-123"
+      });
+
+      transport = new SSEClientTransport(resourceBaseUrl, {
+        delegatedAuthProvider: mockDelegatedAuthProvider,
+      });
+
+      await transport.start();
+
+      expect(lastServerRequest.headers.authorization).toBe("Bearer delegated-token");
+      expect(lastServerRequest.headers["x-api-key"]).toBe("api-key-123");
+    });
+
+    it("takes precedence over OAuth provider", async () => {
+      const mockOAuthProvider = {
+        get redirectUrl() { return "http://localhost/callback"; },
+        get clientMetadata() { return { redirect_uris: ["http://localhost/callback"] }; },
+        clientInformation: jest.fn(() => ({ client_id: "oauth-client", client_secret: "oauth-secret" })),
+        tokens: jest.fn(() => Promise.resolve({ access_token: "oauth-token", token_type: "Bearer" })),
+        saveTokens: jest.fn(),
+        redirectToAuthorization: jest.fn(),
+        saveCodeVerifier: jest.fn(),
+        codeVerifier: jest.fn(),
+      };
+
+      mockDelegatedAuthProvider.headers.mockResolvedValue({
+        "Authorization": "Bearer delegated-token"
+      });
+
+      transport = new SSEClientTransport(resourceBaseUrl, {
+        authProvider: mockOAuthProvider,
+        delegatedAuthProvider: mockDelegatedAuthProvider,
+      });
+
+      await transport.start();
+
+      expect(lastServerRequest.headers.authorization).toBe("Bearer delegated-token");
+      expect(mockOAuthProvider.tokens).not.toHaveBeenCalled();
+    });
+
+    it("handles 401 during SSE connection with successful reauth", async () => {
+      mockDelegatedAuthProvider.headers.mockResolvedValueOnce(undefined);
+      mockDelegatedAuthProvider.authorize.mockResolvedValue(true);
+      mockDelegatedAuthProvider.headers.mockResolvedValueOnce({
+        "Authorization": "Bearer new-delegated-token"
+      });
+
+      // Create server that returns 401 on first attempt, 200 on second
+      resourceServer.close();
+
+      let attemptCount = 0;
+      resourceServer = createServer((req, res) => {
+        lastServerRequest = req;
+        attemptCount++;
+
+        if (attemptCount === 1) {
+          res.writeHead(401).end();
+          return;
+        }
+
+        res.writeHead(200, {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache, no-transform",
+          Connection: "keep-alive",
+        });
+        res.write("event: endpoint\n");
+        res.write(`data: ${resourceBaseUrl.href}\n\n`);
+      });
+
+      await new Promise<void>((resolve) => {
+        resourceServer.listen(0, "127.0.0.1", () => {
+          const addr = resourceServer.address() as AddressInfo;
+          resourceBaseUrl = new URL(`http://127.0.0.1:${addr.port}`);
+          resolve();
+        });
+      });
+
+      transport = new SSEClientTransport(resourceBaseUrl, {
+        delegatedAuthProvider: mockDelegatedAuthProvider,
+      });
+
+      await transport.start();
+
+      expect(mockDelegatedAuthProvider.authorize).toHaveBeenCalledTimes(1);
+      expect(mockDelegatedAuthProvider.authorize).toHaveBeenCalledWith({
+        serverUrl: resourceBaseUrl,
+        resourceMetadataUrl: undefined
+      });
+      expect(attemptCount).toBe(2);
+    });
+
+    it("throws UnauthorizedError when reauth fails", async () => {
+      mockDelegatedAuthProvider.headers.mockResolvedValue(undefined);
+      mockDelegatedAuthProvider.authorize.mockResolvedValue(false);
+
+      // Create server that always returns 401
+      resourceServer.close();
+
+      resourceServer = createServer((req, res) => {
+        res.writeHead(401).end();
+      });
+
+      await new Promise<void>((resolve) => {
+        resourceServer.listen(0, "127.0.0.1", () => {
+          const addr = resourceServer.address() as AddressInfo;
+          resourceBaseUrl = new URL(`http://127.0.0.1:${addr.port}`);
+          resolve();
+        });
+      });
+
+      transport = new SSEClientTransport(resourceBaseUrl, {
+        delegatedAuthProvider: mockDelegatedAuthProvider,
+      });
+
+      await expect(transport.start()).rejects.toThrow(UnauthorizedError);
+      expect(mockDelegatedAuthProvider.authorize).toHaveBeenCalledTimes(1);
+      expect(mockDelegatedAuthProvider.authorize).toHaveBeenCalledWith({
+        serverUrl: resourceBaseUrl,
+        resourceMetadataUrl: undefined
+      });
+    });
+
+    it("handles 401 during POST request with successful reauth", async () => {
+      mockDelegatedAuthProvider.headers.mockResolvedValue({
+        "Authorization": "Bearer delegated-token"
+      });
+      mockDelegatedAuthProvider.authorize.mockResolvedValue(true);
+
+      // Create server that accepts SSE but returns 401 on first POST, 200 on second
+      resourceServer.close();
+
+      let postAttempts = 0;
+      resourceServer = createServer((req, res) => {
+        lastServerRequest = req;
+
+        switch (req.method) {
+          case "GET":
+            res.writeHead(200, {
+              "Content-Type": "text/event-stream",
+              "Cache-Control": "no-cache, no-transform",
+              Connection: "keep-alive",
+            });
+            res.write("event: endpoint\n");
+            res.write(`data: ${resourceBaseUrl.href}\n\n`);
+            break;
+
+          case "POST":
+            postAttempts++;
+            if (postAttempts === 1) {
+              res.writeHead(401).end();
+            } else {
+              res.writeHead(200).end();
+            }
+            break;
+        }
+      });
+
+      await new Promise<void>((resolve) => {
+        resourceServer.listen(0, "127.0.0.1", () => {
+          const addr = resourceServer.address() as AddressInfo;
+          resourceBaseUrl = new URL(`http://127.0.0.1:${addr.port}`);
+          resolve();
+        });
+      });
+
+      transport = new SSEClientTransport(resourceBaseUrl, {
+        delegatedAuthProvider: mockDelegatedAuthProvider,
+      });
+
+      await transport.start();
+
+      const message: JSONRPCMessage = {
+        jsonrpc: "2.0",
+        id: "1",
+        method: "test",
+        params: {},
+      };
+
+      await transport.send(message);
+
+      expect(mockDelegatedAuthProvider.authorize).toHaveBeenCalledTimes(1);
+      expect(mockDelegatedAuthProvider.authorize).toHaveBeenCalledWith({
+        serverUrl: resourceBaseUrl,
+        resourceMetadataUrl: undefined
+      });
+      expect(postAttempts).toBe(2);
+    });
+  });
 });