@mmmbuto/nexuscrew 0.8.43 → 0.8.45

package/lib/nodes/reverse-pool.js

@@ -0,0 +1,221 @@
+'use strict';
+// Reverse-port pool and append-only ledger.  The ledger is deliberately
+// separate from nodes.json: a node store is rewritten often, whereas reusing a
+// released SSH permitlisten is unsafe until an operator changes that policy.
+// Its anchor lives in nodes.json (validated by the caller) so a deleted or
+// truncated ledger can never make a retired pool allocatable again.
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REVERSE_PORT_BASE = 44001;
+const REVERSE_POOL_SIZE = 3;
+const REVERSE_POOL_STRIDE = 100;
+const LEDGER_VERSION = 1;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+const EPOCH_RE = /^[a-f0-9]{32,64}$/;
+const ENTRY_TYPES = new Set(['allocated', 'retired', 'quarantined']);
+
+function isPort(port) {
+  return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+
+function reversePoolForBase(base) {
+  if (!isPort(base)) return null;
+  const slots = Array.from({ length: REVERSE_POOL_SIZE }, (_, index) => base + (index * REVERSE_POOL_STRIDE));
+  return slots.every(isPort) ? slots : null;
+}
+
+function validReversePoolBase(base) {
+  return Array.isArray(reversePoolForBase(base));
+}
+
+function defaultLedgerPath(home = os.homedir()) {
+  return path.join(home, '.nexuscrew', 'reverse-pool-ledger.json');
+}
+
+function genesisDigest(epoch) {
+  return crypto.createHash('sha256').update(`nexuscrew-reverse-pool-ledger/v${LEDGER_VERSION}\0${epoch}`).digest('hex');
+}
+
+function digestEntry(entry) {
+  return crypto.createHash('sha256').update(JSON.stringify({
+    seq: entry.seq,
+    type: entry.type,
+    base: entry.base,
+    at: entry.at,
+    prevDigest: entry.prevDigest,
+  })).digest('hex');
+}
+
+function parseEntry(entry, previous, expectedSeq) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null;
+  const keys = Object.keys(entry);
+  if (keys.length !== 6 || keys.some((key) => !['seq', 'type', 'base', 'at', 'prevDigest', 'digest'].includes(key))) return null;
+  if (!Number.isSafeInteger(entry.seq) || entry.seq !== expectedSeq || !ENTRY_TYPES.has(entry.type)
+    || !validReversePoolBase(entry.base) || !Number.isSafeInteger(entry.at) || entry.at < 0
+    || !DIGEST_RE.test(String(entry.prevDigest || '')) || !DIGEST_RE.test(String(entry.digest || ''))
+    || entry.prevDigest !== previous || digestEntry(entry) !== entry.digest) return null;
+  return { seq: entry.seq, type: entry.type, base: entry.base, at: entry.at, prevDigest: entry.prevDigest, digest: entry.digest };
+}
+
+function parseLedger(raw) {
+  try {
+    const source = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    if (!source || typeof source !== 'object' || Array.isArray(source)) return null;
+    const keys = Object.keys(source);
+    if (keys.length !== 3 || keys.some((key) => !['version', 'epoch', 'entries'].includes(key))) return null;
+    if (source.version !== LEDGER_VERSION || !EPOCH_RE.test(String(source.epoch || ''))
+      || !Array.isArray(source.entries) || source.entries.length > 65535) return null;
+    let previous = genesisDigest(source.epoch);
+    const entries = [];
+    for (let index = 0; index < source.entries.length; index += 1) {
+      const entry = parseEntry(source.entries[index], previous, index + 1);
+      if (!entry) return null;
+      previous = entry.digest;
+      entries.push(entry);
+    }
+    return { version: LEDGER_VERSION, epoch: source.epoch, entries };
+  } catch (_) { return null; }
+}
+
+function emptyLedger(epoch = crypto.randomBytes(16).toString('hex')) {
+  if (!EPOCH_RE.test(epoch)) throw new Error('ledger epoch non valido');
+  return { version: LEDGER_VERSION, epoch, entries: [] };
+}
+
+function ledgerHead(ledger) {
+  const parsed = parseLedger(ledger);
+  if (!parsed) return null;
+  const last = parsed.entries.at(-1);
+  return {
+    epoch: parsed.epoch,
+    seq: last ? last.seq : 0,
+    digest: last ? last.digest : genesisDigest(parsed.epoch),
+  };
+}
+
+function appendLedger(ledger, { type, base, at = Date.now() } = {}) {
+  const parsed = parseLedger(ledger);
+  if (!parsed) throw new Error('reverse pool ledger non valido');
+  if (!ENTRY_TYPES.has(type) || !validReversePoolBase(base) || !Number.isSafeInteger(at) || at < 0) {
+    throw new Error('entry reverse pool ledger non valida');
+  }
+  const head = ledgerHead(parsed);
+  const entry = { seq: head.seq + 1, type, base, at, prevDigest: head.digest };
+  entry.digest = digestEntry(entry);
+  return { ...parsed, entries: [...parsed.entries, entry] };
+}
+
+function parseAnchor(anchor) {
+  if (!anchor || typeof anchor !== 'object' || Array.isArray(anchor)) return null;
+  if (Object.keys(anchor).length !== 3 || !EPOCH_RE.test(String(anchor.epoch || ''))
+    || !Number.isSafeInteger(anchor.seq) || anchor.seq < 0 || !DIGEST_RE.test(String(anchor.digest || ''))) return null;
+  return { epoch: anchor.epoch, seq: anchor.seq, digest: anchor.digest };
+}
+
+// A ledger can legitimately be ahead of the anchor after an interruption
+// between its atomic write and nodes.json's atomic anchor update.  That is
+// conservative and is reconciled by returning advanceAnchor.  Any missing
+// prefix is unsafe and blocks only fresh pool allocation; existing tunnels are
+// intentionally not affected.
+function validateLedgerAnchor(ledger, anchor) {
+  const parsed = parseLedger(ledger);
+  const expected = parseAnchor(anchor);
+  if (!parsed) return { ok: false, code: 'reverse-pool-ledger-invalid', allocationBlocked: true };
+  if (!expected) return { ok: false, code: 'reverse-pool-anchor-missing', allocationBlocked: true };
+  if (parsed.epoch !== expected.epoch) return { ok: false, code: 'reverse-pool-anchor-epoch-mismatch', allocationBlocked: true };
+  const head = ledgerHead(parsed);
+  if (head.seq < expected.seq) return { ok: false, code: 'reverse-pool-ledger-behind-anchor', allocationBlocked: true };
+  const prefix = expected.seq === 0
+    ? { epoch: parsed.epoch, seq: 0, digest: genesisDigest(parsed.epoch) }
+    : parsed.entries[expected.seq - 1];
+  if (!prefix || prefix.digest !== expected.digest) return { ok: false, code: 'reverse-pool-anchor-prefix-mismatch', allocationBlocked: true };
+  if (head.seq > expected.seq) return { ok: true, code: 'reverse-pool-anchor-advance', allocationBlocked: false, advanceAnchor: head };
+  return { ok: true, code: 'reverse-pool-anchor-current', allocationBlocked: false, anchor: head };
+}
+
+function loadLedger(ledgerPath) {
+  try {
+    const st = fs.lstatSync(ledgerPath);
+    if (!st.isFile() || st.isSymbolicLink()) return null;
+    return parseLedger(fs.readFileSync(ledgerPath, 'utf8'));
+  } catch (_) { return null; }
+}
+
+function atomicWriteLedger(ledgerPath, ledger) {
+  const parsed = parseLedger(ledger);
+  if (!parsed) throw new Error('reverse pool ledger non valido');
+  try {
+    if (fs.lstatSync(ledgerPath).isSymbolicLink()) throw new Error('reverse pool ledger target e\' un symlink');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const dir = path.dirname(ledgerPath);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(dir, `.${path.basename(ledgerPath)}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, ledgerPath);
+  } catch (error) {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw error;
+  }
+  return parsed;
+}
+
+function usedPorts(nodes = [], ledger = null) {
+  const ports = new Set();
+  for (const node of nodes || []) {
+    if (isPort(node && node.localPort)) ports.add(node.localPort);
+    if (isPort(node && node.reversePort)) ports.add(node.reversePort);
+    const pool = node && node.reversePool;
+    if (pool && validReversePoolBase(pool.base)) for (const port of reversePoolForBase(pool.base)) ports.add(port);
+  }
+  const parsed = parseLedger(ledger);
+  for (const entry of (parsed && parsed.entries) || []) {
+    // An allocation is permanent for this ledger's epoch.  Keeping every
+    // allocated base reserved is what prevents a removed peer's old SSH key
+    // from binding a newly assigned pool.
+    if (entry.type === 'allocated' && validReversePoolBase(entry.base)) {
+      for (const port of reversePoolForBase(entry.base)) ports.add(port);
+    }
+  }
+  return ports;
+}
+
+function nextReversePool(nodes = [], ledger = null, { start = REVERSE_PORT_BASE } = {}) {
+  const occupied = usedPorts(nodes, ledger);
+  for (let base = start; validReversePoolBase(base); base += 1) {
+    const slots = reversePoolForBase(base);
+    if (slots.every((port) => !occupied.has(port))) return { base, slots };
+  }
+  throw new Error('nessun reverse port pool disponibile');
+}
+
+async function allocateAvailableReversePool(nodes = [], ledger = null, {
+  start = REVERSE_PORT_BASE,
+  canBind = async () => true,
+} = {}) {
+  const occupied = usedPorts(nodes, ledger);
+  for (let base = start; validReversePoolBase(base); base += 1) {
+    const slots = reversePoolForBase(base);
+    if (!slots.every((port) => !occupied.has(port))) continue;
+    let available = true;
+    for (const port of slots) {
+      if (!(await canBind(port))) { available = false; break; }
+    }
+    if (available) return { base, slots };
+  }
+  throw new Error('nessun reverse port pool disponibile');
+}
+
+module.exports = {
+  REVERSE_PORT_BASE, REVERSE_POOL_SIZE, REVERSE_POOL_STRIDE, LEDGER_VERSION,
+  reversePoolForBase, validReversePoolBase, defaultLedgerPath,
+  genesisDigest, digestEntry, parseLedger, emptyLedger, ledgerHead, appendLedger,
+  parseAnchor, validateLedgerAnchor, loadLedger, atomicWriteLedger,
+  usedPorts, nextReversePool, allocateAvailableReversePool,
+};

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,
+};