oh-my-pi/packages/coding-agent/src/mcp/oauth-flow.ts

/**
 * Generic OAuth flow for MCP servers.
 *
 * Allows users to authenticate with any OAuth-compatible MCP server
 * by providing authorization URL, token URL, and client credentials.
 */

import type { OAuthCallbackFlowOptions } from "@oh-my-pi/pi-ai/oauth/callback-server";
import { OAuthCallbackFlow } from "@oh-my-pi/pi-ai/oauth/callback-server";
import type { OAuthController, OAuthCredentials } from "@oh-my-pi/pi-ai/oauth/types";
import type { FetchImpl } from "@oh-my-pi/pi-ai/types";
import { getActiveProfile } from "@oh-my-pi/pi-utils/dirs";
import type { OAuthCredential } from "../session/auth-storage";

/** Credential-id prefix for OMP-managed MCP OAuth credentials keyed by profile and server URL. */
const MCP_OAUTH_URL_CREDENTIAL_PREFIX = "mcp_oauth:";

/** Credential-id prefix for profile-scoped MCP OAuth credentials (`mcp_oauth:profile:<profile>:<serverUrl>`). */
const MCP_OAUTH_PROFILE_CREDENTIAL_PREFIX = `${MCP_OAUTH_URL_CREDENTIAL_PREFIX}profile:`;

/**
 * Deterministic credential id for an MCP server URL scoped to an OMP profile.
 *
 * Local profile stores are already separate, but auth-broker storage shares one
 * provider namespace across profiles. Including the profile in the provider key
 * keeps a shared project `mcp.json` definition from making profile B overwrite
 * or read profile A's OAuth row for the same server URL. The URL is used
 * verbatim (query string included) because it can carry tenant selectors such
 * as `?project_ref=`.
 */
export function mcpOAuthCredentialId(serverUrl: string, profile: string | undefined = getActiveProfile()): string {
	return `${MCP_OAUTH_PROFILE_CREDENTIAL_PREFIX}${profile ?? "default"}:${serverUrl}`;
}

/** Whether a credential id was minted by OMP's MCP OAuth flows (either era). */
export function isManagedMCPOAuthCredentialId(credentialId: string | undefined): credentialId is string {
	return (
		!!credentialId &&
		(credentialId.startsWith("mcp_oauth_") || credentialId.startsWith(MCP_OAUTH_URL_CREDENTIAL_PREFIX))
	);
}

/**
 * Profile segment of a profile-scoped `mcp_oauth:profile:<profile>:<serverUrl>`
 * credential id, or `undefined` for legacy non-profile-scoped managed ids
 * (`mcp_oauth:<url>`, `mcp_oauth_<rand>`). The server URL itself contains `:`
 * and `/`, so only the segment between the prefix and the FIRST subsequent `:`
 * is the profile; everything after it is the URL.
 */
export function mcpOAuthCredentialProfile(credentialId: string): string | undefined {
	if (!credentialId.startsWith(MCP_OAUTH_PROFILE_CREDENTIAL_PREFIX)) return undefined;
	const separator = credentialId.indexOf(":", MCP_OAUTH_PROFILE_CREDENTIAL_PREFIX.length);
	return separator === -1 ? undefined : credentialId.slice(MCP_OAUTH_PROFILE_CREDENTIAL_PREFIX.length, separator);
}

/**
 * Stored MCP OAuth credential. Refresh material is embedded so token refresh
 * works without any `auth` block persisted in (possibly shared) config files.
 */
export interface MCPStoredOAuthCredential extends OAuthCredential {
	tokenUrl?: string;
	clientId?: string;
	clientSecret?: string;
	resource?: string;
	/**
	 * Authorization-server URL (the issuer the grant was minted against). Used
	 * to filter same-origin resource indicators on refresh: RFC 8414 lets the
	 * authorize and token endpoints sit on different origins, so refresh
	 * cannot infer the original auth-server origin from `tokenUrl` alone.
	 * Unset on legacy credentials minted before issue #3502's fix.
	 */
	authorizationUrl?: string;
}

const DEFAULT_PORT = 3000;
const CALLBACK_PATH = "/callback";

function hasOAuthScope(scopes: string | null | undefined, scope: string): boolean {
	return !!scopes && scopes.split(/\s+/).includes(scope);
}

/**
 * Trim a DCR failure body / thrown error message to a single, short line the
 * caller can splice into an error string. `undefined` when nothing salvageable
 * remains after stripping whitespace.
 */
function truncateDetail(raw: string | undefined): string | undefined {
	if (!raw) return undefined;
	const firstLine = raw.split(/\r?\n/, 1)[0]?.trim();
	if (!firstLine) return undefined;
	return firstLine.length > 200 ? `${firstLine.slice(0, 200)}…` : firstLine;
}

/**
 * Read the response body of a rejected DCR request as a short diagnostic
 * string. Never throws — the caller is already building an error and cannot
 * afford to trade the actual failure for a "read body" one.
 */
async function readRegistrationFailureDetail(response: Response): Promise<string | undefined> {
	try {
		return truncateDetail(await response.text());
	} catch {
		return undefined;
	}
}

function isLoopbackHostname(hostname: string): boolean {
	return hostname === "localhost" || hostname === "127.0.0.1";
}

function resolveRedirectUri(redirectUri: string | undefined): string | undefined {
	const configured = redirectUri;
	const trimmed = configured?.trim();
	if (!trimmed) return undefined;
	if (trimmed !== configured) {
		throw new Error("OAuth redirect URI must not include surrounding whitespace");
	}

	const parsed = new URL(configured);
	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
		throw new Error("OAuth redirect URI must use http or https");
	}
	return configured;
}

function parseRedirectUri(redirectUri: string | undefined): URL | undefined {
	return redirectUri ? new URL(redirectUri) : undefined;
}

function getUriPort(uri: URL): number {
	if (uri.port !== "") return Number(uri.port);
	return uri.protocol === "https:" ? 443 : 80;
}

function validateRedirectConfig(config: MCPOAuthConfig, redirectUri: string | undefined): void {
	const parsed = parseRedirectUri(redirectUri);
	if (parsed?.protocol !== "https:" || !isLoopbackHostname(parsed.hostname)) {
		return;
	}

	if (config.callbackPort === undefined) {
		throw new Error(
			"HTTPS loopback redirect URIs require oauth.callbackPort to point at the local HTTP callback listener behind your TLS terminator",
		);
	}

	if (config.callbackPort === getUriPort(parsed)) {
		throw new Error(
			"HTTPS loopback redirect URIs cannot reuse the same local port; terminate TLS separately and forward to oauth.callbackPort",
		);
	}
}

function resolveCallbackPort(callbackPort: number | undefined, redirectUri: string | undefined): number {
	if (callbackPort !== undefined) return callbackPort;

	const parsed = parseRedirectUri(redirectUri);
	if (parsed?.protocol !== "http:" || !isLoopbackHostname(parsed.hostname)) {
		return DEFAULT_PORT;
	}

	const port = getUriPort(parsed);
	return Number.isFinite(port) && port > 0 ? port : DEFAULT_PORT;
}

function resolveCallbackPath(callbackPath: string | undefined, redirectUri: string | undefined): string {
	const trimmed = callbackPath?.trim();
	if (trimmed) return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;

	const parsed = parseRedirectUri(redirectUri);
	if (parsed?.pathname) return parsed.pathname;
	return CALLBACK_PATH;
}

function resolveCallbackHostname(redirectUri: string | undefined): string | undefined {
	const parsed = parseRedirectUri(redirectUri);
	if (!parsed || !isLoopbackHostname(parsed.hostname)) return undefined;
	return parsed.hostname;
}

/**
 * Resolve the client_id MCPOAuthFlow would use without doing any I/O —
 * either the explicitly configured value or one embedded as a query parameter
 * in the authorization URL. Returns `undefined` when no client_id is known
 * statically, which is the trigger for dynamic client registration in
 * {@link MCPOAuthFlow.#tryRegisterClient}.
 */
function staticClientIdFromConfig(config: MCPOAuthConfig): string | undefined {
	const fromConfig = config.clientId?.trim();
	if (fromConfig) return fromConfig;
	try {
		return new URL(config.authorizationUrl).searchParams.get("client_id") ?? undefined;
	} catch {
		return undefined;
	}
}

function resolveCallbackOptions(config: MCPOAuthConfig): OAuthCallbackFlowOptions {
	const redirectUri = resolveRedirectUri(config.redirectUri);
	validateRedirectConfig(config, redirectUri);
	// When a client_id is already pinned (config-supplied or embedded in the
	// authorization URL), it was registered against a specific redirect URI.
	// Silently advertising a different port at the authorize endpoint would
	// be rejected by providers like Atlassian (HTTP 500 in the browser, local
	// flow hangs until the 5-minute timeout), so fail fast instead.
	//
	// When no client_id is pinned, MCPOAuthFlow will attempt dynamic client
	// registration on demand with whichever loopback URI we actually bound —
	// the provider issues a client_id tied to *that* URI, so the random-port
	// fallback remains safe for first-install DCR flows whose preferred port
	// happens to be occupied.
	const allowPortFallback = staticClientIdFromConfig(config) === undefined;
	return {
		preferredPort: resolveCallbackPort(config.callbackPort, redirectUri),
		callbackPath: resolveCallbackPath(config.callbackPath, redirectUri),
		callbackHostname: resolveCallbackHostname(redirectUri),
		redirectUri,
		allowPortFallback,
	};
}

function resolveResourceUri(resource: string | undefined): string | undefined {
	const trimmed = resource?.trim();
	if (!trimmed) return undefined;
	if (trimmed !== resource) {
		throw new Error("OAuth resource URI must not include surrounding whitespace");
	}

	const parsed = new URL(trimmed);
	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
		throw new Error("OAuth resource URI must use http or https");
	}
	if (parsed.hash) {
		throw new Error("OAuth resource URI must not include a fragment");
	}
	return trimmed;
}

interface ResourceIndicatorFilterOptions {
	/** Strip any resource URL on the same origin as the authorization server. */
	stripSameOriginResource?: boolean;
}

/**
 * Drop a redundant fallback resource indicator relative to {@link serverUrl}.
 *
 * Provider-advertised resource indicators are authoritative even when they are
 * origin-only (`https://gateway.example.com`) or path-scoped same-origin
 * (`https://gateway.example.com/my-service/mcp`): servers can use either form
 * as the audience they require for the grant.
 *
 * Plane is stricter for OMP-synthesized fallback resources (e.g. using the
 * configured server URL `https://mcp.plane.so/http/mcp` as `resource`), so
 * fallback callers opt into `stripSameOriginResource`. Provider-advertised
 * `oauth.resource` values and authorization-URL `?resource=` values keep the
 * preserving default.
 */
function filterResourceIndicator(
	resource: string | undefined,
	serverUrl: string,
	options: ResourceIndicatorFilterOptions = {},
): string | undefined {
	if (!resource) return undefined;
	try {
		const origin = new URL(serverUrl).origin;
		const parsedResource = new URL(resource);
		if (parsedResource.origin !== origin) return resource;
		if (options.stripSameOriginResource) return undefined;
	} catch {
		// Malformed serverUrl will fail elsewhere; fall through.
	}
	return resource;
}

export interface MCPOAuthConfig {
	/** Authorization endpoint URL */
	authorizationUrl: string;
	/** Token endpoint URL */
	tokenUrl: string;
	/** Dynamic client registration endpoint advertised by the authorization server. */
	registrationUrl?: string;
	/** Client ID (optional when already embedded in authorization URL) */
	clientId?: string;
	/** Client secret (optional for PKCE flows) */
	clientSecret?: string;
	/** OAuth scopes (space-separated) */
	scopes?: string;
	/**
	 * `prompt` parameter for the authorization request. By default the parameter
	 * is omitted, matching the reference MCP SDK, except for `offline_access`
	 * requests where OIDC Core requires `prompt=consent` to issue refresh-token
	 * access. Set to `""` to omit the parameter entirely.
	 */
	prompt?: string;
	/** Exact redirect URI to advertise to the provider */
	redirectUri?: string;
	/** Custom callback port (default: 3000) */
	callbackPort?: number;
	/** Custom callback path (default: /callback or redirectUri pathname) */
	callbackPath?: string;
	/** MCP resource URI for RFC 8707 resource indicators */
	resource?: string;
	/**
	 * True when `resource` was synthesized from the server URL fallback rather
	 * than advertised by OAuth/protected-resource metadata. Fallback resources
	 * are stripped when same-origin with the authorization server; advertised
	 * path-scoped resources are preserved.
	 */
	stripSameOriginResource?: boolean;
	/** Fetch implementation for token exchange and discovery requests. */
	fetch?: FetchImpl;
}

/**
 * Generic OAuth flow for MCP servers.
 * Supports standard OAuth 2.0 authorization code flow with PKCE.
 */
export class MCPOAuthFlow extends OAuthCallbackFlow {
	#resolvedClientId?: string;
	#registeredClientSecret?: string;
	#codeVerifier?: string;
	#fetch: FetchImpl;
	#resource?: string;
	/**
	 * Details of a rejected dynamic client-registration attempt. Populated by
	 * {@link #tryRegisterClient} when the provider advertises a registration
	 * endpoint but returns a non-2xx / throws (e.g. Figma's DCR endpoint 403s
	 * every request because only catalog-approved clients may connect). Reused
	 * by {@link #missingClientIdError} to explain why the fallback probe now
	 * requires a manually configured `oauth.clientId`, replacing the opaque
	 * "OAuth provider requires client_id" message.
	 */
	#registrationFailure?: {
		endpoint: string;
		/** HTTP status returned by the endpoint; `0` when the request threw. */
		status: number;
		/** First line of the response body (or thrown error message), trimmed. */
		detail?: string;
	};

	constructor(
		private config: MCPOAuthConfig,
		ctrl: OAuthController,
	) {
		super(ctrl, resolveCallbackOptions(config));
		this.#resolvedClientId = this.#resolveClientId(config);
		this.#fetch = config.fetch ?? ctrl.fetch ?? fetch;
		this.#resource = this.#filterResourceIndicator(
			resolveResourceUri(config.resource ?? this.#resourceFromAuthorizationUrl(config.authorizationUrl)),
		);
	}

	/**
	 * Client id used during the authorization request. Returns the value supplied
	 * via {@link MCPOAuthConfig.clientId} or, when the server required dynamic
	 * client registration, the id issued during registration. `undefined` until
	 * {@link generateAuthUrl} (or {@link login}) has run for a server that needs
	 * a client id.
	 */
	get resolvedClientId(): string | undefined {
		return this.#resolvedClientId;
	}

	/**
	 * Client secret issued by dynamic client registration, if any. Always
	 * `undefined` for PKCE-only/public clients and when the caller supplies the
	 * client id via config.
	 */
	get registeredClientSecret(): string | undefined {
		return this.#registeredClientSecret;
	}
	get resource(): string | undefined {
		return this.#resource;
	}
	/**
	 * Authorization-server URL the flow used. Persist alongside the credential
	 * so refresh can filter same-origin resource indicators against the issuer's
	 * origin even when `tokenUrl` lives on a different origin (RFC 8414 permits
	 * the split).
	 */
	get authorizationUrl(): string {
		return this.config.authorizationUrl;
	}

	async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
		if (!this.#resolvedClientId) {
			await this.#tryRegisterClient(redirectUri);
			// `unapproved_client` explicitly establishes that registration cannot
			// produce the required client id. Other DCR failures stay on the
			// clientless probe path because they may be transient or caused by
			// unrelated registration metadata.
			if (!this.#resolvedClientId && this.#isDefinitiveRegistrationRejection()) {
				throw this.#missingClientIdError();
			}
		}

		const authUrl = new URL(this.config.authorizationUrl);
		const params = authUrl.searchParams;

		if (!params.get("response_type")) {
			params.set("response_type", "code");
		}
		const existingClientId = params.get("client_id")?.trim();
		if (this.#resolvedClientId && !existingClientId) {
			params.set("client_id", this.#resolvedClientId);
		}
		if (this.config.scopes && !params.get("scope")) {
			params.set("scope", this.config.scopes);
		}
		const prompt = this.config.prompt ?? (hasOAuthScope(params.get("scope"), "offline_access") ? "consent" : "");
		if (prompt && !params.get("prompt")) {
			params.set("prompt", prompt);
		}
		const existingResource = params.get("resource")?.trim();
		if (existingResource) {
			// A resource already embedded in the provider's authorization URL is
			// provider-authored, not OMP's server-URL fallback. Preserve same-host
			// values here even when the caller marked its separate
			// `config.resource` as fallback; gateway-hosted MCP servers can use
			// origin-only or path-scoped values as the token audience.
			const filtered = filterResourceIndicator(resolveResourceUri(existingResource), this.config.authorizationUrl);
			if (filtered) {
				this.#resource = filtered;
			} else {
				// Defensive path for future policy additions: when filtering says
				// "omit", drop it from both authorize and token requests.
				params.delete("resource");
				this.#resource = undefined;
			}
		} else if (this.#resource) {
			params.set("resource", this.#resource);
		}
		params.set("redirect_uri", redirectUri);
		params.set("state", state);

		// Add PKCE challenge (some providers require it)
		const codeVerifier = this.#generateCodeVerifier();
		const codeChallenge = await this.#generateCodeChallenge(codeVerifier);
		params.set("code_challenge", codeChallenge);
		params.set("code_challenge_method", "S256");

		// Store code verifier for token exchange
		this.#codeVerifier = codeVerifier;

		if (!params.get("client_id")) {
			await this.#assertClientIdNotRequired(authUrl.toString());
		}

		return { url: authUrl.toString() };
	}

	async exchangeToken(code: string, _state: string, redirectUri: string): Promise<OAuthCredentials> {
		const params = new URLSearchParams({
			grant_type: "authorization_code",
			code,
			redirect_uri: redirectUri,
		});
		if (this.#resolvedClientId) {
			params.set("client_id", this.#resolvedClientId);
		}

		// Add code verifier for PKCE
		if (this.#codeVerifier) {
			params.set("code_verifier", this.#codeVerifier);
		}
		this.#codeVerifier = undefined;

		// Add client secret if provided
		if (this.#resource) {
			params.set("resource", this.#resource);
		}
		const clientSecret = this.config.clientSecret ?? this.#registeredClientSecret;
		if (clientSecret) {
			params.set("client_secret", clientSecret);
		}

		const response = await this.#fetch(this.config.tokenUrl, {
			method: "POST",
			headers: {
				"Content-Type": "application/x-www-form-urlencoded",
			},
			body: params.toString(),
			signal: this.ctrl.signal,
		});

		if (!response.ok) {
			const errorText = await response.text();
			throw new Error(`Token exchange failed: ${response.status} ${errorText}`);
		}

		const data = (await response.json()) as {
			access_token?: string;
			refresh_token?: string;
			expires_in?: number;
			token_type?: string;
			error?: string;
			error_description?: string;
		};

		// Some providers (e.g. the Slack Web API) signal failure with HTTP 200 and
		// an `{ ok: false, error }` body. Accepting such a response would store an
		// empty access token and only surface `invalid_token` on a later request.
		if (typeof data.access_token !== "string" || data.access_token.length === 0) {
			const providerError = data.error_description ?? data.error;
			throw new Error(`Token exchange returned no access token${providerError ? `: ${providerError}` : ""}`);
		}

		// Calculate expiry timestamp
		const expiresIn = data.expires_in ?? 3600; // Default to 1 hour
		const expires = Date.now() + expiresIn * 1000;

		return {
			access: data.access_token,
			refresh: data.refresh_token ?? "",
			expires,
		};
	}

	/**
	 * Generate PKCE code verifier (random string).
	 */
	#generateCodeVerifier(): string {
		const bytes = new Uint8Array(32);
		crypto.getRandomValues(bytes);
		return this.#base64UrlEncode(bytes);
	}

	/**
	 * Generate PKCE code challenge from verifier.
	 */
	async #generateCodeChallenge(verifier: string): Promise<string> {
		const encoder = new TextEncoder();
		const data = encoder.encode(verifier);
		const hash = await crypto.subtle.digest("SHA-256", data);
		return this.#base64UrlEncode(new Uint8Array(hash));
	}

	/**
	 * Base64 URL encode (without padding).
	 */
	#base64UrlEncode(bytes: Uint8Array): string {
		const base64 = btoa(String.fromCharCode(...bytes));
		return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
	}

	#resolveClientId(config: MCPOAuthConfig): string | undefined {
		return staticClientIdFromConfig(config);
	}
	#resourceFromAuthorizationUrl(authorizationUrl: string): string | undefined {
		try {
			return new URL(authorizationUrl).searchParams.get("resource") ?? undefined;
		} catch {
			return undefined;
		}
	}

	/**
	 * Drop redundant resource indicators for this authorization server.
	 * Provider-advertised path-scoped values are preserved; fallback server-URL
	 * values opt into same-origin stripping via `stripSameOriginResource`.
	 */
	#filterResourceIndicator(resource: string | undefined): string | undefined {
		return filterResourceIndicator(resource, this.config.authorizationUrl, {
			stripSameOriginResource: this.config.stripSameOriginResource,
		});
	}

	/**
	 * Try OAuth dynamic client registration when provider requires a client_id.
	 *
	 * Records rejection details on {@link #registrationFailure} so that when
	 * DCR is intentionally closed (Figma's `mcp:connect` endpoint returns 403 to
	 * every unlisted client — see https://developers.figma.com/docs/figma-mcp-server/,
	 * "Only clients listed in the Figma MCP Catalog can connect"), the fallback
	 * probe surfaces a message that names the endpoint and status instead of
	 * the historical opaque "OAuth provider requires client_id".
	 *
	 * Includes {@link MCPOAuthConfig.scopes} as RFC 7591 `scope` when set so
	 * providers that bind DCR clients to registered scopes only (e.g. Clerk)
	 * accept the later authorize request for the same scope set.
	 */
	async #tryRegisterClient(redirectUri: string): Promise<void> {
		const registrationEndpoint = this.config.registrationUrl ?? (await this.#resolveRegistrationEndpoint());
		if (!registrationEndpoint) return;

		try {
			const registrationBody: Record<string, unknown> = {
				client_name: "oh-my-pi",
				redirect_uris: [redirectUri],
				grant_types: ["authorization_code", "refresh_token"],
				response_types: ["code"],
				token_endpoint_auth_method: "none",
				application_type: "native",
			};
			const scope = this.config.scopes?.trim();
			if (scope) {
				registrationBody.scope = scope;
			}
			const response = await this.#fetch(registrationEndpoint, {
				method: "POST",
				headers: {
					"Content-Type": "application/json",
					Accept: "application/json",
				},
				signal: this.ctrl.signal,
				body: JSON.stringify(registrationBody),
			});

			if (!response.ok) {
				this.#registrationFailure = {
					endpoint: registrationEndpoint,
					status: response.status,
					detail: await readRegistrationFailureDetail(response),
				};
				return;
			}

			const data = (await response.json()) as {
				client_id?: string;
				client_secret?: string;
			};

			if (data.client_id && data.client_id.trim() !== "") {
				this.#resolvedClientId = data.client_id;
			}
			if (data.client_secret && data.client_secret.trim() !== "") {
				this.#registeredClientSecret = data.client_secret;
			}
		} catch (error) {
			// Distinguish real transport/parse failures from a benign no-DCR
			// response so #missingClientIdError can surface what went wrong.
			this.#registrationFailure = {
				endpoint: registrationEndpoint,
				status: 0,
				detail: error instanceof Error ? truncateDetail(error.message) : undefined,
			};
		}
	}

	async #resolveRegistrationEndpoint(): Promise<string | null> {
		const authorizationUrl = new URL(this.config.authorizationUrl);

		// origin-root well-known; most servers serve metadata here.
		const rootUrl = new URL("/.well-known/oauth-authorization-server", authorizationUrl.origin).toString();
		const endpoint = await this.#tryWellKnownForRegistration(rootUrl);
		if (endpoint) return endpoint;

		// path-prefixed well-known for gateways (e.g. https://gateway.example.com/my-service/).
		const normalizedPath = authorizationUrl.pathname.replace(/\/$/, "");
		const lastSlash = normalizedPath.lastIndexOf("/");
		// Bare-origin authorization URL — nothing further to try.
		if (lastSlash < 0) return null;

		// Single-segment paths are the gateway prefix itself; multi-segment paths
		// drop the trailing segment (typically a service endpoint).
		const prefixPath = lastSlash === 0 ? normalizedPath : normalizedPath.slice(0, lastSlash);
		const prefixedUrl = new URL(
			".well-known/oauth-authorization-server",
			`${authorizationUrl.origin}${prefixPath}/`,
		).toString();
		const prefixedEndpoint = await this.#tryWellKnownForRegistration(prefixedUrl);
		if (prefixedEndpoint) return prefixedEndpoint;

		// RFC 8414 §3.1 path-ful issuer form: /.well-known/oauth-authorization-server/<path>.
		const pathfulUrl = new URL(
			`/.well-known/oauth-authorization-server${normalizedPath}`,
			authorizationUrl.origin,
		).toString();
		return await this.#tryWellKnownForRegistration(pathfulUrl);
	}

	async #tryWellKnownForRegistration(wellKnownUrl: string): Promise<string | null> {
		try {
			const response = await this.#fetch(wellKnownUrl, {
				method: "GET",
				headers: { Accept: "application/json" },
				signal: this.ctrl.signal,
			});
			if (!response.ok) return null;
			const metadata = (await response.json()) as { registration_endpoint?: string };
			if (metadata.registration_endpoint && metadata.registration_endpoint.trim() !== "") {
				return metadata.registration_endpoint;
			}
		} catch {
			// Ignore fetch/parse failures.
		}
		return null;
	}

	async #assertClientIdNotRequired(authorizationUrl: string): Promise<void> {
		try {
			const response = await this.#fetch(authorizationUrl, {
				method: "GET",
				redirect: "manual",
				headers: { Accept: "text/plain,text/html,application/json" },
				signal: this.ctrl.signal,
			});
			if (response.status < 400) return;
			const body = await response.text();
			if (/client[_-]?id/i.test(body) && /(required|missing|invalid)/i.test(body)) {
				throw this.#missingClientIdError();
			}
		} catch (error) {
			if (error instanceof Error && /client[_-]?id/i.test(error.message)) {
				throw error;
			}
			// Ignore network/probe failures to avoid blocking flows that still work.
		}
	}

	/**
	 * Whether the provider explicitly rejected this client as unapproved.
	 *
	 * HTTP status alone is insufficient: payload errors such as
	 * `invalid_client_metadata` and `invalid_redirect_uri` do not establish that
	 * the authorization endpoint requires a client id. Keep those on the
	 * clientless probe path.
	 */
	#isDefinitiveRegistrationRejection(): boolean {
		const failure = this.#registrationFailure;
		return failure?.status === 403 && /\bunapproved_client\b/i.test(failure.detail ?? "");
	}

	/**
	 * Build the error thrown when the authorize probe confirms the provider
	 * demands a `client_id`. When dynamic client registration was attempted and
	 * rejected (e.g. Figma's 403 for unlisted clients), fold the endpoint + HTTP
	 * status into the message and point the user at the manual `oauth.clientId`
	 * workaround. Refs issue #4307.
	 */
	#missingClientIdError(): Error {
		const failure = this.#registrationFailure;
		const manualHint =
			"Configure `oauth.clientId` (and `oauth.clientSecret` if the flow needs one) on the MCP server entry in mcp.json.";
		if (!failure) {
			return new Error(
				`OAuth provider requires client_id, and no dynamic-client-registration endpoint was advertised. ${manualHint}`,
			);
		}
		const outcome =
			failure.status > 0
				? `HTTP ${failure.status}${failure.detail ? ` — ${failure.detail}` : ""}`
				: failure.detail
					? `network error — ${failure.detail}`
					: "network error";
		return new Error(
			`OAuth provider requires client_id, and dynamic client registration was rejected ` +
				`(POST ${failure.endpoint} → ${outcome}). The server likely restricts registration to pre-approved clients. ${manualHint}`,
		);
	}
}

/**
 * Options for {@link refreshMCPOAuthToken}. Carried via the trailing object
 * so positional callers keep working.
 */
export interface RefreshMCPOAuthTokenOptions {
	fetch?: FetchImpl;
	signal?: AbortSignal;
	/**
	 * Authorization-server URL the original grant was minted against. Used to
	 * filter same-origin resource indicators on refresh. Defaults to `tokenUrl`'s
	 * origin when omitted for legacy credentials.
	 */
	authorizationUrl?: string;
	/**
	 * True when the refresh `resource` was synthesized from the server URL
	 * fallback because the credential/auth material carried no resource.
	 * Preserved advertised resources leave this false/undefined.
	 */
	stripSameOriginResource?: boolean;
}

/**
 * Refresh an MCP OAuth token using the standard refresh_token grant.
 * Returns updated credentials; preserves the old refresh token if the server doesn't rotate it.
 */
export async function refreshMCPOAuthToken(
	tokenUrl: string,
	refreshToken: string,
	clientId?: string,
	clientSecret?: string,
	resourceOrOpts?: string | RefreshMCPOAuthTokenOptions,
	opts?: RefreshMCPOAuthTokenOptions,
): Promise<OAuthCredentials> {
	const optsFromTrailing = typeof resourceOrOpts === "string" ? opts : resourceOrOpts;
	const fetchImpl: FetchImpl = optsFromTrailing?.fetch ?? fetch;
	const resource = typeof resourceOrOpts === "string" ? resourceOrOpts : undefined;
	// Filter against the authorization-server origin when known (RFC 8414
	// permits authorize/token endpoints on separate origins). Fall back to
	// `tokenUrl` for legacy credentials minted before the issuer was persisted
	// — same-origin servers (the common case) still match correctly.
	const filterAnchor = optsFromTrailing?.authorizationUrl ?? tokenUrl;
	const params = new URLSearchParams({
		grant_type: "refresh_token",
		refresh_token: refreshToken,
	});
	if (clientId) params.set("client_id", clientId);
	// Drop redundant indicators so refresh stays consistent with the initial
	// grant; see {@link filterResourceIndicator} for context.
	const resolvedResource = filterResourceIndicator(resolveResourceUri(resource), filterAnchor, {
		stripSameOriginResource: optsFromTrailing?.stripSameOriginResource,
	});
	if (resolvedResource) params.set("resource", resolvedResource);
	if (clientSecret) params.set("client_secret", clientSecret);

	const response = await fetchImpl(tokenUrl, {
		method: "POST",
		headers: { "Content-Type": "application/x-www-form-urlencoded" },
		body: params.toString(),
		signal: optsFromTrailing?.signal,
	});

	if (!response.ok) {
		const text = await response.text();
		throw new Error(`MCP OAuth refresh failed: ${response.status} ${text}`);
	}

	const data = (await response.json()) as {
		access_token: string;
		refresh_token?: string;
		expires_in?: number;
	};
	const expiresIn = data.expires_in ?? 3600;
	return {
		access: data.access_token,
		refresh: data.refresh_token ?? refreshToken,
		expires: Date.now() + expiresIn * 1000,
	};
}