@mmmbuto/nexuscrew 0.8.9 → 0.8.10

package/lib/nodes/tunnel.js

@@ -1,12 +1,12 @@
 'use strict';
 // lib/nodes/tunnel.js — SSH tunnel manager (design §4b(1), §7).
 //
-// I processi ssh sono figli del lifecycle CLI/service, MAI di un handler HTTP
-// (nessun spawn dalla superficie web). Template SSH ESATTI dal design §4b(1);
-// argv puro (spawn con array), nessuna shell interpolation.
+// I processi ssh sono gestiti da un solo supervisor detached, avviato dal
+// lifecycle del servizio o dalle azioni PWA autenticate. argv puro (spawn con
+// array), nessuna shell interpolation.
 //
 // Due meccaniche:
-//   - builder puri (buildForwardArgs/buildReverseArgs) + backoff deterministico:
+//   - builder puro buildForwardArgs + backoff deterministico:
 //     unit-testabili senza lanciare ssh.
 //   - lifecycle per-tunnel via pidfile (start/stop/restart/state): il processo
 //     ssh e' detached, la sua liveness/porta stabile e' interrogabile da
@@ -16,6 +16,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
+const crypto = require('node:crypto');
 const { spawn, spawnSync } = require('node:child_process');
 const pidf = require('../cli/pidfile.js');
 const store = require('./store.js');
@@ -39,14 +40,6 @@ function assertForwardSpec(node) {
   if (!store.parseSshTarget(node.ssh)) throw new Error('tunnel: target ssh non valido');
 }
 
-function assertReverseSpec(rdv) {
-  if (!rdv || typeof rdv !== 'object') throw new Error('tunnel: rendezvous mancante');
-  if (!store.isPort(rdv.publishedPort)) throw new Error('tunnel: publishedPort non valida');
-  if (!store.isPort(rdv.localPort)) throw new Error('tunnel: localPort non valida');
-  if (!store.isAbsPath(rdv.keyPath)) throw new Error('tunnel: keyPath non valido');
-  if (!store.parseSsh(rdv.ssh)) throw new Error('tunnel: ssh (user@rendezvous) non valido');
-}
-
 // Forward client->nodo (ruolo client). §4b(1):
 //   ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=30
 //       -o ServerAliveCountMax=3 -o BatchMode=yes -i <key>
@@ -55,9 +48,12 @@ function buildForwardArgs(node) {
   assertForwardSpec(node);
   const transport = node.sshPort === undefined ? [] : ['-p', String(node.sshPort)];
   const identity = node.identityFile || node.keyPath;
-  const reverse = node.reversePort === undefined ? [] : [
+  // The forward channel is the connection to the hub and is always present.
+  // The reverse channel publishes this device back through the hub, so it is
+  // opt-in only. A negotiated reversePort alone must never imply consent.
+  const reverse = node.shared === true && node.reversePort !== undefined ? [
     '-R', `127.0.0.1:${node.reversePort}:127.0.0.1:${node.localAppPort || node.remotePort}`,
-  ];
+  ] : [];
   return SSH_BASE_OPTS.concat(transport, identity ? ['-i', identity] : [], [
     '-L', `127.0.0.1:${node.localPort}:127.0.0.1:${node.remotePort}`,
     ...reverse,
@@ -65,18 +61,6 @@ function buildForwardArgs(node) {
   ]);
 }
 
-// Reverse nodo->rendezvous (ruolo node). §4b(1): bind loopback ESPLICITO lato
-// remoto (mai wildcard):
-//   ssh -N ... -i <key> -R 127.0.0.1:<pubblicata>:127.0.0.1:<locale> user@rendezvous
-function buildReverseArgs(rdv) {
-  assertReverseSpec(rdv);
-  return SSH_BASE_OPTS.concat([
-    '-i', rdv.keyPath,
-    '-R', `127.0.0.1:${rdv.publishedPort}:127.0.0.1:${rdv.localPort}`,
-    rdv.ssh,
-  ]);
-}
-
 // Backoff esponenziale + jitter (design §7). Deterministico con rng iniettato.
 //   delay = clamp(base * factor^attempt, 0..cap) * (1 +- jitter*(2*rand-1))
 // rng()=0.5 -> jitter nullo (ritorna il valore base clamperato); test deterministici.
@@ -98,8 +82,8 @@ function tunnelDir(home) {
   return path.join(home || os.homedir(), '.nexuscrew', 'tunnels');
 }
 
-// pidfile per-tunnel: forward "<name>", reverse "__rendezvous__". Il name e' gia'
-// una chiave strict (^[a-z0-9-]{1,32}$), safe come basename.
+// pidfile per-tunnel: forward "<name>". `__rendezvous__` è riconosciuto soltanto
+// per spegnere un supervisor legacy durante la migrazione.
 function tunnelPidPath(home, name) {
   return path.join(tunnelDir(home), `${name}.pid`);
 }
@@ -108,6 +92,95 @@ function tunnelLogPath(home, name) {
   return path.join(tunnelDir(home), `${name}.log`);
 }
 
+function prepareTunnelDir(home) {
+  const dir = tunnelDir(home);
+  try {
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory()) throw new Error('unsafe tunnel directory');
+    fs.chmodSync(dir, 0o700);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory()) throw new Error('unsafe tunnel directory');
+    fs.chmodSync(dir, 0o700);
+  }
+  return dir;
+}
+
+function openTunnelLog(home, name) {
+  prepareTunnelDir(home);
+  const logPath = tunnelLogPath(home, name);
+  const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC |
+    (fs.constants.O_NOFOLLOW || 0);
+  let fd;
+  try {
+    fd = fs.openSync(logPath, flags, 0o600);
+    const st = fs.fstatSync(fd);
+    if (!st.isFile()) throw new Error('unsafe tunnel log');
+    fs.fchmodSync(fd, 0o600);
+    return { fd, logPath };
+  } catch (error) {
+    if (fd !== undefined) try { fs.closeSync(fd); } catch (_) {}
+    throw error;
+  }
+}
+
+// Classifica soltanto firme SSH note e restituisce messaggi sicuri/azionabili:
+// mai rimandare il log grezzo alla PWA (può contenere host/path locali). Serve
+// soprattutto nel pairing: un normale `ssh hub-alias` può autenticarsi mentre permitopen nega
+// il forward richiesto, caso che prima collassava nel generico "fetch failed".
+function classifySshFailure(text, remotePort) {
+  const s = String(text || '');
+  const target = store.isPort(remotePort) ? `127.0.0.1:${remotePort}` : 'la porta NexusCrew richiesta';
+  if (/administratively prohibited|request (?:was )?denied|open failed:.*prohibited|port forwarding.*(?:disabled|denied)/i.test(s)) {
+    return {
+      code: 'forward-denied',
+      detail: `SSH autenticato, ma il server ha negato il port forwarding verso ${target}`,
+      hint: `verifica AllowTcpForwarding e l'eventuale permitopen per ${target}; il link NON e' stato consumato`,
+    };
+  }
+  if (/Permission denied \((?:publickey|password|keyboard-interactive)[^)]*\)|No supported authentication methods available/i.test(s)) {
+    return { code: 'ssh-auth-failed', detail: 'autenticazione SSH rifiutata', hint: 'verifica la chiave o l’Host SSH configurato su questo dispositivo; il link NON e\' stato consumato' };
+  }
+  if (/REMOTE HOST IDENTIFICATION HAS CHANGED|Host key verification failed|authenticity of host .* can'?t be established/i.test(s)) {
+    return { code: 'ssh-host-key', detail: 'verifica della host key SSH non completata', hint: 'verifica la host key con il normale client SSH; NexusCrew non la accetta automaticamente' };
+  }
+  if (/Could not resolve hostname|Name or service not known|nodename nor servname provided/i.test(s)) {
+    return { code: 'ssh-dns', detail: 'host SSH non risolvibile', hint: 'verifica hostname o alias nel file SSH di questo dispositivo' };
+  }
+  if (/Bad owner or permissions on .*ssh|Bad configuration option|Could not open user configuration file/i.test(s)) {
+    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 (/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' };
+  }
+  if (/Connection refused|No route to host|Connection timed out|Operation timed out|Network is unreachable/i.test(s)) {
+    return { code: 'ssh-unreachable', detail: 'endpoint SSH non raggiungibile', hint: 'verifica rete, hostname e porta SSH' };
+  }
+  return null;
+}
+
+function readTunnelDiagnostic(home, name, remotePort) {
+  if (!store.NODE_NAME_RE.test(String(name || ''))) return null;
+  const p = tunnelLogPath(home, name);
+  let fd;
+  try {
+    fd = fs.openSync(p, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    const st = fs.fstatSync(fd);
+    if (!st.isFile()) return null;
+    const size = Math.min(st.size, 16 * 1024);
+    if (!size) return null;
+    const buf = Buffer.alloc(size);
+    fs.readSync(fd, buf, 0, size, Math.max(0, st.size - size));
+    return classifySshFailure(buf.toString('utf8'), remotePort);
+  } catch (_) { return null; }
+  finally { if (fd !== undefined) try { fs.closeSync(fd); } catch (_) {} }
+}
+
 function tunnelStatePath(home, name) {
   return path.join(tunnelDir(home), `${name}.state.json`);
 }
@@ -119,8 +192,16 @@ function readTunnelState(home, name) {
   if (meta && pidf.isAlive(meta)) {
     try {
       const state = JSON.parse(fs.readFileSync(tunnelStatePath(home, name), 'utf8'));
-      if (state.status === 'up') return { status: 'up', pid: meta.pid, since: meta.startTs || null };
-      return { status: 'down', pid: meta.pid, since: meta.startTs || null, reason: state.status || 'starting' };
+      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 === '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 } : {}) };
+      }
+      return { status: 'down', phase: state.status || 'starting', pid: meta.pid, since: meta.startTs || null,
+        reason: state.status || 'starting', ...(Number.isInteger(state.attempt) ? { attempt: state.attempt } : {}),
+        ...(Number.isFinite(state.delayMs) ? { retryInMs: state.delayMs } : {}), ...(transport ? { transport } : {}) };
     } catch (_) {
       // Backward compatibility for pre-supervisor pidfiles: a live direct ssh
       // process had no state sidecar and was considered up.
@@ -133,6 +214,50 @@ function readTunnelState(home, name) {
   return { status: 'down' };
 }
 
+function diagnoseTunnel(home, node, state = null) {
+  const current = state || readTunnelState(home, node && node.name);
+  const ssh = node && readTunnelDiagnostic(home, node.name, node.remotePort);
+  if (ssh) return { stage: 'ssh', ...ssh, status: current.status, phase: current.phase || current.reason || null };
+  if (current.status === 'up') {
+    return { stage: 'transport', code: 'transport-ready', status: 'up', phase: current.phase || 'transport-ready',
+      detail: 'trasporto SSH stabile; verifica federation in corso' };
+  }
+  if (current.reason === 'starting' || current.phase === 'starting') {
+    return { stage: 'ssh', code: 'ssh-starting', status: 'starting', phase: 'starting',
+      detail: 'connessione SSH in avvio', hint: 'attendi qualche secondo e usa Test connessione' };
+  }
+  if (current.reason === 'retrying' || current.phase === 'retrying') {
+    return { stage: 'ssh', code: 'ssh-retrying', status: 'retrying', phase: 'retrying',
+      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' };
+  }
+  return { stage: 'ssh', code: 'tunnel-stopped', status: 'down', phase: current.phase || null,
+    detail: 'connessione SSH ferma', hint: 'avvia la connessione dalla PWA, Impostazioni > Nodi' };
+}
+
+function removeStateIfOwned(home, name, meta) {
+  const statePath = tunnelStatePath(home, name);
+  try {
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    const samePid = !meta || !meta.pid || state.supervisorPid === meta.pid;
+    const sameRun = !meta || !meta.runId || state.runId === meta.runId;
+    if (samePid && sameRun) { fs.unlinkSync(statePath); return true; }
+  } catch (_) {}
+  return false;
+}
+
+function supervisorExited(pid, timeoutMs = 2500) {
+  const deadline = Date.now() + timeoutMs;
+  const sleeper = new Int32Array(new SharedArrayBuffer(4));
+  const exited = () => {
+    if (!pidf.pidExists(pid)) return true;
+    try { return fs.readFileSync(`/proc/${pid}/stat`, 'utf8').split(' ')[2] === 'Z'; }
+    catch (_) { return false; }
+  };
+  while (!exited() && Date.now() < deadline) Atomics.wait(sleeper, 0, 0, 25);
+  return exited();
+}
+
 // Pre-flight sincrono: l'unico modo di "surfaccare" un binario ssh assente come
 // failure ESPLICITA nel valore di ritorno (lo spawn emette 'error' asincrono, non
 // catturabile sync). spawnSyncImpl iniettabile per test deterministici.
@@ -167,19 +292,40 @@ function startTunnel(opts) {
   if (!Array.isArray(args)) throw new Error('startTunnel: args mancanti');
 
   const pidPath = tunnelPidPath(home, name);
+  const supervisor = path.join(__dirname, 'tunnel-supervisor.js');
+  const runId = crypto.randomBytes(16).toString('hex');
+  const supervisorArgs = [supervisor, sshBin, ...args];
+  const cmd = `${process.execPath} ${supervisorArgs.join(' ')}`;
   const existing = pidf.readPidfile(pidPath);
   if (existing && pidf.isAlive(existing)) {
-    return { started: false, reason: 'already running', pid: existing.pid };
+    // An update or automatic HTTP-port fallback can change -L/-R while the
+    // detached supervisor is still alive.  Keep exact matches idempotent, but
+    // replace a supervisor whose saved argv no longer matches the desired one.
+    if (!existing.cmd || existing.cmd === cmd) {
+      return { started: false, reason: 'already running', pid: existing.pid, transport: sshBin };
+    }
+    const oldMeta = existing;
+    const stopped = pidf.killPidfile(pidPath);
+    if (!stopped.killed) return { started: false, reason: `running spec mismatch: ${stopped.reason || 'stop failed'}`, pid: existing.pid };
+    if (!(opts.supervisorExitedImpl || supervisorExited)(oldMeta.pid, opts.stopWaitMs || 2500)) {
+      return { started: false, reason: `running spec mismatch: old supervisor ${oldMeta.pid} did not exit`, pid: oldMeta.pid };
+    }
+    removeStateIfOwned(home, name, oldMeta);
   }
   pidf.cleanStale(pidPath);
 
-  fs.mkdirSync(tunnelDir(home), { recursive: true });
   const logPath = tunnelLogPath(home, name);
   const statePath = tunnelStatePath(home, name);
   // fdProvided: il caller ci passa un fd (es. test con logFd:null) e ne rimane
   // proprietario; noi chiudiamo solo la fd che apriamo noi (no double-close).
   const fdProvided = opts.logFd !== undefined;
-  const logFd = fdProvided ? opts.logFd : fs.openSync(logPath, 'a');
+  let logFd;
+  try {
+    prepareTunnelDir(home);
+    logFd = fdProvided ? opts.logFd : openTunnelLog(home, name).fd;
+  } catch (_) {
+    return { started: false, reason: 'unsafe tunnel log path' };
+  }
   let fdClosed = false;
   const closeOwnedFd = () => {
     if (fdClosed) return; fdClosed = true;
@@ -196,13 +342,17 @@ function startTunnel(opts) {
   // Spawn a detached Node supervisor. It owns ssh and retries failures with the
   // bounded backoff defined above, so CLI/server lifetime does not own liveness.
   let child;
-  const supervisor = path.join(__dirname, 'tunnel-supervisor.js');
-  const supervisorArgs = [supervisor, sshBin, ...args];
   try {
     child = spawnImpl(process.execPath, supervisorArgs, {
       detached: true,
       stdio: ['ignore', logFd, logFd],
-      env: { ...process.env, AUTOSSH_GATETIME: '0', NEXUSCREW_TUNNEL_STATE: statePath },
+      env: {
+        ...process.env,
+        NEXUSCREW_TUNNEL_STATE: statePath,
+        NEXUSCREW_TUNNEL_PIDFILE: pidPath,
+        NEXUSCREW_TUNNEL_RUN_ID: runId,
+        ...(opts.stableMs === undefined ? {} : { NEXUSCREW_TUNNEL_STABLE_MS: String(opts.stableMs) }),
+      },
     });
   } catch (e) {
     closeOwnedFd();
@@ -216,8 +366,8 @@ function startTunnel(opts) {
   let pid = child && child.pid;
   const cleanupIfOwned = () => {
     const current = pidf.readPidfile(pidPath);
-    if (current && current.pid === pid) pidf.removePidfile(pidPath);
-    try { fs.unlinkSync(statePath); } catch (_) {}
+    if (current && current.pid === pid && current.runId === runId) pidf.removePidfile(pidPath);
+    removeStateIfOwned(home, name, { pid, runId });
   };
   if (child && typeof child.on === 'function') {
     child.on('error', () => {
@@ -232,10 +382,9 @@ function startTunnel(opts) {
     return { started: false, reason: 'spawn error (no pid)' };
   }
 
-  const cmd = `${process.execPath} ${supervisorArgs.join(' ')}`;
   // writePidfile e' exclusive (wx): cleanStale sopra ha gia' tolto uno stale.
   try {
-    pidf.writePidfile(pidPath, pid, cmd);
+    pidf.writePidfile(pidPath, pid, cmd, { runId });
   } catch (e) {
     try { process.kill(pid, 'SIGTERM'); } catch (_) {}
     cleanupIfOwned();
@@ -243,7 +392,7 @@ function startTunnel(opts) {
     return { started: false, reason: 'pidfile error', error: String(e && e.message || e) };
   }
   closeOwnedFd(); // copia del padre: il figlio ha la sua dup; nessun leak (audit F3)
-  return { started: true, pid, logPath };
+  return { started: true, pid, logPath, transport: sshBin };
 }
 
 // Ferma il tunnel: kill verificato via pidfile (mai broad match by name).
@@ -251,8 +400,13 @@ function stopTunnel(opts) {
   const home = opts.home || os.homedir();
   const name = opts.name;
   if (!name) throw new Error('stopTunnel: name mancante');
-  const r = pidf.killPidfile(tunnelPidPath(home, name));
-  try { fs.unlinkSync(tunnelStatePath(home, name)); } catch (_) {}
+  const pidPath = tunnelPidPath(home, name);
+  const meta = pidf.readPidfile(pidPath);
+  const r = pidf.killPidfile(pidPath);
+  if (r.killed && !(opts.supervisorExitedImpl || supervisorExited)(r.pid, opts.stopWaitMs || 2500)) {
+    return { stopped: false, pid: r.pid, reason: `supervisor ${r.pid} did not exit after SIGTERM` };
+  }
+  removeStateIfOwned(home, name, meta);
   return { stopped: r.killed, pid: r.pid, reason: r.reason };
 }
 
@@ -264,29 +418,24 @@ function restartTunnel(opts) {
 // Helper di alto livello: costruisce args dal nodo e avvia il forward.
 function startForward(opts) {
   const node = opts.node;
-  let sshBin = opts.sshBin;
-  let args = buildForwardArgs({ ...node, localAppPort: opts.localAppPort });
-  const wanted = node.transport || (node.keyPath ? 'ssh' : 'auto');
-  if (!sshBin && (wanted === 'auto' || wanted === 'autossh') && sshBinaryAvailable('autossh', opts.spawnSyncImpl)) {
-    sshBin = 'autossh';
-    args = ['-M', '0', ...args];
-  } else if (!sshBin) {
-    sshBin = 'ssh';
-  }
+  const args = buildForwardArgs({ ...node, localAppPort: opts.localAppPort });
+  // NexusCrew already owns retry/backoff in tunnel-supervisor.js. Nesting
+  // autossh inside that supervisor made liveness dishonest: autossh could stay
+  // alive while every SSH child exited 255, so the UI reported "tunnel up".
+  // Use one portable supervisor around OpenSSH on Linux, macOS and Termux.
+  // `transport: autossh` remains readable for old stores but is normalized at
+  // runtime to supervised ssh.
+  const sshBin = opts.sshBin || 'ssh';
   return startTunnel({ ...opts, sshBin, name: node.name, args });
 }
 
-// Helper di alto livello: reverse verso il rendezvous.
+// Cleanup identifier for pre-0.8.10 standalone rendezvous supervisors. New
+// runtimes never start this second connection; stop/restart can still remove a
+// stale legacy process during migration.
 const REVERSE_NAME = '__rendezvous__';
-function startReverse(opts) {
-  const args = buildReverseArgs(opts.rendezvous);
-  return startTunnel({ ...opts, name: REVERSE_NAME, args });
-}
 
-// --- Capability OpenSSH (permitlisten, design §7 advisory (a)) --------------
-// permitlisten (vincola i -R) esiste da OpenSSH 7.8. Serve sul rendezvous per il
-// ruolo node; il check locale su `ssh -V` e' l'unico verificabile in autonomia.
-// null = versione non determinabile (non un fail: warn + verifica manuale).
+// Versione client OpenSSH, solo diagnostica. Non inferire mai da questa la
+// policy `permitlisten` del server remoto: quella si prova con il vero -R.
 function readSshVersion(spawnSyncImpl) {
   try {
     const r = (spawnSyncImpl || spawnSync)('ssh', ['-V'], { encoding: 'utf8' });
@@ -297,19 +446,15 @@ function readSshVersion(spawnSyncImpl) {
   } catch (_) { return null; }
 }
 
-// true/false se determinabile, null se versione ignota.
-function sshSupportsPermitlisten(v) {
-  if (!v) return null;
-  if (v.major > 7) return true;
-  if (v.major === 7 && v.minor >= 8) return true;
-  return false;
-}
-
 module.exports = {
   SSH_BASE_OPTS,
-  buildForwardArgs, buildReverseArgs, backoffDelay,
+  buildForwardArgs, backoffDelay,
   tunnelDir, tunnelPidPath, tunnelLogPath, tunnelStatePath, readTunnelState,
-  startTunnel, stopTunnel, restartTunnel, startForward, startReverse,
+  prepareTunnelDir, openTunnelLog,
+  classifySshFailure, readTunnelDiagnostic,
+  diagnoseTunnel,
+  removeStateIfOwned, supervisorExited,
+  startTunnel, stopTunnel, restartTunnel, startForward,
   REVERSE_NAME,
-  readSshVersion, sshSupportsPermitlisten, sshBinaryAvailable,
+  readSshVersion, sshBinaryAvailable,
 };

package/lib/proxy/federation.js

@@ -29,7 +29,10 @@ function peerAllows(peer, otherId) {
 
 function canTransit(ingress, egress) {
   if (!ingress || !egress || ingress.name === egress.name) return !ingress;
-  return peerAllows(ingress, egress.nodeId) && peerAllows(egress, ingress.nodeId);
+  // `shared` is the explicit publication gate. Visibility remains the hub ACL,
+  // but it cannot make a private peer routable on its own.
+  return egress.shared === true
+    && peerAllows(ingress, egress.nodeId) && peerAllows(egress, ingress.nodeId);
 }
 
 function parseRoute(raw) {
@@ -54,6 +57,13 @@ function knownResource(resource) {
     || resource === '/files'
     || resource === '/files/download'
     || resource === '/files/upload'
+    || resource === '/decks'
+    || /^\/decks\/[a-z0-9-]{1,32}$/.test(resource)
+    || resource === '/topology'
+    // A connected client may ask its hub to mint a hub-owned, one-time
+    // pairing invite. This is the only settings mutation exposed through
+    // Hydra: the rest of /settings stays unreachable.
+    || resource === '/settings/peering/invite'
     || resource === '/ws'
     || /^\/fleet\/(status|schema|definitions|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-cell|edit-cell|remove-cell|restore-cells)$/.test(resource);
 }
@@ -66,6 +76,12 @@ function allowedResource(resource, method = 'GET') {
   if (resource === '/files') return method === 'GET' || method === 'DELETE';
   if (resource === '/files/download') return method === 'GET';
   if (resource === '/files/upload') return method === 'POST';
+  if (resource === '/decks') return method === 'GET' || method === 'POST';
+  if (/^\/decks\/[a-z0-9-]{1,32}$/.test(resource)) {
+    return method === 'PUT' || method === 'PATCH' || method === 'DELETE';
+  }
+  if (resource === '/topology') return method === 'GET';
+  if (resource === '/settings/peering/invite') return method === 'POST';
   if (resource === '/ws') return method === 'GET';
   if (/^\/fleet\/(status|schema|definitions)$/.test(resource)) return method === 'GET';
   if (/^\/fleet\/(up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-cell|edit-cell|remove-cell|restore-cells)$/.test(resource)) return method === 'POST';
@@ -103,7 +119,8 @@ function routeHandler({ nodesPath, localPort, localCredential, ingress = null, r
       return proxyHttp(req, res, { port: typeof localPort === 'function' ? localPort() : localPort, path: `/api${parsed.resource}${queryOf(req.url)}`, credential: localCredential() });
     }
     const next = st && store.getNode(st, parsed.route[0]);
-    if (!next || !next.token || (ingress && !canTransit(ingress, next))) return res.status(403).json({ error: 'route non consentita' });
+    const privateInbound = next && next.direction === 'inbound' && next.shared !== true;
+    if (!next || !next.token || privateInbound || (ingress && !canTransit(ingress, next))) return res.status(403).json({ error: 'route non consentita' });
     const rest = parsed.route.slice(1);
     const path = `/federation/route/${rest.length ? `${rest.join('/')}/` : ''}${ROUTE_DELIMITER}${parsed.resource}${queryOf(req.url)}`;
     proxyHttp(req, res, { port: next.localPort, path, credential: next.token, visited });
@@ -194,7 +211,11 @@ async function collectTopologyDetailed({ nodesPath, ingress = null, ttl = MAX_HO
   const out = [];
   const authoritative = [];
   for (const n of st.nodes) {
-    if (!n.nodeId || seen.has(n.nodeId) || (ingress && !canTransit(ingress, n))) continue;
+    // The local installation always keeps its outbound hub visible. Inbound
+    // clients become part of Hydra only after their explicit Share toggle.
+    if (!n.nodeId || seen.has(n.nodeId)
+      || (!ingress && n.direction === 'inbound' && n.shared !== true)
+      || (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 {
@@ -234,7 +255,9 @@ async function collectTopology(opts) {
 async function collectLocalTopology({ nodesPath, cachePath, fetchImpl = fetch, now = Math.floor(Date.now() / 1000) }) {
   const live = await collectTopologyDetailed({ nodesPath, fetchImpl });
   const st = store.loadStore(nodesPath);
-  const directNames = new Set(((st && st.nodes) || []).map((n) => n.name));
+  const directNames = new Set(((st && st.nodes) || [])
+    .filter((n) => n.direction !== 'inbound' || n.shared === true)
+    .map((n) => n.name));
   const authoritative = new Set(live.authoritative);
   const liveIds = new Set(live.nodes.map((n) => n.instanceId));
   const liveRoutes = new Set(live.nodes.map((n) => n.route.join('/')));
@@ -264,7 +287,7 @@ async function collectLocalTopology({ nodesPath, cachePath, fetchImpl = fetch, n
   return { instanceId: live.instanceId, nodes };
 }
 
-function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly, version = null, roles = null }) {
+function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly = () => false, version = null, roles = null }) {
   const r = express.Router();
   r.use((req, res, next) => {
     const peer = peerFromToken(nodesPath, bearerFrom(req));
@@ -286,6 +309,44 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
     const visited = String(req.query.visited || '').split(',');
     res.json(await collectTopology({ nodesPath, ingress: req.peer, ttl, visited, fetchImpl }));
   });
+  // A connected client publishes itself through the SAME SSH connection by
+  // toggling its optional -R channel. The hub records that intent only after a
+  // real authenticated health probe succeeds; Share off is immediate/fail-safe.
+  r.post('/share', express.json({ limit: '1kb' }), async (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: share bloccato' });
+    const body = req.body || {};
+    if (Object.keys(body).some((k) => k !== 'shared') || typeof body.shared !== 'boolean') {
+      return res.status(400).json({ error: 'body non valido: atteso {shared:boolean}' });
+    }
+    try {
+      if (body.shared) {
+        const health = await probeHealth({
+          port: req.peer.localPort,
+          token: req.peer.token,
+          expectedInstanceId: req.peer.nodeId || null,
+          fetchImpl: fetchImpl || fetch,
+        });
+        if (health.status !== 'healthy') {
+          return res.status(409).json({
+            error: 'canale share non raggiungibile',
+            detail: health.detail || 'reverse SSH non pronto',
+          });
+        }
+      }
+      let st = store.loadOrInitStore(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, {
+        shared: body.shared,
+        roles: { ...current.roles, node: body.shared },
+        rolesKnown: true,
+      });
+      store.atomicWriteStore(nodesPath, st);
+      return res.json({ shared: body.shared });
+    } catch (e) {
+      return res.status(500).json({ error: String(e && e.message || e) });
+    }
+  });
   r.use('/route', (req, res) => routeHandler({ nodesPath, localPort, localCredential, ingress: req.peer, readonly })(req, res));
   return r;
 }
@@ -307,7 +368,8 @@ function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredenti
   let port = typeof localPort === 'function' ? localPort() : localPort; let credential = localCredential(); let path = '/ws';
   if (parsed.route.length) {
     const next = store.getNode(st, parsed.route[0]);
-    if (!next || !next.token || (ingress && !canTransit(ingress, next))) return reject(socket, 403);
+    const privateInbound = next && next.direction === 'inbound' && next.shared !== true;
+    if (!next || !next.token || privateInbound || (ingress && !canTransit(ingress, next))) return reject(socket, 403);
     port = next.localPort; credential = next.token;
     const rest = parsed.route.slice(1);
     path = `/federation/route/${rest.length ? `${rest.join('/')}/` : ''}${ROUTE_DELIMITER}/ws`;