Skip to content

armgit / mso

Public Imported from GitHub
0

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.

fix(browser): retain private viewer connectivity without server access

Rahman7b82b6fd7f84
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 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 retries
The dependency toolchain now requires the same supported Node range everywhere:
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 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 sa
For GitHub connection diagnosis, compare the returned authenticated login with the intended
account, 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.mjs
index 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);
}
}