@mmmbuto/nexuscrew 0.8.0 → 0.8.2

package/lib/proxy/federation.js

@@ -0,0 +1,217 @@
+'use strict';
+
+const http = require('node:http');
+const net = require('node:net');
+const express = require('express');
+const store = require('../nodes/store.js');
+const { bearerFrom } = require('../auth/middleware.js');
+const { safeEqual } = require('../nodes/peering.js');
+const {
+  sanitizeRequestHeaders, sanitizeResponseHeaders, stripLocalTokenQuery,
+} = require('./node-proxy.js');
+
+const MAX_HOPS = 4;
+const ROUTE_DELIMITER = '_';
+
+function peerFromToken(nodesPath, token) {
+  const st = store.loadStore(nodesPath);
+  if (!st || !token) return null;
+  return st.nodes.find((n) => n.acceptToken && safeEqual(n.acceptToken, token)) || null;
+}
+
+function peerAllows(peer, otherId) {
+  if (!peer) return true;
+  if (peer.visibility === 'network') return true;
+  if (peer.visibility === 'relay-only') return false;
+  return Array.isArray(peer.selected) && peer.selected.includes(otherId);
+}
+
+function canTransit(ingress, egress) {
+  if (!ingress || !egress || ingress.name === egress.name) return !ingress;
+  return peerAllows(ingress, egress.nodeId) && peerAllows(egress, ingress.nodeId);
+}
+
+function parseRoute(raw) {
+  const parts = String(raw || '').split('?')[0].split('/').filter(Boolean);
+  const idx = parts.indexOf(ROUTE_DELIMITER);
+  // The delimiter cannot occur in a strict peer name, so the first occurrence
+  // is authoritative. Resource segments may legitimately be "_" (a valid
+  // tmux session name) and must not be mistaken for another boundary.
+  if (idx < 0) return null;
+  const route = parts.slice(0, idx);
+  const resource = `/${parts.slice(idx + 1).join('/')}`;
+  if (route.length > MAX_HOPS || route.some((n) => !store.NODE_NAME_RE.test(n))) return null;
+  if (new Set(route).size !== route.length || !knownResource(resource)) return null;
+  return { route, resource };
+}
+
+function knownResource(resource) {
+  return resource === '/sessions'
+    || /^\/sessions\/[\w.@%:+-]{1,128}$/.test(resource)
+    || resource === '/config'
+    || resource === '/fs/dirs'
+    || resource === '/files'
+    || resource === '/files/download'
+    || resource === '/files/upload'
+    || resource === '/ws';
+}
+
+function allowedResource(resource, method = 'GET') {
+  if (resource === '/sessions') return method === 'GET' || method === 'POST';
+  if (/^\/sessions\/[\w.@%:+-]{1,128}$/.test(resource)) return method === 'DELETE';
+  if (resource === '/config') return method === 'GET';
+  if (resource === '/fs/dirs') return method === 'GET';
+  if (resource === '/files') return method === 'GET' || method === 'DELETE';
+  if (resource === '/files/download') return method === 'GET';
+  if (resource === '/files/upload') return method === 'POST';
+  if (resource === '/ws') return method === 'GET';
+  return false;
+}
+
+function cleanHeaders(headers, credential, visited = null) {
+  const out = sanitizeRequestHeaders(headers, credential);
+  for (const key of Object.keys(out)) {
+    if (['x-nexuscrew-route', 'x-nexuscrew-visited', 'x-nexuscrew-hop'].includes(key.toLowerCase())) delete out[key];
+  }
+  if (Array.isArray(visited) && visited.length) out['x-nexuscrew-visited'] = visited.join(',');
+  return out;
+}
+
+function proxyHttp(req, res, { port, path, credential, visited = null }) {
+  const up = http.request({ host: '127.0.0.1', port, method: req.method, path, headers: cleanHeaders(req.headers, credential, visited) }, (r) => {
+    res.writeHead(r.statusCode, sanitizeResponseHeaders(r.headers)); r.pipe(res);
+  });
+  up.setTimeout(30000, () => up.destroy());
+  up.on('error', () => { if (!res.headersSent) res.status(502).json({ error: 'peer non raggiungibile' }); else res.destroy(); });
+  req.pipe(up);
+}
+
+function routeHandler({ nodesPath, localPort, localCredential, ingress = null, readonly = () => false }) {
+  return (req, res) => {
+    const parsed = parseRoute(req.url);
+    if (!parsed || !allowedResource(parsed.resource, req.method)) return res.status(404).json({ error: 'not found' });
+    if (readonly() && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method)) return res.status(403).json({ error: 'READONLY: federated mutation blocked' });
+    const st = store.loadStore(nodesPath);
+    if (!st) return res.status(503).json({ error: 'node store unavailable' });
+    const visited = controlledVisited(req, ingress, st.nodeId);
+    if (!visited) return res.status(409).json({ error: 'federation cycle rejected' });
+    if (parsed.route.length === 0) {
+      return proxyHttp(req, res, { port: typeof localPort === 'function' ? localPort() : localPort, path: `/api${parsed.resource}${queryOf(req.url)}`, credential: localCredential() });
+    }
+    const next = st && store.getNode(st, parsed.route[0]);
+    if (!next || !next.token || (ingress && !canTransit(ingress, next))) return res.status(403).json({ error: 'route non consentita' });
+    const rest = parsed.route.slice(1);
+    const path = `/federation/route/${rest.length ? `${rest.join('/')}/` : ''}${ROUTE_DELIMITER}${parsed.resource}${queryOf(req.url)}`;
+    proxyHttp(req, res, { port: next.localPort, path, credential: next.token, visited });
+  };
+}
+
+function queryOf(url) {
+  const i = String(url).indexOf('?');
+  return i < 0 ? '' : stripLocalTokenQuery(String(url).slice(i));
+}
+
+function controlledVisited(req, ingress, instanceId) {
+  const raw = ingress ? String(req.headers['x-nexuscrew-visited'] || '') : '';
+  const seen = raw ? raw.split(',').filter(Boolean) : [];
+  if (seen.some((id) => !store.NODE_ID_RE.test(id)) || seen.includes(instanceId) || seen.length > MAX_HOPS) return null;
+  return [...seen, instanceId];
+}
+
+async function collectTopology({ nodesPath, ingress = null, ttl = MAX_HOPS, visited = [], fetchImpl = fetch }) {
+  const st = store.loadStore(nodesPath);
+  if (!st) return { instanceId: null, nodes: [] };
+  const seen = new Set(visited.filter((x) => store.NODE_ID_RE.test(x)));
+  seen.add(st.nodeId);
+  const out = [];
+  for (const n of st.nodes) {
+    if (!n.nodeId || seen.has(n.nodeId) || (ingress && !canTransit(ingress, n))) continue;
+    out.push({ instanceId: n.nodeId, name: n.name, route: [n.name], direct: true });
+    if (ttl <= 1 || !n.token) continue;
+    try {
+      const u = `http://127.0.0.1:${n.localPort}/federation/topology?ttl=${ttl - 1}&visited=${encodeURIComponent([...seen].join(','))}`;
+      const r = await fetchImpl(u, { headers: { authorization: `Bearer ${n.token}` } });
+      const j = await r.json();
+      if (!r.ok || j.instanceId !== n.nodeId || !Array.isArray(j.nodes)) continue;
+      for (const child of j.nodes) {
+        if (!child || !store.NODE_ID_RE.test(child.instanceId) || child.instanceId === n.nodeId || seen.has(child.instanceId)
+          || !store.NODE_NAME_RE.test(child.name)
+          || !Array.isArray(child.route) || child.route.length < 1 || child.route.length >= ttl
+          || child.route.some((x) => !store.NODE_NAME_RE.test(x))
+          || new Set(child.route).size !== child.route.length
+          || child.name !== child.route[child.route.length - 1]
+          || child.route.includes(n.name)) continue;
+        out.push({ instanceId: child.instanceId, name: child.name, route: [n.name, ...child.route], direct: false });
+      }
+    } catch (_) {}
+  }
+  const ids = new Set(); const routes = new Set(); const unique = [];
+  for (const n of out.sort((a, b) => a.route.length - b.route.length)) {
+    const routeKey = n.route.join('/');
+    if (ids.has(n.instanceId) || routes.has(routeKey)) continue;
+    ids.add(n.instanceId); routes.add(routeKey); unique.push(n);
+  }
+  return { instanceId: st.nodeId, nodes: unique };
+}
+
+function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly }) {
+  const r = express.Router();
+  r.use((req, res, next) => {
+    const peer = peerFromToken(nodesPath, bearerFrom(req));
+    if (!peer) return res.status(401).json({ error: 'unauthorized peer' });
+    req.peer = peer; next();
+  });
+  r.get('/topology', async (req, res) => {
+    const ttl = Math.max(0, Math.min(MAX_HOPS, Number(req.query.ttl) || MAX_HOPS));
+    const visited = String(req.query.visited || '').split(',');
+    res.json(await collectTopology({ nodesPath, ingress: req.peer, ttl, visited, fetchImpl }));
+  });
+  r.use('/route', (req, res) => routeHandler({ nodesPath, localPort, localCredential, ingress: req.peer, readonly })(req, res));
+  return r;
+}
+
+function localRouter({ nodesPath, localPort, localCredential, readonly }) {
+  const r = express.Router();
+  r.use((req, res) => routeHandler({ nodesPath, localPort, localCredential, readonly })(req, res));
+  return r;
+}
+
+function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredential, ingress, readonly = () => false, activeSockets = null }) {
+  if (readonly()) return reject(socket, 403);
+  const parsed = parseRoute(req.url.replace(/^\/(?:api\/route|federation\/route)/, ''));
+  if (!parsed || parsed.resource !== '/ws') return reject(socket, 404);
+  const st = store.loadStore(nodesPath);
+  if (!st) return reject(socket, 503);
+  const visited = controlledVisited(req, ingress, st.nodeId);
+  if (!visited) return reject(socket, 409);
+  let port = typeof localPort === 'function' ? localPort() : localPort; let credential = localCredential(); let path = '/ws';
+  if (parsed.route.length) {
+    const next = store.getNode(st, parsed.route[0]);
+    if (!next || !next.token || (ingress && !canTransit(ingress, next))) return reject(socket, 403);
+    port = next.localPort; credential = next.token;
+    const rest = parsed.route.slice(1);
+    path = `/federation/route/${rest.length ? `${rest.join('/')}/` : ''}${ROUTE_DELIMITER}/ws`;
+  }
+  const up = net.connect({ host: '127.0.0.1', port });
+  up.once('connect', () => {
+    const headers = cleanHeaders(req.headers, credential, parsed.route.length ? visited : null);
+    const lines = [`GET ${path} HTTP/1.1`, `Host: 127.0.0.1:${port}`];
+    for (const [k, v] of Object.entries(headers)) lines.push(`${k}: ${Array.isArray(v) ? v.join(', ') : v}`);
+    lines.push('Connection: Upgrade', 'Upgrade: websocket', '', '');
+    up.write(lines.join('\r\n')); if (head && head.length) up.write(head);
+    if (activeSockets && typeof activeSockets.add === 'function') {
+      activeSockets.add(socket); activeSockets.add(up);
+      const remove = () => { activeSockets.delete(socket); activeSockets.delete(up); };
+      socket.once('close', remove); up.once('close', remove);
+    }
+    socket.pipe(up); up.pipe(socket);
+  });
+  up.on('error', () => reject(socket, 502)); socket.on('error', () => up.destroy());
+}
+
+function reject(socket, code) { try { socket.end(`HTTP/1.1 ${code} Error\r\nConnection: close\r\n\r\n`); } catch (_) {} }
+
+module.exports = {
+  MAX_HOPS, ROUTE_DELIMITER, peerFromToken, peerAllows, canTransit, parseRoute, knownResource, allowedResource,
+  collectTopology, peerRouter, localRouter, forwardUpgrade,
+};

package/lib/proxy/node-proxy.js

@@ -49,6 +49,19 @@ function isStrippedRequestHeader(lk) {
   return false;
 }
 
+function connectionOptions(headers) {
+  const names = new Set();
+  for (const [key, value] of Object.entries(headers || {})) {
+    if (key.toLowerCase() !== 'connection') continue;
+    const raw = Array.isArray(value) ? value.join(',') : String(value || '');
+    for (const item of raw.split(',')) {
+      const name = item.trim().toLowerCase();
+      if (/^[!#$%&'*+.^_`|~0-9a-z-]+$/.test(name)) names.add(name);
+    }
+  }
+  return names;
+}
+
 // Divide "/vps/api/x?y=1" -> { name:'vps', rest:'/api/x', search:'?y=1' }.
 // name RAW (non decodificato): validato poi contro l'allowlist strict, cosi'
 // '..', '%2e', nomi lunghi falliscono il regex -> 404. rest/search preservano
@@ -79,8 +92,9 @@ function isTransitiveRest(rest) {
 // del nodo. host lo mette node http.request da host/port (loopback da config).
 function sanitizeRequestHeaders(headers, remoteToken) {
   const out = {};
+  const dynamicHop = connectionOptions(headers);
   for (const [k, v] of Object.entries(headers || {})) {
-    if (isStrippedRequestHeader(k.toLowerCase())) continue;
+    if (isStrippedRequestHeader(k.toLowerCase()) || dynamicHop.has(k.toLowerCase())) continue;
     out[k] = v;
   }
   if (remoteToken) out.authorization = `Bearer ${remoteToken}`;
@@ -91,8 +105,9 @@ function sanitizeRequestHeaders(headers, remoteToken) {
 // token remoto non viene MAI messo qui dal proxy; il nodo remoto non lo riflette.
 function sanitizeResponseHeaders(headers) {
   const out = {};
+  const dynamicHop = connectionOptions(headers);
   for (const [k, v] of Object.entries(headers || {})) {
-    if (HOP_BY_HOP.has(k.toLowerCase())) continue;
+    if (HOP_BY_HOP.has(k.toLowerCase()) || dynamicHop.has(k.toLowerCase())) continue;
     out[k] = v;
   }
   return out;
@@ -187,19 +202,17 @@ function abortUpgrade(socket, code) {
 function buildUpgradeRequest(method, rest, search, headers, remoteToken, localPort) {
   const lines = [];
   const cleanSearch = stripLocalTokenQuery(search);
+  const clean = sanitizeRequestHeaders(headers, remoteToken);
   lines.push(`${method} ${rest}${cleanSearch} HTTP/1.1`);
   lines.push(`Host: 127.0.0.1:${localPort}`);
-  for (const [k, v] of Object.entries(headers || {})) {
+  for (const [k, v] of Object.entries(clean)) {
     const lk = k.toLowerCase();
-    if (lk === 'host') continue;
-    if (lk === 'connection' || lk === 'upgrade') continue; // ri-aggiunti controllati
-    if (isStrippedRequestHeader(lk)) continue;             // authorization/cookie/proxy-*/x-forwarded-*/hop-by-hop
+    if (lk === 'host' || lk === 'connection' || lk === 'upgrade') continue;
     const val = Array.isArray(v) ? v.join(', ') : v;
     lines.push(`${k}: ${val}`);
   }
   lines.push('Connection: Upgrade');
   lines.push('Upgrade: websocket');
-  if (remoteToken) lines.push(`Authorization: Bearer ${remoteToken}`);
   return `${lines.join('\r\n')}\r\n\r\n`;
 }
 
@@ -287,6 +300,6 @@ module.exports = {
   handleNodeUpgrade,
   // esposti per i test
   splitNodePath, isTransitiveRest, sanitizeRequestHeaders, sanitizeResponseHeaders,
-  buildUpgradeRequest, stripLocalTokenQuery, isStrippedRequestHeader, bearerFromUpgrade,
+  buildUpgradeRequest, stripLocalTokenQuery, isStrippedRequestHeader, connectionOptions, bearerFromUpgrade,
   MUTATING, HOP_BY_HOP, PROXY_TIMEOUT_MS,
 };

package/lib/server.js

@@ -2,10 +2,12 @@
 const http = require('node:http');
 const path = require('node:path');
 const os = require('node:os');
+const fs = require('node:fs');
 const { execFileSync } = require('node:child_process');
 const express = require('express');
 const { WebSocketServer } = require('ws');
-const { defaults, loadConfig, assertLoopback } = require('./config.js');
+const { defaults, loadConfig, assertLoopback, configJsonPath } = require('./config.js');
+const { writeConfigAtomic } = require('./cli/init.js');
 const { listSessions, attachedClients } = require('./tmux/list.js');
 const { runAction, pasteToSession } = require('./tmux/actions.js');
 const { createSession, killSession, isProtectedSession } = require('./tmux/lifecycle.js');
@@ -24,7 +26,8 @@ const { fsRoutes } = require('./fs/routes.js');
 const nodesStore = require('./nodes/store.js');
 const nodesTunnel = require('./nodes/tunnel.js');
 const { createNodeProxy, handleNodeUpgrade } = require('./proxy/node-proxy.js');
-const { settingsRoutes } = require('./settings/routes.js');
+const federation = require('./proxy/federation.js');
+const { settingsRoutes, publicPeeringRoutes } = require('./settings/routes.js');
 const decksStore = require('./decks/store.js');
 const { decksRoutes } = require('./decks/routes.js');
 const { createEventsHub } = require('./notify/events.js');
@@ -123,10 +126,29 @@ function createServer(opts = {}) {
     }
   }
 
+  // New Hydra peers are ordinary local+remote nodes. Only the side that owns
+  // the outbound SSH alias dials; inbound records are reached through its -R.
+  {
+    const st = nodesStore.loadStore(nodesPath);
+    for (const node of (st && st.nodes) || []) {
+      if (node.direction !== 'inbound' && node.autostart === true) {
+        const tr = nodesTunnel.startForward({
+          home: cfg.home || os.homedir(), node, localAppPort: cfg.port,
+          spawnImpl: cfg.tunnelSpawnImpl, spawnSyncImpl: cfg.tunnelSpawnSyncImpl,
+          sshBin: cfg.sshBin, logFd: cfg.tunnelLogFd,
+        });
+        if (!tr.started && tr.reason !== 'already running') {
+          process.stderr.write(`[nexuscrew] peer ${node.name} autostart failed: ${tr.reason || 'unknown'}\n`);
+        }
+      }
+    }
+  }
+
   const app = express();
   const distDir = path.join(__dirname, '..', 'frontend', 'dist');
   // no-store on everything (HTML+assets+API): this is a local, token-adjacent tool.
   app.use((_req, res, next) => { res.set('Cache-Control', 'no-store'); next(); });
+  app.use('/pair', publicPeeringRoutes({ cfg, nodesPath }));
 
   // Tutte le /api dietro Bearer: sul loopback il gate vero è il tunnel,
   // ma il token chiude anche altri processi locali della stessa macchina.
@@ -145,6 +167,7 @@ function createServer(opts = {}) {
     } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
   });
   api.post('/sessions', express.json({ limit: '4kb' }), async (req, res) => {
+    if (proxyReadonly()) return res.status(403).json({ error: 'READONLY: creazione sessione bloccata' });
     try {
       const { name, cwd, preset } = req.body || {};
       await createSession(cfg.tmuxBin, { name, cwd, preset },
@@ -153,6 +176,7 @@ function createServer(opts = {}) {
     } catch (e) { res.status(e.status || 500).json({ error: String(e.message || e) }); }
   });
   api.delete('/sessions/:name', async (req, res) => {
+    if (proxyReadonly()) return res.status(403).json({ error: 'READONLY: eliminazione sessione bloccata' });
     const name = String(req.params.name || '');
     try {
       const fleet = await fleetP;
@@ -167,6 +191,7 @@ function createServer(opts = {}) {
   api.get('/config', (_req, res) => res.json({
     readonlyDefault: cfg.readonlyDefault, version: VERSION, uiVersion: uiBuildVersion(distDir),
     bind: cfg.bind, port: cfg.port,
+    instanceId: (nodesStore.loadStore(nodesPath) || {}).nodeId || null,
     presets: ['shell', 'claude', 'codex-vl', 'pi', ...Object.keys(cfg.sessionPresets || {})],
   }));
   api.use('/files', filesRoutes({
@@ -174,6 +199,7 @@ function createServer(opts = {}) {
     sessionExists: (name) => sessionExists(cfg.tmuxBin, name),
     paste: (session, text) => pasteToSession(cfg.tmuxBin, session, text),
     notifier,
+    readonly: proxyReadonly,
   }));
   // MCP bridge (design §2): /notify, /push/*, /asks — dietro lo stesso Bearer
   // del router /api; gate READONLY sui mutanti dentro notifyRoutes.
@@ -195,7 +221,10 @@ function createServer(opts = {}) {
       const st = nodesStore.loadStore(nodesPath);
       if (!st) return res.json({ nodeId: null, nodes: [] });
       const view = nodesStore.redactStore(st);
-      const nodes = view.nodes.map((n) => ({ ...n, tunnel: nodesTunnel.readTunnelState(os.homedir(), n.name) }));
+      const nodes = view.nodes.map((n) => ({
+        ...n,
+        tunnel: n.direction === 'inbound' ? { status: 'up', managed: false } : nodesTunnel.readTunnelState(os.homedir(), n.name),
+      }));
       const out = { nodeId: view.nodeId, nodes };
       if (view.rendezvous) out.rendezvous = view.rendezvous;
       res.json(out);
@@ -205,6 +234,13 @@ function createServer(opts = {}) {
   // wizard/settings UI. Dietro lo stesso requireToken del router /api; il gate
   // READONLY route-level e la redazione token vivono dentro settingsRoutes.
   api.use('/settings', settingsRoutes({ cfg, nodesPath, tokenStore, closeSessions }));
+  api.get('/topology', async (_req, res) => {
+    try { res.json(await federation.collectTopology({ nodesPath })); }
+    catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+  api.use('/route', federation.localRouter({
+    nodesPath, localPort: () => cfg.port, localCredential: () => tokenHolder.value, readonly: proxyReadonly,
+  }));
   api.get('/voice/status', (_req, res) => res.json({ serverSttConfigured: !!cfg.voiceUrl }));
   api.post('/voice/transcribe',
     express.raw({ type: () => true, limit: '25mb' }),
@@ -227,6 +263,9 @@ function createServer(opts = {}) {
   });
 
   app.use('/api', api);
+  app.use('/federation', federation.peerRouter({
+    nodesPath, localPort: () => cfg.port, localCredential: () => tokenHolder.value, readonly: proxyReadonly,
+  }));
 
   // Reverse-proxy single-origin /node/<name>/… (design §4b(2)). Auth locale PRIMA
   // di risolvere <name>: requireToken(token) davanti al router, nessuna route
@@ -282,6 +321,19 @@ function createServer(opts = {}) {
       wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req));
       return;
     }
+    if (pathname.startsWith('/api/route/')) {
+      let u; try { u = new URL(req.url, 'http://127.0.0.1'); } catch (_) { return socket.destroy(); }
+      const given = bearerFrom(req) || u.searchParams.get('token') || '';
+      if (!verify(tokenHolder.value, given)) return socket.destroy();
+      federation.forwardUpgrade({ req, socket, head, nodesPath, localPort: () => cfg.port, localCredential: () => tokenHolder.value, ingress: null, readonly: proxyReadonly, activeSockets: proxySockets });
+      return;
+    }
+    if (pathname.startsWith('/federation/route/')) {
+      const ingress = federation.peerFromToken(nodesPath, bearerFrom(req));
+      if (!ingress) return socket.destroy();
+      federation.forwardUpgrade({ req, socket, head, nodesPath, localPort: () => cfg.port, localCredential: () => tokenHolder.value, ingress, readonly: proxyReadonly, activeSockets: proxySockets });
+      return;
+    }
     if (pathname === '/node' || pathname.startsWith('/node/')) {
       handleNodeUpgrade({
         req, socket, head, resolveNode,
@@ -330,13 +382,44 @@ function createServer(opts = {}) {
 function start(opts = {}) {
   const { server, cfg } = createServer(opts);
   const log = opts.log || console.log;
-  server.listen(cfg.port, cfg.bind, () => {
+  const requestedPort = cfg.port;
+  const onListening = () => {
+    cfg.port = server.address().port;
     // Il token NON si stampa allo startup: finirebbe nei log del servizio
-    // (journalctl/logfile), che `nexuscrew logs` espone — contratto A2
-    // "token mai nei log". Per l'URL completo: `nexuscrew url` (o --qr).
-    log(`nexuscrew on http://${cfg.bind}:${cfg.port}  (token: usa \`nexuscrew url\`)`);
+    // (journalctl/logfile). L'apertura autenticata passa da `nexuscrew show`.
+    log(`nexuscrew on http://${cfg.bind}:${cfg.port}  (open with \`nexuscrew show\`)`);
     log('localhost-only — reach it via SSH/autossh/VPN tunnel.');
+  };
+  const persistFallback = () => {
+    const selected = server.address().port;
+    const configPath = opts.configPath || configJsonPath();
+    let current = {};
+    try {
+      const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) current = parsed;
+    } catch (_) {}
+    writeConfigAtomic(configPath, { ...current, port: selected });
+    log(`preferred port ${requestedPort} busy; selected ${selected}`);
+    onListening();
+  };
+  const tryFallback = (candidate, remaining) => {
+    server.once('error', (error) => {
+      if (error && error.code === 'EADDRINUSE' && remaining > 1) {
+        tryFallback(candidate >= 65535 ? 41820 : candidate + 1, remaining - 1);
+        return;
+      }
+      throw error;
+    });
+    server.listen(candidate, cfg.bind, persistFallback);
+  };
+  server.once('error', (error) => {
+    if (error && error.code === 'EADDRINUSE' && requestedPort !== 0 && opts.autoPort !== false) {
+      tryFallback(requestedPort >= 65535 ? 41820 : requestedPort + 1, 200);
+      return;
+    }
+    throw error;
   });
+  server.listen(requestedPort, cfg.bind, onListening);
   return server;
 }