@adcp/sdk 14.0.0 → 14.1.0

package/dist/lib/signing/agent-resolver/select-agent.d.mts

@@ -1,16 +1,5 @@
-/**
- * Step 5 of the brand_json_url discovery algorithm: locate the brand.json
- * `agents[]` entry whose `url` byte-equals the agent URL the verifier is
- * resolving. The byte-equal rule is deliberate (security.mdx §"Discovering
- * an agent's signing keys via `brand_json_url`" step 5) — no canonicalization,
- * because the most common operator misconfiguration is a trailing-slash or
- * scheme mismatch (`https://x.com/mcp` vs `https://x.com/mcp/`), and silently
- * canonicalizing past that hides the bug. The match must be exact.
- *
- * Both flat (`agents[]` at top level) and house-portfolio
- * (`house.agents[]` + `brands[].agents[]`) brand.json shapes are supported,
- * because either may carry the entry that matches the agent URL.
- */
+/** Shared identifier rules, including query escapes (unlike the signing profile's raw query). */
+export declare function canonicalAgentUrl(raw: string): string;
 export type AgentSelectorErrorCode = 'agent_not_in_brand_json' | 'brand_json_ambiguous';
 export interface AgentEntry {
     url: string;
@@ -18,6 +7,12 @@ export interface AgentEntry {
     /** Other fields preserved verbatim — the resolver passes the entry to the caller. */
     [key: string]: unknown;
 }
+export interface AgentSelector {
+    agentType?: string;
+    agentId?: string;
+}
+/** The key source always belongs to the matched entry, never to the artifact. */
+export declare function agentJwksUri(entry: AgentEntry): string;
 export declare class AgentSelectorError extends Error {
     readonly code: AgentSelectorErrorCode;
     readonly detail: {
@@ -40,7 +35,9 @@ export declare class AgentSelectorError extends Error {
  */
 export declare function collectAgentEntries(brandJson: unknown): AgentEntry[];
 /**
- * Find the unique `agents[]` entry whose `url` byte-equals `agentUrl`.
+ * Find the unique canonical match. Portfolio repetitions across collections
+ * count once when their type and canonical JWKS source agree. Duplicates
+ * within one collection remain ambiguous. Type/id only narrow URL matches.
  *
  * - Returns the matched entry on a unique hit.
  * - Throws `AgentSelectorError('agent_not_in_brand_json')` on zero matches.
@@ -50,4 +47,6 @@ export declare function collectAgentEntries(brandJson: unknown): AgentEntry[];
  *   fields. `matched_entries` reflects counterparty-controlled state and is
  *   marked attacker-influenceable in the resolver's error mapping.
  */
-export declare function selectAgentByUrl(brandJson: unknown, agentUrl: string): AgentEntry;
+export declare function selectAgentByUrl(brandJson: unknown, agentUrl: string, selector?: AgentSelector): AgentEntry;
+/** Select a relying party's collection without incorporating sibling brands. */
+export declare function relyingPartyAgentRecord(brandJson: unknown, brandDomain: string): unknown;

package/dist/lib/signing/agent-resolver/select-agent.d.ts

@@ -1,16 +1,5 @@
-/**
- * Step 5 of the brand_json_url discovery algorithm: locate the brand.json
- * `agents[]` entry whose `url` byte-equals the agent URL the verifier is
- * resolving. The byte-equal rule is deliberate (security.mdx §"Discovering
- * an agent's signing keys via `brand_json_url`" step 5) — no canonicalization,
- * because the most common operator misconfiguration is a trailing-slash or
- * scheme mismatch (`https://x.com/mcp` vs `https://x.com/mcp/`), and silently
- * canonicalizing past that hides the bug. The match must be exact.
- *
- * Both flat (`agents[]` at top level) and house-portfolio
- * (`house.agents[]` + `brands[].agents[]`) brand.json shapes are supported,
- * because either may carry the entry that matches the agent URL.
- */
+/** Shared identifier rules, including query escapes (unlike the signing profile's raw query). */
+export declare function canonicalAgentUrl(raw: string): string;
 export type AgentSelectorErrorCode = 'agent_not_in_brand_json' | 'brand_json_ambiguous';
 export interface AgentEntry {
     url: string;
@@ -18,6 +7,12 @@ export interface AgentEntry {
     /** Other fields preserved verbatim — the resolver passes the entry to the caller. */
     [key: string]: unknown;
 }
+export interface AgentSelector {
+    agentType?: string;
+    agentId?: string;
+}
+/** The key source always belongs to the matched entry, never to the artifact. */
+export declare function agentJwksUri(entry: AgentEntry): string;
 export declare class AgentSelectorError extends Error {
     readonly code: AgentSelectorErrorCode;
     readonly detail: {
@@ -40,7 +35,9 @@ export declare class AgentSelectorError extends Error {
  */
 export declare function collectAgentEntries(brandJson: unknown): AgentEntry[];
 /**
- * Find the unique `agents[]` entry whose `url` byte-equals `agentUrl`.
+ * Find the unique canonical match. Portfolio repetitions across collections
+ * count once when their type and canonical JWKS source agree. Duplicates
+ * within one collection remain ambiguous. Type/id only narrow URL matches.
  *
  * - Returns the matched entry on a unique hit.
  * - Throws `AgentSelectorError('agent_not_in_brand_json')` on zero matches.
@@ -50,4 +47,6 @@ export declare function collectAgentEntries(brandJson: unknown): AgentEntry[];
  *   fields. `matched_entries` reflects counterparty-controlled state and is
  *   marked attacker-influenceable in the resolver's error mapping.
  */
-export declare function selectAgentByUrl(brandJson: unknown, agentUrl: string): AgentEntry;
+export declare function selectAgentByUrl(brandJson: unknown, agentUrl: string, selector?: AgentSelector): AgentEntry;
+/** Select a relying party's collection without incorporating sibling brands. */
+export declare function relyingPartyAgentRecord(brandJson: unknown, brandDomain: string): unknown;

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

@@ -19,10 +19,34 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var select_agent_exports = {};
 __export(select_agent_exports, {
   AgentSelectorError: () => AgentSelectorError,
+  agentJwksUri: () => agentJwksUri,
+  canonicalAgentUrl: () => canonicalAgentUrl,
   collectAgentEntries: () => collectAgentEntries,
+  relyingPartyAgentRecord: () => relyingPartyAgentRecord,
   selectAgentByUrl: () => selectAgentByUrl
 });
 module.exports = __toCommonJS(select_agent_exports);
+var import_canonicalize = require('../canonicalize.js');
+function canonicalAgentUrl(raw) {
+  const authority = /^[a-z][a-z0-9+.\-]*:\/\/([^/?#]*)/i.exec(raw)?.[1];
+  if (authority) (0, import_canonicalize.rejectNonAsciiHost)(`https://${authority.slice(authority.lastIndexOf("@") + 1)}`);
+  const canonical = (0, import_canonicalize.canonicalTargetUri)(raw, "3.2");
+  if (!/^https?:\/\//.test(canonical)) throw new TypeError("Agent identifier must be an HTTP(S) URL");
+  return canonical.replace(/%([0-9a-f]{2})/gi, (_escape, hex) => {
+    const character = String.fromCharCode(parseInt(hex, 16));
+    return /^[a-z0-9._~-]$/i.test(character) ? character : `%${hex.toUpperCase()}`;
+  });
+}
+function agentJwksUri(entry) {
+  if (entry.jwks_uri !== void 0) {
+    if (typeof entry.jwks_uri !== "string" || !entry.jwks_uri) throw new TypeError("Invalid jwks_uri");
+    const source = new URL(entry.jwks_uri);
+    if (source.username || source.password) throw new TypeError("JWKS URI must not contain userinfo");
+    canonicalAgentUrl(entry.jwks_uri);
+    return entry.jwks_uri;
+  }
+  return `${new URL(canonicalAgentUrl(entry.url)).origin}/.well-known/jwks.json`;
+}
 class AgentSelectorError extends Error {
   code;
   detail;
@@ -34,22 +58,31 @@ class AgentSelectorError extends Error {
   }
 }
 function collectAgentEntries(brandJson) {
+  return agentCollections(brandJson).flat();
+}
+function agentCollections(brandJson) {
   if (!brandJson || typeof brandJson !== "object") return [];
-  const entries = [];
+  const collections = [];
   const obj = brandJson;
-  pushAgentArray(obj.agents, entries);
+  const add = (value) => {
+    const entries = [];
+    pushAgentArray(value, entries);
+    collections.push(entries);
+  };
+  if (obj.agents !== void 0) {
+    add(obj.agents);
+    return collections;
+  }
   const house = obj.house;
   if (house && typeof house === "object") {
-    pushAgentArray(house.agents, entries);
-  }
-  if (Array.isArray(obj.brands)) {
-    for (const brand of obj.brands) {
-      if (brand && typeof brand === "object") {
-        pushAgentArray(brand.agents, entries);
+    add(house.agents);
+    if (Array.isArray(obj.brands)) {
+      for (const brand of obj.brands) {
+        if (brand && typeof brand === "object") add(brand.agents);
       }
     }
   }
-  return entries;
+  return collections;
 }
 function pushAgentArray(value, out) {
   if (!Array.isArray(value)) return;
@@ -62,13 +95,37 @@ function pushAgentArray(value, out) {
     }
   }
 }
-function selectAgentByUrl(brandJson, agentUrl) {
-  const entries = collectAgentEntries(brandJson);
-  const matches = entries.filter((e) => e.url === agentUrl);
+function selectAgentByUrl(brandJson, agentUrl, selector = {}) {
+  const canonicalUrl = canonicalAgentUrl(agentUrl);
+  const matches = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const collection of agentCollections(brandJson)) {
+    const local = collection.filter((e) => {
+      try {
+        return canonicalAgentUrl(e.url) === canonicalUrl && (selector.agentType === void 0 || e.type === selector.agentType) && (selector.agentId === void 0 || e.id === selector.agentId);
+      } catch {
+        return false;
+      }
+    });
+    if (local.length > 1) {
+      throw new AgentSelectorError("brand_json_ambiguous", `Multiple brand.json agent entries match ${agentUrl}`, {
+        agent_url: agentUrl,
+        matched_count: local.length,
+        matched_entries: local
+      });
+    }
+    for (const entry of local) {
+      const source = JSON.stringify([entry.type, canonicalAgentUrl(agentJwksUri(entry))]);
+      if (!seen.has(source)) {
+        seen.add(source);
+        matches.push(entry);
+      }
+    }
+  }
   if (matches.length === 0) {
     throw new AgentSelectorError(
       "agent_not_in_brand_json",
-      `No brand.json agent entry has url byte-equal to ${agentUrl}`,
+      `No brand.json agent entry has canonical URL ${canonicalUrl}`,
       { agent_url: agentUrl }
     );
   }
@@ -81,9 +138,37 @@ function selectAgentByUrl(brandJson, agentUrl) {
   }
   return matches[0];
 }
+function relyingPartyAgentRecord(brandJson, brandDomain) {
+  if (!brandJson || typeof brandJson !== "object") throw new TypeError("Invalid brand.json");
+  const obj = brandJson;
+  if (!obj.house || typeof obj.house !== "object") return obj;
+  const domainHost = (domain) => {
+    if (typeof domain !== "string" || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*\.?$/i.test(domain))
+      throw new TypeError("Invalid brand domain");
+    return new URL(canonicalAgentUrl(`https://${domain}`)).hostname;
+  };
+  const host = domainHost(brandDomain);
+  const house = obj.house;
+  if (house.domain !== void 0 && domainHost(house.domain) === host) {
+    return { agents: house.agents };
+  }
+  const brands = Array.isArray(obj.brands) ? obj.brands : [];
+  const matches = brands.filter((b) => {
+    try {
+      return b && typeof b === "object" && typeof b.url === "string" && new URL(canonicalAgentUrl(b.url)).hostname === host;
+    } catch {
+      return false;
+    }
+  });
+  if (matches.length !== 1) throw new TypeError("Brand domain is absent or ambiguous in portfolio");
+  return { agents: matches[0].agents === void 0 ? house.agents : matches[0].agents };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentSelectorError,
+  agentJwksUri,
+  canonicalAgentUrl,
   collectAgentEntries,
+  relyingPartyAgentRecord,
   selectAgentByUrl
 });

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

@@ -1,3 +1,24 @@
+import { canonicalTargetUri, rejectNonAsciiHost } from "../canonicalize.mjs";
+function canonicalAgentUrl(raw) {
+  const authority = /^[a-z][a-z0-9+.\-]*:\/\/([^/?#]*)/i.exec(raw)?.[1];
+  if (authority) rejectNonAsciiHost(`https://${authority.slice(authority.lastIndexOf("@") + 1)}`);
+  const canonical = canonicalTargetUri(raw, "3.2");
+  if (!/^https?:\/\//.test(canonical)) throw new TypeError("Agent identifier must be an HTTP(S) URL");
+  return canonical.replace(/%([0-9a-f]{2})/gi, (_escape, hex) => {
+    const character = String.fromCharCode(parseInt(hex, 16));
+    return /^[a-z0-9._~-]$/i.test(character) ? character : `%${hex.toUpperCase()}`;
+  });
+}
+function agentJwksUri(entry) {
+  if (entry.jwks_uri !== void 0) {
+    if (typeof entry.jwks_uri !== "string" || !entry.jwks_uri) throw new TypeError("Invalid jwks_uri");
+    const source = new URL(entry.jwks_uri);
+    if (source.username || source.password) throw new TypeError("JWKS URI must not contain userinfo");
+    canonicalAgentUrl(entry.jwks_uri);
+    return entry.jwks_uri;
+  }
+  return `${new URL(canonicalAgentUrl(entry.url)).origin}/.well-known/jwks.json`;
+}
 class AgentSelectorError extends Error {
   code;
   detail;
@@ -9,22 +30,31 @@ class AgentSelectorError extends Error {
   }
 }
 function collectAgentEntries(brandJson) {
+  return agentCollections(brandJson).flat();
+}
+function agentCollections(brandJson) {
   if (!brandJson || typeof brandJson !== "object") return [];
-  const entries = [];
+  const collections = [];
   const obj = brandJson;
-  pushAgentArray(obj.agents, entries);
+  const add = (value) => {
+    const entries = [];
+    pushAgentArray(value, entries);
+    collections.push(entries);
+  };
+  if (obj.agents !== void 0) {
+    add(obj.agents);
+    return collections;
+  }
   const house = obj.house;
   if (house && typeof house === "object") {
-    pushAgentArray(house.agents, entries);
-  }
-  if (Array.isArray(obj.brands)) {
-    for (const brand of obj.brands) {
-      if (brand && typeof brand === "object") {
-        pushAgentArray(brand.agents, entries);
+    add(house.agents);
+    if (Array.isArray(obj.brands)) {
+      for (const brand of obj.brands) {
+        if (brand && typeof brand === "object") add(brand.agents);
       }
     }
   }
-  return entries;
+  return collections;
 }
 function pushAgentArray(value, out) {
   if (!Array.isArray(value)) return;
@@ -37,13 +67,37 @@ function pushAgentArray(value, out) {
     }
   }
 }
-function selectAgentByUrl(brandJson, agentUrl) {
-  const entries = collectAgentEntries(brandJson);
-  const matches = entries.filter((e) => e.url === agentUrl);
+function selectAgentByUrl(brandJson, agentUrl, selector = {}) {
+  const canonicalUrl = canonicalAgentUrl(agentUrl);
+  const matches = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const collection of agentCollections(brandJson)) {
+    const local = collection.filter((e) => {
+      try {
+        return canonicalAgentUrl(e.url) === canonicalUrl && (selector.agentType === void 0 || e.type === selector.agentType) && (selector.agentId === void 0 || e.id === selector.agentId);
+      } catch {
+        return false;
+      }
+    });
+    if (local.length > 1) {
+      throw new AgentSelectorError("brand_json_ambiguous", `Multiple brand.json agent entries match ${agentUrl}`, {
+        agent_url: agentUrl,
+        matched_count: local.length,
+        matched_entries: local
+      });
+    }
+    for (const entry of local) {
+      const source = JSON.stringify([entry.type, canonicalAgentUrl(agentJwksUri(entry))]);
+      if (!seen.has(source)) {
+        seen.add(source);
+        matches.push(entry);
+      }
+    }
+  }
   if (matches.length === 0) {
     throw new AgentSelectorError(
       "agent_not_in_brand_json",
-      `No brand.json agent entry has url byte-equal to ${agentUrl}`,
+      `No brand.json agent entry has canonical URL ${canonicalUrl}`,
       { agent_url: agentUrl }
     );
   }
@@ -56,8 +110,36 @@ function selectAgentByUrl(brandJson, agentUrl) {
   }
   return matches[0];
 }
+function relyingPartyAgentRecord(brandJson, brandDomain) {
+  if (!brandJson || typeof brandJson !== "object") throw new TypeError("Invalid brand.json");
+  const obj = brandJson;
+  if (!obj.house || typeof obj.house !== "object") return obj;
+  const domainHost = (domain) => {
+    if (typeof domain !== "string" || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*\.?$/i.test(domain))
+      throw new TypeError("Invalid brand domain");
+    return new URL(canonicalAgentUrl(`https://${domain}`)).hostname;
+  };
+  const host = domainHost(brandDomain);
+  const house = obj.house;
+  if (house.domain !== void 0 && domainHost(house.domain) === host) {
+    return { agents: house.agents };
+  }
+  const brands = Array.isArray(obj.brands) ? obj.brands : [];
+  const matches = brands.filter((b) => {
+    try {
+      return b && typeof b === "object" && typeof b.url === "string" && new URL(canonicalAgentUrl(b.url)).hostname === host;
+    } catch {
+      return false;
+    }
+  });
+  if (matches.length !== 1) throw new TypeError("Brand domain is absent or ambiguous in portfolio");
+  return { agents: matches[0].agents === void 0 ? house.agents : matches[0].agents };
+}
 export {
   AgentSelectorError,
+  agentJwksUri,
+  canonicalAgentUrl,
   collectAgentEntries,
+  relyingPartyAgentRecord,
   selectAgentByUrl
 };

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

@@ -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/index.mjs';
 import type { JwksResolver } from './jwks.mjs';
 import { type HttpsJwksResolverOptions } from './jwks-https.mjs';
 import type { AdcpJsonWebKey } from './types.mjs';
+import type { AgentProtocol, FetchCapabilitiesFn } from './agent-resolver/resolve-agent.mjs';
+import type { JwksResolution } from './jwks.mjs';
 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. */