feat(server): authenticated remote dashboard listener with cookie sessions

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

@@ -34,6 +34,57 @@ password manager can offer to save and autofill it. The dashboard itself still k
 in memory and does not write it to `localStorage` or `sessionStorage`; whether it is saved is entirely
 the browser or password manager's decision.
 
+## 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 specific non-blank bind address; 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. 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 session automatically. `POST /api/auth/session`
+with the token in `X-OpenCodex-API-Key` mints a 12-hour GUI session and sets the HttpOnly
+`opencodex_gui_session` cookie (`Path=/`; `SameSite=Strict`), while `GET /api/auth/session` returns
+the current session's `csrfToken`, `origin`, and `expiresAt` when the cookie is valid. The cookie is
+host-scoped and unreadable by page JavaScript, and 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 should be a private or tailnet address; Tailscale is the recommended setup. The
+session cookie travels over plain HTTP to that address, which is acceptable inside a
+WireGuard-encrypted tailnet but should not be exposed on an untrusted network. The cookie carries no
+`Secure` flag because the tailnet URL is `http://`.
+:::
+
 ## What you can do
 
 | Area | What it does |

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`. |
 | `emptyCompletionRetry?` | `boolean` | `false` | Opt in to one identical Responses retry when a completion has no text or tool call. The retry may be billable. `OCX_EMPTY_COMPLETION_RETRY=0` disables it without changing config; combo and routed-compaction turns remain excluded. |
 | `stallTimeoutSec?` | `number` | `300` | Seconds without upstream data before `response.incomplete`. Minimum 1. |
@@ -112,6 +113,41 @@ 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 specific non-blank bind address,
+typically the machine's Tailscale IP (`100.x.y.z`). 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).
+
+Session endpoints exist on the proxy listener and the dashboard listener: `POST /api/auth/session`
+with the admin token in `X-OpenCodex-API-Key` mints a 12-hour GUI session cookie, and
+`GET /api/auth/session` returns the current session's `csrfToken`, `origin`, and `expiresAt`.
+The unauthenticated loopback listener returns `404` for all of `/api/*`.
+
 ### 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";
+/** Cookie-session endpoint: GET probes the HttpOnly cookie, POST mints one from an admin token. */
+const AUTH_SESSION_PATH = "/api/auth/session";
 
 /**
  * The silent re-bootstrap must fail fast: every /api/* request queues behind the
@@ -69,6 +71,14 @@ let memoryToken: string | null = null;
 let memoryCsrfToken: string | null = null;
 let memorySessionOrigin: string | null = null;
 
+/**
+ * Cookie-session arm, fired once at install when no memory credential exists. A returning
+ * visitor with a live `opencodex_gui_session` cookie authenticates through the cookie alone;
+ * this probe harvests the csrf/origin pair that /api requests must carry alongside it. Any
+ * failure (401, bad shape, foreign origin) is a silent no-op — the header paths still work.
+ */
+let cookieSessionArm: Promise<void> | null = null;
+
 function readToken(): string | null {
   return memoryToken;
 }
@@ -111,6 +121,57 @@ function storeSession(token: string | null, csrfToken: string | null, origin: st
   return true;
 }
 
+function startCookieSessionArm(): void {
+  // Holder: lets the async body compare against the installed arm without a
+  // use-before-assignment on its own const initializer (TS2454).
+  const installed: { arm: Promise<void> | null } = { arm: null };
+  installed.arm = (async () => {
+    if (!rawFetch) return;
+    const bounded = createBoundedFetch(rebootstrapTimeoutMs);
+    try {
+      const response = await rawFetch(AUTH_SESSION_PATH, { cache: "no-store", signal: bounded.signal });
+      if (!response.ok) return;
+      const session = await response.json().catch(() => null) as { csrfToken?: unknown; origin?: unknown } | null;
+      if (!session
+        || typeof session.csrfToken !== "string"
+        || !session.csrfToken
+        || session.origin !== window.location.origin) return;
+      // Superseded by a reset/reinstall (tests) or by a memory credential that landed meanwhile.
+      if (cookieSessionArm !== installed.arm || readToken() !== null) return;
+      // memoryToken stays null on purpose: the HttpOnly cookie is the credential here.
+      memoryCsrfToken = session.csrfToken;
+      memorySessionOrigin = session.origin;
+    } catch {
+      /* best-effort */
+    } finally {
+      bounded.clear();
+    }
+  })();
+  cookieSessionArm = installed.arm;
+}
+
+/**
+ * Mint the HttpOnly cookie alongside a manually entered admin token, so the next page load
+ * signs in silently. Best-effort: on failure the header credential still authenticates every
+ * request; the cookie is an enhancement, never a dependency.
+ */
+async function mintCookieSession(token: string): Promise<void> {
+  if (!rawFetch) return;
+  const bounded = createBoundedFetch(rebootstrapTimeoutMs);
+  try {
+    await rawFetch(AUTH_SESSION_PATH, {
+      method: "POST",
+      cache: "no-store",
+      signal: bounded.signal,
+      headers: { "X-OpenCodex-API-Key": token },
+    });
+  } catch {
+    /* best-effort */
+  } 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 +246,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, no cookie-session pair) — 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);
+  // Cookie-backed sessions carry the GUI binding headers with any credential shape; 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,6 +299,8 @@ async function resolveTokenAfter401(failedToken: string | null, callerSignal?: A
       const prompted = await requestAdminToken(verifyAdminToken);
       if (prompted) {
         storeToken(prompted);
+        // Bounded and fast; awaiting keeps the retry wave ordered after the mint.
+        await mintCookieSession(prompted);
         return prompted;
       }
       promptCancelled = true;
@@ -270,12 +337,35 @@ export function installApiAuthFetch(): void {
   loadInjectedSession();
   const originalFetch = window.fetch.bind(window);
   rawFetch = originalFetch;
+  // No injected meta session (non-loopback or cookie-only visitor): probe the HttpOnly cookie
+  // session so the first /api wave carries origin/CSRF instead of 401-ing into a spurious prompt.
+  if (readToken() === null) startCookieSessionArm();
   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);
+    // While credential-less, wait once for the cookie arm. Racing it would 401 the first wave
+    // and pop a spurious admin-token prompt. The promise is settle-once; awaiting it again is free.
+    if (!callerSignal?.aborted && readToken() === null && cookieSessionArm) {
+      // An aborted caller must not sit out the arm probe's full timeout: race the signal so
+      // this fetch unwinds immediately while other callers keep waiting for the shared arm.
+      if (callerSignal) {
+        let onAbort: (() => void) | undefined;
+        await Promise.race([
+          cookieSessionArm,
+          new Promise<void>((resolve) => {
+            onAbort = () => resolve();
+            callerSignal.addEventListener("abort", onAbort, { once: true });
+          }),
+        ]).finally(() => {
+          if (onAbort) callerSignal.removeEventListener("abort", onAbort);
+        });
+      } else {
+        await cookieSessionArm;
+      }
+    }
     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;
+  cookieSessionArm = null;
   resolutionInFlight = null;
   rawFetch = null;
   promptCancelled = false;