@adcp/sdk 14.3.0 → 15.0.0

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

@@ -1,6 +1,47 @@
-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,
+  assertOAuthServerIssuer,
+  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;
@@ -8,6 +49,8 @@ class MCPOAuthProvider {
   _clientMetadata;
   allowHttp;
   configuredResourceOverride;
+  allowInteractiveAuthorization;
+  pendingDiscoveryState;
   constructor(config) {
     this.agent = config.agent;
     this.storage = config.storage;
@@ -15,6 +58,7 @@ class MCPOAuthProvider {
     this._clientMetadata = config.clientMetadata;
     this.allowHttp = config.allowHttp === true;
     this.configuredResourceOverride = config.resourceOverride;
+    this.allowInteractiveAuthorization = config.allowInteractiveAuthorization === true;
   }
   /**
    * Create a provider for CLI usage
@@ -31,7 +75,8 @@ class MCPOAuthProvider {
       storage,
       clientMetadata,
       allowHttp: options?.allowHttp,
-      resourceOverride: options?.resourceOverride
+      resourceOverride: options?.resourceOverride,
+      allowInteractiveAuthorization: true
     });
   }
   // ========================================
@@ -72,8 +117,14 @@ class MCPOAuthProvider {
   /**
    * Load client information from agent config
    */
-  async clientInformation() {
+  async clientInformation(ctx) {
+    const issuer = this.checkIssuerContext(ctx);
+    if (issuer && !this.agent.oauth_client && !this.allowInteractiveAuthorization) {
+      throw this.ownerReauthorizationRequired();
+    }
     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;
@@ -83,13 +134,16 @@ class MCPOAuthProvider {
    */
   async saveClientInformation(clientInfo) {
     this.agent.oauth_client = fromMCPClientInfo(clientInfo);
-    await this.persistAgent();
+    await this.persistCredentials();
   }
   /**
    * Load existing tokens from agent config
    */
-  async tokens() {
+  async tokens(ctx) {
+    this.checkIssuerContext(ctx);
     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;
@@ -100,19 +154,72 @@ class MCPOAuthProvider {
    */
   async saveTokens(tokens) {
     this.agent.oauth_tokens = fromMCPTokens(tokens);
-    delete this.agent.oauth_code_verifier;
-    await this.persistAgent();
+    if (this.allowInteractiveAuthorization) {
+      this.agent.oauth_code_verifier = void 0;
+      this.agent.oauth_discovery_state = void 0;
+    }
+    this.pendingDiscoveryState = void 0;
+    await this.persistCredentials();
   }
   /**
    * Redirect user to authorization URL
    */
   async redirectToAuthorization(authorizationUrl) {
-    await this.flowHandler.redirectToAuthorization(authorizationUrl);
+    if (!this.allowInteractiveAuthorization) throw this.ownerReauthorizationRequired("interactive_required");
+    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) {
+    this.validateDiscoveryState(state);
+    if (!this.agent.oauth_client && !this.allowInteractiveAuthorization) throw this.ownerReauthorizationRequired();
+    this.pendingDiscoveryState = structuredClone(state);
+    if (this.allowInteractiveAuthorization) {
+      this.agent.oauth_discovery_state = structuredClone(state);
+      await this.persistAgent();
+    }
+  }
+  async discoveryState() {
+    if (!this.allowInteractiveAuthorization) return void 0;
+    if (!this.agent.oauth_code_verifier) return void 0;
+    const state = this.pendingDiscoveryState ?? this.agent.oauth_discovery_state;
+    if (!state) return void 0;
+    this.validateDiscoveryState(state);
+    this.pendingDiscoveryState = structuredClone(state);
+    return structuredClone(state);
+  }
+  validateDiscoveryState(state) {
+    assertOAuthServerIssuer(state.authorizationServerMetadata, String(state.authorizationServerUrl));
+    this.checkIssuerContext({ issuer: String(state.authorizationServerUrl) });
+  }
+  checkIssuerContext(ctx) {
+    const issuer = ctx?.issuer ?? this.pendingDiscoveryState?.authorizationServerUrl;
+    if (issuer !== void 0) {
+      if (this.agent.oauth_tokens) {
+        assertOAuthCredentialIssuer(this.agent.oauth_tokens, issuer, !!this.agent.oauth_tokens.refresh_token);
+      }
+      if (this.agent.oauth_client) {
+        assertOAuthCredentialIssuer(this.agent.oauth_client, issuer, !!this.agent.oauth_client.client_secret);
+      }
+    }
+    return issuer;
+  }
+  ownerReauthorizationRequired(code = "owner_reauthorization_required") {
+    return new OAuthError(
+      "OAuth owner reauthorization is required; this provider will not automatically clear credentials or register a new client. CLI: adcp <alias> --clear-oauth, then adcp <alias> --oauth.",
+      code,
+      this.agent.id
+    );
   }
   /**
    * Save PKCE code verifier
    */
   async saveCodeVerifier(codeVerifier) {
+    if (!this.allowInteractiveAuthorization) throw this.ownerReauthorizationRequired();
     this.agent.oauth_code_verifier = codeVerifier;
     await this.persistAgent();
   }
@@ -122,6 +229,7 @@ class MCPOAuthProvider {
    * retrieves it here during token exchange.
    */
   async codeVerifier() {
+    if (!this.allowInteractiveAuthorization) throw this.ownerReauthorizationRequired();
     if (!this.agent.oauth_code_verifier) {
       throw new Error(
         "No PKCE code verifier found. The OAuth flow may have been interrupted or the agent config was modified. Please try authenticating again."
@@ -133,20 +241,40 @@ class MCPOAuthProvider {
    * Invalidate credentials when server indicates they're invalid
    */
   async invalidateCredentials(scope) {
+    if (!this.allowInteractiveAuthorization && (scope === "discovery" || scope === "verifier")) {
+      this.pendingDiscoveryState = void 0;
+      return;
+    }
+    if (!this.allowInteractiveAuthorization && (scope === "all" || scope === "client" || scope === "tokens")) {
+      throw this.ownerReauthorizationRequired();
+    }
+    await this.clearCredentials(scope);
+  }
+  async clearCredentials(scope) {
     switch (scope) {
       case "all":
-        delete this.agent.oauth_tokens;
-        delete this.agent.oauth_client;
-        delete this.agent.oauth_code_verifier;
+        this.pendingDiscoveryState = void 0;
+        this.agent.oauth_discovery_state = void 0;
+        this.agent.oauth_tokens = void 0;
+        this.agent.oauth_client = void 0;
+        this.agent.oauth_code_verifier = void 0;
         break;
       case "tokens":
-        delete this.agent.oauth_tokens;
+        this.agent.oauth_tokens = void 0;
         break;
       case "client":
-        delete this.agent.oauth_client;
+        this.pendingDiscoveryState = void 0;
+        this.agent.oauth_discovery_state = void 0;
+        this.agent.oauth_client = void 0;
+        break;
+      case "discovery":
+        this.pendingDiscoveryState = void 0;
+        this.agent.oauth_discovery_state = void 0;
         break;
       case "verifier":
-        delete this.agent.oauth_code_verifier;
+        this.pendingDiscoveryState = void 0;
+        this.agent.oauth_discovery_state = void 0;
+        this.agent.oauth_code_verifier = void 0;
         break;
     }
     await this.persistAgent();
@@ -155,11 +283,20 @@ class MCPOAuthProvider {
   // Additional methods
   // ========================================
   /**
-   * Persist agent config to storage if configured
+   * Persist a credential update without modifying independent browser state.
    */
-  async persistAgent() {
+  async persistCredentials() {
+    let savedAgent = this.agent;
+    if (!this.allowInteractiveAuthorization) {
+      savedAgent = { ...this.agent };
+      delete savedAgent.oauth_code_verifier;
+      delete savedAgent.oauth_discovery_state;
+    }
+    await this.persistAgent(savedAgent);
+  }
+  async persistAgent(agent = this.agent) {
     if (this.storage) {
-      await this.storage.saveAgent(this.agent);
+      await this.storage.saveAgent(agent);
     }
   }
   /**
@@ -201,7 +338,7 @@ class MCPOAuthProvider {
    * Clear all OAuth data for this agent
    */
   async clearAuth() {
-    await this.invalidateCredentials("all");
+    await this.clearCredentials("all");
   }
   /**
    * Get the agent config this provider manages
@@ -219,5 +356,6 @@ class MCPOAuthProvider {
   }
 }
 export {
-  MCPOAuthProvider
+  MCPOAuthProvider,
+  assertLegacyOAuthSdk
 };

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

@@ -21,7 +21,7 @@ export interface NonInteractiveFlowHandlerConfig {
     redirectUrl?: string | URL;
     /**
      * Optional hint shown in the error message when a browser flow is
-     * attempted — e.g., the alias name to pass to `adcp --save-auth`.
+     * attempted — e.g., the saved alias for `adcp <alias> --oauth`.
      */
     agentHint?: string;
 }

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

@@ -21,7 +21,7 @@ export interface NonInteractiveFlowHandlerConfig {
     redirectUrl?: string | URL;
     /**
      * Optional hint shown in the error message when a browser flow is
-     * attempted — e.g., the alias name to pass to `adcp --save-auth`.
+     * attempted — e.g., the saved alias for `adcp <alias> --oauth`.
      */
     agentHint?: string;
 }

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

@@ -33,7 +33,7 @@ class NonInteractiveFlowHandler {
     return this._redirectUrl;
   }
   async redirectToAuthorization() {
-    const target = this.agentHint ? `adcp --save-auth ${this.agentHint} --oauth` : "adcp --save-auth <alias> <url> --oauth";
+    const target = this.agentHint ? `adcp ${this.agentHint} --oauth` : "adcp --save-auth <alias> <url> --oauth";
     throw new import_types.OAuthError(
       `OAuth authorization required but this context is non-interactive. Run \`${target}\` from a terminal with a browser, then retry.`,
       "interactive_required"

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

@@ -10,7 +10,7 @@ class NonInteractiveFlowHandler {
     return this._redirectUrl;
   }
   async redirectToAuthorization() {
-    const target = this.agentHint ? `adcp --save-auth ${this.agentHint} --oauth` : "adcp --save-auth <alias> <url> --oauth";
+    const target = this.agentHint ? `adcp ${this.agentHint} --oauth` : "adcp --save-auth <alias> <url> --oauth";
     throw new OAuthError(
       `OAuth authorization required but this context is non-interactive. Run \`${target}\` from a terminal with a browser, then retry.`,
       "interactive_required"

package/dist/lib/auth/oauth/client-credentials-schema.d.mts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+/**
+ * OAuth client credentials configuration shape. Secret references remain
+ * unresolved; endpoint transport and SSRF checks run during token exchange.
+ */
+export declare const AgentOAuthClientCredentialsSchema: z.ZodObject<{
+    token_endpoint: z.ZodString;
+    client_id: z.ZodString;
+    client_secret: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    resource: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    audience: z.ZodOptional<z.ZodString>;
+    auth_method: z.ZodOptional<z.ZodEnum<{
+        basic: "basic";
+        body: "body";
+    }>>;
+}, z.core.$strip>;

package/dist/lib/auth/oauth/client-credentials-schema.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+/**
+ * OAuth client credentials configuration shape. Secret references remain
+ * unresolved; endpoint transport and SSRF checks run during token exchange.
+ */
+export declare const AgentOAuthClientCredentialsSchema: z.ZodObject<{
+    token_endpoint: z.ZodString;
+    client_id: z.ZodString;
+    client_secret: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    resource: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    audience: z.ZodOptional<z.ZodString>;
+    auth_method: z.ZodOptional<z.ZodEnum<{
+        basic: "basic";
+        body: "body";
+    }>>;
+}, z.core.$strip>;

package/dist/lib/auth/oauth/client-credentials-schema.js

@@ -0,0 +1,37 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var client_credentials_schema_exports = {};
+__export(client_credentials_schema_exports, {
+  AgentOAuthClientCredentialsSchema: () => AgentOAuthClientCredentialsSchema
+});
+module.exports = __toCommonJS(client_credentials_schema_exports);
+var import_zod = require("zod");
+const AgentOAuthClientCredentialsSchema = import_zod.z.object({
+  token_endpoint: import_zod.z.string().url(),
+  client_id: import_zod.z.string().min(1),
+  client_secret: import_zod.z.string().min(1),
+  scope: import_zod.z.string().optional(),
+  resource: import_zod.z.union([import_zod.z.string(), import_zod.z.array(import_zod.z.string())]).optional(),
+  audience: import_zod.z.string().optional(),
+  auth_method: import_zod.z.enum(["basic", "body"]).optional()
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentOAuthClientCredentialsSchema
+});

package/dist/lib/auth/oauth/client-credentials-schema.mjs

@@ -0,0 +1,13 @@
+import { z } from "zod";
+const AgentOAuthClientCredentialsSchema = z.object({
+  token_endpoint: z.string().url(),
+  client_id: z.string().min(1),
+  client_secret: z.string().min(1),
+  scope: z.string().optional(),
+  resource: z.union([z.string(), z.array(z.string())]).optional(),
+  audience: z.string().optional(),
+  auth_method: z.enum(["basic", "body"]).optional()
+});
+export {
+  AgentOAuthClientCredentialsSchema
+};

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`.
+ * An own property explicitly set to undefined clears tokens, client, verifier
+ * or discovery state. Omitted properties preserve stored values for partial
+ * callers. Other fields keep their existing 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`.
+ * An own property explicitly set to undefined clears tokens, client, verifier
+ * or discovery state. Omitted properties preserve stored values for partial
+ * callers. Other fields keep their existing 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,18 @@ 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 (Object.prototype.hasOwnProperty.call(agent, "oauth_tokens") && agent.oauth_tokens === void 0) {
+        delete next.oauth_tokens;
+      }
+      if (Object.prototype.hasOwnProperty.call(agent, "oauth_client") && agent.oauth_client === void 0) {
+        delete next.oauth_client;
+      }
+      if (Object.prototype.hasOwnProperty.call(agent, "oauth_code_verifier") && agent.oauth_code_verifier === void 0) {
+        delete next.oauth_code_verifier;
+      }
+      if (Object.prototype.hasOwnProperty.call(agent, "oauth_discovery_state") && agent.oauth_discovery_state === void 0) {
+        delete next.oauth_discovery_state;
+      } else if (agent.oauth_discovery_state !== void 0) 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,18 @@ 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 (Object.prototype.hasOwnProperty.call(agent, "oauth_tokens") && agent.oauth_tokens === void 0) {
+        delete next.oauth_tokens;
+      }
+      if (Object.prototype.hasOwnProperty.call(agent, "oauth_client") && agent.oauth_client === void 0) {
+        delete next.oauth_client;
+      }
+      if (Object.prototype.hasOwnProperty.call(agent, "oauth_code_verifier") && agent.oauth_code_verifier === void 0) {
+        delete next.oauth_code_verifier;
+      }
+      if (Object.prototype.hasOwnProperty.call(agent, "oauth_discovery_state") && agent.oauth_discovery_state === void 0) {
+        delete next.oauth_discovery_state;
+      } else if (agent.oauth_discovery_state !== void 0) 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/index.d.mts

@@ -5,7 +5,8 @@
  *
  * @example
  * ```typescript
- * import { MCPOAuthProvider, CLIFlowHandler } from '@adcp/sdk';
+ * import { MCPOAuthProvider, CLIFlowHandler, DEFAULT_CLIENT_METADATA } from '@adcp/sdk/auth';
+ * import type { AgentConfig } from '@adcp/sdk';
  *
  * // Agent config - tokens will be stored here
  * const agent: AgentConfig = {
@@ -13,14 +14,15 @@
  *   name: 'My Agent',
  *   agent_uri: 'https://agent.example.com/mcp',
  *   protocol: 'mcp',
- *   // After OAuth flow completes:
- *   // oauth_tokens: { access_token: '...', refresh_token: '...' }
+ *   // A fresh interactive flow saves issuer-bound tokens here.
  * };
  *
  * // Create provider with CLI flow handler
  * const provider = new MCPOAuthProvider({
+ *   allowInteractiveAuthorization: true,
  *   agent,
  *   flowHandler: new CLIFlowHandler(),
+ *   clientMetadata: DEFAULT_CLIENT_METADATA,
  *   storage: myConfigStorage  // Optional: persists tokens to file/db
  * });
  *
@@ -99,9 +101,10 @@ export declare function createCLIOAuthProvider(agent: AgentConfig, options?: {
  * runs, scheduled jobs, and other non-interactive contexts where you've
  * already saved tokens via `createCLIOAuthProvider`.
  *
- * If refresh fails (e.g., the refresh_token is revoked or expired), the
- * MCP SDK will throw `UnauthorizedError` at call time — the caller should
- * treat that as a signal to run `adcp --save-auth <alias> --oauth` and retry.
+ * A failed grant can throw `OAuthError` with `owner_reauthorization_required`;
+ * missing or mismatched issuer bindings throw `oauth_issuer_required` or `oauth_issuer_mismatch`.
+ * The owner can run `adcp <alias> --clear-oauth`, then
+ * `adcp <alias> --oauth` to start a fresh browser sign-in.
  */
 export declare function createNonInteractiveOAuthProvider(agent: AgentConfig, options?: {
     /** Hint shown in error messages if an interactive flow is attempted. */
@@ -143,5 +146,6 @@ export { createFileOAuthStorage, type FileOAuthStorageOptions } from './file-sto
 export { exchangeClientCredentials, ensureClientCredentialsTokens, ClientCredentialsExchangeError, type ExchangeClientCredentialsOptions, type EnsureClientCredentialsOptions, } from './ClientCredentialsFlow.mjs';
 export { resolveSecret, isEnvSecretReference, toEnvSecretReference, extractEnvSecretName, MissingEnvSecretError, } from './secret-resolver.mjs';
 export type { AgentOAuthClientCredentials } from '../../types/adcp.mjs';
+export { AgentOAuthClientCredentialsSchema } from './client-credentials-schema.mjs';
 export { bindAgentStorage, getAgentStorage, unbindAgentStorage } from './storage-registry.mjs';
 export { InvalidTokenError, InsufficientScopeError } from '@modelcontextprotocol/sdk/server/auth/errors.js';

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

@@ -5,7 +5,8 @@
  *
  * @example
  * ```typescript
- * import { MCPOAuthProvider, CLIFlowHandler } from '@adcp/sdk';
+ * import { MCPOAuthProvider, CLIFlowHandler, DEFAULT_CLIENT_METADATA } from '@adcp/sdk/auth';
+ * import type { AgentConfig } from '@adcp/sdk';
  *
  * // Agent config - tokens will be stored here
  * const agent: AgentConfig = {
@@ -13,14 +14,15 @@
  *   name: 'My Agent',
  *   agent_uri: 'https://agent.example.com/mcp',
  *   protocol: 'mcp',
- *   // After OAuth flow completes:
- *   // oauth_tokens: { access_token: '...', refresh_token: '...' }
+ *   // A fresh interactive flow saves issuer-bound tokens here.
  * };
  *
  * // Create provider with CLI flow handler
  * const provider = new MCPOAuthProvider({
+ *   allowInteractiveAuthorization: true,
  *   agent,
  *   flowHandler: new CLIFlowHandler(),
+ *   clientMetadata: DEFAULT_CLIENT_METADATA,
  *   storage: myConfigStorage  // Optional: persists tokens to file/db
  * });
  *
@@ -99,9 +101,10 @@ export declare function createCLIOAuthProvider(agent: AgentConfig, options?: {
  * runs, scheduled jobs, and other non-interactive contexts where you've
  * already saved tokens via `createCLIOAuthProvider`.
  *
- * If refresh fails (e.g., the refresh_token is revoked or expired), the
- * MCP SDK will throw `UnauthorizedError` at call time — the caller should
- * treat that as a signal to run `adcp --save-auth <alias> --oauth` and retry.
+ * A failed grant can throw `OAuthError` with `owner_reauthorization_required`;
+ * missing or mismatched issuer bindings throw `oauth_issuer_required` or `oauth_issuer_mismatch`.
+ * The owner can run `adcp <alias> --clear-oauth`, then
+ * `adcp <alias> --oauth` to start a fresh browser sign-in.
  */
 export declare function createNonInteractiveOAuthProvider(agent: AgentConfig, options?: {
     /** Hint shown in error messages if an interactive flow is attempted. */
@@ -143,5 +146,6 @@ export { createFileOAuthStorage, type FileOAuthStorageOptions } from './file-sto
 export { exchangeClientCredentials, ensureClientCredentialsTokens, ClientCredentialsExchangeError, type ExchangeClientCredentialsOptions, type EnsureClientCredentialsOptions, } from './ClientCredentialsFlow';
 export { resolveSecret, isEnvSecretReference, toEnvSecretReference, extractEnvSecretName, MissingEnvSecretError, } from './secret-resolver';
 export type { AgentOAuthClientCredentials } from '../../types/adcp';
+export { AgentOAuthClientCredentialsSchema } from './client-credentials-schema';
 export { bindAgentStorage, getAgentStorage, unbindAgentStorage } from './storage-registry';
 export { InvalidTokenError, InsufficientScopeError } from '@modelcontextprotocol/sdk/server/auth/errors.js';