mcp-server-framework 1.0.0

package/build/server/auth/types.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Auth Types
+ *
+ * Core type definitions for the framework's authentication and authorization system.
+ * Provides the {@link AuthProvider} union type, {@link TokenVerifier} interface,
+ * and {@link AuthOptions} configuration.
+ *
+ * The SDK provides {@link OAuthServerProvider} for full OAuth flows and
+ * {@link OAuthTokenVerifier} for token-only verification. This module wraps
+ * these into a unified {@link AuthProvider} type for framework use.
+ *
+ * @module server/auth/types
+ */
+import type { OAuthServerProvider } from "@modelcontextprotocol/sdk/server/auth/provider.js";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import type { RequestHandler } from "express";
+export type { OAuthServerProvider, AuthInfo };
+/**
+ * Minimal interface for custom token verification.
+ *
+ * Implement this to integrate non-OAuth auth (API keys, JWTs, custom tokens)
+ * into the framework's auth pipeline. Structurally compatible with the SDK's
+ * `OAuthTokenVerifier`.
+ *
+ * @example
+ * ```typescript
+ * const apiKeyVerifier: TokenVerifier = {
+ *   verifyAccessToken: async (token) => {
+ *     const user = await db.users.findByApiKey(token);
+ *     if (!user) throw new Error('Invalid API key');
+ *     return { token, clientId: user.id, scopes: user.permissions };
+ *   },
+ * };
+ * ```
+ */
+export interface TokenVerifier {
+    /**
+     * Verify an access token and return auth information.
+     *
+     * @param token - The bearer token from the Authorization header
+     * @returns Auth info with clientId, scopes, and optional expiry
+     * @throws If the token is invalid, expired, or revoked
+     */
+    verifyAccessToken(token: string): Promise<AuthInfo>;
+}
+/**
+ * Authentication provider — either a full OAuth server or a token verifier.
+ *
+ * - **`OAuthServerProvider`**: Full OAuth 2.1 flow with authorization,
+ *   token exchange, client registration, and token revocation.
+ *   Enables `mcpAuthRouter()` for `/authorize`, `/token`, etc.
+ *
+ * - **`TokenVerifier`**: Token-only verification for custom auth.
+ *   Bearer tokens are validated but no OAuth endpoints are mounted.
+ *
+ * Use {@link isFullOAuthProvider} to discriminate at runtime.
+ */
+export type AuthProvider = OAuthServerProvider | TokenVerifier;
+/**
+ * Type guard to distinguish a full OAuth provider from a token verifier.
+ *
+ * Full OAuth providers have a `clientsStore` property (per SDK's
+ * `OAuthServerProvider` interface) — token verifiers do not.
+ *
+ * @param provider - The auth provider to check
+ * @returns `true` if the provider offers full OAuth capabilities
+ */
+export declare function isFullOAuthProvider(provider: AuthProvider): provider is OAuthServerProvider;
+/**
+ * Extra data attached to the auth context by the consumer.
+ *
+ * Populated via the `onAuthenticated` hook, this allows consumers to
+ * map OAuth `clientId`/`scopes` to their own user model, permissions,
+ * or any additional data needed in tool handlers.
+ *
+ * @example
+ * ```typescript
+ * auth: {
+ *   onAuthenticated: async (authInfo) => ({
+ *     userId: await resolveUser(authInfo.clientId),
+ *     role: 'admin',
+ *     permissions: ['read', 'write', 'deploy'],
+ *   }),
+ * }
+ * ```
+ */
+export type AuthenticatedExtra = Record<string, unknown>;
+/**
+ * Authentication configuration for the server.
+ *
+ * Passed via `ServerOptions.auth` or `McpServerBuilder.withAuthOptions()`.
+ *
+ * @example External OAuth provider (e.g. GitHub via SDK's ProxyOAuthServerProvider)
+ * ```typescript
+ * import { ProxyOAuthServerProvider } from '@modelcontextprotocol/sdk/server/auth/providers/proxyProvider.js';
+ *
+ * const github = new ProxyOAuthServerProvider({ endpoints, verifyAccessToken, getClient });
+ * createServer({
+ *   name: 'my-server',
+ *   version: '1.0.0',
+ *   transport: { mode: 'http' },
+ *   auth: {
+ *     provider: github,
+ *     issuerUrl: new URL('https://github.com'),
+ *     requiredScopes: ['read:user'],
+ *   },
+ * });
+ * ```
+ *
+ * @example Custom header auth (e.g. X-API-Key)
+ * ```typescript
+ * createServer({
+ *   name: 'my-server',
+ *   version: '1.0.0',
+ *   transport: { mode: 'http' },
+ *   auth: {
+ *     provider: myApiKeyVerifier,
+ *     headerName: 'X-API-Key',
+ *   },
+ * });
+ * ```
+ *
+ * @example Token verification only (Bearer)
+ * ```typescript
+ * createServer({
+ *   name: 'my-server',
+ *   version: '1.0.0',
+ *   transport: { mode: 'http' },
+ *   auth: {
+ *     provider: myJwtVerifier,
+ *   },
+ * });
+ * ```
+ */
+export interface AuthOptions {
+    /** Authentication provider (full OAuth or token verifier) */
+    readonly provider: AuthProvider;
+    /**
+     * Global required scopes for the `/mcp` endpoint.
+     *
+     * All requests to `/mcp` must have tokens with these scopes.
+     * Per-capability scopes can be set via `requiredScopes` on tool, resource, and prompt definitions.
+     */
+    readonly requiredScopes?: string[];
+    /**
+     * When `true`, capability list handlers (`tools/list`, `resources/list`, `prompts/list`)
+     * filter out entries whose `requiredScopes` are not satisfied by the requesting user's token.
+     *
+     * **Default: `false`** (spec-konform — all capabilities are listed regardless of scopes).
+     * Enforcement always happens at execution time (403), independent of this setting.
+     *
+     * Enable this for UIs that should only show actionable items to users.
+     */
+    readonly scopeFilterCapabilities?: boolean;
+    /**
+     * OAuth issuer URL (Authorization Server identifier).
+     *
+     * Required for full OAuth providers. Used as the `issuer` in
+     * OAuth Authorization Server Metadata (RFC 8414).
+     * Must use HTTPS scheme and have no query or fragment components.
+     */
+    readonly issuerUrl?: URL;
+    /**
+     * Protected Resource Metadata URL (RFC 9728).
+     *
+     * Included in `WWW-Authenticate` headers for 401 responses,
+     * allowing clients to discover the authorization server.
+     */
+    readonly resourceMetadataUrl?: string;
+    /**
+     * Custom header name for token extraction.
+     *
+     * When set, the framework extracts the token from this header instead of
+     * the standard `Authorization: Bearer <token>` header. Only allowed with
+     * {@link TokenVerifier} providers (not with full OAuth providers).
+     *
+     * @example `'X-API-Key'` — extracts the value of the `X-API-Key` header
+     */
+    readonly headerName?: string;
+    /**
+     * Hook called after successful token verification.
+     *
+     * Use this to map OAuth `clientId`/`scopes` to your own user model.
+     * The returned data is available in tool handlers via `context.auth.extra`.
+     *
+     * @param authInfo - Verified auth info from the token
+     * @returns Extra data for `context.auth.extra`, or `undefined`
+     */
+    readonly onAuthenticated?: (authInfo: AuthInfo) => Promise<AuthenticatedExtra | undefined>;
+    /**
+     * Express handler for the OAuth callback route (`GET /callback`).
+     *
+     * Required for OAuth providers that use server-side callbacks (e.g.,
+     * GitHub, Google) where the upstream provider redirects back to the
+     * MCP server rather than directly to the MCP client.
+     *
+     * The handler receives the authorization code from the upstream provider
+     * and redirects the user to the MCP client's redirect_uri.
+     *
+     * Only effective when a full OAuth provider is configured.
+     */
+    readonly callbackHandler?: RequestHandler;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/server/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/server/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mDAAmD,CAAC;AAC7F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gDAAgD,CAAC;AAC/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C,YAAY,EAAE,mBAAmB,EAAE,QAAQ,EAAE,CAAC;AAM9C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACrD;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GAAG,mBAAmB,GAAG,aAAa,CAAC;AAM/D;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,QAAQ,IAAI,mBAAmB,CAE3F;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAMzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,WAAW,WAAW;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAEhC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAE3C;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,GAAG,CAAC;IAEzB;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAEtC;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAE3F;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,cAAc,CAAC;CAC3C"}

package/build/server/auth/types.js

@@ -0,0 +1,29 @@
+/**
+ * Auth Types
+ *
+ * Core type definitions for the framework's authentication and authorization system.
+ * Provides the {@link AuthProvider} union type, {@link TokenVerifier} interface,
+ * and {@link AuthOptions} configuration.
+ *
+ * The SDK provides {@link OAuthServerProvider} for full OAuth flows and
+ * {@link OAuthTokenVerifier} for token-only verification. This module wraps
+ * these into a unified {@link AuthProvider} type for framework use.
+ *
+ * @module server/auth/types
+ */
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard to distinguish a full OAuth provider from a token verifier.
+ *
+ * Full OAuth providers have a `clientsStore` property (per SDK's
+ * `OAuthServerProvider` interface) — token verifiers do not.
+ *
+ * @param provider - The auth provider to check
+ * @returns `true` if the provider offers full OAuth capabilities
+ */
+export function isFullOAuthProvider(provider) {
+    return "clientsStore" in provider;
+}
+//# sourceMappingURL=types.js.map

package/build/server/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/server/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA4DH,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAsB;IACxD,OAAO,cAAc,IAAI,QAAQ,CAAC;AACpC,CAAC"}

package/build/server/auth/upstream-provider.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Upstream OAuth Provider Factory
+ *
+ * Creates a generic {@link OAuthServerProvider} that proxies OAuth flows
+ * to any upstream authorization server using the **server-side callback pattern**.
+ *
+ * This pattern is needed because MCP clients (Inspector, VS Code, Claude Desktop)
+ * each have their own callback URL, but upstream providers (GitHub, Google, etc.)
+ * validate `redirect_uri` against the registered callback. By routing all callbacks
+ * through the MCP server, we solve this mismatch transparently.
+ *
+ * Flow:
+ *   Client → MCP Server /authorize → Upstream /authorize
+ *     (redirect_uri = MCP Server /callback)
+ *   Upstream → MCP Server /callback?code=X&state=UP
+ *   MCP Server → Client callback?code=X&state=DOWN
+ *   Client → MCP Server /token (code=X)
+ *   MCP Server → Upstream token endpoint → returns token
+ *
+ * @example
+ * ```typescript
+ * import { createUpstreamOAuthProvider } from 'mcp-server-framework';
+ *
+ * const { provider, callbackHandler } = createUpstreamOAuthProvider({
+ *   endpoints: {
+ *     authorizationUrl: 'https://github.com/login/oauth/authorize',
+ *     tokenUrl: 'https://github.com/login/oauth/access_token',
+ *     userinfoUrl: 'https://api.github.com/user',
+ *   },
+ *   clientId: process.env.GITHUB_CLIENT_ID!,
+ *   clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ *   serverUrl: 'http://localhost:8000',
+ *   upstreamScopes: ['read:user'],
+ *   tokenRequestContentType: 'json',
+ *   mapUserInfo: async (token, data) => ({
+ *     token,
+ *     clientId: data.login as string,
+ *     scopes: ['read', 'write'],
+ *     expiresAt: Math.floor(Date.now() / 1000) + 3600,
+ *   }),
+ * });
+ *
+ * createServer({
+ *   auth: { provider, callbackHandler, issuerUrl: new URL('http://localhost:8000') },
+ * });
+ * ```
+ *
+ * @module server/auth/upstream-provider
+ */
+import type { RequestHandler } from "express";
+import type { OAuthServerProvider } from "@modelcontextprotocol/sdk/server/auth/provider.js";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+/**
+ * Upstream OAuth endpoint URLs.
+ */
+export interface UpstreamEndpoints {
+    /** Authorization endpoint (user is redirected here) */
+    readonly authorizationUrl: string;
+    /** Token endpoint (code → access_token exchange) */
+    readonly tokenUrl: string;
+    /**
+     * UserInfo endpoint for token verification.
+     * The response is passed to {@link UpstreamOAuthOptions.mapUserInfo}.
+     * Required unless a custom `verifyAccessToken` is provided.
+     */
+    readonly userinfoUrl?: string | undefined;
+    /** Token revocation endpoint (optional) */
+    readonly revocationUrl?: string | undefined;
+}
+/**
+ * Options for {@link createUpstreamOAuthProvider}.
+ */
+export interface UpstreamOAuthOptions {
+    /** Upstream OAuth endpoint URLs */
+    readonly endpoints: UpstreamEndpoints;
+    /** Client ID registered with the upstream OAuth provider */
+    readonly clientId: string;
+    /** Client secret registered with the upstream OAuth provider */
+    readonly clientSecret: string;
+    /** MCP server base URL (e.g. `http://localhost:8000`). Used as `redirect_uri` target. */
+    readonly serverUrl: string;
+    /** Scopes to request from the upstream provider (e.g. `['read:user']`, `['openid', 'profile']`) */
+    readonly upstreamScopes: readonly string[];
+    /**
+     * Map the upstream userinfo response to MCP {@link AuthInfo}.
+     *
+     * Called by `verifyAccessToken()` after fetching the userinfo endpoint.
+     * The `data` parameter contains the parsed JSON response from the userinfo URL.
+     *
+     * @param token - The access token being verified
+     * @param data - Parsed JSON response from the userinfo endpoint
+     * @returns Auth info for the MCP session
+     */
+    readonly mapUserInfo: (token: string, data: Record<string, unknown>) => Promise<AuthInfo>;
+    /**
+     * Content type for the token exchange request.
+     * - `'form'` — `application/x-www-form-urlencoded` (OAuth 2.1 standard, default)
+     * - `'json'` — `application/json` (used by GitHub)
+     *
+     * @default 'form'
+     */
+    readonly tokenRequestContentType?: "form" | "json";
+    /**
+     * Extra query parameters appended to the upstream authorization URL.
+     * Useful for non-standard providers that need additional parameters
+     * like `response_type`, `access_type`, etc.
+     *
+     * Standard parameters (`client_id`, `redirect_uri`, `state`, `scope`)
+     * are set automatically and should NOT be included here.
+     */
+    readonly upstreamAuthorizeParams?: Readonly<Record<string, string>>;
+    /**
+     * Whether the upstream provider supports refresh tokens.
+     * When `true`, `exchangeRefreshToken()` proxies to the token endpoint.
+     *
+     * @default false
+     */
+    readonly refreshTokenSupport?: boolean;
+    /**
+     * TTL for pending authorization state (upstream state → client info mapping).
+     * @default 600000 (10 minutes)
+     */
+    readonly pendingAuthTtlMs?: number;
+    /**
+     * TTL for code context (authorization code → redirect_uri mapping).
+     * @default 300000 (5 minutes)
+     */
+    readonly codeContextTtlMs?: number;
+}
+/**
+ * Result of {@link createUpstreamOAuthProvider}.
+ *
+ * Pass `provider` and `callbackHandler` to {@link AuthOptions}:
+ * ```typescript
+ * createServer({
+ *   auth: { provider, callbackHandler, issuerUrl: new URL(serverUrl) },
+ * });
+ * ```
+ */
+export interface UpstreamOAuthProviderResult {
+    /** OAuthServerProvider for the framework's auth pipeline */
+    readonly provider: OAuthServerProvider;
+    /** Express handler for `GET /callback` — receives upstream redirects */
+    readonly callbackHandler: RequestHandler;
+    /** Dispose cleanup resources (eviction timers). Called during server shutdown. */
+    readonly dispose?: () => void;
+}
+/**
+ * Creates an {@link OAuthServerProvider} that proxies OAuth flows to an
+ * upstream authorization server using server-side callbacks.
+ *
+ * This is the generic extraction of the server-side callback pattern —
+ * all provider-specific logic is encapsulated in the options (endpoints,
+ * scopes, `mapUserInfo`). The boilerplate (client store, state mapping,
+ * callback handler, token exchange, TTL management) is handled here.
+ *
+ * @param options - Upstream OAuth configuration
+ * @returns Provider and callback handler, ready for {@link AuthOptions}
+ */
+export declare function createUpstreamOAuthProvider(options: UpstreamOAuthOptions): UpstreamOAuthProviderResult;
+//# sourceMappingURL=upstream-provider.d.ts.map

package/build/server/auth/upstream-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream-provider.d.ts","sourceRoot":"","sources":["../../../src/server/auth/upstream-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAGH,OAAO,KAAK,EAAqB,cAAc,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mDAAmD,CAAC;AAC7F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gDAAgD,CAAC;AAsC/E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE1C,2CAA2C;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAEtC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,yFAAyF;IACzF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,mGAAmG;IACnG,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAE3C;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE1F;;;;;;OAMG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEnD;;;;;;;OAOG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAEpE;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,2BAA2B;IAC1C,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IAEvC,wEAAwE;IACxE,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC;IAEzC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CAC/B;AAwBD;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,oBAAoB,GAAG,2BAA2B,CAgXtG"}