@adcp/sdk 14.0.0 → 14.2.0

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';
 /**
@@ -36,6 +14,7 @@ export type BrandJsonResolverErrorCode = 'invalid_url' | 'invalid_house' | 'redi
  */
 export declare class BrandJsonResolverError extends Error {
     readonly code: BrandJsonResolverErrorCode;
+    readonly recovery: 'terminal' | 'transient';
     readonly cause?: unknown;
     /** HTTP status for `fetch_failed` responses, when a response was received. */
     readonly httpStatus?: number;
@@ -45,21 +24,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 +51,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 +64,30 @@ 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;
+    private lastOnboardingError?;
     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 +101,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.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';
 /**
@@ -36,6 +14,7 @@ export type BrandJsonResolverErrorCode = 'invalid_url' | 'invalid_house' | 'redi
  */
 export declare class BrandJsonResolverError extends Error {
     readonly code: BrandJsonResolverErrorCode;
+    readonly recovery: 'terminal' | 'transient';
     readonly cause?: unknown;
     /** HTTP status for `fetch_failed` responses, when a response was received. */
     readonly httpStatus?: number;
@@ -45,21 +24,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 +51,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 +64,30 @@ 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;
+    private lastOnboardingError?;
     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 +101,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. */