Server implementation of MCP auth

package.json

@@ -47,7 +47,9 @@
   },
   "dependencies": {
     "content-type": "^1.0.5",
+    "cors": "^2.8.5",
     "eventsource": "^3.0.2",
+    "express": "^5.0.1",
     "pkce-challenge": "^4.1.0",
     "raw-body": "^3.0.0",
     "zod": "^3.23.8",
@@ -56,14 +58,14 @@
   "devDependencies": {
     "@eslint/js": "^9.8.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/ws": "^8.5.12",
     "eslint": "^9.8.0",
-    "express": "^4.19.2",
     "jest": "^29.7.0",
     "ts-jest": "^29.2.4",
     "tsx": "^4.16.5",
@@ -74,4 +76,4 @@
   "resolutions": {
     "strip-ansi": "6.0.1"
   }
-}
+}

src/client/auth.test.ts

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

src/client/auth.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/sse.test.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/server/auth/clients.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 must ensure that client secrets, if present, are expired in accordance with the `client_secret_expires_at` field.
+   * 
+   * If unimplemented, dynamic client registration is unsupported.
+   */
+  registerClient?(client: OAuthClientInformationFull): OAuthClientInformationFull | Promise<OAuthClientInformationFull>;
+}

src/server/auth/crypto.ts

@@ -0,0 +1,5 @@
+import crypto from "node:crypto";
+
+export function generateToken(): string {
+  return crypto.randomBytes(32).toString("hex");
+}

src/server/auth/handlers/authorize.ts

@@ -0,0 +1,93 @@
+import { RequestHandler } from "express";
+import { z } from "zod";
+import { isValidUrl } from "../validation.js";
+import { OAuthServerProvider } from "../provider.js";
+
+export type AuthorizationHandlerOptions = {
+  provider: OAuthServerProvider;
+};
+
+// Parameters that must be validated in order to issue redirects.
+const ClientAuthorizationParamsSchema = z.object({
+  client_id: z.string(),
+  redirect_uri: z.string().optional().refine((value) => value === undefined || isValidUrl(value), { message: "redirect_uri must be a valid URL" }),
+});
+
+// Parameters that must be validated for a successful authorization request. Failure can be reported to the redirect URI.
+const RequestAuthorizationParamsSchema = z.object({
+  response_type: z.literal("code"),
+  code_challenge: z.string(),
+  code_challenge_method: z.literal("S256"),
+  scope: z.string().optional(),
+  state: z.string().optional(),
+});
+
+export function authorizationHandler({ provider }: AuthorizationHandlerOptions): RequestHandler {
+  return async (req, res) => {
+    if (req.method !== "GET" && req.method !== "POST") {
+      res.status(405).end("Method Not Allowed");
+      return;
+    }
+
+    let client_id, redirect_uri;
+    try {
+      ({ client_id, redirect_uri } = ClientAuthorizationParamsSchema.parse(req.query));
+    } catch (error) {
+      res.status(400).end(`Bad Request: ${error}`);
+      return;
+    }
+
+    const client = await provider.clientsStore.getClient(client_id);
+    if (!client) {
+      res.status(400).end("Bad Request: invalid client_id");
+      return;
+    }
+
+    if (redirect_uri !== undefined) {
+      if (!client.redirect_uris.includes(redirect_uri)) {
+        res.status(400).end("Bad Request: unregistered redirect_uri");
+        return;
+      }
+    } else if (client.redirect_uris.length === 1) {
+      redirect_uri = client.redirect_uris[0];
+    } else {
+      res.status(400).end("Bad Request: missing redirect_uri");
+      return;
+    }
+
+    let params;
+    try {
+      params = RequestAuthorizationParamsSchema.parse(req.query);
+    } catch (error) {
+      const errorUrl = new URL(redirect_uri);
+      errorUrl.searchParams.set("error", "invalid_request");
+      errorUrl.searchParams.set("error_description", String(error));
+      res.redirect(302, errorUrl.href);
+      return;
+    }
+
+    let requestedScopes: string[] = [];
+    if (params.scope !== undefined && client.scope !== undefined) {
+      requestedScopes = params.scope.split(" ");
+      const allowedScopes = new Set(client.scope.split(" "));
+
+      // If any requested scope is not in the client's registered scopes, error out
+      for (const scope of requestedScopes) {
+        if (!allowedScopes.has(scope)) {
+          const errorUrl = new URL(redirect_uri);
+          errorUrl.searchParams.set("error", "invalid_scope");
+          errorUrl.searchParams.set("error_description", `Client was not registered with scope ${scope}`);
+          res.redirect(302, errorUrl.href);
+          return;
+        }
+      }
+    }
+
+    await provider.authorize(client, {
+      state: params.state,
+      scopes: requestedScopes,
+      redirectUri: redirect_uri,
+      codeChallenge: params.code_challenge,
+    }, res);
+  };
+}

src/server/auth/handlers/register.ts

@@ -0,0 +1,66 @@
+import express, { RequestHandler } from "express";
+import { OAuthClientInformationFull, OAuthClientMetadataSchema, OAuthClientRegistrationError } from "../../../shared/auth.js";
+import crypto from 'node:crypto';
+import cors from 'cors';
+import { OAuthRegisteredClientsStore } from "../clients.js";
+
+export type ClientRegistrationHandlerOptions = {
+  /**
+   * A store used to save information about dynamically registered OAuth clients.
+   */
+  clientsStore: OAuthRegisteredClientsStore;
+
+  /**
+   * The number of seconds after which to expire issued client secrets, or 0 to prevent expiration of client secrets (not recommended).
+   * 
+   * If not set, defaults to 30 days.
+   */
+  clientSecretExpirySeconds?: number;
+};
+
+const DEFAULT_CLIENT_SECRET_EXPIRY_SECONDS = 30 * 24 * 60 * 60; // 30 days
+
+export function clientRegistrationHandler({ clientsStore, clientSecretExpirySeconds = DEFAULT_CLIENT_SECRET_EXPIRY_SECONDS }: ClientRegistrationHandlerOptions): RequestHandler {
+  if (!clientsStore.registerClient) {
+    throw new Error("Client registration store does not support registering clients");
+  }
+
+  // Nested router so we can configure middleware and restrict HTTP method
+  const router = express.Router();
+  router.use(express.json());
+
+  // Configure CORS to allow any origin, to make accessible to web-based MCP clients
+  router.use(cors());
+
+  router.post("/", async (req, res) => {
+    let clientMetadata;
+    try {
+      clientMetadata = OAuthClientMetadataSchema.parse(req.body);
+    } catch (error) {
+      res.status(400).json({
+        error: "invalid_client_metadata",
+        error_description: String(error),
+      });
+      return;
+    }
+
+    const clientId = crypto.randomUUID();
+    const clientSecret = clientMetadata.token_endpoint_auth_method !== 'none'
+      ? crypto.randomBytes(32).toString('hex')
+      : undefined;
+    const clientIdIssuedAt = Math.floor(Date.now() / 1000);
+
+    let clientInfo: OAuthClientInformationFull = {
+      ...clientMetadata,
+      client_id: clientId,
+      client_secret: clientSecret,
+      client_id_issued_at: clientIdIssuedAt,
+      client_secret_expires_at: clientSecretExpirySeconds > 0 ? clientIdIssuedAt + clientSecretExpirySeconds : 0
+    };
+
+    clientInfo = await clientsStore.registerClient!(clientInfo);
+    res.status(201).json(clientInfo);
+  });
+
+  return router;
+}