@adcp/sdk 6.5.0 → 6.7.0

package/ADCP_VERSION

@@ -1 +1 @@
-3.0.1
+3.0.5

package/AGENTS.md

@@ -19,6 +19,10 @@ This document contains essential guidelines for AI coding assistants (Claude, Co
 
 **Testing an agent for conformance?** — Read `docs/guides/CONFORMANCE.md` and call `runConformance(agentUrl, opts)` from `@adcp/sdk/conformance`. Property-based fuzzing against the bundled JSON schemas; stateless tier covers 11 discovery tools across every protocol.
 
+**Migration guides** — `docs/migration-6.6-to-6.7.md` (fifteen adopter recipes; two breaking changes — `'implicit'` enforces inline-`account_id` refusal and `SalesPlatform` split into `SalesCorePlatform & SalesIngestionPlatform`; plus `definePlatform` helpers, `composeMethod`, `accounts.resolve` security presets, `accounts.upsert/list/syncGovernance(ctx)`, typed errors, `issues[].hint`, `BuyerAgentRegistry`, `createTenantRegistry`, `createOAuthPassthroughResolver`, `createRosterAccountStore`, `createTenantStore` w/ built-in tenant gate, `MEDIA_BUY_TRANSITIONS` lifecycle helpers, `createMediaBuyStore` for `targeting_overlay` echo, `NoAccountCtx` narrow, `refAccountId(ref)`); `docs/migration-5.x-to-6.x.md` (5 → 6 framework shape); `docs/migration-4.x-to-5.x.md` (4 → 5); `docs/migration-buyer-agent-registry.md` (registry deep-dive).
+
+**Putting credentials in `ctx_metadata`?** — Don't. Read `docs/guides/CTX-METADATA-SAFETY.md` — wire-strip protects buyer responses but not log lines / error envelopes / heap dumps / adopter strings. Re-derive bearers per request; embed only non-secret upstream IDs.
+
 ## Project Overview
 
 **@adcp/sdk** is the official TypeScript client library for the Ad Context Protocol (AdCP), documented at [docs.adcontextprotocol.org](https://docs.adcontextprotocol.org/docs/).

package/README.md

@@ -279,43 +279,56 @@ Building a server that receives AdCP tool calls? **v6 (recommended for new agent
 
 ```typescript
 import { serve } from '@adcp/sdk';
-import { createAdcpServerFromPlatform, type DecisioningPlatform } from '@adcp/sdk/server/decisioning';
+import { createAdcpServerFromPlatform, definePlatform, defineSalesCorePlatform, refAccountId } from '@adcp/sdk/server';
 
-const platform = {
+const platform = definePlatform({
   capabilities: {
     specialisms: ['sales-non-guaranteed'] as const,
-    creative_agents: [],
     channels: ['display'] as const,
     pricingModels: ['cpm'] as const,
-    config: {},
   },
-  statusMappers: {},
   accounts: {
-    resolve: async (ref, ctx) => db.findAccount(ref, ctx),
+    resolve: async (ref, ctx) => {
+      const id = refAccountId(ref);
+      if (!id) return null; // → ACCOUNT_NOT_FOUND
+      return db.findAccount(id, ctx);
+    },
   },
-  sales: {
-    getProducts: async (req, ctx) => ({ products: catalog.search(req) }),
+  sales: defineSalesCorePlatform({
+    getProducts: async (req, ctx) => ({ products: catalog.search(req) }), // req typed ✓
     createMediaBuy: async (req, ctx) => ({
       media_buy_id: 'mb_1',
       status: 'pending_creatives',
       confirmed_at: new Date().toISOString(),
       packages: [],
     }),
-    updateMediaBuy: async (id, req, ctx) => ({ media_buy_id: id, status: 'active' }),
-    syncCreatives: async (creatives, ctx) =>
-      creatives.map(c => ({ creative_id: c.creative_id, action: 'created' as const, status: 'approved' })),
+    updateMediaBuy: async (id, patch, ctx) => ({ media_buy_id: id, status: 'active' }),
     getMediaBuyDelivery: async (req, ctx) => ({
       currency: 'USD',
-      reporting_period: { start: '...', end: '...' },
+      reporting_period: { start: '2026-05-01T00:00:00Z', end: '2026-05-31T23:59:59Z' },
       media_buy_deliveries: [],
     }),
-  },
-} satisfies DecisioningPlatform;
+    getMediaBuys: async (req, ctx) => ({ media_buys: [] }),
+  }),
+});
 
 serve(() => createAdcpServerFromPlatform(platform, { name: 'My Publisher', version: '1.0.0' }));
 ```
 
-`RequiredPlatformsFor<S>` enforces specialism claims at compile time — claim `'sales-non-guaranteed'` and the typechecker requires `sales: SalesPlatform`. `creative-template` and `creative-generative` claims both map to `CreativeBuilderPlatform`; `creative-ad-server` is its own archetype with `listCreatives` + `getCreativeDelivery`.
+`RequiredPlatformsFor<S>` enforces specialism claims at compile time — claim `'sales-non-guaranteed'` and the typechecker requires `SalesCorePlatform & SalesIngestionPlatform` on `sales`. `creative-template` and `creative-generative` claims both map to `CreativeBuilderPlatform`; `creative-ad-server` is its own archetype with `listCreatives` + `getCreativeDelivery`.
+
+**6.7 helpers worth knowing about:**
+
+- `definePlatform` / `defineSalesCorePlatform` / `defineSalesIngestionPlatform` / sibling `define<X>Platform` factories — drop `req: unknown` casts on inline platform objects.
+- `composeMethod(inner, { before, after })` — typed before/after wrappers around any platform method (caching, enrichment under `ext.*`, typed-error guards). Pre-built `accounts.resolve` guards: `requireAccountMatch`, `requireAdvertiserMatch`, `requireOrgScope`.
+- Typed errors: `AuthRequiredError`, `PermissionDeniedError`, `RateLimitedError`, `ServiceUnavailableError`, `GovernanceDeniedError`, `IdempotencyConflictError`, plus the not-found family. Throw these instead of `new AdcpError(code, ...)`.
+- `BuyerAgentRegistry` — durable buyer-agent identity surface threaded through `ctx.agent` to every `AccountStore` method. See [`docs/migration-buyer-agent-registry.md`](docs/migration-buyer-agent-registry.md).
+- Three reference `AccountStore` shapes: `InMemoryImplicitAccountStore` (Shape A — buyer-driven `sync_accounts`), `createOAuthPassthroughResolver` (Shape B — vendor OAuth + `/me/adaccounts`), `createRosterAccountStore` (Shape C — publisher-curated roster).
+- Multi-tenant: `createTenantRegistry({...})` for host-routed (one server per tenant) or `createTenantStore({...})` for account-routed (one server, per-entry tenant gate built in, fail-closed when auth principal can't be resolved).
+- `createMediaBuyStore` — opt-in `targeting_overlay` echo on `get_media_buys` for sellers claiming `property-lists` / `collection-lists`.
+- `MEDIA_BUY_TRANSITIONS` / `assertMediaBuyTransition` (and the creative pair) — canonical lifecycle graphs.
+
+Worked reference adapters live in `examples/hello_*` — pick the one whose specialism matches yours and fork.
 
 **v5 lower-level API** (still fully supported as the substrate the v6 path calls into):
 
@@ -328,7 +341,7 @@ function handleCreateMediaBuy(rawParams: unknown): CreateMediaBuyResponse {
 }
 ```
 
-Migration path from 5.x → 6.x: see [`docs/migration-5.x-to-6.x.md`](docs/migration-5.x-to-6.x.md). Note: `PackageRequest` (creation-shaped, required fields) differs from `Package` (response-shaped). See the [type catalog](docs/ZOD-SCHEMAS.md#type-catalog) for all request types and their required fields.
+Migration path from 6.6 → 6.7: see [`docs/migration-6.6-to-6.7.md`](docs/migration-6.6-to-6.7.md) (fifteen recipes, two breaking — `'implicit'`-resolution platforms now actually enforce the inline-`account_id` refusal the docstring has long claimed (pre-6.7 it was silent-pass, so audit your callers); `SalesPlatform` split into `SalesCorePlatform & SalesIngestionPlatform`). 5.x → 6.x: [`docs/migration-5.x-to-6.x.md`](docs/migration-5.x-to-6.x.md). Note: `PackageRequest` (creation-shaped, required fields) differs from `Package` (response-shaped). See the [type catalog](docs/ZOD-SCHEMAS.md#type-catalog) for all request types and their required fields.
 
 ## Multi-Agent Operations
 

package/bin/adcp-resolve.js

@@ -0,0 +1,166 @@
+'use strict';
+
+/**
+ * `adcp resolve <agent-url>` — runs the brand_json_url discovery chain
+ * (security.mdx §"Discovering an agent's signing keys via `brand_json_url`")
+ * and prints the trace + resolved chain. Pairs with the SDK's `resolveAgent()`
+ * for dev-loop debugging when an operator hits a `request_signature_brand_*`
+ * rejection in production and needs to see exactly which step rejected.
+ *
+ * Flags:
+ *   --json     emit machine-readable JSON instead of the default text trace
+ *   --fresh    bypass any caches the SDK might add later (no-op today)
+ *   --quiet    suppress per-step lines, only print the final summary
+ *   --protocol mcp|a2a   default mcp; only used when calling get_adcp_capabilities
+ *   --allow-private-ip   permit http:// + private-IP targets (dev only)
+ *   --auth-token TOKEN   bearer token for the capabilities call (rare)
+ */
+
+const { resolveAgent, AgentResolverError } = require('../dist/lib/signing/server');
+const { createMCPClient, createA2AClient } = require('../dist/lib/protocols');
+
+function parseArgs(argv) {
+  const opts = { json: false, fresh: false, quiet: false, protocol: 'mcp', allowPrivateIp: false };
+  let agentUrl;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') opts.json = true;
+    else if (a === '--fresh') opts.fresh = true;
+    else if (a === '--quiet') opts.quiet = true;
+    else if (a === '--allow-private-ip') opts.allowPrivateIp = true;
+    else if (a === '--protocol') {
+      opts.protocol = argv[++i];
+      if (opts.protocol !== 'mcp' && opts.protocol !== 'a2a') throw new Error(`--protocol must be mcp or a2a`);
+    } else if (a === '--auth-token') {
+      opts.authToken = argv[++i];
+    } else if (a === '--help' || a === '-h') {
+      opts.help = true;
+    } else if (a.startsWith('-')) {
+      throw new Error(`Unknown flag: ${a}`);
+    } else if (!agentUrl) {
+      agentUrl = a;
+    } else {
+      throw new Error(`Unexpected positional argument: ${a}`);
+    }
+  }
+  return { agentUrl, opts };
+}
+
+function printHelp() {
+  process.stdout.write(`Usage: adcp resolve <agent-url> [--json] [--fresh] [--quiet]
+                          [--protocol mcp|a2a] [--allow-private-ip]
+                          [--auth-token TOKEN]
+
+Resolve an AdCP agent's signing keys by walking the 8-step brand_json_url
+discovery chain (capabilities -> identity.brand_json_url -> brand.json ->
+agents[] -> jwks_uri -> JWKS).
+
+Useful for triaging \`request_signature_brand_*\` rejections in production —
+prints which step rejected and why.
+
+Flags:
+  --json                Emit JSON to stdout instead of the default text trace.
+  --fresh               Bypass any SDK-side caches (reserved; no-op today).
+  --quiet               Print only the final summary, suppress per-step lines.
+  --protocol mcp|a2a    Protocol the agent speaks. Default: mcp.
+  --allow-private-ip    Permit http:// and private-IP targets (dev/test only).
+  --auth-token TOKEN    Bearer token for the capabilities call (rare).
+`);
+}
+
+async function handleResolveCommand(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (err) {
+    process.stderr.write(`adcp resolve: ${err.message}\n`);
+    process.exit(2);
+  }
+  if (parsed.opts.help || !parsed.agentUrl) {
+    printHelp();
+    process.exit(parsed.agentUrl ? 0 : 2);
+  }
+
+  const { agentUrl, opts } = parsed;
+  const fetchCapabilities = async () => {
+    const client =
+      opts.protocol === 'a2a' ? createA2AClient(agentUrl, opts.authToken) : createMCPClient(agentUrl, opts.authToken);
+    return client.callTool('get_adcp_capabilities', {});
+  };
+
+  try {
+    const resolution = await resolveAgent(agentUrl, {
+      protocol: opts.protocol,
+      allowPrivateIp: opts.allowPrivateIp,
+      fetchCapabilities,
+    });
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(serialize(resolution), null, 2) + '\n');
+    } else {
+      printText(resolution, { quiet: opts.quiet });
+    }
+    process.exit(0);
+  } catch (err) {
+    if (err instanceof AgentResolverError) {
+      if (opts.json) {
+        process.stdout.write(
+          JSON.stringify(
+            {
+              ok: false,
+              code: err.code,
+              message: err.message,
+              detail: err.detail,
+            },
+            null,
+            2
+          ) + '\n'
+        );
+      } else {
+        process.stderr.write(`✖ ${err.code}\n  ${err.message}\n`);
+        for (const [k, v] of Object.entries(err.detail)) {
+          process.stderr.write(`  ${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}\n`);
+        }
+      }
+      process.exit(1);
+    }
+    process.stderr.write(`✖ ${err.message ?? err}\n`);
+    process.exit(1);
+  }
+}
+
+function serialize(resolution) {
+  return {
+    ok: true,
+    agent_url: resolution.agentUrl,
+    brand_json_url: resolution.brandJsonUrl,
+    jwks_uri: resolution.jwksUri,
+    jwks_kids: resolution.jwks.keys.map(k => k.kid),
+    identity_posture: resolution.identityPosture,
+    consistency: resolution.consistency,
+    freshness: resolution.freshness,
+    jwks_cache_control: resolution.jwksCacheControl,
+    trace: resolution.trace,
+  };
+}
+
+function printText(resolution, { quiet }) {
+  if (!quiet) {
+    process.stdout.write(`✓ resolved ${resolution.agentUrl}\n\n`);
+    for (const step of resolution.trace) {
+      const mark = step.ok ? '✓' : '✗';
+      const url = step.url ? ` (${step.url})` : '';
+      const age = step.ageSeconds !== undefined ? ` [${step.ageSeconds}s ago]` : '';
+      process.stdout.write(`  ${mark} step ${step.step}: ${step.name}${url}${age}\n`);
+    }
+    process.stdout.write('\n');
+  }
+  process.stdout.write(`agent_url:       ${resolution.agentUrl}\n`);
+  process.stdout.write(`brand_json_url:  ${resolution.brandJsonUrl}\n`);
+  process.stdout.write(`jwks_uri:        ${resolution.jwksUri}\n`);
+  process.stdout.write(`kids:            ${resolution.jwks.keys.map(k => k.kid).join(', ')}\n`);
+  if (resolution.jwksCacheControl) {
+    process.stdout.write(`jwks_cache:      ${resolution.jwksCacheControl}\n`);
+  }
+}
+
+module.exports = { handleResolveCommand };