@adcp/sdk 14.3.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,

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

@@ -30,6 +30,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",
@@ -39,6 +40,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
@@ -54,6 +56,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
@@ -61,16 +64,50 @@ 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"
+    );
+  }
+}
 export {
   DEFAULT_CLIENT_METADATA,
   OAuthCancelledError,
   OAuthError,
   OAuthTimeoutError,
+  assertOAuthCredentialIssuer,
+  assertOAuthServerIssuer,
   fromMCPClientInfo,
   fromMCPTokens,
   toMCPClientInfo,

package/dist/lib/auth/oauth/web-flow.js

@@ -144,6 +144,7 @@ async function startWebOAuthFlow(opts) {
   if (!asMetadata) {
     throw new import_types.OAuthError(`No OAuth metadata at ${asUrl.toString()}`, "no_authorization_server_metadata", agent.id);
   }
+  (0, import_types.assertOAuthServerIssuer)(asMetadata, asUrl.toString());
   const resource = resourceOverride ? new URL(resourceOverride) : prm?.resource ? new URL(prm.resource) : (0, import_auth_utils.resourceUrlFromServerUrl)(new URL(agent.agent_uri));
   const baseClientMetadata = {
     ...import_types.DEFAULT_CLIENT_METADATA,
@@ -230,6 +231,12 @@ async function completeWebOAuthFlow(opts) {
   const asMetadata = await (0, import_auth.discoverAuthorizationServerMetadata)(flow.authorizationServerUrl, {
     fetchFn: guardedFetch
   });
+  (0, import_types.assertOAuthServerIssuer)(asMetadata, flow.authorizationServerUrl);
+  (0, import_types.assertOAuthCredentialIssuer)(
+    flow.clientInformation,
+    flow.authorizationServerUrl,
+    !!flow.clientInformation.client_secret
+  );
   let tokens;
   try {
     tokens = await (0, import_auth.exchangeAuthorization)(flow.authorizationServerUrl, {
@@ -241,6 +248,7 @@ async function completeWebOAuthFlow(opts) {
       resource: flow.resource ? new URL(flow.resource) : void 0,
       fetchFn: guardedFetch
     });
+    tokens = { ...tokens, issuer: flow.authorizationServerUrl };
   } catch (err) {
     throw wrapTokenExchangeError(err);
   }
@@ -410,6 +418,7 @@ function createSsrfSafeOAuthFetch(trustedFetchFn, allowHttp) {
 async function resolveClientInformation(args) {
   const { agent, agentStorage, asUrl, asMetadata, clientMetadata, fetchFn, allowConfidentialClient } = args;
   if (agent.oauth_client) {
+    (0, import_types.assertOAuthCredentialIssuer)(agent.oauth_client, asUrl.toString(), !!agent.oauth_client.client_secret);
     return (0, import_types.toMCPClientInfo)(agent.oauth_client);
   }
   if (!asMetadata.registration_endpoint) {
@@ -419,11 +428,12 @@ async function resolveClientInformation(args) {
       agent.id
     );
   }
-  const registered = await (0, import_auth.registerClient)(asUrl.toString(), {
+  const registration = await (0, import_auth.registerClient)(asUrl.toString(), {
     metadata: asMetadata,
     clientMetadata,
     fetchFn
   });
+  const registered = { ...registration, issuer: asUrl.toString() };
   if (registered.client_secret && !allowConfidentialClient) {
     throw new ConfidentialClientNotAllowedError(agent.id);
   }

package/dist/lib/auth/oauth/web-flow.mjs

@@ -7,7 +7,15 @@ import {
   startAuthorization
 } from "@modelcontextprotocol/sdk/client/auth.js";
 import { checkResourceAllowed, resourceUrlFromServerUrl } from "@modelcontextprotocol/sdk/shared/auth-utils.js";
-import { DEFAULT_CLIENT_METADATA, fromMCPClientInfo, fromMCPTokens, OAuthError, toMCPClientInfo } from "./types.mjs";
+import {
+  DEFAULT_CLIENT_METADATA,
+  fromMCPClientInfo,
+  fromMCPTokens,
+  OAuthError,
+  toMCPClientInfo,
+  assertOAuthCredentialIssuer,
+  assertOAuthServerIssuer
+} from "./types.mjs";
 import { validateOAuthResourceUrl } from "./resource-url.mjs";
 import { ssrfSafeFetch } from "../../net/ssrf-fetch.mjs";
 const DEFAULT_WEB_FLOW_TTL_MS = 10 * 60 * 1e3;
@@ -115,6 +123,7 @@ async function startWebOAuthFlow(opts) {
   if (!asMetadata) {
     throw new OAuthError(`No OAuth metadata at ${asUrl.toString()}`, "no_authorization_server_metadata", agent.id);
   }
+  assertOAuthServerIssuer(asMetadata, asUrl.toString());
   const resource = resourceOverride ? new URL(resourceOverride) : prm?.resource ? new URL(prm.resource) : resourceUrlFromServerUrl(new URL(agent.agent_uri));
   const baseClientMetadata = {
     ...DEFAULT_CLIENT_METADATA,
@@ -201,6 +210,12 @@ async function completeWebOAuthFlow(opts) {
   const asMetadata = await discoverAuthorizationServerMetadata(flow.authorizationServerUrl, {
     fetchFn: guardedFetch
   });
+  assertOAuthServerIssuer(asMetadata, flow.authorizationServerUrl);
+  assertOAuthCredentialIssuer(
+    flow.clientInformation,
+    flow.authorizationServerUrl,
+    !!flow.clientInformation.client_secret
+  );
   let tokens;
   try {
     tokens = await exchangeAuthorization(flow.authorizationServerUrl, {
@@ -212,6 +227,7 @@ async function completeWebOAuthFlow(opts) {
       resource: flow.resource ? new URL(flow.resource) : void 0,
       fetchFn: guardedFetch
     });
+    tokens = { ...tokens, issuer: flow.authorizationServerUrl };
   } catch (err) {
     throw wrapTokenExchangeError(err);
   }
@@ -381,6 +397,7 @@ function createSsrfSafeOAuthFetch(trustedFetchFn, allowHttp) {
 async function resolveClientInformation(args) {
   const { agent, agentStorage, asUrl, asMetadata, clientMetadata, fetchFn, allowConfidentialClient } = args;
   if (agent.oauth_client) {
+    assertOAuthCredentialIssuer(agent.oauth_client, asUrl.toString(), !!agent.oauth_client.client_secret);
     return toMCPClientInfo(agent.oauth_client);
   }
   if (!asMetadata.registration_endpoint) {
@@ -390,11 +407,12 @@ async function resolveClientInformation(args) {
       agent.id
     );
   }
-  const registered = await registerClient(asUrl.toString(), {
+  const registration = await registerClient(asUrl.toString(), {
     metadata: asMetadata,
     clientMetadata,
     fetchFn
   });
+  const registered = { ...registration, issuer: asUrl.toString() };
   if (registered.client_secret && !allowConfidentialClient) {
     throw new ConfidentialClientNotAllowedError(agent.id);
   }

package/dist/lib/protocols/mcp.js

@@ -34,6 +34,7 @@ var import_streamableHttp = require("@modelcontextprotocol/sdk/client/streamable
 var import_sse = require("@modelcontextprotocol/sdk/client/sse.js");
 var import_auth = require("@modelcontextprotocol/sdk/client/auth.js");
 var import_node_crypto = require("node:crypto");
+var import_MCPOAuthProvider = require('../auth/oauth/MCPOAuthProvider.js');
 var import_auth2 = require('../auth/index.js');
 var import_errors = require('../errors/index.js');
 var import_tracing = require('../observability/tracing.js');
@@ -713,6 +714,7 @@ async function connectMCP(options) {
     fetchFn,
     allowPrivateIp
   } = options;
+  if (authProvider) (0, import_MCPOAuthProvider.assertLegacyOAuthSdk)();
   const baseUrl = new URL(agentUrl);
   debugLogs.push({
     type: "info",

package/dist/lib/protocols/mcp.mjs

@@ -11,6 +11,7 @@ import {
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
 import { hkdfSync, randomBytes } from "node:crypto";
+import { assertLegacyOAuthSdk } from "../auth/oauth/MCPOAuthProvider.mjs";
 import { createMCPRequestHeaders } from "../auth/index.mjs";
 import { is401Error } from "../errors/index.mjs";
 import { withSpan, injectTraceHeaders } from "../observability/tracing.mjs";
@@ -700,6 +701,7 @@ async function connectMCP(options) {
     fetchFn,
     allowPrivateIp
   } = options;
+  if (authProvider) assertLegacyOAuthSdk();
   const baseUrl = new URL(agentUrl);
   debugLogs.push({
     type: "info",

package/dist/lib/schemas-data/v2.5/_provenance.json

@@ -4,5 +4,5 @@
   "source_sha": "4e553ad955f83b49c7d221ab5c3ff78237ad02e3",
   "source_tarball_sha256": "580656d6466ef9f0d1119985e6726c2efea718dc671e2ad30957fcb2fd54af0f",
   "upstream_adcp_version": "2.5.3",
-  "synced_at": "2026-10-06T17:21:37.513Z"
+  "synced_at": "2026-10-06T19:28:36.184Z"
 }

package/dist/lib/testing/storyboard/validations.d.mts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "14.3.0";
+export declare const RUNNER_CAPABILITY_VERSION = "14.4.0";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/testing/storyboard/validations.d.ts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "14.3.0";
+export declare const RUNNER_CAPABILITY_VERSION = "14.4.0";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/types/adcp.d.mts

@@ -145,6 +145,8 @@ export interface DayParting {
  * OAuth tokens for agent authentication
  */
 export interface AgentOAuthTokens {
+    /** Authorization server that issued these tokens. Required when reusing a refresh token. */
+    issuer?: string;
     /** OAuth access token */
     access_token: string;
     /** OAuth refresh token (for token renewal) */
@@ -162,6 +164,8 @@ export interface AgentOAuthTokens {
  * OAuth client information (from dynamic registration)
  */
 export interface AgentOAuthClient {
+    /** Authorization server where this client was registered. Required when reusing a client secret. */
+    issuer?: string;
     /** OAuth client ID */
     client_id: string;
     /** OAuth client secret (for confidential clients) */
@@ -401,6 +405,8 @@ export interface AgentConfig {
      * authorization flow.
      */
     oauth_client_credentials?: AgentOAuthClientCredentials;
+    /** Opaque discovery state paired with the pending PKCE verifier; persist and return verbatim. */
+    oauth_discovery_state?: import('@modelcontextprotocol/sdk/client/auth.js').OAuthDiscoveryState;
     /**
      * Additional HTTP headers to include in every request to this agent.
      * Useful for sending API keys, org IDs, or other vendor-specific headers

package/dist/lib/types/adcp.d.ts

@@ -145,6 +145,8 @@ export interface DayParting {
  * OAuth tokens for agent authentication
  */
 export interface AgentOAuthTokens {
+    /** Authorization server that issued these tokens. Required when reusing a refresh token. */
+    issuer?: string;
     /** OAuth access token */
     access_token: string;
     /** OAuth refresh token (for token renewal) */
@@ -162,6 +164,8 @@ export interface AgentOAuthTokens {
  * OAuth client information (from dynamic registration)
  */
 export interface AgentOAuthClient {
+    /** Authorization server where this client was registered. Required when reusing a client secret. */
+    issuer?: string;
     /** OAuth client ID */
     client_id: string;
     /** OAuth client secret (for confidential clients) */
@@ -401,6 +405,8 @@ export interface AgentConfig {
      * authorization flow.
      */
     oauth_client_credentials?: AgentOAuthClientCredentials;
+    /** Opaque discovery state paired with the pending PKCE verifier; persist and return verbatim. */
+    oauth_discovery_state?: import('@modelcontextprotocol/sdk/client/auth.js').OAuthDiscoveryState;
     /**
      * Additional HTTP headers to include in every request to this agent.
      * Useful for sending API keys, org IDs, or other vendor-specific headers

package/dist/lib/version.d.mts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "14.3.0";
+export declare const LIBRARY_VERSION = "14.4.0";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "14.3.0";
+    readonly library: "14.4.0";
     readonly adcp: "3.2.1";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.2.1", "3.2"];
-    readonly generatedAt: "2026-10-06T16:34:47.947Z";
+    readonly generatedAt: "2026-10-06T19:00:01.077Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.d.ts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "14.3.0";
+export declare const LIBRARY_VERSION = "14.4.0";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "14.3.0";
+    readonly library: "14.4.0";
     readonly adcp: "3.2.1";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.2.1", "3.2"];
-    readonly generatedAt: "2026-10-06T16:34:47.947Z";
+    readonly generatedAt: "2026-10-06T19:00:01.077Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.js

@@ -31,7 +31,7 @@ __export(version_exports, {
   toReleasePrecisionVersion: () => toReleasePrecisionVersion
 });
 module.exports = __toCommonJS(version_exports);
-const LIBRARY_VERSION = "14.3.0";
+const LIBRARY_VERSION = "14.4.0";
 const ADCP_VERSION = "3.2.1";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -95,10 +95,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2"
 ];
 const VERSION_INFO = {
-  library: "14.3.0",
+  library: "14.4.0",
   adcp: "3.2.1",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-06T16:34:47.947Z"
+  generatedAt: "2026-10-06T19:00:01.077Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "14.3.0";
+const LIBRARY_VERSION = "14.4.0";
 const ADCP_VERSION = "3.2.1";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -62,10 +62,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2"
 ];
 const VERSION_INFO = {
-  library: "14.3.0",
+  library: "14.4.0",
   adcp: "3.2.1",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-06T16:34:47.947Z"
+  generatedAt: "2026-10-06T19:00:01.077Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
 > Generated at: 2026-10-06
-> @adcp/sdk v14.3.0
+> @adcp/sdk v14.4.0
 
 Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
 

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
 > Generated at: 2026-10-06
-> Library: @adcp/sdk v14.3.0
+> Library: @adcp/sdk v14.4.0
 > AdCP major version: 3
 > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
 > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.

package/docs/migration-14.x-rc-worksheet.md

@@ -11,8 +11,8 @@ below as the publication/deployment gate.
 
 | Fact | Value |
 | --- | --- |
-| Exact npm package | `@adcp/sdk@14.3.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@14.3.0 dist.integrity` |
+| Exact npm package | `@adcp/sdk@14.4.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@14.4.0 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.2.1` |
 | Maintained wire releases | `v2.5`, `v2.6`, `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.2.1`, `3.2` |
@@ -21,8 +21,8 @@ below as the publication/deployment gate.
 Install exact production inputs rather than a moving range or dist-tag:
 
 ```bash
-npm install --save-exact '@adcp/sdk@14.3.0'
-npm view '@adcp/sdk@14.3.0' dist.integrity
+npm install --save-exact '@adcp/sdk@14.4.0'
+npm view '@adcp/sdk@14.4.0' dist.integrity
 ```
 
 ### Required and optional peers
@@ -32,7 +32,7 @@ Install the peer packages used by your application at versions satisfying these
 | Peer | Supported range | Installation |
 | --- | --- | --- |
 | `@a2a-js/sdk` | `^1.0.1` | Required |
-| `@modelcontextprotocol/sdk` | `^1.24.0` | Required |
+| `@modelcontextprotocol/sdk` | `^1.31.0` | Required |
 | `@opentelemetry/api` | `^1.0.0` | Optional |
 | `redis` | `^4.6.0 || ^5.0.0 || ^6.0.0` | Optional |
 | `zod` | `^4.1.5` | Required |

package/docs/migration-oauth-issuer-bindings.md

@@ -0,0 +1,82 @@
+# OAuth issuer bindings
+
+The corrective release after SDK 14.3.0 upgrades the official MCP client and
+server to 2.2.0 and requires the legacy `@modelcontextprotocol/sdk` peer at
+`^1.31.0`. These versions address
+[GHSA-6qxp-vccf-f47h](https://github.com/advisories/GHSA-6qxp-vccf-f47h).
+Installations pinned to legacy SDK 1.24–1.30 must upgrade that peer dependency.
+The legacy OAuth transport rejects vulnerable versions even if package-manager
+peer checks were bypassed. The Node.js requirement remains `^20.19.0 || >=22.12.0`.
+
+OAuth refresh tokens and client secrets belong to an authorization server.
+`AgentOAuthTokens` and `AgentOAuthClient` now preserve an optional `issuer`
+field through the SDK's conversions, providers, and file storage. Newly saved
+credentials receive their binding from the authorization flow. The provider
+persists discovery alongside the pending PKCE verifier and clears that temporary
+state after exchange; a callback uses the original authorization server even if
+resource discovery changes while the browser is away. Custom `OAuthConfigStorage`
+implementations must preserve `oauth_discovery_state` alongside `oauth_code_verifier`. Web flows
+validate the discovered server's metadata issuer before registration and
+token exchange; diagnostic refreshes validate it before sending credentials.
+The provider refuses a changed authorization server before replacing a trusted
+confidential registration or reusing a refresh token. Clear credentials explicitly
+if an independently verified server migration requires a fresh registration.
+
+File storage saves the OAuth fields as an authoritative snapshot: omitted tokens,
+client, verifier, or discovery state are deleted. Load the complete agent from
+storage before creating a provider; keep unrelated persisted fields as before.
+
+## Existing saved credentials
+
+`MCPOAuthProvider` refuses to reuse a saved refresh token or client secret
+without a valid issuer, with `oauth_issuer_required`. The web flow and
+diagnostic runner also refuse mismatched bindings. Access-token-only and
+public-client configurations do not require a new field. A saved unbound refresh
+token blocks every call through the provider, even while its access token is
+still valid; clear the saved credentials before reconnecting.
+
+For a saved CLI alias, run `adcp <alias> --clear-oauth`, then
+`adcp <alias> --oauth` to sign in again.
+
+For legacy saved credentials, clear `oauth_tokens` and any confidential
+`oauth_client` registration, then sign in again. Alternatively, an operator
+may add the authorization-server issuer established independently from
+trusted registration records. **Do not infer it from the current MCP server's
+discovery metadata**, an access token's unverified claims, or its resource URL.
+If the issuer is unknown, sign in again. Raw `issuer: null` is treated as absent for access-token-only and public-client
+configurations; secrets still require a valid string issuer.
+
+```ts
+agent.oauth_tokens = {
+  ...agent.oauth_tokens!,
+  issuer: 'https://auth.example.com', // independently verified token issuer
+};
+agent.oauth_client = {
+  ...agent.oauth_client!,
+  issuer: 'https://auth.example.com', // where this client was registered
+};
+```
+
+An issuer is an authorization-server URL, including its tenant path when one
+exists. A single trailing slash difference is tolerated for credential
+comparison; distinct tenant paths remain distinct. Stored pending web flows
+containing an unbound confidential client must be restarted.
+
+## Custom providers
+
+Preserve the complete `issuer` field passed to `saveTokens()` and
+`saveClientInformation()`, and return it from the corresponding getters. Add
+an independently verified issuer to pre-registered client information. The
+upstream bundled `ClientCredentialsProvider`, `PrivateKeyJwtProvider`,
+`StaticPrivateKeyJwtProvider`, and `CrossAppAccessProvider` also need
+`expectedIssuer` configured. These are adopter-owned provider settings; a
+dependency upgrade cannot reconstruct the ownership of older credentials.
+
+Calls made directly to the upstream `exchangeAuthorization()` and
+`refreshAuthorization()` helpers need their own credential-issuer checks.
+The SDK's web-flow and diagnosis helpers perform those checks. The SDK's
+client-credentials flow uses an explicitly configured token endpoint rather
+than selecting one from MCP server discovery.
+
+If affected credentials were sent to an untrusted authorization server,
+follow the upstream advisory's credential-rotation guidance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "14.3.0",
+  "version": "14.4.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -713,10 +713,10 @@
     "email": "bugs@adcontextprotocol.org"
   },
   "dependencies": {
-    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/client": "2.2.0",
     "@modelcontextprotocol/ext-apps": "2.0.0",
     "@modelcontextprotocol/node": "2.0.0",
-    "@modelcontextprotocol/server": "2.0.0",
+    "@modelcontextprotocol/server": "2.2.0",
     "@types/ws": "^8.18.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
@@ -733,7 +733,7 @@
   },
   "peerDependencies": {
     "@a2a-js/sdk": "^1.0.1",
-    "@modelcontextprotocol/sdk": "^1.24.0",
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "@opentelemetry/api": "^1.0.0",
     "redis": "^4.6.0 || ^5.0.0 || ^6.0.0",
     "zod": "^4.1.5"
@@ -753,7 +753,7 @@
     "@changesets/cli": "^3.0.3",
     "@commitlint/cli": "^20.5.3",
     "@commitlint/config-conventional": "^20.5.3",
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "@opentelemetry/api": "^1.9.1",
     "@types/express": "4.17.25",
     "@types/node": "^20.19.43",