@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/lib/lab-live-pinned-sender.ts

@@ -1,10 +1,32 @@
-import { PinnedHttpError, pinnedHttpGet, pinnedHttpPost } from "./pinned-http";
+import { PinnedHttpError, pinnedHttpGet, pinnedHttpPost, type PinnedHttpErrorCode } from "./pinned-http";
 import { TransportError } from "../lab/live/transport";
-import type { LabCredentialLeaseV1, LabPinnedSender } from "../lab/live/types";
+import type { LabCredentialLeaseV1, LabPinnedSender, TransportErrorCode } from "../lab/live/types";
 
 /** Only response metadata required by current live assertions crosses into Lab. */
 const LAB_RESPONSE_HEADER_ALLOWLIST = ["content-type"] as const;
 
+/**
+ * Every pinned-transport failure code, mapped to the Lab transport taxonomy or to nothing.
+ *
+ * A switch over the codes that existed when it was written silently let later ones fall through
+ * to a raw rethrow. That is not the same as leaving them unclassified: Lab's executor turns an
+ * unrecognized error into `harness_failure` / `execution_error`, so a response the peer coded
+ * in a format this transport cannot undo was reported as a fault of the runner. Both unreadable
+ * answers therefore carry `unreadable_response`, which Lab classifies as a protocol failure.
+ * A total map keeps a future code from acquiring that misattribution by default.
+ */
+const LAB_TRANSPORT_FAILURES = {
+  connect_timeout: { code: "connect_timeout", message: "pinned provider connection timed out" },
+  first_byte_timeout: { code: "first_byte_timeout", message: "pinned provider first byte timed out" },
+  inactivity_timeout: { code: "inactivity_timeout", message: "pinned provider response stalled" },
+  output_byte_limit: { code: "output_byte_limit", message: "pinned provider response exceeded byte budget" },
+  content_decode_failed: { code: "unreadable_response", message: "pinned provider response did not decode" },
+  unsupported_content_encoding: {
+    code: "unreadable_response",
+    message: "pinned provider used a content-encoding this transport cannot decode",
+  },
+} satisfies Record<PinnedHttpErrorCode, { code: TransportErrorCode; message: string }>;
+
 /**
  * Trusted credential/transport owner. Secret headers exist only in this non-Lab module and are
  * consumed directly by the pinned HTTP primitive; they are never returned to Lab code.
@@ -33,16 +55,8 @@ export function createLabAuthorizedPinnedSender(
       body = await response.text();
     } catch (error) {
       if (error instanceof PinnedHttpError) {
-        switch (error.code) {
-          case "connect_timeout":
-            throw new TransportError("connect_timeout", "pinned provider connection timed out");
-          case "first_byte_timeout":
-            throw new TransportError("first_byte_timeout", "pinned provider first byte timed out");
-          case "inactivity_timeout":
-            throw new TransportError("inactivity_timeout", "pinned provider response stalled");
-          case "output_byte_limit":
-            throw new TransportError("output_byte_limit", "pinned provider response exceeded byte budget");
-        }
+        const mapped = LAB_TRANSPORT_FAILURES[error.code];
+        throw new TransportError(mapped.code, mapped.message);
       }
       throw error;
     }

package/src/lib/local-destinations.ts

@@ -21,7 +21,8 @@
  *   loopback listener enabled   → `127.0.0.1:<effective listener port>`, no credential
  *   loopback/absent `hostname`  → `127.0.0.1:<public port>`, no credential
  *   wildcard `hostname`         → `127.0.0.1:<public port>`, ADMISSION CREDENTIAL REQUIRED
- *   anything else               → `<probeHostname(hostname)>:<public port>`, credential REQUIRED
+ *   literal non-loopback IP     → `<probeHostname(hostname)>:<public port>`, credential REQUIRED
+ *   DNS bind name               → `127.0.0.1:<public port>`, credential REQUIRED (fail closed)
  *
  * A wildcard bind does answer on 127.0.0.1, which is why its origin stays loopback, but the
  * public listener demands data-plane admission regardless of which address received the
@@ -36,6 +37,7 @@
  * token: no exported client configuration may carry management authority (reviewer constraint
  * on #4236).
  */
+import { isIP } from "node:net";
 import { effectiveLoopbackListenerPort, isLoopbackHostname, isWildcardHostname, shouldInjectApiAuthHeader } from "../codex/loopback-target";
 import { probeHostname } from "../server/proxy-liveness";
 import { loadServiceTokenFromFile, serviceApiTokenFilePath } from "./service-secrets";
@@ -59,6 +61,31 @@ export interface LocalInferenceDestination {
   requiresAdmissionToken: boolean;
 }
 
+/**
+ * Turn a bind setting into an address that is safe to combine with local credentials.
+ *
+ * Bun resolves a DNS bind name when the listener starts, but a later client lookup can receive
+ * a different answer. Local integrations therefore use only literal addresses; a DNS bind falls
+ * back to loopback and fails closed when the listener does not answer there. Operators who need
+ * local integrations on a DNS-bound listener can enable the dedicated loopback listener.
+ *
+ * `localhost` is deliberately NOT treated as a DNS bind here, even though it is a name. It is
+ * reserved to loopback by RFC 6761, so a second lookup cannot select a peer off this machine —
+ * the thing this function exists to prevent. Rewriting it to `127.0.0.1` would buy no safety and
+ * would change what every existing loopback install writes into its exported client
+ * configuration, which is a contract `tests/claude-integration/claude-cli.test.ts` pins.
+ * `isLoopbackHostname` is the existing encoding of "this name is loopback", so the two stay in
+ * agreement by construction rather than by a second list.
+ */
+export function localCredentialDestinationHostname(hostname: string | undefined): string {
+  const probed = probeHostname(hostname);
+  if (isLoopbackHostname(probed)) return probed;
+  const literal = probed.startsWith("[") && probed.endsWith("]")
+    ? probed.slice(1, -1)
+    : probed;
+  return isIP(literal) !== 0 ? probed : "127.0.0.1";
+}
+
 /**
  * The one answer for "where does a local client send inference, and does it need a key?".
  *
@@ -85,7 +112,7 @@ export function localInferenceDestination(
   // literal; `shouldInjectApiAuthHeader` is the existing encoding of "this bind demands a
   // data-plane credential", so the two stay in agreement by construction.
   return {
-    origin: `http://${probeHostname(hostname)}:${publicPort}`,
+    origin: `http://${localCredentialDestinationHostname(hostname)}:${publicPort}`,
     port: publicPort,
     requiresAdmissionToken: shouldInjectApiAuthHeader(config),
   };
@@ -146,8 +173,8 @@ const ADMISSION_TOKEN_SHAPE = /^[A-Za-z0-9._~+/=-]{8,4096}$/;
  *
  * A hub's management ingress is loopback-only and exists precisely so the operator's own
  * machine has a management address when the proxy listener is bound elsewhere. Everything else
- * keeps dialing the public listener on the bind address it can actually reach — `probeHostname`
- * turns a wildcard bind into 127.0.0.1 and brackets a bare IPv6 literal.
+ * keeps dialing a literal public bind address it can actually reach. DNS bind names fail closed
+ * to loopback because resolving them again could select a different peer after startup.
  *
  * The caller still supplies the management credential. Never write that credential into an
  * exported client configuration.
@@ -158,5 +185,5 @@ export function localManagementOrigin(
 ): string {
   const ingress = config?.runtimeRole === "hub" ? config.hub?.managementIngress : undefined;
   if (ingress?.enabled) return `http://127.0.0.1:${ingress.port}`;
-  return `http://${probeHostname(config?.hostname)}:${publicPort}`;
+  return `http://${localCredentialDestinationHostname(config?.hostname)}:${publicPort}`;
 }

package/src/lib/pinned-http.ts

@@ -1,5 +1,6 @@
 import http, { type ClientRequest, type IncomingMessage, type RequestOptions } from "node:http";
 import https from "node:https";
+import { classifyContentCoding, isNullBodyStatus } from "./http-response-semantics";
 
 export type PinnedAddress = { address: string; family: number };
 
@@ -7,7 +8,9 @@ export type PinnedHttpErrorCode =
   | "connect_timeout"
   | "first_byte_timeout"
   | "inactivity_timeout"
-  | "output_byte_limit";
+  | "output_byte_limit"
+  | "unsupported_content_encoding"
+  | "content_decode_failed";
 
 export class PinnedHttpError extends Error {
   override readonly name = "PinnedHttpError";
@@ -32,6 +35,99 @@ export interface PinnedHttpRequestOptions {
 /** @deprecated Use {@link PinnedHttpRequestOptions}. */
 export type PinnedHttpGetOptions = PinnedHttpRequestOptions;
 
+/**
+ * Undo the content-coding this transport has to undo itself, under the caller's byte ceiling.
+ *
+ * `maxBytes` keeps its existing meaning for the bytes that arrive on the socket, and gains the
+ * same meaning for the bytes the caller ends up reading. Bounding only the coded side would let
+ * a small compressed response expand past a ceiling the caller set precisely so it would not
+ * have to hold an unbounded body in memory.
+ *
+ * A completed body is not torn down here. The response already ended, so there is nothing to
+ * release, and destroying it would take a connection the agent is entitled to reuse. That
+ * matches the identity path, which also only closes. Teardown belongs to the paths that end a
+ * response early: a decode failure, an exceeded ceiling, and a caller that cancels.
+ *
+ * Only a decoder failure is renamed. A mid-body reset, a stalled response and an exceeded
+ * socket-byte ceiling all reach this pipeline as "the stream failed", and calling any of them a
+ * decode failure would tell the caller the peer sent unreadable bytes when the truth is that the
+ * connection died. The source failure is recorded as it passes so the original error survives;
+ * what is left after that is the decompressor's own, and that one is named because the caller's
+ * alternative is a bare TypeError from a stream it never constructed.
+ */
+function decodedBody(
+  source: ReadableStream<Uint8Array>,
+  format: "gzip" | "deflate",
+  maxBytes: number | undefined,
+  context: string,
+  release: () => void,
+): ReadableStream<Uint8Array> {
+  // Interposed purely to attribute failures. Once bytes enter the decompressor, a transport
+  // error and a corrupt trailer are indistinguishable from the far side of the pipe.
+  let sourceFailure: { error: unknown } | undefined;
+  const sourceReader = source.getReader();
+  const attributed = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const next = await sourceReader.read();
+        if (next.done) {
+          controller.close();
+          return;
+        }
+        controller.enqueue(next.value);
+      } catch (error) {
+        sourceFailure = { error };
+        controller.error(error);
+      }
+    },
+    cancel(reason) {
+      return sourceReader.cancel(reason);
+    },
+  });
+  // `DecompressionStream` declares its writable side as `WritableStream<BufferSource>`, and
+  // TypeScript measures `WritableStream` as invariant in its chunk type, so the pair is not
+  // assignable to `ReadableWritablePair<Uint8Array, Uint8Array>` even though every chunk this
+  // body produces is a valid `BufferSource`. The conversion states that relationship and
+  // nothing else; it does not widen what is actually written.
+  const decompressor = new DecompressionStream(format) as unknown as ReadableWritablePair<Uint8Array, Uint8Array>;
+  const reader = attributed.pipeThrough(decompressor).getReader();
+  let decoded = 0;
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const next = await reader.read();
+        if (next.done) {
+          controller.close();
+          return;
+        }
+        decoded += next.value.byteLength;
+        if (maxBytes !== undefined && decoded > maxBytes) {
+          throw new PinnedHttpError("output_byte_limit", `${context} exceeds ${maxBytes} byte cap`);
+        }
+        controller.enqueue(next.value);
+      } catch (error) {
+        // A failure the socket stream raised is the caller's answer, whatever shape it has.
+        // Only what the decompressor itself rejected is renamed.
+        const named = sourceFailure !== undefined
+          ? sourceFailure.error
+          : error instanceof PinnedHttpError
+            ? error
+            : new PinnedHttpError("content_decode_failed", `${context} could not decode its ${format} body`);
+        // Cancelling the decoded reader propagates back through the decompressor to the socket
+        // stream's own `cancel`, which destroys the request; `release` covers the case where
+        // that propagation is already finished.
+        await reader.cancel(named).catch(() => { /* already torn down */ });
+        controller.error(named);
+        release();
+      }
+    },
+    async cancel(reason) {
+      await reader.cancel(reason).catch(() => { /* already torn down */ });
+      release();
+    },
+  });
+}
+
 function pinnedHttpRequest(
   url: string,
   pinned: PinnedAddress,
@@ -55,6 +151,10 @@ function pinnedHttpRequest(
   const maxBytes = options?.maxBytes;
   const headers = new Headers(options?.headers);
   headers.set("host", parsed.host);
+  // This transport assembles the response itself, so a coding it did not ask for becomes its own
+  // problem to undo. Ask for none by default and leave an explicit caller choice alone, which is
+  // the same rule `src/lib/socks5-fetch.ts` applies to the other raw route.
+  if (!headers.has("accept-encoding")) headers.set("accept-encoding", "identity");
   if (body !== undefined && !headers.has("content-length")) {
     headers.set("content-length", String(Buffer.byteLength(body)));
   }
@@ -150,6 +250,39 @@ function pinnedHttpRequest(
         return;
       }
 
+      // A success status can still be null-body. `new Response(stream, { status: 204 })` throws a
+      // TypeError, so attaching the body below would turn a correct no-content answer into a
+      // construction failure raised inside this event handler rather than a resolved response.
+      // Nothing is coming on the socket either, so streaming one of these would hold the caller
+      // until the peer closed a connection it is entitled to keep alive. The headers still
+      // describe the representation the peer would have sent and are preserved as they arrived.
+      if (isNullBodyStatus(status)) {
+        try { response.destroy(); } catch { /* ignore */ }
+        try { req?.destroy(); } catch { /* ignore */ }
+        if (settled) return;
+        settled = true;
+        resolve(new Response(null, { status, headers: responseHeaders }));
+        return;
+      }
+
+      // The peer may have coded the body whatever this request asked for. Classify before the
+      // stream takes the socket so a coding this transport cannot undo fails on the ordinary
+      // error path rather than reaching the caller as bytes its parser cannot read.
+      const coding = classifyContentCoding(responseHeaders);
+      if (coding.kind === "unsupported") {
+        try { response.destroy(); } catch { /* ignore */ }
+        fail(new PinnedHttpError(
+          "unsupported_content_encoding",
+          `${context} returned an unsupported content-encoding: ${coding.coding}`,
+        ));
+        return;
+      }
+      if (coding.kind === "decodable") {
+        responseHeaders.delete("content-encoding");
+        // The declared length counted the coded bytes, not what the caller now reads.
+        responseHeaders.delete("content-length");
+      }
+
       let received = 0;
       const stream = new ReadableStream<Uint8Array>({
         start(controller) {
@@ -191,7 +324,14 @@ function pinnedHttpRequest(
 
       if (settled) return;
       settled = true;
-      resolve(new Response(stream, { status, headers: responseHeaders }));
+      const release = () => {
+        try { response.destroy(); } catch { /* ignore */ }
+        try { req?.destroy(); } catch { /* ignore */ }
+      };
+      const payload = coding.kind === "decodable"
+        ? decodedBody(stream, coding.format, maxBytes, context, release)
+        : stream;
+      resolve(new Response(payload, { status, headers: responseHeaders }));
     };
 
     const requestFn = parsed.protocol === "https:" ? https.request : http.request;

package/src/lib/plain-data.ts

@@ -0,0 +1,103 @@
+/**
+ * Copying a value the way a consumer that must not observe later edits needs it copied.
+ *
+ * Serializing with JSON is not a copier and using it as one is a quiet hole: it drops functions
+ * without saying so, and it invokes getters and toJSON, so the object being copied gets to decide
+ * what the copy contains. Every read here goes through a property descriptor instead, including
+ * array elements, which an exotic array can define as accessors just as an object can.
+ *
+ * The contract is narrow on purpose. This copies what JSON could have produced and refuses
+ * everything else rather than approximating it: an accessor, a cycle, a function, a class instance,
+ * a Map, a Date, a symbol value, a bigint, a non-finite number. A caller that is refused has to
+ * decide what to do about it, which is the point; a copier that silently degraded would leave the
+ * caller believing it held a snapshot of something it never read.
+ *
+ * Symbol-keyed properties are skipped rather than refused. Process bookkeeping rides on symbols by
+ * convention here, and none of it is the data a consumer is being given a copy of.
+ */
+
+/** A copy, or a refusal. A union rather than a nullable value, because null is copyable data. */
+export type PlainDataCopy<T> = { readonly ok: true; readonly value: T } | { readonly ok: false };
+
+const REFUSED = Symbol("refused");
+
+export function copyPlainData<T>(value: T): PlainDataCopy<T> {
+  const copied = copyValue(value, new Set());
+  return copied === REFUSED ? { ok: false } : { ok: true, value: copied as T };
+}
+
+/**
+ * A stable string for comparing two plain-data values.
+ *
+ * Key-sorted entry pairs rather than objects, because property order is observable through
+ * serialization and two values that differ only in it are the same value.
+ */
+export function canonicalPlainData(value: unknown): string {
+  return JSON.stringify(sorted(value));
+}
+
+/** Own enumerable string keys, with null in the position of any key that is an accessor. */
+export function ownDataKeys(value: Record<string, unknown>): Array<string | null> {
+  return Object.keys(value).map(key => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor !== undefined && descriptor.get === undefined && descriptor.set === undefined ? key : null;
+  });
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function copyValue(value: unknown, seen: Set<object>): unknown {
+  if (value === null) return null;
+  const type = typeof value;
+  if (type === "string" || type === "boolean") return value;
+  if (type === "number") return Number.isFinite(value as number) ? value : REFUSED;
+  if (type !== "object") return REFUSED;
+  const object = value as object;
+  if (seen.has(object)) return REFUSED;
+  seen.add(object);
+  try {
+    if (Array.isArray(object)) return copyArray(object, seen);
+    if (!isPlainObject(object)) return REFUSED;
+    const copied: Record<string, unknown> = {};
+    for (const key of ownDataKeys(object)) {
+      if (key === null) return REFUSED;
+      const entry = (object as Record<string, unknown>)[key];
+      if (entry === undefined) continue;
+      const item = copyValue(entry, seen);
+      if (item === REFUSED) return REFUSED;
+      copied[key] = item;
+    }
+    return copied;
+  } finally {
+    seen.delete(object);
+  }
+}
+
+function copyArray(source: unknown[], seen: Set<object>): unknown {
+  const copied: unknown[] = [];
+  for (let index = 0; index < source.length; index += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(source, index);
+    // A hole is written as null, which is what a reader of the serialized value would find there.
+    if (descriptor === undefined) { copied.push(null); continue; }
+    if (descriptor.get !== undefined || descriptor.set !== undefined) return REFUSED;
+    if (descriptor.value === undefined) { copied.push(null); continue; }
+    const item = copyValue(descriptor.value, seen);
+    if (item === REFUSED) return REFUSED;
+    copied.push(item);
+  }
+  return copied;
+}
+
+function sorted(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sorted);
+  if (value !== null && typeof value === "object") {
+    return Object.keys(value as Record<string, unknown>)
+      .sort()
+      .map(key => [key, sorted((value as Record<string, unknown>)[key])]);
+  }
+  return value;
+}

package/src/lib/process-control.ts

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { isIP } from "node:net";
 import { loadConfig } from "../config";
 import { readRuntimePort } from "../config/process-state";
 import { configuredAdminToken } from "./admin-secrets";
@@ -50,9 +51,11 @@ export interface GracefulStopIo {
 }
 
 /**
- * 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.
+ * Host to POST /api/stop against: follow the recorded bind hostname only when it is
+ * an IP literal (a proxy bound to ::1 or a LAN IP is unreachable on 127.0.0.1).
+ * DNS names are not safe here because resolution may change between bind and stop,
+ * while this request carries the management token. Loopback aliases, DNS names, and
+ * wildcard binds therefore all fall back to IPv4 loopback.
  */
 export function gracefulStopHost(hostname: string | undefined): string {
   const trimmed = (hostname ?? "").trim();
@@ -61,8 +64,13 @@ export function gracefulStopHost(hostname: string | undefined): string {
     return "127.0.0.1";
   }
   if (lower === "::1" || lower === "[::1]") return "[::1]";
-  if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed;
-  return trimmed.includes(":") ? `[${trimmed}]` : trimmed;
+  const unbracketed = trimmed.startsWith("[") && trimmed.endsWith("]")
+    ? trimmed.slice(1, -1)
+    : trimmed;
+  const ipVersion = isIP(unbracketed);
+  if (ipVersion === 6) return `[${unbracketed}]`;
+  if (ipVersion === 4) return unbracketed;
+  return "127.0.0.1";
 }
 
 /**

package/src/lib/provider-outbound.ts

@@ -7,7 +7,7 @@ import {
   resolvePublicAddresses,
 } from "./destination-policy";
 import { pinnedHttpGet, pinnedHttpPost } from "./pinned-http";
-import { effectiveProxyFor, noProxyMatches, normalizeProxyHostname, outboundProxyConfigured } from "./proxy-env";
+import { configuredOutboundFetch, effectiveProxyFor, noProxyMatches, normalizeProxyHostname, outboundProxyConfigured } from "./proxy-env";
 import { publicProviderBaseUrl } from "./provider-url";
 
 type ProviderGetInit = Omit<RequestInit, "body" | "method" | "redirect">;
@@ -104,19 +104,67 @@ export async function providerRedirectError(response: Response, requestUrl: stri
   return `provider returned ${response.status} redirect to ${target}; configure the final provider URL directly`;
 }
 
+/**
+ * Default client identity for proxy-originated provider outbound requests.
+ *
+ * Every request through the provider outbound wrapper — connection tests, model
+ * discovery, quota probes — is initiated by the proxy itself, so there is no
+ * client request to inherit a User-Agent from, and the pinned Node-style
+ * transport sends none. WAF/CDN front ends commonly answer UA-less requests
+ * with a 403 that surfaced as "provider added but no models" (#5104). A caller
+ * that materializes its own User-Agent — registry static headers, provider
+ * `headers`, or a vendor-specific client fingerprint — keeps that value and is
+ * never given a second User-Agent; this only fills the name nobody claimed.
+ * The value is what survives, not its spelling: both the pinned transport and
+ * the SOCKS transport rebuild the set through `new Headers()`, which lowercases
+ * every name before it reaches the wire. Inference traffic never uses this
+ * wrapper, so the client-fingerprint rationale of #1751 is unaffected.
+ */
+const PROVIDER_OUTBOUND_DEFAULT_USER_AGENT = "opencodex";
+
+function hasUserAgentHeader(headers: HeadersInit | null | undefined): boolean {
+  if (!headers) return false;
+  if (headers instanceof Headers) return headers.has("user-agent");
+  if (Array.isArray(headers)) return headers.some(([name]) => name.toLowerCase() === "user-agent");
+  return Object.keys(headers).some(name => name.toLowerCase() === "user-agent");
+}
+
+function withDefaultOutboundUserAgent(
+  init: ProviderGetInit | ProviderPostInit,
+): ProviderGetInit | ProviderPostInit {
+  const headers = init.headers;
+  if (hasUserAgentHeader(headers)) return init;
+  if (headers instanceof Headers) {
+    const merged = new Headers(headers);
+    merged.set("User-Agent", PROVIDER_OUTBOUND_DEFAULT_USER_AGENT);
+    return { ...init, headers: merged };
+  }
+  if (Array.isArray(headers)) {
+    return { ...init, headers: [...headers, ["User-Agent", PROVIDER_OUTBOUND_DEFAULT_USER_AGENT]] };
+  }
+  return { ...init, headers: { ...(headers ?? {}), "User-Agent": PROVIDER_OUTBOUND_DEFAULT_USER_AGENT } };
+}
+
 async function providerOutboundRequest(
   name: string,
   provider: ProviderOutboundConfig,
   url: string,
   method: "GET" | "POST",
-  init: ProviderGetInit | ProviderPostInit,
+  rawInit: ProviderGetInit | ProviderPostInit,
   dependencies: ProviderOutboundDependencies = {},
 ): Promise<Response> {
+  // See PROVIDER_OUTBOUND_DEFAULT_USER_AGENT: this wrapper only carries proxy-originated
+  // diagnostic traffic, so it identifies itself unless the caller already did.
+  const init = withDefaultOutboundUserAgent(rawInit);
   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 provider entry keeps unknown configuration keys, so `fetch` can arrive as a value the
+  // operator wrote into the file rather than an executor a caller attached. Calling that would
+  // throw inside discovery and fail the provider for a reason nothing in its configuration
+  // explains; the built-in transport is what a configured value means.
+  if (typeof provider.fetch === "function") {
     // 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.
@@ -184,7 +232,7 @@ async function providerOutboundRequest(
     if (!proxyConfigured) throw error;
     warnProxyBoundaryOnce();
     warnProxyDnsDegradationOnce();
-    return globalThis.fetch(url, { ...init, method, redirect: "manual" });
+    return configuredOutboundFetch(url, { ...init, method, redirect: "manual" });
   }
   // A canonical TUN exception with no scheme-matched proxy must retain the
   // validated address, even when an unrelated HTTP_PROXY/ALL_PROXY is present.
@@ -193,7 +241,7 @@ async function providerOutboundRequest(
     // When the Mihomo exception could have admitted an answer, pin the transport to the
     // proxy the admission assumed instead of letting fetch re-infer it from the environment.
     const proxy = (allowMihomoIpv6FakeIp && effectiveProxy) ? effectiveProxy : undefined;
-    return globalThis.fetch(url, { ...init, method, redirect: "manual", ...(proxy ? { proxy } : {}) });
+    return configuredOutboundFetch(url, { ...init, method, redirect: "manual", ...(proxy ? { proxy } : {}) });
   }
   if (proxyConfigured && resolved.privateNetwork && !noProxyMatches(parsed)) {
     const hostname = normalizeProxyHostname(parsed.hostname);

package/src/lib/proxy-env.ts

@@ -1,3 +1,5 @@
+import { socks5Fetch } from "./socks5-fetch";
+
 export const OUTBOUND_PROXY_ENV_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY"] as const;
 export const PROXY_ENV_KEYS = [...OUTBOUND_PROXY_ENV_KEYS, "NO_PROXY"] as const;
 
@@ -85,11 +87,11 @@ export function outboundProxyConfigured(
 }
 
 /**
- * The proxy URL that Bun's fetch will actually use for `url`, or null when none applies.
+ * The proxy URL selected by configured outbound fetch for `url`, or null when none applies.
  *
  * Bun selects by scheme: `HTTPS_PROXY` for `https:` targets, `HTTP_PROXY` for `http:`.
- * `ALL_PROXY` is deliberately not consulted here — fetch does not honour it, so a caller
- * that needs "this request will ride the proxy" as a precondition must not count it.
+ * A SOCKS5 `ALL_PROXY` is selected by the explicit wrapper first; other ALL_PROXY
+ * schemes remain excluded because the native HTTP fetch does not honor them.
  * Presence of *some* proxy variable (`outboundProxyConfigured`) is not that guarantee.
  */
 export function effectiveProxyFor(
@@ -102,6 +104,71 @@ export function effectiveProxyFor(
       ? "HTTP_PROXY"
       : null;
   if (!key) return null;
+  // The installed SOCKS wrapper takes this route before Bun sees scheme proxies.
+  const socksProxy = socks5ProxyFromEnv(env);
+  if (socksProxy) return socksProxy;
   const value = env[key]?.trim() || env[key.toLowerCase()]?.trim();
   return value ? value : null;
 }
+
+export function isSocks5ProxyUrl(proxy: string): boolean {
+  return /^socks5h?:\/\//i.test(proxy.trim());
+}
+
+export function socks5ProxyFromEnv(env: ProxyEnvMap = process.env): string | undefined {
+  const candidates = [env.ALL_PROXY, env.all_proxy];
+  return candidates.find(value => typeof value === "string" && isSocks5ProxyUrl(value));
+}
+
+export function configuredOutboundFetch(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+  fallback?: typeof globalThis.fetch,
+): Promise<Response> {
+  const base = fallback ?? (globalThis.fetch === installedFetch ? nativeFetch : globalThis.fetch);
+  const explicitProxy = (init as (RequestInit & { proxy?: string }) | undefined)?.proxy;
+  const proxy = typeof explicitProxy === "string"
+    ? (isSocks5ProxyUrl(explicitProxy) ? explicitProxy : undefined)
+    : socks5ProxyFromEnv();
+  let url: URL;
+  try {
+    url = new URL(input instanceof Request ? input.url : String(input));
+  } catch {
+    return base!(input, init);
+  }
+  if (proxy && (url.protocol === "http:" || url.protocol === "https:") && (explicitProxy !== undefined || !noProxyMatches(url))) {
+    return socks5Fetch(input, init, proxy);
+  }
+  return base!(input, init);
+}
+
+type FetchWithPreconnect = typeof globalThis.fetch & {
+  preconnect?: typeof globalThis.fetch.preconnect;
+};
+
+let nativeFetch: FetchWithPreconnect | undefined;
+let installedFetch: FetchWithPreconnect | undefined;
+
+export function configureSocks5Fetch(): void {
+  if (globalThis.fetch !== installedFetch) {
+    nativeFetch = globalThis.fetch as FetchWithPreconnect;
+    installedFetch = undefined;
+  }
+  const proxy = socks5ProxyFromEnv();
+  if (!proxy) {
+    if (installedFetch && globalThis.fetch === installedFetch && nativeFetch) globalThis.fetch = nativeFetch;
+    installedFetch = undefined;
+    return;
+  }
+  if (installedFetch && globalThis.fetch === installedFetch) return;
+  const base = nativeFetch ?? globalThis.fetch as FetchWithPreconnect;
+  nativeFetch = base;
+  const wrapped = Object.assign(
+    (input: RequestInfo | URL, init?: RequestInit) => {
+      return configuredOutboundFetch(input, init, base);
+    },
+    { preconnect: base.preconnect?.bind(base) },
+  ) as FetchWithPreconnect;
+  installedFetch = wrapped;
+  globalThis.fetch = wrapped;
+}