@openclaw/proxyline 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.3 - 2026-05-18
+
+- Fixed managed `globalThis.fetch` so later Undici global dispatcher replacement cannot bypass the active Proxyline dispatcher. Thanks @jesse-merhi.
+- Updated package tooling and test dependencies to exact latest versions, including pnpm 11.1.2, TypeScript 6.0.3, and Undici 8.3.0; raised the Node.js floor to 22.19.0 to match Undici 8.
+
+## 0.3.2 - 2026-05-17
+
+- Fixed managed Undici proxy dispatchers so HTTPS proxy endpoints addressed by IP do not send invalid IP-literal SNI.
+
 ## 0.3.1 - 2026-05-16
 
 - Fixed `withBypass()` to scope temporary bypasses to the calling async context instead of process-wide state.

package/README.md

@@ -31,7 +31,7 @@ pnpm add @openclaw/proxyline
 npm install @openclaw/proxyline
 ```
 
-Requires Node 20.18.1+ and a host `undici` dependency compatible with `>=7.25.0 <9`.
+Requires Node 22.19.0+ and a host `undici` dependency compatible with `>=8.3.0 <9`.
 
 ## Quick start
 
@@ -103,7 +103,8 @@ It uses Proxyline's built-in HTTP/HTTPS Node agent, and `proxyTls` applies only
 
 - `http.request` / `http.get`: covered by global method patching and global agent replacement.
 - `https.request` / `https.get`: covered by global method patching and global agent replacement.
-- `fetch` / undici global dispatcher: covered by the `globalThis.fetch` patch and `setGlobalDispatcher`.
+- `globalThis.fetch`: covered by the fetch patch, including explicit dispatcher options and later Undici global dispatcher replacement in managed mode.
+- Undici global dispatcher: installed for Undici APIs that read the current process dispatcher.
 - WebSocket clients accepting a Node `agent`: covered with `proxy.createWebSocketAgent()`.
 - Caller-built `http.Agent` / `https.Agent`: overridden in managed and active ambient mode, with TLS options preserved.
 - Explicit HTTP CONNECT sockets: covered with `openProxyConnectTunnel()`.

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAIV,eAAe,EACf,gBAAgB,EAIjB,MAAM,YAAY,CAAC;AA0tBpB,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAgI3E;AAED,eAAO,MAAM,kBAAkB,yBAAmB,CAAC"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAIV,eAAe,EACf,gBAAgB,EAIjB,MAAM,YAAY,CAAC;AA8xBpB,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAgI3E;AAED,eAAO,MAAM,kBAAkB,yBAAmB,CAAC"}

package/dist/runtime.js

@@ -1,7 +1,8 @@
 import http from "node:http";
 import https from "node:https";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { Agent as UndiciAgent, Dispatcher, FormData as UndiciFormData, Headers as UndiciHeaders, Request as UndiciRequest, Response as UndiciResponse, errors as undiciErrors, fetch as undiciFetch, getGlobalDispatcher, ProxyAgent as UndiciProxyAgent, setGlobalDispatcher, } from "undici";
+import net from "node:net";
+import { Agent as UndiciAgent, Dispatcher, FormData as UndiciFormData, Headers as UndiciHeaders, Pool as UndiciPool, Request as UndiciRequest, Response as UndiciResponse, errors as undiciErrors, fetch as undiciFetch, getGlobalDispatcher, ProxyAgent as UndiciProxyAgent, setGlobalDispatcher, } from "undici";
 import { createAmbientProxyResolver, EMPTY_PROXY_ENV, resolveAmbientProxyForUrl, readProxyEnv, } from "./env.js";
 import { bindNodeHttpMethod, createDirectNodeAgent, createNodeProxyAgent, } from "./node-http.js";
 import { formatUrl, ProxylineError, redactProxyUrl, resolveProxyTlsCa, } from "./shared.js";
@@ -99,25 +100,32 @@ async function normalizeFetchInput(input, init, options) {
         preserveDispatcher: options.preserveDispatcher,
     });
 }
-function stripFetchDispatcher(init) {
-    if (typeof init !== "object" || init === null) {
-        return init;
-    }
-    const sanitized = Object.create(init);
+function withManagedFetchDispatcher(init, dispatcher) {
+    if (init !== undefined &&
+        init !== null &&
+        typeof init !== "object" &&
+        typeof init !== "function") {
+        throw new TypeError(`Request constructor: Expected ${String(init)} to be one of: Null, Undefined, Object.`);
+    }
+    const sanitized = init === undefined || init === null ? {} : Object.create(init);
     Reflect.defineProperty(sanitized, "dispatcher", {
         configurable: true,
         enumerable: true,
-        value: undefined,
+        value: dispatcher,
         writable: true,
     });
     return sanitized;
 }
 const proxylineFetch = async (input, init) => {
-    const managedMode = activeRuntime?.mode === "managed";
+    const managedDispatcher = activeRuntime?.mode === "managed"
+        ? activeRuntime.installedDispatcher
+        : undefined;
     const normalizedInput = await normalizeFetchInput(input, init, {
-        preserveDispatcher: !managedMode,
+        preserveDispatcher: managedDispatcher === undefined,
     });
-    const normalizedInit = managedMode ? stripFetchDispatcher(init) : init;
+    const normalizedInit = managedDispatcher === undefined
+        ? init
+        : withManagedFetchDispatcher(init, managedDispatcher);
     const response = await Reflect.apply(undiciFetch, undefined, normalizedInit === undefined ? [normalizedInput] : [normalizedInput, normalizedInit]);
     if (!(response instanceof proxylineResponse)) {
         throw new TypeError("Proxyline fetch returned a non-Response value.");
@@ -272,10 +280,40 @@ function resolveUndiciBaseOptions(options) {
 function createUndiciAgent(options) {
     return new UndiciAgent(resolveUndiciBaseOptions(options));
 }
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stripIpServernameFromConnectOptions(options) {
+    if (!isObjectRecord(options) || typeof options.servername !== "string") {
+        return options;
+    }
+    const servername = options.servername.replace(/^\[|\]$/g, "");
+    if (net.isIP(servername) === 0) {
+        return options;
+    }
+    const next = { ...options };
+    delete next.servername;
+    return next;
+}
+function stripIpServernameFromConnect(connect) {
+    if (typeof connect !== "function") {
+        return connect;
+    }
+    return (options, callback) => connect(stripIpServernameFromConnectOptions(options), callback);
+}
+function createProxyClientFactory() {
+    return (origin, options) => {
+        const clientOptions = isObjectRecord(options)
+            ? { ...options, connect: stripIpServernameFromConnect(options.connect) }
+            : options;
+        return new UndiciPool(origin, clientOptions);
+    };
+}
 function createUndiciProxyAgent(proxyUrl, options) {
     return new UndiciProxyAgent({
         ...resolveUndiciBaseOptions(options.undici),
         uri: proxyUrl,
+        clientFactory: createProxyClientFactory(),
         ...(options.proxyCa !== undefined ? { proxyTls: { ca: options.proxyCa } } : {}),
     });
 }
@@ -288,6 +326,18 @@ function createUndiciProxyDispatcher(options, dispatcherOptions) {
     }
     return new ManagedUndiciDispatcher(options.resolver, dispatcherOptions);
 }
+function reportClosedDispatchError(handler, error) {
+    const compatibleHandler = handler;
+    if (compatibleHandler.onResponseError !== undefined) {
+        compatibleHandler.onResponseError(null, error);
+        return false;
+    }
+    if (compatibleHandler.onError !== undefined) {
+        compatibleHandler.onError(error);
+        return false;
+    }
+    throw error;
+}
 class ManagedUndiciDispatcher extends Dispatcher {
     [PROXYLINE_DISPATCHER_BRAND] = true;
     #directDispatcher;
@@ -303,11 +353,7 @@ class ManagedUndiciDispatcher extends Dispatcher {
     }
     dispatch(options, handler) {
         if (this.#closedError !== undefined) {
-            if (handler.onError === undefined) {
-                throw this.#closedError;
-            }
-            handler.onError(this.#closedError);
-            return false;
+            return reportClosedDispatchError(handler, this.#closedError);
         }
         const url = resolveUndiciDispatchUrl(options);
         const proxyUrl = url === undefined ? "" : this.#resolver.getProxyForUrl(url, "undici");
@@ -373,11 +419,7 @@ class AmbientUndiciDispatcher extends Dispatcher {
     }
     dispatch(options, handler) {
         if (this.#closedError !== undefined) {
-            if (handler.onError === undefined) {
-                throw this.#closedError;
-            }
-            handler.onError(this.#closedError);
-            return false;
+            return reportClosedDispatchError(handler, this.#closedError);
         }
         const url = resolveUndiciDispatchUrl(options);
         const proxyUrl = url === undefined ? undefined : resolveAmbientProxyForUrl(url, this.#env);

package/docs/README.md

@@ -25,7 +25,8 @@ Process-global proxy routing for Node.js. Proxyline patches the network surfaces
 
 - `http.request` / `http.get`: covered by global method patching and global agent replacement.
 - `https.request` / `https.get`: covered by global method patching and global agent replacement.
-- `fetch` / undici global dispatcher: covered by the `globalThis.fetch` patch and `setGlobalDispatcher`.
+- `globalThis.fetch`: covered by the fetch patch, including explicit dispatcher options and later Undici global dispatcher replacement in managed mode.
+- Undici global dispatcher: installed for Undici APIs that read the current process dispatcher.
 - WebSocket clients accepting a Node `agent`: covered with `proxy.createWebSocketAgent()`.
 - WebSocket clients without an `agent` option: partially covered when the upgrade path reuses patched `http.request`.
 - Explicit HTTP CONNECT sockets: covered with `openProxyConnectTunnel()`.

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-Proxyline targets Node.js 20.18.1+. It is published as `@openclaw/proxyline` and ships ESM with TypeScript types.
+Proxyline targets Node.js 22.19.0+. It is published as `@openclaw/proxyline` and ships ESM with TypeScript types.
 
 ## Install
 

package/docs/security.md

@@ -30,7 +30,7 @@ Anything that does not flow through the patched APIs:
 
 - Direct `net.connect` or `tls.connect` calls. Code that opens raw sockets is not seen by Proxyline.
 - Native modules with private transport stacks (e.g. some database drivers, gRPC C bindings).
-- Libraries that import and call `undici.fetch` directly with their own explicit `Dispatcher`. Proxyline's managed `globalThis.fetch` strips explicit dispatchers, but it cannot rewrite every imported undici function reference.
+- Libraries that import and call `undici.fetch` directly with their own explicit `Dispatcher`. Proxyline's managed `globalThis.fetch` pins its own dispatcher even when callers pass an explicit dispatcher or later replace the Undici global dispatcher, but it cannot rewrite every imported undici function reference.
 - DNS resolution itself. Proxyline tells the proxy a hostname; DNS-based exfiltration via the local resolver is out of scope.
 - Sockets opened **before** `installProxyline` ran. Existing keepalive connections continue to use whatever transport they were created with.
 - Module references captured before `installProxyline` ran. Anything that stored `http.request` in a local variable at import time keeps the un-patched reference.
@@ -69,7 +69,7 @@ This is deliberate: two competing proxy patches would race on `http.request` and
 | Threat | Mitigated | Notes |
 | --- | --- | --- |
 | Library passes a direct `http.Agent` per request | yes (managed) | Replaced before the request runs |
-| Library passes a direct `Dispatcher` to managed `globalThis.fetch` | yes | Explicit dispatchers are stripped |
+| Library passes a direct `Dispatcher` to managed `globalThis.fetch` | yes | Proxyline pins its dispatcher |
 | Trusted local endpoint needs direct routing | yes, with `bypassPolicy` | Keep the callback narrow and auditable |
 | Library calls imported `undici.fetch` with a direct `Dispatcher` | no | Imported function references are outside the global fetch patch |
 | Library uses `net.connect` directly | no | Out of scope |

package/docs/surfaces.md

@@ -50,7 +50,7 @@ import { fetch } from "undici";
 await fetch("https://api.example.com/health"); // routed through Proxyline
 ```
 
-In managed mode, Proxyline's patched `globalThis.fetch` ignores explicit `dispatcher` options so a per-call undici `Agent` cannot bypass the managed proxy. In ambient mode, and for callers using imported `undici.fetch` directly, an explicit undici `Agent` or `Dispatcher` still wins. Use `proxy.createUndiciDispatcher()` to get a dispatcher pre-wired to the same policy.
+In managed mode, Proxyline's patched `globalThis.fetch` passes Proxyline's own dispatcher explicitly, so a per-call undici `Agent` or a later `setGlobalDispatcher()` call cannot bypass the managed proxy through that global fetch path. In ambient mode, and for callers using imported `undici.fetch` directly, an explicit undici `Agent` or `Dispatcher` still wins. Use `proxy.createUndiciDispatcher()` to get a dispatcher pre-wired to the same policy.
 
 Proxyline also replaces `globalThis.Request`, `Response`, `Headers`, and `FormData` with versions from its undici dependency so `globalThis.fetch` receives compatible objects on Node versions where the built-in fetch no longer shares the package dispatcher. Requests created before Proxyline installs are normalized through the standard public `Request` fields. Install Proxyline first if you need non-standard Request internals, such as a dispatcher embedded in a pre-install native `Request`, to be preserved.
 

package/docs/testing.md

@@ -15,7 +15,7 @@ pnpm typecheck   # type-only
 
 `pnpm test` builds `dist/`, then runs `node --test` via `tsx` against `test/index.test.ts` (unit), `test/e2e.test.ts` (integration), and `test/package.test.ts` (package entrypoint).
 `pnpm check` enforces native Node coverage for `src/**/*.ts` with thresholds of 85% lines, 80% branches, and 80% functions on Node versions that expose native threshold flags.
-CI runs that check on Ubuntu, macOS, and Windows across Node 20.18.1, 22, 24, and 26; Node 20.18.1 keeps the declared minimum covered with native coverage enabled and skips only the unavailable threshold/include flags.
+CI runs that check on Ubuntu, macOS, and Windows across Node 22.19.0, 24, and 26; Node 22.19.0 keeps the declared minimum covered with native coverage enabled.
 
 ## What the lab covers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/proxyline",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Process-global proxy routing for Node.js.",
   "type": "module",
   "license": "MIT",
@@ -17,7 +17,7 @@
     "url": "https://github.com/openclaw/proxyline/issues"
   },
   "homepage": "https://proxyline.dev",
-  "packageManager": "pnpm@10.33.2",
+  "packageManager": "pnpm@11.1.2",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -56,17 +56,17 @@
     "typecheck": "pnpm build && tsc --noEmit"
   },
   "devDependencies": {
-    "@types/node": "^20.19.40",
-    "@types/ws": "^8.18.1",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "undici": "^7.25.0",
-    "ws": "^8.20.0"
+    "@types/node": "25.8.0",
+    "@types/ws": "8.18.1",
+    "tsx": "4.22.1",
+    "typescript": "6.0.3",
+    "undici": "8.3.0",
+    "ws": "8.20.1"
   },
   "engines": {
-    "node": ">=20.18.1"
+    "node": ">=22.19.0"
   },
   "peerDependencies": {
-    "undici": ">=7.25.0 <9"
+    "undici": ">=8.3.0 <9"
   }
 }

package/src/runtime.ts

@@ -1,11 +1,13 @@
 import http from "node:http";
 import https from "node:https";
 import { AsyncLocalStorage } from "node:async_hooks";
+import net from "node:net";
 import {
   Agent as UndiciAgent,
   Dispatcher,
   FormData as UndiciFormData,
   Headers as UndiciHeaders,
+  Pool as UndiciPool,
   Request as UndiciRequest,
   Response as UndiciResponse,
   errors as undiciErrors,
@@ -72,6 +74,11 @@ type ProxylineDispatcher = Dispatcher & {
   [PROXYLINE_DISPATCHER_BRAND]?: true;
 };
 
+type CompatibleDispatchHandler = Dispatcher.DispatchHandler & {
+  onError?: (error: Error) => void;
+  onResponseError?: (controller: Dispatcher.DispatchController | null, error: Error) => void;
+};
+
 // Node's global fetch types come from bundled undici-types, while the runtime
 // implementation intentionally delegates to this package's undici dependency.
 const proxylineHeaders = UndiciHeaders as unknown as typeof globalThis.Headers;
@@ -214,28 +221,40 @@ async function normalizeFetchInput(
   });
 }
 
-function stripFetchDispatcher(
+function withManagedFetchDispatcher(
   init: Parameters<typeof globalThis.fetch>[1],
+  dispatcher: Dispatcher,
 ): Parameters<typeof globalThis.fetch>[1] {
-  if (typeof init !== "object" || init === null) {
-    return init;
+  if (
+    init !== undefined &&
+    init !== null &&
+    typeof init !== "object" &&
+    typeof init !== "function"
+  ) {
+    throw new TypeError(
+      `Request constructor: Expected ${String(init)} to be one of: Null, Undefined, Object.`,
+    );
   }
-  const sanitized = Object.create(init);
+  const sanitized = init === undefined || init === null ? {} : Object.create(init);
   Reflect.defineProperty(sanitized, "dispatcher", {
     configurable: true,
     enumerable: true,
-    value: undefined,
+    value: dispatcher,
     writable: true,
   });
   return sanitized;
 }
 
 const proxylineFetch: typeof globalThis.fetch = async (input, init) => {
-  const managedMode = activeRuntime?.mode === "managed";
+  const managedDispatcher = activeRuntime?.mode === "managed"
+    ? activeRuntime.installedDispatcher
+    : undefined;
   const normalizedInput = await normalizeFetchInput(input, init, {
-    preserveDispatcher: !managedMode,
+    preserveDispatcher: managedDispatcher === undefined,
   });
-  const normalizedInit = managedMode ? stripFetchDispatcher(init) : init;
+  const normalizedInit = managedDispatcher === undefined
+    ? init
+    : withManagedFetchDispatcher(init, managedDispatcher);
   const response: unknown = await Reflect.apply(
     undiciFetch,
     undefined,
@@ -389,6 +408,11 @@ type UndiciDispatcherOptions = Readonly<{
   proxyCa: string | undefined;
   undici: ProxylineUndiciOptions | undefined;
 }>;
+type UndiciProxyAgentOptions = Exclude<ConstructorParameters<typeof UndiciProxyAgent>[0], string | URL>;
+type UndiciProxyClientFactory = NonNullable<
+  UndiciProxyAgentOptions["clientFactory"]
+>;
+type UnknownFunction = (...args: unknown[]) => unknown;
 
 function finiteNonNegativeInteger(value: number | undefined): number | undefined {
   return typeof value === "number" && Number.isFinite(value) && value >= 0
@@ -434,6 +458,43 @@ function createUndiciAgent(options: ProxylineUndiciOptions | undefined): UndiciA
   return new UndiciAgent(resolveUndiciBaseOptions(options));
 }
 
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stripIpServernameFromConnectOptions(options: unknown): unknown {
+  if (!isObjectRecord(options) || typeof options.servername !== "string") {
+    return options;
+  }
+  const servername = options.servername.replace(/^\[|\]$/g, "");
+  if (net.isIP(servername) === 0) {
+    return options;
+  }
+  const next = { ...options };
+  delete next.servername;
+  return next;
+}
+
+function stripIpServernameFromConnect(connect: unknown): unknown {
+  if (typeof connect !== "function") {
+    return connect;
+  }
+  return (options: unknown, callback: unknown): unknown =>
+    (connect as UnknownFunction)(stripIpServernameFromConnectOptions(options), callback);
+}
+
+function createProxyClientFactory(): UndiciProxyClientFactory {
+  return (origin: URL, options: object): Dispatcher => {
+    const clientOptions = isObjectRecord(options)
+      ? { ...options, connect: stripIpServernameFromConnect(options.connect) }
+      : options;
+    return new UndiciPool(
+      origin,
+      clientOptions as ConstructorParameters<typeof UndiciPool>[1],
+    );
+  };
+}
+
 function createUndiciProxyAgent(
   proxyUrl: string,
   options: UndiciDispatcherOptions,
@@ -441,6 +502,7 @@ function createUndiciProxyAgent(
   return new UndiciProxyAgent({
     ...resolveUndiciBaseOptions(options.undici),
     uri: proxyUrl,
+    clientFactory: createProxyClientFactory(),
     ...(options.proxyCa !== undefined ? { proxyTls: { ca: options.proxyCa } } : {}),
   } as ConstructorParameters<typeof UndiciProxyAgent>[0]);
 }
@@ -460,6 +522,22 @@ function createUndiciProxyDispatcher(
   return new ManagedUndiciDispatcher(options.resolver, dispatcherOptions);
 }
 
+function reportClosedDispatchError(
+  handler: Dispatcher.DispatchHandler,
+  error: Error,
+): boolean {
+  const compatibleHandler = handler as CompatibleDispatchHandler;
+  if (compatibleHandler.onResponseError !== undefined) {
+    compatibleHandler.onResponseError(null, error);
+    return false;
+  }
+  if (compatibleHandler.onError !== undefined) {
+    compatibleHandler.onError(error);
+    return false;
+  }
+  throw error;
+}
+
 class ManagedUndiciDispatcher extends Dispatcher {
   public readonly [PROXYLINE_DISPATCHER_BRAND] = true;
   readonly #directDispatcher: UndiciAgent;
@@ -480,11 +558,7 @@ class ManagedUndiciDispatcher extends Dispatcher {
     handler: Dispatcher.DispatchHandler,
   ): boolean {
     if (this.#closedError !== undefined) {
-      if (handler.onError === undefined) {
-        throw this.#closedError;
-      }
-      handler.onError(this.#closedError);
-      return false;
+      return reportClosedDispatchError(handler, this.#closedError);
     }
     const url = resolveUndiciDispatchUrl(options);
     const proxyUrl = url === undefined ? "" : this.#resolver.getProxyForUrl(url, "undici");
@@ -570,11 +644,7 @@ class AmbientUndiciDispatcher extends Dispatcher {
     handler: Dispatcher.DispatchHandler,
   ): boolean {
     if (this.#closedError !== undefined) {
-      if (handler.onError === undefined) {
-        throw this.#closedError;
-      }
-      handler.onError(this.#closedError);
-      return false;
+      return reportClosedDispatchError(handler, this.#closedError);
     }
     const url = resolveUndiciDispatchUrl(options);
     const proxyUrl = url === undefined ? undefined : resolveAmbientProxyForUrl(url, this.#env);