codebase-onboarder 0.2.0 → 0.3.1

package/README.md

@@ -3,7 +3,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
 [![Zero Dependencies](https://img.shields.io/badge/runtime%20dependencies-0-success.svg)](package.json)
-[![Tests](https://img.shields.io/badge/tests-551%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-560%20passing-brightgreen.svg)](tests/)
 
 > **Drop a path. Get a map.**  
 > A lightweight, zero-dependency codebase visualizer and architectural map generator that runs entirely on your local machine.
@@ -202,12 +202,12 @@ 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** — reachable on your network or domain; every API call requires a Bearer access key. Rotate it from the drawer or with `onboarder config key rotate`; the old key dies on the next request, no restart needed.
+- **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
 onboarder setup --mode self-hosted \
-  --domain map.example.com --non-interactive
+  --domain map.example.com --https --start
 onboarder config show                    # current settings (key masked)
 onboarder config set host 0.0.0.0        # direct VPS/LAN access (domain optional)
 onboarder config set port 4311           # move away from a busy port
@@ -216,14 +216,33 @@ onboarder status                         # running PID, stopped, or unmanaged po
 onboarder stop                           # stop a PID-file-managed instance
 onboarder restart                        # graceful stop, then start
 onboarder tunnel cloudflare              # expose via a Cloudflare quick tunnel
-onboarder doctor                         # config, port, reachability, and tunnel checks
+onboarder tunnel tailscale               # expose privately over the tailnet
+onboarder https check                    # DNS, ports 80/443, and Caddy readiness
+onboarder https setup                    # write/validate Caddyfile, obtain TLS, reload/start Caddy
+onboarder https status                   # domain, URL, Caddyfile, and Caddy state
+onboarder doctor                         # config, access key, ports, DNS, TLS, and tunnels
 ```
 
-Direct self-hosting does not require DNS: `--host 0.0.0.0` accepts visitors at `http://<server-ip>:<port>`. Put a reverse proxy and TLS in front of it for production. Binding to `127.0.0.1` is still the safer default and is appropriate behind Cloudflare or Tailscale.
+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:
+
+```bash
+sudo apt update
+sudo apt install caddy
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+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 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.
 
-Cloudflare quick tunnels and Tailscale are supported as reachability layers — the server keeps its loopback bind and the tunnel dials `127.0.0.1`. `ONBOARDER_CONFIG=/path/config.json` overrides the config location (handy for tests and containers).
+Cloudflare quick tunnels and Tailscale remain supported. They terminate TLS and dial `127.0.0.1`, so an existing loopback setup is preserved. `ONBOARDER_CONFIG=/path/config.json` overrides the config location for tests and containers.
 
 ---
 
@@ -237,9 +256,12 @@ 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
 │   ├── httpGuards.js# Host verification & CSRF/rebinding guards
 │   ├── apiScan.js   # Local & remote scan coordination
 │   ├── apiFile.js   # Path-traversal safe file serving
@@ -251,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 (551 unit tests)
+│   ├── index.html   # Main application interface
+│   └── login.html   # Self-hosted access-key sign-in
+└── tests/           # Comprehensive node:test suite (565 tests)
 ```
 
 ---
@@ -262,7 +285,7 @@ codebase-onboarder/
 Onboarder includes a comprehensive automated test suite built with Node's native test runner:
 
 ```bash
-# Run all 551 tests
+# Run all 565 tests
 npm test
 ```
 

package/cli/commands.js

@@ -17,8 +17,9 @@ import {
 import { startServer } from '../server/index.js';
 import { pidIsAlive, readPidFile, removePidFile } from '../server/pidfile.js';
 import { tunnelStatus, cloudflareCommand, tailscaleCommand, installHint, findOnPath } from '../server/tunnel.js';
+import { caddyRun, caddyValidate, httpsReadiness, httpsStatus, writeCaddyfile } from '../server/https.js';
 import { bold, cyan, dim, ok, warn, bad, kv, tick, cross, dash, welcomeBanner } from './ui.js';
-import { buildSteps, pendingSteps, defaultOf, applyFlags, answersToSettings, summaryLines } from './wizard.js';
+import { buildSteps, unansweredSteps, defaultOf, applyFlags, answersToSettings, summaryLines } from './wizard.js';
 import { runSteps, WizardCancelled } from './prompt.js';
 
 // ---------------------------------------------------------------- setup ---
@@ -49,7 +50,7 @@ export async function runSetup({ flags = {}, out = console.log, err = console.er
 
   // Flag answers go in first; the wizard only asks what is left.
   const seed = {};
-  for (const id of ['name', 'email', 'mode', 'host', 'port', 'domain', 'autoOpen']) {
+  for (const id of ['name', 'email', 'mode', 'host', 'port', 'domain', 'https', 'autoOpen']) {
     if (flags[id] !== undefined) seed[id] = flags[id];
   }
   if (flags.provider !== undefined) seed.provider = flags.provider;
@@ -58,7 +59,7 @@ export async function runSetup({ flags = {}, out = console.log, err = console.er
 
   let answers;
   try {
-    answers = await runSteps(pendingSteps(buildSteps(current), seed), seed);
+    answers = await runSteps(unansweredSteps(buildSteps(current), seed), seed);
   } catch (e) {
     if (e instanceof WizardCancelled) {
       err('\n  Setup cancelled — nothing was written.');
@@ -98,7 +99,9 @@ export async function runSetup({ flags = {}, out = console.log, err = console.er
     out('');
     return runStart({ flags, out, err });
   }
-  out(dim('  Later: `onboarder start`'));
+  out(dim(settings.https
+    ? '  Later: `onboarder start` (starts Caddy automatically), or `onboarder https status`'
+    : '  Later: `onboarder start`'));
   return 0;
 }
 
@@ -163,6 +166,14 @@ export async function runStart({ flags = {}, out = console.log, err = console.er
   if (recorded) removePidFile(file, recorded);
 
   const started = await startServer({ configFile: file, log: out });
+  if (started.settings.https) {
+    out('');
+    const httpsCode = await runHttps('setup', { flags, out: flags.json ? () => {} : out, err });
+    if (httpsCode !== 0) {
+      await new Promise((resolve) => started.server.close(resolve));
+      return httpsCode;
+    }
+  }
   if (flags.json) out(JSON.stringify({ host: started.host, port: started.port, url: serverUrls(started.settings).local }));
   // The listening server holds the event loop; resolve so callers/tests know
   // we are up, but leave the process running.
@@ -272,6 +283,7 @@ const SETTABLE = {
   host: (v) => v,
   port: (v) => { const n = Number(v); if (!Number.isInteger(n) || n < 1 || n > 65535) throw new Error('port must be 1-65535.'); return n; },
   domain: (v) => v,
+  https: (v) => ['true', 'yes', '1', 'on'].includes(String(v).toLowerCase()),
   autoOpen: (v) => ['true', 'yes', '1', 'on'].includes(String(v).toLowerCase()),
   'account.name': (v) => v,
   'account.email': (v) => v,
@@ -313,6 +325,7 @@ export async function runConfig(sub, args, { flags = {}, out = console.log } = {
       out(kv('Mode', settings.mode));
       out(kv('Bind', `${settings.host}:${settings.port}`));
       if (settings.domain) out(kv('Domain', settings.domain));
+      out(kv('HTTPS', settings.https ? `enabled — ${urls.domain}` : settings.domain ? 'disabled (plain HTTP)' : 'no domain configured'));
       out(kv('Local', urls.local));
       if (urls.network) out(kv('Network', urls.network));
       if (urls.domain) out(kv('Public', urls.domain));
@@ -447,14 +460,24 @@ export async function runDoctor({ flags = {}, out = console.log } = {}) {
         id: 'domain', ok: true, required: false,
         detail: settings.domain || (loopback ? '(none — a tunnel or local reverse proxy provides the name)' : '(none — visitors can connect by server IP)'),
       });
+      if (settings.https) {
+        const readiness = await httpsReadiness(settings, { configFile: file });
+        for (const check of readiness.checks.slice(1).filter((item) => item.id !== 'caddy')) {
+          checks.push({ ...check, required: check.id !== 'dns-target' });
+        }
+      }
     }
   }
 
-  for (const name of ['git', 'cloudflared', 'tailscale']) {
-    const wanted = name === 'git' || (settings && settings.tunnel?.[name === 'cloudflared' ? 'cloudflare' : 'tailscale']);
+  for (const name of ['git', 'cloudflared', 'tailscale', 'caddy']) {
+    const wanted = name === 'git'
+      || (name === 'caddy' && settings?.https)
+      || (settings && settings.tunnel?.[name === 'cloudflared' ? 'cloudflare' : 'tailscale']);
     const found = Boolean(findOnPath(name));
     checks.push({
-      id: name, ok: found || !wanted, required: name === 'git',
+      id: name,
+      ok: found || !wanted,
+      required: name === 'git' || (name === 'caddy' && settings?.https),
       detail: found ? 'installed' : wanted ? 'not installed — ' + installHint(name) : 'not installed (not needed for your settings)',
     });
   }
@@ -481,6 +504,92 @@ function portIsFree(host, port) {
   });
 }
 
+// ------------------------------------------------------------------ https ---
+
+export async function runHttps(action = 'status', { flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  const settings = await readSettings(file);
+  const status = httpsStatus(settings, file);
+  if (action === 'status') {
+    if (flags.json) out(JSON.stringify(status, null, 2));
+    else {
+      out('');
+      out(bold('  Onboarder HTTPS'));
+      out(kv('Enabled', status.enabled ? 'yes' : 'no'));
+      out(kv('Domain', status.domain || '(not configured)'));
+      out(kv('URL', status.url || '(none)'));
+      out(kv('Caddy', status.caddyInstalled ? status.caddyVersion : 'not installed'));
+      out(kv('Caddyfile', status.caddyfile));
+      if (status.enabled) out(dim('    `onboarder https check` verifies DNS and ports before issuance.'));
+      out('');
+    }
+    return status.enabled ? 0 : 1;
+  }
+  if (action === 'check') {
+    const readiness = await httpsReadiness(settings, { configFile: file });
+    if (flags.json) out(JSON.stringify(readiness, null, 2));
+    else {
+      out('');
+      out(bold('  HTTPS readiness'));
+      for (const check of readiness.checks) out(`${check.ok ? tick : check.required ? cross : dash}${check.id} — ${check.detail}`);
+      if (!readiness.ok) {
+        out('');
+        out(warn('  Fix the required items, then run `onboarder https setup` again.'));
+        out(dim('    DNS: point an A/AAAA record to this VPS. Firewall: allow inbound 80 and 443.'));
+      }
+      out('');
+    }
+    return readiness.ok ? 0 : 1;
+  }
+  if (action === 'setup' || action === 'start') {
+    const readiness = await httpsReadiness(settings, { configFile: file });
+    if (!readiness.ok) {
+      err(bad('  HTTPS setup is not ready:'));
+      for (const check of readiness.checks.filter((item) => item.required && !item.ok)) err(cross + check.id + ' — ' + check.detail);
+      err('    Point DNS at this VPS, allow inbound TCP 80/443, install Caddy, then retry.');
+      return 1;
+    }
+    const caddyfile = await writeCaddyfile(settings, file);
+    out(dim('  Caddyfile: ' + caddyfile));
+    await caddyValidate(settings, file);
+
+    // Ubuntu's package usually leaves Caddy running as a service. Reload first
+    // so repeat setup is idempotent and does not mistake Caddy for a foreign
+    // listener. Reload talks only to Caddy's local admin endpoint and never
+    // stops an unknown process.
+    let result;
+    let reloaded = false;
+    try {
+      result = caddyRun(settings, file, 'reload');
+      reloaded = true;
+    } catch {
+      try {
+        result = caddyRun(settings, file, 'start');
+      } catch (error) {
+        err(bad('  Caddy could not start: ' + (error.message || error)));
+        if (process.platform !== 'win32') {
+          err('    On Ubuntu, start the packaged service once:');
+          err('      sudo systemctl enable --now caddy');
+          err('    Then run `onboarder https setup` again.');
+        }
+        return 1;
+      }
+    }
+    out(tick + (reloaded ? 'Caddy reloaded. It is using' : 'Caddy started. It is using') + ' https://' + settings.domain + '.');
+    out('    Public URL  https://' + settings.domain);
+    out(dim('    Upstream     http://127.0.0.1:' + settings.port));
+    if (result.output) out(dim('    ' + result.output.split('\n').slice(-3).join('\n    ')));
+    return 0;
+  }
+  if (action === 'stop') {
+    if (!status.caddyInstalled) { err('  Caddy is not installed.'); return 1; }
+    caddyRun(settings, file, 'stop');
+    out(tick + 'Caddy stopped. The Onboarder HTTP server is unchanged.');
+    return 0;
+  }
+  throw new Error('Usage: onboarder https <check|setup|start|stop|status>');
+}
+
 // --------------------------------------------------------------- tunnel ---
 
 export async function runTunnel(kind, { flags = {}, out = console.log, err = console.error } = {}) {
@@ -519,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/cli/main.js

@@ -9,7 +9,7 @@ import { parseArgs } from 'node:util';
 
 import {
   runSetup, runStart, runStatus, runStop, runRestart,
-  runConfig, runConfigKey, runConfigReset, runDoctor, runTunnel,
+  runConfig, runConfigKey, runConfigReset, runDoctor, runTunnel, runHttps,
 } from './commands.js';
 
 const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -26,10 +26,12 @@ const HELP = `
     onboarder restart             Stop and start again
     onboarder config [<…>]         show | get <key> | set <key> <value> | path | reset | key <rotate|show|set>
     onboarder tunnel <name>       cloudflare | tailscale
+    onboarder https <action>      check | setup | start | stop | status
     onboarder doctor              Check the machine and the config
 
   Setup flags (interactive wizard skips what they answer)
     --mode local|self-hosted   --host <addr>   --port <n>   --domain <name>
+    --https                    Set up automatic HTTPS through Caddy
     --access-key generate|<k>  --name <n>   --email <e>
     --provider none|openai-compatible|ollama|openrouter|custom
     --base-url <url>   --model <m>   --cloudflare   --tailscale
@@ -50,7 +52,8 @@ const HELP = `
   Examples
     onboarder setup
     onboarder setup --non-interactive --mode local --port 4310
-    onboarder setup --non-interactive --mode self-hosted --domain map.example.com --access-key generate
+    onboarder setup --non-interactive --mode self-hosted --host 0.0.0.0
+    onboarder setup --non-interactive --mode self-hosted --domain map.example.com --https --start
     onboarder config set tunnel.cloudflare true && onboarder tunnel cloudflare
 `;
 
@@ -69,6 +72,7 @@ const OPTIONS = {
   host: { type: 'string' },
   port: { type: 'string' },
   domain: { type: 'string' },
+  https: { type: 'boolean' },
   'access-key': { type: 'string' },
   name: { type: 'string' },
   email: { type: 'string' },
@@ -129,6 +133,8 @@ export async function main(argv = process.argv.slice(2)) {
         return codeOf(await runConfig(sub || 'show', rest, { flags }));
       case 'tunnel':
         return codeOf(await runTunnel(sub, { flags }));
+      case 'https':
+        return codeOf(await runHttps(sub || 'status', { flags }));
       case 'doctor':
         return codeOf(await runDoctor({ flags }));
       default:

package/cli/wizard.js

@@ -99,10 +99,15 @@ export function buildSteps(current = DEFAULT_SETTINGS) {
       id: 'host', section: 'Server', type: 'choice',
       question: 'What should the server bind to?',
       choices: [
-        { value: '127.0.0.1', label: 'Loopback, behind a tunnel (recommended)', hint: 'Cloudflare or Tailscale terminates TLS and dials 127.0.0.1' },
-        { value: '0.0.0.0', label: 'Every interface (LAN)', hint: 'other machines on this network reach it directly — plain HTTP, so front it with a domain + proxy for TLS' },
+        { value: '127.0.0.1', label: 'Loopback only — behind Cloudflare or Tailscale', hint: 'safest remote layout; the tunnel/proxy connects to 127.0.0.1' },
+        { value: '0.0.0.0', label: 'Every interface — direct public/LAN access', hint: 'accessible by server IP; recommended for a cloud VPS' },
       ],
-      default: current.host === '0.0.0.0' ? '0.0.0.0' : '127.0.0.1',
+      default: (answers) => {
+        const currentHost = current.host;
+        if (answers.host) return answers.host;
+        if (current.mode === 'self-hosted' && ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(currentHost)) return currentHost;
+        return '0.0.0.0';
+      },
       when: (a) => a.mode === 'self-hosted',
     },
     {
@@ -113,12 +118,19 @@ export function buildSteps(current = DEFAULT_SETTINGS) {
     },
     {
       id: 'domain', section: 'Server', type: 'text',
-      question: 'Domain (optional; not needed when reached by IP or behind a tunnel)',
-      hint: 'e.g. map.example.com — use a hostname only when visitors will connect by domain',
+      question: 'Domain (optional for direct IP or a tunnel)',
+      hint: 'e.g. map.example.com — point an A/AAAA record to this VPS to enable trusted HTTPS',
       default: current.domain || '',
       validate: validDomain,
       when: (a) => a.mode === 'self-hosted',
     },
+    {
+      id: 'https', section: 'HTTPS', type: 'confirm',
+      question: 'Set up automatic HTTPS with Caddy?',
+      hint: 'Caddy obtains and renews the certificate, proxies 80/443, and sends traffic to this app',
+      default: Boolean(current.domain && current.https),
+      when: (a) => a.mode === 'self-hosted' && Boolean(a.domain),
+    },
     {
       id: 'keyChoice', section: 'Security', type: 'choice',
       question: 'Access key — the one credential remote devices must hold',
@@ -231,9 +243,10 @@ export function answersToSettings(current, answers) {
   return normalizeSettings({
     version: current.version,
     mode: selfHosted ? 'self-hosted' : 'local',
-    host: selfHosted ? (answers.host || current.host || '127.0.0.1') : '127.0.0.1',
+    host: selfHosted ? (answers.host || '0.0.0.0') : '127.0.0.1',
     port: Number(answers.port ?? current.port ?? DEFAULT_SETTINGS.port),
     domain: selfHosted ? String(answers.domain ?? current.domain ?? '').trim().toLowerCase() : '',
+    https: selfHosted && Boolean(answers.domain) && Boolean(answers.https),
     accessKey,
     autoOpen: answers.autoOpen ?? current.autoOpen ?? false,
     account,
@@ -265,6 +278,7 @@ export function applyFlags(current, flags = {}) {
     if (err) throw new Error('--domain: ' + err);
     patch.domain = String(flags.domain).trim().toLowerCase();
   }
+  if (flags.https !== undefined) patch.https = Boolean(flags.https);
   if (flags.accessKey === 'generate') patch.accessKey = generateAccessKey();
   else if (flags.accessKey !== undefined) {
     if (String(flags.accessKey).trim().length < 16) throw new Error('--access-key must be at least 16 characters, or "generate".');
@@ -300,11 +314,15 @@ export function applyFlags(current, flags = {}) {
     account: { ...(current.account || DEFAULT_SETTINGS.account), ...account },
     tunnel: { ...(current.tunnel || DEFAULT_SETTINGS.tunnel), ...tunnel },
   };
-  // Mode drove host/domain rules inside normalize; when flags move a config to
-  // local mode the network fields have to come along rather than linger.
+  // A fresh self-hosted setup is direct-first for cloud/VPS use. Re-running setup
+  // preserves an existing deliberate loopback choice for tunnels and Caddy.
+  if (flags.mode === 'self-hosted' && flags.host === undefined && current.mode !== 'self-hosted') {
+    merged.host = '0.0.0.0';
+  }
   if (merged.mode === 'local') {
     if (!['127.0.0.1', 'localhost', '::1', '[::1]'].includes(merged.host)) merged.host = '127.0.0.1';
     if (flags.domain === undefined) merged.domain = '';
+    if (flags.https === undefined) merged.https = false;
   }
   return { patch, settings: normalizeSettings(merged) };
 }
@@ -316,7 +334,7 @@ export function summaryLines(settings, { revealKey = false } = {}) {
     ['Mode', settings.mode],
     ['Bind', `${settings.host}:${settings.port}`],
   ];
-  if (settings.domain) lines.push(['Domain', 'https://' + settings.domain]);
+  if (settings.domain) lines.push(['Domain', (settings.https ? 'https://' : 'http://') + settings.domain + (settings.https ? '' : ':' + settings.port)]);
   if (settings.mode === 'self-hosted') {
     lines.push(['Access key', revealKey
       ? settings.accessKey

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-onboarder",
-  "version": "0.2.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

@@ -389,9 +389,16 @@
     </label>
   </div>
   <label class="field" id="srvDomainField">
-    <span class="field-label">Domain (optional for LAN, required for a public name)</span>
+    <span class="field-label">Domain (optional for direct IP or a tunnel)</span>
     <input type="text" id="srvDomain" class="text-input" placeholder="map.example.com" spellcheck="false">
   </label>
+  <div id="srvHttpsField" hidden>
+    <label class="check-row">
+      <input type="checkbox" id="srvHttps">
+      <span>Automatic HTTPS with Caddy</span>
+    </label>
+    <p class="drawer-fine" id="srvHttpsStatus"></p>
+  </div>
   <label class="check-row">
     <input type="checkbox" id="srvAutoOpen">
     <span>Open the browser when the server starts</span>
@@ -404,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', {});
+}