opencode-webui 2.4.0 → 3.0.0

package/server/index.ts

@@ -7,20 +7,22 @@
  * headers, and proxies /api/* with streaming. In production it also serves
  * the built frontend from dist/.
  *
- * Dev flow:  vite (5173) --/api--> this server (4097) --> opencode service
+ * Dev flow:  vite (5173) --/api--> dev proxy (4098) --> opencode service
  * Prod flow: this server (4097) serves dist/ + proxies /api
  *
- * Access control (server/auth.ts): every route except the login round-trip
- * requires a session cookie. WEBUI_PASSWORD sets the password; unset means a
- * strong passphrase is generated and printed once — but only on a loopback
- * bind, because a wildcard bind without a password refuses to start. The
- * browser never holds service credentials, and neither the password nor
- * session tokens are ever logged.
+ * Access control (server/auth.ts): every route except the login round-trip and
+ * the PWA shell (manifest/icons/service worker — see isPublicPwaAsset) requires
+ * a session cookie. WEBUI_PASSWORD sets the password; unset means a strong
+ * passphrase is generated and printed once — but only on a loopback bind,
+ * because a wildcard bind without a password refuses to start. The browser
+ * never holds service credentials, and neither the password nor session tokens
+ * are ever logged.
  */
 
 import { Service } from "@opencode-ai/client/service";
 import type { Server } from "bun";
-import { existsSync, mkdirSync, readFileSync, statSync, watch, appendFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, watch, appendFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { appendFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
@@ -42,11 +44,32 @@ import {
   unauthorizedResponse,
 } from "./auth";
 import { syncSkill } from "./skillSync";
+import {
+  ENV_KEYS,
+  analyzeExposure,
+  applyConfigPatch,
+  configPath,
+  mergePatch,
+  readFileConfig,
+  redact,
+  resolveConfig,
+  validatePatch,
+  type ConfigPatch,
+} from "./config";
+import {
+  clearPidFile,
+  ensureSetup,
+  resolveLaunchCommand,
+  runSetupCli,
+  spawnDetached,
+  writePidFile,
+} from "./setup";
 import {
   discoverUserUIEntries,
   extensionSourceRoots,
   globalUserExtensionsDir,
   invalidateExtensionCache,
+  setExtensionDisabled,
   warnOnce,
   type UIEntry,
 } from "./userExtensions";
@@ -75,7 +98,10 @@ if (process.argv.includes("sandbox")) {
   }
 }
 
-const PROXY_PORT = Number(process.env.WEBUI_PROXY_PORT ?? 4097);
+// Serve/security settings: env > ~/.config/opencode/webui/config.json > default
+// (server/config.ts). Read once — changing them requires a restart.
+const CONFIG = resolveConfig();
+const PROXY_PORT = CONFIG.port;
 // Client headers never forwarded to the engine: transport (recomputed by Bun
 // from the proxied request), identity (must WIN over anything the client
 // sends), and credentials the browser has no business relaying.
@@ -90,7 +116,7 @@ const FORBIDDEN_CLIENT_HEADERS = new Set([
   "expect",
   "proxy-authorization",
 ]);
-const HOST = process.env.WEBUI_HOST ?? "127.0.0.1";
+const HOST = CONFIG.host;
 // Bun binds 0.0.0.0 by default; keep the safe loopback default and only pass
 // through what the operator actually asked for ("localhost" binds 127.0.0.1).
 const BIND_HOST = HOST === "localhost" ? "127.0.0.1" : HOST;
@@ -99,10 +125,33 @@ const BIND_HOST = HOST === "localhost" ? "127.0.0.1" : HOST;
 // path that scripts/embed-shim.ts maps onto the embedded assets.
 const DIST_DIR = fileURLToPath(new URL("../dist/", import.meta.url));
 const APP_ROOT = fileURLToPath(new URL("../", import.meta.url));
+// A repo checkout (vite.config.ts present) runs the two-port dev topology:
+// Vite serves the UI and proxies /api to this proxy. Settings that only make
+// sense for the one-port production topology are flagged in the API below.
+const IS_DEV = existsSync(join(APP_ROOT, "vite.config.ts"));
 const DEBUG_LOG = process.env.WEBUI_DEBUG_LOG ?? "/tmp/webui-debug.log";
 const DEBUG = Bun.env.WEBUI_DEBUG === "1";
 const REPORT_REPO = process.env.WEBUI_REPORT_REPO ?? "AbdelftahZowail/opencode-webui";
 
+/**
+ * PWA shell files that must be reachable WITHOUT a session cookie.
+ *
+ * Chrome fetches the web app manifest — and its icons — with credentials mode
+ * "omit" (only `crossorigin="use-credentials"` on the <link> would include
+ * cookies), so a redirect to /login makes the app look non-installable and
+ * suppresses the install promotion entirely. The service worker script is
+ * included so registration/updates never race the session. None of these files
+ * carry secrets: they are static shell metadata and icons.
+ */
+function isPublicPwaAsset(path: string): boolean {
+  return (
+    path === "/manifest.webmanifest" ||
+    path === "/sw.js" ||
+    path === "/assets/opencode.svg" ||
+    path.startsWith("/icons/")
+  );
+}
+
 function dbg(...args: unknown[]) {
   if (!DEBUG) return;
   console.log("[webui]", ...args);
@@ -165,11 +214,36 @@ function persistCrashReason(kind: "uncaughtException" | "unhandledRejection", re
   console.error(`[webui] ${kind} (recorded in ${CRASH_LOG}):`, detail.split("\n")[0]);
 }
 
+/**
+ * The lifecycle plugin can start a webui between our port probe and Bun.serve,
+ * which would surface as EADDRINUSE. That is "another webui won the race", not
+ * a crash — say so and exit 0.
+ */
+function isAddrInUse(reason: unknown): boolean {
+  const code = (reason as { code?: unknown })?.code;
+  const message = reason instanceof Error ? reason.message : String(reason);
+  return code === "EADDRINUSE" || /EADDRINUSE|address already in use/i.test(message);
+}
+
+function portInUseExit(): void {
+  console.log(
+    `[webui] port ${PROXY_PORT} is already serving a webui (http://localhost:${PROXY_PORT}) — nothing to do`,
+  );
+}
+
 process.on("uncaughtException", (err) => {
+  if (isAddrInUse(err)) {
+    portInUseExit();
+    process.exit(0);
+  }
   persistCrashReason("uncaughtException", err);
   process.exit(1);
 });
 process.on("unhandledRejection", (reason) => {
+  if (isAddrInUse(reason)) {
+    portInUseExit();
+    process.exit(0);
+  }
   persistCrashReason("unhandledRejection", reason);
 });
 
@@ -537,20 +611,58 @@ function vendorShimFor(path: string): string | null {
 // ---------------------------------------------------------------------------
 
 type ManifestItem =
-  | { id: string; source: string; origin?: UIEntry["origin"]; url?: string; domUrl?: string }
-  | { id: string; source: string; origin?: UIEntry["origin"]; disabled: true };
+  | {
+      id: string;
+      source: string;
+      origin?: UIEntry["origin"];
+      name?: string;
+      description?: string;
+      settings?: unknown;
+      requires?: unknown;
+      capabilities?: unknown;
+      url?: string;
+      domUrl?: string;
+    }
+  | {
+      id: string;
+      source: string;
+      origin?: UIEntry["origin"];
+      name?: string;
+      description?: string;
+      settings?: unknown;
+      requires?: unknown;
+      capabilities?: unknown;
+      disabled: true;
+    };
 
 async function buildExtensionManifest(): Promise<ManifestItem[]> {
   // discoverAllUIEntries never throws; upstream failures collapse to [].
   const entries = await discoverAllUIEntries();
   return entries.map((e) => {
     if (e.disabled || (!e.entry && !e.domEntry)) {
-      return { id: e.id, source: e.source ?? e.entry, origin: e.origin, disabled: true as const };
+      return {
+        id: e.id,
+        source: e.source ?? e.entry,
+        origin: e.origin,
+        name: e.name,
+        description: e.description,
+        disabled: true as const,
+      };
     }
-    const item: { id: string; source: string; origin?: UIEntry["origin"]; url?: string; domUrl?: string } = {
+    const item: {
+      id: string;
+      source: string;
+      origin?: UIEntry["origin"];
+      name?: string;
+      description?: string;
+      url?: string;
+      domUrl?: string;
+    } = {
       id: e.id,
       source: e.source ?? e.entry,
       origin: e.origin,
+      name: e.name,
+      description: e.description,
     };
     // Shipped browser stratum loads via the in-repo Vite glob
     // (webui-extensions/index.ts, Vite HMR) — never via a bundle URL, or
@@ -667,6 +779,31 @@ function startExtensionWatcher() {
 // Boot: CLI flag → auth policy → skill sync → serve → banner.
 // ---------------------------------------------------------------------------
 
+/**
+ * `setup | update | uninstall | status | stop | restart`: manage the global
+ * command + OpenCode lifecycle plugin and exit without starting the server.
+ * Setup itself is automatic on first non-dev boot — this is the management
+ * surface. `internal:setup` is the hidden handoff `update` calls on the NEW
+ * version so it installs its own artifacts.
+ */
+const SETUP_ACTIONS = new Set([
+  "setup",
+  "update",
+  "uninstall",
+  "status",
+  "stop",
+  "restart",
+  "config",
+  "internal:setup",
+  "help",
+  "--help",
+  "-h",
+]);
+const SETUP_ARGV = process.argv.findIndex((arg) => SETUP_ACTIONS.has(arg));
+if (SETUP_ARGV !== -1) {
+  process.exit(await runSetupCli(process.argv[SETUP_ARGV], import.meta.url, process.argv.slice(SETUP_ARGV + 1)));
+}
+
 /** `--install-skill`: copy the skill and exit without starting the server. */
 if (process.argv.includes("--install-skill")) {
   const result = await syncSkill();
@@ -675,11 +812,18 @@ if (process.argv.includes("--install-skill")) {
   process.exit(result.ok ? 0 : 1);
 }
 
-// Exits with a clear message when a wildcard bind has no WEBUI_PASSWORD.
-const AUTH = resolveAuthPolicy(HOST);
-// Operator-controlled Host allowlist (WEBUI_ALLOWED_HOSTS) — resolved once,
-// consulted on every request by guardRequest below.
-const ALLOWED_HOSTS = resolveAllowedHosts();
+// Auth policy from config/env (server/config.ts). Sandbox and `auth: "none"`
+// disable the login; a reachable unauthenticated bind is warned about, not
+// refused (the user may front it with Tailscale/a private network).
+const AUTH = resolveAuthPolicy(HOST, {
+  mode: SANDBOX() || CONFIG.auth === "none" ? "none" : "password",
+  plaintext: CONFIG.envPassword ?? undefined,
+  hash: CONFIG.passwordHash ?? undefined,
+});
+// Operator-controlled Host allowlist — config/env, consulted on every request
+// by guardRequest below.
+const ALLOWED_HOSTS = resolveAllowedHosts(CONFIG.allowedHosts);
+const EXPOSURE = analyzeExposure(CONFIG);
 const SECRET = loadSecret();
 const SKILL = await syncSkill(); // best-effort — never blocks the banner below it
 
@@ -695,6 +839,173 @@ function readVersion(): string {
 }
 const PKG_VERSION = readVersion();
 
+// ---------------------------------------------------------------------------
+// Build identity for the footer badge (`GET /api/webui/config` → `build`).
+//
+// The badge shows a content hash of the whole served tree (`+a3f9c2d`): ANY
+// save anywhere produces a new hash, which is what dev needs at a glance.
+// `rev`/`dirty`/`changedAt` ride along for tooltips and debugging. npm
+// installs have no .git — the tree hash still works there. Hashing is
+// skipped unless a cheap mtime sweep sees movement (5s floor either way);
+// git failures collapse to nulls, never to errors.
+// ---------------------------------------------------------------------------
+
+interface BuildInfo {
+  /** Content hash (7 hex) over the source tree: any effective save flips it.
+   * Prod badges show the shipped version only; dev appends this hash. */
+  tree: string | null;
+  rev: string | null;
+  dirty: boolean;
+  changedAt: number | null;
+}
+
+let buildCache: { at: number; mtime: number | null; info: BuildInfo } | null = null;
+const BUILD_CACHE_TTL_MS = 5_000;
+
+function gitOut(args: string[]): string | null {
+  try {
+    const proc = Bun.spawnSync(["git", ...args], { cwd: APP_ROOT });
+    if (proc.exitCode !== 0) return null;
+    return proc.stdout.toString("utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Every file shaping the served UI (rel paths, sorted). Skips build output,
+// dependencies, and dot-dirs. Bounded so a stray huge dir can't stall boot. */
+function sourceFiles(): string[] {
+  const roots = ["src", "server", "public", "index.html", "vite.config.ts", "package.json"];
+  const out: string[] = [];
+  const stack = roots.map((r) => join(APP_ROOT, r));
+  let seen = 0;
+  while (stack.length > 0 && seen < 4000) {
+    const p = stack.pop()!;
+    seen++;
+    let st;
+    try {
+      st = statSync(p);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      const base = basename(p);
+      if (base === "node_modules" || base === "dist" || base.startsWith(".")) continue;
+      let kids: string[];
+      try {
+        kids = readdirSync(p);
+      } catch {
+        continue;
+      }
+      for (const k of kids) stack.push(join(p, k));
+    } else {
+      out.push(p);
+    }
+  }
+  return out.sort();
+}
+
+function treeFingerprint(): { tree: string | null; mtime: number | null } {
+  const files = sourceFiles();
+  if (files.length === 0) return { tree: null, mtime: null };
+  let newest = 0;
+  for (const f of files) {
+    try {
+      const m = statSync(f).mtimeMs;
+      if (m > newest) newest = m;
+    } catch {
+      /* raced deletion — skip */
+    }
+  }
+  const mtime = Math.floor(newest);
+  if (buildCache?.info.tree && buildCache.mtime === mtime) {
+    return { tree: buildCache.info.tree, mtime };
+  }
+  try {
+    const hash = createHash("sha256");
+    for (const f of files) {
+      const rel = f.startsWith(APP_ROOT) ? f.slice(APP_ROOT.length + 1) : f;
+      hash.update(rel);
+      hash.update("\0");
+      try {
+        hash.update(readFileSync(f));
+      } catch {
+        /* raced deletion — path already commits to the digest */
+      }
+      hash.update("\0");
+    }
+    return { tree: hash.digest("hex").slice(0, 7), mtime };
+  } catch {
+    return { tree: null, mtime };
+  }
+}
+
+function getBuildInfo(): BuildInfo {
+  const now = Date.now();
+  if (buildCache && now - buildCache.at < BUILD_CACHE_TTL_MS) return buildCache.info;
+  const { tree, mtime } = treeFingerprint();
+  const rev = gitOut(["rev-parse", "--short=7", "HEAD"]);
+  let dirty = false;
+  let changedAt: number | null = null;
+  if (rev) {
+    const st = gitOut(["status", "--porcelain"]);
+    dirty = st !== null && st !== "";
+    if (!dirty) {
+      const ct = gitOut(["log", "-1", "--format=%ct"]);
+      if (ct && /^\d+$/.test(ct)) changedAt = Number(ct) * 1000;
+    }
+  }
+  if (changedAt === null) changedAt = mtime;
+  const info = { tree, rev, dirty, changedAt };
+  buildCache = { at: now, mtime, info };
+  return info;
+}
+
+// The lifecycle plugin starts a webui when OpenCode loads, so a manual start
+// can find the port already held. Probe FIRST and exit before doing any engine
+// work — the running instance is the one the user wants. Fingerprint the login
+// page (unauthenticated, loopback always allowed) so an unrelated service on
+// the port is NOT mistaken for us.
+async function existingWebuiOnPort(port: number): Promise<boolean> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/login`, {
+      signal: AbortSignal.timeout(1500),
+      redirect: "manual",
+    });
+    if (!res.ok) return false;
+    return (await res.text()).includes("opencode webui");
+  } catch {
+    return false;
+  }
+}
+
+if (await existingWebuiOnPort(PROXY_PORT)) {
+  console.log(`[webui] already running at http://localhost:${PROXY_PORT} — nothing to do`);
+  process.exit(0);
+}
+
+// Start the OpenCode background service EAGERLY, before serving. The proxy
+// already reaches it lazily on the first /api call; doing it at boot means the
+// UI is usable the instant the browser opens, and matches `opencode service
+// start` (Service.ensure discovers or spawns `opencode serve --service`).
+//
+// Bounded: an already-running engine resolves instantly, but a cold spawn can
+// take seconds and must not hold the banner/port hostage. On timeout we keep
+// going and let the recorder/API connect when it is ready. Never fatal: the
+// promise is normalized so a rejection can never reach this top-level await.
+let ENGINE_LINE = "[webui] engine: starting the opencode background service…";
+const engineAttempt = serviceEndpoint().then(
+  (ep) => ep,
+  (err) => {
+    ENGINE_LINE = `[webui] engine: NOT running — ${err instanceof Error ? err.message : String(err)} (start it with \`opencode service start\`)`;
+    console.error(ENGINE_LINE);
+    return null;
+  },
+);
+const engineDeadline = new Promise<null>((resolve) => setTimeout(() => resolve(null), 6_000));
+const engineEndpoint = await Promise.race([engineAttempt, engineDeadline]);
+if (engineEndpoint) ENGINE_LINE = `[webui] engine: opencode service at ${engineEndpoint.url}`;
+
 const server: Server<Record<string, unknown>> = Bun.serve({
   port: PROXY_PORT,
   hostname: BIND_HOST,
@@ -721,7 +1032,7 @@ const server: Server<Record<string, unknown>> = Bun.serve({
     const path = url.pathname;
 
     // DNS-rebinding + cross-origin guard — before ANY route, login included.
-    const guarded = guardRequest(req, HOST, ALLOWED_HOSTS);
+    const guarded = guardRequest(req, HOST, ALLOWED_HOSTS, CONFIG.trustProxy);
     if (guarded) return guarded;
 
     // The unauthenticated surface: login page, login POST, logout.
@@ -733,8 +1044,17 @@ const server: Server<Record<string, unknown>> = Bun.serve({
 
     // Everything below — /api/* (JSON 401), pages, dist/ static, SSE, and
     // WebSocket upgrades — requires a valid session cookie. A SANDBOX
-    // instance (loopback-only, passwordless) skips the gate entirely.
-    if (!SANDBOX() && !isAuthed(req, SECRET)) return unauthorizedResponse(url);
+    // instance (loopback-only, passwordless) skips the gate entirely. The PWA
+    // shell is exempt: Chrome fetches the manifest/icons without credentials,
+    // so gating them reads as "not installable" (see isPublicPwaAsset).
+    if (
+      AUTH.mode !== "none" &&
+      !SANDBOX() &&
+      !isAuthed(req, SECRET) &&
+      !((method === "GET" || method === "HEAD") && isPublicPwaAsset(path))
+    ) {
+      return unauthorizedResponse(url);
+    }
 
     if (method === "GET" && path === "/api/webui/status") {
       try {
@@ -750,7 +1070,40 @@ const server: Server<Record<string, unknown>> = Bun.serve({
 
     // Proxy metadata: app version + where to report issues.
     if (method === "GET" && path === "/api/webui/config") {
-      return Response.json({ version: PKG_VERSION, reportRepo: REPORT_REPO });
+      return Response.json({ version: PKG_VERSION, reportRepo: REPORT_REPO, build: getBuildInfo() });
+    }
+
+    // Serve/security settings — one file, edited by this UI and the CLI.
+    // A dangerous change (unauthenticated + reachable) needs explicit confirm.
+    if (method === "GET" && path === "/api/webui/settings") {
+      return Response.json(settingsPayload());
+    }
+    if (method === "PUT" && path === "/api/webui/settings") {
+      let body: unknown;
+      try {
+        body = await req.json();
+      } catch {
+        return Response.json({ error: "invalid JSON body" }, { status: 400 });
+      }
+      const patch = sanitizePatch(body);
+      const errors = validatePatch(patch);
+      if (errors.length > 0) return Response.json({ error: errors.join("; "), errors }, { status: 400 });
+      const pending = analyzeExposure(mergePatch(readFileConfig(), patch));
+      const confirm = (body as { confirm?: unknown } | null)?.confirm === true;
+      if (pending.level === "danger" && !confirm) {
+        return Response.json({ error: "confirmation required", needConfirm: true, exposure: pending }, { status: 409 });
+      }
+      applyConfigPatch(patch);
+      dbg("settings updated:", Object.keys(patch).join(",") || "(no-op)");
+      return Response.json(settingsPayload());
+    }
+    // Restart to apply — spawn the detached `restart` (stop self + start new),
+    // after this response has a chance to flush. The socket may drop; the UI
+    // treats a dropped response as "restarting".
+    if (method === "POST" && path === "/api/webui/settings/restart") {
+      const launch = resolveLaunchCommand(import.meta.url);
+      setTimeout(() => spawnDetached({ cmd: [...launch.cmd, "restart"], display: "restart" }), 300);
+      return Response.json({ ok: true, restarting: true });
     }
 
     if (method === "POST" && path === "/api/debug") {
@@ -795,6 +1148,30 @@ const server: Server<Record<string, unknown>> = Bun.serve({
       return Response.json({ data, version: extManifestVersion });
     }
 
+    // Pause/resume one folder extension (Settings › Extensions switch). Writes
+    // the winning folder's manifest.json `disabled` field — or, for a shipped
+    // id, a user-level shadow folder so app updates never clobber the flag —
+    // then pushes the manifest so the page unloads the bundle immediately.
+    if (method === "POST" && /^\/api\/webui\/extensions\/[^/]+\/state$/.test(path)) {
+      const id = decodeURIComponent(path.split("/")[4] ?? "");
+      try {
+        const body = (await req.json()) as { disabled?: unknown };
+        if (typeof body?.disabled !== "boolean") {
+          return Response.json({ error: "disabled (boolean) required" }, { status: 400 });
+        }
+        const result = setExtensionDisabled(id, body.disabled);
+        if (!result.ok) return Response.json({ error: result.error }, { status: 400 });
+        await checkExtensionManifest(true);
+        dbg("extension", id, body.disabled ? "paused" : "enabled");
+        return Response.json({ ok: true, version: extManifestVersion, reload: result.reload === true });
+      } catch (err) {
+        return Response.json(
+          { error: err instanceof Error ? err.message : String(err) },
+          { status: 400 },
+        );
+      }
+    }
+
     // Manifest push channel (spec §6): one event per manifest change plus a
     // hello on subscribe. The page re-fetches the manifest on each event and
     // re-imports only bundles whose ?v= moved. Heartbeat comments keep the
@@ -968,8 +1345,7 @@ const server: Server<Record<string, unknown>> = Bun.serve({
     // installed package (no src/ on disk) vs a dev checkout (vite owns the
     // frontend). Dev with a stale dist/ still goes to vite for HMR.
     const hasDist = existsSync(join(DIST_DIR, "index.html"));
-    const isDevCheckout = existsSync(join(APP_ROOT, "vite.config.ts"));
-    if (Bun.env.NODE_ENV === "production" || (hasDist && !isDevCheckout)) {
+    if (Bun.env.NODE_ENV === "production" || (hasDist && !IS_DEV)) {
       if (method === "GET" || method === "HEAD") {
         // decodeURIComponent throws on malformed escapes (e.g. "/%") — 400,
         // never an unhandled throw.
@@ -992,11 +1368,13 @@ const server: Server<Record<string, unknown>> = Bun.serve({
           // SPA fallbacks, favicon) must be revalidated — a cached index.html
           // pins the browser to a stale bundle after every update.
           const immutable = /-[A-Za-z0-9_-]{8}\.[a-z0-9]+$/.test(filePath);
-          return new Response(file, {
-            headers: {
-              "cache-control": immutable ? "public, max-age=31536000, immutable" : "no-store",
-            },
-          });
+          const headers: Record<string, string> = {
+            "cache-control": immutable ? "public, max-age=31536000, immutable" : "no-store",
+          };
+          // Bun's MIME guess doesn't cover .webmanifest on every platform;
+          // Chrome ignores a manifest served as octet-stream.
+          if (filePath.endsWith(".webmanifest")) headers["content-type"] = "application/manifest+json";
+          return new Response(file, { headers });
         }
         const index = Bun.file(DIST_DIR + "index.html");
         if (await index.exists())
@@ -1005,10 +1383,10 @@ const server: Server<Record<string, unknown>> = Bun.serve({
       return new Response("not found", { status: 404 });
     }
 
-    return new Response("webui dev server: use vite (port 5173)", {
-      status: 200,
-      headers: { "content-type": "text/plain" },
-    });
+    return new Response(
+      `webui dev server: open the UI at vite (port ${process.env.WEBUI_VITE_PORT ?? 5173})`,
+      { status: 200, headers: { "content-type": "text/plain" } },
+    );
   },
   websocket: {
     open(ws) {
@@ -1064,21 +1442,107 @@ function describeHosts(): string {
   return parts.join(", ");
 }
 
+// ---------------------------------------------------------------------------
+// Serve/security settings (`/api/webui/settings`).
+//
+// The config file is the DESIRED state; this process holds the APPLIED state
+// (read at boot). GET compares them so the UI can say "restart to apply".
+// Values are redacted of any password/hash before they leave the process.
+// ---------------------------------------------------------------------------
+
+function sanitizePatch(body: unknown): ConfigPatch {
+  const b = (body ?? {}) as Record<string, unknown>;
+  const patch: ConfigPatch = {};
+  if (typeof b.host === "string") patch.host = b.host;
+  if (typeof b.port === "number") patch.port = b.port;
+  if (b.auth === "password" || b.auth === "none") patch.auth = b.auth;
+  if (typeof b.password === "string" && b.password.length > 0) patch.password = b.password;
+  if (b.clearPassword === true) patch.clearPassword = true;
+  if (Array.isArray(b.allowedHosts) && b.allowedHosts.every((v) => typeof v === "string")) {
+    patch.allowedHosts = b.allowedHosts as string[];
+  }
+  if (typeof b.trustProxy === "boolean") patch.trustProxy = b.trustProxy;
+  if (typeof b.autostart === "boolean") patch.autostart = b.autostart;
+  if (b.publicUrl === null || typeof b.publicUrl === "string") patch.publicUrl = b.publicUrl as string | null;
+  return patch;
+}
+
+/** Effective state + provenance + restart delta, safe to send to the browser. */
+function settingsPayload() {
+  const file = readFileConfig();
+  const now = resolveConfig();
+  const restartRequired =
+    now.host !== CONFIG.host ||
+    now.port !== CONFIG.port ||
+    (now.auth === "none") !== (CONFIG.auth === "none") ||
+    now.passwordHash !== CONFIG.passwordHash ||
+    now.envPassword !== CONFIG.envPassword ||
+    JSON.stringify(now.allowedHosts) !== JSON.stringify(CONFIG.allowedHosts) ||
+    now.trustProxy !== CONFIG.trustProxy;
+  // key -> the env var overriding it (name included: "env" alone is a dead end).
+  const envPinned: Record<string, string> = {};
+  for (const key of Object.keys(CONFIG.sources) as Array<keyof typeof CONFIG.sources>) {
+    if (CONFIG.sources[key] !== "env") continue;
+    const envVar = ENV_KEYS[key];
+    if (envVar) envPinned[key] = envVar;
+  }
+  return {
+    file: redact(file),
+    effective: {
+      ...redact(now, now.envPassword !== null || now.passwordHash !== null),
+      sources: CONFIG.sources,
+    },
+    runtime: {
+      host: HOST,
+      port: PROXY_PORT,
+      auth: AUTH.mode,
+      version: PKG_VERSION,
+      configPath: configPath(),
+      dev: IS_DEV,
+      vitePort: IS_DEV ? Number(process.env.WEBUI_VITE_PORT ?? 5173) : null,
+    },
+    exposure: analyzeExposure(file),
+    restartRequired,
+    envPinned,
+  };
+}
+
+// First-run setup: the global command + OpenCode lifecycle plugin. A matching
+// install is a no-op; the first install (and a refresh after an upgrade) shows
+// a one-time notice with the undo. The pidfile lets `stop`/`restart`/`update`
+// find this server.
+writePidFile(server.port ?? PROXY_PORT);
+process.on("exit", clearPidFile);
+const SETUP = ensureSetup({
+  entryUrl: import.meta.url,
+  port: server.port ?? PROXY_PORT,
+  version: PKG_VERSION,
+  autostart: CONFIG.autostart,
+});
+
 // First-boot banner — the entire onboarding. The generated password is
 // printed exactly once and never logged anywhere else.
 const displayHost = isLoopbackHostname(HOST === "localhost" ? "localhost" : HOST) ? "localhost" : HOST;
 console.log(
   [
-    `[webui] ready → http://${displayHost}:${server.port}`,
+    `[webui] ready → ${CONFIG.publicUrl ?? `http://${displayHost}:${server.port}`}`,
     SANDBOX()
       ? `[webui] sandbox — loopback only, NO password; extensions (scratch): ${globalUserExtensionsDir()}`
-      : `[webui] password: ${AUTH.generated ?? "from WEBUI_PASSWORD"}`,
+      : AUTH.mode === "none"
+        ? `[webui] auth: NONE — anyone who can reach this port has full access`
+        : `[webui] password: ${
+            AUTH.generated ??
+            (AUTH.source === "env" ? "from WEBUI_PASSWORD" : AUTH.source === "config" ? "set in config" : "set")
+          }`,
+    ENGINE_LINE,
+    ...(EXPOSURE.level === "ok" ? [] : [`[webui] exposed: ${EXPOSURE.message}`]),
     `[webui] hosts: ${describeHosts()}`,
     `[webui] same sessions as your opencode TUI — it's the same engine`,
     `[webui] extensions: drop folders in ${globalUserExtensionsDir()}/<name>/ (index.tsx + manifest.json)`,
     SKILL.ok
       ? `[webui] agent skill installed at ${SKILL.target} (auto-synced each boot)`
       : `[webui] agent skill NOT synced: ${SKILL.reason}`,
+    ...(SETUP.message ? SETUP.message.split("\n") : []),
   ].join("\n"),
 );
 void startEventRecorder();