@adcp/sdk 14.0.0 → 14.2.0

package/dist/lib/signing/brand-jwks.js

@@ -23,10 +23,14 @@ __export(brand_jwks_exports, {
   fetchBrandJson: () => fetchBrandJson
 });
 module.exports = __toCommonJS(brand_jwks_exports);
+var import_fetch_helpers = require('./agent-resolver/fetch-helpers.js');
 var import_net = require('../net/index.js');
-var import_jwks_https = require('./jwks-https.js');
+var import_resolved_agent_jwks = require('./agent-resolver/resolved-agent-jwks.js');
+var import_strict_json = require('./agent-resolver/strict-json.js');
+var import_select_agent = require('./agent-resolver/select-agent.js');
 class BrandJsonResolverError extends Error {
   code;
+  recovery;
   cause;
   /** HTTP status for `fetch_failed` responses, when a response was received. */
   httpStatus;
@@ -36,6 +40,7 @@ class BrandJsonResolverError extends Error {
     this.code = code;
     this.httpStatus = details.httpStatus;
     this.cause = details.cause;
+    this.recovery = code !== "fetch_failed" || (0, import_fetch_helpers.isPermanentDiscoveryFailure)((0, import_fetch_helpers.classifyDiscoveryFailure)(this)) ? "terminal" : "transient";
   }
 }
 const DEFAULT_MIN_COOLDOWN_SECONDS = 30;
@@ -43,115 +48,115 @@ const DEFAULT_MAX_AGE_SECONDS = 3600;
 const DEFAULT_MAX_REDIRECTS = 3;
 const BARE_HOSTNAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
 class BrandJsonJwksResolver {
-  url;
-  selector;
-  minCooldown;
-  maxAge;
-  maxRedirects;
-  allowPrivateIp;
-  lookup;
-  jwksOptions;
-  now;
-  snapshot;
-  inner;
-  inFlight;
   constructor(brandJsonUrl, options) {
-    this.url = brandJsonUrl;
-    this.selector = {
+    this.brandJsonUrl = brandJsonUrl;
+    this.options = options;
+    for (const lifetime of [options.maxAgeSeconds, options.jwksOptions?.maxAgeSeconds]) {
+      if (lifetime !== void 0 && (!Number.isFinite(lifetime) || lifetime <= 0))
+        throw new TypeError("maxAgeSeconds must be a finite positive number.");
+    }
+    for (const cooldown of [options.minCooldownSeconds, options.jwksOptions?.minCooldownSeconds]) {
+      if (cooldown !== void 0 && (!Number.isFinite(cooldown) || cooldown < 0))
+        throw new TypeError("minCooldownSeconds must be a finite non-negative number.");
+    }
+    if (options.agentUrl !== void 0) this.resolver = this.createResolver(options.agentUrl, brandJsonUrl);
+  }
+  brandJsonUrl;
+  options;
+  resolver;
+  onboarding;
+  lastOnboardingAttempt = Number.NEGATIVE_INFINITY;
+  lastOnboardingError;
+  createResolver(agentUrl, operatorUrl) {
+    const options = this.options;
+    return new import_resolved_agent_jwks.ResolvedAgentJwksResolver(agentUrl, options.protocol ?? "mcp", {
       agentType: options.agentType,
-      ...options.agentId !== void 0 && { agentId: options.agentId },
-      ...options.brandId !== void 0 && { brandId: options.brandId }
-    };
-    this.minCooldown = options.minCooldownSeconds ?? DEFAULT_MIN_COOLDOWN_SECONDS;
-    this.maxAge = options.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS;
-    this.maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
-    this.allowPrivateIp = options.allowPrivateIp ?? false;
-    this.lookup = options.lookup;
-    this.jwksOptions = options.jwksOptions ?? {};
-    this.now = options.now ?? (() => Math.floor(Date.now() / 1e3));
+      agentId: options.agentId,
+      expectedBrandJsonUrl: operatorUrl,
+      fetchCapabilities: options.fetchCapabilities,
+      legacyWebhookFallback: options.legacyWebhookFallback ?? true,
+      allowPrivateIp: options.allowPrivateIp,
+      lookup: options.lookup,
+      now: options.now,
+      cacheTtlSeconds: Math.min(
+        options.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS,
+        options.jwksOptions?.maxAgeSeconds ?? 1800
+      ),
+      unknownKidCooldownSeconds: options.minCooldownSeconds ?? options.jwksOptions?.minCooldownSeconds ?? DEFAULT_MIN_COOLDOWN_SECONDS
+    });
   }
-  /**
-   * Resolve a JWK by `kid`. On a cold cache, fetches brand.json first; on an
-   * expired brand.json snapshot, refreshes respecting the cooldown. Unknown
-   * kids cascade: first ask the inner HttpsJwksResolver (which will refetch
-   * its own URL if cooldown has elapsed); if still unknown, refresh
-   * brand.json in case `jwks_uri` rotated.
-   */
-  async resolve(keyid) {
-    if (!this.snapshot || !this.inner) {
-      await this.refresh();
-    } else if (this.now() > this.snapshot.expiresAt && this.now() - this.snapshot.fetchedAt >= this.minCooldown) {
-      await this.refresh().catch(() => {
-      });
-    }
-    if (!this.inner) return null;
-    const hit = await this.inner.resolve(keyid);
-    if (hit) return hit;
-    if (this.snapshot && this.now() - this.snapshot.fetchedAt >= this.minCooldown) {
-      await this.refresh().catch(() => {
+  async confirmedResolver() {
+    if (this.resolver) return this.resolver;
+    if (this.onboarding) return this.onboarding;
+    const now = this.options.now?.() ?? Date.now() / 1e3;
+    if (now - this.lastOnboardingAttempt < 30)
+      throw this.lastOnboardingError ?? new BrandJsonResolverError("fetch_failed", "Operator onboarding discovery is in its retry cooldown.");
+    this.lastOnboardingAttempt = now;
+    this.onboarding = (async () => {
+      const record = await fetchBrandJson({
+        startUrl: this.brandJsonUrl,
+        maxRedirects: this.options.maxRedirects,
+        allowPrivateIp: this.options.allowPrivateIp,
+        lookup: this.options.lookup
       });
-      return this.inner ? this.inner.resolve(keyid) : null;
-    }
-    return null;
+      const agentUrl = inferOnboardingAgentUrl(record.data, this.options);
+      const resolver = this.createResolver(agentUrl, record.finalUrl);
+      await resolver.forceRefresh();
+      this.resolver = resolver;
+      this.lastOnboardingError = void 0;
+      return resolver;
+    })().catch((error) => {
+      this.lastOnboardingError = error;
+      throw error;
+    }).finally(() => {
+      this.onboarding = void 0;
+    });
+    return this.onboarding;
+  }
+  async resolve(keyid) {
+    return (await this.confirmedResolver()).resolve(keyid);
+  }
+  async resolveWithMetadata(keyid) {
+    return (await this.confirmedResolver()).resolveWithMetadata(keyid);
   }
-  /**
-   * The agent URL we resolved `jwks_uri` from. Populated after the first
-   * successful refresh; useful for verifier result attribution
-   * (`VerifyWebhookOptions.agentUrlForKeyid`).
-   */
   get agentUrl() {
-    return this.snapshot?.agentUrl;
+    return this.resolver?.resolvedAgentUrl;
   }
-  /** Force a refetch of both brand.json and the inner JWKS, bypassing the cooldown. */
   async forceRefresh() {
-    this.snapshot = void 0;
-    this.inner = void 0;
-    await this.refresh();
-  }
-  async refresh() {
-    if (this.inFlight) {
-      await this.inFlight;
-      return;
-    }
-    this.inFlight = this.doRefresh().finally(() => {
-      this.inFlight = void 0;
-    });
-    await this.inFlight;
+    if (this.resolver) await this.resolver.forceRefresh();
+    else await this.confirmedResolver();
   }
-  async doRefresh() {
-    const fetched = await fetchBrandJson({
-      startUrl: this.url,
-      currentEtag: this.snapshot?.etag,
-      maxRedirects: this.maxRedirects,
-      allowPrivateIp: this.allowPrivateIp,
-      lookup: this.lookup
-    });
-    if (fetched.status === "not_modified" && this.snapshot) {
-      this.snapshot = {
-        ...this.snapshot,
-        ...fetched.etag && { etag: fetched.etag },
-        fetchedAt: this.now(),
-        expiresAt: this.now() + computeLifetime(fetched.cacheControl, this.maxAge)
-      };
-      return;
+}
+function inferOnboardingAgentUrl(document, selector) {
+  const record = document;
+  const candidates = (agents) => !Array.isArray(agents) ? [] : agents.filter(
+    (entry) => entry?.type === selector.agentType && (selector.agentId === void 0 || entry.id === selector.agentId) && typeof entry.url === "string"
+  ).flatMap((entry) => {
+    try {
+      return [(0, import_select_agent.canonicalAgentUrl)(entry.url)];
+    } catch {
+      return [];
     }
-    const agent = selectAgent(fetched.data, fetched.finalUrl, this.selector);
-    if (!this.inner || this.snapshot?.jwksUri !== agent.jwksUri) {
-      this.inner = new import_jwks_https.HttpsJwksResolver(agent.jwksUri, {
-        ...this.jwksOptions,
-        allowPrivateIp: this.allowPrivateIp,
-        lookup: this.lookup,
-        now: this.now
-      });
+  });
+  let urls;
+  if (isPortfolioHouse(record.house)) {
+    const house = record.house;
+    urls = [];
+    if (selector.brandId !== void 0 && Array.isArray(record.brands)) {
+      const brands = record.brands.filter((brand) => brand?.id === selector.brandId);
+      if (brands.length > 1)
+        throw new BrandJsonResolverError("agent_ambiguous", "Onboarding brand selector is ambiguous.");
+      urls = candidates(brands[0]?.agents);
     }
-    this.snapshot = {
-      jwksUri: agent.jwksUri,
-      agentUrl: agent.url,
-      ...fetched.etag && { etag: fetched.etag },
-      fetchedAt: this.now(),
-      expiresAt: this.now() + computeLifetime(fetched.cacheControl, this.maxAge)
-    };
-  }
+    if (urls.length === 0) urls = candidates(house.agents);
+  } else urls = candidates(record.agents);
+  const unique = [...new Set(urls)];
+  if (unique.length !== 1)
+    throw new BrandJsonResolverError(
+      unique.length === 0 ? "agent_not_found" : "agent_ambiguous",
+      "Onboarding must identify exactly one agent URL; supply agentUrl explicitly."
+    );
+  return unique[0];
 }
 const MAX_BRAND_JSON_TIMEOUT_MS = 1e4;
 const MAX_BRAND_JSON_BODY_BYTES = 262144;
@@ -172,6 +177,8 @@ async function fetchBrandJson(args) {
   const allowPrivateIp = args.allowPrivateIp === true;
   const seen = /* @__PURE__ */ new Set();
   let url = canonicalizeUrl(args.startUrl, allowPrivateIp);
+  const initial = new URL(url);
+  let httpRedirects = 0;
   for (let hop = 0; hop <= maxRedirects; hop++) {
     if (seen.has(url)) {
       throw new BrandJsonResolverError("redirect_loop", `brand.json redirect loop detected`);
@@ -194,6 +201,19 @@ async function fetchBrandJson(args) {
     } catch (cause) {
       throw new BrandJsonResolverError("fetch_failed", "Unable to fetch brand.json", { cause });
     }
+    if (args.domainDerived && hop === 0 && [301, 302, 303, 307, 308].includes(res.status)) {
+      const location = res.headers.location;
+      if (!location || httpRedirects++ >= 3)
+        throw new BrandJsonResolverError("fetch_failed", "Invalid domain-derived redirect");
+      const target = new URL(location, url);
+      const baseHost = initial.hostname.startsWith("www.") ? initial.hostname.slice(4) : initial.hostname;
+      if (target.hostname !== baseHost && target.hostname !== `www.${baseHost}` || target.port !== initial.port || target.protocol !== initial.protocol || target.username || target.password) {
+        throw new BrandJsonResolverError("invalid_url", "brand.json redirect leaves its original host/www boundary");
+      }
+      url = canonicalizeUrl(target.href, allowPrivateIp);
+      hop--;
+      continue;
+    }
     if (hop === 0 && res.status === 304) {
       return {
         status: "not_modified",
@@ -211,7 +231,7 @@ async function fetchBrandJson(args) {
     const text = Buffer.from(res.body).toString("utf8");
     let parsed;
     try {
-      parsed = JSON.parse(text);
+      parsed = (0, import_strict_json.parseStrictJson)(text);
     } catch {
       throw new BrandJsonResolverError("invalid_body", `brand.json response is not valid JSON`);
     }
@@ -303,88 +323,6 @@ function assertBrandJsonShape(obj) {
     }
   }
 }
-function selectAgent(data, finalBrandUrl, selector) {
-  if (!data || typeof data !== "object") {
-    throw new BrandJsonResolverError(
-      "agent_not_found",
-      `brand.json has no agent matching ${describeSelector(selector)}`
-    );
-  }
-  const obj = data;
-  let picked;
-  if (isPortfolioHouse(obj.house)) {
-    const house = obj.house;
-    if (selector.brandId !== void 0) {
-      const brands = Array.isArray(obj.brands) ? obj.brands : [];
-      const brand = brands.find((b) => b && b.id === selector.brandId);
-      if (brand) picked = pickAgent(brand.agents, finalBrandUrl, selector);
-    }
-    picked ??= pickAgent(house.agents, finalBrandUrl, selector);
-  } else {
-    picked = pickAgent(obj.agents, finalBrandUrl, selector);
-  }
-  if (!picked) {
-    throw new BrandJsonResolverError(
-      "agent_not_found",
-      `brand.json has no agent matching ${describeSelector(selector)}`
-    );
-  }
-  return picked;
-}
-function pickAgent(agents, finalBrandUrl, selector) {
-  if (!Array.isArray(agents)) return void 0;
-  const matches = agents.filter((a) => {
-    if (!a || typeof a !== "object") return false;
-    const e = a;
-    if (e.type !== selector.agentType) return false;
-    if (selector.agentId !== void 0 && e.id !== selector.agentId) return false;
-    return typeof e.url === "string";
-  });
-  if (matches.length === 0) return void 0;
-  if (matches.length > 1 && selector.agentId === void 0) {
-    throw new BrandJsonResolverError(
-      "agent_ambiguous",
-      `brand.json declares ${matches.length} agents of type "${selector.agentType}"; pass \`agentId\` to disambiguate (choices: ${matches.map((m) => m.id ?? "<no-id>").join(", ")})`
-    );
-  }
-  const agent = matches[0];
-  const url = agent.url;
-  const jwksUri = agent.jwks_uri ?? defaultJwksUri(url, finalBrandUrl);
-  return { url, jwksUri };
-}
-function defaultJwksUri(agentUrl, finalBrandUrl) {
-  let agent;
-  try {
-    agent = new URL(agentUrl);
-  } catch {
-    throw new BrandJsonResolverError("invalid_url", `agent.url is not a valid URL`);
-  }
-  const brand = new URL(finalBrandUrl);
-  if (agent.origin !== brand.origin) {
-    throw new BrandJsonResolverError(
-      "jwks_origin_mismatch",
-      `agent.url origin (${agent.origin}) does not match brand.json origin (${brand.origin}); publisher must declare an explicit jwks_uri for cross-origin agents`
-    );
-  }
-  return `${agent.origin}/.well-known/jwks.json`;
-}
-function describeSelector(selector) {
-  const parts = [`type=${selector.agentType}`];
-  if (selector.agentId !== void 0) parts.push(`id=${selector.agentId}`);
-  if (selector.brandId !== void 0) parts.push(`brand=${selector.brandId}`);
-  return parts.join(" ");
-}
-function computeLifetime(cacheControl, maxAge) {
-  if (!cacheControl) return maxAge;
-  const lower = cacheControl.toLowerCase();
-  if (/\bno-store\b|\bno-cache\b/.test(lower)) return 0;
-  const match = /max-age\s*=\s*(\d+)/.exec(lower);
-  if (match) {
-    const serverMax = Number(match[1]);
-    if (Number.isFinite(serverMax)) return Math.min(serverMax, maxAge);
-  }
-  return maxAge;
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BrandJsonJwksResolver,