@adcp/sdk 14.4.0 → 15.2.0

package/docs/guides/WEB-OAUTH.md

@@ -1,75 +1,41 @@
-# Web (server-side) OAuth flow
+# Web OAuth
 
-`@adcp/sdk` provides three OAuth flow shapes:
+Web routes span processes; `CLIFlowHandler` is single-process localhost:8766,
+`NonInteractiveFlowHandler` is refresh-only. Web flows are not provider handlers. [Issuer binding](OAUTH-ISSUER-BINDING.md) covers recovery/storage migration.
 
-| Helper                                       | Shape                | When to use                                                                  |
-| -------------------------------------------- | -------------------- | ---------------------------------------------------------------------------- |
-| `CLIFlowHandler`                             | class (`OAuthFlowHandler`) | Single-process loopback (`localhost:8766`) — CLIs and dev tools.       |
-| `NonInteractiveFlowHandler`                  | class (`OAuthFlowHandler`) | Refresh-only contexts — storyboard runs, scheduled jobs, cron.         |
-| `startWebOAuthFlow` / `completeWebOAuthFlow` | standalone functions | **Web servers** where `/oauth/start` and `/oauth/callback` may hit different processes. |
+## Discovery
 
-The web flow is **not** a class implementing `OAuthFlowHandler` — its
-contract spans two HTTP requests and (typically) two processes, which the
-flow-handler interface cannot model. Pass it to your router, not to
-`MCPOAuthProvider`.
+- PRM: `/.well-known/oauth-protected-resource{path}`, first AS. Only 404 absence
+  (RFC 9728 §3) allows agent-origin fallback; network/parse/other HTTP failures
+  raise `ProtectedResourceMetadataError`.
+- Resource: `resourceOverride` > validated `prm.resource` >
+  `resourceUrlFromServerUrl(agent.agent_uri)`. Present PRM is authoritative;
+  its resource origin must match the agent unless explicitly/persistently overridden. Forward
+  resource through authorization, exchange and refresh.
+- Scope: `scopeHint` > `prm.scopes_supported` > `clientMetadata.scope`.
+- DCR requires no client and an advertised `registration_endpoint`. Confidential
+  DCR responses require `allowConfidentialClient: true` and safe secret storage;
+  otherwise use pre-registered clients. Official MCP handles PKCE/exchange;
+  subsequent agent calls refresh.
 
-## What the SDK handles
-
-1. PRM (`/.well-known/oauth-protected-resource{path}`) discovery.
-2. AS resolution: `prm.authorization_servers[0]` falling back to the agent
-   origin when PRM is genuinely absent (404 — RFC 9728 §3 marks the
-   metadata document as optional). Connection / parse / 5xx errors are
-   surfaced as `ProtectedResourceMetadataError`; we do **not** silently
-   downgrade to local guessing on a transient failure.
-3. Resource indicator: caller `resourceOverride` > `prm.resource` (validated
-   against the agent origin when no trusted override is supplied) >
-   `resourceUrlFromServerUrl(agent.agent_uri)`. Never guessed locally
-   when PRM is present. An explicit override is forwarded during authorization,
-   code exchange, and later refreshes.
-4. Scope: caller `scopeHint` > `prm.scopes_supported` > `clientMetadata.scope`.
-5. Dynamic client registration when the agent has no `oauth_client` and
-   the AS advertises `registration_endpoint`. By default we **reject**
-   registrations that return `client_secret` (i.e. confidential clients);
-   pass `allowConfidentialClient: true` if you intend to persist a
-   long-lived AS credential to your agent storage.
-6. PKCE generation, authorization URL construction, and token exchange via
-   the MCP SDK's `client/auth.js` primitives. Refresh runs through
-   `MCPOAuthProvider` on the next agent call and forwards `resource`
-   automatically.
-
-## Express integration
+## Application routes
 
 ```ts
-import {
-  startWebOAuthFlow,
-  completeWebOAuthFlow,
-  safeReturnTo,
-  type PendingWebFlowStore,
-} from '@adcp/sdk';
+import { startWebOAuthFlow, completeWebOAuthFlow, safeReturnTo } from '@adcp/sdk/auth';
 
-// Generate a session-bound state cookie at /start, verify at /callback.
-// Without this, the state we store in the pending row is replay-protected
-// but not browser-bound — anyone with the link can finish your flow.
 const STATE_COOKIE = 'adcp_oauth_state';
-
 router.get('/oauth/start', async (req, res) => {
-  const agent = await loadAgent(String(req.query.agent_id)); // adopter's agent loader
+  const agent = await loadAgent(String(req.query.agent_id));
   const { authorizationUrl, state } = await startWebOAuthFlow({
     agent,
     redirectUri: `${baseUrl}/oauth/callback`,
-    pendingFlowStore: pgPendingFlowStore, // your PendingWebFlowStore
-    agentStorage: pgAgentStorage, // your OAuthConfigStorage (optional)
+    pendingFlowStore: pgPendingFlowStore,
+    agentStorage: pgAgentStorage,
     carry: { user_id: req.user.id, return_to: req.query.return_to },
-    // Optional: forward the scope hint from a prior 401 challenge (SEP-835).
-    // scopeHint: req.query.scope,
-    // Optional operator escape hatch for legacy/non-conformant integrations:
-    // resourceOverride: agent.oauth_resource,
-    // audience: integration.oauthAudience, // Auth0 compatibility; /authorize only
   });
   res.cookie(STATE_COOKIE, state, { httpOnly: true, secure: true, sameSite: 'lax' });
   res.redirect(authorizationUrl);
 });
-
 router.get('/oauth/callback', async (req, res) => {
   try {
     const { carry } = await completeWebOAuthFlow({
@@ -77,119 +43,48 @@ router.get('/oauth/callback', async (req, res) => {
       code: String(req.query.code),
       pendingFlowStore: pgPendingFlowStore,
       agentStorage: pgAgentStorage,
-      // Browser-binding: the state we set on the cookie at /start MUST
-      // match the state the AS sends back to /callback.
       expectedState: req.cookies[STATE_COOKIE],
     });
     res.clearCookie(STATE_COOKIE);
-    // safeReturnTo defaults to path-only redirects; pass allowedReturnHosts
-    // if you need to support absolute URLs against an allowlist.
     res.redirect(safeReturnTo(carry?.return_to) ?? '/');
-  } catch (err) {
-    res.redirect(`/oauth-failed?reason=${encodeURIComponent(err.code ?? 'oauth_error')}`);
+  } catch {
+    res.redirect('/oauth-failed?reason=oauth_error');
   }
 });
 ```
 
-## What you bring
-
-- **`loadAgent(agentId)`** — your code; not provided by the SDK. The
-  `/start` route uses it to look up the `AgentConfig`. The `/callback`
-  route does not need it: `agentId` is round-tripped in the pending row,
-  and `completeWebOAuthFlow` will call `agentStorage.loadAgent(agentId)`
-  itself when persisting tokens.
-
-- **`pendingFlowStore`** — implements `PendingWebFlowStore`. Two methods:
-  `put(flow)` and `consume(state)`. `consume` MUST be a single atomic
-  operation; canonical implementations:
-
-  Postgres:
-
-  ```sql
-  -- put
-  INSERT INTO pending_oauth_flows (state, payload, expires_at)
-    VALUES ($1, $2::jsonb, $3);
-
-  -- consume (atomic — DELETE … RETURNING)
-  DELETE FROM pending_oauth_flows
-    WHERE state = $1 AND expires_at > now()
-    RETURNING payload;
-  ```
-
-  Redis:
-
-  ```
-  SET pending:flow:<state> <payload> EX 600 NX     # put
-  GETDEL pending:flow:<state>                      # consume
-  ```
-
-  A `SELECT` followed by a separate `DELETE` is a replay vulnerability and
-  DOES NOT satisfy this contract. The SDK ships a `PendingWebFlowStore`
-  contract test (`describe('PendingWebFlowStore contract …')` in
-  `test/lib/oauth-web-flow.test.js`) you can run against your store.
-
-- **`agentStorage`** (optional) — implements `OAuthConfigStorage` (the
-  same interface used by `MCPOAuthProvider`). Omit it if you'd rather
-  handle persistence yourself; `completeWebOAuthFlow` returns the issued
-  tokens and a `persisted: false` flag in that case.
-
-`InMemoryPendingFlowStore` ships for tests and single-instance dev. Do
-not use it in production — restarts lose every in-flight flow.
-
-## Errors
-
-- `InvalidOrExpiredFlowError` — `state` not present or past TTL. Treat as
-  user-recoverable: prompt to re-authorize.
-- `StateMismatchError` — caller passed `expectedState` and it didn't
-  match the AS-supplied `state`. Almost always CSRF or a stale cookie.
-- `BrowserBindingRequiredError` — `expectedState` was omitted. Browser callbacks
-  fail closed by default; only non-browser compatibility flows should set
-  `allowUnboundState: true`.
-- `TokenExchangeError` — AS rejected the code exchange. Carries
-  `oauthErrorCode` (`invalid_grant`, `invalid_client`, …), `status`, and
-  a redacted `body` for diagnostics. Treat `body` as sensitive — do not
-  reflect it to the browser or write it to access logs unredacted.
-- `ProtectedResourceMetadataError` — PRM fetch failed (network / parse /
-  non-404 HTTP) or PRM advertised a `resource` whose origin does not
-  match the agent. Either is a configuration bug worth surfacing.
-- `AgentVanishedDuringFlowError` — `agentStorage.loadAgent(agentId)`
-  returned undefined after a successful token exchange. The user's auth
-  succeeded but you have no agent to attach it to; usually an
-  inter-process delete race.
-- `AgentChangedDuringFlowError` — the agent URI or OAuth resource configuration
-  changed while authorization was pending. Reload the current agent
-  configuration and restart authorization; the SDK does not persist tokens
-  against a stale or replacement agent record.
-- `ConfidentialClientNotAllowedError` — DCR returned a `client_secret`
-  and you did not opt into `allowConfidentialClient: true`. Either flip
-  the flag (and store the secret carefully) or pre-register a public
-  client and put the result in `agent.oauth_client`.
-- `OAuthError` — generic catch-all; check `err.code` for the discriminator.
-
-## Operational notes
-
-- **TTL.** Defaults to `DEFAULT_WEB_FLOW_TTL_MS` (10 minutes). Lower if
-  you want a tighter recovery window; do not raise without a reason.
-- **PKCE verifier is a secret.** Encrypt it at rest if your store crosses
-  a trust boundary.
-- **Atomic consume is load-bearing.** Without it, a replayed callback
-  (e.g. user double-clicks the AS redirect) can mint two tokens and
-  burn the authorization code on the second attempt.
-- **CSRF.** `expectedState` binds the flow to the user's browser. The
-  SDK cannot do this for you because it can't see your session
-  middleware — you stash `state` in a cookie at `/start` and pass it
-  back in at `/callback`. Omission throws by default.
-- **`carry` is attacker-influenced.** It's whatever the caller of
-  `/oauth/start` put in the request. Always validate before reflecting
-  (use `safeReturnTo` for redirect targets).
-- **Refresh is not this module's job.** Once `oauth_tokens` are
-  persisted, `MCPOAuthProvider` handles refresh on the next agent call
-  and forwards `resource` into the refresh request automatically. An explicit
-  `resourceOverride` is persisted as `agent.oauth_resource` when `agentStorage`
-  is supplied so the automatic refresh path retains it.
-  Callers who DIY refresh against `oauth_tokens` are responsible for
-  forwarding `resource` themselves.
-- **Removing an override.** Pass `resourceOverride: null` to explicitly use
-  PRM/agent-URL discovery and clear the persisted `agent.oauth_resource` after
-  successful authorization. Omitting `resourceOverride` preserves and reuses
-  an existing persisted override.
+`loadAgent` must authorize the session user for `agent_id`. Bind browser state
+using the start cookie and callback
+`expectedState`: state alone prevents replay, not CSRF; missing binding refuses.
+`allowUnboundState: true` is for deliberate non-browser compatibility. Validate
+attacker-controlled `carry`; `safeReturnTo` is path-only unless `allowedReturnHosts`
+allowlists absolute URLs.
+
+Start accepts prior-401 `scopeHint` (SEP-835), `resourceOverride`, and authorization-only
+Auth0 `audience`. With storage, overrides persist/reuse on omission; successful
+`resourceOverride: null` clears them and returns to discovery. DIY refresh forwards resource.
+
+## Storage and errors
+
+`PendingWebFlowStore`: `put(flow)` and atomic `consume(state)`, e.g. PostgreSQL
+`DELETE ... WHERE state = $1 AND expires_at > now() RETURNING payload`, or Redis
+`SET pending:flow:<state> <payload> EX 600 NX` then `GETDEL`. SELECT/DELETE races
+permit replay. Store contract tests: `test/lib/oauth-web-flow.test.js`.
+`DEFAULT_WEB_FLOW_TTL_MS` is 10 minutes; shorten as needed. `InMemoryPendingFlowStore` is
+test/dev-only; restarts lose flows. Encrypt PKCE verifiers at rest across trust boundaries.
+
+Optional `agentStorage` (`OAuthConfigStorage`): callback loads the pending row's
+agent ID. Without it, completion
+returns `persisted: false` for application persistence. Preserve the issuer guide's
+consistent client-bearing view and partial-save contract.
+
+- `InvalidOrExpiredFlowError`: restart sign-in.
+- `StateMismatchError`: cookie/state mismatch.
+- `BrowserBindingRequiredError`: missing `expectedState`.
+- `TokenExchangeError`: diagnostic `oauthErrorCode`, `status`, redacted `body`;
+  never reflect bodies to browsers/logs.
+- `ProtectedResourceMetadataError`: PRM/resource failure.
+- `AgentVanishedDuringFlowError`: removal during registration/exchange.
+- `AgentChangedDuringFlowError`: URI/resource/client changed; reload and restart.
+- `ConfidentialClientNotAllowedError`: secret DCR without opt-in.
+- `OAuthError`: other controlled `code` values.

package/docs/guides/account-resolution.md

@@ -71,7 +71,7 @@ later occurrences log at debug level. Codes:
 `ADCP_LIST_ACCOUNTS_FILTER_RESOLVED`, and
 `ADCP_IMPLICIT_ACCOUNT_IDENTITY_MISMATCH`.
 
-**Strict mode becomes the default in the next major release.** Opt in now:
+**Strict mode remains an explicit opt-in in SDK 15.** Set `strictAccountReferences: true`:
 
 ```ts
 createAdcpServer({

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-06
-> Library: @adcp/sdk v14.4.0
+> Generated at: 2026-10-07
+> Library: @adcp/sdk v15.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

@@ -56,7 +56,7 @@ single client-credentials refresh attempt.
 |---|---|
 | 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). |
+| Strict seller account references | `strictAccountReferences` remains false by default in SDK 15; compatibility paths warn. Move reference authorization into `resolveAccount`, then set it to true to opt in. 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

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

@@ -1,6 +1,6 @@
-# SDK 14 release-bound upgrade worksheet
+# SDK release-bound upgrade worksheet
 
-This page joins the release facts that adopters need before changing a production pin. It is generated from package and version metadata with `npm run generate-release-worksheet`; migration decisions remain documented in [Migrating from 13.x to 14](./migration-13-to-14.md).
+This page joins the release facts that adopters need before changing a production pin. It is generated from package and version metadata with `npm run generate-release-worksheet`. Before upgrading to SDK 15, review the [OAuth migration](./migration-oauth-issuer-bindings.md) and [issuer-binding and storage contract](./guides/OAUTH-ISSUER-BINDING.md). The [13.x → 14 migration](./migration-13-to-14.md) remains historical guidance.
 
 ## Release represented by this checkout
 
@@ -11,18 +11,18 @@ below as the publication/deployment gate.
 
 | Fact | Value |
 | --- | --- |
-| Exact npm package | `@adcp/sdk@14.4.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@14.4.0 dist.integrity` |
+| Exact npm package | `@adcp/sdk@15.2.0` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@15.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` |
-| Canonical migration notes | [13.x → 14](./migration-13-to-14.md) |
+| Canonical migration notes | [SDK 15 OAuth](./migration-oauth-issuer-bindings.md), [issuer-binding and storage](./guides/OAUTH-ISSUER-BINDING.md); historical [13.x → 14](./migration-13-to-14.md) |
 
 Install exact production inputs rather than a moving range or dist-tag:
 
 ```bash
-npm install --save-exact '@adcp/sdk@14.4.0'
-npm view '@adcp/sdk@14.4.0' dist.integrity
+npm install --save-exact '@adcp/sdk@15.2.0'
+npm view '@adcp/sdk@15.2.0' dist.integrity
 ```
 
 ### Required and optional peers
@@ -32,6 +32,7 @@ Install the peer packages used by your application at versions satisfying these
 | Peer | Supported range | Installation |
 | --- | --- | --- |
 | `@a2a-js/sdk` | `^1.0.1` | Required |
+| `@google-cloud/storage` | `^7.22.0 || ^8.2.0` | Optional |
 | `@modelcontextprotocol/sdk` | `^1.31.0` | Required |
 | `@opentelemetry/api` | `^1.0.0` | Optional |
 | `redis` | `^4.6.0 || ^5.0.0 || ^6.0.0` | Optional |

package/docs/migration-buyer-agent-registry.md

@@ -311,7 +311,7 @@ import { verifySignatureAsAuthenticator } from '@adcp/sdk/server';
 const auth = verifySignatureAsAuthenticator({
   capability,
   jwks,
-  resolveOperation: mcpToolNameResolver,
+  resolveOperation: adcpOperationResolver,
   // CONFIGURE THIS: maps the verified keyid back to the agent_url it
   // belongs to. The verifier stamps `credential.agent_url` from this
   // lookup; without it, the http_sig credential is omitted (no

package/docs/migration-oauth-issuer-bindings.md

@@ -1,82 +1,17 @@
 # OAuth issuer bindings
 
-The corrective release after SDK 14.3.0 upgrades the official MCP client and
-server to 2.2.0 and requires the legacy `@modelcontextprotocol/sdk` peer at
-`^1.31.0`. These versions address
+SDK 14.4 upgrades MCP client/server/core to 2.2.0 and requires the legacy
+`@modelcontextprotocol/sdk` peer at `^1.31.0` to address
 [GHSA-6qxp-vccf-f47h](https://github.com/advisories/GHSA-6qxp-vccf-f47h).
-Installations pinned to legacy SDK 1.24–1.30 must upgrade that peer dependency.
-The legacy OAuth transport rejects vulnerable versions even if package-manager
-peer checks were bypassed. The Node.js requirement remains `^20.19.0 || >=22.12.0`.
-
-OAuth refresh tokens and client secrets belong to an authorization server.
-`AgentOAuthTokens` and `AgentOAuthClient` now preserve an optional `issuer`
-field through the SDK's conversions, providers, and file storage. Newly saved
-credentials receive their binding from the authorization flow. The provider
-persists discovery alongside the pending PKCE verifier and clears that temporary
-state after exchange; a callback uses the original authorization server even if
-resource discovery changes while the browser is away. Custom `OAuthConfigStorage`
-implementations must preserve `oauth_discovery_state` alongside `oauth_code_verifier`. Web flows
-validate the discovered server's metadata issuer before registration and
-token exchange; diagnostic refreshes validate it before sending credentials.
-The provider refuses a changed authorization server before replacing a trusted
-confidential registration or reusing a refresh token. Clear credentials explicitly
-if an independently verified server migration requires a fresh registration.
-
-File storage saves the OAuth fields as an authoritative snapshot: omitted tokens,
-client, verifier, or discovery state are deleted. Load the complete agent from
-storage before creating a provider; keep unrelated persisted fields as before.
-
-## Existing saved credentials
-
-`MCPOAuthProvider` refuses to reuse a saved refresh token or client secret
-without a valid issuer, with `oauth_issuer_required`. The web flow and
-diagnostic runner also refuse mismatched bindings. Access-token-only and
-public-client configurations do not require a new field. A saved unbound refresh
-token blocks every call through the provider, even while its access token is
-still valid; clear the saved credentials before reconnecting.
-
-For a saved CLI alias, run `adcp <alias> --clear-oauth`, then
-`adcp <alias> --oauth` to sign in again.
-
-For legacy saved credentials, clear `oauth_tokens` and any confidential
-`oauth_client` registration, then sign in again. Alternatively, an operator
-may add the authorization-server issuer established independently from
-trusted registration records. **Do not infer it from the current MCP server's
-discovery metadata**, an access token's unverified claims, or its resource URL.
-If the issuer is unknown, sign in again. Raw `issuer: null` is treated as absent for access-token-only and public-client
-configurations; secrets still require a valid string issuer.
-
-```ts
-agent.oauth_tokens = {
-  ...agent.oauth_tokens!,
-  issuer: 'https://auth.example.com', // independently verified token issuer
-};
-agent.oauth_client = {
-  ...agent.oauth_client!,
-  issuer: 'https://auth.example.com', // where this client was registered
-};
-```
-
-An issuer is an authorization-server URL, including its tenant path when one
-exists. A single trailing slash difference is tolerated for credential
-comparison; distinct tenant paths remain distinct. Stored pending web flows
-containing an unbound confidential client must be restarted.
-
-## Custom providers
-
-Preserve the complete `issuer` field passed to `saveTokens()` and
-`saveClientInformation()`, and return it from the corresponding getters. Add
-an independently verified issuer to pre-registered client information. The
-upstream bundled `ClientCredentialsProvider`, `PrivateKeyJwtProvider`,
-`StaticPrivateKeyJwtProvider`, and `CrossAppAccessProvider` also need
-`expectedIssuer` configured. These are adopter-owned provider settings; a
-dependency upgrade cannot reconstruct the ownership of older credentials.
-
-Calls made directly to the upstream `exchangeAuthorization()` and
-`refreshAuthorization()` helpers need their own credential-issuer checks.
-The SDK's web-flow and diagnosis helpers perform those checks. The SDK's
-client-credentials flow uses an explicitly configured token endpoint rather
-than selecting one from MCP server discovery.
-
-If affected credentials were sent to an untrusted authorization server,
-follow the upstream advisory's credential-rotation guidance.
+The transport rejects vulnerable legacy peers even if installation checks were bypassed.
+Node requirements remain `^20.19.0 || >=22.12.0`.
+
+SDK 15 changes direct providers to background by default (explicit
+interactive opt-in). Adapters built for 14.4's authoritative-absence contract
+must switch tokens, client, verifier and discovery to omission-preserves /
+own-undefined-clears.
+
+See [OAuth authorization-server binding](guides/OAUTH-ISSUER-BINDING.md) for
+required owner recovery, interactive opt-in, partial-storage semantics and
+web-flow migration. Rotate any credentials exposed to an untrusted server
+according to the advisory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "14.4.0",
+  "version": "15.2.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -409,6 +409,16 @@
         "types": "./dist/lib/media-buy/actions.d.ts",
         "default": "./dist/lib/media-buy/actions.js"
       }
+    },
+    "./reporting/gcs": {
+      "import": {
+        "types": "./dist/lib/reporting/gcs/index.d.mts",
+        "default": "./dist/lib/reporting/gcs/index.mjs"
+      },
+      "require": {
+        "types": "./dist/lib/reporting/gcs/index.d.ts",
+        "default": "./dist/lib/reporting/gcs/index.js"
+      }
     }
   },
   "typesVersions": {
@@ -529,6 +539,9 @@
       ],
       "media-buy/actions": [
         "dist/lib/media-buy/actions.d.ts"
+      ],
+      "reporting/gcs": [
+        "dist/lib/reporting/gcs/index.d.ts"
       ]
     }
   },
@@ -733,12 +746,16 @@
   },
   "peerDependencies": {
     "@a2a-js/sdk": "^1.0.1",
+    "@google-cloud/storage": "^7.22.0 || ^8.2.0",
     "@modelcontextprotocol/sdk": "^1.31.0",
     "@opentelemetry/api": "^1.0.0",
     "redis": "^4.6.0 || ^5.0.0 || ^6.0.0",
     "zod": "^4.1.5"
   },
   "peerDependenciesMeta": {
+    "@google-cloud/storage": {
+      "optional": true
+    },
     "@opentelemetry/api": {
       "optional": true
     },
@@ -753,6 +770,7 @@
     "@changesets/cli": "^3.0.3",
     "@commitlint/cli": "^20.5.3",
     "@commitlint/config-conventional": "^20.5.3",
+    "@google-cloud/storage": "^7.22.0",
     "@modelcontextprotocol/sdk": "^1.31.0",
     "@opentelemetry/api": "^1.9.1",
     "@types/express": "4.17.25",

package/skills/build-seller-agent/specialisms/signed-requests.md

@@ -25,6 +25,8 @@ The `WWW-Authenticate` header is the grading surface — return the right error
 
 **Auto-wiring via `createAdcpServerFromPlatform`.** Pass `signedRequests: { jwks, replayStore, revocationStore }` alongside your platform and add `'signed-requests'` to `capabilities.specialisms` — the framework builds the verifier preTransport for you and `serve()` auto-mounts it. `createAdcpServerFromPlatform` throws at startup when `signedRequests` is set without the specialism claim (buyers wouldn't sign), and logs a loud error in the other direction. Keep `request_signing` in capabilities separately — it's still how buyers discover your `required_for` policy.
 
+**A2A.** If you also mount `createA2AAdapter({ server })`, it runs the same verifier on the A2A JSON-RPC endpoint automatically, and `required_for` matches the `skill` of the Message's sole DataPart (`SendMessage`, `SendStreamingMessage`, `message/send`, `message/stream`), exactly as `params.name` does over MCP. A body that does not resolve to exactly one operation (several DataParts, a FilePart, duplicate or case-variant keys, a non-string `skill`, a batch) is rejected with `request_body_malformed` before any handler. Record the raw bytes if a body parser runs ahead of the adapter: `app.use(express.json({ verify: a2a.rawBodyVerify }))`. Since SDK 15.0.1 the adapter refuses to construct when the server advertises request signing and nothing verifies signatures on A2A; before that, A2A silently skipped `required_for` entirely (GHSA-frxv-c96c-4vqw), so upgrade if you serve A2A.
+
 ```typescript
 const platform = definePlatform({
   capabilities: {