@mmmbuto/nexuscrew 0.8.19 → 0.8.21

package/lib/nodes/tunnel-supervisor.js

@@ -6,7 +6,7 @@ const fs = require('node:fs');
 const net = require('node:net');
 const path = require('node:path');
 const { spawn } = require('node:child_process');
-const { backoffDelay } = require('./tunnel.js');
+const { backoffDelay, classifySshFailure } = require('./tunnel.js');
 
 const sshBin = process.argv[2];
 const sshArgs = process.argv.slice(3);
@@ -18,6 +18,9 @@ const stableMs = Number.isFinite(stableMsRaw) && stableMsRaw >= 100 ? Math.min(s
 const ownershipGraceRaw = Number(process.env.NEXUSCREW_TUNNEL_OWNERSHIP_GRACE_MS || 2000);
 const ownershipGraceMs = Number.isFinite(ownershipGraceRaw) && ownershipGraceRaw >= 100
   ? Math.min(ownershipGraceRaw, 10000) : 2000;
+const reverseFailureMaxRaw = Number(process.env.NEXUSCREW_TUNNEL_REVERSE_FAILURE_MAX || 8);
+const reverseFailureMax = Number.isInteger(reverseFailureMaxRaw) && reverseFailureMaxRaw >= 1
+  ? Math.min(reverseFailureMaxRaw, 32) : 8;
 if (!sshBin || !statePath || !pidPath || !runId) process.exit(2);
 
 let child = null;
@@ -29,6 +32,7 @@ let forwardProbeTimer = null;
 let forwardSocket = null;
 let ownershipWaitTimer = null;
 let ownershipTimer = null;
+let reverseFailures = 0;
 
 function localForwardPort(args) {
   for (let i = 0; i < args.length - 1; i += 1) {
@@ -42,6 +46,18 @@ function localForwardPort(args) {
 
 const forwardPort = localForwardPort(sshArgs);
 
+function reverseForwardPort(args) {
+  for (let i = 0; i < args.length - 1; i += 1) {
+    if (args[i] !== '-R') continue;
+    const match = String(args[i + 1] || '').match(/^127\.0\.0\.1:(\d+):127\.0\.0\.1:\d+$/);
+    const port = match ? Number(match[1]) : 0;
+    if (Number.isInteger(port) && port >= 1 && port <= 65535) return port;
+  }
+  return null;
+}
+
+const reversePort = reverseForwardPort(sshArgs);
+
 function logEvent(message) {
   try { process.stderr.write(`[nexuscrew] ${String(message).replace(/[\r\n]+/g, ' ')}\n`); } catch (_) {}
 }
@@ -121,17 +137,34 @@ function scheduleRetry(detail) {
   retryTimer = setTimeout(run, delayMs);
 }
 
+function terminalFailure(diagnosis) {
+  const safe = diagnosis || { code: 'reverse-forward-failed', detail: 'canale inverso non disponibile' };
+  logEvent(`ssh terminal failure code=${safe.code} attempts=${reverseFailures}`);
+  writeState('failed', {
+    code: safe.code, detail: safe.detail,
+    ...(safe.hint ? { hint: safe.hint } : {}), terminal: true,
+  });
+  process.exit(0);
+}
+
 function run() {
   if (stopping) return finish();
   if (!writeState('starting')) return stop();
   logEvent(`ssh attempt=${attempt + 1} starting`);
+  let stderrTail = '';
   try {
-    child = spawn(sshBin, sshArgs, { stdio: 'inherit' });
+    child = spawn(sshBin, sshArgs, { stdio: ['ignore', 'inherit', 'pipe'] });
   } catch (e) {
     child = null;
     return scheduleRetry(String(e && e.message || e));
   }
 
+  child.stderr?.on('data', (chunk) => {
+    const text = String(chunk || '');
+    stderrTail = `${stderrTail}${text}`.slice(-8192);
+    try { process.stderr.write(chunk); } catch (_) {}
+  });
+
   let failureHandled = false;
   const handleFailure = (detail) => {
     if (failureHandled) return;
@@ -139,7 +172,15 @@ function run() {
     clearTimeout(upTimer);
     clearForwardProbe();
     child = null;
-    scheduleRetry(detail);
+    const diagnosis = reversePort ? classifySshFailure(stderrTail, reversePort) : null;
+    const reverseFailure = diagnosis && ['reverse-forward-bind', 'reverse-forward-failed'].includes(diagnosis.code);
+    if (reverseFailure) {
+      reverseFailures += 1;
+      if (reverseFailures >= reverseFailureMax) return terminalFailure(diagnosis);
+    } else {
+      reverseFailures = 0;
+    }
+    scheduleRetry((diagnosis && diagnosis.detail) || detail);
   };
   child.once('spawn', () => {
     logEvent(`ssh attempt=${attempt + 1} spawned`);
@@ -156,7 +197,9 @@ function run() {
     logEvent(`ssh child error code=${(e && e.code) || 'unknown'}`);
     handleFailure(String(e && e.message || e));
   });
-  child.once('exit', (code, signal) => {
+  // `close` fires after stderr has drained, so classification sees the complete
+  // OpenSSH diagnostic instead of racing the child `exit` event.
+  child.once('close', (code, signal) => {
     if (stopping) return finish();
     logEvent(`ssh exited code=${code === null ? 'null' : code} signal=${signal || 'none'}`);
     handleFailure(`ssh exited code=${code} signal=${signal || ''}`);

package/lib/nodes/tunnel.js

@@ -186,6 +186,14 @@ function openTunnelLog(home, name) {
 function classifySshFailure(text, remotePort) {
   const s = String(text || '');
   const target = store.isPort(remotePort) ? `127.0.0.1:${remotePort}` : 'la porta NexusCrew richiesta';
+  const reverseMatch = s.match(/remote port forwarding failed for listen port\s+(\d+)/i)
+    || s.match(/(?:bind|listen)[^\r\n]*127\.0\.0\.1:(\d+)/i);
+  const reverseListenPort = reverseMatch ? Number(reverseMatch[1]) : null;
+  const reverseTarget = store.isPort(reverseListenPort)
+    ? `127.0.0.1:${reverseListenPort}` : 'la porta reverse negoziata';
+  const reversePolicy = store.isPort(reverseListenPort)
+    ? `che la chiave SSH autorizzi permitlisten="${reverseTarget}"`
+    : 'che la chiave SSH autorizzi il reverse listen negoziato';
   if (/administratively prohibited|request (?:was )?denied|open failed:.*prohibited|port forwarding.*(?:disabled|denied)/i.test(s)) {
     return {
       code: 'forward-denied',
@@ -209,7 +217,18 @@ function classifySshFailure(text, remotePort) {
     return { code: 'ssh-config', detail: 'configurazione SSH non utilizzabile', hint: 'verifica permessi e opzioni del file ~/.ssh/config' };
   }
   if (/remote port forwarding failed|Could not request remote forwarding/i.test(s)) {
-    return { code: 'reverse-forward-denied', detail: 'il server SSH ha negato il canale inverso del nodo', hint: 'verifica permitlisten/AllowTcpForwarding sul nodo hub' };
+    if (/Address already in use|cannot listen|bind .*failed/i.test(s)) {
+      return {
+        code: 'reverse-forward-bind',
+        detail: 'il canale inverso non può aprire la porta sul nodo hub perché è già occupata',
+        hint: 'verifica un precedente listener SSH sulla stessa porta e l’eventuale doppio supervisor',
+      };
+    }
+    return {
+      code: 'reverse-forward-failed',
+      detail: 'il canale inverso non è stato aperto dal nodo hub',
+      hint: `verifica che ${reverseTarget} non sia occupata e ${reversePolicy}; controlla anche AllowTcpForwarding sul nodo hub`,
+    };
   }
   if (/Could not request local forwarding|Address already in use/i.test(s)) {
     return { code: 'local-forward-bind', detail: 'la porta locale scelta per il tunnel non è disponibile', hint: 'ferma il tunnel precedente e riprova' };
@@ -245,12 +264,27 @@ function tunnelStatePath(home, name) {
 function readTunnelState(home, name) {
   const p = tunnelPidPath(home, name);
   const meta = pidf.readPidfile(p);
+  const terminalState = () => {
+    try {
+      const state = JSON.parse(fs.readFileSync(tunnelStatePath(home, name), 'utf8'));
+      const owned = meta && state.supervisorPid === meta.pid && (!meta.runId || state.runId === meta.runId);
+      if (!owned || state.status !== 'failed' || state.terminal !== true) return null;
+      return {
+        status: 'down', phase: 'failed', reason: 'failed', pid: meta.pid, since: meta.startTs || null,
+        ...(typeof state.code === 'string' ? { code: state.code } : {}),
+        ...(typeof state.detail === 'string' ? { detail: state.detail } : {}),
+        ...(typeof state.hint === 'string' ? { hint: state.hint } : {}),
+        ...(Number.isInteger(state.attempt) ? { attempt: state.attempt } : {}),
+      };
+    } catch (_) { return null; }
+  };
   if (meta && pidf.isAlive(meta)) {
     try {
       const state = JSON.parse(fs.readFileSync(tunnelStatePath(home, name), 'utf8'));
       const transport = typeof state.transport === 'string' ? state.transport : undefined;
       const owned = state.supervisorPid === meta.pid && (!meta.runId || state.runId === meta.runId);
       if (!owned) return { status: 'down', pid: meta.pid, since: meta.startTs || null, reason: 'starting' };
+      if (state.status === 'failed' && state.terminal === true) return terminalState();
       if (state.status === 'transport-ready' || state.status === 'up') {
         return { status: 'up', phase: 'transport-ready', pid: meta.pid, since: meta.startTs || null,
           ...(Number.isInteger(state.attempt) ? { attempt: state.attempt } : {}), ...(transport ? { transport } : {}) };
@@ -267,6 +301,10 @@ function readTunnelState(home, name) {
       return { status: 'down', pid: meta.pid, since: meta.startTs || null, reason: 'starting' };
     }
   }
+  if (meta) {
+    const terminal = terminalState();
+    if (terminal) return terminal;
+  }
   return { status: 'down' };
 }
 
@@ -287,6 +325,13 @@ function diagnoseTunnel(home, node, state = null) {
       detail: `connessione SSH in retry${Number.isInteger(current.attempt) ? ` (tentativo ${current.attempt + 1})` : ''}`,
       hint: 'usa Test connessione per vedere la causa; verifica target SSH, chiave e porta' };
   }
+  if (current.reason === 'failed' || current.phase === 'failed') {
+    return {
+      stage: 'ssh', code: current.code || 'ssh-terminal-failure', status: 'down', phase: 'failed',
+      detail: current.detail || 'connessione SSH fermata dopo errori ripetuti',
+      hint: current.hint || 'correggi la causa e riavvia la connessione dalla PWA',
+    };
+  }
   return { stage: 'ssh', code: 'tunnel-stopped', status: 'down', phase: current.phase || null,
     detail: 'connessione SSH ferma', hint: 'avvia la connessione dalla PWA, Impostazioni > Nodi' };
 }

package/lib/proxy/federation.js

@@ -13,6 +13,7 @@ const {
 
 const MAX_HOPS = 4;
 const ROUTE_DELIMITER = '_';
+const TOPOLOGY_PEER_TIMEOUT_MS = 1500;
 
 function peerFromToken(nodesPath, token) {
   const st = store.loadStore(nodesPath);
@@ -158,10 +159,16 @@ async function probeHealth({ port, token, expectedInstanceId = null, fetchImpl =
   let timer;
   try {
     const ctrl = new AbortController();
-    timer = setTimeout(() => ctrl.abort(), timeoutMs);
-    r = await fetchImpl(`http://127.0.0.1:${port}/federation/health`, {
+    const request = fetchImpl(`http://127.0.0.1:${port}/federation/health`, {
       headers: { authorization: `Bearer ${token}` }, signal: ctrl.signal,
     });
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        ctrl.abort();
+        const e = new Error(`health timeout (${timeoutMs}ms)`); e.name = 'AbortError'; reject(e);
+      }, timeoutMs);
+    });
+    r = await Promise.race([request, timeout]);
   } catch (e) {
     out.transport = 'down';
     out.status = 'down';
@@ -228,6 +235,71 @@ async function waitForHealthyPeer(opts = {}) {
   return last || { status: 'down', detail: 'peer non raggiungibile' };
 }
 
+// Aggiorna lo stato Share sul hub attraverso il canale -L autenticato. Non
+// legge mai il body remoto (potrebbe contenere diagnostica non sicura) e non
+// include credenziali negli errori. Usato sia dal toggle interattivo sia dalla
+// riconciliazione al boot.
+async function notifyHubShare({ node, shared, fetchImpl = fetch, timeoutMs = 5000 }) {
+  if (!node || !store.isPort(node.localPort) || !store.validToken(node.token)
+    || typeof shared !== 'boolean') throw new Error('parametri riconciliazione Share non validi');
+  const ctrl = new AbortController();
+  const budget = Number.isInteger(timeoutMs) ? Math.max(100, Math.min(timeoutMs, 30000)) : 5000;
+  let timer;
+  try {
+    const request = fetchImpl(`http://127.0.0.1:${node.localPort}/federation/share`, {
+      method: 'POST', signal: ctrl.signal,
+      headers: { authorization: `Bearer ${node.token}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ shared }),
+    });
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        ctrl.abort();
+        const e = new Error(`hub Share timeout (${budget}ms)`); e.code = 'ETIMEDOUT'; reject(e);
+      }, budget);
+    });
+    const response = await Promise.race([request, timeout]);
+    if (!response || !response.ok) throw new Error(`hub Share HTTP ${response && response.status || 'unknown'}`);
+    return { shared };
+  } finally { clearTimeout(timer); }
+}
+
+// Il file locale contiene lo stato desiderato. Dopo un crash in qualunque
+// punto del toggle, il boot ristabilisce il tunnel coerente e ripete l'update
+// del hub: ON torna pubblicato, OFF revoca record stale. Tutto e' bounded.
+async function reconcilePeerShare(opts = {}) {
+  const node = opts.node;
+  const shared = opts.shared === true;
+  if (!node || !store.validToken(node.token) || !store.NODE_ID_RE.test(String(node.nodeId || ''))) {
+    throw new Error('peer non associato: riconciliazione Share impossibile');
+  }
+  const fetchImpl = opts.fetchImpl || fetch;
+  const delay = typeof opts.delay === 'function'
+    ? opts.delay : (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  const health = await waitForHealthyPeer({
+    port: node.localPort, token: node.token, expectedInstanceId: node.nodeId,
+    fetchImpl,
+    attempts: Number.isInteger(opts.healthAttempts) ? opts.healthAttempts : 6,
+    delayMs: Number.isInteger(opts.delayMs) ? opts.delayMs : 200,
+    delay,
+  });
+  if (!health || health.status !== 'healthy') {
+    throw new Error((health && health.detail) || 'hub non raggiungibile per riconciliare Share');
+  }
+  const attempts = Number.isInteger(opts.notifyAttempts)
+    ? Math.max(1, Math.min(opts.notifyAttempts, 6)) : (shared ? 3 : 1);
+  let lastError = null;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      await notifyHubShare({ node, shared, fetchImpl, timeoutMs: opts.timeoutMs });
+      return { shared, health };
+    } catch (e) {
+      lastError = e;
+      if (attempt + 1 < attempts) await delay(Number.isInteger(opts.delayMs) ? opts.delayMs : 200);
+    }
+  }
+  throw lastError || new Error('riconciliazione Share fallita');
+}
+
 function controlledVisited(req, ingress, instanceId) {
   const raw = ingress ? String(req.headers['x-nexuscrew-visited'] || '') : '';
   const seen = raw ? raw.split(',').filter(Boolean) : [];
@@ -241,13 +313,41 @@ function controlledVisited(req, ingress, instanceId) {
   return [...seen, instanceId];
 }
 
-async function collectTopologyDetailed({ nodesPath, ingress = null, ttl = MAX_HOPS, visited = [], fetchImpl = fetch }) {
+async function fetchPeerTopology({ node, ttl, seen, fetchImpl, timeoutMs }) {
+  const ctrl = new AbortController();
+  const budget = Number.isFinite(timeoutMs)
+    ? Math.max(1, Math.min(30000, Math.floor(timeoutMs))) : TOPOLOGY_PEER_TIMEOUT_MS;
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      ctrl.abort();
+      const error = new Error(`topology peer timeout (${budget}ms)`);
+      error.code = 'ETIMEDOUT';
+      reject(error);
+    }, budget);
+  });
+  const request = (async () => {
+    const u = `http://127.0.0.1:${node.localPort}/federation/topology?ttl=${ttl - 1}&visited=${encodeURIComponent([...seen].join(','))}`;
+    const response = await fetchImpl(u, {
+      headers: { authorization: `Bearer ${node.token}` }, signal: ctrl.signal,
+    });
+    return { response, body: await response.json() };
+  })();
+  try { return await Promise.race([request, timeout]); }
+  finally { clearTimeout(timer); }
+}
+
+async function collectTopologyDetailed({
+  nodesPath, ingress = null, ttl = MAX_HOPS, visited = [], fetchImpl = fetch,
+  timeoutMs = TOPOLOGY_PEER_TIMEOUT_MS,
+}) {
   const st = store.loadStore(nodesPath);
   if (!st) return { instanceId: null, nodes: [], authoritative: [] };
   const seen = new Set(visited.filter((x) => store.NODE_ID_RE.test(x)));
   seen.add(st.nodeId);
   const out = [];
   const authoritative = [];
+  const probes = [];
   for (const n of st.nodes) {
     // The local installation always keeps its outbound hub visible. Inbound
     // clients become part of Hydra only after their explicit Share toggle.
@@ -256,13 +356,15 @@ async function collectTopologyDetailed({ nodesPath, ingress = null, ttl = MAX_HO
       || (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;
-      authoritative.push(n.name);
-      for (const child of j.nodes) {
+    probes.push({ n, pending: fetchPeerTopology({ node: n, ttl, seen, fetchImpl, timeoutMs }) });
+  }
+  const results = await Promise.all(probes.map(async ({ n, pending }) => {
+    try { return { n, ...(await pending) }; } catch (_) { return { n, response: null, body: null }; }
+  }));
+  for (const { n, response, body } of results) {
+    if (!response || !response.ok || body.instanceId !== n.nodeId || !Array.isArray(body.nodes)) continue;
+    authoritative.push(n.name);
+    for (const child of body.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
@@ -271,8 +373,7 @@ async function collectTopologyDetailed({ nodesPath, ingress = null, ttl = MAX_HO
           || 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)) {
@@ -290,8 +391,11 @@ async function collectTopology(opts) {
 
 // Local roster: live topology plus a credential-free cache of previously seen
 // transitive nodes. Stale entries are never returned by the peer endpoint.
-async function collectLocalTopology({ nodesPath, cachePath, fetchImpl = fetch, now = Math.floor(Date.now() / 1000) }) {
-  const live = await collectTopologyDetailed({ nodesPath, fetchImpl });
+async function collectLocalTopology({
+  nodesPath, cachePath, fetchImpl = fetch, now = Math.floor(Date.now() / 1000),
+  timeoutMs = TOPOLOGY_PEER_TIMEOUT_MS,
+}) {
+  const live = await collectTopologyDetailed({ nodesPath, fetchImpl, timeoutMs });
   const st = store.loadStore(nodesPath);
   const directNames = new Set(((st && st.nodes) || [])
     .filter((n) => n.direction !== 'inbound' || n.shared === true)
@@ -373,7 +477,7 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
           });
         }
       }
-      let st = store.loadOrInitStore(nodesPath);
+      let st = store.loadStoreStrict(nodesPath);
       const current = store.getNode(st, req.peer.name);
       if (!current) return res.status(404).json({ error: 'peer non trovato' });
       st = store.updateNode(st, current.name, {
@@ -384,7 +488,7 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
       store.atomicWriteStore(nodesPath, st);
       return res.json({ shared: body.shared });
     } catch (e) {
-      return res.status(500).json({ error: String(e && e.message || e) });
+      return res.status(e.status || 500).json({ error: String(e && e.message || e), ...(e.code ? { code: e.code } : {}) });
     }
   });
   r.use('/route', (req, res) => routeHandler({ nodesPath, localPort, localCredential, ingress: req.peer, readonly })(req, res));
@@ -434,7 +538,8 @@ function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredenti
 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,
+  MAX_HOPS, ROUTE_DELIMITER, TOPOLOGY_PEER_TIMEOUT_MS,
+  peerFromToken, peerAllows, canTransit, parseRoute, knownResource, allowedResource,
   collectTopology, collectTopologyDetailed, collectLocalTopology, peerRouter, localRouter, forwardUpgrade,
-  probeHealth, waitForHealthyPeer,
+  probeHealth, waitForHealthyPeer, notifyHubShare, reconcilePeerShare,
 };

package/lib/server.js

@@ -156,6 +156,17 @@ function createServer(opts = {}) {
         });
         if (!tr.started && tr.reason !== 'already running') {
           process.stderr.write(`[nexuscrew] peer ${node.name} autostart failed: ${tr.reason || 'unknown'}\n`);
+        } else if (node.token && node.acceptToken && node.nodeId) {
+          // `shared` in nodes.json e' lo stato desiderato. Una riconciliazione
+          // asincrona chiude la finestra di crash tra write locale e ACK hub
+          // senza ritardare il listen del server.
+          const reconcileShare = cfg.reconcilePeerShareImpl || federation.reconcilePeerShare;
+          Promise.resolve(reconcileShare({
+            node, shared: node.shared === true, fetchImpl: healthFetch,
+            healthAttempts: 3, notifyAttempts: node.shared === true ? 3 : 1, delayMs: 200,
+          })).catch((e) => {
+            process.stderr.write(`[nexuscrew] peer ${node.name} Share reconcile pending: ${String(e && e.message || e).replace(/Bearer\s+\S+/gi, 'Bearer ***')}\n`);
+          });
         }
       }
     }

package/lib/settings/pairing-coordinator.js

@@ -117,7 +117,7 @@ function createPairHandler(deps) {
 
     try {
       // --- conflict: il nome non deve gia' esistere --------------------------
-      let st = nodesStore.loadOrInitStore(nodesPath);
+      let st = nodesStore.loadStoreStrict(nodesPath);
       if (st.nodes.some((n) => n.name === b.name)) {
         return fail(409, 'conflict', 'name-exists', `nodo "${b.name}" gia' presente`, {
           retryable: true, hint: 'scegli un altro nome nelle opzioni avanzate e riprova',
@@ -253,7 +253,7 @@ function createPairHandler(deps) {
       // --- tunnel-final: connessione privata, solo -L -------------------------
       // reversePort resta negoziata per un futuro Share opt-in, ma il builder
       // non emette -R finche' shared non diventa true.
-      st = nodesStore.loadOrInitStore(nodesPath);
+      st = nodesStore.loadStoreStrict(nodesPath);
       st = nodesStore.updateNode(st, b.name, {
         token: joined.credential, nodeId: joined.instanceId, reversePort: joined.reversePort,
         shared: false,
@@ -317,7 +317,7 @@ function createPairHandler(deps) {
       send(res, 200, { paired: true, name: b.name, instanceId: joined.instanceId, transport: 'auto', health: { status: health.status } });
     } catch (e) {
       await rollback();
-      fail(502, 'internal', 'unexpected', String((e && e.message) || e), {});
+      fail(e.status || 502, 'internal', e.code || 'unexpected', String((e && e.message) || e), {});
     }
   };
 }

package/lib/settings/public-peering-routes.js

@@ -46,7 +46,7 @@ function publicPeeringRoutes(deps = {}) {
     if (!st || !nodesStore.NODE_ID_RE.test(st.nodeId)) return res.status(503).json({ error: 'identita nodo non disponibile' });
     return res.json({ ok: true, instanceId: st.nodeId, proof });
   });
-  r.post('/join', (req, res) => {
+  r.post('/join', async (req, res) => {
     const key = `join:${String(req.socket && req.socket.remoteAddress || 'local')}`;
     const now = Date.now();
     const recent = (attempts.get(key) || []).filter((x) => now - x < 60_000);
@@ -65,21 +65,42 @@ function publicPeeringRoutes(deps = {}) {
     if (b.label !== undefined && !nodesStore.validLabel(b.label)) {
       return res.status(400).json({ error: 'label non valida' });
     }
-    if (!peering.consumeInvite({ invitesPath, invite: b.invite })) return res.status(410).json({ error: 'invito scaduto o gia usato' });
+    // Validate the one-time capability before conflict checks without burning
+    // it: a duplicate/stale peer must not destroy an otherwise reusable invite.
+    if (!peering.hasInvite({ invitesPath, invite: b.invite, now })) return res.status(410).json({ error: 'invito scaduto o gia usato' });
+    let credential = null;
     try {
-      const st = nodesStore.loadOrInitStore(nodesPath);
-      if (st.nodeId === b.instanceId || st.nodes.some((n) => n.nodeId === b.instanceId)) return res.status(409).json({ error: 'peer duplicato' });
-      let name = b.name;
-      for (let i = 2; nodesStore.getNode(st, name); i += 1) name = `${b.name.slice(0, 28)}-${i}`;
-      const reversePort = peering.allocateReversePort(st.nodes);
-      const credential = peering.createPending({ pendingPath, data: {
+      const st = nodesStore.loadStoreStrict(nodesPath);
+      const pending = peering.readInvites(pendingPath, now);
+      if (st.nodeId === b.instanceId || st.nodes.some((n) => n.nodeId === b.instanceId)
+        || pending.some((row) => row.instanceId === b.instanceId)) return res.status(409).json({ error: 'peer duplicato' });
+      const reservedNames = new Set(pending.map((row) => row.name).filter(validPeerName));
+      if (nodesStore.getNode(st, b.name) || reservedNames.has(b.name)) {
+        return res.status(409).json({
+          error: `nome peer gia' in uso: ${b.name}`,
+          code: 'peer-name-conflict',
+          hint: 'rimuovi il record stale oppure scegli un nome univoco e riprova con lo stesso invito',
+        });
+      }
+      const name = b.name;
+      const reversePort = await peering.allocateAvailableReversePort(st.nodes, pending, {
+        ...(deps.createServerImpl ? { createServerImpl: deps.createServerImpl } : {}),
+      });
+      credential = peering.createPending({ pendingPath, data: {
         name, remotePort: b.port, reversePort, instanceId: b.instanceId, acceptToken: b.acceptToken,
         shared: false,
         label: nodesStore.sanitizeLabel(b.label, name),
         ...(peerRoles ? { roles: { ...peerRoles, node: false }, rolesKnown: true } : { rolesKnown: false }),
       } });
+      if (!peering.consumeInvite({ invitesPath, invite: b.invite, now })) {
+        peering.consumePending({ pendingPath, credential, now });
+        return res.status(410).json({ error: 'invito scaduto o gia usato' });
+      }
       res.json({ paired: true, instanceId: st.nodeId, reversePort, credential, roles: readRoles(configPath) });
-    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+    } catch (e) {
+      if (credential) try { peering.consumePending({ pendingPath, credential, now }); } catch (_) {}
+      res.status(e.status || 500).json({ error: String(e.message || e), ...(e.code ? { code: e.code } : {}) });
+    }
   });
   r.post('/confirm', (req, res) => {
     const b = req.body || {};
@@ -91,8 +112,15 @@ function publicPeeringRoutes(deps = {}) {
       return res.status(410).json({ error: 'pairing pending scaduto o gia usato' });
     }
     try {
-      let st = nodesStore.loadOrInitStore(nodesPath);
+      let st = nodesStore.loadStoreStrict(nodesPath);
       if (st.nodeId === pending.instanceId || st.nodes.some((n) => n.nodeId === pending.instanceId)) return res.status(409).json({ error: 'peer duplicato' });
+      if (st.nodes.some((n) => n.name === pending.name || n.localPort === pending.reversePort)) {
+        return res.status(409).json({
+          error: 'allocazione pairing non piu disponibile',
+          code: 'pairing-allocation-conflict',
+          hint: 'ripeti il pairing: verra negoziata una nuova porta reverse',
+        });
+      }
       st = nodesStore.addNode(st, {
         name: pending.name, remotePort: pending.remotePort, localPort: pending.reversePort,
         direction: 'inbound', transport: 'inbound', autostart: true,
@@ -104,7 +132,7 @@ function publicPeeringRoutes(deps = {}) {
       });
       nodesStore.atomicWriteStore(nodesPath, st);
       res.json({ confirmed: true });
-    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+    } catch (e) { res.status(e.status || 500).json({ error: String(e.message || e), ...(e.code ? { code: e.code } : {}) }); }
   });
   r.post('/cancel', (req, res) => {
     const b = req.body || {};