@adcp/sdk 14.0.0-beta.14 → 14.0.0-beta.15

package/dist/lib/core/SingleAgentClient.js

@@ -59,6 +59,7 @@ var import_AsyncHandler = require('./AsyncHandler.js');
 var import_webhooks = require('../webhooks/index.js');
 var import_webhook_registration = require('./webhook-registration.js');
 var import_server = require('../signing/server.js');
+var import_errors2 = require('../signing/agent-resolver/errors.js');
 var import_a2a_artifacts = require('../utils/a2a-artifacts.js');
 var import_task_status = require('./task-status.js');
 var import_ProtocolResponseParser = require('./ProtocolResponseParser.js');
@@ -79,6 +80,14 @@ var import_augment_response = require('../v2/projection/augment-response.js');
 var import_legacy_metadata = require('../v2/projection/legacy-metadata.js');
 var import_types = require('../v2/projection/types.js');
 var import_jcs = require('../utils/jcs.js');
+function presentedStaticTransportCredential(authToken, headers, authProvider) {
+  if (authProvider) return false;
+  if (authToken) return true;
+  return Object.keys(headers ?? {}).some((key) => {
+    const normalized = key.toLowerCase();
+    return normalized === "authorization" || normalized === "x-adcp-auth";
+  });
+}
 const CAPABILITY_DISCOVERY_CONTEXT = /* @__PURE__ */ Symbol("capabilityDiscoveryContext");
 function a2aUrlString(input) {
   return typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
@@ -214,6 +223,7 @@ const RECORDLESS_HMAC_READ_ONLY_TASKS = /* @__PURE__ */ new Set([
   "get_plan_audit_logs"
 ]);
 const TASK_SCOPED_STATE_LIMIT = 1e4;
+const WEBHOOK_JWKS_RESOLVER_LIMIT = 1024;
 function isDeferredClientFinalizationContext(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const context = value;
@@ -488,7 +498,10 @@ function snapshotTaskOptions(options) {
   return {
     ...options,
     ...options.transport !== void 0 && { transport: { ...options.transport } },
-    ...options.metadata !== void 0 && { metadata: structuredClone(options.metadata) }
+    ...options.metadata !== void 0 && { metadata: structuredClone(options.metadata) },
+    ...options.delegatedOperatorAuthorization !== void 0 && {
+      delegatedOperatorAuthorization: { ...options.delegatedOperatorAuthorization }
+    }
   };
 }
 const PRIMARY_ADCP_TASK_NAMES = {
@@ -821,20 +834,33 @@ class SingleAgentClient {
     persistedAgentUrl.username = "";
     persistedAgentUrl.password = "";
     persistedAgentUrl.hash = "";
+    const delegatedOperatorAuthorization = this.effectiveDelegatedOperatorAuthorization(
+      args.delegatedOperatorAuthorization
+    );
+    const registration = {
+      agentId: args.agent.id,
+      agentUrl: persistedAgentUrl.toString(),
+      protocol: args.agent.protocol,
+      operationId: args.operationId,
+      taskType: args.taskType,
+      callbackUrl: args.callbackUrl,
+      method: "POST",
+      mode: args.mode,
+      authorizationContextVersion: 1,
+      ...delegatedOperatorAuthorization !== void 0 && { delegatedOperatorAuthorization },
+      ...previewMode && { previewMode },
+      createdAt: nowMs,
+      expiresAt: nowMs + ttlSeconds * 1e3
+    };
+    (0, import_webhook_registration.validateWebhookRegistrationAuthorization)(registration);
     try {
-      await this.webhookRegistrationStore.putIfAbsent({
-        agentId: args.agent.id,
-        agentUrl: persistedAgentUrl.toString(),
-        protocol: args.agent.protocol,
-        operationId: args.operationId,
-        taskType: args.taskType,
-        callbackUrl: args.callbackUrl,
-        method: "POST",
-        mode: args.mode,
-        ...previewMode && { previewMode },
-        createdAt: nowMs,
-        expiresAt: nowMs + ttlSeconds * 1e3
-      });
+      await this.webhookRegistrationStore.putIfAbsent(registration);
+      const persisted = await this.webhookRegistrationStore.get(args.agent.id, args.operationId);
+      if (!persisted || persisted.authorizationContextVersion !== 1 || (0, import_webhook_registration.canonicalDelegatedOperatorAuthorization)(persisted.delegatedOperatorAuthorization) !== (0, import_webhook_registration.canonicalDelegatedOperatorAuthorization)(delegatedOperatorAuthorization)) {
+        throw new Error(
+          "Webhook registration store did not preserve the versioned delegated-operator authorization context."
+        );
+      }
     } catch (cause) {
       if (args.mode === "rfc9421" || !RECORDLESS_HMAC_READ_ONLY_TASKS.has(args.taskType)) {
         const error = new import_errors.ConfigurationError("Could not persist trusted webhook registration for this operation.");
@@ -843,6 +869,28 @@ class SingleAgentClient {
       }
     }
   }
+  configuredDelegatedOperatorAuthorization() {
+    const options = this.config.webhookVerification?.resolverOptions;
+    if (!options) return void 0;
+    const context = {
+      ...options.requiredOperatorBrand !== void 0 && { brand: options.requiredOperatorBrand },
+      ...options.requiredOperatorScope !== void 0 && { scope: options.requiredOperatorScope },
+      ...options.requiredOperatorCountry !== void 0 && { country: options.requiredOperatorCountry }
+    };
+    return Object.keys(context).length > 0 ? context : void 0;
+  }
+  effectiveDelegatedOperatorAuthorization(perCall) {
+    const selected = perCall ?? this.configuredDelegatedOperatorAuthorization();
+    if (selected === void 0) return void 0;
+    return { ...selected };
+  }
+  delegatedOperatorAuthorizationForRegistration(registration) {
+    (0, import_webhook_registration.validateWebhookRegistrationAuthorization)(registration);
+    if (registration.authorizationContextVersion === 1) {
+      return registration.delegatedOperatorAuthorization === void 0 ? void 0 : { ...registration.delegatedOperatorAuthorization };
+    }
+    return void 0;
+  }
   async markWebhookDurableSettlementRequired(operationId) {
     const mark = this.webhookRegistrationStore.markRequiresDurableSettlement;
     if (!mark) {
@@ -855,11 +903,42 @@ class SingleAgentClient {
   webhookJwksFor(registration) {
     const configured = this.config.webhookVerification?.jwks;
     if (configured) return configured;
-    const key = `${registration.protocol}\0${registration.agentUrl}`;
+    if (registration.authorizationContextVersion !== 1) {
+      throw new import_errors.ConfigurationError(
+        "Automatic seller-key discovery cannot verify a legacy webhook registration without a persisted authorization context."
+      );
+    }
+    const delegatedOperatorAuthorization = this.delegatedOperatorAuthorizationForRegistration(registration);
+    const key = JSON.stringify([
+      registration.protocol,
+      registration.agentUrl,
+      registration.authorizationContextVersion ?? 0,
+      (0, import_webhook_registration.canonicalDelegatedOperatorAuthorization)(delegatedOperatorAuthorization)
+    ]);
     const existing = this.webhookJwksResolvers.get(key);
-    if (existing) return existing;
+    if (existing) {
+      this.webhookJwksResolvers.delete(key);
+      this.webhookJwksResolvers.set(key, existing);
+      return existing;
+    }
+    const configuredResolverOptions = this.config.webhookVerification?.resolverOptions;
+    const {
+      requiredOperatorBrand: _configuredBrand,
+      requiredOperatorScope: _configuredScope,
+      requiredOperatorCountry: _configuredCountry,
+      ...resolverOptionsWithoutOperatorContext
+    } = configuredResolverOptions ?? {};
     const resolver = new import_server.ResolvedAgentJwksResolver(registration.agentUrl, registration.protocol, {
-      ...this.config.webhookVerification?.resolverOptions,
+      ...resolverOptionsWithoutOperatorContext,
+      ...delegatedOperatorAuthorization?.brand !== void 0 && {
+        requiredOperatorBrand: delegatedOperatorAuthorization.brand
+      },
+      ...delegatedOperatorAuthorization?.scope !== void 0 && {
+        requiredOperatorScope: delegatedOperatorAuthorization.scope
+      },
+      ...delegatedOperatorAuthorization?.country !== void 0 && {
+        requiredOperatorCountry: delegatedOperatorAuthorization.country
+      },
       fetchCapabilities: (agentUrl) => {
         const configuredFetch = this.config.webhookVerification?.fetchCapabilities;
         if (configuredFetch) return configuredFetch(agentUrl, registration.protocol);
@@ -884,6 +963,10 @@ class SingleAgentClient {
         );
       }
     });
+    if (this.webhookJwksResolvers.size >= WEBHOOK_JWKS_RESOLVER_LIMIT) {
+      const oldest = this.webhookJwksResolvers.keys().next().value;
+      if (oldest !== void 0) this.webhookJwksResolvers.delete(oldest);
+    }
     this.webhookJwksResolvers.set(key, resolver);
     return resolver;
   }
@@ -1551,8 +1634,8 @@ class SingleAgentClient {
    *
    * Special handling for authentication errors (401):
    * - If any endpoint returns 401, we know the server exists but requires auth
-   * - We fetch OAuth metadata and throw AuthenticationRequiredError
-   * - This gives consumers clear guidance on how to authenticate
+   * - A validated MCP protected-resource metadata chain yields NeedsAuthorizationError
+   * - Otherwise AuthenticationRequiredError carries the advertised challenge
    *
    * Note: This is async and called lazily on first agent interaction
    */
@@ -1629,6 +1712,7 @@ class SingleAgentClient {
     }
     const uniqueUrls = [...new Set(urlsToTry)];
     let got401 = false;
+    let first401Error;
     let firstWorkingUrl;
     for (const url of uniqueUrls) {
       const result = await testEndpoint(url);
@@ -1638,18 +1722,22 @@ class SingleAgentClient {
       }
       if (result.status === 401) {
         got401 = true;
+        first401Error ??= result.error;
       }
     }
     if (firstWorkingUrl) {
       return firstWorkingUrl;
     }
     if (got401) {
+      if (presentedStaticTransportCredential(authToken, agentHeaders, authProvider)) {
+        throw new import_errors.AuthenticationCredentialsRejectedError(providedUri, first401Error);
+      }
       const requirements = await (0, import_authorization_required.discoverAuthorizationRequirements)(providedUri, {
         allowPrivateIp: transport?.allowPrivateIp ?? (0, import_net.isLikelyPrivateUrl)(providedUri),
         fetchFn: transport?.trustedFetchFn,
         signal: options?.signal
       });
-      if (requirements) {
+      if (requirements && (0, import_authorization_required.hasValidatedMcpAuthorizationRequirements)(requirements, providedUri)) {
         throw new import_authorization_required.NeedsAuthorizationError(requirements);
       }
       const challenge = await (0, import_authorization_required.probeAuthChallenge)(providedUri, {
@@ -1657,12 +1745,7 @@ class SingleAgentClient {
         fetchFn: transport?.trustedFetchFn,
         signal: options?.signal
       });
-      const oauthMetadata = await (0, import_discovery.discoverOAuthMetadata)(providedUri, {
-        trustedFetchFn: transport?.trustedFetchFn,
-        allowPrivateIp: transport?.allowPrivateIp ?? (0, import_net.isLikelyPrivateUrl)(providedUri),
-        signal: options?.signal
-      });
-      throw new import_errors.AuthenticationRequiredError(providedUri, oauthMetadata || void 0, void 0, challenge ?? void 0);
+      throw new import_errors.AuthenticationRequiredError(providedUri, void 0, void 0, challenge ?? void 0);
     }
     throw new Error(
       `Failed to discover MCP endpoint. Tried:
@@ -1801,6 +1884,16 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           message: "Webhook registration state contains invalid timestamps."
         };
       }
+      try {
+        (0, import_webhook_registration.validateWebhookRegistrationAuthorization)(registration);
+      } catch (cause) {
+        return {
+          ok: false,
+          code: "webhook_registration_store_unavailable",
+          message: "Webhook registration state contains invalid authorization context.",
+          cause
+        };
+      }
       try {
         const registeredAgentUrl = new URL(registration.agentUrl);
         if (registeredAgentUrl.username || registeredAgentUrl.password) {
@@ -1893,6 +1986,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       const normalizedHeaders = normalizeRfc9421WebhookHeaders(options.headers);
       if (!normalizedHeaders.ok) return normalizedHeaders.failure;
       try {
+        const delegatedOperatorAuthorization = this.delegatedOperatorAuthorizationForRegistration(registration);
         await (0, import_server.verifyWebhookSignature)(
           {
             method: options.requestMethod,
@@ -1905,13 +1999,24 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
             replayStore: this.webhookReplayStore,
             revocationStore: this.webhookRevocationStore,
             ...this.config.webhookVerification?.now && { now: this.config.webhookVerification.now },
-            agentUrlForKeyid: () => registration.agentUrl
+            agentUrlForKeyid: () => registration.agentUrl,
+            ...registration.authorizationContextVersion === 1 && {
+              replayScopeBinding: `delegated-operator:v1:${crypto.createHash("sha256").update((0, import_webhook_registration.canonicalDelegatedOperatorAuthorization)(delegatedOperatorAuthorization)).digest("base64url")}`
+            }
           }
         );
       } catch (cause) {
         if (cause instanceof import_server.WebhookSignatureError) {
           return { ok: false, code: cause.code, message: cause.message, cause };
         }
+        if (cause instanceof import_errors2.AgentResolverError && !cause.code.endsWith("_unreachable")) {
+          return {
+            ok: false,
+            code: "webhook_signature_key_unknown",
+            message: "The registered seller is not authorized to supply this webhook signing key.",
+            cause
+          };
+        }
         return {
           ok: false,
           code: "webhook_verification_unavailable",
@@ -4503,7 +4608,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    */
   async getAdcpCapabilities(params, inputHandler, options) {
     return (0, import_task_deadline.withTaskDeadline)(
-      options,
+      snapshotTaskOptions(options),
       (effectiveOptions) => this.getAdcpCapabilitiesWithinDeadline(params, inputHandler, effectiveOptions)
     );
   }

package/dist/lib/core/SingleAgentClient.mjs

@@ -35,6 +35,7 @@ import { createMCPRequestHeaders } from "../auth/index.mjs";
 import { isAbortOrTimeoutError } from "../protocols/abort.mjs";
 import { ProtocolClient, normalizeTransportOptions } from "../protocols/index.mjs";
 import {
+  AuthenticationCredentialsRejectedError,
   AuthenticationRequiredError,
   ConfigurationError,
   FeatureUnsupportedError,
@@ -46,6 +47,7 @@ import {
 import { createAgentTransportFetch, isLikelyPrivateUrl } from "../net/index.mjs";
 import {
   discoverAuthorizationRequirements,
+  hasValidatedMcpAuthorizationRequirements,
   NeedsAuthorizationError,
   probeAuthChallenge
 } from "../auth/oauth/authorization-required.mjs";
@@ -58,7 +60,9 @@ import {
 } from "./AsyncHandler.mjs";
 import { verifyWebhookRequest } from "../webhooks/index.mjs";
 import {
-  InMemoryWebhookRegistrationStore
+  canonicalDelegatedOperatorAuthorization,
+  InMemoryWebhookRegistrationStore,
+  validateWebhookRegistrationAuthorization
 } from "./webhook-registration.mjs";
 import {
   InMemoryReplayStore,
@@ -68,6 +72,7 @@ import {
   ResolvedAgentJwksResolver,
   canonicalTargetUri
 } from "../signing/server.mjs";
+import { AgentResolverError } from "../signing/agent-resolver/errors.mjs";
 import { getLatestA2ADataPartFromTask } from "../utils/a2a-artifacts.mjs";
 import { extractAdcpTaskStatusFromPayload, isAdcpStatus } from "./task-status.mjs";
 import { responseParser } from "./ProtocolResponseParser.mjs";
@@ -86,6 +91,14 @@ import {
   throwIfAborted,
   withAbortSignal
 } from "../protocols/abort.mjs";
+function presentedStaticTransportCredential(authToken, headers, authProvider) {
+  if (authProvider) return false;
+  if (authToken) return true;
+  return Object.keys(headers ?? {}).some((key) => {
+    const normalized = key.toLowerCase();
+    return normalized === "authorization" || normalized === "x-adcp-auth";
+  });
+}
 import {
   buildSyntheticCapabilities,
   buildSyntheticV3Capabilities,
@@ -261,6 +274,7 @@ const RECORDLESS_HMAC_READ_ONLY_TASKS = /* @__PURE__ */ new Set([
   "get_plan_audit_logs"
 ]);
 const TASK_SCOPED_STATE_LIMIT = 1e4;
+const WEBHOOK_JWKS_RESOLVER_LIMIT = 1024;
 function isDeferredClientFinalizationContext(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const context = value;
@@ -535,7 +549,10 @@ function snapshotTaskOptions(options) {
   return {
     ...options,
     ...options.transport !== void 0 && { transport: { ...options.transport } },
-    ...options.metadata !== void 0 && { metadata: structuredClone(options.metadata) }
+    ...options.metadata !== void 0 && { metadata: structuredClone(options.metadata) },
+    ...options.delegatedOperatorAuthorization !== void 0 && {
+      delegatedOperatorAuthorization: { ...options.delegatedOperatorAuthorization }
+    }
   };
 }
 const PRIMARY_ADCP_TASK_NAMES = {
@@ -868,20 +885,33 @@ class SingleAgentClient {
     persistedAgentUrl.username = "";
     persistedAgentUrl.password = "";
     persistedAgentUrl.hash = "";
+    const delegatedOperatorAuthorization = this.effectiveDelegatedOperatorAuthorization(
+      args.delegatedOperatorAuthorization
+    );
+    const registration = {
+      agentId: args.agent.id,
+      agentUrl: persistedAgentUrl.toString(),
+      protocol: args.agent.protocol,
+      operationId: args.operationId,
+      taskType: args.taskType,
+      callbackUrl: args.callbackUrl,
+      method: "POST",
+      mode: args.mode,
+      authorizationContextVersion: 1,
+      ...delegatedOperatorAuthorization !== void 0 && { delegatedOperatorAuthorization },
+      ...previewMode && { previewMode },
+      createdAt: nowMs,
+      expiresAt: nowMs + ttlSeconds * 1e3
+    };
+    validateWebhookRegistrationAuthorization(registration);
     try {
-      await this.webhookRegistrationStore.putIfAbsent({
-        agentId: args.agent.id,
-        agentUrl: persistedAgentUrl.toString(),
-        protocol: args.agent.protocol,
-        operationId: args.operationId,
-        taskType: args.taskType,
-        callbackUrl: args.callbackUrl,
-        method: "POST",
-        mode: args.mode,
-        ...previewMode && { previewMode },
-        createdAt: nowMs,
-        expiresAt: nowMs + ttlSeconds * 1e3
-      });
+      await this.webhookRegistrationStore.putIfAbsent(registration);
+      const persisted = await this.webhookRegistrationStore.get(args.agent.id, args.operationId);
+      if (!persisted || persisted.authorizationContextVersion !== 1 || canonicalDelegatedOperatorAuthorization(persisted.delegatedOperatorAuthorization) !== canonicalDelegatedOperatorAuthorization(delegatedOperatorAuthorization)) {
+        throw new Error(
+          "Webhook registration store did not preserve the versioned delegated-operator authorization context."
+        );
+      }
     } catch (cause) {
       if (args.mode === "rfc9421" || !RECORDLESS_HMAC_READ_ONLY_TASKS.has(args.taskType)) {
         const error = new ConfigurationError("Could not persist trusted webhook registration for this operation.");
@@ -890,6 +920,28 @@ class SingleAgentClient {
       }
     }
   }
+  configuredDelegatedOperatorAuthorization() {
+    const options = this.config.webhookVerification?.resolverOptions;
+    if (!options) return void 0;
+    const context = {
+      ...options.requiredOperatorBrand !== void 0 && { brand: options.requiredOperatorBrand },
+      ...options.requiredOperatorScope !== void 0 && { scope: options.requiredOperatorScope },
+      ...options.requiredOperatorCountry !== void 0 && { country: options.requiredOperatorCountry }
+    };
+    return Object.keys(context).length > 0 ? context : void 0;
+  }
+  effectiveDelegatedOperatorAuthorization(perCall) {
+    const selected = perCall ?? this.configuredDelegatedOperatorAuthorization();
+    if (selected === void 0) return void 0;
+    return { ...selected };
+  }
+  delegatedOperatorAuthorizationForRegistration(registration) {
+    validateWebhookRegistrationAuthorization(registration);
+    if (registration.authorizationContextVersion === 1) {
+      return registration.delegatedOperatorAuthorization === void 0 ? void 0 : { ...registration.delegatedOperatorAuthorization };
+    }
+    return void 0;
+  }
   async markWebhookDurableSettlementRequired(operationId) {
     const mark = this.webhookRegistrationStore.markRequiresDurableSettlement;
     if (!mark) {
@@ -902,11 +954,42 @@ class SingleAgentClient {
   webhookJwksFor(registration) {
     const configured = this.config.webhookVerification?.jwks;
     if (configured) return configured;
-    const key = `${registration.protocol}\0${registration.agentUrl}`;
+    if (registration.authorizationContextVersion !== 1) {
+      throw new ConfigurationError(
+        "Automatic seller-key discovery cannot verify a legacy webhook registration without a persisted authorization context."
+      );
+    }
+    const delegatedOperatorAuthorization = this.delegatedOperatorAuthorizationForRegistration(registration);
+    const key = JSON.stringify([
+      registration.protocol,
+      registration.agentUrl,
+      registration.authorizationContextVersion ?? 0,
+      canonicalDelegatedOperatorAuthorization(delegatedOperatorAuthorization)
+    ]);
     const existing = this.webhookJwksResolvers.get(key);
-    if (existing) return existing;
+    if (existing) {
+      this.webhookJwksResolvers.delete(key);
+      this.webhookJwksResolvers.set(key, existing);
+      return existing;
+    }
+    const configuredResolverOptions = this.config.webhookVerification?.resolverOptions;
+    const {
+      requiredOperatorBrand: _configuredBrand,
+      requiredOperatorScope: _configuredScope,
+      requiredOperatorCountry: _configuredCountry,
+      ...resolverOptionsWithoutOperatorContext
+    } = configuredResolverOptions ?? {};
     const resolver = new ResolvedAgentJwksResolver(registration.agentUrl, registration.protocol, {
-      ...this.config.webhookVerification?.resolverOptions,
+      ...resolverOptionsWithoutOperatorContext,
+      ...delegatedOperatorAuthorization?.brand !== void 0 && {
+        requiredOperatorBrand: delegatedOperatorAuthorization.brand
+      },
+      ...delegatedOperatorAuthorization?.scope !== void 0 && {
+        requiredOperatorScope: delegatedOperatorAuthorization.scope
+      },
+      ...delegatedOperatorAuthorization?.country !== void 0 && {
+        requiredOperatorCountry: delegatedOperatorAuthorization.country
+      },
       fetchCapabilities: (agentUrl) => {
         const configuredFetch = this.config.webhookVerification?.fetchCapabilities;
         if (configuredFetch) return configuredFetch(agentUrl, registration.protocol);
@@ -931,6 +1014,10 @@ class SingleAgentClient {
         );
       }
     });
+    if (this.webhookJwksResolvers.size >= WEBHOOK_JWKS_RESOLVER_LIMIT) {
+      const oldest = this.webhookJwksResolvers.keys().next().value;
+      if (oldest !== void 0) this.webhookJwksResolvers.delete(oldest);
+    }
     this.webhookJwksResolvers.set(key, resolver);
     return resolver;
   }
@@ -1598,8 +1685,8 @@ class SingleAgentClient {
    *
    * Special handling for authentication errors (401):
    * - If any endpoint returns 401, we know the server exists but requires auth
-   * - We fetch OAuth metadata and throw AuthenticationRequiredError
-   * - This gives consumers clear guidance on how to authenticate
+   * - A validated MCP protected-resource metadata chain yields NeedsAuthorizationError
+   * - Otherwise AuthenticationRequiredError carries the advertised challenge
    *
    * Note: This is async and called lazily on first agent interaction
    */
@@ -1676,6 +1763,7 @@ class SingleAgentClient {
     }
     const uniqueUrls = [...new Set(urlsToTry)];
     let got401 = false;
+    let first401Error;
     let firstWorkingUrl;
     for (const url of uniqueUrls) {
       const result = await testEndpoint(url);
@@ -1685,18 +1773,22 @@ class SingleAgentClient {
       }
       if (result.status === 401) {
         got401 = true;
+        first401Error ??= result.error;
       }
     }
     if (firstWorkingUrl) {
       return firstWorkingUrl;
     }
     if (got401) {
+      if (presentedStaticTransportCredential(authToken, agentHeaders, authProvider)) {
+        throw new AuthenticationCredentialsRejectedError(providedUri, first401Error);
+      }
       const requirements = await discoverAuthorizationRequirements(providedUri, {
         allowPrivateIp: transport?.allowPrivateIp ?? isLikelyPrivateUrl(providedUri),
         fetchFn: transport?.trustedFetchFn,
         signal: options?.signal
       });
-      if (requirements) {
+      if (requirements && hasValidatedMcpAuthorizationRequirements(requirements, providedUri)) {
         throw new NeedsAuthorizationError(requirements);
       }
       const challenge = await probeAuthChallenge(providedUri, {
@@ -1704,12 +1796,7 @@ class SingleAgentClient {
         fetchFn: transport?.trustedFetchFn,
         signal: options?.signal
       });
-      const oauthMetadata = await discoverOAuthMetadata(providedUri, {
-        trustedFetchFn: transport?.trustedFetchFn,
-        allowPrivateIp: transport?.allowPrivateIp ?? isLikelyPrivateUrl(providedUri),
-        signal: options?.signal
-      });
-      throw new AuthenticationRequiredError(providedUri, oauthMetadata || void 0, void 0, challenge ?? void 0);
+      throw new AuthenticationRequiredError(providedUri, void 0, void 0, challenge ?? void 0);
     }
     throw new Error(
       `Failed to discover MCP endpoint. Tried:
@@ -1848,6 +1935,16 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           message: "Webhook registration state contains invalid timestamps."
         };
       }
+      try {
+        validateWebhookRegistrationAuthorization(registration);
+      } catch (cause) {
+        return {
+          ok: false,
+          code: "webhook_registration_store_unavailable",
+          message: "Webhook registration state contains invalid authorization context.",
+          cause
+        };
+      }
       try {
         const registeredAgentUrl = new URL(registration.agentUrl);
         if (registeredAgentUrl.username || registeredAgentUrl.password) {
@@ -1940,6 +2037,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       const normalizedHeaders = normalizeRfc9421WebhookHeaders(options.headers);
       if (!normalizedHeaders.ok) return normalizedHeaders.failure;
       try {
+        const delegatedOperatorAuthorization = this.delegatedOperatorAuthorizationForRegistration(registration);
         await verifyRfc9421WebhookSignature(
           {
             method: options.requestMethod,
@@ -1952,13 +2050,24 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
             replayStore: this.webhookReplayStore,
             revocationStore: this.webhookRevocationStore,
             ...this.config.webhookVerification?.now && { now: this.config.webhookVerification.now },
-            agentUrlForKeyid: () => registration.agentUrl
+            agentUrlForKeyid: () => registration.agentUrl,
+            ...registration.authorizationContextVersion === 1 && {
+              replayScopeBinding: `delegated-operator:v1:${crypto.createHash("sha256").update(canonicalDelegatedOperatorAuthorization(delegatedOperatorAuthorization)).digest("base64url")}`
+            }
           }
         );
       } catch (cause) {
         if (cause instanceof WebhookSignatureError) {
           return { ok: false, code: cause.code, message: cause.message, cause };
         }
+        if (cause instanceof AgentResolverError && !cause.code.endsWith("_unreachable")) {
+          return {
+            ok: false,
+            code: "webhook_signature_key_unknown",
+            message: "The registered seller is not authorized to supply this webhook signing key.",
+            cause
+          };
+        }
         return {
           ok: false,
           code: "webhook_verification_unavailable",
@@ -4550,7 +4659,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    */
   async getAdcpCapabilities(params, inputHandler, options) {
     return withTaskDeadline(
-      options,
+      snapshotTaskOptions(options),
       (effectiveOptions) => this.getAdcpCapabilitiesWithinDeadline(params, inputHandler, effectiveOptions)
     );
   }

package/dist/lib/core/TaskExecutor.d.mts

@@ -153,6 +153,7 @@ export declare class TaskExecutor {
             operationId: string;
             callbackUrl: string;
             mode: 'rfc9421' | 'hmac-sha256';
+            delegatedOperatorAuthorization?: TaskOptions['delegatedOperatorAuthorization'];
         }) => void | Promise<void>;
         /** Persist fail-closed routing provenance before a durable mutation claim can run. */
         onDurableSettlementRequired?: (operationId: string) => void | Promise<void>;

package/dist/lib/core/TaskExecutor.d.ts

@@ -153,6 +153,7 @@ export declare class TaskExecutor {
             operationId: string;
             callbackUrl: string;
             mode: 'rfc9421' | 'hmac-sha256';
+            delegatedOperatorAuthorization?: TaskOptions['delegatedOperatorAuthorization'];
         }) => void | Promise<void>;
         /** Persist fail-closed routing provenance before a durable mutation claim can run. */
         onDurableSettlementRequired?: (operationId: string) => void | Promise<void>;

package/dist/lib/core/TaskExecutor.js

@@ -372,7 +372,10 @@ function snapshotTaskOptions(options) {
   return {
     ...options,
     ...options.transport !== void 0 && { transport: snapshotTransportOptions(options.transport) },
-    ...options.metadata !== void 0 && { metadata: structuredClone(options.metadata) }
+    ...options.metadata !== void 0 && { metadata: structuredClone(options.metadata) },
+    ...options.delegatedOperatorAuthorization !== void 0 && {
+      delegatedOperatorAuthorization: { ...options.delegatedOperatorAuthorization }
+    }
   };
 }
 function snapshotTransportOptions(transport) {
@@ -851,6 +854,9 @@ class TaskExecutor {
             agent,
             taskType: taskName,
             operationId: taskId,
+            ...options.delegatedOperatorAuthorization !== void 0 && {
+              delegatedOperatorAuthorization: options.delegatedOperatorAuthorization
+            },
             ...registration
           });
           webhookRegistrationPersisted = true;

package/dist/lib/core/TaskExecutor.mjs

@@ -346,7 +346,10 @@ function snapshotTaskOptions(options) {
   return {
     ...options,
     ...options.transport !== void 0 && { transport: snapshotTransportOptions(options.transport) },
-    ...options.metadata !== void 0 && { metadata: structuredClone(options.metadata) }
+    ...options.metadata !== void 0 && { metadata: structuredClone(options.metadata) },
+    ...options.delegatedOperatorAuthorization !== void 0 && {
+      delegatedOperatorAuthorization: { ...options.delegatedOperatorAuthorization }
+    }
   };
 }
 function snapshotTransportOptions(transport) {
@@ -825,6 +828,9 @@ class TaskExecutor {
             agent,
             taskType: taskName,
             operationId: taskId,
+            ...options.delegatedOperatorAuthorization !== void 0 && {
+              delegatedOperatorAuthorization: options.delegatedOperatorAuthorization
+            },
             ...registration
           });
           webhookRegistrationPersisted = true;