@mmmbuto/nexuscrew 0.8.19 → 0.8.20

package/lib/nodes/peering.js

@@ -2,6 +2,7 @@
 
 const crypto = require('node:crypto');
 const fs = require('node:fs');
+const net = require('node:net');
 const path = require('node:path');
 const store = require('./store.js');
 
@@ -132,9 +133,14 @@ function consumeInvite({ invitesPath, invite, now = Date.now() }) {
   return true;
 }
 
-function allocateReversePort(nodes) {
+function hasInvite({ invitesPath, invite, now = Date.now() }) {
+  const hash = crypto.createHash('sha256').update(String(invite || '')).digest('hex');
+  return readInvites(invitesPath, now).some((row) => safeEqual(row.hash, hash));
+}
+
+function allocateReversePort(nodes, reservations = []) {
   const used = new Set();
-  for (const n of nodes || []) {
+  for (const n of [...(nodes || []), ...(reservations || [])]) {
     if (store.isPort(n.localPort)) used.add(n.localPort);
     if (store.isPort(n.reversePort)) used.add(n.reversePort);
   }
@@ -144,6 +150,41 @@ function allocateReversePort(nodes) {
   return p;
 }
 
+function canBindReversePort(port, createServerImpl = net.createServer) {
+  return new Promise((resolve, reject) => {
+    const server = createServerImpl();
+    let settled = false;
+    const finish = (value, error = null) => {
+      if (settled) return;
+      settled = true;
+      server.removeAllListeners?.();
+      if (error) reject(error); else resolve(value);
+    };
+    server.once('error', (error) => {
+      if (error && (error.code === 'EADDRINUSE' || error.code === 'EACCES')) finish(false);
+      else finish(false, error);
+    });
+    server.once('listening', () => {
+      if (typeof server.unref === 'function') server.unref();
+      try { server.close(() => finish(true)); } catch (error) { finish(false, error); }
+    });
+    server.listen({ host: '127.0.0.1', port, exclusive: true });
+  });
+}
+
+// The reverse listener will be owned by sshd, but allocation happens on the
+// hub. Probe the real loopback bind before issuing a candidate so a stale or
+// unrelated listener absent from nodes.json cannot be reallocated blindly.
+async function allocateAvailableReversePort(nodes, reservations = [], opts = {}) {
+  const rejected = [];
+  while (rejected.length < (65535 - REVERSE_PORT_BASE)) {
+    const candidate = allocateReversePort(nodes, [...reservations, ...rejected]);
+    if (await canBindReversePort(candidate, opts.createServerImpl || net.createServer)) return candidate;
+    rejected.push({ localPort: candidate });
+  }
+  throw new Error('no reverse port available');
+}
+
 function createPending({ pendingPath, data, now = Date.now() }) {
   const rows = readInvites(pendingPath, now);
   const credential = crypto.randomBytes(32).toString('base64url');
@@ -269,6 +310,7 @@ async function probeTransportReady({
 module.exports = {
   INVITE_TTL_MS, REVERSE_PORT_BASE, defaultInvitesPath, defaultPendingPath, safeEqual,
   readInvites, writeInvites, encodePairing, decodePairing, parsePairingUrl,
-  createInvite, consumeInvite, allocateReversePort, createPending, consumePending,
+  createInvite, consumeInvite, hasInvite, allocateReversePort, canBindReversePort,
+  allocateAvailableReversePort, createPending, consumePending,
   capabilityIdentity, capabilityProbeMaterial, probeTransportReady,
 };

package/lib/nodes/store.js

@@ -9,7 +9,8 @@
 //   - nessun token in output redatto (redactStore/redactNode)
 //
 // Modulo PURO al parse: parseStore/parseNode non toccano il filesystem.
-// Tutto l'I/O vive in loadStore/atomicWriteStore/loadOrInitStore/migrateLegacyNodes.
+// Tutto l'I/O vive in loadStore/loadStoreStrict/initStore/atomicWriteStore/
+// migrateLegacyNodes.
 // Principio fail-closed: qualunque dato malformato -> null (parse) o throw
 // esplicito (mutazioni/write), mai un default silenzioso.
 const fs = require('node:fs');
@@ -227,12 +228,15 @@ function parseStore(raw) {
 
     const names = new Set();
     const ids = new Set();
+    const localPorts = new Set();
     const nodes = [];
     for (const raw2 of d.nodes) {
       const node = parseNode(raw2, d.schemaVersion);
       if (!node) return null;
       if (names.has(node.name)) return null;             // name univoco
       names.add(node.name);
+      if (localPorts.has(node.localPort)) return null;   // ogni listener locale ha un solo owner
+      localPorts.add(node.localPort);
       if (node.nodeId) {
         if (node.nodeId === d.nodeId) return null;        // self-reference nei dati salvati
         if (ids.has(node.nodeId)) return null;            // nodeId remoto univoco
@@ -306,22 +310,56 @@ function emptyStore(nodeId) {
   return { schemaVersion: SCHEMA_VERSION, nodeId: nodeId || newNodeId(), nodes: [] };
 }
 
-// loadOrInitStore(p): store esistente, oppure ne crea uno vuoto (nodeId fresco,
-// STABILE una volta scritto). Se il file esiste ma e' invalido -> throw esplicito
-// (mai sovrascrivere/mascherare corruzione o un file altrui).
-function loadOrInitStore(p) {
+function storeUnavailable(code, message) {
+  const e = new Error(message);
+  e.status = 503;
+  e.code = code;
+  return e;
+}
+
+// Runtime strict: nodes.json e' identita' + credential store. Se sparisce non
+// deve MAI essere rigenerato implicitamente da una route/command: un nuovo
+// nodeId farebbe apparire l'installazione come un altro dispositivo e
+// maschererebbe una perdita di stato. Solo `nexuscrew init` usa initStore().
+function loadStoreStrict(p) {
   let st;
   try { st = fs.lstatSync(p); }
   catch (e) {
-    if (e.code === 'ENOENT') return atomicWriteStore(p, emptyStore());
+    if (e.code === 'ENOENT') {
+      throw storeUnavailable('NODES_STORE_MISSING',
+        `nodes.json assente (${p}): esegui \`nexuscrew init\` per inizializzare esplicitamente lo store`);
+    }
     throw e;
   }
-  if (st.isSymbolicLink()) throw new Error('nodes.json e\' un symlink (rifiutato)');
+  if (st.isSymbolicLink()) {
+    throw storeUnavailable('NODES_STORE_INVALID', 'nodes.json e\' un symlink (rifiutato)');
+  }
+  if (!st.isFile()) {
+    throw storeUnavailable('NODES_STORE_INVALID', 'nodes.json non e\' un file regolare');
+  }
   const parsed = loadStore(p);
-  if (!parsed) throw new Error('nodes.json presente ma invalido (schema strict): correggi o rimuovi il file');
+  if (!parsed) {
+    throw storeUnavailable('NODES_STORE_INVALID',
+      'nodes.json presente ma invalido (schema strict): ripristina un backup valido; non viene sovrascritto');
+  }
   return parsed;
 }
 
+// Init esplicito e idempotente. E' l'unico percorso autorizzato a creare uno
+// store mancante; un file presente ma invalido resta fail-closed.
+function initStore(p) {
+  try { fs.lstatSync(p); }
+  catch (e) {
+    if (e.code === 'ENOENT') return atomicWriteStore(p, emptyStore());
+    throw e;
+  }
+  return loadStoreStrict(p);
+}
+
+// Compatibilita' API interna: il vecchio nome non inizializza piu' a runtime.
+// Tenerlo strict impedisce che un call-site dimenticato reintroduca F1.
+function loadOrInitStore(p) { return loadStoreStrict(p); }
+
 // --- Mutazioni pure (ritornano un nuovo store; il caller lo scrive) ---------
 
 function getNode(store, name) {
@@ -334,6 +372,9 @@ function addNode(store, entry) {
   if (store.nodes.some((n) => n.name === node.name)) {
     throw new Error(`nodo duplicato: name "${node.name}" gia' presente`);
   }
+  if (store.nodes.some((n) => n.localPort === node.localPort)) {
+    throw new Error(`nodo duplicato: localPort ${node.localPort} gia' assegnata`);
+  }
   if (node.nodeId) {
     if (node.nodeId === store.nodeId) throw new Error('self-reference: il nodeId coincide con questa installazione');
     if (store.nodes.some((n) => n.nodeId === node.nodeId)) {
@@ -425,7 +466,7 @@ function migrateLegacyNodes(configPath, nodesPath) {
   if (!cfg || typeof cfg !== 'object' || !Array.isArray(cfg.nodes) || cfg.nodes.length === 0) {
     return { migrated: false, count: 0, reason: 'nessun campo nodes legacy in config.json' };
   }
-  const store = loadOrInitStore(nodesPath);
+  const store = initStore(nodesPath);
   if (store.nodes.length > 0) {
     return { migrated: false, count: 0, reason: 'nodes.json gia\' popolato (no overwrite)' };
   }
@@ -498,7 +539,7 @@ module.exports = {
   // parse/validate
   parseStore, parseNode, parseRendezvous, parseRoles, parseSsh, parseSshTarget, isPort, isAbsPath, validToken,
   // I/O
-  defaultNodesPath, loadStore, atomicWriteStore, loadOrInitStore, emptyStore, newNodeId,
+  defaultNodesPath, loadStore, loadStoreStrict, initStore, atomicWriteStore, loadOrInitStore, emptyStore, newNodeId,
   // mutazioni
   getNode, addNode, removeNode, setNodeToken, updateNode,
   // redazione

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

@@ -209,7 +209,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: 'la porta può essere già occupata oppure il server può vietare il forwarding; verifica listener e policy SSH 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 +256,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 +293,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 +317,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), {});
     }
   };
 }