@iislee/opencodex 2.11.0

package/src/lib/debug-log-buffer.ts

@@ -0,0 +1,83 @@
+/** In-memory ring buffer of debug log lines for `ocx debug logs` / GUI tailing. */
+
+export interface DebugLogEntry {
+  /** Monotonic cursor for pagination; survives same-millisecond bursts. */
+  seq: number;
+  at: number;
+  line: string;
+}
+
+const MAX_LINES = 2_000;
+const MAX_DEBUG_SUBSCRIBERS = 64;
+const MAX_DEBUG_LINE_BYTES = 16 * 1024;
+const buffer: DebugLogEntry[] = [];
+interface DebugSubscriberRegistration { lease: AdmissionLease }
+const listeners = new Map<(entry: DebugLogEntry) => void, DebugSubscriberRegistration>();
+const subscriberGate = createAdmissionGate("debug_subscribers", MAX_DEBUG_SUBSCRIBERS);
+let nextSeq = 1;
+let bufferBytes = 0;
+
+function removeOldestEntry(): number {
+  const entry = buffer.shift();
+  if (!entry) return 0;
+  const bytes = retainedUtf8Bytes(entry.line);
+  bufferBytes -= bytes;
+  return bytes;
+}
+
+export function appendDebugLogLine(line: string): void {
+  const retainedLine = truncateRetainedUtf8(line, MAX_DEBUG_LINE_BYTES);
+  const entry: DebugLogEntry = { seq: nextSeq++, at: Date.now(), line: retainedLine };
+  buffer.push(entry);
+  bufferBytes += retainedUtf8Bytes(retainedLine);
+  while (buffer.length > MAX_LINES) removeOldestEntry();
+  enforceAppOwnedMemoryBudget();
+  for (const listener of listeners.keys()) {
+    try { listener(entry); } catch { /* listeners must not break logging */ }
+  }
+}
+
+export function getDebugLogEntries(options?: { after?: number; limit?: number }): DebugLogEntry[] {
+  const after = options?.after ?? 0;
+  const limit = options?.limit ?? 500;
+  const filtered = after > 0 ? buffer.filter(entry => entry.seq > after) : buffer;
+  if (filtered.length <= limit) return filtered;
+  return filtered.slice(-limit);
+}
+
+export function subscribeDebugLogEntries(listener: (entry: DebugLogEntry) => void): () => void {
+  let registration = listeners.get(listener);
+  if (!registration) {
+    const lease = subscriberGate.tryAcquire();
+    if (!lease) throw new ResourceAdmissionError("debug_subscribers", MAX_DEBUG_SUBSCRIBERS);
+    registration = { lease };
+    listeners.set(listener, registration);
+  }
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    if (listeners.get(listener) !== registration) return;
+    listeners.delete(listener);
+    registration.lease.release();
+  };
+}
+
+export function debugBufferMetrics(): { entries: number; bytes: number; subscribers: AdmissionMetrics; oldestAt: number | null } {
+  return { entries: buffer.length, bytes: bufferBytes, subscribers: subscriberGate.metrics(), oldestAt: buffer[0]?.at ?? null };
+}
+
+export function evictOldestDebugEntryForBudget(): number {
+  return removeOldestEntry();
+}
+
+/** Test isolation. */
+export function resetDebugLogBufferForTests(): void {
+  buffer.length = 0;
+  bufferBytes = 0;
+  for (const registration of listeners.values()) registration.lease.release();
+  listeners.clear();
+  nextSeq = 1;
+}
+import { createAdmissionGate, ResourceAdmissionError, retainedUtf8Bytes, truncateRetainedUtf8, type AdmissionLease, type AdmissionMetrics } from "./admission";
+import { enforceAppOwnedMemoryBudget } from "./app-owned-memory";

package/src/lib/debug-settings.ts

@@ -0,0 +1,108 @@
+/**
+ * Runtime-controllable debug flags.
+ * Provider debug: `ocx debug provider on|off|status|reset|logs [-f]` (or OCX_DEBUG=1 on start).
+ * Usage capture: `ocx debug usage on|off|status|reset|logs [-f]` (or OPENCODEX_USAGE_DEBUG=1).
+ * Injection log: `ocx debug injection on|off|status|reset` (or OCX_INJECTION_DEBUG=1) —
+ * multi-agent guidance-injection console lines, default OFF.
+ * Claude inbound capture: `ocx debug claude on|off|status|reset` (or OCX_CLAUDE_DEBUG=1) —
+ * allowlist-scalar ring of inbound Anthropic request metadata, default OFF.
+ * `/api/debug` and `ocx debug` override env defaults without restart.
+ */
+
+export const DEBUG_ENV = {
+  debug: "OCX_DEBUG",
+  usage: "OPENCODEX_USAGE_DEBUG",
+  injection: "OCX_INJECTION_DEBUG",
+  claude: "OCX_CLAUDE_DEBUG",
+} as const;
+
+/** Legacy env var that still enables provider debug logging. */
+const LEGACY_DEBUG_ENV = ["OCX_DEBUG_FRAMES"] as const;
+
+export type DebugFlag = keyof typeof DEBUG_ENV;
+
+export interface DebugSettingsView {
+  enabled: boolean;
+  usage: boolean;
+  injection: boolean;
+  claude: boolean;
+  runtimeOverride: Partial<Record<DebugFlag, boolean>>;
+  env: Record<DebugFlag, boolean>;
+}
+
+const runtimeOverride: Partial<Record<DebugFlag, boolean>> = {};
+
+function envFlag(name: string): boolean {
+  return process.env[name] === "1";
+}
+
+function legacyDebugEnvEnabled(): boolean {
+  return LEGACY_DEBUG_ENV.some(name => envFlag(name));
+}
+
+export function isDebugEnabled(): boolean {
+  if (runtimeOverride.debug !== undefined) return runtimeOverride.debug;
+  return envFlag(DEBUG_ENV.debug) || legacyDebugEnvEnabled();
+}
+
+/** @deprecated Use isDebugEnabled(). */
+export function isFramesDebugEnabled(): boolean {
+  return isDebugEnabled();
+}
+
+export function isUsageDebugEnabled(): boolean {
+  if (runtimeOverride.usage !== undefined) return runtimeOverride.usage;
+  return envFlag(DEBUG_ENV.usage);
+}
+
+/** Multi-agent guidance-injection log lines (default OFF; GUI checkbox / API / CLI). */
+export function isInjectionDebugEnabled(): boolean {
+  if (runtimeOverride.injection !== undefined) return runtimeOverride.injection;
+  return envFlag(DEBUG_ENV.injection);
+}
+
+/** Claude inbound request capture (default OFF; GUI toggle / API / CLI). */
+export function isClaudeDebugEnabled(): boolean {
+  if (runtimeOverride.claude !== undefined) return runtimeOverride.claude;
+  return envFlag(DEBUG_ENV.claude);
+}
+
+export function getDebugSettings(): DebugSettingsView {
+  return {
+    enabled: isDebugEnabled(),
+    usage: isUsageDebugEnabled(),
+    injection: isInjectionDebugEnabled(),
+    claude: isClaudeDebugEnabled(),
+    runtimeOverride: { ...runtimeOverride },
+    env: {
+      debug: envFlag(DEBUG_ENV.debug) || legacyDebugEnvEnabled(),
+      usage: envFlag(DEBUG_ENV.usage),
+      injection: envFlag(DEBUG_ENV.injection),
+      claude: envFlag(DEBUG_ENV.claude),
+    },
+  };
+}
+
+export function setDebugSettings(partial: Partial<Record<DebugFlag, boolean>>): DebugSettingsView {
+  for (const key of ["debug", "usage", "injection", "claude"] as const) {
+    if (partial[key] !== undefined) runtimeOverride[key] = partial[key];
+  }
+  return getDebugSettings();
+}
+
+export function clearDebugSetting(flag: DebugFlag): DebugSettingsView {
+  delete runtimeOverride[flag];
+  return getDebugSettings();
+}
+
+export function clearDebugSettings(): DebugSettingsView {
+  for (const key of ["debug", "usage", "injection", "claude"] as const) {
+    delete runtimeOverride[key];
+  }
+  return getDebugSettings();
+}
+
+/** Test isolation: drop runtime overrides only (env vars untouched). */
+export function resetDebugSettingsForTests(): void {
+  clearDebugSettings();
+}

package/src/lib/debug.ts

@@ -0,0 +1,31 @@
+import { appendDebugLogLine } from "./debug-log-buffer";
+import { isDebugEnabled } from "./debug-settings";
+import { redactSecrets } from "./redact";
+
+function emitDebugLine(line: string): void {
+  if (!isDebugEnabled()) return;
+  try {
+    appendDebugLogLine(line);
+    console.error(line);
+  } catch {
+    /* diagnostics must never affect request handling */
+  }
+}
+
+// Opt-in provider diagnostics. Streaming adapters stay quiet unless provider debug is on
+// (`ocx debug provider on`, GUI Logs toggle, or OCX_DEBUG=1). Tail with `ocx debug provider logs -f`.
+
+export function debugDroppedFrame(adapter: string, payload: string): void {
+  if (!isDebugEnabled()) return;
+  emitDebugLine(`[ocx:frame-drop] ${adapter}: dropped malformed upstream frame (payload redacted, bytes=${payload.length})`);
+}
+
+/** Provider-agnostic diagnostic logging: `[ocx:<adapter>:<event>] {...}`. */
+export function debugProviderDiagnostic(adapter: string, event: string, details: Record<string, unknown>): void {
+  if (!isDebugEnabled()) return;
+  try {
+    emitDebugLine(`[ocx:${adapter}:${event}] ${JSON.stringify(redactSecrets(details))}`);
+  } catch {
+    /* diagnostics must never affect request handling */
+  }
+}

package/src/lib/destination-policy.ts

@@ -0,0 +1,316 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { getProviderRegistryEntry } from "../providers/registry";
+import type { OcxProviderConfig } from "../types";
+
+const BLOCKED_METADATA_HOSTS = new Set([
+  "instance-data.ec2.internal",
+  "metadata.azure.internal",
+  "metadata.google.internal",
+]);
+
+const BLOCKED_METADATA_IPV4 = new Set([
+  "100.100.100.200",
+  "169.254.169.254",
+  "169.254.170.2",
+]);
+
+const BLOCKED_METADATA_IPV6 = new Set([
+  "fd00:ec2::254",
+]);
+
+export type DestinationKind =
+  | "public"
+  | "hostname"
+  | "localhost"
+  | "loopback"
+  | "private"
+  | "link-local"
+  | "unspecified"
+  | "metadata";
+
+interface DestinationAssessment {
+  kind: DestinationKind;
+  detail: string;
+}
+
+function normalizeHostname(hostname: string): string {
+  const trimmed = hostname.trim().toLowerCase().replace(/\.+$/, "");
+  return trimmed.startsWith("[") && trimmed.endsWith("]") ? trimmed.slice(1, -1) : trimmed;
+}
+
+function parseIpv4(hostname: string): number[] | null {
+  const parts = hostname.split(".");
+  if (parts.length !== 4) return null;
+  const octets = parts.map(part => Number(part));
+  return octets.every(octet => Number.isInteger(octet) && octet >= 0 && octet <= 255) ? octets : null;
+}
+
+function classifyIpv4(hostname: string): DestinationAssessment {
+  if (BLOCKED_METADATA_IPV4.has(hostname)) return { kind: "metadata", detail: "blocked metadata endpoint" };
+  const octets = parseIpv4(hostname);
+  if (!octets) return { kind: "public", detail: "public IP" };
+  const [a, b, c] = octets;
+  if (a === 127) return { kind: "loopback", detail: "loopback address" };
+  if (a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127)) {
+    return { kind: "private", detail: "private-network address" };
+  }
+  if (a === 169 && b === 254) return { kind: "link-local", detail: "link-local address" };
+  if (a === 0) return { kind: "unspecified", detail: "unspecified address" };
+  // Reserved / non-public ranges (review finding, PR #96): protocol-assignment,
+  // documentation, benchmark, multicast, and reserved-future space never name a
+  // legitimate provider endpoint.
+  if (a === 192 && b === 0 && (c === 0 || c === 2)) return { kind: "private", detail: "reserved address" };
+  if (a === 198 && (b === 18 || b === 19)) return { kind: "private", detail: "benchmark address" };
+  if (a === 198 && b === 51 && c === 100) return { kind: "private", detail: "documentation address" };
+  if (a === 203 && b === 0 && c === 113) return { kind: "private", detail: "documentation address" };
+  if (a >= 224) return { kind: "private", detail: "multicast/reserved address" };
+  return { kind: "public", detail: "public IP" };
+}
+
+function firstIpv6Hextet(hostname: string): number | null {
+  const head = hostname.split(":")[0];
+  if (!head) return 0;
+  const parsed = Number.parseInt(head, 16);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+function classifyIpv6(hostname: string): DestinationAssessment {
+  if (BLOCKED_METADATA_IPV6.has(hostname)) return { kind: "metadata", detail: "blocked metadata endpoint" };
+  const mappedIpv4 = hostname.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i)?.[1];
+  if (mappedIpv4) return classifyIpv4(mappedIpv4);
+  // Decode hex IPv4-mapped IPv6: ::ffff:7f00:1 → 127.0.0.1
+  // The dotted-decimal regex above only matches ::ffff:127.0.0.1; without this,
+  // hex form bypasses all private/loopback checks (hextet is 0 → classified "public").
+  const hexMapped = hostname.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+  if (hexMapped) {
+    const hi = Number.parseInt(hexMapped[1], 16);
+    const lo = Number.parseInt(hexMapped[2], 16);
+    const ipv4 = `${(hi >> 8) & 255}.${hi & 255}.${(lo >> 8) & 255}.${lo & 255}`;
+    return classifyIpv4(ipv4);
+  }
+  if (hostname === "::1") return { kind: "loopback", detail: "loopback address" };
+  if (hostname === "::") return { kind: "unspecified", detail: "unspecified address" };
+  const hextet = firstIpv6Hextet(hostname);
+  if (hextet === null) return { kind: "private", detail: "non-global address" };
+  // Multicast ff00::/8, deprecated site-local fec0::/10, ULA fc00::/7, link-local fe80::/10.
+  if (hextet >= 0xff00) return { kind: "private", detail: "multicast address" };
+  if (hextet >= 0xfe80 && hextet <= 0xfebf) return { kind: "link-local", detail: "link-local address" };
+  if (hextet >= 0xfec0 && hextet <= 0xfeff) return { kind: "private", detail: "site-local address" };
+  if (hextet >= 0xfc00 && hextet <= 0xfdff) return { kind: "private", detail: "private-network address" };
+  // Documentation 2001:db8::/32 (inside global-unicast 2000::/3).
+  if (hextet === 0x2001) {
+    const second = Number.parseInt(hostname.split(":")[1] || "0", 16);
+    if (second === 0xdb8) return { kind: "private", detail: "documentation address" };
+  }
+  // Only global unicast 2000::/3 is treated as a public image/CDN peer.
+  if (hextet >= 0x2000 && hextet <= 0x3fff) return { kind: "public", detail: "public IP" };
+  return { kind: "private", detail: "non-global address" };
+}
+
+function assessDestination(baseUrl: string): DestinationAssessment | null {
+  try {
+    const parsed = new URL(baseUrl.trim());
+    const hostname = normalizeHostname(parsed.hostname);
+    if (!hostname) return null;
+    if (BLOCKED_METADATA_HOSTS.has(hostname)) return { kind: "metadata", detail: "blocked metadata endpoint" };
+    if (hostname === "localhost" || hostname.endsWith(".localhost")) {
+      return { kind: "localhost", detail: "localhost destination" };
+    }
+    const ipKind = isIP(hostname);
+    if (ipKind === 4) return classifyIpv4(hostname);
+    if (ipKind === 6) return classifyIpv6(hostname);
+    return { kind: "hostname", detail: "hostname destination" };
+  } catch {
+    return null;
+  }
+}
+
+function registryAllowsPrivateNetwork(name: string): boolean {
+  return getProviderRegistryEntry(name)?.allowPrivateNetworkByDefault === true;
+}
+
+/**
+ * Whether a provider may reach loopback/private addresses.
+ *
+ * Two sources, and both have to be consulted at every boundary: the operator's explicit
+ * `allowPrivateNetwork`, and the registry's `allowPrivateNetworkByDefault` for entries that are
+ * local BY DEFINITION (Ollama, vLLM, LM Studio, LiteLLM). Config validation already read both;
+ * outbound discovery read only the first, so a stock Ollama entry passed validation and was then
+ * refused at the fetch (#758).
+ *
+ * This grants nothing new. Metadata, link-local and unspecified destinations are rejected before
+ * this is consulted, and a provider without either source still cannot reach a private address.
+ */
+export function providerAllowsPrivateNetwork(
+  name: string,
+  provider: Pick<OcxProviderConfig, "allowPrivateNetwork">,
+): boolean {
+  return provider.allowPrivateNetwork === true || registryAllowsPrivateNetwork(name);
+}
+
+export function providerDestinationConfigError(name: string, provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">): string | null {
+  const assessment = assessDestination(provider.baseUrl);
+  if (!assessment) return null;
+  if (assessment.kind === "public" || assessment.kind === "hostname") return null;
+  if (assessment.kind === "metadata") return "baseUrl targets a blocked metadata endpoint";
+  if (providerAllowsPrivateNetwork(name, provider)) return null;
+  return `baseUrl points to a ${assessment.detail}; set allowPrivateNetwork:true only for intentionally local/self-hosted providers`;
+}
+
+export function assertProviderDestinationAllowed(name: string, provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">): void {
+  const error = providerDestinationConfigError(name, provider);
+  if (error) throw new Error(`provider ${name} ${error}`);
+}
+
+/**
+ * Async companion to {@link providerDestinationConfigError} for hostname destinations:
+ * resolves A/AAAA records and classifies every address, so a hostname that points at
+ * loopback/private/metadata space is caught at provider write time (review finding,
+ * PR #96 — the sync path must stay literal-only because the router hot path and
+ * config load are synchronous). DNS failures return null: config-time validation is
+ * advisory and must not hard-fail offline startups. DNS rebinding after validation is
+ * a recorded residual for this loopback proxy (devlog 260712_pr_batch_landing 000).
+ *
+ * `allowBenchmarkAddresses` is only for the exact canonical ChatGPT Codex seed under
+ * Clash fake-IP DNS (198.18.0.0/15). Every other non-public answer — including mixed
+ * benchmark + private/metadata sets — still fails.
+ */
+export async function providerDestinationResolvedError(
+  name: string,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">,
+  options?: { allowBenchmarkAddresses?: boolean },
+): Promise<string | null> {
+  const syncError = providerDestinationConfigError(name, provider);
+  if (syncError) return syncError;
+  let hostname: string;
+  try {
+    hostname = normalizeHostname(new URL(provider.baseUrl.trim()).hostname);
+  } catch {
+    return null;
+  }
+  if (!hostname || isIP(hostname) !== 0 || hostname === "localhost" || hostname.endsWith(".localhost")) {
+    return null; // literals and localhost are fully handled by the sync path
+  }
+  if (providerAllowsPrivateNetwork(name, provider)) return null;
+  let addresses: { address: string }[];
+  try {
+    addresses = await lookup(hostname, { all: true, verbatim: true });
+  } catch {
+    return null; // unresolvable now ≠ malicious; the provider simply won't connect
+  }
+  for (const { address } of addresses) {
+    const ipKind = isIP(address);
+    const assessment = ipKind === 4 ? classifyIpv4(address) : ipKind === 6 ? classifyIpv6(normalizeHostname(address)) : null;
+    if (!assessment || assessment.kind === "public") continue;
+    // Clash fake-IP only: 198.18/19 benchmark detail. Mixed dangerous sets still reject.
+    if (
+      options?.allowBenchmarkAddresses
+      && assessment.kind === "private"
+      && assessment.detail === "benchmark address"
+    ) {
+      continue;
+    }
+    if (assessment.kind === "metadata") return `baseUrl hostname ${hostname} resolves to a blocked metadata endpoint (${address})`;
+    return `baseUrl hostname ${hostname} resolves to a ${assessment.detail} (${address}); set allowPrivateNetwork:true only for intentionally local/self-hosted providers`;
+  }
+  return null;
+}
+
+export interface UrlDestinationAssessment {
+  kind: DestinationKind;
+  detail: string;
+}
+
+export class DestinationDnsResolutionError extends Error {
+  override readonly name = "DestinationDnsResolutionError";
+}
+
+/**
+ * Synchronous literal URL destination assessment — classifies the hostname
+ * without DNS resolution. Returns null for unparseable URLs.
+ */
+export function assessUrlDestination(url: string): UrlDestinationAssessment | null {
+  return assessDestination(url);
+}
+
+/**
+ * Async DNS-resolved URL safety check. By default, rejects every non-public
+ * address. Provider diagnostics may explicitly admit loopback/private answers;
+ * metadata, link-local, and unspecified addresses remain unconditionally denied.
+ * Returns the validated addresses so direct callers can pin the connect peer and
+ * avoid a second, rebindable resolution. DNS failures remain fail-closed here;
+ * the provider proxy wrapper alone may recognize that typed failure and degrade.
+ */
+export async function resolvePublicAddresses(
+  url: string,
+  options?: string | { context?: string; allowPrivateNetwork?: boolean },
+): Promise<{
+  hostname: string;
+  addresses: { address: string; family: number }[];
+  privateNetwork: boolean;
+}> {
+  const context = typeof options === "string"
+    ? `${options.trim() || "image"} URL`
+    : options?.context?.trim() || "image URL";
+  const privateNetworkAllowed = typeof options === "object" && options?.allowPrivateNetwork === true;
+  let hostname: string;
+  try {
+    hostname = normalizeHostname(new URL(url.trim()).hostname);
+  } catch {
+    throw new Error(`${context} is not a valid URL`);
+  }
+  if (!hostname) throw new Error(`${context} has no hostname`);
+  const literalAssessment = assessDestination(url);
+  let privateNetwork = false;
+  if (literalAssessment && literalAssessment.kind !== "public" && literalAssessment.kind !== "hostname") {
+    const allowedPrivateLiteral = privateNetworkAllowed
+      && (literalAssessment.kind === "localhost"
+        || literalAssessment.kind === "loopback"
+        || literalAssessment.kind === "private");
+    if (!allowedPrivateLiteral) throw new Error(`${context} targets ${literalAssessment.detail}`);
+    privateNetwork = true;
+  }
+  // Literal public IPs: no DNS round-trip; pin the literal itself.
+  const literalKind = isIP(hostname);
+  if (literalKind !== 0) {
+    return { hostname, addresses: [{ address: hostname, family: literalKind }], privateNetwork };
+  }
+  let addresses: { address: string; family: number }[];
+  try {
+    addresses = await lookup(hostname, { all: true, verbatim: true });
+  } catch {
+    // If DNS fails, we can't verify — fail-closed (unlike provider config-time validation,
+    // this is a runtime fetch to an untrusted URL, so be conservative).
+    throw new DestinationDnsResolutionError(`${context} hostname ${hostname} could not be resolved`);
+  }
+  if (addresses.length === 0) {
+    throw new DestinationDnsResolutionError(`${context} hostname ${hostname} could not be resolved`);
+  }
+  const validatedAddresses: { address: string; family: number }[] = [];
+  for (const { address, family } of addresses) {
+    // Prefer classifying from the address string itself — do not trust a mislabeled
+    // resolver `family` that could skip IPv4/IPv6 private checks.
+    const ipKind = isIP(address) || (family === 4 || family === 6 ? family : 0);
+    const assessment = ipKind === 4 ? classifyIpv4(address) : ipKind === 6 ? classifyIpv6(normalizeHostname(address)) : null;
+    if (!assessment || assessment.kind !== "public") {
+      const allowedPrivateAddress = privateNetworkAllowed
+        && assessment
+        && (assessment.kind === "loopback" || assessment.kind === "private");
+      if (!allowedPrivateAddress) {
+        throw new Error(`${context} hostname ${hostname} resolves to ${assessment?.detail ?? "an unsafe address"} (${address})`);
+      }
+      privateNetwork = true;
+    }
+    validatedAddresses.push({ address, family: ipKind === 4 || ipKind === 6 ? ipKind : (family || 4) });
+  }
+  return { hostname, addresses: validatedAddresses, privateNetwork };
+}
+
+/**
+ * Void assertion wrapper around {@link resolvePublicAddresses} for call sites
+ * that only need the safety check.
+ */
+export async function assertUrlResolvesPublic(url: string): Promise<void> {
+  await resolvePublicAddresses(url);
+}