pi-studio 0.9.59 → 0.9.60-rc.0

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to `pi-studio` are documented here.
 
 ## [Unreleased]
 
+## [0.9.60-rc.0] — 2026-09-03
+
+### Added
+- Add explicit `/studio --listen-all` support for container and trusted private-network workflows. Studio binds to `0.0.0.0` only when requested, retains token authentication, keeps generated browser URLs on `127.0.0.1` for same-port host publishing, reports the active listening address in `/studio --status`, and requires a stop/restart before changing a running localhost server to wildcard binding.
+
+### Security
+- Wildcard network binding remains opt-in and emits a prominent warning that the tokenized URL grants control of Studio for the Pi process, including prompt submission and broad file access through Studio workflows. HTTP routing no longer derives its base authority from the inbound `Host` header. In wildcard mode, a browser-supplied HTTP(S) `Origin` must match that request's `Host`; originless non-browser or embedded clients continue to rely on the URL token. Documentation recommends loopback-only host port publishing, forbids direct public-internet exposure, and retains localhost plus SSH forwarding as the safe default.
+
 ## [0.9.59] — 2026-09-03
 
 ### Added

package/README.md

@@ -83,8 +83,9 @@ When Pi accepts **Run editor text**, Studio clears the linked terminal draft onl
 | `/studio --last` | Force last response |
 | `/studio --blank` | Force blank editor |
 | `/studio --no-browser` | Start/print the Studio URL without opening a browser, useful for forwarded or phone/browser sessions |
-| `/studio --port <port>` | Bind Studio to a fixed localhost port instead of a random free port |
-| `/studio --status` | Show studio server status |
+| `/studio --port <port>` | Bind Studio to a fixed port instead of a random free port; the default host remains localhost |
+| `/studio --listen-all` | Explicitly bind Studio to all IPv4 interfaces (`0.0.0.0`) for a container or trusted private-network workflow |
+| `/studio --status` | Show studio server status, including its listening address |
 | `/studio --stop` | Stop studio server |
 | `/studio --help` | Show help |
 | `/studio-replace [path\|--blank\|--last]` | Replace the current full Studio view with a new full Studio view |
@@ -118,6 +119,18 @@ Run once without installing:
 pi -e https://github.com/omaclaren/pi-studio
 ```
 
+## Container and network access
+
+Studio binds to `127.0.0.1` by default. For a container or sandbox whose port must be published to the host, opt in explicitly and choose a stable port:
+
+```text
+/studio --no-browser --listen-all --port 4321
+```
+
+This listens on `0.0.0.0:4321` while still printing a tokenized `http://127.0.0.1:4321/...` browser URL. With a same-port mapping such as `sbx run --publish 4321:4321`, open that URL unchanged on the host. `--listen-all` is a server-lifetime setting: if Studio is already running on localhost, use `/studio --stop` before restarting it with the flag.
+
+Treat wildcard binding as a security-sensitive mode. The URL token remains required, but anyone who obtains the full URL can control Studio for that Pi process: they can submit prompts, read or write files through Studio, and expand local-resource access. Studio does not add TLS. Treat the URL like a password, never expose the port directly to the public internet, and bind the host side of a container mapping to loopback when possible—for example, `-p 127.0.0.1:4321:4321`. For access across an untrusted network, keep Studio on its localhost default and use SSH local port forwarding instead.
+
 ## Shared REPL record
 
 Studio remains a standalone REPL client: it can create and use its own tmux sessions without `pi-repl`. When a compatible `pi-repl` installation uses the same tmux session, both clients automatically discover one session-owned clean record and see each other's code and captured output. No package imports or depends on the other.
@@ -220,7 +233,7 @@ Thanks to [Hal Gumbert / CampSoftware](https://github.com/campsoftware) for publ
 
 ## Notes
 
-- Local-only server (`127.0.0.1`) with tokenized Studio URLs.
+- The Studio server is localhost-only (`127.0.0.1`) by default and every Studio URL carries a server-lifetime token. The explicit `--listen-all` option changes the listening address to `0.0.0.0` without changing the advertised loopback URL or removing token authentication; `/studio --status` reports the active binding.
 - When Pi runs inside Muxy or cmux, Studio opens in that terminal app’s built-in browser. Muxy is detected from its pane/socket environment without installing global hooks; cmux targets and focuses the caller’s workspace. If the detected terminal browser is unavailable, disabled, or declines the request, Studio falls back once to the system browser.
 - For remote SSH sessions, keep Studio bound to localhost and use SSH local port forwarding; `/studio` and `/studio --status` print the full tokenized localhost URL. The SSH hint repeats the full URL so it is visible even if your terminal only shows the latest notification. Open that URL through the tunnel, preserving the `?token=...` parameter. If SSH is not auto-detected, use `/studio --no-browser`; for stable forwarding, use `/studio --port <port>` or combine them, e.g. `/studio --no-browser --port 3417`.
 - Full Studio is a singleton per Pi session: use `/studio` to open it, `/studio-replace` to explicitly replace it, and `/studio-editor-only` for extra editing/preview tabs that do not take over the full Studio session view.

package/ROADMAP.md

@@ -116,6 +116,17 @@ A small workflow refinement for moving Neovim-provided context through Pi and St
 - provide `Cmd/Ctrl+Shift+L` for loading and a confirmed **Clear Pi editor text…** fallback without changing Studio text or conversation history;
 - keep `pi-nvim-context`, protocol v1, networking, and the buffer-first architecture unchanged.
 
+## 0.9.60 — Opt-in container/network binding (`0.9.60-rc.0` prerelease, 2026-09-03)
+
+A bounded implementation of GitHub issue #4, separate from REPL transcript and buffer work:
+
+- retain `127.0.0.1` as the default and require explicit `--listen-all` intent before binding to `0.0.0.0`;
+- keep the server-lifetime bearer token mandatory and the generated URL on loopback for same-port container publishing;
+- keep inbound `Host` values out of route parsing and require wildcard-mode browser origins to match the request authority;
+- report the actual listening address, emit a prominent exposure warning, and require `/studio --stop` before changing a running server's binding;
+- document loopback-only host publishing, private-network limits, and SSH forwarding as the safer option on untrusted networks;
+- validate both default loopback and opt-in wildcard sockets without changing the buffer model, protocol v1, or `pi-repl`.
+
 ## 0.10.0 — Buffer-first editing
 
 The first architectural `0.10` release should add:

package/index.ts

@@ -46,6 +46,13 @@ import { createStudioPandocHtmlResourceFlagResolver } from "./shared/studio-pand
 import { createStudioResourceGrantRegistry } from "./shared/studio-resource-grants.js";
 import { prepareStudioLatexForPandoc } from "./shared/studio-latex-pandoc-compat.js";
 import { isStudioCmuxSession, openStudioUrlInBrowser } from "./shared/studio-browser-launcher.js";
+import {
+	buildStudioListenAllWarning,
+	isStudioWebSocketOriginAllowed,
+	parseStudioRequestTarget,
+	resolveStudioNetworkBinding,
+	STUDIO_ADVERTISED_HOST,
+} from "./shared/studio-network-binding.js";
 import { buildStudioReplTmuxStartArgs } from "./shared/studio-repl-tmux.js";
 import {
 	REPL_SESSION_RECORD_ID_OPTION,
@@ -197,6 +204,8 @@ interface StudioServerState {
 	clients: Set<WebSocket>;
 	clientModes: Map<WebSocket, StudioUiMode>;
 	port: number;
+	bindHost: string;
+	listenAll: boolean;
 	token: string;
 }
 
@@ -11865,13 +11874,6 @@ function interruptStudioReplSession(sessionName: string): { ok: true; message: s
 	return { ok: true, message: `Interrupted ${sessionName}.` };
 }
 
-function isAllowedOrigin(_origin: string | undefined, _port: number): boolean {
-	// For local-only studio, token auth is the primary guard. In practice,
-	// browser origin headers can vary (or be omitted) across wrappers/browsers,
-	// so we avoid brittle origin-based rejection here.
-	return true;
-}
-
 function normalizeStudioUiMode(raw: string | null | undefined): StudioUiMode {
 	return raw === "editor-only" ? "editor-only" : "full";
 }
@@ -11936,7 +11938,7 @@ function buildStudioUrl(
 	docId?: string,
 	options?: StudioUrlOptions,
 ): string {
-	return `http://127.0.0.1:${port}${buildStudioRelativeUrl(token, mode, doc, docId, options)}`;
+	return `http://${STUDIO_ADVERTISED_HOST}:${port}${buildStudioRelativeUrl(token, mode, doc, docId, options)}`;
 }
 
 interface StudioLaunchFlags {
@@ -11944,17 +11946,19 @@ interface StudioLaunchFlags {
 	openRemoteBrowser: boolean;
 	noBrowser: boolean;
 	watchPdf: boolean;
+	listenAll: boolean;
 	port?: number;
 	error?: string;
 }
 
 function parseStudioLaunchOpenFlags(rawArgs: string): StudioLaunchFlags {
 	const parsed = tokenizeStudioCommandArgs(rawArgs);
-	if (parsed.error) return { args: rawArgs, openRemoteBrowser: false, noBrowser: false, watchPdf: false, error: parsed.error };
+	if (parsed.error) return { args: rawArgs, openRemoteBrowser: false, noBrowser: false, watchPdf: false, listenAll: false, error: parsed.error };
 	const remaining: string[] = [];
 	let openRemoteBrowser = false;
 	let noBrowser = false;
 	let watchPdf = false;
+	let listenAll = false;
 	let port: number | undefined;
 	for (let i = 0; i < parsed.tokens.length; i += 1) {
 		const token = parsed.tokens[i]!;
@@ -11970,14 +11974,18 @@ function parseStudioLaunchOpenFlags(rawArgs: string): StudioLaunchFlags {
 			watchPdf = true;
 			continue;
 		}
+		if (token === "--listen-all") {
+			listenAll = true;
+			continue;
+		}
 		if (token === "--port" || token.startsWith("--port=")) {
 			const rawPort = token.startsWith("--port=") ? token.slice("--port=".length) : parsed.tokens[++i];
 			if (!rawPort) {
-				return { args: rawArgs, openRemoteBrowser, noBrowser, watchPdf, error: "Missing value for --port." };
+				return { args: rawArgs, openRemoteBrowser, noBrowser, watchPdf, listenAll, error: "Missing value for --port." };
 			}
 			const requestedPort = Number(rawPort);
 			if (!Number.isInteger(requestedPort) || requestedPort < 1 || requestedPort > 65535) {
-				return { args: rawArgs, openRemoteBrowser, noBrowser, watchPdf, error: `Invalid --port value: ${rawPort}. Use an integer from 1 to 65535.` };
+				return { args: rawArgs, openRemoteBrowser, noBrowser, watchPdf, listenAll, error: `Invalid --port value: ${rawPort}. Use an integer from 1 to 65535.` };
 			}
 			port = requestedPort;
 			continue;
@@ -11985,9 +11993,9 @@ function parseStudioLaunchOpenFlags(rawArgs: string): StudioLaunchFlags {
 		remaining.push(token);
 	}
 	if (openRemoteBrowser && noBrowser) {
-		return { args: rawArgs, openRemoteBrowser, noBrowser, watchPdf, port, error: "Use either --no-browser or --open-browser, not both." };
+		return { args: rawArgs, openRemoteBrowser, noBrowser, watchPdf, listenAll, port, error: "Use either --no-browser or --open-browser, not both." };
 	}
-	return { args: remaining.join(" "), openRemoteBrowser, noBrowser, watchPdf, port };
+	return { args: remaining.join(" "), openRemoteBrowser, noBrowser, watchPdf, listenAll, port };
 }
 
 function shouldAutoOpenStudioBrowser(options?: { openRemoteBrowser?: boolean; noBrowser?: boolean }): boolean {
@@ -17446,12 +17454,9 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
-		let requestUrl: URL;
-		try {
-			const host = req.headers.host ?? `127.0.0.1:${serverState.port}`;
-			requestUrl = new URL(req.url ?? "/", `http://${host}`);
-		} catch (error) {
-			respondText(res, 400, `Invalid request URL: ${error instanceof Error ? error.message : String(error)}`);
+		const requestUrl = parseStudioRequestTarget(req.url);
+		if (!requestUrl) {
+			respondText(res, 400, "Invalid request URL");
 			return;
 		}
 
@@ -18044,9 +18049,10 @@ export default function (pi: ExtensionAPI) {
 		res.end(buildStudioHtml(requestInitialDocument, serverState.token, lastCommandCtx?.ui.theme, currentModelLabel, terminalSessionLabel, terminalSessionDetail, contextUsageSnapshot, studioMode));
 	};
 
-	const ensureServer = async (requestedPort?: number): Promise<StudioServerState> => {
+	const ensureServer = async (requestedPort?: number, listenAll = false): Promise<StudioServerState> => {
 		if (serverState) return serverState;
 
+		const binding = resolveStudioNetworkBinding(listenAll);
 		const server = createServer(handleHttpRequest);
 		const wsServer = new WebSocketServer({ noServer: true });
 		const clients = new Set<WebSocket>();
@@ -18058,12 +18064,18 @@ export default function (pi: ExtensionAPI) {
 			clients,
 			clientModes,
 			port: 0,
+			bindHost: binding.bindHost,
+			listenAll: binding.listenAll,
 			token: createSessionToken(),
 		};
 
 		server.on("upgrade", (req, socket, head) => {
-			const host = req.headers.host ?? `127.0.0.1:${state.port}`;
-			const requestUrl = new URL(req.url ?? "/", `http://${host}`);
+			const requestUrl = parseStudioRequestTarget(req.url);
+			if (!requestUrl) {
+				socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+				socket.destroy();
+				return;
+			}
 
 			if (requestUrl.pathname !== "/ws") {
 				socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
@@ -18078,7 +18090,9 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			if (!isAllowedOrigin(req.headers.origin, state.port)) {
+			const origin = typeof req.headers.origin === "string" ? req.headers.origin : undefined;
+			const requestHost = typeof req.headers.host === "string" ? req.headers.host : undefined;
+			if (!isStudioWebSocketOriginAllowed(origin, requestHost, state.listenAll)) {
 				socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
 				socket.destroy();
 				return;
@@ -18090,8 +18104,15 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		wsServer.on("connection", (ws, req) => {
-			const host = req.headers.host ?? `127.0.0.1:${state.port}`;
-			const requestUrl = new URL(req.url ?? "/ws", `http://${host}`);
+			const requestUrl = parseStudioRequestTarget(req.url);
+			if (!requestUrl) {
+				try {
+					ws.close(1008, "Invalid request URL");
+				} catch {
+					// Ignore close errors.
+				}
+				return;
+			}
 			const clientMode = normalizeStudioUiMode(requestUrl.searchParams.get("mode"));
 			const requestedWatchedPath = (requestUrl.searchParams.get("watchPath") ?? "").trim();
 			const canonicalWatchedPath = requestedWatchedPath ? resolve(requestedWatchedPath) : "";
@@ -18190,7 +18211,7 @@ export default function (pi: ExtensionAPI) {
 			};
 			server.once("error", onError);
 			server.once("listening", onListening);
-			server.listen(listenPort, "127.0.0.1");
+			server.listen(listenPort, state.bindHost);
 		});
 
 		const address = server.address();
@@ -19063,6 +19084,10 @@ export default function (pi: ExtensionAPI) {
 		if (serverState && launchOpenFlags.port && serverState.port !== launchOpenFlags.port) {
 			ctx.ui.notify(`Studio server is already running on port ${serverState.port}; requested port ${launchOpenFlags.port}. Use /studio --stop, then restart Studio with --port ${launchOpenFlags.port} to change it.`, "warning");
 		}
+		if (serverState && launchOpenFlags.listenAll && !serverState.listenAll) {
+			ctx.ui.notify(`Studio server is already bound to localhost at 127.0.0.1:${serverState.port}. Use /studio --stop, then restart it with --listen-all.`, "warning");
+			return;
+		}
 
 		const parsedLaunchPath = options?.allowPdfPreview ? parsePathArgument(launchArgs) : null;
 		const launchesPdfPreview = parsedLaunchPath
@@ -19082,9 +19107,12 @@ export default function (pi: ExtensionAPI) {
 				if (serverState) {
 					const url = buildStudioUrl(serverState.port, serverState.token, "full");
 					ctx.ui.notify(`Studio URL: ${url}`, "info");
-					const tunnelHint = buildStudioSshTunnelHint(serverState.port, url)
-						?? (launchOpenFlags.noBrowser ? buildStudioForwardingHint(serverState.port, url, { prefix: "Browser auto-open was skipped because --no-browser was used." }) : null);
+					const tunnelHint = serverState.listenAll
+						? null
+						: buildStudioSshTunnelHint(serverState.port, url)
+							?? (launchOpenFlags.noBrowser ? buildStudioForwardingHint(serverState.port, url, { prefix: "Browser auto-open was skipped because --no-browser was used." }) : null);
 					if (tunnelHint) ctx.ui.notify(tunnelHint, "info");
+					if (serverState.listenAll) ctx.ui.notify(buildStudioListenAllWarning(serverState.port, url), "warning");
 				}
 				return;
 			}
@@ -19117,7 +19145,7 @@ export default function (pi: ExtensionAPI) {
 
 		let state: StudioServerState;
 		try {
-			state = await ensureServer(launchOpenFlags.port);
+			state = await ensureServer(launchOpenFlags.port, launchOpenFlags.listenAll);
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			const portText = launchOpenFlags.port ? ` on port ${launchOpenFlags.port}` : "";
@@ -19130,8 +19158,10 @@ export default function (pi: ExtensionAPI) {
 			skipWorkspaceRestore: selection.skipWorkspaceRestore,
 			paneFocus: selection.paneFocus,
 		});
-		const tunnelHint = buildStudioSshTunnelHint(state.port, url)
-			?? (launchOpenFlags.noBrowser ? buildStudioForwardingHint(state.port, url, { prefix: "Browser auto-open was skipped because --no-browser was used." }) : null);
+		const tunnelHint = state.listenAll
+			? null
+			: buildStudioSshTunnelHint(state.port, url)
+				?? (launchOpenFlags.noBrowser ? buildStudioForwardingHint(state.port, url, { prefix: "Browser auto-open was skipped because --no-browser was used." }) : null);
 		const openedLabel = selection.kind === "pdf-preview"
 			? "pi Studio PDF preview"
 			: (selection.kind === "watched-preview"
@@ -19171,11 +19201,12 @@ export default function (pi: ExtensionAPI) {
 		} finally {
 			ctx.ui.notify(`Studio URL: ${url}`, "info");
 			if (tunnelHint) ctx.ui.notify(tunnelHint, "info");
+			if (state.listenAll) ctx.ui.notify(buildStudioListenAllWarning(state.port, url), "warning");
 		}
 	};
 
 	pi.registerCommand("studio", {
-		description: "Open pi Studio browser UI or a read-only watched preview (/studio, /studio <file>, /studio --watch <file>, /studio --blank, /studio --last, /studio --no-browser)",
+		description: "Open pi Studio browser UI or a read-only watched preview (/studio, /studio <file>, /studio --watch <file>, /studio --blank, /studio --last, /studio --no-browser, /studio --listen-all)",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const trimmed = args.trim();
 
@@ -19193,11 +19224,12 @@ export default function (pi: ExtensionAPI) {
 				const counts = getStudioClientCounts();
 				const url = buildStudioUrl(serverState.port, serverState.token, "full");
 				ctx.ui.notify(
-					`Studio running at ${url} (busy: ${isStudioBusy() ? "yes" : "no"}; full views: ${counts.full}; editor-only views: ${counts.editorOnly})`,
+					`Studio running at ${url} (listening on ${serverState.bindHost}:${serverState.port}; busy: ${isStudioBusy() ? "yes" : "no"}; full views: ${counts.full}; editor-only views: ${counts.editorOnly})`,
 					"info",
 				);
-				const sshTunnelHint = buildStudioSshTunnelHint(serverState.port, url);
+				const sshTunnelHint = serverState.listenAll ? null : buildStudioSshTunnelHint(serverState.port, url);
 				if (sshTunnelHint) ctx.ui.notify(sshTunnelHint, "info");
+				if (serverState.listenAll) ctx.ui.notify(buildStudioListenAllWarning(serverState.port, url), "warning");
 				return;
 			}
 
@@ -19210,7 +19242,8 @@ export default function (pi: ExtensionAPI) {
 						+ "  /studio --blank   Open with blank editor\n"
 						+ "  /studio --last    Open with last model response\n"
 						+ "  /studio --no-browser  Print the Studio URL without opening a browser\n"
-						+ "  /studio --port <port> Bind Studio to a fixed localhost port when starting\n"
+						+ "  /studio --port <port> Bind Studio to a fixed port when starting\n"
+						+ "  /studio --listen-all  Explicitly bind to 0.0.0.0 instead of localhost (security-sensitive)\n"
 						+ "  /studio --open-remote  Over SSH, open the remote browser anyway\n"
 						+ "  /studio --status  Show studio status\n"
 						+ "  /studio --stop    Stop studio server\n"
@@ -19241,7 +19274,8 @@ export default function (pi: ExtensionAPI) {
 						+ "  /studio-replace --blank Replace with blank editor\n"
 						+ "  /studio-replace --last  Replace with last model response\n"
 						+ "  /studio-replace --no-browser  Print URL without opening a browser\n"
-						+ "  /studio-replace --port <port> Bind Studio to a fixed localhost port when starting\n"
+						+ "  /studio-replace --port <port> Bind Studio to a fixed port when starting\n"
+						+ "  /studio-replace --listen-all  Explicitly bind to 0.0.0.0 instead of localhost\n"
 						+ "Editor-only Studio views stay open.",
 					"info",
 				);
@@ -19269,7 +19303,8 @@ export default function (pi: ExtensionAPI) {
 						+ "  /studio-editor-only --blank Open with blank editor\n"
 						+ "  /studio-editor-only --last  Open with last model response loaded into the editor\n"
 						+ "  /studio-editor-only --no-browser  Print URL without opening a browser\n"
-						+ "  /studio-editor-only --port <port> Bind Studio to a fixed localhost port when starting\n"
+						+ "  /studio-editor-only --port <port> Bind Studio to a fixed port when starting\n"
+						+ "  /studio-editor-only --listen-all  Explicitly bind to 0.0.0.0 instead of localhost\n"
 						+ "Multiple editor-only views are allowed in the same Pi session.",
 					"info",
 				);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-studio",
-  "version": "0.9.59",
+  "version": "0.9.60-rc.0",
   "description": "Two-pane browser workspace for pi with prompt/response editing, annotations, critiques, active quiz, prompt/response history, live previews, and tmux-backed REPL/literate REPL workflows",
   "type": "module",
   "license": "MIT",

package/shared/studio-network-binding.js

@@ -0,0 +1,103 @@
+export const STUDIO_LOOPBACK_BIND_HOST = "127.0.0.1";
+export const STUDIO_ALL_INTERFACES_BIND_HOST = "0.0.0.0";
+export const STUDIO_ADVERTISED_HOST = STUDIO_LOOPBACK_BIND_HOST;
+
+/**
+ * Resolve Studio's server-lifetime network binding. Listening on every IPv4
+ * interface is deliberately opt-in; generated browser URLs remain loopback URLs
+ * so same-port container publishing does not require URL editing.
+ *
+ * @param {boolean} [listenAll]
+ * @returns {{ bindHost: string, advertisedHost: string, listenAll: boolean }}
+ */
+export function resolveStudioNetworkBinding(listenAll = false) {
+	const enabled = listenAll === true;
+	return {
+		bindHost: enabled ? STUDIO_ALL_INTERFACES_BIND_HOST : STUDIO_LOOPBACK_BIND_HOST,
+		advertisedHost: STUDIO_ADVERTISED_HOST,
+		listenAll: enabled,
+	};
+}
+
+/**
+ * Parse only an HTTP origin-form request target. The inbound Host header is not
+ * needed for Studio routing and must not become the base URL authority.
+ *
+ * @param {string | undefined} requestTarget
+ * @returns {URL | null}
+ */
+export function parseStudioRequestTarget(requestTarget) {
+	const value = typeof requestTarget === "string" ? requestTarget : "/";
+	if (!value.startsWith("/") || value.startsWith("//")) return null;
+	try {
+		const expectedOrigin = `http://${STUDIO_ADVERTISED_HOST}`;
+		const parsed = new URL(value, expectedOrigin);
+		return parsed.origin === expectedOrigin ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Preserve the existing permissive Origin behavior for the localhost server.
+ * In wildcard mode, an omitted Origin remains compatible with embedded and
+ * non-browser clients; a supplied browser Origin must be HTTP(S) and match the
+ * request's Host authority so a cross-origin page cannot drive the WebSocket.
+ *
+ * @param {string | undefined} originHeader
+ * @param {string | undefined} requestHost
+ * @param {boolean} [requireSameHost]
+ * @returns {boolean}
+ */
+export function isStudioWebSocketOriginAllowed(originHeader, requestHost, requireSameHost = false) {
+	if (!originHeader || !requireSameHost) return true;
+	let originUrl;
+	try {
+		originUrl = new URL(originHeader);
+	} catch {
+		return false;
+	}
+	if (originUrl.protocol !== "http:" && originUrl.protocol !== "https:") return false;
+	if (
+		originUrl.username
+		|| originUrl.password
+		|| originUrl.pathname !== "/"
+		|| originUrl.search
+		|| originUrl.hash
+	) return false;
+	if (typeof requestHost !== "string" || requestHost.length === 0) return false;
+
+	try {
+		const requestOrigin = new URL(`http://${requestHost}`);
+		if (
+			requestOrigin.username
+			|| requestOrigin.password
+			|| requestOrigin.pathname !== "/"
+			|| requestOrigin.search
+			|| requestOrigin.hash
+		) return false;
+		return originUrl.host.toLowerCase() === requestOrigin.host.toLowerCase();
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * @param {number} port
+ * @param {string} [studioUrl]
+ * @returns {string}
+ */
+export function buildStudioListenAllWarning(port, studioUrl) {
+	const normalizedPort = Number.isInteger(port) && port > 0 && port <= 65535
+		? port
+		: "<port>";
+	const urlLine = typeof studioUrl === "string" && studioUrl.length > 0
+		? `\nStudio URL: ${studioUrl}`
+		: "";
+	return "Security warning: pi Studio is listening on all IPv4 interfaces at "
+		+ `${STUDIO_ALL_INTERFACES_BIND_HOST}:${normalizedPort}. `
+		+ "Anyone who obtains the tokenized Studio URL can control Studio for this Pi process, including submitting prompts, reading or writing files through Studio, and expanding local-resource access. "
+		+ "Treat the URL like a password. Expose this port only through a trusted local mapping or private network, and prefer SSH tunnelling on untrusted networks. "
+		+ "Use /studio --stop before restarting without --listen-all to return to localhost-only mode."
+		+ urlLine;
+}