@mmmbuto/nexuscrew 0.8.7 → 0.8.10

package/lib/nodes/commands.js

@@ -1,20 +1,22 @@
 'use strict';
-// lib/nodes/commands.js — subcomandi CLI `nodes` e `node` (design §3, §4, §4b).
+// lib/nodes/commands.js — implementation helpers for the authenticated PWA.
 //
-// nodes add/list/remove/test/up/down/restart/set-token + node on/off.
+// Nodes add/list/remove/test/up/down/restart/set-token. These helpers are not
+// advertised as public CLI commands.
 // Invarianti:
 //   - token per-nodo MAI loggati/stampati (redazione sempre; set-token li legge
 //     da stdin/env, mai da argv -> niente segreti in `ps`).
 //   - NEXUSCREW_READONLY blocca le MUTAZIONI DI CONFIG (add/remove/set-token/
-//     on/off), non list/test/status/up/down/restart (lifecycle tunnel, non config).
+//     configuration), while the Settings routes separately gate process lifecycle.
 //   - niente shell interpolation: ssh-keygen via execFile (argv), tunnel via spawn argv.
 const fs = require('node:fs');
+const net = require('node:net');
 const os = require('node:os');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const store = require('./store.js');
 const tunnel = require('./tunnel.js');
-const { resolvePaths, loadPort, DEFAULT_PORT } = require('../cli/url.js');
+const { resolvePaths, DEFAULT_PORT } = require('../cli/url.js');
 
 const LOCAL_PORT_BASE = 43001; // porte locali stabili per i forward (design: stabili da nodes.json)
 
@@ -38,6 +40,49 @@ function assignLocalPort(st) {
   return p;
 }
 
+function bindLocalPort(port, createServerImpl = net.createServer) {
+  return new Promise((resolve, reject) => {
+    const server = createServerImpl();
+    const onError = (error) => {
+      server.removeListener('listening', onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.removeListener('error', onError);
+      if (typeof server.unref === 'function') server.unref();
+      let released = false;
+      resolve({
+        port,
+        release: () => new Promise((done) => {
+          if (released) return done();
+          released = true;
+          try { server.close(() => done()); } catch (_) { done(); }
+        }),
+      });
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen({ host: '127.0.0.1', port, exclusive: true });
+  });
+}
+
+// Selezione OS-aware per il pairing: nodes.json evita collisioni logiche, il
+// bind reale evita porte gia' occupate da processi estranei. La socket resta
+// riservata fino all'avvio del supervisor SSH e viene poi rilasciata una volta.
+async function reserveLocalPort(st, opts = {}) {
+  const used = new Set((st.nodes || []).map((n) => n.localPort));
+  const createServerImpl = opts.createServerImpl || net.createServer;
+  for (let port = opts.start || LOCAL_PORT_BASE; port <= 65535; port += 1) {
+    if (used.has(port)) continue;
+    try { return await bindLocalPort(port, createServerImpl); }
+    catch (error) {
+      if (error && (error.code === 'EADDRINUSE' || error.code === 'EACCES')) continue;
+      throw error;
+    }
+  }
+  throw new Error('nessuna porta locale disponibile per il tunnel');
+}
+
 function defaultKeyPath(home, name) {
   return path.join(home, '.nexuscrew', 'keys', `${name}_ed25519`);
 }
@@ -59,24 +104,6 @@ function ensureKey(keyPath, name, opts = {}) {
   return fs.readFileSync(pubPath, 'utf8').trim();
 }
 
-// Scrittura atomica di config.json preservando il resto (per roles).
-function writeConfigRole(configPath, key, value) {
-  let cfg = {};
-  try { const c = JSON.parse(fs.readFileSync(configPath, 'utf8')); if (c && typeof c === 'object') cfg = c; } catch (_) {}
-  const roles = (cfg.roles && typeof cfg.roles === 'object') ? cfg.roles : {};
-  cfg.roles = { client: !!roles.client, node: !!roles.node };
-  cfg.roles[key] = value;
-  const dir = path.dirname(configPath);
-  fs.mkdirSync(dir, { recursive: true });
-  const tmp = path.join(dir, `.${path.basename(configPath)}.${process.pid}.tmp`);
-  try {
-    fs.writeFileSync(tmp, `${JSON.stringify(cfg, null, 2)}\n`, { mode: 0o600 });
-    fs.chmodSync(tmp, 0o600);
-    fs.renameSync(tmp, configPath);
-  } catch (e) { try { fs.unlinkSync(tmp); } catch (_) {} throw e; }
-  return cfg.roles;
-}
-
 // Legge il token remoto da fonte NON-argv: opts.token (test) > env > stdin.
 // MAI da flag CLI: il token comparirebbe in `ps`/history.
 function readSecretToken(opts) {
@@ -93,7 +120,7 @@ function nodesAdd(opts) {
   const { home, nodesPath } = resolveNodePaths(opts);
   const name = opts.name;
   const ssh = opts.ssh;
-  if (!name) { log('usage: nexuscrew nodes add <name> --ssh user@host [--ssh-port N] [--remote-port N] [--key path] [--local-port N]'); return { code: 1, reason: 'name mancante' }; }
+  if (!name) { log('nodes add: name mancante (configura il nodo dalla PWA)'); return { code: 1, reason: 'name mancante' }; }
   if (!ssh) { log('nodes add: --ssh user@host obbligatorio'); return { code: 1, reason: 'ssh mancante' }; }
 
   const remotePort = opts.remotePort ? Number(opts.remotePort) : DEFAULT_PORT;
@@ -159,7 +186,6 @@ function nodesList(opts) {
   const view = store.redactStore(st); // MAI il token
   const nodes = view.nodes.map((n) => ({ ...n, tunnel: tunnel.readTunnelState(home, n.name) }));
   const out = { nodeId: view.nodeId, nodes };
-  if (view.rendezvous) out.rendezvous = view.rendezvous;
 
   if (opts.json) { log(JSON.stringify(out, null, 2)); return { code: 0, nodes }; }
   if (nodes.length === 0) { log('nodes: (nessun nodo)'); return { code: 0, nodes }; }
@@ -175,7 +201,7 @@ function nodesRemove(opts) {
   if (isReadonly(opts)) { log('nodes remove: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
   const { home, nodesPath } = resolveNodePaths(opts);
   const name = opts.name;
-  if (!name) { log('usage: nexuscrew nodes remove <name>'); return { code: 1 }; }
+  if (!name) { log('nodes remove: name mancante'); return { code: 1 }; }
   const st = store.loadStore(nodesPath);
   if (!st) { log('nodes remove: nessun nodes.json valido'); return { code: 1 }; }
   let next;
@@ -207,15 +233,16 @@ async function nodesTest(opts) {
   const log = opts.log || console.log;
   const { home, nodesPath } = resolveNodePaths(opts);
   const name = opts.name;
-  if (!name) { log('usage: nexuscrew nodes test <name>'); return { code: 1 }; }
+  if (!name) { log('nodes test: name mancante'); return { code: 1 }; }
   const st = store.loadStore(nodesPath);
   const node = st ? store.getNode(st, name) : null;
   if (!node) { log(`nodes test: nodo sconosciuto "${name}"`); return { code: 1, result: 'unknown-node' }; }
 
   const state = tunnel.readTunnelState(home, name);
   if (state.status !== 'up') {
-    log(`nodes test [${name}]: TUNNEL DOWN — avvia con \`nexuscrew nodes up ${name}\``);
-    return { code: 1, result: 'tunnel-down' };
+    const diagnostic = tunnel.diagnoseTunnel(home, node, state);
+    log(`nodes test [${name}]: ${diagnostic.code.toUpperCase()} — ${diagnostic.detail}${diagnostic.hint ? ` · ${diagnostic.hint}` : ''}`);
+    return { code: 1, result: 'tunnel-down', diagnostic };
   }
 
   const httpProbe = opts.httpProbe || defaultHttpProbe;
@@ -226,13 +253,17 @@ async function nodesTest(opts) {
   try { health = await httpProbe(`${base}/`, {}); }
   catch (e) { health = { ok: false, error: e && e.message }; }
   if (!health || !health.ok) {
-    log(`nodes test [${name}]: HEALTH KO — tunnel up ma il server remoto non risponde (${(health && health.error) || 'no 2xx'})`);
-    return { code: 1, result: 'health-ko' };
+    const diagnostic = tunnel.diagnoseTunnel(home, node);
+    const realCause = diagnostic.code !== 'transport-ready' ? diagnostic.detail : ((health && health.error) || 'server HTTP non raggiungibile');
+    log(`nodes test [${name}]: HEALTH KO — ${realCause}${diagnostic.hint ? ` · ${diagnostic.hint}` : ''}`);
+    return { code: 1, result: 'health-ko', diagnostic: diagnostic.code === 'transport-ready'
+      ? { stage: 'http', code: 'peer-http-unreachable', detail: realCause, hint: 'verifica la porta NexusCrew contenuta nel link' }
+      : diagnostic };
   }
 
   // token: GET /api/config con Bearer del nodo -> 200 ok, 401 token KO.
   if (!node.token) {
-    log(`nodes test [${name}]: TOKEN ASSENTE — salva il token remoto con \`nexuscrew nodes set-token ${name}\``);
+    log(`nodes test [${name}]: ASSOCIAZIONE INCOMPLETA — rimuovi il nodo e ripeti il pairing dalla PWA`);
     return { code: 1, result: 'token-missing' };
   }
   let authed;
@@ -242,7 +273,7 @@ async function nodesTest(opts) {
     log(`nodes test [${name}]: OK — tunnel up, health ok, token valido`);
     return { code: 0, result: 'ok' };
   }
-  log(`nodes test [${name}]: TOKEN KO — il token remoto salvato non e' valido (status ${(authed && authed.status) || '?'}); ruota con \`nexuscrew nodes set-token ${name}\``);
+  log(`nodes test [${name}]: CREDENZIALE KO — il pairing non e' piu' valido (status ${(authed && authed.status) || '?'}); ripeti il pairing dalla PWA`);
   return { code: 1, result: 'token-ko' };
 }
 
@@ -256,11 +287,18 @@ async function defaultHttpProbe(url, headers) {
 function loadNodeOrFail(opts, log) {
   const { home, nodesPath } = resolveNodePaths(opts);
   const name = opts.name;
-  if (!name) { log('usage: nexuscrew nodes up|down|restart <name>'); return null; }
+  if (!name) { log('nodes: name mancante'); return null; }
   const st = store.loadStore(nodesPath);
   const node = st ? store.getNode(st, name) : null;
   if (!node) { log(`nodes: nodo sconosciuto "${name}"`); return null; }
-  return { home, node };
+  return { home, nodesPath, store: st, node };
+}
+
+function persistAutostart(ctx, enabled) {
+  const next = store.updateNode(ctx.store, ctx.node.name, { autostart: enabled });
+  store.atomicWriteStore(ctx.nodesPath, next);
+  ctx.store = next;
+  ctx.node = store.getNode(next, ctx.node.name);
 }
 
 function nodesUp(opts) {
@@ -268,29 +306,35 @@ function nodesUp(opts) {
   const ctx = loadNodeOrFail(opts, log);
   if (!ctx) return { code: 1 };
   if (ctx.node.direction === 'inbound') return { code: 0, started: false, inbound: true };
+  if (opts.persistAutostart === true && ctx.node.autostart !== true) {
+    try { persistAutostart(ctx, true); }
+    catch (e) { log(`nodes up [${ctx.node.name}]: impossibile salvare l'avvio automatico — ${e.message}`); return { code: 1, reason: 'autostart write failed' }; }
+  }
   const r = tunnel.startForward({ home: ctx.home, node: ctx.node, localAppPort: opts.localAppPort, spawnImpl: opts.spawnImpl, spawnSyncImpl: opts.spawnSyncImpl, sshBin: opts.sshBin, logFd: opts.logFd });
   if (r.started) {
     log(`nodes up [${ctx.node.name}]: tunnel avviato (pid ${r.pid}, local ${ctx.node.localPort})`);
-    return { code: 0, started: true, pid: r.pid };
+    return { code: 0, started: true, pid: r.pid, diagnostic: tunnel.diagnoseTunnel(ctx.home, ctx.node) };
   }
   if (r.reason === 'already running') {
     log(`nodes up [${ctx.node.name}]: gia' attivo (pid ${r.pid})`);
-    return { code: 0, started: false, pid: r.pid };
+    return { code: 0, started: false, pid: r.pid, diagnostic: tunnel.diagnoseTunnel(ctx.home, ctx.node) };
   }
   // failure esplicita (ssh mancante / spawn error): surfacciata a CLI e Settings API.
   log(`nodes up [${ctx.node.name}]: avvio tunnel fallito — ${r.reason}`);
-  return { code: 1, started: false, reason: r.reason };
+  return { code: 1, started: false, reason: r.reason, diagnostic: tunnel.diagnoseTunnel(ctx.home, ctx.node) };
 }
 
 function nodesDown(opts) {
   const log = opts.log || console.log;
-  const { home, nodesPath } = resolveNodePaths(opts);
-  const name = opts.name;
-  if (!name) { log('usage: nexuscrew nodes down <name>'); return { code: 1 }; }
-  const st = store.loadStore(nodesPath);
-  if (!st || !store.getNode(st, name)) { log(`nodes down: nodo sconosciuto "${name}"`); return { code: 1 }; }
-  const r = tunnel.stopTunnel({ home, name });
-  log(`nodes down [${name}]: ${r.stopped ? `fermato (pid ${r.pid})` : r.reason}`);
+  const ctx = loadNodeOrFail(opts, log);
+  if (!ctx) return { code: 1 };
+  if (ctx.node.direction === 'inbound') return { code: 0, stopped: false, inbound: true };
+  if (opts.persistAutostart === true && ctx.node.autostart !== false) {
+    try { persistAutostart(ctx, false); }
+    catch (e) { log(`nodes down [${ctx.node.name}]: impossibile salvare lo stop — ${e.message}`); return { code: 1, reason: 'autostart write failed' }; }
+  }
+  const r = tunnel.stopTunnel({ home: ctx.home, name: ctx.node.name });
+  log(`nodes down [${ctx.node.name}]: ${r.stopped ? `fermato (pid ${r.pid})` : r.reason}`);
   return { code: 0, stopped: r.stopped };
 }
 
@@ -298,16 +342,17 @@ function nodesRestart(opts) {
   const log = opts.log || console.log;
   const ctx = loadNodeOrFail(opts, log);
   if (!ctx) return { code: 1 };
-  const args = tunnel.buildForwardArgs(ctx.node);
-  const r = tunnel.restartTunnel({ home: ctx.home, name: ctx.node.name, args, spawnImpl: opts.spawnImpl, spawnSyncImpl: opts.spawnSyncImpl, sshBin: opts.sshBin, logFd: opts.logFd });
+  if (ctx.node.direction === 'inbound') return { code: 0, started: false, inbound: true };
+  tunnel.stopTunnel({ home: ctx.home, name: ctx.node.name });
+  const r = tunnel.startForward({ home: ctx.home, node: ctx.node, localAppPort: opts.localAppPort, spawnImpl: opts.spawnImpl, spawnSyncImpl: opts.spawnSyncImpl, sshBin: opts.sshBin, logFd: opts.logFd });
   if (r.started) {
     log(`nodes restart [${ctx.node.name}]: tunnel riavviato (pid ${r.pid})`);
-    return { code: 0, started: true, pid: r.pid };
+    return { code: 0, started: true, pid: r.pid, diagnostic: tunnel.diagnoseTunnel(ctx.home, ctx.node) };
   }
   // dopo stop+start, 'already running' non e' atteso: qualunque !started e' un problema
   // esplicito (ssh mancante / spawn error), surfacciato a CLI e Settings API.
   log(`nodes restart [${ctx.node.name}]: riavvio tunnel fallito — ${r.reason || 'sconosciuto'}`);
-  return { code: 1, started: false, reason: r.reason || 'spawn failed' };
+  return { code: 1, started: false, reason: r.reason || 'spawn failed', diagnostic: tunnel.diagnoseTunnel(ctx.home, ctx.node) };
 }
 
 // --- nodes set-token (aggiorna il token remoto; MAI da argv) ----------------
@@ -316,7 +361,7 @@ function nodesSetToken(opts) {
   if (isReadonly(opts)) { log('nodes set-token: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
   const { nodesPath } = resolveNodePaths(opts);
   const name = opts.name;
-  if (!name) { log('usage: nexuscrew nodes set-token <name>  (token da stdin o env NEXUSCREW_NODE_TOKEN)'); return { code: 1 }; }
+  if (!name) { log('nodes set-token: name mancante'); return { code: 1 }; }
   const st = store.loadStore(nodesPath);
   if (!st || !store.getNode(st, name)) { log(`nodes set-token: nodo sconosciuto "${name}"`); return { code: 1 }; }
   const token = readSecretToken(opts);
@@ -329,83 +374,10 @@ function nodesSetToken(opts) {
   return { code: 0, name };
 }
 
-// --- node on|off (ruolo "nodo raggiungibile", reverse tunnel) ---------------
-function nodeOn(opts) {
-  const log = opts.log || console.log;
-  if (isReadonly(opts)) { log('node on: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
-  const { home, configPath, nodesPath } = resolveNodePaths(opts);
-
-  // Gate permitlisten (§7 advisory a): il ruolo node richiede reverse tunnel con
-  // permitlisten sul rendezvous (OpenSSH >=7.8). Se la versione e' nota ed e'
-  // troppo vecchia -> rifiuta PRIMA di abilitare. Ignota -> warn, non blocca.
-  const v = (opts.sshVersion || tunnel.readSshVersion)(opts.spawnSyncImpl);
-  const supp = tunnel.sshSupportsPermitlisten(v);
-  if (supp === false) {
-    log(`node on: OpenSSH ${v.major}.${v.minor} < 7.8 — permitlisten non supportato dal client; il ruolo node NON e' abilitabile con questa toolchain`);
-    return { code: 1, reason: 'permitlisten' };
-  }
-  if (supp === null) log('node on: versione OpenSSH non determinabile — verifica che il rendezvous supporti permitlisten (>=7.8)');
-
-  // Configurazione rendezvous opzionale (flags) o gia' presente in nodes.json.
-  let st;
-  try { st = store.loadOrInitStore(nodesPath); }
-  catch (e) { log(`node on: ${e.message}`); return { code: 1 }; }
-
-  if (opts.rendezvousSsh) {
-    const localPort = loadPort(opts); // porta nexus locale da esporre
-    const publishedPort = opts.publishedPort ? Number(opts.publishedPort) : localPort;
-    const keyPath = opts.key || path.join(home, '.nexuscrew', 'keys', 'rendezvous_ed25519');
-    let pub;
-    try { pub = ensureKey(keyPath, 'rendezvous', opts); }
-    catch (e) { log(`node on: generazione chiave rendezvous fallita (${e.message})`); return { code: 1 }; }
-    let next;
-    try { next = store.setRendezvous(st, { ssh: opts.rendezvousSsh, publishedPort, localPort, keyPath }); }
-    catch (e) { log(`node on: ${e.message}`); return { code: 1 }; }
-    store.atomicWriteStore(nodesPath, next);
-    st = next;
-    log(`node on: rendezvous configurato (${opts.rendezvousSsh}, published ${publishedPort} <- local ${localPort})`);
-    log('Incolla nel ~/.ssh/authorized_keys del RENDEZVOUS (lato reverse, chiave dedicata):');
-    // permitlisten vincola i -R alla SOLA porta pubblicata (loopback esplicito).
-    log(`restrict,port-forwarding,permitlisten="127.0.0.1:${publishedPort}",command="/bin/false" ${pub}`);
-  } else if (!st.rendezvous) {
-    log('node on: nessun rendezvous configurato — passa --rendezvous user@host [--published-port N] [--key path]');
-    return { code: 1, reason: 'no rendezvous' };
-  }
-
-  // Avvia un supervisor detached per il reverse tunnel. Il supervisor ritenta
-  // con backoff: al primo setup può partire prima che la pubkey sia stata
-  // incollata sul rendezvous e convergerà automaticamente appena autorizzata.
-  const tr = tunnel.startReverse({
-    home, rendezvous: st.rendezvous,
-    spawnImpl: opts.spawnImpl, spawnSyncImpl: opts.spawnSyncImpl,
-    sshBin: opts.sshBin, logFd: opts.logFd,
-  });
-  if (!tr.started && tr.reason !== 'already running') {
-    log(`node on: reverse tunnel non avviato — ${tr.reason || 'errore sconosciuto'}; ruolo NON abilitato`);
-    return { code: 1, reason: 'reverse tunnel failed' };
-  }
-
-  const roles = writeConfigRole(configPath, 'node', true);
-  log(`node on: ruolo node ABILITATO (roles: client=${roles.client} node=${roles.node}, reverse pid=${tr.pid})`);
-  return { code: 0, roles, tunnel: { started: !!tr.started, pid: tr.pid } };
-}
-
-function nodeOff(opts) {
-  const log = opts.log || console.log;
-  if (isReadonly(opts)) { log('node off: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
-  const { home, configPath } = resolveNodePaths(opts);
-  const roles = writeConfigRole(configPath, 'node', false);
-  // Ferma un eventuale reverse tunnel attivo (best-effort, non tocca la config rendezvous).
-  try { tunnel.stopTunnel({ home, name: tunnel.REVERSE_NAME }); } catch (_) {}
-  log(`node off: ruolo node DISABILITATO (roles: client=${roles.client} node=${roles.node})`);
-  return { code: 0, roles };
-}
-
 module.exports = {
   nodesAdd, nodesList, nodesRemove, nodesTest,
   nodesUp, nodesDown, nodesRestart, nodesSetToken,
-  nodeOn, nodeOff,
   // helper esposti per test/riuso
-  assignLocalPort, defaultKeyPath, ensureKey, writeConfigRole, readSecretToken,
+  assignLocalPort, bindLocalPort, reserveLocalPort, defaultKeyPath, ensureKey, readSecretToken,
   resolveNodePaths, defaultHttpProbe,
 };

package/lib/nodes/health.js

@@ -30,22 +30,29 @@ function clearHealthCache() { cache.clear(); }
 // onesto). outbound down/401 -> 'down'/'degraded'.
 function tunnelFromHealth(h) {
   if (!h) return { status: 'unknown', managed: false };
-  if (h.transport === 'up' && h.auth === 'ok') return { status: 'up', managed: h.managed !== false };
-  if (h.transport === 'up' && h.auth === 'failed') return { status: 'degraded', managed: h.managed !== false };
-  if (h.transport === 'up') return { status: 'degraded', managed: h.managed !== false };
-  if (h.transport === 'down') return { status: 'down', managed: h.managed !== false };
+  const used = h.transportEngine ? { transport: h.transportEngine } : {};
+  if (h.status === 'passive') return { status: 'passive', managed: false, ...used };
+  if (h.transport === 'up' && h.auth === 'ok') return { status: 'up', managed: h.managed !== false, ...used };
+  if (h.transport === 'up' && h.auth === 'failed') return { status: 'degraded', managed: h.managed !== false, ...used };
+  if (h.transport === 'up') return { status: 'degraded', managed: h.managed !== false, ...used };
+  if (h.transport === 'down') return { status: 'down', managed: h.managed !== false, ...used };
   return { status: 'unknown', managed: false }; // inbound / unknown
 }
 
 async function nodeHealth({ node, home, fetchImpl, now = Date.now(), force = false }) {
   if (!node || typeof node !== 'object') return null;
-  const cacheKey = `${home || ''}\0${node.direction || 'outbound'}\0${node.name}\0${node.localPort}\0${node.nodeId || ''}`;
+  const cacheKey = `${home || ''}\0${node.direction || 'outbound'}\0${node.name}\0${node.localPort}\0${node.nodeId || ''}\0${node.shared === true}\0${node.rolesKnown === true}\0${node.roles?.node === true}`;
   const cached = !force && cache.get(cacheKey);
   if (cached && (now - cached.at) < TTL_MS) return cached.health;
 
   let health;
   if (node.direction === 'inbound') {
-    if (!node.token) {
+    if (node.shared !== true) {
+      health = {
+        transport: 'unknown', auth: 'unknown', reachability: 'unknown', status: 'passive',
+        detail: 'client privato collegato (Share disattivato)', expected: true, managed: false, at: now,
+      };
+    } else if (!node.token) {
       health = {
         transport: 'unknown', auth: 'unknown', reachability: 'unknown', status: 'degraded',
         detail: 'peer inbound senza credenziale federation — re-pair', managed: false, at: now,
@@ -54,27 +61,39 @@ async function nodeHealth({ node, home, fetchImpl, now = Date.now(), force = fal
       const probed = await probeHealth({
         port: node.localPort, token: node.token, expectedInstanceId: node.nodeId || null, fetchImpl, now,
       });
-      health = { ...probed, managed: false };
+      // The receiving side does not own an inbound client's lifecycle. A
+      // client-only (or legacy unknown-role) peer being offline is expected,
+      // not a broken server. Live auth/payload failures remain real failures.
+      if (probed.transport === 'down' && (node.rolesKnown !== true || node.roles?.node !== true)) {
+        health = {
+          ...probed, status: 'passive', expected: true, managed: false,
+          detail: node.rolesKnown === true ? 'client peer offline (expected)' : 'inbound peer offline',
+        };
+      } else {
+        health = { ...probed, managed: false };
+      }
     }
   } else {
     const ts = nodesTunnel.readTunnelState(home, node.name);
     if (ts.status !== 'up') {
-    health = {
-      transport: 'down', auth: 'unknown', reachability: 'unknown', status: 'down',
-      detail: ts.reason ? `tunnel down (${ts.reason})` : 'tunnel down',
-      managed: ts.managed !== false, at: now,
-    };
+      const diagnostic = nodesTunnel.diagnoseTunnel(home, node, ts);
+      health = {
+        transport: 'down', auth: 'unknown', reachability: 'unknown', status: 'down',
+        detail: diagnostic.detail, code: diagnostic.code, stage: diagnostic.stage,
+        ...(diagnostic.hint ? { hint: diagnostic.hint } : {}),
+        transportEngine: ts.transport || 'ssh', managed: ts.managed !== false, at: now,
+      };
     } else if (!node.token) {
     health = {
       transport: 'up', auth: 'unknown', reachability: 'unknown', status: 'degraded',
       detail: 'tunnel up, credenziali federation assenti (token mancante) — re-pair',
-      managed: true, at: now,
+      transportEngine: ts.transport || 'ssh', managed: true, at: now,
     };
     } else {
       const probed = await probeHealth({
         port: node.localPort, token: node.token, expectedInstanceId: node.nodeId || null, fetchImpl, now,
       });
-      health = { ...probed, managed: true };
+      health = { ...probed, transportEngine: ts.transport || 'ssh', managed: true };
     }
   }
   cache.set(cacheKey, { health, at: now });

package/lib/nodes/peering.js

@@ -7,6 +7,8 @@ const store = require('./store.js');
 
 const INVITE_TTL_MS = 10 * 60 * 1000;
 const REVERSE_PORT_BASE = 44001;
+const CAPABILITY_ID_RE = /^[a-f0-9]{64}$/;
+const CHALLENGE_RE = /^[A-Za-z0-9_-]{16,128}$/;
 
 function defaultInvitesPath(home) { return path.join(home, '.nexuscrew', 'invites.json'); }
 function defaultPendingPath(home) { return path.join(home, '.nexuscrew', 'pairing-pending.json'); }
@@ -89,7 +91,7 @@ function parsePairingUrl(value) {
 }
 
 function createInvite({
-  invitesPath, instanceId, port, label = 'NexusCrew', now = Date.now(), randomBytes = crypto.randomBytes,
+  invitesPath, instanceId, port, linkPort = port, label = 'NexusCrew', now = Date.now(), randomBytes = crypto.randomBytes,
   ssh, sshPort, name,
 } = {}) {
   const invite = randomBytes(32).toString('base64url');
@@ -116,7 +118,8 @@ function createInvite({
     if (sshVal && store.isPort(sshPort)) payload.sshPort = sshPort;
   }
   const pair = encodePairing(payload);
-  return { pairingUrl: `http://127.0.0.1:${port}/#pair=${pair}`, expiresAt, version: payload.v };
+  if (!store.isPort(linkPort)) throw new Error('porta locale del link non valida');
+  return { pairingUrl: `http://127.0.0.1:${linkPort}/#pair=${pair}`, expiresAt, version: payload.v };
 }
 
 function consumeInvite({ invitesPath, invite, now = Date.now() }) {
@@ -161,21 +164,81 @@ function consumePending({ pendingPath, credential, now = Date.now() }) {
   return found;
 }
 
-// Probe di trasporto del tunnel -L provvisorio PRIMA di consumare l'invite
-// one-time: qualunque risposta HTTP dal peer attraverso la forward (anche un
-// 401 su /federation/health senza credenziali) dimostra che ssh+forward sono
-// vivi; un errore di rete no. Sostituisce lo sleep fisso 900ms: bounded, con
-// sleep iniettabile (deterministico nei test) e timeout per tentativo.
-async function probeTransportReady({ port, fetchImpl = fetch, attempts = 6, timeoutMs = 1500, sleep } = {}) {
+// Prova pubblica ma capability-bound usata durante il pairing. Il client NON
+// invia mai l'invito/credential: invia SHA256(SHA256(capability)) + challenge;
+// il peer cerca il record attivo e firma il challenge con SHA256(capability).
+// Un processo HTTP estraneo sulla stessa porta non puo' quindi diventare un
+// falso positivo e non riceve materiale sufficiente per consumare l'invito.
+function capabilityIdentity({ invitesPath, pendingPath, capabilityId, challenge, now = Date.now() } = {}) {
+  if (!CAPABILITY_ID_RE.test(String(capabilityId || '')) || !CHALLENGE_RE.test(String(challenge || ''))) return null;
+  const rows = [
+    ...readInvites(invitesPath, now),
+    ...readInvites(pendingPath, now),
+  ];
+  const row = rows.find((x) => {
+    if (!x || !CAPABILITY_ID_RE.test(String(x.hash || ''))) return false;
+    const id = crypto.createHash('sha256').update(Buffer.from(x.hash, 'hex')).digest('hex');
+    return safeEqual(id, capabilityId);
+  });
+  if (!row) return null;
+  return crypto.createHmac('sha256', Buffer.from(row.hash, 'hex')).update(challenge).digest('base64url');
+}
+
+function capabilityProbeMaterial(capability, randomBytes = crypto.randomBytes) {
+  if (!store.validToken(capability)) return null;
+  const key = crypto.createHash('sha256').update(capability).digest();
+  return {
+    key,
+    capabilityId: crypto.createHash('sha256').update(key).digest('hex'),
+    challenge: randomBytes(24).toString('base64url'),
+  };
+}
+
+// Probe di trasporto del tunnel -L PRIMA di consumare l'invito e dopo il
+// restart negoziato. Oltre alla reachability verifica prova capability e
+// instanceId atteso. Bounded, con sleep/random iniettabili per test.
+async function probeTransportReady({
+  port, capability, expectedInstanceId, fetchImpl = fetch, attempts = 6,
+  timeoutMs = 1500, sleep, randomBytes,
+} = {}) {
   const wait = typeof sleep === 'function' ? sleep : (ms) => new Promise((r) => setTimeout(r, ms));
+  const material = capabilityProbeMaterial(capability, randomBytes);
+  if (!store.isPort(port) || !material || !store.NODE_ID_RE.test(String(expectedInstanceId || ''))) {
+    return { ready: false, attempts: 0, code: 'identity-probe-invalid', lastError: 'parametri identity probe non validi' };
+  }
   let lastError = '';
+  let code = 'transport-not-ready';
   for (let i = 0; i < attempts; i += 1) {
     let timer;
     try {
       const ctrl = new AbortController();
       timer = setTimeout(() => ctrl.abort(), timeoutMs);
-      await fetchImpl(`http://127.0.0.1:${port}/federation/health`, { signal: ctrl.signal });
-      return { ready: true, attempts: i + 1 };
+      const response = await fetchImpl(`http://127.0.0.1:${port}/pair/identity`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ capabilityId: material.capabilityId, challenge: material.challenge }),
+        signal: ctrl.signal,
+      });
+      if (!response || response.status !== 200) {
+        code = 'identity-proof-rejected';
+        throw new Error(`identity probe HTTP ${(response && response.status) || '?'}`);
+      }
+      const body = await response.json().catch(() => null);
+      if (!body || body.ok !== true || !store.NODE_ID_RE.test(String(body.instanceId || ''))
+        || typeof body.proof !== 'string') {
+        code = 'identity-proof-invalid';
+        throw new Error('identity probe payload non valido');
+      }
+      if (body.instanceId !== expectedInstanceId) {
+        code = 'peer-identity-mismatch';
+        throw new Error('instanceId del peer non coincide con il link');
+      }
+      const expected = crypto.createHmac('sha256', material.key).update(material.challenge).digest('base64url');
+      if (!safeEqual(expected, body.proof)) {
+        code = 'identity-proof-invalid';
+        throw new Error('prova crittografica del peer non valida');
+      }
+      return { ready: true, attempts: i + 1, instanceId: body.instanceId };
     } catch (e) {
       lastError = String((e && e.message) || e);
     } finally {
@@ -183,12 +246,12 @@ async function probeTransportReady({ port, fetchImpl = fetch, attempts = 6, time
     }
     if (i < attempts - 1) await wait(250 * (i + 1));
   }
-  return { ready: false, attempts, lastError };
+  return { ready: false, attempts, code, lastError };
 }
 
 module.exports = {
   INVITE_TTL_MS, REVERSE_PORT_BASE, defaultInvitesPath, defaultPendingPath, safeEqual,
   readInvites, writeInvites, encodePairing, decodePairing, parsePairingUrl,
   createInvite, consumeInvite, allocateReversePort, createPending, consumePending,
-  probeTransportReady,
+  capabilityIdentity, capabilityProbeMaterial, probeTransportReady,
 };