@mmmbuto/nexuscrew 0.8.44 → 0.8.45

package/lib/nodes/reverse-rotation.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// Pure state transitions for the three-slot reverse pool.  SSH side effects
+// live outside this module: callers reserve, prove the candidate, commit on
+// the hub, then let the peer drain the old sidecar.  Keeping the transitions
+// pure makes crash/replay cases explicit and testable.
+const crypto = require('node:crypto');
+
+const LEASE_MS = 60_000;
+const GRACE_MS = 30_000;
+
+function clone(pool) { return JSON.parse(JSON.stringify(pool)); }
+function validSlot(pool, slot) { return Number.isInteger(slot) && pool && Array.isArray(pool.slots) && slot >= 0 && slot < pool.slots.length; }
+
+function nextReadySlot(pool) {
+  if (!pool || !Array.isArray(pool.slots)) return null;
+  return pool.slots.findIndex((slot, index) => index !== pool.activeSlot && slot && slot.state === 'ready');
+}
+
+function prepareRotation(pool, { slot = nextReadySlot(pool), now = Date.now(), leaseId = crypto.randomBytes(16).toString('hex'), leaseMs = LEASE_MS } = {}) {
+  if (!pool || pool.verification !== 'verified' || !Array.isArray(pool.verifiedSlots)
+    || pool.verifiedSlots.length !== pool.slots.length || pool.rotation?.phase !== 'active' || !validSlot(pool, slot)
+    || pool.slots[slot].state !== 'ready' || !Number.isSafeInteger(now) || !Number.isSafeInteger(leaseMs) || leaseMs < 1
+    || typeof leaseId !== 'string' || !/^[a-f0-9]{32,64}$/.test(leaseId)) return null;
+  const next = clone(pool);
+  const generation = next.activeGeneration + 1;
+  next.slots[slot] = { ...next.slots[slot], state: 'reserved', generation };
+  next.rotation = { phase: 'prepared', generation, slot, leaseId, expiresAt: now + leaseMs };
+  return next;
+}
+
+function abortPrepared(pool, { now = Date.now() } = {}) {
+  if (!pool || pool.rotation?.phase !== 'prepared' || !Number.isSafeInteger(now)) return null;
+  const next = clone(pool);
+  const slot = next.rotation.slot;
+  next.slots[slot] = { ...next.slots[slot], state: 'ready' };
+  next.rotation = { phase: 'active', generation: next.activeGeneration, slot: next.activeSlot };
+  return next;
+}
+
+function commitRotation(pool, { leaseId, now = Date.now(), graceMs = GRACE_MS } = {}) {
+  if (!pool || pool.rotation?.phase !== 'prepared' || typeof leaseId !== 'string' || leaseId !== pool.rotation.leaseId
+    || !Number.isSafeInteger(now) || now > pool.rotation.expiresAt || !Number.isSafeInteger(graceMs) || graceMs < 0) return null;
+  const next = clone(pool);
+  const oldSlot = next.activeSlot;
+  const oldGeneration = next.activeGeneration;
+  const slot = next.rotation.slot;
+  next.slots[oldSlot] = { ...next.slots[oldSlot], state: 'draining' };
+  next.slots[slot] = { ...next.slots[slot], state: 'active', generation: next.rotation.generation };
+  next.activeSlot = slot;
+  next.activeGeneration = next.rotation.generation;
+  next.rotation = {
+    phase: 'switched', generation: next.activeGeneration, slot,
+    oldSlot, oldGeneration, graceUntil: now + graceMs,
+  };
+  return next;
+}
+
+function settleGrace(pool, { now = Date.now() } = {}) {
+  if (!pool || pool.rotation?.phase !== 'switched' || !Number.isSafeInteger(now) || now < pool.rotation.graceUntil) return null;
+  const next = clone(pool);
+  const oldSlot = next.rotation.oldSlot;
+  if (next.slots[oldSlot]?.state === 'draining') next.slots[oldSlot] = { ...next.slots[oldSlot], state: 'ready' };
+  next.rotation = { phase: 'active', generation: next.activeGeneration, slot: next.activeSlot };
+  return next;
+}
+
+function quarantineSlot(pool, { slot, now = Date.now() } = {}) {
+  if (!pool || !validSlot(pool, slot) || slot === pool.activeSlot || !Number.isSafeInteger(now)) return null;
+  const next = clone(pool);
+  next.slots[slot] = { ...next.slots[slot], state: 'quarantined' };
+  if (next.rotation?.phase === 'prepared' && next.rotation.slot === slot) {
+    next.rotation = { phase: 'abandoned', generation: next.activeGeneration, slot: next.activeSlot };
+  }
+  return next;
+}
+
+module.exports = { LEASE_MS, GRACE_MS, nextReadySlot, prepareRotation, abortPrepared, commitRotation, settleGrace, quarantineSlot };

package/lib/nodes/reverse-slot-listeners.js

@@ -0,0 +1,80 @@
+'use strict';
+// Per-slot loopback listeners owned by this NexusCrew process.  They run the
+// same Express application as the primary listener, but expose a distinct TCP
+// destination to every -R.  That physical distinction is what makes an
+// old-port -> new-port relay unable to obtain a slot MAC.
+const http = require('node:http');
+const proof = require('./reverse-slot-proof.js');
+
+function listen(server, options) {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.once('listening', () => {
+      server.removeListener('error', reject);
+      resolve(server.address());
+    });
+    server.listen(options);
+  });
+}
+
+function close(server) {
+  return new Promise((resolve) => {
+    try { server.close(() => resolve()); } catch (_) { resolve(); }
+  });
+}
+
+function createReverseSlotListeners({ app, createServerImpl = http.createServer, diagnostics } = {}) {
+  if (typeof app !== 'function') throw new Error('reverse slot listeners richiede app HTTP');
+  const listeners = new Map(); // local target port -> owned server + immutable expected tuple
+
+  async function open({ nodeName, remotePort, generation, instanceId, secret }) {
+    if (typeof nodeName !== 'string' || !proof.newProbe({ remotePort, generation, instanceId }, () => Buffer.alloc(24))) {
+      throw new Error('reverse slot listener spec non valida');
+    }
+    if (typeof secret !== 'string' || !secret) throw new Error('reverse slot listener credential mancante');
+    const server = createServerImpl(app);
+    let address;
+    try { address = await listen(server, { host: '127.0.0.1', port: 0, exclusive: true }); }
+    catch (error) { try { server.close(); } catch (_) {} throw error; }
+    const localPort = address && address.port;
+    if (!Number.isInteger(localPort)) { await close(server); throw new Error('reverse slot listener non ha una porta locale'); }
+    listeners.set(localPort, {
+      server, nodeName, secret,
+      expected: { remotePort, generation, instanceId },
+    });
+    diagnostics?.record?.('info', 'reverse-pool', 'REVERSE_SLOT_LISTENER_READY', 'Reverse slot listener ready', {
+      node: nodeName, remotePort, generation,
+    });
+    return { localPort, remotePort, generation };
+  }
+
+  async function closePort(localPort) {
+    const entry = listeners.get(localPort);
+    if (!entry) return false;
+    listeners.delete(localPort);
+    await close(entry.server);
+    return true;
+  }
+
+  async function closeAll() {
+    await Promise.all([...listeners.keys()].map(closePort));
+  }
+
+  function respond(req, res) {
+    const localPort = req && req.socket && req.socket.localPort;
+    const entry = listeners.get(localPort);
+    if (!entry) return false;
+    const body = req.body || {};
+    const response = proof.respondSlotProof({ secret: entry.secret, expected: entry.expected, request: body });
+    if (!response.ok) {
+      res.status(409).json({ error: 'reverse slot proof non valida', code: response.code });
+    } else {
+      res.json(response);
+    }
+    return true;
+  }
+
+  return { open, closePort, closeAll, respond, size: () => listeners.size };
+}
+
+module.exports = { createReverseSlotListeners };

package/lib/nodes/reverse-slot-proof.js

@@ -0,0 +1,108 @@
+'use strict';
+// No-bearer ownership proof for one reverse slot.  The local listener knows
+// which remote -R slot targets it; a request relayed from another slot therefore
+// reaches a listener with different expectedPort and is rejected before a MAC
+// is emitted.  The hub sends only public challenge material to an untrusted
+// loopback listener, never the peer credential itself.
+const crypto = require('node:crypto');
+
+const PROBE_ID_RE = /^[A-Za-z0-9_-]{16,128}$/;
+const NONCE_RE = /^[A-Za-z0-9_-]{16,128}$/;
+const INSTANCE_RE = /^[a-f0-9]{16,64}$/;
+
+function isPort(port) { return Number.isInteger(port) && port >= 1 && port <= 65535; }
+function safeEqual(a, b) {
+  const aa = Buffer.from(String(a || ''));
+  const bb = Buffer.from(String(b || ''));
+  return aa.length === bb.length && crypto.timingSafeEqual(aa, bb);
+}
+
+function parseTuple(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some((key) => !['probeId', 'nonce', 'dialedPort', 'generation', 'instanceId'].includes(key))
+    || !PROBE_ID_RE.test(String(value.probeId || '')) || !NONCE_RE.test(String(value.nonce || ''))
+    || !isPort(value.dialedPort) || !Number.isSafeInteger(value.generation) || value.generation < 1
+    || !INSTANCE_RE.test(String(value.instanceId || ''))) return null;
+  return {
+    probeId: value.probeId, nonce: value.nonce, dialedPort: value.dialedPort,
+    generation: value.generation, instanceId: value.instanceId,
+  };
+}
+
+function canonicalTuple(tuple) {
+  const parsed = parseTuple(tuple);
+  return parsed ? `nexuscrew-reverse-slot-proof/v1\0${JSON.stringify(parsed)}` : null;
+}
+
+function signSlotProof(secret, tuple) {
+  const canonical = canonicalTuple(tuple);
+  if (typeof secret !== 'string' || !secret || !canonical) return null;
+  return crypto.createHmac('sha256', secret).update(canonical).digest('base64url');
+}
+
+function expectedTuple(expected, request) {
+  const tuple = parseTuple(request && {
+    probeId: request.probeId,
+    nonce: request.nonce,
+    dialedPort: request.dialedPort,
+    generation: request.generation,
+    instanceId: request.instanceId,
+  });
+  if (!tuple || !expected || tuple.dialedPort !== expected.remotePort
+    || tuple.generation !== expected.generation || tuple.instanceId !== expected.instanceId) return null;
+  return tuple;
+}
+
+function respondSlotProof({ secret, expected, request }) {
+  const tuple = expectedTuple(expected, request);
+  const mac = tuple && signSlotProof(secret, tuple);
+  return mac ? { ok: true, ...tuple, mac } : { ok: false, code: 'reverse-slot-proof-mismatch' };
+}
+
+function verifySlotProof({ secret, expected, challenge, response }) {
+  const issued = expectedTuple(expected, challenge);
+  const tuple = expectedTuple(expected, response);
+  const issuedCanonical = canonicalTuple(issued);
+  const responseCanonical = canonicalTuple(tuple);
+  if (!issued || !tuple || !issuedCanonical || !responseCanonical
+    || !safeEqual(issuedCanonical, responseCanonical)
+    || !response || typeof response.mac !== 'string') {
+    return { owned: false, code: 'reverse-slot-proof-mismatch' };
+  }
+  const expectedMac = signSlotProof(secret, tuple);
+  if (!expectedMac || !safeEqual(expectedMac, response.mac)) return { owned: false, code: 'reverse-slot-proof-invalid' };
+  return { owned: true, code: 'reverse-slot-owned', tuple };
+}
+
+function newProbe(expected, randomBytes = crypto.randomBytes) {
+  if (!expected || !isPort(expected.remotePort) || !Number.isSafeInteger(expected.generation)
+    || expected.generation < 1 || !INSTANCE_RE.test(String(expected.instanceId || ''))) return null;
+  return {
+    probeId: randomBytes(18).toString('base64url'),
+    nonce: randomBytes(24).toString('base64url'),
+    dialedPort: expected.remotePort,
+    generation: expected.generation,
+    instanceId: expected.instanceId,
+  };
+}
+
+async function probeReverseSlot({ port, secret, expected, fetchImpl = fetch, timeoutMs = 1500, randomBytes } = {}) {
+  if (!isPort(port) || typeof secret !== 'string' || !secret) return { owned: false, code: 'reverse-slot-proof-invalid-input' };
+  const probe = newProbe(expected, randomBytes);
+  if (!probe) return { owned: false, code: 'reverse-slot-proof-invalid-input' };
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), Math.max(1, Math.min(timeoutMs, 5000)));
+  try {
+    const response = await fetchImpl(`http://127.0.0.1:${port}/reverse-slot-proof`, {
+      method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(probe), signal: ctrl.signal,
+    });
+    if (!response || response.status !== 200) return { owned: false, code: 'reverse-slot-proof-unavailable' };
+    const body = await response.json().catch(() => null);
+    return verifySlotProof({ secret, expected, challenge: probe, response: body });
+  } catch (_) { return { owned: false, code: 'reverse-slot-proof-unavailable' }; }
+  finally { clearTimeout(timer); }
+}
+
+module.exports = {
+  parseTuple, canonicalTuple, signSlotProof, respondSlotProof, verifySlotProof, newProbe, probeReverseSlot,
+};

package/lib/nodes/store.js

@@ -17,8 +17,10 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const reversePool = require('./reverse-pool.js');
 
-const SCHEMA_VERSION = 2;
+const SCHEMA_VERSION = 3;
+const PREVIOUS_SCHEMA_VERSION = 2;
 const LEGACY_SCHEMA_VERSION = 1;
 const MAX_NODES = 64;
 const MAX_TOKEN_LEN = 4096;
@@ -105,8 +107,89 @@ const LABEL_MAX = 64;
 const NODE_KEYS = new Set([
   'name', 'ssh', 'sshPort', 'remotePort', 'localPort', 'keyPath', 'identityFile',
   'roles', 'rolesKnown', 'token', 'acceptToken', 'nodeId', 'transport', 'autostart', 'visibility', 'selected',
-  'direction', 'reversePort', 'shared', 'label',
+  'direction', 'reversePort', 'shared', 'label', 'reversePool',
 ]);
+
+const REVERSE_POOL_SLOT_STATES = new Set(['active', 'ready', 'reserved', 'draining', 'quarantined', 'retired']);
+const REVERSE_POOL_VERIFICATIONS = new Set(['verified', 'unverifiable', 'missing', 'invalidated']);
+const REVERSE_POOL_PHASES = new Set(['active', 'prepared', 'switched', 'abandoned']);
+
+function parseReversePool(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const keys = Object.keys(value);
+  if (keys.some((key) => !['base', 'slots', 'activeSlot', 'activeGeneration', 'verification', 'verifiedSlots', 'rotation', 'lastAutoRotationAt'].includes(key))) return null;
+  const ports = reversePool.reversePoolForBase(value.base);
+  if (!ports || !Array.isArray(value.slots) || value.slots.length !== ports.length
+    || !Number.isInteger(value.activeSlot) || value.activeSlot < 0 || value.activeSlot >= ports.length
+    || !Number.isSafeInteger(value.activeGeneration) || value.activeGeneration < 1
+    || !REVERSE_POOL_VERIFICATIONS.has(value.verification)) return null;
+  if (value.lastAutoRotationAt !== undefined && (!Number.isSafeInteger(value.lastAutoRotationAt) || value.lastAutoRotationAt < 0)) return null;
+  const verifiedSlots = value.verifiedSlots === undefined ? [] : value.verifiedSlots;
+  if (!Array.isArray(verifiedSlots) || verifiedSlots.length > ports.length
+    || new Set(verifiedSlots).size !== verifiedSlots.length
+    || verifiedSlots.some((slot) => !Number.isInteger(slot) || slot < 0 || slot >= ports.length)) return null;
+  if (value.verification === 'verified' && verifiedSlots.length !== ports.length) return null;
+  const slots = value.slots.map((slot, index) => {
+    if (!slot || typeof slot !== 'object' || Array.isArray(slot) || Object.keys(slot).some((key) => !['port', 'state', 'generation'].includes(key))) return null;
+    if (slot.port !== ports[index] || !REVERSE_POOL_SLOT_STATES.has(slot.state)
+      || !Number.isSafeInteger(slot.generation) || slot.generation < 1) return null;
+    return { port: slot.port, state: slot.state, generation: slot.generation };
+  });
+  if (slots.some((slot) => !slot) || slots[value.activeSlot].state !== 'active'
+    || slots[value.activeSlot].generation !== value.activeGeneration) return null;
+  let rotation = { phase: 'active', generation: value.activeGeneration, slot: value.activeSlot };
+  if (value.rotation !== undefined) {
+    const r = value.rotation;
+    if (!r || typeof r !== 'object' || Array.isArray(r)
+      || Object.keys(r).some((key) => !['phase', 'generation', 'slot', 'leaseId', 'expiresAt', 'oldSlot', 'oldGeneration', 'graceUntil'].includes(key))
+      || !REVERSE_POOL_PHASES.has(r.phase) || !Number.isSafeInteger(r.generation) || r.generation < 1
+      || !Number.isInteger(r.slot) || r.slot < 0 || r.slot >= ports.length) return null;
+    if (r.phase === 'prepared') {
+      if (typeof r.leaseId !== 'string' || !/^[a-f0-9]{32,64}$/.test(r.leaseId)
+        || !Number.isSafeInteger(r.expiresAt) || r.expiresAt < 0) return null;
+    } else if (r.phase === 'switched') {
+      if (!Number.isInteger(r.oldSlot) || r.oldSlot < 0 || r.oldSlot >= ports.length || r.oldSlot === r.slot
+        || !Number.isSafeInteger(r.oldGeneration) || r.oldGeneration < 1
+        || !Number.isSafeInteger(r.graceUntil) || r.graceUntil < 0
+        || r.leaseId !== undefined || r.expiresAt !== undefined) return null;
+    } else if (r.leaseId !== undefined || r.expiresAt !== undefined || r.oldSlot !== undefined
+      || r.oldGeneration !== undefined || r.graceUntil !== undefined) return null;
+    rotation = { phase: r.phase, generation: r.generation, slot: r.slot,
+      ...(r.phase === 'prepared' ? { leaseId: r.leaseId, expiresAt: r.expiresAt } : {}),
+      ...(r.phase === 'switched' ? { oldSlot: r.oldSlot, oldGeneration: r.oldGeneration, graceUntil: r.graceUntil } : {}) };
+  }
+  return {
+    base: value.base,
+    slots,
+    activeSlot: value.activeSlot,
+    activeGeneration: value.activeGeneration,
+    verification: value.verification,
+    verifiedSlots: [...verifiedSlots].sort((a, b) => a - b),
+    rotation,
+    ...(value.lastAutoRotationAt === undefined ? {} : { lastAutoRotationAt: value.lastAutoRotationAt }),
+  };
+}
+
+function parseReversePoolAnchor(value) {
+  return reversePool.parseAnchor(value);
+}
+
+function reversePoolDefault(base, { verification = 'unverifiable', generation = 1 } = {}) {
+  const ports = reversePool.reversePoolForBase(base);
+  if (!ports || !REVERSE_POOL_VERIFICATIONS.has(verification) || !Number.isSafeInteger(generation) || generation < 1) {
+    throw new Error('reverse pool non valida');
+  }
+  return {
+    base,
+    slots: ports.map((port, index) => ({ port, state: index === 0 ? 'active' : 'ready', generation })),
+    activeSlot: 0,
+    activeGeneration: generation,
+    verification,
+    verifiedSlots: verification === 'verified' ? ports.map((_, index) => index) : [],
+    rotation: { phase: 'active', generation, slot: 0 },
+  };
+}
+
 function parseNode(n, schemaVersion = SCHEMA_VERSION) {
   if (!n || typeof n !== 'object' || Array.isArray(n)) return null;
   for (const k of Object.keys(n)) { if (!NODE_KEYS.has(k)) return null; } // schema chiuso
@@ -170,6 +253,12 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
     if (!isPort(n.reversePort)) return null;
     out.reversePort = n.reversePort;
   }
+  if (n.reversePool !== undefined) {
+    if (schemaVersion < SCHEMA_VERSION) return null;
+    const parsedPool = parseReversePool(n.reversePool);
+    if (!parsedPool) return null;
+    out.reversePool = parsedPool;
+  }
   if (n.selected !== undefined) {
     if (!Array.isArray(n.selected) || n.selected.length > MAX_NODES) return null;
     const selected = [...new Set(n.selected)];
@@ -222,7 +311,11 @@ function parseStore(raw) {
       return null;
     }
 
-    if (d.schemaVersion !== SCHEMA_VERSION && d.schemaVersion !== LEGACY_SCHEMA_VERSION) return null;
+    if (![SCHEMA_VERSION, PREVIOUS_SCHEMA_VERSION, LEGACY_SCHEMA_VERSION].includes(d.schemaVersion)) return null;
+    const rootKeys = d.schemaVersion === SCHEMA_VERSION
+      ? new Set(['schemaVersion', 'nodeId', 'nodes', 'rendezvous', 'reversePoolAnchor', 'reversePoolLedgerInitialized'])
+      : new Set(['schemaVersion', 'nodeId', 'nodes', 'rendezvous']);
+    if (Object.keys(d).some((key) => !rootKeys.has(key))) return null;
     if (typeof d.nodeId !== 'string' || !NODE_ID_RE.test(d.nodeId)) return null;
     if (!Array.isArray(d.nodes) || d.nodes.length > MAX_NODES) return null;
 
@@ -252,6 +345,24 @@ function parseStore(raw) {
       if (!rdv) return null;
       out.rendezvous = rdv;
     }
+    if (d.schemaVersion === SCHEMA_VERSION) {
+      // This marker distinguishes a fresh v3 peer (which may have received a
+      // pool from another hub) from a hub that has once owned allocations. If
+      // the latter loses its anchor, it must not silently start a new ledger.
+      if (d.reversePoolLedgerInitialized !== undefined && d.reversePoolLedgerInitialized !== true) return null;
+      if (d.reversePoolLedgerInitialized === true) out.reversePoolLedgerInitialized = true;
+      if (d.reversePoolAnchor !== undefined) {
+        if (d.reversePoolLedgerInitialized !== true) return null;
+        const anchor = parseReversePoolAnchor(d.reversePoolAnchor);
+        if (!anchor) return null;
+        out.reversePoolAnchor = anchor;
+      }
+      // The allocator and monotonic ledger live on the hub, which owns inbound
+      // peers.  An outbound peer persists the pool negotiated by that hub but
+      // must not invent a second local allocation ledger for it.
+      if (nodes.some((node) => node.direction === 'inbound' && node.reversePool)
+        && (!out.reversePoolAnchor || d.reversePoolLedgerInitialized !== true)) return null;
+    }
     return out;
   } catch (_) {
     return null; // fail-closed: qualunque eccezione inattesa -> null, MAI throw
@@ -366,8 +477,12 @@ function getNode(store, name) {
   return store.nodes.find((n) => n.name === name) || null;
 }
 
+function mutationSchemaVersion(store) {
+  return store && store.schemaVersion === SCHEMA_VERSION ? SCHEMA_VERSION : PREVIOUS_SCHEMA_VERSION;
+}
+
 function addNode(store, entry) {
-  const node = parseNode(entry, SCHEMA_VERSION);
+  const node = parseNode(entry, mutationSchemaVersion(store));
   if (!node) throw new Error('nodo non valido (schema strict): controlla name/ssh/remotePort/localPort');
   if (store.nodes.some((n) => n.name === node.name)) {
     throw new Error(`nodo duplicato: name "${node.name}" gia' presente`);
@@ -381,7 +496,7 @@ function addNode(store, entry) {
       throw new Error(`nodo duplicato: nodeId "${node.nodeId}" gia' presente`);
     }
   }
-  return { ...store, schemaVersion: SCHEMA_VERSION, nodes: store.nodes.concat([node]) };
+  return { ...store, schemaVersion: mutationSchemaVersion(store), nodes: store.nodes.concat([node]) };
 }
 
 function removeNode(store, name) {
@@ -389,7 +504,7 @@ function removeNode(store, name) {
   if (idx < 0) throw new Error(`nodo sconosciuto: "${name}"`);
   const nodes = store.nodes.slice();
   nodes.splice(idx, 1);
-  return { ...store, schemaVersion: SCHEMA_VERSION, nodes };
+  return { ...store, schemaVersion: mutationSchemaVersion(store), nodes };
 }
 
 function setNodeToken(store, name, token) {
@@ -398,17 +513,47 @@ function setNodeToken(store, name, token) {
   if (!validToken(token)) throw new Error('token non valido (vuoto, multilinea o troppo lungo)');
   const nodes = store.nodes.slice();
   nodes[idx] = { ...nodes[idx], token };
-  return { ...store, schemaVersion: SCHEMA_VERSION, nodes };
+  return { ...store, schemaVersion: mutationSchemaVersion(store), nodes };
 }
 
 function updateNode(store, name, patch) {
   const idx = store.nodes.findIndex((n) => n.name === name);
   if (idx < 0) throw new Error(`nodo sconosciuto: "${name}"`);
-  const parsed = parseNode({ ...store.nodes[idx], ...patch }, SCHEMA_VERSION);
+  const parsed = parseNode({ ...store.nodes[idx], ...patch }, mutationSchemaVersion(store));
   if (!parsed) throw new Error('aggiornamento nodo non valido');
   const nodes = store.nodes.slice();
   nodes[idx] = parsed;
-  return { ...store, schemaVersion: SCHEMA_VERSION, nodes };
+  return { ...store, schemaVersion: mutationSchemaVersion(store), nodes };
+}
+
+// The upgrade is explicit: normal legacy pairing remains schema v2 and keeps
+// working with a previous NexusCrew binary.  Enabling rotation is the only
+// path that writes the v3 anchor and therefore requires both peers to support
+// the capability.
+function upgradeToReversePoolSchema(store, anchor = undefined) {
+  const current = parseStore(store);
+  if (!current) throw new Error('nodes store non valido');
+  const parsedAnchor = anchor === undefined ? null : parseReversePoolAnchor(anchor);
+  if (anchor !== undefined && !parsedAnchor) throw new Error('reverse pool anchor non valida');
+  const next = {
+    ...current,
+    schemaVersion: SCHEMA_VERSION,
+    ...(parsedAnchor ? { reversePoolLedgerInitialized: true, reversePoolAnchor: parsedAnchor } : {}),
+  };
+  const parsed = parseStore(next);
+  if (!parsed) throw new Error('upgrade reverse pool non valido');
+  return parsed;
+}
+
+function setNodeReversePool(store, name, value) {
+  const current = store && getNode(store, name);
+  if (!store || store.schemaVersion !== SCHEMA_VERSION || !current) {
+    throw new Error('reverse pool richiede schema v3');
+  }
+  if (current.direction === 'inbound' && !parseReversePoolAnchor(store.reversePoolAnchor)) {
+    throw new Error('reverse pool inbound richiede anchor valida');
+  }
+  return updateNode(store, name, { reversePool: value });
 }
 
 // --- Redazione (view sicura per status/list: MAI il token) ------------------
@@ -434,6 +579,18 @@ function redactNode(n) {
   if (n.visibility === 'selected') out.selected = [...(n.selected || [])];
   if (n.sshPort !== undefined) out.sshPort = n.sshPort;
   if (n.nodeId) out.nodeId = n.nodeId;
+  if (n.reversePool) {
+    out.reversePool = {
+      base: n.reversePool.base,
+      slots: n.reversePool.slots.map((slot) => ({ ...slot })),
+      activeSlot: n.reversePool.activeSlot,
+      activeGeneration: n.reversePool.activeGeneration,
+      verification: n.reversePool.verification,
+      verifiedSlots: [...n.reversePool.verifiedSlots],
+      rotation: { ...n.reversePool.rotation },
+      ...(n.reversePool.lastAutoRotationAt === undefined ? {} : { lastAutoRotationAt: n.reversePool.lastAutoRotationAt }),
+    };
+  }
   return out;
 }
 
@@ -577,10 +734,11 @@ function suggestNodeName(input, existing = []) {
 module.exports = {
   // parse/validate
   parseStore, parseNode, parseRendezvous, parseRoles, parseSsh, parseSshTarget, isPort, isAbsPath, validToken,
+  parseReversePool, parseReversePoolAnchor, reversePoolDefault,
   // I/O
   defaultNodesPath, loadStore, loadStoreStrict, initStore, atomicWriteStore, loadOrInitStore, emptyStore, newNodeId,
   // mutazioni
-  getNode, addNode, removeNode, setNodeToken, updateNode,
+  getNode, addNode, removeNode, setNodeToken, updateNode, upgradeToReversePoolSchema, setNodeReversePool,
   // redazione
   redactNode, redactStore, hasPairedPeers,
   // migrazione
@@ -588,5 +746,5 @@ module.exports = {
   // label / slug
   nodeLabel, validLabel, sanitizeLabel, toSlug, deriveNodeHandle, suggestNodeName, LABEL_MAX,
   // costanti
-  SCHEMA_VERSION, LEGACY_SCHEMA_VERSION, MAX_NODES, MAX_TOKEN_LEN, NODE_NAME_RE, NODE_ID_RE,
+  SCHEMA_VERSION, PREVIOUS_SCHEMA_VERSION, LEGACY_SCHEMA_VERSION, MAX_NODES, MAX_TOKEN_LEN, NODE_NAME_RE, NODE_ID_RE,
 };

package/lib/nodes/tunnel-supervisor.js

@@ -89,7 +89,14 @@ function clearForwardProbe() {
 function probeForward(expectedChild) {
   if (stopping || child !== expectedChild || !child || child.exitCode != null) return;
   if (!forwardPort) {
-    writeState('transport-probing', { sshPid: child.pid, detail: 'local forward unavailable' });
+    // A reverse-only sidecar has no local -L to probe.  With
+    // ExitOnForwardFailure enabled, surviving the stability window proves that
+    // ssh accepted its -R request; the hub still performs the stronger MAC
+    // ownership probe before it publishes Share.
+    attempt = 0;
+    reverseFailures = 0;
+    logEvent(`reverse forward ready stableMs=${stableMs}`);
+    if (!writeState('transport-ready', { sshPid: child.pid, stableMs, probe: 'reverse-forward' })) stop();
     return;
   }
   let settled = false;