feat: private hostname guard for authenticated/private mode

Reject requests from unrecognised Host headers when running
authenticated/private. Adds server middleware, CLI `allowed-hostname`
command, config-schema field, and prompt support for configuring
allowed hostnames during onboard/configure.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

cli/src/__tests__/allowed-hostname.test.ts

@@ -0,0 +1,71 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import type { PaperclipConfig } from "../config/schema.js";
+import { addAllowedHostname } from "../commands/allowed-hostname.js";
+
+function createTempConfigPath() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-allowed-hostname-"));
+  return path.join(dir, "config.json");
+}
+
+function writeBaseConfig(configPath: string) {
+  const base: PaperclipConfig = {
+    $meta: {
+      version: 1,
+      updatedAt: new Date("2026-01-01T00:00:00.000Z").toISOString(),
+      source: "configure",
+    },
+    database: {
+      mode: "embedded-postgres",
+      embeddedPostgresDataDir: "/tmp/paperclip-db",
+      embeddedPostgresPort: 54329,
+    },
+    logging: {
+      mode: "file",
+      logDir: "/tmp/paperclip-logs",
+    },
+    server: {
+      deploymentMode: "authenticated",
+      exposure: "private",
+      host: "0.0.0.0",
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    },
+    auth: {
+      baseUrlMode: "auto",
+    },
+    storage: {
+      provider: "local_disk",
+      localDisk: { baseDir: "/tmp/paperclip-storage" },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted",
+      strictMode: false,
+      localEncrypted: { keyFilePath: "/tmp/paperclip-secrets/master.key" },
+    },
+  };
+  fs.writeFileSync(configPath, JSON.stringify(base, null, 2));
+}
+
+describe("allowed-hostname command", () => {
+  it("adds and normalizes hostnames", async () => {
+    const configPath = createTempConfigPath();
+    writeBaseConfig(configPath);
+
+    await addAllowedHostname("https://Dotta-MacBook-Pro:3100", { config: configPath });
+    await addAllowedHostname("dotta-macbook-pro", { config: configPath });
+
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf-8")) as PaperclipConfig;
+    expect(raw.server.allowedHostnames).toEqual(["dotta-macbook-pro"]);
+  });
+});
+

cli/src/commands/allowed-hostname.ts

@@ -0,0 +1,37 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { normalizeHostnameInput } from "../config/hostnames.js";
+import { readConfig, resolveConfigPath, writeConfig } from "../config/store.js";
+
+export async function addAllowedHostname(host: string, opts: { config?: string }): Promise<void> {
+  const configPath = resolveConfigPath(opts.config);
+  const config = readConfig(opts.config);
+
+  if (!config) {
+    p.log.error(`No config found at ${configPath}. Run ${pc.cyan("paperclip onboard")} first.`);
+    return;
+  }
+
+  const normalized = normalizeHostnameInput(host);
+  const current = new Set((config.server.allowedHostnames ?? []).map((value) => value.trim().toLowerCase()).filter(Boolean));
+  const existed = current.has(normalized);
+  current.add(normalized);
+
+  config.server.allowedHostnames = Array.from(current).sort();
+  config.$meta.updatedAt = new Date().toISOString();
+  config.$meta.source = "configure";
+  writeConfig(config, opts.config);
+
+  if (existed) {
+    p.log.info(`Hostname ${pc.cyan(normalized)} is already allowed.`);
+  } else {
+    p.log.success(`Added allowed hostname: ${pc.cyan(normalized)}`);
+  }
+
+  if (!(config.server.deploymentMode === "authenticated" && config.server.exposure === "private")) {
+    p.log.message(
+      pc.dim("Note: allowed hostnames are enforced only in authenticated/private mode."),
+    );
+  }
+}
+

cli/src/commands/configure.ts

@@ -48,6 +48,7 @@ function defaultConfig(): PaperclipConfig {
       exposure: "private",
       host: "127.0.0.1",
       port: 3100,
+      allowedHostnames: [],
       serveUi: true,
     },
     auth: {
@@ -131,7 +132,10 @@ export async function configure(opts: {
         break;
       case "server":
         {
-          const { server, auth } = await promptServer();
+          const { server, auth } = await promptServer({
+            currentServer: config.server,
+            currentAuth: config.auth,
+          });
           config.server = server;
           config.auth = auth;
         }

cli/src/commands/onboard.ts

@@ -163,6 +163,7 @@ export async function onboard(opts: { config?: string }): Promise<void> {
       llm ? `LLM: ${llm.provider}` : "LLM: not configured",
       `Logging: ${logging.mode} → ${logging.logDir}`,
       `Server: ${server.deploymentMode}/${server.exposure} @ ${server.host}:${server.port}`,
+      `Allowed hosts: ${server.allowedHostnames.length > 0 ? server.allowedHostnames.join(", ") : "(loopback only)"}`,
       `Auth URL mode: ${auth.baseUrlMode}${auth.publicBaseUrl ? ` (${auth.publicBaseUrl})` : ""}`,
       `Storage: ${storage.provider}`,
       `Secrets: ${secrets.provider} (strict mode ${secrets.strictMode ? "on" : "off"})`,

cli/src/config/hostnames.ts

@@ -0,0 +1,26 @@
+export function normalizeHostnameInput(raw: string): string {
+  const input = raw.trim();
+  if (!input) {
+    throw new Error("Hostname is required");
+  }
+
+  try {
+    const url = input.includes("://") ? new URL(input) : new URL(`http://${input}`);
+    const hostname = url.hostname.trim().toLowerCase();
+    if (!hostname) throw new Error("Hostname is required");
+    return hostname;
+  } catch {
+    throw new Error(`Invalid hostname: ${raw}`);
+  }
+}
+
+export function parseHostnameCsv(raw: string): string[] {
+  if (!raw.trim()) return [];
+  const unique = new Set<string>();
+  for (const part of raw.split(",")) {
+    const hostname = normalizeHostnameInput(part);
+    unique.add(hostname);
+  }
+  return Array.from(unique);
+}
+

cli/src/index.ts

@@ -4,6 +4,7 @@ import { onboard } from "./commands/onboard.js";
 import { doctor } from "./commands/doctor.js";
 import { envCommand } from "./commands/env.js";
 import { configure } from "./commands/configure.js";
+import { addAllowedHostname } from "./commands/allowed-hostname.js";
 import { heartbeatRun } from "./commands/heartbeat-run.js";
 import { runCommand } from "./commands/run.js";
 import { bootstrapCeoInvite } from "./commands/auth-bootstrap-ceo.js";
@@ -52,6 +53,13 @@ program
   .option("-s, --section <section>", "Section to configure (llm, database, logging, server, storage, secrets)")
   .action(configure);
 
+program
+  .command("allowed-hostname")
+  .description("Allow a hostname for authenticated/private mode access")
+  .argument("<host>", "Hostname to allow (for example dotta-macbook-pro)")
+  .option("-c, --config <path>", "Path to config file")
+  .action(addAllowedHostname);
+
 program
   .command("run")
   .description("Bootstrap local setup (onboard + doctor) and run Paperclip")

cli/src/prompts/server.ts

@@ -1,7 +1,14 @@
 import * as p from "@clack/prompts";
 import type { AuthConfig, ServerConfig } from "../config/schema.js";
+import { parseHostnameCsv } from "../config/hostnames.js";
+
+export async function promptServer(opts?: {
+  currentServer?: Partial<ServerConfig>;
+  currentAuth?: Partial<AuthConfig>;
+}): Promise<{ server: ServerConfig; auth: AuthConfig }> {
+  const currentServer = opts?.currentServer;
+  const currentAuth = opts?.currentAuth;
 
-export async function promptServer(): Promise<{ server: ServerConfig; auth: AuthConfig }> {
   const deploymentModeSelection = await p.select({
     message: "Deployment mode",
     options: [
@@ -16,7 +23,7 @@ export async function promptServer(): Promise<{ server: ServerConfig; auth: Auth
         hint: "Login required; use for private network or public hosting",
       },
     ],
-    initialValue: "local_trusted",
+    initialValue: currentServer?.deploymentMode ?? "local_trusted",
   });
 
   if (p.isCancel(deploymentModeSelection)) {
@@ -24,6 +31,7 @@ export async function promptServer(): Promise<{ server: ServerConfig; auth: Auth
     process.exit(0);
   }
   const deploymentMode = deploymentModeSelection as ServerConfig["deploymentMode"];
+
   let exposure: ServerConfig["exposure"] = "private";
   if (deploymentMode === "authenticated") {
     const exposureSelection = await p.select({
@@ -40,7 +48,7 @@ export async function promptServer(): Promise<{ server: ServerConfig; auth: Auth
           hint: "Internet-facing deployment with stricter requirements",
         },
       ],
-      initialValue: "private",
+      initialValue: currentServer?.exposure ?? "private",
     });
     if (p.isCancel(exposureSelection)) {
       p.cancel("Setup cancelled.");
@@ -52,7 +60,7 @@ export async function promptServer(): Promise<{ server: ServerConfig; auth: Auth
   const hostDefault = deploymentMode === "local_trusted" ? "127.0.0.1" : "0.0.0.0";
   const hostStr = await p.text({
     message: "Bind host",
-    defaultValue: hostDefault,
+    defaultValue: currentServer?.host ?? hostDefault,
     placeholder: hostDefault,
     validate: (val) => {
       if (!val.trim()) return "Host is required";
@@ -66,7 +74,7 @@ export async function promptServer(): Promise<{ server: ServerConfig; auth: Auth
 
   const portStr = await p.text({
     message: "Server port",
-    defaultValue: "3100",
+    defaultValue: String(currentServer?.port ?? 3100),
     placeholder: "3100",
     validate: (val) => {
       const n = Number(val);
@@ -81,11 +89,35 @@ export async function promptServer(): Promise<{ server: ServerConfig; auth: Auth
     process.exit(0);
   }
 
+  let allowedHostnames: string[] = [];
+  if (deploymentMode === "authenticated" && exposure === "private") {
+    const allowedHostnamesInput = await p.text({
+      message: "Allowed hostnames (comma-separated, optional)",
+      defaultValue: (currentServer?.allowedHostnames ?? []).join(", "),
+      placeholder: "dotta-macbook-pro, your-host.tailnet.ts.net",
+      validate: (val) => {
+        try {
+          parseHostnameCsv(val);
+          return;
+        } catch (err) {
+          return err instanceof Error ? err.message : "Invalid hostname list";
+        }
+      },
+    });
+
+    if (p.isCancel(allowedHostnamesInput)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    allowedHostnames = parseHostnameCsv(allowedHostnamesInput);
+  }
+
   const port = Number(portStr) || 3100;
   let auth: AuthConfig = { baseUrlMode: "auto" };
   if (deploymentMode === "authenticated" && exposure === "public") {
     const urlInput = await p.text({
       message: "Public base URL",
+      defaultValue: currentAuth?.publicBaseUrl ?? "",
       placeholder: "https://paperclip.example.com",
       validate: (val) => {
         const candidate = val.trim();
@@ -109,10 +141,16 @@ export async function promptServer(): Promise<{ server: ServerConfig; auth: Auth
       baseUrlMode: "explicit",
       publicBaseUrl: urlInput.trim().replace(/\/+$/, ""),
     };
+  } else if (currentAuth?.baseUrlMode === "explicit" && currentAuth.publicBaseUrl) {
+    auth = {
+      baseUrlMode: "explicit",
+      publicBaseUrl: currentAuth.publicBaseUrl,
+    };
   }
 
   return {
-    server: { deploymentMode, exposure, host: hostStr.trim(), port, serveUi: true },
+    server: { deploymentMode, exposure, host: hostStr.trim(), port, allowedHostnames, serveUi: true },
     auth,
   };
 }
+