@adcp/sdk 14.1.0 → 14.2.0

package/docs/guides/account-resolution.md

@@ -26,6 +26,8 @@ accounts: {
 
 For buyer setup and opt-in lifecycle management, see
 [First call to a seller](./FIRST-CALL-TO-A-SELLER.md).
+For upgrading an existing integration, use the
+[14.0-to-14.1 checklist](../migration-14.0-to-14.1.md).
 
 Account resolvers receive `ctx.provisioning`. It is false on discovery and
 negotiation (`get_products`, `list_products`, `get_signals`, and proposal
@@ -133,29 +135,53 @@ construction, not a silent fallback.
 
 ### 1 · How it works
 
-1. Buyer calls `sync_accounts` with `AccountReference[]`.
+1. Buyer calls `sync_accounts` with natural-key provisioning entries.
 2. Framework calls your `accounts.upsert()` — you create/find accounts and
    store the `authPrincipal → accounts` mapping.
-3. Buyer calls any tool (e.g. `create_media_buy`) without `ext.account_ref`.
-4. Framework calls `accounts.resolve(undefined, ctx)` — you look up the
-   account by `ctx.authInfo`.
+3. On subsequent account-scoped calls, the buyer supplies top-level
+   `account: { brand, operator, ... }`. The framework calls
+   `accounts.resolve(ref, ctx)` with that natural key. Look it up within the
+   authenticated caller's synced roster; do not substitute another account.
+4. When a request omits `account`, the framework instead calls
+   `accounts.resolve(undefined, ctx)`. This is a separate auth-derived lookup
+   path. A null result is allowed for account-optional tools and yields
+   `ACCOUNT_REQUIRED` for account-required operations.
+
+Implicit sellers refuse the `{ account_id }` reference arm. A seller handle
+returned by `sync_accounts` does not replace the natural key on later calls.
 
 ### 2 · Key derivation
 
 Extract the principal key from `ctx.authInfo.credential`:
 
 ```ts
-resolve: async (_ref, ctx) => {
+resolve: async (ref, ctx) => {
   const cred = ctx?.authInfo?.credential;
   const key = cred?.kind === 'oauth'    ? `oauth:${cred.client_id}`
             : cred?.kind === 'api_key'  ? `api_key:${cred.key_id}`
             : cred?.kind === 'http_sig' ? `http_sig:${cred.agent_url}`
             : undefined;
   if (!key) return null;
+  if (ref !== undefined) {
+    // Match the full natural key within THIS principal's synced roster.
+    // An unknown or unauthorized ref returns null, without a fallback.
+    return await db.findSyncedAccountByNaturalKey(key, ref);
+  }
+  // Account omitted: use your existing auth-derived selection policy.
   return await db.findAccountByPrincipalKey(key);
 },
 ```
 
+The `db` methods above are operations you implement in your own store.
+`findSyncedAccountByNaturalKey` must compare the complete brand identity
+(domain, optional brand ID and countries), operator, operator-unit ID,
+currency, timezone, and sandbox within the principal's roster. Use consistent
+normalization at sync and lookup, including country ordering and omitted/false
+sandbox. It must not create an account or match on brand/operator alone.
+`findAccountByPrincipalKey` handles only the omitted-reference path according
+to your documented selection policy. The built-in `InMemoryImplicitAccountStore`
+keeps its historical first-account selection for that path.
+
 **Why `credential.client_id`, not `authInfo.sub`?**
 
 `credential.client_id` is the OAuth *client* identity — stable across token
@@ -187,14 +213,24 @@ receiving auth errors will refresh credentials or escalate, not call
 
 ```ts
 // ✓ Correct
-resolve: async (_ref, ctx) => {
-  const account = await db.findByPrincipal(extractKey(ctx?.authInfo));
-  return account ?? null;  // omitted account → ACCOUNT_REQUIRED
+resolve: async (ref, ctx) => {
+  const key = extractKey(ctx?.authInfo);
+  if (!key) return null;
+  const account = ref === undefined
+    ? await db.findAccountByPrincipalKey(key)
+    : await db.findSyncedAccountByNaturalKey(key, ref);
+  // Missing: supplied account → ACCOUNT_NOT_FOUND;
+  // omitted account on an account-required operation → ACCOUNT_REQUIRED.
+  return account ?? null;
 },
 
 // ✗ Wrong — misleads buyers about how to recover
-resolve: async (_ref, ctx) => {
-  const account = await db.findByPrincipal(extractKey(ctx?.authInfo));
+resolve: async (ref, ctx) => {
+  const key = extractKey(ctx?.authInfo);
+  if (!key) return null;
+  const account = ref === undefined
+    ? await db.findAccountByPrincipalKey(key)
+    : await db.findSyncedAccountByNaturalKey(key, ref);
   if (!account) throw new AdcpError('AUTH_MISSING', { message: 'call sync_accounts first' });
   return account;
 },

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-04
-> Library: @adcp/sdk v14.1.0
+> Generated at: 2026-10-05
+> Library: @adcp/sdk v14.2.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.

package/docs/migration-14.0-to-14.1.md

@@ -0,0 +1,85 @@
+# Migrating from SDK 14.0 to 14.1
+
+SDK **14.1.0** still uses AdCP **3.2.1** on the wire. Its signature verification
+adopts the AdCP 3.3 agent-resolution algorithm; this does not upgrade your wire
+protocol or require enabling a new media-buy lifecycle.
+
+```sh
+npm install @adcp/sdk@14.1.0
+```
+
+Account policies and strict account references keep their 14.0 defaults. Check
+the applicable rows below before rolling out: some TypeScript types change,
+and signature verification rejects identities or keys it cannot confirm.
+
+## Required changes when applicable
+
+| If your integration… | Change for 14.1 |
+|---|---|
+| Exhaustively switches over `WholesaleFeedSyncState` | Add a `degraded` case. A failed refresh preserves an existing mirror and marks it degraded; an initial failure still sets `error`. |
+| Reads registry refresh fence fields as required values | Handle `undefined` on the deprecated fields in `AgentComplianceDetail.refresh_availability` and the `refreshAgent` 503 response. For example, use `refresh_availability.code ?? 'unknown'` for a local display label. The live registry no longer returns these fields; removal from SDK types is planned for the next major release. |
+| Uses a standalone `BrandJsonJwksResolver` with A2A | Set `protocol: 'a2a'`. Capability discovery defaults to MCP; the onboarding record does not select the transport. |
+| Supplies a natural-key account reference to an implicit seller | Resolve the complete key within the authenticated caller's synced roster. Include brand identity, operator, operator unit, currency, timezone, and sandbox. An unknown supplied reference must return `null`, never fall back to another account. See [account resolution](./guides/account-resolution.md#implicit-deep-dive). |
+| Stores non-canonical issuer URLs in governance principal, replay, or revocation indexes | Migrate those keys to the canonical issuer identity before switching verification. Preserve replay and revocation history; use the [signature migration guide](./migration-agent-resolution-3.3.md) to check normalization rules. |
+| Configures JWKS or operator discovery cache limits | Review the bounds in the [signature migration guide](./migration-agent-resolution-3.3.md). Brand discovery requires positive `maxAgeSeconds`; non-finite or negative cache options fail configuration validation. Expired mappings and keys are refused rather than reused. |
+| Repairs wholesale mirrors from webhook deliveries | Acknowledge only after `refresh()` or repair succeeds. Failed catalog reads now reject, preserving the mirror and leaving the delivery eligible for retry. |
+
+For the complete list of newly optional registry fields, see the
+[14.1.0 changelog](https://github.com/adcontextprotocol/adcp-client/blob/main/CHANGELOG.md#1410).
+
+## Security behavior to verify
+
+Existing resolver constructor signatures remain supported, but accepting a key
+now requires a confirmed canonical agent identity and the capabilities-selected
+operator record. Ambiguous onboarding and unconfirmed cross-domain mappings
+fail closed. Prefer supplying the expected `agentUrl` already recorded by your
+integration.
+
+Publisher-pinned webhook keys must also appear in the agent JWKS as the same
+public key. Resolve pins from your persisted registration and media-buy record
+for every affected publisher, rather than selecting publishers from the webhook
+payload. Refresh callbacks must throw on fetch failure; `null` confirms removal
+of a pin. Follow the [publisher-pin migration guidance](./migration-agent-resolution-3.3.md#publisher-pin-context).
+
+`SingleAgentClient` and `BrandJsonJwksResolver` retain legacy 3.x webhook
+fallback by default. A standalone `ResolvedAgentJwksResolver` requires explicit
+opt-in. That fallback does not authorize request signatures.
+
+Signed MCP and A2A HTTP 401 errors now retain signature diagnostics and repair
+guidance. Explicit Signature-challenge rejections skip unsigned authentication
+probes and credential refresh retries. Bare signed 401s retain the existing
+single client-credentials refresh attempt.
+
+## Optional adoption
+
+| Feature | Default and adoption path |
+|---|---|
+| Buyer account registry | `accountPolicy` remains `'off'`. Set `'auto'` or `'strict'` to enforce setup, or configure registry storage/scope/capacity to opt into memoized `resolveAccount()`. Without opt-in, that helper still sends `sync_accounts` on each call. See [first call to a seller](./guides/FIRST-CALL-TO-A-SELLER.md). |
+| Product cache | Opt in with `createProductCache`. Public and account-scoped responses stay separate; missing `cache_scope` prevents caching. See [buyer setup and caching](./guides/FIRST-CALL-TO-A-SELLER.md). |
+| Strict seller account references | `strictAccountReferences` remains false; compatibility paths warn. Move reference authorization into `resolveAccount`, then set it to true. It becomes the default in the next major release. See [strict account references](./guides/account-resolution.md#strict-account-references-strictaccountreferences). |
+| Additive implicit account sync | `InMemoryImplicitAccountStore` keeps replacement sync semantics and its 24-hour TTL. Set `mergeOnUpsert: true` for additive batches; `delete_missing: true` still requests replacement. Use `remove(ref, ctx)` for individual revocation. |
+
+Account resolvers now receive `ctx.provisioning`. Discovery and negotiation
+must remain lookup-only; gate any lazy account creation on this flag. The
+[seller account guide](./guides/account-resolution.md) includes an example.
+
+## Check your rollout
+
+- Compile your application to catch the new state and optional registry fields.
+- Exercise signed requests and webhooks against your actual agent/operator
+  records, including key rotation and any publisher pins.
+- Check that supplied unknown or unauthorized account references are refused,
+  and that discovery does not create accounts.
+- If you handle `sync_accounts` results, handle per-account notification
+  event-type failures. In strict request validation, valid siblings can proceed;
+  with `delete_missing: true`, the invalid batch is refused before writes.
+  Warn-mode validation remains advisory, as in 14.0.
+- Exercise failed feed refreshes and webhook redelivery without losing the last
+  good mirror.
+
+The published 14.1.0 artifact passed reporting core **4/4** and full lifecycle
+**4/4** qualification, with integrity and provenance verified. This covers
+Python producers and TypeScript consumers. It does not establish reverse-direction
+parity or Python version-skew coverage; broader work remains in
+[#3027](https://github.com/adcontextprotocol/adcp-client/issues/3027).
+See the [published release and qualification evidence](https://github.com/adcontextprotocol/adcp-client/releases/tag/%40adcp/sdk%4014.1.0).

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.1.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@14.1.0 dist.integrity` |
+| Exact npm package | `@adcp/sdk@14.2.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@14.2.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.1.0'
-npm view '@adcp/sdk@14.1.0' dist.integrity
+npm install --save-exact '@adcp/sdk@14.2.0'
+npm view '@adcp/sdk@14.2.0' dist.integrity
 ```
 
 ### Required and optional peers

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

@@ -1,8 +1,10 @@
 # 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.
+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
 

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

@@ -387,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.1.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/**/*",

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