@karoc/dsh-proxy 0.1.4 → 0.1.18

package/lib/index.js

@@ -1,9 +1,186 @@
+import { createRequire } from "node:module";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { createServer, request } from "node:http";
-import { connect } from "node:net";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Agent, createServer, request } from "node:http";
+import { connect, isIPv6 } from "node:net";
 import { connect as connect$1 } from "node:tls";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+//#region src/egress.ts
+/**
+* In-process egress for dsh-proxy: put the harness's OWN requests (model calls,
+* web fetch/search) behind this plugin's loopback forward proxy.
+*
+* Why this is not just "set some env vars": dsh resolves its egress policy from
+* the environment it was LAUNCHED with, before any plugin mounts
+* (`apps/cli/src/profile-boot.ts` → `@deepseek-ai/dsh-http-proxy`
+* `installProxyFromEnvironment`), and that package owns undici's global
+* dispatcher. Child processes inherit variables this plugin publishes, but the
+* harness's own `fetch` does not read them afterwards — which is why model
+* traffic stayed direct on a systemd-run `dsh web` while npm/git/curl were
+* proxied.
+*
+* The same public installer is reachable from a plugin, and layering a policy is
+* a designed behavior (the package's own suite covers a second install layered
+* over the launcher's). So when — and only when — the launch environment named
+* no proxy at all, this plugin installs a policy that points http/https at its
+* own listener.
+*
+* The "only when" is a correctness rule, not politeness: this plugin's proxy
+* sends hosts that are not ticked DIRECT, so layering it over a launcher's proxy
+* would silently bypass that launcher's egress policy (a desktop shell or a
+* corporate launcher that set `HTTP_PROXY` on purpose). A launcher that already
+* decides egress keeps deciding it; the settings page says so and offers the
+* port/launch-environment route instead.
+*/
+/** The harness package that owns undici's global dispatcher and the route matcher. */
+const POLICY_PACKAGE = "@deepseek-ai/dsh-http-proxy";
+/**
+* Resolve the policy package the way a plugin installed INTO A PROFILE would:
+* the bare specifier first (hoisted layouts), then anchored at each candidate
+* file — the profile's own `package.json` (that is where the harness resolved it
+* from, so the import lands on the same module instance and `proxyRouteFor`
+* callers see our policy too), the dsh entry point, and the working directory.
+*
+* Resolution is best-effort by design: a failure is REPORTED (the page then
+* tells the user to declare the proxy in the launch environment instead), never
+* silently ignored.
+*/
+function createPolicyImporter(anchors) {
+	return async () => {
+		const failures = [];
+		try {
+			return await import(POLICY_PACKAGE);
+		} catch (error) {
+			failures.push(`bare specifier — ${error.message}`);
+		}
+		for (const anchor of anchors) try {
+			const resolved = createRequire(anchor).resolve(POLICY_PACKAGE);
+			const module = await import(pathToFileURL(resolved).href);
+			if (typeof module.installProxyFromEnvironment !== "function") {
+				failures.push(`${anchor} — resolved ${resolved} without installProxyFromEnvironment`);
+				continue;
+			}
+			return module;
+		} catch (error) {
+			failures.push(`${anchor} — ${error.message}`);
+		}
+		throw new Error(`${POLICY_PACKAGE} is not resolvable here (${failures.join(" | ")})`);
+	};
+}
+/**
+* Install the harness policy that routes http/https at `proxyUrl`, unless a
+* launcher already declared egress.
+*
+* @param opts.proxyUrl - this plugin's loopback proxy, e.g. `http://127.0.0.1:41234`.
+* @param opts.launch - the launch-time proxy variable, or null when there was none.
+* @param opts.importer - resolves the harness policy module.
+* @param opts.log - receives the policy module's own diagnostics.
+* @returns the outcome, including the disposer that restores the previous policy.
+*/
+async function installInProcessEgress(opts) {
+	if (opts.launch !== null) return {
+		status: "launcher",
+		detail: `${opts.launch.name} was set before dsh started — the launcher owns egress`,
+		dispose: null
+	};
+	let policy;
+	try {
+		policy = await opts.importer();
+	} catch (error) {
+		return {
+			status: "unavailable",
+			detail: error.message,
+			dispose: null
+		};
+	}
+	const values = {
+		HTTP_PROXY: opts.proxyUrl,
+		HTTPS_PROXY: opts.proxyUrl,
+		NO_PROXY: "127.0.0.1,localhost,::1,[::1]"
+	};
+	try {
+		return {
+			status: "self-installed",
+			detail: null,
+			dispose: await policy.installProxyFromEnvironment({ get(name) {
+				const hit = values[name] ?? values[name.toUpperCase()];
+				return hit === void 0 ? void 0 : { value: hit };
+			} }, opts.log)
+		};
+	} catch (error) {
+		return {
+			status: "unavailable",
+			detail: error.message,
+			dispose: null
+		};
+	}
+}
+//#endregion
+//#region src/host-match.ts
+/**
+* Host matching shared by the HOST half (routing, observation, provider list) and
+* the CLIENT half (which row reads *via upstream*). Kept in one module because a
+* second copy is how the IPv6 spellings drifted apart in the first place: a URL
+* parser hands over `[::1]`, Node normalizes an IPv4-mapped literal to
+* `::ffff:7f00:1`, and a CONNECT authority is `[::1]:443` — all the same host.
+*
+* No node builtins here: this module is bundled into the browser bundle too.
+*/
+const LOOPBACK = /^(127\.\d{1,3}\.\d{1,3}\.\d{1,3}|localhost|::1|0\.0\.0\.0)$/i;
+/**
+* Normalize a host so ONE comparison covers every spelling it arrives in.
+* @param host - hostname, possibly bracketed (`[::1]`) or IPv4-mapped.
+* @returns the comparable form (brackets stripped, IPv4-mapped collapsed).
+*/
+function normalizeHostForMatch(host) {
+	const bare = String(host ?? "").trim().toLowerCase().replace(/^\[|\]$/g, "");
+	const dotted = bare.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+	if (dotted !== null) return dotted[1];
+	const mapped = bare.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+	if (mapped === null) return bare;
+	const hi = Number.parseInt(mapped[1], 16);
+	const lo = Number.parseInt(mapped[2], 16);
+	return [
+		hi >> 8,
+		hi & 255,
+		lo >> 8,
+		lo & 255
+	].join(".");
+}
+/** Whether `host` is a loopback/unspecified target in any of its spellings. */
+function isLoopbackHost(host) {
+	return LOOPBACK.test(normalizeHostForMatch(host));
+}
+/**
+* Split a CONNECT authority into the routing host and port. `[v6]:port` keeps its
+* brackets around the ADDRESS only — splitting on ':' turns the whole thing into
+* host `[`, which both defeats the loopback test and pollutes the host list.
+* @param authority - the CONNECT request target.
+* @returns the host and port, or null when the authority is unusable.
+*/
+function parseConnectAuthority(authority) {
+	const value = String(authority ?? "");
+	const match = value.match(/^\[([^\]]+)\](?::(\d+))?$/) ?? value.match(/^([^:]+):(\d+)$/);
+	if (match === null) return null;
+	const host = match[1].trim().toLowerCase();
+	if (host === "") return null;
+	const port = Number(match[2]);
+	return {
+		host,
+		port: Number.isInteger(port) && port > 0 && port <= 65535 ? port : 443
+	};
+}
+/**
+* Format host:port for a request line / Host header (brackets for IPv6).
+* @param host - bare or bracketed host.
+* @param port - target port.
+*/
+function formatAuthority(host, port) {
+	const bare = String(host ?? "").trim();
+	return bare.includes(":") ? `[${bare}]:${port}` : `${bare}:${port}`;
+}
+//#endregion
 //#region src/proxy-core.ts
 /**
 * dsh-proxy core: a loopback forward proxy with per-host routing, ported
@@ -31,14 +208,64 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 *   * loopback targets are ALWAYS direct (never sent to an upstream proxy);
 *   * an upstream pointing back at this very proxy is treated as disabled
 *     (self-loop guard);
-*   * the proxy itself uses raw net/http (never undici's env-proxy), so it can
-*     never route its own outbound connections back through itself.
+*   * the proxy itself uses raw net/http through an explicit Agent (never the
+*     environment proxy), so it can never route its own outbound connections
+*     back through itself — even when the launch environment sets
+*     NODE_USE_ENV_PROXY for the host's own fetch.
 */
-const LOOPBACK = /^(127\.\d{1,3}\.\d{1,3}\.\d{1,3}|localhost|::1|0\.0\.0\.0)$/i;
 /** Upstream proxy protocol, defaulting to http (legacy configs have no field). */
 function upstreamProtocol(cfg) {
 	return String(cfg?.upstream?.protocol || "http").toLowerCase();
 }
+/**
+* Expand an IPv6 literal into its 16 wire bytes (SOCKS5 ATYP=4). Handles `::`
+* compression, an embedded IPv4 tail (`::ffff:1.2.3.4`) and a zone id
+* (`fe80::1%eth0` — a zone has no wire representation and is dropped).
+* Returns null when the text is not a valid IPv6 address.
+*/
+function ipv6ToBytes(address) {
+	let text = String(address ?? "").trim().toLowerCase();
+	const zone = text.indexOf("%");
+	if (zone >= 0) text = text.slice(0, zone);
+	if (text === "") return null;
+	const halves = text.split("::");
+	if (halves.length > 2) return null;
+	const parseGroups = (part) => {
+		if (part === "") return [];
+		const groups = [];
+		for (const group of part.split(":")) {
+			if (group.includes(".")) {
+				const octets = group.split(".");
+				if (octets.length !== 4) return null;
+				for (const octet of octets) if (!/^\d{1,3}$/.test(octet) || Number(octet) > 255) return null;
+				const [a, b, c, d] = octets.map(Number);
+				groups.push(a << 8 | b, c << 8 | d);
+				continue;
+			}
+			if (!/^[0-9a-f]{1,4}$/.test(group)) return null;
+			groups.push(Number.parseInt(group, 16));
+		}
+		return groups;
+	};
+	const head = parseGroups(halves[0]);
+	if (head === null) return null;
+	let groups;
+	if (halves.length === 2) {
+		const tail = parseGroups(halves[1]);
+		if (tail === null) return null;
+		const missing = 8 - head.length - tail.length;
+		if (missing < 1) return null;
+		groups = [
+			...head,
+			...new Array(missing).fill(0),
+			...tail
+		];
+	} else {
+		if (head.length !== 8) return null;
+		groups = head;
+	}
+	return Buffer.from(groups.flatMap((group) => [group >> 8 & 255, group & 255]));
+}
 /** Read exactly n bytes from a socket (SOCKS5 fixed-size frames). */
 function readExactly(socket, n, timeoutMs = 1e4) {
 	return new Promise((resolvePromise, rejectPromise) => {
@@ -130,7 +357,11 @@ async function socks5Handshake(socket, upstream, targetHost, targetPort) {
 	const isIpv4 = /^\d{1,3}(?:\.\d{1,3}){3}$/.test(targetHost);
 	let addrPart;
 	if (isIpv4) addrPart = Buffer.concat([Buffer.from([1]), ...targetHost.split(".").map((o) => Buffer.from([Number(o) & 255]))]);
-	else {
+	else if (isIPv6(targetHost)) {
+		const bytes = ipv6ToBytes(targetHost);
+		if (bytes === null) throw new Error(`socks5: cannot encode IPv6 target ${targetHost}`);
+		addrPart = Buffer.concat([Buffer.from([4]), bytes]);
+	} else {
 		const name = Buffer.from(targetHost, "ascii");
 		addrPart = Buffer.concat([Buffer.from([3, name.length]), name]);
 	}
@@ -187,7 +418,7 @@ function openUpstreamTunnel(cfg, targetHost, targetPort, authHeader) {
 						rest: Buffer.alloc(0)
 					});
 				} else {
-					const lines = [`CONNECT ${targetHost}:${targetPort} HTTP/1.1`, `Host: ${targetHost}:${targetPort}`];
+					const lines = [`CONNECT ${formatAuthority(targetHost, targetPort)} HTTP/1.1`, `Host: ${formatAuthority(targetHost, targetPort)}`];
 					if (authHeader) lines.push(`Proxy-Authorization: ${authHeader}`);
 					socket.write(lines.join("\r\n") + "\r\n\r\n");
 					const { head, rest } = await readUntil(socket, "\r\n\r\n");
@@ -215,29 +446,148 @@ function defaultProxyConfig() {
 			password: ""
 		},
 		proxiedHosts: [],
-		knownHosts: []
+		knownHosts: [],
+		listenPort: 0,
+		routeMode: "only-listed"
 	};
 }
 /** Read <configFile> (proxy.json), tolerant of a missing/corrupt file. */
+const lastGoodConfig = /* @__PURE__ */ new Map();
+/**
+* Write a file so that a concurrent reader can never observe a half-written
+* document: the bytes land in a sibling temp file first and `rename` swaps it in
+* atomically. Without this, a read landing between truncate and write parses as
+* broken and the request it belongs to falls back to the DEFAULT config — the
+* upstream silently stops being used for that request.
+*/
+function writeFileAtomic(file, text) {
+	const temp = `${file}.tmp-${process.pid}`;
+	try {
+		writeFileSync(temp, text);
+		renameSync(temp, file);
+	} catch (error) {
+		try {
+			unlinkSync(temp);
+		} catch {}
+		throw error;
+	}
+}
+/** Read + sanitize proxy.json, remembering the last document that parsed. */
 function readProxyConfig(configFile) {
 	try {
 		const raw = JSON.parse(readFileSync(configFile, "utf8"));
-		return {
+		const cfg = {
 			...defaultProxyConfig(),
 			...raw ?? {},
 			upstream: {
 				...defaultProxyConfig().upstream,
 				...raw?.upstream ?? {}
-			}
+			},
+			listenPort: normalizeListenPort(raw?.listenPort),
+			routeMode: normalizeRouteMode(raw?.routeMode)
 		};
+		lastGoodConfig.set(configFile, cfg);
+		return cfg;
 	} catch {
-		return defaultProxyConfig();
+		return lastGoodConfig.get(configFile) ?? defaultProxyConfig();
+	}
+}
+/**
+* The endpoint the harness itself uses when `llm-deepseek` configures no
+* `baseURL`: its schema has no default for that field, so the live config carries
+* no host to read and the DeepSeek route would be missing from the list even
+* though it carries real traffic. Keep in sync with the plugin's public constant
+* (`PUBLIC_BASE_URL` = https://api.deepseek.com/anthropic).
+*/
+const DEEPSEEK_PUBLIC_BASE_URL = "https://api.deepseek.com/anthropic";
+/** Friendly name for a namespace whose providers carry no `displayName`. */
+function defaultDisplayName(ns) {
+	return ns === "llm-deepseek" ? "DeepSeek" : null;
+}
+/**
+* Append one provider unit's hosts. `name` is the dsh namespace (or
+* `ns/provider`); loopback hosts are dropped — they can never be proxied
+* (routing sends them direct no matter what), so offering them as a toggle
+* would be a checkbox that does nothing.
+*/
+function pushProviderHosts(out, unit) {
+	const name = unit.provider ? `${unit.ns}/${unit.provider}` : unit.ns;
+	const displayName = unit.displayName || defaultDisplayName(unit.ns);
+	for (const baseUrl of unit.baseUrls) for (const candidate of String(baseUrl).split(",").map((s) => s.trim()).filter(Boolean)) try {
+		const host = new URL(candidate).hostname;
+		if (host && !isLoopbackHost(host)) out.push({
+			name,
+			...displayName ? { displayName } : {},
+			host
+		});
+	} catch {}
+}
+/** True when `value` is a plain object we can read fields from. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Model provider hosts from the LIVE settings document — the shape
+* `settings.describe()` answers with (and the GUI's own model page renders).
+* Sources of truth move: dsh ≥ 0.2 imports the old `<home>/settings.yaml` into
+* the active profile's config document and deletes it, so a file reader
+* silently returns nothing. Reading the harness's own live values survives
+* that (and any future document move).
+*
+* Accepts the descriptor container (`{ namespaces: [...] }`) or the bare array,
+* and reads each `llm-*` namespace: `providers.<key>.{baseURL, displayName}`
+* (llm-pi-ai) or a namespace-level `baseURL` (llm-deepseek). Non-`llm-*`
+* namespaces are ignored — a settings document holds every plugin's entries,
+* and this list is the model provider list.
+*/
+function providerHostsFromEntries(entries) {
+	const list = Array.isArray(entries) ? entries : isRecord(entries) && Array.isArray(entries["namespaces"]) ? entries["namespaces"] : [];
+	const out = [];
+	for (const entry of list) {
+		if (!isRecord(entry)) continue;
+		const ns = typeof entry["ns"] === "string" ? entry["ns"] : "";
+		if (!ns.startsWith("llm-")) continue;
+		const value = entry["value"];
+		if (!isRecord(value)) continue;
+		const before = out.length;
+		if (isRecord(value["providers"])) for (const [provider, block] of Object.entries(value["providers"])) {
+			if (!isRecord(block)) continue;
+			pushProviderHosts(out, {
+				ns,
+				provider,
+				displayName: (typeof block["displayName"] === "string" ? block["displayName"].trim() : "") || null,
+				baseUrls: typeof block["baseURL"] === "string" ? [block["baseURL"]] : []
+			});
+		}
+		else if (typeof value["baseURL"] === "string") pushProviderHosts(out, {
+			ns,
+			provider: null,
+			displayName: null,
+			baseUrls: [value["baseURL"]]
+		});
+		if (ns === "llm-deepseek" && out.length === before) pushProviderHosts(out, {
+			ns,
+			provider: null,
+			displayName: "DeepSeek",
+			baseUrls: [DEEPSEEK_PUBLIC_BASE_URL]
+		});
 	}
+	return out;
 }
 /**
-* Best-effort extraction of model provider hosts from a dsh settings.yaml
-* (llm-deepseek.baseURL / llm-pi-ai.providers.<n>.baseURL / any other llm-*
-* namespace). Returns [{name, host, displayName?}]: `name` is the dsh
+* Resolve the model-provider list from the best source available: the LIVE
+* settings document when the harness exposes one (`live` is an array — empty
+* included), else the legacy `<home>/settings.yaml` of dsh < 0.2. A readable
+* live document always wins: on dsh ≥ 0.2 the legacy file has been renamed
+* `.imported`, so falling back to it could only resurrect stale hosts.
+*/
+function resolveProviderHosts(opts) {
+	return opts.live !== void 0 ? providerHostsFromEntries(opts.live) : providerHostsFromSettings(opts.legacyPath);
+}
+/**
+* Best-effort extraction of model provider hosts from a LEGACY dsh settings.yaml
+* (dsh < 0.2: llm-deepseek.baseURL / llm-pi-ai.providers.<n>.baseURL / any other
+* llm-* namespace). Returns [{name, host, displayName?}]: `name` is the dsh
 * namespace (or `ns/provider`), `displayName` the friendly name when known
 * (llm-pi-ai providers carry a `displayName` field; llm-deepseek is fixed to
 * "DeepSeek"). Empty when unreadable — the proxy's observed-host list still
@@ -252,16 +602,7 @@ function providerHostsFromSettings(settingsPath) {
 		return out;
 	}
 	const push = (current) => {
-		const name = current.provider ? `${current.ns}/${current.provider}` : current.ns;
-		const displayName = current.displayName || (current.ns === "llm-deepseek" ? "DeepSeek" : null);
-		for (const baseUrl of current.baseUrls) for (const candidate of String(baseUrl).split(",").map((s) => s.trim()).filter(Boolean)) try {
-			const host = new URL(candidate).hostname;
-			if (host) out.push({
-				name,
-				...displayName ? { displayName } : {},
-				host
-			});
-		} catch {}
+		pushProviderHosts(out, current);
 	};
 	let ns = null;
 	let inProviders = false;
@@ -334,21 +675,27 @@ function providerHostsFromSettings(settingsPath) {
 */
 function shouldProxy(cfg, host, selfPort) {
 	const h = String(host ?? "").toLowerCase();
-	if (LOOPBACK.test(h)) return false;
+	if (isLoopbackHost(h)) return false;
 	const u = cfg?.upstream;
-	const selfRef = u?.host && LOOPBACK.test(u.host.toLowerCase()) && Number(u.port) === selfPort;
-	return Boolean(u?.enabled) && !selfRef && (cfg?.proxiedHosts ?? []).includes(h);
+	const selfRef = u?.host && isLoopbackHost(u.host) && Number(u.port) === selfPort;
+	if (!Boolean(u?.enabled) || selfRef) return false;
+	const wanted = normalizeHostForMatch(h);
+	const listed = (cfg?.proxiedHosts ?? []).some((entry) => normalizeHostForMatch(entry) === wanted);
+	return normalizeRouteMode(cfg?.routeMode) === "except-listed" ? !listed : listed;
 }
 /**
 * Start a forward proxy bound to 127.0.0.1:<random>.
 */
 function createForwardProxy(opts) {
 	const { configFile, onHosts, log = () => {} } = opts;
+	const requestedPort = normalizeListenPort(opts.listenPort ?? 0);
+	let boundPort = null;
 	const seenHosts = /* @__PURE__ */ new Set();
 	let notifyTimer = null;
+	const outboundAgent = new Agent({ keepAlive: true });
 	const markHost = (host) => {
 		const h = String(host ?? "").trim().toLowerCase();
-		if (!h || LOOPBACK.test(h)) return;
+		if (!h || isLoopbackHost(h)) return;
 		if (seenHosts.has(h)) return;
 		seenHosts.add(h);
 		if (notifyTimer) clearTimeout(notifyTimer);
@@ -414,6 +761,7 @@ function createForwardProxy(opts) {
 		const headers = { ...req.headers };
 		delete headers["proxy-connection"];
 		delete headers["connection"];
+		headers.host = u.host;
 		let useUpstream = via === "upstream";
 		if (useUpstream && upstreamProtocol(cfg) === "socks5") {
 			log(`socks5 upstream: http target ${host} falls back to direct`);
@@ -422,32 +770,48 @@ function createForwardProxy(opts) {
 		if (useUpstream) {
 			const auth = upstreamAuth(cfg);
 			if (auth) headers["proxy-authorization"] = auth;
-			const up = request({
-				host: cfg.upstream.host,
-				port: Number(cfg.upstream.port),
-				method: req.method,
-				path: req.url ?? "",
-				headers
-			}, (upRes) => {
-				res.writeHead(upRes.statusCode ?? 502, upRes.headers);
-				upRes.pipe(res);
-			});
+			let up;
+			try {
+				up = request({
+					host: cfg.upstream.host,
+					port: Number(cfg.upstream.port),
+					method: req.method,
+					path: req.url ?? "",
+					headers,
+					agent: outboundAgent
+				}, (upRes) => {
+					res.writeHead(upRes.statusCode ?? 502, upRes.headers);
+					upRes.pipe(res);
+				});
+			} catch (e) {
+				res.writeHead(502, { "content-type": "text/plain" });
+				res.end(`proxy: upstream error: ${e.message}`);
+				return;
+			}
 			up.on("error", (e) => {
 				res.writeHead(502, { "content-type": "text/plain" });
 				res.end(`proxy: upstream error: ${e.message}`);
 			});
 			req.pipe(up);
 		} else {
-			const up = request({
-				host,
-				port,
-				method: req.method,
-				path: u.pathname + u.search,
-				headers
-			}, (upRes) => {
-				res.writeHead(upRes.statusCode ?? 502, upRes.headers);
-				upRes.pipe(res);
-			});
+			let up;
+			try {
+				up = request({
+					host,
+					port,
+					method: req.method,
+					path: u.pathname + u.search,
+					headers,
+					agent: outboundAgent
+				}, (upRes) => {
+					res.writeHead(upRes.statusCode ?? 502, upRes.headers);
+					upRes.pipe(res);
+				});
+			} catch (e) {
+				res.writeHead(502, { "content-type": "text/plain" });
+				res.end(`proxy: origin error: ${e.message}`);
+				return;
+			}
 			up.on("error", (e) => {
 				res.writeHead(502, { "content-type": "text/plain" });
 				res.end(`proxy: origin error: ${e.message}`);
@@ -456,13 +820,12 @@ function createForwardProxy(opts) {
 		}
 	});
 	server.on("connect", (req, clientSocket, head) => {
-		const [hostRaw, portRaw] = String(req.url ?? "").split(":");
-		const host = (hostRaw ?? "").toLowerCase();
-		const port = Number(portRaw) || 443;
-		if (!host || !port) {
+		const target = parseConnectAuthority(String(req.url ?? ""));
+		if (target === null) {
 			clientSocket.destroy();
 			return;
 		}
+		const { host, port } = target;
 		markHost(host);
 		const { via, cfg } = routeFor(host, server.address()?.port);
 		const rejectClient = (reason) => {
@@ -496,8 +859,31 @@ function createForwardProxy(opts) {
 	});
 	return {
 		port: new Promise((resolve) => {
-			server.listen(0, "127.0.0.1", () => resolve(server.address().port));
+			const listen = (candidate, isFallback) => {
+				const onError = (error) => {
+					server.removeListener("listening", onListening);
+					if (candidate > 0 && !isFallback) {
+						log(`proxy: listen port ${candidate} unavailable (${error.code ?? error.message}) — falling back to an ephemeral port; a launcher pointing at ${candidate} will not reach this proxy`);
+						listen(0, true);
+						return;
+					}
+					log(`proxy: listen failed: ${error.message}`);
+					resolve(0);
+				};
+				const onListening = () => {
+					server.removeListener("error", onError);
+					boundPort = server.address()?.port ?? 0;
+					resolve(boundPort);
+				};
+				server.once("error", onError);
+				server.once("listening", onListening);
+				server.listen(candidate, "127.0.0.1");
+			};
+			listen(requestedPort, false);
 		}),
+		requestedPort,
+		portHonored: () => requestedPort > 0 && boundPort === requestedPort,
+		address: () => server.address()?.address ?? null,
 		hosts: () => [...seenHosts].sort(),
 		config,
 		/** Merge observed hosts into proxy.json's knownHosts (UI candidate list). */
@@ -505,7 +891,7 @@ function createForwardProxy(opts) {
 			try {
 				const cfg = config();
 				const merged = [.../* @__PURE__ */ new Set([...cfg.knownHosts ?? [], ...seenHosts])].sort();
-				writeFileSync(configFile, JSON.stringify({
+				writeFileAtomic(configFile, JSON.stringify({
 					...cfg,
 					knownHosts: merged
 				}, null, 2) + "\n");
@@ -513,8 +899,28 @@ function createForwardProxy(opts) {
 				log(`proxy: persist known hosts failed: ${e.message}`);
 			}
 		},
+		/**
+		* Clear the observed-host list. The session's own set is cleared too: leaving
+		* it would make the very next persist merge the just-forgotten hosts back into
+		* proxy.json, so the button would look like it did nothing.
+		*/
+		forgetHosts: () => {
+			seenHosts.clear();
+			if (notifyTimer) clearTimeout(notifyTimer);
+			try {
+				const cfg = config();
+				writeFileAtomic(configFile, JSON.stringify({
+					...cfg,
+					knownHosts: []
+				}, null, 2) + "\n");
+			} catch (e) {
+				log(`proxy: clear known hosts failed: ${e.message}`);
+			}
+			onHosts?.([]);
+		},
 		close: () => {
 			if (notifyTimer) clearTimeout(notifyTimer);
+			outboundAgent.destroy();
 			server.close();
 		}
 	};
@@ -553,23 +959,25 @@ function sanitizeUpstream(v) {
 * arbitrary keys). Takes effect immediately: the running proxy re-reads
 * proxy.json on every request.
 */
-function writeProxyConfig(configFile, upstream, proxiedHosts) {
+function writeProxyConfig(configFile, patch) {
 	const cfg = readProxyConfig(configFile);
 	const hosts = [];
-	for (const h of proxiedHosts ?? []) {
+	for (const h of patch.proxiedHosts ?? cfg.proxiedHosts ?? []) {
 		const t = normalizeHost(h);
 		if (t !== "") hosts.push(t);
 	}
 	const next = {
 		...cfg,
-		upstream: sanitizeUpstream(upstream),
-		proxiedHosts: hosts
+		upstream: patch.upstream === void 0 ? cfg.upstream : sanitizeUpstream(patch.upstream),
+		proxiedHosts: hosts,
+		listenPort: patch.listenPort === void 0 ? cfg.listenPort : normalizeListenPort(patch.listenPort),
+		routeMode: patch.routeMode === void 0 ? cfg.routeMode : normalizeRouteMode(patch.routeMode)
 	};
 	const text = JSON.stringify(next, null, 2);
 	try {
 		mkdirSync(dirname(configFile), { recursive: true });
 	} catch {}
-	writeFileSync(configFile, text + "\n");
+	writeFileAtomic(configFile, text + "\n");
 	return next;
 }
 /**
@@ -756,6 +1164,17 @@ function testUpstreamProxy(upstream) {
 		});
 	});
 }
+/** Coerce a stored/edited route mode; anything unknown means the default. */
+function normalizeRouteMode(value) {
+	return value === "except-listed" ? "except-listed" : "only-listed";
+}
+/** Coerce a stored/edited listen port: integer 1..65535, anything else -> 0 (ephemeral). */
+function normalizeListenPort(value) {
+	const n = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
+	if (!Number.isFinite(n)) return 0;
+	const port = Math.trunc(n);
+	return port >= 1 && port <= 65535 ? port : 0;
+}
 //#endregion
 //#region src/index.ts
 const name = "@karoc/dsh-proxy";
@@ -770,7 +1189,7 @@ function resolveDshHome() {
 function proxyConfigPath(home = resolveDshHome()) {
 	return join(home, "proxy.json");
 }
-/** The dsh settings.yaml this plugin derives model-provider hosts from. */
+/** The LEGACY dsh settings.yaml (dsh < 0.2), kept as the fallback provider source. */
 function settingsPath(home = resolveDshHome()) {
 	return join(home, "settings.yaml");
 }
@@ -797,26 +1216,133 @@ function readBody(req) {
 		req.on("error", reject);
 	});
 }
+/** Environment names a launcher may have used to point dsh at a proxy, in resolution order. */
+const LAUNCH_PROXY_NAMES = [
+	"HTTP_PROXY",
+	"http_proxy",
+	"HTTPS_PROXY",
+	"https_proxy",
+	"ALL_PROXY",
+	"all_proxy"
+];
+/**
+* Read the launch-time proxy variable, before {@link startProxy} publishes this
+* plugin's own values into the environment. dsh resolves its egress policy from
+* the launch environment BEFORE plugins mount, so this snapshot is the only
+* evidence of whether the harness's own requests are routed here.
+*/
+function readLaunchProxy() {
+	for (const name of LAUNCH_PROXY_NAMES) {
+		const value = process.env[name];
+		if (typeof value === "string" && value.trim() !== "") return {
+			name,
+			value: value.trim()
+		};
+	}
+	return null;
+}
+/** Mask credentials in a proxy URL before it leaves the process (the page shows this). */
+function maskProxyUrl(value) {
+	try {
+		const url = new URL(value);
+		if (url.username !== "" || url.password !== "") {
+			url.username = "***";
+			url.password = "***";
+		}
+		return url.toString();
+	} catch {
+		return value.replace(/\/\/[^@/]*@/, "//***:***@");
+	}
+}
+/**
+* The loopback port a launch proxy names, when that proxy is this plugin.
+*
+* A launcher that declares `HTTP_PROXY=http://127.0.0.1:<port>` did so because
+* it expects THIS proxy to be at that address (that is the 0.1.7 contract), so an
+* ephemeral configuration adopts it rather than leaving the launcher pointed at
+* nothing. A port already serving something else simply fails to bind, and the
+* plugin falls back to an ephemeral one — which is also the correct outcome when
+* the launch proxy is a *different* local proxy, since that one keeps owning
+* egress.
+*/
+function launchProxyLoopbackPort(launch) {
+	if (launch === null) return 0;
+	try {
+		const url = new URL(launch.value);
+		const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+		if (host !== "127.0.0.1" && host !== "localhost" && host !== "::1") return 0;
+		const port = Number(url.port);
+		return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : 0;
+	} catch {
+		return 0;
+	}
+}
+/** Whether a launch proxy URL addresses `port` on loopback. */
+function launchProxyTargetsPort(launch, port) {
+	if (launch === null || port === null || port <= 0) return false;
+	try {
+		const url = new URL(launch.value);
+		const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+		return (host === "127.0.0.1" || host === "localhost" || host === "::1") && url.port === String(port);
+	} catch {
+		return false;
+	}
+}
+/**
+* The live settings document, when this composition exposes one. `settings.
+* describe()` answers with every active entry's CURRENT values — the same call
+* the GUI's own settings pages read — so the provider list follows the running
+* configuration instead of a file whose name and shape upstream is free to
+* change (dsh ≥ 0.2 moved it into the profile document and deleted the legacy
+* `settings.yaml`, which is exactly how this list went empty).
+*
+* `undefined` when no settings service is in the composition or the read
+* throws: the caller then falls back to the legacy `<home>/settings.yaml`.
+*/
+function liveSettingsDocument(ctx) {
+	try {
+		const settings = ctx.get("settings");
+		if (settings === void 0 || typeof settings.describe !== "function") return void 0;
+		return settings.describe();
+	} catch {
+		return;
+	}
+}
 /** Build the fresh settings view. */
-function viewOf(forwardProxy) {
+function viewOf(forwardProxy, providers, launch, egress) {
 	const cfg = forwardProxy.config();
+	const port = forwardProxy.currentPort;
+	const policy = egress();
 	return {
 		ok: true,
-		port: forwardProxy.currentPort,
+		port,
+		listenPort: cfg.listenPort,
+		portRequested: forwardProxy.requestedPort,
+		portHonored: forwardProxy.portHonored(),
+		launchProxy: launch === null ? null : maskProxyUrl(launch.value),
+		inProcessRouted: policy.status === "self-installed" || launchProxyTargetsPort(launch, port),
+		egressStatus: policy.status,
+		egressDetail: policy.detail,
 		upstream: cfg.upstream,
 		proxiedHosts: cfg.proxiedHosts,
+		routeMode: cfg.routeMode,
 		knownHosts: cfg.knownHosts,
 		hosts: forwardProxy.hosts(),
-		providers: providerHostsFromSettings(settingsPath())
+		providers: providers()
 	};
 }
 /** Start the loopback forward proxy and re-point the process at it. */
 function startProxy(opts) {
-	const { configFile, log } = opts;
+	const { configFile, launch, log } = opts;
 	let currentPort = null;
 	let persistTimer = null;
+	const configuredPort = readProxyConfig(configFile).listenPort;
+	const adoptedPort = configuredPort > 0 ? 0 : launchProxyLoopbackPort(launch);
+	const requestedPort = configuredPort > 0 ? configuredPort : adoptedPort;
+	if (adoptedPort > 0) log(`dsh-proxy: adopting the launch environment's proxy port 127.0.0.1:${adoptedPort}`);
 	const handle = createForwardProxy({
 		configFile,
+		listenPort: requestedPort,
 		onHosts: (hosts) => {
 			if (persistTimer) clearTimeout(persistTimer);
 			persistTimer = setTimeout(() => {
@@ -831,17 +1357,24 @@ function startProxy(opts) {
 	const wrapped = {
 		port: handle.port,
 		currentPort,
+		requestedPort: handle.requestedPort,
+		portHonored: handle.portHonored,
 		hosts: handle.hosts,
 		config: handle.config,
 		persistKnownHosts: handle.persistKnownHosts,
+		forgetHosts: handle.forgetHosts,
 		close: () => {
 			if (persistTimer) clearTimeout(persistTimer);
 			handle.close();
 		}
 	};
 	handle.port.then((port) => {
+		if (port <= 0) {
+			log("dsh-proxy: forward proxy could not bind any port — leaving the environment untouched");
+			return;
+		}
 		wrapped.currentPort = port;
-		log(`dsh-proxy: forward proxy on 127.0.0.1:${port}`);
+		log(`dsh-proxy: forward proxy on 127.0.0.1:${port}${handle.portHonored() ? "" : ` (requested ${handle.requestedPort}; a launcher pointing at it will not reach this proxy)`}`);
 		process.env.NODE_USE_ENV_PROXY = "1";
 		process.env.HTTP_PROXY = `http://127.0.0.1:${port}`;
 		process.env.HTTPS_PROXY = `http://127.0.0.1:${port}`;
@@ -858,13 +1391,31 @@ function startProxy(opts) {
 	return wrapped;
 }
 /** Register the /proxy/api route (GET view, POST save/test/persist). */
-function registerWebApi(ctx, forwardProxy) {
+function registerWebApi(ctx, forwardProxy, providers, launch, egress) {
 	const server = ctx.get("webServer");
 	if (server === void 0) return;
+	const admissionRejection = (req) => {
+		const connection = ctx.get?.("connection");
+		if (connection === void 0 || typeof connection.admit !== "function") return void 0;
+		try {
+			const rejection = connection.admit(req)?.rejection;
+			return rejection === 401 || rejection === 403 ? rejection : void 0;
+		} catch {
+			return;
+		}
+	};
 	server.register({
 		kind: "prefix",
 		path: "/proxy/api",
 		handler: (req, res) => {
+			const rejection = admissionRejection(req);
+			if (rejection !== void 0) {
+				sendJson(res, rejection, {
+					ok: false,
+					error: rejection === 401 ? "unauthorized" : "forbidden"
+				});
+				return;
+			}
 			handle(req, res).catch((error) => {
 				if (!res.writableEnded) sendJson(res, 500, {
 					ok: false,
@@ -876,7 +1427,7 @@ function registerWebApi(ctx, forwardProxy) {
 	async function handle(req, res) {
 		const method = req.method ?? "GET";
 		if (method === "GET") {
-			sendJson(res, 200, viewOf(forwardProxy));
+			sendJson(res, 200, viewOf(forwardProxy, providers, launch, egress));
 			return;
 		}
 		if (method === "POST") {
@@ -894,11 +1445,17 @@ function registerWebApi(ctx, forwardProxy) {
 			switch (body.op) {
 				case "save":
 					try {
-						const cfg = writeProxyConfig(proxyConfigPath(), body.upstream, Array.isArray(body.proxiedHosts) ? body.proxiedHosts : []);
+						const cfg = writeProxyConfig(proxyConfigPath(), {
+							upstream: body.upstream,
+							...Array.isArray(body.proxiedHosts) ? { proxiedHosts: body.proxiedHosts } : {},
+							listenPort: body.listenPort,
+							routeMode: body.routeMode
+						});
 						sendJson(res, 200, {
-							...viewOf(forwardProxy),
+							...viewOf(forwardProxy, providers, launch, egress),
 							upstream: cfg.upstream,
-							proxiedHosts: cfg.proxiedHosts
+							proxiedHosts: cfg.proxiedHosts,
+							routeMode: cfg.routeMode
 						});
 					} catch (error) {
 						sendJson(res, 400, {
@@ -919,7 +1476,13 @@ function registerWebApi(ctx, forwardProxy) {
 					try {
 						forwardProxy.persistKnownHosts();
 					} catch {}
-					sendJson(res, 200, viewOf(forwardProxy));
+					sendJson(res, 200, viewOf(forwardProxy, providers, launch, egress));
+					return;
+				case "forget":
+					try {
+						forwardProxy.forgetHosts();
+					} catch {}
+					sendJson(res, 200, viewOf(forwardProxy, providers, launch, egress));
 					return;
 				default: sendJson(res, 400, {
 					ok: false,
@@ -945,16 +1508,72 @@ function apply(ctx) {
 			ctx.logger?.info(`[dsh-proxy] ${line}`);
 		} catch {}
 	};
+	const launch = readLaunchProxy();
 	const forwardProxy = startProxy({
 		configFile: proxyConfigPath(),
+		launch,
 		log
 	});
-	registerWebApi(ctx, forwardProxy);
-	ctx.effect(() => () => {
+	/**
+	* Where the harness's policy package can be resolved from, most specific
+	* first: the active profile (the harness resolved it from there, so importing
+	* the same file shares one module instance — which is what makes
+	* `proxyRouteFor` callers see this policy too), then the dsh entry point.
+	*/
+	const policyAnchors = () => {
+		const anchors = [];
 		try {
-			forwardProxy.close();
+			const settings = ctx.get("settings");
+			if (typeof settings?.documentPath === "string") anchors.push(join(dirname(settings.documentPath), "package.json"));
 		} catch {}
+		const entry = process.argv[1];
+		if (typeof entry === "string" && isAbsolute(entry)) anchors.push(entry);
+		anchors.push(join(process.cwd(), "package.json"));
+		return anchors;
+	};
+	let outcome = {
+		status: "unavailable",
+		detail: "the forward proxy is not listening yet",
+		dispose: null
+	};
+	forwardProxy.port.then(async (port) => {
+		if (port <= 0) {
+			outcome = {
+				status: "unavailable",
+				detail: "the forward proxy could not bind any port",
+				dispose: null
+			};
+			return;
+		}
+		outcome = await installInProcessEgress({
+			proxyUrl: `http://127.0.0.1:${port}`,
+			launch,
+			importer: createPolicyImporter(policyAnchors()),
+			log
+		});
+		log(`dsh-proxy: in-process egress ${outcome.status}${outcome.detail === null ? "" : ` — ${outcome.detail}`}`);
+	}).catch((error) => {
+		outcome = {
+			status: "unavailable",
+			detail: error.message,
+			dispose: null
+		};
+	});
+	const providers = () => resolveProviderHosts({
+		live: liveSettingsDocument(ctx),
+		legacyPath: settingsPath()
+	});
+	registerWebApi(ctx, forwardProxy, providers, launch, () => outcome);
+	ctx.effect(() => () => {
+		(async () => {
+			try {
+				await outcome.dispose?.();
+			} catch {}
+			try {
+				forwardProxy.close();
+			} catch {}
+		})();
 	}, "dsh-proxy: teardown");
 }
 //#endregion
-export { apply, inject, name, proxyConfigPath, resolveDshHome, settingsPath };
+export { apply, inject, launchProxyLoopbackPort, launchProxyTargetsPort, maskProxyUrl, name, proxyConfigPath, resolveDshHome, settingsPath };