The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(runtime): only rewrite base-URL port for loopback hosts (#10258)
Eric Brookfield166f381d3fa5
diff --git a/server/src/__tests__/server-startup-feedback-export.test.ts b/server/src/__tests__/server-startup-feedback-export.test.tsindex 63dd0b716c..b01ad17d02 100644--- a/server/src/__tests__/server-startup-feedback-export.test.ts+++ b/server/src/__tests__/server-startup-feedback-export.test.ts@@ -693,7 +693,7 @@ describe("startServer PAPERCLIP_API_URL handling", () => {);});- it("rewrites explicit-port auth public URLs when detect-port selects a new port", async () => {+ it("preserves explicit-port external auth public URLs when detect-port selects a new port", async () => {loadConfigMock.mockReturnValueOnce(buildTestConfig({port: 3100,authBaseUrlMode: "explicit",@@ -703,9 +703,12 @@ describe("startServer PAPERCLIP_API_URL handling", () => {const started = await startServer();+ // The server listens internally on 3110, but an explicit *external* base URL must keep+ // its advertised port. Rewriting it to the internal listen port produced an unreachable+ // URL that leaked to spawned agents as a dead PAPERCLIP_API_URL. (BRO-1558)expect(started.listenPort).toBe(3110);- expect(started.apiUrl).toBe("http://my-host.ts.net:3110");- expect(process.env.PAPERCLIP_RUNTIME_API_URL).toBe("http://my-host.ts.net:3110");+ expect(started.apiUrl).toBe("http://my-host.ts.net:3100");+ expect(process.env.PAPERCLIP_RUNTIME_API_URL).toBe("http://my-host.ts.net:3100");});it("keeps no-port auth public URLs stable when detect-port selects a new port", async () => {diff --git a/server/src/index.ts b/server/src/index.tsindex b46b9d2324..c338564356 100644--- a/server/src/index.ts+++ b/server/src/index.ts@@ -78,6 +78,7 @@ import {} from "./services/adapter-registry-bootstrap.js";import { createFeedbackTraceShareClientFromConfig } from "./services/feedback-share-client.js";import { buildRuntimeApiCandidateUrls, choosePrimaryRuntimeApiUrl } from "./runtime-api.js";+import { isLoopbackHost, rewriteLoopbackUrlPort } from "./url-utils.js";import { createPluginWorkerManager } from "./services/plugin-worker-manager.js";import { createStorageServiceFromConfig } from "./storage/index.js";import { printStartupBanner } from "./startup-banner.js";@@ -235,11 +236,6 @@ export async function startServer(): Promise<StartedServer> {return "applied (pending migrations)";}- function isLoopbackHost(host: string): boolean {- const normalized = host.trim().toLowerCase();- return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";- }-function isPostgresConnectionString(connectionString: string): boolean {try {const parsed = new URL(connectionString);@@ -265,19 +261,6 @@ export async function startServer(): Promise<StartedServer> {}}- function rewriteLocalUrlPort(rawUrl: string | undefined, port: number): string | undefined {- if (!rawUrl) return undefined;- try {- const parsed = new URL(rawUrl);- // The URL API normalizes default ports like :80/:443 to "", so treat them as stable URLs.- if (!parsed.port) return rawUrl;- parsed.port = String(port);- return parsed.toString();- } catch {- return rawUrl;- }- }-const LOCAL_BOARD_USER_ID = "local-board";const LOCAL_BOARD_USER_EMAIL = "[email protected]";const LOCAL_BOARD_USER_NAME = "Board";@@ -558,7 +541,7 @@ export async function startServer(): Promise<StartedServer> {const requestedListenPort = config.port;const listenPort = await detectPort(requestedListenPort);if (config.authBaseUrlMode === "explicit" && config.authPublicBaseUrl) {- config.authPublicBaseUrl = rewriteLocalUrlPort(config.authPublicBaseUrl, listenPort);+ config.authPublicBaseUrl = rewriteLoopbackUrlPort(config.authPublicBaseUrl, listenPort);}let authReady = config.deploymentMode === "local_trusted";diff --git a/server/src/url-utils.test.ts b/server/src/url-utils.test.tsnew file mode 100644index 0000000000..7f061d5373--- /dev/null+++ b/server/src/url-utils.test.ts@@ -0,0 +1,65 @@+import { describe, expect, it } from "vitest";+import { isLoopbackHost, rewriteLoopbackUrlPort, rewriteUrlPort } from "./url-utils.js";++describe("rewriteUrlPort", () => {+ it("rewrites the port for any explicit-port URL, including external hosts", () => {+ expect(rewriteUrlPort("http://localhost:5678", 3101)).toBe("http://localhost:3101/");+ expect(rewriteUrlPort("http://127.0.0.1:9999", 3101)).toBe("http://127.0.0.1:3101/");+ // A worktree advertises its own port even on a non-loopback host.+ expect(rewriteUrlPort("http://my-host.ts.net:3100", 3103)).toBe("http://my-host.ts.net:3103/");+ });++ it("leaves URLs without an explicit port stable", () => {+ expect(rewriteUrlPort("https://paperclip.example", 3101)).toBe("https://paperclip.example");+ expect(rewriteUrlPort("http://localhost", 3101)).toBe("http://localhost");+ });++ it("passes through empty and unparseable inputs", () => {+ expect(rewriteUrlPort(undefined, 3101)).toBeUndefined();+ expect(rewriteUrlPort("", 3101)).toBeUndefined();+ expect(rewriteUrlPort("not a url", 3101)).toBe("not a url");+ });+});++describe("rewriteLoopbackUrlPort", () => {+ it("rewrites the port for loopback base URLs", () => {+ expect(rewriteLoopbackUrlPort("http://localhost:5678", 3101)).toBe("http://localhost:3101/");+ expect(rewriteLoopbackUrlPort("http://127.0.0.1:9999", 3101)).toBe("http://127.0.0.1:3101/");+ expect(rewriteLoopbackUrlPort("http://[::1]:9999", 3101)).toBe("http://[::1]:3101/");+ });++ it("leaves explicit external base URLs untouched (BRO-1558)", () => {+ // A Tailscale Serve listener on :8443 must survive; rewriting its port to the internal+ // listen port produced an unreachable URL that leaked to agents as a dead PAPERCLIP_API_URL.+ const serve = "https://erics-mac-studio-1.tailc54c7.ts.net:8443";+ expect(rewriteLoopbackUrlPort(serve, 3101)).toBe(serve);+ });++ it("leaves URLs without an explicit port stable", () => {+ expect(rewriteLoopbackUrlPort("https://paperclip.example.com", 3101)).toBe(+ "https://paperclip.example.com",+ );+ expect(rewriteLoopbackUrlPort("http://localhost", 3101)).toBe("http://localhost");+ });++ it("passes through empty and unparseable inputs", () => {+ expect(rewriteLoopbackUrlPort(undefined, 3101)).toBeUndefined();+ expect(rewriteLoopbackUrlPort("", 3101)).toBeUndefined();+ expect(rewriteLoopbackUrlPort("not a url", 3101)).toBe("not a url");+ });+});++describe("isLoopbackHost", () => {+ it("matches loopback hosts including bracketed IPv6", () => {+ expect(isLoopbackHost("localhost")).toBe(true);+ expect(isLoopbackHost("127.0.0.1")).toBe(true);+ expect(isLoopbackHost("::1")).toBe(true);+ expect(isLoopbackHost("[::1]")).toBe(true);+ expect(isLoopbackHost("LOCALHOST")).toBe(true);+ });++ it("rejects external hosts", () => {+ expect(isLoopbackHost("erics-mac-studio-1.tailc54c7.ts.net")).toBe(false);+ expect(isLoopbackHost("paperclip.example.com")).toBe(false);+ });+});diff --git a/server/src/url-utils.ts b/server/src/url-utils.tsnew file mode 100644index 0000000000..30992ec9cc--- /dev/null+++ b/server/src/url-utils.ts@@ -0,0 +1,57 @@+/**+ * Shared base-URL helpers used by both server startup (index.ts) and worktree+ * config materialization (worktree-config.ts). Keeping a single source of truth+ * for host classification and port rewriting prevents the two paths from drifting.+ */++export function isLoopbackHost(host: string): boolean {+ // Strip surrounding brackets so a URL hostname form ("[::1]") matches too.+ const normalized = host.trim().toLowerCase().replace(/^\[|\]$/g, "");+ return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";+}++/**+ * Rewrite the port of any explicit-port base URL to `port`, leaving portless and+ * unparseable URLs untouched.+ *+ * Used by the worktree path: a worktree is a distinct instance on its own server+ * port, so its advertised base URL must follow that port even for a non-loopback+ * host (worktrees are reachable at the same host on their own port).+ */+export function rewriteUrlPort(rawUrl: string | undefined, port: number): string | undefined {+ if (!rawUrl) return undefined;+ try {+ const parsed = new URL(rawUrl);+ // The URL API normalizes default ports like :80/:443 to "", so treat them as stable URLs.+ if (!parsed.port) return rawUrl;+ parsed.port = String(port);+ return parsed.toString();+ } catch {+ return rawUrl;+ }+}++/**+ * Like {@link rewriteUrlPort}, but only for loopback hosts.+ *+ * Used at server startup for the main instance's `authPublicBaseUrl`. An explicit+ * *external* base URL (e.g. a Tailscale Serve listener on a non-default port like+ * :8443) must survive untouched: rewriting its port to the internal listen port+ * yields an unreachable URL (scheme/port mismatch) that then propagates to spawned+ * agents as a dead PAPERCLIP_API_URL. (BRO-1558)+ */+export function rewriteLoopbackUrlPort(+ rawUrl: string | undefined,+ port: number,+): string | undefined {+ if (!rawUrl) return undefined;+ try {+ const parsed = new URL(rawUrl);+ if (!parsed.port) return rawUrl;+ if (!isLoopbackHost(parsed.hostname)) return rawUrl;+ parsed.port = String(port);+ return parsed.toString();+ } catch {+ return rawUrl;+ }+}diff --git a/server/src/worktree-config.ts b/server/src/worktree-config.tsindex b05686204e..db4e9fffe7 100644--- a/server/src/worktree-config.ts+++ b/server/src/worktree-config.ts@@ -9,6 +9,7 @@ import {} from "@paperclipai/shared";import { updateEnvFileContents, writeEnvFileAtomicallyIfChanged } from "@paperclipai/shared/env-file";import { resolvePaperclipConfigPath, resolvePaperclipEnvPath } from "./paths.js";+import { rewriteUrlPort } from "./url-utils.js";function nonEmpty(value: string | null | undefined): string | null {return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;@@ -33,19 +34,6 @@ function sanitizeWorktreeInstanceId(rawValue: string): string {return normalized || "worktree";}-function rewriteLocalUrlPort(rawUrl: string | undefined, port: number): string | undefined {- if (!rawUrl) return undefined;- try {- const parsed = new URL(rawUrl);- // The URL API normalizes default ports like :80/:443 to "", so treat them as stable URLs.- if (!parsed.port) return rawUrl;- parsed.port = String(port);- return parsed.toString();- } catch {- return rawUrl;- }-}-function parseEnvFile(contents: string): Record<string, string> {const entries: Record<string, string> = {};@@ -444,7 +432,7 @@ function buildIsolatedWorktreeConfig(if (config.auth.baseUrlMode === "explicit" && config.auth.publicBaseUrl) {nextConfig.auth = {...config.auth,- publicBaseUrl: rewriteLocalUrlPort(config.auth.publicBaseUrl, serverPort),+ publicBaseUrl: rewriteUrlPort(config.auth.publicBaseUrl, serverPort),};}@@ -520,7 +508,7 @@ export function applyRuntimePortSelectionToConfig(}if (nextConfig.auth.baseUrlMode === "explicit" && nextConfig.auth.publicBaseUrl) {- const rewritten = rewriteLocalUrlPort(nextConfig.auth.publicBaseUrl, input.serverPort);+ const rewritten = rewriteUrlPort(nextConfig.auth.publicBaseUrl, input.serverPort);if (rewritten && rewritten !== nextConfig.auth.publicBaseUrl) {nextConfig = {...nextConfig,