@adcp/sdk 14.0.0 → 14.2.0

package/docs/migration-agent-resolution-3.3.md

@@ -0,0 +1,125 @@
+# Agent resolution and publisher pins
+
+SDK 14.1 follows the shared AdCP 3.3 agent-resolution algorithm for request,
+webhook and governance signatures. SDK 14.1.0 still uses **AdCP 3.2.1 on the
+wire**: this alignment changes key discovery and verification, not the configured
+wire protocol version. Start with the [14.0-to-14.1 upgrade checklist](./migration-14.0-to-14.1.md)
+for required changes and opt-in features outside signature verification.
+
+## Expected agent URLs
+
+Prefer passing the agent URL already recorded by your integration:
+
+```ts
+const jwks = new ResolvedAgentJwksResolver(expectedSellerUrl, 'mcp', {
+  legacyWebhookFallback: true, // Webhooks from older 3.x sellers only.
+});
+```
+
+`BrandJsonJwksResolver(operatorUrl, { agentUrl, agentType, agentId })` remains
+available for onboarding mappings. It confirms `operatorUrl` against the agent's
+capabilities on cache refresh. `agentUrl` is optional for existing callers.
+When omitted, the resolver infers one canonical URL from its trusted onboarding
+record using the existing type/id/brand selectors, then confirms that URL's
+capabilities-selected operator record before accepting any key. Ambiguous
+onboarding fails closed; the inferred identity stays pinned for that resolver.
+Moving to a different agent URL requires a new resolver instance. Explicit
+`agentUrl` configurations must use the exact capabilities-published operator
+URL; legacy onboarding may resolve document indirection before confirming it.
+Existing `jwksOptions` types remain accepted; cache age and cooldown settings
+apply within protocol bounds, and verification always fails closed on expiry.
+`agentType` and `agentId` only narrow the final canonical URL match. Deprecated
+`brandId` and `maxRedirects` apply only to legacy onboarding, and do not restrict
+the final operator collections or capability discovery.
+Explicit capability URLs allow no HTTP or document-indirection redirects. The
+webhook-only fallback allows the bounded host/www HTTP policy and one document
+indirection. Request verification rejects keys discovered through that fallback.
+`SingleAgentClient` and `BrandJsonJwksResolver` enable the fallback by default for webhooks;
+set `webhookVerification.resolverOptions.legacyWebhookFallback` to `false` to
+disable it. Set `legacyWebhookFallback: false` on a standalone brand resolver to disable it.
+`ResolvedAgentJwksResolver` requires explicitly enabling the fallback for webhook use.
+Wrappers shared with request verification must forward `resolveWithMetadata`
+so the verifier can refuse webhook-only fallback keys.
+
+Capabilities discovery defaults to MCP. A2A integrations using
+`BrandJsonJwksResolver` must set `protocol: 'a2a'`; the onboarding record does
+not determine the transport. Existing cross-domain onboarding records must
+agree with the agent's capabilities-selected operator record. A legacy
+webhook without `brand_json_url` must use the agent-origin well-known record.
+
+Expired operator mappings fail closed. Successful operator records have a
+30-second minimum polling interval, including `no-cache` records, with their
+effective cache lifetime bounded above by the JWKS revocation polling interval
+and the configured local cap. Capabilities are re-confirmed on every refresh.
+A local cap shorter than the discovery cooldown can temporarily reject
+verification rather than reuse an expired mapping. Negative discovery results
+are throttled for at most 60 seconds.
+`maxAgeSeconds` must be positive; zero cannot provide a usable verified mapping
+with the protocol discovery cooldown. Public `forceRefresh()` is an
+operator-triggered cache flush and bypasses normal resolved-key cooldowns;
+failed onboarding attempts retain their 30-second cooldown.
+Standalone `HttpsJwksResolver` also applies its configured cooldown after a
+failed initial fetch or refresh and rejects non-finite or negative cache
+options. Brand resolvers validate their configuration before fetching.
+
+Canonical identity normalization preserves path slashes, query order, trailing
+empty queries and scheme distinctions. Update principal indexes that previously
+used non-canonical spellings. Duplicate canonical matches within one collection
+are ambiguous. Shared portfolio declarations count once only when their type
+and JWKS source agree.
+
+## Publisher pin context
+
+Pass `publisherPins` to `verifyWebhookSignature` or `createWebhookVerifier`.
+With the high-level client, configure `webhookVerification.publisherPins` to
+look up those pins from the persisted registration and your own media-buy record.
+Include every publisher whose inventory the delivery concerns. Never use payload
+fields to choose publishers.
+
+Each pin holds `publisher`, `signingKeys` and an async `refresh` callback that
+bypasses the publisher's adagents.json cache. Reuse the refresh callback across
+deliveries and bind it to the agent, publisher and tenant context it reads.
+The SDK coalesces concurrent refreshes and reuses their confirmed result (or
+failure) for 30 seconds, so a captured rejected delivery cannot repeatedly force
+uncached publisher fetches. Missing `signingKeys` means no pin;
+an empty array accepts no key. `refresh` must throw on failure; `null` means a
+successful fetch confirmed removal of the pin. A pinned key must also appear in
+the agent JWKS and match by RFC 7638 thumbprint. `kid`-only entries match nothing;
+revoked entries cannot authorize delivery. `key_origins` remains enforced.
+
+## Governance
+
+Supply `buyerIdentity` for each authenticated request to governance verification
+or enforcement middleware:
+
+```ts
+await enforceGovernance({
+  ...governedRequest,
+  buyerIdentity: {
+    brandJson: request.verifiedSigner.operatorRecord.document,
+    brandDomain: governedRequest.payload.brand.domain,
+  },
+}, performGovernedAction);
+```
+
+For signed buyers, use the exact `operatorRecord.document` exposed by request
+verification, the authenticator or Express middleware. Do not refetch a different
+brand.json at its host. Other authenticated buyer identity paths may supply their
+own trusted current record. Select the governed brand's collection, with house
+fallback only when it has no agents override; never use a sibling brand's agents.
+The inline brand URL hostname must equal the governed brand domain; `www` and
+the bare domain are distinct here.
+
+The legacy `jwks` plus `expectedIssuer` integration remains available for trusted
+onboarding resolvers. With `buyerIdentity`, the SDK selects and caches the matched
+entry's JWKS instead; no extra `jwks` argument is needed. Reuse a configured
+`jwksOptions` object across requests to share its bounded resolver cache.
+Governance replay and
+revocation lookups use canonical issuer URLs. Migrate external indexes and replay
+store keys when they contain non-canonical issuer spellings.
+
+Origin binding reads `authorized_operators` only from a House Portfolio and
+matches the exact agent eTLD+1. Brands and countries apply to account authorization,
+separately from key discovery. Existing explicit `requiredOperatorBrand`,
+`requiredOperatorScope` and `requiredOperatorCountry` receiver policies still
+check the delegation tuple and its validity bounds, including at cache acceptance.

package/docs/recipes/verifying-inbound-webhooks.md

@@ -75,12 +75,12 @@ verify before parsing or re-serializing.
 ## Recommended RFC 9421 Setup
 
 Create one verifier per expected sending agent. The resolver is bound to that
-agent's `brand.json` and selector, so a webhook for one seller cannot be
+agent's canonical URL and protocol, so a webhook for one seller cannot be
 verified with another seller's keys.
 
 ```ts
 import {
-  BrandJsonJwksResolver,
+  ResolvedAgentJwksResolver,
   createWebhookVerifier,
   type BrandAgentType,
   type RequestLike,
@@ -89,24 +89,26 @@ import {
 const verifiers = new Map<string, ReturnType<typeof createWebhookVerifier>>();
 
 type SenderRecord = {
+  operationId: string;
+  agentUrl: string;
+  protocol: 'mcp' | 'a2a';
   agentId: string;
+  publisherPins?: readonly import('@adcp/sdk/signing/server').PublisherSigningKeyPin[];
   agentType: BrandAgentType;
-  brandJsonUrl: string;
-  brandId?: string;
   webhookAuth: 'rfc9421' | 'legacy-hmac';
   legacyHmacSecret?: string;
 };
 
 function verifierFor(sender: SenderRecord) {
-  const cacheKey = `${sender.brandJsonUrl}#${sender.brandId ?? '-'}#${sender.agentType}:${sender.agentId}`;
+  const cacheKey = `${sender.operationId}#${sender.agentUrl}#${sender.agentType}:${sender.agentId}`;
   let verifier = verifiers.get(cacheKey);
   if (!verifier) {
-    const jwks = new BrandJsonJwksResolver(sender.brandJsonUrl, {
+    const jwks = new ResolvedAgentJwksResolver(sender.agentUrl, sender.protocol, {
       agentType: sender.agentType,
       agentId: sender.agentId,
-      ...(sender.brandId ? { brandId: sender.brandId } : {}),
+      legacyWebhookFallback: true,
     });
-    verifier = createWebhookVerifier({ jwks });
+    verifier = createWebhookVerifier({ jwks, publisherPins: sender.publisherPins });
     verifiers.set(cacheKey, verifier);
   }
   return verifier;
@@ -117,13 +119,50 @@ async function verifyRfc9421Webhook(sender: SenderRecord, request: RequestLike)
 }
 ```
 
+Discovery fetches the seller's `get_adcp_capabilities` through the official
+protocol client and uses its `identity.brand_json_url`. Canonical URL matching
+selects the agent; type and id only narrow that match. `key_origins` is checked
+for pinned keys too. Cached mappings are re-confirmed within the brand.json
+cache lifetime. The explicitly enabled 3.x fallback uses the agent host's
+`/.well-known/brand.json`, then its eTLD+1 only when the host serves no record.
+A present `brand_json_url` is always used, including when it is invalid or unreachable.
+
+Populate `publisherPins` from your **own stored media-buy inventory**, including
+every applicable publisher. Never choose publishers from the incoming payload.
+A key must be published in the agent JWKS and match every applicable pin by
+RFC 7638 thumbprint; a matching `kid` alone is insufficient. Each pin's `refresh`
+callback must bypass the publisher's adagents.json cache and throw on failure.
+Reuse each callback bound to its seller and tenant context across deliveries;
+concurrent refreshes and retries share a 30-second cooldown.
+Return `null` only when a successful authoritative fetch confirms removal of the
+pin. Cache verifier instances per operation because different buys may have
+different publishers, and remove them when the operation is retired.
+
+```ts
+const publisherPins = mediaBuy.publisherAuthorizations.map(authorization => ({
+  publisher: authorization.publisherDomain,
+  signingKeys: authorization.signingKeys,
+  refresh: async () => {
+    const current = await publisherStore.refreshAgentAuthorization(
+      authorization.publisherDomain, sender.agentUrl, { bypassCache: true }
+    );
+    return current.signingKeys ?? null;
+  },
+}));
+```
+
+`mediaBuy` and `publisherStore` are application-owned trusted records and a
+publisher-document fetcher. Pin misses force-refresh before final rejection,
+after signature authentication, and fail with `webhook_signature_key_unknown`.
+Use `onKeyResolutionError` to log the specific `request_signature_*` cause locally.
+
 `createWebhookVerifier` defaults replay and revocation stores once at factory
 creation time. That is safe for a single process. It is not enough behind a
 load balancer.
 
 `SenderRecord`, `lookupSenderForOperation()`, and `processWebhook()` are
 application-owned. Persist the expected `agentId`, `agentType`,
-`brandJsonUrl`, optional `brandId`, and exact `webhookAuth` mode when you
+`agentUrl`, protocol, and exact `webhookAuth` mode when you
 initiate or register the operation. The webhook receiver should read that
 state by operation ID before looking at any signature header.
 
@@ -234,7 +273,7 @@ Postgres:
 ```ts
 import { Pool } from 'pg';
 import {
-  BrandJsonJwksResolver,
+  ResolvedAgentJwksResolver,
   PostgresReplayStore,
   createWebhookVerifier,
   getReplayStoreMigration,
@@ -249,12 +288,13 @@ const replayStore = new PostgresReplayStore(pool);
 
 function buildVerifier(sender: SenderRecord) {
   return createWebhookVerifier({
-    jwks: new BrandJsonJwksResolver(sender.brandJsonUrl, {
+    jwks: new ResolvedAgentJwksResolver(sender.agentUrl, sender.protocol, {
       agentType: sender.agentType,
       agentId: sender.agentId,
-      ...(sender.brandId ? { brandId: sender.brandId } : {}),
+      legacyWebhookFallback: true,
     }),
     replayStore,
+    publisherPins: sender.publisherPins,
   });
 }
 ```
@@ -263,7 +303,7 @@ Redis:
 
 ```ts
 import { createClient } from 'redis';
-import { BrandJsonJwksResolver, RedisReplayStore, createWebhookVerifier } from '@adcp/sdk/signing/server';
+import { ResolvedAgentJwksResolver, RedisReplayStore, createWebhookVerifier } from '@adcp/sdk/signing/server';
 
 const redis = createClient({ url: process.env.REDIS_URL });
 await redis.connect();
@@ -275,12 +315,13 @@ const replayStore = new RedisReplayStore(redis, {
 
 function buildVerifier(sender: SenderRecord) {
   return createWebhookVerifier({
-    jwks: new BrandJsonJwksResolver(sender.brandJsonUrl, {
+    jwks: new ResolvedAgentJwksResolver(sender.agentUrl, sender.protocol, {
       agentType: sender.agentType,
       agentId: sender.agentId,
-      ...(sender.brandId ? { brandId: sender.brandId } : {}),
+      legacyWebhookFallback: true,
     }),
     replayStore,
+    publisherPins: sender.publisherPins,
   });
 }
 ```
@@ -346,3 +387,7 @@ debug sink with redaction.
 - [ ] Multi-replica deployments use Redis or Postgres replay storage.
 - [ ] Signature failure never falls back to another auth scheme.
 - [ ] JSON parsing and side effects happen only after verification succeeds.
+
+Legacy HMAC receivers can call `preflightWebhookRequest({ headers }, { maxSkewSeconds: 300 })`
+from `@adcp/sdk/webhooks` before secret lookup. Success checks syntax/freshness;
+then authenticate with `verifyWebhookRequest` using the secret and exact raw body.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "14.0.0",
+  "version": "14.2.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -541,6 +541,7 @@
     "!dist/lib/schemas-data/*/bundled/**/*",
     "bin/**/*.js",
     "skills/**/*",
+    "!skills/*.previous/**/*",
     ".claude-plugin/**/*",
     "compliance/cache/3.0.25/**/*",
     "compliance/cache/3.1.24/**/*",
@@ -749,7 +750,7 @@
     "@a2a-js/sdk": "^1.0.1",
     "@apidevtools/json-schema-ref-parser": "^15.5.2",
     "@arethetypeswrong/cli": "^0.18.5",
-    "@changesets/cli": "^2.31.1",
+    "@changesets/cli": "^3.0.3",
     "@commitlint/cli": "^20.5.3",
     "@commitlint/config-conventional": "^20.5.3",
     "@modelcontextprotocol/sdk": "^1.30.0",

package/skills/adcp-brand.previous/SKILL.md

@@ -1,200 +0,0 @@
----
-name: adcp-brand
-description: Execute AdCP Brand Protocol operations with brand agents - get brand identity data, search for licensable rights, acquire rights for campaigns, and manage existing grants. Use when users want to look up brand identities, find talent or IP for licensing, or manage rights grants.
----
-
-# AdCP Brand Protocol
-
-This skill enables you to execute the AdCP Brand Protocol with brand agents. The Brand Protocol provides access to brand identity, creative guidelines, and licensable rights (talent, IP, content).
-
-> **Buyer-side basics** — idempotency replay, `oneOf` variants, async `status:'submitted'` polling, error recovery from `adcp_error.issues[]` — live in `skills/call-adcp-agent/SKILL.md`. This skill covers per-task semantics only.
-
-## Overview
-
-The Brand Protocol provides 4 standardized tasks:
-
-| Task | Purpose | Response Time |
-|------|---------|---------------|
-| `get_brand_identity` | Get brand identity and guidelines | ~1-3s |
-| `get_rights` | Search licensable rights | ~1-5s |
-| `acquire_rights` | Acquire rights for a campaign | ~1-10s |
-| `update_rights` | Modify an existing grant | ~1-5s |
-
-## Typical Workflow
-
-### Brand Identity Lookup
-1. **Get identity**: `get_brand_identity` with brand domain and optional field filter
-2. **Use data**: Apply colors, logos, tone, guidelines to creative generation
-
-### Rights Licensing
-1. **Search rights**: `get_rights` with natural language query and use types
-2. **Review options**: Evaluate matches by pricing, availability, compatibility
-3. **Acquire**: `acquire_rights` with selected pricing option and campaign details
-4. **Manage**: `update_rights` to extend, adjust caps, or pause/resume
-
----
-
-## Task Reference
-
-### get_brand_identity
-
-Get brand identity data from a brand agent.
-
-**Request:**
-```json
-{
-  "brand_id": "athlete-jane-doe",
-  "fields": ["description", "logos", "colors", "tone"],
-  "use_case": "creative_production",
-  "authorized": true
-}
-```
-
-**Key fields:**
-- `brand_id` (string, required): Brand identifier within the agent's roster
-- `fields` (array, optional): Sections to include — `description`, `industry`, `keller_type`, `logos`, `colors`, `fonts`, `visual_guidelines`, `tone`, `tagline`, `voice_synthesis`, `assets`, `rights`. Omit for all.
-- `use_case` (string, optional): Intended use — `endorsement`, `voice_synthesis`, `likeness`, `creative_production`, `media_planning`
-- `authorized` (boolean, optional): Sandbox only — simulate authorized access to see protected fields. Real agents use OAuth. Default false.
-
-**Response contains:**
-- `brand`: Brand identity object with requested fields
-- Public fields (always available): `description`, `industry`, `logos` (public subset)
-- Protected fields (require authorization): `colors`, `fonts`, `tone`, `voice_synthesis`, `visual_guidelines`, full `assets`
-
----
-
-### get_rights
-
-Search for licensable rights (talent, IP, content) from a brand agent.
-
-**Request:**
-```json
-{
-  "query": "Dutch athlete for restaurant brand in Amsterdam, budget 400 EUR/month",
-  "uses": ["likeness", "endorsement"],
-  "buyer_brand": {
-    "domain": "restaurant.nl"
-  },
-  "countries": ["NL"],
-  "include_excluded": false
-}
-```
-
-**Key fields:**
-- `query` (string, required): Natural language description of desired rights
-- `uses` (array, required): Rights uses — `likeness`, `voice`, `name`, `endorsement`
-- `buyer_brand` (object, optional): Buyer brand for compatibility filtering — `{ domain, brand_id }`
-- `countries` (array, optional): Countries where rights are needed (ISO 3166-1 alpha-2)
-- `brand_id` (string, optional): Search within a specific brand only
-- `include_excluded` (boolean, optional): Include filtered-out results with reasons. Default false.
-
-**Response contains:**
-- `rights`: Array of matching rights offerings with:
-  - `rights_id`: Use in `acquire_rights`
-  - `brand_id`, `name`, `description`: Who/what the rights cover
-  - `uses`: Available use types
-  - `pricing_options`: Array with `pricing_option_id`, `price`, `currency`, `period`
-  - `availability`: Geographic and temporal restrictions
-  - `exclusions`: Any brand/category conflicts
-
----
-
-### acquire_rights
-
-Acquire rights from a brand agent for a campaign.
-
-**Request:**
-```json
-{
-  "rights_id": "rights_jane_doe_endorsement",
-  "pricing_option_id": "monthly_standard",
-  "buyer": {
-    "domain": "restaurant.nl"
-  },
-  "campaign": {
-    "description": "Social media campaign featuring athlete endorsement for Amsterdam restaurant launch",
-    "uses": ["likeness", "endorsement"],
-    "countries": ["NL"],
-    "estimated_impressions": 500000,
-    "start_date": "2025-03-01",
-    "end_date": "2025-06-30"
-  }
-}
-```
-
-**Key fields:**
-- `rights_id` (string, required): From `get_rights` response
-- `pricing_option_id` (string, required): Selected pricing option
-- `buyer` (object, required): Buyer brand identity — `{ domain, brand_id }`
-- `campaign` (object, required): Campaign details for rights clearance
-  - `description` (string, required): How the rights will be used
-  - `uses` (array, required): Rights uses for this campaign
-  - `countries` (array, optional): Campaign countries
-  - `estimated_impressions` (integer, optional): Estimated total impressions
-  - `start_date`, `end_date` (string, optional): Campaign dates (YYYY-MM-DD)
-
-**Response contains:**
-- `status`: `acquired`, `pending_approval`, or `rejected`
-- `rights_grant_id`: Grant identifier (if acquired)
-- `generation_credentials`: Credentials for AI generation (voice synthesis, likeness, etc.)
-- `rejection_reason`: Why the request was rejected (category conflict, exclusivity, etc.)
-
----
-
-### update_rights
-
-Update an existing rights grant — extend dates, adjust impression caps, or pause/resume.
-
-**Request:**
-```json
-{
-  "rights_id": "grant_abc123",
-  "end_date": "2025-09-30",
-  "impression_cap": 1000000,
-  "paused": false
-}
-```
-
-**Key fields:**
-- `rights_id` (string, required): Rights grant identifier from `acquire_rights`
-- `end_date` (string, optional): New end date (must be >= current end date)
-- `impression_cap` (number, optional): New impression cap (must be >= current)
-- `paused` (boolean, optional): Pause or resume the grant
-
----
-
-## Key Concepts
-
-### Public vs Protected Fields
-
-Brand agents distinguish between public and protected data:
-- **Public**: Available without authorization — basic description, industry, public logos
-- **Protected**: Requires OAuth or authorized flag — colors, fonts, tone, voice synthesis credentials, full asset library
-
-### Rights Use Types
-
-- `likeness`: Use of a person's visual likeness (photos, AI-generated images)
-- `voice`: Voice synthesis or audio recording rights
-- `name`: Use of a person's name in advertising
-- `endorsement`: Endorsement/testimonial rights
-
-### Rights Clearance
-
-`acquire_rights` checks:
-1. Brand/category compatibility (no competitor conflicts)
-2. Geographic availability
-3. Temporal availability
-4. Existing exclusivity agreements
-
-Results: `acquired` (immediate), `pending_approval` (human review), or `rejected` (with reason).
-
----
-
-## Error Handling
-
-Common error codes:
-
-- `REFERENCE_NOT_FOUND`: Invalid brand_id, rights_id, or pricing_option_id (brand-protocol resources use the universal not-found fallback per `error-handling.mdx`; brands lack a dedicated `*_NOT_FOUND` code)
-- `CATEGORY_CONFLICT`: Buyer brand conflicts with existing agreements
-- `GEOGRAPHIC_RESTRICTION`: Rights not available in requested countries
-- `AUTHORIZATION_REQUIRED`: Protected fields require OAuth