fix: keep MCP daemon loopback-only by default (#46)

Author: benvinegar

README.md

@@ -144,6 +144,8 @@ agent_notes = false
 
 - `hunk diff --agent-context <file>` loads inline agent rationale from a JSON sidecar
 - `hunk mcp serve` runs the local MCP daemon for agent-to-diff communication
+  - Hunk keeps the daemon loopback-only by default
+  - if you intentionally need remote access, set `HUNK_MCP_UNSAFE_ALLOW_REMOTE=1` and choose a non-loopback `HUNK_MCP_HOST`
 
 ## Performance notes
 

src/core/cli.ts

@@ -353,8 +353,9 @@ async function parseMcpCommand(tokens: string[]): Promise<ParsedCliInput> {
         "Run the local Hunk MCP daemon and websocket session broker.",
         "",
         "Environment:",
-        "  HUNK_MCP_HOST   bind host (default 127.0.0.1)",
-        "  HUNK_MCP_PORT   bind port (default 47657)",
+        "  HUNK_MCP_HOST                  bind host (default 127.0.0.1; loopback only unless explicitly overridden)",
+        "  HUNK_MCP_PORT                  bind port (default 47657)",
+        "  HUNK_MCP_UNSAFE_ALLOW_REMOTE   set to 1 to allow non-loopback binding (unsafe)",
       ].join("\n") + "\n",
     };
   }

src/mcp/client.ts

@@ -7,7 +7,7 @@ import type {
   SessionCommandResult,
   SessionServerMessage,
 } from "./types";
-import { HUNK_SESSION_SOCKET_PATH, resolveHunkMcpConfig } from "./config";
+import { HUNK_SESSION_SOCKET_PATH, resolveHunkMcpConfig, type ResolvedHunkMcpConfig } from "./config";
 import { isHunkDaemonHealthy, isLoopbackPortReachable, launchHunkDaemon, waitForHunkDaemonHealth } from "./daemonLauncher";
 
 const DAEMON_LAUNCH_COOLDOWN_MS = 5_000;
@@ -31,7 +31,6 @@ export class HunkHostClient {
   private startupPromise: Promise<void> | null = null;
   private lastDaemonLaunchStartedAt = 0;
   private lastConnectionWarning: string | null = null;
-  private readonly config = resolveHunkMcpConfig();
 
   constructor(
     private readonly registration: HunkSessionRegistration,
@@ -73,13 +72,18 @@ export class HunkHostClient {
     this.websocket = null;
   }
 
+  private resolveConfig() {
+    return resolveHunkMcpConfig();
+  }
+
   private async ensureDaemonAndConnect() {
-    await this.ensureDaemonAvailable();
-    this.connect();
+    const config = this.resolveConfig();
+    await this.ensureDaemonAvailable(config);
+    this.connect(config);
   }
 
-  private async ensureDaemonAvailable() {
-    if (await isHunkDaemonHealthy(this.config)) {
+  private async ensureDaemonAvailable(config: ResolvedHunkMcpConfig) {
+    if (await isHunkDaemonHealthy(config)) {
       this.lastConnectionWarning = null;
       return;
     }
@@ -91,7 +95,7 @@ export class HunkHostClient {
     }
 
     const ready = await waitForHunkDaemonHealth({
-      config: this.config,
+      config,
       timeoutMs: shouldLaunch ? DAEMON_STARTUP_TIMEOUT_MS : 1_500,
     });
 
@@ -100,16 +104,16 @@ export class HunkHostClient {
       return;
     }
 
-    const portReachable = await isLoopbackPortReachable(this.config);
+    const portReachable = await isLoopbackPortReachable(config);
     if (portReachable) {
       throw new Error(
-        `Hunk MCP port ${this.config.host}:${this.config.port} is already in use by another process. ` +
+        `Hunk MCP port ${config.host}:${config.port} is already in use by another process. ` +
           `Stop the conflicting process or set HUNK_MCP_PORT to a different loopback port.`,
       );
     }
 
     throw new Error(
-      `Timed out waiting for the Hunk MCP daemon on ${this.config.host}:${this.config.port}. ` +
+      `Timed out waiting for the Hunk MCP daemon on ${config.host}:${config.port}. ` +
         `Hunk will retry in the background.`,
     );
   }
@@ -128,12 +132,12 @@ export class HunkHostClient {
     });
   }
 
-  private connect() {
+  private connect(config: ResolvedHunkMcpConfig) {
     if (this.stopped || this.websocket) {
       return;
     }
 
-    const websocket = new WebSocket(`${this.config.wsOrigin}${HUNK_SESSION_SOCKET_PATH}`);
+    const websocket = new WebSocket(`${config.wsOrigin}${HUNK_SESSION_SOCKET_PATH}`);
     this.websocket = websocket;
 
     websocket.onopen = () => {

src/mcp/config.ts

@@ -1,7 +1,10 @@
+import { isIP } from "node:net";
+
 const DEFAULT_HUNK_MCP_HOST = "127.0.0.1";
 const DEFAULT_HUNK_MCP_PORT = 47657;
 export const HUNK_MCP_PATH = "/mcp";
 export const HUNK_SESSION_SOCKET_PATH = "/session";
+export const HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV = "HUNK_MCP_UNSAFE_ALLOW_REMOTE";
 
 export interface ResolvedHunkMcpConfig {
   host: string;
@@ -10,12 +13,51 @@ export interface ResolvedHunkMcpConfig {
   wsOrigin: string;
 }
 
+/** Return whether one bind host stays on the local loopback interface. */
+export function isLoopbackHost(host: string) {
+  const normalized = host.trim().toLowerCase();
+
+  if (normalized.length === 0) {
+    return false;
+  }
+
+  if (normalized === "localhost" || normalized === "::1" || normalized === "0:0:0:0:0:0:0:1") {
+    return true;
+  }
+
+  if (normalized.startsWith("[") && normalized.endsWith("]")) {
+    return isLoopbackHost(normalized.slice(1, -1));
+  }
+
+  if (normalized.startsWith("::ffff:")) {
+    return isLoopbackHost(normalized.slice("::ffff:".length));
+  }
+
+  if (isIP(normalized) === 4) {
+    return normalized.startsWith("127.");
+  }
+
+  return false;
+}
+
+/** Return whether the user explicitly opted into exposing the daemon beyond loopback. */
+export function allowsUnsafeRemoteMcp(env: NodeJS.ProcessEnv = process.env) {
+  return env[HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV] === "1";
+}
+
 /** Resolve the loopback host/port Hunk should use for the local MCP daemon. */
 export function resolveHunkMcpConfig(env: NodeJS.ProcessEnv = process.env): ResolvedHunkMcpConfig {
   const host = env.HUNK_MCP_HOST?.trim() || DEFAULT_HUNK_MCP_HOST;
   const parsedPort = Number.parseInt(env.HUNK_MCP_PORT ?? "", 10);
   const port = Number.isInteger(parsedPort) && parsedPort > 0 ? parsedPort : DEFAULT_HUNK_MCP_PORT;
 
+  if (!isLoopbackHost(host) && !allowsUnsafeRemoteMcp(env)) {
+    throw new Error(
+      `Hunk MCP refuses to bind ${host}:${port} because the daemon is local-only by default. ` +
+        `Use a loopback host such as 127.0.0.1, localhost, or ::1, or set ${HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV}=1 if you intentionally want remote access.`,
+    );
+  }
+
   return {
     host,
     port,

test/mcp-client.test.ts

@@ -6,6 +6,7 @@ import type { HunkSessionRegistration, HunkSessionSnapshot } from "../src/mcp/ty
 const originalHost = process.env.HUNK_MCP_HOST;
 const originalPort = process.env.HUNK_MCP_PORT;
 const originalDisable = process.env.HUNK_MCP_DISABLE;
+const originalUnsafeRemote = process.env.HUNK_MCP_UNSAFE_ALLOW_REMOTE;
 const originalConsoleError = console.error;
 
 function createRegistration(): HunkSessionRegistration {
@@ -74,10 +75,40 @@ afterEach(() => {
     process.env.HUNK_MCP_DISABLE = originalDisable;
   }
 
+  if (originalUnsafeRemote === undefined) {
+    delete process.env.HUNK_MCP_UNSAFE_ALLOW_REMOTE;
+  } else {
+    process.env.HUNK_MCP_UNSAFE_ALLOW_REMOTE = originalUnsafeRemote;
+  }
+
   console.error = originalConsoleError;
 });
 
 describe("Hunk MCP client", () => {
+  test("logs one actionable warning when MCP is configured for a non-loopback host without opt-in", async () => {
+    process.env.HUNK_MCP_HOST = "0.0.0.0";
+    process.env.HUNK_MCP_PORT = "47657";
+    delete process.env.HUNK_MCP_UNSAFE_ALLOW_REMOTE;
+    delete process.env.HUNK_MCP_DISABLE;
+
+    const messages: string[] = [];
+    console.error = (...args: unknown[]) => {
+      messages.push(args.map((value) => String(value)).join(" "));
+    };
+
+    const client = new HunkHostClient(createRegistration(), createSnapshot());
+
+    try {
+      client.start();
+      await waitUntil("non-loopback MCP warning", () => messages.length === 1);
+
+      expect(messages[0]).toContain("[hunk:mcp] Hunk MCP refuses to bind 0.0.0.0:47657 because the daemon is local-only by default.");
+      expect(messages[0]).toContain("HUNK_MCP_UNSAFE_ALLOW_REMOTE=1");
+    } finally {
+      client.stop();
+    }
+  }, 10_000);
+
   test("logs one actionable warning when a non-Hunk listener owns the MCP port", async () => {
     const conflictingListener = createServer((_request, response) => {
       response.writeHead(404, { "content-type": "text/plain" });

test/mcp-config.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import {
+  HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV,
+  allowsUnsafeRemoteMcp,
+  isLoopbackHost,
+  resolveHunkMcpConfig,
+} from "../src/mcp/config";
+
+describe("Hunk MCP config", () => {
+  test("accepts loopback hosts without an unsafe override", () => {
+    expect(isLoopbackHost("127.0.0.1")).toBe(true);
+    expect(isLoopbackHost("127.1.2.3")).toBe(true);
+    expect(isLoopbackHost("localhost")).toBe(true);
+    expect(isLoopbackHost("::1")).toBe(true);
+    expect(isLoopbackHost("0:0:0:0:0:0:0:1")).toBe(true);
+    expect(isLoopbackHost("::ffff:127.0.0.1")).toBe(true);
+    expect(isLoopbackHost("0.0.0.0")).toBe(false);
+    expect(isLoopbackHost("192.168.1.20")).toBe(false);
+    expect(isLoopbackHost("example.com")).toBe(false);
+  });
+
+  test("refuses non-loopback binds unless the unsafe override is enabled", () => {
+    expect(() =>
+      resolveHunkMcpConfig({
+        HUNK_MCP_HOST: "0.0.0.0",
+        HUNK_MCP_PORT: "49000",
+      }),
+    ).toThrow("local-only by default");
+
+    expect(
+      resolveHunkMcpConfig({
+        HUNK_MCP_HOST: "0.0.0.0",
+        HUNK_MCP_PORT: "49000",
+        [HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV]: "1",
+      }),
+    ).toMatchObject({
+      host: "0.0.0.0",
+      port: 49000,
+    });
+  });
+
+  test("reports whether unsafe remote MCP access was explicitly enabled", () => {
+    expect(allowsUnsafeRemoteMcp({})).toBe(false);
+    expect(allowsUnsafeRemoteMcp({ [HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV]: "0" })).toBe(false);
+    expect(allowsUnsafeRemoteMcp({ [HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV]: "1" })).toBe(true);
+  });
+});

test/mcp-server.test.ts

@@ -4,6 +4,7 @@ import { serveHunkMcpServer } from "../src/mcp/server";
 
 const originalHost = process.env.HUNK_MCP_HOST;
 const originalPort = process.env.HUNK_MCP_PORT;
+const originalUnsafeRemote = process.env.HUNK_MCP_UNSAFE_ALLOW_REMOTE;
 
 afterEach(() => {
   if (originalHost === undefined) {
@@ -17,9 +18,23 @@ afterEach(() => {
   } else {
     process.env.HUNK_MCP_PORT = originalPort;
   }
+
+  if (originalUnsafeRemote === undefined) {
+    delete process.env.HUNK_MCP_UNSAFE_ALLOW_REMOTE;
+  } else {
+    process.env.HUNK_MCP_UNSAFE_ALLOW_REMOTE = originalUnsafeRemote;
+  }
 });
 
 describe("Hunk MCP server", () => {
+  test("refuses non-loopback binding unless explicitly allowed", () => {
+    process.env.HUNK_MCP_HOST = "0.0.0.0";
+    process.env.HUNK_MCP_PORT = "47657";
+    delete process.env.HUNK_MCP_UNSAFE_ALLOW_REMOTE;
+
+    expect(() => serveHunkMcpServer()).toThrow("local-only by default");
+  });
+
   test("reports a clear error when the daemon port is already in use", async () => {
     const listener = createServer(() => undefined);
     await new Promise<void>((resolve, reject) => {