@adcp/sdk 14.0.0-beta.19 → 14.0.0-beta.20

package/dist/lib/testing/storyboard/webhook-receiver.js

@@ -22,7 +22,9 @@ __export(webhook_receiver_exports, {
 });
 module.exports = __toCommonJS(webhook_receiver_exports);
 var import_node_http = require("node:http");
+var import_node_https = require("node:https");
 var import_node_crypto = require("node:crypto");
+var import_node_net = require("node:net");
 var import_schema_loader = require('../../validation/schema-loader.js');
 const MAX_BODY_BYTES = 1048576;
 const MAX_CHALLENGE_BODY_BYTES = 16384;
@@ -35,7 +37,7 @@ const MAX_CONNECTIONS = 64;
 const MAX_HEADERS_COUNT = 64;
 const STEP_PATH_RE = /^\/step\/([A-Za-z0-9_]+)\/([A-Za-z0-9_-]+)\/?$/;
 const SECRET_HEADER_PATTERN = /^(authorization|credentials?|token|api[_-]?key|x-api[_-]?key|x-auth[_-]?token|password|secret|client[_-]secret|refresh[_-]token|access[_-]token|bearer|session[_-]token|cookie|set[_-]cookie)$/i;
-function validateProxyUrl(raw) {
+function validateProxyUrl(raw, allowHttp) {
   if (/[\r\n\x00]/.test(raw)) {
     throw new Error("webhook_receiver.public_url must not contain CR/LF/NUL");
   }
@@ -48,10 +50,16 @@ function validateProxyUrl(raw) {
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
     throw new Error(`webhook_receiver.public_url must be http(s); got ${parsed.protocol}`);
   }
+  if (parsed.protocol === "http:" && !allowHttp) {
+    throw new Error("webhook_receiver.public_url must use https (set allowHttp only for controlled local development)");
+  }
   if (parsed.username || parsed.password) {
     throw new Error("webhook_receiver.public_url must not include userinfo");
   }
-  return raw.replace(/\/$/, "");
+  if (parsed.search || parsed.hash) {
+    throw new Error("webhook_receiver.public_url must not include a query string or fragment");
+  }
+  return raw.replace(/\/+$/, "");
 }
 function retryKeyString(k) {
   return `${k.step_id}::${k.operation_id}`;
@@ -62,13 +70,18 @@ async function createWebhookReceiver(options = {}) {
     throw new Error("webhook_receiver.mode=proxy_url requires `public_url`");
   }
   const host = options.host ?? "127.0.0.1";
-  if (mode === "loopback_mock" && (host === "0.0.0.0" || host === "::")) {
+  if (mode === "loopback_mock" && !isLoopbackHost(host)) {
     throw new Error(
       `webhook_receiver host ${host} is not permitted in loopback_mock mode. Use mode=proxy_url with an explicit public_url for publicly-reachable runs.`
     );
   }
   const port = options.port ?? 0;
-  const proxyBase = mode === "proxy_url" ? validateProxyUrl(options.public_url) : void 0;
+  const proxyBase = mode === "proxy_url" ? validateProxyUrl(options.public_url, options.allowHttp === true) : void 0;
+  if (options.tls && proxyBase && new URL(proxyBase).protocol !== "https:") {
+    throw new Error("webhook_receiver.public_url must use https when local TLS is configured");
+  }
+  const publicRouteSuffix = mode === "proxy_url" ? `/_adcp_receiver/${(0, import_node_crypto.randomUUID)()}` : "";
+  const routePrefix = proxyBase ? `${new URL(proxyBase).pathname.replace(/\/+$/, "")}${publicRouteSuffix}` : "";
   const captured = [];
   const challenges = [];
   const waiters = [];
@@ -77,9 +90,23 @@ async function createWebhookReceiver(options = {}) {
   const deliveryCounts = /* @__PURE__ */ new Map();
   const challengeCounts = /* @__PURE__ */ new Map();
   let closed = false;
-  const server = (0, import_node_http.createServer)(
-    (req, res) => handleRequest(req, res, { captured, challenges, waiters, retryPolicies, deliveryCounts, challengeCounts })
-  );
+  const requestListener = (req, res) => handleRequest(req, res, {
+    captured,
+    challenges,
+    waiters,
+    retryPolicies,
+    deliveryCounts,
+    challengeCounts,
+    routePrefix
+  });
+  const server = options.tls ? (0, import_node_https.createServer)(
+    {
+      cert: options.tls.cert,
+      key: options.tls.key,
+      ...options.tls.passphrase !== void 0 && { passphrase: options.tls.passphrase }
+    },
+    requestListener
+  ) : (0, import_node_http.createServer)(requestListener);
   server.headersTimeout = HEADERS_TIMEOUT_MS;
   server.requestTimeout = REQUEST_TIMEOUT_MS;
   server.keepAliveTimeout = KEEP_ALIVE_TIMEOUT_MS;
@@ -94,10 +121,11 @@ async function createWebhookReceiver(options = {}) {
     });
   });
   const bound = server.address();
-  const base_url = proxyBase ?? `http://${formatHost(bound.address)}:${bound.port}`;
+  const base_url = proxyBase ? `${proxyBase}${publicRouteSuffix}` : `${options.tls ? "https" : "http"}://${formatHost(bound.address)}:${bound.port}`;
   return {
     base_url,
     mode,
+    bind_host: host,
     all: () => captured.slice(),
     challenges: () => challenges.slice(),
     matching: (filter) => captured.filter((w) => matchesFilter(w, filter)),
@@ -116,19 +144,26 @@ async function createWebhookReceiver(options = {}) {
     }
   };
 }
+function isLoopbackHost(host) {
+  const normalized = host.toLowerCase();
+  if (normalized === "localhost") return true;
+  if ((0, import_node_net.isIP)(host) === 4) return /^127(?:\.\d{1,3}){3}$/.test(host);
+  if ((0, import_node_net.isIP)(host) === 6) return normalized === "::1" || /^(?:0:){7}1$/.test(normalized);
+  return false;
+}
 function handleRequest(req, res, state) {
   if (req.method !== "POST") {
     res.statusCode = 405;
     res.end();
     return;
   }
-  const pathParts = parseStepPath(req.url ?? "");
+  const pathParts = parseStepPath(req.url ?? "", state.routePrefix);
   if (!pathParts) {
     res.statusCode = 404;
     res.end();
     return;
   }
-  const { step_id, operation_id } = pathParts;
+  const { step_id, operation_id, logical_path } = pathParts;
   let size = 0;
   const chunks = [];
   let tooLarge = false;
@@ -181,7 +216,7 @@ function handleRequest(req, res, state) {
         operation_id,
         received_at: Date.now(),
         method: req.method ?? "POST",
-        path: req.url ?? "/",
+        path: logical_path,
         headers: redactHeaders(headers),
         raw_body: raw,
         body: parsedBody.body,
@@ -210,7 +245,7 @@ function handleRequest(req, res, state) {
       delivery_index: deliveryIndex,
       received_at: Date.now(),
       method: req.method ?? "POST",
-      path: req.url ?? "/",
+      path: logical_path,
       headers: redactHeaders(headers),
       raw_body: raw,
       ...parsedBody,
@@ -242,10 +277,15 @@ function requestPathname(reqUrl) {
   const q = reqUrl.indexOf("?");
   return q === -1 ? reqUrl : reqUrl.slice(0, q);
 }
-function parseStepPath(reqUrl) {
-  const match = STEP_PATH_RE.exec(requestPathname(reqUrl));
+function parseStepPath(reqUrl, routePrefix) {
+  const pathname = requestPathname(reqUrl);
+  if (routePrefix && !pathname.startsWith(`${routePrefix}/`)) return void 0;
+  const logicalPath = routePrefix ? pathname.slice(routePrefix.length) : pathname;
+  const match = STEP_PATH_RE.exec(logicalPath);
   if (!match) return void 0;
-  return { step_id: match[1], operation_id: match[2] };
+  const queryIndex = reqUrl.indexOf("?");
+  const query = queryIndex === -1 ? "" : reqUrl.slice(queryIndex);
+  return { step_id: match[1], operation_id: match[2], logical_path: `${logicalPath}${query}` };
 }
 function normalizeHeaders(raw) {
   const out = {};

package/dist/lib/testing/storyboard/webhook-receiver.mjs

@@ -1,5 +1,7 @@
 import { createServer } from "node:http";
+import { createServer as createHttpsServer } from "node:https";
 import { randomUUID } from "node:crypto";
+import { isIP } from "node:net";
 import { getSchemaValidatorByRef } from "../../validation/schema-loader.mjs";
 const MAX_BODY_BYTES = 1048576;
 const MAX_CHALLENGE_BODY_BYTES = 16384;
@@ -12,7 +14,7 @@ const MAX_CONNECTIONS = 64;
 const MAX_HEADERS_COUNT = 64;
 const STEP_PATH_RE = /^\/step\/([A-Za-z0-9_]+)\/([A-Za-z0-9_-]+)\/?$/;
 const SECRET_HEADER_PATTERN = /^(authorization|credentials?|token|api[_-]?key|x-api[_-]?key|x-auth[_-]?token|password|secret|client[_-]secret|refresh[_-]token|access[_-]token|bearer|session[_-]token|cookie|set[_-]cookie)$/i;
-function validateProxyUrl(raw) {
+function validateProxyUrl(raw, allowHttp) {
   if (/[\r\n\x00]/.test(raw)) {
     throw new Error("webhook_receiver.public_url must not contain CR/LF/NUL");
   }
@@ -25,10 +27,16 @@ function validateProxyUrl(raw) {
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
     throw new Error(`webhook_receiver.public_url must be http(s); got ${parsed.protocol}`);
   }
+  if (parsed.protocol === "http:" && !allowHttp) {
+    throw new Error("webhook_receiver.public_url must use https (set allowHttp only for controlled local development)");
+  }
   if (parsed.username || parsed.password) {
     throw new Error("webhook_receiver.public_url must not include userinfo");
   }
-  return raw.replace(/\/$/, "");
+  if (parsed.search || parsed.hash) {
+    throw new Error("webhook_receiver.public_url must not include a query string or fragment");
+  }
+  return raw.replace(/\/+$/, "");
 }
 function retryKeyString(k) {
   return `${k.step_id}::${k.operation_id}`;
@@ -39,13 +47,18 @@ async function createWebhookReceiver(options = {}) {
     throw new Error("webhook_receiver.mode=proxy_url requires `public_url`");
   }
   const host = options.host ?? "127.0.0.1";
-  if (mode === "loopback_mock" && (host === "0.0.0.0" || host === "::")) {
+  if (mode === "loopback_mock" && !isLoopbackHost(host)) {
     throw new Error(
       `webhook_receiver host ${host} is not permitted in loopback_mock mode. Use mode=proxy_url with an explicit public_url for publicly-reachable runs.`
     );
   }
   const port = options.port ?? 0;
-  const proxyBase = mode === "proxy_url" ? validateProxyUrl(options.public_url) : void 0;
+  const proxyBase = mode === "proxy_url" ? validateProxyUrl(options.public_url, options.allowHttp === true) : void 0;
+  if (options.tls && proxyBase && new URL(proxyBase).protocol !== "https:") {
+    throw new Error("webhook_receiver.public_url must use https when local TLS is configured");
+  }
+  const publicRouteSuffix = mode === "proxy_url" ? `/_adcp_receiver/${randomUUID()}` : "";
+  const routePrefix = proxyBase ? `${new URL(proxyBase).pathname.replace(/\/+$/, "")}${publicRouteSuffix}` : "";
   const captured = [];
   const challenges = [];
   const waiters = [];
@@ -54,9 +67,23 @@ async function createWebhookReceiver(options = {}) {
   const deliveryCounts = /* @__PURE__ */ new Map();
   const challengeCounts = /* @__PURE__ */ new Map();
   let closed = false;
-  const server = createServer(
-    (req, res) => handleRequest(req, res, { captured, challenges, waiters, retryPolicies, deliveryCounts, challengeCounts })
-  );
+  const requestListener = (req, res) => handleRequest(req, res, {
+    captured,
+    challenges,
+    waiters,
+    retryPolicies,
+    deliveryCounts,
+    challengeCounts,
+    routePrefix
+  });
+  const server = options.tls ? createHttpsServer(
+    {
+      cert: options.tls.cert,
+      key: options.tls.key,
+      ...options.tls.passphrase !== void 0 && { passphrase: options.tls.passphrase }
+    },
+    requestListener
+  ) : createServer(requestListener);
   server.headersTimeout = HEADERS_TIMEOUT_MS;
   server.requestTimeout = REQUEST_TIMEOUT_MS;
   server.keepAliveTimeout = KEEP_ALIVE_TIMEOUT_MS;
@@ -71,10 +98,11 @@ async function createWebhookReceiver(options = {}) {
     });
   });
   const bound = server.address();
-  const base_url = proxyBase ?? `http://${formatHost(bound.address)}:${bound.port}`;
+  const base_url = proxyBase ? `${proxyBase}${publicRouteSuffix}` : `${options.tls ? "https" : "http"}://${formatHost(bound.address)}:${bound.port}`;
   return {
     base_url,
     mode,
+    bind_host: host,
     all: () => captured.slice(),
     challenges: () => challenges.slice(),
     matching: (filter) => captured.filter((w) => matchesFilter(w, filter)),
@@ -93,19 +121,26 @@ async function createWebhookReceiver(options = {}) {
     }
   };
 }
+function isLoopbackHost(host) {
+  const normalized = host.toLowerCase();
+  if (normalized === "localhost") return true;
+  if (isIP(host) === 4) return /^127(?:\.\d{1,3}){3}$/.test(host);
+  if (isIP(host) === 6) return normalized === "::1" || /^(?:0:){7}1$/.test(normalized);
+  return false;
+}
 function handleRequest(req, res, state) {
   if (req.method !== "POST") {
     res.statusCode = 405;
     res.end();
     return;
   }
-  const pathParts = parseStepPath(req.url ?? "");
+  const pathParts = parseStepPath(req.url ?? "", state.routePrefix);
   if (!pathParts) {
     res.statusCode = 404;
     res.end();
     return;
   }
-  const { step_id, operation_id } = pathParts;
+  const { step_id, operation_id, logical_path } = pathParts;
   let size = 0;
   const chunks = [];
   let tooLarge = false;
@@ -158,7 +193,7 @@ function handleRequest(req, res, state) {
         operation_id,
         received_at: Date.now(),
         method: req.method ?? "POST",
-        path: req.url ?? "/",
+        path: logical_path,
         headers: redactHeaders(headers),
         raw_body: raw,
         body: parsedBody.body,
@@ -187,7 +222,7 @@ function handleRequest(req, res, state) {
       delivery_index: deliveryIndex,
       received_at: Date.now(),
       method: req.method ?? "POST",
-      path: req.url ?? "/",
+      path: logical_path,
       headers: redactHeaders(headers),
       raw_body: raw,
       ...parsedBody,
@@ -219,10 +254,15 @@ function requestPathname(reqUrl) {
   const q = reqUrl.indexOf("?");
   return q === -1 ? reqUrl : reqUrl.slice(0, q);
 }
-function parseStepPath(reqUrl) {
-  const match = STEP_PATH_RE.exec(requestPathname(reqUrl));
+function parseStepPath(reqUrl, routePrefix) {
+  const pathname = requestPathname(reqUrl);
+  if (routePrefix && !pathname.startsWith(`${routePrefix}/`)) return void 0;
+  const logicalPath = routePrefix ? pathname.slice(routePrefix.length) : pathname;
+  const match = STEP_PATH_RE.exec(logicalPath);
   if (!match) return void 0;
-  return { step_id: match[1], operation_id: match[2] };
+  const queryIndex = reqUrl.indexOf("?");
+  const query = queryIndex === -1 ? "" : reqUrl.slice(queryIndex);
+  return { step_id: match[1], operation_id: match[2], logical_path: `${logicalPath}${query}` };
 }
 function normalizeHeaders(raw) {
   const out = {};

package/dist/lib/version.d.mts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "14.0.0-beta.19";
+export declare const LIBRARY_VERSION = "14.0.0-beta.20";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "14.0.0-beta.19";
+    readonly library: "14.0.0-beta.20";
     readonly adcp: "3.2.0-beta.9";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0-beta.1", "3.0-beta.1", "3.0-beta", "3.0.0-beta.3", "3.0-beta.3", "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.2.0-beta.9", "3.2-beta.9"];
-    readonly generatedAt: "2026-08-30T04:12:52.476Z";
+    readonly generatedAt: "2026-08-30T05:56:08.494Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.d.ts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "14.0.0-beta.19";
+export declare const LIBRARY_VERSION = "14.0.0-beta.20";
 /**
  * AdCP specification version this library is built for
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "14.0.0-beta.19";
+    readonly library: "14.0.0-beta.20";
     readonly adcp: "3.2.0-beta.9";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0-beta.1", "3.0-beta.1", "3.0-beta", "3.0.0-beta.3", "3.0-beta.3", "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.2.0-beta.9", "3.2-beta.9"];
-    readonly generatedAt: "2026-08-30T04:12:52.476Z";
+    readonly generatedAt: "2026-08-30T05:56:08.494Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.js

@@ -31,7 +31,7 @@ __export(version_exports, {
   toReleasePrecisionVersion: () => toReleasePrecisionVersion
 });
 module.exports = __toCommonJS(version_exports);
-const LIBRARY_VERSION = "14.0.0-beta.19";
+const LIBRARY_VERSION = "14.0.0-beta.20";
 const ADCP_VERSION = "3.2.0-beta.9";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -94,10 +94,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2-beta.9"
 ];
 const VERSION_INFO = {
-  library: "14.0.0-beta.19",
+  library: "14.0.0-beta.20",
   adcp: "3.2.0-beta.9",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-08-30T04:12:52.476Z"
+  generatedAt: "2026-08-30T05:56:08.494Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "14.0.0-beta.19";
+const LIBRARY_VERSION = "14.0.0-beta.20";
 const ADCP_VERSION = "3.2.0-beta.9";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -61,10 +61,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2-beta.9"
 ];
 const VERSION_INFO = {
-  library: "14.0.0-beta.19",
+  library: "14.0.0-beta.20",
   adcp: "3.2.0-beta.9",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-08-30T04:12:52.476Z"
+  generatedAt: "2026-08-30T05:56:08.494Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
 > Generated at: 2026-08-30
-> Library: @adcp/sdk v14.0.0-beta.19
+> Library: @adcp/sdk v14.0.0-beta.20
 > 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/package.json

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