feat(tunnel): auth expiry detection, in-app renewal, and token monitoring

Handle DevTunnel auth token expiry gracefully with proactive monitoring
and in-app renewal via device code flow.

Backend (src/tunnel/index.js):
- Detect auth errors ('login required', 'not logged in') in health check
- Auth-wait mode: poll every 30s, auto-reconnect when user re-auths
- Check isLoggedIn() as fallback for 'Tunnel not found' errors
- Token lifetime monitoring: emit auth-expiring when < 1h remaining
- Prefer Entra login for new sessions (auto-refreshes for weeks via MSAL)
- Warn when logged in with GitHub (8h token limit)
- Export parseLoginInfo() and getLoginInfo() for routes
- Remove unref() from health check interval (unreliable in PM2)

Backend (src/server/index.js):
- Wire tunnel events before startTunnel() (fixes missed connected event)
- Broadcast tunnel-status WebSocket messages to all clients
- Push notifications on auth-expiring and auth-expired
- Track tunnelStatus in server state for API endpoint
- Detect auth-expired on startup when tunnel fails to start

Backend (src/server/routes.js):
- GET /api/tunnel/status: returns tunnel state, provider, token lifetime
- POST /api/tunnel/renew: spawns devtunnel user login -d, parses device
  code and URL from output, returns { url, code } as JSON

Frontend:
- TunnelBanner component with shared Zustand store (tunnelStore.ts)
- States: expiring, expired, renewing (shows code + copy/open), renewed, failed
- All states have dismiss (✕) button
- Renew button on all states (user picks their account on auth page)
- 20s fetch timeout for renew endpoint (devtunnel takes up to 15s)
- WebSocket tunnel-status forwarding in useTerminalSocket
- WSTunnelStatusMessage type added to WebSocket protocol
- fetchTunnelStatus() and renewTunnelAuth() API functions

Tests:
- 22 new tests: parseLoginInfo, device code regex, event contracts,
  API endpoints, WebSocket broadcast patterns
- Updated server.test.js tunnel mock with new exports

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

Author: dorlugasigal

docs/api.md

@@ -975,6 +975,55 @@ Remove a previously registered push subscription.
 
 ---
 
+### Tunnel
+
+#### `GET /api/tunnel/status`
+
+Returns the current tunnel connection state, provider, and token lifetime.
+
+**Response (200):**
+
+```json
+{
+  "state": "connected",
+  "provider": "microsoft",
+  "tokenLifetimeSeconds": 3200
+}
+```
+
+| Field                  | Type        | Description                                                                                |
+| ---------------------- | ----------- | ------------------------------------------------------------------------------------------ |
+| `state`                | string      | Tunnel state: `connected`, `disconnected`, `expiring`, `auth-expired`, or `unknown`        |
+| `provider`             | string/null | Auth provider used for the tunnel: `microsoft`, `github`, or `null` if no tunnel is active |
+| `tokenLifetimeSeconds` | number/null | Seconds remaining on the current auth token, or `null` if unavailable                      |
+
+---
+
+#### `POST /api/tunnel/renew`
+
+Initiates a device code authentication flow to renew an expired tunnel token. The client should display the returned URL and code to the user.
+
+**Response (200):**
+
+```json
+{ "url": "https://microsoft.com/devicelogin", "code": "ABC123" }
+```
+
+| Field  | Type   | Description                                     |
+| ------ | ------ | ----------------------------------------------- |
+| `url`  | string | Device login URL the user should open           |
+| `code` | string | One-time code the user enters at the device URL |
+
+**Response (504):**
+
+```json
+{ "error": "Timed out waiting for device code" }
+```
+
+Returned when the device code flow does not complete within the expected timeout.
+
+---
+
 ### Port Preview
 
 #### `GET /preview/:port/*`
@@ -1140,6 +1189,25 @@ Sent during an in-app update (triggered via `POST /api/update`). Allows the fron
 
 The `status` field follows the same values as `GET /api/update/status`. When `status` reaches `restarting`, the WebSocket connection will close shortly after (close code 1012 for non-PM2 installs).
 
+#### Tunnel Status
+
+Broadcast when the tunnel connection state changes. Allows the frontend to show tunnel health and prompt for re-authentication when tokens expire.
+
+```json
+{
+  "type": "tunnel-status",
+  "state": "expiring",
+  "expiresIn": 1800,
+  "provider": "microsoft"
+}
+```
+
+| Field       | Type   | Description                                                                                        |
+| ----------- | ------ | -------------------------------------------------------------------------------------------------- |
+| `state`     | string | Tunnel state: `connected`, `disconnected`, `expiring`, `auth-expired`, `reconnecting`, or `failed` |
+| `expiresIn` | number | Seconds until the auth token expires (present when `state` is `expiring` or `connected`)           |
+| `provider`  | string | Auth provider: `microsoft` or `github` (present when a tunnel is active)                           |
+
 ---
 
 ## See Also

docs/architecture.md

@@ -118,8 +118,12 @@ Manages Azure DevTunnel lifecycle: login, create, host, cleanup. Includes a **wa
 - **Zombie detection** — if host connections drop to 0 for two consecutive checks (60s grace), the stale process is killed and a restart is initiated.
 - **Crash detection** — an `exit` handler on the child process triggers immediate restart if the process dies.
 - **Auto-restart** — exponential backoff (1s → 2s → 5s → 10s → 15s → 30s), up to 10 attempts before giving up.
+- **Auth-wait system** — detects auth token expiry (Microsoft limitation), enters an auth-wait mode, polls for re-authentication via device code flow, and auto-reconnects once a fresh token is obtained.
+- **Token lifetime monitoring** — tracks the remaining lifetime of the DevTunnel auth token and emits warnings when less than 1 hour remains, giving the frontend time to prompt the user.
 - **Event emitter** — exports `tunnelEvents` (EventEmitter) with events: `connected`, `disconnected`, `reconnecting`, `failed`. The server subscribes for logging.
 
+Also exports `getLoginInfo()` (returns current auth provider and token expiry) and `parseLoginInfo()` (parses raw `devtunnel` CLI output into structured login metadata).
+
 ### `tunnel/install.js` — DevTunnel Installer
 
 Handles automatic installation of the DevTunnel CLI when it's not found on the system. Prompts the user interactively and installs via the appropriate package manager (brew on macOS, curl on Linux, winget on Windows). Used by `server.js` during startup when tunnel mode is enabled.

docs/security.md

@@ -176,6 +176,13 @@ The following UI features are entirely client-side and introduce **no new server
 - Use `--lan` or `--host 0.0.0.0` to allow LAN access
 - The tunnel feature handles TLS via Azure DevTunnels
 
+### Tunnel Token Expiry
+
+- DevTunnel auth tokens expire periodically (a Microsoft-imposed limitation)
+- TermBeam detects token expiry and enters **auth-wait mode**, pausing tunnel operations until a fresh token is obtained
+- Users can renew the token in-app via a device code flow (`POST /api/tunnel/renew`), which returns a URL and one-time code to complete re-authentication
+- Once renewed, the tunnel reconnects automatically — no server restart required
+
 ## Best Practices
 
 <!-- prettier-ignore -->

src/frontend/src/components/SessionsHub/SessionsHub.tsx

@@ -6,6 +6,7 @@ import { useThemeStore } from '@/stores/themeStore';
 import { THEMES, type ThemeId } from '@/themes/terminalThemes';
 import type { Session } from '@/types';
 import UpdateBanner from '@/components/common/UpdateBanner';
+import TunnelBanner from '@/components/common/TunnelBanner';
 import SessionCard from './SessionCard';
 import NewSessionModal from './NewSessionModal';
 import styles from './SessionsHub.module.css';
@@ -166,6 +167,7 @@ export default function SessionsHub() {
   return (
     <div className={styles.page}>
       <UpdateBanner />
+      <TunnelBanner />
 
       <header className={styles.header}>
         <h1 className={styles.title}>

src/frontend/src/components/TerminalApp/TerminalApp.tsx

@@ -18,6 +18,7 @@ import NewSessionModal from '@/components/SessionsHub/NewSessionModal';
 import { UploadModal } from '@/components/Modals/UploadModal';
 import { PreviewModal } from '@/components/Modals/PreviewModal';
 import CopyOverlay from '@/components/Overlays/CopyOverlay';
+import TunnelBanner from '@/components/common/TunnelBanner';
 import type { Session } from '@/types';
 import styles from './TerminalApp.module.css';
 
@@ -449,6 +450,9 @@ export function TerminalApp() {
         </div>
       )}
 
+      {/* ── Tunnel token banner ── */}
+      <TunnelBanner />
+
       {/* ── Search bar ── */}
       <SearchBar />
 

src/frontend/src/components/common/TunnelBanner.module.css

@@ -0,0 +1,76 @@
+.banner {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.75rem;
+  padding: calc(0.55rem + env(safe-area-inset-top, 0px)) 1rem 0.55rem;
+  color: #fff;
+  font-size: 0.82rem;
+  font-weight: 500;
+  animation: slide-down 0.25s ease;
+}
+
+.warning {
+  background: #e65100;
+}
+
+.error {
+  background: #d32f2f;
+}
+
+.success {
+  background: #2e7d32;
+}
+
+.text {
+  flex: 1;
+  text-align: center;
+}
+
+.actionBtn {
+  background: rgba(255, 255, 255, 0.2);
+  border: 1px solid rgba(255, 255, 255, 0.35);
+  color: #fff;
+  font-size: 0.78rem;
+  font-weight: 600;
+  cursor: pointer;
+  padding: 0.25rem 0.65rem;
+  border-radius: 5px;
+  transition:
+    background 0.15s,
+    opacity 0.15s;
+  white-space: nowrap;
+  text-decoration: none;
+}
+
+.actionBtn:hover {
+  background: rgba(255, 255, 255, 0.35);
+}
+
+.dismiss {
+  background: transparent;
+  border: none;
+  color: #fff;
+  font-size: 1rem;
+  cursor: pointer;
+  opacity: 0.7;
+  padding: 0.15rem 0.35rem;
+  border-radius: 4px;
+  transition: opacity 0.15s;
+  line-height: 1;
+}
+
+.dismiss:hover {
+  opacity: 1;
+}
+
+@keyframes slide-down {
+  from {
+    transform: translateY(-100%);
+    opacity: 0;
+  }
+  to {
+    transform: translateY(0);
+    opacity: 1;
+  }
+}