codebase-onboarder 0.2.0 → 0.3.1

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', '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',
@@ -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 || '';
@@ -70,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();
   }
 
@@ -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) {
@@ -134,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
@@ -146,9 +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,7 +12,9 @@ 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';
 
 // 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 +39,7 @@ async function publicBody(config) {
     configFile: settingsFile(config) || configPath(),
     node: process.version,
     tunnels: tunnelStatus(settings),
+    https: httpsStatus(settings, settingsFile(config) || configPath()),
   };
 }
 
@@ -48,15 +51,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 +75,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(', ')}.`);
@@ -92,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.');
@@ -104,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

@@ -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,10 @@ export function maskAccessKey(key) {
   return `${value.slice(0, 6)}…${value.slice(-4)}`;
 }
 
+export function browserUrl(settings) {
+  return new URL(serverUrls(settings).local).toString();
+}
+
 export function publicSettings(value = DEFAULT_SETTINGS) {
   const settings = normalizeSettings(value);
   return {
@@ -132,6 +142,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,9 +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' || settings.host === '::') {
-      for (const ip of ownInterfaceHosts()) 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');
@@ -200,9 +213,20 @@ export function bearerToken(req) {
   return match ? match[1].trim() : '';
 }
 
+export function requestIsLoopback(req) {
+  const remote = String(req.socket?.remoteAddress || '').replace(/^::ffff:/, '');
+  return remote === '127.0.0.1' || remote === '::1';
+}
+
 export function authReason(req, settings = DEFAULT_SETTINGS) {
   const normalized = normalizeSettings(settings);
   if (normalized.mode !== 'self-hosted') return null;
+  // A self-hosted server can still be opened on the same machine. Caddy and
+  // tunnels arrive from loopback but keep the public Host, so both signals must
+  // agree before a login page is skipped.
+  const host = String(req.headers?.host || '').toLowerCase();
+  const hostIsLoopback = isLoopbackHost(host.replace(/:\d+$/, '')) || /^localhost:\d+$/.test(host);
+  if (requestIsLoopback(req) && hostIsLoopback) return null;
   if (!normalized.accessKey) return 'Self-hosted mode has no access key configured.';
   const token = bearerToken(req);
   if (!accessKeysMatch(normalized.accessKey, token)) return 'A valid access key is required.';

package/server/http.js

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

package/server/httpGuards.js

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