@adcp/sdk 14.4.0 → 15.0.0

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

@@ -124,6 +124,8 @@ async function startWebOAuthFlow(opts) {
     throw new OAuthError(`No OAuth metadata at ${asUrl.toString()}`, "no_authorization_server_metadata", agent.id);
   }
   assertOAuthServerIssuer(asMetadata, asUrl.toString());
+  const authorizationServerIssuer = asUrl.toString();
+  assertSavedCredentialIssuers(agent, authorizationServerIssuer);
   const resource = resourceOverride ? new URL(resourceOverride) : prm?.resource ? new URL(prm.resource) : resourceUrlFromServerUrl(new URL(agent.agent_uri));
   const baseClientMetadata = {
     ...DEFAULT_CLIENT_METADATA,
@@ -138,7 +140,8 @@ async function startWebOAuthFlow(opts) {
     asMetadata,
     clientMetadata: baseClientMetadata,
     fetchFn: guardedFetch,
-    allowConfidentialClient
+    allowConfidentialClient,
+    issuer: authorizationServerIssuer
   });
   const state = (generateState ?? defaultGenerateState)();
   const { authorizationUrl, codeVerifier } = await startAuthorization(asUrl.toString(), {
@@ -166,6 +169,7 @@ async function startWebOAuthFlow(opts) {
     resourceOverrideSnapshot: agent.oauth_resource ?? null,
     scope,
     authorizationServerUrl: asUrl.toString(),
+    authorizationServerIssuer,
     clientInformation,
     createdAt: now,
     expiresAt,
@@ -211,11 +215,16 @@ async function completeWebOAuthFlow(opts) {
     fetchFn: guardedFetch
   });
   assertOAuthServerIssuer(asMetadata, flow.authorizationServerUrl);
+  assertFrozenIssuer(flow);
   assertOAuthCredentialIssuer(
     flow.clientInformation,
-    flow.authorizationServerUrl,
+    flow.authorizationServerIssuer,
     !!flow.clientInformation.client_secret
   );
+  if (agentStorage) {
+    agentForPersistence = await agentStorage.loadAgent(flow.agentId);
+    assertAgentUnchangedForFlow(agentForPersistence, flow);
+  }
   let tokens;
   try {
     tokens = await exchangeAuthorization(flow.authorizationServerUrl, {
@@ -227,7 +236,7 @@ async function completeWebOAuthFlow(opts) {
       resource: flow.resource ? new URL(flow.resource) : void 0,
       fetchFn: guardedFetch
     });
-    tokens = { ...tokens, issuer: flow.authorizationServerUrl };
+    tokens = { ...tokens, issuer: flow.authorizationServerIssuer };
   } catch (err) {
     throw wrapTokenExchangeError(err);
   }
@@ -241,7 +250,8 @@ async function completeWebOAuthFlow(opts) {
     } else if (flow.resourceOverrideAction === "clear") {
       delete agentForPersistence.oauth_resource;
     }
-    delete agentForPersistence.oauth_code_verifier;
+    agentForPersistence.oauth_code_verifier = void 0;
+    agentForPersistence.oauth_discovery_state = void 0;
     await agentStorage.saveAgent(agentForPersistence);
     persisted = true;
   }
@@ -253,6 +263,20 @@ async function completeWebOAuthFlow(opts) {
     persisted
   };
 }
+function assertSavedCredentialIssuers(agent, issuer) {
+  if (agent.oauth_tokens) assertOAuthCredentialIssuer(agent.oauth_tokens, issuer, !!agent.oauth_tokens.refresh_token);
+  if (agent.oauth_client) assertOAuthCredentialIssuer(agent.oauth_client, issuer, !!agent.oauth_client.client_secret);
+}
+function assertFrozenIssuer(flow) {
+  if (!flow.authorizationServerIssuer) {
+    throw new OAuthError(
+      "Pending OAuth flow lacks a validated authorization-server issuer. Start a new owner sign-in.",
+      "oauth_issuer_required",
+      flow.agentId
+    );
+  }
+  assertOAuthServerIssuer({ issuer: flow.authorizationServerIssuer }, flow.authorizationServerUrl);
+}
 function assertAgentUnchangedForFlow(agent, flow) {
   if (!agent) {
     throw new AgentVanishedDuringFlowError(flow.agentId);
@@ -260,6 +284,13 @@ function assertAgentUnchangedForFlow(agent, flow) {
   if (agent.agent_uri !== flow.agentUrl) {
     throw new AgentChangedDuringFlowError(flow.agentId);
   }
+  if (!agent.oauth_client) throw new AgentChangedDuringFlowError(flow.agentId);
+  const currentClient = toMCPClientInfo(agent.oauth_client);
+  for (const key of ["client_id", "client_secret", "client_secret_expires_at", "issuer"]) {
+    if (currentClient[key] !== flow.clientInformation[key]) throw new AgentChangedDuringFlowError(flow.agentId);
+  }
+  assertFrozenIssuer(flow);
+  assertSavedCredentialIssuers(agent, flow.authorizationServerIssuer);
   if (Object.prototype.hasOwnProperty.call(flow, "resourceOverrideSnapshot") && (agent.oauth_resource ?? null) !== flow.resourceOverrideSnapshot) {
     throw new AgentChangedDuringFlowError(flow.agentId);
   }
@@ -395,9 +426,8 @@ function createSsrfSafeOAuthFetch(trustedFetchFn, allowHttp) {
   });
 }
 async function resolveClientInformation(args) {
-  const { agent, agentStorage, asUrl, asMetadata, clientMetadata, fetchFn, allowConfidentialClient } = args;
+  const { agent, agentStorage, asUrl, asMetadata, clientMetadata, fetchFn, allowConfidentialClient, issuer } = 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) {
@@ -407,17 +437,20 @@ async function resolveClientInformation(args) {
       agent.id
     );
   }
-  const registration = await registerClient(asUrl.toString(), {
+  const response = await registerClient(asUrl.toString(), {
     metadata: asMetadata,
     clientMetadata,
     fetchFn
   });
-  const registered = { ...registration, issuer: asUrl.toString() };
+  const registered = { ...response, issuer };
   if (registered.client_secret && !allowConfidentialClient) {
     throw new ConfidentialClientNotAllowedError(agent.id);
   }
   if (agentStorage) {
-    const fresh = await agentStorage.loadAgent(agent.id) ?? agent;
+    const fresh = await agentStorage.loadAgent(agent.id);
+    if (!fresh) throw new AgentVanishedDuringFlowError(agent.id);
+    if (fresh.agent_uri !== agent.agent_uri || fresh.oauth_client) throw new AgentChangedDuringFlowError(agent.id);
+    assertSavedCredentialIssuers(fresh, issuer);
     fresh.oauth_client = fromMCPClientInfo(registered);
     await agentStorage.saveAgent(fresh);
   }

package/dist/lib/index.d.mts

@@ -186,7 +186,7 @@ export { getAuthToken, createAdCPHeaders, createMCPAuthHeaders, createAuthentica
 export { parseWWWAuthenticate, decodeAccessTokenClaims, validateTokenAudience, type WWWAuthenticateChallenge, type DecodedJWTHeader, type DecodedJWTClaims, type DecodedAccessToken, type TokenAudienceResult, InvalidTokenError, InsufficientScopeError, } from './auth/oauth/index.mjs';
 export { runAuthDiagnosis, AUTH_DIAGNOSIS_SCHEMA_VERSION, type DiagnoseOptions, type HttpCapture as DiagnosisHttpCapture, type DiagnosisStep, type Hypothesis as DiagnosisHypothesis, type HypothesisVerdict as DiagnosisHypothesisVerdict, type AuthDiagnosisReport, } from './auth/oauth/index.mjs';
 export { NeedsAuthorizationError, discoverAuthorizationRequirements, hasValidatedMcpAuthorizationRequirements, createFileOAuthStorage, bindAgentStorage, getAgentStorage, unbindAgentStorage, type AuthorizationRequirements, type DiscoverAuthorizationOptions, type FileOAuthStorageOptions, } from './auth/oauth/index.mjs';
-export { exchangeClientCredentials, ensureClientCredentialsTokens, ClientCredentialsExchangeError, MissingEnvSecretError, resolveSecret, isEnvSecretReference, toEnvSecretReference, extractEnvSecretName, type ExchangeClientCredentialsOptions, type EnsureClientCredentialsOptions, type AgentOAuthClientCredentials, } from './auth/oauth/index.mjs';
+export { exchangeClientCredentials, ensureClientCredentialsTokens, ClientCredentialsExchangeError, MissingEnvSecretError, resolveSecret, isEnvSecretReference, toEnvSecretReference, extractEnvSecretName, type ExchangeClientCredentialsOptions, type EnsureClientCredentialsOptions, type AgentOAuthClientCredentials, AgentOAuthClientCredentialsSchema, } from './auth/oauth/index.mjs';
 export { validateAgentUrl, validateAdCPResponse, getExpectedSchema, handleAdCPResponse } from './validation/index.mjs';
 export { ProtocolClient, callMCPTool, callA2ATool, createA2AClientFromCardUrl, createMCPClient, createA2AClient, closeMCPConnections, closeOAuthConnections, bundleSupportsAdcpVersionField, BODY_SNIPPET_TIMEOUT_MS, OBSERVER_FLUSH_TIMEOUT_MS, sanitizeTransportHeaders, sanitizeTransportUrl, } from './protocols/index.mjs';
 export { toReleasePrecisionWire, validateAdcpVersionWire } from './validation/schema-loader.mjs';

package/dist/lib/index.d.ts

@@ -186,7 +186,7 @@ export { getAuthToken, createAdCPHeaders, createMCPAuthHeaders, createAuthentica
 export { parseWWWAuthenticate, decodeAccessTokenClaims, validateTokenAudience, type WWWAuthenticateChallenge, type DecodedJWTHeader, type DecodedJWTClaims, type DecodedAccessToken, type TokenAudienceResult, InvalidTokenError, InsufficientScopeError, } from './auth/oauth';
 export { runAuthDiagnosis, AUTH_DIAGNOSIS_SCHEMA_VERSION, type DiagnoseOptions, type HttpCapture as DiagnosisHttpCapture, type DiagnosisStep, type Hypothesis as DiagnosisHypothesis, type HypothesisVerdict as DiagnosisHypothesisVerdict, type AuthDiagnosisReport, } from './auth/oauth';
 export { NeedsAuthorizationError, discoverAuthorizationRequirements, hasValidatedMcpAuthorizationRequirements, createFileOAuthStorage, bindAgentStorage, getAgentStorage, unbindAgentStorage, type AuthorizationRequirements, type DiscoverAuthorizationOptions, type FileOAuthStorageOptions, } from './auth/oauth';
-export { exchangeClientCredentials, ensureClientCredentialsTokens, ClientCredentialsExchangeError, MissingEnvSecretError, resolveSecret, isEnvSecretReference, toEnvSecretReference, extractEnvSecretName, type ExchangeClientCredentialsOptions, type EnsureClientCredentialsOptions, type AgentOAuthClientCredentials, } from './auth/oauth';
+export { exchangeClientCredentials, ensureClientCredentialsTokens, ClientCredentialsExchangeError, MissingEnvSecretError, resolveSecret, isEnvSecretReference, toEnvSecretReference, extractEnvSecretName, type ExchangeClientCredentialsOptions, type EnsureClientCredentialsOptions, type AgentOAuthClientCredentials, AgentOAuthClientCredentialsSchema, } from './auth/oauth';
 export { validateAgentUrl, validateAdCPResponse, getExpectedSchema, handleAdCPResponse } from './validation';
 export { ProtocolClient, callMCPTool, callA2ATool, createA2AClientFromCardUrl, createMCPClient, createA2AClient, closeMCPConnections, closeOAuthConnections, bundleSupportsAdcpVersionField, BODY_SNIPPET_TIMEOUT_MS, OBSERVER_FLUSH_TIMEOUT_MS, sanitizeTransportHeaders, sanitizeTransportUrl, } from './protocols';
 export { toReleasePrecisionWire, validateAdcpVersionWire } from './validation/schema-loader';

package/dist/lib/index.js

@@ -48,6 +48,7 @@ __export(index_exports, {
   AdagentsJsonSchema: () => import_wellknown_schemas.AdagentsJsonSchema,
   AgentClient: () => import_AgentClient.AgentClient,
   AgentNotFoundError: () => import_errors.AgentNotFoundError,
+  AgentOAuthClientCredentialsSchema: () => import_oauth4.AgentOAuthClientCredentialsSchema,
   Asset: () => import_asset_builders.Asset,
   AsyncHandler: () => import_AsyncHandler.AsyncHandler,
   AuthenticationCredentialsRejectedError: () => import_errors.AuthenticationCredentialsRejectedError,
@@ -888,6 +889,7 @@ function createAdCPClientFromEnv() {
   AdagentsJsonSchema,
   AgentClient,
   AgentNotFoundError,
+  AgentOAuthClientCredentialsSchema,
   Asset,
   AsyncHandler,
   AuthenticationCredentialsRejectedError,

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/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-06T19:28:36.184Z"
+  "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.4.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.4.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/version.d.mts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "14.4.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.4.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-06T19:00:01.077Z";
+    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.4.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.4.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-06T19:00:01.077Z";
+    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.4.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.4.0",
+  library: "15.0.0",
   adcp: "3.2.1",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-06T19:00:01.077Z"
+  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.4.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.4.0",
+  library: "15.0.0",
   adcp: "3.2.1",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-06T19:00:01.077Z"
+  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.4.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.