@mmmbuto/nexuscrew 0.8.44 → 0.8.45

package/lib/nodes/tunnel.js

@@ -44,7 +44,7 @@ function assertForwardSpec(node) {
   if (node.keyPath !== undefined && !store.isAbsPath(node.keyPath)) throw new Error('tunnel: keyPath non valido');
   if (node.reversePort !== undefined && !store.isPort(node.reversePort)) throw new Error('tunnel: reversePort non valida');
   if (node.localAppPort !== undefined && !store.isPort(node.localAppPort)) throw new Error('tunnel: localAppPort non valida');
-  if (node.shared === true && node.reversePort !== undefined && !store.isPort(node.localAppPort)) {
+  if (node.shared === true && node.reversePort !== undefined && !node.reversePool && !store.isPort(node.localAppPort)) {
     throw new Error('tunnel: Share richiede localAppPort esplicita');
   }
   if (!store.parseSshTarget(node.ssh)) throw new Error('tunnel: target ssh non valido');
@@ -61,7 +61,7 @@ function buildForwardArgs(node) {
   // 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 ? [
+  const reverse = node.shared === true && node.reversePort !== undefined && !node.reversePool ? [
     '-R', `127.0.0.1:${node.reversePort}:127.0.0.1:${node.localAppPort}`,
   ] : [];
   return SSH_BASE_OPTS.concat(transport, identity ? ['-i', identity] : [], [
@@ -71,6 +71,24 @@ function buildForwardArgs(node) {
   ]);
 }
 
+// A rotatable peer keeps its private -L on the primary supervisor and owns a
+// reverse-only supervisor per generation.  No ControlMaster and no hidden
+// rendezvous connection: every process has its own pidfile, intent and slot.
+function buildReverseArgs(node, { remotePort, targetPort } = {}) {
+  assertForwardSpec({ ...node, shared: false });
+  if (!store.isPort(remotePort) || !store.isPort(targetPort)) throw new Error('tunnel: reverse slot non valida');
+  if (!node.reversePool || !Array.isArray(node.reversePool.slots)
+    || !node.reversePool.slots.some((slot) => slot && slot.port === remotePort)) {
+    throw new Error('tunnel: reverse slot non appartiene al pool');
+  }
+  const transport = node.sshPort === undefined ? [] : ['-p', String(node.sshPort)];
+  const identity = node.identityFile || node.keyPath;
+  return SSH_BASE_OPTS.concat(transport, identity ? ['-i', identity] : [], [
+    '-R', `127.0.0.1:${remotePort}:127.0.0.1:${targetPort}`,
+    node.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.
@@ -106,6 +124,17 @@ function tunnelLogPath(home, name) {
 // runtimes never start this second connection; reconciliation can still stop a
 // stale legacy process left by an older install.
 const REVERSE_NAME = '__rendezvous__';
+const REVERSE_SLOT_NAME_RE = /^reverse-([a-z0-9-]{1,32})-(\d{1,5})-(\d{1,10})$/;
+
+function reverseTunnelName(nodeName, remotePort, generation) {
+  if (!store.NODE_NAME_RE.test(String(nodeName || '')) || !store.isPort(remotePort)
+    || !Number.isSafeInteger(generation) || generation < 1) throw new Error('reverse tunnel name non valido');
+  return `reverse-${nodeName}-${remotePort}-${generation}`;
+}
+
+function isTunnelName(name) {
+  return store.NODE_NAME_RE.test(name) || name === REVERSE_NAME || REVERSE_SLOT_NAME_RE.test(name);
+}
 
 // Reconcile detached supervisors against the authoritative node store. A
 // server crash or an older rollback could leave a valid supervisor pidfile
@@ -120,14 +149,14 @@ function tunnelPidNames(home) {
     return fs.readdirSync(dir, { withFileTypes: true })
       .filter((entry) => entry.isFile() && !entry.isSymbolicLink() && entry.name.endsWith('.pid'))
       .map((entry) => entry.name.slice(0, -4))
-      .filter((name) => store.NODE_NAME_RE.test(name) || name === REVERSE_NAME)
+      .filter((name) => isTunnelName(name))
       .sort();
   } catch (_) { return []; }
 }
 
 function reconcileTunnelSupervisors({ home = os.homedir(), configuredNames = [], stopImpl } = {}) {
   const keep = new Set((Array.isArray(configuredNames) ? configuredNames : [])
-    .filter((name) => store.NODE_NAME_RE.test(String(name || ''))));
+    .filter((name) => isTunnelName(String(name || ''))));
   const stopOne = typeof stopImpl === 'function' ? stopImpl : stopTunnel;
   const result = { kept: [], stopped: [], cleaned: [], failed: [] };
   const safeAbsent = new Set([
@@ -265,6 +294,19 @@ function tunnelStatePath(home, name) {
   return path.join(tunnelDir(home), `${name}.state.json`);
 }
 
+// A reverse sidecar is allowed to be terminated only when we can prove it is
+// this exact NexusCrew generation: same UID, argv/start-time identity and the
+// runId recorded by its own state file.  A stale or foreign pidfile is a
+// diagnostic/quarantine condition, never a reason to signal a PID.
+function tunnelSupervisorAttributable(home, name, meta, impl = {}) {
+  if (!meta || typeof meta.runId !== 'string' || !/^[a-f0-9]{32,64}$/.test(meta.runId)) return false;
+  if (!pidf.isAttributable(meta, impl)) return false;
+  try {
+    const state = JSON.parse((impl.readFileSyncImpl || fs.readFileSync)(tunnelStatePath(home, name), 'utf8'));
+    return state && state.supervisorPid === meta.pid && state.runId === meta.runId;
+  } catch (_) { return false; }
+}
+
 // Stato interrogabile del tunnel: { status: 'up'|'down', pid?, since? }.
 function readTunnelState(home, name) {
   const p = tunnelPidPath(home, name);
@@ -283,7 +325,7 @@ function readTunnelState(home, name) {
       };
     } catch (_) { return null; }
   };
-  if (meta && pidf.isAlive(meta)) {
+  if (meta && pidf.isAttributable(meta)) {
     try {
       const state = JSON.parse(fs.readFileSync(tunnelStatePath(home, name), 'utf8'));
       const transport = typeof state.transport === 'string' ? state.transport : undefined;
@@ -373,6 +415,23 @@ function removeStateIfOwned(home, name, meta) {
   return false;
 }
 
+function writeStartingState(home, name, { pid, runId, transport } = {}) {
+  if (!Number.isFinite(pid) || typeof runId !== 'string' || !/^[a-f0-9]{32,64}$/.test(runId)) return false;
+  const statePath = tunnelStatePath(home, name);
+  const tmp = `${statePath}.tmp.${process.pid}.${runId}`;
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify({
+      status: 'starting', supervisorPid: pid, runId, transport: path.basename(String(transport || 'ssh')), updatedAt: Date.now(), attempt: 0,
+    })}\n`, { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, statePath);
+    return true;
+  } catch (_) {
+    try { fs.unlinkSync(tmp); } catch (_error) {}
+    return false;
+  }
+}
+
 function supervisorExited(pid, timeoutMs = 2500, impl = {}) {
   const deadline = Date.now() + timeoutMs;
   const sleeper = new Int32Array(new SharedArrayBuffer(4));
@@ -425,7 +484,7 @@ function startTunnel(opts) {
   const spawnImpl = opts.spawnImpl || spawn;
   const spawnSyncImpl = opts.spawnSyncImpl || spawnSync;
   const sshBin = opts.sshBin || 'ssh';
-  if (!name) throw new Error('startTunnel: name mancante');
+  if (!isTunnelName(name)) throw new Error('startTunnel: name mancante o non valido');
   if (!Array.isArray(args)) throw new Error('startTunnel: args mancanti');
 
   const pidPath = tunnelPidPath(home, name);
@@ -435,12 +494,18 @@ function startTunnel(opts) {
   const cmd = `${process.execPath} ${supervisorArgs.join(' ')}`;
   const existing = pidf.readPidfile(pidPath);
   if (existing && pidf.isAlive(existing)) {
+    const strictSidecar = REVERSE_SLOT_NAME_RE.test(name);
+    if (strictSidecar && !pidf.isAttributable(existing, opts.pidfileImpl || {})) {
+      return { started: false, reason: 'unattributable existing supervisor', pid: existing.pid };
+    }
+    const stateOwned = !strictSidecar || tunnelSupervisorAttributable(home, name, existing, opts.pidfileImpl || {});
     // 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 };
     }
+    if (!stateOwned) return { started: false, reason: 'unattributable existing supervisor', pid: existing.pid };
     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 };
@@ -449,7 +514,7 @@ function startTunnel(opts) {
     }
     removeStateIfOwned(home, name, oldMeta);
   }
-  pidf.cleanStale(pidPath);
+  if (!existing || !pidf.isAlive(existing)) pidf.cleanStale(pidPath);
 
   const logPath = tunnelLogPath(home, name);
   const statePath = tunnelStatePath(home, name);
@@ -528,6 +593,12 @@ function startTunnel(opts) {
     closeOwnedFd();
     return { started: false, reason: 'pidfile error', error: String(e && e.message || e) };
   }
+  if (!writeStartingState(home, name, { pid, runId, transport: sshBin })) {
+    try { process.kill(pid, 'SIGTERM'); } catch (_) {}
+    cleanupIfOwned();
+    closeOwnedFd();
+    return { started: false, reason: 'statefile error' };
+  }
   // Safe local breadcrumb: argv, host, key paths and credentials are omitted.
   // The detached supervisor appends lifecycle events to the same 0600 file.
   if (Number.isInteger(logFd)) {
@@ -544,6 +615,10 @@ function stopTunnel(opts) {
   if (!name) throw new Error('stopTunnel: name mancante');
   const pidPath = tunnelPidPath(home, name);
   const meta = pidf.readPidfile(pidPath);
+  if (meta && REVERSE_SLOT_NAME_RE.test(name) && pidf.isAlive(meta)
+    && !tunnelSupervisorAttributable(home, name, meta, opts.pidfileImpl || {})) {
+    return { stopped: false, pid: meta.pid, reason: 'unattributable supervisor' };
+  }
   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` };
@@ -572,6 +647,15 @@ function startForward(opts) {
   return startTunnel({ ...opts, sshBin, name: node.name, args });
 }
 
+function startReverseForward(opts) {
+  const node = opts.node;
+  const remotePort = opts.remotePort;
+  const generation = opts.generation;
+  const args = buildReverseArgs(node, { remotePort, targetPort: opts.targetPort });
+  const name = reverseTunnelName(node.name, remotePort, generation);
+  return startTunnel({ ...opts, sshBin: opts.sshBin || 'ssh', name, args });
+}
+
 // 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) {
@@ -586,14 +670,15 @@ function readSshVersion(spawnSyncImpl) {
 
 module.exports = {
   SSH_BASE_OPTS,
-  buildForwardArgs, backoffDelay,
+  buildForwardArgs, buildReverseArgs, backoffDelay,
   tunnelDir, tunnelPidPath, tunnelLogPath, tunnelStatePath, readTunnelState,
   prepareTunnelDir, openTunnelLog,
   tunnelPidNames, reconcileTunnelSupervisors,
   classifySshFailure, readTunnelDiagnostic,
   diagnoseTunnel,
-  removeStateIfOwned, supervisorExited,
-  startTunnel, stopTunnel, restartTunnel, startForward,
-  REVERSE_NAME,
+  removeStateIfOwned, writeStartingState, supervisorExited,
+  tunnelSupervisorAttributable,
+  startTunnel, stopTunnel, restartTunnel, startForward, startReverseForward,
+  REVERSE_NAME, REVERSE_SLOT_NAME_RE, reverseTunnelName, isTunnelName,
   readSshVersion, sshBinaryAvailable,
 };

package/lib/proxy/federation.js

@@ -5,8 +5,10 @@ const net = require('node:net');
 const express = require('express');
 const store = require('../nodes/store.js');
 const topologyCache = require('../nodes/topology-cache.js');
+const reverseRotation = require('../nodes/reverse-rotation.js');
 const { bearerFrom } = require('../auth/middleware.js');
 const { safeEqual } = require('../nodes/peering.js');
+const { probeReverseSlot } = require('../nodes/reverse-slot-proof.js');
 const {
   sanitizeRequestHeaders, sanitizeResponseHeaders, stripLocalTokenQuery,
 } = require('./node-proxy.js');
@@ -289,6 +291,73 @@ async function waitForHealthyPeer(opts = {}) {
   return last || { status: 'down', detail: 'peer non raggiungibile' };
 }
 
+// Verifica locale e limitata alla porta reverse gia' assegnata al peer
+// autenticato. Non accetta una porta dal chiamante: il peer non puo' usarla
+// come scanner e la risposta non rivela quale processo la stia occupando.
+function canListenLoopback(port, createServerImpl = net.createServer) {
+  if (!store.isPort(port)) return Promise.resolve({ available: false, code: 'reverse-port-invalid' });
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    let server;
+    try {
+      server = createServerImpl();
+      server.once('error', (error) => {
+        settle({ available: false, code: error && error.code === 'EADDRINUSE' ? 'reverse-port-in-use' : 'reverse-port-unavailable' });
+      });
+      server.listen({ host: '127.0.0.1', port, exclusive: true }, () => {
+        server.close((error) => settle(error
+          ? { available: false, code: 'reverse-port-unavailable' }
+          : { available: true }));
+      });
+    } catch (_) { settle({ available: false, code: 'reverse-port-unavailable' }); }
+  });
+}
+
+// Preflight best-effort da client verso il proprio hub attraverso il -L gia'
+// autenticato. Un hub precedente che non conosce la route (404), o una rete
+// transitoriamente guasta, conserva il percorso legacy: l'SSH con
+// ExitOnForwardFailure resta l'autorita' finale. Un 409 del nuovo hub invece
+// evita di spegnere il -L privato per tentare un -R gia' noto come conflittuale.
+// Una porta gia' risposta dal peer autenticato stesso e' invece transitabile:
+// e' il caso normale di Share che registra un reverse gia' pronto.
+async function preflightHubReverse({ node, fetchImpl = fetch, timeoutMs = 1500 }) {
+  if (!node || !store.isPort(node.localPort) || !store.validToken(node.token)) {
+    throw new Error('parametri preflight Share non validi');
+  }
+  const ctrl = new AbortController();
+  const budget = Number.isInteger(timeoutMs) ? Math.max(100, Math.min(timeoutMs, 10000)) : 1500;
+  let timer;
+  try {
+    const request = fetchImpl(`http://127.0.0.1:${node.localPort}/federation/reverse-status`, {
+      headers: { authorization: `Bearer ${node.token}` }, signal: ctrl.signal,
+    });
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        ctrl.abort();
+        const error = new Error(`hub reverse preflight timeout (${budget}ms)`);
+        error.code = 'ETIMEDOUT';
+        reject(error);
+      }, budget);
+    });
+    const response = await Promise.race([request, timeout]);
+    if (!response || response.status === 404) return { supported: false };
+    if (response.status === 409) return { supported: true, available: false, code: 'reverse-port-in-use' };
+    if (!response.ok) return { supported: false };
+    let body = null;
+    try { body = await response.json(); } catch (_) { return { supported: false }; }
+    return body && (body.available === true || body.ownedByAuthenticatedPeer === true)
+      ? { supported: true, available: true, ...(body.ownedByAuthenticatedPeer === true ? { ownedByAuthenticatedPeer: true } : {}) }
+      : { supported: false };
+  } catch (_) {
+    return { supported: false };
+  } finally { clearTimeout(timer); }
+}
+
 // 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
@@ -317,6 +386,61 @@ async function notifyHubShare({ node, shared, fetchImpl = fetch, timeoutMs = 500
   } finally { clearTimeout(timer); }
 }
 
+// Internal pool-control calls travel only through the established private -L.
+// Bodies are deliberately index/lease based: neither a caller nor a remote
+// UI can turn them into an arbitrary loopback port probe.
+async function hubPoolRequest({ node, endpoint, body, fetchImpl = fetch, timeoutMs = 5000 }) {
+  if (!node || !store.isPort(node.localPort) || !store.validToken(node.token)
+    || !['verify', 'reserve', 'commit', 'settle', 'abort', 'status'].includes(endpoint)) {
+    throw new Error('parametri reverse pool non validi');
+  }
+  const ctrl = new AbortController();
+  const budget = Number.isInteger(timeoutMs) ? Math.max(100, Math.min(timeoutMs, 30000)) : 5000;
+  const timer = setTimeout(() => ctrl.abort(), budget);
+  try {
+    const method = endpoint === 'status' ? 'GET' : 'POST';
+    const response = await fetchImpl(`http://127.0.0.1:${node.localPort}/federation/reverse-pool/${endpoint}`, {
+      method, signal: ctrl.signal,
+      headers: { authorization: `Bearer ${node.token}`, ...(method === 'POST' ? { 'content-type': 'application/json' } : {}) },
+      ...(method === 'POST' ? { body: JSON.stringify(body || {}) } : {}),
+    });
+    const payload = response && typeof response.json === 'function'
+      ? await response.json().catch(() => ({})) : {};
+    if (!response?.ok) {
+      const error = new Error(`hub reverse pool HTTP ${response?.status || 'unknown'}`);
+      error.status = response?.status; error.code = payload && payload.code;
+      throw error;
+    }
+    return payload || {};
+  } finally { clearTimeout(timer); }
+}
+
+async function verifyHubPoolSlot({ node, slot, generation, fetchImpl = fetch, attempts = 3, delayMs = 200 }) {
+  const total = Number.isInteger(attempts) ? Math.max(1, Math.min(attempts, 6)) : 3;
+  let last = null;
+  for (let attempt = 0; attempt < total; attempt += 1) {
+    try { return await hubPoolRequest({ node, endpoint: 'verify', body: { slot, generation }, fetchImpl }); }
+    catch (error) { last = error; if (attempt < total - 1) await new Promise((resolve) => setTimeout(resolve, delayMs)); }
+  }
+  throw last || new Error('verifica reverse pool fallita');
+}
+
+function reserveHubPoolSlot({ node, slot, fetchImpl = fetch }) {
+  return hubPoolRequest({ node, endpoint: 'reserve', body: { slot }, fetchImpl });
+}
+function commitHubPoolSlot({ node, leaseId, fetchImpl = fetch }) {
+  return hubPoolRequest({ node, endpoint: 'commit', body: { leaseId }, fetchImpl });
+}
+function settleHubPoolSlot({ node, generation, fetchImpl = fetch }) {
+  return hubPoolRequest({ node, endpoint: 'settle', body: { generation }, fetchImpl });
+}
+function abortHubPoolSlot({ node, leaseId, fetchImpl = fetch }) {
+  return hubPoolRequest({ node, endpoint: 'abort', body: { leaseId }, fetchImpl });
+}
+function getHubPoolStatus({ node, fetchImpl = fetch }) {
+  return hubPoolRequest({ node, endpoint: 'status', fetchImpl });
+}
+
 // 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.
@@ -544,6 +668,26 @@ async function collectLocalTopology({
   return { instanceId: live.instanceId, nodes };
 }
 
+async function probeReverseOwner(peer, fetchImpl = fetch) {
+  const pool = peer && peer.reversePool;
+  const active = pool && pool.slots && pool.slots[pool.activeSlot];
+  if (active && peer.token && peer.nodeId) {
+    const proof = await probeReverseSlot({
+      port: active.port, secret: peer.token,
+      expected: { remotePort: active.port, generation: pool.activeGeneration, instanceId: peer.nodeId },
+      fetchImpl,
+    });
+    return proof.owned
+      ? { status: 'healthy', detail: 'reverse slot autenticata', slotProof: true }
+      : { status: 'degraded', detail: 'reverse slot non autenticata', slotProof: true, code: proof.code };
+  }
+  return probeHealth({
+    port: peer.localPort, token: peer.token,
+    expectedInstanceId: peer.nodeId || null,
+    fetchImpl,
+  });
+}
+
 function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly = () => false, version = null, roles = null, hopSecret = null }) {
   const r = express.Router();
   r.use((req, res, next) => {
@@ -561,6 +705,180 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
     res.json({ ok: true, instanceId: (st && st.nodeId) || null, version, readonly: !!readonly(),
       ...(advertisedRoles ? { roles: advertisedRoles } : {}) });
   });
+  // Il client puo' verificare SOLO la reverse port che il pairing gli ha
+  // assegnato. Non e' un endpoint di discovery: nessun parametro, nessuna
+  // identita' del listener e nessun dettaglio SSH vengono esposti.
+  r.get('/reverse-status', async (req, res) => {
+    const result = await canListenLoopback(req.peer.localPort);
+    if (result.available) return res.json({ available: true });
+    // Una porta gia' ascoltata dal peer che ha autenticato QUESTA richiesta
+    // non e' un conflitto: e' il reverse preesistente dello stesso dispositivo.
+    // La health vincola sia token sia instanceId e non restituisce alcun
+    // dettaglio sul processo. Un listener estraneo, legacy o non verificabile
+    // resta invece un 409 senza restart/persist/publish lato client.
+    const health = await probeReverseOwner(req.peer, fetchImpl || fetch);
+    if (health.status === 'healthy') {
+      return res.json({ available: false, ownedByAuthenticatedPeer: true });
+    }
+    return res.status(409).json({
+      available: false,
+      code: result.code === 'reverse-port-in-use' ? 'reverse-port-in-use' : 'reverse-port-unavailable',
+    });
+  });
+  // Pool verification is intentionally slot-indexed, never port-indexed: the
+  // peer can ask the hub to prove only a slot it was assigned.  The hub keeps
+  // the proof result itself; a client cannot simply claim that its SSH key has
+  // three permitlisten grants.
+  r.post('/reverse-pool/verify', express.json({ limit: '1kb' }), async (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: verifica pool bloccata' });
+    const body = req.body || {};
+    if (Object.keys(body).some((key) => !['slot', 'generation'].includes(key))
+      || !Number.isInteger(body.slot) || !Number.isSafeInteger(body.generation) || body.generation < 1) {
+      return res.status(400).json({ error: 'body non valido: attesi slot e generation' });
+    }
+    const peer = req.peer;
+    const current = store.loadStoreStrict(nodesPath);
+    const node = store.getNode(current, peer.name);
+    const pool = node && node.reversePool;
+    const candidate = pool && pool.slots[body.slot];
+    if (!candidate || candidate.generation !== body.generation) {
+      return res.status(409).json({ error: 'slot reverse non assegnata a questa generation', code: 'reverse-slot-stale' });
+    }
+    const proof = await probeReverseSlot({
+      port: candidate.port, secret: node.token,
+      expected: { remotePort: candidate.port, generation: candidate.generation, instanceId: node.nodeId },
+      fetchImpl: fetchImpl || fetch,
+    });
+    const verifiedSlots = proof.owned
+      ? [...new Set([...pool.verifiedSlots, body.slot])].sort((a, b) => a - b)
+      : [...pool.verifiedSlots];
+    const updatedPool = {
+      ...pool,
+      verifiedSlots,
+      verification: verifiedSlots.length === pool.slots.length ? 'verified' : 'unverifiable',
+    };
+    store.atomicWriteStore(nodesPath, store.setNodeReversePool(current, node.name, updatedPool));
+    if (!proof.owned) return res.status(409).json({ error: 'slot reverse non autenticata', code: proof.code });
+    return res.json({ verified: true, slot: body.slot, verification: updatedPool.verification });
+  });
+  // The peer proposes a slot through its still-live -L; the hub alone grants
+  // the lease and generation.  There is no port parameter, scanner or tunnel
+  // termination path here.
+  r.post('/reverse-pool/reserve', express.json({ limit: '1kb' }), (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: rotazione pool bloccata' });
+    const body = req.body || {};
+    if (Object.keys(body).some((key) => key !== 'slot') || !Number.isInteger(body.slot)) {
+      return res.status(400).json({ error: 'body non valido: atteso slot' });
+    }
+    try {
+      const current = store.loadStoreStrict(nodesPath);
+      const node = store.getNode(current, req.peer.name);
+      let pool = node && node.reversePool;
+      // A crashed peer may leave a reservation behind. Its lease has no
+      // privilege after expiry, so clear it before considering the requested
+      // slot; this is state cleanup only, never SSH/process cleanup.
+      if (pool?.rotation?.phase === 'prepared' && Date.now() > pool.rotation.expiresAt) {
+        pool = reverseRotation.abortPrepared(pool);
+      }
+      const prepared = pool && reverseRotation.prepareRotation(pool, { slot: body.slot });
+      if (!prepared) return res.status(409).json({ error: 'pool non verificato o slot non disponibile', code: 'reverse-rotation-not-ready' });
+      store.atomicWriteStore(nodesPath, store.setNodeReversePool(current, node.name, prepared));
+      return res.json({ leaseId: prepared.rotation.leaseId, slot: prepared.rotation.slot,
+        generation: prepared.rotation.generation, expiresAt: prepared.rotation.expiresAt });
+    } catch (error) { return res.status(500).json({ error: String(error.message || error) }); }
+  });
+  r.post('/reverse-pool/abort', express.json({ limit: '1kb' }), (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: rotazione pool bloccata' });
+    const body = req.body || {};
+    if (Object.keys(body).some((key) => key !== 'leaseId') || typeof body.leaseId !== 'string') {
+      return res.status(400).json({ error: 'body non valido: atteso leaseId' });
+    }
+    try {
+      const current = store.loadStoreStrict(nodesPath);
+      const node = store.getNode(current, req.peer.name);
+      const pool = node && node.reversePool;
+      if (!pool || pool.rotation?.phase !== 'prepared' || pool.rotation.leaseId !== body.leaseId) {
+        return res.status(409).json({ error: 'lease reverse non valida o gia conclusa', code: 'reverse-lease-stale' });
+      }
+      const aborted = reverseRotation.abortPrepared(pool);
+      if (!aborted) return res.status(409).json({ error: 'lease reverse non annullabile', code: 'reverse-lease-stale' });
+      store.atomicWriteStore(nodesPath, store.setNodeReversePool(current, node.name, aborted));
+      return res.json({ aborted: true });
+    } catch (error) { return res.status(500).json({ error: String(error.message || error) }); }
+  });
+  r.post('/reverse-pool/commit', express.json({ limit: '1kb' }), async (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: rotazione pool bloccata' });
+    const body = req.body || {};
+    if (Object.keys(body).some((key) => key !== 'leaseId') || typeof body.leaseId !== 'string') {
+      return res.status(400).json({ error: 'body non valido: atteso leaseId' });
+    }
+    try {
+      const current = store.loadStoreStrict(nodesPath);
+      const node = store.getNode(current, req.peer.name);
+      const prepared = node && node.reversePool;
+      const rotation = prepared && prepared.rotation;
+      if (!rotation || rotation.phase !== 'prepared' || rotation.leaseId !== body.leaseId) {
+        return res.status(409).json({ error: 'lease reverse non valida o scaduta', code: 'reverse-lease-stale' });
+      }
+      const slot = prepared.slots[rotation.slot];
+      let proof = { owned: false, code: 'reverse-slot-proof-unavailable' };
+      for (let attempt = 0; attempt < 3; attempt += 1) {
+        proof = await probeReverseSlot({
+          port: slot.port, secret: node.token,
+          expected: { remotePort: slot.port, generation: rotation.generation, instanceId: node.nodeId },
+          fetchImpl: fetchImpl || fetch,
+        });
+        if (proof.owned || attempt === 2) break;
+        await new Promise((resolve) => setTimeout(resolve, 200));
+      }
+      if (!proof.owned) {
+        const abandoned = reverseRotation.quarantineSlot(prepared, { slot: rotation.slot }) || prepared;
+        const invalidated = { ...abandoned, verification: 'invalidated', verifiedSlots: [] };
+        store.atomicWriteStore(nodesPath, store.setNodeReversePool(current, node.name, invalidated));
+        return res.status(409).json({ error: 'candidate reverse non autenticata', code: proof.code });
+      }
+      const committed = reverseRotation.commitRotation(prepared, { leaseId: body.leaseId });
+      if (!committed) return res.status(409).json({ error: 'lease reverse scaduta', code: 'reverse-lease-expired' });
+      // The hub routes the peer through the newly proven slot immediately. The
+      // old slot is only draining and is never reassigned to another peer.
+      const updated = store.updateNode(current, node.name, {
+        localPort: committed.slots[committed.activeSlot].port,
+        reversePool: committed,
+      });
+      store.atomicWriteStore(nodesPath, updated);
+      return res.json({ committed: true, slot: committed.activeSlot, generation: committed.activeGeneration,
+        graceUntil: committed.rotation.graceUntil });
+    } catch (error) { return res.status(500).json({ error: String(error.message || error) }); }
+  });
+  r.post('/reverse-pool/settle', express.json({ limit: '1kb' }), (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: rotazione pool bloccata' });
+    const body = req.body || {};
+    if (Object.keys(body).some((key) => key !== 'generation') || !Number.isSafeInteger(body.generation) || body.generation < 1) {
+      return res.status(400).json({ error: 'body non valido: atteso generation' });
+    }
+    try {
+      const current = store.loadStoreStrict(nodesPath);
+      const node = store.getNode(current, req.peer.name);
+      if (!node?.reversePool || node.reversePool.activeGeneration !== body.generation) {
+        return res.status(409).json({ error: 'generation reverse non corrente', code: 'reverse-generation-stale' });
+      }
+      const settled = reverseRotation.settleGrace(node.reversePool);
+      if (!settled) return res.status(409).json({ error: 'grace reverse non conclusa', code: 'reverse-grace-pending' });
+      store.atomicWriteStore(nodesPath, store.setNodeReversePool(current, node.name, settled));
+      return res.json({ settled: true, generation: settled.activeGeneration });
+    } catch (error) { return res.status(500).json({ error: String(error.message || error) }); }
+  });
+  r.get('/reverse-pool/status', (req, res) => {
+    try {
+      const current = store.loadStoreStrict(nodesPath);
+      const node = store.getNode(current, req.peer.name);
+      if (!node?.reversePool) return res.status(409).json({ error: 'pool reverse non configurato', code: 'reverse-pool-missing' });
+      // This travels only on the peer's authenticated private -L. It includes
+      // no bearer material and lets a restarted peer converge on the hub's
+      // committed generation instead of reopening an obsolete slot.
+      return res.json({ pool: node.reversePool });
+    } catch (error) { return res.status(500).json({ error: String(error.message || error) }); }
+  });
   r.get('/topology', async (req, res) => {
     const ttl = Math.max(0, Math.min(MAX_HOPS, Number(req.query.ttl) || MAX_HOPS));
     const visited = String(req.query.visited || '').split(',');
@@ -577,14 +895,23 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
     }
     try {
       if (body.shared) {
-        const health = await waitForHealthyPeer({
-          port: req.peer.localPort,
-          token: req.peer.token,
-          expectedInstanceId: req.peer.nodeId || null,
-          fetchImpl: fetchImpl || fetch,
-          attempts: 6,
-          delayMs: 200,
-        });
+        let health;
+        if (req.peer.reversePool) {
+          for (let attempt = 0; attempt < 6; attempt += 1) {
+            health = await probeReverseOwner(req.peer, fetchImpl || fetch);
+            if (health.status === 'healthy') break;
+            if (attempt < 5) await new Promise((resolve) => setTimeout(resolve, 200));
+          }
+        } else {
+          health = await waitForHealthyPeer({
+            port: req.peer.localPort,
+            token: req.peer.token,
+            expectedInstanceId: req.peer.nodeId || null,
+            fetchImpl: fetchImpl || fetch,
+            attempts: 6,
+            delayMs: 200,
+          });
+        }
         if (health.status !== 'healthy') {
           return res.status(409).json({
             error: 'canale share non raggiungibile',
@@ -656,5 +983,6 @@ module.exports = {
   MAX_HOPS, ROUTE_DELIMITER, TOPOLOGY_PEER_TIMEOUT_MS,
   peerFromToken, peerAllows, canTransit, parseRoute, knownResource, allowedResource, allowedQuery, readonlyBlocksFederated,
   collectTopology, collectTopologyDetailed, collectLocalTopology, peerRouter, localRouter, forwardUpgrade,
-  probeHealth, waitForHealthyPeer, notifyHubShare, reconcilePeerShare, runShareRevokeBoot,
+  probeHealth, waitForHealthyPeer, canListenLoopback, preflightHubReverse, notifyHubShare, reconcilePeerShare, runShareRevokeBoot, probeReverseOwner,
+  hubPoolRequest, verifyHubPoolSlot, reserveHubPoolSlot, commitHubPoolSlot, settleHubPoolSlot, abortHubPoolSlot, getHubPoolStatus,
 };