@adcp/sdk 17.0.0-beta.2 → 17.0.0-beta.4

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-27
-> Library: @adcp/sdk v17.0.0-beta.2
+> Generated at: 2026-10-28
+> Library: @adcp/sdk v17.0.0-beta.4
 > 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.x-rc-worksheet.md

@@ -16,8 +16,8 @@ pin using `ADCP_VERSION` inside that tarball.
 
 | Fact | Value |
 | --- | --- |
-| Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.2` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.2 dist.integrity` |
+| Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.4` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.4 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.3.0-beta.0` |
 | Maintained wire releases | `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.1.25`, `3.1.26`, `3.1.27`, `3.1.28`, `3.1.29`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4`, `3.2.5`, `3.2.6`, `3.2.7`, `3.3.0-beta.0`, `3.3-beta.0` |
@@ -26,8 +26,8 @@ pin using `ADCP_VERSION` inside that tarball.
 For a checkout at the published release commit, install the exact package version:
 
 ```bash
-npm install --save-exact '@adcp/sdk@17.0.0-beta.2'
-npm view '@adcp/sdk@17.0.0-beta.2' dist.integrity
+npm install --save-exact '@adcp/sdk@17.0.0-beta.4'
+npm view '@adcp/sdk@17.0.0-beta.4' dist.integrity
 ```
 
 ### Required and optional peers

package/docs/migration-16-to-17.md

@@ -151,6 +151,25 @@ server handlers are `mediaBuy.listCollections` and `mediaBuy.listProposals`,
 or optional methods on `MediaBuyLifecyclePlatform`. Their synchronous results
 use `outcome` and do not acquire a synthetic task `status` field.
 
+## Postgres replay store
+
+`PostgresReplayStore` inserts through a table-specific guarded function
+(`<table>_insert_guarded`) that keeps the replay check, the per-key cap and the
+insert on one backend. A database created by an earlier SDK has the table but
+not the function. Every insert then fails with "PostgresReplayStore database
+migration is outdated", and signed requests answer 503 (Web Bot Auth) or are
+refused. Rerun the migration for each replay table before deploying SDK 17:
+
+```ts
+import { getReplayStoreMigration } from '@adcp/sdk/signing/server';
+
+await pool.query(getReplayStoreMigration('adcp_replay_cache')); // your table name
+```
+
+The migration is idempotent. If you manage schema with numbered migration
+files, add a new file with the current `getReplayStoreMigration()` output; a
+file copied from an older SDK does not create the function.
+
 ## Account resolution and optional declarations
 
 On a served AdCP 3.3 route, buyer-supplied account references require a
@@ -255,6 +274,14 @@ For AdCP 3.0 buyers, `create_media_buy` and `update_media_buy` responses move
 waiting on creatives therefore returns `status: 'pending_creatives'`; 3.1+
 responses keep task `status` separate from `media_buy_status`.
 
+This projection applies to responses the framework emits. A webhook your
+platform builds itself from a copy of the response, such as an inline completion
+callback to a 3.0 buyer, does not pass through it. Apply the same mapping so the
+webhook `result` matches the buyer-visible response: for a 3.0 buyer, carry the
+media buy status as `status` and omit `media_buy_status`. A test comparing the
+webhook `result` with the synchronous response catches drift. Exporting the
+projection for seller-emitted webhooks is tracked in #3475.
+
 ## Receivers with their own delivery webhook verification
 
 `parseMediaBuyDeliveryWebhook` from `@adcp/sdk/webhooks` validates an already

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

@@ -3,10 +3,11 @@
 The experimental identity rollout is tracked in
 [adcp-client#3233](https://github.com/adcontextprotocol/adcp-client/issues/3233).
 This release implements the rollout behind explicit experimental configuration.
-The SDK's default `ADCP_VERSION` remains **3.2.5**. Experimental client/server
-instances select the 3.3 carrier and apply the pinned draft overlays to the
-released bundle; they do not regenerate or replace the public 3.2 types.
-Upstream PRs remain open, so the experiment can change before graduation.
+SDK 17 beta pins `ADCP_VERSION` to **3.3.0-beta.0**; SDK 16 remains on 3.2.
+The identity experiment can change before graduation. Setting `identity33`
+selects the 3.3 schema scope for the entire server instance, including its
+non-identity tools. To keep an existing 3.2 endpoint while evaluating identity,
+create a separate server instance and mount it on another route.
 
 The dedicated API is `@adcp/sdk/identity-3.3`. Existing RFC configuration remains
 supported through 3.x and emits a one-time deprecation warning when used.
@@ -287,6 +288,99 @@ reassignment. Authorization runs before idempotency lookup and handler effects.
 Keep the normal buyer registry's suspension, blocking, sandbox and billing
 gates enabled; grants do not replace them.
 
+### Custom MCP hosts
+
+`signedRequests` installs HTTP middleware through `ADCP_PRE_TRANSPORT`. `serve()`
+and `createA2AAdapter()` consume it automatically. A host that calls
+`server.connect(transport)` directly must mount that middleware before handing
+requests to the MCP transport; the server refuses the connection when the hook has not been
+consumed. Connecting the transport alone cannot verify HTTP signatures.
+Reading the symbol acknowledges that the custom host mounts the middleware;
+the framework cannot verify external middleware installation. Socket Mode and
+in-memory transports cannot run this HTTP verifier; use a separate server
+instance without `signedRequests` for those transports.
+Framework-managed MCP connections are permitted per transport after middleware
+accepts the request. Creating an A2A adapter does not acknowledge MCP middleware.
+
+For a host with its own authentication layer, compose
+`verifySignatureAsAuthenticator({ webBotAuth, ... })` instead. A Web Bot Auth-only
+authenticator can omit `jwks`; legacy signatures are then refused. For example:
+
+```ts
+import { createIdentity33PrincipalResolver } from '@adcp/sdk/identity-3.3';
+import {
+  adcpOperationResolver,
+  requireSignatureWhenPresent,
+  verifySignatureAsAuthenticator,
+} from '@adcp/sdk/server';
+
+const signature = verifySignatureAsAuthenticator({
+  capability: {
+    supported: true,
+    profiles: ['web-bot-auth'],
+    covers_content_digest: 'required',
+    required_for: [],
+  },
+  replayStore, // Shared across requests and replicas.
+  resolveOperation: adcpOperationResolver,
+  // Trusted deployment config; never use caller-supplied forwarding headers.
+  getUrl: () => 'https://seller.example.com/mcp',
+  webBotAuth: {
+    directory,
+    resolvePrincipal: createIdentity33PrincipalResolver({ lifecycle, revocation: revocations }),
+  },
+});
+const authenticate = requireSignatureWhenPresent(signature, existingAuthenticator);
+```
+
+Bind this authenticator to the configured `/mcp` route. The host must capture
+the exact UTF-8 body in `req.rawBody` before JSON parsing,
+run `authenticate` before `transport.handleRequest`, and propagate the returned
+principal and authentication failures through its existing auth integration.
+Hoist the authenticator and replay store outside request factories. If using
+`serve()` with this authenticator, it captures the body automatically.
+
+### Signed storyboard steps against a local agent
+
+Storyboard steps can select a named runtime identity:
+
+```yaml
+auth: { type: web_bot_auth, identity: authorized_buyer }
+```
+
+Pass keys separately from the YAML:
+
+```ts
+import { runStoryboard } from '@adcp/sdk/testing';
+
+await runStoryboard('http://127.0.0.1:3001/mcp', storyboard, {
+  protocol: 'mcp',
+  allow_http: true,
+  web_bot_auth: {
+    publicUrl: 'https://seller.example.com/mcp',
+    identities: {
+      authorized_buyer: { origin: 'https://buyer.agency.com', key: { privateKey: buyerJwk } },
+      impersonator: { origin: 'https://other.agency.com', key: { privateKey: otherJwk } },
+    },
+  },
+});
+```
+
+Loopback delivery supports MCP; A2A steps can sign directly to HTTPS. The
+official MCP client signs the public HTTPS target and delivers to the exact
+loopback endpoint. Configure the local verifier's trusted public URL to match,
+and publish or inject the identities' directory, revocation and trust records.
+Each overridden step uses a separate client and strips ambient bearer/API-key
+credentials. An unknown identity fails the step before dispatch. These steps
+support tool-response validations; HTTP probe assertions and session probes
+require their existing authentication directives. The URL override accepts only
+loopback delivery, keeps redirects disabled, and does not relax the production
+signer's HTTPS requirement. Omit `publicUrl` for signing directly to HTTPS.
+For custom official transport wiring, `createStoryboardWebBotAuthFetch` from
+`@adcp/sdk/testing` exposes the same delivery helper.
+For direct HTTPS use of the helper, pass `agentUrl` to pin the destination
+origin. Redirects are refused before the transport can follow them.
+
 `bindPrincipal` requires seller audit evidence. Existing RFC mappings require
 explicit migration approval and an unambiguous origin. `sync_principal` may
 create only a new principal under declared open tiers; legacy-ledger lookup is
@@ -310,6 +404,14 @@ provided notification ID as the emitter's delivery ID. Call
 
 ## Trust, grants, and revocation
 
+Identity authorization requires registrable domains from the pinned PSL.
+Special-use names such as `brand.example`, `localhost`, and IP addresses cannot
+establish trust or grants; invalid brand, account-operator, and resolved-house
+domains receive coded `PERMISSION_DENIED` refusals. For tests, use registrable
+fixture domains and inject `TrustEvaluator({ fetchOptions: { trustedFetchFn } })`
+to serve their test trust records without relying on live DNS. This hook changes
+record delivery, not domain validation or grant authorization.
+
 The operator is derived using the pinned ICANN+PRIVATE PSL, never a document
 field or authoritative hop host. Trust reads allow one document hop, zero HTTP
 redirects, 2 MiB, depth 32, and no duplicate JSON keys. Exactly one canonical

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "17.0.0-beta.2",
+  "version": "17.0.0-beta.4",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -51,6 +51,16 @@
         "default": "./dist/lib/compliance/index.js"
       }
     },
+    "./adapters/version": {
+      "import": {
+        "types": "./dist/lib/adapters/version/index.d.mts",
+        "default": "./dist/lib/adapters/version/index.mjs"
+      },
+      "require": {
+        "types": "./dist/lib/adapters/version/index.d.ts",
+        "default": "./dist/lib/adapters/version/index.js"
+      }
+    },
     "./advanced": {
       "import": {
         "types": "./dist/lib/advanced.d.mts",
@@ -432,6 +442,9 @@
       "compliance": [
         "dist/lib/compliance/index.d.ts"
       ],
+      "adapters/version": [
+        "dist/lib/adapters/version/index.d.ts"
+      ],
       "advanced": [
         "dist/lib/advanced.d.ts"
       ],
@@ -732,7 +745,7 @@
   "dependencies": {
     "@modelcontextprotocol/client": "2.3.1",
     "@modelcontextprotocol/ext-apps": "2.0.0",
-    "@modelcontextprotocol/node": "2.0.0",
+    "@modelcontextprotocol/node": "2.1.1",
     "@modelcontextprotocol/server": "2.3.1",
     "@types/ws": "^8.18.1",
     "ajv": "^8.20.0",