@adcp/sdk 14.0.0 → 14.1.0

package/docs/guides/SIGNING-GUIDE.md

@@ -53,7 +53,7 @@ Your domain (e.g., agent.example.com)
         -> /.well-known/jwks.json      # JSON Web Key Set with public keys
 ```
 
-`@adcp/sdk` provides `BrandJsonJwksResolver` which handles this entire chain automatically, with caching and refresh.
+`@adcp/sdk` provides `ResolvedAgentJwksResolver` which handles this entire chain automatically, with caching and refresh.
 
 ## Step 1: Generate a Signing Key
 
@@ -214,6 +214,12 @@ const signingFetch = buildAgentSigningFetch({
 });
 ```
 
+### Diagnosing a seller's rejection of a signed request
+
+For SDK client calls over A2A or MCP, a signed HTTP 401 with a `Signature` challenge (or no challenge) produces an `AuthenticationRequiredError` with `requestSigned: true` and `status: 401`. Its `code` remains `AUTHENTICATION_REQUIRED` for compatibility; `signatureErrorCode` carries a recognized seller `request_signature_*` code, and the message includes the protocol's repair hint. Check the public discovery chain, `brand_json_url` → `agents[]` → `jwks_uri`, when the seller cannot resolve your key. Explicit Bearer or Basic gateway challenges retain their existing authentication recovery. For client-credentials agents, a bare 401 still permits one token refresh; a persistent signed rejection keeps its diagnostics. Other signed bare 401s bypass unsigned authentication probes and interactive OAuth recovery, so gateways requiring those flows should send an explicit Bearer challenge.
+
+`error.responseBody` contains a bounded, redacted seller diagnostic when capture succeeds. It is non-enumerable and excluded from JSON error reports. Custom header values are conservatively treated as credentials; short values can mask matching diagnostic text. Treat it as untrusted operator diagnostic text; do not feed it to automated prompts or use it as recovery instructions. Failed `TaskResult` values preserve this error under `result.errorInstance`, so the diagnostic is available as `result.errorInstance.responseBody` after narrowing to `AuthenticationRequiredError`. Conformance raw capture uses the same bounded, redacted diagnostic rather than the original response bytes for these failures. Low-level signing fetch presets continue to return the original HTTP `Response`.
+
 ## Step 3.5: Production Key Storage — KMS / HSM / Vault
 
 Holding a private JWK in process memory is fine for development and testing but it's not where you want production signing keys to live. A process compromise leaks the signing key, and the only remedy is rotation across every counterparty that's cached your public key (within their TTL). The AdCP spec recommends storing keys in a managed key store (HSM or KMS); the SDK supports this directly via the `SigningProvider` interface.
@@ -429,13 +435,13 @@ import {
   requireAuthenticatedOrSigned,
   mcpToolNameResolver,
 } from '@adcp/sdk/server';
-import { BrandJsonJwksResolver } from '@adcp/sdk/signing/server';
+import { ResolvedAgentJwksResolver } from '@adcp/sdk/signing/server';
 
 serve(createAgent, {
   authenticate: requireAuthenticatedOrSigned({
     signature: verifySignatureAsAuthenticator({
       capability: { supported: true, required_for: ['create_media_buy'], covers_content_digest: 'either' },
-      jwks: new BrandJsonJwksResolver(),
+      jwks: new ResolvedAgentJwksResolver(expectedBuyerAgentUrl, 'mcp'),
       resolveOperation: mcpToolNameResolver,
     }),
     fallback: verifyApiKey({ keys: { 'sk_live_abc': { principal: 'acct_42' } } }),
@@ -453,7 +459,8 @@ Set `requiredFor` to the AdCP operations you want to gate behind signatures —
 |---|---|
 | `StaticJwksResolver` | Fixed set of known buyer keys. Good for dev/testing. |
 | `HttpsJwksResolver` | Fetches JWKS from a URL with caching and refresh. |
-| `BrandJsonJwksResolver` | Full discovery chain: brand.json -> jwks_uri -> JWKS. Production recommended. |
+| `ResolvedAgentJwksResolver` | Capability-bound discovery from an expected agent URL. Production recommended. |
+| `BrandJsonJwksResolver` | Confirms an operator mapping against capabilities; accepts an explicit `agentUrl` or infers a unique onboarding URL from existing configuration. |
 
 ## Step 5: Verify Inbound Webhooks (Buyer / Orchestrator)
 
@@ -462,16 +469,18 @@ When sellers send webhooks, verify the signature to confirm authenticity:
 ```typescript
 import {
   verifyWebhookSignature,
-  BrandJsonJwksResolver,
+  ResolvedAgentJwksResolver,
   InMemoryReplayStore,
+  InMemoryRevocationStore,
 } from '@adcp/sdk/signing/server';
 
-const jwks = new BrandJsonJwksResolver();
+const jwks = new ResolvedAgentJwksResolver(expectedSellerAgentUrl, 'mcp', { legacyWebhookFallback: true });
 const replayStore = new InMemoryReplayStore();
+const revocationStore = new InMemoryRevocationStore();
 
 app.post('/webhook', async (req, res) => {
   try {
-    await verifyWebhookSignature(req, { jwks, replayStore });
+    await verifyWebhookSignature(req, { jwks, replayStore, revocationStore });
   } catch (err) {
     return res.status(401).json({ error: 'invalid webhook signature' });
   }

package/docs/guides/account-resolution.md

@@ -24,6 +24,92 @@ accounts: {
 }
 ```
 
+For buyer setup and opt-in lifecycle management, see
+[First call to a seller](./FIRST-CALL-TO-A-SELLER.md).
+
+Account resolvers receive `ctx.provisioning`. It is false on discovery and
+negotiation (`get_products`, `list_products`, `get_signals`, and proposal
+request/refine/decline); these tasks MUST use lookup only. It is true on spend
+commitments, `activate_signal`, and `sync_*` tasks. Lazy provisioning must be
+explicitly gated:
+
+```ts
+resolve: async (ref, ctx) => {
+  const existing = await db.findAuthorizedAccount(ref, ctx?.authInfo);
+  if (existing || !ctx?.provisioning) return existing;
+  return await db.createAuthorizedAccount(ref, ctx?.authInfo);
+},
+```
+
+When `resolveAccount` is configured, a supplied unknown reference returns
+`ACCOUNT_NOT_FOUND`, even on optional account tools.
+
+### Strict account references (`strictAccountReferences`)
+
+SDK 14 keeps four compatibility behaviors that strict mode removes:
+
+- A buyer-supplied `account` still reaches a raw handler-bag seller that has
+  no reference-aware `resolveAccount`: the handler sees `params.account` and
+  `ctx.account` is undefined. An auth-only `resolveAccountFromAuth` does not
+  authorize an arbitrary reference.
+- A seller that declares `capabilities.account.requiredForProducts` still
+  serves `get_products` when the request carries no account and
+  authentication resolves none.
+- `list_accounts.account` is resolved through `resolveAccount` as the
+  request's account (an unknown or unauthorized filter returns
+  `ACCOUNT_NOT_FOUND`). Strict mode treats it as a filter instead.
+- On `createAdcpServerFromPlatform` with `resolution: 'implicit'`, an account
+  whose returned identity metadata disagrees with the supplied natural key is
+  still used.
+
+Each logs a deprecation warning once per process per warning code (through
+`logger.warn`, plus `process.emitWarning` outside `NODE_ENV=production`);
+later occurrences log at debug level. Codes:
+`ADCP_UNRESOLVED_ACCOUNT_REFERENCE`, `ADCP_REQUIRED_FOR_PRODUCTS_NOT_ENFORCED`,
+`ADCP_LIST_ACCOUNTS_FILTER_RESOLVED`, and
+`ADCP_IMPLICIT_ACCOUNT_IDENTITY_MISMATCH`.
+
+**Strict mode becomes the default in the next major release.** Opt in now:
+
+```ts
+createAdcpServer({
+  name: 'Seller',
+  version: '1.0.0',
+  strictAccountReferences: true,
+  resolveAccount: (ref, ctx) => authorizedAccounts.find(ref, ctx.authInfo),
+  mediaBuy: {
+    getProducts: (params, ctx) => catalog.forAccount(ctx.account, params),
+  },
+});
+```
+
+With `strictAccountReferences: true`:
+
+- A supplied reference on a server without `resolveAccount` fails with
+  `ACCOUNT_NOT_FOUND` before the handler runs.
+- A `requiredForProducts` seller refuses account-less `get_products` with
+  `ACCOUNT_REQUIRED`.
+- `list_accounts.account` is a filter: `resolveAccount` is not called for it
+  and `ctx.account` comes from `resolveAccountFromAuth`.
+- An implicit-mode account whose returned identity metadata (`brand`,
+  `operator`, `operator_unit`, `currency`, `timezone`, `sandbox`) disagrees
+  with the supplied natural key is refused with `ACCOUNT_NOT_FOUND`. Fields
+  your store does not return are not compared.
+
+Migration for handler-bag sellers: move account authorization out of
+individual handlers and into `resolveAccount`, then set the flag.
+`authorizedAccounts.find` must return null on an unknown reference or a
+reference owned by another principal. Public discovery may omit `account`;
+resource creation and spend commitments need an authorized account. Implicit
+stores should resolve by the complete natural key and return identity
+metadata that echoes it, or omit the metadata.
+
+`InMemoryImplicitAccountStore` matches supplied refs on the complete natural
+key, including operator unit, currency, timezone, and sandbox. It retains its
+24-hour TTL and replacement sync semantics. Set `mergeOnUpsert: true` for
+additive batches and revoke individual refs with `remove(ref, ctx)`; passing
+`delete_missing: true` in `sync_accounts` retains replacement semantics.
+
 **Each mode has exactly one spelling.** `'derived'` keeps its name even
 though [adcp#5062](https://github.com/adcontextprotocol/adcp/pull/5062)
 calls the shape an *upstream-managed account-id namespace*: `resolution` is

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-01
-> Library: @adcp/sdk v14.0.0
+> Generated at: 2026-10-04
+> Library: @adcp/sdk v14.1.0
 > AdCP major version: 3
 > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
 > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.
@@ -19,6 +19,7 @@ SDK 14 is compact-lifecycle first: `list_products → buy_products → control_m
 
 - **MediaBuy change rights:** use `assessMediaBuyAction` from `@adcp/sdk/media-buy/actions` for possible / promised / available-now assessment, and `mediaBuyActionResolver` from `@adcp/sdk/server` for explicit seller acceptance and current projection. See `docs/guides/MEDIA-BUY-ACTION-ASSESSMENT.md`.
 - **Buyer** (calling a seller): read `docs/guides/BUYER-QUICKSTART-3.2.md` first.
+- **Account setup and first discovery:** read `docs/guides/FIRST-CALL-TO-A-SELLER.md` for the provisioning registry, account policies, billing terms, and product cache.
 - **Buyer Reliable Reporting**: import reconciliation, PostgreSQL persistence, and the worker from `@adcp/sdk/reporting/consumer`; see `docs/guides/REPORTING-RECONCILIATION.md`.
 - **Before proposal acceptance:** use `verifyProposalCommercialTerms` from `@adcp/sdk/negotiation/verification` with a complete, independently reviewed snapshot and the seller-served schema version. Never use an unreviewed candidate as its own expected terms. See `docs/guides/PROPOSAL-TERMS-VERIFICATION.md`.
 - **Seller** (implementing an agent that others call): read `docs/guides/SELLER-QUICKSTART-3.2.md` first, then `docs/guides/BUILD-AN-AGENT.md` for the complete framework surface.

package/docs/migration-14.x-rc-worksheet.md

@@ -11,8 +11,8 @@ below as the publication/deployment gate.
 
 | Fact | Value |
 | --- | --- |
-| Exact npm package | `@adcp/sdk@14.0.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@14.0.0 dist.integrity` |
+| Exact npm package | `@adcp/sdk@14.1.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@14.1.0 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.2.1` |
 | Maintained wire releases | `v2.5`, `v2.6`, `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.2.1`, `3.2` |
@@ -21,8 +21,8 @@ below as the publication/deployment gate.
 Install exact production inputs rather than a moving range or dist-tag:
 
 ```bash
-npm install --save-exact '@adcp/sdk@14.0.0'
-npm view '@adcp/sdk@14.0.0' dist.integrity
+npm install --save-exact '@adcp/sdk@14.1.0'
+npm view '@adcp/sdk@14.1.0' dist.integrity
 ```
 
 ### Required and optional peers

package/docs/migration-4.x-to-5.x.md

@@ -450,6 +450,7 @@ import {
 } from '@adcp/sdk/signing/server';
 
 const jwks = new BrandJsonJwksResolver('https://publisher.example/.well-known/brand.json', {
+  agentUrl: 'https://publisher.example/mcp',
   agentType: 'sales',
 });
 

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

@@ -0,0 +1,123 @@
+# Agent resolution and publisher pins
+
+The SDK follows the shared AdCP 3.3 agent-resolution algorithm for request,
+webhook and governance signatures. The protocol alignment changes key discovery
+and verification; it does not change the SDK's configured wire protocol version.
+
+## 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,
   });
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "14.0.0",
+  "version": "14.1.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -749,7 +749,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",