fix(auth): prevent white page in no-password mode after idle

Add /api/config endpoint so frontend knows when auth is disabled.
In no-password mode, skip auth checks and show reconnecting UI
instead of a dead-end login page when tunnel is stale.
Add CacheableResponsePlugin to service worker to prevent caching
non-200 responses from DevTunnel.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: dorlugasigal

docs/api.md

@@ -4,7 +4,7 @@ TermBeam exposes a REST API and WebSocket interface.
 
 ## REST API
 
-All API endpoints (except `/login`, `/api/auth`, and `/api/version`) require authentication via cookie or Bearer token.
+All API endpoints (except `/login`, `/api/auth`, `/api/version`, and `/api/config`) require authentication via cookie or Bearer token.
 
 <!-- prettier-ignore -->
 !!! note
@@ -281,6 +281,20 @@ Get the server version.
 { "version": "1.0.0" }
 ```
 
+#### `GET /api/config`
+
+Get public server configuration. No authentication required.
+
+**Response:**
+
+```json
+{ "passwordRequired": true }
+```
+
+| Field              | Type    | Description                                    |
+| ------------------ | ------- | ---------------------------------------------- |
+| `passwordRequired` | boolean | Whether the server requires password to access |
+
 #### `GET /api/update-check`
 
 Check if a newer version of TermBeam is available on npm. Results are cached for 24 hours.

src/frontend/package-lock.json

@@ -26,6 +26,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "sonner": "^2.0.3",
+    "workbox-cacheable-response": "^7.4.0",
     "zustand": "^5.0.3"
   },
   "overrides": {

src/frontend/package.json

@@ -21,7 +21,7 @@ function normalizeSessionParam() {
 }
 
 export default function App() {
-  const { authenticated, login, loading } = useAuth();
+  const { authenticated, passwordRequired, login, loading } = useAuth();
   const [path, setPath] = useState(getPath);
 
   useEffect(() => {
@@ -53,6 +53,43 @@ export default function App() {
   }
 
   if (!authenticated) {
+    // No-password mode: server is unreachable — show reconnecting UI instead of login
+    if (!passwordRequired) {
+      return (
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            justifyContent: 'center',
+            height: '100vh',
+            gap: '16px',
+            background: 'var(--bg)',
+            color: 'var(--text)',
+          }}
+        >
+          <div className="spinner" />
+          <p style={{ color: 'var(--text-secondary)', fontSize: '14px' }}>
+            Reconnecting to server…
+          </p>
+          <button
+            onClick={() => window.location.reload()}
+            style={{
+              marginTop: '8px',
+              padding: '8px 20px',
+              background: 'var(--accent)',
+              color: '#fff',
+              border: 'none',
+              borderRadius: '6px',
+              cursor: 'pointer',
+              fontSize: '13px',
+            }}
+          >
+            Retry
+          </button>
+        </div>
+      );
+    }
     return <LoginPage onLogin={login} loading={loading} />;
   }
 

src/frontend/src/App.tsx

@@ -1,21 +1,34 @@
 import { useState, useEffect, useCallback } from 'react';
-import { checkAuth, login as apiLogin, logout as apiLogout } from '@/services/api';
+import { checkAuth, getConfig, login as apiLogin, logout as apiLogout } from '@/services/api';
 
 interface UseAuthReturn {
   authenticated: boolean | null;
+  passwordRequired: boolean;
   login: (password: string) => Promise<boolean>;
   logout: () => Promise<void>;
   loading: boolean;
 }
 
 export function useAuth(): UseAuthReturn {
   const [authenticated, setAuthenticated] = useState<boolean | null>(null);
+  const [passwordRequired, setPasswordRequired] = useState(true);
   const [loading, setLoading] = useState(false);
 
   useEffect(() => {
     let cancelled = false;
 
     async function init() {
+      // Determine if password is required (uses localStorage cache when server unreachable)
+      const config = await getConfig();
+      if (cancelled) return;
+      setPasswordRequired(config.passwordRequired);
+
+      // No-password mode: skip auth checks entirely — always grant access
+      if (!config.passwordRequired) {
+        setAuthenticated(true);
+        return;
+      }
+
       // Check for one-time-token in URL
       const params = new URLSearchParams(window.location.search);
       const ott = params.get('ott');
@@ -50,8 +63,6 @@ export function useAuth(): UseAuthReturn {
         const { authenticated: isAuth, serverReachable } = await checkAuth();
         if (!cancelled) {
           if (!isAuth && !serverReachable) {
-            // Server unreachable — show login page so user sees something
-            // (a full reload could loop if the server is genuinely down)
             setAuthenticated(false);
             return;
           }
@@ -69,17 +80,41 @@ export function useAuth(): UseAuthReturn {
   }, []);
 
   // Re-check auth when returning from background (e.g. mobile tab switch after hours idle).
-  // Catches expired tokens / stale DevTunnel sessions that would otherwise show a white screen.
   useEffect(() => {
+    let retryTimer: ReturnType<typeof setTimeout> | null = null;
+
     function handleVisibility() {
-      if (document.hidden || authenticated !== true) return;
+      if (document.hidden) return;
+
+      if (!passwordRequired) {
+        // No-password mode: server is always "authenticated", but verify reachability.
+        // If unreachable, keep authenticated=true — the terminal/sessions hub will
+        // show its own connection banner. Once reachable again, everything auto-recovers.
+        checkAuth().then(({ serverReachable }) => {
+          if (!serverReachable && retryTimer === null) {
+            // Schedule a silent retry in case tunnel just needs a moment
+            retryTimer = setTimeout(() => {
+              retryTimer = null;
+              checkAuth(); // fire-and-forget; UI stays on terminal
+            }, 5000);
+          }
+        });
+        return;
+      }
+
+      // Password mode: if we were authenticated and now we're not, show login
+      if (authenticated !== true) return;
       checkAuth().then(({ authenticated: isAuth }) => {
         if (!isAuth) setAuthenticated(false);
       });
     }
+
     document.addEventListener('visibilitychange', handleVisibility);
-    return () => document.removeEventListener('visibilitychange', handleVisibility);
-  }, [authenticated]);
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibility);
+      if (retryTimer !== null) clearTimeout(retryTimer);
+    };
+  }, [authenticated, passwordRequired]);
 
   const login = useCallback(async (password: string): Promise<boolean> => {
     setLoading(true);
@@ -88,7 +123,6 @@ export function useAuth(): UseAuthReturn {
       setAuthenticated(ok);
       return ok;
     } catch (err) {
-      // Re-throw so caller can distinguish 429 from other errors
       throw err;
     } finally {
       setLoading(false);
@@ -100,5 +134,5 @@ export function useAuth(): UseAuthReturn {
     setAuthenticated(false);
   }, []);
 
-  return { authenticated, login, logout, loading };
+  return { authenticated, passwordRequired, login, logout, loading };
 }

src/frontend/src/hooks/useAuth.ts

@@ -181,6 +181,25 @@ export async function checkAuth(): Promise<{
   }
 }
 
+export async function getConfig(): Promise<{ passwordRequired: boolean }> {
+  try {
+    const res = await fetchWithTimeout(`${BASE}/api/config`, { credentials: 'same-origin' });
+    const ct = res.headers.get('content-type') || '';
+    if (!ct.includes('application/json')) {
+      // Server unreachable or tunnel returning HTML — use cached value
+      const cached = localStorage.getItem('tb:passwordRequired');
+      return { passwordRequired: cached !== 'false' };
+    }
+    const data = (await res.json()) as { passwordRequired: boolean };
+    localStorage.setItem('tb:passwordRequired', String(data.passwordRequired));
+    return data;
+  } catch {
+    // Network error — fall back to cached value
+    const cached = localStorage.getItem('tb:passwordRequired');
+    return { passwordRequired: cached !== 'false' };
+  }
+}
+
 export async function login(password: string): Promise<{ ok: boolean }> {
   const res = await fetchWithTimeout(`${BASE}/api/auth`, {
     method: 'POST',

src/frontend/src/services/api.ts

@@ -3,6 +3,7 @@ import { precacheAndRoute, cleanupOutdatedCaches } from 'workbox-precaching';
 import { registerRoute, NavigationRoute } from 'workbox-routing';
 import { CacheFirst, NetworkFirst, NetworkOnly } from 'workbox-strategies';
 import { ExpirationPlugin } from 'workbox-expiration';
+import { CacheableResponsePlugin } from 'workbox-cacheable-response';
 
 declare let self: ServiceWorkerGlobalScope;
 
@@ -13,11 +14,14 @@ cleanupOutdatedCaches();
 // Navigation requests (HTML documents) use NetworkFirst so that external auth
 // redirects (e.g. DevTunnel Microsoft login) pass through to the browser
 // instead of being short-circuited by the precache.
+// CacheableResponsePlugin ensures only 200 OK responses are cached — prevents
+// stale DevTunnel auth pages or error HTML from polluting the navigation cache.
 registerRoute(
   new NavigationRoute(
     new NetworkFirst({
       cacheName: 'termbeam-navigation',
       networkTimeoutSeconds: 5,
+      plugins: [new CacheableResponsePlugin({ statuses: [200] })],
     }),
   ),
 );

src/frontend/src/sw.ts

@@ -88,6 +88,11 @@ function setupRoutes(app, { auth, sessions, config, state }) {
     res.json({ version: getVersion() });
   });
 
+  // Public config — no auth required
+  app.get('/api/config', (_req, res) => {
+    res.json({ passwordRequired: !!auth.password });
+  });
+
   // Update check API
   app.get('/api/update-check', apiRateLimit, auth.middleware, async (req, res) => {
     log.debug('Update check requested');

src/server/routes.js

@@ -0,0 +1,108 @@
+const { describe, it, after } = require('node:test');
+const assert = require('node:assert');
+const http = require('http');
+const { createTermBeamServer } = require('../../src/server');
+
+// --- Helpers ---
+
+const baseConfig = {
+  port: 0,
+  host: '127.0.0.1',
+  password: null,
+  useTunnel: false,
+  persistedTunnel: false,
+  shell: process.platform === 'win32' ? 'cmd.exe' : '/bin/sh',
+  shellArgs: [],
+  cwd: process.cwd(),
+  defaultShell: process.platform === 'win32' ? 'cmd.exe' : '/bin/sh',
+  version: '0.1.0-test',
+  logLevel: 'error',
+};
+
+function makeConfig(overrides = {}) {
+  return { ...baseConfig, ...overrides };
+}
+
+function httpRequest(options) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(options, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () =>
+        resolve({
+          statusCode: res.statusCode,
+          headers: res.headers,
+          data: Buffer.concat(chunks).toString(),
+        }),
+      );
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+async function startServer(configOverrides = {}) {
+  const instance = createTermBeamServer({ config: makeConfig(configOverrides) });
+  await instance.start();
+  const port = instance.server.address().port;
+  return { ...instance, port };
+}
+
+// --- Tests ---
+
+describe('GET /api/config', () => {
+  describe('with password set', () => {
+    let inst;
+    after(() => inst?.shutdown());
+
+    it('returns passwordRequired: true', async () => {
+      inst = await startServer({ password: 'testpass' });
+      const res = await httpRequest({
+        hostname: '127.0.0.1',
+        port: inst.port,
+        path: '/api/config',
+        method: 'GET',
+      });
+      assert.strictEqual(res.statusCode, 200);
+      const body = JSON.parse(res.data);
+      assert.deepStrictEqual(body, { passwordRequired: true });
+    });
+  });
+
+  describe('with no password', () => {
+    let inst;
+    after(() => inst?.shutdown());
+
+    it('returns passwordRequired: false', async () => {
+      inst = await startServer({ password: null });
+      const res = await httpRequest({
+        hostname: '127.0.0.1',
+        port: inst.port,
+        path: '/api/config',
+        method: 'GET',
+      });
+      assert.strictEqual(res.statusCode, 200);
+      const body = JSON.parse(res.data);
+      assert.deepStrictEqual(body, { passwordRequired: false });
+    });
+  });
+
+  describe('does not require authentication', () => {
+    let inst;
+    after(() => inst?.shutdown());
+
+    it('returns 200 without any auth cookie or token', async () => {
+      inst = await startServer({ password: 'secretpass' });
+      // No cookie or authorization header — should still succeed
+      const res = await httpRequest({
+        hostname: '127.0.0.1',
+        port: inst.port,
+        path: '/api/config',
+        method: 'GET',
+      });
+      assert.strictEqual(res.statusCode, 200);
+      const body = JSON.parse(res.data);
+      assert.strictEqual(body.passwordRequired, true);
+    });
+  });
+});