codebase-onboarder 0.3.0 → 0.4.0

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/daemon.js

@@ -0,0 +1,195 @@
+// Running the server without the terminal that asked for it.
+//
+// `onboarder start` keeps the process attached: closing the shell kills it, and
+// that is the right behavior for a foreground command. `onboarder start
+// background` wants the opposite — the whole point is that the terminal can go
+// away — so this module does what a shell job control cannot do portably: it
+// re-launches the CLI as a **detached** child with its stdio pointed at a log
+// file, unrefs it, and then waits for the port to actually answer before it
+// claims success.
+//
+// Two rules keep this honest:
+//
+//   1. Never report "running" on the strength of the spawn alone. `spawn`
+//      returning a pid proves a process was created, not that it bound the port
+//      or survived settings validation. Readiness is an HTTP answer from
+//      `/api/health`, polled with a deadline; on timeout the caller gets the
+//      child's last log lines, not a false green light.
+//   2. Detach properly, or "background" is a lie. `detached: true` puts the
+//      child in its own process group, and `unref()` drops our handle on it, so
+//      a Ctrl-C in the parent terminal does not take the server down with it.
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { configPath } from './config.js';
+import { readPidFile } from './pidfile.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+// The installed entry point, not `process.argv[1]`: a globally installed
+// `onboarder` is a symlink into node_modules, and the child has to run the real
+// file to find its siblings.
+export const CLI_ENTRY = path.resolve(HERE, '..', 'bin', 'onboarder.js');
+
+// One file per config, beside the config, so `--config` isolation (tests,
+// containers, several profiles) carries the log with it.
+export function logPath(configFile = configPath()) {
+  return path.join(path.dirname(path.resolve(configFile)), 'onboarder.log');
+}
+
+// Rotated history. One generation is deliberate: a log that grows without bound
+// is a bug report waiting to happen, and one previous file is enough to see what
+// happened just before a crash.
+export const MAX_LOG_BYTES = 2 * 1024 * 1024;
+
+export async function rotateLogIfNeeded(file = logPath(), maxBytes = MAX_LOG_BYTES) {
+  try {
+    const { size } = await fsp.stat(file);
+    if (size <= maxBytes) return false;
+    await fsp.rename(file, file + '.1');
+    return true;
+  } catch {
+    return false; // no log yet, or not ours to move
+  }
+}
+
+export async function readLog(file = logPath(), bytes = 64 * 1024) {
+  try {
+    const handle = await fsp.open(file, 'r');
+    try {
+      const { size } = await handle.stat();
+      const start = Math.max(0, size - bytes);
+      const buffer = Buffer.alloc(size - start);
+      await handle.read(buffer, 0, buffer.length, start);
+      return buffer.toString('utf8');
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    return '';
+  }
+}
+
+// The last `count` lines, oldest first — the shape `onboarder logs` prints and
+// the shape an error report wants pasted into it.
+export async function tailLog(file = logPath(), count = 40) {
+  const text = await readLog(file);
+  const lines = text.split('\n').filter((line) => line.trim());
+  return lines.slice(-Math.max(1, count));
+}
+
+export async function logExists(file = logPath()) {
+  try { await fsp.access(file); return true; } catch { return false; }
+}
+
+// Ask the server whether it is up. A 2xx–4xx from /api/health means the socket
+// is bound and the router is serving; the body is not interesting, the answer is.
+export function probe(url, timeoutMs = 1000) {
+  return new Promise((resolve) => {
+    const request = http.get(url, { timeout: timeoutMs }, (res) => {
+      res.resume();
+      resolve(res.statusCode >= 200 && res.statusCode < 500);
+    });
+    request.on('timeout', () => { request.destroy(); resolve(false); });
+    request.on('error', () => resolve(false));
+  });
+}
+
+export async function waitForReady(url, { timeoutMs = 20000, intervalMs = 200, check = probe } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (await check(url)) return true;
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+
+// Re-run this same CLI, detached. The child is a plain foreground `start` — it
+// writes the pid file, prints its own banner, and handles signals exactly as it
+// always has. Nothing about the server changes; only who is holding the terminal
+// does.
+export function spawnDetached({ configFile = configPath(), entry = CLI_ENTRY, env = process.env, log = logPath(configFile) } = {}) {
+  const fd = fs.openSync(log, 'a');
+  try {
+    const child = spawn(process.execPath, [entry, 'start', '--config', configFile], {
+      detached: true,
+      stdio: ['ignore', fd, fd],
+      env: { ...env, ONBOARDER_BACKGROUND: '1' },
+    });
+    child.on('error', () => {});
+    child.unref();
+    return child.pid;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// Does the OS still have this process? Signal 0 asks without delivering.
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+// Wait for the detached child to become the *recorded* server. The pid file is
+// the authority here, not the spawn pid: it is what `status` and `stop` read,
+// so waiting on it means the process we report is the one the user can control.
+export async function waitForPidFile(configFile, { timeoutMs = 20000, intervalMs = 150, readPid = readPidFile, isAlive = alive } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const pid = readPid(configFile);
+    if (pid && isAlive(pid)) return pid;
+    if (Date.now() >= deadline) return null;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+
+// Follow a growing file. Polling rather than fs.watch: the log is appended by a
+// *different* process, and watchers on a file another process holds open are
+// unreliable across platforms (and absent on some network mounts). Half a second
+// of latency on a human-facing log tail is invisible.
+export function followLog(file, onLine, { intervalMs = 500, from = 'end' } = {}) {
+  let position = 0;
+  let partial = '';
+  let stopped = false;
+  const stop = () => { stopped = true; };
+
+  if (from === 'start') {
+    fsp.readFile(file, 'utf8').then(
+      (text) => { for (const line of text.split('\n')) if (line) onLine(line); },
+      () => {},
+    );
+  }
+
+  const tick = async () => {
+    if (stopped) return;
+    try {
+      const { size } = await fsp.stat(file);
+      if (size < position) { position = 0; partial = ''; } // rotated under us
+      if (size > position) {
+        const handle = await fsp.open(file, 'r');
+        try {
+          const length = size - position;
+          const buffer = Buffer.alloc(length);
+          await handle.read(buffer, 0, length, position);
+          position = size;
+          // A read can land mid-line; hold the remainder until its newline shows.
+          const lines = (partial + buffer.toString('utf8')).split('\n');
+          partial = lines.pop() ?? '';
+          for (const line of lines) onLine(line);
+        } finally {
+          await handle.close();
+        }
+      }
+    } catch {
+      // The file may not exist yet (first run) — try again on the next tick.
+    }
+    if (!stopped) setTimeout(tick, intervalMs).unref();
+  };
+
+  setTimeout(tick, intervalMs).unref();
+  return stop;
+}