@adcp/sdk 14.3.0 → 15.0.0

package/dist/lib/index.mjs

@@ -445,7 +445,8 @@ import {
   resolveSecret,
   isEnvSecretReference,
   toEnvSecretReference,
-  extractEnvSecretName
+  extractEnvSecretName,
+  AgentOAuthClientCredentialsSchema
 } from "./auth/oauth/index.mjs";
 import { validateAgentUrl, validateAdCPResponse, getExpectedSchema, handleAdCPResponse } from "./validation/index.mjs";
 import {
@@ -847,6 +848,7 @@ export {
   AdagentsJsonSchema,
   AgentClient,
   AgentNotFoundError,
+  AgentOAuthClientCredentialsSchema,
   Asset,
   AsyncHandler,
   AuthenticationCredentialsRejectedError,

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/index.d.mts

@@ -46,6 +46,8 @@ import type { KnownToolRequestSchemas } from '../utils/tool-request-schemas.mjs'
 import { getSchemaDocumentByRef, type Direction, type ResolvedToolSchemaDocument, type ResponseVariant } from '../validation/schema-loader.mjs';
 import type { ValidateFunction } from 'ajv';
 export * from '../types/schemas.generated.mjs';
+export { AgentOAuthClientCredentialsSchema } from '../auth/oauth/client-credentials-schema.mjs';
+export type { AgentOAuthClientCredentials } from '../types/adcp.mjs';
 export type { PlacementPresentationDocument, PlacementPresentationReference } from '../types/core.generated.mjs';
 type LooseObjectShapeFor<T extends object> = {
     [K in keyof T]-?: undefined extends T[K] ? z.ZodOptional<z.ZodType<Exclude<T[K], undefined>, Exclude<T[K], undefined>>> : z.ZodType<T[K], T[K]>;

package/dist/lib/schemas/index.d.ts

@@ -46,6 +46,8 @@ import type { KnownToolRequestSchemas } from '../utils/tool-request-schemas';
 import { getSchemaDocumentByRef, type Direction, type ResolvedToolSchemaDocument, type ResponseVariant } from '../validation/schema-loader';
 import type { ValidateFunction } from 'ajv';
 export * from '../types/schemas.generated';
+export { AgentOAuthClientCredentialsSchema } from '../auth/oauth/client-credentials-schema';
+export type { AgentOAuthClientCredentials } from '../types/adcp';
 export type { PlacementPresentationDocument, PlacementPresentationReference } from '../types/core.generated';
 type LooseObjectShapeFor<T extends object> = {
     [K in keyof T]-?: undefined extends T[K] ? z.ZodOptional<z.ZodType<Exclude<T[K], undefined>, Exclude<T[K], undefined>>> : z.ZodType<T[K], T[K]>;

package/dist/lib/schemas/index.js

@@ -29,6 +29,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var schemas_exports = {};
 __export(schemas_exports, {
+  AgentOAuthClientCredentialsSchema: () => import_client_credentials_schema.AgentOAuthClientCredentialsSchema,
   BiddingPolicySchema: () => import_bidding_policy.BiddingPolicySchema,
   CanonicalBudgetAllocationSchema: () => import_budget_allocation.CanonicalBudgetAllocationSchema,
   GetProductsRequestSchema: () => GetProductsRequestSchema,
@@ -56,6 +57,7 @@ var import_tool_request_schemas = require('../utils/tool-request-schemas.js');
 var import_schema_loader = require('../validation/schema-loader.js');
 var import_adcp_version_config = require('../utils/adcp-version-config.js');
 __reExport(schemas_exports, require('../types/schemas.generated.js'), module.exports);
+var import_client_credentials_schema = require('../auth/oauth/client-credentials-schema.js');
 var import_bidding_policy = require('../validation/bidding-policy.js');
 var import_budget_allocation = require('../validation/budget-allocation.js');
 var import_tool_request_schemas2 = require('../utils/tool-request-schemas.js');
@@ -114,6 +116,7 @@ function customToolForSchema(name, description, inputSchema, handler) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AgentOAuthClientCredentialsSchema,
   BiddingPolicySchema,
   CanonicalBudgetAllocationSchema,
   GetProductsRequestSchema,

package/dist/lib/schemas/index.mjs

@@ -9,6 +9,7 @@ import {
 } from "../validation/schema-loader.mjs";
 import { resolveAdcpVersion } from "../utils/adcp-version-config.mjs";
 export * from "../types/schemas.generated.mjs";
+import { AgentOAuthClientCredentialsSchema } from "../auth/oauth/client-credentials-schema.mjs";
 const LegacyGetProductsRequestSchema = schemas.GetProductsRequestSchema;
 const canonicalGetProductsFields = GetProductsRequest_FieldsValues.filter(
   (field) => field !== "format_ids"
@@ -71,6 +72,7 @@ function customToolForSchema(name, description, inputSchema, handler) {
   return { description, inputSchema, handler };
 }
 export {
+  AgentOAuthClientCredentialsSchema,
   BiddingPolicySchema,
   CanonicalBudgetAllocationSchema,
   GetProductsRequestSchema,

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-07T00:14:46.446Z"
 }

package/dist/lib/testing/client.js

@@ -52,6 +52,7 @@ var import_node_crypto = require("node:crypto");
 var import_client_hooks = require('../validation/client-hooks.js');
 var import_error_extraction = require('../utils/error-extraction.js');
 var import_client = require('../signing/client.js');
+var import_storage_registry = require('../auth/oauth/storage-registry.js');
 const TEST_CLIENT_VERSION_OPTIONS = /* @__PURE__ */ Symbol("adcp.testClientVersionOptions");
 const TEST_CLIENT_SCOPE_SALT = (0, import_node_crypto.randomBytes)(32);
 function resolveAuthPrincipal(options) {
@@ -123,6 +124,7 @@ function createTestClient(agentUrl, protocol = "mcp", options = {}) {
     } else if (options.auth.type === "oauth") {
       agentConfig.oauth_tokens = options.auth.tokens;
       if (options.auth.client) agentConfig.oauth_client = options.auth.client;
+      if (options.auth.storage) (0, import_storage_registry.bindAgentStorage)(agentConfig, options.auth.storage);
     } else if (options.auth.type === "oauth_client_credentials") {
       agentConfig.oauth_client_credentials = options.auth.credentials;
       if (options.auth.tokens) agentConfig.oauth_tokens = options.auth.tokens;
@@ -160,6 +162,7 @@ function createTestClient(agentUrl, protocol = "mcp", options = {}) {
       ...authMode !== void 0 && { authMode },
       ...requestScopeMode !== void 0 && { requestScopeMode },
       ...requestSigningMode !== void 0 && { requestSigningMode },
+      ...options.auth?.type === "oauth" && options.auth.storage && { oauthStorage: options.auth.storage },
       ...options.transport?.trustedFetchFn && { fetchFn: options.transport.trustedFetchFn },
       ...options.transport?.allowPrivateIp !== void 0 && { allowPrivateIp: options.transport.allowPrivateIp },
       ...options.transport?.maxResponseBytes !== void 0 && {
@@ -198,13 +201,14 @@ function testClientMatchesVersionOptions(client, agentUrl, options) {
   const expectedAuthMode = authReuseMode(effectiveOptions);
   const expectedRequestScopeMode = requestScopeReuseMode(effectiveOptions);
   const expectedRequestSigningMode = requestSigningReuseMode(effectiveOptions.functional_request_signing);
+  const expectedOAuthStorage = effectiveOptions.auth?.type === "oauth" ? effectiveOptions.auth.storage : void 0;
   if (!meta) {
-    return expectedRequestSigningMode === void 0 && effectiveOptions.adcpVersion === void 0 && effectiveOptions.versionEnvelope === void 0 && effectiveOptions.transport === void 0;
+    return expectedOAuthStorage === void 0 && expectedRequestSigningMode === void 0 && effectiveOptions.adcpVersion === void 0 && effectiveOptions.versionEnvelope === void 0 && effectiveOptions.transport === void 0;
   }
   const expectedAdcpVersion = effectiveOptions.adcpVersion ?? import_version.ADCP_VERSION;
   const expectedWireAdcpVersion = effectiveOptions.wireAdcpVersion;
   const expectedVersionEnvelope = effectiveOptions.versionEnvelope ?? "auto";
-  return meta.agentUrl === agentUrl && meta.protocol === (effectiveOptions.protocol ?? "mcp") && meta.adcpVersion === expectedAdcpVersion && meta.wireAdcpVersion === expectedWireAdcpVersion && meta.versionEnvelope === expectedVersionEnvelope && meta.strictResponseSchemaValidation === (effectiveOptions.strictResponseSchemaValidation !== false) && meta.authMode === expectedAuthMode && meta.requestScopeMode === expectedRequestScopeMode && meta.requestSigningMode === expectedRequestSigningMode && meta.fetchFn === effectiveOptions.transport?.trustedFetchFn && meta.allowPrivateIp === effectiveOptions.transport?.allowPrivateIp && meta.maxResponseBytes === effectiveOptions.transport?.maxResponseBytes && meta.requestTimeoutMs === effectiveOptions.transport?.requestTimeoutMs && meta.legacyCompatEnabled === effectiveOptions.transport?.legacyCompat?.enabled;
+  return meta.agentUrl === agentUrl && meta.protocol === (effectiveOptions.protocol ?? "mcp") && meta.adcpVersion === expectedAdcpVersion && meta.wireAdcpVersion === expectedWireAdcpVersion && meta.versionEnvelope === expectedVersionEnvelope && meta.strictResponseSchemaValidation === (effectiveOptions.strictResponseSchemaValidation !== false) && meta.authMode === expectedAuthMode && meta.requestScopeMode === expectedRequestScopeMode && meta.requestSigningMode === expectedRequestSigningMode && meta.oauthStorage === expectedOAuthStorage && meta.fetchFn === effectiveOptions.transport?.trustedFetchFn && meta.allowPrivateIp === effectiveOptions.transport?.allowPrivateIp && meta.maxResponseBytes === effectiveOptions.transport?.maxResponseBytes && meta.requestTimeoutMs === effectiveOptions.transport?.requestTimeoutMs && meta.legacyCompatEnabled === effectiveOptions.transport?.legacyCompat?.enabled;
 }
 function withTestKitAuthDefaults(options) {
   if (options.auth) return options;
@@ -240,9 +244,10 @@ function requestScopeReuseMode(options) {
     Object.entries(options.headers).map(([name, value]) => [name.toLowerCase(), value]).sort(([a], [b]) => a.localeCompare(b))
   ) : void 0;
   if (!options.auth && !headers && !options.test_session_id && !options.userAgent) return void 0;
+  const auth = options.auth?.type === "oauth" ? { ...options.auth, storage: void 0 } : options.auth;
   return testClientScopeDisambiguator(
     JSON.stringify({
-      auth: options.auth,
+      auth,
       headers,
       testSessionId: options.test_session_id,
       userAgent: options.userAgent

package/dist/lib/testing/client.mjs

@@ -12,6 +12,7 @@ import { createHmac, hkdfSync, randomBytes } from "node:crypto";
 import { validateIncomingResponse } from "../validation/client-hooks.mjs";
 import { extractVersionUnsupportedDetails } from "../utils/error-extraction.mjs";
 import { buildAgentSigningContext } from "../signing/client.mjs";
+import { bindAgentStorage } from "../auth/oauth/storage-registry.mjs";
 const TEST_CLIENT_VERSION_OPTIONS = /* @__PURE__ */ Symbol("adcp.testClientVersionOptions");
 const TEST_CLIENT_SCOPE_SALT = randomBytes(32);
 function resolveAuthPrincipal(options) {
@@ -83,6 +84,7 @@ function createTestClient(agentUrl, protocol = "mcp", options = {}) {
     } else if (options.auth.type === "oauth") {
       agentConfig.oauth_tokens = options.auth.tokens;
       if (options.auth.client) agentConfig.oauth_client = options.auth.client;
+      if (options.auth.storage) bindAgentStorage(agentConfig, options.auth.storage);
     } else if (options.auth.type === "oauth_client_credentials") {
       agentConfig.oauth_client_credentials = options.auth.credentials;
       if (options.auth.tokens) agentConfig.oauth_tokens = options.auth.tokens;
@@ -120,6 +122,7 @@ function createTestClient(agentUrl, protocol = "mcp", options = {}) {
       ...authMode !== void 0 && { authMode },
       ...requestScopeMode !== void 0 && { requestScopeMode },
       ...requestSigningMode !== void 0 && { requestSigningMode },
+      ...options.auth?.type === "oauth" && options.auth.storage && { oauthStorage: options.auth.storage },
       ...options.transport?.trustedFetchFn && { fetchFn: options.transport.trustedFetchFn },
       ...options.transport?.allowPrivateIp !== void 0 && { allowPrivateIp: options.transport.allowPrivateIp },
       ...options.transport?.maxResponseBytes !== void 0 && {
@@ -158,13 +161,14 @@ function testClientMatchesVersionOptions(client, agentUrl, options) {
   const expectedAuthMode = authReuseMode(effectiveOptions);
   const expectedRequestScopeMode = requestScopeReuseMode(effectiveOptions);
   const expectedRequestSigningMode = requestSigningReuseMode(effectiveOptions.functional_request_signing);
+  const expectedOAuthStorage = effectiveOptions.auth?.type === "oauth" ? effectiveOptions.auth.storage : void 0;
   if (!meta) {
-    return expectedRequestSigningMode === void 0 && effectiveOptions.adcpVersion === void 0 && effectiveOptions.versionEnvelope === void 0 && effectiveOptions.transport === void 0;
+    return expectedOAuthStorage === void 0 && expectedRequestSigningMode === void 0 && effectiveOptions.adcpVersion === void 0 && effectiveOptions.versionEnvelope === void 0 && effectiveOptions.transport === void 0;
   }
   const expectedAdcpVersion = effectiveOptions.adcpVersion ?? ADCP_VERSION;
   const expectedWireAdcpVersion = effectiveOptions.wireAdcpVersion;
   const expectedVersionEnvelope = effectiveOptions.versionEnvelope ?? "auto";
-  return meta.agentUrl === agentUrl && meta.protocol === (effectiveOptions.protocol ?? "mcp") && meta.adcpVersion === expectedAdcpVersion && meta.wireAdcpVersion === expectedWireAdcpVersion && meta.versionEnvelope === expectedVersionEnvelope && meta.strictResponseSchemaValidation === (effectiveOptions.strictResponseSchemaValidation !== false) && meta.authMode === expectedAuthMode && meta.requestScopeMode === expectedRequestScopeMode && meta.requestSigningMode === expectedRequestSigningMode && meta.fetchFn === effectiveOptions.transport?.trustedFetchFn && meta.allowPrivateIp === effectiveOptions.transport?.allowPrivateIp && meta.maxResponseBytes === effectiveOptions.transport?.maxResponseBytes && meta.requestTimeoutMs === effectiveOptions.transport?.requestTimeoutMs && meta.legacyCompatEnabled === effectiveOptions.transport?.legacyCompat?.enabled;
+  return meta.agentUrl === agentUrl && meta.protocol === (effectiveOptions.protocol ?? "mcp") && meta.adcpVersion === expectedAdcpVersion && meta.wireAdcpVersion === expectedWireAdcpVersion && meta.versionEnvelope === expectedVersionEnvelope && meta.strictResponseSchemaValidation === (effectiveOptions.strictResponseSchemaValidation !== false) && meta.authMode === expectedAuthMode && meta.requestScopeMode === expectedRequestScopeMode && meta.requestSigningMode === expectedRequestSigningMode && meta.oauthStorage === expectedOAuthStorage && meta.fetchFn === effectiveOptions.transport?.trustedFetchFn && meta.allowPrivateIp === effectiveOptions.transport?.allowPrivateIp && meta.maxResponseBytes === effectiveOptions.transport?.maxResponseBytes && meta.requestTimeoutMs === effectiveOptions.transport?.requestTimeoutMs && meta.legacyCompatEnabled === effectiveOptions.transport?.legacyCompat?.enabled;
 }
 function withTestKitAuthDefaults(options) {
   if (options.auth) return options;
@@ -200,9 +204,10 @@ function requestScopeReuseMode(options) {
     Object.entries(options.headers).map(([name, value]) => [name.toLowerCase(), value]).sort(([a], [b]) => a.localeCompare(b))
   ) : void 0;
   if (!options.auth && !headers && !options.test_session_id && !options.userAgent) return void 0;
+  const auth = options.auth?.type === "oauth" ? { ...options.auth, storage: void 0 } : options.auth;
   return testClientScopeDisambiguator(
     JSON.stringify({
-      auth: options.auth,
+      auth,
       headers,
       testSessionId: options.test_session_id,
       userAgent: options.userAgent

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 = "15.0.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 = "15.0.0";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

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

@@ -88,7 +88,7 @@ export interface TestOptions {
      * - `basic`: cleartext `username` and `password`, encoded internally.
      * - `oauth`: saved OAuth tokens (access_token + refresh_token). MCP only.
      *   The library auto-refreshes on 401. Obtain tokens interactively via
-     *   `adcp --save-auth <alias> --oauth`, then pass the saved blob here for
+     *   `adcp --save-auth <alias> <url> --oauth`, then pass the saved blob here for
      *   non-interactive reuse.
      * - `oauth_client_credentials`: RFC 6749 §4.4 machine-to-machine flow.
      *   The library exchanges the secret for a fresh access token before each
@@ -106,6 +106,15 @@ export interface TestOptions {
         type: 'oauth';
         tokens: import('../types/adcp.mjs').AgentOAuthTokens;
         client?: import('../types/adcp.mjs').AgentOAuthClient;
+        /**
+         * Trusted runtime storage for refreshed OAuth configuration. Bound before
+         * client normalization; never sent to the agent. The adapter receives
+         * the testing client's ID (`test`), so capture any database context or
+         * tenant identity in the adapter itself. Shared clients require the
+         * same adapter object. Persistence alone does not coordinate concurrent
+         * refreshes of a rotating grant.
+         */
+        storage?: import('../auth/oauth/types.mjs').OAuthConfigStorage;
     } | {
         type: 'oauth_client_credentials';
         credentials: import('../types/adcp.mjs').AgentOAuthClientCredentials;

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

@@ -88,7 +88,7 @@ export interface TestOptions {
      * - `basic`: cleartext `username` and `password`, encoded internally.
      * - `oauth`: saved OAuth tokens (access_token + refresh_token). MCP only.
      *   The library auto-refreshes on 401. Obtain tokens interactively via
-     *   `adcp --save-auth <alias> --oauth`, then pass the saved blob here for
+     *   `adcp --save-auth <alias> <url> --oauth`, then pass the saved blob here for
      *   non-interactive reuse.
      * - `oauth_client_credentials`: RFC 6749 §4.4 machine-to-machine flow.
      *   The library exchanges the secret for a fresh access token before each
@@ -106,6 +106,15 @@ export interface TestOptions {
         type: 'oauth';
         tokens: import('../types/adcp').AgentOAuthTokens;
         client?: import('../types/adcp').AgentOAuthClient;
+        /**
+         * Trusted runtime storage for refreshed OAuth configuration. Bound before
+         * client normalization; never sent to the agent. The adapter receives
+         * the testing client's ID (`test`), so capture any database context or
+         * tenant identity in the adapter itself. Shared clients require the
+         * same adapter object. Persistence alone does not coordinate concurrent
+         * refreshes of a rotating grant.
+         */
+        storage?: import('../auth/oauth/types').OAuthConfigStorage;
     } | {
         type: 'oauth_client_credentials';
         credentials: import('../types/adcp').AgentOAuthClientCredentials;

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 = "15.0.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: "15.0.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-06T23:38:05.170Z";
 };
 /**
  * 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 = "15.0.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: "15.0.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-06T23:38:05.170Z";
 };
 /**
  * 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 = "15.0.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: "15.0.0",
   adcp: "3.2.1",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-06T16:34:47.947Z"
+  generatedAt: "2026-10-06T23:38:05.170Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "14.3.0";
+const LIBRARY_VERSION = "15.0.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: "15.0.0",
   adcp: "3.2.1",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-06T16:34:47.947Z"
+  generatedAt: "2026-10-06T23:38:05.170Z"
 };
 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 v15.0.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/ZOD-SCHEMAS.md

@@ -41,6 +41,25 @@ if (result.success) {
 
 ## Common Use Cases
 
+### OAuth Client Credentials Configuration
+
+`AgentOAuthClientCredentialsSchema` validates SDK configuration accepted by an API. It is available from `@adcp/sdk`, `@adcp/sdk/auth`, and `@adcp/sdk/schemas`.
+
+```typescript
+import { AgentOAuthClientCredentialsSchema } from '@adcp/sdk/schemas';
+
+const credentials = AgentOAuthClientCredentialsSchema.parse({
+  token_endpoint: 'https://auth.example.com/oauth/token',
+  client_id: 'client-id',
+  client_secret: '$ENV:ADCP_CLIENT_SECRET',
+  scope: 'adcp',
+  resource: ['https://agent.example.com'],
+  auth_method: 'basic',
+});
+```
+
+The schema requires a valid `token_endpoint` URL and non-empty `client_id` and `client_secret` strings. Optional fields are `scope`, `resource` (a string or string array), `audience`, and `auth_method` (`'basic'` or `'body'`). Parsing preserves `$ENV:VAR_NAME` references and leaves omitted fields unset. Token exchange resolves secrets and enforces HTTPS, URL userinfo, and private-address restrictions; this schema validates the configuration shape.
+
 ### API Request Validation
 
 ```typescript

package/docs/guides/OAUTH-ISSUER-BINDING.md

@@ -0,0 +1,46 @@
+# OAuth authorization-server binding
+
+Major migration: background defaults and partial storage.
+
+Refresh tokens/confidential clients need independently trusted `issuer` in
+`AgentOAuthTokens` / `AgentOAuthClient`. Missing/mismatched bindings refuse before
+secret refresh, DCR or replacement (`oauth_issuer_required` / `oauth_issuer_mismatch`).
+Access-only tokens/public clients permit missing/null issuer; refresh requires it
+even with valid access. Comparison tolerates one trailing slash, never different
+tenant paths. Metadata follows the official asymmetric issuer-echo rule.
+
+Recover: `adcp <alias> --clear-oauth`, then `adcp <alias> --oauth`.
+Clear tokens/client/verifier/discovery, keeping URL/other auth. Each issuer may come
+from trusted registration records, never PRM, unverified JWT, token-endpoint hostname
+or successful requests. Upgrades cannot restore historical trust. Trust the resource
+before fresh credentialless sign-in uses AS metadata; missing/mismatched returned
+metadata issuer refuses.
+
+Direct `MCPOAuthProvider` defaults to background; interactive opt-in:
+`allowInteractiveAuthorization: true` (CLI factories do). Background PKCE/DCR and
+token/client/all invalidation refuse (`owner_reauthorization_required`); direct
+redirects retain `interactive_required`. Discovery/verifier invalidation is private
+in background. Callers must authorize explicit `clearAuth`.
+
+Adapters must retain token/client issuer and interactive PKCE/discovery. The SDK
+revalidates restored discovery. File/custom adapters must BOTH preserve omitted
+`oauth_tokens`, `oauth_client`, `oauth_code_verifier`, `oauth_discovery_state` AND
+clear own `undefined` fields. Other fields retain backend semantics: omitted
+`oauth_resource` clears in file storage. Background token/client/configured
+client-credentials saves omit pending fields, preserving browser state created
+during HTTP. Interactive completion clears its state; background never borrows owner PKCE.
+
+Web stores must retain `PendingWebFlow.authorizationServerIssuer` and
+`clientInformation.issuer`; restart unbound flows. Check frozen AS/current client
+after metadata, before POST and before save; use the same client-bearing view at
+start/callback. Explicit fresh owner flows may present a credentialless view,
+stage DCR privately and reconstruct for callback. Applications provide ownership
+and atomic generation replacement. No distributed refresh coordination,
+grant/client CAS or spent-grant cancellation: quiesce background callers for recovery.
+
+Custom providers must preserve issuer in getters/saves. Upstream
+`ClientCredentialsProvider`, `PrivateKeyJwtProvider`, `StaticPrivateKeyJwtProvider`,
+`CrossAppAccessProvider` need independent `expectedIssuer`. Direct exchange/refresh
+helpers require caller binding checks (SDK web/diagnosis do them). Configured client
+credentials retain the exact operator token endpoint, without PRM replacement or
+credential-bearing redirects.