@openclaw/proxyline 0.2.0 → 0.3.1

package/docs/README.md

@@ -0,0 +1,34 @@
+---
+title: Overview
+permalink: /
+description: "Process-global proxy routing for Node.js. One install routes node:http, node:https, undici/fetch, plus WebSocket and HTTP CONNECT helpers through a single explicit policy."
+---
+
+# Proxyline Documentation
+
+Process-global proxy routing for Node.js. Proxyline patches the network surfaces a Node process can reach without owning a private transport stack, so a single policy applies to `node:http`, `node:https`, undici/fetch, WebSocket clients that accept agents, and explicit HTTP CONNECT helpers.
+
+## Contents
+
+- [Getting Started](./getting-started.md) — install, first proxy, shutdown.
+- [Modes](./modes.md) — `managed` vs `ambient` safety postures.
+- [Surfaces](./surfaces.md) — which network APIs Proxyline covers and how.
+- [API Reference](./api-reference.md) — every exported type, function, and field.
+- [Environment Variables](./environment-variables.md) — how `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` are interpreted.
+- [Proxy TLS](./proxy-tls.md) — scoping CA trust to the proxy endpoint.
+- [Observability](./observability.md) — events, `explain()`, credential redaction.
+- [Security](./security.md) — threat model, limits, what Proxyline does **not** do.
+- [Troubleshooting](./troubleshooting.md) — common failure modes and fixes.
+- [Testing](./testing.md) — the in-process proxy lab.
+
+## Product coverage
+
+- `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`.
+- 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()`.
+- Caller-built `http.Agent` / `https.Agent`: overridden per request in managed and active ambient mode.
+- Raw `net.connect` / `tls.connect`: out of scope; see [Security](./security.md).
+- Native or third-party transport stacks: out of scope; see [Security](./security.md).

package/docs/api-reference.md

@@ -0,0 +1,280 @@
+# API Reference
+
+Every public export, with the exact shape from `src/index.ts`, `src/connect.ts`, and `src/node-http.ts`.
+
+## Functions
+
+### `installProxyline(options): ProxylineHandle`
+
+Aliased as `installGlobalProxy`. Installs the runtime and returns a handle.
+
+- Throws `ProxylineError` with code `MANAGED_PROXY_URL_REQUIRED` if `mode: "managed"` is used without a `proxyUrl`.
+- Throws `ProxylineError` with code `UNSUPPORTED_PROXY_PROTOCOL` if managed-mode `proxyUrl` is not `http://` or `https://`.
+- Throws `ProxylineError` with code `RUNTIME_ALREADY_ACTIVE` if another Proxyline runtime is already installed and `ifActive` is omitted or cannot safely reuse the active runtime.
+
+In managed mode (and active ambient mode), `installProxyline`:
+
+- Captures originals for `http.request`, `http.get`, `http.globalAgent`, `https.request`, `https.get`, `https.globalAgent`.
+- Captures the current undici global dispatcher and fetch globals.
+- Installs patched `http.request`/`get`, `https.request`/`get`.
+- Replaces `http.globalAgent` and `https.globalAgent` with Proxyline's HTTP/HTTPS Node agent.
+- Calls `undici.setGlobalDispatcher` with a `ProxyAgent` (managed) or Proxyline's ambient dispatcher (ambient), and patches `globalThis.fetch` plus `Request`, `Response`, `Headers`, and `FormData` to use that dispatcher-compatible fetch stack.
+- Emits `runtime.installed`.
+
+In inactive ambient mode (no supported proxy env variables), no patches are installed; the handle returns a passive observer with `active: false`.
+
+### `openProxyConnectTunnel(options): Promise<net.Socket | tls.TLSSocket>`
+
+Opens a one-shot HTTP CONNECT tunnel through a proxy. See [Surfaces — HTTP CONNECT tunnel](./surfaces.md#http-connect-tunnel).
+
+### `hasAmbientNodeProxyConfigured(options?): boolean`
+
+Returns `true` when the ambient proxy environment would proxy a probe URL for the requested protocol. Defaults to `protocol: "https"`.
+
+```ts
+hasAmbientNodeProxyConfigured({ protocol: "https" });
+```
+
+### `createAmbientNodeProxyAgent(options?): http.Agent | undefined`
+
+Returns a Proxyline-backed Node agent when ambient env proxy settings apply, or `undefined` when no proxy is configured for the requested protocol. This is for libraries that accept a Node `agent` option but should stay direct when the operator has no proxy env configured.
+
+```ts
+const agent = createAmbientNodeProxyAgent({
+  protocol: "https",
+  proxyTls: { caFile: "/etc/proxy-ca.pem" },
+});
+```
+
+### `redactProxyUrl(value: string | URL): string`
+
+Strips userinfo, search, and fragment from a URL. Used internally to keep events and decisions free of credentials. Safe to use on log lines you build yourself.
+
+```ts
+redactProxyUrl("https://user:secret@proxy.example:8443/path?q=1#frag");
+// → "https://proxy.example:8443/path"
+```
+
+### `resolveProxyTlsCa(options): string | undefined`
+
+Resolves a `ProxylineTlsOptions` value to a PEM string by reading `caFile` from disk if needed. Returns `undefined` when no CA material is supplied. Exposed so callers can pre-resolve before passing values into their own TLS-using code.
+
+## Classes
+
+### `ProxylineError extends Error`
+
+```ts
+class ProxylineError extends Error {
+  readonly code: string;
+  readonly name: "ProxylineError";
+}
+```
+
+Codes:
+
+- `MANAGED_PROXY_URL_REQUIRED` — `mode: "managed"` was used without `proxyUrl`.
+- `UNSUPPORTED_PROXY_PROTOCOL` — proxy URL scheme is not `http://` or `https://`.
+- `RUNTIME_ALREADY_ACTIVE` — another Proxyline runtime is already installed.
+- `CONNECT_FAILED` — `openProxyConnectTunnel` failed (bad response, timeout, header overrun, or socket error).
+- `INVALID_CONNECT_TARGET` — `openProxyConnectTunnel` received an empty or unsafe target host, invalid bracket syntax, or an invalid target port.
+
+## Types
+
+### `ProxylineMode`
+
+```ts
+type ProxylineMode = "managed" | "ambient";
+```
+
+See [Modes](./modes.md).
+
+### `ProxylineSurface`
+
+```ts
+type ProxylineSurface =
+  | "node-http"
+  | "node-https"
+  | "undici"
+  | "websocket"
+  | "connect"
+  | "unknown";
+```
+
+Used in `explain()` decisions and event payloads to identify which network surface a decision is for. Pass it via `explain(url, { surface })`.
+
+### `ProxylineOptions`
+
+```ts
+type ProxylineOptions = Readonly<{
+  mode: ProxylineMode;
+  proxyUrl?: string | URL;
+  proxyTls?: ProxylineTlsOptions;
+  bypassPolicy?: ProxylineBypassPolicy;
+  ifActive?: "error" | "reuse-compatible" | "replace";
+  onEvent?: (event: ProxylineEvent) => void;
+  undici?: ProxylineUndiciOptions;
+}>;
+```
+
+- `mode` — required. `"managed"` or `"ambient"`.
+- `proxyUrl` — required in managed mode, ignored in ambient mode. Managed-mode URLs must be `http://` or `https://`.
+- `proxyTls` — CA trust scoped to the proxy endpoint. See [Proxy TLS](./proxy-tls.md).
+- `bypassPolicy` — managed-mode escape hatch for trusted traffic that should go direct. Ignored in ambient mode.
+- `ifActive` — process singleton behavior when Proxyline is already active. Defaults to `"error"`. `"reuse-compatible"` returns the active handle when mode/proxy/TLS/bypass/undici settings match; ambient mode also requires the captured proxy env snapshot to match. `"replace"` stops the active runtime before installing the new one.
+- `onEvent` — callback fired with every `ProxylineEvent`.
+- `undici` — default options for Proxyline-owned undici dispatchers.
+
+### `ProxylineUndiciOptions`
+
+```ts
+type ProxylineUndiciOptions = Readonly<{
+  allowH2?: boolean;
+  bodyTimeout?: number;
+  headersTimeout?: number;
+  connect?: Readonly<{
+    autoSelectFamily?: boolean;
+    autoSelectFamilyAttemptTimeout?: number;
+  }>;
+}>;
+```
+
+These options apply to the global dispatcher installed by `installGlobalProxy()` and to dispatchers returned by `createUndiciDispatcher()`.
+
+### `ProxylineTlsOptions`
+
+```ts
+type ProxylineTlsOptions = Readonly<{
+  ca?: string;     // PEM string
+  caFile?: string; // path read with fs.readFileSync(..., "utf8")
+}>;
+```
+
+When both are provided, `ca` wins.
+
+### `ProxylineDecision`
+
+```ts
+type ProxylineDecision = Readonly<{
+  kind: "proxied" | "direct" | "blocked";
+  reason: string;
+  surface: ProxylineSurface;
+  url: string;
+  proxyUrl?: string; // redacted
+}>;
+```
+
+Known `reason` values:
+
+- `"managed-proxy-active"` — managed mode applied.
+- `"managed-proxy-bypass-policy"` — managed mode was active, but `bypassPolicy` intentionally sent the URL direct.
+- `"managed-proxy-unsupported-url-scheme"` — managed mode is active, but the URL scheme is not one Proxyline can proxy.
+- `"ambient-proxy-active"` — ambient mode resolved a proxy from env.
+- `"ambient-proxy-not-configured"` — ambient mode has no proxy env set, or the URL scheme is unsupported.
+- `"no-proxy-match"` — the URL matched `NO_PROXY`.
+- `"runtime-stopped"` — `explain()` was called after `stop()`.
+
+`kind: "blocked"` is reserved for future explicit deny rules; the current implementation does not produce blocked decisions.
+
+### `ProxylineBypassRequest`
+
+```ts
+type ProxylineBypassRequest = Readonly<{
+  surface: ProxylineSurface;
+  url: string;
+}>;
+```
+
+### `ProxylineBypassPolicy`
+
+```ts
+type ProxylineBypassPolicy = (request: ProxylineBypassRequest) => boolean;
+```
+
+Return `true` to send that managed-mode request direct. Use this only for explicitly trusted destinations such as loopback control-plane endpoints.
+
+### `ProxylineEvent`
+
+```ts
+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 }>;
+```
+
+`decision` events fire from inside `explain()`. `runtime.installed` and `runtime.stopped` fire from `installProxyline` and `handle.stop()` respectively. `warning` is reserved for future runtime diagnostics.
+
+### `ExplainOptions`
+
+```ts
+type ExplainOptions = Readonly<{
+  surface?: ProxylineSurface;
+}>;
+```
+
+### `ProxylineHandle`
+
+```ts
+type ProxylineHandle = Readonly<{
+  mode: ProxylineMode;
+  active: boolean;
+  proxyUrl?: string;
+  createNodeAgent: () => http.Agent;
+  createUndiciDispatcher: () => Dispatcher;
+  createWebSocketAgent: () => http.Agent;
+  explain: (url: string | URL, options?: ExplainOptions) => ProxylineDecision;
+  registerBypass: (registration: ProxylineBypassRegistration) => () => void;
+  stop: () => void;
+  withBypass: <T>(registration: ProxylineBypassRegistration, run: () => T) => T;
+}>;
+```
+
+- `mode` — the mode this handle was installed with.
+- `active` — `true` when the runtime is installed and forcing/respecting a proxy.
+- `proxyUrl` — redacted proxy URL string when active.
+- `createNodeAgent()` — proxy-aware `http.Agent` for ad-hoc node:http(s) use. Returns a direct agent when inactive or after `stop()`.
+- `createUndiciDispatcher()` — proxy-aware undici `Dispatcher`. Returns a direct `UndiciAgent()` when ambient-inactive or after `stop()`.
+- `createWebSocketAgent()` — same as `createNodeAgent()` but typed for WebSocket clients.
+- `explain(url, options?)` — returns a `ProxylineDecision` and emits a `decision` event.
+- `registerBypass({ url, surface? })` — managed-mode process-wide bypass. Returns an unregister callback. When `surface` is omitted, the bypass matches any surface for that exact URL.
+- `stop()` — restores the captured Node HTTP(S) stack, undici dispatcher, and fetch globals, destroys Proxyline-owned runtime agents/dispatchers, emits `runtime.stopped`. Idempotent.
+- `withBypass(registration, run)` — applies a bypass only to `run()` and async work created inside that callback.
+
+### Dispatcher Detection
+
+```ts
+isProxylineDispatcher(dispatcher: unknown): boolean;
+```
+
+Returns `true` for Proxyline-owned managed and ambient undici dispatchers. Use this instead of constructor-name checks when integrating with code that also manages undici globals. Import from `@openclaw/proxyline/dispatcher-brand` when detection must not load Proxyline's full runtime.
+
+### `OpenProxyConnectTunnelOptions`
+
+```ts
+type OpenProxyConnectTunnelOptions = Readonly<{
+  proxyUrl: string | URL;
+  proxyTls?: ProxylineTlsOptions;
+  targetHost: string;
+  targetPort: number;
+  timeoutMs?: number;
+}>;
+```
+
+- `proxyUrl` — `http://` or `https://`. Userinfo becomes a `Proxy-Authorization: Basic` header.
+- `proxyTls` — CA trust for HTTPS proxies. See [Proxy TLS](./proxy-tls.md).
+- `targetHost` / `targetPort` — what to ask the proxy to connect to.
+- `timeoutMs` — overall budget for the CONNECT handshake.
+
+### `AmbientNodeProxyAgentOptions`
+
+```ts
+type AmbientNodeProxyAgentOptions = {
+  env?: ProxyEnvSnapshot;
+  protocol?: "http" | "https";
+  proxyTls?: ProxylineTlsOptions;
+};
+```
+
+- `env` — optional env snapshot. Defaults to reading process env.
+- `protocol` — probe protocol, defaulting to `"https"`.
+- `proxyTls` — CA trust for HTTPS proxy endpoints. See [Proxy TLS](./proxy-tls.md).

package/docs/environment-variables.md

@@ -0,0 +1,70 @@
+# Environment Variables
+
+Ambient mode reads its configuration from the environment at install time. Managed mode does not.
+
+## Variables
+
+| Variable | Used for | Notes |
+| --- | --- | --- |
+| `HTTP_PROXY` | proxy for `http:` and `ws:` URLs | lower case wins when both are set |
+| `HTTPS_PROXY` | proxy for `https:` and `wss:` URLs | |
+| `ALL_PROXY` | fallback when the protocol-specific variable is unset or unsupported | |
+| `NO_PROXY` | comma- or whitespace-separated list of exemptions | matched against the destination URL |
+| `http_proxy` | lowercase alias for `HTTP_PROXY` | takes precedence over uppercase |
+| `https_proxy` | lowercase alias | |
+| `all_proxy` | lowercase alias | |
+| `no_proxy` | lowercase alias | |
+
+Empty or whitespace-only values are treated as unset.
+
+## Activation
+
+The ambient runtime is **active** when any of `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY` (or their lowercase forms) is set to a supported `http://` or `https://` proxy endpoint. Bare endpoints count because Proxyline defaults them to `http://`.
+
+`NO_PROXY` alone does not activate the runtime. With only `NO_PROXY` set, `proxy.active` is `false` and Proxyline installs no patches.
+
+## Snapshot at install
+
+The values are read **once** at `installProxyline` time. Changing `process.env.HTTP_PROXY` afterwards does not retroactively activate or reconfigure Proxyline. Call `proxy.stop()` and re-install if the environment changes.
+
+## Proxy URL parsing
+
+- Bare endpoints (no scheme) default to `http://`. `HTTPS_PROXY=proxy.corp:8080` becomes `http://proxy.corp:8080`.
+- `http://` and `https://` are the only accepted schemes. Anything else is ignored.
+- Userinfo (`user:pass@`) in the proxy URL becomes a `Proxy-Authorization: Basic` header.
+
+## NO_PROXY matching
+
+Entries are split on commas and whitespace. Matching rules, in order:
+
+1. `*` alone matches everything. The URL goes direct.
+2. Entries can include a port: `internal.corp:8443`. When present, the entry only matches the URL's port (defaulting to `80` for `http`/`ws` and `443` for `https`/`wss`).
+3. Entries starting with `.` or `*` are suffix matches. `.corp.example` matches `api.corp.example` and `corp.example`. `*.corp.example` is equivalent.
+4. Other entries are exact host matches.
+5. IPv6 entries may be bracketed (`[::1]:8443`) or bare (`::1`). Bracketed forms are stripped before comparison.
+6. Hostnames are lowercased and trailing dots are stripped before comparison.
+
+When a URL matches `NO_PROXY`, `explain()` returns `kind: "direct"`, `reason: "no-proxy-match"`.
+
+## Examples
+
+```bash
+# go through the proxy for everything except internal hosts
+export HTTPS_PROXY="https://proxy.corp.example:8443"
+export NO_PROXY=".corp.example,localhost,127.0.0.1,::1"
+```
+
+```bash
+# only https traffic via proxy, http stays direct
+export HTTPS_PROXY="https://proxy.corp.example:8443"
+```
+
+```bash
+# fall through to ALL_PROXY for everything
+export ALL_PROXY="socks-not-supported://example"   # ignored — only http/https proxies are honored
+export ALL_PROXY="http://gateway.corp:3128"        # used for both http and https URLs
+```
+
+## Interaction with `fetch`
+
+The undici global dispatcher is installed with Proxyline's own ambient resolver over the same `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` snapshot Proxyline read at install time. `fetch` and `node:http` therefore agree on the proxy decision for any URL.

package/docs/getting-started.md

@@ -0,0 +1,82 @@
+# Getting Started
+
+Proxyline targets Node.js 20.18.1+. It is published as `@openclaw/proxyline` and ships ESM with TypeScript types.
+
+## Install
+
+```bash
+pnpm add @openclaw/proxyline
+# or
+npm install @openclaw/proxyline
+# or
+yarn add @openclaw/proxyline
+```
+
+## Install Proxyline first
+
+Patches replace `http.request`, `http.get`, `https.request`, `https.get`, `http.globalAgent`, `https.globalAgent`, the undici global dispatcher, and the fetch globals. Any module that captured the original references before Proxyline installs will bypass the runtime. Initialize Proxyline before importing third-party HTTP clients when proxy routing is a security policy.
+
+```ts
+// entry.ts — first import in your application
+import { installGlobalProxy } from "@openclaw/proxyline";
+
+const proxy = installGlobalProxy({
+  mode: "managed",
+  proxyUrl: "https://proxy.corp.example:8443",
+  proxyTls: { caFile: "/etc/proxy-ca.pem" },
+});
+
+// only now load the rest of the app
+await import("./app.js");
+```
+
+## Minimal managed proxy
+
+Managed mode treats proxy routing as policy: setup failures throw, requests are forced through the configured proxy, and caller-supplied `http.Agent` / `https.Agent` instances are replaced per request.
+
+```ts
+import { installGlobalProxy } from "@openclaw/proxyline";
+
+const proxy = installGlobalProxy({
+  mode: "managed",
+  proxyUrl: "https://proxy.corp.example:8443",
+  onEvent: (event) => console.debug("[proxyline]", event),
+});
+
+const decision = proxy.explain("https://api.example.com/");
+console.log(decision.kind, decision.reason, decision.proxyUrl);
+```
+
+## Minimal ambient proxy
+
+Ambient mode reads the usual environment variables. With no proxy configured, requests stay direct and `explain()` reports `ambient-proxy-not-configured`.
+
+```bash
+export HTTPS_PROXY="http://proxy.corp.example:8080"
+export NO_PROXY="metadata.google.internal,127.0.0.1"
+```
+
+```ts
+import { installGlobalProxy } from "@openclaw/proxyline";
+
+const proxy = installGlobalProxy({ mode: "ambient" });
+console.log(proxy.active);            // true if a supported HTTP_PROXY/HTTPS_PROXY/ALL_PROXY is set
+console.log(proxy.proxyUrl);          // redacted URL string when active
+```
+
+See [Modes](./modes.md) for the full posture contract and [Environment Variables](./environment-variables.md) for parsing rules.
+
+## Shutdown
+
+Call `proxy.stop()` from your shutdown path (and from tests). It restores the saved Node HTTP(S) methods and global agents, restores the previous undici global dispatcher and fetch globals, and destroys the internal proxy agent. Only one Proxyline runtime can be active at a time; a second install throws `RUNTIME_ALREADY_ACTIVE` by default unless you opt into compatible reuse or replacement with `ifActive`.
+
+```ts
+process.once("SIGTERM", () => proxy.stop());
+process.once("SIGINT", () => proxy.stop());
+```
+
+## What to read next
+
+- [Surfaces](./surfaces.md) for per-API behavior, including WebSocket and CONNECT helpers.
+- [Observability](./observability.md) to log decisions without leaking credentials.
+- [Security](./security.md) for the boundaries of what Proxyline can enforce.

package/docs/index.md

@@ -0,0 +1,46 @@
+# Proxyline
+
+Process-global proxy routing for Node.js.
+
+Proxyline patches the network surfaces a Node process can reach without owning a private transport stack, so one policy applies to `node:http`, `node:https`, undici/fetch, WebSocket clients that accept agents, and explicit HTTP CONNECT helpers.
+
+## Start
+
+- [Getting Started](./getting-started.md)
+- [Modes](./modes.md)
+- [Surfaces](./surfaces.md)
+- [API Reference](./api-reference.md)
+- [Environment Variables](./environment-variables.md)
+- [Proxy TLS](./proxy-tls.md)
+- [Observability](./observability.md)
+- [Security](./security.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Testing](./testing.md)
+
+## Install
+
+```bash
+pnpm add @openclaw/proxyline
+```
+
+## 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" },
+});
+
+console.log(proxy.explain("https://api.example.com/"));
+```
+
+## Ambient Mode
+
+```ts
+import { installGlobalProxy } from "@openclaw/proxyline";
+
+const proxy = installGlobalProxy({ mode: "ambient" });
+```

package/docs/modes.md

@@ -0,0 +1,68 @@
+# Modes
+
+Proxyline models two safety postures. The `mode` option selects one explicitly — there is no implicit fallback between them.
+
+## Managed
+
+Managed mode treats proxy routing as a security policy.
+
+- `proxyUrl` is **required**. Omitting it throws `ProxylineError` with code `MANAGED_PROXY_URL_REQUIRED`.
+- Only `http://` and `https://` proxy endpoints are accepted. Other schemes throw `UNSUPPORTED_PROXY_PROTOCOL`.
+- The managed proxy is forced for HTTP(S) and WS(S) requests on the patched surfaces.
+- `bypassPolicy`, `registerBypass()`, and `withBypass()` are the managed-mode direct-routing escape hatches. They match `{ surface, url }` and intentionally send matching requests direct. `registerBypass()` is process-wide until unregistered; `withBypass()` is limited to the callback's async context.
+- Caller-supplied `http.Agent` or `https.Agent` values are replaced per request. TLS-relevant agent options (`ca`, `cert`, `key`, `ciphers`, `minVersion`, `maxVersion`, `rejectUnauthorized`, etc.) are copied onto the proxy request so destination TLS identity is preserved. See [Surfaces — TLS identity preservation](./surfaces.md#tls-identity-preservation) for the full list.
+- The undici global dispatcher is replaced with Proxyline's managed dispatcher, backed by `undici.ProxyAgent` instances pointed at `proxyUrl`.
+- Environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, ...) are **ignored**.
+- `explain()` returns `kind: "proxied"` with `reason: "managed-proxy-active"` for supported URL schemes. Bypassed URLs return `kind: "direct"` with `reason: "managed-proxy-bypass-policy"`. Unsupported schemes return `kind: "direct"` with `reason: "managed-proxy-unsupported-url-scheme"` because Proxyline has no safe proxy mapping for them.
+
+Use managed mode when "go direct" must never be silent. If your network policy demands traffic egress through a specific gateway, this is the posture you want.
+
+```ts
+const proxy = installGlobalProxy({
+  mode: "managed",
+  proxyUrl: "https://proxy.corp.example:8443",
+  proxyTls: { caFile: "/etc/proxy-ca.pem" },
+  bypassPolicy: ({ url }) => new URL(url).hostname === "127.0.0.1",
+});
+```
+
+## Ambient
+
+Ambient mode mirrors the conventional "respect the environment" behavior used by most CLI tooling.
+
+- `proxyUrl` is **ignored** if supplied. Configuration comes from `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` (and their lowercase forms).
+- The runtime only installs patches when at least one of `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY` resolves to a supported `http://` or `https://` proxy endpoint. `proxy.active` is `false` otherwise and the handle behaves as a passive observer.
+- Per-request proxy resolution honors protocol-specific variables, falls back to `ALL_PROXY`, and applies `NO_PROXY` matching (suffix, wildcard, exact, IPv6).
+- Bare endpoints (no scheme) default to `http://` — e.g. `HTTPS_PROXY=proxy.corp:8080` becomes `http://proxy.corp:8080`.
+- The undici global dispatcher becomes Proxyline's ambient dispatcher so `fetch` sees the same routing rules.
+- `explain()` returns one of:
+  - `kind: "proxied"`, `reason: "ambient-proxy-active"` — a proxy applies.
+  - `kind: "direct"`, `reason: "no-proxy-match"` — `NO_PROXY` exempted the host.
+  - `kind: "direct"`, `reason: "ambient-proxy-not-configured"` — no supported proxy variables are set, the configured proxy scheme is unsupported, or the URL scheme is unsupported.
+
+Use ambient mode for tooling and CLIs that need best-effort compatibility with whatever the operator has configured.
+
+```ts
+const proxy = installGlobalProxy({ mode: "ambient" });
+if (!proxy.active) {
+  console.warn("no HTTP_PROXY/HTTPS_PROXY/ALL_PROXY set — direct egress");
+}
+```
+
+## Comparison
+
+| Behavior | `managed` | `ambient` |
+| --- | --- | --- |
+| Requires `proxyUrl` | yes | no (ignored if passed) |
+| Reads env variables | no | yes |
+| Honors `NO_PROXY` | no | yes |
+| Supports `bypassPolicy` | yes | no |
+| Forces traffic through proxy | yes | only when env says so |
+| Replaces caller-supplied agents | yes | yes (when active) |
+| Installs undici dispatcher | `ProxyAgent` | Proxyline ambient dispatcher |
+| `explain()` direct reason | `managed-proxy-bypass-policy` or `managed-proxy-unsupported-url-scheme` | `no-proxy-match` or `ambient-proxy-not-configured` |
+| Setup failure mode | throws | inactive but installed |
+
+## Why a strict managed mode
+
+If you mix environment-based configuration with a security policy you get drift: a missing variable, a forgotten `NO_PROXY` entry, or a transient unset turns "always through the proxy" into "sometimes direct." Managed mode refuses to start without the URL and refuses to honor environment overrides, so the policy is encoded in code, not in shell state.

package/docs/observability.md

@@ -0,0 +1,98 @@
+# Observability
+
+Proxyline exposes its decisions through two channels: an `onEvent` callback and an `explain()` method on the handle. Both share the same `ProxylineDecision` shape and the same credential-redaction rules.
+
+## Events
+
+Subscribe at install time:
+
+```ts
+const proxy = installGlobalProxy({
+  mode: "managed",
+  proxyUrl: "https://user:secret@proxy.corp.example:8443",
+  onEvent: (event) => log(event),
+});
+```
+
+Event types:
+
+- `runtime.installed` — fired once at install. Includes `mode`, `active`, and the redacted `proxyUrl`.
+- `runtime.stopped` — fired from `handle.stop()`. Includes `mode`.
+- `decision` — fired from every `explain()` call. Includes the full decision.
+- `warning` — reserved for future runtime diagnostics.
+
+`runtime.installed` is the cleanest place to confirm "this is the proxy we're actually using" in logs.
+
+## explain()
+
+Ask Proxyline what it would do for a given URL:
+
+```ts
+const decision = proxy.explain("https://api.example.com/v1/users", {
+  surface: "undici",
+});
+
+// decision.kind: "proxied" | "direct" | "blocked"
+// decision.reason: "managed-proxy-active" | "ambient-proxy-active" | ...
+// decision.surface: "undici"
+// decision.url: "https://api.example.com/v1/users"
+// decision.proxyUrl: "https://proxy.corp.example:8443/"   (redacted)
+```
+
+`explain()` does not perform a request; it inspects the resolver and returns its verdict. It also emits a `decision` event, so a single callback can capture every explicit routing probe in your logs.
+
+After `stop()`, `explain()` returns `kind: "direct"`, `reason: "runtime-stopped"`.
+
+## Credential redaction
+
+Anywhere Proxyline reports a proxy URL — in `handle.proxyUrl`, `decision.proxyUrl`, and the `runtime.installed` event — it passes the URL through `redactProxyUrl`. That strips userinfo, search, and fragment:
+
+```ts
+redactProxyUrl("https://user:secret@proxy.example:8443/path?token=abc#fragment");
+// → "https://proxy.example:8443/path"
+```
+
+Use it on URLs you log yourself to keep credentials out of operational data.
+
+## Logging recipes
+
+### Per-request decision log
+
+```ts
+const proxy = installGlobalProxy({
+  mode: "managed",
+  proxyUrl: process.env.PROXY_URL!,
+  onEvent: (event) => {
+    if (event.type === "decision") {
+      logger.info({
+        url: event.decision.url,
+        proxyUrl: event.decision.proxyUrl,
+        kind: event.decision.kind,
+        reason: event.decision.reason,
+        surface: event.decision.surface,
+      }, "proxy decision");
+    }
+  },
+});
+```
+
+`explain()` is decoupled from real requests, so wire it into the codepaths you actually care about, e.g. inside a fetch wrapper:
+
+```ts
+async function loggedFetch(url: string, init?: RequestInit) {
+  proxy.explain(url, { surface: "undici" });
+  return fetch(url, init);
+}
+```
+
+### Install / stop audit
+
+```ts
+onEvent: (event) => {
+  if (event.type === "runtime.installed") {
+    logger.info({ mode: event.mode, active: event.active, proxyUrl: event.proxyUrl }, "proxyline up");
+  } else if (event.type === "runtime.stopped") {
+    logger.info({ mode: event.mode }, "proxyline down");
+  }
+}
+```