@adcp/sdk 14.0.0 → 14.2.0

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

@@ -22,10 +22,14 @@ __export(resolve_agent_exports, {
 });
 module.exports = __toCommonJS(resolve_agent_exports);
 var import_tldts = require("tldts");
+var import_node_net = require("node:net");
 var import_protocols = require('../../protocols/index.js');
 var import_domain = require('../../brand/domain.js');
 var import_capabilities_types = require('./capabilities-types.js');
-var import_canonicalize = require('./canonicalize.js');
+var import_net = require('../../net/index.js');
+var import_agent_transport_fetch = require('../../net/agent-transport-fetch.js');
+var import_operator_authorization = require('./operator-authorization.js');
+var import_legacy_brand = require('./legacy-brand.js');
 var import_consistency = require('./consistency.js');
 var import_errors = require('./errors.js');
 var import_etld = require('./etld.js');
@@ -41,7 +45,7 @@ async function resolveAgent(agentUrl, options = {}) {
   const caps = options.bodyCaps ?? {};
   const brandJsonCap = caps.brandJsonBytes ?? import_fetch_helpers.MAX_BRAND_JSON_BYTES;
   const jwksCap = caps.jwksBytes ?? import_fetch_helpers.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 {
@@ -58,7 +62,7 @@ async function resolveAgent(agentUrl, options = {}) {
   } catch (err) {
     const detail = {
       agent_url: agentUrl,
-      dns_error: err instanceof import_fetch_helpers.SafeFetchError ? err.transport : "fetch_failed",
+      ...(0, import_fetch_helpers.classifyDiscoveryFailure)(err),
       last_attempt_at: now()
     };
     pushTrace(trace, { step: 1, name: "fetch_capabilities", ok: false, url: agentUrl, detail });
@@ -69,7 +73,10 @@ async function resolveAgent(agentUrl, options = {}) {
       ["agent_url"]
     );
   }
-  const brandJsonUrl = (0, import_capabilities_types.readBrandJsonUrl)(capabilitiesPayload);
+  let brandJsonUrl = (0, import_capabilities_types.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 = (0, import_capabilities_types.readIdentityPosture)(capabilitiesPayload);
   const acceptsScheme = (url) => {
     if (!url) return false;
@@ -87,24 +94,43 @@ async function resolveAgent(agentUrl, options = {}) {
       ["agent_url"]
     );
   }
+  if (!legacyFallback && options.expectedBrandJsonUrl !== void 0 && (0, import_select_agent.canonicalAgentUrl)(brandJsonUrl) !== (0, import_select_agent.canonicalAgentUrl)(options.expectedBrandJsonUrl)) {
+    throw new import_errors.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 = (0, import_etld.eTldPlusOne)(agentUrl);
-    brandEtld1 = (0, import_etld.eTldPlusOne)(brandJsonUrl);
-    sameOrigin = (0, import_etld.sameEtldPlusOne)(agentUrl, brandJsonUrl);
-  } catch {
-    if (allowPrivateIp) {
-      const agentHost = new URL(agentUrl).hostname;
-      const brandHost = new URL(brandJsonUrl).hostname;
-      const agentIsExplicitDevelopmentHost = agentHost === "localhost" || (0, import_domain.isDevelopmentBrandDomain)(agentHost) || (0, import_tldts.parse)(agentHost, { extractHostname: false }).isIp;
-      const brandIsExplicitDevelopmentHost = brandHost === "localhost" || (0, import_domain.isDevelopmentBrandDomain)(brandHost) || (0, import_tldts.parse)(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 = (0, import_etld.eTldPlusOne)(agentUrl);
+      brandEtld1 = (0, import_etld.eTldPlusOne)(brandJsonUrl);
+      sameOrigin = (0, import_etld.sameEtldPlusOne)(agentUrl, brandJsonUrl);
+    } catch {
+      if (allowPrivateIp) {
+        const agentHost = new URL(agentUrl).hostname;
+        const brandHost = new URL(brandJsonUrl).hostname;
+        const agentIsExplicitDevelopmentHost = agentHost === "localhost" || (0, import_domain.isDevelopmentBrandDomain)(agentHost) || (0, import_tldts.parse)(agentHost, { extractHostname: false }).isIp;
+        const brandIsExplicitDevelopmentHost = brandHost === "localhost" || (0, import_domain.isDevelopmentBrandDomain)(brandHost) || (0, import_tldts.parse)(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 import_errors.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 });
@@ -115,25 +141,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 import_errors.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 (0, import_fetch_helpers.safeFetchJson)(brandJsonUrl, "brand.json", {
-      allowPrivateIp,
-      timeoutMs,
-      maxBodyBytes: brandJsonCap
-    });
+    const fetchOptions = { allowPrivateIp, timeoutMs, maxBodyBytes: brandJsonCap, lookup: options.lookup };
+    const fetched = legacyFallback ? await (0, import_legacy_brand.fetchLegacyBrandJson)(agentUrl, fetchOptions) : await (0, import_fetch_helpers.safeFetchJson)(brandJsonUrl, "brand.json", fetchOptions);
+    if (legacyFallback && "url" in fetched) brandJsonUrl = fetched.url;
+    brandJsonCacheControl = fetched.headers["cache-control"];
+    if (legacyFallback && options.expectedBrandJsonUrl !== void 0 && (0, import_select_agent.canonicalAgentUrl)(brandJsonUrl) !== (0, import_select_agent.canonicalAgentUrl)(options.expectedBrandJsonUrl) && (0, import_select_agent.canonicalAgentUrl)(`${new URL(agentUrl).origin}/.well-known/brand.json`) !== (0, import_select_agent.canonicalAgentUrl)(options.expectedBrandJsonUrl)) {
+      throw new import_errors.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, {
@@ -144,6 +169,7 @@ async function resolveAgent(agentUrl, options = {}) {
       url: brandJsonUrl
     });
   } catch (err) {
+    if (err instanceof import_errors.AgentResolverError) throw err;
     if (err instanceof import_fetch_helpers.SafeFetchError && /strict-JSON parse/.test(err.message)) {
       const detail2 = {
         brand_json_url: brandJsonUrl,
@@ -187,7 +213,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 = (0, import_operator_authorization.checkDelegatedOperatorAuthorization)(brandJson, agentEtld1, now(), options);
+      if (!authorization)
+        throw new import_errors.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",
@@ -204,7 +240,7 @@ async function resolveAgent(agentUrl, options = {}) {
   }
   let agentEntry;
   try {
-    agentEntry = (0, import_select_agent.selectAgentByUrl)(brandJson, agentUrl);
+    agentEntry = (0, import_select_agent.selectAgentByUrl)(brandJson, agentUrl, options);
     pushTrace(trace, { step: 5, name: "select_agent", ok: true, detail: { url: agentEntry.url } });
   } catch (err) {
     if (err instanceof import_select_agent.AgentSelectorError) {
@@ -227,17 +263,19 @@ async function resolveAgent(agentUrl, options = {}) {
       pushTrace(trace, { step: 5, name: "select_agent", ok: false, detail });
       throw new import_errors.AgentResolverError(code, err.message, detail, attacker);
     }
-    throw err;
+    throw new import_errors.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 = (0, import_select_agent.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);
@@ -270,7 +308,8 @@ async function resolveAgent(agentUrl, options = {}) {
     const fetched = await (0, import_fetch_helpers.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 import_fetch_helpers.SafeFetchError("jwks", "fetch_failed", "JWKS document has no keys[] array");
@@ -307,8 +346,11 @@ async function resolveAgent(agentUrl, options = {}) {
     );
   }
   return {
-    agentUrl,
+    agentUrl: (0, import_select_agent.canonicalAgentUrl)(agentEntry.url),
     brandJsonUrl,
+    brandJson,
+    ...legacyFallback && { legacyWebhookFallback: true },
+    ...brandJsonCacheControl !== void 0 && { brandJsonCacheControl },
     agentEntry,
     jwksUri,
     jwks,
@@ -329,101 +371,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" ? (0, import_protocols.createA2AClient)(agentUrl) : (0, import_protocols.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 ((0, import_etld.eTldPlusOne)(domain) !== agentEtld1) continue;
-    } catch {
-      if (!(options.allowPrivateIp && (0, import_domain.isDevelopmentBrandDomain)(domain) && domain === agentEtld1)) {
-        continue;
+    const url = new URL(agentUrl);
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    if (!allowPrivateIp && url.protocol !== "https:" || (0, import_node_net.isIP)(hostname) && ((0, import_net.isAlwaysBlocked)(hostname) || !allowPrivateIp && (0, import_net.isPrivateIp)(hostname)))
+      throw new import_agent_transport_fetch.AgentTransportPolicyError("Signing discovery URL refused by address or HTTPS policy.");
+    let failure;
+    const upstream = (0, import_agent_transport_fetch.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 && !(0, import_fetch_helpers.isPermanentDiscoveryFailure)(failure) && (0, import_fetch_helpers.isPermanentDiscoveryFailure)(observed)))
+          failure = observed;
+        return response;
+      } catch (error) {
+        if (!(protocol === "mcp" && method.toUpperCase() === "GET" && postSucceeded))
+          failure = (0, import_fetch_helpers.classifyDiscoveryFailure)(error);
+        throw error;
       }
+    };
+    const transport = { trustedFetchFn, requestTimeoutMs: timeoutMs };
+    const client = protocol === "a2a" ? (0, import_protocols.createA2AClient)(agentUrl, void 0, void 0, void 0, void 0, transport) : (0, import_protocols.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 import_fetch_helpers.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 (0, import_canonicalize.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);
@@ -445,14 +445,25 @@ function runConsistencyChecks(args) {
       const result = (0, import_consistency.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;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   resolveAgent