feat(server): authenticated remote dashboard listener with origin-scoped sessions

docs-site/src/content/docs/guides/web-dashboard.md

@@ -30,9 +30,59 @@ the admin token (`OPENCODEX_ADMIN_AUTH_TOKEN`, or the auto-generated
 `~/.opencodex/admin-api-token` file).
 
 When a remote dashboard needs that credential, it presents a standard password form so a browser
-password manager can offer to save and autofill it. The dashboard itself still keeps the token only
-in memory and does not write it to `localStorage` or `sessionStorage`; whether it is saved is entirely
-the browser or password manager's decision.
+password manager can offer to save and autofill it. The raw admin token stays only in memory; after
+sign-in, the dashboard stores a separate opaque session for that exact browser origin.
+
+## Remote dashboard access (Tailscale)
+
+opencodex can serve the dashboard to another device — a phone, a second computer — without opening
+the proxy itself to the network. The opt-in `dashboardListener` config key opens a second listener
+that serves only the dashboard: the web app and the `/api/*` management API. The loopback-only
+`/opencodex-session` bootstrap is not part of this remote surface.
+
+```json
+{
+  "dashboardListener": {
+    "enabled": true,
+    "port": 10101,
+    "hostname": "100.88.9.100"
+  }
+}
+```
+
+`hostname` is required and must be a literal private address: RFC1918 IPv4, Tailscale CGNAT
+(`100.64.0.0/10`), or IPv6 ULA (`fc00::/7`). The typical choice is the machine's Tailscale IP,
+making the dashboard reachable at `http://100.88.9.100:10101` from anywhere on your tailnet.
+Wildcard, loopback, public, and DNS addresses are rejected. The key is absent by default, and
+`{ "enabled": false }` is also accepted. The `port` must differ from the proxy port and from
+`unauthenticatedLoopbackListener`'s port — a collision is rejected when the config is written.
+
+The main proxy listener is completely unchanged: it stays on `127.0.0.1`, and Codex and every other
+client keep pointing at the original proxy port. Nothing about provider or API-key mode changes.
+
+Every data-plane route is refused on this listener: `/v1/*` (Responses, Chat Completions, models,
+Messages, Realtime/live), data-plane WebSocket upgrades, and `/readyz` all return `404`. `GET /healthz` is served because the dashboard itself polls it; it returns the standard health payload — service name, version, uptime, pid, port, and restart/provider-reload capability flags — operational metadata only, with no credentials or provider data.
+
+### Sign-in on the remote dashboard
+
+Management calls on this listener require the existing admin token (`OPENCODEX_ADMIN_AUTH_TOKEN` or
+the generated `~/.opencodex/admin-api-token` file) — the same credential as the local dashboard.
+After sign-in the dashboard exchanges the token for a 12-hour opaque session automatically.
+`POST /api/auth/session` receives the admin token in `X-OpenCodex-API-Key` and returns the opaque
+session, CSRF token, bound origin, and expiry. The browser stores that separate session only for the
+exact scheme, host, and port; it never stores the raw admin token. Mutations additionally require the
+per-session CSRF token. The phone therefore asks for the admin token once per 12 hours instead of on
+every refresh.
+
+Loopback dashboard behavior is unchanged: the local dashboard keeps auto-minting its 5-minute
+sessions into the served page.
+
+:::caution[Keep it on the tailnet]
+The bind hostname is limited to a private or tailnet address; Tailscale is the recommended setup.
+This feature does not add TLS, so use it only over a trusted private transport such as a
+WireGuard-encrypted tailnet. The persistent opaque session is readable by JavaScript at that exact
+origin, so keep the dashboard free of untrusted scripts and do not expose it on an untrusted network.
+:::
 
 ## What you can do
 

docs-site/src/content/docs/reference/configuration/server.md

@@ -12,6 +12,7 @@ runs helper features around provider requests.
 | --- | --- | --- | --- |
 | `port` | `number` | `10100` | Proxy listen port. |
 | `hostname?` | `string` | `"127.0.0.1"` | Bind address. Non-loopback binds require `OPENCODEX_API_AUTH_TOKEN`. |
+| `dashboardListener?` | `{ enabled?: boolean; port: number; hostname: string }` | off | Opt-in second listener serving only the dashboard and `/api/*` on a private/tailnet address. The main proxy listener is unchanged. See [Remote dashboard access](/guides/web-dashboard/#remote-dashboard-access-tailscale). |
 | `proxy?` | `string` | — | Outbound HTTP(S) proxy URL or `${ENV_VAR}`. Applied to `HTTP_PROXY` / `HTTPS_PROXY` only when those variables are unset; loopback remains in `NO_PROXY`. |
 | `noProxy?` | `string \| string[]` | — | Hosts that bypass `proxy`, merged with inherited `NO_PROXY` and loopback entries. A string may use comma-separated `NO_PROXY` syntax or `${ENV_VAR}`. |
 | `emptyCompletionRetry?` | `boolean` | `false` | Opt in to one identical Responses retry when a turn has no text or tool call, including a stream that ends before a terminal event. The retry may be billable. `OCX_EMPTY_COMPLETION_RETRY=0` disables it without changing config; combo and routed-compaction turns remain excluded. |
@@ -125,6 +126,46 @@ a page you visit can make your browser connect to `127.0.0.1`. The listener ther
 same `Host` and `Origin` checks as an ordinary loopback bind. Off by default.
 :::
 
+### Remote dashboard listener
+
+`dashboardListener` opens a second listener that serves only the dashboard: the web app and the
+`/api/*` management API. The loopback-only `/opencodex-session` bootstrap is not part of this
+remote surface. The main proxy listener — and
+its `hostname` and `port` — are completely unchanged; Codex and every other client keep using the
+original `127.0.0.1` address exactly as before.
+
+```json
+{
+  "dashboardListener": {
+    "enabled": true,
+    "port": 10101,
+    "hostname": "100.88.9.100"
+  }
+}
+```
+
+`hostname` is required when the listener is enabled and must be a literal private address: RFC1918
+IPv4, Tailscale CGNAT (`100.64.0.0/10`), or IPv6 ULA (`fc00::/7`). Typically this is the machine's
+Tailscale IP (`100.x.y.z`). Wildcard, loopback, public, and DNS addresses are rejected. The key is
+absent by default; an `{ "enabled": false }` shape is also accepted. `port` must differ from the
+proxy `port` and from `unauthenticatedLoopbackListener`'s port; a collision is a write-time
+validation error.
+
+Every data-plane route is refused on this listener: `/v1/*` (Responses, Chat Completions, models,
+Messages, Realtime/live), data-plane WebSocket upgrades, and `/readyz` all return `404`. `GET /healthz` is served because the dashboard itself polls it; it returns the standard health payload — service name, version, uptime, pid, port, and restart/provider-reload capability flags — operational metadata only, with no credentials or provider data.
+Management calls still require the existing admin token (`OPENCODEX_ADMIN_AUTH_TOKEN` or the
+generated `~/.opencodex/admin-api-token` file) — the same credential the local dashboard uses. The
+bind address should be a private or tailnet address; see
+[Remote dashboard access (Tailscale)](/guides/web-dashboard/#remote-dashboard-access-tailscale).
+
+Only the dashboard listener exposes `POST /api/auth/session`. With the admin token in
+`X-OpenCodex-API-Key`, it mints a 12-hour opaque session carrying its CSRF token, exact bound origin,
+and expiry. The dashboard stores that session only at the exact browser origin; it never persists the
+raw admin token. `GET /api/auth/session` is not supported, and the proxy and unauthenticated loopback
+listeners return `404` for this endpoint. This feature does not add TLS: use the allowed private bind
+only through a trusted transport such as Tailscale, and keep the dashboard free of untrusted scripts
+because that origin can read its opaque session.
+
 ### SSH port forwarding
 
 Remote use does not require a remote bind. Keep loopback and forward it:

gui/src/api.ts

@@ -25,6 +25,8 @@ let requestAdminToken: AdminTokenPrompt = promptForAdminToken;
 const SESSION_REBOOTSTRAP_PATH = "/opencodex-session";
 /** Safe authenticated read used to validate a raw admin token before closing the sign-in form. */
 const ADMIN_TOKEN_VALIDATION_PATH = "/api/settings";
+/** Remote-dashboard session endpoint: POST mints an opaque session from an admin token. */
+const AUTH_SESSION_PATH = "/api/auth/session";
 
 /**
  * The silent re-bootstrap must fail fast: every /api/* request queues behind the
@@ -63,24 +65,32 @@ function needsApiAuth(input: RequestInfo | URL): boolean {
 
 /** Legacy sessionStorage key from pre-memory auth — wiped once on install, never read. */
 const LEGACY_TOKEN_KEY = "opencodex-api-token";
+/** Persistent remote session: origin-scoped and opaque; never contains the raw admin token. */
+const PERSISTENT_GUI_SESSION_KEY = "opencodex-gui-session";
 
-/** In-memory only — never write tokens to web storage (XSS can read sessionStorage/localStorage). */
+/** The raw admin token stays memory-only. Remote GUI sessions are opaque and process-local. */
 let memoryToken: string | null = null;
 let memoryCsrfToken: string | null = null;
 let memorySessionOrigin: string | null = null;
+let memorySessionPersistent = false;
 
 function readToken(): string | null {
   return memoryToken;
 }
 
 function storeToken(token: string): void {
   memoryToken = token;
+  memoryCsrfToken = null;
+  memorySessionOrigin = null;
+  memorySessionPersistent = false;
 }
 
 function clearToken(): void {
+  if (memorySessionPersistent) clearPersistentGuiSession();
   memoryToken = null;
   memoryCsrfToken = null;
   memorySessionOrigin = null;
+  memorySessionPersistent = false;
 }
 
 function takeMetaContent(name: string): string | null {
@@ -108,9 +118,81 @@ function storeSession(token: string | null, csrfToken: string | null, origin: st
   memoryToken = token;
   memoryCsrfToken = csrfToken;
   memorySessionOrigin = origin;
+  memorySessionPersistent = false;
   return true;
 }
 
+function clearPersistentGuiSession(): void {
+  try {
+    localStorage.removeItem(PERSISTENT_GUI_SESSION_KEY);
+  } catch {
+    /* browser storage may be disabled */
+  }
+}
+
+function loadPersistentGuiSession(): void {
+  try {
+    const raw = localStorage.getItem(PERSISTENT_GUI_SESSION_KEY);
+    if (!raw) return;
+    const session = JSON.parse(raw) as { token?: unknown; csrfToken?: unknown; origin?: unknown; expiresAt?: unknown };
+    if (typeof session.expiresAt !== "number"
+      || !Number.isFinite(session.expiresAt)
+      || session.expiresAt <= Date.now()
+      || !storeSession(
+        typeof session.token === "string" ? session.token : null,
+        typeof session.csrfToken === "string" ? session.csrfToken : null,
+        typeof session.origin === "string" ? session.origin : null,
+      )) {
+      clearPersistentGuiSession();
+      return;
+    }
+    memorySessionPersistent = true;
+  } catch {
+    clearPersistentGuiSession();
+  }
+}
+
+function persistGuiSession(token: string, csrfToken: string, origin: string, expiresAt: number): void {
+  try {
+    localStorage.setItem(PERSISTENT_GUI_SESSION_KEY, JSON.stringify({ token, csrfToken, origin, expiresAt }));
+    memorySessionPersistent = true;
+  } catch {
+    /* storage is an enhancement; keep the current page session alive */
+  }
+}
+
+/** Mint an opaque session alongside a manually entered admin token for future page loads. */
+async function mintPersistentGuiSession(token: string): Promise<string | null> {
+  if (!rawFetch) return null;
+  const bounded = createBoundedFetch(rebootstrapTimeoutMs);
+  try {
+    const response = await rawFetch(AUTH_SESSION_PATH, {
+      method: "POST",
+      cache: "no-store",
+      signal: bounded.signal,
+      headers: { "X-OpenCodex-API-Key": token },
+    });
+    if (!response.ok) return null;
+    const session = await response.json().catch(() => null) as {
+      token?: unknown; csrfToken?: unknown; origin?: unknown; expiresAt?: unknown;
+    } | null;
+    if (!session
+      || typeof session.token !== "string"
+      || typeof session.csrfToken !== "string"
+      || typeof session.origin !== "string"
+      || typeof session.expiresAt !== "number"
+      || !Number.isFinite(session.expiresAt)
+      || session.expiresAt <= Date.now()
+      || !storeSession(session.token, session.csrfToken, session.origin)) return null;
+    persistGuiSession(session.token, session.csrfToken, session.origin, session.expiresAt);
+    return session.token;
+  } catch {
+    return null;
+  } finally {
+    bounded.clear();
+  }
+}
+
 /** Read one named meta tag out of a served HTML document (attribute order varies). */
 function metaContentFromHtml(html: string, name: string): string | null {
   for (const tag of html.match(/<meta\b[^>]*>/gi) ?? []) {
@@ -185,10 +267,14 @@ function clearLegacySessionToken(): void {
   }
 }
 
-function withToken(input: RequestInfo | URL, init: RequestInit | undefined, token: string): [RequestInfo | URL, RequestInit | undefined] {
+function withToken(input: RequestInfo | URL, init: RequestInit | undefined, token: string | null): [RequestInfo | URL, RequestInit | undefined] {
+  // Nothing to attach (no credential or opaque session) — pass through untouched.
+  if (!token && !(memorySessionOrigin && memoryCsrfToken)) return [input, init];
   const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
-  headers.set("X-OpenCodex-API-Key", token);
-  if (memorySessionOrigin && memoryCsrfToken && token.startsWith("ocx_session_")) {
+  if (token) headers.set("X-OpenCodex-API-Key", token);
+  // Opaque sessions carry the GUI binding headers; the server ignores them on the
+  // raw-admin-token header path.
+  if (memorySessionOrigin && memoryCsrfToken) {
     headers.set("X-OpenCodex-GUI-Origin", memorySessionOrigin);
     const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
     if (method !== "GET" && method !== "HEAD") {
@@ -234,7 +320,9 @@ async function resolveTokenAfter401(failedToken: string | null, callerSignal?: A
       const prompted = await requestAdminToken(verifyAdminToken);
       if (prompted) {
         storeToken(prompted);
-        return prompted;
+        // Bounded and fast; awaiting keeps the retry wave ordered after the mint.
+        // The raw token remains a current-page fallback if the remote session mint fails.
+        return await mintPersistentGuiSession(prompted) ?? prompted;
       }
       promptCancelled = true;
       return null;
@@ -270,12 +358,14 @@ export function installApiAuthFetch(): void {
   loadInjectedSession();
   const originalFetch = window.fetch.bind(window);
   rawFetch = originalFetch;
+  // Remote dashboards restore only an opaque session scoped to this exact browser origin.
+  if (readToken() === null) loadPersistentGuiSession();
   window.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
     if (!needsApiAuth(input)) return originalFetch(input, init);
 
     const callerSignal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
     const token = readToken();
-    const [firstInput, firstInit] = token ? withToken(input, init, token) : [input, init];
+    const [firstInput, firstInit] = withToken(input, init, token);
     const response = await originalFetch(firstInput, firstInit);
     if (response.status !== 401) return response;
 
@@ -306,6 +396,7 @@ export function resetApiAuthFetchForTests(adminTokenPrompt: AdminTokenPrompt = p
   memoryToken = null;
   memoryCsrfToken = null;
   memorySessionOrigin = null;
+  memorySessionPersistent = false;
   resolutionInFlight = null;
   rawFetch = null;
   promptCancelled = false;

gui/tests/api-auth-deadline.test.ts

@@ -178,6 +178,8 @@ test("the retried request carries the caller signal", async () => {
   const seenSignals: Array<AbortSignal | null | undefined> = [];
   const mockFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
     if (pathnameOf(input) === "/opencodex-session") return MINTED();
+    // The session endpoint is not a data request; keep it out of seenSignals.
+    if (pathnameOf(input) === "/api/auth/session") return new Response("unauthorized", { status: 401 });
     seenSignals.push(init?.signal ?? (input instanceof Request ? input.signal : undefined));
     const key = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined)).get("X-OpenCodex-API-Key");
     if (key === "ocx_session_fresh") return new Response("{}", { status: 200 });

gui/tests/api-auth-memory.test.ts

@@ -155,9 +155,10 @@ test("concurrent 401s share one token prompt and all retry with the stored token
   const release401: Array<() => void> = [];
   const mockFetch = (async (_input: RequestInfo | URL, init?: RequestInit) => {
     const headers = new Headers(init?.headers);
-    // Session re-bootstrap probe: this fixture never mints sessions, so fail it fast
-    // instead of letting it join the release queue below.
-    if (new URL(_input instanceof Request ? _input.url : String(_input), "http://localhost/").pathname === "/opencodex-session") {
+    // Session bootstrap/mint requests: this fixture never mints
+    // sessions, so fail them fast instead of letting them join the release queue below.
+    const path = new URL(_input instanceof Request ? _input.url : String(_input), "http://localhost/").pathname;
+    if (path === "/opencodex-session" || path === "/api/auth/session") {
       return new Response("unauthorized", { status: 401 });
     }
     if (headers.get("X-OpenCodex-API-Key") === "shared-token") {
@@ -278,7 +279,9 @@ test("canceling the token prompt once does not reopen it for the rest of the 401
   const release401: Array<() => void> = [];
   const mockFetch = (async (_input: RequestInfo | URL, init?: RequestInit) => {
     const headers = new Headers(init?.headers);
-    if (new URL(_input instanceof Request ? _input.url : String(_input), "http://localhost/").pathname === "/opencodex-session") {
+    // Session probes fail fast: this fixture queues only /api data requests.
+    const path = new URL(_input instanceof Request ? _input.url : String(_input), "http://localhost/").pathname;
+    if (path === "/opencodex-session" || path === "/api/auth/session") {
       return new Response("unauthorized", { status: 401 });
     }
     if (headers.get("X-OpenCodex-API-Key")) {
@@ -325,6 +328,9 @@ test("data-plane requests never receive the management token or prompt", async (
   let phase: "seed" | "cross" = "seed";
   const seenHeaders: Array<string | null> = [];
   const stateful = (async (_input: RequestInfo | URL, init?: RequestInit) => {
+    // Session endpoints must not count as data-plane probes here.
+    const path = new URL(_input instanceof Request ? _input.url : String(_input), "http://localhost/").pathname;
+    if (path === "/api/auth/session") return new Response("unauthorized", { status: 401 });
     const headers = new Headers(init?.headers);
     seenHeaders.push(headers.get("X-OpenCodex-API-Key"));
     if (phase === "seed") {