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

package/dist/lib/adapters/version/index.d.mts

@@ -88,3 +88,12 @@ export declare function downgradeResponse<T>(toolName: string, data: T, options:
     data: T;
     drifts: import('./types.mjs').VersionDrift[];
 };
+/**
+ * Project a seller-owned webhook result with the same per-release conversion
+ * as framework responses. Pass the originating request's `ctx.servedAdcpVersion`;
+ * when the server uses another source release, pass it as `fromVersion`.
+ * Envelope construction, credential stripping and webhook signing remain the
+ * emitter's responsibility. The input is never mutated.
+ * Use `downgradeResponse` when translation diagnostics are also needed.
+ */
+export declare function projectResponseForRelease<T>(toolName: string, payload: T, servedAdcpVersion: string, fromVersion?: string): T;

package/dist/lib/adapters/version/index.d.ts

@@ -88,3 +88,12 @@ export declare function downgradeResponse<T>(toolName: string, data: T, options:
     data: T;
     drifts: import('./types').VersionDrift[];
 };
+/**
+ * Project a seller-owned webhook result with the same per-release conversion
+ * as framework responses. Pass the originating request's `ctx.servedAdcpVersion`;
+ * when the server uses another source release, pass it as `fromVersion`.
+ * Envelope construction, credential stripping and webhook signing remain the
+ * emitter's responsibility. The input is never mutated.
+ * Use `downgradeResponse` when translation diagnostics are also needed.
+ */
+export declare function projectResponseForRelease<T>(toolName: string, payload: T, servedAdcpVersion: string, fromVersion?: string): T;

package/dist/lib/adapters/version/index.js

@@ -18,16 +18,17 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var version_exports = {};
 __export(version_exports, {
-  adcpMinorLine: () => import_negotiate.adcpMinorLine,
-  compareAdcpMinorLines: () => import_negotiate.compareAdcpMinorLines,
+  adcpMinorLine: () => import_negotiate2.adcpMinorLine,
+  compareAdcpMinorLines: () => import_negotiate2.compareAdcpMinorLines,
   convertRequest: () => convertRequest,
   convertResponse: () => convertResponse,
   downgradeResponse: () => downgradeResponse,
   getVersionAdapter: () => getVersionAdapter,
-  isNegotiationFailure: () => import_negotiate.isNegotiationFailure,
+  isNegotiationFailure: () => import_negotiate2.isNegotiationFailure,
   listVersionAdapterTools: () => listVersionAdapterTools,
-  negotiateAdcpRelease: () => import_negotiate.negotiateAdcpRelease,
-  parseAdcpRelease: () => import_negotiate.parseAdcpRelease,
+  negotiateAdcpRelease: () => import_negotiate2.negotiateAdcpRelease,
+  parseAdcpRelease: () => import_negotiate2.parseAdcpRelease,
+  projectResponseForRelease: () => projectResponseForRelease,
   projectToolPayload: () => import_schema_projection.projectToolPayload,
   releaseDefinesTool: () => import_schema_projection.releaseDefinesTool,
   resolveAdapterKey: () => resolveAdapterKey,
@@ -36,12 +37,15 @@ __export(version_exports, {
 });
 module.exports = __toCommonJS(version_exports);
 var import_adcp_version_config = require('../../utils/adcp-version-config.js');
+var import_version = require('../../version.js');
+var import_negotiate = require('./negotiate.js');
+var import_schema_loader = require('../../validation/schema-loader.js');
 var import_idempotency = require('../../utils/idempotency.js');
 var import__ = require('./3.0/index.js');
 var import__2 = require('./3.1/index.js');
 var import_translate = require('./translate.js');
 var import_translate2 = require('./translate.js');
-var import_negotiate = require('./negotiate.js');
+var import_negotiate2 = require('./negotiate.js');
 var import_schema_projection = require('./schema-projection.js');
 const REGISTRY = /* @__PURE__ */ new Map();
 function register(version, adapters) {
@@ -77,6 +81,15 @@ function upgradeRequest(toolName, params, options) {
 function downgradeResponse(toolName, data, options) {
   return (0, import_translate.convertResponseToRelease)(toolName, data, { ...options, adapters: getVersionAdapter });
 }
+function projectResponseForRelease(toolName, payload, servedAdcpVersion, fromVersion = import_version.ADCP_VERSION) {
+  const source = typeof fromVersion === "string" ? (0, import_negotiate.parseAdcpRelease)(fromVersion) : void 0;
+  const target = typeof servedAdcpVersion === "string" ? (0, import_negotiate.parseAdcpRelease)(servedAdcpVersion) : void 0;
+  if (!source || !target || source.major !== 3 || target.major !== 3 || target.minor > source.minor || source.minor === target.minor && source.prerelease !== target.prerelease || !(0, import_schema_loader.hasSchemaBundle)(fromVersion) || !(0, import_schema_loader.hasSchemaBundle)(servedAdcpVersion))
+    throw new TypeError(
+      "projectResponseForRelease requires valid AdCP 3 schema bundles, with the served minor line on or below the source and matching same-line previews"
+    );
+  return downgradeResponse(toolName, payload, { fromVersion, toVersion: servedAdcpVersion }).data;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   adcpMinorLine,
@@ -89,6 +102,7 @@ function downgradeResponse(toolName, data, options) {
   listVersionAdapterTools,
   negotiateAdcpRelease,
   parseAdcpRelease,
+  projectResponseForRelease,
   projectToolPayload,
   releaseDefinesTool,
   resolveAdapterKey,

package/dist/lib/adapters/version/index.mjs

@@ -1,4 +1,7 @@
 import { shouldOmit31Fields } from "../../utils/adcp-version-config.mjs";
+import { ADCP_VERSION } from "../../version.mjs";
+import { parseAdcpRelease } from "./negotiate.mjs";
+import { hasSchemaBundle } from "../../validation/schema-loader.mjs";
 import { isMutatingTask } from "../../utils/idempotency.mjs";
 import { v30Adapters } from "./3.0/index.mjs";
 import { v31Adapters } from "./3.1/index.mjs";
@@ -12,7 +15,7 @@ import { translationSteps } from "./translate.mjs";
 import {
   negotiateAdcpRelease,
   isNegotiationFailure,
-  parseAdcpRelease,
+  parseAdcpRelease as parseAdcpRelease2,
   adcpMinorLine,
   compareAdcpMinorLines
 } from "./negotiate.mjs";
@@ -51,6 +54,15 @@ function upgradeRequest(toolName, params, options) {
 function downgradeResponse(toolName, data, options) {
   return convertResponseToRelease(toolName, data, { ...options, adapters: getVersionAdapter });
 }
+function projectResponseForRelease(toolName, payload, servedAdcpVersion, fromVersion = ADCP_VERSION) {
+  const source = typeof fromVersion === "string" ? parseAdcpRelease(fromVersion) : void 0;
+  const target = typeof servedAdcpVersion === "string" ? parseAdcpRelease(servedAdcpVersion) : void 0;
+  if (!source || !target || source.major !== 3 || target.major !== 3 || target.minor > source.minor || source.minor === target.minor && source.prerelease !== target.prerelease || !hasSchemaBundle(fromVersion) || !hasSchemaBundle(servedAdcpVersion))
+    throw new TypeError(
+      "projectResponseForRelease requires valid AdCP 3 schema bundles, with the served minor line on or below the source and matching same-line previews"
+    );
+  return downgradeResponse(toolName, payload, { fromVersion, toVersion: servedAdcpVersion }).data;
+}
 export {
   adcpMinorLine,
   compareAdcpMinorLines,
@@ -61,7 +73,8 @@ export {
   isNegotiationFailure,
   listVersionAdapterTools,
   negotiateAdcpRelease,
-  parseAdcpRelease,
+  parseAdcpRelease2 as parseAdcpRelease,
+  projectResponseForRelease,
   projectToolPayload,
   releaseDefinesTool,
   resolveAdapterKey,

package/dist/lib/identity-3.3/trust.js

@@ -100,6 +100,13 @@ function failure(cause) {
   if (cause !== void 0) Object.defineProperty(error, "cause", { value: cause });
   throw error;
 }
+function claimRegistrableDomain(domain) {
+  try {
+    return (0, import_etld.eTldPlusOne)(domain);
+  } catch (cause) {
+    return failure(cause);
+  }
+}
 function validateTrustRecord(value) {
   if (!validateIdentity33Schema("trust/v1/trust", value)) failure();
   const record = value;
@@ -361,7 +368,7 @@ async function authorizeDemandGrant(claim, options) {
   const now = (options.now ?? (() => Date.now() / 1e3))();
   const signer = await options.evaluator.match(claim.signerOrigin, "adcp:buying", claim.brand.countries);
   if (signer.agent.countries && !claim.brand.countries?.length) failure();
-  const brand = (0, import_etld.eTldPlusOne)(claim.brand.domain), account = (0, import_etld.eTldPlusOne)(claim.accountOperator), operator = signer.operator;
+  const brand = claimRegistrableDomain(claim.brand.domain), account = claimRegistrableDomain(claim.accountOperator), operator = signer.operator;
   const result = (source, chain, grants = []) => ({
     source,
     chain,
@@ -378,7 +385,7 @@ async function authorizeDemandGrant(claim, options) {
       throw cause;
     unavailable(cause);
   }
-  const authoritativeBrand = house ? (0, import_etld.eTldPlusOne)(house.domain) : brand;
+  const authoritativeBrand = house ? claimRegistrableDomain(house.domain) : brand;
   const self = /* @__PURE__ */ new Set([brand, authoritativeBrand]);
   if (self.has(account) && self.has(operator)) return result("implicit", [.../* @__PURE__ */ new Set([brand, account, operator])]);
   const grantClaim = house ? { ...claim, brand: { ...claim.brand, brand_id: house.brand_id } } : claim;

package/dist/lib/identity-3.3/trust.mjs

@@ -59,6 +59,13 @@ function failure(cause) {
   if (cause !== void 0) Object.defineProperty(error, "cause", { value: cause });
   throw error;
 }
+function claimRegistrableDomain(domain) {
+  try {
+    return eTldPlusOne(domain);
+  } catch (cause) {
+    return failure(cause);
+  }
+}
 function validateTrustRecord(value) {
   if (!validateIdentity33Schema("trust/v1/trust", value)) failure();
   const record = value;
@@ -320,7 +327,7 @@ async function authorizeDemandGrant(claim, options) {
   const now = (options.now ?? (() => Date.now() / 1e3))();
   const signer = await options.evaluator.match(claim.signerOrigin, "adcp:buying", claim.brand.countries);
   if (signer.agent.countries && !claim.brand.countries?.length) failure();
-  const brand = eTldPlusOne(claim.brand.domain), account = eTldPlusOne(claim.accountOperator), operator = signer.operator;
+  const brand = claimRegistrableDomain(claim.brand.domain), account = claimRegistrableDomain(claim.accountOperator), operator = signer.operator;
   const result = (source, chain, grants = []) => ({
     source,
     chain,
@@ -337,7 +344,7 @@ async function authorizeDemandGrant(claim, options) {
       throw cause;
     unavailable(cause);
   }
-  const authoritativeBrand = house ? eTldPlusOne(house.domain) : brand;
+  const authoritativeBrand = house ? claimRegistrableDomain(house.domain) : brand;
   const self = /* @__PURE__ */ new Set([brand, authoritativeBrand]);
   if (self.has(account) && self.has(operator)) return result("implicit", [.../* @__PURE__ */ new Set([brand, account, operator])]);
   const grantClaim = house ? { ...claim, brand: { ...claim.brand, brand_id: house.brand_id } } : claim;

package/dist/lib/server/a2a-adapter.js

@@ -32,6 +32,7 @@ var import_operation_resolution = require('../signing/operation-resolution.js');
 var import_adcp_server = require('./adcp-server.js');
 var import_create_adcp_server = require('./create-adcp-server.js');
 var import_auth = require('./auth.js');
+var import_signed_request_transport = require('./signed-request-transport.js');
 class RedactingA2ATaskStore {
   constructor(delegate) {
     this.delegate = delegate;
@@ -625,7 +626,7 @@ function captureRawBody(req, _res, buf) {
 }
 function resolveSignatureGate(options) {
   const symbols = options.server;
-  const attached = symbols[import_create_adcp_server.ADCP_PRE_TRANSPORT];
+  const attached = (0, import_signed_request_transport.getSignedRequestPreTransport)(options.server) ?? symbols[import_create_adcp_server.ADCP_PRE_TRANSPORT];
   const gate = options.preTransport ?? (typeof attached === "function" ? attached : void 0);
   if (gate) return gate;
   const state = symbols[import_create_adcp_server.ADCP_SIGNED_REQUESTS_STATE];

package/dist/lib/server/a2a-adapter.mjs

@@ -25,6 +25,7 @@ import {
   ADCP_SIGNED_REQUESTS_STATE
 } from "./create-adcp-server.mjs";
 import { ADCP_SERVE_REQUEST_CONTEXT } from "./auth.mjs";
+import { getSignedRequestPreTransport } from "./signed-request-transport.mjs";
 class RedactingA2ATaskStore {
   constructor(delegate) {
     this.delegate = delegate;
@@ -618,7 +619,7 @@ function captureRawBody(req, _res, buf) {
 }
 function resolveSignatureGate(options) {
   const symbols = options.server;
-  const attached = symbols[ADCP_PRE_TRANSPORT];
+  const attached = getSignedRequestPreTransport(options.server) ?? symbols[ADCP_PRE_TRANSPORT];
   const gate = options.preTransport ?? (typeof attached === "function" ? attached : void 0);
   if (gate) return gate;
   const state = symbols[ADCP_SIGNED_REQUESTS_STATE];

package/dist/lib/server/auth-signature.d.mts

@@ -64,8 +64,8 @@ export interface VerifySignatureAsAuthenticatorOptions {
      *  requests fall through to the next authenticator — so set it to whatever
      *  your `request_signing` capability claim advertises. */
     capability: VerifierCapability;
-    /** Resolves verification keys by `keyid`. */
-    jwks: JwksResolver;
+    /** Resolves legacy RFC 9421 keys. May be omitted for a Web Bot Auth-only endpoint. */
+    jwks?: JwksResolver;
     /**
      * Stores `(keyid, signature-bytes, expires)` tuples for replay detection.
      * Defaults to a fresh {@link InMemoryReplayStore} — fine for single-process

package/dist/lib/server/auth-signature.d.ts

@@ -64,8 +64,8 @@ export interface VerifySignatureAsAuthenticatorOptions {
      *  requests fall through to the next authenticator — so set it to whatever
      *  your `request_signing` capability claim advertises. */
     capability: VerifierCapability;
-    /** Resolves verification keys by `keyid`. */
-    jwks: JwksResolver;
+    /** Resolves legacy RFC 9421 keys. May be omitted for a Web Bot Auth-only endpoint. */
+    jwks?: JwksResolver;
     /**
      * Stores `(keyid, signature-bytes, expires)` tuples for replay detection.
      * Defaults to a fresh {@link InMemoryReplayStore} — fine for single-process

package/dist/lib/server/auth-signature.js

@@ -36,6 +36,8 @@ var import_verifier = require('../signing/verifier.js');
 var import_buyer_agent = require('./decisioning/buyer-agent.js');
 var import_auth = require('./auth.js');
 function verifySignatureAsAuthenticator(options) {
+  if (!options.jwks && !options.webBotAuth)
+    throw new TypeError("verifySignatureAsAuthenticator requires jwks or webBotAuth");
   const replayStore = options.replayStore ?? new import_replay.InMemoryReplayStore();
   const legacyOriginGate = options.assertLegacyOriginAllowed ?? (0, import_web_bot_auth.getWebBotAuthLegacyOriginGate)(options.webBotAuth?.resolvePrincipal);
   if (options.webBotAuth && !legacyOriginGate)
@@ -102,6 +104,7 @@ function verifySignatureAsAuthenticator(options) {
           }
         };
       }
+      if (!options.jwks) throw new import_web_bot_auth2.WebBotAuthError(403, "profile_disabled");
       result = await (0, import_verifier.verifyRequestSignature)(requestLike, {
         capability: options.capability,
         jwks: options.jwks,

package/dist/lib/server/auth-signature.mjs

@@ -36,6 +36,8 @@ import {
   tagAuthenticatorPresenceGated
 } from "./auth.mjs";
 function verifySignatureAsAuthenticator(options) {
+  if (!options.jwks && !options.webBotAuth)
+    throw new TypeError("verifySignatureAsAuthenticator requires jwks or webBotAuth");
   const replayStore = options.replayStore ?? new InMemoryReplayStore();
   const legacyOriginGate = options.assertLegacyOriginAllowed ?? getWebBotAuthLegacyOriginGate(options.webBotAuth?.resolvePrincipal);
   if (options.webBotAuth && !legacyOriginGate)
@@ -102,6 +104,7 @@ function verifySignatureAsAuthenticator(options) {
           }
         };
       }
+      if (!options.jwks) throw new WebBotAuthError(403, "profile_disabled");
       result = await verifyRequestSignature(requestLike, {
         capability: options.capability,
         jwks: options.jwks,

package/dist/lib/server/create-adcp-server.d.mts

@@ -946,8 +946,8 @@ export interface AdcpCapabilitiesOverrides {
 export interface SignedRequestsConfig {
     webBotAuth?: import('./auth-signature.mjs').VerifySignatureAsAuthenticatorOptions['webBotAuth'];
     assertLegacyOriginAllowed?: (agentUrl: string) => Promise<void>;
-    /** Resolves verification keys by `keyid`. */
-    jwks: JwksResolver;
+    /** Resolves legacy RFC 9421 keys. May be omitted for a Web Bot Auth-only endpoint. */
+    jwks?: JwksResolver;
     /** Stores `(keyid, signature-bytes, expires)` tuples for replay detection. */
     replayStore: ReplayStore;
     /** Consulted for revoked `kid` / `jti` before accepting a signature. */

package/dist/lib/server/create-adcp-server.d.ts

@@ -946,8 +946,8 @@ export interface AdcpCapabilitiesOverrides {
 export interface SignedRequestsConfig {
     webBotAuth?: import('./auth-signature').VerifySignatureAsAuthenticatorOptions['webBotAuth'];
     assertLegacyOriginAllowed?: (agentUrl: string) => Promise<void>;
-    /** Resolves verification keys by `keyid`. */
-    jwks: JwksResolver;
+    /** Resolves legacy RFC 9421 keys. May be omitted for a Web Bot Auth-only endpoint. */
+    jwks?: JwksResolver;
     /** Stores `(keyid, signature-bytes, expires)` tuples for replay detection. */
     replayStore: ReplayStore;
     /** Consulted for revoked `kid` / `jti` before accepting a signature. */

package/dist/lib/server/create-adcp-server.js

@@ -81,6 +81,7 @@ var import_middleware = require('../signing/middleware.js');
 var import_operation_resolution = require('../signing/operation-resolution.js');
 var import_account_mode = require('./account-mode.js');
 var import_test_controller_bridge = require('./test-controller-bridge.js');
+var import_signed_request_transport = require('./signed-request-transport.js');
 var import_version3 = require('../version.js');
 var import_schemas2 = require('../types/schemas.generated.js');
 var import_error_codes = require('../types/error-codes.js');
@@ -1466,6 +1467,8 @@ function resolveEffectiveSignedRequestPolicy(signedRequests, capabilityRequestSi
   };
 }
 function buildSignedRequestsPreTransport(signedRequests, effectiveRequestSigning, adcpVersion) {
+  if (!signedRequests.jwks && !signedRequests.webBotAuth)
+    throw new TypeError("signedRequests requires jwks or webBotAuth");
   const legacyOriginGate = signedRequests.assertLegacyOriginAllowed ?? (0, import_web_bot_auth.getWebBotAuthLegacyOriginGate)(signedRequests.webBotAuth?.resolvePrincipal);
   if (signedRequests.webBotAuth && !legacyOriginGate)
     throw new Error(
@@ -1485,7 +1488,7 @@ function buildSignedRequestsPreTransport(signedRequests, effectiveRequestSigning
       required_for: requiredFor,
       ...effectiveRequestSigning.protocol_methods_required_for ? { protocol_methods_required_for: effectiveRequestSigning.protocol_methods_required_for } : {}
     },
-    jwks: signedRequests.jwks,
+    jwks: signedRequests.jwks ?? { resolve: async () => null },
     replayStore: signedRequests.replayStore,
     revocationStore: signedRequests.revocationStore,
     adcpVersion,
@@ -1558,6 +1561,12 @@ function buildSignedRequestsPreTransport(signedRequests, effectiveRequestSigning
         return true;
       }
     }
+    if (!signedRequests.jwks && (req.headers["signature"] !== void 0 || req.headers["signature-input"] !== void 0)) {
+      const refused = new import_web_bot_auth2.WebBotAuthError(403, "profile_disabled");
+      res.writeHead(refused.status, { ...refused.headers, "Content-Type": "application/json" });
+      res.end(JSON.stringify(refused.body));
+      return true;
+    }
     const reqShim = {
       method: req.method ?? "POST",
       url: req.url ?? "/mcp",
@@ -5121,12 +5130,25 @@ function createAdcpServer(config) {
   (0, import_adcp_server.setMcpAppResources)(wrapped, mcpAppResources);
   if (signedRequests) {
     const preTransport = buildSignedRequestsPreTransport(signedRequests, enforcedRequestSigningPolicy, adcpVersion);
+    const transportPermitted = (0, import_signed_request_transport.registerSignedRequestTransportGuard)(wrapped, preTransport);
+    let preTransportConsumed = false;
     Object.defineProperty(wrapped, ADCP_PRE_TRANSPORT, {
-      value: preTransport,
+      get() {
+        preTransportConsumed = true;
+        return preTransport;
+      },
       enumerable: false,
-      writable: false,
       configurable: true
     });
+    const connect = wrapped.connect.bind(wrapped);
+    wrapped.connect = async (transport) => {
+      if (!preTransportConsumed && !transportPermitted(transport)) {
+        throw new Error(
+          "signedRequests verifier is not mounted: direct server.connect(transport) does not run HTTP middleware. Use serve(), createA2AAdapter(), or mount server[ADCP_PRE_TRANSPORT] before handling requests. For custom authentication, compose verifySignatureAsAuthenticator({ webBotAuth }) and capture rawBody."
+        );
+      }
+      return connect(transport);
+    };
   }
   const signedRequestsState = {
     autoWired: Boolean(signedRequests),

package/dist/lib/server/create-adcp-server.mjs

@@ -183,6 +183,7 @@ import {
   filterValidSeededRights,
   filterValidSeededSiOffering
 } from "./test-controller-bridge.mjs";
+import { registerSignedRequestTransportGuard } from "./signed-request-transport.mjs";
 import { ADCP_VERSION, LIBRARY_VERSION } from "../version.mjs";
 import { AccountReferenceSchema } from "../types/schemas.generated.mjs";
 import {
@@ -1568,6 +1569,8 @@ function resolveEffectiveSignedRequestPolicy(signedRequests, capabilityRequestSi
   };
 }
 function buildSignedRequestsPreTransport(signedRequests, effectiveRequestSigning, adcpVersion) {
+  if (!signedRequests.jwks && !signedRequests.webBotAuth)
+    throw new TypeError("signedRequests requires jwks or webBotAuth");
   const legacyOriginGate = signedRequests.assertLegacyOriginAllowed ?? getWebBotAuthLegacyOriginGate(signedRequests.webBotAuth?.resolvePrincipal);
   if (signedRequests.webBotAuth && !legacyOriginGate)
     throw new Error(
@@ -1587,7 +1590,7 @@ function buildSignedRequestsPreTransport(signedRequests, effectiveRequestSigning
       required_for: requiredFor,
       ...effectiveRequestSigning.protocol_methods_required_for ? { protocol_methods_required_for: effectiveRequestSigning.protocol_methods_required_for } : {}
     },
-    jwks: signedRequests.jwks,
+    jwks: signedRequests.jwks ?? { resolve: async () => null },
     replayStore: signedRequests.replayStore,
     revocationStore: signedRequests.revocationStore,
     adcpVersion,
@@ -1660,6 +1663,12 @@ function buildSignedRequestsPreTransport(signedRequests, effectiveRequestSigning
         return true;
       }
     }
+    if (!signedRequests.jwks && (req.headers["signature"] !== void 0 || req.headers["signature-input"] !== void 0)) {
+      const refused = new WebBotAuthError(403, "profile_disabled");
+      res.writeHead(refused.status, { ...refused.headers, "Content-Type": "application/json" });
+      res.end(JSON.stringify(refused.body));
+      return true;
+    }
     const reqShim = {
       method: req.method ?? "POST",
       url: req.url ?? "/mcp",
@@ -5223,12 +5232,25 @@ function createAdcpServer(config) {
   setMcpAppResources(wrapped, mcpAppResources);
   if (signedRequests) {
     const preTransport = buildSignedRequestsPreTransport(signedRequests, enforcedRequestSigningPolicy, adcpVersion);
+    const transportPermitted = registerSignedRequestTransportGuard(wrapped, preTransport);
+    let preTransportConsumed = false;
     Object.defineProperty(wrapped, ADCP_PRE_TRANSPORT, {
-      value: preTransport,
+      get() {
+        preTransportConsumed = true;
+        return preTransport;
+      },
       enumerable: false,
-      writable: false,
       configurable: true
     });
+    const connect = wrapped.connect.bind(wrapped);
+    wrapped.connect = async (transport) => {
+      if (!preTransportConsumed && !transportPermitted(transport)) {
+        throw new Error(
+          "signedRequests verifier is not mounted: direct server.connect(transport) does not run HTTP middleware. Use serve(), createA2AAdapter(), or mount server[ADCP_PRE_TRANSPORT] before handling requests. For custom authentication, compose verifySignatureAsAuthenticator({ webBotAuth }) and capture rawBody."
+        );
+      }
+      return connect(transport);
+    };
   }
   const signedRequestsState = {
     autoWired: Boolean(signedRequests),

package/dist/lib/server/serve.js

@@ -36,6 +36,7 @@ var import_create_adcp_server = require('./create-adcp-server.js');
 var import_tasks = require('./tasks.js');
 var import_adcp_server = require('./adcp-server.js');
 var import_mcp_modern_server = require('./mcp-modern-server.js');
+var import_signed_request_transport = require('./signed-request-transport.js');
 class UnknownHostError extends Error {
   constructor(message = "Unknown host") {
     super(message);
@@ -407,7 +408,7 @@ function serve(createAgent, options) {
           return;
         }
       }
-      const attached = agentServer[import_create_adcp_server.ADCP_PRE_TRANSPORT];
+      const attached = (0, import_signed_request_transport.getSignedRequestPreTransport)(agentServer) ?? agentServer[import_create_adcp_server.ADCP_PRE_TRANSPORT];
       const autoWiredPreTransport = typeof attached === "function" ? attached : void 0;
       const activePreTransport = explicitPreTransport ?? autoWiredPreTransport;
       if (activePreTransport) {
@@ -487,6 +488,7 @@ function serve(createAgent, options) {
             const transport = new import_streamableHttp.StreamableHTTPServerTransport({
               sessionIdGenerator: void 0
             });
+            (0, import_signed_request_transport.permitSignedRequestTransport)(agentServer, transport);
             await agentServer.connect(transport);
             if (parsedBody !== void 0) {
               await transport.handleRequest(req, res, parsedBody);

package/dist/lib/server/serve.mjs

@@ -19,6 +19,7 @@ import {
 import { ADCP_TASK_MESSAGE_QUEUE } from "./tasks.mjs";
 import { getSdkServer, isAdcpServer } from "./adcp-server.mjs";
 import { createModernMcpServerAdapter } from "./mcp-modern-server.mjs";
+import { getSignedRequestPreTransport, permitSignedRequestTransport } from "./signed-request-transport.mjs";
 class UnknownHostError extends Error {
   constructor(message = "Unknown host") {
     super(message);
@@ -390,7 +391,7 @@ function serve(createAgent, options) {
           return;
         }
       }
-      const attached = agentServer[ADCP_PRE_TRANSPORT];
+      const attached = getSignedRequestPreTransport(agentServer) ?? agentServer[ADCP_PRE_TRANSPORT];
       const autoWiredPreTransport = typeof attached === "function" ? attached : void 0;
       const activePreTransport = explicitPreTransport ?? autoWiredPreTransport;
       if (activePreTransport) {
@@ -470,6 +471,7 @@ function serve(createAgent, options) {
             const transport = new StreamableHTTPServerTransport({
               sessionIdGenerator: void 0
             });
+            permitSignedRequestTransport(agentServer, transport);
             await agentServer.connect(transport);
             if (parsedBody !== void 0) {
               await transport.handleRequest(req, res, parsedBody);

package/dist/lib/server/signed-request-transport.d.mts

@@ -0,0 +1 @@
+export {};

package/dist/lib/server/signed-request-transport.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/server/signed-request-transport.js

@@ -0,0 +1,46 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var signed_request_transport_exports = {};
+__export(signed_request_transport_exports, {
+  getSignedRequestPreTransport: () => getSignedRequestPreTransport,
+  permitSignedRequestTransport: () => permitSignedRequestTransport,
+  registerSignedRequestTransportGuard: () => registerSignedRequestTransportGuard
+});
+module.exports = __toCommonJS(signed_request_transport_exports);
+const GUARD = /* @__PURE__ */ Symbol.for("@adcp/client.signedRequestTransportGuard");
+function guardFor(server) {
+  return server[GUARD];
+}
+function registerSignedRequestTransportGuard(server, preTransport) {
+  const entry = { preTransport, transports: /* @__PURE__ */ new WeakSet() };
+  Object.defineProperty(server, GUARD, { value: entry });
+  return (transport) => entry.transports.has(transport);
+}
+function getSignedRequestPreTransport(server) {
+  return guardFor(server)?.preTransport;
+}
+function permitSignedRequestTransport(server, transport) {
+  guardFor(server)?.transports.add(transport);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getSignedRequestPreTransport,
+  permitSignedRequestTransport,
+  registerSignedRequestTransportGuard
+});

package/dist/lib/server/signed-request-transport.mjs

@@ -0,0 +1,20 @@
+const GUARD = /* @__PURE__ */ Symbol.for("@adcp/client.signedRequestTransportGuard");
+function guardFor(server) {
+  return server[GUARD];
+}
+function registerSignedRequestTransportGuard(server, preTransport) {
+  const entry = { preTransport, transports: /* @__PURE__ */ new WeakSet() };
+  Object.defineProperty(server, GUARD, { value: entry });
+  return (transport) => entry.transports.has(transport);
+}
+function getSignedRequestPreTransport(server) {
+  return guardFor(server)?.preTransport;
+}
+function permitSignedRequestTransport(server, transport) {
+  guardFor(server)?.transports.add(transport);
+}
+export {
+  getSignedRequestPreTransport,
+  permitSignedRequestTransport,
+  registerSignedRequestTransportGuard
+};

package/dist/lib/server/test-controller.d.mts

@@ -367,6 +367,7 @@ export interface TestControllerStore {
     forceUpstreamUnavailable?(params: {
         tool: string;
         upstream_name?: string;
+        cache_age_seconds?: number;
     }): Promise<StateTransitionSuccess>;
 }
 /**

package/dist/lib/server/test-controller.d.ts

@@ -367,6 +367,7 @@ export interface TestControllerStore {
     forceUpstreamUnavailable?(params: {
         tool: string;
         upstream_name?: string;
+        cache_age_seconds?: number;
     }): Promise<StateTransitionSuccess>;
 }
 /**

package/dist/lib/server/test-controller.js

@@ -764,10 +764,14 @@ async function handleTestControllerRequestImpl(storeOrFactory, input, options) {
         if (typeof forceParams.tool !== "string" || forceParams.tool.length === 0) {
           return controllerError("INVALID_PARAMS", "force_upstream_unavailable requires params.tool");
         }
+        if (forceParams.cache_age_seconds !== void 0 && (!Number.isInteger(forceParams.cache_age_seconds) || forceParams.cache_age_seconds < 0)) {
+          return controllerError("INVALID_PARAMS", "cache_age_seconds must be a non-negative integer");
+        }
         return wrapStoreSuccess(
           await store.forceUpstreamUnavailable({
             tool: forceParams.tool,
-            upstream_name: typeof forceParams.upstream_name === "string" ? forceParams.upstream_name : void 0
+            upstream_name: typeof forceParams.upstream_name === "string" ? forceParams.upstream_name : void 0,
+            ...typeof forceParams.cache_age_seconds === "number" ? { cache_age_seconds: forceParams.cache_age_seconds } : {}
           })
         );
       }

package/dist/lib/server/test-controller.mjs

@@ -736,10 +736,14 @@ async function handleTestControllerRequestImpl(storeOrFactory, input, options) {
         if (typeof forceParams.tool !== "string" || forceParams.tool.length === 0) {
           return controllerError("INVALID_PARAMS", "force_upstream_unavailable requires params.tool");
         }
+        if (forceParams.cache_age_seconds !== void 0 && (!Number.isInteger(forceParams.cache_age_seconds) || forceParams.cache_age_seconds < 0)) {
+          return controllerError("INVALID_PARAMS", "cache_age_seconds must be a non-negative integer");
+        }
         return wrapStoreSuccess(
           await store.forceUpstreamUnavailable({
             tool: forceParams.tool,
-            upstream_name: typeof forceParams.upstream_name === "string" ? forceParams.upstream_name : void 0
+            upstream_name: typeof forceParams.upstream_name === "string" ? forceParams.upstream_name : void 0,
+            ...typeof forceParams.cache_age_seconds === "number" ? { cache_age_seconds: forceParams.cache_age_seconds } : {}
           })
         );
       }

package/dist/lib/testing/index.d.mts

@@ -23,3 +23,4 @@ export { COLLECTION_DIAGNOSTIC_LIMIT, COLLECTION_PAIR_LIMIT, COLLECTION_TARGETIN
 export type { CollectionNormalizationCode, CollectionNormalizationFailure, CollectionNormalizationResult, CrossPublisherCollectionRelation, CollectionPair, CollectionSelectionEvaluation, CollectionSelectionSelector, CollectionSelectionWitness, CollectionSelectorObject, CollectionWitnessKind, CollectionWitnessReadResult, FixtureContextOutput, NormalizedCollectionSelectors, PreparedFixtureBinding, PreparedFixtureSelection, PreparedFixturesAuthorizer, PreparedFixturesDecision, PreparedFixturesDisposition, PreparedFixturesLookup, PreparedFixturesPreparationLookup, PreparedFixturesPreparationAuthorizer, PreparedFixturesRefusal, PreparedFixturesRefusalCode, PreparedFixturesReference, PreparedSchemaArtifact, ProtectedContextViolationCode, ResolvedCollectionSelectionSelector, } from './storyboard/index.mjs';
 export { resolveCreativeBuildProbe, validateCreativeBuildProbeSpec } from './storyboard/index.mjs';
 export type { CreativeBuildProbeSpec, CreativeBuildProbeInputFixture, CreativeBuildProbeResolution, } from './storyboard/index.mjs';
+export { createStoryboardWebBotAuthFetch } from './storyboard/web-bot-auth.mjs';