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

package/dist/lib/auth/oauth/authorization-required.d.mts

@@ -1,9 +1,10 @@
 import { AuthenticationRequiredError } from '../../errors/index.mjs';
 import { type WWWAuthenticateChallenge } from './diagnostics.mjs';
 /**
- * Structured description of what an agent's authorization server requires
- * before it will accept a `tools/call`. Produced by
- * {@link discoverAuthorizationRequirements}.
+ * Structured result from a Bearer challenge and its available discovery
+ * metadata. Records may be partial; use
+ * {@link hasValidatedMcpAuthorizationRequirements} before treating one as
+ * proof that an MCP endpoint requires OAuth.
  */
 export interface AuthorizationRequirements {
     /** The agent URL we probed. */
@@ -62,12 +63,12 @@ export interface AuthorizationRequirements {
  *   `instanceof NeedsAuthorizationError` for type-narrowing and use `subCode`
  *   only for structured-log keying.
  *
- * Note on `hasOAuth`:
+ * Note on validation and `hasOAuth`:
  *   The inherited getter returns `true` only when both `authorization_endpoint`
  *   and `token_endpoint` were walked successfully. A partially-walked
- *   requirements record (PRM reachable but AS metadata missing) still yields
- *   `hasOAuth === false` even though `requirements.authorizationServer` is set.
- *   Treat it as "we have enough to start a flow," not "server wants OAuth."
+ *   requirements record still yields `hasOAuth === false`. Callers should
+ *   construct this error only after
+ *   {@link hasValidatedMcpAuthorizationRequirements} succeeds.
  */
 export declare class NeedsAuthorizationError extends AuthenticationRequiredError {
     /** Narrow discriminator for consumers that already know about this class. */
@@ -95,14 +96,17 @@ export interface DiscoverAuthorizationOptions {
     wwwAuthenticate?: string;
 }
 /**
- * Walk the OAuth discovery chain starting from an agent URL. Returns
- * `AuthorizationRequirements` when the agent demands OAuth, or `null` when a
- * `tools/list` call succeeds without credentials.
+ * Walk the OAuth discovery chain starting from an agent URL. Returns an
+ * `AuthorizationRequirements` diagnostic record for a Bearer challenge (even
+ * when later metadata is absent), or `null` when the probe is not a Bearer
+ * 401. Use {@link hasValidatedMcpAuthorizationRequirements} before promoting
+ * the record to an interactive OAuth requirement.
  *
  * Strategy:
  *   1. POST `tools/list` to the agent with no `Authorization` header.
  *   2. If 401 + `WWW-Authenticate: Bearer`: parse the challenge.
- *   3. If the challenge carries `resource_metadata=…`: GET it and read
+ *   3. Resolve `resource_metadata=…`, or the RFC 9728 well-known fallback,
+ *      then GET it and read
  *      `resource` + `authorization_servers`.
  *   4. For the first `authorization_servers[0]`: GET `/.well-known/oauth-authorization-server`
  *      and read `authorization_endpoint`, `token_endpoint`, `registration_endpoint`,
@@ -113,6 +117,16 @@ export interface DiscoverAuthorizationOptions {
  * callers can still present a partial picture without re-probing.
  */
 export declare function discoverAuthorizationRequirements(agentUrl: string, options?: DiscoverAuthorizationOptions): Promise<AuthorizationRequirements | null>;
+/**
+ * Whether a discovery record proves the MCP endpoint is OAuth protected.
+ *
+ * `discoverAuthorizationRequirements` intentionally returns partial records
+ * for diagnostics. Those records are not sufficient evidence for an
+ * interactive OAuth prompt: the MCP authorization profile requires protected
+ * resource metadata whose `resource` exactly identifies the endpoint and
+ * which names at least one authorization server.
+ */
+export declare function hasValidatedMcpAuthorizationRequirements(requirements: AuthorizationRequirements, agentUrl: string): boolean;
 /**
  * Probe the agent for the parsed `WWW-Authenticate` challenge on a 401.
  *

package/dist/lib/auth/oauth/authorization-required.d.ts

@@ -1,9 +1,10 @@
 import { AuthenticationRequiredError } from '../../errors';
 import { type WWWAuthenticateChallenge } from './diagnostics';
 /**
- * Structured description of what an agent's authorization server requires
- * before it will accept a `tools/call`. Produced by
- * {@link discoverAuthorizationRequirements}.
+ * Structured result from a Bearer challenge and its available discovery
+ * metadata. Records may be partial; use
+ * {@link hasValidatedMcpAuthorizationRequirements} before treating one as
+ * proof that an MCP endpoint requires OAuth.
  */
 export interface AuthorizationRequirements {
     /** The agent URL we probed. */
@@ -62,12 +63,12 @@ export interface AuthorizationRequirements {
  *   `instanceof NeedsAuthorizationError` for type-narrowing and use `subCode`
  *   only for structured-log keying.
  *
- * Note on `hasOAuth`:
+ * Note on validation and `hasOAuth`:
  *   The inherited getter returns `true` only when both `authorization_endpoint`
  *   and `token_endpoint` were walked successfully. A partially-walked
- *   requirements record (PRM reachable but AS metadata missing) still yields
- *   `hasOAuth === false` even though `requirements.authorizationServer` is set.
- *   Treat it as "we have enough to start a flow," not "server wants OAuth."
+ *   requirements record still yields `hasOAuth === false`. Callers should
+ *   construct this error only after
+ *   {@link hasValidatedMcpAuthorizationRequirements} succeeds.
  */
 export declare class NeedsAuthorizationError extends AuthenticationRequiredError {
     /** Narrow discriminator for consumers that already know about this class. */
@@ -95,14 +96,17 @@ export interface DiscoverAuthorizationOptions {
     wwwAuthenticate?: string;
 }
 /**
- * Walk the OAuth discovery chain starting from an agent URL. Returns
- * `AuthorizationRequirements` when the agent demands OAuth, or `null` when a
- * `tools/list` call succeeds without credentials.
+ * Walk the OAuth discovery chain starting from an agent URL. Returns an
+ * `AuthorizationRequirements` diagnostic record for a Bearer challenge (even
+ * when later metadata is absent), or `null` when the probe is not a Bearer
+ * 401. Use {@link hasValidatedMcpAuthorizationRequirements} before promoting
+ * the record to an interactive OAuth requirement.
  *
  * Strategy:
  *   1. POST `tools/list` to the agent with no `Authorization` header.
  *   2. If 401 + `WWW-Authenticate: Bearer`: parse the challenge.
- *   3. If the challenge carries `resource_metadata=…`: GET it and read
+ *   3. Resolve `resource_metadata=…`, or the RFC 9728 well-known fallback,
+ *      then GET it and read
  *      `resource` + `authorization_servers`.
  *   4. For the first `authorization_servers[0]`: GET `/.well-known/oauth-authorization-server`
  *      and read `authorization_endpoint`, `token_endpoint`, `registration_endpoint`,
@@ -113,6 +117,16 @@ export interface DiscoverAuthorizationOptions {
  * callers can still present a partial picture without re-probing.
  */
 export declare function discoverAuthorizationRequirements(agentUrl: string, options?: DiscoverAuthorizationOptions): Promise<AuthorizationRequirements | null>;
+/**
+ * Whether a discovery record proves the MCP endpoint is OAuth protected.
+ *
+ * `discoverAuthorizationRequirements` intentionally returns partial records
+ * for diagnostics. Those records are not sufficient evidence for an
+ * interactive OAuth prompt: the MCP authorization profile requires protected
+ * resource metadata whose `resource` exactly identifies the endpoint and
+ * which names at least one authorization server.
+ */
+export declare function hasValidatedMcpAuthorizationRequirements(requirements: AuthorizationRequirements, agentUrl: string): boolean;
 /**
  * Probe the agent for the parsed `WWW-Authenticate` challenge on a 401.
  *

package/dist/lib/auth/oauth/authorization-required.js

@@ -20,6 +20,7 @@ var authorization_required_exports = {};
 __export(authorization_required_exports, {
   NeedsAuthorizationError: () => NeedsAuthorizationError,
   discoverAuthorizationRequirements: () => discoverAuthorizationRequirements,
+  hasValidatedMcpAuthorizationRequirements: () => hasValidatedMcpAuthorizationRequirements,
   probeAuthChallenge: () => probeAuthChallenge
 });
 module.exports = __toCommonJS(authorization_required_exports);
@@ -27,6 +28,7 @@ var import_net = require('../../net/index.js');
 var import_errors = require('../../errors/index.js');
 var import_abort = require('../../protocols/abort.js');
 var import_diagnostics = require('./diagnostics.js');
+var import_resource_url = require('./resource-url.js');
 const MAX_DISPLAY_STRING = 256;
 const MAX_SCOPES = 64;
 const MAX_CHALLENGE_PARAMS = 32;
@@ -106,14 +108,22 @@ async function discoverAuthorizationRequirements(agentUrl, options = {}) {
   }
   const requirements = {
     agentUrl,
-    resourceMetadataUrl: challenge.resource_metadata ? sanitizeDisplay(challenge.resource_metadata) : void 0,
     challengeScope: challenge.scope ? sanitizeDisplay(challenge.scope) : void 0,
     challenge: sanitizeChallenge(challenge)
   };
-  if (challenge.resource_metadata && isSafeHttpUrl(challenge.resource_metadata)) {
+  let resourceMetadataUrl = challenge.resource_metadata;
+  if (!resourceMetadataUrl) {
+    try {
+      resourceMetadataUrl = (0, import_resource_url.buildProtectedResourceMetadataUrl)(agentUrl);
+    } catch {
+      resourceMetadataUrl = void 0;
+    }
+  }
+  if (resourceMetadataUrl) requirements.resourceMetadataUrl = sanitizeDisplay(resourceMetadataUrl);
+  if (resourceMetadataUrl && isSafeHttpUrl(resourceMetadataUrl)) {
     const prm = await fetchJson(
-      challenge.resource_metadata,
-      allowPrivateIpForHop(challenge.resource_metadata),
+      resourceMetadataUrl,
+      allowPrivateIpForHop(resourceMetadataUrl),
       options.timeoutMs,
       options.fetchFn,
       options.signal
@@ -187,6 +197,9 @@ async function discoverAuthorizationRequirements(agentUrl, options = {}) {
   }
   return requirements;
 }
+function hasValidatedMcpAuthorizationRequirements(requirements, agentUrl) {
+  return (0, import_resource_url.normalizeOAuthResourceForComparison)(requirements.resource ?? "") === (0, import_resource_url.normalizeOAuthResourceForComparison)(agentUrl) && Array.isArray(requirements.authorizationServers) && requirements.authorizationServers.length > 0;
+}
 async function probeAuthChallenge(agentUrl, options = {}) {
   const probe = await probeAgent401(
     agentUrl,
@@ -267,5 +280,6 @@ async function fetchJson(url, allowPrivateIp, timeoutMs, fetchFn, signal) {
 0 && (module.exports = {
   NeedsAuthorizationError,
   discoverAuthorizationRequirements,
+  hasValidatedMcpAuthorizationRequirements,
   probeAuthChallenge
 });

package/dist/lib/auth/oauth/authorization-required.mjs

@@ -2,6 +2,7 @@ import { ssrfSafeFetch, decodeBodyAsJsonOrText } from "../../net/index.mjs";
 import { AuthenticationRequiredError } from "../../errors/index.mjs";
 import { throwIfAborted } from "../../protocols/abort.mjs";
 import { parseWWWAuthenticate } from "./diagnostics.mjs";
+import { buildProtectedResourceMetadataUrl, normalizeOAuthResourceForComparison } from "./resource-url.mjs";
 const MAX_DISPLAY_STRING = 256;
 const MAX_SCOPES = 64;
 const MAX_CHALLENGE_PARAMS = 32;
@@ -81,14 +82,22 @@ async function discoverAuthorizationRequirements(agentUrl, options = {}) {
   }
   const requirements = {
     agentUrl,
-    resourceMetadataUrl: challenge.resource_metadata ? sanitizeDisplay(challenge.resource_metadata) : void 0,
     challengeScope: challenge.scope ? sanitizeDisplay(challenge.scope) : void 0,
     challenge: sanitizeChallenge(challenge)
   };
-  if (challenge.resource_metadata && isSafeHttpUrl(challenge.resource_metadata)) {
+  let resourceMetadataUrl = challenge.resource_metadata;
+  if (!resourceMetadataUrl) {
+    try {
+      resourceMetadataUrl = buildProtectedResourceMetadataUrl(agentUrl);
+    } catch {
+      resourceMetadataUrl = void 0;
+    }
+  }
+  if (resourceMetadataUrl) requirements.resourceMetadataUrl = sanitizeDisplay(resourceMetadataUrl);
+  if (resourceMetadataUrl && isSafeHttpUrl(resourceMetadataUrl)) {
     const prm = await fetchJson(
-      challenge.resource_metadata,
-      allowPrivateIpForHop(challenge.resource_metadata),
+      resourceMetadataUrl,
+      allowPrivateIpForHop(resourceMetadataUrl),
       options.timeoutMs,
       options.fetchFn,
       options.signal
@@ -162,6 +171,9 @@ async function discoverAuthorizationRequirements(agentUrl, options = {}) {
   }
   return requirements;
 }
+function hasValidatedMcpAuthorizationRequirements(requirements, agentUrl) {
+  return normalizeOAuthResourceForComparison(requirements.resource ?? "") === normalizeOAuthResourceForComparison(agentUrl) && Array.isArray(requirements.authorizationServers) && requirements.authorizationServers.length > 0;
+}
 async function probeAuthChallenge(agentUrl, options = {}) {
   const probe = await probeAgent401(
     agentUrl,
@@ -241,5 +253,6 @@ async function fetchJson(url, allowPrivateIp, timeoutMs, fetchFn, signal) {
 export {
   NeedsAuthorizationError,
   discoverAuthorizationRequirements,
+  hasValidatedMcpAuthorizationRequirements,
   probeAuthChallenge
 };

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

@@ -138,7 +138,7 @@ export declare function getEffectiveAuthToken(agent: AgentConfig): string | unde
 export { discoverOAuthMetadata, supportsOAuth, supportsDynamicRegistration, type OAuthMetadata, type DiscoveryOptions, } from './discovery.mjs';
 export { parseWWWAuthenticate, decodeAccessTokenClaims, validateTokenAudience, type WWWAuthenticateChallenge, type DecodedJWTHeader, type DecodedJWTClaims, type DecodedAccessToken, type TokenAudienceResult, } from './diagnostics.mjs';
 export { runAuthDiagnosis, AUTH_DIAGNOSIS_SCHEMA_VERSION, type DiagnoseOptions, type HttpCapture, type DiagnosisStep, type Hypothesis, type HypothesisVerdict, type AuthDiagnosisReport, } from './diagnose.mjs';
-export { NeedsAuthorizationError, discoverAuthorizationRequirements, probeAuthChallenge, type AuthorizationRequirements, type DiscoverAuthorizationOptions, } from './authorization-required.mjs';
+export { NeedsAuthorizationError, discoverAuthorizationRequirements, hasValidatedMcpAuthorizationRequirements, probeAuthChallenge, type AuthorizationRequirements, type DiscoverAuthorizationOptions, } from './authorization-required.mjs';
 export { createFileOAuthStorage, type FileOAuthStorageOptions } from './file-storage.mjs';
 export { exchangeClientCredentials, ensureClientCredentialsTokens, ClientCredentialsExchangeError, type ExchangeClientCredentialsOptions, type EnsureClientCredentialsOptions, } from './ClientCredentialsFlow.mjs';
 export { resolveSecret, isEnvSecretReference, toEnvSecretReference, extractEnvSecretName, MissingEnvSecretError, } from './secret-resolver.mjs';

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

@@ -138,7 +138,7 @@ export declare function getEffectiveAuthToken(agent: AgentConfig): string | unde
 export { discoverOAuthMetadata, supportsOAuth, supportsDynamicRegistration, type OAuthMetadata, type DiscoveryOptions, } from './discovery';
 export { parseWWWAuthenticate, decodeAccessTokenClaims, validateTokenAudience, type WWWAuthenticateChallenge, type DecodedJWTHeader, type DecodedJWTClaims, type DecodedAccessToken, type TokenAudienceResult, } from './diagnostics';
 export { runAuthDiagnosis, AUTH_DIAGNOSIS_SCHEMA_VERSION, type DiagnoseOptions, type HttpCapture, type DiagnosisStep, type Hypothesis, type HypothesisVerdict, type AuthDiagnosisReport, } from './diagnose';
-export { NeedsAuthorizationError, discoverAuthorizationRequirements, probeAuthChallenge, type AuthorizationRequirements, type DiscoverAuthorizationOptions, } from './authorization-required';
+export { NeedsAuthorizationError, discoverAuthorizationRequirements, hasValidatedMcpAuthorizationRequirements, probeAuthChallenge, type AuthorizationRequirements, type DiscoverAuthorizationOptions, } from './authorization-required';
 export { createFileOAuthStorage, type FileOAuthStorageOptions } from './file-storage';
 export { exchangeClientCredentials, ensureClientCredentialsTokens, ClientCredentialsExchangeError, type ExchangeClientCredentialsOptions, type EnsureClientCredentialsOptions, } from './ClientCredentialsFlow';
 export { resolveSecret, isEnvSecretReference, toEnvSecretReference, extractEnvSecretName, MissingEnvSecretError, } from './secret-resolver';

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

@@ -58,6 +58,7 @@ __export(oauth_exports, {
   getAgentStorage: () => import_storage_registry.getAgentStorage,
   getEffectiveAuthToken: () => getEffectiveAuthToken,
   hasValidOAuthTokens: () => hasValidOAuthTokens,
+  hasValidatedMcpAuthorizationRequirements: () => import_authorization_required.hasValidatedMcpAuthorizationRequirements,
   isEnvSecretReference: () => import_secret_resolver.isEnvSecretReference,
   isOAuthRequired: () => isOAuthRequired,
   parseWWWAuthenticate: () => import_diagnostics.parseWWWAuthenticate,
@@ -204,6 +205,7 @@ function getEffectiveAuthToken(agent) {
   getAgentStorage,
   getEffectiveAuthToken,
   hasValidOAuthTokens,
+  hasValidatedMcpAuthorizationRequirements,
   isEnvSecretReference,
   isOAuthRequired,
   parseWWWAuthenticate,

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

@@ -116,6 +116,7 @@ import {
 import {
   NeedsAuthorizationError,
   discoverAuthorizationRequirements,
+  hasValidatedMcpAuthorizationRequirements,
   probeAuthChallenge
 } from "./authorization-required.mjs";
 import { createFileOAuthStorage } from "./file-storage.mjs";
@@ -174,6 +175,7 @@ export {
   getAgentStorage,
   getEffectiveAuthToken,
   hasValidOAuthTokens,
+  hasValidatedMcpAuthorizationRequirements,
   isEnvSecretReference,
   isOAuthRequired,
   parseWWWAuthenticate,

package/dist/lib/auth/oauth/resource-url.d.mts

@@ -1,3 +1,11 @@
+/**
+ * RFC 9728 resource comparison semantics used by OAuth discovery and
+ * compliance grading. Scheme and host are case-insensitive and default ports
+ * are equivalent; the remainder stays byte-for-byte significant.
+ */
+export declare function normalizeOAuthResourceForComparison(value: string): string;
+/** Build the RFC 9728 well-known metadata URL for a protected resource. */
+export declare function buildProtectedResourceMetadataUrl(agentUrl: string): string;
 /** Validate and canonicalize an operator-configured RFC 8707 resource URI. */
 export declare function validateOAuthResourceUrl(value: string, options?: {
     allowHttp?: boolean;

package/dist/lib/auth/oauth/resource-url.d.ts

@@ -1,3 +1,11 @@
+/**
+ * RFC 9728 resource comparison semantics used by OAuth discovery and
+ * compliance grading. Scheme and host are case-insensitive and default ports
+ * are equivalent; the remainder stays byte-for-byte significant.
+ */
+export declare function normalizeOAuthResourceForComparison(value: string): string;
+/** Build the RFC 9728 well-known metadata URL for a protected resource. */
+export declare function buildProtectedResourceMetadataUrl(agentUrl: string): string;
 /** Validate and canonicalize an operator-configured RFC 8707 resource URI. */
 export declare function validateOAuthResourceUrl(value: string, options?: {
     allowHttp?: boolean;

package/dist/lib/auth/oauth/resource-url.js

@@ -18,11 +18,51 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var resource_url_exports = {};
 __export(resource_url_exports, {
+  buildProtectedResourceMetadataUrl: () => buildProtectedResourceMetadataUrl,
+  normalizeOAuthResourceForComparison: () => normalizeOAuthResourceForComparison,
   validateOAuthResourceUrl: () => validateOAuthResourceUrl
 });
 module.exports = __toCommonJS(resource_url_exports);
 var import_types = require('./types.js');
 const MAX_RESOURCE_URL_LENGTH = 2048;
+function normalizeOAuthResourceForComparison(value) {
+  const match = /^([A-Za-z][A-Za-z\d+.-]*):\/\/([^/?#]*)([\s\S]*)$/.exec(value);
+  if (!match) return value;
+  const scheme = match[1].toLowerCase();
+  const authority = match[2];
+  const remainder = match[3];
+  const at = authority.lastIndexOf("@");
+  const userinfo = at >= 0 ? authority.slice(0, at + 1) : "";
+  const hostAndPort = at >= 0 ? authority.slice(at + 1) : authority;
+  let host;
+  let port = "";
+  if (hostAndPort.startsWith("[")) {
+    const bracket = hostAndPort.indexOf("]");
+    if (bracket < 0) return value;
+    host = hostAndPort.slice(0, bracket + 1).toLowerCase();
+    const suffix = hostAndPort.slice(bracket + 1);
+    if (suffix && !/^:\d+$/.test(suffix)) return value;
+    port = suffix.slice(1);
+  } else {
+    const colon = hostAndPort.lastIndexOf(":");
+    if (colon >= 0) {
+      const suffix = hostAndPort.slice(colon + 1);
+      if (!/^\d+$/.test(suffix)) return value;
+      host = hostAndPort.slice(0, colon).toLowerCase();
+      port = suffix;
+    } else {
+      host = hostAndPort.toLowerCase();
+    }
+  }
+  if (!host) return value;
+  const defaultPort = scheme === "https" ? "443" : scheme === "http" ? "80" : void 0;
+  const renderedPort = port && port !== defaultPort ? `:${port}` : "";
+  return `${scheme}://${userinfo}${host}${renderedPort}${remainder}`;
+}
+function buildProtectedResourceMetadataUrl(agentUrl) {
+  const url = new URL(agentUrl);
+  return `${url.origin}/.well-known/oauth-protected-resource${url.pathname}`;
+}
 function validateOAuthResourceUrl(value, options = {}) {
   if (value.length === 0 || value.length > MAX_RESOURCE_URL_LENGTH) {
     throw new import_types.OAuthError("OAuth resource override must be between 1 and 2048 characters", "invalid_resource_override");
@@ -46,5 +86,7 @@ function validateOAuthResourceUrl(value, options = {}) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  buildProtectedResourceMetadataUrl,
+  normalizeOAuthResourceForComparison,
   validateOAuthResourceUrl
 });

package/dist/lib/auth/oauth/resource-url.mjs

@@ -1,5 +1,43 @@
 import { OAuthError } from "./types.mjs";
 const MAX_RESOURCE_URL_LENGTH = 2048;
+function normalizeOAuthResourceForComparison(value) {
+  const match = /^([A-Za-z][A-Za-z\d+.-]*):\/\/([^/?#]*)([\s\S]*)$/.exec(value);
+  if (!match) return value;
+  const scheme = match[1].toLowerCase();
+  const authority = match[2];
+  const remainder = match[3];
+  const at = authority.lastIndexOf("@");
+  const userinfo = at >= 0 ? authority.slice(0, at + 1) : "";
+  const hostAndPort = at >= 0 ? authority.slice(at + 1) : authority;
+  let host;
+  let port = "";
+  if (hostAndPort.startsWith("[")) {
+    const bracket = hostAndPort.indexOf("]");
+    if (bracket < 0) return value;
+    host = hostAndPort.slice(0, bracket + 1).toLowerCase();
+    const suffix = hostAndPort.slice(bracket + 1);
+    if (suffix && !/^:\d+$/.test(suffix)) return value;
+    port = suffix.slice(1);
+  } else {
+    const colon = hostAndPort.lastIndexOf(":");
+    if (colon >= 0) {
+      const suffix = hostAndPort.slice(colon + 1);
+      if (!/^\d+$/.test(suffix)) return value;
+      host = hostAndPort.slice(0, colon).toLowerCase();
+      port = suffix;
+    } else {
+      host = hostAndPort.toLowerCase();
+    }
+  }
+  if (!host) return value;
+  const defaultPort = scheme === "https" ? "443" : scheme === "http" ? "80" : void 0;
+  const renderedPort = port && port !== defaultPort ? `:${port}` : "";
+  return `${scheme}://${userinfo}${host}${renderedPort}${remainder}`;
+}
+function buildProtectedResourceMetadataUrl(agentUrl) {
+  const url = new URL(agentUrl);
+  return `${url.origin}/.well-known/oauth-protected-resource${url.pathname}`;
+}
 function validateOAuthResourceUrl(value, options = {}) {
   if (value.length === 0 || value.length > MAX_RESOURCE_URL_LENGTH) {
     throw new OAuthError("OAuth resource override must be between 1 and 2048 characters", "invalid_resource_override");
@@ -22,5 +60,7 @@ function validateOAuthResourceUrl(value, options = {}) {
   return url;
 }
 export {
+  buildProtectedResourceMetadataUrl,
+  normalizeOAuthResourceForComparison,
   validateOAuthResourceUrl
 };

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

@@ -1,4 +1,5 @@
 import type { ProductPropertyPolicyDiagnostic, ProductPropertyPolicyMode } from '../media-buy/property-policy.mjs';
+import type { DelegatedOperatorAuthorizationContext } from '../signing/agent-resolver/resolve-agent.mjs';
 /**
  * Represents a single message in a conversation with an agent
  */
@@ -152,6 +153,15 @@ export interface TaskOptions {
     debug?: boolean;
     /** Suppress automatic webhook URL generation for this call. */
     disableWebhook?: boolean;
+    /**
+     * Trusted local authorization tuple for a delegated, cross-origin seller.
+     * The SDK snapshots this before dispatch and persists it with any generated
+     * webhook registration. It is never inferred from or sent in task arguments.
+     *
+     * When present, this whole object takes precedence over the client-wide
+     * `webhookVerification.resolverOptions.requiredOperator*` fallback.
+     */
+    delegatedOperatorAuthorization?: DelegatedOperatorAuthorizationContext;
     /** Additional metadata to include */
     metadata?: Record<string, any>;
     /**

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

@@ -1,4 +1,5 @@
 import type { ProductPropertyPolicyDiagnostic, ProductPropertyPolicyMode } from '../media-buy/property-policy';
+import type { DelegatedOperatorAuthorizationContext } from '../signing/agent-resolver/resolve-agent';
 /**
  * Represents a single message in a conversation with an agent
  */
@@ -152,6 +153,15 @@ export interface TaskOptions {
     debug?: boolean;
     /** Suppress automatic webhook URL generation for this call. */
     disableWebhook?: boolean;
+    /**
+     * Trusted local authorization tuple for a delegated, cross-origin seller.
+     * The SDK snapshots this before dispatch and persists it with any generated
+     * webhook registration. It is never inferred from or sent in task arguments.
+     *
+     * When present, this whole object takes precedence over the client-wide
+     * `webhookVerification.resolverOptions.requiredOperator*` fallback.
+     */
+    delegatedOperatorAuthorization?: DelegatedOperatorAuthorizationContext;
     /** Additional metadata to include */
     metadata?: Record<string, any>;
     /**

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

@@ -457,6 +457,9 @@ export declare class SingleAgentClient {
     private readonly durableDeferredResumeTokenReplacers;
     constructor(agent: AgentConfig, config?: SingleAgentClientConfig);
     private persistWebhookRegistration;
+    private configuredDelegatedOperatorAuthorization;
+    private effectiveDelegatedOperatorAuthorization;
+    private delegatedOperatorAuthorizationForRegistration;
     private markWebhookDurableSettlementRequired;
     private webhookJwksFor;
     private resolveLegacyFormatConverter;
@@ -536,8 +539,8 @@ export declare 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
      */

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

@@ -457,6 +457,9 @@ export declare class SingleAgentClient {
     private readonly durableDeferredResumeTokenReplacers;
     constructor(agent: AgentConfig, config?: SingleAgentClientConfig);
     private persistWebhookRegistration;
+    private configuredDelegatedOperatorAuthorization;
+    private effectiveDelegatedOperatorAuthorization;
+    private delegatedOperatorAuthorizationForRegistration;
     private markWebhookDurableSettlementRequired;
     private webhookJwksFor;
     private resolveLegacyFormatConverter;
@@ -536,8 +539,8 @@ export declare 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
      */