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): 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.ts
new file mode 100644
index 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.ts
index 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.md
index 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.md
index 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 candidate
The continuation preserved the pending cooldown and lock-fixture fixes and reconciled
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 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.tsx
index 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 ? (
<iframe
src={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.ts
new file mode 100644
index 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.tsx
index 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. Your
logins, history and open tabs are kept on the server&apos;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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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;