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>;
+}