codebase-onboarder 0.3.0 → 0.3.1

package/README.md

@@ -202,7 +202,7 @@ with it instead of orphaning a process holding the scan cache.
 Onboarder has two modes, one config file, and three ways to edit it — the CLI wizard, CLI flags, and the web UI's Server drawer all write the same validated `config.json` (`~/.config/onboarder/config.json`, mode `0600`).
 
 - **Local (default)** — binds to loopback only, asks for no credentials. The safe default.
-- **Self-hosted** — a fresh setup binds `0.0.0.0` for direct LAN/VPS access; every API call requires a Bearer access key. Re-running setup preserves an existing loopback tunnel layout. Rotate the key with `onboarder config key rotate`; the old key dies on the next request.
+- **Self-hosted** — a fresh setup binds `0.0.0.0` for direct LAN/VPS access. Any IP-literal address is accepted, while arbitrary Host names are not. Remote browsers get a themed access-key login page and exchange the key for a 7-day signed `HttpOnly`, `SameSite=Strict` session cookie; true localhost requests skip login. API clients can continue using `Authorization: Bearer <access-key>`. Rotate the key with `onboarder config key rotate`; the old key and every old browser session die on the next request.
 
 ```bash
 onboarder setup                          # interactive wizard
@@ -223,7 +223,9 @@ onboarder https status                   # domain, URL, Caddyfile, and Caddy sta
 onboarder doctor                         # config, access key, ports, DNS, TLS, and tunnels
 ```
 
-A fresh self-hosted setup uses `0.0.0.0`, so a VPS is reachable at `http://<server-ip>:<port>` without a reverse proxy. A domain is optional for direct-IP access. If a domain is entered, setup asks whether to enable automatic HTTPS.
+A fresh self-hosted setup uses `0.0.0.0`, so a VPS is reachable at `http://<server-ip>:<port>` without a reverse proxy. The server accepts IPv4 and IPv6 IP literals, including a public address that reaches the host through provider NAT, but still rejects arbitrary DNS Host headers. A domain is optional for direct-IP access. If a domain is entered, setup asks whether to enable automatic HTTPS.
+
+When a remote browser opens the URL, Onboarder shows its themed sign-in page. The access key is sent in a POST body—not in the URL—and the browser stores only the signed session cookie. Opening the same server through `http://localhost:<port>` on that machine skips the page. Caddy and tunnel connections remain authenticated because their public Host is not loopback.
 
 For trusted HTTPS, DNS must already point the domain to the VPS and inbound TCP `80` and `443` must be allowed in both the cloud security group/NSG and the host firewall. On Ubuntu:
 
@@ -236,7 +238,7 @@ onboarder https check
 onboarder https setup
 ```
 
-Onboarder writes a private `Caddyfile` beside `config.json`, validates it, and asks Caddy to obtain and renew the certificate. It never runs `sudo` or installs packages silently. Caddy proxies `https://map.example.com` to `http://127.0.0.1:4310`; Onboarder continues to enforce the access key on every API call. A bare public IP cannot use a normal trusted domain certificate.
+Onboarder writes a private `Caddyfile` beside `config.json`, validates it, and asks Caddy to obtain and renew the certificate. It never runs `sudo` or installs packages silently. Caddy proxies `https://map.example.com` to `http://127.0.0.1:4310`; Onboarder recognizes the connection as remote and shows the access-key login page. A bare public IP cannot use a normal trusted domain certificate.
 
 If startup reports `EADDRINUSE`, run `onboarder status` first. If it identifies an Onboarder PID, use `onboarder stop` or `onboarder restart`; otherwise inspect the unrelated listener with `ss -ltnp` or `lsof -i :4310`, or choose another port. The error names these recovery commands instead of printing only the raw Node error.
 
@@ -254,7 +256,9 @@ codebase-onboarder/
 │   ├── index.js     # createServer / startServer / startup banner
 │   ├── config.js    # Settings schema, normalization, atomic 0600 writes
 │   ├── pidfile.js   # PID ownership for status / stop / restart
-│   ├── router.js    # Route table, live per-request settings, Bearer gate
+│   ├── router.js    # Route table, live per-request settings, auth & CSRF gates
+│   ├── auth.js      # Signed HttpOnly browser sessions
+│   ├── apiAuth.js   # Login/status/logout endpoints
 │   ├── apiSettings.js# GET/PUT /api/settings, key rotation
 │   ├── tunnel.js    # Cloudflare & Tailscale status/commands
 │   ├── https.js     # Caddy config, ACME/TLS readiness & lifecycle
@@ -269,8 +273,9 @@ codebase-onboarder/
 ├── public/          # Frontend client application
 │   ├── js/          # Vanilla ES modules (State, Inspector, Views, Settings)
 │   ├── vendor/      # Vendored Mermaid & Monaco Editor (Offline)
-│   └── index.html   # Main application interface
-└── tests/           # Comprehensive node:test suite (560 unit tests)
+│   ├── index.html   # Main application interface
+│   └── login.html   # Self-hosted access-key sign-in
+└── tests/           # Comprehensive node:test suite (565 tests)
 ```
 
 ---
@@ -280,7 +285,7 @@ codebase-onboarder/
 Onboarder includes a comprehensive automated test suite built with Node's native test runner:
 
 ```bash
-# Run all 560 tests
+# Run all 565 tests
 npm test
 ```
 

package/cli/commands.js

@@ -628,7 +628,7 @@ export async function runTunnel(kind, { flags = {}, out = console.log, err = con
       if (m && !announced) {
         announced = true;
         out(tick + 'Public URL: ' + bold(m[0]));
-        out(dim('    Anyone with the URL still needs the access key: ' + m[0] + '?key=<your-key>'));
+        out(dim('    Anyone with the URL still needs the access key: ' + m[0]));
       }
       if (flags.verbose) process.stderr.write(text);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-onboarder",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Drop a path. Get a map. A zero-dependency codebase visualizer with a CLI onboarding wizard, a web UI, and an optional key-gated self-hosted mode.",
   "type": "module",
   "bin": {

package/public/index.html

@@ -411,13 +411,14 @@
       <button class="btn btn-ghost btn-sm" id="srvRotate" title="Mint a new key; the old one dies immediately">Rotate</button>
     </div>
     <div class="server-fresh-key" id="srvFreshKeyRow" hidden>
-      <p class="drawer-fine">New key — shown once. It is already saved in this browser:</p>
+      <p class="drawer-fine">New key — shown once. This browser has been signed in with it:</p>
       <div class="mcp-config-row">
         <input type="text" class="text-input mcp-config-input" id="srvFreshKey" readonly spellcheck="false">
         <button class="btn btn-ghost btn-sm" id="srvCopyKey">Copy</button>
       </div>
     </div>
     <p class="drawer-fine" id="srvKeyHint"></p>
+    <button class="btn btn-ghost btn-sm" id="srvLogout">Sign out this browser</button>
   </div>
 
   <div class="server-section">

package/public/js/api.js

@@ -1,58 +1,19 @@
 // Server round-trips. Thin and honest: JSON in, JSON (or an SSE stream) out,
 // server error messages surfaced untouched.
 
-// ---------------------------------------------------------------- access key --
-//
-// A self-hosted server gates every API route behind a Bearer key. The browser
-// learns it one of two ways: the startup banner links here with `?key=…` in
-// the URL (adopted once, then stripped so it does not linger in history), or
-// the person pastes it into the Server drawer. Either way it lives in
-// localStorage and rides along as an Authorization header from then on. Local
-// mode ignores the header entirely, so sending it is harmless.
+// Browser access is an HttpOnly session cookie set by the themed self-hosted
+// login page. Same-origin fetches include it automatically, and JavaScript never
+// reads or stores the access key. API clients can still use `Authorization:
+// Bearer …`; local mode needs no credential at all.
 
-const ACCESS_KEY_STORAGE = 'onboarder.accessKey';
-
-let urlKeyChecked = false;
-
-// Lazy on purpose, and a function declaration for the same reason: running
-// this at import would touch `window`, and the front-end test suite requires
-// every module to be importable from Node. The first API call is still early
-// enough — the key is adopted before any request leaves.
-function adoptKeyFromUrl() {
-  if (urlKeyChecked) return;
-  urlKeyChecked = true;
-  try {
-    const url = new URL(window.location.href);
-    const key = url.searchParams.get('key');
-    if (!key) return;
-    localStorage.setItem(ACCESS_KEY_STORAGE, key);
-    url.searchParams.delete('key');
-    window.history.replaceState(null, '', url);
-  } catch {
-    /* no usable URL API — the drawer can still take the key by hand */
-  }
-}
-
-export function getAccessKey() {
-  adoptKeyFromUrl();
-  return localStorage.getItem(ACCESS_KEY_STORAGE) || '';
-}
-
-export function setAccessKey(key) {
-  const trimmed = String(key || '').trim();
-  if (trimmed) localStorage.setItem(ACCESS_KEY_STORAGE, trimmed);
-  else localStorage.removeItem(ACCESS_KEY_STORAGE);
-}
-
-function authHeaders() {
-  const key = getAccessKey();
-  return key ? { authorization: `Bearer ${key}` } : {};
-}
+// 0.3.0 briefly stored a raw self-hosted key here. Remove that legacy value on
+// first load so upgrading also removes the old secret rather than merely ignoring it.
+try { localStorage.removeItem('onboarder.accessKey'); } catch { /* storage may be unavailable */ }
 
 async function postJSON(url, body) {
   const res = await fetch(url, {
     method: 'POST',
-    headers: { 'content-type': 'application/json', ...authHeaders() },
+    headers: { 'content-type': 'application/json' },
     body: JSON.stringify(body),
   });
   let data = null;
@@ -73,14 +34,14 @@ export function scanOnServer(payload) {
 
 export async function cleanupClone(cloneId) {
   try {
-    await fetch('/api/scan/' + encodeURIComponent(cloneId), { method: 'DELETE', headers: authHeaders() });
+    await fetch('/api/scan/' + encodeURIComponent(cloneId), { method: 'DELETE' });
   } catch {
     /* best-effort: the temp dir expires on its own eventually */
   }
 }
 
 export async function fetchFileText(scanId, path) {
-  const res = await fetch('/api/file?scan=' + encodeURIComponent(scanId) + '&path=' + encodeURIComponent(path), { headers: authHeaders() });
+  const res = await fetch('/api/file?scan=' + encodeURIComponent(scanId) + '&path=' + encodeURIComponent(path));
   if (!res.ok) throw new Error('Could not read that file from the server.');
   return res.text();
 }
@@ -90,7 +51,7 @@ export async function fetchFileText(scanId, path) {
 // tool at, and this returns that honestly instead of pretending.
 export async function fetchToolsStatus() {
   try {
-    const res = await fetch('/api/tools', { headers: authHeaders() });
+    const res = await fetch('/api/tools');
     if (!res.ok) return null;
     const data = await res.json();
     return data && data.tools ? data.tools : null;
@@ -122,7 +83,7 @@ export async function streamToolInstall(tool, onEvent) {
   const emit = typeof onEvent === 'function' ? onEvent : () => {};
   const res = await fetch('/api/tools/install', {
     method: 'POST',
-    headers: { 'content-type': 'application/json', ...authHeaders() },
+    headers: { 'content-type': 'application/json' },
     body: JSON.stringify({ tool }),
   });
   if (!res.ok || !res.body) {
@@ -160,7 +121,7 @@ export async function streamToolInstall(tool, onEvent) {
 // this machine, which is exactly the side effect `postJSON` is here for.
 export async function fetchMcpStatus() {
   try {
-    const res = await fetch('/api/mcp', { headers: authHeaders() });
+    const res = await fetch('/api/mcp');
     if (!res.ok) return null;
     return await res.json();
   } catch {
@@ -181,7 +142,7 @@ export function stopMcpServer() {
 // than on every poll.
 export async function fetchMcpCommand() {
   try {
-    const res = await fetch('/api/mcp/command', { headers: authHeaders() });
+    const res = await fetch('/api/mcp/command');
     if (!res.ok) return null;
     return await res.json();
   } catch {
@@ -195,7 +156,7 @@ export async function fetchMcpCommand() {
 export async function* streamExplain({ baseUrl, apiKey, model, messages, maxTokens = 1200, providerOptions = {} }) {
   const res = await fetch('/api/explain', {
     method: 'POST',
-    headers: { 'content-type': 'application/json', ...authHeaders() },
+    headers: { 'content-type': 'application/json' },
     body: JSON.stringify({ baseUrl, apiKey, model, messages, stream: true, max_tokens: maxTokens, ...providerOptions }),
   });
 
@@ -241,7 +202,7 @@ export async function* streamExplain({ baseUrl, apiKey, model, messages, maxToke
 // rotation is a POST because it mints a new key on the server — the one and
 // only time a key ever crosses the wire in the clear.
 export async function fetchServerSettings() {
-  const res = await fetch('/api/settings', { headers: authHeaders() });
+  const res = await fetch('/api/settings');
   const data = await res.json().catch(() => null);
   if (!res.ok) throw new Error(data?.error || `The server said ${res.status}.`);
   return data;
@@ -250,7 +211,7 @@ export async function fetchServerSettings() {
 export async function updateServerSettings(patch) {
   const res = await fetch('/api/settings', {
     method: 'PUT',
-    headers: { 'content-type': 'application/json', ...authHeaders() },
+    headers: { 'content-type': 'application/json' },
     body: JSON.stringify(patch),
   });
   const data = await res.json().catch(() => null);
@@ -261,3 +222,7 @@ export async function updateServerSettings(patch) {
 export function rotateServerAccessKey() {
   return postJSON('/api/settings/access-key', {});
 }
+
+export function logoutRemoteSession() {
+  return postJSON('/api/auth/logout', {});
+}

package/public/js/serverSettings.js

@@ -1,13 +1,13 @@
 // The Server drawer: the web face of the same config file the CLI wizard
 // writes. Reads come back with the key masked; saves send only the changed
-// keys; rotation reveals the new key once and stores it in this browser.
+// keys; rotation reveals the new key once and signs this browser in.
 //
 // The module owns its own DOM and its own round-trips. What it borrows from
 // app.js is the drawer choreography — one scrim at a time, Escape to close —
 // which is why it returns open/close/isOpen instead of wiring the topbar
 // button itself.
 
-import { getAccessKey, setAccessKey, fetchServerSettings, updateServerSettings, rotateServerAccessKey } from '/js/api.js';
+import { fetchServerSettings, updateServerSettings, rotateServerAccessKey, logoutRemoteSession } from '/js/api.js';
 
 // A function declaration, not a const arrow: the import-time DOM check in
 // tests/frontend.test.js blanks top-level function bodies but reads const
@@ -29,7 +29,7 @@ export function createServerDrawer(options = {}) {
   const dom = {};
   [
     'serverDrawer', 'serverScrim', 'serverClose', 'serverModeNote', 'srvMode', 'srvHost', 'srvPort',
-    'srvDomain', 'srvDomainField', 'srvHttps', 'srvHttpsField', 'srvHttpsStatus', 'srvAutoOpen', 'srvKeySection', 'srvKeyMasked', 'srvRotate',
+    'srvDomain', 'srvDomainField', 'srvHttps', 'srvHttpsField', 'srvHttpsStatus', 'srvAutoOpen', 'srvKeySection', 'srvKeyMasked', 'srvRotate', 'srvLogout',
     'srvFreshKeyRow', 'srvFreshKey', 'srvCopyKey', 'srvKeyHint', 'srvName', 'srvEmail',
     'srvTunnelCloudflare', 'srvTunnelCloudflareStatus', 'srvTunnelTailscale', 'srvTunnelTailscaleStatus',
     'srvSave', 'srvStatus', 'srvConfigPath',
@@ -74,9 +74,9 @@ export function createServerDrawer(options = {}) {
     tunnelLine(dom.srvTunnelTailscaleStatus, data.tunnels?.tailscale);
     dom.srvConfigPath.textContent = `Config file: ${data.configFile}`;
     dom.srvKeyMasked.value = s.accessKeyMasked || (s.hasAccessKey ? '' : '(none set — the API refuses every call)');
-    dom.srvKeyHint.textContent = getAccessKey()
-      ? 'This browser holds a key and sends it with every request.'
-      : 'This browser has no key saved. Paste one via rotate, or open the link from the startup banner.';
+    dom.srvKeyHint.textContent = s.hasAccessKey
+      ? 'Remote browsers sign in once; the key is exchanged for a secure HTTP-only session.'
+      : 'No key is set. Generate one before remote access is possible.';
     applyModeVisibility();
   }
 
@@ -145,9 +145,8 @@ export function createServerDrawer(options = {}) {
     status('Rotating…');
     try {
       const data = await rotateServerAccessKey();
-      // The one moment a key is ever shown. It goes straight into this
-      // browser's localStorage too, so this tab keeps working without a paste.
-      setAccessKey(data.accessKey);
+      // The server refreshes this browser's signed session as part of rotation.
+      // The raw key is shown once for copying elsewhere, never stored locally.
       render({ ...current, settings: data.settings });
       dom.srvFreshKey.value = data.accessKey;
       dom.srvFreshKeyRow.hidden = false; // render() does not know about the reveal
@@ -157,10 +156,20 @@ export function createServerDrawer(options = {}) {
     }
   }
 
+  async function signOut() {
+    try {
+      await logoutRemoteSession();
+      location.replace('/');
+    } catch (err) {
+      status(err.message, 'err');
+    }
+  }
+
   dom.srvMode.addEventListener('change', applyModeVisibility);
   dom.srvDomain.addEventListener('input', applyModeVisibility);
   dom.srvSave.addEventListener('click', save);
   dom.srvRotate.addEventListener('click', rotate);
+  dom.srvLogout.addEventListener('click', signOut);
   dom.serverClose.addEventListener('click', close);
   dom.serverScrim.addEventListener('click', close);
   dom.srvCopyKey.addEventListener('click', async () => {

package/public/login.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>Sign in · Onboarder</title>
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' fill='%23f7f4ed'/%3E%3Ccircle cx='9' cy='16' r='4' fill='none' stroke='%232a2721' stroke-width='2'/%3E%3Ccircle cx='24' cy='8' r='3.2' fill='none' stroke='%232e5d43' stroke-width='2'/%3E%3Ccircle cx='24' cy='24' r='3.2' fill='none' stroke='%232a2721' stroke-width='2'/%3E%3Cpath d='M13 14 L21 9 M13 18 L21 23' stroke='%232a2721' stroke-width='1.6'/%3E%3C/svg%3E">
+<style>
+:root{color-scheme:light dark;--paper:#f7f4ed;--paper2:#efe9dc;--card:#fffdf7;--ink:#2a2721;--ink2:#57503f;--faint:#8a8577;--line:rgba(42,39,33,.22);--accent:#2e5d43;--soft:#dce8d8;--warn:#a4442a;--serif:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,serif;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;--mono:ui-monospace,"SF Mono",Menlo,Consolas,monospace;--shadow:3px 3px 0 rgba(42,39,33,.9)}
+@media(prefers-color-scheme:dark){:root{color-scheme:dark;--paper:#211e19;--paper2:#292520;--card:#2b2721;--ink:#ece7db;--ink2:#c9c2b2;--faint:#9b9484;--line:rgba(236,231,219,.22);--accent:#8fbd9f;--soft:#243d2c;--warn:#d97b5a;--shadow:3px 3px 0 rgba(0,0,0,.6)}}
+*{box-sizing:border-box}.username-field{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}html,body{min-height:100%}body{margin:0;display:grid;place-items:center;padding:28px;overflow-x:hidden;background-color:var(--paper);background-image:radial-gradient(var(--line) .7px,transparent .7px);background-size:18px 18px;color:var(--ink);font-family:var(--sans)}.shell{width:min(100%,430px);position:relative}.shell:before{content:"";position:fixed;inset:14px;border:1px solid var(--line);pointer-events:none}.brand{display:flex;align-items:center;gap:10px;margin-bottom:18px}.mark{width:42px;height:42px;display:grid;place-items:center;background:var(--card);border:1.5px solid var(--ink);box-shadow:var(--shadow)}.mark svg{width:28px}.wordmark{font:600 25px/1 var(--serif)}.tagline{margin:5px 0 0;color:var(--faint);font-size:12px}.card{padding:clamp(25px,6vw,38px);background:var(--card);border:1.5px solid var(--ink);border-radius:10px;box-shadow:var(--shadow)}.eyebrow{display:flex;align-items:center;gap:7px;margin:0 0 13px;color:var(--accent);font:600 11px/1 var(--mono);letter-spacing:.08em;text-transform:uppercase}.eyebrow:before{content:"";width:7px;height:7px;border-radius:50%;background:currentColor}h1{margin:0;font:600 clamp(30px,8vw,40px)/1.03 var(--serif);letter-spacing:-.025em}.intro{margin:14px 0 24px;color:var(--ink2);font-size:14px;line-height:1.6}label{display:block;font:600 12px var(--mono)}.input-wrap{position:relative;margin-top:8px}input{width:100%;height:48px;padding:0 47px 0 13px;border:1.5px solid var(--ink);border-radius:5px;outline:0;background:var(--paper);color:var(--ink);font:14px var(--mono)}input:focus{border-color:var(--accent);box-shadow:0 0 0 3px var(--soft)}.toggle{position:absolute;top:5px;right:5px;width:38px;height:38px;border:0;border-radius:4px;background:transparent;color:var(--ink2);cursor:pointer}.toggle:hover,.toggle:focus-visible{background:var(--paper2);color:var(--ink);outline:0}.submit{width:100%;height:46px;margin-top:13px;border:1.5px solid var(--ink);border-radius:5px;background:var(--ink);color:var(--paper);font:600 12px var(--mono);cursor:pointer;transition:.08s}.submit:hover{transform:translate(-1px,-1px);box-shadow:2px 2px 0 var(--accent)}.submit:disabled{cursor:wait;opacity:.65}.message{min-height:21px;margin:13px 0 0;color:var(--warn);font-size:12.5px}.message[data-ok=true]{color:var(--accent)}.privacy{display:flex;gap:9px;margin:23px -4px 0;padding-top:17px;border-top:1px solid var(--line);color:var(--faint);font-size:11.5px;line-height:1.5}.privacy svg{flex:none;width:15px;margin-top:1px}.foot{margin:18px 0 0;text-align:center;color:var(--faint);font:10.5px var(--mono)}@media(max-width:480px){body{padding:20px;place-items:start center}.shell{margin:5vh 0}.shell:before{inset:8px}.card{padding:24px 20px}}
+</style>
+</head>
+<body>
+<main class="shell">
+  <div class="brand"><div class="mark" aria-hidden="true"><svg viewBox="0 0 32 32" fill="none" stroke="currentColor" stroke-width="1.8"><circle cx="9" cy="16" r="4"/><circle cx="24" cy="8" r="3.2" stroke="#2e5d43"/><circle cx="24" cy="24" r="3.2"/><path d="M13 14 21 9M13 18 21 23"/></svg></div><div><div class="wordmark">onboarder</div><p class="tagline">a map for any codebase</p></div></div>
+  <section class="card" aria-labelledby="loginTitle">
+    <p class="eyebrow">Private server</p><h1 id="loginTitle">Welcome back.</h1>
+    <p class="intro">This Onboarder instance is self-hosted. Enter its access key to open the codebase map.</p>
+    <form id="loginForm"><label for="accessKey">Access key</label><input id="username" name="username" type="text" value="onboarder" autocomplete="username" tabindex="-1" aria-hidden="true" class="username-field"><div class="input-wrap">
+      <input id="accessKey" name="accessKey" type="password" placeholder="ob_••••••••••••" autocomplete="current-password" autocapitalize="off" spellcheck="false" required autofocus>
+      <button class="toggle" id="toggleKey" type="button" aria-label="Show access key" aria-pressed="false"><svg width="19" height="19" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M2.5 12s3.5-6 9.5-6 9.5 6 9.5 6-3.5 6-9.5 6-9.5-6-9.5-6Z"/><circle cx="12" cy="12" r="2.5"/></svg></button>
+    </div><button class="submit" type="submit">Unlock Onboarder →</button><p class="message" id="message" role="status" aria-live="polite"></p></form>
+    <div class="privacy"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><rect x="5" y="10" width="14" height="10" rx="2"/><path d="M8 10V7a4 4 0 0 1 8 0v3"/></svg><span>Your key is exchanged for a secure, HTTP-only session. It is not stored in this page or added to the address bar.</span></div>
+  </section><p class="foot">Everything runs on your server.</p>
+</main>
+<script type="module">
+const form=document.getElementById('loginForm'),input=document.getElementById('accessKey'),message=document.getElementById('message'),toggle=document.getElementById('toggleKey'),submit=form.querySelector('.submit');
+toggle.addEventListener('click',()=>{const showing=input.type==='text';input.type=showing?'password':'text';toggle.setAttribute('aria-pressed',String(!showing));toggle.setAttribute('aria-label',showing?'Show access key':'Hide access key');input.focus()});
+form.addEventListener('submit',async event=>{event.preventDefault();const accessKey=input.value.trim();if(!accessKey)return;submit.disabled=true;message.textContent='Checking…';message.dataset.ok='false';try{const res=await fetch('/api/auth/login',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({accessKey})}),data=await res.json().catch(()=>({}));if(!res.ok)throw new Error(data.error||'That access key is not correct.');message.textContent='Key accepted. Opening Onboarder…';message.dataset.ok='true';window.location.replace('/')}catch(error){message.textContent=error.message;message.dataset.ok='false';input.select()}finally{submit.disabled=false}});
+</script>
+</body>
+</html>

package/server/apiAuth.js

@@ -0,0 +1,32 @@
+// The access-key form. Kept tiny and independent from the main app: an
+// unauthenticated visitor must be able to load this page without loading any
+// analyzer, settings drawer, or other application surface.
+
+import { accessKeysMatch, authReason } from './config.js';
+import { hasValidSession, sessionCookie } from './auth.js';
+import { sendError, sendJSON } from './http.js';
+
+export function handleAuthStatus(req, res, settings) {
+  sendJSON(res, 200, {
+    authenticated: !authReason(req, settings) || hasValidSession(req, settings),
+    configured: Boolean(settings.accessKey),
+  });
+}
+
+export function handleLogin(req, res, body, settings) {
+  if (!settings.accessKey) return sendError(res, 503, 'This server has no access key configured. Run `onboarder setup` on the server.');
+  if (!accessKeysMatch(settings.accessKey, body?.accessKey)) {
+    return sendError(res, 401, 'That access key is not correct.');
+  }
+  sendJSON(res, 200, { ok: true }, {
+    'cache-control': 'no-store',
+    'set-cookie': sessionCookie(req, settings),
+  });
+}
+
+export function handleLogout(req, res) {
+  sendJSON(res, 200, { ok: true }, {
+    'cache-control': 'no-store',
+    'set-cookie': sessionCookie(req, {}, { clear: true }),
+  });
+}

package/server/apiSettings.js

@@ -12,6 +12,7 @@ import {
   readSettings, updateSettings, writeSettings, configPath,
 } from './config.js';
 import { sendError, sendJSON } from './http.js';
+import { sessionCookie } from './auth.js';
 import { tunnelStatus } from './tunnel.js';
 import { httpsStatus } from './https.js';
 
@@ -96,7 +97,7 @@ export async function handleUpdateSettings(res, body, config) {
 // Rotation returns the new key in the clear, once. It is never in a GET after
 // that — `hasAccessKey`/`accessKeyMasked` are all the readback there is. The
 // person copies it from this response into the devices that need it.
-export async function handleRotateAccessKey(res, config) {
+export async function handleRotateAccessKey(req, res, config) {
   const file = settingsFile(config);
   if (!file) {
     return sendError(res, 400, 'This server was started without a config file, so there is nothing to save to.');
@@ -108,7 +109,10 @@ export async function handleRotateAccessKey(res, config) {
     sendJSON(res, 200, {
       accessKey,
       settings: publicSettings(next),
-      note: 'Shown once. Update every device that connects remotely; the old key is dead.',
+      note: 'Shown once. This browser is signed in with the new key; update every other device.',
+    }, {
+      'cache-control': 'no-store',
+      'set-cookie': sessionCookie(req, next),
     });
   } catch (err) {
     sendError(res, 400, err.message || 'The key could not be rotated.');

package/server/auth.js

@@ -0,0 +1,72 @@
+// Browser sessions for the self-hosted access-key gate.
+//
+// The access key itself never becomes a cookie. A successful login mints an
+// opaque timestamp + HMAC using the configured key as the signing secret. The
+// browser gets an HttpOnly cookie, JavaScript cannot read it, and rotating the
+// access key invalidates every old session immediately.
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export const SESSION_COOKIE = 'onboarder_session';
+export const SESSION_TTL_SECONDS = 7 * 24 * 60 * 60;
+
+function signature(expires, accessKey) {
+  return createHmac('sha256', accessKey)
+    .update(`onboarder-session-v1:${expires}`)
+    .digest('base64url');
+}
+
+export function createSession(settings, now = Date.now()) {
+  const key = String(settings?.accessKey || '');
+  if (!key) return '';
+  const expires = Math.floor(now / 1000) + SESSION_TTL_SECONDS;
+  return `${expires}.${signature(expires, key)}`;
+}
+
+function cookieValue(req, name) {
+  const header = String(req.headers?.cookie || '');
+  for (const part of header.split(';')) {
+    const at = part.indexOf('=');
+    if (at === -1) continue;
+    if (part.slice(0, at).trim() !== name) continue;
+    try { return decodeURIComponent(part.slice(at + 1).trim()); } catch { return ''; }
+  }
+  return '';
+}
+
+export function hasValidSession(req, settings, now = Date.now()) {
+  const key = String(settings?.accessKey || '');
+  const token = cookieValue(req, SESSION_COOKIE);
+  const dot = token.indexOf('.');
+  if (!key || dot < 1) return false;
+
+  const expires = Number(token.slice(0, dot));
+  const supplied = token.slice(dot + 1);
+  if (!Number.isSafeInteger(expires) || expires <= Math.floor(now / 1000) || !supplied) return false;
+
+  const expected = signature(expires, key);
+  const a = Buffer.from(supplied);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+function requestIsSecure(req) {
+  if (req.socket?.encrypted) return true;
+  const forwarded = String(req.headers?.['x-forwarded-proto'] || '').split(',')[0].trim().toLowerCase();
+  return forwarded === 'https';
+}
+
+export function sessionCookie(req, settings, { clear = false } = {}) {
+  const parts = [
+    `${SESSION_COOKIE}=${clear ? '' : encodeURIComponent(createSession(settings))}`,
+    'Path=/',
+    'HttpOnly',
+    'SameSite=Strict',
+    `Max-Age=${clear ? 0 : SESSION_TTL_SECONDS}`,
+  ];
+  // A direct bare-IP deployment may still be plain HTTP, where Secure would make
+  // the cookie unusable. Caddy forwards the original scheme, so domain HTTPS
+  // gets the production-safe flag automatically.
+  if (requestIsSecure(req)) parts.push('Secure');
+  return parts.join('; ');
+}

package/server/config.js

@@ -131,9 +131,7 @@ export function maskAccessKey(key) {
 }
 
 export function browserUrl(settings) {
-  const url = new URL(serverUrls(settings).local);
-  if (settings.mode === 'self-hosted' && settings.accessKey) url.searchParams.set('key', settings.accessKey);
-  return url.toString();
+  return new URL(serverUrls(settings).local).toString();
 }
 
 export function publicSettings(value = DEFAULT_SETTINGS) {
@@ -192,16 +190,11 @@ export function allowedHosts(value = DEFAULT_SETTINGS) {
     // A wildcard bind is useful as a literal Host value to diagnostics, even
     // though browsers normally address the machine by one of its real IPs.
     hosts.add(settings.host.toLowerCase());
-    if (settings.host === '0.0.0.0') {
-      // A cloud VPS commonly reaches its public address through provider NAT,
-      // so that address is not present in os.networkInterfaces(). These markers
-      // let the guard accept an IP literal without accepting arbitrary domains.
-      hosts.add('ipv4:*');
-      for (const ip of ownInterfaceHosts()) if (!ip.includes(':')) hosts.add(ip);
-    } else if (settings.host === '::') {
-      hosts.add('ipv6:*');
-      for (const ip of ownInterfaceHosts()) if (ip.includes(':')) hosts.add(ip);
-    }
+    // Any network bind can sit behind NAT: a VPS may be configured as a private
+    // interface address while browsers address its public/NAT IP. Accept every IP
+    // literal, never arbitrary DNS names; the access key protects remote data.
+    hosts.add('ip:*');
+    for (const ip of ownInterfaceHosts()) if (!isLoopbackHost(ip)) hosts.add(ip);
   }
   if (settings.tunnel.cloudflare) hosts.add('*.trycloudflare.com');
   if (settings.tunnel.tailscale) hosts.add('*.ts.net');
@@ -220,9 +213,20 @@ export function bearerToken(req) {
   return match ? match[1].trim() : '';
 }
 
+export function requestIsLoopback(req) {
+  const remote = String(req.socket?.remoteAddress || '').replace(/^::ffff:/, '');
+  return remote === '127.0.0.1' || remote === '::1';
+}
+
 export function authReason(req, settings = DEFAULT_SETTINGS) {
   const normalized = normalizeSettings(settings);
   if (normalized.mode !== 'self-hosted') return null;
+  // A self-hosted server can still be opened on the same machine. Caddy and
+  // tunnels arrive from loopback but keep the public Host, so both signals must
+  // agree before a login page is skipped.
+  const host = String(req.headers?.host || '').toLowerCase();
+  const hostIsLoopback = isLoopbackHost(host.replace(/:\d+$/, '')) || /^localhost:\d+$/.test(host);
+  if (requestIsLoopback(req) && hostIsLoopback) return null;
   if (!normalized.accessKey) return 'Self-hosted mode has no access key configured.';
   const token = bearerToken(req);
   if (!accessKeysMatch(normalized.accessKey, token)) return 'A valid access key is required.';

package/server/http.js

@@ -37,8 +37,8 @@ export function readBody(req, limit = MAX_BODY_BYTES) {
   });
 }
 
-export function sendJSON(res, status, data) {
-  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+export function sendJSON(res, status, data, headers = {}) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', ...headers });
   res.end(JSON.stringify(data));
 }
 

package/server/httpGuards.js

@@ -43,6 +43,7 @@ export function rebindingReason(req, extraHosts = []) {
   const name = hostnameOf(host);
   if (LOOPBACK_HOSTS.has(name)) return null;
   for (const extra of extraHosts) {
+    if (extra === 'ip:*' && net.isIP(name.replace(/^\[|\]$/g, '')) > 0) return null;
     if (extra === 'ipv4:*' && net.isIP(name) === 4) return null;
     if (extra === 'ipv6:*' && net.isIP(name.replace(/^\[|\]$/g, '')) === 6) return null;
     if (extra.startsWith('*.')) {

package/server/index.js

@@ -82,7 +82,7 @@ export function startupBanner(settings, { configFile } = {}) {
     }
   }
   if (settings.mode === 'self-hosted' && settings.accessKey) {
-    lines.push('  Browser this URL is opened with the access key automatically; the key is removed from the address bar.');
+    lines.push('  Remote browsers show an access-key sign-in page; the key is never put in the URL.');
   }
   if (settings.mode === 'self-hosted' && !settings.accessKey) {
     lines.push('  WARNING self-hosted with no access key — every API call is refused until one is set.');
@@ -176,8 +176,8 @@ export async function startServer({ configFile = configPath(), openBrowser, log
   log(startupBanner(live, { configFile }));
 
   const shouldOpen = openBrowser ?? (live.autoOpen && process.stdout.isTTY && !process.env.NO_OPEN);
-  // The browser adopts a self-hosted key from the query string, stores it locally,
-  // and removes the secret from the visible URL before any API request.
+  // Local requests never need a credential. Remote browsers are sent to the
+  // themed login page and exchange the key for an HttpOnly session cookie.
   if (shouldOpen) openInBrowser(browserUrl(live));
   return { server, settings: live, host, port };
 }

package/server/router.js

@@ -1,16 +1,14 @@
-// The route table and the two gates in front of it.
+// The route table and the gates in front of it.
 //
 // Everything arrives here: one function decides whether a request is allowed to
 // be answered at all, then which handler answers it. The routes are a list rather
 // than a ladder of `if` statements so that the whole surface of the server is
-// visible in one screen — six endpoints, and everything else is a static file.
+// visible in one screen, and everything else is a static file.
 //
-// Neither gate is authentication. A local server with no accounts cannot
-// authenticate anyone; what it can do is refuse requests that a browser on some
-// other site made on the person's behalf. `server/httpGuards.js` explains both
-// attacks; the short version is that `Host` stops DNS rebinding from turning
-// `evil.com` into our own origin, and `Origin`/`Sec-Fetch-Site` stops a page the
-// person happened to have open from driving the API.
+// There are three concerns. Local mode relies on `Host`, `Origin`, and
+// `Sec-Fetch-Site` to stop another page and DNS rebinding from driving it.
+// Self-hosted mode adds real access-key authentication: local browser requests
+// stay open, remote browsers get a signed session, and API clients use Bearer.
 
 import { handleDocs } from './apiDocs.js';
 import { handleFile } from './apiFile.js';
@@ -25,7 +23,9 @@ import { handleDiff, handleDiffRefs } from './apiDiff.js';
 import { handleToolsInstall, handleToolsRun, handleToolsStatus } from './apiTools.js';
 import { handleMcpStart, handleMcpStatus, handleMcpStop, handleMcpCommand } from './apiMcp.js';
 import { handleGetSettings, handleRotateAccessKey, handleUpdateSettings } from './apiSettings.js';
-import { allowedHosts, authReason, DEFAULT_SETTINGS } from './config.js';
+import { handleAuthStatus, handleLogin, handleLogout } from './apiAuth.js';
+import { accessKeysMatch, allowedHosts, authReason, bearerToken, DEFAULT_SETTINGS } from './config.js';
+import { hasValidSession } from './auth.js';
 
 const ROUTES = [
   {
@@ -110,6 +110,18 @@ const ROUTES = [
     method: 'GET', path: '/api/health',
     run: ({ res }) => sendJSON(res, 200, { ok: true }),
   },
+  {
+    method: 'GET', path: '/api/auth/status', sameOrigin: true,
+    run: ({ req, res, settings }) => handleAuthStatus(req, res, settings),
+  },
+  {
+    method: 'POST', path: '/api/auth/login', body: true, sameOrigin: true,
+    run: ({ req, res, body, settings }) => handleLogin(req, res, body, settings),
+  },
+  {
+    method: 'POST', path: '/api/auth/logout', body: true, sameOrigin: true,
+    run: ({ req, res }) => handleLogout(req, res),
+  },
   {
     // The settings drawer and the CLI read the same public shape: everything
     // about the configuration except the access key itself.
@@ -128,7 +140,7 @@ const ROUTES = [
     // this response, never readable again. In self-hosted mode this endpoint
     // is itself behind the current key, so rotation requires possession.
     method: 'POST', path: '/api/settings/access-key', body: true,
-    run: ({ res, config }) => handleRotateAccessKey(res, config),
+    run: ({ req, res, config }) => handleRotateAccessKey(req, res, config),
   },
 ];
 
@@ -184,6 +196,7 @@ export function createRouter(config) {
       }
 
       const found = matchRoute(req.method, url.pathname);
+      const publicAuthRoute = ['/api/health', '/api/auth/status', '/api/auth/login', '/api/auth/logout'].includes(url.pathname);
       if (req.method !== 'GET' || found?.route.sameOrigin) {
         const foreign = crossOriginReason(req);
         if (foreign) {
@@ -191,18 +204,34 @@ export function createRouter(config) {
         }
       }
 
-      // The self-hosted gate. It is authentication, unlike the two guards
-      // above: the mode says the network can reach us, so every API call
-      // proves it holds the access key. `/api/health` stays open — a tunnel
-      // or uptime check has no key and tells an attacker nothing.
-      if (found && url.pathname.startsWith('/api/') && url.pathname !== '/api/health') {
-        const denied = authReason(req, settings);
-        if (denied) return sendError(res, 401, denied);
+      // Bearer clients keep their existing API contract. A browser gets a signed,
+      // HttpOnly session from the login form instead of storing the raw key.
+      const bearerClient = accessKeysMatch(settings.accessKey, bearerToken(req));
+      const browserAuthenticated = hasValidSession(req, settings);
+      const authDenied = authReason(req, settings);
+      const locallyExempt = !authDenied;
+      const authenticated = bearerClient || browserAuthenticated || locallyExempt;
+      const remoteSelfHosted = settings.mode === 'self-hosted' && Boolean(authDenied);
+
+      if (remoteSelfHosted && !authenticated && !publicAuthRoute) {
+        // API callers keep a machine-readable 401. A browser navigation gets the
+        // themed sign-in document so the user never has to paste JSON into a tab.
+        const accepts = String(req.headers?.accept || '');
+        if (req.method === 'GET' && (url.pathname === '/' || accepts.includes('text/html'))) {
+          res.statusCode = 200;
+          return await serveStatic(res, '/login.html', config);
+        }
+        return sendError(res, 401, authDenied || 'Sign in with the Onboarder access key first.');
+      }
+
+      if (url.pathname === '/api/auth/logout') {
+        // Always clear the browser cookie, even if it had already expired.
+        return handleLogout(req, res);
       }
 
       if (found) {
         const body = found.route.body ? await readBody(req) : null;
-        return await found.route.run({ req, res, url, body, rest: found.rest, config });
+        return await found.route.run({ req, res, url, body, rest: found.rest, config, settings });
       }
 
       if (req.method === 'GET') return await serveStatic(res, url.pathname, config);