import pkceChallenge from 'pkce-challenge';

import { LATEST_PROTOCOL_VERSION } from '../types.js';

import {

OAuthClientMetadata,

OAuthClientInformation,

OAuthClientInformationMixed,

OAuthTokens,

OAuthMetadata,

OAuthClientInformationFull,

OAuthProtectedResourceMetadata,

OAuthErrorResponseSchema,

AuthorizationServerMetadata,

OpenIdProviderDiscoveryMetadataSchema

} from '../shared/auth.js';

import {

OAuthClientInformationFullSchema,

OAuthMetadataSchema,

OAuthProtectedResourceMetadataSchema,

OAuthTokensSchema

} from '../shared/auth.js';

import { checkResourceAllowed, resourceUrlFromServerUrl } from '../shared/auth-utils.js';

import {

InvalidClientError,

InvalidClientMetadataError,

InvalidGrantError,

OAUTH_ERRORS,

OAuthError,

ServerError,

UnauthorizedClientError

} from '../server/auth/errors.js';

import { FetchLike, fetchWithinOrigin, unfollowedRedirect } from '../shared/transport.js';

/**

* Function type for adding client authentication to token requests.

*/

export type AddClientAuthentication = (

headers: Headers,

params: URLSearchParams,

url: string | URL,

metadata?: AuthorizationServerMetadata

) => void | Promise<void>;

/**

* Implements an end-to-end OAuth client to be used with one MCP server.

*

* This client relies upon a concept of an authorized "session," the exact

* meaning of which is application-defined. Tokens, authorization codes, and

* code verifiers should not cross different sessions.

*/

export interface OAuthClientProvider {

/**

* The URL to redirect the user agent to after authorization.

* Return undefined for non-interactive flows that don't require user interaction

* (e.g., client_credentials, jwt-bearer).

*/

get redirectUrl(): string | URL | undefined;

/**

* External URL the server should use to fetch client metadata document

*/

clientMetadataUrl?: string;

/**

* Metadata about this OAuth client.

*/

get clientMetadata(): OAuthClientMetadata;

/**

* Returns a OAuth2 state parameter.

*/

state?(): string | Promise<string>;

/**

* Loads information about this OAuth client, as registered already with the

* server, or returns `undefined` if the client is not registered with the

* server.

*

* A provider that returns pre-registered credentials should include `issuer`, the URL of

* the authorization server they were registered with; {@linkcode auth} then does not

* present them to any other.

*/

clientInformation(): OAuthClientInformationMixed | undefined | Promise<OAuthClientInformationMixed | undefined>;

/**

* If implemented, this permits the OAuth client to dynamically register with

* the server. Client information saved this way should later be read via

* `clientInformation()`.

*

* This method is not required to be implemented if client information is

* statically known (e.g., pre-registered).

*

* The object carries `issuer`, the authorization server it was obtained from. Store it

* unchanged so that {@linkcode auth} does not reuse the registration with a different one.

* Client information stored without `issuer` is passed here, with it, after its first successful use.

*/

saveClientInformation?(clientInformation: OAuthClientInformationMixed): void | Promise<void>;

/**

* Loads any existing OAuth tokens for the current session, or returns

* `undefined` if there are no saved tokens.

*/

tokens(): OAuthTokens | undefined | Promise<OAuthTokens | undefined>;

/**

* Stores new OAuth tokens for the current session, after a successful

* authorization.

*

* The object carries `issuer`, the authorization server that issued the tokens. Store it

* unchanged so that {@linkcode auth} does not present the refresh token to a different one.

*/

saveTokens(tokens: OAuthTokens): void | Promise<void>;

/**

* Invoked to redirect the user agent to the given URL to begin the authorization flow.

*/

redirectToAuthorization(authorizationUrl: URL): void | Promise<void>;

/**

* Saves a PKCE code verifier for the current session, before redirecting to

* the authorization flow.

*/

saveCodeVerifier(codeVerifier: string): void | Promise<void>;

/**

* Loads the PKCE code verifier for the current session, necessary to validate

* the authorization result.

*/

codeVerifier(): string | Promise<string>;

/**

* Adds custom client authentication to OAuth token requests.

*

* This optional method allows implementations to customize how client credentials

* are included in token exchange and refresh requests. When provided, this method

* is called instead of the default authentication logic, giving full control over

* the authentication mechanism.

*

* Common use cases include:

* - Supporting authentication methods beyond the standard OAuth 2.0 methods

* - Adding custom headers for proprietary authentication schemes

* - Implementing client assertion-based authentication (e.g., JWT bearer tokens)

*

* @param headers - The request headers (can be modified to add authentication)

* @param params - The request body parameters (can be modified to add credentials)

* @param url - The token endpoint URL being called

* @param metadata - Optional OAuth metadata for the server, which may include supported authentication methods

*/

addClientAuthentication?: AddClientAuthentication;

/**

* If defined, overrides the selection and validation of the

* RFC 8707 Resource Indicator. If left undefined, default

* validation behavior will be used.

*

* Implementations must verify the returned resource matches the MCP server.

*/

validateResourceURL?(serverUrl: string | URL, resource?: string): Promise<URL | undefined>;

/**

* If implemented, provides a way for the client to invalidate (e.g. delete) the specified

* credentials, in the case where the server has indicated that they are no longer valid.

* This avoids requiring the user to intervene manually.

*/

invalidateCredentials?(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): void | Promise<void>;

/**

* Prepares grant-specific parameters for a token request.

*

* This optional method allows providers to customize the token request based on

* the grant type they support. When implemented, it returns the grant type and

* any grant-specific parameters needed for the token exchange.

*

* If not implemented, the default behavior depends on the flow:

* - For authorization code flow: uses code, code_verifier, and redirect_uri

* - For client_credentials: detected via grant_types in clientMetadata

*

* @param scope - Optional scope to request

* @returns Grant type and parameters, or undefined to use default behavior

*

* @example

* // For client_credentials grant:

* prepareTokenRequest(scope) {

* return {

* grantType: 'client_credentials',

* params: scope ? { scope } : {}

* };

* }

*

* @example

* // For authorization_code grant (default behavior):

* async prepareTokenRequest() {

* return {

* grantType: 'authorization_code',

* params: {

* code: this.authorizationCode,

* code_verifier: await this.codeVerifier(),

* redirect_uri: String(this.redirectUrl)

* }

* };

* }

*/

prepareTokenRequest?(scope?: string): URLSearchParams | Promise<URLSearchParams | undefined> | undefined;

/**

* Saves the OAuth discovery state after RFC 9728 and authorization server metadata

* discovery. Providers can persist this state to avoid redundant discovery requests

* on subsequent {@linkcode auth} calls.

*

* This state can also be provided out-of-band (e.g., from a previous session or

* external configuration) to bootstrap the OAuth flow without discovery.

*

* Called by {@linkcode auth} after successful discovery.

*/

saveDiscoveryState?(state: OAuthDiscoveryState): void | Promise<void>;

/**

* Returns previously saved discovery state, or `undefined` if none is cached.

*

* When available, {@linkcode auth} restores the discovery state (authorization server

* URL, resource metadata, etc.) instead of performing RFC 9728 discovery, reducing

* latency on subsequent calls.

*

* Providers should clear cached discovery state on repeated authentication failures

* (via {@linkcode invalidateCredentials} with scope `'discovery'` or `'all'`) to allow

* re-discovery in case the authorization server has changed.

*/

discoveryState?(): OAuthDiscoveryState | undefined | Promise<OAuthDiscoveryState | undefined>;

}

/**

* Discovery state that can be persisted across sessions by an {@linkcode OAuthClientProvider}.

*

* Contains the results of RFC 9728 protected resource metadata discovery and

* authorization server metadata discovery. Persisting this state avoids

* redundant discovery HTTP requests on subsequent {@linkcode auth} calls.

*/

// TODO: Consider adding `authorizationServerMetadataUrl` to capture the exact well-known URL

// at which authorization server metadata was discovered. This would require

// `discoverAuthorizationServerMetadata()` to return the successful discovery URL.

export interface OAuthDiscoveryState extends OAuthServerInfo {

/** The URL at which the protected resource metadata was found, if available. */

resourceMetadataUrl?: string;

}

export type AuthResult = 'AUTHORIZED' | 'REDIRECT';

export class UnauthorizedError extends Error {

constructor(message?: string) {

super(message ?? 'Unauthorized');

}

}

type ClientAuthMethod = 'client_secret_basic' | 'client_secret_post' | 'none';

function isClientAuthMethod(method: string): method is ClientAuthMethod {

return ['client_secret_basic', 'client_secret_post', 'none'].includes(method);

}

const AUTHORIZATION_CODE_RESPONSE_TYPE = 'code';

const AUTHORIZATION_CODE_CHALLENGE_METHOD = 'S256';

/**

* Determines the best client authentication method to use based on server support and client configuration.

*

* Priority order (highest to lowest):

* 1. client_secret_basic (if client secret is available)

* 2. client_secret_post (if client secret is available)

* 3. none (for public clients)

*

* @param clientInformation - OAuth client information containing credentials

* @param supportedMethods - Authentication methods supported by the authorization server

* @returns The selected authentication method

*/

export function selectClientAuthMethod(clientInformation: OAuthClientInformationMixed, supportedMethods: string[]): ClientAuthMethod {

const hasClientSecret = clientInformation.client_secret !== undefined;

// Prefer the method returned by the server during client registration, if valid.

// When server metadata is present we also require the method to be listed as supported;

// when supportedMethods is empty (metadata omitted the field) the DCR hint stands alone.

if (

'token_endpoint_auth_method' in clientInformation &&

clientInformation.token_endpoint_auth_method &&

isClientAuthMethod(clientInformation.token_endpoint_auth_method) &&

(supportedMethods.length === 0 || supportedMethods.includes(clientInformation.token_endpoint_auth_method))

) {

return clientInformation.token_endpoint_auth_method;

}

// If server metadata omits token_endpoint_auth_methods_supported, RFC 8414 §2 says the

// default is client_secret_basic. RFC 6749 §2.3.1 also requires servers to support HTTP

// Basic authentication for clients with a secret, making it the safest default.

if (supportedMethods.length === 0) {

return hasClientSecret ? 'client_secret_basic' : 'none';

}

// Try methods in priority order (most secure first)

if (hasClientSecret && supportedMethods.includes('client_secret_basic')) {

return 'client_secret_basic';

}

if (hasClientSecret && supportedMethods.includes('client_secret_post')) {

return 'client_secret_post';

}

if (supportedMethods.includes('none')) {

return 'none';

}

// Fallback: use what we have

return hasClientSecret ? 'client_secret_post' : 'none';

}

/**

* Applies client authentication to the request based on the specified method.

*

* Implements OAuth 2.1 client authentication methods:

* - client_secret_basic: HTTP Basic authentication (RFC 6749 Section 2.3.1)

* - client_secret_post: Credentials in request body (RFC 6749 Section 2.3.1)

* - none: Public client authentication (RFC 6749 Section 2.1)

*

* @param method - The authentication method to use

* @param clientInformation - OAuth client information containing credentials

* @param headers - HTTP headers object to modify

* @param params - URL search parameters to modify

* @throws {Error} When required credentials are missing

*/

function applyClientAuthentication(

method: ClientAuthMethod,

clientInformation: OAuthClientInformation,

headers: Headers,

params: URLSearchParams

): void {

const { client_id, client_secret } = clientInformation;

switch (method) {

case 'client_secret_basic':

applyBasicAuth(client_id, client_secret, headers);

return;

case 'client_secret_post':

applyPostAuth(client_id, client_secret, params);

return;

case 'none':

applyPublicAuth(client_id, params);

return;

default:

throw new Error(`Unsupported client authentication method: ${method}`);

}

}

/**

* Applies HTTP Basic authentication (RFC 6749 Section 2.3.1)

*/

function applyBasicAuth(clientId: string, clientSecret: string | undefined, headers: Headers): void {

if (!clientSecret) {

throw new Error('client_secret_basic authentication requires a client_secret');

}

const credentials = btoa(`${clientId}:${clientSecret}`);

headers.set('Authorization', `Basic ${credentials}`);

}

/**

* Applies POST body authentication (RFC 6749 Section 2.3.1)

*/

function applyPostAuth(clientId: string, clientSecret: string | undefined, params: URLSearchParams): void {

params.set('client_id', clientId);

if (clientSecret) {

params.set('client_secret', clientSecret);

}

}

/**

* Applies public client authentication (RFC 6749 Section 2.1)

*/

function applyPublicAuth(clientId: string, params: URLSearchParams): void {

params.set('client_id', clientId);

}

/**

* Parses an OAuth error response from a string or Response object.

*

* If the input is a standard OAuth2.0 error response, it will be parsed according to the spec

* and an instance of the appropriate OAuthError subclass will be returned.

* If parsing fails, it falls back to a generic ServerError that includes

* the response status (if available) and original content.

*

* @param input - A Response object or string containing the error response

* @returns A Promise that resolves to an OAuthError instance

*/

export async function parseErrorResponse(input: Response | string): Promise<OAuthError> {

const statusCode = input instanceof Response ? input.status : undefined;

const body = input instanceof Response ? await input.text() : input;

try {

const result = OAuthErrorResponseSchema.parse(JSON.parse(body));

const { error, error_description, error_uri } = result;

const errorClass = OAUTH_ERRORS[error] || ServerError;

return new errorClass(error_description || '', error_uri);

} catch (error) {

// Not a valid OAuth error response, but try to inform the user of the raw data anyway

const redirect = input instanceof Response ? unfollowedRedirect(input, input.url) : undefined;

const errorMessage = `${statusCode ? `HTTP ${statusCode}: ` : ''}${redirect ?? `Invalid OAuth error response: ${error}. Raw body: ${body}`}`;

return new ServerError(errorMessage);

}

}

/**

* Compares two authorization server identifiers, tolerating a single trailing `/`

* difference (`String(new URL(...))` is slash-suffixed, advertised values often are not).

*/

function issuersMatch(a: string, b: string): boolean {

let [x, y] = [a, b];

try {

// Two URLs are compared as parsed, so the spelling of scheme, host or default port does not matter.

[x, y] = [new URL(a).href, new URL(b).href];

} catch {

// Not two URLs: compared as written.

}

return x === y || (x.endsWith('/') && x.slice(0, -1) === y) || (y.endsWith('/') && y.slice(0, -1) === x);

}

/**

* {@linkcode auth} stamps everything it passes to `saveClientInformation` / `saveTokens` with

* `issuer`, the authorization server URL used for discovery. This returns `stored` unless its

* stamp names a different authorization server, in which case the caller behaves as if nothing

* were stored. A value without a stamp (saved by an earlier version) is returned as-is, and

* is stamped once this authorization server has accepted it.

*/

function discardIfIssuerMismatch<T extends { issuer?: string }>(stored: T | null | undefined, issuer: string): T | undefined {

// `null`: a `JSON.parse(storage.getItem(...))`-style getter with nothing stored.

if (!stored) return undefined;

// A stamp that is not a string (raw storage) counts as no stamp.

if (typeof stored.issuer !== 'string') return stored.issuer == null ? stored : { ...stored, issuer: undefined };

return issuersMatch(stored.issuer, issuer) ? stored : undefined;

}

// `issuer` is added by the client when it stores a value; authorization server responses are parsed without it.

const TokenResponseSchema = OAuthTokensSchema.omit({ issuer: true });

const RegistrationResponseSchema = OAuthClientInformationFullSchema.omit({ issuer: true });

function boundElsewhereError(stored: { issuer?: string }, issuer: string): Error {

return new Error(

`OAuth client information is bound to authorization server ${stored.issuer} and is not presented to ${issuer}. ` +

'Clear the stored client information, or correct `expectedIssuer`, if the authorization server has moved.'

);

}

/**

* Orchestrates the full auth flow with a server.

*

* This can be used as a single entry point for all authorization functionality,

* instead of linking together the other lower-level functions in this module.

*/

export async function auth(

provider: OAuthClientProvider,

options: {

serverUrl: string | URL;

authorizationCode?: string;

scope?: string;

resourceMetadataUrl?: URL;

fetchFn?: FetchLike;

}

): Promise<AuthResult> {

try {

return await authInternal(provider, options);

} catch (error) {

// Handle recoverable error types by invalidating credentials and retrying

if (error instanceof InvalidClientError || error instanceof UnauthorizedClientError) {

await provider.invalidateCredentials?.('all');

return await authInternal(provider, options);

} else if (error instanceof InvalidGrantError) {

await provider.invalidateCredentials?.('tokens');

return await authInternal(provider, options);

}

// Throw otherwise

throw error;

}

}

async function authInternal(

provider: OAuthClientProvider,

{

serverUrl,

authorizationCode,

scope,

resourceMetadataUrl,

fetchFn

}: {

serverUrl: string | URL;

authorizationCode?: string;

scope?: string;

resourceMetadataUrl?: URL;

fetchFn?: FetchLike;

}

): Promise<AuthResult> {

// Check if the provider has cached discovery state to skip discovery

const cachedState = await provider.discoveryState?.();

let resourceMetadata: OAuthProtectedResourceMetadata | undefined;

let authorizationServerUrl: string | URL;

let metadata: AuthorizationServerMetadata | undefined;

// If resourceMetadataUrl is not provided, try to load it from cached state

// This handles browser redirects where the URL was saved before navigation

let effectiveResourceMetadataUrl = resourceMetadataUrl;

if (!effectiveResourceMetadataUrl && cachedState?.resourceMetadataUrl) {

effectiveResourceMetadataUrl = new URL(cachedState.resourceMetadataUrl);

}

if (cachedState?.authorizationServerUrl) {

// Restore discovery state from cache

authorizationServerUrl = cachedState.authorizationServerUrl;

resourceMetadata = cachedState.resourceMetadata;

metadata =

cachedState.authorizationServerMetadata ?? (await discoverAuthorizationServerMetadata(authorizationServerUrl, { fetchFn }));

// If resource metadata wasn't cached, try to fetch it for selectResourceURL

if (!resourceMetadata) {

try {

resourceMetadata = await discoverOAuthProtectedResourceMetadata(

serverUrl,

{ resourceMetadataUrl: effectiveResourceMetadataUrl },

fetchFn

);

} catch {

// RFC 9728 not available — selectResourceURL will handle undefined

}

}

// Re-save if we enriched the cached state with missing metadata

if (metadata !== cachedState.authorizationServerMetadata || resourceMetadata !== cachedState.resourceMetadata) {

await provider.saveDiscoveryState?.({

authorizationServerUrl: String(authorizationServerUrl),

resourceMetadataUrl: effectiveResourceMetadataUrl?.toString(),

resourceMetadata,

authorizationServerMetadata: metadata

});

}

} else {

// Full discovery via RFC 9728

const serverInfo = await discoverOAuthServerInfo(serverUrl, { resourceMetadataUrl: effectiveResourceMetadataUrl, fetchFn });

authorizationServerUrl = serverInfo.authorizationServerUrl;

metadata = serverInfo.authorizationServerMetadata;

resourceMetadata = serverInfo.resourceMetadata;

// Persist discovery state for future use

// TODO: resourceMetadataUrl is only populated when explicitly provided via options

// or loaded from cached state. The URL derived internally by

// discoverOAuthProtectedResourceMetadata() is not captured back here.

await provider.saveDiscoveryState?.({

authorizationServerUrl: String(authorizationServerUrl),

resourceMetadataUrl: effectiveResourceMetadataUrl?.toString(),

resourceMetadata,

authorizationServerMetadata: metadata

});

}

// Binding key for stored credentials: the authorization server URL that discovery used

// (advertised by the resource server, restored from discoveryState(), or the legacy

// resource-origin fallback). `metadata.issuer` is deliberately not used: this version does

// not check that the metadata document echoes the URL it was fetched from.

const issuer = String(authorizationServerUrl);

// Send the metadata's resource indicator verbatim: `selectResourceURL` returns a parsed

// `URL`, and `URL.href` appends "/" to a pathless indicator such as `https://example.com`,

// which exact-match authorization servers reject (#1968). A URL returned by the

// provider's own `validateResourceURL` is used as returned.

const selectedResource = await selectResourceURL(serverUrl, provider, resourceMetadata);

const resource: string | URL | undefined =

selectedResource && resourceMetadata && !provider.validateResourceURL ? resourceMetadata.resource : selectedResource;

// Apply scope selection strategy (SEP-835):

// 1. WWW-Authenticate scope (passed via `scope` param)

// 2. PRM scopes_supported

// 3. Client metadata scope (user-configured fallback)

// The resolved scope is used consistently for both DCR and the authorization request.

const resolvedScope = scope || resourceMetadata?.scopes_supported?.join(' ') || provider.clientMetadata.scope;

// Handle client registration if needed. Client information stamped for a different

// authorization server reads back as `undefined`, so the flow re-registers exactly as if

// nothing were stored.

const storedClientInformation = await Promise.resolve(provider.clientInformation());

let clientInformation = discardIfIssuerMismatch(storedClientInformation, issuer);

const canRegisterAgain = provider.saveClientInformation !== undefined && !!provider.redirectUrl;

if (storedClientInformation && !clientInformation && !canRegisterAgain) {

// Pre-registered credentials, or a non-interactive client running on configured

// credentials: neither can be re-created by registering with this authorization server.

throw boundElsewhereError(storedClientInformation, issuer);

}

// Saved by an earlier version: bound to the first authorization server that accepts it.

const unstampedClientInformation = clientInformation?.issuer == null ? clientInformation : undefined;

const bindClientInformation = async () => {

try {

if (unstampedClientInformation) await provider.saveClientInformation?.({ ...unstampedClientInformation, issuer });

} catch {

// A provider that only expects this call after a registration keeps working, unbound.

}

};

if (!clientInformation) {

if (authorizationCode !== undefined) {

throw new Error('Existing OAuth client information is required when exchanging an authorization code');

}

const supportsUrlBasedClientId = metadata?.client_id_metadata_document_supported === true;

const clientMetadataUrl = provider.clientMetadataUrl;

if (clientMetadataUrl && !isHttpsUrl(clientMetadataUrl)) {

throw new InvalidClientMetadataError(

`clientMetadataUrl must be a valid HTTPS URL with a non-root pathname, got: ${clientMetadataUrl}`

);

}

const shouldUseUrlBasedClientId = supportsUrlBasedClientId && clientMetadataUrl;

if (shouldUseUrlBasedClientId) {

// SEP-991: URL-based Client IDs

clientInformation = { client_id: clientMetadataUrl, issuer };

await provider.saveClientInformation?.(clientInformation);

} else {

// Fallback to dynamic registration

if (!provider.saveClientInformation) {

throw new Error('OAuth client information must be saveable for dynamic registration');

}

const fullInformation = await registerClient(authorizationServerUrl, {

metadata,

clientMetadata: provider.clientMetadata,

scope: resolvedScope,

fetchFn

});

clientInformation = { ...fullInformation, issuer };

await provider.saveClientInformation(clientInformation);

}

}

// Non-interactive flows (e.g., client_credentials, jwt-bearer) don't need a redirect URL

const nonInteractiveFlow = !provider.redirectUrl;

// Exchange authorization code for tokens, or fetch tokens directly for non-interactive flows

if (authorizationCode !== undefined || nonInteractiveFlow) {

const tokens = await fetchToken(provider, authorizationServerUrl, {

metadata,

resource,

authorizationCode,

fetchFn

});

await bindClientInformation();

await provider.saveTokens({ ...tokens, issuer });

return 'AUTHORIZED';

}

// A refresh token stamped for a different authorization server reads back as `undefined`,

// so it is never posted to this one's token endpoint.

const tokens = discardIfIssuerMismatch(await provider.tokens(), issuer);

if (tokens?.refresh_token && tokens.issuer == null) {

// eslint-disable-next-line no-console

console.warn(

"[mcp-sdk] stored OAuth tokens have no 'issuer' property (saved by an earlier version, or by a provider that " +

'does not keep it) and are used as-is; make sure your OAuthClientProvider stores what saveTokens() and ' +

'saveClientInformation() receive unchanged.'

);

}

// Handle token refresh or new authorization

if (tokens?.refresh_token) {

try {

// Attempt to refresh the token

const newTokens = await refreshAuthorization(authorizationServerUrl, {

metadata,

clientInformation,

refreshToken: tokens.refresh_token,

resource,

addClientAuthentication: provider.addClientAuthentication,

fetchFn

});

await bindClientInformation();

await provider.saveTokens({ ...newTokens, issuer });

return 'AUTHORIZED';

} catch (error) {

// If this is a ServerError, or an unknown type, log it out and try to continue. Otherwise, escalate so we can fix things and retry.

if (!(error instanceof OAuthError) || error instanceof ServerError) {

// Could not refresh OAuth tokens

} else {

// Refresh failed for another reason, re-throw

throw error;

}

}

}

const state = provider.state ? await provider.state() : undefined;

// Start new authorization flow

const { authorizationUrl, codeVerifier } = await startAuthorization(authorizationServerUrl, {

metadata,

clientInformation,

state,

redirectUrl: provider.redirectUrl,

scope: resolvedScope,

resource

});

await provider.saveCodeVerifier(codeVerifier);

await provider.redirectToAuthorization(authorizationUrl);

return 'REDIRECT';

}

/**

* SEP-991: URL-based Client IDs

* Validate that the client_id is a valid URL with https scheme

*/

export function isHttpsUrl(value?: string): boolean {

if (!value) return false;

try {

const url = new URL(value);

return url.protocol === 'https:' && url.pathname !== '/';

} catch {

return false;

}

}

/**

* Selects the RFC 8707 resource indicator for an MCP server: the provider's

* {@linkcode OAuthClientProvider.validateResourceURL | validateResourceURL} result when

* implemented, otherwise the protected resource metadata's `resource` (checked against the

* server URL with `checkResourceAllowed`), or `undefined` when there is no metadata.

*

* The result is a parsed `URL`, so a pathless indicator such as `https://example.com` has

* the `href` `https://example.com/`. {@linkcode auth} therefore sends the metadata string

* verbatim instead of this URL's `href` (#1968); callers that emit the `resource`

* parameter themselves should do the same.

*/

export async function selectResourceURL(

serverUrl: string | URL,

provider: OAuthClientProvider,

resourceMetadata?: OAuthProtectedResourceMetadata

): Promise<URL | undefined> {

const defaultResource = resourceUrlFromServerUrl(serverUrl);

// If provider has custom validation, delegate to it

if (provider.validateResourceURL) {

return await provider.validateResourceURL(defaultResource, resourceMetadata?.resource);

}

// Only include resource parameter when Protected Resource Metadata is present

if (!resourceMetadata) {

return undefined;

}

// Validate that the metadata's resource is compatible with our request

if (!checkResourceAllowed({ requestedResource: defaultResource, configuredResource: resourceMetadata.resource })) {

throw new Error(`Protected resource ${resourceMetadata.resource} does not match expected ${defaultResource} (or origin)`);

}

// Prefer the resource from metadata since it's what the server is telling us to request

return new URL(resourceMetadata.resource);

}

/**

* Extract resource_metadata, scope, and error from WWW-Authenticate header.

*/

export function extractWWWAuthenticateParams(res: Response): { resourceMetadataUrl?: URL; scope?: string; error?: string } {

const authenticateHeader = res.headers.get('WWW-Authenticate');

if (!authenticateHeader) {

return {};

}

const [type, scheme] = authenticateHeader.split(' ');

if (type.toLowerCase() !== 'bearer' || !scheme) {

return {};

}

const resourceMetadataMatch = extractFieldFromWwwAuth(res, 'resource_metadata') || undefined;

let resourceMetadataUrl: URL | undefined;

if (resourceMetadataMatch) {

try {

resourceMetadataUrl = new URL(resourceMetadataMatch);

} catch {

// Ignore invalid URL

}

}

const scope = extractFieldFromWwwAuth(res, 'scope') || undefined;

const error = extractFieldFromWwwAuth(res, 'error') || undefined;

return {

resourceMetadataUrl,

scope,

error

};

}

/**

* Extracts a specific field's value from the WWW-Authenticate header string.

*

* @param response The HTTP response object containing the headers.

* @param fieldName The name of the field to extract (e.g., "realm", "nonce").

* @returns The field value

*/

function extractFieldFromWwwAuth(response: Response, fieldName: string): string | null {

const wwwAuthHeader = response.headers.get('WWW-Authenticate');

if (!wwwAuthHeader) {

return null;

}

const pattern = new RegExp(`${fieldName}=(?:"([^"]+)"|([^\\s,]+))`);

const match = wwwAuthHeader.match(pattern);

if (match) {

// Pattern matches: field_name="value" or field_name=value (unquoted)

return match[1] || match[2];

}

return null;

}

/**

* Extract resource_metadata from response header.

* @deprecated Use `extractWWWAuthenticateParams` instead.

*/

export function extractResourceMetadataUrl(res: Response): URL | undefined {

const authenticateHeader = res.headers.get('WWW-Authenticate');

if (!authenticateHeader) {

return undefined;

}

const [type, scheme] = authenticateHeader.split(' ');

if (type.toLowerCase() !== 'bearer' || !scheme) {

return undefined;

}

const regex = /resource_metadata="([^"]*)"/;

const match = regex.exec(authenticateHeader);

if (!match) {

return undefined;

}

try {

return new URL(match[1]);

} catch {

return undefined;

}

}

/**

* Looks up RFC 9728 OAuth 2.0 Protected Resource Metadata.

*

* If the server returns a 404 for the well-known endpoint, this function will

* return `undefined`. Any other errors will be thrown as exceptions.

*/

export async function discoverOAuthProtectedResourceMetadata(

serverUrl: string | URL,

opts?: { protocolVersion?: string; resourceMetadataUrl?: string | URL },

fetchFn: FetchLike = fetch

): Promise<OAuthProtectedResourceMetadata> {

const response = await discoverMetadataWithFallback(serverUrl, 'oauth-protected-resource', fetchFn, {

protocolVersion: opts?.protocolVersion,

metadataUrl: opts?.resourceMetadataUrl

});

if (!response || response.status === 404) {

await response?.body?.cancel();

throw new Error(`Resource server does not implement OAuth 2.0 Protected Resource Metadata.`);

}

if (!response.ok) {

await response.body?.cancel();

throw new Error(`HTTP ${response.status} trying to load well-known OAuth protected resource metadata.`);

}

return OAuthProtectedResourceMetadataSchema.parse(await response.json());

}

/**

* Helper function to handle fetch with CORS retry logic

*/

async function fetchWithCorsRetry(url: URL, headers?: Record<string, string>, fetchFn: FetchLike = fetch): Promise<Response | undefined> {

try {

return await fetchWithinOrigin(fetchFn)(url, { headers });

} catch (error) {

if (error instanceof TypeError) {

if (headers) {

// CORS errors come back as TypeError, retry without headers

return fetchWithCorsRetry(url, undefined, fetchFn);

} else {

// We're getting CORS errors on retry too, return undefined

return undefined;

}

}

throw error;

}

}

/**

* Constructs the well-known path for auth-related metadata discovery

*/

function buildWellKnownPath(

wellKnownPrefix: 'oauth-authorization-server' | 'oauth-protected-resource' | 'openid-configuration',

pathname: string = '',

options: { prependPathname?: boolean } = {}

): string {

// Strip trailing slash from pathname to avoid double slashes

if (pathname.endsWith('/')) {

pathname = pathname.slice(0, -1);

}

return options.prependPathname ? `${pathname}/.well-known/${wellKnownPrefix}` : `/.well-known/${wellKnownPrefix}${pathname}`;

}

/**

* Tries to discover OAuth metadata at a specific URL

*/

async function tryMetadataDiscovery(url: URL, protocolVersion: string, fetchFn: FetchLike = fetch): Promise<Response | undefined> {

const headers = {

'MCP-Protocol-Version': protocolVersion

};

return await fetchWithCorsRetry(url, headers, fetchFn);

}

/**

* Determines if fallback to root discovery should be attempted

*/

function shouldAttemptFallback(response: Response | undefined, pathname: string): boolean {

return !response || (!response.ok && response.status < 500 && pathname !== '/');

}

/**

* Generic function for discovering OAuth metadata with fallback support

*/

async function discoverMetadataWithFallback(

serverUrl: string | URL,

wellKnownType: 'oauth-authorization-server' | 'oauth-protected-resource',

fetchFn: FetchLike,

opts?: { protocolVersion?: string; metadataUrl?: string | URL; metadataServerUrl?: string | URL }

): Promise<Response | undefined> {

const issuer = new URL(serverUrl);

const protocolVersion = opts?.protocolVersion ?? LATEST_PROTOCOL_VERSION;

let url: URL;

if (opts?.metadataUrl) {

url = new URL(opts.metadataUrl);

} else {

// Try path-aware discovery first

const wellKnownPath = buildWellKnownPath(wellKnownType, issuer.pathname);

url = new URL(wellKnownPath, opts?.metadataServerUrl ?? issuer);

url.search = issuer.search;

}

let response = await tryMetadataDiscovery(url, protocolVersion, fetchFn);

// If path-aware discovery fails with 404 and we're not already at root, try fallback to root discovery

if (!opts?.metadataUrl && shouldAttemptFallback(response, issuer.pathname)) {

const rootUrl = new URL(`/.well-known/${wellKnownType}`, issuer);

response = await tryMetadataDiscovery(rootUrl, protocolVersion, fetchFn);

}

return response;

}

/**

* Looks up RFC 8414 OAuth 2.0 Authorization Server Metadata.

*

* If the server returns a 404 for the well-known endpoint, this function will

* return `undefined`. Any other errors will be thrown as exceptions.

*

* @deprecated This function is deprecated in favor of `discoverAuthorizationServerMetadata`.

*/

export async function discoverOAuthMetadata(

issuer: string | URL,

{

authorizationServerUrl,

protocolVersion

}: {

authorizationServerUrl?: string | URL;

protocolVersion?: string;

} = {},

fetchFn: FetchLike = fetch

): Promise<OAuthMetadata | undefined> {

if (typeof issuer === 'string') {

issuer = new URL(issuer);

}

if (!authorizationServerUrl) {

authorizationServerUrl = issuer;

}

if (typeof authorizationServerUrl === 'string') {

authorizationServerUrl = new URL(authorizationServerUrl);

}

protocolVersion ??= LATEST_PROTOCOL_VERSION;

const response = await discoverMetadataWithFallback(authorizationServerUrl, 'oauth-authorization-server', fetchFn, {

protocolVersion,

metadataServerUrl: authorizationServerUrl

});

if (!response || response.status === 404) {

await response?.body?.cancel();

return undefined;

}