nterminal 1.2.0

package/dist/scripts/onboarding.js

@@ -0,0 +1,814 @@
+import crypto from 'node:crypto';
+import net from 'node:net';
+import os from 'node:os';
+import { existsSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as readline from 'node:readline';
+import QRCode from 'qrcode';
+import { ensureFirewallAllowsPort, pickSudoMode, setupNginxProxy, validateDeploymentUrl } from './proxySetup.js';
+// ---------------------------------------------------------------------------
+// Pure helpers (unit-tested)
+// ---------------------------------------------------------------------------
+export function generateSessionSecret() {
+    return crypto.randomBytes(48).toString('base64url');
+}
+export function generateAgentToken() {
+    return crypto.randomBytes(32).toString('base64url');
+}
+export function originOf(url) {
+    return new URL(url).origin;
+}
+// First non-internal IPv4 we can find, or 127.0.0.1 if none. Used to pick a
+// sensible bind address for main and to default the URL a secondary advertises
+// to its main.
+export function detectBindHost(interfaces) {
+    for (const list of Object.values(interfaces)) {
+        for (const entry of list ?? []) {
+            // node >=18 reports family as 'IPv4' (string) or 4 (number) on older builds
+            const isV4 = entry.family === 'IPv4' || entry.family === 4;
+            if (isV4 && !entry.internal) {
+                return entry.address;
+            }
+        }
+    }
+    return '127.0.0.1';
+}
+export function detectAgentUrl(interfaces, port, protocol = 'http') {
+    return `${protocol}://${detectBindHost(interfaces)}:${port}`;
+}
+// Try to bind a server on `host:port` — resolve true when the bind succeeds
+// (port is free) and false when it errors. Used by pickFreePort to decide
+// whether the preferred port is usable without asking the operator.
+export function isPortAvailable(port, host = '127.0.0.1') {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        const finish = (free) => {
+            server.removeAllListeners();
+            server.close(() => resolve(free));
+        };
+        server.once('error', () => finish(false));
+        server.once('listening', () => finish(true));
+        try {
+            server.listen(port, host);
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+// Pick a usable port without asking. Prefer the documented default so the
+// README's instructions ("open http://...:3107") keep working when nothing
+// else is on the host; fall back to a kernel-assigned ephemeral port when
+// the preferred one is taken. A non-positive `preferred` skips the bind probe
+// (since port 0 means "any" to the OS) and goes straight to ephemeral.
+export async function pickFreePort(host = '127.0.0.1', preferred = 3107) {
+    if (preferred > 0 && (await isPortAvailable(preferred, host))) {
+        return preferred;
+    }
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.once('error', reject);
+        server.listen(0, host, () => {
+            const address = server.address();
+            const assigned = address && typeof address === 'object' ? address.port : 0;
+            server.close((err) => (err ? reject(err) : resolve(assigned)));
+        });
+    });
+}
+export function renderEnvFile(map) {
+    return `${Object.entries(map)
+        .map(([key, value]) => `${key}=${value}`)
+        .join('\n')}\n`;
+}
+/** Replace targeted keys in an existing .env, preserving comments, blanks, and unrelated keys. Appends new keys. */
+export function mergeEnv(existing, updates) {
+    const applied = new Set();
+    // Allow optional whitespace around `=` to match loadDotEnvFile()'s parsing; rewrite canonically as KEY=value.
+    const lines = existing.split(/\r?\n/).map((line) => {
+        const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+        const key = match?.[1];
+        if (key && Object.prototype.hasOwnProperty.call(updates, key)) {
+            applied.add(key);
+            return `${key}=${updates[key]}`;
+        }
+        return line;
+    });
+    for (const [key, value] of Object.entries(updates)) {
+        if (!applied.has(key)) {
+            lines.push(`${key}=${value}`);
+        }
+    }
+    return `${lines.join('\n').replace(/\n+$/, '')}\n`;
+}
+export function buildAgentRegisterPayload(name, url, token) {
+    return { name: name.trim(), url: url.trim().replace(/\/$/, ''), token: token.trim() };
+}
+// Resolve the bind host: existing .env value wins so a re-run never silently
+// overwrites an operator's manual override, otherwise call the detector
+// (main: first non-loopback IPv4; secondary: hardcoded 0.0.0.0).
+export function resolveBindHost(envValue, detect) {
+    const trimmed = envValue?.trim();
+    if (trimmed) {
+        return { value: trimmed, origin: 'env' };
+    }
+    return { value: detect(), origin: 'detected' };
+}
+// Resolve the bind port. Existing .env value wins as long as it parses as
+// a positive integer, otherwise call `pickFreePort` to choose without
+// asking the operator. Returns the chosen port plus how we got it.
+export async function resolveBindPort(envValue, host, preferred = 3107) {
+    const trimmed = envValue?.trim();
+    if (trimmed && /^[1-9]\d*$/.test(trimmed)) {
+        return { value: trimmed, origin: 'env' };
+    }
+    const port = await pickFreePort(host, preferred);
+    return { value: String(port), origin: port === preferred ? 'default' : 'ephemeral' };
+}
+/** Read a single KEY=value from an .env file's contents (last occurrence wins, quotes stripped). */
+export function parseEnvValue(content, key) {
+    // loadDotEnvFile() uses the FIRST occurrence and tolerates spaces around `=`; match that here.
+    for (const line of content.split(/\r?\n/)) {
+        const match = new RegExp(`^\\s*${key}\\s*=(.*)$`).exec(line);
+        if (match) {
+            let value = (match[1] ?? '').trim();
+            if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            return value;
+        }
+    }
+    return undefined;
+}
+/** Default access URL derived from bind host/port so it stays consistent with the chosen port. */
+export function defaultPublicUrl(host, port, https) {
+    let reachableHost = host === '0.0.0.0' || host === '::' || host === '' ? '127.0.0.1' : host;
+    // Bracket IPv6 literals so the URL stays valid (e.g. http://[::1]:3107).
+    if (reachableHost.includes(':') && !reachableHost.startsWith('[')) {
+        reachableHost = `[${reachableHost}]`;
+    }
+    return `${https ? 'https' : 'http'}://${reachableHost}:${port}`;
+}
+export function groupSecret(secret) {
+    return secret.replace(/(.{4})/g, '$1 ').trim();
+}
+export function buildOtpAuthUri(secret, issuer = 'NTerminal', account = 'nterminal') {
+    // Label is "Issuer:Account" with a literal colon (per the otpauth URI convention).
+    // Only secret + issuer are emitted — every authenticator app defaults period/digits/algorithm
+    // to 30/6/SHA1, so encoding them just inflates the QR for no behavioral change.
+    const label = `${encodeURIComponent(issuer)}:${encodeURIComponent(account)}`;
+    const params = new URLSearchParams({ secret, issuer });
+    return `otpauth://totp/${label}?${params.toString()}`;
+}
+export async function renderOtpAuthQr(uri) {
+    // `small: true` uses half-block characters to halve vertical size — confirmed scannable
+    // on a phone camera even when the host terminal renders the wider blank frame.
+    return QRCode.toString(uri, { type: 'terminal', small: true });
+}
+// Print a single-color box around a labeled summary + a numbered "Next steps"
+// section. ANSI escapes are stripped before measuring width so the right
+// border lines up even when the title carries a green ✓.
+export function printSummaryBox(title, rows, nextSteps) {
+    const visibleLen = (s) => stripAnsi(s).length;
+    const labelWidth = rows.reduce((max, row) => Math.max(max, row.label.length), 0);
+    const contentLines = [];
+    contentLines.push(title);
+    contentLines.push('');
+    for (const row of rows) {
+        contentLines.push(`  ${row.label.padEnd(labelWidth)}  ${row.value}`);
+    }
+    if (nextSteps.length > 0) {
+        contentLines.push('');
+        contentLines.push('Next steps');
+        nextSteps.forEach((step, idx) => {
+            contentLines.push(`  ${idx + 1}. ${step}`);
+        });
+    }
+    const inner = Math.max(...contentLines.map((line) => visibleLen(line)));
+    const width = inner + 4; // 2-space padding on each side
+    const top = '┌' + '─'.repeat(width - 2) + '┐';
+    const bottom = '└' + '─'.repeat(width - 2) + '┘';
+    console.log('');
+    console.log(top);
+    for (const line of contentLines) {
+        const pad = ' '.repeat(inner - visibleLen(line));
+        console.log(`│ ${line}${pad}  │`);
+    }
+    console.log(bottom);
+}
+function stripAnsi(s) {
+    // Minimal CSI stripper, enough for our `\x1b[..m` color codes.
+    return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+export function isPubliclyBoundHost(host) {
+    // Loopback / link-local / "unset" binds never need a firewall hole because
+    // the bind itself already excludes external traffic. Anything else
+    // (0.0.0.0, ::, a routable address) is the case we have to worry about.
+    const normalized = host.trim().toLowerCase();
+    if (!normalized || normalized === '127.0.0.1' || normalized === '::1' || normalized === 'localhost') {
+        return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Interactive flow
+// ---------------------------------------------------------------------------
+function resolveAppDir() {
+    if (process.env.NTERMINAL_APP_DIR) {
+        return path.resolve(process.env.NTERMINAL_APP_DIR);
+    }
+    const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+    const sourceRoot = path.resolve(scriptDir, '..');
+    if (existsSync(path.join(sourceRoot, 'package.json'))) {
+        return sourceRoot;
+    }
+    const distRoot = path.resolve(scriptDir, '..', '..');
+    if (existsSync(path.join(distRoot, 'package.json'))) {
+        return distRoot;
+    }
+    return sourceRoot;
+}
+const APP_DIR = resolveAppDir();
+const ENV_PATH = process.env.NTERMINAL_ENV_FILE
+    ? path.resolve(process.env.NTERMINAL_ENV_FILE)
+    : path.join(APP_DIR, '.env');
+function serverModuleUrl(modulePath) {
+    const built = path.join(APP_DIR, 'dist/server', `${modulePath}.js`);
+    if (existsSync(built)) {
+        return pathToFileURL(built).href;
+    }
+    const source = path.join(APP_DIR, 'src/server', `${modulePath}.ts`);
+    if (existsSync(source)) {
+        return pathToFileURL(source).href;
+    }
+    return pathToFileURL(path.join(APP_DIR, 'src/server', `${modulePath}.js`)).href;
+}
+// Arrow-key + Enter list selector for a TTY. The caller is responsible for
+// falling back to text input when stdin is not a TTY — see chooseRole().
+async function pickFromList(prompt, options, initialIndex = 0) {
+    const stdout = process.stdout;
+    let index = Math.max(0, Math.min(initialIndex, options.length - 1));
+    const lines = options.length + 1;
+    let rendered = false;
+    const render = () => {
+        if (rendered) {
+            // Move the cursor back to the prompt line so we can rewrite the block.
+            readline.moveCursor(stdout, 0, -lines);
+        }
+        stdout.write(`? ${prompt} (↑/↓ then Enter)\n`);
+        for (const [i, opt] of options.entries()) {
+            const marker = i === index ? '›' : ' ';
+            const label = i === index ? `${opt.label}` : opt.label;
+            stdout.write(`${marker} ${label}\n`);
+        }
+        rendered = true;
+    };
+    readline.emitKeypressEvents(process.stdin);
+    const wasRaw = Boolean(process.stdin.isRaw);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    return new Promise((resolve) => {
+        const cleanup = () => {
+            process.stdin.removeListener('keypress', onKeypress);
+            if (!wasRaw) {
+                process.stdin.setRawMode(false);
+            }
+            process.stdin.pause();
+        };
+        const onKeypress = (_str, key) => {
+            if (!key)
+                return;
+            if (key.ctrl && key.name === 'c') {
+                cleanup();
+                stdout.write('\n');
+                process.exit(130);
+            }
+            if (key.name === 'up' || key.name === 'k') {
+                index = (index - 1 + options.length) % options.length;
+                render();
+            }
+            else if (key.name === 'down' || key.name === 'j') {
+                index = (index + 1) % options.length;
+                render();
+            }
+            else if (key.name === 'return' || key.name === 'enter') {
+                cleanup();
+                resolve(options[index].value);
+            }
+        };
+        process.stdin.on('keypress', onKeypress);
+        render();
+    });
+}
+function createPrompter() {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: Boolean(process.stdin.isTTY) });
+    const rlAny = rl;
+    const originalWrite = rlAny._writeToOutput.bind(rl);
+    let muted = false;
+    rlAny._writeToOutput = (stringToWrite) => {
+        if (muted) {
+            return;
+        }
+        originalWrite(stringToWrite);
+    };
+    return {
+        ask(question, fallback) {
+            const suffix = fallback ? ` [${fallback}]` : '';
+            return new Promise((resolve) => {
+                rl.question(`${question}${suffix}: `, (answer) => {
+                    const value = answer.trim();
+                    resolve(value || fallback || '');
+                });
+            });
+        },
+        askSecret(question) {
+            // Masking via output muting only works on a real TTY; in piped/automation contexts fall back to a plain read.
+            if (!process.stdin.isTTY) {
+                return new Promise((resolve) => rl.question(`${question}: `, (answer) => resolve(answer)));
+            }
+            return new Promise((resolve) => {
+                rl.question(`${question}: `, (answer) => {
+                    muted = false;
+                    rlAny.output.write('\n');
+                    resolve(answer);
+                });
+                muted = true;
+            });
+        },
+        async confirm(question, defaultYes) {
+            const hint = defaultYes ? 'Y/n' : 'y/N';
+            const answer = (await this.ask(`${question} (${hint})`)).toLowerCase();
+            if (!answer) {
+                return defaultYes;
+            }
+            return answer === 'y' || answer === 'yes';
+        },
+        close() {
+            rl.close();
+        }
+    };
+}
+function writeEnv(updates) {
+    const content = existsSync(ENV_PATH) ? mergeEnv(readFileSync(ENV_PATH, 'utf8'), updates) : renderEnvFile(updates);
+    writeFileSync(ENV_PATH, content, { mode: 0o600 });
+    chmodSync(ENV_PATH, 0o600);
+}
+/** Return an existing .env value so re-running onboarding never rotates a secret already in use. */
+function existingEnvValue(key) {
+    if (!existsSync(ENV_PATH)) {
+        return undefined;
+    }
+    return parseEnvValue(readFileSync(ENV_PATH, 'utf8'), key);
+}
+async function askUrl(p, question, fallback) {
+    for (;;) {
+        const value = (await p.ask(question, fallback)).replace(/\/$/, '');
+        let parsed;
+        try {
+            parsed = new URL(value);
+        }
+        catch {
+            console.log('Invalid URL. Try again.');
+            continue;
+        }
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            console.log('URL must start with http:// or https://. Try again.');
+            continue;
+        }
+        return value;
+    }
+}
+// Normalize a typed URL-or-domain. Accepts bare `cli.example.com` and
+// prepends https:// (the only accepted scheme), leaves any explicit scheme
+// alone so the validator can reject non-https with a clear reason. Trims
+// surrounding whitespace and a trailing slash so neither rejects the input
+// for spurious reasons.
+export function normalizeDeploymentUrlInput(raw) {
+    const trimmed = raw.trim().replace(/\/$/, '');
+    if (!trimmed)
+        return trimmed;
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+}
+// Stricter version for the main's public URL: forces https:// + a real
+// domain because the security model requires Let's Encrypt-issued TLS in
+// front (no raw IPs, no localhost, no .local). Reasons are echoed back so
+// the operator knows why their value was rejected.
+async function askDeploymentUrl(p, question, fallback) {
+    for (;;) {
+        const value = normalizeDeploymentUrlInput(await p.ask(question, fallback));
+        if (!value) {
+            console.log('A domain is required. Try again.');
+            continue;
+        }
+        const result = validateDeploymentUrl(value);
+        if (result.ok) {
+            return value;
+        }
+        console.log(`Rejected: ${result.reason}. Try again.`);
+    }
+}
+// Best-effort default for the deployment URL: if the machine's hostname
+// already passes the same validation we apply to the typed answer (FQDN,
+// not localhost/.local, not a raw IP, …), suggest it as a starting point —
+// otherwise show an obvious placeholder the operator must replace.
+// Running it through validateDeploymentUrl rather than re-implementing the
+// rules keeps the suggestion in lock-step with what we'd accept.
+export function suggestDeploymentUrl(hostname = os.hostname()) {
+    const candidate = `https://${hostname.trim().toLowerCase()}`;
+    if (validateDeploymentUrl(candidate).ok) {
+        return candidate;
+    }
+    return 'https://your-domain.example.com';
+}
+function runDeploy() {
+    console.log('\nBuilding and starting (scripts/nterminalctl deploy)...\n');
+    const result = spawnSync('bash', [path.join(APP_DIR, 'scripts/nterminalctl'), 'deploy'], {
+        cwd: APP_DIR,
+        stdio: 'inherit'
+    });
+    return result.status === 0;
+}
+function printResolvedBindHost(resolved, detectedNote) {
+    const note = resolved.origin === 'env' ? 'preserved from .env' : detectedNote;
+    console.log(`Bind host: ${resolved.value} \x1b[2m(${note})\x1b[0m`);
+}
+function printResolvedBindPort(resolved) {
+    const note = resolved.origin === 'env'
+        ? 'preserved from .env'
+        : resolved.origin === 'default'
+            ? 'default 3107 is free'
+            : 'default 3107 was busy; picked an ephemeral port';
+    console.log(`Port: ${resolved.value} \x1b[2m(${note})\x1b[0m`);
+}
+async function onboardMain(p) {
+    console.log('\n=== Main server setup ===\n');
+    // Main MUST bind to 127.0.0.1 — the nginx reverse proxy set up in
+    // `setupNginxProxy` below hard-codes 127.0.0.1 as its upstream, and
+    // binding wider would let clients bypass TLS by hitting the server's
+    // LAN/public IP directly. We do NOT preserve a previous NTERMINAL_HOST
+    // here even when one exists in .env: pre-loopback onboarding versions
+    // wrote the detected LAN IP, and silently honoring that stale value
+    // would make the new nginx proxy 502 with a confusing "config loaded but
+    // upstream unreachable" error. Tell the operator we're overriding so the
+    // change isn't a surprise, and remind them to restart NTerminal after
+    // since the running process is still on the old bind until then. Port
+    // still preserves any explicit value, otherwise picks the first free
+    // port (preferring 3107) — the port itself has no security implication
+    // once the bind is loopback.
+    const existingHost = existingEnvValue('NTERMINAL_HOST');
+    if (existingHost && existingHost !== '127.0.0.1') {
+        console.log(`Overriding NTERMINAL_HOST=${existingHost} from .env → 127.0.0.1 (loopback is required behind the reverse proxy). The running process keeps the old bind until you redeploy below.`);
+    }
+    const host = { value: '127.0.0.1', origin: existingHost === '127.0.0.1' ? 'env' : 'detected' };
+    printResolvedBindHost(host, 'loopback only — public traffic is fronted by the nginx proxy below');
+    const port = await resolveBindPort(existingEnvValue('NTERMINAL_PORT'), host.value);
+    printResolvedBindPort(port);
+    // One deployment-shape question: the public https://<domain> the main
+    // will live at. Forced to https + a real domain because the security
+    // model is "TLS in front via Let's Encrypt + reverse proxy" — raw IPs
+    // can't get a public cert, and unencrypted HTTP exposes the login
+    // password + session cookies on whatever network the browser uses.
+    // NTERMINAL_COOKIE_SECURE and NTERMINAL_TRUST_PROXY are therefore both
+    // set to true unconditionally.
+    const publicUrl = await askDeploymentUrl(p, 'Public domain or URL for this main (https:// is added if you omit it)', suggestDeploymentUrl());
+    // Preserve an existing session secret: the password hash is peppered with it, so rotating
+    // it on a re-run would lock out the already-stored password.
+    const sessionSecret = existingEnvValue('NTERMINAL_SESSION_SECRET') ?? generateSessionSecret();
+    const reusedSecret = Boolean(existingEnvValue('NTERMINAL_SESSION_SECRET'));
+    writeEnv({
+        NTERMINAL_SESSION_SECRET: sessionSecret,
+        NTERMINAL_HOST: host.value,
+        NTERMINAL_PORT: port.value,
+        NTERMINAL_ALLOWED_ORIGINS: originOf(publicUrl),
+        NTERMINAL_COOKIE_SECURE: 'true',
+        NTERMINAL_TRUST_PROXY: 'true'
+    });
+    console.log(`\nWrote ${ENV_PATH} (session secret ${reusedSecret ? 'preserved' : 'generated'}).`);
+    // Seed password + TOTP directly into the state file (in-process; no server needed).
+    const { loadConfig, loadDotEnvFile } = await import(serverModuleUrl('config'));
+    const { FileStore } = await import(serverModuleUrl('storage/fileStore'));
+    const { AuthService } = await import(serverModuleUrl('auth/authService'));
+    const { TotpService } = await import(serverModuleUrl('auth/totpService'));
+    // File-only: ignore the surrounding shell env so a stray NTERMINAL_SESSION_SECRET /
+    // NTERMINAL_STATE_PATH can't make us seed into the wrong secret or state file.
+    const config = loadConfig(loadDotEnvFile(ENV_PATH, {}));
+    const store = new FileStore(config.statePath);
+    await store.init();
+    const auth = new AuthService(config, store, { totpService: new TotpService('NTerminal') });
+    const existing = await store.read();
+    if (existing.passwordCredential) {
+        console.log('\nA password is already set for this server — skipping password/2FA setup.');
+    }
+    else {
+        let sessionId = '';
+        for (;;) {
+            const pw = await p.askSecret('Set login password (min 8 chars)');
+            const confirmPw = await p.askSecret('Confirm password');
+            if (pw !== confirmPw) {
+                console.log('Passwords do not match. Try again.');
+                continue;
+            }
+            try {
+                const result = await auth.setupPassword(pw);
+                sessionId = result.session.sessionId;
+                break;
+            }
+            catch (error) {
+                console.log(`Password rejected: ${errorText(error)}`);
+            }
+        }
+        const setup = await auth.setupTotp(sessionId);
+        console.log('\nAdd NTerminal to your authenticator app (Google Authenticator, Authy, 1Password, ...).');
+        console.log('Scan this QR with the app, or type the secret below by hand:\n');
+        process.stdout.write(await renderOtpAuthQr(buildOtpAuthUri(setup.secret)));
+        console.log(`\n  Secret : ${groupSecret(setup.secret)}`);
+        console.log('  NTerminal · nterminal · 6 digits · 30s\n');
+        for (;;) {
+            const code = (await p.ask('Enter the 6-digit code from your app')).replace(/\D/g, '');
+            try {
+                await auth.activateTotp(sessionId, setup.secret, code);
+                console.log('Two-factor authentication enabled.');
+                break;
+            }
+            catch (error) {
+                console.log(`Code rejected (${errorText(error)}). Try again.`);
+            }
+        }
+        // setupPassword issued an in-process trusted-device token that nobody holds.
+        // Clear it so the operator's first real browser login establishes the trusted device.
+        await store.update((current) => ({ ...current, trustedDevices: [] }));
+    }
+    const deploy = await p.confirm('\nBuild and start the server now?', true);
+    const deployed = deploy ? runDeploy() : false;
+    if (deploy && !deployed) {
+        p.close();
+        console.error('\nDeploy failed. Fix the issue and run: scripts/nterminalctl deploy');
+        process.exitCode = 1;
+        return;
+    }
+    // Proxy setup is independent of the deploy step — on a re-run where NTerminal
+    // is already running, the operator typically wants to skip the redeploy but
+    // still finish (or verify) the nginx + TLS half. If NTerminal happens to be
+    // stopped, the curl verification inside setupNginxProxy will surface a 502
+    // and tell them to run nterminalctl start.
+    const proxyResult = await setupNginxProxy({
+        domain: new URL(publicUrl).hostname,
+        port: Number(port.value),
+        prompter: p
+    });
+    p.close();
+    // Order matters: httpsReady is the strongest signal — when nginx + cert
+    // verify passed end-to-end, NTerminal must be running (otherwise the proxy
+    // would have 502'd), so the "did the operator say yes to deploy this time"
+    // distinction stops mattering. Previously we checked `!deploy` first and
+    // printed "Config written but not deployed" alongside a successful
+    // ✓ TLS-ready line, which was contradictory on re-runs where NTerminal was
+    // already up from an earlier session.
+    if (proxyResult.httpsReady) {
+        printSummaryBox('\x1b[32m✓\x1b[0m Main is ready', [
+            { label: 'Public URL', value: publicUrl },
+            { label: 'Internal', value: `${host.value}:${port.value}` }
+        ], [
+            `Open ${publicUrl} in your browser`,
+            'Log in with your password + 6-digit authenticator code',
+            'iPad Safari: Share → Add to Home Screen (optional)'
+        ]);
+        return;
+    }
+    if (!deploy) {
+        console.log(`\nConfig written but not deployed, and the proxy step couldn't verify NTerminal is reachable on 127.0.0.1:${port.value}. Run \`scripts/nterminalctl deploy\` (or restart if already running) and re-run onboarding.`);
+        return;
+    }
+    // deploy succeeded but httpsReady is false — proxy or cert step was
+    // skipped or failed verification.
+    console.log(`\n\x1b[33m⚠\x1b[0m NTerminal itself is running on 127.0.0.1:${port.value}, but the public URL is not verified yet — the reverse-proxy or TLS step above was skipped or did not pass its check.`);
+    console.log(`Finish the remaining commands shown above, then re-run \`npm run onboarding\` to re-verify ${publicUrl}.`);
+}
+async function onboardSecondary(p) {
+    console.log('\n=== Secondary (agent) server setup ===\n');
+    // Secondary listens on all interfaces by default so the main can reach it
+    // across hosts. Existing .env value wins — same preservation rule as main.
+    const host = resolveBindHost(existingEnvValue('NTERMINAL_HOST'), () => '0.0.0.0');
+    printResolvedBindHost(host, 'listens on all interfaces so the main can reach this server');
+    const port = await resolveBindPort(existingEnvValue('NTERMINAL_PORT'), host.value);
+    printResolvedBindPort(port);
+    const suggestedUrl = detectAgentUrl(os.networkInterfaces(), Number(port.value));
+    const selfUrl = await p.ask('URL the MAIN will use to reach THIS server', suggestedUrl);
+    const name = await p.ask('Name shown in the main', os.hostname());
+    // Preserve existing secret/token on re-run so a re-registration keeps the same agent identity.
+    const sessionSecret = existingEnvValue('NTERMINAL_SESSION_SECRET') ?? generateSessionSecret();
+    const agentToken = existingEnvValue('NTERMINAL_AGENT_TOKEN') ?? generateAgentToken();
+    const reused = Boolean(existingEnvValue('NTERMINAL_SESSION_SECRET'));
+    writeEnv({
+        NTERMINAL_SESSION_SECRET: sessionSecret,
+        NTERMINAL_AGENT_TOKEN: agentToken,
+        NTERMINAL_HOST: host.value,
+        NTERMINAL_PORT: port.value
+    });
+    console.log(`\nWrote ${ENV_PATH} (session secret + agent token ${reused ? 'preserved' : 'generated'}).`);
+    // Firewall: when the agent is publicly bound, the main can only reach it
+    // if the host firewall lets the bind port in. Loopback / private binds
+    // never need this so we skip the prompt entirely there. Onboarding used
+    // to leave this manual and the symptom was always the same — main says
+    // "unreachable", the operator forgets ufw is even on, and debugging
+    // burns a half hour before someone runs `ufw status`.
+    if (isPubliclyBoundHost(host.value)) {
+        const portNumber = Number(port.value);
+        if (Number.isFinite(portNumber)) {
+            const sudoMode = await pickSudoMode(p);
+            await ensureFirewallAllowsPort(portNumber, p, sudoMode);
+        }
+    }
+    const wantRegister = await p.confirm('\nRegister this server with a main now?', true);
+    if (wantRegister) {
+        await registerWithMain(p, { name, selfUrl, agentToken });
+    }
+    else {
+        console.log('Skipped registration. Add it later from the main sidebar (URL + the agent token in this .env).');
+    }
+    const deploy = await p.confirm('\nBuild and start this server now?', true);
+    p.close();
+    if (deploy && !runDeploy()) {
+        console.error('\nDeploy failed. Fix the issue and run: scripts/nterminalctl deploy');
+        process.exitCode = 1;
+        return;
+    }
+    printSummaryBox(`\x1b[32m✓\x1b[0m Secondary "${name}" is ready`, [
+        { label: 'Reachable at', value: selfUrl },
+        { label: 'Bind', value: `${host.value}:${port.value}` },
+        { label: 'Registered', value: wantRegister ? 'yes (logged into the main)' : 'no — paste the agent token in the main sidebar later' }
+    ], wantRegister
+        ? [
+            'On the main, the Servers list should now show this agent',
+            'Re-login on the main in your browser (CLI login revoked any active session)'
+        ]
+        : [
+            `In the main sidebar, add a server with URL ${selfUrl}`,
+            'Paste the agent token from this server\'s .env'
+        ]);
+}
+async function registerWithMain(p, agent) {
+    let mainUrl = '';
+    let mainOrigin = '';
+    for (;;) {
+        mainUrl = await askUrl(p, 'Main server URL', 'https://nterminal.example.com');
+        mainOrigin = originOf(mainUrl);
+        try {
+            const res = await fetch(`${mainUrl}/api/auth/session`, { signal: AbortSignal.timeout(8000) });
+            const status = (await res.json());
+            if (!status.passwordSet) {
+                console.log('That main has no password set yet. Onboard the MAIN first, then re-run this on the secondary.');
+                return;
+            }
+            break;
+        }
+        catch {
+            console.log(`Could not reach ${mainUrl}. Check the URL/network and try again.`);
+        }
+    }
+    let cookie = '';
+    for (;;) {
+        const password = await p.askSecret('Main login password');
+        const otp = (await p.ask('Main authenticator code')).replace(/\D/g, '');
+        try {
+            const res = await fetch(`${mainUrl}/api/auth/login`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', origin: mainOrigin },
+                body: JSON.stringify({ password, otp, rememberNetwork: false }),
+                signal: AbortSignal.timeout(8000)
+            });
+            if (!res.ok) {
+                const body = (await res.json().catch(() => ({})));
+                console.log(`Login failed (${body.error ?? res.status}). Try again.`);
+                continue;
+            }
+            cookie = collectCookies(res.headers);
+            break;
+        }
+        catch (error) {
+            console.log(`Login error: ${errorText(error)}. Try again.`);
+        }
+    }
+    const payload = buildAgentRegisterPayload(agent.name, agent.selfUrl, agent.agentToken);
+    try {
+        // Remove any existing agent pointing at the same URL to avoid duplicates.
+        try {
+            const listRes = await fetch(`${mainUrl}/api/agents`, { headers: { cookie }, signal: AbortSignal.timeout(8000) });
+            if (listRes.ok) {
+                const { agents } = (await listRes.json());
+                for (const existing of agents.filter((a) => a.url.replace(/\/$/, '') === payload.url)) {
+                    await fetch(`${mainUrl}/api/agents/${encodeURIComponent(existing.id)}`, {
+                        method: 'DELETE',
+                        headers: { cookie, origin: mainOrigin },
+                        signal: AbortSignal.timeout(8000)
+                    });
+                }
+            }
+        }
+        catch {
+            // best-effort de-dup; ignore
+        }
+        const regRes = await fetch(`${mainUrl}/api/agents`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', origin: mainOrigin, cookie },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(8000)
+        });
+        if (regRes.status === 403) {
+            console.log(`Registration blocked by origin policy. Add "${mainOrigin}" to the main's NTERMINAL_ALLOWED_ORIGINS.`);
+        }
+        else if (!regRes.ok) {
+            const body = (await regRes.json().catch(() => ({})));
+            console.log(`Registration failed (${body.error ?? regRes.status}).`);
+        }
+        else {
+            console.log(`Registered with main as "${payload.name}".`);
+        }
+    }
+    finally {
+        // Always clean up the CLI session + the trusted-device record it created on the main,
+        // even if registration threw.
+        await fetch(`${mainUrl}/api/auth/logout`, {
+            method: 'POST',
+            headers: { origin: mainOrigin, cookie },
+            signal: AbortSignal.timeout(8000)
+        }).catch(() => undefined);
+    }
+    console.log('\nNote: logging into the main from this CLI revoked any active browser session on the main');
+    console.log('      (single active session policy). Re-login in your browser.');
+}
+function collectCookies(headers) {
+    // Node fetch exposes combined set-cookie via getSetCookie()
+    const setCookies = headers.getSetCookie?.() ?? [];
+    return setCookies.map((c) => c.split(';')[0]).join('; ');
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function printTopology() {
+    // Lays out the relationship between the two roles before we ask which one
+    // the operator is installing — first-time users often don't know whether
+    // they want main or secondary, and a name + one-line description fits in
+    // the picker but doesn't show how the pieces connect.
+    const lines = [
+        '\x1b[2m  browser\x1b[0m',
+        "\x1b[2m     │  https\x1b[0m",
+        '\x1b[2m     ▼\x1b[0m',
+        '  ┌───────────┐',
+        '  │   main    │\x1b[2m   ← password + TOTP, fronts everything\x1b[0m',
+        '  └─────┬─────┘',
+        "\x1b[2m        │  agent token over LAN/VPN\x1b[0m",
+        "\x1b[2m        ▼\x1b[0m",
+        '  ┌───────────┐',
+        '  │ secondary │\x1b[2m   ← additional shell hosts, registered with the main\x1b[0m',
+        '  └───────────┘\x1b[2m     (zero or more; optional)\x1b[0m'
+    ];
+    console.log('Topology:');
+    for (const line of lines) {
+        console.log(line);
+    }
+    console.log('');
+}
+async function chooseRole() {
+    if (process.stdin.isTTY) {
+        return pickFromList('Install as', [
+            { label: 'main      — orchestrates secondaries; password + 2FA gate', value: 'main' },
+            { label: 'secondary — agent that registers with a main', value: 'secondary' }
+        ]);
+    }
+    // Non-TTY (piped/automation): keep a one-line text prompt so scripted runs
+    // and the pre-existing test harness continue to work.
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        rl.question('Install as (main / secondary) [main]: ', (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase().startsWith('s') ? 'secondary' : 'main');
+        });
+    });
+}
+async function main() {
+    console.log('NTerminal onboarding\n');
+    printTopology();
+    let p;
+    try {
+        const role = await chooseRole();
+        p = createPrompter();
+        if (role === 'secondary') {
+            await onboardSecondary(p);
+        }
+        else {
+            await onboardMain(p);
+        }
+    }
+    catch (error) {
+        p?.close();
+        console.error(`\nOnboarding aborted: ${errorText(error)}`);
+        process.exitCode = 1;
+    }
+}
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+    void main();
+}
+//# sourceMappingURL=onboarding.js.map