refactor: rename allowedHosts to hostnames (#413)

* refactor: rename allowedHosts to hostnames for DNS rebinding config

The old name confused users who thought it was related to CORS.
"hostnames" communicates that you're declaring the daemon's own
hostnames, not granting access to external parties.

Backward compatible: old config files (daemon.allowedHosts), env var
(PASEO_ALLOWED_HOSTS), CLI flag (--allowed-hosts), and Nix option
(allowedHosts) all still work as deprecated aliases.

* fix(nix): update npmDepsHash to match current package-lock.json

packages/server/src/server/agent/agent-mcp.e2e.test.ts

@@ -119,7 +119,7 @@ describe("agent MCP end-to-end (offline)", () => {
       listen: `127.0.0.1:${port}`,
       paseoHome,
       corsAllowedOrigins: [],
-      allowedHosts: true,
+      hostnames: true,
       mcpEnabled: true,
       staticDir,
       mcpDebug: false,
@@ -192,7 +192,7 @@ describe("agent MCP end-to-end (offline)", () => {
       listen: `127.0.0.1:${port}`,
       paseoHome,
       corsAllowedOrigins: [],
-      allowedHosts: true,
+      hostnames: true,
       mcpEnabled: true,
       staticDir,
       mcpDebug: false,
@@ -216,7 +216,7 @@ describe("agent MCP end-to-end (offline)", () => {
       listen: `127.0.0.1:${disabledPort}`,
       paseoHome: disabledPaseoHome,
       corsAllowedOrigins: [],
-      allowedHosts: true,
+      hostnames: true,
       mcpEnabled: true,
       mcpInjectIntoAgents: false,
       staticDir: disabledStaticDir,
@@ -307,7 +307,7 @@ describe("agent MCP end-to-end (offline)", () => {
       listen: `127.0.0.1:${port}`,
       paseoHome,
       corsAllowedOrigins: [],
-      allowedHosts: true,
+      hostnames: true,
       mcpEnabled: true,
       staticDir,
       mcpDebug: false,

packages/server/src/server/agent/agent-response-loop.e2e.test.ts

@@ -42,7 +42,7 @@ async function startAgentMcpServer(logger: pino.Logger): Promise<AgentMcpServerH
     logger,
   });
 
-  let allowedHosts: string[] | undefined;
+  let mcpAllowedHosts: string[] | undefined;
   const agentMcpTransports = new Map<string, StreamableHTTPServerTransport>();
 
   const createAgentMcpTransport = async (callerAgentId?: string) => {
@@ -62,7 +62,7 @@ async function startAgentMcpServer(logger: pino.Logger): Promise<AgentMcpServerH
         agentMcpTransports.delete(sessionId);
       },
       enableDnsRebindingProtection: true,
-      ...(allowedHosts ? { allowedHosts } : {}),
+      ...(mcpAllowedHosts ? { allowedHosts: mcpAllowedHosts } : {}),
     });
 
     transport.onclose = () => {
@@ -129,7 +129,7 @@ async function startAgentMcpServer(logger: pino.Logger): Promise<AgentMcpServerH
     });
   });
 
-  allowedHosts = [`127.0.0.1:${port}`, `localhost:${port}`];
+  mcpAllowedHosts = [`127.0.0.1:${port}`, `localhost:${port}`];
   const url = `http://127.0.0.1:${port}/mcp/agents`;
 
   return {

packages/server/src/server/allowed-hosts.test.ts

@@ -1,45 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { isHostAllowed, mergeAllowedHosts, parseAllowedHostsEnv } from "./allowed-hosts.js";
-
-describe("allowed hosts (vite-style)", () => {
-  it("allows localhost by default", () => {
-    expect(isHostAllowed("localhost:6767", undefined)).toBe(true);
-  });
-
-  it("allows subdomains of .localhost by default", () => {
-    expect(isHostAllowed("foo.localhost:6767", undefined)).toBe(true);
-  });
-
-  it("allows IP addresses by default", () => {
-    expect(isHostAllowed("127.0.0.1:6767", undefined)).toBe(true);
-    expect(isHostAllowed("[::1]:6767", undefined)).toBe(true);
-  });
-
-  it("rejects non-default hosts when no allowlist is provided", () => {
-    expect(isHostAllowed("evil.com:6767", undefined)).toBe(false);
-  });
-
-  it("allows any host when set to true", () => {
-    expect(isHostAllowed("evil.com:6767", true)).toBe(true);
-  });
-
-  it("supports leading-dot patterns", () => {
-    const allowed = [".example.com"];
-    expect(isHostAllowed("example.com:6767", allowed)).toBe(true);
-    expect(isHostAllowed("foo.example.com:6767", allowed)).toBe(true);
-    expect(isHostAllowed("foo.bar.example.com:6767", allowed)).toBe(true);
-    expect(isHostAllowed("notexample.com:6767", allowed)).toBe(false);
-  });
-
-  it("merges arrays (append + de-dupe) and short-circuits on true", () => {
-    expect(mergeAllowedHosts([["a"], ["a", "b"]])).toEqual(["a", "b"]);
-    expect(mergeAllowedHosts([["a"], true, ["b"]])).toBe(true);
-  });
-
-  it("parses env var values", () => {
-    expect(parseAllowedHostsEnv(undefined)).toBeUndefined();
-    expect(parseAllowedHostsEnv("")).toBeUndefined();
-    expect(parseAllowedHostsEnv("true")).toBe(true);
-    expect(parseAllowedHostsEnv("localhost,.example.com")).toEqual(["localhost", ".example.com"]);
-  });
-});

packages/server/src/server/bootstrap.smoke.test.ts

@@ -50,7 +50,7 @@ describe("paseo daemon bootstrap", () => {
       listen: "127.0.0.1:0",
       paseoHome,
       corsAllowedOrigins: [],
-      allowedHosts: true,
+      hostnames: true,
       mcpEnabled: false,
       staticDir,
       mcpDebug: false,
@@ -163,7 +163,7 @@ describe("paseo daemon bootstrap", () => {
       listen: socketPath,
       paseoHome,
       corsAllowedOrigins: [],
-      allowedHosts: true,
+      hostnames: true,
       mcpEnabled: false,
       staticDir,
       mcpDebug: false,

packages/server/src/server/bootstrap.ts

@@ -119,7 +119,7 @@ import type {
   AgentProviderRuntimeSettingsMap,
   ProviderOverride,
 } from "./agent/provider-launch-config.js";
-import { isHostAllowed, type AllowedHostsConfig } from "./allowed-hosts.js";
+import { isHostnameAllowed, type HostnamesConfig } from "./hostnames.js";
 
 type AgentMcpTransportMap = Map<string, StreamableHTTPServerTransport>;
 
@@ -162,7 +162,7 @@ export type PaseoDaemonConfig = {
   listen: string;
   paseoHome: string;
   corsAllowedOrigins: string[];
-  allowedHosts?: AllowedHostsConfig;
+  hostnames?: HostnamesConfig;
   mcpEnabled?: boolean;
   mcpInjectIntoAgents?: boolean;
   staticDir: string;
@@ -231,7 +231,7 @@ export async function createPaseoDaemon(
     if (listenTarget.type === "tcp") {
       app.use((req, res, next) => {
         const hostHeader = typeof req.headers.host === "string" ? req.headers.host : undefined;
-        if (!isHostAllowed(hostHeader, config.allowedHosts)) {
+        if (!isHostnameAllowed(hostHeader, config.hostnames)) {
           res.status(403).json({ error: "Invalid Host header" });
           return;
         }
@@ -604,7 +604,7 @@ export async function createPaseoDaemon(
               config.paseoHome,
               daemonConfigStore,
               mcpBaseUrl,
-              { allowedOrigins, allowedHosts: config.allowedHosts },
+              { allowedOrigins, hostnames: config.hostnames },
               speechService,
               terminalManager,
               {

packages/server/src/server/config.ts

@@ -11,11 +11,7 @@ import type {
 import { ProviderOverrideSchema } from "./agent/provider-launch-config.js";
 import { AgentProviderSchema } from "./agent/provider-manifest.js";
 import { resolveSpeechConfig } from "./speech/speech-config-resolver.js";
-import {
-  mergeAllowedHosts,
-  parseAllowedHostsEnv,
-  type AllowedHostsConfig,
-} from "./allowed-hosts.js";
+import { mergeHostnames, parseHostnamesEnv, type HostnamesConfig } from "./hostnames.js";
 
 const DEFAULT_PORT = 6767;
 const DEFAULT_RELAY_ENDPOINT = "relay.paseo.sh:443";
@@ -42,7 +38,7 @@ export type CliConfigOverrides = Partial<{
   relayEnabled: boolean;
   mcpEnabled: boolean;
   mcpInjectIntoAgents: boolean;
-  allowedHosts: AllowedHostsConfig;
+  hostnames: HostnamesConfig;
 }>;
 
 const OptionalVoiceLlmProviderSchema = z
@@ -133,10 +129,10 @@ export function loadConfig(
 
   const persistedCorsOrigins = persisted.daemon?.cors?.allowedOrigins ?? [];
 
-  const allowedHosts = mergeAllowedHosts([
-    persisted.daemon?.allowedHosts,
-    parseAllowedHostsEnv(env.PASEO_ALLOWED_HOSTS),
-    options?.cli?.allowedHosts,
+  const hostnames = mergeHostnames([
+    persisted.daemon?.hostnames,
+    parseHostnamesEnv(env.PASEO_HOSTNAMES ?? env.PASEO_ALLOWED_HOSTS),
+    options?.cli?.hostnames,
   ]);
 
   const mcpEnabled = options?.cli?.mcpEnabled ?? persisted.daemon?.mcp?.enabled ?? true;
@@ -181,7 +177,7 @@ export function loadConfig(
     corsAllowedOrigins: Array.from(
       new Set([...persistedCorsOrigins, ...envCorsOrigins].filter((s) => s.length > 0)),
     ),
-    allowedHosts,
+    hostnames,
     mcpEnabled,
     mcpInjectIntoAgents,
     mcpDebug: env.MCP_DEBUG === "1",

packages/server/src/server/hostnames.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import { PersistedConfigSchema } from "./persisted-config.js";
+import { isHostnameAllowed, mergeHostnames, parseHostnamesEnv } from "./hostnames.js";
+
+describe("hostnames (vite-style)", () => {
+  it("allows localhost by default", () => {
+    expect(isHostnameAllowed("localhost:6767", undefined)).toBe(true);
+  });
+
+  it("allows subdomains of .localhost by default", () => {
+    expect(isHostnameAllowed("foo.localhost:6767", undefined)).toBe(true);
+  });
+
+  it("allows IP addresses by default", () => {
+    expect(isHostnameAllowed("127.0.0.1:6767", undefined)).toBe(true);
+    expect(isHostnameAllowed("[::1]:6767", undefined)).toBe(true);
+  });
+
+  it("rejects non-default hosts when no allowlist is provided", () => {
+    expect(isHostnameAllowed("evil.com:6767", undefined)).toBe(false);
+  });
+
+  it("allows any host when set to true", () => {
+    expect(isHostnameAllowed("evil.com:6767", true)).toBe(true);
+  });
+
+  it("supports leading-dot patterns", () => {
+    const hostnames = [".example.com"];
+    expect(isHostnameAllowed("example.com:6767", hostnames)).toBe(true);
+    expect(isHostnameAllowed("foo.example.com:6767", hostnames)).toBe(true);
+    expect(isHostnameAllowed("foo.bar.example.com:6767", hostnames)).toBe(true);
+    expect(isHostnameAllowed("notexample.com:6767", hostnames)).toBe(false);
+  });
+
+  it("merges arrays (append + de-dupe) and short-circuits on true", () => {
+    expect(mergeHostnames([["a"], ["a", "b"]])).toEqual(["a", "b"]);
+    expect(mergeHostnames([["a"], true, ["b"]])).toBe(true);
+  });
+
+  it("parses env var values", () => {
+    expect(parseHostnamesEnv(undefined)).toBeUndefined();
+    expect(parseHostnamesEnv("")).toBeUndefined();
+    expect(parseHostnamesEnv("true")).toBe(true);
+    expect(parseHostnamesEnv("localhost,.example.com")).toEqual(["localhost", ".example.com"]);
+  });
+
+  it("normalizes persisted allowedHosts into hostnames for backward compatibility", () => {
+    const parsed = PersistedConfigSchema.parse({
+      daemon: {
+        allowedHosts: [".example.com"],
+      },
+    });
+
+    expect(parsed.daemon?.hostnames).toEqual([".example.com"]);
+  });
+});

packages/server/src/server/hostnames.ts

@@ -1,6 +1,6 @@
 import net from "node:net";
 
-export type AllowedHostsConfig = true | string[] | undefined;
+export type HostnamesConfig = true | string[] | undefined;
 
 function normalizeHostname(hostname: string): string {
   return hostname.trim().toLowerCase();
@@ -25,7 +25,7 @@ function parseHostnameFromHostHeader(hostHeader: string): string | null {
   return normalizeHostname(trimmed.slice(0, colonIndex));
 }
 
-function matchesAllowedHostPattern(hostname: string, pattern: string): boolean {
+function matchesHostnamePattern(hostname: string, pattern: string): boolean {
   const normalizedPattern = normalizeHostname(pattern);
   if (!normalizedPattern) return false;
 
@@ -47,33 +47,33 @@ function isDefaultAllowedHostname(hostname: string): boolean {
 }
 
 /**
- * Vite-style allowed hosts check, adapted to raw Host headers.
+ * Vite-style hostname allowlist check, adapted to raw Host headers.
  *
  * Semantics:
- * - `allowedHosts === true` => allow any host.
- * - `allowedHosts === []` or `undefined` => allow localhost, *.localhost, and all IPs.
- * - `allowedHosts === ['.example.com', 'myhost']` => allow those *in addition* to defaults.
+ * - `hostnames === true` => allow any host.
+ * - `hostnames === []` or `undefined` => allow localhost, *.localhost, and all IPs.
+ * - `hostnames === ['.example.com', 'myhost']` => allow those *in addition* to defaults.
  */
-export function isHostAllowed(
+export function isHostnameAllowed(
   hostHeader: string | undefined,
-  allowedHosts: AllowedHostsConfig,
+  hostnames: HostnamesConfig,
 ): boolean {
   const hostname = hostHeader ? parseHostnameFromHostHeader(hostHeader) : null;
   if (!hostname) return false;
 
-  if (allowedHosts === true) return true;
+  if (hostnames === true) return true;
 
   // Defaults are always allowed.
   if (isDefaultAllowedHostname(hostname)) return true;
 
-  const patterns = allowedHosts ?? [];
+  const patterns = hostnames ?? [];
   for (const pattern of patterns) {
-    if (matchesAllowedHostPattern(hostname, pattern)) return true;
+    if (matchesHostnamePattern(hostname, pattern)) return true;
   }
   return false;
 }
 
-export function mergeAllowedHosts(values: Array<AllowedHostsConfig>): AllowedHostsConfig {
+export function mergeHostnames(values: Array<HostnamesConfig>): HostnamesConfig {
   let merged: string[] = [];
   for (const value of values) {
     if (value === true) return true;
@@ -85,7 +85,7 @@ export function mergeAllowedHosts(values: Array<AllowedHostsConfig>): AllowedHos
   return deduped;
 }
 
-export function parseAllowedHostsEnv(raw: string | undefined): AllowedHostsConfig {
+export function parseHostnamesEnv(raw: string | undefined): HostnamesConfig {
   if (!raw) return undefined;
   const trimmed = raw.trim();
   if (!trimmed) return undefined;

packages/server/src/server/persisted-config.ts

@@ -228,6 +228,7 @@ export const PersistedConfigSchema = z
     daemon: z
       .object({
         listen: z.string().optional(),
+        hostnames: z.union([z.literal(true), z.array(z.string())]).optional(),
         allowedHosts: z.union([z.literal(true), z.array(z.string())]).optional(),
         mcp: z
           .object({
@@ -252,6 +253,10 @@ export const PersistedConfigSchema = z
           .optional(),
       })
       .strict()
+      .transform(({ allowedHosts, ...daemon }) => {
+        const hostnames = daemon.hostnames ?? allowedHosts;
+        return hostnames === undefined ? daemon : { ...daemon, hostnames };
+      })
       .optional(),
 
     app: z

packages/server/src/server/test-utils/paseo-daemon.ts

@@ -85,7 +85,7 @@ export async function createTestPaseoDaemon(
       listen: `${listenHost}:0`,
       paseoHome,
       corsAllowedOrigins: options.corsAllowedOrigins ?? [],
-      allowedHosts: true,
+      hostnames: true,
       mcpEnabled: true,
       staticDir,
       mcpDebug: false,

packages/server/src/server/websocket-server.ts

@@ -23,8 +23,8 @@ import {
   wrapSessionMessage,
 } from "./messages.js";
 import { asUint8Array, decodeTerminalStreamFrame } from "../shared/terminal-stream-protocol.js";
-import type { AllowedHostsConfig } from "./allowed-hosts.js";
-import { isHostAllowed } from "./allowed-hosts.js";
+import type { HostnamesConfig } from "./hostnames.js";
+import { isHostnameAllowed } from "./hostnames.js";
 import { Session, type SessionLifecycleIntent, type SessionRuntimeMetrics } from "./session.js";
 import type { AgentProvider } from "./agent/agent-sdk-types.js";
 import type {
@@ -61,7 +61,7 @@ type PendingConnection = {
 
 type WebSocketServerConfig = {
   allowedOrigins: Set<string>;
-  allowedHosts?: AllowedHostsConfig;
+  hostnames?: HostnamesConfig;
 };
 
 type WebSocketRuntimeMetrics = SessionRuntimeMetrics & CheckoutDiffMetrics;
@@ -433,7 +433,7 @@ export class VoiceAssistantWebSocketServer {
       this.broadcastAgentAttention(params);
     });
 
-    const { allowedOrigins, allowedHosts } = wsConfig;
+    const { allowedOrigins, hostnames } = wsConfig;
     this.wss = new WebSocketServer({
       server,
       path: "/ws",
@@ -441,7 +441,7 @@ export class VoiceAssistantWebSocketServer {
         const requestMetadata = extractSocketRequestMetadata(req);
         const origin = requestMetadata.origin;
         const requestHost = requestMetadata.host ?? null;
-        if (requestHost && !isHostAllowed(requestHost, allowedHosts)) {
+        if (requestHost && !isHostnameAllowed(requestHost, hostnames)) {
           this.incrementRuntimeCounter("hostRejected");
           this.logger.warn(
             { ...requestMetadata, host: requestHost },