@akon-labs/nexus-cli 0.1.9 → 0.1.10

package/dist/extensions/mcp/mcp-keyring-helper.cjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+'use strict';
+
+const { createRequire } = require('node:module');
+const { dirname, join } = require('node:path');
+
+const requireFromHere = createRequire(__filename);
+
+function loadKeyringEntryClass() {
+  try {
+    return requireFromHere('@napi-rs/keyring').Entry;
+  } catch (loaderError) {
+    const suffixes = getNativeBindingSuffixes(process.platform, process.arch);
+    let lastError;
+    for (const suffix of suffixes) {
+      try {
+        const packageJsonPath = requireFromHere.resolve(`@napi-rs/keyring-${suffix}/package.json`);
+        return requireFromHere(join(dirname(packageJsonPath), `keyring.${suffix}.node`)).Entry;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    const error = new Error(`Failed to load @napi-rs/keyring in recovery helper: ${lastError?.message ?? loaderError.message}`);
+    error.cause = loaderError;
+    throw error;
+  }
+}
+
+function getNativeBindingSuffixes(platform, arch) {
+  if (platform === 'linux') {
+    if (arch === 'arm64') return ['linux-arm64-gnu', 'linux-arm64-musl'];
+    if (arch === 'arm') return ['linux-arm-gnueabihf'];
+    if (arch === 'riscv64') return ['linux-riscv64-gnu'];
+    if (arch === 'x64') return ['linux-x64-gnu', 'linux-x64-musl'];
+  }
+  return [];
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      input += chunk;
+      if (input.length > 1024 * 1024) {
+        reject(new Error('request too large'));
+        process.stdin.destroy();
+      }
+    });
+    process.stdin.on('error', reject);
+    process.stdin.on('end', () => resolve(input));
+  });
+}
+
+function writeResponse(response) {
+  process.stdout.write(`${JSON.stringify(response)}\n`);
+}
+
+(async () => {
+  try {
+    const request = JSON.parse(await readStdin());
+    if (!request || typeof request !== 'object') throw new Error('invalid request');
+    const { operation, service, account, payload } = request;
+    if (!['read', 'write', 'remove'].includes(operation)) throw new Error('invalid operation');
+    if (typeof service !== 'string' || !service) throw new Error('invalid service');
+    if (typeof account !== 'string' || !account) throw new Error('invalid account');
+
+    const Entry = loadKeyringEntryClass();
+    const entry = new Entry(service, account);
+
+    if (operation === 'read') {
+      const value = entry.getPassword();
+      writeResponse(value === null ? { ok: true, found: false } : { ok: true, found: true, value });
+      return;
+    }
+    if (operation === 'write') {
+      if (typeof payload !== 'string') throw new Error('invalid payload');
+      entry.setPassword(payload);
+      writeResponse({ ok: true });
+      return;
+    }
+
+    entry.deleteCredential();
+    writeResponse({ ok: true });
+  } catch (error) {
+    writeResponse({ ok: false, error: error instanceof Error ? error.message : String(error) });
+    process.exitCode = 1;
+  }
+})();

package/dist/extensions/mcp/mcp-oauth-provider.d.ts

@@ -0,0 +1,135 @@
+/**
+ * MCP OAuth Provider
+ *
+ * Implementation of the MCP SDK's OAuthClientProvider interface.
+ * Handles OAuth client registration, token storage, and authorization redirection.
+ */
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/client";
+import { type AddClientAuthentication, type OAuthClientProvider, type OAuthDiscoveryState } from "@modelcontextprotocol/client";
+import { type AuthStorageOptions } from "./mcp-auth.ts";
+declare const DEFAULT_OAUTH_CALLBACK_PORT = 19876;
+declare const DEFAULT_OAUTH_CALLBACK_PATH = "/callback";
+export declare function getConfiguredOAuthCallbackPort(): number;
+export declare function getOAuthCallbackPort(): number;
+export declare function setOAuthCallbackPort(port: number): void;
+export declare function getOAuthCallbackPath(): string;
+export declare function setOAuthCallbackPath(path: string): void;
+/** Configuration options for OAuth */
+export interface McpOAuthConfig {
+    grantType?: "authorization_code" | "client_credentials";
+    clientId?: string;
+    clientSecret?: string;
+    scope?: string;
+    authorizationParams?: Record<string, string>;
+    redirectUri?: string;
+    clientName?: string;
+    clientUri?: string;
+    logoUri?: string;
+    skipIssuerMetadataValidation?: boolean;
+}
+/** Callbacks for OAuth flow interactions */
+export interface McpOAuthCallbacks {
+    onRedirect: (url: URL) => void | Promise<void>;
+}
+/**
+ * OAuth provider implementation for MCP servers.
+ * Implements the OAuthClientProvider interface from the MCP SDK.
+ */
+export declare class McpOAuthProvider implements OAuthClientProvider {
+    private readonly redirectUrlSnapshot;
+    private active;
+    private flowClientInfo;
+    private flowCodeVerifier;
+    private flowDiscoveryState;
+    private flowIssuerMismatch;
+    private flowState;
+    private serverName;
+    private serverUrl;
+    private config;
+    private callbacks;
+    private storageOptions;
+    private runtimeSignal;
+    constructor(serverName: string, serverUrl: string, config: McpOAuthConfig, callbacks: McpOAuthCallbacks, storageOptions?: AuthStorageOptions, runtimeSignal?: AbortSignal, initialState?: string);
+    private get usesClientCredentials();
+    private get discoveredIssuer();
+    deactivate(): void;
+    private assertStoredIssuerBindings;
+    private throwIfInactive;
+    /**
+     * The redirect URL for OAuth callbacks.
+     * This must match the redirect_uri in client metadata.
+     */
+    get redirectUrl(): string | undefined;
+    /** Configured homepage, otherwise the Nexus repository. */
+    private get clientUri();
+    /**
+     * Client metadata for dynamic registration.
+     * Describes this client to the OAuth authorization server.
+     */
+    get clientMetadata(): OAuthClientMetadata;
+    /**
+     * Get client information (for pre-registered or dynamically registered clients).
+     * Returns undefined if no client info exists or if the server URL has changed.
+     */
+    clientInformation(): Promise<OAuthClientInformationMixed | undefined>;
+    /**
+     * Save client information from dynamic registration.
+     */
+    saveClientInformation(info: OAuthClientInformationMixed): Promise<void>;
+    /**
+     * Get stored OAuth tokens.
+     * Returns undefined if no tokens exist or if the server URL has changed.
+     */
+    tokens(): Promise<OAuthTokens | undefined>;
+    /**
+     * Save OAuth tokens.
+     */
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    /**
+     * Redirect the user to the authorization URL.
+     * This opens the browser for the user to authenticate.
+     *
+     * Throws UnauthorizedError when called outside of a user-initiated flow
+     * (no oauthState saved by startAuth). That path is reached when the SDK
+     * falls through from a failed refresh into a fresh authorization_code
+     * flow, which library hosts cannot complete in-process.
+     */
+    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    /**
+     * Save the PKCE code verifier.
+     */
+    saveCodeVerifier(codeVerifier: string): Promise<void>;
+    /**
+     * Get the stored PKCE code verifier.
+     * @throws Error if no code verifier is stored
+     */
+    codeVerifier(): Promise<string>;
+    /**
+     * Keep discovery with the in-flight PKCE verifier. The callback leg uses it
+     * to validate the authorization response issuer before token exchange.
+     */
+    saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
+    discoveryState(): Promise<OAuthDiscoveryState | undefined>;
+    /**
+     * Save the OAuth state parameter for CSRF protection.
+     */
+    saveState(state: string): Promise<void>;
+    /**
+     * Get the stored OAuth state parameter.
+     * @throws UnauthorizedError if no flow is in progress (see redirectToAuthorization)
+     */
+    state(): Promise<string>;
+    /**
+     * Invalidate credentials when authentication fails.
+     * Clears tokens, client info, or all credentials based on the type.
+     */
+    invalidateCredentials(type: "all" | "client" | "tokens" | "verifier" | "discovery"): Promise<void>;
+    /**
+     * Adds configured authorization-code scope without replacing the SDK's
+     * default token endpoint authentication behavior.
+     */
+    addClientAuthentication: AddClientAuthentication;
+    prepareTokenRequest(scope?: string): URLSearchParams | undefined;
+}
+export { DEFAULT_OAUTH_CALLBACK_PORT, DEFAULT_OAUTH_CALLBACK_PATH };
+//# sourceMappingURL=mcp-oauth-provider.d.ts.map

package/dist/extensions/mcp/mcp-oauth-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-oauth-provider.d.ts","sourceRoot":"","sources":["../../../src/extensions/mcp/mcp-oauth-provider.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * MCP OAuth Provider\n *\n * Implementation of the MCP SDK's OAuthClientProvider interface.\n * Handles OAuth client registration, token storage, and authorization redirection.\n */\n\nimport type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from \"@modelcontextprotocol/client\";\nimport {\n\ttype AddClientAuthentication,\n\ttype OAuthClientProvider,\n\ttype OAuthDiscoveryState,\n\tUnauthorizedError,\n} from \"@modelcontextprotocol/client\";\nimport { getAppClientUri, getAppName } from \"./agent-dir.ts\";\nimport {\n\ttype AuthEntry,\n\ttype AuthStorageOptions,\n\tclearAllCredentials,\n\tclearClientInfo,\n\tclearCodeVerifier,\n\tclearTokens,\n\tgetAuthForUrl,\n\ttype StoredClientInfo,\n\ttype StoredTokens,\n\tupdateClientInfo,\n\tupdateTokens,\n} from \"./mcp-auth.ts\";\nimport { resolveCommandSecret } from \"./utils.ts\";\n\n/**\n * Client name advertised during Dynamic Client Registration.\n *\n * OAuth consent screens must identify the application users are running.\n */\nfunction defaultClientName(): string {\n\treturn getAppName();\n}\n\n/**\n * Client homepage advertised during Dynamic Client Registration.\n *\n * RFC 7591 defines client_uri as the home page of the client.\n */\nfunction defaultClientUri(): string | undefined {\n\tconst declared = getAppClientUri();\n\tif (declared) return declared;\n\treturn getAppName() === \"Nexus\" ? \"https://github.com/Akon-Labs/nexus-cli\" : undefined;\n}\n\ntype IssuerBoundClientInformation = OAuthClientInformationMixed & { issuer?: string };\ntype IssuerBoundTokens = OAuthTokens & { issuer?: string };\n\nfunction issuersMatch(first: string, second: string): boolean {\n\treturn (\n\t\tfirst === second ||\n\t\t(first.endsWith(\"/\") && first.slice(0, -1) === second) ||\n\t\t(second.endsWith(\"/\") && second.slice(0, -1) === first)\n\t);\n}\n\n// Callback server configuration\nconst DEFAULT_OAUTH_CALLBACK_PORT = 19876;\nconst DEFAULT_OAUTH_CALLBACK_PATH = \"/callback\";\n\nlet configuredOAuthCallbackPort = DEFAULT_OAUTH_CALLBACK_PORT;\n\nif (process.env.MCP_OAUTH_CALLBACK_PORT) {\n\tconst parsedPort = Number.parseInt(process.env.MCP_OAUTH_CALLBACK_PORT, 10);\n\tif (Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535) {\n\t\tconfiguredOAuthCallbackPort = parsedPort;\n\t}\n}\n\nlet oauthCallbackPort = configuredOAuthCallbackPort;\nlet oauthCallbackPath = DEFAULT_OAUTH_CALLBACK_PATH;\n\nexport function getConfiguredOAuthCallbackPort(): number {\n\treturn configuredOAuthCallbackPort;\n}\n\nexport function getOAuthCallbackPort(): number {\n\treturn oauthCallbackPort;\n}\n\nexport function setOAuthCallbackPort(port: number): void {\n\toauthCallbackPort = port;\n}\n\nexport function getOAuthCallbackPath(): string {\n\treturn oauthCallbackPath;\n}\n\nexport function setOAuthCallbackPath(path: string): void {\n\toauthCallbackPath = path.startsWith(\"/\") ? path : `/${path}`;\n}\n\n/** Configuration options for OAuth */\nexport interface McpOAuthConfig {\n\tgrantType?: \"authorization_code\" | \"client_credentials\";\n\tclientId?: string;\n\tclientSecret?: string;\n\tscope?: string;\n\tauthorizationParams?: Record<string, string>;\n\tredirectUri?: string;\n\tclientName?: string;\n\tclientUri?: string;\n\tlogoUri?: string;\n\tskipIssuerMetadataValidation?: boolean;\n}\n\nconst reservedAuthorizationParams = new Set([\n\t\"client_id\",\n\t\"code_challenge\",\n\t\"code_challenge_method\",\n\t\"redirect_uri\",\n\t\"resource\",\n\t\"response_type\",\n\t\"scope\",\n\t\"state\",\n]);\n\nfunction addAuthorizationParams(authorizationUrl: URL, params: Record<string, string> | undefined): URL {\n\tif (!params) return authorizationUrl;\n\tconst nextUrl = new URL(authorizationUrl.toString());\n\tfor (const [key, value] of Object.entries(params)) {\n\t\tif (reservedAuthorizationParams.has(key) || nextUrl.searchParams.has(key)) {\n\t\t\tthrow new Error(`OAuth authorizationParams.${key} cannot override an authorization flow parameter`);\n\t\t}\n\t\tnextUrl.searchParams.set(key, value);\n\t}\n\treturn nextUrl;\n}\n\n/** Callbacks for OAuth flow interactions */\nexport interface McpOAuthCallbacks {\n\tonRedirect: (url: URL) => void | Promise<void>;\n}\n\n/**\n * OAuth provider implementation for MCP servers.\n * Implements the OAuthClientProvider interface from the MCP SDK.\n */\nexport class McpOAuthProvider implements OAuthClientProvider {\n\tprivate readonly redirectUrlSnapshot: string | undefined;\n\tprivate active = true;\n\tprivate flowClientInfo: StoredClientInfo | undefined;\n\tprivate flowCodeVerifier: string | undefined;\n\tprivate flowDiscoveryState: OAuthDiscoveryState | undefined;\n\tprivate flowIssuerMismatch = false;\n\tprivate flowState: string | undefined;\n\tprivate serverName: string;\n\tprivate serverUrl: string;\n\tprivate config: McpOAuthConfig;\n\tprivate callbacks: McpOAuthCallbacks;\n\tprivate storageOptions: AuthStorageOptions;\n\tprivate runtimeSignal: AbortSignal | undefined;\n\n\tconstructor(\n\t\tserverName: string,\n\t\tserverUrl: string,\n\t\tconfig: McpOAuthConfig,\n\t\tcallbacks: McpOAuthCallbacks,\n\t\tstorageOptions: AuthStorageOptions = {},\n\t\truntimeSignal?: AbortSignal,\n\t\tinitialState?: string,\n\t) {\n\t\tthis.serverName = serverName;\n\t\tthis.serverUrl = serverUrl;\n\t\tthis.config = config;\n\t\tthis.callbacks = callbacks;\n\t\tthis.storageOptions = storageOptions;\n\t\tthis.runtimeSignal = runtimeSignal;\n\t\tthis.flowState = initialState;\n\t\tthis.redirectUrlSnapshot =\n\t\t\tconfig.grantType === \"client_credentials\"\n\t\t\t\t? undefined\n\t\t\t\t: (config.redirectUri ?? `http://localhost:${getOAuthCallbackPort()}${getOAuthCallbackPath()}`);\n\t}\n\n\tprivate get usesClientCredentials(): boolean {\n\t\treturn this.config.grantType === \"client_credentials\";\n\t}\n\n\tprivate get discoveredIssuer(): string | undefined {\n\t\treturn (\n\t\t\tthis.flowDiscoveryState?.authorizationServerMetadata?.issuer ?? this.flowDiscoveryState?.authorizationServerUrl\n\t\t);\n\t}\n\n\tdeactivate(): void {\n\t\tthis.active = false;\n\t}\n\n\tprivate assertStoredIssuerBindings(entry: AuthEntry | undefined, issuer: string | undefined): void {\n\t\tif (this.flowIssuerMismatch) {\n\t\t\tthrow new Error(\n\t\t\t\t`OAuth authorization server issuer changed for ${this.serverName}; clear credentials before authenticating again`,\n\t\t\t);\n\t\t}\n\t\tif (!entry || !issuer) return;\n\n\t\tconst storedIssuers = [entry.clientInfo?.issuer, entry.tokens?.issuer].filter(\n\t\t\t(storedIssuer): storedIssuer is string => storedIssuer !== undefined,\n\t\t);\n\t\tif (storedIssuers.some((storedIssuer) => !issuersMatch(storedIssuer, issuer))) {\n\t\t\tthis.flowIssuerMismatch = true;\n\t\t\tthrow new Error(\n\t\t\t\t`OAuth authorization server issuer changed for ${this.serverName}; clear credentials before authenticating again`,\n\t\t\t);\n\t\t}\n\t}\n\n\tprivate throwIfInactive(): void {\n\t\tif (!this.active) throw new Error(\"OAuth flow is no longer active\");\n\t\tthis.runtimeSignal?.throwIfAborted();\n\t}\n\n\t/**\n\t * The redirect URL for OAuth callbacks.\n\t * This must match the redirect_uri in client metadata.\n\t */\n\tget redirectUrl(): string | undefined {\n\t\treturn this.redirectUrlSnapshot;\n\t}\n\n\t/** Configured homepage, otherwise the Nexus repository. */\n\tprivate get clientUri(): string | undefined {\n\t\treturn this.config.clientUri ?? defaultClientUri();\n\t}\n\n\t/**\n\t * Client metadata for dynamic registration.\n\t * Describes this client to the OAuth authorization server.\n\t */\n\tget clientMetadata(): OAuthClientMetadata {\n\t\tif (this.usesClientCredentials) {\n\t\t\treturn {\n\t\t\t\tclient_name: this.config.clientName ?? defaultClientName(),\n\t\t\t\t...(this.clientUri !== undefined ? { client_uri: this.clientUri } : {}),\n\t\t\t\t...(this.config.logoUri !== undefined ? { logo_uri: this.config.logoUri } : {}),\n\t\t\t\tredirect_uris: [],\n\t\t\t\tgrant_types: [\"client_credentials\"],\n\t\t\t\ttoken_endpoint_auth_method: this.config.clientSecret ? \"client_secret_post\" : \"none\",\n\t\t\t};\n\t\t}\n\n\t\tconst redirectUrl = this.redirectUrl;\n\t\tif (!redirectUrl) {\n\t\t\tthrow new Error(\"redirectUrl is required for authorization_code flow\");\n\t\t}\n\n\t\treturn {\n\t\t\tredirect_uris: [redirectUrl],\n\t\t\tclient_name: this.config.clientName ?? defaultClientName(),\n\t\t\t...(this.clientUri !== undefined ? { client_uri: this.clientUri } : {}),\n\t\t\t...(this.config.logoUri !== undefined ? { logo_uri: this.config.logoUri } : {}),\n\t\t\tgrant_types: [\"authorization_code\", \"refresh_token\"],\n\t\t\tresponse_types: [\"code\"],\n\t\t\ttoken_endpoint_auth_method: this.config.clientSecret ? \"client_secret_post\" : \"none\",\n\t\t\t...(this.config.scope !== undefined ? { scope: this.config.scope } : {}),\n\t\t};\n\t}\n\n\t/**\n\t * Get client information (for pre-registered or dynamically registered clients).\n\t * Returns undefined if no client info exists or if the server URL has changed.\n\t */\n\tasync clientInformation(): Promise<OAuthClientInformationMixed | undefined> {\n\t\tconst issuer = this.discoveredIssuer;\n\t\tconst stored = await getAuthForUrl(this.serverName, this.serverUrl, this.storageOptions);\n\t\tthis.assertStoredIssuerBindings(stored, issuer);\n\n\t\t// Check config first (pre-registered client). Store only its issuer binding.\n\t\t// The configured secret stays in config and never enters the credential store.\n\t\tif (this.config.clientId) {\n\t\t\tconst storedClient = stored?.clientInfo?.clientId === this.config.clientId ? stored.clientInfo : undefined;\n\t\t\tif (issuer && (storedClient?.issuer !== issuer || storedClient.configPreRegistered !== true)) {\n\t\t\t\tupdateClientInfo(\n\t\t\t\t\tthis.serverName,\n\t\t\t\t\t{ clientId: this.config.clientId, issuer, configPreRegistered: true },\n\t\t\t\t\tthis.serverUrl,\n\t\t\t\t\tthis.storageOptions,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst clientSecret = this.config.clientSecret?.startsWith(\"!\")\n\t\t\t\t? resolveCommandSecret(this.config.clientSecret, `MCP server \"${this.serverName}\" OAuth clientSecret`)\n\t\t\t\t: this.config.clientSecret;\n\t\t\treturn {\n\t\t\t\tclient_id: this.config.clientId,\n\t\t\t\tclient_secret: clientSecret,\n\t\t\t\t...(issuer !== undefined ? { issuer } : {}),\n\t\t\t} as IssuerBoundClientInformation;\n\t\t}\n\n\t\t// Keep client registration associated with this in-flight flow even if\n\t\t// another runtime writes the shared persistent entry for the same name.\n\t\tconst clientInfo = this.flowClientInfo ?? stored?.clientInfo;\n\t\tif (clientInfo) {\n\t\t\t// A stored SEP-2352 issuer stub for a config-pre-registered client\n\t\t\t// (identified by its explicit marker) is only meaningful\n\t\t\t// when the config supplies the matching client secret. Since we reach\n\t\t\t// this branch only when config.clientId is absent, serving the stub\n\t\t\t// would let a token refresh go out with a client_id but no secret,\n\t\t\t// causing invalid_client and credential invalidation. Return undefined\n\t\t\t// so callers treat this as \"no client info\".\n\t\t\tconst isConfigStub = clientInfo.configPreRegistered === true;\n\t\t\tif (isConfigStub) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\t\t\t// Check if client secret has expired\n\t\t\tif (clientInfo.clientSecretExpiresAt && clientInfo.clientSecretExpiresAt < Date.now() / 1000) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\t\t\tif (issuer && clientInfo.issuer && !issuersMatch(clientInfo.issuer, issuer)) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\t\t\tif (issuer && clientInfo.issuer === undefined) {\n\t\t\t\tclientInfo.issuer = issuer;\n\t\t\t\tthis.flowClientInfo = clientInfo;\n\t\t\t\tupdateClientInfo(this.serverName, clientInfo, this.serverUrl, this.storageOptions);\n\t\t\t}\n\t\t\t// Return all registration metadata and the local issuer extension.\n\t\t\t// This keeps the SDK OAuth view and the stored issuer binding consistent.\n\t\t\treturn {\n\t\t\t\tclient_id: clientInfo.clientId,\n\t\t\t\tclient_secret: clientInfo.clientSecret,\n\t\t\t\t...(clientInfo.clientIdIssuedAt !== undefined ? { client_id_issued_at: clientInfo.clientIdIssuedAt } : {}),\n\t\t\t\t...(clientInfo.clientSecretExpiresAt !== undefined\n\t\t\t\t\t? { client_secret_expires_at: clientInfo.clientSecretExpiresAt }\n\t\t\t\t\t: {}),\n\t\t\t\t...(clientInfo.redirectUris !== undefined ? { redirect_uris: clientInfo.redirectUris } : {}),\n\t\t\t\t...(clientInfo.issuer !== undefined ? { issuer: clientInfo.issuer } : {}),\n\t\t\t} as IssuerBoundClientInformation;\n\t\t}\n\n\t\t// No client info or URL changed - will trigger dynamic registration\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Save client information from dynamic registration.\n\t */\n\tasync saveClientInformation(info: OAuthClientInformationMixed): Promise<void> {\n\t\tthis.throwIfInactive();\n\t\tconst issuer = this.discoveredIssuer ?? (info as IssuerBoundClientInformation).issuer;\n\t\tif (this.config.clientId && info.client_id === this.config.clientId) {\n\t\t\tupdateClientInfo(\n\t\t\t\tthis.serverName,\n\t\t\t\t{\n\t\t\t\t\tclientId: info.client_id,\n\t\t\t\t\t...(issuer !== undefined ? { issuer } : {}),\n\t\t\t\t\tconfigPreRegistered: true,\n\t\t\t\t},\n\t\t\t\tthis.serverUrl,\n\t\t\t\tthis.storageOptions,\n\t\t\t);\n\t\t\treturn;\n\t\t}\n\n\t\tconst redirectUris =\n\t\t\t(\"redirect_uris\" in info ? info.redirect_uris : undefined) ??\n\t\t\t(this.redirectUrl ? [this.redirectUrl] : undefined);\n\t\tconst clientInfo: StoredClientInfo = {\n\t\t\tclientId: info.client_id,\n\t\t\t...(info.client_secret !== undefined ? { clientSecret: info.client_secret } : {}),\n\t\t\t...(info.client_id_issued_at !== undefined ? { clientIdIssuedAt: info.client_id_issued_at } : {}),\n\t\t\t...(info.client_secret_expires_at !== undefined\n\t\t\t\t? { clientSecretExpiresAt: info.client_secret_expires_at }\n\t\t\t\t: {}),\n\t\t\t...(redirectUris !== undefined ? { redirectUris } : {}),\n\t\t\t...(issuer !== undefined ? { issuer } : {}),\n\t\t};\n\t\tthis.flowClientInfo = clientInfo;\n\t\tupdateClientInfo(this.serverName, clientInfo, this.serverUrl, this.storageOptions);\n\t}\n\n\t/**\n\t * Get stored OAuth tokens.\n\t * Returns undefined if no tokens exist or if the server URL has changed.\n\t */\n\tasync tokens(): Promise<OAuthTokens | undefined> {\n\t\t// Use getAuthForUrl to validate tokens are for the current server URL.\n\t\tconst entry = await getAuthForUrl(this.serverName, this.serverUrl, this.storageOptions);\n\t\tif (!entry?.tokens) return undefined;\n\t\tconst issuer = this.discoveredIssuer;\n\t\tthis.assertStoredIssuerBindings(entry, issuer);\n\t\tif (issuer && entry.tokens.issuer === undefined) {\n\t\t\tentry.tokens.issuer = issuer;\n\t\t\tupdateTokens(this.serverName, entry.tokens, this.serverUrl, this.storageOptions);\n\t\t}\n\n\t\treturn {\n\t\t\taccess_token: entry.tokens.accessToken,\n\t\t\ttoken_type: \"Bearer\",\n\t\t\trefresh_token: entry.tokens.refreshToken,\n\t\t\texpires_in:\n\t\t\t\tentry.tokens.expiresAt !== undefined\n\t\t\t\t\t? Math.max(0, Math.floor(entry.tokens.expiresAt - Date.now() / 1000))\n\t\t\t\t\t: undefined,\n\t\t\tscope: entry.tokens.scope,\n\t\t\t...(entry.tokens.issuer !== undefined ? { issuer: entry.tokens.issuer } : {}),\n\t\t} as IssuerBoundTokens;\n\t}\n\n\t/**\n\t * Save OAuth tokens.\n\t */\n\tasync saveTokens(tokens: OAuthTokens): Promise<void> {\n\t\tconst issuer = this.discoveredIssuer ?? (tokens as IssuerBoundTokens).issuer;\n\t\tconst storedTokens: StoredTokens = {\n\t\t\taccessToken: tokens.access_token,\n\t\t\t...(tokens.refresh_token !== undefined ? { refreshToken: tokens.refresh_token } : {}),\n\t\t\t// Preserve expiry even when expires_in is 0 (e.g. the SDK re-saving an\n\t\t\t// already-expired token) so expired tokens stay expired instead of\n\t\t\t// being persisted as never-expiring.\n\t\t\t...(tokens.expires_in !== undefined ? { expiresAt: Date.now() / 1000 + tokens.expires_in } : {}),\n\t\t\t...(tokens.scope !== undefined ? { scope: tokens.scope } : {}),\n\t\t\t...(issuer !== undefined ? { issuer } : {}),\n\t\t};\n\t\tthis.throwIfInactive();\n\t\tupdateTokens(this.serverName, storedTokens, this.serverUrl, this.storageOptions);\n\t\t// Discovery must survive the browser redirect so the callback can verify\n\t\t// the authorization server that minted the code. Once token issuance\n\t\t// succeeds, clear it so a later 401 re-reads PRM and can observe an\n\t\t// authorization-server migration.\n\t\tthis.flowDiscoveryState = undefined;\n\t}\n\n\t/**\n\t * Redirect the user to the authorization URL.\n\t * This opens the browser for the user to authenticate.\n\t *\n\t * Throws UnauthorizedError when called outside of a user-initiated flow\n\t * (no oauthState saved by startAuth). That path is reached when the SDK\n\t * falls through from a failed refresh into a fresh authorization_code\n\t * flow, which library hosts cannot complete in-process.\n\t */\n\tasync redirectToAuthorization(authorizationUrl: URL): Promise<void> {\n\t\tif (this.usesClientCredentials) {\n\t\t\tthrow new Error(\"redirectToAuthorization is not used for client_credentials flow\");\n\t\t}\n\t\t// No flow-local state means we're on the post-refresh authorize fallback.\n\t\tthis.throwIfInactive();\n\t\tif (!this.flowState) {\n\t\t\tthrow new UnauthorizedError(`Re-authentication required for MCP server: ${this.serverName}`);\n\t\t}\n\t\t// URL is passed to callback, not logged (may contain sensitive params)\n\t\tawait this.callbacks.onRedirect(addAuthorizationParams(authorizationUrl, this.config.authorizationParams));\n\t}\n\n\t/**\n\t * Save the PKCE code verifier.\n\t */\n\tasync saveCodeVerifier(codeVerifier: string): Promise<void> {\n\t\tthis.throwIfInactive();\n\t\tthis.flowCodeVerifier = codeVerifier;\n\t}\n\n\t/**\n\t * Get the stored PKCE code verifier.\n\t * @throws Error if no code verifier is stored\n\t */\n\tasync codeVerifier(): Promise<string> {\n\t\tif (this.usesClientCredentials) {\n\t\t\tthrow new Error(\"codeVerifier is not used for client_credentials flow\");\n\t\t}\n\t\tthis.throwIfInactive();\n\t\tif (!this.flowCodeVerifier) {\n\t\t\tthrow new Error(`No code verifier saved for MCP server: ${this.serverName}`);\n\t\t}\n\t\treturn this.flowCodeVerifier;\n\t}\n\n\t/**\n\t * Keep discovery with the in-flight PKCE verifier. The callback leg uses it\n\t * to validate the authorization response issuer before token exchange.\n\t */\n\tasync saveDiscoveryState(state: OAuthDiscoveryState): Promise<void> {\n\t\tthis.throwIfInactive();\n\t\tthis.flowDiscoveryState = structuredClone(state);\n\t}\n\n\tasync discoveryState(): Promise<OAuthDiscoveryState | undefined> {\n\t\tthis.throwIfInactive();\n\t\treturn this.flowDiscoveryState ? structuredClone(this.flowDiscoveryState) : undefined;\n\t}\n\n\t/**\n\t * Save the OAuth state parameter for CSRF protection.\n\t */\n\tasync saveState(state: string): Promise<void> {\n\t\tthis.throwIfInactive();\n\t\tthis.flowState = state;\n\t}\n\n\t/**\n\t * Get the stored OAuth state parameter.\n\t * @throws UnauthorizedError if no flow is in progress (see redirectToAuthorization)\n\t */\n\tasync state(): Promise<string> {\n\t\tif (this.usesClientCredentials) {\n\t\t\tthrow new Error(\"state is not used for client_credentials flow\");\n\t\t}\n\t\tthis.throwIfInactive();\n\t\tif (!this.flowState) {\n\t\t\tthrow new UnauthorizedError(`Re-authentication required for MCP server: ${this.serverName}`);\n\t\t}\n\t\treturn this.flowState;\n\t}\n\n\t/**\n\t * Invalidate credentials when authentication fails.\n\t * Clears tokens, client info, or all credentials based on the type.\n\t */\n\tasync invalidateCredentials(type: \"all\" | \"client\" | \"tokens\" | \"verifier\" | \"discovery\"): Promise<void> {\n\t\tthis.throwIfInactive();\n\t\tswitch (type) {\n\t\t\tcase \"all\":\n\t\t\t\tthis.flowClientInfo = undefined;\n\t\t\t\tthis.flowCodeVerifier = undefined;\n\t\t\t\tthis.flowDiscoveryState = undefined;\n\t\t\t\tthis.flowIssuerMismatch = false;\n\t\t\t\tthis.flowState = undefined;\n\t\t\t\tclearAllCredentials(this.serverName, this.storageOptions);\n\t\t\t\tbreak;\n\t\t\tcase \"client\":\n\t\t\t\tthis.flowClientInfo = undefined;\n\t\t\t\tclearClientInfo(this.serverName, this.storageOptions);\n\t\t\t\tbreak;\n\t\t\tcase \"tokens\":\n\t\t\t\tclearTokens(this.serverName, this.storageOptions);\n\t\t\t\tbreak;\n\t\t\tcase \"verifier\":\n\t\t\t\tclearCodeVerifier(this.serverName, this.storageOptions);\n\t\t\t\tbreak;\n\t\t\tcase \"discovery\":\n\t\t\t\tthis.flowDiscoveryState = undefined;\n\t\t\t\tbreak;\n\t\t}\n\t}\n\n\t/**\n\t * Adds configured authorization-code scope without replacing the SDK's\n\t * default token endpoint authentication behavior.\n\t */\n\taddClientAuthentication: AddClientAuthentication = async (headers, params, _url, metadata) => {\n\t\tthis.throwIfInactive();\n\t\tif (params.get(\"grant_type\") === \"authorization_code\" && !params.has(\"scope\") && this.config.scope) {\n\t\t\tparams.set(\"scope\", this.config.scope);\n\t\t}\n\n\t\tconst clientInfo = await this.clientInformation();\n\t\tthis.throwIfInactive();\n\t\tif (!clientInfo) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst supportedMethods = metadata?.token_endpoint_auth_methods_supported ?? [];\n\t\tconst hasClientSecret = clientInfo.client_secret !== undefined;\n\t\tlet authMethod: \"client_secret_basic\" | \"client_secret_post\" | \"none\";\n\n\t\tif (supportedMethods.length === 0) {\n\t\t\tauthMethod = hasClientSecret ? \"client_secret_post\" : \"none\";\n\t\t} else if (hasClientSecret && supportedMethods.includes(\"client_secret_basic\")) {\n\t\t\tauthMethod = \"client_secret_basic\";\n\t\t} else if (hasClientSecret && supportedMethods.includes(\"client_secret_post\")) {\n\t\t\tauthMethod = \"client_secret_post\";\n\t\t} else if (supportedMethods.includes(\"none\")) {\n\t\t\tauthMethod = \"none\";\n\t\t} else {\n\t\t\tauthMethod = hasClientSecret ? \"client_secret_post\" : \"none\";\n\t\t}\n\n\t\tif (authMethod === \"client_secret_basic\") {\n\t\t\tif (!clientInfo.client_secret) {\n\t\t\t\tthrow new Error(\"client_secret_basic authentication requires a client_secret\");\n\t\t\t}\n\t\t\theaders.set(\n\t\t\t\t\"Authorization\",\n\t\t\t\t`Basic ${Buffer.from(`${clientInfo.client_id}:${clientInfo.client_secret}`).toString(\"base64\")}`,\n\t\t\t);\n\t\t\treturn;\n\t\t}\n\n\t\tif (!params.has(\"client_id\")) {\n\t\t\tparams.set(\"client_id\", clientInfo.client_id);\n\t\t}\n\t\tif (authMethod === \"client_secret_post\" && clientInfo.client_secret && !params.has(\"client_secret\")) {\n\t\t\tparams.set(\"client_secret\", clientInfo.client_secret);\n\t\t}\n\t};\n\n\tprepareTokenRequest(scope?: string): URLSearchParams | undefined {\n\t\tif (!this.usesClientCredentials) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst params = new URLSearchParams({ grant_type: \"client_credentials\" });\n\t\tconst requestedScope = scope ?? this.config.scope;\n\t\tif (requestedScope) {\n\t\t\tparams.set(\"scope\", requestedScope);\n\t\t}\n\t\treturn params;\n\t}\n}\n\nexport { DEFAULT_OAUTH_CALLBACK_PORT, DEFAULT_OAUTH_CALLBACK_PATH };\n"]}