@adcp/sdk 14.0.0 → 14.1.0

package/dist/lib/signing/brand-jwks.d.ts

@@ -1,32 +1,10 @@
-/**
- * Receiver-side ergonomic: resolve a sender's JWKS by fetching their
- * `brand.json`, extracting the `jwks_uri` for the agent whose webhooks we're
- * verifying, and delegating to {@link HttpsJwksResolver}.
- *
- * Hand the resulting instance to `verifyWebhookSignature.jwks` (or
- * `verifyRequestSignature.jwks`) and the receiver never has to know where the
- * sender hosts their keys — brand.json is the single source of truth.
- *
- * Follows the two documented redirect variants of `brand.json`
- * (`authoritative_location` and `house`) up to a caller-configurable hop
- * depth. When the selected agent has no `jwks_uri`, falls back to
- * `/.well-known/jwks.json` on the origin of the agent's `url` — but only
- * when that origin matches the final brand.json origin. The spec's
- * well-known fallback exists so publishers hosting brand.json and their
- * agents on the same origin can skip the explicit `jwks_uri`; accepting a
- * cross-origin fallback would let an attacker pivot the trust anchor to a
- * controlled host with a permissive JWKS.
- *
- * Caching is stacked with the inner {@link HttpsJwksResolver}: brand.json
- * honors its own `Cache-Control`/`ETag` (bounded by `maxAgeSeconds`), and
- * unknown-kid refreshes cascade — first to the JWKS endpoint, then (if the
- * JWKS still doesn't have the kid and the brand.json cooldown has elapsed) to
- * brand.json itself, in case the sender rotated `jwks_uri`.
- */
+/** Capability-confirmed sender key discovery and SSRF-safe brand.json fetching. */
 import { type SsrfDnsLookup } from '../net';
 import type { JwksResolver } from './jwks';
 import { type HttpsJwksResolverOptions } from './jwks-https';
 import type { AdcpJsonWebKey } from './types';
+import type { AgentProtocol, FetchCapabilitiesFn } from './agent-resolver/resolve-agent';
+import type { JwksResolution } from './jwks';
 export type BrandAgentType = 'brand' | 'rights' | 'measurement' | 'governance' | 'creative' | 'sales' | 'buying' | 'signals';
 export type BrandJsonResolverErrorCode = 'invalid_url' | 'invalid_house' | 'redirect_loop' | 'redirect_depth_exceeded' | 'fetch_failed' | 'invalid_body' | 'schema_invalid' | 'agent_not_found' | 'agent_ambiguous' | 'jwks_origin_mismatch';
 /**
@@ -45,21 +23,20 @@ export declare class BrandJsonResolverError extends Error {
     });
 }
 export interface BrandJsonJwksResolverOptions {
+    /** Expected agent URL. Prefer supplying it; legacy configurations infer one onboarding URL, then confirm it through capabilities and canonical matching. */
+    agentUrl?: string;
+    /** Capabilities transport. Defaults to MCP; A2A integrations must set 'a2a'. */
+    protocol?: AgentProtocol;
+    /** Enable the 3.x webhook-only domain-derived fallback. Default true. Request verification refuses these keys. */
+    legacyWebhookFallback?: boolean;
+    fetchCapabilities?: FetchCapabilitiesFn;
     /** Functional role of the agent whose keys we want to resolve. */
     agentType: BrandAgentType;
     /**
-     * Agent id from `agents[].id`. Required when brand.json declares more than
-     * one agent of the requested type (otherwise the selector is ambiguous).
-     * Optional when the type is unique.
+     * Agent id from `agents[].id`, used only to narrow canonical URL matches.
      */
     agentId?: string;
-    /**
-     * Brand id within a house portfolio (`brands[].id`). When omitted on a
-     * portfolio brand.json, the resolver looks at `house.agents[]`. When set,
-     * the resolver looks at `brands[brandId].agents[]` first and falls back to
-     * `house.agents[]` if no agent of the requested type is declared on the
-     * brand itself.
-     */
+    /** @deprecated Used only to infer an onboarding URL when agentUrl is absent. Canonical verification searches all operator collections. */
     brandId?: string;
     /**
      * Minimum seconds between brand.json refetches. Mirrors the JWKS cooldown
@@ -73,11 +50,7 @@ export interface BrandJsonJwksResolverOptions {
      * allow longer. Default 3600s (1 hour).
      */
     maxAgeSeconds?: number;
-    /**
-     * Maximum redirect hops to follow through `authoritative_location` /
-     * `house` variants. Default 3 — enough for `authoritative_location → house
-     * → portfolio` without inviting loops.
-     */
+    /** @deprecated Only controls legacy onboarding indirection. Explicit capability URLs allow no redirects; webhook fallback allows one document hop. */
     maxRedirects?: number;
     /**
      * Allow `http://` / private-IP brand.json and JWKS URLs (dev loops only).
@@ -90,52 +63,29 @@ export interface BrandJsonJwksResolverOptions {
      * address remains subject to SSRF classification and connection pinning.
      */
     lookup?: SsrfDnsLookup;
-    /**
-     * Forwarded to the inner {@link HttpsJwksResolver} constructor.
-     * `allowPrivateIp`, `lookup`, and `now` are set from the outer options and
-     * should not be passed here.
-     */
+    /** Existing settings remain accepted. maxAgeSeconds/minCooldownSeconds configure caching; protocol floors and fail-closed behavior replace other settings. */
     jwksOptions?: Omit<HttpsJwksResolverOptions, 'allowPrivateIp' | 'lookup' | 'now'>;
     /** Clock override for deterministic tests. Returns epoch seconds. */
     now?: () => number;
 }
 /**
- * JWKS resolver backed by a sender's `brand.json`. Construct one per
- * counterparty (or keyed by `brand.json` URL + agent selector) and hand it to
- * the webhook/request verifier as the `jwks` dependency.
+ * Confirmed operator mapping. The supplied brand.json URL must agree with
+ * capabilities on every cache refresh. Prefer ResolvedAgentJwksResolver
+ * when the application's onboarding record holds only the seller URL.
  */
 export declare class BrandJsonJwksResolver implements JwksResolver {
-    private readonly url;
-    private readonly selector;
-    private readonly minCooldown;
-    private readonly maxAge;
-    private readonly maxRedirects;
-    private readonly allowPrivateIp;
-    private readonly lookup;
-    private readonly jwksOptions;
-    private readonly now;
-    private snapshot;
-    private inner;
-    private inFlight;
+    private readonly brandJsonUrl;
+    private readonly options;
+    private resolver?;
+    private onboarding?;
+    private lastOnboardingAttempt;
     constructor(brandJsonUrl: string, options: BrandJsonJwksResolverOptions);
-    /**
-     * 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.
-     */
+    private createResolver;
+    private confirmedResolver;
     resolve(keyid: string): Promise<AdcpJsonWebKey | null>;
-    /**
-     * The agent URL we resolved `jwks_uri` from. Populated after the first
-     * successful refresh; useful for verifier result attribution
-     * (`VerifyWebhookOptions.agentUrlForKeyid`).
-     */
+    resolveWithMetadata(keyid: string): Promise<JwksResolution>;
     get agentUrl(): string | undefined;
-    /** Force a refetch of both brand.json and the inner JWKS, bypassing the cooldown. */
     forceRefresh(): Promise<void>;
-    private refresh;
-    private doRefresh;
 }
 export interface FetchedBrandJson {
     status: 'ok' | 'not_modified';
@@ -149,6 +99,8 @@ export interface FetchBrandJsonOptions {
     startUrl: string;
     /** ETag sent only to the entry URL for cache revalidation. */
     currentEtag?: string;
+    /** Initial domain-derived fetch may redirect only between host and exact www counterpart. */
+    domainDerived?: boolean;
     /** Maximum JSON-level `authoritative_location` / `house` hops. Default 3, hard maximum 10. */
     maxRedirects?: number;
     /** Permit HTTP and private addresses for controlled development environments. */

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

@@ -24,7 +24,9 @@ __export(brand_jwks_exports, {
 });
 module.exports = __toCommonJS(brand_jwks_exports);
 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;
   cause;
@@ -43,115 +45,110 @@ 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;
+  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 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;
+      return resolver;
+    })().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 +169,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 +193,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 +223,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 +315,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,