@adcp/sdk 14.0.0 → 14.2.0

package/dist/lib/signing/agent-resolver/resolve-agent.mjs

@@ -1,8 +1,12 @@
 import { parse as parseTld } from "tldts";
+import { isIP } from "node:net";
 import { createA2AClient, createMCPClient } from "../../protocols/index.mjs";
 import { isDevelopmentBrandDomain } from "../../brand/domain.mjs";
 import { readBrandJsonUrl, readIdentityPosture } from "./capabilities-types.mjs";
-import { canonicalizeOrigin } from "./canonicalize.mjs";
+import { isAlwaysBlocked, isPrivateIp } from "../../net/index.mjs";
+import { AgentTransportPolicyError, createAgentTransportFetch } from "../../net/agent-transport-fetch.mjs";
+import { checkDelegatedOperatorAuthorization } from "./operator-authorization.mjs";
+import { fetchLegacyBrandJson } from "./legacy-brand.mjs";
 import {
   checkOriginConsistency,
   checkRequiredOrigins,
@@ -10,9 +14,16 @@ import {
 } from "./consistency.mjs";
 import { AgentResolverError } from "./errors.mjs";
 import { eTldPlusOne, sameEtldPlusOne } from "./etld.mjs";
-import { MAX_BRAND_JSON_BYTES, MAX_JWKS_BYTES, safeFetchJson, SafeFetchError } from "./fetch-helpers.mjs";
+import {
+  MAX_BRAND_JSON_BYTES,
+  MAX_JWKS_BYTES,
+  safeFetchJson,
+  SafeFetchError,
+  classifyDiscoveryFailure,
+  isPermanentDiscoveryFailure
+} from "./fetch-helpers.mjs";
 import { unwrapProtocolResponse } from "../protocol-response.mjs";
-import { selectAgentByUrl, AgentSelectorError } from "./select-agent.mjs";
+import { selectAgentByUrl, agentJwksUri, AgentSelectorError, canonicalAgentUrl } from "./select-agent.mjs";
 const DEFAULT_TIMEOUT_MS = 1e4;
 async function resolveAgent(agentUrl, options = {}) {
   const trace = [];
@@ -22,7 +33,7 @@ async function resolveAgent(agentUrl, options = {}) {
   const caps = options.bodyCaps ?? {};
   const brandJsonCap = caps.brandJsonBytes ?? MAX_BRAND_JSON_BYTES;
   const jwksCap = caps.jwksBytes ?? MAX_JWKS_BYTES;
-  const fetchCapabilities = options.fetchCapabilities ?? defaultFetchCapabilities(agentUrl, options.protocol ?? "mcp");
+  const fetchCapabilities = options.fetchCapabilities ?? defaultFetchCapabilities(agentUrl, options.protocol ?? "mcp", allowPrivateIp, timeoutMs);
   let capabilitiesPayload;
   let capabilitiesFetchedAt;
   try {
@@ -39,7 +50,7 @@ async function resolveAgent(agentUrl, options = {}) {
   } catch (err) {
     const detail = {
       agent_url: agentUrl,
-      dns_error: err instanceof SafeFetchError ? err.transport : "fetch_failed",
+      ...classifyDiscoveryFailure(err),
       last_attempt_at: now()
     };
     pushTrace(trace, { step: 1, name: "fetch_capabilities", ok: false, url: agentUrl, detail });
@@ -50,7 +61,10 @@ async function resolveAgent(agentUrl, options = {}) {
       ["agent_url"]
     );
   }
-  const brandJsonUrl = readBrandJsonUrl(capabilitiesPayload);
+  let brandJsonUrl = readBrandJsonUrl(capabilitiesPayload);
+  const identity = capabilitiesPayload?.identity;
+  const legacyFallback = options.legacyWebhookFallback === true && identity?.brand_json_url === void 0 && permitsLegacyWebhookDiscovery(capabilitiesPayload);
+  if (legacyFallback) brandJsonUrl = `${new URL(agentUrl).origin}/.well-known/brand.json`;
   const identityPosture = readIdentityPosture(capabilitiesPayload);
   const acceptsScheme = (url) => {
     if (!url) return false;
@@ -68,24 +82,43 @@ async function resolveAgent(agentUrl, options = {}) {
       ["agent_url"]
     );
   }
+  if (!legacyFallback && options.expectedBrandJsonUrl !== void 0 && canonicalAgentUrl(brandJsonUrl) !== canonicalAgentUrl(options.expectedBrandJsonUrl)) {
+    throw new AgentResolverError(
+      "request_signature_brand_origin_mismatch",
+      "Cached operator mapping disagrees with identity.brand_json_url",
+      { agent_url: agentUrl },
+      ["agent_url"]
+    );
+  }
   pushTrace(trace, { step: 2, name: "read_brand_json_url", ok: true, detail: { brand_json_url: brandJsonUrl } });
-  let agentEtld1;
-  let brandEtld1;
-  let sameOrigin;
-  try {
-    agentEtld1 = eTldPlusOne(agentUrl);
-    brandEtld1 = eTldPlusOne(brandJsonUrl);
-    sameOrigin = sameEtldPlusOne(agentUrl, brandJsonUrl);
-  } catch {
-    if (allowPrivateIp) {
-      const agentHost = new URL(agentUrl).hostname;
-      const brandHost = new URL(brandJsonUrl).hostname;
-      const agentIsExplicitDevelopmentHost = agentHost === "localhost" || isDevelopmentBrandDomain(agentHost) || parseTld(agentHost, { extractHostname: false }).isIp;
-      const brandIsExplicitDevelopmentHost = brandHost === "localhost" || isDevelopmentBrandDomain(brandHost) || parseTld(brandHost, { extractHostname: false }).isIp;
-      if (agentIsExplicitDevelopmentHost && brandIsExplicitDevelopmentHost) {
-        agentEtld1 = agentHost;
-        brandEtld1 = brandHost;
-        sameOrigin = agentHost === brandHost;
+  let agentEtld1 = "";
+  let brandEtld1 = "";
+  let sameOrigin = true;
+  if (!legacyFallback) {
+    try {
+      agentEtld1 = eTldPlusOne(agentUrl);
+      brandEtld1 = eTldPlusOne(brandJsonUrl);
+      sameOrigin = sameEtldPlusOne(agentUrl, brandJsonUrl);
+    } catch {
+      if (allowPrivateIp) {
+        const agentHost = new URL(agentUrl).hostname;
+        const brandHost = new URL(brandJsonUrl).hostname;
+        const agentIsExplicitDevelopmentHost = agentHost === "localhost" || isDevelopmentBrandDomain(agentHost) || parseTld(agentHost, { extractHostname: false }).isIp;
+        const brandIsExplicitDevelopmentHost = brandHost === "localhost" || isDevelopmentBrandDomain(brandHost) || parseTld(brandHost, { extractHostname: false }).isIp;
+        if (agentIsExplicitDevelopmentHost && brandIsExplicitDevelopmentHost) {
+          agentEtld1 = agentHost;
+          brandEtld1 = brandHost;
+          sameOrigin = agentHost === brandHost;
+        } else {
+          const detail = { agent_url: agentUrl, brand_json_url: brandJsonUrl };
+          pushTrace(trace, { step: 3, name: "etld1_binding", ok: false, detail });
+          throw new AgentResolverError(
+            "request_signature_brand_origin_mismatch",
+            `Cannot compute eTLD+1 for agent or brand.json host`,
+            detail,
+            ["agent_url", "brand_json_url"]
+          );
+        }
       } else {
         const detail = { agent_url: agentUrl, brand_json_url: brandJsonUrl };
         pushTrace(trace, { step: 3, name: "etld1_binding", ok: false, detail });
@@ -96,25 +129,24 @@ async function resolveAgent(agentUrl, options = {}) {
           ["agent_url", "brand_json_url"]
         );
       }
-    } else {
-      const detail = { agent_url: agentUrl, brand_json_url: brandJsonUrl };
-      pushTrace(trace, { step: 3, name: "etld1_binding", ok: false, detail });
-      throw new AgentResolverError(
-        "request_signature_brand_origin_mismatch",
-        `Cannot compute eTLD+1 for agent or brand.json host`,
-        detail,
-        ["agent_url", "brand_json_url"]
-      );
     }
   }
   let brandJson;
   let brandJsonFetchedAt;
+  let brandJsonCacheControl;
   try {
-    const fetched = await safeFetchJson(brandJsonUrl, "brand.json", {
-      allowPrivateIp,
-      timeoutMs,
-      maxBodyBytes: brandJsonCap
-    });
+    const fetchOptions = { allowPrivateIp, timeoutMs, maxBodyBytes: brandJsonCap, lookup: options.lookup };
+    const fetched = legacyFallback ? await fetchLegacyBrandJson(agentUrl, fetchOptions) : await safeFetchJson(brandJsonUrl, "brand.json", fetchOptions);
+    if (legacyFallback && "url" in fetched) brandJsonUrl = fetched.url;
+    brandJsonCacheControl = fetched.headers["cache-control"];
+    if (legacyFallback && options.expectedBrandJsonUrl !== void 0 && canonicalAgentUrl(brandJsonUrl) !== canonicalAgentUrl(options.expectedBrandJsonUrl) && canonicalAgentUrl(`${new URL(agentUrl).origin}/.well-known/brand.json`) !== canonicalAgentUrl(options.expectedBrandJsonUrl)) {
+      throw new AgentResolverError(
+        "request_signature_brand_origin_mismatch",
+        "Cached mapping disagrees with legacy discovery",
+        { agent_url: agentUrl },
+        ["agent_url"]
+      );
+    }
     brandJson = fetched.body;
     brandJsonFetchedAt = fetched.fetchedAt;
     pushTrace(trace, {
@@ -125,6 +157,7 @@ async function resolveAgent(agentUrl, options = {}) {
       url: brandJsonUrl
     });
   } catch (err) {
+    if (err instanceof AgentResolverError) throw err;
     if (err instanceof SafeFetchError && /strict-JSON parse/.test(err.message)) {
       const detail2 = {
         brand_json_url: brandJsonUrl,
@@ -168,7 +201,17 @@ async function resolveAgent(agentUrl, options = {}) {
         ["agent_url"]
       );
     }
-    operatorAuthorizationValidUntil = delegation.validUntil;
+    if (options.requiredOperatorBrand !== void 0 || options.requiredOperatorScope !== void 0 || options.requiredOperatorCountry !== void 0) {
+      const authorization = checkDelegatedOperatorAuthorization(brandJson, agentEtld1, now(), options);
+      if (!authorization)
+        throw new AgentResolverError(
+          "request_signature_brand_origin_mismatch",
+          "Delegated operator does not satisfy the receiver account authorization policy",
+          { agent_url: agentUrl },
+          ["agent_url"]
+        );
+      operatorAuthorizationValidUntil = authorization.validUntil;
+    }
     pushTrace(trace, {
       step: 3,
       name: "etld1_binding",
@@ -185,7 +228,7 @@ async function resolveAgent(agentUrl, options = {}) {
   }
   let agentEntry;
   try {
-    agentEntry = selectAgentByUrl(brandJson, agentUrl);
+    agentEntry = selectAgentByUrl(brandJson, agentUrl, options);
     pushTrace(trace, { step: 5, name: "select_agent", ok: true, detail: { url: agentEntry.url } });
   } catch (err) {
     if (err instanceof AgentSelectorError) {
@@ -208,17 +251,19 @@ async function resolveAgent(agentUrl, options = {}) {
       pushTrace(trace, { step: 5, name: "select_agent", ok: false, detail });
       throw new AgentResolverError(code, err.message, detail, attacker);
     }
-    throw err;
+    throw new AgentResolverError(
+      "request_signature_brand_json_malformed",
+      "Matched agent has an invalid URL or JWKS source",
+      { brand_json_url: brandJsonUrl },
+      ["brand_json_url"]
+    );
   }
-  const declaredJwksUri = agentEntry.jwks_uri;
-  const jwksUriFromEntry = typeof declaredJwksUri === "string" && acceptsScheme(declaredJwksUri) ? declaredJwksUri : void 0;
-  const jwksUri = jwksUriFromEntry ?? `${originOf(agentUrl)}/.well-known/jwks.json`;
+  const jwksUri = agentJwksUri(agentEntry);
   pushTrace(trace, { step: 6, name: "resolve_jwks_uri", ok: true, detail: { jwks_uri: jwksUri } });
-  const consistencyResults = runConsistencyChecks({
+  const consistencyResults = legacyFallback ? [] : runConsistencyChecks({
     capabilitiesPayload,
     identityPosture,
     jwksUri,
-    publisherPinnedWebhookSigning: options.publisherPinned?.webhook_signing === true,
     extraDeclaredPurposes: options.declaredPurposes ?? []
   });
   const failedConsistency = consistencyResults.filter((r) => r.ok === false);
@@ -251,7 +296,8 @@ async function resolveAgent(agentUrl, options = {}) {
     const fetched = await safeFetchJson(jwksUri, "jwks", {
       allowPrivateIp,
       timeoutMs,
-      maxBodyBytes: jwksCap
+      maxBodyBytes: jwksCap,
+      lookup: options.lookup
     });
     if (!fetched.body || typeof fetched.body !== "object" || !Array.isArray(fetched.body.keys)) {
       throw new SafeFetchError("jwks", "fetch_failed", "JWKS document has no keys[] array");
@@ -288,8 +334,11 @@ async function resolveAgent(agentUrl, options = {}) {
     );
   }
   return {
-    agentUrl,
+    agentUrl: canonicalAgentUrl(agentEntry.url),
     brandJsonUrl,
+    brandJson,
+    ...legacyFallback && { legacyWebhookFallback: true },
+    ...brandJsonCacheControl !== void 0 && { brandJsonCacheControl },
     agentEntry,
     jwksUri,
     jwks,
@@ -310,101 +359,59 @@ function checkAllowPrivateIp(requested) {
     "resolveAgent: allowPrivateIp=true refused outside {NODE_ENV=test, NODE_ENV=development}. Set NODE_ENV appropriately for dev/test, or set ADCP_RESOLVER_ALLOW_PRIVATE_IP=1 as an explicit ops acknowledgment if you genuinely need private-IP discovery in this process."
   );
 }
-function defaultFetchCapabilities(agentUrl, protocol) {
+function defaultFetchCapabilities(agentUrl, protocol, allowPrivateIp, timeoutMs) {
   return async () => {
-    const client = protocol === "a2a" ? createA2AClient(agentUrl) : createMCPClient(agentUrl);
-    return client.callTool("get_adcp_capabilities", {});
-  };
-}
-const AUTHORIZED_OPERATOR_SCOPES = /* @__PURE__ */ new Set([
-  "all",
-  "media_buying",
-  "creative_generation",
-  "rights_clearance",
-  "governance",
-  "measurement",
-  "agent_operations"
-]);
-const AUTHORIZED_OPERATOR_DOMAIN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
-function findAuthorizedOperator(brandJson, agentEtld1, now, options) {
-  if (!brandJson || typeof brandJson !== "object") return void 0;
-  const operators = brandJson.authorized_operators;
-  if (!Array.isArray(operators)) return void 0;
-  let latestValidUntil;
-  let matched = false;
-  for (const op of operators) {
-    if (!op || typeof op !== "object" || Array.isArray(op)) continue;
-    const candidate = op;
-    const domain = candidate.domain;
-    const brands = candidate.brands;
-    if (typeof domain !== "string" || !AUTHORIZED_OPERATOR_DOMAIN.test(domain) || !isValidBrandGrant(brands)) {
-      continue;
-    }
-    try {
-      if (eTldPlusOne(domain) !== agentEtld1) continue;
-    } catch {
-      if (!(options.allowPrivateIp && isDevelopmentBrandDomain(domain) && domain === agentEtld1)) {
-        continue;
+    const url = new URL(agentUrl);
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    if (!allowPrivateIp && url.protocol !== "https:" || isIP(hostname) && (isAlwaysBlocked(hostname) || !allowPrivateIp && isPrivateIp(hostname)))
+      throw new AgentTransportPolicyError("Signing discovery URL refused by address or HTTPS policy.");
+    let failure;
+    const upstream = createAgentTransportFetch(agentUrl, {
+      allowPrivateIp,
+      allowPrivateInitialOrigin: false,
+      requireHttps: true
+    });
+    let postSucceeded = false;
+    const trustedFetchFn = async (input, init) => {
+      const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+      try {
+        const response = await upstream(input, init);
+        const isGet = method.toUpperCase() === "GET";
+        const observed = response.status >= 400 ? { dns_error: "fetch_failed", http_status: response.status } : void 0;
+        if (protocol === "mcp" && method.toUpperCase() === "POST" && response.ok) postSucceeded = true;
+        if (!(protocol === "mcp" && isGet && (postSucceeded || response.status === 405)) && !(isGet && observed && failure && !isPermanentDiscoveryFailure(failure) && isPermanentDiscoveryFailure(observed)))
+          failure = observed;
+        return response;
+      } catch (error) {
+        if (!(protocol === "mcp" && method.toUpperCase() === "GET" && postSucceeded))
+          failure = classifyDiscoveryFailure(error);
+        throw error;
       }
+    };
+    const transport = { trustedFetchFn, requestTimeoutMs: timeoutMs };
+    const client = protocol === "a2a" ? createA2AClient(agentUrl, void 0, void 0, void 0, void 0, transport) : createMCPClient(agentUrl, void 0, void 0, void 0, void 0, transport);
+    try {
+      return await client.callTool("get_adcp_capabilities", {});
+    } catch (error) {
+      if (failure)
+        throw new SafeFetchError(
+          "capabilities",
+          failure.dns_error,
+          "Capabilities fetch failed",
+          failure.http_status
+        );
+      throw error;
     }
-    const scopes = candidate.scopes;
-    if (scopes !== void 0 && !isValidScopeGrant(scopes)) continue;
-    const countries = candidate.countries;
-    if (countries !== void 0 && !isValidCountryGrant(countries)) continue;
-    const validFrom = parseOptionalRfc3339(candidate.valid_from);
-    const validUntil = parseOptionalRfc3339(candidate.valid_until);
-    if (validFrom === null || validUntil === null) continue;
-    if (validFrom !== void 0 && validUntil !== void 0 && validFrom >= validUntil) continue;
-    if (validFrom !== void 0 && now < validFrom) continue;
-    if (validUntil !== void 0 && now >= validUntil) continue;
-    if (!matchesGrant(brands, options.requiredOperatorBrand, "*")) continue;
-    if (scopes !== void 0 && !matchesGrant(scopes, options.requiredOperatorScope, "all")) continue;
-    if (countries !== void 0 && !matchesGrant(countries, options.requiredOperatorCountry)) continue;
-    matched = true;
-    if (validUntil === void 0) return {};
-    latestValidUntil = Math.max(latestValidUntil ?? Number.NEGATIVE_INFINITY, validUntil);
-  }
-  return matched ? { validUntil: latestValidUntil } : void 0;
-}
-function isValidBrandGrant(value) {
-  return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string" && (item === "*" || /^[a-z0-9_]+$/.test(item)));
-}
-function isValidScopeGrant(value) {
-  return Array.isArray(value) && value.length > 0 && new Set(value).size === value.length && value.every((item) => typeof item === "string" && AUTHORIZED_OPERATOR_SCOPES.has(item));
-}
-function isValidCountryGrant(value) {
-  return Array.isArray(value) && value.every((item) => typeof item === "string" && /^[A-Z]{2}$/.test(item));
-}
-function matchesGrant(grants, required, wildcard) {
-  if (wildcard !== void 0 && grants.includes(wildcard)) return true;
-  return required !== void 0 && grants.includes(required);
+  };
 }
-function parseOptionalRfc3339(value) {
-  if (value === void 0) return void 0;
-  if (typeof value !== "string") return null;
-  const match = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?([Zz]|([+-])(\d{2}):(\d{2}))$/.exec(
-    value
-  );
-  if (!match) return null;
-  const year = Number(match[1]);
-  const month = Number(match[2]);
-  const day = Number(match[3]);
-  const hour = Number(match[4]);
-  const minute = Number(match[5]);
-  const second = Number(match[6]);
-  const offsetHour = match[10] === void 0 ? 0 : Number(match[10]);
-  const offsetMinute = match[11] === void 0 ? 0 : Number(match[11]);
-  if (month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month) || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59) {
-    return null;
+function findAuthorizedOperator(brandJson, agentEtld1, _now, _options) {
+  if (!brandJson || typeof brandJson !== "object") return void 0;
+  const obj = brandJson;
+  if (!obj.house || typeof obj.house !== "object" || Array.isArray(obj.house) || !Array.isArray(obj.brands)) {
+    return void 0;
   }
-  const parsed = Date.parse(value) / 1e3;
-  return Number.isFinite(parsed) ? parsed : null;
-}
-function daysInMonth(year, month) {
-  return new Date(Date.UTC(year, month, 0)).getUTCDate();
-}
-function originOf(url) {
-  return canonicalizeOrigin(url);
+  if (!Array.isArray(obj.authorized_operators)) return void 0;
+  return obj.authorized_operators.some((op) => op && typeof op === "object" && op.domain === agentEtld1) ? {} : void 0;
 }
 function pushTrace(trace, step) {
   trace.push(step);
@@ -426,14 +433,25 @@ function runConsistencyChecks(args) {
       const result = checkOriginConsistency({
         purpose,
         declaredOrigin,
-        resolvedJwksUri: args.jwksUri,
-        publisherPinned: purpose === "webhook_signing" && args.publisherPinnedWebhookSigning
+        resolvedJwksUri: args.jwksUri
       });
       if (result.ok === false) results.push(result);
     }
   }
   return results;
 }
+function permitsLegacyWebhookDiscovery(payload) {
+  if (!payload || typeof payload !== "object") return true;
+  const caps = payload;
+  const major = (value) => typeof value === "string" ? Number(/^(\d+)\./.exec(value)?.[1]) : value;
+  if (Number(major(caps.adcp_version)) >= 4 || Array.isArray(caps.adcp?.supported_versions) && caps.adcp.supported_versions.some((v) => Number(major(v)) >= 4) || Array.isArray(caps.adcp?.major_versions) && caps.adcp.major_versions.some((v) => typeof v === "number" && v >= 4))
+    return false;
+  if (caps.adcp_version !== void 0) return typeof caps.adcp_version === "string" && /^3\./.test(caps.adcp_version);
+  if (Array.isArray(caps.adcp?.supported_versions))
+    return caps.adcp.supported_versions.some((v) => typeof v === "string" && /^3\./.test(v));
+  if (Array.isArray(caps.adcp?.major_versions)) return caps.adcp.major_versions.includes(3);
+  return true;
+}
 export {
   resolveAgent
 };

package/dist/lib/signing/agent-resolver/resolved-agent-jwks.d.mts

@@ -1,7 +1,7 @@
 import type { AdcpJsonWebKey } from '../types.mjs';
 import type { JwksResolution, JwksResolver } from '../jwks.mjs';
 import { type AgentProtocol, type AgentResolution, type ResolveAgentOptions } from './resolve-agent.mjs';
-export interface ResolvedAgentJwksResolverOptions extends Pick<ResolveAgentOptions, 'fetchCapabilities' | 'allowPrivateIp' | 'bodyCaps' | 'timeoutMs' | 'now' | 'requiredOperatorBrand' | 'requiredOperatorScope' | 'requiredOperatorCountry'> {
+export interface ResolvedAgentJwksResolverOptions extends Pick<ResolveAgentOptions, 'fetchCapabilities' | 'agentType' | 'agentId' | 'expectedBrandJsonUrl' | 'legacyWebhookFallback' | 'lookup' | 'allowPrivateIp' | 'bodyCaps' | 'timeoutMs' | 'now' | 'requiredOperatorBrand' | 'requiredOperatorScope' | 'requiredOperatorCountry'> {
     /** Positive cache lifetime in seconds. Defaults to 300. */
     cacheTtlSeconds?: number;
     /** Cooldown before an unknown kid can force another discovery. Defaults to 30. */
@@ -18,14 +18,20 @@ export declare class ResolvedAgentJwksResolver implements JwksResolver {
     private readonly cacheTtlSeconds;
     private readonly unknownKidCooldownSeconds;
     private readonly resolveAgentFn;
+    private canonicalAgentUrl?;
+    private legacyWebhookFallback?;
+    private operatorRecord?;
+    get resolvedAgentUrl(): string | undefined;
     private keys;
     private expiresAt;
     private operatorAuthorizationValidUntil?;
     private lastUnknownKidRefresh;
+    private lastDiscoveryAttemptAt;
     private inFlight?;
     constructor(agentUrl: string, protocol: AgentProtocol, options?: ResolvedAgentJwksResolverOptions);
     resolve(keyid: string): Promise<AdcpJsonWebKey | null>;
     resolveWithMetadata(keyid: string): Promise<JwksResolution>;
+    forceRefresh(): Promise<void>;
     private resolution;
     private refresh;
 }

package/dist/lib/signing/agent-resolver/resolved-agent-jwks.d.ts

@@ -1,7 +1,7 @@
 import type { AdcpJsonWebKey } from '../types';
 import type { JwksResolution, JwksResolver } from '../jwks';
 import { type AgentProtocol, type AgentResolution, type ResolveAgentOptions } from './resolve-agent';
-export interface ResolvedAgentJwksResolverOptions extends Pick<ResolveAgentOptions, 'fetchCapabilities' | 'allowPrivateIp' | 'bodyCaps' | 'timeoutMs' | 'now' | 'requiredOperatorBrand' | 'requiredOperatorScope' | 'requiredOperatorCountry'> {
+export interface ResolvedAgentJwksResolverOptions extends Pick<ResolveAgentOptions, 'fetchCapabilities' | 'agentType' | 'agentId' | 'expectedBrandJsonUrl' | 'legacyWebhookFallback' | 'lookup' | 'allowPrivateIp' | 'bodyCaps' | 'timeoutMs' | 'now' | 'requiredOperatorBrand' | 'requiredOperatorScope' | 'requiredOperatorCountry'> {
     /** Positive cache lifetime in seconds. Defaults to 300. */
     cacheTtlSeconds?: number;
     /** Cooldown before an unknown kid can force another discovery. Defaults to 30. */
@@ -18,14 +18,20 @@ export declare class ResolvedAgentJwksResolver implements JwksResolver {
     private readonly cacheTtlSeconds;
     private readonly unknownKidCooldownSeconds;
     private readonly resolveAgentFn;
+    private canonicalAgentUrl?;
+    private legacyWebhookFallback?;
+    private operatorRecord?;
+    get resolvedAgentUrl(): string | undefined;
     private keys;
     private expiresAt;
     private operatorAuthorizationValidUntil?;
     private lastUnknownKidRefresh;
+    private lastDiscoveryAttemptAt;
     private inFlight?;
     constructor(agentUrl: string, protocol: AgentProtocol, options?: ResolvedAgentJwksResolverOptions);
     resolve(keyid: string): Promise<AdcpJsonWebKey | null>;
     resolveWithMetadata(keyid: string): Promise<JwksResolution>;
+    forceRefresh(): Promise<void>;
     private resolution;
     private refresh;
 }

package/dist/lib/signing/agent-resolver/resolved-agent-jwks.js

@@ -46,10 +46,17 @@ class ResolvedAgentJwksResolver {
   cacheTtlSeconds;
   unknownKidCooldownSeconds;
   resolveAgentFn;
+  canonicalAgentUrl;
+  legacyWebhookFallback;
+  operatorRecord;
+  get resolvedAgentUrl() {
+    return this.canonicalAgentUrl;
+  }
   keys = /* @__PURE__ */ new Map();
   expiresAt = 0;
   operatorAuthorizationValidUntil;
   lastUnknownKidRefresh = Number.NEGATIVE_INFINITY;
+  lastDiscoveryAttemptAt = Number.NEGATIVE_INFINITY;
   inFlight;
   async resolve(keyid) {
     return (await this.resolveWithMetadata(keyid)).jwk;
@@ -58,6 +65,15 @@ class ResolvedAgentJwksResolver {
     const now = this.now();
     let refreshed = false;
     if (now >= this.expiresAt) {
+      if (!this.inFlight && now - this.lastDiscoveryAttemptAt < 30) {
+        const expiredAuthorization = this.operatorAuthorizationValidUntil !== void 0 && now >= this.operatorAuthorizationValidUntil;
+        throw new import_errors.AgentResolverError(
+          expiredAuthorization ? "request_signature_brand_origin_mismatch" : "request_signature_brand_json_unreachable",
+          "Expired operator mapping cannot be used during the discovery cooldown",
+          { agent_url: this.agentUrl },
+          ["agent_url"]
+        );
+      }
       await this.refresh();
       refreshed = true;
     }
@@ -67,14 +83,22 @@ class ResolvedAgentJwksResolver {
       this.lastUnknownKidRefresh = now;
       return this.resolution(null);
     }
-    if (now - this.lastUnknownKidRefresh < this.unknownKidCooldownSeconds) return this.resolution(null);
+    if (now - Math.max(this.lastUnknownKidRefresh, this.lastDiscoveryAttemptAt) < Math.max(30, this.unknownKidCooldownSeconds))
+      return this.resolution(null);
     await this.refresh();
     this.lastUnknownKidRefresh = now;
     return this.resolution(this.keys.get(keyid) ?? null);
   }
+  async forceRefresh() {
+    this.expiresAt = 0;
+    await this.refresh();
+  }
   resolution(jwk) {
     return {
       jwk,
+      ...this.operatorRecord !== void 0 && { operatorRecord: this.operatorRecord },
+      ...this.legacyWebhookFallback && { legacyWebhookFallback: true },
+      ...this.resolvedAgentUrl !== void 0 && { agentUrl: this.resolvedAgentUrl },
       ...this.operatorAuthorizationValidUntil !== void 0 && {
         operatorAuthorizationValidUntil: this.operatorAuthorizationValidUntil
       }
@@ -82,23 +106,11 @@ class ResolvedAgentJwksResolver {
   }
   async refresh() {
     if (this.inFlight) return this.inFlight;
+    this.lastDiscoveryAttemptAt = this.now();
     this.inFlight = (async () => {
       const resolution = await this.resolveAgentFn(this.agentUrl, {
-        protocol: this.protocol,
-        ...this.options.fetchCapabilities && { fetchCapabilities: this.options.fetchCapabilities },
-        ...this.options.allowPrivateIp !== void 0 && { allowPrivateIp: this.options.allowPrivateIp },
-        ...this.options.bodyCaps && { bodyCaps: this.options.bodyCaps },
-        ...this.options.timeoutMs !== void 0 && { timeoutMs: this.options.timeoutMs },
-        ...this.options.now && { now: this.options.now },
-        ...this.options.requiredOperatorBrand !== void 0 && {
-          requiredOperatorBrand: this.options.requiredOperatorBrand
-        },
-        ...this.options.requiredOperatorScope !== void 0 && {
-          requiredOperatorScope: this.options.requiredOperatorScope
-        },
-        ...this.options.requiredOperatorCountry !== void 0 && {
-          requiredOperatorCountry: this.options.requiredOperatorCountry
-        }
+        ...this.options,
+        protocol: this.protocol
       });
       const refreshedAt = this.now();
       if (resolution.operatorAuthorizationValidUntil !== void 0 && refreshedAt >= resolution.operatorAuthorizationValidUntil) {
@@ -112,13 +124,28 @@ class ResolvedAgentJwksResolver {
       const next = /* @__PURE__ */ new Map();
       for (const candidate of resolution.jwks.keys) {
         if (candidate && typeof candidate === "object" && typeof candidate.kid === "string") {
+          if (next.has(candidate.kid))
+            throw new import_errors.AgentResolverError(
+              "request_signature_key_unknown",
+              "JWKS has duplicate key identifiers",
+              { agent_url: this.agentUrl },
+              ["agent_url"]
+            );
           next.set(candidate.kid, candidate);
         }
       }
       this.keys = next;
+      this.canonicalAgentUrl = resolution.agentUrl;
+      this.operatorRecord = resolution.brandJson === void 0 ? void 0 : { url: resolution.brandJsonUrl, document: resolution.brandJson };
+      this.legacyWebhookFallback = resolution.legacyWebhookFallback;
       this.operatorAuthorizationValidUntil = resolution.operatorAuthorizationValidUntil;
       this.expiresAt = Math.min(
-        refreshedAt + this.cacheTtlSeconds,
+        refreshedAt + Math.min(
+          this.cacheTtlSeconds,
+          1800,
+          Math.max(30, cacheLifetime(resolution.brandJsonCacheControl)),
+          Math.max(60, cacheLifetime(resolution.jwksCacheControl))
+        ),
         resolution.operatorAuthorizationValidUntil ?? Number.POSITIVE_INFINITY
       );
     })().finally(() => {
@@ -127,6 +154,12 @@ class ResolvedAgentJwksResolver {
     return this.inFlight;
   }
 }
+function cacheLifetime(cacheControl) {
+  if (!cacheControl) return Infinity;
+  if (/\bno-cache\b|\bno-store\b/i.test(cacheControl)) return 0;
+  const match = /(?:^|,)\s*max-age\s*=\s*"?(\d+)/i.exec(cacheControl);
+  return match ? Number(match[1]) : Infinity;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ResolvedAgentJwksResolver