Merge pull request #151 from modelcontextprotocol/justin/server-auth

Server implementation of MCP auth

Author: jspahrsummers

package-lock.json

@@ -47,24 +47,30 @@
   },
   "dependencies": {
     "content-type": "^1.0.5",
+    "cors": "^2.8.5",
     "eventsource": "^3.0.2",
+    "express": "^5.0.1",
+    "express-rate-limit": "^7.5.0",
     "pkce-challenge": "^4.1.0",
     "raw-body": "^3.0.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.24.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.8.0",
+    "@jest-mock/express": "^3.0.0",
     "@types/content-type": "^1.1.8",
+    "@types/cors": "^2.8.17",
     "@types/eslint__js": "^8.42.3",
     "@types/eventsource": "^1.1.15",
-    "@types/express": "^4.17.21",
+    "@types/express": "^5.0.0",
     "@types/jest": "^29.5.12",
     "@types/node": "^22.0.2",
+    "@types/supertest": "^6.0.2",
     "@types/ws": "^8.5.12",
     "eslint": "^9.8.0",
-    "express": "^4.19.2",
     "jest": "^29.7.0",
+    "supertest": "^7.0.0",
     "ts-jest": "^29.2.4",
     "tsx": "^4.16.5",
     "typescript": "^5.5.4",
@@ -74,4 +80,4 @@
   "resolutions": {
     "strip-ansi": "6.0.1"
   }
-}
+}

package.json

@@ -6,7 +6,6 @@ import {
   registerClient,
 } from "./auth.js";
 
-
 // Mock fetch globally
 const mockFetch = jest.fn();
 global.fetch = mockFetch;

src/client/auth.test.ts

@@ -1,84 +1,7 @@
 import pkceChallenge from "pkce-challenge";
-import { z } from "zod";
 import { LATEST_PROTOCOL_VERSION } from "../types.js";
-
-export const OAuthMetadataSchema = z
-  .object({
-    issuer: z.string(),
-    authorization_endpoint: z.string(),
-    token_endpoint: z.string(),
-    registration_endpoint: z.string().optional(),
-    scopes_supported: z.array(z.string()).optional(),
-    response_types_supported: z.array(z.string()),
-    response_modes_supported: z.array(z.string()).optional(),
-    grant_types_supported: z.array(z.string()).optional(),
-    token_endpoint_auth_methods_supported: z.array(z.string()).optional(),
-    token_endpoint_auth_signing_alg_values_supported: z
-      .array(z.string())
-      .optional(),
-    service_documentation: z.string().optional(),
-    revocation_endpoint: z.string().optional(),
-    revocation_endpoint_auth_methods_supported: z.array(z.string()).optional(),
-    revocation_endpoint_auth_signing_alg_values_supported: z
-      .array(z.string())
-      .optional(),
-    introspection_endpoint: z.string().optional(),
-    introspection_endpoint_auth_methods_supported: z
-      .array(z.string())
-      .optional(),
-    introspection_endpoint_auth_signing_alg_values_supported: z
-      .array(z.string())
-      .optional(),
-    code_challenge_methods_supported: z.array(z.string()).optional(),
-  })
-  .passthrough();
-
-export const OAuthTokensSchema = z
-  .object({
-    access_token: z.string(),
-    token_type: z.string(),
-    expires_in: z.number().optional(),
-    scope: z.string().optional(),
-    refresh_token: z.string().optional(),
-  })
-  .strip();
-
-/**
- * Client metadata schema according to RFC 7591 OAuth 2.0 Dynamic Client Registration
- */
-export const OAuthClientMetadataSchema = z.object({
-  redirect_uris: z.array(z.string()),
-  token_endpoint_auth_method: z.string().optional(),
-  grant_types: z.array(z.string()).optional(),
-  response_types: z.array(z.string()).optional(),
-  client_name: z.string().optional(),
-  client_uri: z.string().optional(),
-  logo_uri: z.string().optional(),
-  scope: z.string().optional(),
-  contacts: z.array(z.string()).optional(),
-  tos_uri: z.string().optional(),
-  policy_uri: z.string().optional(),
-  jwks_uri: z.string().optional(),
-  jwks: z.any().optional(),
-  software_id: z.string().optional(),
-  software_version: z.string().optional(),
-}).passthrough();
-
-/**
- * Client information response schema according to RFC 7591
- */
-export const OAuthClientInformationSchema = z.object({
-  client_id: z.string(),
-  client_secret: z.string().optional(),
-  client_id_issued_at: z.number().optional(),
-  client_secret_expires_at: z.number().optional(),
-}).passthrough();
-
-export type OAuthMetadata = z.infer<typeof OAuthMetadataSchema>;
-export type OAuthTokens = z.infer<typeof OAuthTokensSchema>;
-
-export type OAuthClientMetadata = z.infer<typeof OAuthClientMetadataSchema>;
-export type OAuthClientInformation = z.infer<typeof OAuthClientInformationSchema>;
+import type { OAuthClientMetadata, OAuthClientInformation, OAuthTokens, OAuthMetadata, OAuthClientInformationFull } from "../shared/auth.js";
+import { OAuthClientInformationFullSchema, OAuthMetadataSchema, OAuthTokensSchema } from "../shared/auth.js";
 
 /**
  * Implements an end-to-end OAuth client to be used with one MCP server.
@@ -113,7 +36,7 @@ export interface OAuthClientProvider {
    * This method is not required to be implemented if client information is
    * statically known (e.g., pre-registered).
    */
-  saveClientInformation?(clientInformation: OAuthClientInformation): void | Promise<void>;
+  saveClientInformation?(clientInformation: OAuthClientInformationFull): void | Promise<void>;
 
   /**
    * Loads any existing OAuth tokens for the current session, or returns
@@ -175,12 +98,13 @@ export async function auth(
       throw new Error("OAuth client information must be saveable for dynamic registration");
     }
 
-    clientInformation = await registerClient(serverUrl, {
+    const fullInformation = await registerClient(serverUrl, {
       metadata,
       clientMetadata: provider.clientMetadata,
     });
 
-    await provider.saveClientInformation(clientInformation);
+    await provider.saveClientInformation(fullInformation);
+    clientInformation = fullInformation;
   }
 
   // Exchange authorization code for tokens
@@ -448,7 +372,7 @@ export async function registerClient(
     metadata?: OAuthMetadata;
     clientMetadata: OAuthClientMetadata;
   },
-): Promise<OAuthClientInformation> {
+): Promise<OAuthClientInformationFull> {
   let registrationUrl: URL;
 
   if (metadata) {
@@ -473,5 +397,5 @@ export async function registerClient(
     throw new Error(`Dynamic client registration failed: HTTP ${response.status}`);
   }
 
-  return OAuthClientInformationSchema.parse(await response.json());
+  return OAuthClientInformationFullSchema.parse(await response.json());
 }

src/client/auth.ts

@@ -2,7 +2,8 @@ import { createServer, type IncomingMessage, type Server } from "http";
 import { AddressInfo } from "net";
 import { JSONRPCMessage } from "../types.js";
 import { SSEClientTransport } from "./sse.js";
-import { OAuthClientProvider, OAuthTokens, UnauthorizedError } from "./auth.js";
+import { OAuthClientProvider, UnauthorizedError } from "./auth.js";
+import { OAuthTokens } from "../shared/auth.js";
 
 describe("SSEClientTransport", () => {
   let server: Server;

src/client/sse.test.ts

@@ -0,0 +1,20 @@
+import { OAuthClientInformationFull } from "../../shared/auth.js";
+
+/**
+ * Stores information about registered OAuth clients for this server.
+ */
+export interface OAuthRegisteredClientsStore {
+  /**
+   * Returns information about a registered client, based on its ID.
+   */
+  getClient(clientId: string): OAuthClientInformationFull | undefined | Promise<OAuthClientInformationFull | undefined>;
+
+  /**
+   * Registers a new client with the server. The client ID and secret will be automatically generated by the library. A modified version of the client information can be returned to reflect specific values enforced by the server.
+   * 
+   * NOTE: Implementations should NOT delete expired client secrets in-place. Auth middleware provided by this library will automatically check the `client_secret_expires_at` field and reject requests with expired secrets. Any custom logic for authenticating clients should check the `client_secret_expires_at` field as well.
+   * 
+   * If unimplemented, dynamic client registration is unsupported.
+   */
+  registerClient?(client: OAuthClientInformationFull): OAuthClientInformationFull | Promise<OAuthClientInformationFull>;
+}