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): diagnose secure viewer failures without losing power state
Rahman6d8eed4d7702
diff --git a/app/api/v1/camoufox/service/route.test.ts b/app/api/v1/camoufox/service/route.test.tsnew file mode 100644index 00000000..a9a148e6--- /dev/null+++ b/app/api/v1/camoufox/service/route.test.ts@@ -0,0 +1,32 @@+import { beforeEach, expect, it, vi } from "vitest";+const mocks = vi.hoisted(() => ({ auth: vi.fn(), probe: vi.fn(), status: vi.fn(), limit: vi.fn() }));+vi.mock("@/lib/agent/server", () => ({ verifyAuth: mocks.auth }));+vi.mock("@/lib/camoufox/viewer-transport", () => ({ probeViewerTransport: mocks.probe }));+vi.mock("@/lib/camoufox/service", () => ({ camoufoxStatus: mocks.status, setCamoufoxEnabled: vi.fn() }));+vi.mock("@/lib/host/request-api", () => ({ apiError: vi.fn(), readJson: vi.fn() }));+vi.mock("@/lib/host/audit-api", () => ({ audit: vi.fn() }));+vi.mock("@/lib/host/limits-api", () => ({ rateLimited: mocks.limit }));+import { GET } from "./route";+beforeEach(() => { vi.clearAllMocks(); mocks.auth.mockResolvedValue(true); mocks.limit.mockReturnValue(false); });+it("does not probe any network target before authorization", async () => {+ mocks.auth.mockResolvedValue(false);+ expect((await GET(new Request("https://mso.example.com/api/v1/camoufox/service?probe=viewer"))).status).toBe(401);+ expect(mocks.probe).not.toHaveBeenCalled(); expect(mocks.status).not.toHaveBeenCalled();+});+it("returns uncached public-transport metadata only on explicit inspection", async () => {+ mocks.probe.mockResolvedValue({ reachable: false, state: "tls", message: "TLS validation failed" });+ const response = await GET(new Request("https://mso.example.com/api/v1/camoufox/service?probe=viewer"));+ expect(response.headers.get("cache-control")).toBe("no-store");+ expect(await response.json()).toMatchObject({ reachable: false, state: "tls" });+ expect(mocks.status).not.toHaveBeenCalled();+});+it("bounds repeated explicit probes", async () => {+ mocks.limit.mockReturnValue(true);+ expect((await GET(new Request("https://mso.example.com/api/v1/camoufox/service?probe=viewer"))).status).toBe(429);+ expect(mocks.probe).not.toHaveBeenCalled();+});+it("keeps ordinary power-status requests local", async () => {+ mocks.status.mockResolvedValue({ running: true, viewerReady: true });+ expect(await (await GET(new Request("https://mso.example.com/api/v1/camoufox/service"))).json()).toMatchObject({ running: true });+ expect(mocks.probe).not.toHaveBeenCalled();+});diff --git a/app/api/v1/camoufox/service/route.ts b/app/api/v1/camoufox/service/route.tsindex e77b64a6..d53c50c5 100644--- a/app/api/v1/camoufox/service/route.ts+++ b/app/api/v1/camoufox/service/route.ts@@ -2,6 +2,7 @@ import { NextResponse } from "next/server";import { verifyAuth } from "@/lib/agent/server";import { camoufoxStatus, setCamoufoxEnabled } from "@/lib/camoufox/service";import { apiError, readJson } from "@/lib/host/request-api";+import { probeViewerTransport } from "@/lib/camoufox/viewer-transport";import { audit } from "@/lib/host/audit-api";import { rateLimited } from "@/lib/host/limits-api";@@ -16,6 +17,10 @@ export const dynamic = "force-dynamic";export async function GET(req: Request) {if (!(await verifyAuth(req))) return NextResponse.json({ error: "unauthorized" }, { status: 401 });try {+ if (new URL(req.url).searchParams.get("probe") === "viewer") {+ if (rateLimited("camoufox.viewer-probe", 30, 60_000)) return NextResponse.json({ error: "too many viewer probes" }, { status: 429 });+ return NextResponse.json(await probeViewerTransport(), { headers: { "Cache-Control": "no-store" } });+ }return NextResponse.json(await camoufoxStatus());} catch (e) {return apiError("camoufox/service", e);diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex dce50355..16d2583c 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -4,6 +4,12 @@Newest first. `docs/PROGRESS.md` is the source of truth for *why* a change was made;this is the *what*, and it is what Settings → About shows as “What's new”.+## 2026-09-18++**Fixed**++- `browser` diagnose secure viewer failures without losing power state+## 2026-09-17**Added**diff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 3e90c958..b4bdbe61 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -1,3 +1,19 @@+## 2026-09-18 — Separate Camoufox process health from secure viewer reachability++A running user service and loopback noVNC response did not prove the separate public+viewer could negotiate TLS. The Browser app now requests an authenticated, rate-limited+transport diagnosis before fetching its VNC credential. The probe uses the existing+public-address/DNS-pinned transport, no credentials, no redirects, a bounded wait and+short in-flight cache. Anonymous denial is recorded only as HTTPS transport evidence,+never as proof of authenticated VNC access. TLS, DNS and upstream failures are readable.+Connection failures preserve the service's real running state and expose retry rather+than an endless spinner. Power help now acknowledges deployment-configured session limits.++Native GitHub verification now displays the validated account login from the official+user endpoint, while still explicitly declining to claim repository permissions. An+MSO profile label is not a GitHub account identity. Unexpected payloads and credential+reflections never enter the account label; no connection, token or account is replaced.+## 2026-09-17 — Reconcile dependency PRs as one tested release candidateThe continuation preserved the pending cooldown and lock-fixture fixes and reconcileddiff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex 3f45023d..22423e5e 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -452,3 +452,29 @@ continue with the returned cursor instead of concluding absence.- managed apps: `docs/MANAGED-APPS.md`- Camoufox: `claude-skills/mso-camoufox/SKILL.md`- security: `SECURITY.md`++## Camoufox is running but its viewer is blank++Check each boundary separately. `mso api GET /api/v1/camoufox/service` reports the+user service and loopback viewer; `mso api GET '/api/v1/camoufox/service?probe=viewer'`+checks public HTTPS transport through the authenticated API. The second operation+never forwards session cookies or VNC passwords and does not authenticate a VNC client.+A TLS failure must be fixed at the exact viewer hostname, certificate and reverse-proxy+route; repeatedly starting an already running browser cannot fix it. Keep the viewer+on its isolated origin, retain live Operator/Owner authorization, and never expose a+bare noVNC listener or disable certificate verification as a workaround.++A certificate for `*.example.com` does not cover `camoufox.mso.example.com`.+Check the edge provider's coverage independently from the origin certificate.+For Cloudflare full-setup Universal SSL, see its [hostname coverage limits](https://developers.cloudflare.com/ssl/edge-certificates/universal-ssl/limitations/).+DNS-only routing requires a publicly trusted origin certificate and the intended+origin route; changing the record also changes which edge protections apply.++The browser session may stop at its configured service time limit. A failed transport+probe is not a stopped process. Verify actual navigation independently using an isolated+profile before attributing a saved-profile failure to the browser binary. Preserve+saved logins and profile data; a passing clean-profile test is not a repaired saved profile.++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.diff --git a/frontend/slices/camoufox-browser/app.tsx b/frontend/slices/camoufox-browser/app.tsxindex 23643565..25b012fb 100644--- a/frontend/slices/camoufox-browser/app.tsx+++ b/frontend/slices/camoufox-browser/app.tsx@@ -4,7 +4,7 @@ import { useCallback, useEffect, useRef, useState } from "react";import { Loader2, Power, ScanEye } from "lucide-react";import { IS_DEMO } from "@/lib/demo";import { PowerPanel } from "./power-panel";-import { fetchStatus, setPower, waitForViewer, type CamoufoxServiceStatus } from "./service-client";+import { fetchStatus, setPower, waitForViewer, verifyViewerTransport, type CamoufoxServiceStatus } from "./service-client";import { camoufoxViewerOrigin } from "@/lib/camoufox/origin";// A REAL Firefox (Camoufox, anti-fingerprinting) running on a headless X display on@@ -78,7 +78,13 @@ export default function CamoufoxBrowser() {if (signal.aborted) return;if (!ready) {setError("The browser session started but is not answering. Check its logs on the host.");- setStatus((current) => (current ? { ...current, running: false } : current));+ setSrc(null); // A failed connection must not falsify the host power state.+ return;+ }+ try { await verifyViewerTransport(signal); }+ catch (cause) {+ if (!signal.aborted) setError(cause instanceof Error ? cause.message : "The secure viewer is unavailable");+ setSrc(null);return;}const source = await viewerSrc();@@ -182,7 +188,9 @@ export default function CamoufoxBrowser() {{busy ? "Working…" : "Turn off"}</button></header>- {error && <p className="shrink-0 bg-destructive/10 px-3 py-1.5 text-[11px] text-destructive">{error}</p>}+ {error && <div role="alert" className="shrink-0 bg-destructive/10 px-3 py-2 text-[11px] text-destructive">+ <p>{error}</p><button type="button" disabled={busy} className="mt-2 underline" onClick={() => void power(true)}>Retry connection</button>+ </div>}{src ? (<iframesrc={src}@@ -193,11 +201,11 @@ export default function CamoufoxBrowser() {referrerPolicy="no-referrer"allowFullScreen/>- ) : (+ ) : !error ? (<div className="flex min-h-0 w-full flex-1 items-center justify-center gap-2 bg-black text-xs text-white/60"><Loader2 className="size-4 animate-spin" /> Connecting to the browser session…</div>- )}+ ) : null}</div>);}diff --git a/frontend/slices/camoufox-browser/connection-state.test.ts b/frontend/slices/camoufox-browser/connection-state.test.tsnew file mode 100644index 00000000..93a108a1--- /dev/null+++ b/frontend/slices/camoufox-browser/connection-state.test.ts@@ -0,0 +1,9 @@+import { readFileSync } from "node:fs";+import { expect, it } from "vitest";+it("keeps power truth and offers retry instead of an endless failed spinner", () => {+ const source = readFileSync(new URL("./app.tsx", import.meta.url), "utf8");+ expect(source).toContain("await verifyViewerTransport(signal)");+ expect(source).not.toContain("...current, running: false");+ expect(source).toContain("Retry connection");+ expect(source).toContain(") : !error ? (");+});diff --git a/frontend/slices/camoufox-browser/power-panel.tsx b/frontend/slices/camoufox-browser/power-panel.tsxindex cf2a7985..984318c9 100644--- a/frontend/slices/camoufox-browser/power-panel.tsx+++ b/frontend/slices/camoufox-browser/power-panel.tsx@@ -45,7 +45,7 @@ export function PowerPanel({{busy ? "Starting the browser…" : "Turn the browser on"}</Button><p className="text-[10px] text-muted-foreground">- Takes a few seconds. It runs until you switch it off here, and stays off after a reboot. Your+ Takes a few seconds. It may also stop at the server’s configured session limit, and stays off after a reboot. Yourlogins, history and open tabs are kept on the server's disk and come back next time.</p>{error && <Failure message={error} />}diff --git a/frontend/slices/camoufox-browser/service-client.test.ts b/frontend/slices/camoufox-browser/service-client.test.tsindex cda3c862..157703c6 100644--- a/frontend/slices/camoufox-browser/service-client.test.ts+++ b/frontend/slices/camoufox-browser/service-client.test.ts@@ -21,3 +21,11 @@ describe("Camoufox viewer readiness", () => {await expect(waitForViewer(new AbortController().signal, 0)).resolves.toBe(false);});});++it("surfaces public TLS failure without changing the process state", async () => {+ const { verifyViewerTransport } = await import("./service-client");+ const fetchMock = vi.fn(async () => new Response(JSON.stringify({ reachable: false, state: "tls", message: "Viewer TLS failed" }), { status: 200 }));+ vi.stubGlobal("fetch", fetchMock);+ await expect(verifyViewerTransport(new AbortController().signal)).rejects.toThrow("Viewer TLS failed");+ expect(fetchMock).toHaveBeenCalledWith("/api/v1/camoufox/service?probe=viewer", expect.objectContaining({ cache: "no-store" }));+});diff --git a/frontend/slices/camoufox-browser/service-client.ts b/frontend/slices/camoufox-browser/service-client.tsindex 9565adcb..22bfbd01 100644--- a/frontend/slices/camoufox-browser/service-client.ts+++ b/frontend/slices/camoufox-browser/service-client.ts@@ -47,3 +47,10 @@ export async function waitForViewer(signal: AbortSignal, timeoutMs = 30_000): Pr}return false;}++/** 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");+}diff --git a/lib/camoufox/viewer-transport.test.ts b/lib/camoufox/viewer-transport.test.tsnew file mode 100644index 00000000..77640261--- /dev/null+++ b/lib/camoufox/viewer-transport.test.ts@@ -0,0 +1,34 @@+import { describe, expect, it, vi } from "vitest";+vi.mock("server-only", () => ({}));+import { inspectViewerTransport } from "./viewer-transport";++describe("Camoufox public transport is separate from power", () => {+ it("does not probe an absent origin", async () => {+ const fetcher = vi.fn();+ expect(await inspectViewerTransport(null, fetcher)).toMatchObject({ reachable: false, state: "unconfigured" });+ expect(fetcher).not.toHaveBeenCalled();+ });+ it.each([200, 401, 403, 404])("accepts HTTP %s only as transport evidence without credentials", async status => {+ const fetcher = vi.fn(async () => new Response(null, { status }));+ expect(await inspectViewerTransport("https://camoufox.example.com", fetcher)).toMatchObject({ reachable: true, status });+ const [target, init] = fetcher.mock.calls[0] as unknown as [URL, RequestInit];+ expect(target.href).toBe("https://camoufox.example.com/vnc.html");+ expect(init).toMatchObject({ method: "HEAD", redirect: "error", cache: "no-store" });+ expect(init.headers).toBeUndefined();+ });+ it.each([302, 500, 502])("does not follow or accept HTTP %s", async status => {+ expect(await inspectViewerTransport("https://camoufox.example.com", async () => new Response(null, { status }))).toMatchObject({ reachable: false, state: "http" });+ });+ it("reports nested TLS errors without leaking raw exception text", async () => {+ const fetcher = vi.fn(async () => { throw new Error("secret-value", { cause: { code: "ERR_SSL_SSLV3_ALERT_HANDSHAKE_FAILURE" } }); });+ const result = await inspectViewerTransport("https://camoufox.example.com", fetcher);+ expect(result).toMatchObject({ reachable: false, state: "tls" });+ expect(JSON.stringify(result)).not.toContain("secret-value");+ });+ it("distinguishes DNS failure", async () => {+ expect(await inspectViewerTransport("https://camoufox.example.com", async () => { throw { code: "ENOTFOUND" }; })).toMatchObject({ state: "dns" });+ });+ it.each(["http://example.com", "https://user:[email protected]", "https://example.com/path"])('refuses malformed origin %s before a request', async origin => {+ const fetcher = vi.fn(); await inspectViewerTransport(origin, fetcher); expect(fetcher).not.toHaveBeenCalled();+ });+});diff --git a/lib/camoufox/viewer-transport.ts b/lib/camoufox/viewer-transport.tsnew file mode 100644index 00000000..7f2c84f8--- /dev/null+++ b/lib/camoufox/viewer-transport.ts@@ -0,0 +1,63 @@+import "server-only";+import { safeProviderFetch } from "@/lib/host/ssrf";+import { camoufoxViewerOrigin } from "./origin";++export type ViewerTransport = {+ reachable: boolean;+ state: "reachable" | "unconfigured" | "tls" | "dns" | "network" | "http";+ message: string;+ status?: number;+};++function failure(error: unknown): ViewerTransport {+ const codes: string[] = [];+ let value = error;+ for (let i = 0; i < 4 && value && typeof value === "object"; i++) {+ const row = value as { code?: unknown; name?: unknown; cause?: unknown };+ codes.push(String(row.code ?? ""), String(row.name ?? "")); value = row.cause;+ }+ const code = codes.join(" ");+ 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.",+ };+ if (/ENOTFOUND|EAI_AGAIN/.test(code)) return {+ reachable: false, state: "dns", message: "The viewer hostname could not resolve. Check its DNS record before reconnecting.",+ };+ return { reachable: false, state: "network", message: "The separate HTTPS viewer could not be reached. Check its proxy route, DNS and certificate; the local browser has not been stopped." };+}++/** No cookies/passwords, no redirects, public DNS pinned by the existing SSRF guard.+ * Reachable means transport only: authentication and the VNC handshake are separate. */+export async function inspectViewerTransport(origin: string | null, fetcher = safeProviderFetch): Promise<ViewerTransport> {+ if (!origin) return { reachable: false, state: "unconfigured", message: "Configure the separate browser viewer hostname before connecting." };+ try {+ const url = new URL(origin);+ if (url.protocol !== "https:" || url.username || url.password || url.origin !== origin) throw new Error("Invalid viewer origin");+ url.pathname = "/vnc.html";+ const signal = AbortSignal.timeout(4_000);+ let timer: ReturnType<typeof setTimeout> | undefined;+ try {+ const response = await Promise.race([+ fetcher(url, { method: "HEAD", redirect: "error", cache: "no-store", signal }),+ new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error("Viewer probe timed out")), 4_500); }),+ ]);+ await response.body?.cancel().catch(() => undefined);+ // Private viewers refuse anonymous requests. Do not forward cockpit credentials.+ if (response.ok || [401, 403, 404].includes(response.status)) return {+ reachable: true, state: "reachable", status: response.status,+ message: "HTTPS answered. Browser authentication and the VNC handshake still require client verification.",+ };+ return { reachable: false, state: "http", status: response.status, message: "The viewer proxy returned an unexpected HTTP response. Check the exact hostname route before reconnecting." };+ } finally { if (timer) clearTimeout(timer); }+ } catch (error) { return failure(error); }+}++let cached: { origin: string | null; expires: number; result: Promise<ViewerTransport> } | undefined;+export function probeViewerTransport(): Promise<ViewerTransport> {+ const origin = camoufoxViewerOrigin();+ if (cached?.origin === origin && cached.expires > Date.now()) return cached.result;+ const result = inspectViewerTransport(origin);+ cached = { origin, result, expires: Date.now() + 10_000 };+ return result;+}diff --git a/lib/infra/additional-doctor.test.ts b/lib/infra/additional-doctor.test.tsindex 1412878e..476c1929 100644--- a/lib/infra/additional-doctor.test.ts+++ b/lib/infra/additional-doctor.test.ts@@ -98,3 +98,15 @@ describe("additional native credential providers", () => {expect(JSON.stringify(summarizeInfraProvider("doku", { mcpClientId: "BRN-synthetic", mcpApiKey: KEY, environment: "sandbox" }))).not.toContain(KEY);});});++it("shows the verified GitHub login without claiming repository access", async () => {+ vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ login: "account-other", email: "[email protected]", extra: KEY }), { status: 200 })));+ const result = await doctorAdditionalProvider("github", { apiKey: KEY });+ expect(result).toBe("authenticated as account-other; repository scope not verified");+ expect(result).not.toContain(KEY); expect(result).not.toContain("[email protected]");+});+it("does not echo malformed or reflected account identity", async () => {+ vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ login: KEY }), { status: 200 })));+ const result = await doctorAdditionalProvider("github", { apiKey: KEY });+ expect(result).toContain("account identity unavailable"); expect(result).not.toContain(KEY);+});diff --git a/lib/infra/additional-doctor.ts b/lib/infra/additional-doctor.tsindex 5ec1c57d..19b7fb6f 100644--- a/lib/infra/additional-doctor.ts+++ b/lib/infra/additional-doctor.ts@@ -77,7 +77,7 @@ export async function doctorAdditionalProvider(id: string, values: Record<string}case "github": {if (!present(values.apiKey)) return null;- await checked("GitHub", "https://api.github.com/user", {+ const response = await checked("GitHub", "https://api.github.com/user", {authorization: `Bearer ${values.apiKey}`,accept: "application/vnd.github+json","user-agent": "MSO-integration-doctor",@@ -85,7 +85,10 @@ export async function doctorAdditionalProvider(id: string, values: Record<string});// request intentionally does not return response headers. Therefore this// doctor never claims repo scope: authentication is all it can prove here.- return "authenticated; repository scope not verified";+ const login = obj(response.body).login;+ const account = typeof login === "string" && /^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?$/i.test(login) && login !== values.apiKey+ ? ` as ${login}` : " (account identity unavailable)";+ return `authenticated${account}; repository scope not verified`;}case "vercel": {if (!present(values.apiKey)) return null;