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

package/dist/lib/signing/brand-jwks.d.ts

@@ -10,7 +10,13 @@ export type BrandJsonResolverErrorCode = 'invalid_url' | 'invalid_house' | 'redi
  */
 export declare class BrandJsonResolverError extends Error {
     readonly code: BrandJsonResolverErrorCode;
-    constructor(code: BrandJsonResolverErrorCode, message: string);
+    readonly cause?: unknown;
+    /** HTTP status for `fetch_failed` responses, when a response was received. */
+    readonly httpStatus?: number;
+    constructor(code: BrandJsonResolverErrorCode, message: string, details?: {
+        httpStatus?: number;
+        cause?: unknown;
+    });
 }
 export interface BrandJsonJwksResolverOptions {
     /** Functional role of the agent whose keys we want to resolve. */
@@ -99,3 +105,40 @@ export declare class BrandJsonJwksResolver implements JwksResolver {
     private refresh;
     private doRefresh;
 }
+export interface FetchedBrandJson {
+    status: 'ok' | 'not_modified';
+    finalUrl: string;
+    data: unknown;
+    etag?: string;
+    cacheControl?: string;
+}
+export interface FetchBrandJsonOptions {
+    /** Entry-point URL. HTTPS and public addresses are required by default. */
+    startUrl: string;
+    /** ETag sent only to the entry URL for cache revalidation. */
+    currentEtag?: string;
+    /** Maximum JSON-level `authoritative_location` / `house` hops. Default 3, hard maximum 10. */
+    maxRedirects?: number;
+    /** Permit HTTP and private addresses for controlled development environments. */
+    allowPrivateIp?: boolean;
+    /** Whole-request deadline per hop. Default and hard maximum 10 seconds. */
+    timeoutMs?: number;
+    /** Response-body cap per hop. Default and hard maximum 256 KiB. */
+    maxBodyBytes?: number;
+}
+/**
+ * Fetch brand.json from `startUrl`, following `authoritative_location` and
+ * `house` string redirect variants up to `maxRedirects` hops. Each hop goes
+ * through the SSRF-safe fetch primitive so an attacker-supplied chain can't
+ * land on a private address or IMDS. Redirect targets are structurally
+ * validated before dispatch — an attacker-controlled brand.json that emits
+ * `{"house": "evil.com\\@victim.com"}` or `{"authoritative_location":
+ * "http://169.254.169.254/..."}` is rejected at parse time rather than
+ * relying on `ssrfSafeFetch` to catch every pathological shape.
+ *
+ * This low-level function is intentionally stateless. Callers MUST add
+ * response caching and a minimum refresh cooldown rather than invoking it on
+ * every authorization request. Prefer `BrandJsonJwksResolver` when resolving
+ * signing keys; it provides both safeguards.
+ */
+export declare function fetchBrandJson(args: FetchBrandJsonOptions): Promise<FetchedBrandJson>;

package/dist/lib/signing/brand-jwks.js

@@ -19,17 +19,23 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var brand_jwks_exports = {};
 __export(brand_jwks_exports, {
   BrandJsonJwksResolver: () => BrandJsonJwksResolver,
-  BrandJsonResolverError: () => BrandJsonResolverError
+  BrandJsonResolverError: () => BrandJsonResolverError,
+  fetchBrandJson: () => fetchBrandJson
 });
 module.exports = __toCommonJS(brand_jwks_exports);
 var import_net = require('../net/index.js');
 var import_jwks_https = require('./jwks-https.js');
 class BrandJsonResolverError extends Error {
   code;
-  constructor(code, message) {
+  cause;
+  /** HTTP status for `fetch_failed` responses, when a response was received. */
+  httpStatus;
+  constructor(code, message, details = {}) {
     super(message);
     this.name = "BrandJsonResolverError";
     this.code = code;
+    this.httpStatus = details.httpStatus;
+    this.cause = details.cause;
   }
 }
 const DEFAULT_MIN_COOLDOWN_SECONDS = 30;
@@ -143,10 +149,26 @@ class BrandJsonJwksResolver {
     };
   }
 }
+const MAX_BRAND_JSON_TIMEOUT_MS = 1e4;
+const MAX_BRAND_JSON_BODY_BYTES = 262144;
+const MAX_BRAND_JSON_REDIRECTS = 10;
 async function fetchBrandJson(args) {
+  const maxRedirects = boundedIntegerOption("maxRedirects", args.maxRedirects ?? DEFAULT_MAX_REDIRECTS, {
+    min: 0,
+    max: MAX_BRAND_JSON_REDIRECTS
+  });
+  const timeoutMs = boundedIntegerOption("timeoutMs", args.timeoutMs ?? MAX_BRAND_JSON_TIMEOUT_MS, {
+    min: 1,
+    max: MAX_BRAND_JSON_TIMEOUT_MS
+  });
+  const maxBodyBytes = boundedIntegerOption("maxBodyBytes", args.maxBodyBytes ?? MAX_BRAND_JSON_BODY_BYTES, {
+    min: 1,
+    max: MAX_BRAND_JSON_BODY_BYTES
+  });
+  const allowPrivateIp = args.allowPrivateIp === true;
   const seen = /* @__PURE__ */ new Set();
-  let url = canonicalizeUrl(args.startUrl, args.allowPrivateIp);
-  for (let hop = 0; hop <= args.maxRedirects; hop++) {
+  let url = canonicalizeUrl(args.startUrl, allowPrivateIp);
+  for (let hop = 0; hop <= maxRedirects; hop++) {
     if (seen.has(url)) {
       throw new BrandJsonResolverError("redirect_loop", `brand.json redirect loop detected`);
     }
@@ -155,11 +177,18 @@ async function fetchBrandJson(args) {
       accept: "application/json"
     };
     if (hop === 0 && args.currentEtag) headers["if-none-match"] = args.currentEtag;
-    const res = await (0, import_net.ssrfSafeFetch)(url, {
-      method: "GET",
-      headers,
-      allowPrivateIp: args.allowPrivateIp
-    });
+    let res;
+    try {
+      res = await (0, import_net.ssrfSafeFetch)(url, {
+        method: "GET",
+        headers,
+        allowPrivateIp,
+        timeoutMs,
+        maxBodyBytes
+      });
+    } catch (cause) {
+      throw new BrandJsonResolverError("fetch_failed", "Unable to fetch brand.json", { cause });
+    }
     if (hop === 0 && res.status === 304) {
       return {
         status: "not_modified",
@@ -170,7 +199,9 @@ async function fetchBrandJson(args) {
       };
     }
     if (res.status !== 200) {
-      throw new BrandJsonResolverError("fetch_failed", `brand.json fetch returned HTTP ${res.status}`);
+      throw new BrandJsonResolverError("fetch_failed", `brand.json fetch returned HTTP ${res.status}`, {
+        httpStatus: res.status
+      });
     }
     const text = Buffer.from(res.body).toString("utf8");
     let parsed;
@@ -186,20 +217,20 @@ async function fetchBrandJson(args) {
     const authoritative = typeof obj.authoritative_location === "string" ? obj.authoritative_location : void 0;
     const house = typeof obj.house === "string" ? obj.house : void 0;
     if (authoritative !== void 0) {
-      if (hop === args.maxRedirects) {
+      if (hop === maxRedirects) {
         throw new BrandJsonResolverError("redirect_depth_exceeded", `brand.json redirect depth exceeded`);
       }
-      url = canonicalizeUrl(authoritative, args.allowPrivateIp);
+      url = canonicalizeUrl(authoritative, allowPrivateIp);
       continue;
     }
     if (house !== void 0) {
       if (!BARE_HOSTNAME.test(house)) {
         throw new BrandJsonResolverError("invalid_house", `brand.json "house" is not a bare hostname`);
       }
-      if (hop === args.maxRedirects) {
+      if (hop === maxRedirects) {
         throw new BrandJsonResolverError("redirect_depth_exceeded", `brand.json redirect depth exceeded`);
       }
-      url = canonicalizeUrl(`https://${house}/.well-known/brand.json`, args.allowPrivateIp);
+      url = canonicalizeUrl(`https://${house}/.well-known/brand.json`, allowPrivateIp);
       continue;
     }
     assertBrandJsonShape(obj);
@@ -213,6 +244,12 @@ async function fetchBrandJson(args) {
   }
   throw new BrandJsonResolverError("redirect_depth_exceeded", `brand.json redirect depth exceeded`);
 }
+function boundedIntegerOption(name, value, bounds) {
+  if (!Number.isInteger(value) || value < bounds.min || value > bounds.max) {
+    throw new TypeError(`fetchBrandJson: ${name} must be an integer between ${bounds.min} and ${bounds.max}`);
+  }
+  return value;
+}
 function canonicalizeUrl(raw, allowPrivateIp) {
   let parsed;
   try {
@@ -346,5 +383,6 @@ function computeLifetime(cacheControl, maxAge) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BrandJsonJwksResolver,
-  BrandJsonResolverError
+  BrandJsonResolverError,
+  fetchBrandJson
 });

package/dist/lib/signing/brand-jwks.mjs

@@ -2,10 +2,15 @@ import { ssrfSafeFetch } from "../net/index.mjs";
 import { HttpsJwksResolver } from "./jwks-https.mjs";
 class BrandJsonResolverError extends Error {
   code;
-  constructor(code, message) {
+  cause;
+  /** HTTP status for `fetch_failed` responses, when a response was received. */
+  httpStatus;
+  constructor(code, message, details = {}) {
     super(message);
     this.name = "BrandJsonResolverError";
     this.code = code;
+    this.httpStatus = details.httpStatus;
+    this.cause = details.cause;
   }
 }
 const DEFAULT_MIN_COOLDOWN_SECONDS = 30;
@@ -119,10 +124,26 @@ class BrandJsonJwksResolver {
     };
   }
 }
+const MAX_BRAND_JSON_TIMEOUT_MS = 1e4;
+const MAX_BRAND_JSON_BODY_BYTES = 262144;
+const MAX_BRAND_JSON_REDIRECTS = 10;
 async function fetchBrandJson(args) {
+  const maxRedirects = boundedIntegerOption("maxRedirects", args.maxRedirects ?? DEFAULT_MAX_REDIRECTS, {
+    min: 0,
+    max: MAX_BRAND_JSON_REDIRECTS
+  });
+  const timeoutMs = boundedIntegerOption("timeoutMs", args.timeoutMs ?? MAX_BRAND_JSON_TIMEOUT_MS, {
+    min: 1,
+    max: MAX_BRAND_JSON_TIMEOUT_MS
+  });
+  const maxBodyBytes = boundedIntegerOption("maxBodyBytes", args.maxBodyBytes ?? MAX_BRAND_JSON_BODY_BYTES, {
+    min: 1,
+    max: MAX_BRAND_JSON_BODY_BYTES
+  });
+  const allowPrivateIp = args.allowPrivateIp === true;
   const seen = /* @__PURE__ */ new Set();
-  let url = canonicalizeUrl(args.startUrl, args.allowPrivateIp);
-  for (let hop = 0; hop <= args.maxRedirects; hop++) {
+  let url = canonicalizeUrl(args.startUrl, allowPrivateIp);
+  for (let hop = 0; hop <= maxRedirects; hop++) {
     if (seen.has(url)) {
       throw new BrandJsonResolverError("redirect_loop", `brand.json redirect loop detected`);
     }
@@ -131,11 +152,18 @@ async function fetchBrandJson(args) {
       accept: "application/json"
     };
     if (hop === 0 && args.currentEtag) headers["if-none-match"] = args.currentEtag;
-    const res = await ssrfSafeFetch(url, {
-      method: "GET",
-      headers,
-      allowPrivateIp: args.allowPrivateIp
-    });
+    let res;
+    try {
+      res = await ssrfSafeFetch(url, {
+        method: "GET",
+        headers,
+        allowPrivateIp,
+        timeoutMs,
+        maxBodyBytes
+      });
+    } catch (cause) {
+      throw new BrandJsonResolverError("fetch_failed", "Unable to fetch brand.json", { cause });
+    }
     if (hop === 0 && res.status === 304) {
       return {
         status: "not_modified",
@@ -146,7 +174,9 @@ async function fetchBrandJson(args) {
       };
     }
     if (res.status !== 200) {
-      throw new BrandJsonResolverError("fetch_failed", `brand.json fetch returned HTTP ${res.status}`);
+      throw new BrandJsonResolverError("fetch_failed", `brand.json fetch returned HTTP ${res.status}`, {
+        httpStatus: res.status
+      });
     }
     const text = Buffer.from(res.body).toString("utf8");
     let parsed;
@@ -162,20 +192,20 @@ async function fetchBrandJson(args) {
     const authoritative = typeof obj.authoritative_location === "string" ? obj.authoritative_location : void 0;
     const house = typeof obj.house === "string" ? obj.house : void 0;
     if (authoritative !== void 0) {
-      if (hop === args.maxRedirects) {
+      if (hop === maxRedirects) {
         throw new BrandJsonResolverError("redirect_depth_exceeded", `brand.json redirect depth exceeded`);
       }
-      url = canonicalizeUrl(authoritative, args.allowPrivateIp);
+      url = canonicalizeUrl(authoritative, allowPrivateIp);
       continue;
     }
     if (house !== void 0) {
       if (!BARE_HOSTNAME.test(house)) {
         throw new BrandJsonResolverError("invalid_house", `brand.json "house" is not a bare hostname`);
       }
-      if (hop === args.maxRedirects) {
+      if (hop === maxRedirects) {
         throw new BrandJsonResolverError("redirect_depth_exceeded", `brand.json redirect depth exceeded`);
       }
-      url = canonicalizeUrl(`https://${house}/.well-known/brand.json`, args.allowPrivateIp);
+      url = canonicalizeUrl(`https://${house}/.well-known/brand.json`, allowPrivateIp);
       continue;
     }
     assertBrandJsonShape(obj);
@@ -189,6 +219,12 @@ async function fetchBrandJson(args) {
   }
   throw new BrandJsonResolverError("redirect_depth_exceeded", `brand.json redirect depth exceeded`);
 }
+function boundedIntegerOption(name, value, bounds) {
+  if (!Number.isInteger(value) || value < bounds.min || value > bounds.max) {
+    throw new TypeError(`fetchBrandJson: ${name} must be an integer between ${bounds.min} and ${bounds.max}`);
+  }
+  return value;
+}
 function canonicalizeUrl(raw, allowPrivateIp) {
   let parsed;
   try {
@@ -321,5 +357,6 @@ function computeLifetime(cacheControl, maxAge) {
 }
 export {
   BrandJsonJwksResolver,
-  BrandJsonResolverError
+  BrandJsonResolverError,
+  fetchBrandJson
 };

package/dist/lib/signing/server.d.mts

@@ -15,7 +15,7 @@ export { jwkToPublicKey, verifySignature } from './crypto.mjs';
 export { RequestSignatureError, type RequestSignatureErrorCode, ResponseSignatureError, type ResponseSignatureErrorCode, WebhookSignatureError, type WebhookSignatureErrorCode, } from './errors.mjs';
 export { StaticJwksResolver, type JwksResolution, type JwksResolver } from './jwks.mjs';
 export { HttpsJwksResolver, type HttpsJwksResolverOptions } from './jwks-https.mjs';
-export { BrandJsonJwksResolver, BrandJsonResolverError, type BrandAgentType, type BrandJsonJwksResolverOptions, type BrandJsonResolverErrorCode, } from './brand-jwks.mjs';
+export { BrandJsonJwksResolver, BrandJsonResolverError, fetchBrandJson, type BrandAgentType, type FetchedBrandJson, type FetchBrandJsonOptions, type BrandJsonJwksResolverOptions, type BrandJsonResolverErrorCode, } from './brand-jwks.mjs';
 export { parseSignature, parseSignatureInput, type ParsedSignature, type ParsedSignatureInput } from './parser.mjs';
 export { InMemoryReplayStore, type InMemoryReplayStoreOptions, type ReplayInsertResult, type ReplayStore, } from './replay.mjs';
 export { PostgresReplayStore, REPLAY_CACHE_MIGRATION, getReplayStoreMigration, sweepExpiredReplays, type PostgresReplayStoreOptions, type SweepExpiredReplaysOptions, } from './postgres-replay-store.mjs';

package/dist/lib/signing/server.d.ts

@@ -15,7 +15,7 @@ export { jwkToPublicKey, verifySignature } from './crypto';
 export { RequestSignatureError, type RequestSignatureErrorCode, ResponseSignatureError, type ResponseSignatureErrorCode, WebhookSignatureError, type WebhookSignatureErrorCode, } from './errors';
 export { StaticJwksResolver, type JwksResolution, type JwksResolver } from './jwks';
 export { HttpsJwksResolver, type HttpsJwksResolverOptions } from './jwks-https';
-export { BrandJsonJwksResolver, BrandJsonResolverError, type BrandAgentType, type BrandJsonJwksResolverOptions, type BrandJsonResolverErrorCode, } from './brand-jwks';
+export { BrandJsonJwksResolver, BrandJsonResolverError, fetchBrandJson, type BrandAgentType, type FetchedBrandJson, type FetchBrandJsonOptions, type BrandJsonJwksResolverOptions, type BrandJsonResolverErrorCode, } from './brand-jwks';
 export { parseSignature, parseSignatureInput, type ParsedSignature, type ParsedSignatureInput } from './parser';
 export { InMemoryReplayStore, type InMemoryReplayStoreOptions, type ReplayInsertResult, type ReplayStore, } from './replay';
 export { PostgresReplayStore, REPLAY_CACHE_MIGRATION, getReplayStoreMigration, sweepExpiredReplays, type PostgresReplayStoreOptions, type SweepExpiredReplaysOptions, } from './postgres-replay-store';

package/dist/lib/signing/server.js

@@ -54,6 +54,7 @@ __export(server_exports, {
   createAgentJwksSet: () => import_agent_resolver.createAgentJwksSet,
   createExpressVerifier: () => import_middleware.createExpressVerifier,
   createWebhookVerifier: () => import_webhook_verifier.createWebhookVerifier,
+  fetchBrandJson: () => import_brand_jwks.fetchBrandJson,
   finalizeResponseSignature: () => import_signer.finalizeResponseSignature,
   formatSignatureParams: () => import_canonicalize.formatSignatureParams,
   getAgentJwks: () => import_agent_resolver.getAgentJwks,
@@ -138,6 +139,7 @@ var import_agent_resolver = require('./agent-resolver/index.js');
   createAgentJwksSet,
   createExpressVerifier,
   createWebhookVerifier,
+  fetchBrandJson,
   finalizeResponseSignature,
   formatSignatureParams,
   getAgentJwks,

package/dist/lib/signing/server.mjs

@@ -23,7 +23,8 @@ import { StaticJwksResolver } from "./jwks.mjs";
 import { HttpsJwksResolver } from "./jwks-https.mjs";
 import {
   BrandJsonJwksResolver,
-  BrandJsonResolverError
+  BrandJsonResolverError,
+  fetchBrandJson
 } from "./brand-jwks.mjs";
 import { parseSignature, parseSignatureInput } from "./parser.mjs";
 import {
@@ -112,6 +113,7 @@ export {
   createAgentJwksSet,
   createExpressVerifier,
   createWebhookVerifier,
+  fetchBrandJson,
   finalizeResponseSignature,
   formatSignatureParams,
   getAgentJwks,

package/dist/lib/testing/storyboard/runner.js

@@ -1529,7 +1529,9 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     ...options.webhook_receiver.mode && { mode: options.webhook_receiver.mode },
     ...options.webhook_receiver.host !== void 0 && { host: options.webhook_receiver.host },
     ...options.webhook_receiver.port !== void 0 && { port: options.webhook_receiver.port },
-    ...options.webhook_receiver.public_url !== void 0 && { public_url: options.webhook_receiver.public_url }
+    ...options.webhook_receiver.public_url !== void 0 && { public_url: options.webhook_receiver.public_url },
+    allowHttp: options.allow_http === true,
+    ...options.webhook_receiver.tls !== void 0 && { tls: options.webhook_receiver.tls }
   }) : void 0;
   const runnerVars = (0, import_context.createRunnerVariables)({
     ...webhookReceiver && { webhookBase: webhookReceiver.base_url }
@@ -2602,7 +2604,9 @@ async function runStoryboardStepBody(agentUrl, storyboard, stepId, options) {
     ...options.webhook_receiver.port !== void 0 && { port: options.webhook_receiver.port },
     ...options.webhook_receiver.public_url !== void 0 && {
       public_url: options.webhook_receiver.public_url
-    }
+    },
+    allowHttp: options.allow_http === true,
+    ...options.webhook_receiver.tls !== void 0 && { tls: options.webhook_receiver.tls }
   }) : void 0);
   const ownsWebhookReceiver = !injectedReceiver && !!webhookReceiver;
   const runnerVars = (0, import_context.createRunnerVariables)({

package/dist/lib/testing/storyboard/runner.mjs

@@ -1546,7 +1546,9 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     ...options.webhook_receiver.mode && { mode: options.webhook_receiver.mode },
     ...options.webhook_receiver.host !== void 0 && { host: options.webhook_receiver.host },
     ...options.webhook_receiver.port !== void 0 && { port: options.webhook_receiver.port },
-    ...options.webhook_receiver.public_url !== void 0 && { public_url: options.webhook_receiver.public_url }
+    ...options.webhook_receiver.public_url !== void 0 && { public_url: options.webhook_receiver.public_url },
+    allowHttp: options.allow_http === true,
+    ...options.webhook_receiver.tls !== void 0 && { tls: options.webhook_receiver.tls }
   }) : void 0;
   const runnerVars = createRunnerVariables({
     ...webhookReceiver && { webhookBase: webhookReceiver.base_url }
@@ -2619,7 +2621,9 @@ async function runStoryboardStepBody(agentUrl, storyboard, stepId, options) {
     ...options.webhook_receiver.port !== void 0 && { port: options.webhook_receiver.port },
     ...options.webhook_receiver.public_url !== void 0 && {
       public_url: options.webhook_receiver.public_url
-    }
+    },
+    allowHttp: options.allow_http === true,
+    ...options.webhook_receiver.tls !== void 0 && { tls: options.webhook_receiver.tls }
   }) : void 0);
   const ownsWebhookReceiver = !injectedReceiver && !!webhookReceiver;
   const runnerVars = createRunnerVariables({

package/dist/lib/testing/storyboard/types.d.mts

@@ -1718,6 +1718,12 @@ export interface StoryboardRunOptions extends TestOptions {
          * validate reachability.
          */
         public_url?: string;
+        /** TLS material for direct HTTPS serving; omit behind a TLS-terminating proxy. */
+        tls?: {
+            cert: string | Buffer;
+            key: string | Buffer;
+            passphrase?: string;
+        };
     };
     /**
      * Target receiver for `replay_webhook_vector` storyboards. This is separate

package/dist/lib/testing/storyboard/types.d.ts

@@ -1718,6 +1718,12 @@ export interface StoryboardRunOptions extends TestOptions {
          * validate reachability.
          */
         public_url?: string;
+        /** TLS material for direct HTTPS serving; omit behind a TLS-terminating proxy. */
+        tls?: {
+            cert: string | Buffer;
+            key: string | Buffer;
+            passphrase?: string;
+        };
     };
     /**
      * Target receiver for `replay_webhook_vector` storyboards. This is separate

package/dist/lib/testing/storyboard/validations.d.mts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "14.0.0-beta.19";
+export declare const RUNNER_CAPABILITY_VERSION = "14.0.0-beta.20";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

package/dist/lib/testing/storyboard/validations.d.ts

@@ -197,7 +197,7 @@ export interface UpstreamTrafficQueryResult {
  */
 export declare function runValidations(validations: StoryboardValidation[], context: ValidationContext): ValidationResult[];
 /** Capability semver emitted in run summaries and used for advisory expiry. */
-export declare const RUNNER_CAPABILITY_VERSION = "14.0.0-beta.19";
+export declare const RUNNER_CAPABILITY_VERSION = "14.0.0-beta.20";
 /** True when a failed validation contributes to the owning step's grade. */
 export declare function validationFailsStep(result: ValidationResult): boolean;
 /**

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

@@ -64,7 +64,12 @@ const DEFAULT_RETRY_COUNT = 3;
 const DEFAULT_RETRY_HTTP_STATUS = 503;
 const DEFAULT_MIN_DELIVERIES = 2;
 function webhookTimeoutDetail(receiver, base) {
-  return receiver.mode === "loopback_mock" && receiver.all().length === 0 && receiver.challenges().length === 0 ? `${base} No request reached the loopback receiver; an out-of-process agent must use webhook_receiver.mode="proxy_url".` : base;
+  if (receiver.all().length > 0 || receiver.challenges().length > 0) return base;
+  const bindHost = receiver.bind_host ?? "the configured local address";
+  if (receiver.mode === "loopback_mock") {
+    return `${base} No request reached the receiver bound to ${bindHost}; an out-of-process agent must use webhook_receiver.mode="proxy_url".`;
+  }
+  return `${base} No request reached the receiver bound to ${bindHost}; verify that the advertised callback URL routes to this container and bind address.`;
 }
 const DEFAULT_WEBHOOK_SIGNING_TAG = "adcp/webhook-signing/v1";
 const MAX_RETRY_REPLAY_COUNT = 10;

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

@@ -39,7 +39,12 @@ const DEFAULT_RETRY_COUNT = 3;
 const DEFAULT_RETRY_HTTP_STATUS = 503;
 const DEFAULT_MIN_DELIVERIES = 2;
 function webhookTimeoutDetail(receiver, base) {
-  return receiver.mode === "loopback_mock" && receiver.all().length === 0 && receiver.challenges().length === 0 ? `${base} No request reached the loopback receiver; an out-of-process agent must use webhook_receiver.mode="proxy_url".` : base;
+  if (receiver.all().length > 0 || receiver.challenges().length > 0) return base;
+  const bindHost = receiver.bind_host ?? "the configured local address";
+  if (receiver.mode === "loopback_mock") {
+    return `${base} No request reached the receiver bound to ${bindHost}; an out-of-process agent must use webhook_receiver.mode="proxy_url".`;
+  }
+  return `${base} No request reached the receiver bound to ${bindHost}; verify that the advertised callback URL routes to this container and bind address.`;
 }
 const DEFAULT_WEBHOOK_SIGNING_TAG = "adcp/webhook-signing/v1";
 const MAX_RETRY_REPLAY_COUNT = 10;

package/dist/lib/testing/storyboard/webhook-receiver.d.mts

@@ -80,6 +80,8 @@ export interface WebhookReceiver {
     readonly base_url: string;
     /** Whether the receiver is in loopback-mock or proxy-url mode. */
     readonly mode: 'loopback_mock' | 'proxy_url';
+    /** Local address the listener is bound to. */
+    readonly bind_host?: string;
     /** All webhooks captured so far, in arrival order. */
     all(): CapturedWebhook[];
     /** Schema-valid proof-of-control challenges, kept separate from event deliveries. */
@@ -114,5 +116,18 @@ export interface CreateWebhookReceiverOptions {
     port?: number;
     /** Public URL to advertise when `mode: 'proxy_url'`. */
     public_url?: string;
+    /**
+     * Permit an HTTP public URL for controlled local-development topologies.
+     */
+    allowHttp?: boolean;
+    /**
+     * TLS material for serving HTTPS directly. Omit when HTTPS terminates at a
+     * tunnel or reverse proxy in front of this listener.
+     */
+    tls?: {
+        cert: string | Buffer;
+        key: string | Buffer;
+        passphrase?: string;
+    };
 }
 export declare function createWebhookReceiver(options?: CreateWebhookReceiverOptions): Promise<WebhookReceiver>;

package/dist/lib/testing/storyboard/webhook-receiver.d.ts

@@ -80,6 +80,8 @@ export interface WebhookReceiver {
     readonly base_url: string;
     /** Whether the receiver is in loopback-mock or proxy-url mode. */
     readonly mode: 'loopback_mock' | 'proxy_url';
+    /** Local address the listener is bound to. */
+    readonly bind_host?: string;
     /** All webhooks captured so far, in arrival order. */
     all(): CapturedWebhook[];
     /** Schema-valid proof-of-control challenges, kept separate from event deliveries. */
@@ -114,5 +116,18 @@ export interface CreateWebhookReceiverOptions {
     port?: number;
     /** Public URL to advertise when `mode: 'proxy_url'`. */
     public_url?: string;
+    /**
+     * Permit an HTTP public URL for controlled local-development topologies.
+     */
+    allowHttp?: boolean;
+    /**
+     * TLS material for serving HTTPS directly. Omit when HTTPS terminates at a
+     * tunnel or reverse proxy in front of this listener.
+     */
+    tls?: {
+        cert: string | Buffer;
+        key: string | Buffer;
+        passphrase?: string;
+    };
 }
 export declare function createWebhookReceiver(options?: CreateWebhookReceiverOptions): Promise<WebhookReceiver>;