@firstpick/pi-package-webui 0.4.1 → 0.4.3

package/README.md

@@ -6,7 +6,7 @@ Local browser UI for [Pi coding agent](https://www.npmjs.com/package/@earendil-w
 
 Pi Web UI gives you a local browser companion for Pi: multi-tab chat, streaming output, model controls, uploads, slash-command helpers, workspace navigation, and optional extension widgets.
 
-> **Security:** Pi Web UI has no authentication. It can control the spawned Pi session and run anything that session is allowed to run. It binds to `127.0.0.1` by default; only expose it on trusted networks.
+> **Security:** Pi Web UI can control the spawned Pi session and run anything that session is allowed to run. It binds to `127.0.0.1` by default. Remote PIN authentication is off by default on first use; enabling it in **Controls → Network → Remote PIN auth** persists that preference for later Web UI starts.
 
 ## Requirements
 
@@ -54,6 +54,8 @@ Check a running Web UI with:
   --no-open          Do not open the browser automatically
   --no-session       Start Pi RPC with --no-session
   --name <name>      Initial Web UI tab name
+  --remote-auth      Enable startup PIN authentication for non-local clients
+  --no-remote-auth   Disable startup PIN authentication
   -- <pi args...>    Extra arguments forwarded to Pi RPC
 ```
 
@@ -63,6 +65,7 @@ Examples:
 /webui-start
 /webui-start 31500
 /webui-start --port 31500 --no-open
+/webui-start --remote-auth --host 0.0.0.0
 /webui-start --name browser -- --model anthropic/claude-sonnet-4-5:high
 ```
 
@@ -74,7 +77,7 @@ Running `/webui-start` again on the same URL restarts the server and restores cu
 /webui-status [detailed] [port] [--port N] [--host HOST]
 ```
 
-`/webui-status` reports the URL, online state, and network exposure. `detailed` adds tabs, sessions, models/providers, and recent backend events.
+`/webui-status` reports the URL, online state, network exposure, and Remote PIN auth state. `detailed` adds tabs, sessions, models/providers, and recent backend events.
 
 ## Standalone CLI
 
@@ -96,6 +99,8 @@ pi-webui [options] [-- <pi args...>]
   --pi <command>      Pi executable to spawn (default: bundled dependency, then "pi")
   --no-session        Start Pi RPC with --no-session
   --name <name>       Initial Web UI tab name
+  --remote-auth       Enable startup PIN authentication for non-local clients
+  --no-remote-auth    Disable startup PIN authentication
   -h, --help          Show help
   -v, --version       Print version
 ```
@@ -107,6 +112,7 @@ Examples:
 ```bash
 pi-webui
 pi-webui --cwd ~/src/my-project
+pi-webui --host 0.0.0.0 --remote-auth --cwd ~/src/my-project
 pi-webui --port 3000 -- --model anthropic/claude-sonnet-4-5:high
 PI_WEBUI_PI_BIN=/path/to/pi pi-webui --no-session
 ```
@@ -116,6 +122,8 @@ Environment variables:
 - `PI_WEBUI_HOST`
 - `PI_WEBUI_PORT`
 - `PI_WEBUI_PI_BIN`
+- `PI_WEBUI_REMOTE_AUTH=1` to start with remote PIN authentication enabled
+- `PI_WEBUI_SETTINGS_FILE=/path/to/settings.json` to override where Web UI stores persisted settings such as the Remote PIN auth preference
 
 ## Main features
 
@@ -123,7 +131,7 @@ Environment variables:
 - Multi-tab Pi sessions with isolated processes, working directories, prompt drafts, activity state, and a workspace dashboard for common actions.
 - Unified command palette (`Ctrl/Cmd+K`) for commands, tabs, models, sessions, settings, and frequent Web UI actions.
 - Automatic tab naming from the first prompt, with `--name <name>` still available for an explicit initial tab name.
-- Streaming chat transcript with Markdown, thinking output, tool/bash cards, queue and compaction events, edit-and-retry from user prompts, and abort controls.
+- Streaming chat transcript with Markdown, thinking output, tool/bash cards, queue and compaction events, edit-and-retry from user prompts, and guarded abort controls that require holding Esc or the Abort button for 3 seconds.
 - Prompt composer with uploads, drag/drop/paste, inline image support, slash-command autocomplete, and `@` file/path references with live suggestions.
 - Browser dialogs for common Pi selectors such as `/model`, `/settings`, `/theme`, `/fork`, `/clone`, `/resume`, `/tree`, `/scoped-models`, `/tools`, and `/skills`.
 - Model, thinking, session, workspace, theme, optional-feature, Codex usage, network, update/restart, event, and notification controls in the side panel.
@@ -143,6 +151,7 @@ Useful browser endpoints exposed by the local server include:
 - `GET /api/optional-features` for optional companion package install/update status.
 - `POST /api/optional-feature-install` for installing or updating known optional companion packages from the side panel.
 - `GET /api/update-status` and localhost-only `POST /api/update` for checking Pi/Web UI updates and running `pi update` plus all detected local/global Web UI and Pi package-manager updates followed by a Web UI server restart.
+- `GET /api/remote-auth`, `POST /api/remote-auth`, and localhost-only `POST /api/remote-auth/settings` for optional 4-digit PIN authentication when serving non-local browser clients.
 
 For local development, run the checkout helper directly, for example:
 
@@ -167,6 +176,7 @@ Optional companions:
 - `@firstpick/pi-extension-setup-skills` — TUI `/skills` setup command alongside WebUI-native skill toggles.
 - `@firstpick/pi-extension-todo-progress` — todo-progress rendering.
 - `@firstpick/pi-extension-tools` — TUI `/tools` active-tool manager alongside WebUI-native tool toggles.
+- `@firstpick/pi-package-remote-webui` — `/remote` trusted-LAN QR helper for connecting mobile browsers to Web UI.
 - `@firstpick/pi-extension-git-footer-status` — richer extension-owned git/footer status, including the structured Web UI footer payload.
 - `@firstpick/pi-extension-stats` — stats commands and status data.
 - `@firstpick/pi-themes-bundle` — Web UI and Pi theme resources.
@@ -197,8 +207,11 @@ This requires `/git-staged-msg` and `/pr` from `@firstpick/pi-prompts-git-pr`; b
 
 - Default bind is localhost-only: `127.0.0.1:31415`.
 - The side-panel **Open to network** button rebinds the server to `0.0.0.0`, shows LAN URLs when available, and toggles to "Close for network".
-- `--host 0.0.0.0` also exposes the Web UI to the local network.
-- Any connected browser client can control Pi and run Web UI bash actions as the Web UI process user.
+- The side-panel **Remote PIN auth** toggle is off by default on first use. When enabled, the server saves that preference, generates a fresh random 4-digit PIN for each server start, shows it in Controls and `/webui-status`, and requires it from non-local browser clients.
+- Localhost clients stay frictionless and can toggle Remote PIN auth; changing the toggle persists the preference and disconnects existing event streams so remote clients must re-authenticate after enablement.
+- `--host 0.0.0.0` also exposes the Web UI to the local network; pass `--remote-auth` to start with PIN auth already enabled.
+- Any connected browser client with access (and the PIN, if enabled) can control Pi and run Web UI bash actions as the Web UI process user.
+- Remote PIN auth is a simple trusted-LAN HTTP gate, not hardened multi-user authentication; do not expose it to untrusted networks.
 - The Web UI update endpoint is restricted to localhost, because it runs package update commands and restarts the server.
 - Treat Pi Web UI as a local companion, not a hardened multi-user web service.
 
@@ -207,4 +220,5 @@ This requires `/git-staged-msg` and `/pr` from `@firstpick/pi-prompts-git-pr`; b
 - **`/webui-start` is missing:** restart Pi after installing the package.
 - **Wrong port or existing server:** use `/webui-status detailed`, or start on another port with `/webui-start --port 31500`.
 - **Optional feature is disabled or missing:** check the side panel, install the companion package if needed, then run `/reload` in the active Pi tab.
+- **Remote browser asks for a PIN:** read it from **Controls → Network → Remote PIN auth**, `/webui-status`, or the local Web UI server log. Disable the toggle from localhost to remove the PIN gate.
 - **PWA install or notifications are unavailable:** use `localhost` or HTTPS; browser support varies on LAN HTTP URLs.

package/WEBUI_TUI_NATIVE_PARITY.json

@@ -445,8 +445,8 @@
       "priority": "P1",
       "sensitive": false,
       "guards": ["confirmation"],
-      "currentBehavior": "Escape aborts active user bash first, then active agent runs, and closes UI surfaces with tab scoping.",
-      "targetBehavior": "Abort active bash first where applicable; keep agent/tab scoping and clear UI cancellation rules."
+      "currentBehavior": "Holding Escape for 3 seconds aborts active user bash first, then active agent runs, and closes UI surfaces with tab scoping before arming abort.",
+      "targetBehavior": "Abort active bash first where applicable; keep agent/tab scoping and clear UI cancellation rules with a guarded hold-to-abort affordance."
     },
     {
       "id": "shortcut.editor.clear",

package/bin/pi-webui.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, randomInt, randomUUID, timingSafeEqual } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { createServer } from "node:http";
 import { createRequire } from "node:module";
@@ -43,6 +43,7 @@ const publicDir = path.join(packageRoot, "public");
 const webuiHelperExtensionPath = path.join(packageRoot, "webui-rpc-helper.mjs");
 const agentDir = process.env.PI_CODING_AGENT_DIR || path.join(homedir(), ".pi", "agent");
 const OPTIONAL_FEATURE_INSTALL_ROOT_ENV = "PI_WEBUI_OPTIONAL_FEATURE_INSTALL_ROOT";
+const WEBUI_SETTINGS_FILE_ENV = "PI_WEBUI_SETTINGS_FILE";
 const packageJson = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
 let piPackageJson = {};
 try {
@@ -227,6 +228,7 @@ const OPTIONAL_FEATURE_PACKAGES = new Map([
   ["tuiSkillsCommand", "@firstpick/pi-extension-setup-skills"],
   ["todoProgressWidget", "@firstpick/pi-extension-todo-progress"],
   ["tuiToolsCommand", "@firstpick/pi-extension-tools"],
+  ["remoteWebui", "@firstpick/pi-package-remote-webui"],
   ["gitFooterStatus", "@firstpick/pi-extension-git-footer-status"],
   ["statsCommand", "@firstpick/pi-extension-stats"],
   ["themeBundle", "@firstpick/pi-themes-bundle"],
@@ -249,6 +251,8 @@ Options:
   --pi <command>      Pi executable to spawn (default: bundled dependency, then "pi")
   --no-session        Start Pi RPC with --no-session
   --name <name>       Initial Web UI tab display name
+  --remote-auth       Enable startup PIN authentication for non-local clients
+  --no-remote-auth    Disable startup PIN authentication
   -h, --help          Show this help
   -v, --version       Print version
 
@@ -262,8 +266,9 @@ Examples:
   PI_WEBUI_PI_BIN=/path/to/pi pi-webui --no-session
 
 Security:
-  The web UI has no authentication and can control Pi tools. It binds to
-  localhost by default. Do not expose it on untrusted networks.
+  The web UI controls Pi tools. It binds to localhost by default. Remote PIN
+  authentication is off by default on first use; enabling it in Controls saves
+  that preference for later starts.
 `);
 }
 
@@ -285,6 +290,8 @@ function parseArgs(argv) {
     piBinExplicit: !!process.env.PI_WEBUI_PI_BIN,
     noSession: false,
     name: undefined,
+    remoteAuth: isTruthyEnv(process.env.PI_WEBUI_REMOTE_AUTH),
+    remoteAuthExplicit: process.env.PI_WEBUI_REMOTE_AUTH !== undefined,
     piArgs: [],
     help: false,
     version: false,
@@ -339,6 +346,16 @@ function parseArgs(argv) {
       i++;
       continue;
     }
+    if (arg === "--remote-auth") {
+      options.remoteAuth = true;
+      options.remoteAuthExplicit = true;
+      continue;
+    }
+    if (arg === "--no-remote-auth") {
+      options.remoteAuth = false;
+      options.remoteAuthExplicit = true;
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}. Pass Pi CLI args after --.`);
   }
 
@@ -649,6 +666,153 @@ async function readJsonBody(req, { limitBytes = BODY_LIMIT_BYTES } = {}) {
   return JSON.parse(text);
 }
 
+function parseCookieHeader(header = "") {
+  const cookies = new Map();
+  for (const part of String(header || "").split(";")) {
+    const index = part.indexOf("=");
+    if (index === -1) continue;
+    const name = part.slice(0, index).trim();
+    const value = part.slice(index + 1).trim();
+    if (name) {
+      try {
+        cookies.set(name, decodeURIComponent(value));
+      } catch {
+        cookies.set(name, value);
+      }
+    }
+  }
+  return cookies;
+}
+
+function safeTimingEqual(a = "", b = "") {
+  const left = Buffer.from(String(a));
+  const right = Buffer.from(String(b));
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+function safeReturnPath(value) {
+  const text = String(value || "/").trim();
+  if (!text.startsWith("/") || text.startsWith("//")) return "/";
+  return text;
+}
+
+function remoteAuthCookie(token = remoteAuth.token) {
+  const maxAge = Math.max(0, Math.floor((remoteAuth.tokenExpiresAt - Date.now()) / 1000));
+  return `pi_remote_auth=${encodeURIComponent(token || "")}; HttpOnly; SameSite=Lax; Path=/; Max-Age=${maxAge}`;
+}
+
+function clearRemoteAuthCookie() {
+  return "pi_remote_auth=; HttpOnly; SameSite=Lax; Path=/; Max-Age=0";
+}
+
+function requestHasRemoteAuth(req) {
+  if (!remoteAuthRequired()) return true;
+  const token = parseCookieHeader(req.headers.cookie).get("pi_remote_auth");
+  return !!(token && remoteAuth.token && remoteAuth.tokenExpiresAt > Date.now() && safeTimingEqual(token, remoteAuth.token));
+}
+
+function isRemoteAuthPublicPath(pathname) {
+  return pathname === "/remote-auth" || pathname === "/api/remote-auth" || pathname === "/favicon.svg";
+}
+
+function shouldChallengeRemoteAuth(req, url) {
+  if (isLocalRequest(req) || !remoteAuthRequired() || isRemoteAuthPublicPath(url.pathname)) return false;
+  return !requestHasRemoteAuth(req);
+}
+
+function sendRemoteAuthPage(res, returnPath = "/") {
+  const safeReturn = safeReturnPath(returnPath);
+  const body = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Pi Web UI Remote PIN</title>
+  <style>
+    :root { color-scheme: dark; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #0f172a; color: #e5e7eb; }
+    body { min-height: 100vh; display: grid; place-items: center; margin: 0; padding: 24px; box-sizing: border-box; }
+    main { width: min(420px, 100%); padding: 28px; border: 1px solid rgba(148, 163, 184, 0.28); border-radius: 20px; background: rgba(15, 23, 42, 0.92); box-shadow: 0 24px 80px rgba(0, 0, 0, 0.35); }
+    h1 { margin: 0 0 8px; font-size: 1.45rem; }
+    p { margin: 0 0 20px; color: #94a3b8; line-height: 1.5; }
+    label { display: block; margin-bottom: 8px; color: #cbd5e1; font-weight: 650; }
+    input { width: 100%; box-sizing: border-box; border: 1px solid rgba(148, 163, 184, 0.36); border-radius: 14px; padding: 14px 16px; background: #020617; color: #f8fafc; font: inherit; font-size: 1.6rem; letter-spacing: 0.32em; text-align: center; }
+    button { width: 100%; margin-top: 16px; border: 0; border-radius: 14px; padding: 14px 16px; background: #22c55e; color: #052e16; font: inherit; font-weight: 800; cursor: pointer; }
+    button:disabled { opacity: 0.65; cursor: wait; }
+    .error { min-height: 1.4em; margin-top: 14px; color: #fca5a5; }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>Remote PIN required</h1>
+    <p>Scan a trusted /remote QR code to unlock automatically, or enter the 4-digit PIN shown in the local Pi terminal or local Web UI.</p>
+    <form id="pinForm" autocomplete="off">
+      <label for="pin">PIN</label>
+      <input id="pin" name="pin" inputmode="numeric" pattern="[0-9]{4}" maxlength="4" autofocus required>
+      <button id="submit" type="submit">Unlock Web UI</button>
+      <div id="error" class="error" role="alert"></div>
+    </form>
+  </main>
+  <script>
+    const returnPath = ${JSON.stringify(safeReturn).replace(/</g, "\\u003c")};
+    const form = document.getElementById("pinForm");
+    const input = document.getElementById("pin");
+    const button = document.getElementById("submit");
+    const error = document.getElementById("error");
+    function pinFromHash() {
+      const params = new URLSearchParams(String(window.location.hash || "").replace(/^#/, ""));
+      const pin = String(params.get("pin") || "").trim();
+      return /^\\d{4}$/.test(pin) ? pin : "";
+    }
+    async function submitPin(pin) {
+      button.disabled = true;
+      error.textContent = "";
+      try {
+        const response = await fetch("/api/remote-auth", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ pin }),
+        });
+        const data = await response.json().catch(() => ({}));
+        if (!response.ok || data.ok !== true) throw new Error(data.error || "Incorrect PIN");
+        window.location.replace(returnPath || "/");
+      } catch (err) {
+        error.textContent = err?.message || String(err);
+        input.select();
+      } finally {
+        button.disabled = false;
+      }
+    }
+    input.addEventListener("input", () => { input.value = input.value.replace(/\\D/g, "").slice(0, 4); error.textContent = ""; });
+    form.addEventListener("submit", async (event) => {
+      event.preventDefault();
+      await submitPin(input.value);
+    });
+    const autoPin = pinFromHash();
+    if (autoPin) {
+      input.value = autoPin;
+      window.history.replaceState(null, "", window.location.pathname + (window.location.search || ""));
+      submitPin(autoPin);
+    }
+  </script>
+</body>
+</html>`;
+  res.writeHead(200, {
+    "content-type": "text/html; charset=utf-8",
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff",
+  });
+  res.end(body);
+}
+
+function sendRemoteAuthRequired(req, res, url) {
+  const acceptsHtml = String(req.headers.accept || "").includes("text/html");
+  if (req.method === "GET" && (acceptsHtml || url.pathname === "/" || url.pathname === "/index.html" || url.pathname === "/remote-auth")) {
+    sendRemoteAuthPage(res, `${url.pathname}${url.search || ""}`);
+    return;
+  }
+  sendJson(res, 401, { ok: false, error: "Remote PIN required", remoteAuthRequired: true }, { "www-authenticate": "PiRemotePin" });
+}
+
 function sendSse(res, event) {
   res.write(`data: ${JSON.stringify(event)}\n\n`);
 }
@@ -1187,6 +1351,50 @@ async function writePathFastPicks(picks) {
   return normalized;
 }
 
+function webuiSettingsFile() {
+  if (process.env[WEBUI_SETTINGS_FILE_ENV]) return path.resolve(expandUserPath(process.env[WEBUI_SETTINGS_FILE_ENV]));
+  const configRoot = process.env.XDG_CONFIG_HOME || path.join(homedir(), ".config");
+  return path.join(configRoot, "pi-webui", "settings.json");
+}
+
+function normalizeWebuiSettings(value) {
+  return {
+    version: 1,
+    remoteAuthEnabled: value?.remoteAuthEnabled === true,
+  };
+}
+
+let webuiSettingsCache = null;
+
+async function readWebuiSettings() {
+  if (webuiSettingsCache) return webuiSettingsCache;
+  webuiSettingsCache = normalizeWebuiSettings(await readJsonFileIfExists(webuiSettingsFile()));
+  return webuiSettingsCache;
+}
+
+async function writeWebuiSettings(patch) {
+  const current = await readWebuiSettings();
+  const next = normalizeWebuiSettings({ ...current, ...(patch || {}) });
+  const storageFile = webuiSettingsFile();
+  await mkdir(path.dirname(storageFile), { recursive: true });
+  const tmpFile = `${storageFile}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(tmpFile, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  await rename(tmpFile, storageFile);
+  webuiSettingsCache = next;
+  return next;
+}
+
+async function readPersistedRemoteAuthEnabled() {
+  return (await readWebuiSettings()).remoteAuthEnabled === true;
+}
+
+async function saveRemoteAuthPreference(enabled) {
+  const nextEnabled = enabled === true;
+  await writeWebuiSettings({ remoteAuthEnabled: nextEnabled });
+  persistedRemoteAuthEnabled = nextEnabled;
+  return persistedRemoteAuthEnabled;
+}
+
 function parseCliScopedModelPatterns() {
   for (let index = 0; index < options.piArgs.length; index++) {
     const arg = options.piArgs[index];
@@ -6461,11 +6669,17 @@ async function createInitialTabs() {
 }
 
 const serverStartedAt = new Date().toISOString();
+let persistedRemoteAuthEnabled = await readPersistedRemoteAuthEnabled();
 const initialTabs = await createInitialTabs();
 const initialTab = initialTabs[0];
 let currentHost = options.host;
 let networkRebindInProgress = false;
 let networkRebindTargetHost = null;
+const remoteAuth = {
+  pin: undefined,
+  token: undefined,
+  tokenExpiresAt: 0,
+};
 
 function localNetworkAddresses() {
   const addresses = [];
@@ -6478,7 +6692,52 @@ function localNetworkAddresses() {
   return [...new Set(addresses)].sort();
 }
 
-function networkStatus() {
+function remoteAuthRequired() {
+  return !isLocalHost(currentHost) && !!remoteAuth.pin;
+}
+
+function generateRemotePin() {
+  return String(randomInt(0, 10_000)).padStart(4, "0");
+}
+
+function enableRemoteAuth(reason = "network exposure") {
+  remoteAuth.pin = generateRemotePin();
+  remoteAuth.token = createHash("sha256").update(`${randomUUID()}:${remoteAuth.pin}:${Date.now()}`).digest("base64url");
+  remoteAuth.tokenExpiresAt = Date.now() + 7 * 24 * 60 * 60 * 1000;
+  console.warn(`Pi Web UI remote PIN for ${reason}: ${remoteAuth.pin}`);
+  return remoteAuth.pin;
+}
+
+function resetRemoteAuth() {
+  remoteAuth.pin = undefined;
+  remoteAuth.token = undefined;
+  remoteAuth.tokenExpiresAt = 0;
+}
+
+function remoteAuthPreferenceEnabled() {
+  return persistedRemoteAuthEnabled === true;
+}
+
+function remoteAuthStartupEnabled() {
+  return options.remoteAuthExplicit ? options.remoteAuth === true : remoteAuthPreferenceEnabled();
+}
+
+function remoteAuthStartupReason() {
+  if (options.remoteAuthExplicit) return "startup option";
+  return "saved setting";
+}
+
+function remoteAuthStatus({ includePin = false } = {}) {
+  const enabled = !!remoteAuth.pin;
+  const status = {
+    enabled,
+    required: enabled && !isLocalHost(currentHost),
+  };
+  if (includePin && enabled) status.pin = remoteAuth.pin;
+  return status;
+}
+
+function networkStatus({ includeAuthPin = false } = {}) {
   const open = !isLocalHost(currentHost);
   const targetHost = networkRebindTargetHost || currentHost;
   const opening = networkRebindInProgress && !isLocalHost(targetHost);
@@ -6492,6 +6751,7 @@ function networkStatus() {
     port: options.port,
     localUrl: `http://127.0.0.1:${options.port}/`,
     networkUrls,
+    auth: remoteAuthStatus({ includePin: includeAuthPin }),
   };
 }
 
@@ -6515,6 +6775,23 @@ function closeSseClientsForRebind(nextHost) {
   }
 }
 
+function closeSseClientsForRemoteAuthChange() {
+  for (const tab of tabs.values()) {
+    const authEvent = {
+      type: "webui_remote_auth_changed",
+      tabId: tab.id,
+      tabTitle: tab.title,
+      auth: remoteAuthStatus(),
+    };
+    recordEvent(authEvent);
+    for (const client of tab.sseClients) {
+      sendSse(client, authEvent);
+      client.end();
+    }
+    tab.sseClients.clear();
+  }
+}
+
 function closeServerListener() {
   return new Promise((resolve, reject) => {
     if (!server.listening) {
@@ -6558,7 +6835,7 @@ function listenOn(host) {
 
 async function openToLocalNetwork() {
   const nextHost = "0.0.0.0";
-  if (!isLocalHost(currentHost) || networkRebindInProgress) return networkStatus();
+  if (!isLocalHost(currentHost) || networkRebindInProgress) return networkStatus({ includeAuthPin: true });
 
   networkRebindInProgress = true;
   networkRebindTargetHost = nextHost;
@@ -6568,8 +6845,8 @@ async function openToLocalNetwork() {
     await closeServerListener();
     await listenOn(nextHost);
     currentHost = nextHost;
-    console.warn("WARNING: Web UI is now reachable from the local network and has no authentication.");
-    return networkStatus();
+    console.warn(`WARNING: Web UI is now reachable from the local network${remoteAuth.pin ? " and requires the remote PIN for non-local clients" : " without remote PIN authentication"}.`);
+    return networkStatus({ includeAuthPin: true });
   } catch (error) {
     console.error("Failed to open Web UI to local network:", sanitizeError(error));
     if (!server.listening) {
@@ -6598,8 +6875,9 @@ async function closeNetworkAccess() {
     await closeServerListener();
     await listenOn(nextHost);
     currentHost = nextHost;
+    if (!remoteAuthPreferenceEnabled()) resetRemoteAuth();
     console.warn("Web UI network access closed; listening on localhost only.");
-    return networkStatus();
+    return networkStatus({ includeAuthPin: true });
   } catch (error) {
     console.error("Failed to close Web UI network access:", sanitizeError(error));
     if (!server.listening) {
@@ -6616,6 +6894,8 @@ async function closeNetworkAccess() {
   }
 }
 
+if (remoteAuthStartupEnabled()) enableRemoteAuth(remoteAuthStartupReason());
+
 async function safeRpcData(tab, command, timeoutMs = STATUS_RPC_TIMEOUT_MS) {
   try {
     const response = await tab.rpc.send(command, timeoutMs);
@@ -6693,9 +6973,9 @@ async function tabStatusDetails(tab) {
   };
 }
 
-async function webuiStatus({ detailed = false, eventLimit = 40 } = {}) {
+async function webuiStatus({ detailed = false, eventLimit = 40, includeAuthPin = false } = {}) {
   const tab = firstTab();
-  const network = networkStatus();
+  const network = networkStatus({ includeAuthPin });
   const statusTabs = listTabs();
   const data = {
     online: true,
@@ -6731,6 +7011,46 @@ const server = createServer(async (req, res) => {
   try {
     const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
 
+    if (url.pathname === "/remote-auth" && req.method === "GET") {
+      sendRemoteAuthPage(res, url.searchParams.get("return") || "/");
+      return;
+    }
+
+    if (url.pathname === "/api/remote-auth" && req.method === "GET") {
+      sendJson(res, 200, { ok: true, data: { auth: remoteAuthStatus({ includePin: isLocalRequest(req) }), local: isLocalRequest(req) } });
+      return;
+    }
+
+    if (url.pathname === "/api/remote-auth" && req.method === "POST") {
+      const body = await readJsonBody(req);
+      const pin = String(body.pin || "").trim();
+      if (!remoteAuth.pin) throw makeHttpError(400, "Remote PIN authentication is not enabled");
+      if (!/^\d{4}$/.test(pin) || !safeTimingEqual(pin, remoteAuth.pin)) throw makeHttpError(403, "Incorrect remote PIN");
+      sendJson(res, 200, { ok: true, data: { auth: remoteAuthStatus() } }, { "set-cookie": remoteAuthCookie() });
+      return;
+    }
+
+    if (shouldChallengeRemoteAuth(req, url)) {
+      sendRemoteAuthRequired(req, res, url);
+      return;
+    }
+
+    if (url.pathname === "/api/remote-auth/settings" && req.method === "POST") {
+      requireLocalhostRoute(req, url.pathname);
+      const body = await readJsonBody(req);
+      if (body.enabled === true) {
+        enableRemoteAuth("side panel toggle");
+        await saveRemoteAuthPreference(true);
+      } else if (body.enabled === false) {
+        resetRemoteAuth();
+        await saveRemoteAuthPreference(false);
+      } else throw makeHttpError(400, "enabled must be true or false");
+      closeSseClientsForRemoteAuthChange();
+      const headers = body.enabled === false ? { "set-cookie": clearRemoteAuthCookie() } : {};
+      sendJson(res, 200, { ok: true, data: { auth: remoteAuthStatus({ includePin: true }), network: networkStatus({ includeAuthPin: true }) } }, headers);
+      return;
+    }
+
     if (url.pathname === "/api/tabs" && req.method === "GET") {
       sendJson(res, 200, { ok: true, data: { tabs: await listTabsWithReconciledActivity() } });
       return;
@@ -6800,7 +7120,7 @@ const server = createServer(async (req, res) => {
     }
 
     if (url.pathname === "/api/health" && req.method === "GET") {
-      const status = await webuiStatus();
+      const status = await webuiStatus({ includeAuthPin: isLocalRequest(req) });
       sendJson(res, 200, {
         ok: true,
         webuiVersion: status.webuiVersion,
@@ -6821,7 +7141,7 @@ const server = createServer(async (req, res) => {
       const detailed = ["1", "true", "yes", "detailed"].includes(String(url.searchParams.get("detailed") || "").toLowerCase());
       const parsedEventLimit = Number.parseInt(url.searchParams.get("events") || "40", 10);
       const eventLimit = Number.isFinite(parsedEventLimit) ? parsedEventLimit : 40;
-      sendJson(res, 200, { ok: true, data: await webuiStatus({ detailed, eventLimit }) });
+      sendJson(res, 200, { ok: true, data: await webuiStatus({ detailed, eventLimit, includeAuthPin: isLocalRequest(req) }) });
       return;
     }
 
@@ -6858,13 +7178,13 @@ const server = createServer(async (req, res) => {
     }
 
     if (url.pathname === "/api/network" && req.method === "GET") {
-      sendJson(res, 200, { ok: true, data: networkStatus() });
+      sendJson(res, 200, { ok: true, data: networkStatus({ includeAuthPin: isLocalRequest(req) }) });
       return;
     }
 
     if (url.pathname === "/api/network/open" && req.method === "POST") {
       requireLocalhostRoute(req, url.pathname);
-      const before = networkStatus();
+      const before = networkStatus({ includeAuthPin: true });
       const shouldOpen = !before.open && !networkRebindInProgress;
       sendJson(res, 202, { ok: true, data: { ...before, opening: shouldOpen || before.opening, closing: before.closing } }, { connection: "close" });
       if (shouldOpen) {
@@ -6875,7 +7195,7 @@ const server = createServer(async (req, res) => {
 
     if (url.pathname === "/api/network/close" && req.method === "POST") {
       requireLocalhostRoute(req, url.pathname);
-      const before = networkStatus();
+      const before = networkStatus({ includeAuthPin: true });
       const shouldClose = before.open && !networkRebindInProgress;
       sendJson(res, 202, { ok: true, data: { ...before, opening: before.opening, closing: shouldClose || before.closing } }, { connection: "close" });
       if (shouldClose) {
@@ -7363,7 +7683,7 @@ server.listen(options.port, currentHost, () => {
   else console.log("Pi RPC: waiting for CWD selection in the Web UI");
   if (restoreTabs.length) console.log(`Restored Web UI tabs: ${initialTabs.length}`);
   if (!isLocalHost(currentHost)) {
-    console.warn("WARNING: Web UI has no authentication. Only expose it on trusted networks.");
+    console.warn(`WARNING: Web UI is exposed to the network. Remote PIN auth is ${remoteAuth.pin ? "enabled" : "OFF"}; only expose it on trusted networks.`);
   }
 });