@adcp/sdk 8.1.0-beta.18 → 8.1.0-beta.19

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-05-30
-> Library: @adcp/sdk v8.1.0-beta.16
+> Generated at: 2026-05-31
+> Library: @adcp/sdk v8.1.0-beta.18
 > 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.
@@ -56,6 +56,8 @@ Lower-level option: `createAdcpServer({ signals: { getSignals: ... } })` from `@
 
 **Four reference `AccountStore` shapes.** Pick the one whose onboarding model matches yours. **Shape A — `InMemoryImplicitAccountStore`**: `resolution: 'implicit'`, buyer-driven `sync_accounts` populates the auth-principal → accounts map. **Shape B — `createOAuthPassthroughResolver`**: `resolution: 'explicit'`, returns just the `resolve` function for adapters fronting an upstream OAuth listing endpoint (Snap, Meta, TikTok, LinkedIn — `extract bearer → GET /me/adaccounts → match by id`). **Shape C — `createRosterAccountStore`**: `resolution: 'explicit'`, returns a complete `AccountStore` for adopters who own the roster (storefront table, admin-UI-managed JSON). Supports `resolveWithoutRef` for tools that send no `account` field on the wire (`list_creative_formats`, `preview_creative`, `provide_performance_feedback`) — set it to return a synthetic publisher-wide entry instead of `null`. **Shape D — `createDerivedAccountStore`**: `resolution: 'derived'`, single-tenant agents where there is no `account_id` on the wire and the auth principal alone identifies the tenant (audiostack, flashtalking, single-namespace retail-media). Provide `toAccount(ctx)`; the factory still emits legacy-compatible `AUTH_REQUIRED` on missing-credential calls and ignores buyer-supplied `account_id` (single-tenant by definition). Buyer code must continue to handle `AUTH_REQUIRED` alongside `AUTH_MISSING` / `AUTH_INVALID`. All four live at `@adcp/sdk/server`.
 
+**Stateless BYOK provider auth.** For single-account API-key or bearer-token BYOK, the provider credential can be the AdCP request credential for that endpoint: `Authorization: Bearer <provider_api_key_or_access_token>`. This keeps the baseline seller-agent wrapper pattern single-plane: the seller agent authenticates the request with the caller-presented provider credential, derives the account from request auth, and uses the same request-local token for upstream provider calls. No SDK-managed OAuth flow, refresh-token store, provider-token store, or callback route is required when the caller owns the provider credential lifecycle. If the provider credential can see multiple upstream accounts, use an explicit account roster pattern such as `createOAuthPassthroughResolver` instead of `'derived'`. Handlers with a resolved account should read the active token from `ctx.account.authInfo?.token`; refresh hooks update `account.authInfo`. Handlers without a resolved account can read the request token from `ctx.authInfo.token`. Use a stable non-secret identity such as `ctx.authInfo.credential.key_id`, `ctx.authInfo.credential.client_id`, or an adopter-supplied `principal` string for cache/idempotency scoping. Treat both token paths as request-local: do not copy provider tokens into persisted Account rows, `ctx_metadata`, `ctx.authInfo.extra`, request `ext` / body fields, or log lines. Add a separate provider-auth channel only for dual-auth proxy deployments where one request carries both caller-to-agent auth and a distinct upstream-provider credential.
+
 **Multi-tenant.** Two helpers, pick by deployment shape. **Host-routed**: `createTenantRegistry({...})` — one server per tenant, tenant-id keyed lookup with `registry.get(tenantId)`. **Account-routed**: `createTenantStore({...})` — one server, per-entry tenant-isolation gate built in (cross-tenant entries on `upsert` / `syncGovernance` rejected with `PERMISSION_DENIED` BEFORE adopter callbacks run; fail-closed when the auth principal can't be resolved). `createTenantStore` mitigates the canonical multi-tenant write-across-tenants bug class at the SDK layer rather than relying on adopter discipline.
 
 **`BuyerAgentRegistry`** — durable buyer-agent identity surface. `BuyerAgentRegistry.signingOnly({ resolveByAgentUrl })` (production target — only `http_sig` credentials route through), `bearerOnly({ resolveByCredential })` (pre-trust beta — bearer/api-key/oauth all route), `mixed(...)` (transition posture). Wrap with `BuyerAgentRegistry.cached(inner, { ttlSeconds })` for TTL + LRU + concurrent-resolve coalescing. The resolved `BuyerAgent` flows through `ctx.agent` to every `AccountStore` method (`resolve` / `upsert` / `list` / `syncGovernance` / `reportUsage` / `getAccountFinancials`) and to `tasks_get` polling. `BuyerAgent.status === 'suspended' | 'blocked'` triggers framework-level `PERMISSION_DENIED`. `BuyerAgent.sandbox_only: true` rejects requests against non-sandbox accounts. See [`docs/migration-buyer-agent-registry.md`](./migration-buyer-agent-registry.md) for the full surface.
@@ -1492,7 +1494,7 @@ Every tool call returns a `TaskResult` with one of these statuses:
 
 ## Protocols
 
-AdCP tools are served over MCP (Model Context Protocol) or A2A (Agent-to-Agent). The client auto-detects based on `AgentConfig.protocol`. MCP endpoints end with `/mcp/`. Auth is via bearer token in `x-adcp-auth` header.
+AdCP tools are served over MCP (Model Context Protocol) or A2A (Agent-to-Agent). The client auto-detects based on `AgentConfig.protocol`. MCP endpoints end with `/mcp/`. Bearer auth uses `Authorization: Bearer <token>`; SDK clients also send the legacy `x-adcp-auth` header for compatibility, and servers accept it as a fallback.
 
 **Deep dive:** docs/development/PROTOCOL_DIFFERENCES.md
 

package/examples/README.md

@@ -70,6 +70,10 @@ Cross-specialism dispatch: `brandRights.acquireRights` consults `campaignGoverna
 
 This is distinct from `decisioning-platform-multi-tenant.ts` which uses **host-routed** tenancy via `TenantRegistry` (different agentUrls per tenant). Both are valid; pick by deployment shape.
 
+### Multi-tenant (path-routed Express)
+
+`decisioning-platform-path-routed.ts` demonstrates the **path-routed** TenantRegistry model for existing Express apps that must keep legacy public paths such as `/storefront/:platformId/mcp`. The route resolves the tenant from the decoded path segment, creates a per-request `StreamableHTTPServerTransport`, stamps MCP `req.auth` from the app's existing auth middleware, and lets each platform's `accounts.resolve(ref, ctx)` scope buyer identity from `ctx.authInfo`.
+
 ### Agent testing (`comply_test_controller`)
 
 Start with `createComplyController` (`comply-controller-seller.ts`). Switch to `registerTestController` (`seller-test-controller.ts`) only when your domain state has internal structure that multiple production tools read from — i.e., when the adapter surface's one-method-per-scenario shape starts fighting the code you already have.

package/examples/decisioning-platform-path-routed.ts

@@ -0,0 +1,278 @@
+/**
+ * Path-routed TenantRegistry + Express StreamableHTTP auth example.
+ *
+ * Use this shape when an existing buyer-facing Express app already owns a
+ * public path such as `/storefront/:platformId/mcp` and existing auth
+ * middleware, but you want SDK-owned tenant servers instead of constructing
+ * one AdCP server per buyer request.
+ *
+ * The important boundary is:
+ *
+ *   Express auth middleware -> req.user -> req.auth -> ctx.authInfo -> accounts.resolve()
+ *
+ * Tenant selection stays at the route/registry boundary. Buyer identity stays
+ * in MCP `AuthInfo`, so platform handlers do not close over Express `req.user`.
+ *
+ * Mount this route after your JSON body parser, for example
+ * `app.use(express.json({ limit: '2mb' }))`.
+ */
+
+import type { Express, NextFunction, Request, RequestHandler, Response } from 'express';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import { mcpAcceptHeaderMiddleware } from '@adcp/sdk/express-mcp';
+import {
+  createTenantRegistry,
+  type AccountStore,
+  type DecisioningAdcpServer,
+  type ResolveContext,
+  type TenantRegistry,
+  type TenantSigningKey,
+} from '@adcp/sdk/server';
+import type { AccountReference } from '@adcp/sdk/types';
+import { ProgrammaticSeller } from './decisioning-platform-programmatic';
+import { BroadcastTvSeller } from './decisioning-platform-broadcast-tv';
+
+type PlatformId = 'snap' | 'vertex';
+
+interface StorefrontUser {
+  buyerCustomerId: string;
+  accessToken: string;
+  scopes: string[];
+}
+
+type StorefrontRequest = Request<{ platformId: string }, unknown, unknown> & {
+  user?: StorefrontUser;
+  auth?: AuthInfo;
+  body?: unknown;
+};
+
+interface ProgrammaticCtxMeta {
+  network_id: string;
+  advertiser_id: string;
+  buyer_customer_id: string;
+  tenant_id: PlatformId;
+  [key: string]: unknown;
+}
+
+interface BroadcastCtxMeta {
+  agency_buyer_id: string;
+  affiliate_advertiser_id: string;
+  buyer_customer_id: string;
+  tenant_id: PlatformId;
+  [key: string]: unknown;
+}
+
+/**
+ * Existing apps usually already have this function behind their auth
+ * middleware. The example accepts it as a dependency instead of inventing
+ * bearer tokens or fake users.
+ */
+export type VerifyStorefrontUser = (req: Request) => Promise<StorefrontUser | null>;
+
+// ---------------------------------------------------------------------------
+// PRODUCTION: REPLACE WITH KMS-BACKED LOADER
+// ---------------------------------------------------------------------------
+//
+// The registry can serve unsigned tenants in AdCP 3.x, so this example returns
+// undefined to keep the route runnable before KMS/brand.json is wired. In a
+// production signed-webhook deployment, load one tenant-specific key from your
+// KMS or secret manager and publish the public half in that tenant's brand.json.
+// Never commit private signing material to source.
+// ---------------------------------------------------------------------------
+async function loadTenantSigningKey(_tenantId: PlatformId): Promise<TenantSigningKey | undefined> {
+  return undefined;
+}
+
+function optionalSigningKey(signingKey: TenantSigningKey | undefined): { signingKey?: TenantSigningKey } {
+  return signingKey ? { signingKey } : {};
+}
+
+class StorefrontProgrammaticSeller extends ProgrammaticSeller {
+  override accounts: AccountStore<ProgrammaticCtxMeta> = {
+    resolve: async (ref: AccountReference | undefined, ctx?: ResolveContext) => {
+      const buyerCustomerId = buyerCustomerIdFrom(ctx);
+      if (!buyerCustomerId) return null;
+      const accountId = accountIdFrom(ref) ?? `snap_${buyerCustomerId}`;
+      return {
+        id: accountId,
+        name: `Snap storefront account ${accountId}`,
+        status: 'active',
+        operator: 'snap.example.com',
+        ctx_metadata: {
+          network_id: this.capabilities.config.networkId,
+          advertiser_id: buyerCustomerId,
+          buyer_customer_id: buyerCustomerId,
+          tenant_id: 'snap',
+        },
+        authInfo: { kind: 'oauth', token: ctx?.authInfo?.token, principal: buyerCustomerId },
+      };
+    },
+  };
+}
+
+class StorefrontBroadcastSeller extends BroadcastTvSeller {
+  override accounts: AccountStore<BroadcastCtxMeta> = {
+    resolve: async (ref: AccountReference | undefined, ctx?: ResolveContext) => {
+      const buyerCustomerId = buyerCustomerIdFrom(ctx);
+      if (!buyerCustomerId) return null;
+      const accountId = accountIdFrom(ref) ?? `vertex_${buyerCustomerId}`;
+      return {
+        id: accountId,
+        name: `Vertex storefront account ${accountId}`,
+        status: 'active',
+        operator: 'vertex.example.com',
+        ctx_metadata: {
+          agency_buyer_id: buyerCustomerId,
+          affiliate_advertiser_id: accountId,
+          buyer_customer_id: buyerCustomerId,
+          tenant_id: 'vertex',
+        },
+        authInfo: { kind: 'oauth', token: ctx?.authInfo?.token, principal: buyerCustomerId },
+      };
+    },
+  };
+}
+
+export async function buildPathRoutedStorefrontRegistry(): Promise<TenantRegistry> {
+  const registry = createTenantRegistry({
+    defaultServerOptions: {
+      name: 'path-routed-storefront',
+      version: '0.0.1',
+      validation: { requests: 'strict', responses: 'strict' },
+    },
+    autoValidate: true,
+  });
+
+  registry.register('snap', {
+    agentUrl: 'https://storefront.example.com/storefront/snap/mcp',
+    ...optionalSigningKey(await loadTenantSigningKey('snap')),
+    platform: new StorefrontProgrammaticSeller(),
+    label: 'Snap Storefront',
+    serverOptions: { name: 'snap-storefront', version: '1.0.0' },
+  });
+
+  registry.register('vertex', {
+    agentUrl: 'https://storefront.example.com/storefront/vertex/mcp',
+    ...optionalSigningKey(await loadTenantSigningKey('vertex')),
+    platform: new StorefrontBroadcastSeller(),
+    label: 'Vertex Storefront',
+    serverOptions: { name: 'vertex-storefront', version: '1.0.0' },
+  });
+
+  return registry;
+}
+
+export interface MountPathRoutedStorefrontOptions {
+  /**
+   * Existing app-specific verifier. Return null for unauthenticated requests;
+   * the middleware below maps that to 401 before the MCP transport runs.
+   */
+  verifyUser: VerifyStorefrontUser;
+}
+
+export function mountPathRoutedStorefront(
+  app: Pick<Express, 'all'>,
+  registry: TenantRegistry,
+  options: MountPathRoutedStorefrontOptions
+): void {
+  const acceptMiddleware = mcpAcceptHeaderMiddleware() as RequestHandler;
+  const authMiddleware = createStorefrontAuthMiddleware(options.verifyUser);
+
+  app.all('/storefront/:platformId/mcp', acceptMiddleware, authMiddleware, async (req: Request, res: Response) => {
+    const storefrontReq = req as StorefrontRequest;
+    const platformId = normalizePlatformId(storefrontReq.params.platformId);
+    if (!platformId) {
+      res.status(404).json({ error: 'unknown platform' });
+      return;
+    }
+
+    // Express already decoded `:platformId`, so prefer direct tenant lookup.
+    // If your app uses a catch-all route instead, use
+    // `registry.resolveByRequest(req.headers.host!, req.path)` here.
+    const resolved = registry.get(platformId);
+    if (!resolved) {
+      res.status(404).json({ error: 'tenant unavailable' });
+      return;
+    }
+
+    storefrontReq.auth = toMcpAuthInfo(storefrontReq.user!);
+    await handleWithPerRequestTransport(resolved.server, storefrontReq, res, storefrontReq.body);
+  });
+}
+
+function createStorefrontAuthMiddleware(verifyUser: VerifyStorefrontUser): RequestHandler {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const user = await verifyUser(req);
+      if (!user) {
+        res.status(401).json({ error: 'unauthorized' });
+        return;
+      }
+      (req as StorefrontRequest).user = user;
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+function toMcpAuthInfo(user: StorefrontUser): AuthInfo {
+  return {
+    token: user.accessToken,
+    clientId: user.buyerCustomerId,
+    scopes: user.scopes,
+    extra: {
+      buyerCustomerId: user.buyerCustomerId,
+    },
+  };
+}
+
+const transportLocks = new WeakMap<DecisioningAdcpServer, Promise<void>>();
+
+async function handleWithPerRequestTransport(
+  server: DecisioningAdcpServer,
+  req: StorefrontRequest,
+  res: Response,
+  parsedBody: unknown
+): Promise<void> {
+  const runTransportCycle = async (): Promise<void> => {
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    try {
+      await server.connect(transport);
+      if (parsedBody !== undefined) {
+        await transport.handleRequest(req, res, parsedBody);
+      } else {
+        await transport.handleRequest(req, res);
+      }
+    } catch (err) {
+      console.error('MCP transport error:', err);
+      if (!res.headersSent) {
+        res.status(500).json({ error: 'Internal server error' });
+      }
+    } finally {
+      await server.close();
+    }
+  };
+
+  const previous = transportLocks.get(server) ?? Promise.resolve();
+  const current = previous.then(runTransportCycle, runTransportCycle);
+  transportLocks.set(
+    server,
+    current.catch(() => {})
+  );
+  await current;
+}
+
+function buyerCustomerIdFrom(ctx: ResolveContext | undefined): string | undefined {
+  const value = ctx?.authInfo?.extra?.buyerCustomerId;
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function accountIdFrom(ref: AccountReference | undefined): string | undefined {
+  return ref && 'account_id' in ref ? ref.account_id : undefined;
+}
+
+function normalizePlatformId(value: string | undefined): PlatformId | null {
+  return value === 'snap' || value === 'vertex' ? value : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "8.1.0-beta.18",
+  "version": "8.1.0-beta.19",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",