@yansigit/opencodex 2.31.0

package/src/lib/pinned-http.ts

@@ -0,0 +1,270 @@
+import http, { type ClientRequest, type IncomingMessage, type RequestOptions } from "node:http";
+import https from "node:https";
+
+export type PinnedAddress = { address: string; family: number };
+
+export type PinnedHttpErrorCode =
+  | "connect_timeout"
+  | "first_byte_timeout"
+  | "inactivity_timeout"
+  | "output_byte_limit";
+
+export class PinnedHttpError extends Error {
+  override readonly name = "PinnedHttpError";
+  constructor(readonly code: PinnedHttpErrorCode, message: string) { super(message); }
+}
+
+export interface PinnedHttpRequestOptions {
+  headers?: HeadersInit;
+  maxBytes?: number;
+  /** Optional deadline for establishing the TCP connection and, for HTTPS, completing TLS. */
+  connectTimeoutMs?: number;
+  /** Optional deadline from connection establishment until response headers arrive. */
+  firstByteTimeoutMs?: number;
+  /** Optional maximum idle interval between response-body chunks. */
+  inactivityTimeoutMs?: number;
+  /** @deprecated Use firstByteTimeoutMs and inactivityTimeoutMs. */
+  idleTimeoutMs?: number;
+  rejectUnauthorized?: boolean;
+  context?: string;
+}
+
+/** @deprecated Use {@link PinnedHttpRequestOptions}. */
+export type PinnedHttpGetOptions = PinnedHttpRequestOptions;
+
+function pinnedHttpRequest(
+  url: string,
+  pinned: PinnedAddress,
+  method: "GET" | "POST",
+  body: string | undefined,
+  signal?: AbortSignal,
+  options?: PinnedHttpRequestOptions,
+): Promise<Response> {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`${options?.context ?? "request"} must use HTTP or HTTPS, got ${parsed.protocol}`);
+  }
+  const context = options?.context ?? "request";
+  const connectTimeoutMs = options?.connectTimeoutMs;
+  const legacyIdleTimeoutMs = options?.idleTimeoutMs ?? 60_000;
+  const usesLegacyIdleTimeout = options?.firstByteTimeoutMs === undefined
+    && options?.inactivityTimeoutMs === undefined;
+  const firstByteTimeoutMs = options?.firstByteTimeoutMs ?? legacyIdleTimeoutMs;
+  const inactivityTimeoutMs = options?.inactivityTimeoutMs ?? legacyIdleTimeoutMs;
+  const legacyFirstByteDisabled = usesLegacyIdleTimeout && legacyIdleTimeoutMs === 0;
+  const maxBytes = options?.maxBytes;
+  const headers = new Headers(options?.headers);
+  headers.set("host", parsed.host);
+  if (body !== undefined && !headers.has("content-length")) {
+    headers.set("content-length", String(Buffer.byteLength(body)));
+  }
+  const requestHeaders: Record<string, string> = {};
+  headers.forEach((value, key) => { requestHeaders[key] = value; });
+
+  return new Promise<Response>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
+      return;
+    }
+
+    let settled = false;
+    let req: ClientRequest | undefined;
+    let connectTimer: ReturnType<typeof setTimeout> | undefined;
+    let firstByteTimer: ReturnType<typeof setTimeout> | undefined;
+    const clearConnectTimer = () => {
+      if (connectTimer !== undefined) clearTimeout(connectTimer);
+      connectTimer = undefined;
+    };
+    const clearFirstByteTimer = () => {
+      if (firstByteTimer !== undefined) clearTimeout(firstByteTimer);
+      firstByteTimer = undefined;
+    };
+    const fail = (error: unknown) => {
+      clearConnectTimer();
+      clearFirstByteTimer();
+      try { req?.destroy(); } catch { /* ignore */ }
+      if (settled) return;
+      settled = true;
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+    const startFirstByteTimer = () => {
+      clearFirstByteTimer();
+      if (settled || legacyFirstByteDisabled) return;
+      firstByteTimer = setTimeout(
+        () => fail(new PinnedHttpError("first_byte_timeout", `${context} first byte timed out`)),
+        firstByteTimeoutMs,
+      );
+    };
+    const requestOptions: RequestOptions & { servername?: string } = {
+      protocol: parsed.protocol,
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === "https:" ? 443 : 80),
+      path: `${parsed.pathname}${parsed.search}`,
+      method,
+      headers: requestHeaders,
+      ...(parsed.protocol === "https:"
+        ? {
+          servername: parsed.hostname,
+          rejectUnauthorized: options?.rejectUnauthorized ?? true,
+        }
+        : {}),
+      lookup(_hostname, lookupOptions, callback) {
+        const opts = typeof lookupOptions === "function" ? undefined : lookupOptions;
+        const cb = typeof lookupOptions === "function" ? lookupOptions : callback;
+        if (!cb) return;
+        if (opts && typeof opts === "object" && "all" in opts && opts.all) {
+          (cb as (error: NodeJS.ErrnoException | null, addresses: PinnedAddress[]) => void)(
+            null,
+            [{ address: pinned.address, family: pinned.family }],
+          );
+          return;
+        }
+        (cb as (error: NodeJS.ErrnoException | null, address: string, family: 4 | 6) => void)(
+          null,
+          pinned.address,
+          pinned.family as 4 | 6,
+        );
+      },
+    };
+
+    const onResponse = (response: IncomingMessage) => {
+      clearConnectTimer();
+      clearFirstByteTimer();
+      const status = response.statusCode ?? 0;
+      const responseHeaders = new Headers();
+      for (const [key, value] of Object.entries(response.headers)) {
+        if (value === undefined || value === null) continue;
+        if (Array.isArray(value)) {
+          for (const item of value) responseHeaders.append(key, String(item));
+        } else {
+          responseHeaders.set(key, String(value));
+        }
+      }
+
+      if (status < 200 || status >= 300) {
+        try { response.destroy(); } catch { /* ignore */ }
+        try { req?.destroy(); } catch { /* ignore */ }
+        if (settled) return;
+        settled = true;
+        resolve(new Response(null, { status, headers: responseHeaders }));
+        return;
+      }
+
+      let received = 0;
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          let bodySettled = false;
+          const failBody = (error: Error) => {
+            if (bodySettled) return;
+            bodySettled = true;
+            try { controller.error(error); } catch { /* closed */ }
+            try { response.destroy(); } catch { /* ignore */ }
+            try { req?.destroy(); } catch { /* ignore */ }
+          };
+
+          response.setTimeout(inactivityTimeoutMs, () => {
+            failBody(new PinnedHttpError("inactivity_timeout", `${context} stalled`));
+          });
+          response.on("data", (chunk: Buffer | string) => {
+            if (bodySettled) return;
+            const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            received += buffer.byteLength;
+            if (maxBytes !== undefined && received > maxBytes) {
+              failBody(new PinnedHttpError("output_byte_limit", `${context} exceeds ${maxBytes} byte cap`));
+              return;
+            }
+            try { controller.enqueue(buffer); } catch { /* closed */ }
+          });
+          response.on("end", () => {
+            if (bodySettled) return;
+            bodySettled = true;
+            try { controller.close(); } catch { /* closed */ }
+          });
+          response.on("error", (error: Error) => {
+            failBody(error);
+          });
+        },
+        cancel() {
+          req?.destroy();
+        },
+      });
+
+      if (settled) return;
+      settled = true;
+      resolve(new Response(stream, { status, headers: responseHeaders }));
+    };
+
+    const requestFn = parsed.protocol === "https:" ? https.request : http.request;
+    req = requestFn(requestOptions, onResponse);
+    if (usesLegacyIdleTimeout) startFirstByteTimer();
+    const onAbort = () => fail(signal?.reason instanceof Error ? signal.reason : new Error("aborted"));
+    req.on("socket", (socket) => {
+      const connectedEvent = parsed.protocol === "https:" ? "secureConnect" : "connect";
+      if (!socket.connecting) {
+        if (!usesLegacyIdleTimeout) startFirstByteTimer();
+        return;
+      }
+      if (connectTimeoutMs !== undefined) {
+        connectTimer = setTimeout(
+          () => fail(new PinnedHttpError("connect_timeout", `${context} connect timed out`)),
+          connectTimeoutMs,
+        );
+      }
+      socket.once(connectedEvent, () => {
+        clearConnectTimer();
+        if (!usesLegacyIdleTimeout) startFirstByteTimer();
+      });
+      socket.once("error", () => {
+        clearConnectTimer();
+        clearFirstByteTimer();
+      });
+      socket.once("close", () => {
+        clearConnectTimer();
+        clearFirstByteTimer();
+      });
+    });
+    if (usesLegacyIdleTimeout) {
+      req.setTimeout(legacyIdleTimeoutMs, () => fail(new Error(`${context} timed out`)));
+    }
+    req.on("error", error => {
+      signal?.removeEventListener("abort", onAbort);
+      fail(error);
+    });
+    req.on("close", () => {
+      clearConnectTimer();
+      clearFirstByteTimer();
+      signal?.removeEventListener("abort", onAbort);
+    });
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted && !settled) onAbort();
+    if (settled) return;
+    req.end(body);
+  });
+}
+
+/**
+ * GET a URL through one previously validated address. The original hostname
+ * remains authoritative for Host, SNI, and certificate verification.
+ */
+export function pinnedHttpGet(
+  url: string,
+  pinned: PinnedAddress,
+  signal?: AbortSignal,
+  options?: PinnedHttpRequestOptions,
+): Promise<Response> {
+  return pinnedHttpRequest(url, pinned, "GET", undefined, signal, options);
+}
+
+/**
+ * POST a string body through one previously validated address. The original
+ * hostname remains authoritative for Host, SNI, and certificate verification.
+ */
+export function pinnedHttpPost(
+  url: string,
+  pinned: PinnedAddress,
+  body: string,
+  signal?: AbortSignal,
+  options?: PinnedHttpRequestOptions,
+): Promise<Response> {
+  return pinnedHttpRequest(url, pinned, "POST", body, signal, options);
+}

package/src/lib/privacy.ts

@@ -0,0 +1,20 @@
+export function maskEmail(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const at = value.indexOf("@");
+  if (at <= 0) return value;
+  const local = value.slice(0, at);
+  const domain = value.slice(at + 1);
+  if (!domain) return value;
+  if (local.length === 1) return `*@${domain}`;
+  if (local.length === 2) return `${local[0]}*@${domain}`;
+  return `${local[0]}***${local[local.length - 1]}@${domain}`;
+}
+
+export function maskAccountId(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const id = value.trim();
+  if (!id) return null;
+  // Short IDs would disclose the entire identifier via the suffix; use a non-identifying placeholder.
+  if (id.length <= 4) return "account-…";
+  return `account-…${id.slice(-4)}`;
+}

package/src/lib/process-control.ts

@@ -0,0 +1,168 @@
+import { execFileSync } from "node:child_process";
+import { loadConfig, readRuntimePort } from "../config";
+import { configuredAdminToken } from "./admin-secrets";
+
+export function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function waitForExit(pid: number, timeoutMs: number): boolean {
+  const deadline = Date.now() + timeoutMs;
+  const marker = new Int32Array(new SharedArrayBuffer(4));
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) return true;
+    Atomics.wait(marker, 0, 0, 50);
+  }
+  return !isProcessAlive(pid);
+}
+
+/** Injectable seams so the graceful-stop flow is unit-testable without a live proxy. */
+export interface GracefulStopIo {
+  fetchFn?: typeof fetch;
+  readRuntime?: (pid: number) => { port: number; hostname?: string } | null;
+  waitExit?: (pid: number, timeoutMs: number) => boolean;
+  env?: Record<string, string | undefined>;
+  exitTimeoutMs?: number;
+}
+
+/**
+ * Host to POST /api/stop against: follow the recorded bind hostname when it names a
+ * concrete address (a proxy bound to ::1 or a LAN IP is unreachable on 127.0.0.1);
+ * loopback aliases and wildcard binds all answer on IPv4 loopback.
+ */
+export function gracefulStopHost(hostname: string | undefined): string {
+  const trimmed = (hostname ?? "").trim();
+  const lower = trimmed.toLowerCase();
+  if (!trimmed || lower === "localhost" || trimmed === "127.0.0.1" || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]") {
+    return "127.0.0.1";
+  }
+  if (lower === "::1" || lower === "[::1]") return "[::1]";
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed;
+  return trimmed.includes(":") ? `[${trimmed}]` : trimmed;
+}
+
+/**
+ * Outcome of a graceful stop attempt. `"refused"` is distinct from failure: the proxy answered
+ * that it must NOT be stopped from here, so callers must not escalate to a forced kill.
+ */
+export type GracefulStopResult = boolean | "refused";
+
+/** A proxy declined shutdown because a service under another home owns it (HTTP 409). */
+export class ProxyOwnershipRefusedError extends Error {}
+
+/**
+ * Ask a running proxy to stop itself via the management API (`POST /api/stop`), which
+ * drains in-flight turns, restores native Codex, and cleans its pid/runtime files.
+ * This is the only way to get a GRACEFUL stop on Windows, where the POSIX
+ * SIGTERM-then-SIGKILL ladder does not exist and `taskkill /F` gives the proxy no
+ * chance to run its shutdown handlers. Returns false when the proxy can't be reached
+ * or doesn't exit in time — callers fall back to {@link killProxy}. Returns `"refused"`
+ * when the proxy declines the stop (HTTP 409), which callers must NOT force past.
+ */
+export async function stopProxyGracefully(pid: number, io: GracefulStopIo = {}): Promise<GracefulStopResult> {
+  const readRuntime = io.readRuntime ?? readRuntimePort;
+  const runtime = readRuntime(pid);
+  if (!runtime?.port) return false;
+  const env = io.env ?? process.env;
+  const headers: Record<string, string> = {};
+  const token = configuredAdminToken(env.OPENCODEX_HOME?.trim() || undefined, env as NodeJS.ProcessEnv);
+  if (token) headers["x-opencodex-api-key"] = token;
+  const fetchFn = io.fetchFn ?? fetch;
+  try {
+    const res = await fetchFn(`http://${gracefulStopHost(runtime.hostname)}:${runtime.port}/api/stop`, {
+      method: "POST",
+      headers,
+      // Hung proxies with many CLOSE_WAIT clients can be slow to accept; give them
+      // longer than a health poll so we prefer drain over taskkill /F.
+      signal: AbortSignal.timeout(io.exitTimeoutMs ? Math.min(io.exitTimeoutMs, 10_000) : 10_000),
+    });
+    // 409 is the proxy REFUSING to stop (a service installed under another home owns it and
+    // would respawn it anyway). That is a policy answer, not a dead endpoint — escalating to
+    // SIGTERM here would run the daemon's cleanup and strip shared config out from under the
+    // still-running service. Report the refusal instead of forcing.
+    if (res.status === 409) return "refused";
+    if (!res.ok) return false;
+  } catch {
+    return false;
+  }
+  const waitExit = io.waitExit ?? waitForExit;
+  // Honor the server's own drain window: /api/stop answers 200 first, then drains for
+  // config.shutdownTimeoutMs. Waiting less than that hard-kills mid-drain.
+  const exitTimeoutMs = io.exitTimeoutMs ?? drainDeadlineMs();
+  return waitExit(pid, exitTimeoutMs);
+}
+
+function drainDeadlineMs(): number {
+  try {
+    return (loadConfig().shutdownTimeoutMs ?? 5000) + 3000;
+  } catch {
+    return 8000;
+  }
+}
+
+/** Graceful-first stop: management-API drain, then the platform kill ladder. */
+export async function stopProxy(pid: number): Promise<void> {
+  if (!isProcessAlive(pid)) return;
+  const runtime = readRuntimePort(pid);
+  const graceful = await stopProxyGracefully(pid);
+  if (graceful === "refused") {
+    // The proxy refused on purpose (foreign service owns it). Forcing would strip shared
+    // config while that service keeps the proxy alive.
+    throw new ProxyOwnershipRefusedError(
+      "The running proxy refused to stop: a service installed under a different "
+      + "CODEX_HOME/OPENCODEX_HOME owns it. Run the stop from that home.",
+    );
+  }
+  if (graceful) {
+    await waitForStoppedPort(runtime, pid);
+    return;
+  }
+  killProxy(pid);
+  await waitForStoppedPort(runtime, pid);
+}
+
+/** After stop/kill, wait for the former listen port to become bindable (Windows drain). */
+async function waitForStoppedPort(
+  runtime: { port: number; hostname?: string } | null | undefined,
+  stoppedPid?: number,
+): Promise<void> {
+  if (!runtime?.port) return;
+  try {
+    const { reclaimListenPort } = await import("../server/port-reclaim");
+    await reclaimListenPort(runtime.port, runtime.hostname ?? "127.0.0.1", {
+      timeoutMs: 15_000,
+      intervalMs: 100,
+      scanIntervalMs: 500,
+      // Only the process we just stopped — never kill a newly started twin proxy.
+      killOcxHolders: !!(stoppedPid && stoppedPid > 0),
+      onlyKillPids: stoppedPid && stoppedPid > 0 ? [stoppedPid] : [],
+    });
+  } catch {
+    /* best-effort — callers that need a hard guarantee reclaim again before bind */
+  }
+}
+
+export function killProxy(pid: number): void {
+  if (!isProcessAlive(pid)) return;
+  if (process.platform === "win32") {
+    // Windows process.kill(SIGTERM/SIGINT) is TerminateProcess — not a graceful signal.
+    // Graceful drain happens only via stopProxyGracefully() (POST /api/stop). This path
+    // is the hard fallback: taskkill /T /F so the process tree exits (ghost LISTEN /
+    // CLOSE_WAIT are then cleared by reclaimListenPort / SetTcpEntry).
+    const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
+    try {
+      execFileSync(taskkill, ["/PID", String(pid), "/T", "/F"], { stdio: "pipe", windowsHide: true });
+    } catch (err) {
+      if (isProcessAlive(pid)) throw err;
+    }
+  } else {
+    process.kill(pid, "SIGTERM");
+    if (!waitForExit(pid, 5000)) process.kill(pid, "SIGKILL");
+  }
+  if (!waitForExit(pid, 5000)) throw new Error(`process ${pid} did not exit`);
+}

package/src/lib/provider-outbound.ts

@@ -0,0 +1,210 @@
+import type { OcxProviderConfig } from "../types";
+import {
+  assessUrlDestination,
+  DestinationDnsResolutionError,
+  providerAllowsPrivateNetwork,
+  providerDestinationConfigError,
+  resolvePublicAddresses,
+} from "./destination-policy";
+import { pinnedHttpGet, pinnedHttpPost } from "./pinned-http";
+import { outboundProxyConfigured } from "./proxy-env";
+import { publicProviderBaseUrl } from "./provider-url";
+
+type ProviderGetInit = Omit<RequestInit, "body" | "method" | "redirect">;
+type ProviderPostInit = ProviderGetInit & { body: string };
+type ProviderOutboundConfig = Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork"> & {
+  fetch?: typeof globalThis.fetch;
+};
+export interface ProviderOutboundDependencies {
+  resolveAddresses?: typeof resolvePublicAddresses;
+  pinnedGet?: typeof pinnedHttpGet;
+  pinnedPost?: typeof pinnedHttpPost;
+}
+
+export class ProviderOutboundPolicyError extends Error {
+  override readonly name = "ProviderOutboundPolicyError";
+}
+
+function pickPinnedAddress(addresses: Array<{ address: string; family: number }>): { address: string; family: number } {
+  return addresses.find(address => address.family === 4) ?? addresses[0]!;
+}
+
+function configuredProxyFor(): boolean {
+  return outboundProxyConfigured();
+}
+
+function normalizeProxyHostname(hostname: string): string {
+  const normalized = hostname.trim().toLowerCase().replace(/\.+$/, "");
+  return normalized.startsWith("[") && normalized.endsWith("]")
+    ? normalized.slice(1, -1)
+    : normalized;
+}
+
+function noProxyMatches(url: URL): boolean {
+  const raw = process.env.NO_PROXY ?? process.env.no_proxy ?? "";
+  const hostname = normalizeProxyHostname(url.hostname);
+  const port = url.port || (url.protocol === "https:" ? "443" : "80");
+  for (const rawEntry of raw.split(",")) {
+    let entry = rawEntry.trim().toLowerCase();
+    if (!entry) continue;
+    if (entry === "*") return true;
+    entry = entry.replace(/^https?:\/\//, "").split("/", 1)[0]!;
+
+    let entryHost = entry;
+    let entryPort = "";
+    const bracketed = /^\[([^\]]+)](?::(\d+))?$/.exec(entry);
+    if (bracketed) {
+      entryHost = bracketed[1]!;
+      entryPort = bracketed[2] ?? "";
+    } else if ((entry.match(/:/g)?.length ?? 0) === 1) {
+      const separator = entry.lastIndexOf(":");
+      const possiblePort = entry.slice(separator + 1);
+      if (/^\d+$/.test(possiblePort)) {
+        entryHost = entry.slice(0, separator);
+        entryPort = possiblePort;
+      }
+    }
+    if (entryPort && entryPort !== port) continue;
+    entryHost = normalizeProxyHostname(entryHost.replace(/^\*?\./, ""));
+    if (!entryHost) continue;
+    if (hostname === entryHost || hostname.endsWith(`.${entryHost}`)) return true;
+  }
+  return false;
+}
+
+let proxyBoundaryWarned = false;
+let proxyDnsDegradationWarned = false;
+
+function warnProxyBoundaryOnce(): void {
+  if (proxyBoundaryWarned) return;
+  proxyBoundaryWarned = true;
+  console.warn(
+    "[opencodex] Provider outbound proxy mode preserves Bun proxy/NO_PROXY routing and validates "
+    + "the URL plus available local DNS results; the final route and peer cannot be pinned locally.",
+  );
+}
+
+function warnProxyDnsDegradationOnce(): void {
+  if (proxyDnsDegradationWarned) return;
+  proxyDnsDegradationWarned = true;
+  console.warn(
+    "[opencodex] Local DNS could not resolve a proxied provider hostname; continuing after URL/literal checks. "
+    + "The proxy-selected peer cannot be verified or pinned locally.",
+  );
+}
+
+export async function providerRedirectError(response: Response, requestUrl: string): Promise<string | null> {
+  if (response.status < 300 || response.status >= 400) return null;
+  try { await response.body?.cancel(); } catch { /* ignore cancellation failures */ }
+  const location = response.headers.get("location");
+  let target = "the final upstream URL";
+  if (location) {
+    try { target = publicProviderBaseUrl(new URL(location, requestUrl).toString()); } catch { /* keep fallback */ }
+  }
+  return `provider returned ${response.status} redirect to ${target}; configure the final provider URL directly`;
+}
+
+async function providerOutboundRequest(
+  name: string,
+  provider: ProviderOutboundConfig,
+  url: string,
+  method: "GET" | "POST",
+  init: ProviderGetInit | ProviderPostInit,
+  dependencies: ProviderOutboundDependencies = {},
+): Promise<Response> {
+  const postUrl = method === "POST" ? new URL(url) : undefined;
+  if (postUrl?.protocol !== undefined && postUrl.protocol !== "https:") {
+    throw new ProviderOutboundPolicyError("provider POST URL must use HTTPS");
+  }
+  if (provider.fetch) {
+    // A caller-owned executor cannot be peer-pinned here. This branch keeps literal/config
+    // checks and redirect blocking, but does not provide the resolved-address guarantees of
+    // the built-in transport. Main-request migration must define that executor contract first.
+    const assessment = assessUrlDestination(url);
+    if (assessment?.kind === "metadata" || assessment?.kind === "link-local" || assessment?.kind === "unspecified") {
+      throw new ProviderOutboundPolicyError(`provider URL targets ${assessment.detail}`);
+    }
+    // Registry defaults count here too, not just the operator flag: a stock Ollama entry is
+    // local by definition and previously passed config validation only to be refused at the
+    // fetch (#758). Metadata/link-local/unspecified were already rejected above.
+    const allowPrivate = providerAllowsPrivateNetwork(name, provider);
+    if (!allowPrivate) {
+      const destinationError = providerDestinationConfigError(name, {
+        baseUrl: url,
+        allowPrivateNetwork: false,
+      });
+      if (destinationError) throw new ProviderOutboundPolicyError(destinationError);
+    }
+    return provider.fetch(url, { ...init, method, redirect: "manual" });
+  }
+  const parsed = postUrl ?? new URL(url);
+  const proxyConfigured = configuredProxyFor();
+  const resolveAddresses = dependencies.resolveAddresses ?? resolvePublicAddresses;
+  const pinnedGet = dependencies.pinnedGet ?? pinnedHttpGet;
+  const pinnedPost = dependencies.pinnedPost ?? pinnedHttpPost;
+  const allowPrivate = providerAllowsPrivateNetwork(name, provider);
+  let resolved: Awaited<ReturnType<typeof resolvePublicAddresses>>;
+  try {
+    resolved = await resolveAddresses(url, {
+      context: "provider URL",
+      allowPrivateNetwork: allowPrivate,
+      // Clash/Surge/Mihomo fake-IP DNS (198.18.0.0/15) answers are admitted only
+      // when this exact host will use the configured outbound proxy: the hostname
+      // then rides the proxy as an ordinary CONNECT instead of failing as a private
+      // destination or being pin-connected to the fake-IP (credit #1748). A NO_PROXY
+      // match is a direct route, so it keeps the benchmark answer rejected. Image/Lab
+      // fetch never passes this flag.
+      allowBenchmarkAddresses: proxyConfigured && !noProxyMatches(parsed),
+    });
+  } catch (error) {
+    const dnsResolutionFailed = error instanceof DestinationDnsResolutionError
+      || (error instanceof Error && error.name === "DestinationDnsResolutionError");
+    if (!dnsResolutionFailed) {
+      throw new ProviderOutboundPolicyError(error instanceof Error ? error.message : "provider destination was blocked");
+    }
+    if (!proxyConfigured) throw error;
+    warnProxyBoundaryOnce();
+    warnProxyDnsDegradationOnce();
+    return globalThis.fetch(url, { ...init, method, redirect: "manual" });
+  }
+  if (proxyConfigured && !resolved.privateNetwork) {
+    warnProxyBoundaryOnce();
+    return globalThis.fetch(url, { ...init, method, redirect: "manual" });
+  }
+  if (proxyConfigured && resolved.privateNetwork && !noProxyMatches(parsed)) {
+    const hostname = normalizeProxyHostname(parsed.hostname);
+    throw new Error(
+      `provider URL resolves to a private-network destination; add ${hostname} to NO_PROXY before using allowPrivateNetwork with an outbound proxy`,
+    );
+  }
+  const requestOptions = {
+    headers: init.headers,
+    rejectUnauthorized: true,
+    context: "provider response",
+  };
+  const pinned = pickPinnedAddress(resolved.addresses);
+  if (method === "POST") {
+    return pinnedPost(url, pinned, (init as ProviderPostInit).body, init.signal ?? undefined, requestOptions);
+  }
+  return pinnedGet(url, pinned, init.signal ?? undefined, requestOptions);
+}
+
+export async function providerOutboundGet(
+  name: string,
+  provider: ProviderOutboundConfig,
+  url: string,
+  init: ProviderGetInit = {},
+  dependencies: ProviderOutboundDependencies = {},
+): Promise<Response> {
+  return providerOutboundRequest(name, provider, url, "GET", init, dependencies);
+}
+
+export async function providerOutboundPost(
+  name: string,
+  provider: ProviderOutboundConfig,
+  url: string,
+  init: ProviderPostInit,
+  dependencies: ProviderOutboundDependencies = {},
+): Promise<Response> {
+  return providerOutboundRequest(name, provider, url, "POST", init, dependencies);
+}

package/src/lib/provider-url.ts

@@ -0,0 +1,14 @@
+/** Strip credentials and non-routing URL components before displaying a provider URL. */
+export function publicProviderBaseUrl(baseUrl: string): string {
+  try {
+    const parsed = new URL(baseUrl.trim());
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return "(invalid URL)";
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString().replace(/\/$/, baseUrl.endsWith("/") ? "/" : "");
+  } catch {
+    return "(invalid URL)";
+  }
+}