Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
fix(browser): retain private viewer connectivity without server access
Rahman7b82b6fd7f84
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 9756335f..af4974d9 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -1,3 +1,17 @@+## 2026-09-18 — Keep private viewer routing client-verifiable++The PR review reproduced a deployment-compatibility regression: a hostname resolving+only to RFC1918, carrier-grade NAT or unique-local IPv6 was blocked by the generic+public-provider SSRF guard before the client's authenticated viewer could mount.+Keep that guard intact. A typed refusal now distinguishes these private addresses+from loopback, metadata, link-local, malformed and mixed DNS responses. The browser+transport diagnostic records reachable=false and client-only verification instead+of claiming success or opening any private server connection. The authenticated+client accepts only that exact diagnostic; all other TLS/DNS/HTTP failures retain+their behavior. Configured separate origins, TLS, cookies and VNC auth are unchanged.+Boundary tests cover refused address classes and malformed hints; a desktop/mobile+browser journey verifies private viewer mounting while connection retry stays read-only.+## 2026-09-18 — Resolve release review on Node support and browser retriesThe dependency toolchain now requires the same supported Node range everywhere:diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex 22423e5e..63a8665b 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -478,3 +478,12 @@ saved logins and profile data; a passing clean-profile test is not a repaired saFor GitHub connection diagnosis, compare the returned authenticated login with the intendedaccount, then verify permissions on the exact repository. A named MSO profile, a successful`/user` response, and permission to merge a repository are three different facts.++### Private or split-DNS Camoufox viewers++A configured viewer hostname may resolve exclusively to RFC1918, carrier-grade NAT,+or unique-local IPv6 addresses. MSO does not send a server-side request to these+addresses: diagnostics report `client-only` and `reachable: false`. The browser may+then load the configured, separate viewer origin and verify its own HTTPS/authentication.+This is not a server reachability pass. Loopback, metadata, link-local and mixed DNS+answers remain denied; there is no unauthenticated proxy or same-origin fallback.diff --git a/frontend/slices/camoufox-browser/service-client.test.ts b/frontend/slices/camoufox-browser/service-client.test.tsindex b3264cee..75dda6fd 100644--- a/frontend/slices/camoufox-browser/service-client.test.ts+++ b/frontend/slices/camoufox-browser/service-client.test.ts@@ -58,3 +58,23 @@ it("does not publish a state observation after cancellation", async () => {await expect(waitForViewer(controller.signal, 0, observed)).resolves.toBe(false);expect(observed).not.toHaveBeenCalled();});++it("permits client verification only for the explicit private-route diagnostic", async () => {+ const { verifyViewerTransport } = await import("./service-client");+ vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ reachable: false, state: "client-only", clientOnly: true }), { status: 200 })));+ await expect(verifyViewerTransport(new AbortController().signal)).resolves.toBeUndefined();+ vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ reachable: false, state: "tls", clientOnly: true, message: "TLS remains blocked" }), { status: 200 })));+ await expect(verifyViewerTransport(new AbortController().signal)).rejects.toThrow("TLS remains blocked");+});++it.each([+ [200, { reachable: false, state: "client-only" }],+ [200, { reachable: false, state: "client-only", clientOnly: "true" }],+ [200, { reachable: false, state: "network", clientOnly: true }],+ [401, { reachable: false, state: "client-only", clientOnly: true }],+ [503, { reachable: false, state: "client-only", clientOnly: true }],+])("does not turn HTTP %s or incomplete client-only evidence into permission", async (status, payload) => {+ const { verifyViewerTransport } = await import("./service-client");+ vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify(payload), { status })));+ await expect(verifyViewerTransport(new AbortController().signal)).rejects.toThrow();+});diff --git a/frontend/slices/camoufox-browser/service-client.ts b/frontend/slices/camoufox-browser/service-client.tsindex d8864319..2d676758 100644--- a/frontend/slices/camoufox-browser/service-client.ts+++ b/frontend/slices/camoufox-browser/service-client.ts@@ -54,6 +54,7 @@ export async function waitForViewer(signal: AbortSignal, timeoutMs = 30_000, onS/** Check public TLS through the authenticated API, never by widening browser CORS. */export async function verifyViewerTransport(signal: AbortSignal): Promise<void> {const response = await fetch("/api/v1/camoufox/service?probe=viewer", { cache: "no-store", signal });- const result = await response.json() as { reachable?: boolean; message?: string; error?: string };- if (!response.ok || result.reachable !== true) throw new Error(result.message ?? result.error ?? "The secure viewer is unavailable");+ const result = await response.json() as { reachable?: boolean; state?: string; clientOnly?: boolean; message?: string; error?: string };+ const clientPrivateRoute = result.state === "client-only" && result.clientOnly === true;+ if (!response.ok || (result.reachable !== true && !clientPrivateRoute)) throw new Error(result.message ?? result.error ?? "The secure viewer is unavailable");}diff --git a/lib/camoufox/private-viewer.test.ts b/lib/camoufox/private-viewer.test.tsnew file mode 100644index 00000000..2277c7dc--- /dev/null+++ b/lib/camoufox/private-viewer.test.ts@@ -0,0 +1,36 @@+import { describe, expect, it, vi } from "vitest";+vi.mock("server-only", () => ({}));+import { resolveSafeProviderEndpoint } from "@/lib/host/ssrf";+import { inspectViewerTransport } from "./viewer-transport";++async function inspect(addresses: string[]) {+ return inspectViewerTransport("https://camoufox.example.com", async () => {+ await resolveSafeProviderEndpoint("https://camoufox.example.com", async () => addresses.map(address => ({ address, family: address.includes(":") ? 6 : 4 })));+ throw new Error("A forbidden address unexpectedly escaped the server guard");+ });+}+describe("deployment-owned private viewer diagnostics", () => {+ it.each(["10.0.0.4", "172.16.0.4", "192.168.1.4", "100.64.0.4", "fd7a:115c:a1e0::4"])("keeps %s server-blocked and delegates reachability to the client", async address => {+ await expect(resolveSafeProviderEndpoint("https://viewer.example", async () => [{ address, family: address.includes(":") ? 6 : 4 }])).rejects.toThrow(/DNS resolved/);+ expect(await inspect([address])).toMatchObject({ reachable: false, state: "client-only", clientOnly: true });+ });+ it.each(["127.0.0.1", "169.254.169.254", "fe80::1", "::1", "0.0.0.0"])("never treats unsafe address %s as client-verifiable private routing", async address => {+ const result = await inspect([address]);+ expect(result.reachable).toBe(false); expect(result.clientOnly).not.toBe(true);+ });+ it("keeps mixed public/private and private/metadata DNS answers denied", async () => {+ for (const addresses of [["1.1.1.1", "10.0.0.4"], ["10.0.0.4", "169.254.169.254"]])+ expect((await inspect(addresses)).clientOnly).not.toBe(true);+ });+});++ it("does not infer private routing from a local hostname or arbitrary exception text", async () => {+ for (const origin of ["https://viewer.localhost", "https://viewer.internal", "https://169.254.169.254"]) {+ const result = await inspectViewerTransport(origin);+ expect(result.reachable).toBe(false); expect(result.clientOnly).not.toBe(true);+ }+ const result = await inspectViewerTransport("https://viewer.example", async () => {+ throw new Error("MSO_DEPLOYMENT_PRIVATE_ROUTE secret must not be reflected");+ });+ expect(result.clientOnly).not.toBe(true); expect(JSON.stringify(result)).not.toContain("secret");+ });diff --git a/lib/camoufox/viewer-transport.ts b/lib/camoufox/viewer-transport.tsindex 7f2c84f8..f3ad81e9 100644--- a/lib/camoufox/viewer-transport.ts+++ b/lib/camoufox/viewer-transport.ts@@ -1,10 +1,12 @@import "server-only";import { safeProviderFetch } from "@/lib/host/ssrf";import { camoufoxViewerOrigin } from "./origin";+import { PRIVATE_ROUTE_CODE } from "@/lib/host/provider-network-policy";export type ViewerTransport = {reachable: boolean;- state: "reachable" | "unconfigured" | "tls" | "dns" | "network" | "http";+ state: "reachable" | "unconfigured" | "tls" | "dns" | "network" | "http" | "client-only";+ clientOnly?: boolean;message: string;status?: number;};@@ -17,6 +19,10 @@ function failure(error: unknown): ViewerTransport {codes.push(String(row.code ?? ""), String(row.name ?? "")); value = row.cause;}const code = codes.join(" ");+ if (codes.includes(PRIVATE_ROUTE_CODE)) return {+ reachable: false, state: "client-only", clientOnly: true,+ message: "The server did not access this deployment-owned private route. The client browser must validate its HTTPS, authentication and viewer connection.",+ };if (/TLS|SSL|CERT|SELF_SIGNED|UNABLE_TO_VERIFY/i.test(code)) return {reachable: false, state: "tls",message: "The browser is running, but its separate HTTPS viewer failed TLS validation. Check certificate coverage for the exact viewer hostname; restarting the browser will not repair TLS.",diff --git a/lib/host/provider-network-policy.test.ts b/lib/host/provider-network-policy.test.tsnew file mode 100644index 00000000..6393380c--- /dev/null+++ b/lib/host/provider-network-policy.test.ts@@ -0,0 +1,15 @@+import { describe, expect, it } from "vitest";+import { isDeploymentPrivateAddress, PRIVATE_ROUTE_CODE, providerNetworkRefusal } from "./provider-network-policy";++describe("private-route refusal classification does not grant network access", () => {+ it.each(["10.0.0.0", "10.255.255.255", "172.16.0.0", "172.31.255.255", "192.168.0.0", "192.168.255.255", "100.64.0.0", "100.127.255.255", "fc00::1", "fd7a:115c:a1e0::4"])("classifies private address %s", address => {+ expect(isDeploymentPrivateAddress(address)).toBe(true);+ });+ it.each(["127.0.0.1", "169.254.169.254", "0.0.0.0", "172.15.255.255", "172.32.0.0", "100.63.255.255", "100.128.0.0", "192.169.0.1", "192.0.2.1", "224.0.0.1", "::1", "::", "fe80::1", "ff02::1", "2001:db8::1", "invalid"])("does not label %s a private deployment route", address => {+ expect(isDeploymentPrivateAddress(address)).toBe(false);+ });+ it("adds a typed hint without changing the thrown refusal message", () => {+ expect(providerNetworkRefusal("denied", true)).toMatchObject({ message: "denied", code: PRIVATE_ROUTE_CODE });+ expect(providerNetworkRefusal("denied")).toMatchObject({ message: "denied", code: "MSO_FORBIDDEN_PROVIDER_ENDPOINT" });+ });+});diff --git a/lib/host/provider-network-policy.ts b/lib/host/provider-network-policy.tsnew file mode 100644index 00000000..12324cbf--- /dev/null+++ b/lib/host/provider-network-policy.ts@@ -0,0 +1,15 @@+import { isIP } from "node:net";++// This code classifies a refusal; it never grants a server-side network request.+export const PRIVATE_ROUTE_CODE = "MSO_DEPLOYMENT_PRIVATE_ROUTE";+export function isDeploymentPrivateAddress(address: string): boolean {+ if (isIP(address) === 4) {+ const [a, b] = address.split(".").map(Number);+ return a === 10 || (a === 172 && b >= 16 && b <= 31) ||+ (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127);+ }+ return isIP(address) === 6 && /^f[cd][0-9a-f]{2}:/i.test(address);+}+export function providerNetworkRefusal(message: string, privateRoute = false): Error {+ return Object.assign(new Error(message), { code: privateRoute ? PRIVATE_ROUTE_CODE : "MSO_FORBIDDEN_PROVIDER_ENDPOINT" });+}diff --git a/lib/host/ssrf.ts b/lib/host/ssrf.tsindex 45c655b0..3dd969ec 100644--- a/lib/host/ssrf.ts+++ b/lib/host/ssrf.ts@@ -1,3 +1,4 @@+import { isDeploymentPrivateAddress, providerNetworkRefusal } from "./provider-network-policy";import { lookup as dnsLookup } from "node:dns/promises";import { request as httpRequest } from "node:http";import { request as httpsRequest } from "node:https";@@ -120,10 +121,10 @@ export function assertSafeUrl(raw: string): URL {if (url.hash) throw new Error("Base URL must not contain a fragment");const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");if (!host || host === "localhost" || host === "0.0.0.0" || FORBIDDEN_HOST_SUFFIXES.some((suffix) => host.endsWith(suffix))) {- throw new Error("Base URL host not allowed (private / loopback / link-local / metadata)");+ throw providerNetworkRefusal("Base URL host not allowed (private / loopback / link-local / metadata)");}if (isIP(host) && isForbiddenProviderAddress(host)) {- throw new Error("Base URL host not allowed (private / loopback / link-local / metadata)");+ throw providerNetworkRefusal("Base URL host not allowed (private / loopback / link-local / metadata)", isDeploymentPrivateAddress(host));}return url;}@@ -140,7 +141,7 @@ export async function resolveSafeProviderEndpoint(: await resolver(host, { all: true, verbatim: true });if (!resolved.length) throw new Error("Base URL host did not resolve");if (resolved.some((entry) => isForbiddenProviderAddress(entry.address))) {- throw new Error("Base URL DNS resolved to a private / loopback / link-local / metadata address");+ throw providerNetworkRefusal("Base URL DNS resolved to a private / loopback / link-local / metadata address", resolved.every(entry => isDeploymentPrivateAddress(entry.address)));}const first = resolved[0];if (first.family !== 4 && first.family !== 6) throw new Error("Base URL resolved to an unsupported address family");diff --git a/scripts/e2e/camoufox-connection.mjs b/scripts/e2e/camoufox-connection.mjsindex f385f50a..d7f7cee1 100644--- a/scripts/e2e/camoufox-connection.mjs+++ b/scripts/e2e/camoufox-connection.mjs@@ -11,17 +11,23 @@ export async function camoufoxConnectionJourney(page, fixture) {return route.fulfill({ status: 503, json: { error: "Power mutation is forbidden in connection-only retry" } });}if (url.searchParams.get("probe") === "viewer") return route.fulfill({- status: 200, json: { reachable: false, state: "tls", message: "Fixture viewer TLS failed" },+ status: 200, json: mode === "private"+ ? { reachable: false, state: "client-only", clientOnly: true, message: "Client must verify the private deployment viewer" }+ : { reachable: false, state: "tls", message: "Fixture viewer TLS failed" },});reads++;- const running = mode === "tls" || reads === 1;- return route.fulfill({ status: 200, json: { installed: true, running, enabled: false, viewerReady: mode === "tls" } });+ const running = mode !== "stopping" || reads === 1;+ return route.fulfill({ status: 200, json: { installed: true, running, enabled: false, viewerReady: mode !== "stopping" } });};+ const session = route => route.fulfill({ status: 200, json: { password: null } });+ const viewer = route => route.fulfill({ status: 200, contentType: "text/html", body: "<!doctype html><title>Private fixture viewer</title><p>Client-only viewer fixture</p>" });page.on("request", observe);+ await page.route("**/api/v1/camoufox/session", session);+ await page.route("**/vnc.html?*", viewer);await page.route("**/api/v1/camoufox/service*", service);try {for (const viewport of [{ width: 1280, height: 900 }, { width: 390, height: 844 }]) {- mode = "tls"; reads = 0;+ mode = "tls"; reads = 0; const beforeCredentials = credentials;await page.setViewportSize(viewport);await page.goto(fixture.base + "/browser");const retry = page.getByRole("button", { name: "Retry connection", exact: true });@@ -33,17 +39,25 @@ export async function camoufoxConnectionJourney(page, fixture) {await expect(retry).toBeEnabled();await expect(connectionAlert).toContainText("Fixture viewer TLS failed");}- expect(posts).toBe(0); expect(credentials).toBe(0);- mode = "stopping"; reads = 0;+ expect(posts).toBe(0); expect(credentials).toBe(beforeCredentials);+ mode = "private"; reads = 0;await retry.click();+ const frame = page.locator('iframe[title="Camoufox browser"]');+ await expect(frame).toBeVisible();+ await expect(page.frameLocator('iframe[title="Camoufox browser"]').getByText("Client-only viewer fixture")).toBeVisible();+ expect(credentials).toBe(beforeCredentials + 1); expect(posts).toBe(0);+ mode = "stopping"; reads = 0;+ await page.goto(fixture.base + "/browser");await expect(page.getByText("The browser session is off.", { exact: true })).toBeVisible();await expect(page.getByRole("button", { name: "Turn the browser on", exact: true })).toBeVisible();await expect(page.getByText("Running on the server", { exact: true })).toHaveCount(0);expect(posts).toBe(0); expect(reads).toBe(2);}- console.log("PASS Camoufox read-only retries, no premature credential fetch, and observed session stop on desktop/mobile");+ console.log("PASS Camoufox read-only retries, client-only private viewer mounting, no premature credentials, and observed stop on desktop/mobile");} finally {page.off("request", observe);+ await page.unroute("**/api/v1/camoufox/session", session);+ await page.unroute("**/vnc.html?*", viewer);await page.unroute("**/api/v1/camoufox/service*", service);}}