@firstpick/pi-package-webui 0.4.1 → 0.4.2

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; enable it in **Controls → Network → Remote PIN auth** before exposing it on trusted networks.
 
 ## 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,7 @@ Environment variables:
 - `PI_WEBUI_HOST`
 - `PI_WEBUI_PORT`
 - `PI_WEBUI_PI_BIN`
+- `PI_WEBUI_REMOTE_AUTH=1` to start with remote PIN authentication enabled
 
 ## Main features
 
@@ -143,6 +150,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:
 
@@ -197,8 +205,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. When enabled, the server generates a random 4-digit PIN, 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 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 +218,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/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";
@@ -249,6 +249,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 +264,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; enable it in Controls or with --remote-auth
+  before exposing the server on trusted networks.
 `);
 }
 
@@ -285,6 +288,7 @@ function parseArgs(argv) {
     piBinExplicit: !!process.env.PI_WEBUI_PI_BIN,
     noSession: false,
     name: undefined,
+    remoteAuth: isTruthyEnv(process.env.PI_WEBUI_REMOTE_AUTH),
     piArgs: [],
     help: false,
     version: false,
@@ -339,6 +343,14 @@ function parseArgs(argv) {
       i++;
       continue;
     }
+    if (arg === "--remote-auth") {
+      options.remoteAuth = true;
+      continue;
+    }
+    if (arg === "--no-remote-auth") {
+      options.remoteAuth = false;
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}. Pass Pi CLI args after --.`);
   }
 
@@ -649,6 +661,139 @@ 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>Enter the 4-digit PIN shown in the local Pi terminal or local Web UI to continue.</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");
+    input.addEventListener("input", () => { input.value = input.value.replace(/\\D/g, "").slice(0, 4); error.textContent = ""; });
+    form.addEventListener("submit", async (event) => {
+      event.preventDefault();
+      button.disabled = true;
+      error.textContent = "";
+      try {
+        const response = await fetch("/api/remote-auth", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ pin: input.value }),
+        });
+        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;
+      }
+    });
+  </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`);
 }
@@ -6466,6 +6611,11 @@ 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 +6628,39 @@ 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 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 +6674,7 @@ function networkStatus() {
     port: options.port,
     localUrl: `http://127.0.0.1:${options.port}/`,
     networkUrls,
+    auth: remoteAuthStatus({ includePin: includeAuthPin }),
   };
 }
 
@@ -6515,6 +6698,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 +6758,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 +6768,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,6 +6798,7 @@ async function closeNetworkAccess() {
     await closeServerListener();
     await listenOn(nextHost);
     currentHost = nextHost;
+    resetRemoteAuth();
     console.warn("Web UI network access closed; listening on localhost only.");
     return networkStatus();
   } catch (error) {
@@ -6616,6 +6817,8 @@ async function closeNetworkAccess() {
   }
 }
 
+if (!isLocalHost(currentHost) && options.remoteAuth !== false) enableRemoteAuth("startup network listener");
+
 async function safeRpcData(tab, command, timeoutMs = STATUS_RPC_TIMEOUT_MS) {
   try {
     const response = await tab.rpc.send(command, timeoutMs);
@@ -6693,9 +6896,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 +6934,42 @@ 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");
+      else if (body.enabled === false) resetRemoteAuth();
+      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 +7039,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 +7060,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 +7097,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 +7114,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 +7602,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.`);
   }
 });
 

package/index.ts

@@ -22,6 +22,7 @@ type WebuiAddress = {
 type StartWebuiOptions = WebuiAddress & {
   open: boolean;
   noSession: boolean;
+  remoteAuth: boolean;
   name?: string;
   piArgs: string[];
 };
@@ -104,6 +105,7 @@ function parseStartWebuiArgs(args: string): StartWebuiOptions {
     port: DEFAULT_PORT,
     open: true,
     noSession: false,
+    remoteAuth: false,
     piArgs: [],
   };
   const tokens = tokenizeArgs(args || "");
@@ -122,6 +124,14 @@ function parseStartWebuiArgs(args: string): StartWebuiOptions {
       options.noSession = true;
       continue;
     }
+    if (token === "--remote-auth") {
+      options.remoteAuth = true;
+      continue;
+    }
+    if (token === "--no-remote-auth") {
+      options.remoteAuth = false;
+      continue;
+    }
     if (token === "--host") {
       options.host = takeValue(tokens, i, token);
       i++;
@@ -516,6 +526,7 @@ function waitForWebuiUrl(child: WebuiChild, timeoutMs = START_TIMEOUT_MS): Promi
 async function startWebui(options: StartWebuiOptions, ctx: ExtensionCommandContext, restoreTabs: RestorableWebuiTab[] = []): Promise<string> {
   const args = [webuiBin, "--host", options.host, "--port", String(options.port), "--cwd", ctx.cwd];
   if (options.noSession) args.push("--no-session");
+  if (options.remoteAuth) args.push("--remote-auth");
   if (options.name) args.push("--name", options.name);
   if (options.piArgs.length > 0) args.push("--", ...options.piArgs);
 
@@ -688,8 +699,10 @@ function formatWebuiStatus(result: WebuiStatusFetchResult, requestedDetailed: bo
   const network = data.network || {};
   const tabs = Array.isArray(data.tabs) ? data.tabs : [];
   const networkUrls = Array.isArray(network.networkUrls) ? network.networkUrls : [];
+  const auth = network.auth || {};
   const pageUrl = data.pageUrl || network.localUrl || result.url;
   const networkLabel = network.open ? `open to LAN${network.opening ? " (opening)" : ""}` : network.opening ? "opening" : "local only";
+  const authLabel = auth.enabled ? `remote PIN on${auth.pin ? ` · PIN ${auth.pin}` : ""}` : "remote PIN off";
 
   if (!requestedDetailed) {
     const lines = [
@@ -698,6 +711,7 @@ function formatWebuiStatus(result: WebuiStatusFetchResult, requestedDetailed: bo
       detailLine("URL", pageUrl),
       detailLine("Online", "yes"),
       detailLine("Network", networkLabel),
+      detailLine("Auth", authLabel),
       detailLine("Tabs", tabs.length || "?"),
     ];
     if (networkUrls.length) lines.push(detailLine("LAN URLs", networkUrls.join(", ")));
@@ -712,6 +726,7 @@ function formatWebuiStatus(result: WebuiStatusFetchResult, requestedDetailed: bo
     detailLine("URL", pageUrl),
     detailLine("Online", "yes"),
     detailLine("Network", networkLabel),
+    detailLine("Auth", authLabel),
     detailLine("Bind", `${data.boundHost || network.host || "unknown"}:${data.port || network.port || "?"}`),
     detailLine("Version", data.webuiVersion || "unknown"),
     detailLine("PIDs", `webui ${data.webuiPid || "unknown"} · pi ${data.piPid || "unknown"}`),
@@ -758,7 +773,7 @@ function formatWebuiStatus(result: WebuiStatusFetchResult, requestedDetailed: bo
 
 function usage(): string {
   return [
-    "Usage: /webui-start [port] [--port N] [--no-open] [--no-session] [--name NAME] [-- --model provider/model]",
+    "Usage: /webui-start [port] [--port N] [--no-open] [--no-session] [--remote-auth] [--name NAME] [-- --model provider/model]",
     "Starts the Pi Web UI companion server for the current cwd, prints the localhost URL, and opens it in your default browser.",
   ].join("\n");
 }

package/lib/trust-boundaries.mjs

@@ -12,6 +12,7 @@ export const TRUST_GUARD_TYPES = new Set([
 export const LOCALHOST_ONLY_POST_ROUTES = new Map([
   ["/api/network/open", "Opening to the network is only allowed from localhost"],
   ["/api/network/close", "Closing network access is only allowed from localhost"],
+  ["/api/remote-auth/settings", "Remote PIN authentication settings are only allowed from localhost"],
   ["/api/restart", "Restart is only allowed from localhost"],
   ["/api/update", "Updating Pi from the Web UI is only allowed from localhost"],
   ["/api/shutdown", "Shutdown is only allowed from localhost"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firstpick/pi-package-webui",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Pi Web UI companion package with a local browser UI CLI plus /webui-start and /webui-status commands.",
   "license": "MIT",
   "homepage": "https://github.com/Firstp1ck/npm-packages/tree/main/pi-package-webui#readme",

package/public/app.js

@@ -127,6 +127,8 @@ const elements = {
   backgroundClearButton: $("#backgroundClearButton"),
   backgroundStatus: $("#backgroundStatus"),
   networkStatus: $("#networkStatus"),
+  remoteAuthToggle: $("#remoteAuthToggle"),
+  remoteAuthStatus: $("#remoteAuthStatus"),
   openNetworkButton: $("#openNetworkButton"),
   serverActionSelect: $("#serverActionSelect"),
   runServerActionButton: $("#runServerActionButton"),
@@ -2267,6 +2269,10 @@ async function api(path, { method = "GET", body, tabId = activeTabId, scoped = t
   setBackendOffline(false);
   const data = await response.json().catch(() => ({}));
   if (!response.ok) {
+    if (response.status === 401 && data.remoteAuthRequired) {
+      const returnPath = `${window.location.pathname}${window.location.search || ""}` || "/";
+      window.location.assign(`/remote-auth?return=${encodeURIComponent(returnPath)}`);
+    }
     const error = new Error(data.error || data.message || JSON.stringify(data));
     error.statusCode = response.status;
     error.data = data;
@@ -14838,7 +14844,22 @@ function renderNetworkStatus() {
     if (networkUrls.length === 0) list.append(make("div", "network-status-empty", "No LAN address detected."));
   }
 
-  elements.networkStatus.replaceChildren(heading, detail, list);
+  const auth = network?.auth || {};
+  const authText = auth.enabled
+    ? auth.pin
+      ? `Remote PIN auth on · PIN ${auth.pin}`
+      : "Remote PIN auth on"
+    : "Remote PIN auth off";
+  const authDetail = make("div", "network-status-detail", authText);
+
+  elements.networkStatus.replaceChildren(heading, detail, list, authDetail);
+  elements.remoteAuthToggle.checked = !!auth.enabled;
+  elements.remoteAuthToggle.disabled = rebinding;
+  elements.remoteAuthStatus.textContent = auth.enabled
+    ? auth.pin
+      ? `PIN ${auth.pin}`
+      : "On"
+    : "Off";
   elements.openNetworkButton.disabled = rebinding;
   elements.openNetworkButton.textContent = opening ? "Opening…" : closing ? "Closing…" : open ? "Close for network" : "Open to network";
 }
@@ -14854,6 +14875,28 @@ async function refreshNetworkStatus() {
   renderNetworkStatus();
 }
 
+async function toggleRemoteAuth() {
+  const enable = !latestNetwork?.auth?.enabled;
+  const message = enable
+    ? "Enable remote PIN authentication?\n\nA random 4-digit PIN will be required for non-local browser clients. The PIN is shown in Controls."
+    : "Disable remote PIN authentication?\n\nNon-local browser clients will no longer need a PIN while the network listener is open.";
+  if (!confirm(message)) {
+    renderNetworkStatus();
+    return;
+  }
+
+  elements.remoteAuthToggle.disabled = true;
+  try {
+    const response = await api("/api/remote-auth/settings", { method: "POST", body: { enabled: enable }, scoped: false });
+    latestNetwork = response.data?.network || { ...(latestNetwork || {}), auth: response.data?.auth };
+    addEvent(enable ? "remote PIN auth enabled" : "remote PIN auth disabled", enable ? "warn" : "info");
+  } catch (error) {
+    addEvent(error.message || String(error), "error");
+  } finally {
+    renderNetworkStatus();
+  }
+}
+
 async function refreshFooterData(tabContext = activeTabContext()) {
   if (!tabContext.tabId) return;
   await Promise.allSettled([refreshStats(tabContext), refreshWorkspace(tabContext)]);
@@ -15636,7 +15679,7 @@ async function openToNetwork() {
     await closeNetworkAccess();
     return;
   }
-  if (!confirm("Open Pi Web UI to your local network?\n\nThe Web UI has no authentication and can control Pi/tools. Only do this on a trusted LAN.")) return;
+  if (!confirm(`Open Pi Web UI to your local network?\n\nRemote PIN auth is ${latestNetwork?.auth?.enabled ? "ON" : "OFF"}. The Web UI can control Pi/tools, so only do this on a trusted LAN.`)) return;
 
   elements.openNetworkButton.disabled = true;
   elements.openNetworkButton.textContent = "Opening…";
@@ -16374,6 +16417,11 @@ function handleEvent(event) {
       renderNetworkStatus();
       break;
     }
+    case "webui_remote_auth_changed":
+      latestNetwork = { ...(latestNetwork || {}), auth: event.auth || {} };
+      addEvent(`remote PIN auth ${event.auth?.enabled ? "enabled" : "disabled"}`, event.auth?.enabled ? "warn" : "info");
+      renderNetworkStatus();
+      break;
     case "pi_process_exit":
       addEvent(`pi rpc exited (${event.code ?? event.signal ?? "unknown"})`, "error");
       clearRunIndicatorActivity();
@@ -17071,6 +17119,7 @@ if (elements.backgroundChooseButton && elements.backgroundInput) {
 if (elements.backgroundClearButton) {
   elements.backgroundClearButton.addEventListener("click", () => clearCustomBackground().catch((error) => addEvent(error.message || String(error), "error")));
 }
+elements.remoteAuthToggle.addEventListener("change", () => toggleRemoteAuth().catch((error) => addEvent(error.message || String(error), "error")));
 elements.openNetworkButton.addEventListener("click", openToNetwork);
 elements.serverActionSelect.addEventListener("change", updateServerActionButton);
 elements.runServerActionButton.addEventListener("click", () => runSelectedServerAction().catch((error) => addEvent(error.message || String(error), "error")));

package/public/index.html

@@ -370,6 +370,13 @@
                 <div class="control-field network-control-field">
                   <label>Network</label>
                   <div id="networkStatus" class="network-status closed">Local only</div>
+                  <label class="toggle-control remote-auth-toggle" for="remoteAuthToggle">
+                    <input id="remoteAuthToggle" type="checkbox" />
+                    <span>
+                      <span class="toggle-control-label">Remote PIN auth</span>
+                      <span id="remoteAuthStatus" class="toggle-control-hint">Off</span>
+                    </span>
+                  </label>
                   <button id="openNetworkButton" type="button">Open to network</button>
                 </div>
                 <div class="control-field server-control-field">

package/tests/http-endpoints-harness.test.mjs

@@ -245,8 +245,15 @@ try {
   assert.equal(traversalDelete.status, 403, "session delete outside the session dir must return 403");
   assert.match(String(traversalDelete.body?.error || ""), /session directory/i);
 
+  const initialAuth = await request("127.0.0.1", "/api/remote-auth");
+  assert.equal(initialAuth.status, 200);
+  assert.equal(initialAuth.body?.data?.auth?.enabled, false, "remote PIN auth should be off by default");
+
   const lan = lanAddress();
   if (lan) {
+    const remoteHealthBeforeAuth = await request(lan, "/api/health");
+    assert.equal(remoteHealthBeforeAuth.status, 200, "LAN clients should connect without a PIN while auth is off");
+
     const remoteDelete = await request(lan, "/api/session-delete", {
       method: "POST",
       body: { sessionPath: path.join(cwd, "outside.jsonl"), confirmed: true, tab: tabId },
@@ -262,7 +269,55 @@ try {
 
     const remoteClose = await request(lan, "/api/network/close", { method: "POST" });
     assert.equal(remoteClose.status, 403, "network close must be localhost-only");
+
+    const enableAuth = await request("127.0.0.1", "/api/remote-auth/settings", { method: "POST", body: { enabled: true } });
+    assert.equal(enableAuth.status, 200, "localhost can enable remote PIN auth");
+    const pin = enableAuth.body?.data?.auth?.pin;
+    assert.match(pin, /^\d{4}$/, "enabling remote auth should generate a 4-digit PIN");
+
+    const remoteHealthWithAuth = await request(lan, "/api/health");
+    assert.equal(remoteHealthWithAuth.status, 401, "unauthenticated LAN clients should be challenged while remote auth is on");
+
+    const wrongPin = pin === "0000" ? "0001" : "0000";
+    const badLogin = await request(lan, "/api/remote-auth", { method: "POST", body: { pin: wrongPin } });
+    assert.equal(badLogin.status, 403, "wrong remote PIN should be rejected");
+
+    const loginResponse = await fetch(`http://${lan}:${port}/api/remote-auth`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ pin }),
+      signal: AbortSignal.timeout(5_000),
+    });
+    assert.equal(loginResponse.status, 200, "correct remote PIN should be accepted");
+    const authCookie = loginResponse.headers.get("set-cookie")?.split(";", 1)[0];
+    assert.ok(authCookie, "remote auth login should set an auth cookie");
+
+    const authedHealth = await fetch(`http://${lan}:${port}/api/health`, {
+      headers: { cookie: authCookie },
+      signal: AbortSignal.timeout(5_000),
+    });
+    assert.equal(authedHealth.status, 200, "authenticated LAN client should reach guarded APIs");
+    await authedHealth.json();
+
+    const remoteSettings = await fetch(`http://${lan}:${port}/api/remote-auth/settings`, {
+      method: "POST",
+      headers: { "content-type": "application/json", cookie: authCookie },
+      body: JSON.stringify({ enabled: false }),
+      signal: AbortSignal.timeout(5_000),
+    });
+    assert.equal(remoteSettings.status, 403, "remote clients must not toggle remote PIN auth settings");
+    await remoteSettings.json().catch(() => undefined);
+
+    const disableAuth = await request("127.0.0.1", "/api/remote-auth/settings", { method: "POST", body: { enabled: false } });
+    assert.equal(disableAuth.status, 200, "localhost can disable remote PIN auth");
+    const remoteHealthAfterDisable = await request(lan, "/api/health");
+    assert.equal(remoteHealthAfterDisable.status, 200, "LAN clients should reconnect without a PIN after auth is disabled");
   } else {
+    const enableAuth = await request("127.0.0.1", "/api/remote-auth/settings", { method: "POST", body: { enabled: true } });
+    assert.equal(enableAuth.status, 200, "localhost can enable remote PIN auth");
+    assert.match(enableAuth.body?.data?.auth?.pin, /^\d{4}$/);
+    const disableAuth = await request("127.0.0.1", "/api/remote-auth/settings", { method: "POST", body: { enabled: false } });
+    assert.equal(disableAuth.status, 200, "localhost can disable remote PIN auth");
     console.log("http-endpoints-harness: no LAN address detected; skipping remote-client checks");
   }
 

package/tests/mobile-static.test.mjs

@@ -399,6 +399,8 @@ assert.match(app, /initializeCustomBackground\(\)\.catch/, "startup should resto
 assert.match(app, /Restart Web UI to load themes/, "frontend should explain when a stale server cannot serve the themes endpoint");
 assert.match(app, /themeSelect\.addEventListener\("change"/, "side-panel theme selector should switch themes immediately");
 assert.match(app, /open \? "Close for network" : "Open to network"/, "network button should toggle from open to close action");
+assert.match(app, /remoteAuthToggle: \$\("#remoteAuthToggle"\)/, "Controls should expose the remote PIN auth toggle");
+assert.match(app, /api\("\/api\/remote-auth\/settings", \{ method: "POST"/, "remote PIN auth toggle should call the settings endpoint");
 assert.match(app, /api\("\/api\/network\/close", \{ method: "POST"/, "network close action should call the close endpoint");
 assert.match(app, /webuiVersionBadge: \$\("#webuiVersionBadge"\)/, "frontend should bind the Control Deck version badge");
 assert.match(app, /webuiDevBadge: \$\("#webuiDevBadge"\)/, "frontend should bind the Control Deck dev badge");

package/tests/session-auth-harness.test.mjs

@@ -132,6 +132,10 @@ try {
     LOCALHOST_ONLY_POST_ROUTES.has("/api/network/close"),
     "closing network access must be localhost-only like opening it",
   );
+  assert.ok(
+    LOCALHOST_ONLY_POST_ROUTES.has("/api/remote-auth/settings"),
+    "remote PIN auth settings must be localhost-only",
+  );
 } finally {
   await rm(tempDir, { recursive: true, force: true });
   await rm(outsideDir, { recursive: true, force: true });