fix(proxy): restrict gateway bypass to loopback IPs

joshavant · joshavant · commit 63f0b97f4640 · 2026-04-28T00:12:47.000-05:00
diff --git a/src/gateway/client.ts b/src/gateway/client.ts
@@ -17,6 +17,7 @@ import { dangerouslyBypassManagedProxyForGatewayLoopbackControlPlane } from "../
 import { normalizeFingerprint } from "../infra/tls/fingerprint.js";
 import { rawDataToString } from "../infra/ws.js";
 import { logDebug, logError } from "../logger.js";
+import { isLoopbackIpAddress } from "../shared/net/ip.js";
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
@@ -99,7 +100,7 @@ function createDirectGatewayAgent(url: string): http.Agent | https.Agent | undef
   } catch {
     return undefined;
   }
-  if (!isLoopbackHost(hostname)) {
+  if (!isLoopbackIpAddress(hostname)) {
     return undefined;
   }
   return url.startsWith("wss://") ? new https.Agent() : new http.Agent();
diff --git a/src/gateway/gateway-misc.test.ts b/src/gateway/gateway-misc.test.ts
@@ -97,6 +97,22 @@ describe("GatewayClient", () => {
     );
   });
 
+  test("uses an explicit direct agent for IPv6 loopback control-plane WebSocket connections", () => {
+    const client = new GatewayClient({ url: "ws://[::1]:1" });
+    client.start();
+    const last = wsMockState.last as { opts: { agent?: unknown } } | null;
+
+    expect(last?.opts.agent).toBeDefined();
+  });
+
+  test("does not use the direct control-plane bypass for localhost hostnames", () => {
+    const client = new GatewayClient({ url: "ws://localhost:1" });
+    client.start();
+    const last = wsMockState.last as { opts: { agent?: unknown } } | null;
+
+    expect(last?.opts.agent).toBeUndefined();
+  });
+
   test("does not force a direct agent for remote Gateway WebSocket connections", () => {
     const client = new GatewayClient({
       url: "wss://gateway.example.com",
diff --git a/src/infra/net/proxy/proxy-lifecycle.test.ts b/src/infra/net/proxy/proxy-lifecycle.test.ts
@@ -332,6 +332,24 @@ describe("startProxy", () => {
     await stopProxy(handle);
   });
 
+  it("allows the Gateway control-plane bypass for literal loopback IPs only", () => {
+    expect(
+      dangerouslyBypassManagedProxyForGatewayLoopbackControlPlane(
+        "ws://127.0.0.1:18789",
+        () => "ok",
+      ),
+    ).toBe("ok");
+    expect(
+      dangerouslyBypassManagedProxyForGatewayLoopbackControlPlane("ws://[::1]:18789", () => "ok"),
+    ).toBe("ok");
+    expect(() =>
+      dangerouslyBypassManagedProxyForGatewayLoopbackControlPlane(
+        "ws://localhost:18789",
+        () => undefined,
+      ),
+    ).toThrow("loopback-only");
+  });
+
   it("rejects dangerous Gateway control-plane bypass for non-loopback URLs", () => {
     expect(() =>
       dangerouslyBypassManagedProxyForGatewayLoopbackControlPlane(
diff --git a/src/infra/net/proxy/proxy-lifecycle.ts b/src/infra/net/proxy/proxy-lifecycle.ts
@@ -12,6 +12,7 @@ import https from "node:https";
 import { bootstrap as bootstrapGlobalAgent } from "global-agent";
 import type { ProxyConfig } from "../../../config/zod-schema.proxy.js";
 import { logInfo, logWarn } from "../../../logger.js";
+import { isLoopbackIpAddress } from "../../../shared/net/ip.js";
 import { forceResetGlobalDispatcher } from "../undici-global-dispatcher.js";
 
 export type ProxyHandle = {
@@ -287,13 +288,7 @@ function isGatewayLoopbackControlPlaneUrl(value: string): boolean {
   ) {
     return false;
   }
-  const hostname = url.hostname.toLowerCase();
-  return (
-    hostname === "localhost" ||
-    hostname === "127.0.0.1" ||
-    hostname === "::1" ||
-    hostname === "[::1]"
-  );
+  return isLoopbackIpAddress(url.hostname);
 }
 
 export function dangerouslyBypassManagedProxyForGatewayLoopbackControlPlane<T>(
