@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/lib/provider-egress.ts

@@ -0,0 +1,310 @@
+/**
+ * Per-provider egress: which transport a request for THIS provider actually leaves by.
+ *
+ * The global `proxy`/`noProxy` pair is process-wide (mirrored into HTTP_PROXY/HTTPS_PROXY/
+ * ALL_PROXY/NO_PROXY by `applyProxyEnv`), so it cannot express the split #2894 describes:
+ * one upstream must exit through a regional proxy, another must stay direct on the local
+ * network. This module is the single authority that answers that question for one request,
+ * and every transport owner that can carry the answer consumes it rather than re-deriving it.
+ *
+ * It deliberately mirrors the shape #5087 established for the global decision in
+ * `effectiveProxyFor`: the question is never "is a proxy configured" but "does a proxy apply
+ * to THIS request". A provider route is resolved against the request URL, so a per-provider
+ * bypass list is part of the decision rather than a second check somewhere downstream.
+ *
+ * The three states are exactly the ones the issue asks for, with one deliberate divergence:
+ *
+ * - field absent          -> `inherit`: the global decision stands, byte-identical to today;
+ * - `null` or `"direct"` -> `direct`: this provider never uses the global proxy;
+ * - an http(s) URL        -> `proxy`: this provider uses its own HTTP(S) proxy;
+ * - a socks5(h) URL       -> `proxy`: this provider uses its own SOCKS5 proxy.
+ *
+ * The divergence is the empty string. #2894 sketches `""` as a third spelling of DIRECT.
+ * Treating it that way would make a dashboard field the operator merely cleared silently
+ * change a provider from "inherit the global proxy" to "never use the global proxy" — the
+ * quiet reinterpretation this batch exists to remove. An empty or whitespace-only value is
+ * therefore a configuration error naming both real alternatives.
+ */
+import type { OcxProviderConfig } from "../types";
+import { isSocks5ProxyUrl, noProxyMatches } from "./proxy-env";
+
+export class InvalidProviderEgressError extends Error {
+  override readonly name = "InvalidProviderEgressError";
+  constructor(
+    /** The provider field that carries the offending value. */
+    readonly field: "proxy" | "noProxy",
+    /** The failure on its own, so configuration surfaces can phrase it their own way. */
+    readonly reason: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** The literal an operator writes to pin one provider to direct egress. */
+export const PROVIDER_EGRESS_DIRECT = "direct";
+
+export type ProviderEgress =
+  | { kind: "inherit" }
+  | { kind: "direct"; reason: "configured" | "noProxy" }
+  | { kind: "proxy"; proxyUrl: string; transport: "http" | "socks5" };
+
+export interface ProviderEgressContext {
+  providerName: string;
+  provider: Pick<OcxProviderConfig, "proxy" | "noProxy">;
+  url: string | URL;
+}
+
+function egressFailure(providerName: string, field: "proxy" | "noProxy", reason: string): never {
+  throw new InvalidProviderEgressError(field, reason, `providers.${providerName}.${field} is invalid: ${reason}`);
+}
+
+/**
+ * A proxy URL reduced to scheme, host and port for operator-facing output.
+ *
+ * A proxy URL routinely carries `user:password@`, and this value reaches startup banners,
+ * diagnostics and the dashboard DTO. `URL.origin` drops userinfo, query and path, so what is
+ * left identifies the route without reproducing the credential. Nothing derived from the
+ * credential is emitted either — not a hash, not a prefix — because a short digest over a
+ * known host is a guessable stand-in for the secret and a durable correlation key for the
+ * account behind it.
+ */
+export function sanitizeProxyUrlForLog(proxyUrl: string): string {
+  try {
+    const parsed = new URL(proxyUrl);
+    return parsed.port ? `${parsed.protocol}//${parsed.hostname}:${parsed.port}` : parsed.origin;
+  } catch {
+    return "<unparseable-proxy-url>";
+  }
+}
+
+export function describeProviderEgressForLog(egress: ProviderEgress): string {
+  if (egress.kind === "inherit") return "inherit";
+  if (egress.kind === "direct") return `direct(${egress.reason})`;
+  return `${egress.transport}(${sanitizeProxyUrlForLog(egress.proxyUrl)})`;
+}
+
+function parseTargetUrl(providerName: string, url: string | URL): URL {
+  if (url instanceof URL) return url;
+  try {
+    return new URL(url);
+  } catch {
+    return egressFailure(providerName, "proxy", "the request URL is not parseable, so no provider route can be decided for it");
+  }
+}
+
+function normalizeNoProxy(providerName: string, raw: string | string[] | undefined): string | null {
+  if (raw === undefined) return null;
+  const entries = Array.isArray(raw) ? raw : [raw];
+  for (const entry of entries) {
+    if (typeof entry !== "string") {
+      return egressFailure(providerName, "noProxy", "every entry must be a string host pattern");
+    }
+  }
+  const joined = entries.join(",").trim();
+  return joined.length > 0 ? joined : null;
+}
+
+function parseProviderProxyRoute(providerName: string, raw: string): ProviderEgress {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return egressFailure(
+      providerName,
+      "proxy",
+      `an empty value is ambiguous; write "${PROVIDER_EGRESS_DIRECT}" to force direct egress, or remove the field to inherit the global proxy`,
+    );
+  }
+  if (trimmed.toLowerCase() === PROVIDER_EGRESS_DIRECT) return { kind: "direct", reason: "configured" };
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return egressFailure(
+      providerName,
+      "proxy",
+      `"${PROVIDER_EGRESS_DIRECT}" or an absolute proxy URL is required; this value is neither`,
+    );
+  }
+  if (isSocks5ProxyUrl(trimmed)) {
+    if (!parsed.hostname) {
+      return egressFailure(providerName, "proxy", "the SOCKS5 proxy URL has no host");
+    }
+    return { kind: "proxy", proxyUrl: trimmed, transport: "socks5" };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return egressFailure(
+      providerName,
+      "proxy",
+      `unsupported proxy scheme "${parsed.protocol}"; supported schemes are http, https, socks5 and socks5h`,
+    );
+  }
+  if (!parsed.hostname) {
+    return egressFailure(providerName, "proxy", "the proxy URL has no host");
+  }
+  return { kind: "proxy", proxyUrl: parsed.toString(), transport: "http" };
+}
+
+/**
+ * The route this provider's request leaves by, or `inherit` when the global decision stands.
+ *
+ * Throws `InvalidProviderEgressError` rather than degrading to `inherit`: a malformed egress
+ * field is the one case where guessing is worst. Falling back to the global proxy would send a
+ * credential through a route the operator did not choose, and falling back to direct would
+ * leave a restricted network with no exit. Both read as success at the call site.
+ *
+ * A per-provider `noProxy` match outranks the provider's own proxy for the same reason it
+ * outranks the global one: it names destinations this provider must reach without a proxy.
+ * It is evaluated against the resolved route, so it also carves holes in an inherited global
+ * proxy — which is how a provider exempts one host without owning a proxy of its own.
+ */
+export function resolveProviderEgress(context: ProviderEgressContext): ProviderEgress {
+  const { providerName, provider } = context;
+  const raw = provider.proxy;
+  let route: ProviderEgress;
+  if (raw === undefined) {
+    route = { kind: "inherit" };
+  } else if (raw === null) {
+    route = { kind: "direct", reason: "configured" };
+  } else if (typeof raw !== "string") {
+    return egressFailure(providerName, "proxy", "the value must be a proxy URL string, \"direct\", null, or absent");
+  } else {
+    route = parseProviderProxyRoute(providerName, raw);
+  }
+  const noProxy = normalizeNoProxy(providerName, provider.noProxy);
+  if (noProxy !== null) {
+    const target = parseTargetUrl(providerName, context.url);
+    if (noProxyMatches(target, { NO_PROXY: noProxy })) return { kind: "direct", reason: "noProxy" };
+  }
+  return route;
+}
+
+/**
+ * Whether this provider decided the route itself, as opposed to deferring to the global one.
+ *
+ * Transport owners use this to tell "the operator chose this" from "nothing was configured",
+ * which are the two cases that must not be collapsed when a transport cannot carry the choice.
+ */
+export function providerEgressIsExplicit(egress: ProviderEgress): boolean {
+  return egress.kind !== "inherit";
+}
+
+/**
+ * The request-scoped fetch options that express `egress` to Bun's fetch.
+ *
+ * `proxy: false` is Bun's documented per-request direct connection: it ignores HTTP_PROXY,
+ * HTTPS_PROXY and ALL_PROXY, and it ignores NO_PROXY as well, which is what makes it a
+ * decision rather than a hint. `undefined`, `null` and `""` all mean "no option given" to
+ * Bun and fall through to the environment, so none of them can express direct egress — the
+ * reason this returns the literal `false` and never an empty string.
+ *
+ * A SOCKS5 route is returned as the same `proxy` string; `configuredOutboundFetch` recognises
+ * the scheme and hands the request to the SOCKS transport, because Bun's own fetch ignores a
+ * socks5 value.
+ */
+export function providerEgressFetchInit(egress: ProviderEgress): { proxy?: string | false } {
+  if (egress.kind === "inherit") return {};
+  if (egress.kind === "direct") return { proxy: false };
+  return { proxy: egress.proxyUrl };
+}
+
+/**
+ * Marker for an executor that forwards its `RequestInit` to a transport which honours the
+ * request-scoped proxy option.
+ *
+ * A provider route is refused on an executor that owns its own transport, because applying it
+ * is impossible and ignoring it is worse. But not every `provider.fetch` owns a transport:
+ * some are internal wrappers that add a header and delegate, and `src/providers/xai-transport.ts`
+ * installs exactly such a wrapper on every xAI route. Refusing those would make the per-provider
+ * proxy unusable on one of the two providers the original issue names.
+ *
+ * The marker is opt-in and applied by the wrapper's author, so an executor that arrives from
+ * configuration or from a caller is opaque by default and still refused. `Symbol.for` keeps the
+ * mark readable across duplicated module instances.
+ */
+const EGRESS_TRANSPARENT_EXECUTOR = Symbol.for("opencodex.provider-egress.transparent-executor");
+
+export function markEgressTransparentExecutor<Fetch extends typeof globalThis.fetch>(executor: Fetch): Fetch {
+  (executor as unknown as Record<symbol, boolean>)[EGRESS_TRANSPARENT_EXECUTOR] = true;
+  return executor;
+}
+
+export function isEgressTransparentExecutor(executor: unknown): boolean {
+  return typeof executor === "function"
+    && (executor as unknown as Record<symbol, unknown>)[EGRESS_TRANSPARENT_EXECUTOR] === true;
+}
+
+/** The destination of a fetch input, or null when it cannot be read as a URL. */
+export function egressTargetUrl(input: string | URL | Request): string | null {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.toString();
+  return typeof input?.url === "string" ? input.url : null;
+}
+
+/** Everything a physical send needs to decide the route for the request it is about to make. */
+export interface ProviderEgressBinding {
+  providerName: string;
+  provider: Pick<OcxProviderConfig, "proxy" | "noProxy">;
+}
+
+/**
+ * The request options expressing `binding`'s route for the destination actually being sent to.
+ *
+ * Resolved at the physical send rather than when the executor was built, for the reason #4992
+ * already established for the connection policy: a queued request can be rebuilt against a
+ * different upstream host before it leaves, and a route decided against the original
+ * destination would then be applied to a different one. With a host-scoped `noProxy` that
+ * inverts the decision, and the credential leaves by a route the operator did not choose.
+ *
+ * Refuses rather than degrades when the selected executor owns its own transport.
+ */
+export function providerEgressSendInit(
+  binding: ProviderEgressBinding,
+  physicalFetch: unknown,
+  input: string | URL | Request,
+): { proxy?: string | false } {
+  const url = egressTargetUrl(input);
+  if (url === null) return {};
+  const egress = resolveProviderEgress({ providerName: binding.providerName, provider: binding.provider, url });
+  if (providerEgressIsExplicit(egress) && !isEgressTransparentExecutor(physicalFetch)) {
+    // Name the field that actually made the route explicit. A bypass-list match with no
+    // `proxy` field at all would otherwise tell the operator to remove an override they
+    // never wrote.
+    const field = egress.kind === "direct" && egress.reason === "noProxy" ? "noProxy" : "proxy";
+    throw new InvalidProviderEgressError(
+      field,
+      "the selected transport owns its own routing, so this route cannot be applied",
+      `providers.${binding.providerName}.${field} cannot be applied to the selected provider transport; `
+      + "remove the provider egress override or the custom executor",
+    );
+  }
+  return providerEgressFetchInit(egress);
+}
+
+/**
+ * A destination used only to exercise the resolver at configuration time.
+ *
+ * Validation has no request URL, but `noProxy` is only meaningful against one. Resolving a
+ * reserved name checks the shape of both fields without asserting anything about which route a
+ * real request would take.
+ */
+const EGRESS_VALIDATION_URL = "https://validation.invalid/";
+
+/**
+ * The configuration error for a provider's egress fields, or null when they are usable.
+ *
+ * Delegates to `resolveProviderEgress` so configuration and request time cannot drift apart:
+ * a value accepted by `ocx config set` or the dashboard is one the transport will accept, and
+ * one rejected here is rejected there for the identical reason. Restating the rules would give
+ * this repository two definitions of a valid proxy value and no check that they agree.
+ */
+export function providerEgressConfigError(
+  provider: Pick<OcxProviderConfig, "proxy" | "noProxy">,
+): string | null {
+  try {
+    resolveProviderEgress({ providerName: "<validation>", provider, url: EGRESS_VALIDATION_URL });
+    return null;
+  } catch (error) {
+    if (error instanceof InvalidProviderEgressError) return `${error.field} is invalid: ${error.reason}`;
+    throw error;
+  }
+}

package/src/lib/provider-outbound.ts

@@ -7,12 +7,13 @@ import {
   resolvePublicAddresses,
 } from "./destination-policy";
 import { pinnedHttpGet, pinnedHttpPost } from "./pinned-http";
-import { configuredOutboundFetch, effectiveProxyFor, noProxyMatches, normalizeProxyHostname, outboundProxyConfigured } from "./proxy-env";
+import { configuredOutboundFetch, effectiveProxyFor, noProxyMatches, normalizeProxyHostname, schemeMatchedProxyFor } from "./proxy-env";
+import { InvalidProviderEgressError, resolveProviderEgress } from "./provider-egress";
 import { publicProviderBaseUrl } from "./provider-url";
 
 type ProviderGetInit = Omit<RequestInit, "body" | "method" | "redirect">;
 type ProviderPostInit = ProviderGetInit & { body: string };
-type ProviderOutboundConfig = Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork"> & {
+type ProviderOutboundConfig = Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork" | "proxy" | "noProxy"> & {
   fetch?: typeof globalThis.fetch;
 };
 export interface ProviderOutboundDependencies {
@@ -104,19 +105,78 @@ 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 decides its own transport, so a provider egress route cannot be
+    // applied to it. Refusing is the only honest answer: running the executor anyway would send
+    // the request by whatever route that executor picked while the configuration says otherwise.
+    if (resolveProviderEgress({ providerName: name, provider, url }).kind !== "inherit") {
+      throw new InvalidProviderEgressError(
+        "proxy",
+        "a caller-supplied fetch executor owns its own routing, so this route cannot be applied",
+        `providers.${name}.proxy cannot be applied to a caller-supplied fetch executor; `
+        + "remove the provider egress override or the custom executor",
+      );
+    }
     // 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.
@@ -138,13 +198,39 @@ async function providerOutboundRequest(
     return provider.fetch(url, { ...init, method, redirect: "manual" });
   }
   const parsed = postUrl ?? new URL(url);
-  const proxyConfigured = outboundProxyConfigured();
-  // Snapshot the scheme-matched proxy once, before the DNS await, so admission and transport
-  // below reason about the same value. `null` here means "no proxy fetch would actually use",
-  // even if some other proxy variable is set.
-  const effectiveProxy = effectiveProxyFor(parsed);
+  // The provider's own route, decided against this request URL. `inherit` leaves every value
+  // below exactly as the global decision computed it.
+  const egress = resolveProviderEgress({ providerName: name, provider, url: parsed });
+  const providerProxy = egress.kind === "proxy" ? egress.proxyUrl : null;
+  // Snapshot the proxy fetch would actually use once, before the DNS await, so admission
+  // and transport below reason about the same value. `null` here means "no proxy fetch
+  // would actually use", even if some other proxy variable is set.
+  const globalProxy = effectiveProxyFor(parsed);
+  // The request leaves the DNS-pinned transport only when a proxy will actually carry it:
+  // a proxy variable fetch would use for this URL that NO_PROXY does not exempt.
+  // A scheme-mismatched or unusable variable, a NO_PROXY match, or an ALL_PROXY
+  // this target's scheme cannot use must not downgrade pinning or admit
+  // proxy-only DNS answers.
+  //
+  // A provider route replaces that decision outright rather than combining with it. An
+  // explicit provider proxy applies even where global NO_PROXY exempts the host, because the
+  // operator named this proxy for this provider; `providers.<name>.noProxy` is the exemption
+  // that belongs to that choice, and `resolveProviderEgress` has already applied it. A
+  // provider pinned to `direct` keeps the DNS-pinned transport, which reaches the peer
+  // through no proxy at all — the one route on this path that needs nothing from Bun.
+  const proxyApplies = egress.kind === "inherit"
+    ? globalProxy !== null && !noProxyMatches(parsed)
+    : providerProxy !== null;
   const isCanonicalUrl = dependencies.isCanonicalUrl ?? (() => false);
-  const allowMihomoIpv6FakeIp = (effectiveProxy !== null && !noProxyMatches(parsed))
+  // The IPv6 fake-IP gate keeps its stricter documented condition — a
+  // scheme-matched variable or a SOCKS5 ALL_PROXY, never a non-SOCKS
+  // ALL_PROXY — even when proxyApplies admits one for the transport
+  // decision, because admission binds the fetch to this value explicitly.
+  // An explicit provider proxy is exactly such a binding: the fetch below is pinned to it.
+  const bindingProxy = egress.kind === "inherit"
+    ? schemeMatchedProxyFor(parsed)
+    : providerProxy;
+  const allowMihomoIpv6FakeIp = (bindingProxy !== null && (providerProxy !== null || !noProxyMatches(parsed)))
     || transparentFakeIpException(url, parsed, isCanonicalUrl, name);
   const resolveAddresses = dependencies.resolveAddresses ?? resolvePublicAddresses;
   const pinnedGet = dependencies.pinnedGet ?? pinnedHttpGet;
@@ -168,7 +254,7 @@ async function providerOutboundRequest(
       // proof is on the final request URL — not the provider name — because an
       // OAuth/forward name matches any baseUrl by design while the bearer is
       // pinned to the registry destination independently.
-      allowBenchmarkAddresses: (proxyConfigured && !noProxyMatches(parsed))
+      allowBenchmarkAddresses: proxyApplies
         || transparentFakeIpException(url, parsed, isCanonicalUrl, name),
       // Mihomo IPv6 fake-IP (fdfe:dcba:9876::/48) answers are admitted either when bound
       // to a scheme-matched proxy (#3462) or under the TUN transparency exception for a
@@ -181,21 +267,28 @@ async function providerOutboundRequest(
     if (!dnsResolutionFailed) {
       throw new ProviderOutboundPolicyError(error instanceof Error ? error.message : "provider destination was blocked");
     }
-    if (!proxyConfigured) throw error;
+    if (!proxyApplies) throw error;
     warnProxyBoundaryOnce();
     warnProxyDnsDegradationOnce();
-    return configuredOutboundFetch(url, { ...init, method, redirect: "manual" });
+    // An explicit provider proxy stays pinned through the degradation too; re-inferring the
+    // route from the environment here would quietly move the request to a different exit.
+    return configuredOutboundFetch(url, {
+      ...init, method, redirect: "manual",
+      ...(providerProxy ? { proxy: providerProxy } : {}),
+    });
   }
   // A canonical TUN exception with no scheme-matched proxy must retain the
   // validated address, even when an unrelated HTTP_PROXY/ALL_PROXY is present.
-  if (proxyConfigured && !resolved.privateNetwork && (effectiveProxy !== null || !allowMihomoIpv6FakeIp)) {
+  if (proxyApplies && !resolved.privateNetwork) {
     warnProxyBoundaryOnce();
     // 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;
+    // An explicit provider proxy is always pinned, for the same reason and unconditionally:
+    // the operator named the exit for this provider, so the environment must not re-decide it.
+    const proxy = providerProxy ?? ((allowMihomoIpv6FakeIp && bindingProxy) ? bindingProxy : undefined);
     return configuredOutboundFetch(url, { ...init, method, redirect: "manual", ...(proxy ? { proxy } : {}) });
   }
-  if (proxyConfigured && resolved.privateNetwork && !noProxyMatches(parsed)) {
+  if (proxyApplies && resolved.privateNetwork) {
     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`,

package/src/lib/proxy-env.ts

@@ -86,12 +86,30 @@ export function outboundProxyConfigured(
   return OUTBOUND_PROXY_ENV_KEYS.some(key => proxyEnvPresent(key, env));
 }
 
+/**
+ * The value when `raw` is a proxy URL Bun fetch can actually use, else null.
+ * Bun rejects unparseable values and non-http(s) schemes (UnsupportedProxyProtocol),
+ * so admitting them as "the proxy that applies" would only downgrade DNS pinning.
+ */
+function usableHttpProxyUrl(raw: string | undefined): string | null {
+  if (!raw) return null;
+  try {
+    const scheme = new URL(raw).protocol;
+    return scheme === "http:" || scheme === "https:" ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * 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:`.
- * 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.
+ * A SOCKS5 `ALL_PROXY` is selected by the explicit wrapper first. A non-SOCKS
+ * `ALL_PROXY` is still honoured by the native fetch for plain `http:` targets on
+ * every platform the CI matrix covers — the provider-outbound e2e drives exactly that
+ * request through the proxy on Linux, macOS and Windows. For `https:` targets the
+ * SOCKS wrapper remains the only `ALL_PROXY` route this module counts.
  * Presence of *some* proxy variable (`outboundProxyConfigured`) is not that guarantee.
  */
 export function effectiveProxyFor(
@@ -107,8 +125,47 @@ export function effectiveProxyFor(
   // The installed SOCKS wrapper takes this route before Bun sees scheme proxies.
   const socksProxy = socks5ProxyFromEnv(env);
   if (socksProxy) return socksProxy;
+  const schemeValue = env[key]?.trim() || env[key.toLowerCase()]?.trim();
+  if (schemeValue) {
+    // A SOCKS URL in a scheme-matched variable is a usable proxy: admission
+    // binds it explicitly and the transport follows, so it applies here too.
+    if (isSocks5ProxyUrl(schemeValue)) return schemeValue;
+    // A present but unusable scheme-matched variable fails closed: it is not a
+    // proxy Bun fetch can use, and it must not fall through to ALL_PROXY either.
+    // If Bun would have used ALL_PROXY here, keeping the DNS-pinned transport is
+    // the safe direction; if it would not, this is exactly right.
+    return usableHttpProxyUrl(schemeValue);
+  }
+  if (url.protocol !== "http:") return null;
+  return usableHttpProxyUrl(env.ALL_PROXY?.trim() || env.all_proxy?.trim());
+}
+
+/**
+ * The proxy a request can be explicitly bound to for fake-IP admission, or
+ * null: a scheme-matched variable or a SOCKS5 `ALL_PROXY`. This is the
+ * stricter documented gate for Mihomo IPv6 fake-IP answers — a non-SOCKS
+ * `ALL_PROXY` does not count here even when `effectiveProxyFor` reports it,
+ * because admission pins the transport to the returned value and the gate's
+ * contract is stated in those terms. The scheme-matched value counts only as
+ * a usable binding — a SOCKS or http(s) URL; anything else would admit a
+ * fake-IP answer nothing can resolve.
+ */
+export function schemeMatchedProxyFor(
+  url: URL,
+  env: ProxyEnvMap = process.env,
+): string | null {
+  const key: ProxyEnvKey | null = url.protocol === "https:"
+    ? "HTTPS_PROXY"
+    : url.protocol === "http:"
+      ? "HTTP_PROXY"
+      : null;
+  if (!key) return null;
+  const socksProxy = socks5ProxyFromEnv(env);
+  if (socksProxy) return socksProxy;
   const value = env[key]?.trim() || env[key.toLowerCase()]?.trim();
-  return value ? value : null;
+  if (!value) return null;
+  if (isSocks5ProxyUrl(value)) return value;
+  return usableHttpProxyUrl(value);
 }
 
 export function isSocks5ProxyUrl(proxy: string): boolean {
@@ -120,16 +177,34 @@ export function socks5ProxyFromEnv(env: ProxyEnvMap = process.env): string | und
   return candidates.find(value => typeof value === "string" && isSocks5ProxyUrl(value));
 }
 
+/**
+ * A request-scoped proxy decision as the outbound transports express it.
+ *
+ * `false` is Bun's documented "connect directly": it overrides HTTP_PROXY, HTTPS_PROXY and
+ * ALL_PROXY, and it overrides NO_PROXY too. Bun treats `undefined`, `null` and `""` alike as
+ * "no option given" and falls back to the environment, so none of those can express direct
+ * egress. Declared locally because the value travels through `RequestInit`, which does not
+ * carry it in the ambient DOM types.
+ */
+export type ProxyCapableRequestInit = RequestInit & { proxy?: string | false };
+
 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();
+  const explicitProxy = (init as ProxyCapableRequestInit | undefined)?.proxy;
+  // An explicit `false` is a decision, so it also has to win over the installed SOCKS wrapper.
+  // Reading it as "no string was supplied" would fall through to ALL_PROXY and send a request
+  // the caller pinned to direct egress through the global SOCKS proxy instead — the silent
+  // substitution the caller asked this option to prevent. Bun applies the same `false` to its
+  // own HTTP(S) proxy environment once the request reaches the base fetch below.
+  const proxy = explicitProxy === false
+    ? undefined
+    : typeof explicitProxy === "string"
+      ? (isSocks5ProxyUrl(explicitProxy) ? explicitProxy : undefined)
+      : socks5ProxyFromEnv();
   let url: URL;
   try {
     url = new URL(input instanceof Request ? input.url : String(input));