@openclaw/proxyline 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 - 2026-05-11
+
+- Initial public release of `@openclaw/proxyline` for process-global proxy routing in Node.js.
+- Added managed mode for fail-closed proxy policy with required `proxyUrl`, global `node:http`/`node:https` patching, global agent replacement, and undici/fetch routing through `ProxyAgent`.
+- Added ambient mode for `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, lowercase variants, bare proxy endpoints, and `NO_PROXY` exemptions with matching diagnostics.
+- Added proxy-aware helpers for Node agents, WebSocket clients, undici dispatchers, and explicit HTTP CONNECT tunnels.
+- Added scoped proxy TLS trust via `proxyTls.ca` and `proxyTls.caFile`, preserving destination TLS identity while trusting private proxy CAs.
+- Added structured observability with `explain()`, `onEvent`, redacted proxy URLs, install/stop lifecycle events, and per-decision diagnostics.
+- Added runtime cleanup with `proxy.stop()` to restore captured Node HTTP(S) methods, global agents, and the undici global dispatcher.
+- Added credential-safe proxy authorization handling for proxy URLs with userinfo.
+- Added in-process proxy lab coverage for HTTP, HTTPS, CONNECT, WebSocket, undici/fetch, proxy auth, loopback blocking, HTTPS proxies, TLS preservation, and IPv6 `NO_PROXY`.
+- Added full documentation for getting started, modes, surfaces, API reference, environment variables, proxy TLS, observability, security, troubleshooting, and testing.
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesse Merhi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# Proxyline
+
+[![npm](https://img.shields.io/npm/v/@openclaw/proxyline.svg)](https://www.npmjs.com/package/@openclaw/proxyline)
+[![node](https://img.shields.io/node/v/@openclaw/proxyline.svg)](https://nodejs.org/)
+[![license](https://img.shields.io/npm/l/@openclaw/proxyline.svg)](./LICENSE)
+
+Process-global proxy routing for Node.js. One install replaces `node:http`, `node:https`, the undici/fetch global dispatcher, and routes WebSocket and explicit HTTP CONNECT traffic through the same policy.
+
+Proxyline exists to make proxy behavior **explicit, observable, and hard to bypass accidentally** — so that "all egress goes through this gateway" is something you encode in code rather than hope for from environment variables.
+
+Website: [proxyline.dev](https://proxyline.dev)
+
+## Highlights
+
+- **Two modes.** `managed` forces traffic through a configured proxy and fails closed on bad config. `ambient` reads `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY` for tooling that needs environment compatibility.
+- **Covers the surfaces that matter.** `http.request`, `http.get`, `https.request`, `https.get`, both global agents, the undici global dispatcher, and helpers for WebSocket agents and HTTP CONNECT sockets.
+- **Replaces caller agents.** In managed mode, a per-request `http.Agent` passed by a library does not bypass the proxy. TLS options on the caller agent (`ca`, `cert`, `key`, `rejectUnauthorized`, …) are preserved so destination TLS still validates.
+- **Scoped proxy CA trust.** `proxyTls.ca` / `proxyTls.caFile` trust a private CA for the proxy endpoint only — no `NODE_EXTRA_CA_CERTS` and no `NODE_TLS_REJECT_UNAUTHORIZED=0`.
+- **Observable.** `proxy.explain(url)` returns a structured decision (`proxied` / `direct` with a `reason`), and an `onEvent` callback receives `runtime.installed`, `runtime.stopped`, and per-decision events. Proxy URLs are credential-redacted.
+- **Restoreable.** `proxy.stop()` restores the captured Node HTTP(S) methods, global agents, and undici dispatcher. The runtime is a process-wide singleton — a second install throws `RUNTIME_ALREADY_ACTIVE`.
+
+## Install
+
+```bash
+pnpm add @openclaw/proxyline
+# or
+npm install @openclaw/proxyline
+```
+
+Requires Node 20+.
+
+## Quick start
+
+### Managed mode
+
+```ts
+import { installGlobalProxy } from "@openclaw/proxyline";
+
+const proxy = installGlobalProxy({
+  mode: "managed",
+  proxyUrl: "https://proxy.corp.example:8443",
+  proxyTls: { caFile: "/etc/proxy-ca.pem" },
+  onEvent: (event) => console.debug("[proxyline]", event),
+});
+
+console.log(proxy.explain("https://api.example.com/"));
+```
+
+### Ambient mode
+
+```ts
+import { installGlobalProxy } from "@openclaw/proxyline";
+
+const proxy = installGlobalProxy({ mode: "ambient" });
+if (!proxy.active) {
+  console.warn("no HTTP_PROXY/HTTPS_PROXY/ALL_PROXY set — egress will be direct");
+}
+```
+
+### WebSocket
+
+```ts
+import WebSocket from "ws";
+
+const socket = new WebSocket("wss://events.example.com/", {
+  agent: proxy.createWebSocketAgent(),
+});
+```
+
+### Explicit HTTP CONNECT
+
+```ts
+import { openProxyConnectTunnel } from "@openclaw/proxyline";
+
+const socket = await openProxyConnectTunnel({
+  proxyUrl: "https://proxy.corp.example:8443",
+  proxyTls: { caFile: "/etc/proxy-ca.pem" },
+  targetHost: "api.example.com",
+  targetPort: 443,
+  timeoutMs: 2_000,
+});
+```
+
+## Feature matrix
+
+| Surface | Covered | Notes |
+| --- | --- | --- |
+| `http.request` / `http.get` | yes | global method patch + global agent swap |
+| `https.request` / `https.get` | yes | global method patch + global agent swap |
+| `fetch` / undici global dispatcher | yes | `setGlobalDispatcher` |
+| WebSocket clients accepting a Node `agent` | yes | `proxy.createWebSocketAgent()` |
+| Caller-built `http.Agent` / `https.Agent` | overridden in managed mode | TLS options preserved |
+| Explicit HTTP CONNECT socket | yes | `openProxyConnectTunnel()` |
+| Raw `net.connect` / `tls.connect` | no | out of scope, see [Security](./docs/security.md) |
+| Native or private transport stacks | no | out of scope, see [Security](./docs/security.md) |
+
+## Why not just env vars?
+
+Environment-based proxies are best-effort. A missing variable, a stale shell, a `NO_PROXY` typo, or a library that built its own `Dispatcher` quietly turns "always through the proxy" into "sometimes direct." Proxyline encodes the policy in code, replaces caller-built agents, and exposes a structured decision so logs can prove every request went the right way.
+
+For tooling that *should* honor whatever the operator configured, ambient mode keeps the conventional behavior — with the same observability and the same credential redaction.
+
+## Documentation
+
+Full docs live in [`docs/`](./docs/README.md):
+
+- [Getting Started](./docs/getting-started.md)
+- [Modes](./docs/modes.md) — managed vs ambient
+- [Surfaces](./docs/surfaces.md) — per-API behavior
+- [API Reference](./docs/api-reference.md)
+- [Environment Variables](./docs/environment-variables.md)
+- [Proxy TLS](./docs/proxy-tls.md)
+- [Observability](./docs/observability.md)
+- [Security](./docs/security.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+- [Testing](./docs/testing.md)
+
+## Limits
+
+Proxyline is a Node-process runtime, not an operating-system sandbox. Code can still bypass it by using raw `net`, raw `tls`, custom native networking, or a library that owns a private transport stack. Anything that captured `http.request` or `https.request` before Proxyline installed also bypasses it — install before loading third-party integrations when proxy routing is a security policy. See [`docs/security.md`](./docs/security.md) for the full threat model.
+
+## License
+
+[MIT](./LICENSE)

package/dist/connect.d.ts

@@ -0,0 +1,14 @@
+import net from "node:net";
+import tls from "node:tls";
+import { type ProxylineTlsOptions } from "./shared.js";
+export type OpenProxyConnectTunnelOptions = Readonly<{
+    proxyUrl: string | URL;
+    proxyTls?: ProxylineTlsOptions;
+    targetHost: string;
+    targetPort: number;
+    timeoutMs?: number;
+}>;
+type ProxySocket = net.Socket | tls.TLSSocket;
+export declare function openProxyConnectTunnel(options: OpenProxyConnectTunnelOptions): Promise<ProxySocket>;
+export {};
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,EAAkB,KAAK,mBAAmB,EAAqC,MAAM,aAAa,CAAC;AAE1G,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC;IACnD,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC;IACvB,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAIH,KAAK,WAAW,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,SAAS,CAAC;AA6D9C,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,WAAW,CAAC,CA6GtB"}

package/dist/connect.js

@@ -0,0 +1,153 @@
+import net from "node:net";
+import tls from "node:tls";
+import { ProxylineError, redactProxyUrl, resolveProxyTlsCa } from "./shared.js";
+const MAX_CONNECT_RESPONSE_HEADER_BYTES = 16 * 1024;
+function resolveProxyHost(proxy) {
+    return (proxy.hostname || proxy.host).replace(/^\[|\]$/g, "");
+}
+function resolveProxyPort(proxy) {
+    if (proxy.port) {
+        return Number(proxy.port);
+    }
+    return proxy.protocol === "https:" ? 443 : 80;
+}
+function resolveProxyAuthorization(proxy) {
+    if (!proxy.username && !proxy.password) {
+        return undefined;
+    }
+    const username = decodeURIComponent(proxy.username);
+    const password = decodeURIComponent(proxy.password);
+    return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+}
+function connectToProxy(proxy, proxyTls) {
+    const host = resolveProxyHost(proxy);
+    const connectOptions = {
+        host,
+        port: resolveProxyPort(proxy),
+    };
+    if (proxy.protocol === "https:") {
+        const ca = resolveProxyTlsCa(proxyTls);
+        const servername = net.isIP(host) === 0 ? host : undefined;
+        return tls.connect({
+            ...connectOptions,
+            ALPNProtocols: ["http/1.1"],
+            ...(servername !== undefined ? { servername } : {}),
+            ...(ca !== undefined ? { ca } : {}),
+        });
+    }
+    if (proxy.protocol === "http:") {
+        return net.connect(connectOptions);
+    }
+    throw new ProxylineError("UNSUPPORTED_PROXY_PROTOCOL", `CONNECT tunnels support http:// and https:// proxy endpoints: ${proxy.protocol}`);
+}
+function writeConnectRequest(socket, proxy, target) {
+    const headers = [`CONNECT ${target} HTTP/1.1`, `Host: ${target}`, "Proxy-Connection: Keep-Alive"];
+    const authorization = resolveProxyAuthorization(proxy);
+    if (authorization !== undefined) {
+        headers.push(`Proxy-Authorization: ${authorization}`);
+    }
+    socket.write([...headers, "", ""].join("\r\n"));
+}
+function failConnect(proxy, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new ProxylineError("CONNECT_FAILED", `Proxy CONNECT failed via ${redactProxyUrl(proxy)}: ${message}`);
+}
+export async function openProxyConnectTunnel(options) {
+    const proxy = options.proxyUrl instanceof URL ? new URL(options.proxyUrl.href) : new URL(options.proxyUrl);
+    const target = `${options.targetHost}:${options.targetPort}`;
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        let responseBuffer = Buffer.alloc(0);
+        let timeout;
+        let socket;
+        const cleanup = () => {
+            if (timeout !== undefined) {
+                clearTimeout(timeout);
+                timeout = undefined;
+            }
+            socket?.off("data", onData);
+            socket?.off("error", onError);
+            socket?.off("end", onClosed);
+            socket?.off("close", onClosed);
+            socket?.off("connect", onConnected);
+            socket?.off("secureConnect", onConnected);
+        };
+        const fail = (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            socket?.destroy();
+            reject(failConnect(proxy, error));
+        };
+        const succeed = (connectedSocket, tunneledBytes) => {
+            if (settled) {
+                connectedSocket.destroy();
+                return;
+            }
+            settled = true;
+            cleanup();
+            if (tunneledBytes !== undefined && tunneledBytes.length > 0) {
+                connectedSocket.unshift(tunneledBytes);
+            }
+            resolve(connectedSocket);
+        };
+        const onConnected = () => {
+            if (socket === undefined) {
+                fail(new Error("proxy socket missing after connect"));
+                return;
+            }
+            writeConnectRequest(socket, proxy, target);
+        };
+        const onData = (chunk) => {
+            responseBuffer = Buffer.concat([responseBuffer, chunk]);
+            const headerEnd = responseBuffer.indexOf("\r\n\r\n");
+            if (headerEnd === -1) {
+                if (responseBuffer.length > MAX_CONNECT_RESPONSE_HEADER_BYTES) {
+                    fail(new Error(`proxy CONNECT response headers exceeded ${MAX_CONNECT_RESPONSE_HEADER_BYTES} bytes`));
+                }
+                return;
+            }
+            const bodyOffset = headerEnd + 4;
+            if (bodyOffset > MAX_CONNECT_RESPONSE_HEADER_BYTES) {
+                fail(new Error(`proxy CONNECT response headers exceeded ${MAX_CONNECT_RESPONSE_HEADER_BYTES} bytes`));
+                return;
+            }
+            const responseHeader = responseBuffer.subarray(0, bodyOffset).toString("latin1");
+            const statusLine = responseHeader.split("\r\n", 1)[0] ?? "";
+            if (!/^HTTP\/1\.[01] 2\d\d\b/.test(statusLine)) {
+                fail(new Error(statusLine || "proxy returned an invalid CONNECT response"));
+                return;
+            }
+            if (socket === undefined) {
+                fail(new Error("proxy socket missing after CONNECT response"));
+                return;
+            }
+            const tunneledBytes = responseBuffer.length > bodyOffset ? responseBuffer.subarray(bodyOffset) : undefined;
+            succeed(socket, tunneledBytes);
+        };
+        const onError = (error) => {
+            fail(error);
+        };
+        const onClosed = () => {
+            fail(new Error("proxy socket closed before CONNECT response"));
+        };
+        try {
+            if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
+                timeout = setTimeout(() => {
+                    fail(new Error(`proxy CONNECT timed out after ${Math.trunc(options.timeoutMs ?? 0)}ms`));
+                }, Math.trunc(options.timeoutMs));
+            }
+            socket = connectToProxy(proxy, options.proxyTls);
+            socket.once(proxy.protocol === "https:" ? "secureConnect" : "connect", onConnected);
+            socket.on("data", onData);
+            socket.once("error", onError);
+            socket.once("end", onClosed);
+            socket.once("close", onClosed);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import http from "node:http";
+import { type Dispatcher } from "undici";
+import { type ProxylineTlsOptions } from "./shared.js";
+export { ProxylineError, redactProxyUrl, resolveProxyTlsCa, type ProxylineTlsOptions, } from "./shared.js";
+export { openProxyConnectTunnel, type OpenProxyConnectTunnelOptions } from "./connect.js";
+export type ProxylineMode = "managed" | "ambient";
+export type ProxylineSurface = "node-http" | "node-https" | "undici" | "websocket" | "connect" | "unknown";
+export type ProxylineOptions = Readonly<{
+    mode: ProxylineMode;
+    proxyUrl?: string | URL;
+    proxyTls?: ProxylineTlsOptions;
+    onEvent?: (event: ProxylineEvent) => void;
+}>;
+export type ProxylineDecision = Readonly<{
+    kind: "proxied" | "direct" | "blocked";
+    reason: string;
+    surface: ProxylineSurface;
+    url: string;
+    proxyUrl?: string;
+}>;
+export type ProxylineEvent = Readonly<{
+    type: "runtime.installed";
+    mode: ProxylineMode;
+    active: boolean;
+    proxyUrl?: string;
+}> | Readonly<{
+    type: "runtime.stopped";
+    mode: ProxylineMode;
+}> | Readonly<{
+    type: "decision";
+    decision: ProxylineDecision;
+}> | Readonly<{
+    type: "warning";
+    code: string;
+    message: string;
+}>;
+export type ExplainOptions = Readonly<{
+    surface?: ProxylineSurface;
+}>;
+export type ProxylineHandle = Readonly<{
+    mode: ProxylineMode;
+    active: boolean;
+    proxyUrl?: string;
+    createNodeAgent: () => http.Agent;
+    createUndiciDispatcher: () => Dispatcher;
+    createWebSocketAgent: () => http.Agent;
+    explain: (url: string | URL, options?: ExplainOptions) => ProxylineDecision;
+    stop: () => void;
+}>;
+export declare function installProxyline(options: ProxylineOptions): ProxylineHandle;
+export declare const installGlobalProxy: typeof installProxyline;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAI7B,OAAO,EAEL,KAAK,UAAU,EAKhB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,sBAAsB,EAAE,KAAK,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAE1F,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC;AAElD,MAAM,MAAM,gBAAgB,GACxB,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,WAAW,GACX,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IACxB,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAC3C,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,gBAAgB,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH,MAAM,MAAM,cAAc,GACtB,QAAQ,CAAC;IACP,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,GACF,QAAQ,CAAC;IACP,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,aAAa,CAAC;CACrB,CAAC,GACF,QAAQ,CAAC;IACP,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,iBAAiB,CAAC;CAC7B,CAAC,GACF,QAAQ,CAAC;IACP,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEP,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B,CAAC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC;IAClC,sBAAsB,EAAE,MAAM,UAAU,CAAC;IACzC,oBAAoB,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC;IACvC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,CAAC,EAAE,cAAc,KAAK,iBAAiB,CAAC;IAC5E,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC,CAAC;AAsjBH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAmF3E;AAED,eAAO,MAAM,kBAAkB,yBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,522 @@
+import http from "node:http";
+import https from "node:https";
+import net from "node:net";
+import { ProxyAgent as NodeProxyAgent } from "proxy-agent";
+import { Agent as UndiciAgent, EnvHttpProxyAgent, getGlobalDispatcher, ProxyAgent as UndiciProxyAgent, setGlobalDispatcher, } from "undici";
+import { ProxylineError, redactProxyUrl, resolveProxyTlsCa, } from "./shared.js";
+export { ProxylineError, redactProxyUrl, resolveProxyTlsCa, } from "./shared.js";
+export { openProxyConnectTunnel } from "./connect.js";
+function normalizeProxyUrl(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const url = value instanceof URL ? new URL(value.href) : new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new ProxylineError("UNSUPPORTED_PROXY_PROTOCOL", `Proxyline only supports http:// and https:// proxy endpoints in this slice: ${url.protocol}`);
+    }
+    return url;
+}
+function emit(onEvent, event) {
+    onEvent?.(event);
+}
+function formatUrl(value) {
+    return value instanceof URL ? value.href : new URL(value).href;
+}
+const CALLER_AGENT_TLS_OPTION_KEYS = [
+    "ca",
+    "cert",
+    "ciphers",
+    "clientCertEngine",
+    "crl",
+    "dhparam",
+    "ecdhCurve",
+    "honorCipherOrder",
+    "key",
+    "maxVersion",
+    "minVersion",
+    "passphrase",
+    "pfx",
+    "rejectUnauthorized",
+    "secureOptions",
+    "secureProtocol",
+    "sessionIdContext",
+];
+let activeRuntime;
+const EMPTY_PROXY_ENV = {
+    HTTP_PROXY: undefined,
+    HTTPS_PROXY: undefined,
+    ALL_PROXY: undefined,
+    NO_PROXY: undefined,
+    http_proxy: undefined,
+    https_proxy: undefined,
+    all_proxy: undefined,
+    no_proxy: undefined,
+};
+function copyNodeHttpOptions(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {};
+    }
+    return { ...value };
+}
+function readAgentOptions(agent) {
+    if (agent === undefined || agent === false) {
+        return undefined;
+    }
+    return agent.options;
+}
+function preserveCallerAgentOptions(options) {
+    const agentOptions = readAgentOptions(options.agent);
+    if (agentOptions === undefined) {
+        return;
+    }
+    for (const key of CALLER_AGENT_TLS_OPTION_KEYS) {
+        const value = agentOptions[key];
+        if (value !== undefined && options[key] === undefined) {
+            options[key] = value;
+        }
+    }
+}
+function inferDestinationHostname(url, options) {
+    if (url !== undefined) {
+        return url instanceof URL ? url.hostname : new URL(url).hostname;
+    }
+    if (typeof options.hostname === "string") {
+        return options.hostname;
+    }
+    if (typeof options.host === "string") {
+        return options.host.replace(/:\d*$/, "");
+    }
+    return undefined;
+}
+function preserveDestinationTlsIdentity(url, options) {
+    if (options.servername !== undefined) {
+        return;
+    }
+    const hostname = inferDestinationHostname(url, options);
+    if (!hostname) {
+        return;
+    }
+    if (net.isIP(hostname) === 0) {
+        options.servername = hostname;
+    }
+}
+function bindNodeHttpMethod(originalMethod, createAgent) {
+    return ((...args) => {
+        let url;
+        let options;
+        let callback;
+        const firstArg = args[0];
+        if (typeof firstArg === "string" || firstArg instanceof URL) {
+            url = firstArg;
+            if (typeof args[1] === "function") {
+                options = {};
+                callback = args[1];
+            }
+            else {
+                options = copyNodeHttpOptions(args[1]);
+                callback = args[2];
+            }
+        }
+        else {
+            options = copyNodeHttpOptions(firstArg);
+            callback = args[1];
+        }
+        preserveCallerAgentOptions(options);
+        preserveDestinationTlsIdentity(url, options);
+        const agent = createAgent(options);
+        options.agent = agent;
+        delete options.createConnection;
+        if (url !== undefined) {
+            const request = originalMethod(url, options, callback);
+            request.once("close", () => {
+                agent.destroy();
+            });
+            return request;
+        }
+        const request = originalMethod(options, callback);
+        request.once("close", () => {
+            agent.destroy();
+        });
+        return request;
+    });
+}
+function readProxyEnv() {
+    return {
+        HTTP_PROXY: process.env.HTTP_PROXY,
+        HTTPS_PROXY: process.env.HTTPS_PROXY,
+        ALL_PROXY: process.env.ALL_PROXY,
+        NO_PROXY: process.env.NO_PROXY,
+        http_proxy: process.env.http_proxy,
+        https_proxy: process.env.https_proxy,
+        all_proxy: process.env.all_proxy,
+        no_proxy: process.env.no_proxy,
+    };
+}
+function normalizeEnvValue(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function upperProxyEnvKey(key) {
+    switch (key) {
+        case "http_proxy":
+            return "HTTP_PROXY";
+        case "https_proxy":
+            return "HTTPS_PROXY";
+        case "all_proxy":
+            return "ALL_PROXY";
+        case "no_proxy":
+            return "NO_PROXY";
+    }
+}
+function readProxyEnvValue(env, key) {
+    return normalizeEnvValue(env[key]) ?? normalizeEnvValue(env[upperProxyEnvKey(key)]);
+}
+function proxyUrlWithDefaultScheme(proxyUrl) {
+    return proxyUrl.includes("://") ? proxyUrl : `http://${proxyUrl}`;
+}
+function defaultPort(protocol) {
+    if (protocol === "http:" || protocol === "ws:") {
+        return 80;
+    }
+    if (protocol === "https:" || protocol === "wss:") {
+        return 443;
+    }
+    return 0;
+}
+function matchesNoProxy(url, env) {
+    const rawNoProxy = readProxyEnvValue(env, "no_proxy")?.toLowerCase();
+    if (!rawNoProxy) {
+        return false;
+    }
+    if (rawNoProxy === "*") {
+        return true;
+    }
+    const hostname = normalizeNoProxyHost(url.hostname);
+    const port = Number.parseInt(url.port, 10) || defaultPort(url.protocol);
+    for (const rawEntry of rawNoProxy.split(/[,\s]/)) {
+        if (!rawEntry) {
+            continue;
+        }
+        const { host: parsedHost, port: entryPort } = parseNoProxyEntry(rawEntry);
+        let entryHost = normalizeNoProxyHost(parsedHost);
+        if (entryPort && entryPort !== port) {
+            continue;
+        }
+        if (!/^[.*]/.test(entryHost)) {
+            if (hostname === entryHost) {
+                return true;
+            }
+            continue;
+        }
+        if (entryHost.startsWith("*")) {
+            entryHost = entryHost.slice(1);
+        }
+        if (hostname.endsWith(entryHost)) {
+            return true;
+        }
+    }
+    return false;
+}
+function normalizeNoProxyHost(hostname) {
+    const normalized = hostname.trim().toLowerCase().replace(/\.+$/, "");
+    return normalized.startsWith("[") && normalized.endsWith("]")
+        ? normalized.slice(1, -1)
+        : normalized;
+}
+function parseNoProxyEntry(entry) {
+    const bracketedIpv6 = entry.match(/^\[([^\]]+)\](?::(\d+))?$/);
+    if (bracketedIpv6) {
+        return {
+            host: bracketedIpv6[1] ?? "",
+            port: bracketedIpv6[2] ? Number.parseInt(bracketedIpv6[2], 10) : 0,
+        };
+    }
+    const lastColon = entry.lastIndexOf(":");
+    const hasSingleColon = lastColon !== -1 && entry.indexOf(":") === lastColon;
+    if (hasSingleColon) {
+        const possiblePort = entry.slice(lastColon + 1);
+        if (/^\d+$/.test(possiblePort)) {
+            return {
+                host: entry.slice(0, lastColon),
+                port: Number.parseInt(possiblePort, 10),
+            };
+        }
+    }
+    return { host: entry, port: 0 };
+}
+function formatNoProxyEntryForUndici(entry) {
+    const { host, port } = parseNoProxyEntry(entry);
+    const normalizedHost = normalizeNoProxyHost(host);
+    const formattedHost = normalizedHost.includes(":") ? `[${normalizedHost}]` : host;
+    return port ? `${formattedHost}:${port}` : formattedHost;
+}
+function normalizeNoProxyForUndici(noProxy) {
+    if (noProxy === undefined) {
+        return undefined;
+    }
+    const entries = noProxy
+        .split(/[,\s]/)
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map(formatNoProxyEntryForUndici);
+    return entries.length > 0 ? entries.join(",") : undefined;
+}
+function proxyEnvKeyForProtocol(protocol) {
+    if (protocol === "http:" || protocol === "ws:") {
+        return "http_proxy";
+    }
+    if (protocol === "https:" || protocol === "wss:") {
+        return "https_proxy";
+    }
+    return undefined;
+}
+function resolveAmbientProxyForUrl(url, env) {
+    let parsedUrl;
+    try {
+        parsedUrl = url instanceof URL ? new URL(url.href) : new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+    const protocol = parsedUrl.protocol;
+    if (protocol !== "http:" &&
+        protocol !== "https:" &&
+        protocol !== "ws:" &&
+        protocol !== "wss:") {
+        return undefined;
+    }
+    if (matchesNoProxy(parsedUrl, env)) {
+        return undefined;
+    }
+    const protocolProxyKey = proxyEnvKeyForProtocol(protocol);
+    if (protocolProxyKey === undefined) {
+        return undefined;
+    }
+    const proxy = readProxyEnvValue(env, protocolProxyKey) ?? readProxyEnvValue(env, "all_proxy");
+    return proxy ? proxyUrlWithDefaultScheme(proxy) : undefined;
+}
+function createManagedProxyResolver(proxyUrl) {
+    const redactedProxyUrl = redactProxyUrl(proxyUrl);
+    return {
+        active: true,
+        describeProxy: () => redactedProxyUrl,
+        explain: (url, surface) => ({
+            kind: "proxied",
+            reason: "managed-proxy-active",
+            surface,
+            url: formatUrl(url),
+            proxyUrl: redactedProxyUrl,
+        }),
+        getProxyForUrl: (url) => {
+            const protocol = new URL(url).protocol;
+            return protocol === "http:" ||
+                protocol === "https:" ||
+                protocol === "ws:" ||
+                protocol === "wss:"
+                ? proxyUrl.href
+                : "";
+        },
+    };
+}
+function createAmbientProxyResolver(env) {
+    const configuredProxy = readProxyEnvValue(env, "http_proxy") ??
+        readProxyEnvValue(env, "https_proxy") ??
+        readProxyEnvValue(env, "all_proxy");
+    return {
+        active: configuredProxy !== undefined,
+        describeProxy: () => configuredProxy
+            ? redactProxyUrl(proxyUrlWithDefaultScheme(configuredProxy))
+            : undefined,
+        explain: (url, surface) => {
+            const formattedUrl = formatUrl(url);
+            const proxyUrl = resolveAmbientProxyForUrl(formattedUrl, env);
+            if (proxyUrl !== undefined) {
+                return {
+                    kind: "proxied",
+                    reason: "ambient-proxy-active",
+                    surface,
+                    url: formattedUrl,
+                    proxyUrl: redactProxyUrl(proxyUrl),
+                };
+            }
+            return {
+                kind: "direct",
+                reason: matchesNoProxy(new URL(formattedUrl), env)
+                    ? "no-proxy-match"
+                    : "ambient-proxy-not-configured",
+                surface,
+                url: formattedUrl,
+            };
+        },
+        getProxyForUrl: (url) => resolveAmbientProxyForUrl(url, env) ?? "",
+    };
+}
+function createNodeProxyAgent(resolver, proxyCa, options) {
+    return new NodeProxyAgent({
+        ...(proxyCa !== undefined ? { ca: proxyCa } : {}),
+        ...(options?.cert !== undefined ? { cert: options.cert } : {}),
+        ...(options?.ciphers !== undefined ? { ciphers: options.ciphers } : {}),
+        ...(options?.clientCertEngine !== undefined ? { clientCertEngine: options.clientCertEngine } : {}),
+        ...(options?.crl !== undefined ? { crl: options.crl } : {}),
+        ...(options?.dhparam !== undefined ? { dhparam: options.dhparam } : {}),
+        ...(options?.ecdhCurve !== undefined ? { ecdhCurve: options.ecdhCurve } : {}),
+        ...(options?.honorCipherOrder !== undefined ? { honorCipherOrder: options.honorCipherOrder } : {}),
+        ...(options?.key !== undefined ? { key: options.key } : {}),
+        ...(options?.maxVersion !== undefined ? { maxVersion: options.maxVersion } : {}),
+        ...(options?.minVersion !== undefined ? { minVersion: options.minVersion } : {}),
+        ...(options?.passphrase !== undefined ? { passphrase: options.passphrase } : {}),
+        ...(options?.pfx !== undefined ? { pfx: options.pfx } : {}),
+        ...(options?.rejectUnauthorized !== undefined ? { rejectUnauthorized: options.rejectUnauthorized } : {}),
+        ...(options?.secureOptions !== undefined ? { secureOptions: options.secureOptions } : {}),
+        ...(options?.secureProtocol !== undefined ? { secureProtocol: options.secureProtocol } : {}),
+        ...(options?.servername !== undefined ? { servername: options.servername } : {}),
+        ...(options?.sessionIdContext !== undefined ? { sessionIdContext: options.sessionIdContext } : {}),
+        getProxyForUrl: resolver.getProxyForUrl,
+        httpAgent: new http.Agent(),
+        httpsAgent: new https.Agent(),
+    });
+}
+function createUndiciProxyDispatcher(options, proxyCa) {
+    if (options.mode === "ambient") {
+        if (!options.active) {
+            return new UndiciAgent();
+        }
+        const rawHttpProxy = readProxyEnvValue(options.env, "http_proxy") ?? readProxyEnvValue(options.env, "all_proxy");
+        const rawHttpsProxy = readProxyEnvValue(options.env, "https_proxy") ??
+            readProxyEnvValue(options.env, "all_proxy");
+        const noProxy = normalizeNoProxyForUndici(readProxyEnvValue(options.env, "no_proxy"));
+        return new EnvHttpProxyAgent({
+            ...(rawHttpProxy !== undefined
+                ? { httpProxy: proxyUrlWithDefaultScheme(rawHttpProxy) }
+                : {}),
+            ...(rawHttpsProxy !== undefined
+                ? { httpsProxy: proxyUrlWithDefaultScheme(rawHttpsProxy) }
+                : {}),
+            ...(noProxy !== undefined ? { noProxy } : {}),
+            ...(proxyCa !== undefined ? { proxyTls: { ca: proxyCa } } : {}),
+        });
+    }
+    return new UndiciProxyAgent({
+        uri: options.proxyUrl,
+        ...(proxyCa !== undefined ? { proxyTls: { ca: proxyCa } } : {}),
+    });
+}
+function installRuntime(resolver, dispatcherOptions, proxyCa) {
+    if (activeRuntime !== undefined) {
+        throw new ProxylineError("RUNTIME_ALREADY_ACTIVE", "Proxyline already has an active runtime.");
+    }
+    const snapshot = {
+        httpRequest: http.request,
+        httpGet: http.get,
+        httpGlobalAgent: http.globalAgent,
+        httpsRequest: https.request,
+        httpsGet: https.get,
+        httpsGlobalAgent: https.globalAgent,
+    };
+    const nodeAgent = createNodeProxyAgent(resolver, proxyCa);
+    const originalDispatcher = getGlobalDispatcher();
+    const runtime = {
+        nodeAgent,
+        originalDispatcher,
+        snapshot,
+    };
+    activeRuntime = runtime;
+    try {
+        http.globalAgent = nodeAgent;
+        https.globalAgent = nodeAgent;
+        http.request = bindNodeHttpMethod(snapshot.httpRequest, (options) => createNodeProxyAgent(resolver, proxyCa, options));
+        http.get = bindNodeHttpMethod(snapshot.httpGet, (options) => createNodeProxyAgent(resolver, proxyCa, options));
+        https.request = bindNodeHttpMethod(snapshot.httpsRequest, (options) => createNodeProxyAgent(resolver, proxyCa, options));
+        https.get = bindNodeHttpMethod(snapshot.httpsGet, (options) => createNodeProxyAgent(resolver, proxyCa, options));
+        setGlobalDispatcher(createUndiciProxyDispatcher(dispatcherOptions, proxyCa));
+    }
+    catch (error) {
+        activeRuntime = undefined;
+        nodeAgent.destroy();
+        throw error;
+    }
+    return runtime;
+}
+function stopRuntime(runtime) {
+    if (activeRuntime !== runtime) {
+        return;
+    }
+    http.request = runtime.snapshot.httpRequest;
+    http.get = runtime.snapshot.httpGet;
+    http.globalAgent = runtime.snapshot.httpGlobalAgent;
+    https.request = runtime.snapshot.httpsRequest;
+    https.get = runtime.snapshot.httpsGet;
+    https.globalAgent = runtime.snapshot.httpsGlobalAgent;
+    setGlobalDispatcher(runtime.originalDispatcher);
+    runtime.nodeAgent.destroy();
+    activeRuntime = undefined;
+}
+export function installProxyline(options) {
+    const proxyUrl = options.mode === "managed" ? normalizeProxyUrl(options.proxyUrl) : undefined;
+    if (options.mode === "managed" && proxyUrl === undefined) {
+        throw new ProxylineError("MANAGED_PROXY_URL_REQUIRED", "Proxyline managed mode requires an explicit proxyUrl.");
+    }
+    let stopped = false;
+    const proxyCa = resolveProxyTlsCa(options.proxyTls);
+    const ambientEnv = proxyUrl === undefined ? readProxyEnv() : undefined;
+    const resolver = proxyUrl !== undefined
+        ? createManagedProxyResolver(proxyUrl)
+        : createAmbientProxyResolver(ambientEnv ?? EMPTY_PROXY_ENV);
+    const redactedProxyUrl = resolver.describeProxy();
+    const hasActiveProxy = resolver.active;
+    const runtime = hasActiveProxy
+        ? installRuntime(resolver, proxyUrl !== undefined
+            ? { mode: "managed", proxyUrl: proxyUrl.href }
+            : { mode: "ambient", env: ambientEnv ?? EMPTY_PROXY_ENV, active: hasActiveProxy }, proxyCa)
+        : undefined;
+    emit(options.onEvent, {
+        type: "runtime.installed",
+        mode: options.mode,
+        active: hasActiveProxy,
+        ...(redactedProxyUrl ? { proxyUrl: redactedProxyUrl } : {}),
+    });
+    const handle = {
+        mode: options.mode,
+        active: hasActiveProxy,
+        ...(redactedProxyUrl ? { proxyUrl: redactedProxyUrl } : {}),
+        createNodeAgent: () => {
+            if (!hasActiveProxy) {
+                return new http.Agent();
+            }
+            return createNodeProxyAgent(resolver, proxyCa);
+        },
+        createUndiciDispatcher: () => createUndiciProxyDispatcher(proxyUrl !== undefined
+            ? { mode: "managed", proxyUrl: proxyUrl.href }
+            : { mode: "ambient", env: ambientEnv ?? EMPTY_PROXY_ENV, active: hasActiveProxy }, proxyCa),
+        createWebSocketAgent: () => {
+            if (!hasActiveProxy) {
+                return new http.Agent();
+            }
+            return createNodeProxyAgent(resolver, proxyCa);
+        },
+        explain: (url, explainOptions) => {
+            const decision = stopped
+                ? {
+                    kind: "direct",
+                    reason: "runtime-stopped",
+                    surface: explainOptions?.surface ?? "unknown",
+                    url: formatUrl(url),
+                }
+                : resolver.explain(url, explainOptions?.surface ?? "unknown");
+            emit(options.onEvent, { type: "decision", decision });
+            return decision;
+        },
+        stop: () => {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            if (runtime !== undefined) {
+                stopRuntime(runtime);
+            }
+            emit(options.onEvent, { type: "runtime.stopped", mode: options.mode });
+        },
+    };
+    return handle;
+}
+export const installGlobalProxy = installProxyline;

package/dist/shared.d.ts

@@ -0,0 +1,11 @@
+export type ProxylineTlsOptions = Readonly<{
+    ca?: string;
+    caFile?: string;
+}>;
+export declare class ProxylineError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function resolveProxyTlsCa(options: ProxylineTlsOptions | undefined): string | undefined;
+export declare function redactProxyUrl(value: string | URL): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAKjD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAW9F;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,MAAM,CAO1D"}

package/dist/shared.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+export class ProxylineError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ProxylineError";
+        this.code = code;
+    }
+}
+export function resolveProxyTlsCa(options) {
+    if (!options) {
+        return undefined;
+    }
+    if (options.ca !== undefined) {
+        return options.ca;
+    }
+    if (options.caFile !== undefined) {
+        return fs.readFileSync(options.caFile, "utf8");
+    }
+    return undefined;
+}
+export function redactProxyUrl(value) {
+    const url = value instanceof URL ? new URL(value.href) : new URL(value);
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    return url.href;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@openclaw/proxyline",
+  "version": "0.1.0",
+  "description": "Process-global proxy routing for Node.js.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jesse Merhi",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openclaw/proxyline.git"
+  },
+  "bugs": {
+    "url": "https://github.com/openclaw/proxyline/issues"
+  },
+  "homepage": "https://proxyline.dev",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "dist/*.d.ts.map",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.19.25",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "ws": "^8.20.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "proxy-agent": "^8.0.1",
+    "undici": "^7.25.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "pnpm typecheck && pnpm test && pnpm build",
+    "docs:build": "node scripts/build-docs-site.mjs",
+    "package:dry-run": "pnpm pack --dry-run",
+    "publish:dry-run": "pnpm publish --dry-run --access public",
+    "test": "tsx --test test/index.test.ts test/e2e.test.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}