@adcp/sdk 14.2.0 → 14.4.0

package/bin/adcp.js

@@ -1386,9 +1386,7 @@ async function ensureOAuthTokensForAlias(alias, url, { quiet = false, allowHttp
     return existing;
   }
 
-  // Spread the in-flight PKCE verifier too: if a prior attempt crashed mid-
-  // flow the verifier lives on the saved record, and without it the MCP SDK
-  // throws "No PKCE code verifier found" when the AS redirects back.
+  // A fresh login starts a new PKCE leg and rediscovers the authorization server.
   const tempAgent = {
     id: alias,
     name: alias,
@@ -1396,7 +1394,6 @@ async function ensureOAuthTokensForAlias(alias, url, { quiet = false, allowHttp
     protocol: 'mcp',
     ...(existing?.oauth_client && { oauth_client: existing.oauth_client }),
     ...(existing?.oauth_tokens && { oauth_tokens: existing.oauth_tokens }),
-    ...(existing?.oauth_code_verifier && { oauth_code_verifier: existing.oauth_code_verifier }),
   };
 
   const { Client: MCPClient } = require('@modelcontextprotocol/sdk/client/index.js');
@@ -6671,6 +6668,7 @@ credential material — never sync or commit.
     delete agentConfig.oauth_tokens;
     delete agentConfig.oauth_client;
     delete agentConfig.oauth_code_verifier;
+    delete agentConfig.oauth_discovery_state;
     saveAgent(alias, agentConfig);
 
     console.log(`\n✅ Cleared OAuth tokens for '${alias}'`);

package/dist/lib/auth/oauth/MCPOAuthProvider.d.mts

@@ -4,8 +4,9 @@
  * Implements the MCP SDK's OAuthClientProvider interface
  * using AgentConfig for token storage.
  */
-import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { OAuthClientProvider, OAuthDiscoveryState } from '@modelcontextprotocol/sdk/client/auth.js';
 import type { OAuthClientMetadata, OAuthClientInformation, OAuthClientInformationFull, OAuthTokens, OAuthFlowHandler, OAuthProviderConfig, OAuthConfigStorage, AgentConfig } from './types.mjs';
+export declare function assertLegacyOAuthSdk(): void;
 /**
  * MCP OAuth Client Provider
  *
@@ -90,6 +91,9 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
      * Redirect user to authorization URL
      */
     redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    /** Persist the authorization-server identity across the callback leg. */
+    saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
+    discoveryState(): Promise<OAuthDiscoveryState | undefined>;
     /**
      * Save PKCE code verifier
      */
@@ -103,7 +107,7 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
     /**
      * Invalidate credentials when server indicates they're invalid
      */
-    invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier'): Promise<void>;
+    invalidateCredentials(scope: Parameters<NonNullable<OAuthClientProvider['invalidateCredentials']>>[0]): Promise<void>;
     /**
      * Persist agent config to storage if configured
      */

package/dist/lib/auth/oauth/MCPOAuthProvider.d.ts

@@ -4,8 +4,9 @@
  * Implements the MCP SDK's OAuthClientProvider interface
  * using AgentConfig for token storage.
  */
-import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { OAuthClientProvider, OAuthDiscoveryState } from '@modelcontextprotocol/sdk/client/auth.js';
 import type { OAuthClientMetadata, OAuthClientInformation, OAuthClientInformationFull, OAuthTokens, OAuthFlowHandler, OAuthProviderConfig, OAuthConfigStorage, AgentConfig } from './types';
+export declare function assertLegacyOAuthSdk(): void;
 /**
  * MCP OAuth Client Provider
  *
@@ -90,6 +91,9 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
      * Redirect user to authorization URL
      */
     redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    /** Persist the authorization-server identity across the callback leg. */
+    saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
+    discoveryState(): Promise<OAuthDiscoveryState | undefined>;
     /**
      * Save PKCE code verifier
      */
@@ -103,7 +107,7 @@ export declare class MCPOAuthProvider implements OAuthClientProvider {
     /**
      * Invalidate credentials when server indicates they're invalid
      */
-    invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier'): Promise<void>;
+    invalidateCredentials(scope: Parameters<NonNullable<OAuthClientProvider['invalidateCredentials']>>[0]): Promise<void>;
     /**
      * Persist agent config to storage if configured
      */

package/dist/lib/auth/oauth/MCPOAuthProvider.js

@@ -18,12 +18,40 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var MCPOAuthProvider_exports = {};
 __export(MCPOAuthProvider_exports, {
-  MCPOAuthProvider: () => MCPOAuthProvider
+  MCPOAuthProvider: () => MCPOAuthProvider,
+  assertLegacyOAuthSdk: () => assertLegacyOAuthSdk
 });
 module.exports = __toCommonJS(MCPOAuthProvider_exports);
 var import_types = require('./types.js');
 var import_crypto = require("crypto");
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+var import_node_module = require("node:module");
 var import_resource_url = require('./resource-url.js');
+let legacyOAuthSdkChecked = false;
+function assertLegacyOAuthSdk() {
+  if (legacyOAuthSdkChecked) return;
+  try {
+    const clientPath = (0, import_node_module.createRequire)((0, import_node_path.resolve)(__dirname, "MCPOAuthProvider.js")).resolve(
+      "@modelcontextprotocol/sdk/client/index.js"
+    );
+    const { version } = JSON.parse((0, import_node_fs.readFileSync)((0, import_node_path.resolve)((0, import_node_path.dirname)(clientPath), "../../../package.json"), "utf8"));
+    const match = typeof version === "string" && /^1\.(\d+)\.\d+$/.exec(version);
+    if (!match || Number(match[1]) < 31) {
+      throw new import_types.OAuthError(
+        "Legacy MCP OAuth requires @modelcontextprotocol/sdk >=1.31.0 within major 1. Upgrade the installed peer dependency.",
+        "mcp_oauth_sdk_upgrade_required"
+      );
+    }
+  } catch (error) {
+    if (error instanceof import_types.OAuthError) throw error;
+    throw new import_types.OAuthError(
+      "Cannot verify a patched legacy MCP SDK. Install @modelcontextprotocol/sdk ^1.31.0 and keep it external when bundling.",
+      "mcp_oauth_sdk_upgrade_required"
+    );
+  }
+  legacyOAuthSdkChecked = true;
+}
 class MCPOAuthProvider {
   agent;
   storage;
@@ -97,6 +125,8 @@ class MCPOAuthProvider {
    */
   async clientInformation() {
     if (this.agent.oauth_client) {
+      if (this.agent.oauth_client.client_secret) assertLegacyOAuthSdk();
+      (0, import_types.assertOAuthCredentialIssuer)(this.agent.oauth_client, void 0, !!this.agent.oauth_client.client_secret);
       return (0, import_types.toMCPClientInfo)(this.agent.oauth_client);
     }
     return void 0;
@@ -113,6 +143,8 @@ class MCPOAuthProvider {
    */
   async tokens() {
     if (this.agent.oauth_tokens) {
+      if (this.agent.oauth_tokens.refresh_token) assertLegacyOAuthSdk();
+      (0, import_types.assertOAuthCredentialIssuer)(this.agent.oauth_tokens, void 0, !!this.agent.oauth_tokens.refresh_token);
       return (0, import_types.toMCPTokens)(this.agent.oauth_tokens);
     }
     return void 0;
@@ -124,13 +156,34 @@ class MCPOAuthProvider {
   async saveTokens(tokens) {
     this.agent.oauth_tokens = (0, import_types.fromMCPTokens)(tokens);
     delete this.agent.oauth_code_verifier;
+    delete this.agent.oauth_discovery_state;
     await this.persistAgent();
   }
   /**
    * Redirect user to authorization URL
    */
   async redirectToAuthorization(authorizationUrl) {
-    await this.flowHandler.redirectToAuthorization(authorizationUrl);
+    try {
+      await this.flowHandler.redirectToAuthorization(authorizationUrl);
+    } catch (error) {
+      await this.invalidateCredentials("verifier");
+      throw error;
+    }
+  }
+  /** Persist the authorization-server identity across the callback leg. */
+  async saveDiscoveryState(state) {
+    const issuer = String(state.authorizationServerUrl);
+    if (this.agent.oauth_tokens?.refresh_token) {
+      (0, import_types.assertOAuthCredentialIssuer)(this.agent.oauth_tokens, issuer, true);
+    }
+    if (this.agent.oauth_client?.client_secret) {
+      (0, import_types.assertOAuthCredentialIssuer)(this.agent.oauth_client, issuer, true);
+    }
+    this.agent.oauth_discovery_state = state;
+    await this.persistAgent();
+  }
+  async discoveryState() {
+    return this.agent.oauth_code_verifier ? this.agent.oauth_discovery_state : void 0;
   }
   /**
    * Save PKCE code verifier
@@ -158,6 +211,7 @@ class MCPOAuthProvider {
   async invalidateCredentials(scope) {
     switch (scope) {
       case "all":
+        delete this.agent.oauth_discovery_state;
         delete this.agent.oauth_tokens;
         delete this.agent.oauth_client;
         delete this.agent.oauth_code_verifier;
@@ -166,9 +220,14 @@ class MCPOAuthProvider {
         delete this.agent.oauth_tokens;
         break;
       case "client":
+        delete this.agent.oauth_discovery_state;
         delete this.agent.oauth_client;
         break;
+      case "discovery":
+        delete this.agent.oauth_discovery_state;
+        break;
       case "verifier":
+        delete this.agent.oauth_discovery_state;
         delete this.agent.oauth_code_verifier;
         break;
     }
@@ -243,5 +302,6 @@ class MCPOAuthProvider {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  MCPOAuthProvider
+  MCPOAuthProvider,
+  assertLegacyOAuthSdk
 });

package/dist/lib/auth/oauth/MCPOAuthProvider.mjs

@@ -1,6 +1,46 @@
-import { DEFAULT_CLIENT_METADATA, toMCPTokens, fromMCPTokens, toMCPClientInfo, fromMCPClientInfo } from "./types.mjs";
+import { fileURLToPath as __adcpFileURLToPath } from "node:url";
+import { dirname as __adcpDirname } from "node:path";
+import { createRequire as __adcpCreateRequire } from "node:module";
+const __dirname = __adcpDirname(__adcpFileURLToPath(import.meta.url));
+const require2 = __adcpCreateRequire(import.meta.url);
+import {
+  DEFAULT_CLIENT_METADATA,
+  toMCPTokens,
+  fromMCPTokens,
+  toMCPClientInfo,
+  fromMCPClientInfo,
+  assertOAuthCredentialIssuer,
+  OAuthError
+} from "./types.mjs";
 import { randomBytes } from "crypto";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { createRequire } from "node:module";
 import { validateOAuthResourceUrl } from "./resource-url.mjs";
+let legacyOAuthSdkChecked = false;
+function assertLegacyOAuthSdk() {
+  if (legacyOAuthSdkChecked) return;
+  try {
+    const clientPath = createRequire(resolve(__dirname, "MCPOAuthProvider.js")).resolve(
+      "@modelcontextprotocol/sdk/client/index.js"
+    );
+    const { version } = JSON.parse(readFileSync(resolve(dirname(clientPath), "../../../package.json"), "utf8"));
+    const match = typeof version === "string" && /^1\.(\d+)\.\d+$/.exec(version);
+    if (!match || Number(match[1]) < 31) {
+      throw new OAuthError(
+        "Legacy MCP OAuth requires @modelcontextprotocol/sdk >=1.31.0 within major 1. Upgrade the installed peer dependency.",
+        "mcp_oauth_sdk_upgrade_required"
+      );
+    }
+  } catch (error) {
+    if (error instanceof OAuthError) throw error;
+    throw new OAuthError(
+      "Cannot verify a patched legacy MCP SDK. Install @modelcontextprotocol/sdk ^1.31.0 and keep it external when bundling.",
+      "mcp_oauth_sdk_upgrade_required"
+    );
+  }
+  legacyOAuthSdkChecked = true;
+}
 class MCPOAuthProvider {
   agent;
   storage;
@@ -74,6 +114,8 @@ class MCPOAuthProvider {
    */
   async clientInformation() {
     if (this.agent.oauth_client) {
+      if (this.agent.oauth_client.client_secret) assertLegacyOAuthSdk();
+      assertOAuthCredentialIssuer(this.agent.oauth_client, void 0, !!this.agent.oauth_client.client_secret);
       return toMCPClientInfo(this.agent.oauth_client);
     }
     return void 0;
@@ -90,6 +132,8 @@ class MCPOAuthProvider {
    */
   async tokens() {
     if (this.agent.oauth_tokens) {
+      if (this.agent.oauth_tokens.refresh_token) assertLegacyOAuthSdk();
+      assertOAuthCredentialIssuer(this.agent.oauth_tokens, void 0, !!this.agent.oauth_tokens.refresh_token);
       return toMCPTokens(this.agent.oauth_tokens);
     }
     return void 0;
@@ -101,13 +145,34 @@ class MCPOAuthProvider {
   async saveTokens(tokens) {
     this.agent.oauth_tokens = fromMCPTokens(tokens);
     delete this.agent.oauth_code_verifier;
+    delete this.agent.oauth_discovery_state;
     await this.persistAgent();
   }
   /**
    * Redirect user to authorization URL
    */
   async redirectToAuthorization(authorizationUrl) {
-    await this.flowHandler.redirectToAuthorization(authorizationUrl);
+    try {
+      await this.flowHandler.redirectToAuthorization(authorizationUrl);
+    } catch (error) {
+      await this.invalidateCredentials("verifier");
+      throw error;
+    }
+  }
+  /** Persist the authorization-server identity across the callback leg. */
+  async saveDiscoveryState(state) {
+    const issuer = String(state.authorizationServerUrl);
+    if (this.agent.oauth_tokens?.refresh_token) {
+      assertOAuthCredentialIssuer(this.agent.oauth_tokens, issuer, true);
+    }
+    if (this.agent.oauth_client?.client_secret) {
+      assertOAuthCredentialIssuer(this.agent.oauth_client, issuer, true);
+    }
+    this.agent.oauth_discovery_state = state;
+    await this.persistAgent();
+  }
+  async discoveryState() {
+    return this.agent.oauth_code_verifier ? this.agent.oauth_discovery_state : void 0;
   }
   /**
    * Save PKCE code verifier
@@ -135,6 +200,7 @@ class MCPOAuthProvider {
   async invalidateCredentials(scope) {
     switch (scope) {
       case "all":
+        delete this.agent.oauth_discovery_state;
         delete this.agent.oauth_tokens;
         delete this.agent.oauth_client;
         delete this.agent.oauth_code_verifier;
@@ -143,9 +209,14 @@ class MCPOAuthProvider {
         delete this.agent.oauth_tokens;
         break;
       case "client":
+        delete this.agent.oauth_discovery_state;
         delete this.agent.oauth_client;
         break;
+      case "discovery":
+        delete this.agent.oauth_discovery_state;
+        break;
       case "verifier":
+        delete this.agent.oauth_discovery_state;
         delete this.agent.oauth_code_verifier;
         break;
     }
@@ -219,5 +290,6 @@ class MCPOAuthProvider {
   }
 }
 export {
-  MCPOAuthProvider
+  MCPOAuthProvider,
+  assertLegacyOAuthSdk
 };

package/dist/lib/auth/oauth/diagnose.js

@@ -23,6 +23,7 @@ __export(diagnose_exports, {
 });
 module.exports = __toCommonJS(diagnose_exports);
 var import_net = require('../../net/index.js');
+var import_types = require('./types.js');
 var import_diagnostics = require('./diagnostics.js');
 const AUTH_DIAGNOSIS_SCHEMA_VERSION = 1;
 async function runAuthDiagnosis(agent, options = {}) {
@@ -48,6 +49,17 @@ async function runAuthDiagnosis(agent, options = {}) {
   if (!options.skipRefresh && agent.oauth_tokens?.refresh_token) {
     const tokenEndpoint = extractTokenEndpoint(asCapture);
     const clientId = agent.oauth_client?.client_id;
+    let issuerError;
+    if (tokenEndpoint && clientId) {
+      try {
+        const issuer = new URL(extractIssuer(prmCapture) ?? "").toString();
+        (0, import_types.assertOAuthServerIssuer)(asCapture.body, issuer);
+        (0, import_types.assertOAuthCredentialIssuer)(agent.oauth_tokens, issuer, true);
+        (0, import_types.assertOAuthCredentialIssuer)(agent.oauth_client, issuer, !!agent.oauth_client?.client_secret);
+      } catch (error) {
+        issuerError = error instanceof import_types.OAuthError ? error.message : "Authorization-server issuer could not be validated";
+      }
+    }
     const resource = agentUrl;
     if (!tokenEndpoint) {
       steps.push({
@@ -59,6 +71,8 @@ async function runAuthDiagnosis(agent, options = {}) {
         name: "token_refresh_attempt",
         error: "No saved oauth_client.client_id \u2014 cannot attempt refresh without it"
       });
+    } else if (issuerError) {
+      steps.push({ name: "token_refresh_attempt", error: issuerError });
     } else {
       const refreshCapture = await attemptTokenRefresh({
         tokenEndpoint,

package/dist/lib/auth/oauth/diagnose.mjs

@@ -1,4 +1,5 @@
 import { ssrfSafeFetch, decodeBodyAsJsonOrText, SsrfRefusedError } from "../../net/index.mjs";
+import { assertOAuthCredentialIssuer, assertOAuthServerIssuer, OAuthError } from "./types.mjs";
 import { decodeAccessTokenClaims, parseWWWAuthenticate, validateTokenAudience } from "./diagnostics.mjs";
 const AUTH_DIAGNOSIS_SCHEMA_VERSION = 1;
 async function runAuthDiagnosis(agent, options = {}) {
@@ -24,6 +25,17 @@ async function runAuthDiagnosis(agent, options = {}) {
   if (!options.skipRefresh && agent.oauth_tokens?.refresh_token) {
     const tokenEndpoint = extractTokenEndpoint(asCapture);
     const clientId = agent.oauth_client?.client_id;
+    let issuerError;
+    if (tokenEndpoint && clientId) {
+      try {
+        const issuer = new URL(extractIssuer(prmCapture) ?? "").toString();
+        assertOAuthServerIssuer(asCapture.body, issuer);
+        assertOAuthCredentialIssuer(agent.oauth_tokens, issuer, true);
+        assertOAuthCredentialIssuer(agent.oauth_client, issuer, !!agent.oauth_client?.client_secret);
+      } catch (error) {
+        issuerError = error instanceof OAuthError ? error.message : "Authorization-server issuer could not be validated";
+      }
+    }
     const resource = agentUrl;
     if (!tokenEndpoint) {
       steps.push({
@@ -35,6 +47,8 @@ async function runAuthDiagnosis(agent, options = {}) {
         name: "token_refresh_attempt",
         error: "No saved oauth_client.client_id \u2014 cannot attempt refresh without it"
       });
+    } else if (issuerError) {
+      steps.push({ name: "token_refresh_attempt", error: issuerError });
     } else {
       const refreshCapture = await attemptTokenRefresh({
         tokenEndpoint,

package/dist/lib/auth/oauth/file-storage.d.mts

@@ -28,8 +28,10 @@ export interface FileOAuthStorageOptions {
  *
  * Does NOT touch fields outside the OAuth envelope (`auth_token`, custom
  * fields) when saving — the MCP provider only mutates `oauth_tokens`,
- * `oauth_client`, `oauth_resource`, and `oauth_code_verifier`, and we preserve
- * everything else.
+ * `oauth_client`, `oauth_resource`, `oauth_code_verifier`, and `oauth_discovery_state`.
+ * Those fields are authoritative: an absent value deletes the stored value.
+ * Load the complete agent before constructing a provider; partial snapshots
+ * cannot preserve omitted OAuth fields. Other fields keep merge semantics.
  *
  * @example
  * ```ts

package/dist/lib/auth/oauth/file-storage.d.ts

@@ -28,8 +28,10 @@ export interface FileOAuthStorageOptions {
  *
  * Does NOT touch fields outside the OAuth envelope (`auth_token`, custom
  * fields) when saving — the MCP provider only mutates `oauth_tokens`,
- * `oauth_client`, `oauth_resource`, and `oauth_code_verifier`, and we preserve
- * everything else.
+ * `oauth_client`, `oauth_resource`, `oauth_code_verifier`, and `oauth_discovery_state`.
+ * Those fields are authoritative: an absent value deletes the stored value.
+ * Load the complete agent before constructing a provider; partial snapshots
+ * cannot preserve omitted OAuth fields. Other fields keep merge semantics.
  *
  * @example
  * ```ts

package/dist/lib/auth/oauth/file-storage.js

@@ -75,7 +75,8 @@ function createFileOAuthStorage(options) {
         oauth_client: stored.oauth_client,
         oauth_resource: stored.oauth_resource,
         oauth_client_credentials: stored.oauth_client_credentials,
-        oauth_code_verifier: stored.oauth_code_verifier
+        oauth_code_verifier: stored.oauth_code_verifier,
+        oauth_discovery_state: stored.oauth_discovery_state
       };
     },
     async saveAgent(agent) {
@@ -93,6 +94,11 @@ function createFileOAuthStorage(options) {
         ...agent.oauth_client_credentials !== void 0 ? { oauth_client_credentials: agent.oauth_client_credentials } : {},
         ...agent.oauth_code_verifier !== void 0 ? { oauth_code_verifier: agent.oauth_code_verifier } : {}
       };
+      if (agent.oauth_tokens === void 0) delete next.oauth_tokens;
+      if (agent.oauth_client === void 0) delete next.oauth_client;
+      if (agent.oauth_code_verifier === void 0) delete next.oauth_code_verifier;
+      if (agent.oauth_discovery_state === void 0) delete next.oauth_discovery_state;
+      else next.oauth_discovery_state = agent.oauth_discovery_state;
       if (agent.oauth_resource === void 0) delete next.oauth_resource;
       config.agents[key] = next;
       await writeConfig(config);

package/dist/lib/auth/oauth/file-storage.mjs

@@ -42,7 +42,8 @@ function createFileOAuthStorage(options) {
         oauth_client: stored.oauth_client,
         oauth_resource: stored.oauth_resource,
         oauth_client_credentials: stored.oauth_client_credentials,
-        oauth_code_verifier: stored.oauth_code_verifier
+        oauth_code_verifier: stored.oauth_code_verifier,
+        oauth_discovery_state: stored.oauth_discovery_state
       };
     },
     async saveAgent(agent) {
@@ -60,6 +61,11 @@ function createFileOAuthStorage(options) {
         ...agent.oauth_client_credentials !== void 0 ? { oauth_client_credentials: agent.oauth_client_credentials } : {},
         ...agent.oauth_code_verifier !== void 0 ? { oauth_code_verifier: agent.oauth_code_verifier } : {}
       };
+      if (agent.oauth_tokens === void 0) delete next.oauth_tokens;
+      if (agent.oauth_client === void 0) delete next.oauth_client;
+      if (agent.oauth_code_verifier === void 0) delete next.oauth_code_verifier;
+      if (agent.oauth_discovery_state === void 0) delete next.oauth_discovery_state;
+      else next.oauth_discovery_state = agent.oauth_discovery_state;
       if (agent.oauth_resource === void 0) delete next.oauth_resource;
       config.agents[key] = next;
       await writeConfig(config);

package/dist/lib/auth/oauth/types.d.mts

@@ -13,6 +13,8 @@ export type { AgentConfig, AgentOAuthTokens, AgentOAuthClient };
  * Agent config storage interface
  *
  * Implement this to persist OAuth tokens back to agent configuration.
+ * Round-trip pending `oauth_code_verifier` and `oauth_discovery_state` verbatim,
+ * and remove OAuth fields absent from the authoritative agent snapshot.
  * This allows different storage backends (file, database, memory)
  * while keeping tokens in the agent config structure.
  */
@@ -132,3 +134,11 @@ export declare function toMCPClientInfo(client: AgentOAuthClient): OAuthClientIn
  * Convert MCP SDK OAuthClientInformationFull to AgentOAuthClient format
  */
 export declare function fromMCPClientInfo(info: OAuthClientInformationFull): AgentOAuthClient;
+/** Internal credential-binding guard; old secrets must be migrated from trusted configuration. */
+export declare function assertOAuthCredentialIssuer(credential: {
+    issuer?: unknown;
+}, expectedIssuer?: string, requireIssuer?: boolean): void;
+/** Internal metadata guard, matching the modern MCP SDK's asymmetric issuer-echo rule. */
+export declare function assertOAuthServerIssuer(metadata: {
+    issuer?: unknown;
+} | undefined, authorizationServerUrl: string): void;

package/dist/lib/auth/oauth/types.d.ts

@@ -13,6 +13,8 @@ export type { AgentConfig, AgentOAuthTokens, AgentOAuthClient };
  * Agent config storage interface
  *
  * Implement this to persist OAuth tokens back to agent configuration.
+ * Round-trip pending `oauth_code_verifier` and `oauth_discovery_state` verbatim,
+ * and remove OAuth fields absent from the authoritative agent snapshot.
  * This allows different storage backends (file, database, memory)
  * while keeping tokens in the agent config structure.
  */
@@ -132,3 +134,11 @@ export declare function toMCPClientInfo(client: AgentOAuthClient): OAuthClientIn
  * Convert MCP SDK OAuthClientInformationFull to AgentOAuthClient format
  */
 export declare function fromMCPClientInfo(info: OAuthClientInformationFull): AgentOAuthClient;
+/** Internal credential-binding guard; old secrets must be migrated from trusted configuration. */
+export declare function assertOAuthCredentialIssuer(credential: {
+    issuer?: unknown;
+}, expectedIssuer?: string, requireIssuer?: boolean): void;
+/** Internal metadata guard, matching the modern MCP SDK's asymmetric issuer-echo rule. */
+export declare function assertOAuthServerIssuer(metadata: {
+    issuer?: unknown;
+} | undefined, authorizationServerUrl: string): void;

package/dist/lib/auth/oauth/types.js

@@ -22,6 +22,8 @@ __export(types_exports, {
   OAuthCancelledError: () => OAuthCancelledError,
   OAuthError: () => OAuthError,
   OAuthTimeoutError: () => OAuthTimeoutError,
+  assertOAuthCredentialIssuer: () => assertOAuthCredentialIssuer,
+  assertOAuthServerIssuer: () => assertOAuthServerIssuer,
   fromMCPClientInfo: () => fromMCPClientInfo,
   fromMCPTokens: () => fromMCPTokens,
   toMCPClientInfo: () => toMCPClientInfo,
@@ -60,6 +62,7 @@ class OAuthTimeoutError extends OAuthError {
 }
 function toMCPTokens(tokens) {
   return {
+    ...tokens.issuer !== void 0 && tokens.issuer !== null && { issuer: tokens.issuer },
     access_token: tokens.access_token,
     refresh_token: tokens.refresh_token,
     token_type: tokens.token_type || "Bearer",
@@ -69,6 +72,7 @@ function toMCPTokens(tokens) {
 }
 function fromMCPTokens(tokens) {
   const result = {
+    ...tokens.issuer !== void 0 && tokens.issuer !== null && { issuer: tokens.issuer },
     access_token: tokens.access_token,
     token_type: tokens.token_type,
     scope: tokens.scope
@@ -84,6 +88,7 @@ function fromMCPTokens(tokens) {
 }
 function toMCPClientInfo(client) {
   return {
+    ...client.issuer !== void 0 && client.issuer !== null && { issuer: client.issuer },
     client_id: client.client_id,
     client_secret: client.client_secret,
     client_secret_expires_at: client.client_secret_expires_at
@@ -91,17 +96,51 @@ function toMCPClientInfo(client) {
 }
 function fromMCPClientInfo(info) {
   return {
+    ...info.issuer !== void 0 && info.issuer !== null && { issuer: info.issuer },
     client_id: info.client_id,
     client_secret: info.client_secret,
     client_secret_expires_at: info.client_secret_expires_at
   };
 }
+function isOAuthIssuer(value) {
+  if (typeof value !== "string" || value.length === 0) return false;
+  try {
+    const url = new URL(value);
+    return (url.protocol === "https:" || url.protocol === "http:") && !url.username && !url.password && !url.search && !url.hash;
+  } catch {
+    return false;
+  }
+}
+function assertOAuthCredentialIssuer(credential, expectedIssuer, requireIssuer = false) {
+  const issuer = credential.issuer;
+  if ((issuer === void 0 || issuer === null) && !requireIssuer) return;
+  if (!isOAuthIssuer(issuer)) {
+    throw new OAuthError(
+      "Saved OAuth credentials need a valid issuer. Clear them and sign in again, or set their issuer from trusted configuration.",
+      "oauth_issuer_required"
+    );
+  }
+  if (expectedIssuer !== void 0 && issuer !== expectedIssuer && !(issuer.endsWith("/") && issuer.slice(0, -1) === expectedIssuer) && !(expectedIssuer.endsWith("/") && expectedIssuer.slice(0, -1) === issuer)) {
+    throw new OAuthError("OAuth credentials belong to a different authorization server.", "oauth_issuer_mismatch");
+  }
+}
+function assertOAuthServerIssuer(metadata, authorizationServerUrl) {
+  const issuer = metadata?.issuer;
+  if (!isOAuthIssuer(issuer) || issuer !== authorizationServerUrl && !(authorizationServerUrl.endsWith("/") && issuer === authorizationServerUrl.slice(0, -1))) {
+    throw new OAuthError(
+      "Authorization-server metadata does not match the discovered issuer.",
+      "oauth_issuer_mismatch"
+    );
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_CLIENT_METADATA,
   OAuthCancelledError,
   OAuthError,
   OAuthTimeoutError,
+  assertOAuthCredentialIssuer,
+  assertOAuthServerIssuer,
   fromMCPClientInfo,
   fromMCPTokens,
   toMCPClientInfo,