@fitchmultz/pi-mcp-adapter 5.0.0

package/dist/mcp-auth-flow.js

@@ -0,0 +1,834 @@
+/**
+ * MCP Auth Flow
+ *
+ * High-level OAuth flow management using the MCP SDK's built-in auth functions.
+ */
+import { auth as runSdkAuth, extractWWWAuthenticateParams, UnauthorizedError, Client, StreamableHTTPClientTransport, validateAuthorizationResponseIssuer, InsufficientScopeError, SdkHttpError, computeScopeUnion, isStrictScopeSuperset, } from "@modelcontextprotocol/client";
+import open from "open";
+import { McpOAuthProvider, issuersMatch, loopbackRedirectsMatch, validateOAuthClientMetadataUrl, validateOAuthPrivateKeyJwt, validateOAuthCrossAppAccess } from "./mcp-oauth-provider.js";
+import { ensureCallbackServer, waitForCallback, cancelPendingCallback, stopCallbackServer, releaseCallbackServer, takeCallbackResult, } from "./mcp-callback-server.js";
+import { getAuthForUrl, clearAllCredentials, clearClientInfo, clearTokens, clearCodeVerifier, getOAuthState, clearOAuthState, getAuthBaseDir, } from "./mcp-auth.js";
+import { isServerDisabled, isNonInteractiveOAuth, validateServerProtocolConfig } from "./types.js";
+import { formatTerminalError, interpolateEnvRecord, interpolateEnvVars, normalizeRequestTimeoutMs } from "./utils.js";
+import { abortable, throwIfAborted } from "./abort.js";
+import { combineAbortSignals, isAbortError } from "./runtime-owner.js";
+function applyConfiguredScope(discovery, config) {
+    return {
+        ...discovery,
+        ...(config.scope !== undefined ? { scope: config.scope } : {}),
+        ...(config.skipIssuerMetadataValidation !== undefined ? { skipIssuerMetadataValidation: config.skipIssuerMetadataValidation } : {}),
+    };
+}
+function validateCallbackIssuer(serverName, context, response) {
+    if (response.error && context.expectedIssuer === undefined) {
+        throw new Error("Cannot verify the OAuth error callback issuer");
+    }
+    try {
+        validateAuthorizationResponseIssuer({ expectedIssuer: context.expectedIssuer ?? context.fallbackIssuer, issParameterSupported: context.issParameterSupported === true, iss: response.iss });
+    }
+    catch {
+        if (response.iss === undefined && context.issParameterSupported) {
+            throw new Error(`The authorization server for ${serverName} requires the RFC 9207 "iss" parameter. ` +
+                "Paste the full redirect URL from the browser address bar (not just the authorization code).");
+        }
+        throw new Error(`The OAuth authorization response issuer does not match the discovered issuer for ${serverName}.`);
+    }
+}
+const runtimeStates = new WeakMap();
+const activeRuntimes = new Set();
+export function createOAuthRuntime(signal) {
+    const controller = new AbortController();
+    const runtime = { signal: combineAbortSignals(signal, controller.signal) };
+    runtimeStates.set(runtime, {
+        controller,
+        generation: 0,
+        activeOperations: 0,
+        pendingAuths: new Map(),
+        pendingAuthStates: new Map(),
+        pendingAuthCleanupTimers: new Map(),
+        pendingAuthentications: new Map(),
+        requests: new Map(),
+    });
+    activeRuntimes.add(runtime);
+    return runtime;
+}
+let legacyRuntime = createOAuthRuntime();
+activeRuntimes.delete(legacyRuntime);
+function getRuntime(options) {
+    if (options?.runtime) {
+        options.runtime.signal.throwIfAborted();
+        activeRuntimes.add(options.runtime);
+        return options.runtime;
+    }
+    if (legacyRuntime.signal.aborted)
+        legacyRuntime = createOAuthRuntime();
+    activeRuntimes.add(legacyRuntime);
+    return legacyRuntime;
+}
+function getRuntimeState(runtime) {
+    const state = runtimeStates.get(runtime);
+    if (!state)
+        throw new Error("Unknown OAuth runtime");
+    return state;
+}
+export function holdOAuthCheckpoint(runtime, event) {
+    const state = getRuntimeState(runtime);
+    if (state.checkpoint)
+        throw new Error("MCP OAuth checkpoint is already held");
+    state.checkpoint = event;
+    return () => { if (state.checkpoint === event)
+        state.checkpoint = undefined; };
+}
+export function getOAuthCheckpointBlocker(runtime) {
+    const state = getRuntimeState(runtime);
+    if (state.activeOperations || state.pendingAuthentications.size)
+        return "MCP OAuth operation is active";
+    if (state.pendingAuths.size || state.pendingAuthStates.size || state.pendingAuthCleanupTimers.size)
+        return "MCP browser OAuth callback/flow is pending";
+    // requests caches server challenges/discovery, not a pending user callback.
+    // Cold connect re-challenges; granted scopes and issuer bindings live in the
+    // native credential store. Actual interactive/auth operations veto above.
+    return undefined;
+}
+async function withOAuthOperation(runtime, run) {
+    const state = getRuntimeState(runtime);
+    state.checkpoint?.invalidate();
+    state.activeOperations++;
+    try {
+        return await run();
+    }
+    finally {
+        state.activeOperations--;
+    }
+}
+function getPendingAuthKey(serverName, options) {
+    return JSON.stringify([serverName, getAuthBaseDir(options)]);
+}
+export function isOAuthChallenge(error) {
+    return error instanceof InsufficientScopeError || error instanceof UnauthorizedError
+        || (error instanceof SdkHttpError && error.status === 401);
+}
+export function getOAuthRequest(serverName, serverUrl, storageBase, runtime = legacyRuntime) {
+    if (runtime.signal.aborted)
+        return undefined;
+    const request = getRuntimeState(runtime).requests.get(JSON.stringify([serverName, storageBase]));
+    return request?.serverUrl === serverUrl ? request : undefined;
+}
+/** Observe native challenges only; no credential reads or auth work here. */
+export function recordOAuthChallenge(serverName, serverUrl, storageBase, error, runtime = legacyRuntime) {
+    if (runtime.signal.aborted || !isOAuthChallenge(error))
+        return;
+    getRuntimeState(runtime).checkpoint?.invalidate();
+    const previous = getOAuthRequest(serverName, serverUrl, storageBase, runtime);
+    const request = { ...previous, serverName, serverUrl };
+    if (error instanceof InsufficientScopeError) {
+        const requiredScope = computeScopeUnion(previous?.challenge?.requiredScope, error.requiredScope);
+        const resourceMetadataUrl = error.resourceMetadataUrl ?? previous?.challenge?.resourceMetadataUrl;
+        request.challenge = { ...(requiredScope ? { requiredScope } : {}), ...(resourceMetadataUrl ? { resourceMetadataUrl } : {}) };
+    }
+    getRuntimeState(runtime).requests.set(JSON.stringify([serverName, storageBase]), request);
+}
+export function bindOAuthRequestIssuer(serverName, serverUrl, storageBase, issuer, runtime = legacyRuntime) {
+    const request = getOAuthRequest(serverName, serverUrl, storageBase, runtime);
+    if (!request)
+        return;
+    if (request.issuer && !issuersMatch(request.issuer, issuer)) {
+        throw new Error(`OAuth authorization server issuer changed for ${serverName}; clear credentials before authenticating again`);
+    }
+    request.issuer = issuer;
+}
+export function hasPendingAuth(serverName, options, runtime) {
+    const state = getRuntimeState(runtime ?? legacyRuntime);
+    if (options) {
+        return state.pendingAuths.has(getPendingAuthKey(serverName, options));
+    }
+    return Array.from(state.pendingAuths.values()).some(pendingAuth => pendingAuth.serverName === serverName);
+}
+/** Timeout for manual auth completion (5 minutes) */
+const MANUAL_AUTH_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Generate a cryptographically secure random state parameter.
+ */
+function generateState() {
+    return Array.from(crypto.getRandomValues(new Uint8Array(32)))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Extract OAuth configuration from a ServerEntry.
+ */
+export function extractOAuthConfig(definition) {
+    validateServerProtocolConfig(definition);
+    if (definition.oauth === false) {
+        return {};
+    }
+    const config = {};
+    if (definition.oauth?.skipIssuerMetadataValidation !== undefined)
+        config.skipIssuerMetadataValidation = definition.oauth.skipIssuerMetadataValidation;
+    if (definition.oauth?.grantType !== undefined)
+        config.grantType = definition.oauth.grantType;
+    if (definition.oauth?.clientId !== undefined) {
+        if (typeof definition.oauth.clientId !== "string")
+            throw new Error("OAuth clientId must be a string");
+        config.clientId = interpolateEnvVars(definition.oauth.clientId);
+    }
+    if (definition.oauth?.clientSecret !== undefined) {
+        if (typeof definition.oauth.clientSecret !== "string")
+            throw new Error("OAuth clientSecret must be a string");
+        // Preserve command expressions for the provider; interpolation remains eager for ordinary values.
+        config.clientSecret = definition.oauth.clientSecret.startsWith("!")
+            ? definition.oauth.clientSecret
+            : interpolateEnvVars(definition.oauth.clientSecret);
+    }
+    if (definition.oauth?.clientMetadataUrl !== undefined) {
+        const value = definition.oauth.clientMetadataUrl;
+        if (value !== false && typeof value !== "string")
+            throw new Error("OAuth clientMetadataUrl must be a string or false");
+        config.clientMetadataUrl = value === false ? false : interpolateEnvVars(value);
+        validateOAuthClientMetadataUrl(config.clientMetadataUrl);
+    }
+    if (definition.oauth?.privateKeyJwt !== undefined) {
+        // Keep environment and command sources lazy; each authentication resolves its own key.
+        config.privateKeyJwt = definition.oauth.privateKeyJwt;
+    }
+    if (definition.oauth?.crossAppAccess !== undefined)
+        config.crossAppAccess = definition.oauth.crossAppAccess;
+    validateOAuthPrivateKeyJwt(config);
+    validateOAuthCrossAppAccess(config);
+    if (definition.oauth?.scope !== undefined) {
+        if (typeof definition.oauth.scope !== "string")
+            throw new Error("OAuth scope must be a string");
+        config.scope = interpolateEnvVars(definition.oauth.scope);
+    }
+    if (definition.oauth?.authorizationParams !== undefined) {
+        const params = definition.oauth.authorizationParams;
+        if (!params || typeof params !== "object" || Array.isArray(params)) {
+            throw new Error("OAuth authorizationParams must be an object");
+        }
+        config.authorizationParams = {};
+        for (const [key, value] of Object.entries(params)) {
+            if (!key)
+                throw new Error("OAuth authorizationParams keys must not be empty");
+            if (typeof value !== "string")
+                throw new Error(`OAuth authorizationParams.${key} must be a string`);
+            config.authorizationParams[key] = interpolateEnvVars(value);
+        }
+    }
+    if (definition.oauth?.redirectUri !== undefined) {
+        if (typeof definition.oauth.redirectUri !== "string") {
+            throw new Error("OAuth redirectUri must be a string");
+        }
+        const redirectUri = interpolateEnvVars(definition.oauth.redirectUri).trim();
+        if (!redirectUri) {
+            throw new Error("OAuth redirectUri must not be empty");
+        }
+        config.redirectUri = redirectUri;
+    }
+    if (definition.oauth?.clientName !== undefined) {
+        if (typeof definition.oauth.clientName !== "string") {
+            throw new Error("OAuth clientName must be a string");
+        }
+        const clientName = interpolateEnvVars(definition.oauth.clientName).trim();
+        if (!clientName) {
+            throw new Error("OAuth clientName must not be empty");
+        }
+        config.clientName = clientName;
+    }
+    if (definition.oauth?.clientUri !== undefined) {
+        if (typeof definition.oauth.clientUri !== "string") {
+            throw new Error("OAuth clientUri must be a string");
+        }
+        const clientUri = interpolateEnvVars(definition.oauth.clientUri).trim();
+        if (!clientUri) {
+            throw new Error("OAuth clientUri must not be empty");
+        }
+        config.clientUri = clientUri;
+    }
+    return config;
+}
+async function probeAuthDiscovery(serverUrl, definition, signal) {
+    // Discovery must not execute config commands or send their source text.
+    const discoveryHeaders = definition?.headers
+        ? Object.fromEntries(Object.entries(definition.headers).filter(([, value]) => !value.startsWith("!") || value.startsWith("!!")))
+        : undefined;
+    const headers = new Headers(interpolateEnvRecord(discoveryHeaders));
+    const timeout = normalizeRequestTimeoutMs(definition?.requestTimeoutMs) ?? 5000;
+    const discoverySignal = combineAbortSignals(signal, AbortSignal.timeout(Math.ceil(timeout)));
+    let discovery = {};
+    const client = new Client({ name: "pi-mcp-auth-discovery", version: "4.3.1" }, {
+        versionNegotiation: { mode: definition?.protocolVersion ?? "auto" },
+        ...(isNonInteractiveOAuth(definition?.oauth)
+            ? { capabilities: { extensions: { [definition?.oauth && definition.oauth.crossAppAccess
+                            ? "io.modelcontextprotocol/enterprise-managed-authorization" : "io.modelcontextprotocol/oauth-client-credentials"]: {} } } } : {}),
+    });
+    const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
+        requestInit: { headers },
+        fetch: async (input, init) => {
+            const response = await fetch(input, init);
+            const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
+            discovery = { ...(resourceMetadataUrl ? { resourceMetadataUrl } : {}), ...(scope ? { scope } : {}) };
+            return response;
+        },
+    });
+    try {
+        await abortable(client.connect(transport, { timeout }), discoverySignal);
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throwIfAborted(signal);
+    }
+    finally {
+        await (client.transport ? client.close() : transport.close());
+    }
+    return discovery;
+}
+function parseOAuthRedirectUri(redirectUri) {
+    let url;
+    try {
+        url = new URL(redirectUri);
+    }
+    catch (error) {
+        throw new Error(`Invalid OAuth redirectUri: ${redirectUri}`, { cause: error });
+    }
+    const hostname = url.hostname.toLowerCase();
+    const isLocalhost = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+    if (url.protocol !== "http:" || !isLocalhost) {
+        throw new Error("OAuth redirectUri must be an http:// localhost or loopback URI");
+    }
+    if (url.username || url.password) {
+        throw new Error("OAuth redirectUri must not include username or password");
+    }
+    if (url.hash) {
+        throw new Error("OAuth redirectUri must not include a fragment");
+    }
+    if (!url.port) {
+        throw new Error("OAuth redirectUri must include an explicit numeric port");
+    }
+    const port = Number.parseInt(url.port, 10);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error("OAuth redirectUri must include an explicit numeric port");
+    }
+    const callbackHost = hostname === "[::1]" ? "::1" : hostname;
+    return { port, callbackHost, callbackPath: url.pathname };
+}
+/**
+ * Start OAuth authentication flow for a server.
+ * Returns the authorization URL when browser authorization is required.
+ */
+export const startAuth = async (...args) => withOAuthOperation(getRuntime(args[3]), () => startAuthOperation(...args));
+async function startAuthOperation(serverName, serverUrl, definition, options = {}) {
+    if (isServerDisabled(definition))
+        throw new Error(`MCP server "${serverName}" is disabled`);
+    const runtime = getRuntime(options);
+    const runtimeState = getRuntimeState(runtime);
+    const config = definition ? extractOAuthConfig(definition) : {};
+    const authStorageOptions = options.authStorageOptions ?? {};
+    const signal = combineAbortSignals(runtime.signal, options.signal);
+    const generation = runtimeState.generation;
+    throwIfAborted(signal);
+    if (isNonInteractiveOAuth(config)) {
+        const storedAuth = await getAuthForUrl(serverName, serverUrl, authStorageOptions);
+        if (!config.crossAppAccess && storedAuth?.clientInfo && !storedAuth.tokens && !config.clientId) {
+            clearClientInfo(serverName, authStorageOptions);
+            clearCodeVerifier(serverName, authStorageOptions);
+            await clearOAuthState(serverName, authStorageOptions);
+        }
+        const authProvider = new McpOAuthProvider(serverName, serverUrl, config, {
+            onRedirect: async () => {
+                throw new Error("Browser redirect is not used for noninteractive OAuth flows");
+            },
+        }, authStorageOptions, signal);
+        try {
+            const discovery = applyConfiguredScope(await probeAuthDiscovery(serverUrl, definition, signal), config);
+            throwIfAborted(signal);
+            const result = await abortable(runSdkAuth(authProvider, { serverUrl, ...discovery, fetchFn: authProvider.fetch }), signal);
+            throwIfAborted(signal);
+            if (result !== "AUTHORIZED") {
+                throw new UnauthorizedError("Failed to authorize");
+            }
+            return { authorizationUrl: "" };
+        }
+        finally {
+            authProvider.deactivate();
+        }
+    }
+    const storageBase = getAuthBaseDir(authStorageOptions);
+    const request = getOAuthRequest(serverName, serverUrl, storageBase, runtime);
+    const existingPendingAuth = runtimeState.pendingAuths.get(getPendingAuthKey(serverName, authStorageOptions));
+    if (existingPendingAuth?.serverUrl === serverUrl) {
+        return { authorizationUrl: existingPendingAuth.authorizationUrl };
+    }
+    const redirectCallback = config.redirectUri !== undefined ? parseOAuthRedirectUri(config.redirectUri) : undefined;
+    const oauthState = generateState();
+    const callbackIssuer = {};
+    try {
+        await ensureCallbackServer({
+            strictPort: Boolean(config.clientId) || config.redirectUri !== undefined,
+            oauthState,
+            reserveState: true,
+            validate: response => validateCallbackIssuer(serverName, callbackIssuer, response),
+            ...(redirectCallback ? { port: redirectCallback.port, callbackHost: redirectCallback.callbackHost, callbackPath: redirectCallback.callbackPath } : {}),
+        });
+        throwIfAborted(signal);
+    }
+    catch (error) {
+        releaseCallbackServer(oauthState);
+        try {
+            await clearOAuthState(serverName, authStorageOptions);
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "OAuth startup cleanup failed");
+        }
+        throw error;
+    }
+    let capturedUrl;
+    let authProvider;
+    try {
+        const storedAuth = await getAuthForUrl(serverName, serverUrl, authStorageOptions);
+        let discovery = applyConfiguredScope(await probeAuthDiscovery(serverUrl, definition, signal), config);
+        if (request?.challenge) {
+            const scope = computeScopeUnion(discovery.scope, request.requestedScope, storedAuth?.tokens?.scope, request.challenge.requiredScope);
+            discovery = { ...discovery, ...(scope ? { scope } : {}), ...(request.challenge.resourceMetadataUrl ? { resourceMetadataUrl: request.challenge.resourceMetadataUrl } : {}) };
+        }
+        throwIfAborted(signal);
+        const flowConfig = { ...config, ...(request?.challenge && discovery.scope ? { scope: discovery.scope } : {}) };
+        authProvider = new McpOAuthProvider(serverName, serverUrl, flowConfig, {
+            onRedirect: url => {
+                capturedUrl = url;
+                const requestedScope = url.searchParams.get("scope") ?? undefined;
+                if (requestedScope) {
+                    discovery = { ...discovery, scope: requestedScope };
+                    if (request?.challenge)
+                        flowConfig.scope = requestedScope;
+                }
+                const current = getOAuthRequest(serverName, serverUrl, storageBase, runtime);
+                const scope = computeScopeUnion(current?.requestedScope, requestedScope);
+                if (current && scope)
+                    current.requestedScope = scope;
+            },
+            onDiscoveryState: state => {
+                callbackIssuer.expectedIssuer = state.authorizationServerMetadata?.issuer;
+                callbackIssuer.fallbackIssuer = state.authorizationServerUrl;
+                callbackIssuer.issParameterSupported = state.authorizationServerMetadata?.authorization_response_iss_parameter_supported === true;
+                bindOAuthRequestIssuer(serverName, serverUrl, storageBase, callbackIssuer.expectedIssuer ?? state.authorizationServerUrl, runtime);
+            },
+        }, authStorageOptions, runtime.signal, oauthState);
+        if (storedAuth?.clientInfo && !config.clientId) {
+            if (!storedAuth.tokens) {
+                clearClientInfo(serverName, authStorageOptions);
+                clearCodeVerifier(serverName, authStorageOptions);
+                await clearOAuthState(serverName, authStorageOptions);
+            }
+            else {
+                const redirectUris = storedAuth.clientInfo.redirectUris;
+                const redirectUrl = authProvider.redirectUrl ?? "";
+                const matchesRedirect = Array.isArray(redirectUris) && (redirectUris.includes(redirectUrl)
+                    || (storedAuth.clientInfo.registrationType === "cimd"
+                        && redirectUris.some(uri => loopbackRedirectsMatch(redirectUrl, uri))));
+                if (!matchesRedirect) {
+                    clearClientInfo(serverName, authStorageOptions);
+                    clearTokens(serverName, authStorageOptions);
+                    clearCodeVerifier(serverName, authStorageOptions);
+                    await clearOAuthState(serverName, authStorageOptions);
+                }
+            }
+        }
+        throwIfAborted(signal);
+        const result = await abortable(runSdkAuth(authProvider, {
+            serverUrl, ...discovery,
+            ...(request?.challenge ? { forceReauthorization: isStrictScopeSuperset(discovery.scope, storedAuth?.tokens?.scope) } : {}),
+        }), signal);
+        throwIfAborted(signal);
+        if (result === "AUTHORIZED") {
+            authProvider.deactivate();
+            releaseCallbackServer(oauthState);
+            await clearOAuthState(serverName, authStorageOptions);
+            return { authorizationUrl: "" };
+        }
+        if (!capturedUrl) {
+            throw new UnauthorizedError("OAuth authorization URL was not provided");
+        }
+        await setPendingAuth(runtime, serverName, { serverName, authProvider, serverUrl, authorizationUrl: capturedUrl.toString(), discovery, callbackIssuer: { ...callbackIssuer }, authStorageOptions, ...(request ? { request } : {}) }, oauthState, signal, generation);
+        return { authorizationUrl: capturedUrl.toString() };
+    }
+    catch (error) {
+        authProvider?.deactivate();
+        try {
+            await clearPendingAuth(runtime, serverName, oauthState, authStorageOptions);
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "OAuth startup cleanup failed");
+        }
+        throw error;
+    }
+}
+async function setPendingAuth(runtime, serverName, pendingAuth, oauthState, signal, generation = getRuntimeState(runtime).generation) {
+    const state = getRuntimeState(runtime);
+    const key = getPendingAuthKey(serverName, pendingAuth.authStorageOptions);
+    await clearPendingAuth(runtime, serverName, undefined, pendingAuth.authStorageOptions);
+    throwIfAborted(signal);
+    if (generation !== state.generation)
+        throw new Error("OAuth runtime stopped");
+    state.pendingAuths.set(key, pendingAuth);
+    state.pendingAuthStates.set(key, oauthState);
+    const cleanupTimer = setTimeout(() => {
+        void clearPendingAuth(runtime, serverName, oauthState, pendingAuth.authStorageOptions).catch(error => {
+            console.error(`MCP Auth: Timed-out flow cleanup failed: ${formatTerminalError(error)}`);
+        });
+    }, MANUAL_AUTH_TIMEOUT_MS);
+    cleanupTimer.unref?.();
+    state.pendingAuthCleanupTimers.set(key, cleanupTimer);
+}
+function clearPendingAuth(...args) {
+    return withOAuthOperation(args[0], () => clearPendingAuthOperation(...args));
+}
+async function clearPendingAuthOperation(runtime, serverName, oauthState, fallbackStorageOptions = {}) {
+    const state = getRuntimeState(runtime);
+    const key = getPendingAuthKey(serverName, fallbackStorageOptions);
+    const pendingAuth = state.pendingAuths.get(key);
+    const authStorageOptions = pendingAuth?.authStorageOptions ?? fallbackStorageOptions;
+    const pendingState = state.pendingAuthStates.get(key);
+    if (oauthState && pendingState && pendingState !== oauthState)
+        return;
+    const timer = state.pendingAuthCleanupTimers.get(key);
+    if (timer) {
+        clearTimeout(timer);
+        state.pendingAuthCleanupTimers.delete(key);
+    }
+    pendingAuth?.authProvider.deactivate();
+    state.pendingAuths.delete(key);
+    state.pendingAuthStates.delete(key);
+    const stateToRelease = pendingState ?? oauthState;
+    if (stateToRelease) {
+        cancelPendingCallback(stateToRelease);
+        const storedState = await getOAuthState(serverName, authStorageOptions);
+        if (storedState === stateToRelease) {
+            await clearOAuthState(serverName, authStorageOptions);
+        }
+    }
+}
+function getSearchParamsFromInput(input) {
+    try {
+        const url = new URL(input);
+        const params = new URLSearchParams(url.search);
+        if (url.hash) {
+            const hash = url.hash.startsWith("#") ? url.hash.slice(1) : url.hash;
+            const hashParams = new URLSearchParams(hash);
+            for (const [key, value] of hashParams) {
+                if (!params.has(key))
+                    params.set(key, value);
+            }
+        }
+        return params;
+    }
+    catch {
+        const query = input.includes("?") ? input.slice(input.indexOf("?") + 1) : input;
+        const params = new URLSearchParams(query.startsWith("#") ? query.slice(1) : query);
+        return params.has("code") || params.has("state") || params.has("error") ? params : undefined;
+    }
+}
+export function parseAuthorizationRedirectInput(input, expectedState) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new Error("Authorization code or redirect URL is required");
+    }
+    const params = getSearchParamsFromInput(trimmed);
+    if (params) {
+        const state = params.get("state");
+        if (expectedState && !state) {
+            throw new Error("OAuth state missing from redirect URL");
+        }
+        if (expectedState && state !== expectedState) {
+            throw new Error("OAuth state mismatch - potential CSRF attack");
+        }
+        const error = params.get("error");
+        if (error) {
+            const description = params.get("error_description");
+            const iss = params.get("iss");
+            return { error, ...(description !== null ? { errorDescription: description } : {}), ...(iss !== null ? { iss } : {}) };
+        }
+        const code = params.get("code");
+        if (code) {
+            const iss = params.get("iss");
+            return { code, ...(iss !== null ? { iss } : {}) };
+        }
+    }
+    if (/^[A-Za-z0-9._~+/=-]+$/.test(trimmed)) {
+        return { code: trimmed };
+    }
+    throw new Error("Could not find an OAuth authorization code in the provided input");
+}
+/**
+ * Complete OAuth authentication from pasted input or a captured browser callback.
+ */
+export async function completeAuthFromInput(serverName, input, options = {}) {
+    const runtime = getRuntime(options);
+    const runtimeState = getRuntimeState(runtime);
+    const fallbackAuthStorageOptions = options.authStorageOptions ?? {};
+    const signal = combineAbortSignals(runtime.signal, options.signal);
+    throwIfAborted(signal);
+    const key = getPendingAuthKey(serverName, fallbackAuthStorageOptions);
+    const oauthState = runtimeState.pendingAuthStates.get(key);
+    throwIfAborted(signal);
+    const parsed = input === undefined ? undefined : parseAuthorizationRedirectInput(input, oauthState);
+    return completeAuth(serverName, parsed, options);
+}
+/**
+ * Complete OAuth authentication with an explicit code or a captured callback.
+ */
+export const completeAuth = async (...args) => withOAuthOperation(getRuntime(args[2]), () => completeAuthOperation(...args));
+async function completeAuthOperation(serverName, authorizationCode, options = {}) {
+    const runtime = getRuntime(options);
+    const runtimeState = getRuntimeState(runtime);
+    const fallbackAuthStorageOptions = options.authStorageOptions ?? {};
+    const signal = combineAbortSignals(runtime.signal, options.signal);
+    throwIfAborted(signal);
+    const key = getPendingAuthKey(serverName, fallbackAuthStorageOptions);
+    const pendingAuth = runtimeState.pendingAuths.get(key);
+    const authStorageOptions = pendingAuth?.authStorageOptions ?? fallbackAuthStorageOptions;
+    if (!pendingAuth) {
+        throw new Error(`No pending OAuth flow for server: ${serverName}. Run auth-start for this server first.`);
+    }
+    const oauthState = runtimeState.pendingAuthStates.get(key);
+    throwIfAborted(signal);
+    const response = typeof authorizationCode === "string" ? { code: authorizationCode }
+        : authorizationCode ?? (oauthState ? takeCallbackResult(oauthState) : undefined);
+    if (!response) {
+        throw new Error(`No OAuth callback received yet for ${serverName}. Finish authorization in the browser, then retry auth-complete. ` +
+            "If the browser cannot reach this Pi session's callback, pass args: { redirectUrl: \"FULL_REDIRECT_URL\" } instead.");
+    }
+    const { iss } = response;
+    let keepPendingForRetry = false;
+    let caughtError;
+    try {
+        keepPendingForRetry = iss === undefined && pendingAuth.callbackIssuer.issParameterSupported === true;
+        validateCallbackIssuer(serverName, pendingAuth.callbackIssuer, response);
+        if ("error" in response) {
+            keepPendingForRetry = true;
+            throw new Error(response.errorDescription ? `${response.error}: ${response.errorDescription}` : response.error);
+        }
+        const result = await abortable(runSdkAuth(pendingAuth.authProvider, {
+            serverUrl: pendingAuth.serverUrl,
+            authorizationCode: response.code,
+            ...(iss !== undefined ? { iss } : {}),
+            ...pendingAuth.discovery,
+        }), signal);
+        throwIfAborted(signal);
+        if (result !== "AUTHORIZED") {
+            throw new UnauthorizedError("Failed to authorize");
+        }
+        const request = pendingAuth.request;
+        if (request?.challenge?.requiredScope
+            && request === getOAuthRequest(serverName, pendingAuth.serverUrl, getAuthBaseDir(authStorageOptions), runtime)) {
+            const issuedScope = (await getAuthForUrl(serverName, pendingAuth.serverUrl, authStorageOptions))?.tokens?.scope;
+            if (issuedScope !== undefined && !isStrictScopeSuperset(request.challenge.requiredScope, issuedScope))
+                delete request.challenge;
+        }
+        return "authenticated";
+    }
+    catch (error) {
+        caughtError = error;
+        throw error;
+    }
+    finally {
+        if (!keepPendingForRetry) {
+            try {
+                await clearPendingAuth(runtime, serverName, oauthState, authStorageOptions);
+            }
+            catch (cleanupError) {
+                if (caughtError !== undefined) {
+                    throw new AggregateError([caughtError, cleanupError], "OAuth completion cleanup failed");
+                }
+                throw cleanupError;
+            }
+        }
+    }
+}
+/**
+ * Perform the complete OAuth authentication flow for a server.
+ *
+ * @param serverName - The name of the MCP server
+ * @param serverUrl - The URL of the MCP server
+ * @param definition - The server definition (optional)
+ * @returns The final auth status
+ */
+export async function authenticate(serverName, serverUrl, definition, options = {}) {
+    if (isServerDisabled(definition))
+        throw new Error(`MCP server "${serverName}" is disabled`);
+    const runtime = getRuntime(options);
+    const runtimeState = getRuntimeState(runtime);
+    const authStorageOptions = options.authStorageOptions ?? {};
+    const signal = combineAbortSignals(runtime.signal, options.signal);
+    throwIfAborted(signal);
+    const authKey = JSON.stringify([serverName, serverUrl, getAuthBaseDir(authStorageOptions)]);
+    const inFlight = runtimeState.pendingAuthentications.get(authKey);
+    if (inFlight) {
+        return inFlight;
+    }
+    const operation = (async () => {
+        // Start auth flow
+        const { authorizationUrl } = await startAuth(serverName, serverUrl, definition, {
+            ...options,
+            ...(signal ? { signal } : {}),
+            runtime,
+        });
+        // If no auth URL needed, already authenticated
+        if (!authorizationUrl) {
+            return "authenticated";
+        }
+        let oauthState;
+        try {
+            // Get the state that was already generated and stored in startAuth().
+            // Keep this lookup and its abort check inside the cleanup boundary because
+            // startAuth has already reserved callback state at this point.
+            oauthState = runtimeState.pendingAuthStates.get(getPendingAuthKey(serverName, authStorageOptions));
+            throwIfAborted(signal);
+            if (!oauthState) {
+                throw new Error("OAuth state not found - this should not happen");
+            }
+            // Register the callback BEFORE opening the browser.
+            const callbackPromise = waitForCallback(oauthState);
+            void callbackPromise.catch(() => { });
+            // Open browser. Always surface the URL first so remote/headless users can copy it
+            // even when the OS browser handoff is unavailable or invisible.
+            if (options.onAuthorizationUrl) {
+                await abortable(Promise.resolve(options.onAuthorizationUrl(authorizationUrl)), signal);
+            }
+            else {
+                console.log(`MCP Auth: Open this URL to authenticate ${serverName}:\n${authorizationUrl}`);
+            }
+            try {
+                await abortable(open(authorizationUrl), signal);
+            }
+            catch (error) {
+                if (isAbortError(error, signal))
+                    throw error;
+                console.warn(`MCP Auth: Failed to open browser for ${serverName}; waiting for manual callback`, { error });
+            }
+            // Wait for callback
+            const callbackResult = await abortable(callbackPromise, signal);
+            // The callback server accepted only the flow-local reserved state.
+            throwIfAborted(signal);
+            // Complete the auth
+            return await completeAuth(serverName, callbackResult, {
+                ...options,
+                ...(signal ? { signal } : {}),
+                runtime,
+            });
+        }
+        catch (error) {
+            if (oauthState)
+                cancelPendingCallback(oauthState);
+            try {
+                await clearPendingAuth(runtime, serverName, oauthState, authStorageOptions);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], "OAuth cancellation cleanup failed");
+            }
+            throw error;
+        }
+    })();
+    runtimeState.pendingAuthentications.set(authKey, operation);
+    try {
+        return await operation;
+    }
+    finally {
+        if (runtimeState.pendingAuthentications.get(authKey) === operation) {
+            runtimeState.pendingAuthentications.delete(authKey);
+        }
+    }
+}
+/**
+ * Remove all OAuth credentials for a server.
+ *
+ * @param serverName - The name of the MCP server
+ */
+export const removeAuth = async (...args) => withOAuthOperation(getRuntime(args[1]), () => removeAuthOperation(...args));
+async function removeAuthOperation(serverName, options = {}) {
+    const runtime = getRuntime(options);
+    const signal = combineAbortSignals(runtime.signal, options.signal);
+    throwIfAborted(signal);
+    const authStorageOptions = options.authStorageOptions ?? {};
+    const oauthState = await getOAuthState(serverName, authStorageOptions);
+    throwIfAborted(signal);
+    if (oauthState) {
+        cancelPendingCallback(oauthState);
+    }
+    await clearPendingAuth(runtime, serverName, oauthState, authStorageOptions);
+    throwIfAborted(signal);
+    for (const [key, request] of getRuntimeState(runtime).requests) {
+        if (request.serverName === serverName)
+            getRuntimeState(runtime).requests.delete(key);
+    }
+    clearAllCredentials(serverName, authStorageOptions);
+    await clearOAuthState(serverName, authStorageOptions);
+    throwIfAborted(signal);
+    console.log(`MCP Auth: Removed credentials for ${serverName}`);
+}
+/**
+ * Check if OAuth is supported for a server configuration.
+ * OAuth is supported for HTTP servers unless explicitly disabled.
+ *
+ * @param definition - The server definition
+ * @returns True if OAuth is supported
+ */
+export function supportsOAuth(definition) {
+    // OAuth requires a URL
+    if (!definition.url)
+        return false;
+    // Explicitly disabled via auth: false or oauth: false
+    if (definition.auth === false)
+        return false;
+    if (definition.oauth === false)
+        return false;
+    if (definition.auth === "oauth")
+        return true;
+    // Configured custom headers take precedence over implicit OAuth auto-detection.
+    if (definition.headers && Object.keys(definition.headers).length > 0)
+        return false;
+    // OAuth is enabled when auth is not specified (auto-detect)
+    return definition.auth === undefined;
+}
+/**
+ * Initialize the OAuth system on startup.
+ * OAuth callback binding is lazy and starts from startAuth() only.
+ */
+export async function initializeOAuth(runtimeOrSignal) {
+    if (runtimeOrSignal && "signal" in runtimeOrSignal) {
+        runtimeOrSignal.signal.throwIfAborted();
+        activeRuntimes.add(runtimeOrSignal);
+        return runtimeOrSignal;
+    }
+    await shutdownOAuth(legacyRuntime);
+    legacyRuntime = createOAuthRuntime(runtimeOrSignal);
+    return legacyRuntime;
+}
+/**
+ * Shutdown one OAuth runtime. The callback server remains process-shared while
+ * another runtime has pending/reserved callback state or is still active.
+ */
+export async function shutdownOAuth(runtime = legacyRuntime) {
+    const state = getRuntimeState(runtime);
+    if (state.controller.signal.aborted)
+        return;
+    state.checkpoint?.invalidate();
+    state.generation += 1;
+    state.controller.abort(new Error("OAuth runtime stopped"));
+    for (const callbackState of Array.from(state.pendingAuthStates.values()))
+        cancelPendingCallback(callbackState);
+    const results = await Promise.allSettled(Array.from(state.pendingAuths.values(), pendingAuth => clearPendingAuth(runtime, pendingAuth.serverName, undefined, pendingAuth.authStorageOptions)));
+    const failures = results.flatMap(result => result.status === "rejected" ? [result.reason] : []);
+    state.pendingAuthentications.clear();
+    state.requests.clear();
+    activeRuntimes.delete(runtime);
+    if (activeRuntimes.size === 0) {
+        try {
+            await stopCallbackServer();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (failures.length)
+        throw new AggregateError(failures, "MCP OAuth cleanup failed");
+}