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

package/bin/adcp.js

@@ -23,7 +23,7 @@ if (process.argv.includes('--allow-http')) {
 }
 
 const { AdCPClient, detectProtocol, usesDeprecatedAssetsField } = require('../dist/lib/index.js');
-const { readFileSync, statSync } = require('fs');
+const { readFileSync, statSync, openSync, fstatSync, readSync, closeSync, constants: fsConstants } = require('fs');
 const path = require('path');
 const { pathToFileURL } = require('url');
 const net = require('net');
@@ -1130,6 +1130,13 @@ function parseAgentOptions(args) {
     !args[webhookReceiverPortIdx + 1].startsWith('--')
       ? args[webhookReceiverPortIdx + 1]
       : null;
+  const webhookReceiverHostIdx = args.indexOf('--webhook-receiver-host');
+  const webhookReceiverHostValue =
+    webhookReceiverHostIdx !== -1 &&
+    webhookReceiverHostIdx + 1 < args.length &&
+    !args[webhookReceiverHostIdx + 1].startsWith('--')
+      ? args[webhookReceiverHostIdx + 1]
+      : null;
   const webhookReceiverPublicUrlIdx = args.indexOf('--webhook-receiver-public-url');
   const webhookReceiverPublicUrlValue =
     webhookReceiverPublicUrlIdx !== -1 &&
@@ -1137,6 +1144,20 @@ function parseAgentOptions(args) {
     !args[webhookReceiverPublicUrlIdx + 1].startsWith('--')
       ? args[webhookReceiverPublicUrlIdx + 1]
       : null;
+  const webhookReceiverTlsCertIdx = args.indexOf('--webhook-receiver-tls-cert');
+  const webhookReceiverTlsCertValue =
+    webhookReceiverTlsCertIdx !== -1 &&
+    webhookReceiverTlsCertIdx + 1 < args.length &&
+    !args[webhookReceiverTlsCertIdx + 1].startsWith('--')
+      ? args[webhookReceiverTlsCertIdx + 1]
+      : null;
+  const webhookReceiverTlsKeyIdx = args.indexOf('--webhook-receiver-tls-key');
+  const webhookReceiverTlsKeyValue =
+    webhookReceiverTlsKeyIdx !== -1 &&
+    webhookReceiverTlsKeyIdx + 1 < args.length &&
+    !args[webhookReceiverTlsKeyIdx + 1].startsWith('--')
+      ? args[webhookReceiverTlsKeyIdx + 1]
+      : null;
 
   const invariantsIdx = args.indexOf('--invariants');
   const invariantsValue =
@@ -1212,7 +1233,10 @@ function parseAgentOptions(args) {
     multiInstanceStrategyValue,
     webhookReceiverModeValue,
     webhookReceiverPortValue,
+    webhookReceiverHostValue,
     webhookReceiverPublicUrlValue,
+    webhookReceiverTlsCertValue,
+    webhookReceiverTlsKeyValue,
     invariantsValue,
     localAgentValue,
     formatValue,
@@ -2111,11 +2135,19 @@ WEBHOOK OPTIONS:
                                   the webhook-emission and idempotency bundles
                                   to produce grades instead of skips.
   --webhook-receiver-port PORT    Force a bind port (default: auto-assign).
+  --webhook-receiver-host HOST    Bind address for the local listener (default:
+                                  127.0.0.1). Use 0.0.0.0 or :: with proxy mode
+                                  for container-to-container callbacks.
   --webhook-receiver-public-url URL
-                                  Public HTTPS base URL for proxy mode. Implies
+                                  Public HTTPS base URL for proxy mode. HTTP is
+                                  accepted only with --allow-http. Implies
                                   --webhook-receiver proxy when used alone.
                                   Incompatible with --multi-instance-strategy
                                   multi-pass (receiver URL is per-pass).
+  --webhook-receiver-tls-cert FILE
+  --webhook-receiver-tls-key FILE Serve HTTPS directly with this certificate
+                                  and private key. Both flags are required.
+                                  Omit when a tunnel or ingress terminates TLS.
   --webhook-receiver-auto-tunnel  Autodetect a tunnel binary on PATH (ngrok or
                                   cloudflared; override with $ADCP_WEBHOOK_TUNNEL),
                                   spawn it against the receiver, and plug its
@@ -2923,6 +2955,7 @@ async function handleStoryboardRun(args) {
     ...(fileComplianceOptions.adcpVersion && { adcpVersion: fileComplianceOptions.adcpVersion }),
     ...(fileComplianceOptions.schemaRoot && { schemaRoot: fileComplianceOptions.schemaRoot }),
     ...(!opts.strictResponseSchemaValidation && { strictResponseSchemaValidation: false }),
+    ...(opts.allowHttp && { allow_http: true }),
     ...sandboxRunOptions(opts),
     ...(opts.assertsSeededState && { assertsSeededState: true }),
     ...(opts.mediaBuyLifecycleCompatibility && {
@@ -3031,8 +3064,8 @@ async function handleStoryboardRun(args) {
  * transport and land in attribution output.
  */
 /**
- * Parse `--webhook-receiver [mode]`, `--webhook-receiver-port <port>`, and
- * `--webhook-receiver-public-url <url>`. Returns a `{ webhook_receiver, contracts }`
+ * Parse `--webhook-receiver [mode]` and its host, port, public-URL, and TLS
+ * flags. Returns a `{ webhook_receiver, contracts }`
  * pair suitable for spreading into `runStoryboard` / `comply` options, or
  * `null` if no webhook-receiver flag is set.
  *
@@ -3046,8 +3079,13 @@ function extractWebhookReceiverOptions(args) {
   const idx = args.indexOf('--webhook-receiver');
   const publicUrlIdx = args.indexOf('--webhook-receiver-public-url');
   const portIdx = args.indexOf('--webhook-receiver-port');
+  const hostIdx = args.indexOf('--webhook-receiver-host');
+  const tlsCertIdx = args.indexOf('--webhook-receiver-tls-cert');
+  const tlsKeyIdx = args.indexOf('--webhook-receiver-tls-key');
 
-  if (idx === -1 && publicUrlIdx === -1 && portIdx === -1) return null;
+  if (idx === -1 && publicUrlIdx === -1 && portIdx === -1 && hostIdx === -1 && tlsCertIdx === -1 && tlsKeyIdx === -1) {
+    return null;
+  }
 
   let mode = 'loopback_mock';
   if (idx !== -1) {
@@ -3071,6 +3109,29 @@ function extractWebhookReceiverOptions(args) {
       process.exit(2);
     }
     publicUrl = val;
+    let parsedPublicUrl;
+    try {
+      parsedPublicUrl = new URL(publicUrl);
+    } catch {
+      console.error(`ERROR: --webhook-receiver-public-url is not a valid URL: "${publicUrl}"`);
+      process.exit(2);
+    }
+    if (parsedPublicUrl.protocol !== 'http:' && parsedPublicUrl.protocol !== 'https:') {
+      console.error(`ERROR: --webhook-receiver-public-url must use http or https, got ${parsedPublicUrl.protocol}`);
+      process.exit(2);
+    }
+    if (parsedPublicUrl.username || parsedPublicUrl.password) {
+      console.error('ERROR: --webhook-receiver-public-url must not include userinfo');
+      process.exit(2);
+    }
+    if (parsedPublicUrl.search || parsedPublicUrl.hash) {
+      console.error('ERROR: --webhook-receiver-public-url must not include a query string or fragment');
+      process.exit(2);
+    }
+    if (parsedPublicUrl.protocol === 'http:' && !args.includes('--allow-http')) {
+      console.error('ERROR: an http:// webhook receiver public URL requires --allow-http (local development only)');
+      process.exit(2);
+    }
     // --webhook-receiver-public-url without --webhook-receiver implies proxy mode.
     // With explicit `--webhook-receiver loopback`, the combination is a user
     // error — loopback mode ignores public_url.
@@ -3105,16 +3166,93 @@ function extractWebhookReceiverOptions(args) {
     port = parsed;
   }
 
+  let host;
+  if (hostIdx !== -1) {
+    host = args[hostIdx + 1];
+    if (host === undefined || host.startsWith('--')) {
+      console.error('ERROR: --webhook-receiver-host requires a hostname or bind address');
+      process.exit(2);
+    }
+    if (host.length === 0 || /[\s/\\\r\n\x00]/.test(host)) {
+      console.error(`ERROR: --webhook-receiver-host is not a valid bind address: "${host}"`);
+      process.exit(2);
+    }
+  }
+
+  const tlsCertPath = tlsCertIdx === -1 ? undefined : args[tlsCertIdx + 1];
+  const tlsKeyPath = tlsKeyIdx === -1 ? undefined : args[tlsKeyIdx + 1];
+  if (tlsCertPath === undefined && tlsCertIdx !== -1) {
+    console.error('ERROR: --webhook-receiver-tls-cert requires a file path');
+    process.exit(2);
+  }
+  if (tlsKeyPath === undefined && tlsKeyIdx !== -1) {
+    console.error('ERROR: --webhook-receiver-tls-key requires a file path');
+    process.exit(2);
+  }
+  if (tlsCertPath?.startsWith('--')) {
+    console.error('ERROR: --webhook-receiver-tls-cert requires a file path');
+    process.exit(2);
+  }
+  if (tlsKeyPath?.startsWith('--')) {
+    console.error('ERROR: --webhook-receiver-tls-key requires a file path');
+    process.exit(2);
+  }
+  if ((tlsCertPath === undefined) !== (tlsKeyPath === undefined)) {
+    console.error('ERROR: --webhook-receiver-tls-cert and --webhook-receiver-tls-key must be provided together');
+    process.exit(2);
+  }
+  let tls;
+  if (tlsCertPath !== undefined && tlsKeyPath !== undefined) {
+    try {
+      tls = {
+        cert: readBoundedRegularFile(path.resolve(tlsCertPath), 'TLS certificate'),
+        key: readBoundedRegularFile(path.resolve(tlsKeyPath), 'TLS private key'),
+      };
+    } catch (err) {
+      console.error(`ERROR: unable to read webhook receiver TLS files: ${err.message}`);
+      process.exit(2);
+    }
+  }
+  if (tls && publicUrl && new URL(publicUrl).protocol !== 'https:') {
+    console.error('ERROR: direct webhook receiver TLS requires an https:// public URL');
+    process.exit(2);
+  }
+
   return {
     webhook_receiver: {
       mode,
+      ...(host !== undefined && { host }),
       ...(port !== undefined && { port }),
       ...(publicUrl !== undefined && { public_url: publicUrl }),
+      ...(tls !== undefined && { tls }),
     },
     contracts: ['webhook_receiver_runner'],
   };
 }
 
+const MAX_WEBHOOK_TLS_FILE_BYTES = 1_048_576;
+
+function readBoundedRegularFile(filePath, label) {
+  const fd = openSync(filePath, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile()) throw new Error(`${label} must be a regular file`);
+    if (stat.size > MAX_WEBHOOK_TLS_FILE_BYTES) {
+      throw new Error(`${label} exceeds the 1 MiB size limit`);
+    }
+    const buffer = Buffer.alloc(stat.size);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const count = readSync(fd, buffer, offset, buffer.length - offset, null);
+      if (count === 0) break;
+      offset += count;
+    }
+    return offset === buffer.length ? buffer : buffer.subarray(0, offset);
+  } finally {
+    closeSync(fd);
+  }
+}
+
 /**
  * Dynamic-import modules listed in --invariants so their `registerAssertion(...)`
  * calls populate the storyboard assertion registry before the runner resolves
@@ -3466,6 +3604,11 @@ function validateAutoTunnelArgs(args, base) {
     console.error('       Pick one — auto-tunnel mints a URL for you, public-url supplies your own.');
     process.exit(2);
   }
+  if (base?.webhook_receiver.tls) {
+    console.error('ERROR: --webhook-receiver-auto-tunnel cannot be combined with direct TLS certificate flags.');
+    console.error('       The tunnel terminates HTTPS and forwards plain HTTP to the local receiver.');
+    process.exit(2);
+  }
   // Auto-tunnel implies proxy mode and mints the URL itself. A coexisting
   // `--webhook-receiver [mode]` flag is always wrong: `loopback` contradicts
   // the minted URL, `proxy` without public-url is caught earlier in
@@ -3488,7 +3631,12 @@ async function resolveWebhookReceiverOptions(args, { jsonOutput } = {}) {
   const { publicUrl } = await spawnAutoTunnel({ port, timeoutMs, jsonOutput });
 
   return {
-    webhook_receiver: { mode: 'proxy_url', port, public_url: publicUrl },
+    webhook_receiver: {
+      mode: 'proxy_url',
+      ...(base?.webhook_receiver.host !== undefined && { host: base.webhook_receiver.host }),
+      port,
+      public_url: publicUrl,
+    },
     contracts: ['webhook_receiver_runner'],
   };
 }

package/dist/lib/schemas-data/v2.5/_provenance.json

@@ -4,5 +4,5 @@
   "source_sha": "4e553ad955f83b49c7d221ab5c3ff78237ad02e3",
   "source_tarball_sha256": "580656d6466ef9f0d1119985e6726c2efea718dc671e2ad30957fcb2fd54af0f",
   "upstream_adcp_version": "2.5.3",
-  "synced_at": "2026-08-30T04:26:50.358Z"
+  "synced_at": "2026-08-30T06:10:51.963Z"
 }

package/dist/lib/server/decisioning/runtime/postgres-task-settlement.d.mts

@@ -67,6 +67,16 @@ export interface PostgresTaskSettlementCoordinator {
     readonly durability: 'durable';
     /** Wire this into the normal webhook recovery poller/emitter. */
     readonly recovery: DurableWebhookDeliveryRecovery;
+    /**
+     * Prove that a scoped terminal task has its deterministic durable webhook
+     * checkpoint. This does not compare the task's result/error with a caller's
+     * intended artifact and does not prove delivery; verify terminal artifact
+     * compatibility separately before acknowledging an intent. Reconstructed
+     * coordinators must use the same registry, publisher scope, and outbox, and
+     * the checkpoint must be retained for the full intent replay horizon. The
+     * proof does not require the now-redacted push config.
+     */
+    hasTerminalCheckpoint(ref: ScopedTaskRef): Promise<boolean>;
     settle(ref: ScopedTaskRef, terminal: TerminalSettlement, push: TaskPushSettlementConfig): Promise<TaskPushSettlementOutcome>;
 }
 /** Configuration or immutable-delivery conflict detected before commit. */

package/dist/lib/server/decisioning/runtime/postgres-task-settlement.d.ts

@@ -67,6 +67,16 @@ export interface PostgresTaskSettlementCoordinator {
     readonly durability: 'durable';
     /** Wire this into the normal webhook recovery poller/emitter. */
     readonly recovery: DurableWebhookDeliveryRecovery;
+    /**
+     * Prove that a scoped terminal task has its deterministic durable webhook
+     * checkpoint. This does not compare the task's result/error with a caller's
+     * intended artifact and does not prove delivery; verify terminal artifact
+     * compatibility separately before acknowledging an intent. Reconstructed
+     * coordinators must use the same registry, publisher scope, and outbox, and
+     * the checkpoint must be retained for the full intent replay horizon. The
+     * proof does not require the now-redacted push config.
+     */
+    hasTerminalCheckpoint(ref: ScopedTaskRef): Promise<boolean>;
     settle(ref: ScopedTaskRef, terminal: TerminalSettlement, push: TaskPushSettlementConfig): Promise<TaskPushSettlementOutcome>;
 }
 /** Configuration or immutable-delivery conflict detected before commit. */

package/dist/lib/server/decisioning/runtime/postgres-task-settlement.js

@@ -77,6 +77,27 @@ function createPostgresTaskSettlementCoordinator(options) {
   return {
     durability: "durable",
     recovery,
+    async hasTerminalCheckpoint(ref) {
+      const settlementRef = snapshotSettlementRef(ref);
+      if (settlementRef.registryId !== registryId) return false;
+      const deliveryKey = {
+        ...claimScope,
+        deliveryId: stableScope("task-webhook", settlementRef)
+      };
+      try {
+        const task = await readTaskRow(
+          pool,
+          binding.tableName,
+          binding.namespace,
+          settlementRef,
+          false
+        );
+        if (!task || !TERMINAL.has(task.status) || task.has_webhook !== true) return false;
+        return Boolean(await readOutbox(pool, outboxTable, deliveryKey, false));
+      } catch (cause) {
+        throw new Error("PostgresTaskSettlementCoordinator.hasTerminalCheckpoint: query failed", { cause });
+      }
+    },
     async settle(ref, terminal, push) {
       const settlementRef = snapshotSettlementRef(ref);
       if (settlementRef.registryId !== registryId) {

package/dist/lib/server/decisioning/runtime/postgres-task-settlement.mjs

@@ -56,6 +56,27 @@ function createPostgresTaskSettlementCoordinator(options) {
   return {
     durability: "durable",
     recovery,
+    async hasTerminalCheckpoint(ref) {
+      const settlementRef = snapshotSettlementRef(ref);
+      if (settlementRef.registryId !== registryId) return false;
+      const deliveryKey = {
+        ...claimScope,
+        deliveryId: stableScope("task-webhook", settlementRef)
+      };
+      try {
+        const task = await readTaskRow(
+          pool,
+          binding.tableName,
+          binding.namespace,
+          settlementRef,
+          false
+        );
+        if (!task || !TERMINAL.has(task.status) || task.has_webhook !== true) return false;
+        return Boolean(await readOutbox(pool, outboxTable, deliveryKey, false));
+      } catch (cause) {
+        throw new Error("PostgresTaskSettlementCoordinator.hasTerminalCheckpoint: query failed", { cause });
+      }
+    },
     async settle(ref, terminal, push) {
       const settlementRef = snapshotSettlementRef(ref);
       if (settlementRef.registryId !== registryId) {

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

@@ -187,8 +187,19 @@ export interface ServeOptions {
      * deriving a URL and throw {@link UnknownHostError} for unknown hosts.
      * Evicted hosts are resolved again on their next request.
      * Setting {@link trustForwardedHost} is recommended when behind a proxy.
+     *
+     * @see {@link allowHttpHosts} for explicitly allowlisted development-only
+     * plain-HTTP hostnames.
      */
     publicUrl?: string | ((host: string) => string);
+    /**
+     * Exact hostnames permitted to use plain HTTP in {@link publicUrl}, in
+     * addition to the built-in loopback allowance. This development-only
+     * escape hatch supports private container-network names such as
+     * docker-compose service aliases. Entries are case-insensitive and must
+     * not contain ports or wildcards. HTTPS remains required by default.
+     */
+    allowHttpHosts?: string[];
     /**
      * Authentication middleware applied to every request. When configured,
      * missing or invalid credentials produce a 401 with a compliant

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

@@ -187,8 +187,19 @@ export interface ServeOptions {
      * deriving a URL and throw {@link UnknownHostError} for unknown hosts.
      * Evicted hosts are resolved again on their next request.
      * Setting {@link trustForwardedHost} is recommended when behind a proxy.
+     *
+     * @see {@link allowHttpHosts} for explicitly allowlisted development-only
+     * plain-HTTP hostnames.
      */
     publicUrl?: string | ((host: string) => string);
+    /**
+     * Exact hostnames permitted to use plain HTTP in {@link publicUrl}, in
+     * addition to the built-in loopback allowance. This development-only
+     * escape hatch supports private container-network names such as
+     * docker-compose service aliases. Entries are case-insensitive and must
+     * not contain ports or wildcards. HTTPS remains required by default.
+     */
+    allowHttpHosts?: string[];
     /**
      * Authentication middleware applied to every request. When configured,
      * missing or invalid credentials produce a 401 with a compliant

package/dist/lib/server/serve.js

@@ -104,13 +104,14 @@ function serve(createAgent, options) {
     );
   }
   const publicUrlOption = options?.publicUrl;
+  const allowHttpHosts = normalizeAllowHttpHosts(options?.allowHttpHosts);
   const protectedResourceOption = options?.protectedResource;
   const publicUrlIsFn = typeof publicUrlOption === "function";
   const prmIsFn = typeof protectedResourceOption === "function";
   const authenticationNeedsRawBody = (0, import_auth.authenticatorNeedsRawBody)(options?.authenticate);
   let staticPublicOrigin;
   if (typeof publicUrlOption === "string") {
-    staticPublicOrigin = validatePublicUrl(publicUrlOption, mountPath);
+    staticPublicOrigin = validatePublicUrl(publicUrlOption, mountPath, allowHttpHosts);
   }
   const MAX_HOST_METADATA_CACHE_ENTRIES = 128;
   const hostMetadataCache = /* @__PURE__ */ new Map();
@@ -140,7 +141,7 @@ function serve(createAgent, options) {
     const cached = getHostMetadata(host);
     if (cached?.publicUrl !== void 0) return cached.publicUrl;
     const publicUrl = publicUrlOption(canonicalHostnameForScope(host));
-    const publicOrigin = validatePublicUrl(publicUrl, mountPath);
+    const publicOrigin = validatePublicUrl(publicUrl, mountPath, allowHttpHosts);
     updateHostMetadata(host, { publicUrl, publicOrigin });
     return publicUrl;
   };
@@ -165,6 +166,11 @@ function serve(createAgent, options) {
       "[adcp/serve] No `authenticate` configured \u2014 this agent will accept unauthenticated requests. AdCP security_baseline requires authentication in production."
     );
   }
+  if (allowHttpHosts.size > 0 && process.env.NODE_ENV === "production") {
+    console.warn(
+      "[adcp/serve] `allowHttpHosts` enables plaintext HTTP for explicitly named hosts. Remove this development-only option from production deployments."
+    );
+  }
   const explicitPreTransport = options?.preTransport;
   const protectedResourcePath = `/.well-known/oauth-protected-resource${mountPath}`;
   const httpServer = (0, import_http.createServer)(async (req, res) => {
@@ -545,7 +551,7 @@ function trimTrailingSlashes(s) {
   while (end > 0 && s.charCodeAt(end - 1) === 47) end--;
   return s.slice(0, end);
 }
-function validatePublicUrl(publicUrl, mountPath) {
+function validatePublicUrl(publicUrl, mountPath, allowHttpHosts) {
   let parsed;
   try {
     parsed = new URL(publicUrl);
@@ -556,8 +562,11 @@ function validatePublicUrl(publicUrl, mountPath) {
     throw new Error("serve(): `publicUrl` must not include username or password credentials");
   }
   const loopbackHost = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]";
-  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && loopbackHost)) {
-    throw new Error("serve(): `publicUrl` must use https (http is allowed only for loopback development URLs)");
+  const explicitlyAllowedHttpHost = allowHttpHosts.has(parsed.hostname.toLowerCase());
+  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && (loopbackHost || explicitlyAllowedHttpHost))) {
+    throw new Error(
+      "serve(): `publicUrl` must use https (http is allowed only for loopback or hosts named in `allowHttpHosts`)"
+    );
   }
   if (trimTrailingSlashes(parsed.pathname) !== trimTrailingSlashes(mountPath)) {
     throw new Error(
@@ -569,6 +578,27 @@ function validatePublicUrl(publicUrl, mountPath) {
   }
   return parsed.origin;
 }
+function normalizeAllowHttpHosts(entries) {
+  const hosts = /* @__PURE__ */ new Set();
+  for (const entry of entries ?? []) {
+    if (entry.length === 0 || entry.trim() !== entry || entry.includes("*") || entry.includes("?") || entry.includes(":")) {
+      throw new Error(
+        `serve(): invalid allowHttpHosts entry "${entry}"; use an exact hostname without whitespace, wildcards, or a port`
+      );
+    }
+    let parsed;
+    try {
+      parsed = new URL(`https://${entry}/`);
+    } catch {
+      throw new Error(`serve(): invalid allowHttpHosts entry "${entry}"; expected a hostname`);
+    }
+    if (parsed.hostname.length === 0 || parsed.username.length > 0 || parsed.password.length > 0 || parsed.port.length > 0 || parsed.pathname !== "/" || parsed.search.length > 0 || parsed.hash.length > 0) {
+      throw new Error(`serve(): invalid allowHttpHosts entry "${entry}"; expected a hostname without a port`);
+    }
+    hosts.add(parsed.hostname.toLowerCase());
+  }
+  return hosts;
+}
 function hostname(host) {
   if (host.startsWith("[")) {
     const end = host.indexOf("]");

package/dist/lib/server/serve.mjs

@@ -87,13 +87,14 @@ function serve(createAgent, options) {
     );
   }
   const publicUrlOption = options?.publicUrl;
+  const allowHttpHosts = normalizeAllowHttpHosts(options?.allowHttpHosts);
   const protectedResourceOption = options?.protectedResource;
   const publicUrlIsFn = typeof publicUrlOption === "function";
   const prmIsFn = typeof protectedResourceOption === "function";
   const authenticationNeedsRawBody = authenticatorNeedsRawBody(options?.authenticate);
   let staticPublicOrigin;
   if (typeof publicUrlOption === "string") {
-    staticPublicOrigin = validatePublicUrl(publicUrlOption, mountPath);
+    staticPublicOrigin = validatePublicUrl(publicUrlOption, mountPath, allowHttpHosts);
   }
   const MAX_HOST_METADATA_CACHE_ENTRIES = 128;
   const hostMetadataCache = /* @__PURE__ */ new Map();
@@ -123,7 +124,7 @@ function serve(createAgent, options) {
     const cached = getHostMetadata(host);
     if (cached?.publicUrl !== void 0) return cached.publicUrl;
     const publicUrl = publicUrlOption(canonicalHostnameForScope(host));
-    const publicOrigin = validatePublicUrl(publicUrl, mountPath);
+    const publicOrigin = validatePublicUrl(publicUrl, mountPath, allowHttpHosts);
     updateHostMetadata(host, { publicUrl, publicOrigin });
     return publicUrl;
   };
@@ -148,6 +149,11 @@ function serve(createAgent, options) {
       "[adcp/serve] No `authenticate` configured \u2014 this agent will accept unauthenticated requests. AdCP security_baseline requires authentication in production."
     );
   }
+  if (allowHttpHosts.size > 0 && process.env.NODE_ENV === "production") {
+    console.warn(
+      "[adcp/serve] `allowHttpHosts` enables plaintext HTTP for explicitly named hosts. Remove this development-only option from production deployments."
+    );
+  }
   const explicitPreTransport = options?.preTransport;
   const protectedResourcePath = `/.well-known/oauth-protected-resource${mountPath}`;
   const httpServer = createServer(async (req, res) => {
@@ -528,7 +534,7 @@ function trimTrailingSlashes(s) {
   while (end > 0 && s.charCodeAt(end - 1) === 47) end--;
   return s.slice(0, end);
 }
-function validatePublicUrl(publicUrl, mountPath) {
+function validatePublicUrl(publicUrl, mountPath, allowHttpHosts) {
   let parsed;
   try {
     parsed = new URL(publicUrl);
@@ -539,8 +545,11 @@ function validatePublicUrl(publicUrl, mountPath) {
     throw new Error("serve(): `publicUrl` must not include username or password credentials");
   }
   const loopbackHost = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]";
-  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && loopbackHost)) {
-    throw new Error("serve(): `publicUrl` must use https (http is allowed only for loopback development URLs)");
+  const explicitlyAllowedHttpHost = allowHttpHosts.has(parsed.hostname.toLowerCase());
+  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && (loopbackHost || explicitlyAllowedHttpHost))) {
+    throw new Error(
+      "serve(): `publicUrl` must use https (http is allowed only for loopback or hosts named in `allowHttpHosts`)"
+    );
   }
   if (trimTrailingSlashes(parsed.pathname) !== trimTrailingSlashes(mountPath)) {
     throw new Error(
@@ -552,6 +561,27 @@ function validatePublicUrl(publicUrl, mountPath) {
   }
   return parsed.origin;
 }
+function normalizeAllowHttpHosts(entries) {
+  const hosts = /* @__PURE__ */ new Set();
+  for (const entry of entries ?? []) {
+    if (entry.length === 0 || entry.trim() !== entry || entry.includes("*") || entry.includes("?") || entry.includes(":")) {
+      throw new Error(
+        `serve(): invalid allowHttpHosts entry "${entry}"; use an exact hostname without whitespace, wildcards, or a port`
+      );
+    }
+    let parsed;
+    try {
+      parsed = new URL(`https://${entry}/`);
+    } catch {
+      throw new Error(`serve(): invalid allowHttpHosts entry "${entry}"; expected a hostname`);
+    }
+    if (parsed.hostname.length === 0 || parsed.username.length > 0 || parsed.password.length > 0 || parsed.port.length > 0 || parsed.pathname !== "/" || parsed.search.length > 0 || parsed.hash.length > 0) {
+      throw new Error(`serve(): invalid allowHttpHosts entry "${entry}"; expected a hostname without a port`);
+    }
+    hosts.add(parsed.hostname.toLowerCase());
+  }
+  return hosts;
+}
 function hostname(host) {
   if (host.startsWith("[")) {
     const end = host.indexOf("]");

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

@@ -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>;