@mmmbuto/nexuscrew 0.9.4 → 0.9.5

package/lib/nodes/tunnel-supervisor.js

@@ -21,6 +21,24 @@ const ownershipGraceMs = Number.isFinite(ownershipGraceRaw) && ownershipGraceRaw
 const reverseFailureMaxRaw = Number(process.env.NEXUSCREW_TUNNEL_REVERSE_FAILURE_MAX || 8);
 const reverseFailureMax = Number.isInteger(reverseFailureMaxRaw) && reverseFailureMaxRaw >= 1
   ? Math.min(reverseFailureMaxRaw, 32) : 8;
+// R19 seguito — contratto per la sonda del canale -L quando non conclude MAI:
+// continuare a sondare ogni 250ms e' giusto per la finestra transitoria (il
+// servizio remoto non e' ancora su dopo un restart/aggiornamento: la prossima
+// sonda e' una connessione FRESCA, si qualifica da sola appena il servizio
+// risponde) ma sbagliato oltre — un vero permitopen mancante o un servizio
+// remoto permanentemente giu' non si risolvono mai da soli, e la sonda gira
+// per sempre senza mai diventare osservabile ne' degradare, la stessa cosa
+// che l'assenza di storia delle transizioni peer faceva prima di questo
+// registro. 60 tentativi * 250ms = 15s, lo stesso budget di attesa gia' in
+// uso altrove in questo prodotto per "il runtime e' tornato sano dopo un
+// riavvio" (vedi healthAttempts/healthDelayMs in lib/update/runner.js): oltre
+// quella soglia il canale entra in degraded, ESATTAMENTE come il fallimento
+// del forward inverso — stesso stato, stessa auto-guarigione a cadenza fissa,
+// mai un "pronto" dichiarato senza averlo verificato (sarebbe la stessa bugia
+// che R19 ha tolto, solo con una bandiera "non verificato" appesa sopra).
+const channelProbeMaxRaw = Number(process.env.NEXUSCREW_TUNNEL_CHANNEL_PROBE_MAX || 60);
+const channelProbeMax = Number.isInteger(channelProbeMaxRaw) && channelProbeMaxRaw >= 1
+  ? Math.min(channelProbeMaxRaw, 240) : 60;
 // Once the initial reverse-forward budget is exhausted the supervisor does NOT
 // die: it stays "degraded" and retries at the fixed production cadence of 60s,
 // so a transient reverse listener on the hub (e.g. a mobile reconnect) heals on
@@ -32,7 +50,7 @@ const steadyRetryMsRaw = Number(steadyRetryTestMode ? (process.env.NEXUSCREW_TUN
 const steadyRetryMinMs = steadyRetryTestMode ? 1 : 60000;
 const steadyRetryMs = Number.isFinite(steadyRetryMsRaw) && steadyRetryMsRaw >= steadyRetryMinMs
   ? Math.min(steadyRetryMsRaw, 120000) : 60000;
-if (!sshBin || !statePath || !pidPath || !runId) process.exit(2);
+if (require.main === module && (!sshBin || !statePath || !pidPath || !runId)) process.exit(2);
 
 let child = null;
 let stopping = false;
@@ -44,18 +62,25 @@ let forwardSocket = null;
 let ownershipWaitTimer = null;
 let ownershipTimer = null;
 let reverseFailures = 0;
+let channelRefusedLogged = false;
+let channelProbeFailures = 0;
 
 function localForwardPort(args) {
+  return localForwardPorts(args)[0] || null;
+}
+function localForwardPorts(args) {
+  const ports = [];
   for (let i = 0; i < args.length - 1; i += 1) {
     if (args[i] !== '-L') continue;
-    const match = String(args[i + 1] || '').match(/^127\.0\.0\.1:(\d+):127\.0\.0\.1:\d+$/);
+    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;
+    if (Number.isInteger(port) && port >= 1 && port <= 65535 && !ports.includes(port)) ports.push(port);
   }
-  return null;
+  return ports;
 }
 
 const forwardPort = localForwardPort(sshArgs);
+const forwardPorts = localForwardPorts(sshArgs);
 
 function reverseForwardPort(args) {
   for (let i = 0; i < args.length - 1; i += 1) {
@@ -86,6 +111,109 @@ function clearForwardProbe() {
 // blocked connecting to an unreachable endpoint. Opening the local -L socket
 // forces OpenSSH to establish the real forward channel. Only that event may
 // advertise transport-ready or reset retry backoff.
+//
+// R19: connect NON è prova di canale. OpenSSH accetta la TCP sul listener
+// locale SUBITO e chiede il canale al server DOPO: se il server lo nega
+// (permitopen senza quella destinazione) il socket viene CHIUSO nel giro di
+// millisecondi — bind locale riuscito, canale morto. Una finestra di grazia
+// dopo connect distingue le due metà: «il canale è aperto» da «il server ha
+// rifiutato». Ready senza questa prova misura la metà comoda.
+const CHANNEL_GRACE_MS = 350;
+
+// Pura (con net iniettabile): per ogni porta locale -L riporta
+// 'channel-ok' | 'channel-refused' | 'bind-failed'.
+function probeForwardChannels({ ports, graceMs = CHANNEL_GRACE_MS, connect = net.connect } = {}) {
+  return new Promise((resolveOuter) => {
+    const esiti = new Map();
+    const sockets = [];
+    let pending = ports.length;
+    if (!pending) return resolveOuter(esiti);
+    const settle = (port, esito, sock) => {
+      if (!esiti.has(port)) {
+        esiti.set(port, esito);
+        if (sock) { try { sock.destroy(); } catch (_) {} }
+        pending -= 1;
+        if (pending <= 0) resolveOuter(esiti);
+      }
+    };
+    for (const port of ports) {
+      const sock = connect({ host: '127.0.0.1', port });
+      sockets.push(sock);
+      let connected = false;
+      let graceTimer = null;
+      sock.setTimeout(1000);
+      sock.once('connect', () => {
+        connected = true;
+        // La finestra che decide: se entro graceMs il socket muore, il canale
+        // è stato negato dall'altro capo (o chiuso da lui): non è nostro.
+        graceTimer = setTimeout(() => settle(port, 'channel-ok', sock), graceMs);
+      });
+      const morte = () => {
+        if (graceTimer) clearTimeout(graceTimer);
+        settle(port, connected ? 'channel-refused' : 'bind-failed', sock);
+      };
+      sock.once('close', morte);
+      sock.once('error', morte);
+      sock.once('timeout', morte);
+    }
+  });
+}
+
+// R19 punto 3: chi ha installato la chiave quando il pannello non esisteva è
+// rotto e NON lo sapeva. Il prodotto lo DICE, con la riga da sostituire: le
+// destinazioni arrivano dagli `-L`, la pubblica si DERIVA dalla privata
+// indicata da `-i`. Quando non si riesce a derivarla, dice comunque COSA
+// aggiungere — mai una riga a metà.
+// La riga e' un DATO, non una frase: chi la deve mostrare non deve ritagliarla
+// da un testo costruito qui. `hint` resta per chi legge un log;
+// `authorizedKeys` e' il campo che la UI consuma, e resta vuoto quando la riga
+// completa non si puo' comporre.
+// I DUE RAMI NON DICONO LA STESSA COSA, e prima la dicevano: senza la chiave
+// pubblica si costruiva un FRAMMENTO ("aggiungi a permitopen: ...") e lo si
+// infilava nella frase "Riga da usare (SOSTITUISCI quella esistente)". Chi
+// avesse obbedito avrebbe sostituito una riga valida con mezza riga, rompendo
+// l'accesso invece di ripararlo: una promessa falsa che peggiora il guasto.
+// Con la chiave: riga completa, sostituzione, ed e' anche il campo copiabile.
+// Senza: si dice che la chiave non e' identificabile e si chiede una modifica
+// A MANO della riga esistente, mostrando solo le destinazioni da aggiungere.
+function refusalDetails({ remoteDestinations, identityFile } = {}) {
+  const dests = (remoteDestinations || []).join('",permitopen="');
+  const pub = require('./tunnel.js').readPublicKey(identityFile);
+  const premessa = 'canale rifiutato dal NODO remoto: la chiave in ~/.ssh/authorized_keys non autorizza queste destinazioni.';
+  if (!pub) {
+    // Due situazioni diverse, e il messaggio non deve confonderle — ne'
+    // inventare una causa che non conosce. Senza `-i` la chiave non e'
+    // dichiarata affatto. Con `-i`, la derivazione dalla privata puo' fallire
+    // per piu' motivi (privata assente o illeggibile, protetta da passphrase,
+    // `ssh-keygen` non disponibile) e da qui non si distinguono: si elencano,
+    // invece di sceglierne uno a caso. Dire «la parte pubblica non e'
+    // leggibile» a chi ha una chiave cifrata col suo `.pub` accanto e' falso,
+    // e manda a cercare il problema dove non e'.
+    const causa = identityFile
+      ? `non riesco a derivare la chiave pubblica da ${path.basename(identityFile)}`
+        + ' (privata assente o illeggibile, protetta da passphrase, oppure ssh-keygen non disponibile)'
+      : 'nessun -i: ssh usa le chiavi di default, un agent o la config, e da qui non si sa quale';
+    return {
+      hint: `${premessa} NON posso identificare la chiave da correggere — ${causa}`
+        + `. Modifica A MANO la riga di quella chiave aggiungendo queste destinazioni: permitopen="${dests}"`,
+      authorizedKeys: '',
+    };
+  }
+  const riga = `restrict,port-forwarding,permitopen="${dests}",command="/bin/false" ${pub}`;
+  // NON diciamo «quella con cui il supervisor si autentica»: `-i` DICHIARA
+  // un'identita', non la impone — senza `IdentitiesOnly=yes` OpenSSH puo'
+  // comunque usare l'agent o la config, e il canale essere autenticato da
+  // un'altra chiave. Affermarlo sarebbe una promessa che il comando non
+  // mantiene, e manderebbe a sostituire la riga sbagliata.
+  const quale = identityFile ? ` (chiave DICHIARATA per questo nodo: ${path.basename(identityFile)}, non un'eventuale chiave "jump" dello stesso nodo; se ssh ne sceglie un'altra via agent o config, la riga da correggere e' quella)` : '';
+  return {
+    hint: `${premessa} Riga da usare (SOSTITUISCI quella esistente, non aggiungerne una seconda)${quale}: ${riga}`,
+    authorizedKeys: riga,
+  };
+}
+
+function refusalHint(opts) { return refusalDetails(opts).hint; }
+
 function probeForward(expectedChild) {
   if (stopping || child !== expectedChild || !child || child.exitCode != null) return;
   if (!forwardPort) {
@@ -99,29 +227,72 @@ function probeForward(expectedChild) {
     if (!writeState('transport-ready', { sshPid: child.pid, stableMs, probe: 'reverse-forward' })) stop();
     return;
   }
-  let settled = false;
-  const socket = net.connect({ host: '127.0.0.1', port: forwardPort });
-  forwardSocket = socket;
-  const done = (ready) => {
-    if (settled) return;
-    settled = true;
-    try { socket.destroy(); } catch (_) {}
-    if (forwardSocket === socket) forwardSocket = null;
+  const ports = forwardPorts.length ? forwardPorts : [forwardPort];
+  probeForwardChannels({ ports, graceMs: CHANNEL_GRACE_MS }).then((esiti) => {
     if (stopping || child !== expectedChild || !child || child.exitCode != null) return;
-    if (ready) {
+    const rifiutate = ports.filter((p) => esiti.get(p) === 'channel-refused');
+    const mancanti = ports.filter((p) => esiti.get(p) === 'bind-failed');
+    if (!rifiutate.length && !mancanti.length) {
       attempt = 0;
       reverseFailures = 0;
-      logEvent(`forward ready stableMs=${stableMs}`);
-      if (!writeState('transport-ready', { sshPid: child.pid, stableMs, probe: 'tcp-forward' })) stop();
+      channelProbeFailures = 0;
+      logEvent(`forward ready stableMs=${stableMs} channel=verified`);
+      if (!writeState('transport-ready', { sshPid: child.pid, stableMs, probe: 'tcp-forward-verified' })) stop();
       return;
     }
-    if (!writeState('transport-probing', { sshPid: child.pid, stableMs })) return stop();
+    if (rifiutate.length && !channelRefusedLogged) {
+      // Una volta per generazione: il ciclo di probing continua (la
+      // concessione può essere aggiornata), ma chi guarda SA qual è la metà
+      // malata e COSA sostituire.
+      channelRefusedLogged = true;
+      logEvent(refusalHint({ remoteDestinations: remoteDestinationsOf(sshArgs), identityFile: identityFileOf(sshArgs) }));
+    }
+    channelProbeFailures += 1;
+    if (channelProbeFailures > channelProbeMax) {
+      // Budget esaurito: la finestra transitoria (servizio remoto non ancora
+      // su) aveva 15s per qualificarsi da sola con una sonda fresca ogni
+      // volta — non l'ha fatto. Da qui in poi non e' piu' "sta per succedere",
+      // e continuare a sondare ogni 250ms sarebbe la stessa sonda che gira
+      // per sempre senza mai diventare osservabile. Stesso stato del forward
+      // inverso: degraded, vivo, si riprova a cadenza fissa — mai "pronto"
+      // dichiarato senza averlo verificato.
+      return enterDegraded({
+        code: 'forward-channel-blocked',
+        detail: rifiutate.length
+          ? `canale rifiutato dal nodo remoto dopo ${channelProbeFailures} sonde`
+          : `nessun canale locale disponibile dopo ${channelProbeFailures} sonde`,
+        ...(rifiutate.length
+          ? (() => {
+            const d = refusalDetails({ remoteDestinations: remoteDestinationsOf(sshArgs), identityFile: identityFileOf(sshArgs) });
+            return { hint: d.hint, ...(d.authorizedKeys ? { authorizedKeys: d.authorizedKeys } : {}) };
+          })()
+          : {}),
+      });
+    }
+    if (!writeState('transport-probing', {
+      sshPid: child.pid, stableMs,
+      ...(rifiutate.length ? { probeDetail: 'channel-refused', refusedLocalPorts: rifiutate } : {}),
+      ...(mancanti.length ? { probeDetail: 'bind-failed', missingLocalPorts: mancanti } : {}),
+    })) return stop();
     forwardProbeTimer = setTimeout(() => probeForward(expectedChild), 250);
-  };
-  socket.setTimeout(1000);
-  socket.once('connect', () => done(true));
-  socket.once('error', () => done(false));
-  socket.once('timeout', () => done(false));
+  });
+}
+
+// Le destinazioni REMOTE degli -L, nella forma che vive in permitopen.
+function remoteDestinationsOf(args) {
+  const out = [];
+  for (let i = 0; i < args.length - 1; i += 1) {
+    if (args[i] !== '-L') continue;
+    const m = String(args[i + 1] || '').match(/^127\.0\.0\.1:\d+:(127\.0\.0\.1:\d+)$/);
+    if (m && !out.includes(m[1])) out.push(m[1]);
+  }
+  return out;
+}
+function identityFileOf(args) {
+  for (let i = 0; i < args.length - 1; i += 1) {
+    if (args[i] === '-i') return args[i + 1];
+  }
+  return null;
 }
 
 function ownsGeneration() {
@@ -169,10 +340,21 @@ function enterDegraded(diagnosis) {
   // it cannot identify the process holding a listener on the hub.  Never turn
   // local pidfile ownership into a false remote-listener attribution.
   const ownership = 'unknown';
-  logEvent(`ssh degraded code=${safe.code} reversePort=${reversePort || 'none'} ownership=${ownership} failures=${reverseFailures} steadyRetryMs=${steadyRetryMs}`);
+  // Il contatore che si logga dipende da QUALE budget si e' esaurito: il
+  // canale -L (channelProbeFailures) e il forward inverso (reverseFailures)
+  // sono guasti indipendenti sullo stesso processo (vedi CHANNEL_GRACE_MS
+  // sopra) — loggare sempre reverseFailures direbbe "0" su un degraded di
+  // canale, come se non fosse mai stato provato.
+  const failures = safe.code === 'forward-channel-blocked' ? channelProbeFailures : reverseFailures;
+  logEvent(`ssh degraded code=${safe.code} reversePort=${reversePort || 'none'} ownership=${ownership} failures=${failures} steadyRetryMs=${steadyRetryMs}`);
   if (!writeState('degraded', {
     code: safe.code, detail: safe.detail,
     ...(safe.hint ? { hint: safe.hint } : {}),
+    // Il campo viaggia insieme alla frase, non al posto suo: chi legge un log
+    // vuole l'hint, la UI vuole la riga intera. Scriverne solo uno qui e' il
+    // modo in cui il campo si perde a meta' strada e tutto il resto della
+    // catena, gia' cablato, riceve per sempre il fallback testuale.
+    ...(safe.authorizedKeys ? { authorizedKeys: safe.authorizedKeys } : {}),
     reversePort, ownership, steadyRetryMs, terminal: false,
   })) return stop();
   // Keep the backoff counter honest for observers; the degraded retry is fixed.
@@ -180,19 +362,70 @@ function enterDegraded(diagnosis) {
   retryTimer = setTimeout(run, steadyRetryMs);
 }
 
+// R19 seguito, secondo difetto (2026-08-17, audit su develop@437d29f):
+// enterDegraded per il canale -L riusava la macchina del forward inverso
+// senza la sua precondizione implicita. Nel reverse failure `child` e' GIA'
+// null quando enterDegraded gira (handleFailure lo azzera PRIMA, perche' e'
+// il crash del processo l'evento che ci porta li'). Nel canale -L rifiutato
+// il processo NON e' morto — e' il canale a essere negato — quindi `child`
+// e' ancora vivo quando enterDegraded schedula run() per la prossima
+// generazione. run() faceva `child = spawn(...)` incondizionatamente: la
+// vecchia generazione, ancora viva, restava senza piu' nessuna variabile che
+// la referenzi — irraggiungibile da stop(), orfana, titolare dei suoi bind
+// per sempre. Misurato dall'auditor: due fake-ssh vivi dopo un degraded,
+// SIGTERM al supervisor ne ferma solo l'ultimo.
+//
+// La correzione non e' locale (un kill dentro enterDegraded): e' che
+// run() — l'UNICO punto che assegna `child` a un nuovo spawn — non
+// garantiva la precondizione da solo. replaceChild() e' ora quel punto
+// unico: ferma SEMPRE il child uscente (se vivo) e ne attende l'uscita
+// prima di procedere. Se non c'e' nulla da fermare (gia' null, o gia'
+// uscito — il caso reverse, verificato invariato) procede subito: la stessa
+// funzione copre correttamente entrambi i versi, nessun percorso bypassa la
+// garanzia senza dichiararlo qui.
+function replaceChild(spawnNext) {
+  const outgoing = child;
+  const proceed = () => {
+    clearTimeout(upTimer);
+    clearForwardProbe();
+    spawnNext();
+  };
+  if (!outgoing || outgoing.exitCode != null) return proceed();
+  // La generazione uscente muore per NOSTRA mano qui, non per un crash che
+  // handleFailure deve classificare: distacchiamo i suoi listener prima di
+  // ucciderla, altrimenti il kill sotto farebbe scattare la gestione
+  // fallimento della generazione vecchia in corsa con quella nuova (doppio
+  // scheduleRetry/enterDegraded, `child` azzerato da sotto i piedi).
+  outgoing.removeAllListeners('error');
+  outgoing.removeAllListeners('close');
+  outgoing.once('exit', proceed);
+  try { outgoing.kill('SIGTERM'); } catch (_) { return proceed(); }
+  const killTimer = setTimeout(() => {
+    try { if (outgoing.exitCode == null) outgoing.kill('SIGKILL'); } catch (_) {}
+  }, 1500);
+  if (typeof killTimer.unref === 'function') killTimer.unref();
+}
+
 function run() {
+  if (stopping) return finish();
+  replaceChild(spawnGeneration);
+}
+
+function spawnGeneration() {
   if (stopping) return finish();
   if (!writeState('starting')) return stop();
   logEvent(`ssh attempt=${attempt + 1} starting`);
   let stderrTail = '';
+  let localChild;
   try {
-    child = spawn(sshBin, sshArgs, { stdio: ['ignore', 'inherit', 'pipe'] });
+    localChild = spawn(sshBin, sshArgs, { stdio: ['ignore', 'inherit', 'pipe'] });
   } catch (e) {
     child = null;
     return scheduleRetry(String(e && e.message || e));
   }
+  child = localChild;
 
-  child.stderr?.on('data', (chunk) => {
+  localChild.stderr?.on('data', (chunk) => {
     const text = String(chunk || '');
     stderrTail = `${stderrTail}${text}`.slice(-8192);
     try { process.stderr.write(chunk); } catch (_) {}
@@ -202,6 +435,12 @@ function run() {
   const handleFailure = (detail) => {
     if (failureHandled) return;
     failureHandled = true;
+    // Difesa in profondita', come probeForward: se replaceChild ha gia'
+    // sostituito questa generazione (i suoi listener sono stati distaccati,
+    // quindi in pratica questo ramo non dovrebbe piu' potersi attivare per
+    // una generazione rimpiazzata) non tocchiamo lo stato di una generazione
+    // che non e' piu' quella corrente.
+    if (child !== localChild) return;
     clearTimeout(upTimer);
     clearForwardProbe();
     child = null;
@@ -215,25 +454,26 @@ function run() {
     }
     scheduleRetry((diagnosis && diagnosis.detail) || detail);
   };
-  child.once('spawn', () => {
+  localChild.once('spawn', () => {
     logEvent(`ssh attempt=${attempt + 1} spawned`);
     // ExitOnForwardFailure only proves that the local bind was accepted. It
     // does not prove authentication or remote reachability, so after the
     // stability window require a real TCP open through the -L channel.
     upTimer = setTimeout(() => {
-      if (!stopping && child && child.exitCode == null) {
-        probeForward(child);
+      if (!stopping && child === localChild && localChild.exitCode == null) {
+        probeForward(localChild);
       }
     }, stableMs);
   });
-  child.once('error', (e) => {
+  localChild.once('error', (e) => {
     logEvent(`ssh child error code=${(e && e.code) || 'unknown'}`);
     handleFailure(String(e && e.message || e));
   });
   // `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) => {
+  localChild.once('close', (code, signal) => {
     if (stopping) return finish();
+    if (child !== localChild) return; // sostituita da replaceChild: gestita li', non qui
     logEvent(`ssh exited code=${code === null ? 'null' : code} signal=${signal || 'none'}`);
     handleFailure(`ssh exited code=${code} signal=${signal || ''}`);
   });
@@ -286,4 +526,8 @@ function acquireGeneration() {
   if (Date.now() >= ownershipDeadline) return finish();
   ownershipWaitTimer = setTimeout(acquireGeneration, 20);
 }
-acquireGeneration();
+if (require.main === module) acquireGeneration();
+
+// Esportate per prova diretta (R19): il main resta argv/env-driven e NON parte
+// al require.
+module.exports = { probeForwardChannels, refusalHint, refusalDetails, CHANNEL_GRACE_MS };

package/lib/nodes/tunnel.js

@@ -409,6 +409,10 @@ function diagnoseTunnel(home, node, state = null) {
       stage: 'ssh', code: current.code || 'reverse-forward-failed', status: 'down', phase: 'degraded',
       detail: current.detail || 'canale inverso non disponibile, retry fisso in corso',
       hint: current.hint || 'il tunnel resta attivo e riprovera automaticamente; verifica il listener reverse sul hub',
+      // Campo strutturato: la riga authorized_keys viaggia INTERA fino alla UI,
+      // che non deve ritagliarla dall'hint.
+      ...(typeof current.authorizedKeys === 'string' && current.authorizedKeys
+        ? { authorizedKeys: current.authorizedKeys } : {}),
       ...(Number.isInteger(current.reversePort) ? { reversePort: current.reversePort } : {}),
     };
   }
@@ -690,8 +694,116 @@ function readSshVersion(spawnSyncImpl) {
   } catch (_) { return null; }
 }
 
+// R19: la riga authorized_keys con le destinazioni EXPLICITE dei -L. Una sola
+// porta quando il pannello non è (ancora) noto: nodesAdd non può conoscerla,
+// la annuncia il peer nel join — e allora la riga la emette CHI ha
+// l'informazione (pairing, supervisor). Due permitopen distinti, MAI un
+// permesso generico: è il vincolo che impedisce a una chiave di tunnel di
+// aprire canali arbitrari sulla macchina. Dedup: nexus e pannello sulla
+// stessa porta si dichiarano una volta.
+function authorizedKeysLine({ remotePort, panelRemotePort, pub } = {}) {
+  if (!pub || typeof pub !== 'string') return null;
+  const ports = [];
+  for (const p of [remotePort, panelRemotePort]) {
+    const n = Number(p);
+    if (Number.isInteger(n) && n >= 1 && n <= 65535 && !ports.includes(n)) ports.push(n);
+  }
+  if (!ports.length) return null;
+  const permitopen = ports.map((p) => `permitopen="127.0.0.1:${p}"`).join(',');
+  return `restrict,port-forwarding,${permitopen},command="/bin/false" ${pub}`;
+}
+
+// LA PUBBLICA SI DERIVA DALLA PRIVATA, non si legge dal file accanto.
+//
+// Tre giri fa validavo il nome dell'algoritmo, due giri fa la struttura del
+// blob, un giro fa la chiedevo a `ssh-keygen -l` sul file `.pub`. Tutte e tre
+// le volte un audit ha trovato il caso che restava: e l'ultimo lo chiude solo
+// cambiando la domanda. Validare `A.pub` prova che quel file contiene UNA
+// chiave valida — non che sia LA chiave di `A`. Se `A.pub` e' stale, ripristinato
+// da un backup o sostituito, si pubblica la chiave sbagliata: l'utente
+// sostituisce la riga di A con quella di B, e al reconnect successivo A perde
+// l'accesso. Il prodotto avrebbe causato il guasto che prometteva di riparare.
+//
+// `ssh-keygen -y -f <privata>` deriva la pubblica DALLA privata: il legame e'
+// garantito per costruzione, non verificato a posteriori. E siccome i byte
+// arrivano da un solo comando, sparisce anche la finestra fra "leggo il file" e
+// "lo faccio validare a qualcun altro", in cui il file poteva cambiare.
+//
+// Torna null se la privata non e' leggibile, e' protetta da passphrase (in
+// batch non si puo' sbloccare) o `ssh-keygen` non c'e': senza poterla derivare
+// non si compone nessuna riga.
+function readPublicKey(identityFile, impl = {}) {
+  if (!identityFile || typeof identityFile !== 'string') return null;
+  const exec = impl.execImpl || require('node:child_process').execFileSync;
+  // Timeout iniettabile (test): il default 5000 ms e' la RETE, non il
+  // meccanismo — il meccanismo e' l'ambiente controllato qui sotto.
+  const timeoutMs = Number.isFinite(impl.timeoutMs) && impl.timeoutMs > 0 ? impl.timeoutMs : 5000;
+  let out;
+  try {
+    // AMBIENTE CONTROLLATO, e non e' pignoleria: con una privata cifrata
+    // `ssh-keygen` va a caccia della passphrase, e il timeout di execFileSync
+    // uccide solo il processo diretto — un helper askpass resterebbe orfano.
+    // Il supervisore chiama questa funzione a ogni rifiuto del canale, quindi
+    // i retry accumulerebbero prompt e processi che nessuno raccoglie: lo
+    // stesso difetto degli ssh orfani, per un'altra strada.
+    //
+    // La passphrase NON si legge da stdin (chiuderlo non basta): OpenSSH apre
+    // /dev/tty quando esiste un controlling terminal — il caso di `nexuscrew
+    // serve` foreground, che chiama questa via in modo sincrono — e li' resta
+    // ad aspettare input fino al timeout. La cura e' spostare la lettura via
+    // dal tty: `SSH_ASKPASS_REQUIRE=force` usa l'askpass ANCHE col tty
+    // presente, e SSH_ASKPASS punta a un path che NON ESISTE dentro una
+    // directory che controlliamo: l'askpass ineseguibile fa fallire SUBITO la
+    // chiave cifrata (misurato: 0.11 s contro gli 8 s dell'attesa su tty) e
+    // non puo' lasciare helper. Un path inesistente vince su /bin/false: su
+    // Termux i binari stanno sotto $PREFIX, e un path assoluto sbagliato e'
+    // una scommessa.
+    // LIMITE DA SAPERE: SSH_ASKPASS_REQUIRE esiste da OpenSSH 8.4. Le versioni
+    // piu' vecchie lo ignorano e tornano al tty: li' il timeout qui sopra
+    // resta come rete — il degrado e' «lento», non «appeso».
+    out = exec('ssh-keygen', ['-y', '-f', identityFile], {
+      encoding: 'utf8', timeout: timeoutMs, stdio: ['ignore', 'pipe', 'ignore'],
+      env: {
+        PATH: process.env.PATH || '/usr/bin:/bin',
+        HOME: process.env.HOME || '',
+        SSH_ASKPASS_REQUIRE: 'force',
+        SSH_ASKPASS: path.join(process.env.HOME || os.homedir(), '.nexuscrew', 'askpass-inesistente'),
+      },
+    });
+  } catch (_) { return null; }   // assente, passphrase, privata illeggibile
+  const righe = String(out || '').split('\n').filter((r) => r.trim() !== '');
+  if (righe.length !== 1) return null;
+  const riga = righe[0].trim();
+  if (/[\u0000-\u0008\u000b-\u001f\u007f]/.test(riga)) return null;
+  const campi = riga.split(/[ \t]+/);
+  if (campi.length < 2 || !/^[A-Za-z0-9+/]+={0,2}$/.test(campi[1])) return null;
+  return riga;
+}
+
+// La riga per UN nodo, dal nodo. Sta qui e non nella route perche' la stessa
+// domanda — "quale riga deve incollare il peer di questo nodo?" — se la pongono
+// due punti lontani, e perche' la risposta dipende da un LIMITE che va detto.
+//
+// Senza `identityFile` il prodotto non sa quale chiave usera' ssh: usera' quelle
+// di default dell'utente, un agent o la config, e da qui non si puo' sapere
+// quale. Si torna `null` invece di inventarne una.
+//
+// E NON C'E' UN ALTRO CANALE CHE RIPARI, in quel caso: nemmeno la sonda del
+// supervisore, che ricava la chiave solo da `-i` e senza quello puo' dire
+// soltanto QUALI destinazioni aggiungere, non a quale riga. La riparazione
+// automatica esiste solo per chi ha un'identita' dedicata; per gli altri il
+// prodotto lo dichiara e chiede una modifica manuale. Il completamento vero e'
+// provisionare un'identita' per peer — lavoro suo, non un ramo di questa
+// funzione.
+function authorizedKeysForNode(nodo, panelRemotePort) {
+  const pub = readPublicKey(nodo && nodo.identityFile);
+  if (!pub) return null;
+  return authorizedKeysLine({ remotePort: nodo.remotePort, panelRemotePort, pub });
+}
+
 module.exports = {
   SSH_BASE_OPTS,
+  authorizedKeysLine, readPublicKey, authorizedKeysForNode,
   buildForwardArgs, buildReverseArgs, backoffDelay,
   tunnelDir, tunnelPidPath, tunnelLogPath, tunnelStatePath, readTunnelState,
   prepareTunnelDir, openTunnelLog,

package/lib/proxy/panel-auth.js

@@ -16,8 +16,14 @@
 //    UNA cella. Il token del nodo non deve finire nella cronologia del
 //    browser, nei log del proxy o in un Referer.
 // 2. IL TICKET SI CONSUMA ALLA PRIMA RICHIESTA e la risposta imposta un cookie
-//    HttpOnly SameSite Strict con `Path=/api/panel/<cella>` — ESATTAMENTE quel
-//    path, perche' le sotto-risorse relative passino e nient'altro.
+//    HttpOnly SameSite Strict con Path=ESATTAMENTE il mount da cui la
+//    richiesta e' entrata + la cella (R22, 2026-08-17): `/api/panel/<cella>`
+//    sul control plane, `/panel/<cella>` sulla porta pannello dedicata — MAI
+//    una costante unica, perche' i due mount servono path diversi e un cookie
+//    scritto per l'uno non verrebbe mai mandato dal browser sotto l'altro
+//    (misura originale: pannello bianco, ogni sotto-risorsa in 401). Lo scope
+//    resta stretto quanto prima — perche' le sotto-risorse relative passino
+//    e nient'altro — solo il prefisso non e' piu' assunto fisso.
 // 3. IL COOKIE NON E' UN'AUTENTICAZIONE DELL'ORIGINE. Il progetto non ne ha
 //    una, e introdurla aprirebbe CSRF su tutte le altre route: qui si verifica
 //    SEMPRE che il cookie sia stato emesso per la cella del path, e lo scope
@@ -153,10 +159,14 @@ function createPanelAuth({
     return !!rec && rec.exp > now() && rec.cell === cellId;
   }
 
-  function cookieHeaderValue(cellId, value) {
+  // R22: il Path deve valere per il mount da cui la richiesta e' ENTRATA, non
+  // per una costante. Whitelist stretta invece di un default permissivo — un
+  // prefisso non riconosciuto rifiuta (vedi mountPrefixOf) invece di produrre
+  // un cookie con uno scope che nessuno ha verificato.
+  function cookieHeaderValue(mountPrefix, cellId, value) {
     const attrs = [
       `${COOKIE_NAME}=${value}`,
-      `Path=/api/panel/${encodeURIComponent(cellId)}`,
+      `Path=${mountPrefix}/${encodeURIComponent(cellId)}`,
       'HttpOnly',
       'SameSite=Strict',
       `Max-Age=${Math.floor(cookieTtlMs / 1000)}`,
@@ -164,6 +174,25 @@ function createPanelAuth({
     return attrs.join('; ');
   }
 
+  // I DUE mount legittimi, misurati sul wire (non dedotti dalla struttura del
+  // codice — la stessa disciplina del commento a hopKind, righe 112-114):
+  // control plane (`api.use('/panel', …)` sotto `app.use('/api', api)`) e
+  // porta pannello dedicata (`panelApp.use('/panel', …)`, nessun livello
+  // sopra). `req.baseUrl` accumula i prefissi dei router express attraversati
+  // fino al middleware — misurato `/api/panel` nel primo caso, `/panel` nel
+  // secondo, per un mount annidato E per un mount diretto a due segmenti
+  // (il caso federato: `remoteApi.use('/api/panel', panelAuthMiddleware)`).
+  const PANEL_MOUNT_PREFIXES = new Set(['/api/panel', '/panel']);
+
+  // Un mount NON riconosciuto (baseUrl mancante, vuoto, o qualunque valore
+  // fuori dai due noti) non deve MAI produrre un Path per analogia o per
+  // default — significherebbe indovinare uno scope che nessuno ha verificato.
+  // Ritorna null per far fallire chiuso, mai una stringa "ragionevole".
+  function mountPrefixOf(req) {
+    const raw = String(req.baseUrl || '');
+    return PANEL_MOUNT_PREFIXES.has(raw) ? raw : null;
+  }
+
   // —— Emissione: POST /api/panel/<cella>/ticket, SOLO per la PWA autenticata.
   // La cella deve esistere ed avere un pannello valido: nessun ticket per
   // destinazioni che il proxy rifiuterebbe comunque.
@@ -208,9 +237,19 @@ function createPanelAuth({
     const qi = url.indexOf('?');
     if (qi !== -1) qTicket = new URLSearchParams(url.slice(qi + 1)).get('ticket');
     if (qTicket) {
+      // R22: il mount si verifica PRIMA di toccare il ticket — un mount non
+      // riconosciuto non deve bruciare un ticket monouso per un errore che
+      // non dipende da chi lo presenta.
+      const mountPrefix = mountPrefixOf(req);
+      if (!mountPrefix) {
+        log({ event: 'panel-auth', outcome: 'denied', reason: 'mount-non-riconosciuto', cell: cellId });
+        res.writeHead(500, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'mount non riconosciuto' }));
+        return;
+      }
       if (consumeTicket(qTicket, cellId)) {
         const value = issueCookie(cellId);
-        res.setHeader('set-cookie', cookieHeaderValue(cellId, value));
+        res.setHeader('set-cookie', cookieHeaderValue(mountPrefix, cellId, value));
         log({ event: 'panel-auth', outcome: 'ticket-consumed', cell: cellId });
         return next();
       }
@@ -326,6 +365,7 @@ function createPanelAuth({
     verifyCookieForTest: verifyCookie,
     issueCookieForTest: issueCookie,
     cookieHeaderValueForTest: cookieHeaderValue,
+    mountPrefixOfForTest: mountPrefixOf,
   };
 }