codebase-onboarder 0.2.0 → 0.3.0

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; 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.
 
 ```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,31 @@ 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. A domain is optional for direct-IP access. If a domain is entered, setup asks whether to enable automatic HTTPS.
+
+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 continues to enforce the access key on every API call. 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.
 
 ---
 
@@ -240,6 +257,7 @@ codebase-onboarder/
 │   ├── router.js    # Route table, live per-request settings, Bearer gate
 │   ├── 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
@@ -252,7 +270,7 @@ codebase-onboarder/
 │   ├── 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)
+└── tests/           # Comprehensive node:test suite (560 unit tests)
 ```
 
 ---
@@ -262,7 +280,7 @@ codebase-onboarder/
 Onboarder includes a comprehensive automated test suite built with Node's native test runner:
 
 ```bash
-# Run all 551 tests
+# Run all 560 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 } = {}) {

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.0",
   "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>

package/public/js/serverSettings.js

@@ -29,7 +29,7 @@ export function createServerDrawer(options = {}) {
   const dom = {};
   [
     'serverDrawer', 'serverScrim', 'serverClose', 'serverModeNote', 'srvMode', 'srvHost', 'srvPort',
-    'srvDomain', 'srvDomainField', 'srvAutoOpen', 'srvKeySection', 'srvKeyMasked', 'srvRotate',
+    'srvDomain', 'srvDomainField', 'srvHttps', 'srvHttpsField', 'srvHttpsStatus', 'srvAutoOpen', 'srvKeySection', 'srvKeyMasked', 'srvRotate',
     'srvFreshKeyRow', 'srvFreshKey', 'srvCopyKey', 'srvKeyHint', 'srvName', 'srvEmail',
     'srvTunnelCloudflare', 'srvTunnelCloudflareStatus', 'srvTunnelTailscale', 'srvTunnelTailscaleStatus',
     'srvSave', 'srvStatus', 'srvConfigPath',
@@ -61,6 +61,10 @@ export function createServerDrawer(options = {}) {
     dom.srvHost.value = s.host;
     dom.srvPort.value = s.port;
     dom.srvDomain.value = s.domain || '';
+    dom.srvHttps.checked = Boolean(s.https);
+    dom.srvHttpsStatus.textContent = data.https?.caddyInstalled
+      ? `Caddy ${data.https.caddyVersion || 'installed'}. ${s.https ? 'Run `onboarder https setup` after saving.' : 'Enable HTTPS above, save, then run the command.'}`
+      : 'Caddy is not installed. Ubuntu: sudo apt install caddy; macOS: brew install caddy.';
     dom.srvAutoOpen.checked = Boolean(s.autoOpen);
     dom.srvName.value = s.account?.name || '';
     dom.srvEmail.value = s.account?.email || '';
@@ -82,6 +86,7 @@ export function createServerDrawer(options = {}) {
     const remote = dom.srvMode.value === 'self-hosted';
     dom.srvKeySection.hidden = !remote;
     dom.srvDomainField.hidden = !remote;
+    dom.srvHttpsField.hidden = !remote || !dom.srvDomain.value.trim();
     dom.serverModeNote.textContent = MODE_NOTES[dom.srvMode.value] || '';
   }
 
@@ -113,16 +118,22 @@ export function createServerDrawer(options = {}) {
       account: { name: dom.srvName.value.trim(), email: dom.srvEmail.value.trim() },
       tunnel: { cloudflare: dom.srvTunnelCloudflare.checked, tailscale: dom.srvTunnelTailscale.checked },
     };
-    if (patch.mode === 'self-hosted') patch.domain = dom.srvDomain.value.trim();
+    if (patch.mode === 'self-hosted') {
+      patch.domain = dom.srvDomain.value.trim();
+      patch.https = dom.srvHttps.checked;
+    }
     status('Saving…');
     try {
       const data = await updateServerSettings(patch);
       render({ ...current, settings: data.settings });
       const restart = (data.restartRequired || []).join(' and ');
+      const httpsChanged = (data.restartRequired || []).some((key) => key === 'domain' || key === 'https');
       status(
-        restart
-          ? `Saved. The ${restart} change takes effect after a restart — the running socket cannot move.`
-          : 'Saved — live already.',
+        httpsChanged
+          ? 'Saved. Run `onboarder https setup` to validate the Caddyfile and reload TLS.'
+          : restart
+            ? `Saved. The ${restart} change takes effect after a restart — the running socket cannot move.`
+            : 'Saved — live already.',
         'ok',
       );
     } catch (err) {
@@ -147,6 +158,7 @@ export function createServerDrawer(options = {}) {
   }
 
   dom.srvMode.addEventListener('change', applyModeVisibility);
+  dom.srvDomain.addEventListener('input', applyModeVisibility);
   dom.srvSave.addEventListener('click', save);
   dom.srvRotate.addEventListener('click', rotate);
   dom.serverClose.addEventListener('click', close);

package/server/apiSettings.js

@@ -13,6 +13,7 @@ import {
 } from './config.js';
 import { sendError, sendJSON } from './http.js';
 import { tunnelStatus } from './tunnel.js';
+import { httpsStatus } from './https.js';
 
 // Where this request's settings live. The router's config object carries the
 // path when the server was booted with one; tests and a bare `createServer()`
@@ -37,6 +38,7 @@ async function publicBody(config) {
     configFile: settingsFile(config) || configPath(),
     node: process.version,
     tunnels: tunnelStatus(settings),
+    https: httpsStatus(settings, settingsFile(config) || configPath()),
   };
 }
 
@@ -48,15 +50,17 @@ export async function handleGetSettings(req, res, config) {
   }
 }
 
-// Which changes the running server cannot absorb. Auth, domain, and tunnel
-// flags are read live from disk on each request; the bind is a socket that
-// already exists.
+// Which changes the running server cannot absorb. Access-key and tunnel flags
+// are read live per request. Host/port are bound sockets. Domain/HTTPS change
+// the managed Caddyfile and certificate, so Caddy must validate/reload too.
 function restartRequired(config, next) {
   const boot = config?.boot;
   if (!boot) return [];
   const changed = [];
   if (next.host !== boot.host) changed.push('host');
   if (next.port !== boot.port) changed.push('port');
+  if (next.domain !== boot.domain) changed.push('domain');
+  if (next.https !== boot.https) changed.push('https');
   return changed;
 }
 
@@ -70,7 +74,7 @@ export async function handleUpdateSettings(res, body, config) {
   }
   // Only known keys may be patched — a typo like "ports" must be a loud 400,
   // not a silently ignored write that the UI then claims it saved.
-  const allowed = new Set(['mode', 'host', 'port', 'domain', 'autoOpen', 'account', 'tunnel']);
+  const allowed = new Set(['mode', 'host', 'port', 'domain', 'https', 'autoOpen', 'account', 'tunnel']);
   const unknown = Object.keys(body).filter((k) => k !== 'accessKey' && !allowed.has(k));
   if (unknown.length) {
     return sendError(res, 400, `Unknown setting${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}.`);

package/server/config.js

@@ -7,7 +7,7 @@ import { randomBytes, timingSafeEqual } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 
-export const CONFIG_VERSION = 1;
+export const CONFIG_VERSION = 2;
 export const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
 export const DEFAULT_SETTINGS = Object.freeze({
   version: CONFIG_VERSION,
@@ -15,6 +15,10 @@ export const DEFAULT_SETTINGS = Object.freeze({
   host: '127.0.0.1',
   port: 4310,
   domain: '',
+  // When a domain is configured, ask Caddy to obtain and renew a trusted TLS
+  // certificate and reverse-proxy this app. The certificate itself belongs to
+  // Caddy; the server still speaks plain HTTP to its local upstream.
+  https: false,
   accessKey: '',
   // Whether `onboarder start` opens the app in a browser once it is listening.
   // Off in the schema so `npm start` from a checkout stays quiet; the setup
@@ -82,6 +86,7 @@ export function normalizeSettings(value = {}) {
     host,
     port: normalizePort(value.port ?? DEFAULT_SETTINGS.port),
     domain: normalizeDomain(value.domain),
+    https: Boolean(value.https),
     accessKey: cleanString(value.accessKey, 256),
     autoOpen: value.autoOpen === undefined ? DEFAULT_SETTINGS.autoOpen : Boolean(value.autoOpen),
     account: normalizeAccount(value.account),
@@ -91,10 +96,11 @@ export function normalizeSettings(value = {}) {
   if (settings.mode === 'local' && !isLoopbackHost(settings.host)) {
     throw new Error('Local mode only binds to 127.0.0.1, localhost, or ::1. Choose self-hosted mode for a network bind.');
   }
+  if (settings.https && !settings.domain) {
+    throw new Error('HTTPS needs a domain such as map.example.com. A public IP alone cannot be used for a normal trusted certificate.');
+  }
   // Self-hosted needs no domain: a bare-IP bind (a VPS with no DNS name) is a
-  // legitimate layout. The rebinding guard still answers only to the
-  // configured domain or this machine's own interface addresses (see
-  // allowedHosts), and every API call needs the access key either way.
+  // legitimate layout. Every API call needs the access key either way.
   return settings;
 }
 
@@ -113,7 +119,7 @@ export function serverUrls(value = DEFAULT_SETTINGS) {
       ? `http://<this-machine>:${settings.port} (every interface)`
       : `http://${settings.host}:${settings.port}`;
   }
-  if (settings.domain) urls.domain = `https://${settings.domain}`;
+  if (settings.domain) urls.domain = settings.https ? `https://${settings.domain}` : `http://${settings.domain}:${settings.port}`;
   return urls;
 }
 
@@ -124,6 +130,12 @@ export function maskAccessKey(key) {
   return `${value.slice(0, 6)}…${value.slice(-4)}`;
 }
 
+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();
+}
+
 export function publicSettings(value = DEFAULT_SETTINGS) {
   const settings = normalizeSettings(value);
   return {
@@ -132,6 +144,7 @@ export function publicSettings(value = DEFAULT_SETTINGS) {
     host: settings.host,
     port: settings.port,
     domain: settings.domain,
+    https: settings.https,
     autoOpen: settings.autoOpen,
     hasAccessKey: Boolean(settings.accessKey),
     accessKeyMasked: maskAccessKey(settings.accessKey),
@@ -179,8 +192,15 @@ 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' || settings.host === '::') {
-      for (const ip of ownInterfaceHosts()) hosts.add(ip);
+    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);
     }
   }
   if (settings.tunnel.cloudflare) hosts.add('*.trycloudflare.com');

package/server/httpGuards.js

@@ -7,6 +7,8 @@
 // open from driving this server on their behalf. Binding to 127.0.0.1 keeps
 // the network out; it does nothing about the browser, which is already inside.
 
+import net from 'node:net';
+
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
 
 // "localhost:4310" -> "localhost", "[::1]:4310" -> "[::1]"
@@ -41,6 +43,8 @@ export function rebindingReason(req, extraHosts = []) {
   const name = hostnameOf(host);
   if (LOOPBACK_HOSTS.has(name)) return null;
   for (const extra of extraHosts) {
+    if (extra === 'ipv4:*' && net.isIP(name) === 4) return null;
+    if (extra === 'ipv6:*' && net.isIP(name.replace(/^\[|\]$/g, '')) === 6) return null;
     if (extra.startsWith('*.')) {
       // "*.trycloudflare.com" matches "abc.trycloudflare.com" but not the bare
       // suffix itself and not "evil-trycloudflare.com".

package/server/https.js

@@ -0,0 +1,142 @@
+import { promises as dns } from 'node:dns';
+import { promises as fs, statSync } from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { configPath, normalizeSettings } from './config.js';
+import { findOnPath, installHint } from './tunnel.js';
+
+export function caddyfilePath(configFile = configPath()) {
+  return path.join(path.dirname(configFile), 'Caddyfile');
+}
+
+export function renderCaddyfile(settings) {
+  const s = normalizeSettings(settings);
+  if (!s.domain) throw new Error('HTTPS needs a domain. Run `onboarder setup` and enter one first.');
+  return `# Managed by Onboarder. Edits are replaced by \`onboarder https setup\`.\n${s.domain} {\n  reverse_proxy 127.0.0.1:${s.port}\n}\n`;
+}
+
+function portIsFree(port, host = '0.0.0.0') {
+  return new Promise((resolve) => {
+    const probe = net.createServer();
+    probe.once('error', () => resolve(false));
+    probe.listen(port, host, () => probe.close(() => resolve(true)));
+  });
+}
+
+async function resolveDomain(domain) {
+  const [v4, v6] = await Promise.allSettled([dns.resolve4(domain), dns.resolve6(domain)]);
+  const addresses = [
+    ...(v4.status === 'fulfilled' ? v4.value : []),
+    ...(v6.status === 'fulfilled' ? v6.value : []),
+  ];
+  return [...new Set(addresses)];
+}
+
+function localAddresses() {
+  const found = [];
+  for (const list of Object.values(os.networkInterfaces())) {
+    for (const address of list || []) if (!address.internal) found.push(address.address);
+  }
+  return found;
+}
+
+async function caddyIsRunning(probe = portIsFree) {
+  // If 80 and 443 are both occupied, probe Caddy's local admin endpoint. This
+  // distinguishes the Ubuntu service from an unknown listener without sudo.
+  if (await probe(80)) return false;
+  if (await probe(443)) return false;
+  return new Promise((resolve) => {
+    const socket = net.connect(2019, '127.0.0.1');
+    const finish = (value) => { socket.destroy(); resolve(value); };
+    socket.setTimeout(800, () => finish(false));
+    socket.once('connect', () => finish(true));
+    socket.once('error', () => finish(false));
+  });
+}
+
+export async function httpsReadiness(settings, { configFile = configPath(), resolve = resolveDomain, probe = portIsFree, tool = findOnPath, running = caddyIsRunning } = {}) {
+  const s = normalizeSettings(settings);
+  const caddy = tool('caddy');
+  const checks = [{ id: 'domain', ok: Boolean(s.domain), required: true, detail: s.domain || 'not configured' }];
+  if (!s.domain) return { ok: false, checks, caddy, addresses: [], local: [] };
+
+  let addresses = [];
+  let dnsError = '';
+  try { addresses = await resolve(s.domain); } catch (error) { dnsError = error.code || error.message; }
+  checks.push({ id: 'dns', ok: addresses.length > 0, required: true, detail: addresses.length ? addresses.join(', ') : `does not resolve${dnsError ? ` (${dnsError})` : ''}` });
+  const local = localAddresses();
+  const matches = addresses.some((address) => local.includes(address));
+  checks.push({ id: 'dns-target', ok: matches, required: false, detail: matches ? 'resolves to this machine' : 'does not match a local interface address (NAT/public-IP and proxy setups can still be valid)' });
+
+  const serviceRunning = await running(probe);
+  for (const port of [80, 443]) {
+    const free = await probe(port);
+    const ownedByCaddy = !free && serviceRunning;
+    checks.push({
+      id: `port-${port}`,
+      ok: free || ownedByCaddy,
+      required: true,
+      detail: free ? 'available for Caddy' : ownedByCaddy ? 'in use by the running Caddy service' : 'already in use — stop the existing web server or proxy',
+    });
+  }
+  checks.push({ id: 'caddy', ok: caddy.installed, required: true, detail: caddy.installed ? caddy.version : 'not installed — ' + installHint('caddy') });
+  return { ok: checks.every((check) => check.ok || !check.required), checks, caddy, addresses, local };
+}
+
+export function httpsStatus(settings, configFile = configPath()) {
+  const s = normalizeSettings(settings);
+  const file = caddyfilePath(configFile);
+  const caddy = findOnPath('caddy');
+  let configured = false;
+  try { configured = Boolean(statSync(file)); } catch { configured = false; }
+  return {
+    enabled: Boolean(s.domain && s.https),
+    domain: s.domain,
+    url: s.domain && s.https ? `https://${s.domain}` : '',
+    caddyfile: file,
+    caddyInstalled: caddy.installed,
+    caddyVersion: caddy.version || '',
+    configured,
+    command: s.domain && s.https ? `caddy start --config ${file}` : '',
+  };
+}
+
+export async function writeCaddyfile(settings, configFile = configPath()) {
+  const file = caddyfilePath(configFile);
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  await fs.writeFile(file, renderCaddyfile(settings), { encoding: 'utf8', mode: 0o600 });
+  return file;
+}
+
+export async function caddyValidate(settings, configFile = configPath()) {
+  const s = normalizeSettings(settings);
+  if (!s.domain) throw new Error('HTTPS needs a domain. Run `onboarder setup` and enter one first.');
+  const caddy = findOnPath('caddy');
+  if (!caddy.installed) throw new Error('Caddy is not installed. ' + installHint('caddy'));
+  const file = caddyfilePath(configFile);
+  const result = spawnSync('caddy', ['validate', '--config', file], { encoding: 'utf8' });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || 'Caddy configuration is invalid.').trim());
+  return { file, output: String(result.stdout || result.stderr || '').trim() };
+}
+
+export function caddyRun(settings, configFile = configPath(), action = 'start') {
+  const s = normalizeSettings(settings);
+  if (!s.domain || !s.https) throw new Error('Enable HTTPS with a domain first: `onboarder setup`.');
+  const caddy = findOnPath('caddy');
+  if (!caddy.installed) throw new Error('Caddy is not installed. ' + installHint('caddy'));
+  const file = caddyfilePath(configFile);
+  const result = spawnSync('caddy', [action, '--config', file], { encoding: 'utf8' });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const message = String(result.stderr || result.stdout || `caddy ${action} failed`).trim();
+    if (/permission denied|address already in use/i.test(message) && process.platform !== 'win32') {
+      throw new Error(`${message}\nStart the packaged service with: sudo systemctl enable --now caddy`);
+    }
+    throw new Error(message);
+  }
+  return { action, file, output: String(result.stdout || result.stderr || '').trim() };
+}

package/server/index.js

@@ -21,7 +21,7 @@ import { createRouter } from './router.js';
 import { installExitCleanup } from './sessions.js';
 import { createLogger } from './logger.js';
 import { createMcpRunner } from './mcp/runner.js';
-import { configPath, isLoopbackHost, readSettings, serverUrls } from './config.js';
+import { browserUrl, configPath, isLoopbackHost, readSettings, serverUrls } from './config.js';
 import { tunnelStatus } from './tunnel.js';
 import { pidIsAlive, readPidFile, removePidFile, writePidFile } from './pidfile.js';
 
@@ -73,7 +73,17 @@ export function startupBanner(settings, { configFile } = {}) {
     : '  Mode    local — only this machine can reach it');
   lines.push('  Local   ' + urls.local);
   if (urls.network) lines.push('  Network ' + urls.network);
-  if (urls.domain) lines.push('  Domain  ' + urls.domain);
+  if (urls.domain) {
+    lines.push('  Domain  ' + urls.domain);
+    if (settings.domain && !settings.https) {
+      lines.push('  HTTPS   disabled — `onboarder setup` or `onboarder https setup` enables trusted TLS');
+    } else if (settings.https) {
+      lines.push('  HTTPS   Caddy obtains, renews, and terminates TLS for this domain');
+    }
+  }
+  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.');
+  }
   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.');
     lines.push('          Run `onboarder setup` or `onboarder config key rotate`.');
@@ -130,7 +140,7 @@ export async function startServer({ configFile = configPath(), openBrowser, log
     ...CONFIG,
     configPath: configFile,
     getSettings: () => readSettings(configFile),
-    boot: { host, port },
+    boot: { host, port, domain: settings.domain, https: settings.https },
   });
 
   installExitCleanup();
@@ -166,9 +176,9 @@ export async function startServer({ configFile = configPath(), openBrowser, log
   log(startupBanner(live, { configFile }));
 
   const shouldOpen = openBrowser ?? (live.autoOpen && process.stdout.isTTY && !process.env.NO_OPEN);
-  // Remote visitors still need the key; what opens locally is the loopback URL,
-  // which in local mode needs nothing and in self-hosted mode asks for the key.
-  if (shouldOpen) openInBrowser(serverUrls(live).local);
+  // 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.
+  if (shouldOpen) openInBrowser(browserUrl(live));
   return { server, settings: live, host, port };
 }
 

package/server/tunnel.js

@@ -50,6 +50,11 @@ export function tailscaleCommand(settings) {
 }
 
 export function installHint(name) {
+  if (name === 'caddy') {
+    return process.platform === 'darwin'
+      ? 'brew install caddy'
+      : 'Install Caddy with: sudo apt install caddy';
+  }
   if (name === 'cloudflared') {
     return process.platform === 'darwin'
       ? 'brew install cloudflared  (or see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)'