@mmmbuto/nexuscrew 0.8.20 → 0.8.22

package/lib/nodes/commands.js

@@ -16,6 +16,8 @@ const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const store = require('./store.js');
 const tunnel = require('./tunnel.js');
+const topologyCache = require('./topology-cache.js');
+const inventory = require('./inventory.js');
 const federation = require('../proxy/federation.js');
 const { resolvePaths, DEFAULT_PORT } = require('../cli/url.js');
 
@@ -31,6 +33,32 @@ function resolveNodePaths(opts) {
   return { home, configDir, configPath, nodesPath };
 }
 
+function resolveStoredNode(st, ref) {
+  const value = String(ref || '').trim();
+  if (!value) return null;
+  return st.nodes.find((node) => node.name === value || node.nodeId === value) || null;
+}
+
+function loadPeerInventory(opts = {}) {
+  const { home, nodesPath } = resolveNodePaths(opts);
+  const st = store.loadStore(nodesPath);
+  if (!st) return { nodeId: null, nodes: [], peers: [] };
+  const direct = store.redactStore(st).nodes;
+  const extras = new Map(direct.map((node) => [node.name, {
+    tunnel: node.direction === 'inbound'
+      ? { status: node.shared === true ? 'shared-peer' : 'private-peer', managed: false }
+      : tunnel.readTunnelState(home, node.name),
+  }]));
+  const cachePath = opts.topologyCachePath || topologyCache.defaultPath(home);
+  const cached = topologyCache.loadCache(cachePath);
+  const peers = inventory.buildInventory({
+    direct,
+    topology: cached && Array.isArray(cached.nodes) ? cached.nodes : [],
+    extras,
+  });
+  return { nodeId: st.nodeId, nodes: peers.filter((peer) => peer.kind === 'direct'), peers };
+}
+
 // Prima localPort libera >= base, evitando le porte gia' assegnate (porta STABILE:
 // una volta scelta resta in nodes.json, non si ricicla).
 function assignLocalPort(st) {
@@ -187,16 +215,122 @@ function nodesList(opts) {
     return { code: 0, nodes: [] };
   }
 
-  const view = store.redactStore(st); // MAI il token
-  const nodes = view.nodes.map((n) => ({ ...n, tunnel: tunnel.readTunnelState(home, n.name) }));
-  const out = { nodeId: view.nodeId, nodes };
+  const out = loadPeerInventory(opts); // MAI il token
+  const { nodes, peers } = out;
+  const visiblePeers = opts.direct === true ? nodes : peers;
 
-  if (opts.json) { log(JSON.stringify(out, null, 2)); return { code: 0, nodes }; }
-  if (nodes.length === 0) { log('nodes: (nessun nodo)'); return { code: 0, nodes }; }
+  if (opts.json) {
+    log(JSON.stringify({ ...out, peers: visiblePeers }, null, 2));
+    return { code: 0, nodes, peers: visiblePeers };
+  }
+  if (visiblePeers.length === 0) { log('nodes: (nessun nodo)'); return { code: 0, nodes, peers: visiblePeers }; }
   for (const n of nodes) {
-    log(`${n.name}\t${n.ssh}${n.sshPort ? `:${n.sshPort}` : ''}\tlocal:${n.localPort} -> nexus:${n.remotePort}\ttunnel:${n.tunnel.status}\ttoken:${n.hasToken ? 'set' : 'unset'}`);
+    const endpoint = n.direction === 'inbound' ? 'client collegato al hub'
+      : `${n.ssh}${n.sshPort ? `:${n.sshPort}` : ''} · local:${n.localPort} -> nexus:${n.remotePort}`;
+    log(`${n.name}\t${n.nodeId || '-'}\t${n.relation}\t${endpoint}\tstatus:${n.tunnel.status}`);
+  }
+  for (const n of visiblePeers.filter((peer) => peer.kind === 'transitive')) {
+    log(`${n.name}\t${n.nodeId}\trouted\tvia:${n.route.join(' -> ')}\tazioni:inspect`);
+  }
+  return { code: 0, nodes, peers: visiblePeers };
+}
+
+function nodesInspect(opts) {
+  const log = opts.log || console.log;
+  const out = loadPeerInventory(opts);
+  const found = inventory.resolvePeer(out.peers, opts.ref || opts.name);
+  if (!found.peer) {
+    log(`nodes inspect: ${found.error}`);
+    return { code: 1, reason: 'unknown-node' };
   }
-  return { code: 0, nodes };
+  if (opts.json) log(JSON.stringify(found.peer, null, 2));
+  else {
+    const peer = found.peer;
+    log(`${peer.label || peer.name} (${peer.name})`);
+    log(`nodeId:    ${peer.nodeId || '-'}`);
+    log(`tipo:      ${peer.kind} · ${peer.relation}`);
+    log(`route:     ${peer.route.join(' -> ')}`);
+    if (peer.tunnel) log(`status:    ${peer.tunnel.status}`);
+    log(`azioni:    ${Object.keys(peer.actions || {}).filter((key) => peer.actions[key]).join(', ')}`);
+  }
+  return { code: 0, peer: found.peer };
+}
+
+function nodesEdit(opts) {
+  const log = opts.log || console.log;
+  if (isReadonly(opts)) { log('nodes edit: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
+  const { home, nodesPath } = resolveNodePaths(opts);
+  let st;
+  try { st = store.loadStoreStrict(nodesPath); }
+  catch (e) { log(`nodes edit: ${e.message}`); return { code: 1, reason: 'store invalido', status: e.status || 500, errorCode: e.code || null }; }
+  const node = resolveStoredNode(st, opts.ref || opts.name);
+  if (!node) { log(`nodes edit: nodo sconosciuto "${opts.ref || opts.name || ''}"`); return { code: 1, reason: 'unknown-node' }; }
+  const supplied = opts.patch && typeof opts.patch === 'object' ? opts.patch : {};
+  const allowed = node.direction === 'inbound'
+    ? new Set(['label', 'visibility', 'selected'])
+    : new Set(['label', 'ssh', 'sshPort', 'autostart']);
+  const keys = Object.keys(supplied);
+  const invalid = keys.find((key) => !allowed.has(key));
+  if (invalid) {
+    log(`nodes edit: campo "${invalid}" non modificabile per un peer ${node.direction}`);
+    return { code: 1, reason: 'field-not-editable' };
+  }
+  if (keys.length === 0) { log('nodes edit: nessuna modifica richiesta'); return { code: 1, reason: 'empty-patch' }; }
+  const patch = { ...supplied };
+  if (Object.hasOwn(patch, 'label')) {
+    if (!store.validLabel(patch.label)) { log('nodes edit: label non valida (max 64 char, niente a capo)'); return { code: 1, reason: 'invalid-label' }; }
+    patch.label = patch.label.trim();
+  }
+  if (Object.hasOwn(patch, 'ssh')) {
+    const parsed = store.parseSshTarget(patch.ssh);
+    if (!parsed) { log('nodes edit: ssh non valido (atteso user@host o Host alias)'); return { code: 1, reason: 'invalid-ssh' }; }
+    patch.ssh = parsed.value;
+  }
+  if (Object.hasOwn(patch, 'sshPort')) {
+    patch.sshPort = Number(patch.sshPort);
+    if (!store.isPort(patch.sshPort)) { log('nodes edit: sshPort non valida (1..65535)'); return { code: 1, reason: 'invalid-ssh-port' }; }
+  }
+  if (Object.hasOwn(patch, 'autostart') && typeof patch.autostart !== 'boolean') {
+    log('nodes edit: autostart deve essere booleano'); return { code: 1, reason: 'invalid-autostart' };
+  }
+  if (Object.hasOwn(patch, 'visibility') && !['network', 'relay-only', 'selected'].includes(patch.visibility)) {
+    log('nodes edit: visibility non valida'); return { code: 1, reason: 'invalid-visibility' };
+  }
+  if (patch.visibility !== 'selected') delete patch.selected;
+
+  let next;
+  try { next = store.updateNode(st, node.name, patch); }
+  catch (e) { log(`nodes edit: ${e.message}`); return { code: 1, reason: 'invalid-patch' }; }
+
+  const transportChanged = node.direction === 'outbound'
+    && ['ssh', 'sshPort'].some((key) => Object.hasOwn(patch, key));
+  const wasUp = transportChanged && tunnel.readTunnelState(home, node.name).status === 'up';
+  try {
+    store.atomicWriteStore(nodesPath, next);
+    if (wasUp) {
+      const stopImpl = opts.stopTunnel || tunnel.stopTunnel;
+      const startImpl = opts.startForward || tunnel.startForward;
+      stopImpl({ home, name: node.name });
+      const started = startImpl({
+        home, node: store.getNode(next, node.name), localAppPort: opts.localAppPort,
+        spawnImpl: opts.spawnImpl, spawnSyncImpl: opts.spawnSyncImpl, sshBin: opts.sshBin, logFd: opts.logFd,
+      });
+      if (!started.started && started.reason !== 'already running') throw new Error(started.reason || 'riavvio tunnel fallito');
+    }
+  } catch (e) {
+    try {
+      store.atomicWriteStore(nodesPath, st);
+      if (wasUp) (opts.startForward || tunnel.startForward)({
+        home, node, localAppPort: opts.localAppPort,
+        spawnImpl: opts.spawnImpl, spawnSyncImpl: opts.spawnSyncImpl, sshBin: opts.sshBin, logFd: opts.logFd,
+      });
+    } catch (_) { /* rollback best-effort */ }
+    log(`nodes edit: modifica annullata — ${e.message}`);
+    return { code: 1, reason: 'write-or-restart-failed' };
+  }
+  const edited = store.redactNode(store.getNode(next, node.name));
+  log(`nodes edit: nodo "${node.name}" aggiornato`);
+  return { code: 0, name: node.name, node: edited, restarted: wasUp };
 }
 
 // --- nodes remove ----------------------------------------------------------
@@ -204,10 +338,13 @@ function nodesRemove(opts) {
   const log = opts.log || console.log;
   if (isReadonly(opts)) { log('nodes remove: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
   const { home, nodesPath } = resolveNodePaths(opts);
-  const name = opts.name;
-  if (!name) { log('nodes remove: name mancante'); return { code: 1 }; }
+  const ref = opts.ref || opts.name;
+  if (!ref) { log('nodes remove: riferimento nodo mancante'); return { code: 1 }; }
   const st = store.loadStore(nodesPath);
   if (!st) { log('nodes remove: nessun nodes.json valido'); return { code: 1 }; }
+  const node = resolveStoredNode(st, ref);
+  if (!node) { log(`nodes remove: nodo sconosciuto "${ref}"`); return { code: 1, reason: 'unknown-node' }; }
+  const name = node.name;
   let next;
   try { next = store.removeNode(st, name); }
   catch (e) { log(`nodes remove: ${e.message}`); return { code: 1 }; }
@@ -236,11 +373,12 @@ function nodesRemove(opts) {
 async function nodesTest(opts) {
   const log = opts.log || console.log;
   const { home, nodesPath } = resolveNodePaths(opts);
-  const name = opts.name;
-  if (!name) { log('nodes test: name mancante'); return { code: 1 }; }
+  const ref = opts.ref || opts.name;
+  if (!ref) { log('nodes test: riferimento nodo mancante'); return { code: 1 }; }
   const st = store.loadStore(nodesPath);
-  const node = st ? store.getNode(st, name) : null;
-  if (!node) { log(`nodes test: nodo sconosciuto "${name}"`); return { code: 1, result: 'unknown-node' }; }
+  const node = st ? resolveStoredNode(st, ref) : null;
+  if (!node) { log(`nodes test: nodo sconosciuto "${ref}"`); return { code: 1, result: 'unknown-node' }; }
+  const name = node.name;
 
   // An inbound peer is reached through the reverse listener owned by sshd on
   // this hub; there is intentionally no local tunnel pidfile to inspect.
@@ -319,11 +457,11 @@ async function defaultHttpProbe(url, headers) {
 // --- nodes up/down/restart (lifecycle tunnel, NON tocca la config) ----------
 function loadNodeOrFail(opts, log) {
   const { home, nodesPath } = resolveNodePaths(opts);
-  const name = opts.name;
-  if (!name) { log('nodes: name mancante'); return null; }
+  const ref = opts.ref || opts.name;
+  if (!ref) { log('nodes: riferimento nodo mancante'); return null; }
   const st = store.loadStore(nodesPath);
-  const node = st ? store.getNode(st, name) : null;
-  if (!node) { log(`nodes: nodo sconosciuto "${name}"`); return null; }
+  const node = st ? resolveStoredNode(st, ref) : null;
+  if (!node) { log(`nodes: nodo sconosciuto "${ref}"`); return null; }
   return { home, nodesPath, store: st, node };
 }
 
@@ -336,6 +474,7 @@ function persistAutostart(ctx, enabled) {
 
 function nodesUp(opts) {
   const log = opts.log || console.log;
+  if (isReadonly(opts)) { log('nodes up: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
   const ctx = loadNodeOrFail(opts, log);
   if (!ctx) return { code: 1 };
   if (ctx.node.direction === 'inbound') return { code: 0, started: false, inbound: true };
@@ -359,6 +498,7 @@ function nodesUp(opts) {
 
 function nodesDown(opts) {
   const log = opts.log || console.log;
+  if (isReadonly(opts)) { log('nodes down: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
   const ctx = loadNodeOrFail(opts, log);
   if (!ctx) return { code: 1 };
   if (ctx.node.direction === 'inbound') return { code: 0, stopped: false, inbound: true };
@@ -373,6 +513,7 @@ function nodesDown(opts) {
 
 function nodesRestart(opts) {
   const log = opts.log || console.log;
+  if (isReadonly(opts)) { log('nodes restart: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
   const ctx = loadNodeOrFail(opts, log);
   if (!ctx) return { code: 1 };
   if (ctx.node.direction === 'inbound') return { code: 0, started: false, inbound: true };
@@ -408,9 +549,9 @@ function nodesSetToken(opts) {
 }
 
 module.exports = {
-  nodesAdd, nodesList, nodesRemove, nodesTest,
+  nodesAdd, nodesList, nodesInspect, nodesEdit, nodesRemove, nodesTest,
   nodesUp, nodesDown, nodesRestart, nodesSetToken,
   // helper esposti per test/riuso
   assignLocalPort, bindLocalPort, reserveLocalPort, defaultKeyPath, ensureKey, readSecretToken,
-  resolveNodePaths, defaultHttpProbe,
+  resolveNodePaths, resolveStoredNode, loadPeerInventory, defaultHttpProbe,
 };

package/lib/nodes/inventory.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// Canonical peer inventory shared by HTTP, CLI and the PWA.  A direct peer is
+// backed by nodes.json and can therefore expose management actions.  A routed
+// peer comes from topology-cache.json: it is visible and inspectable, but it
+// must never pretend to support mutations on this installation.
+
+function actionsFor(node, kind = 'direct') {
+  if (kind !== 'direct') return { inspect: true };
+  const outbound = node.direction !== 'inbound';
+  return {
+    inspect: true,
+    edit: true,
+    remove: true,
+    test: true,
+    ...(outbound ? {
+      connect: true,
+      disconnect: true,
+      restart: true,
+      share: true,
+    } : {
+      visibility: true,
+    }),
+  };
+}
+
+function directPeer(node, extra = {}) {
+  const direction = node.direction || 'outbound';
+  return {
+    ...node,
+    ...extra,
+    kind: 'direct',
+    relation: direction === 'inbound' ? 'client' : 'hub',
+    manageable: true,
+    route: [node.name],
+    hops: 1,
+    actions: actionsFor(node, 'direct'),
+  };
+}
+
+function routedPeer(entry) {
+  const route = Array.isArray(entry.route) ? [...entry.route] : [];
+  return {
+    name: entry.name,
+    nodeId: entry.instanceId,
+    instanceId: entry.instanceId,
+    kind: 'transitive',
+    relation: 'routed',
+    manageable: false,
+    route,
+    hops: route.length,
+    lastSeen: entry.lastSeen,
+    stale: entry.stale === true,
+    actions: actionsFor(entry, 'transitive'),
+  };
+}
+
+function buildInventory({ direct = [], topology = [], extras = new Map() } = {}) {
+  const directIds = new Set(direct.map((node) => node && node.nodeId).filter(Boolean));
+  const peers = direct.map((node) => directPeer(node, extras.get(node.name) || {}));
+  for (const entry of topology) {
+    if (!entry || directIds.has(entry.instanceId)) continue;
+    peers.push(routedPeer(entry));
+  }
+  return peers;
+}
+
+function resolvePeer(peers, ref) {
+  const value = String(ref || '').trim();
+  if (!value) return { error: 'riferimento nodo mancante' };
+  const byId = peers.filter((peer) => peer.nodeId === value || peer.instanceId === value);
+  if (byId.length === 1) return { peer: byId[0] };
+  const byName = peers.filter((peer) => peer.name === value);
+  if (byName.length === 1) return { peer: byName[0] };
+  if (byId.length > 1 || byName.length > 1) {
+    return { error: `riferimento ambiguo "${value}": usa il nodeId` };
+  }
+  return { error: `nodo sconosciuto "${value}"` };
+}
+
+module.exports = { actionsFor, directPeer, routedPeer, buildInventory, resolvePeer };

package/lib/nodes/tunnel.js

@@ -186,6 +186,14 @@ function openTunnelLog(home, name) {
 function classifySshFailure(text, remotePort) {
   const s = String(text || '');
   const target = store.isPort(remotePort) ? `127.0.0.1:${remotePort}` : 'la porta NexusCrew richiesta';
+  const reverseMatch = s.match(/remote port forwarding failed for listen port\s+(\d+)/i)
+    || s.match(/(?:bind|listen)[^\r\n]*127\.0\.0\.1:(\d+)/i);
+  const reverseListenPort = reverseMatch ? Number(reverseMatch[1]) : null;
+  const reverseTarget = store.isPort(reverseListenPort)
+    ? `127.0.0.1:${reverseListenPort}` : 'la porta reverse negoziata';
+  const reversePolicy = store.isPort(reverseListenPort)
+    ? `che la chiave SSH autorizzi permitlisten="${reverseTarget}"`
+    : 'che la chiave SSH autorizzi il reverse listen negoziato';
   if (/administratively prohibited|request (?:was )?denied|open failed:.*prohibited|port forwarding.*(?:disabled|denied)/i.test(s)) {
     return {
       code: 'forward-denied',
@@ -219,7 +227,7 @@ function classifySshFailure(text, remotePort) {
     return {
       code: 'reverse-forward-failed',
       detail: 'il canale inverso non è stato aperto dal nodo hub',
-      hint: 'la porta può essere già occupata oppure il server può vietare il forwarding; verifica listener e policy SSH sul nodo hub',
+      hint: `verifica che ${reverseTarget} non sia occupata e ${reversePolicy}; controlla anche AllowTcpForwarding sul nodo hub`,
     };
   }
   if (/Could not request local forwarding|Address already in use/i.test(s)) {

package/lib/server.js

@@ -27,6 +27,8 @@ const { fsRoutes } = require('./fs/routes.js');
 const nodesStore = require('./nodes/store.js');
 const nodesTunnel = require('./nodes/tunnel.js');
 const nodesHealth = require('./nodes/health.js');
+const nodesInventory = require('./nodes/inventory.js');
+const topologyCache = require('./nodes/topology-cache.js');
 const { createNodeProxy, handleNodeUpgrade } = require('./proxy/node-proxy.js');
 const federation = require('./proxy/federation.js');
 const { settingsRoutes, publicPeeringRoutes } = require('./settings/routes.js');
@@ -107,8 +109,8 @@ function createServer(opts = {}) {
     ...(cfg.updateSeams || {}),
   });
   const attachedWs = new Map(); // ws -> session (per il push dei frame files)
-  // selectProvider sceglie UNA volta (startup) il provider external|builtin|disabled
-  // (design §4b/§9b/§9g) e ritorna {mode,reason,fleet}; routes consumano il .fleet,
+  // selectProvider sceglie UNA volta (startup) builtin|disabled e ritorna
+  // {mode,reason,fleet}; routes consumano il .fleet,
   // quindi fleetP resta una Promise<Fleet> (createServer non diventa async).
   const fleetP = selectProvider(cfg).then((p) => p.fleet);
 
@@ -119,7 +121,7 @@ function createServer(opts = {}) {
   const nodesPath = cfg.nodesPath || nodesStore.defaultNodesPath(cfg.home || os.homedir());
   // fetch usata dai probe di salute federati (iniettabile nei test); default globale.
   const healthFetch = cfg.fetchImpl || fetch;
-  const topologyCachePath = cfg.topologyCachePath || require('./nodes/topology-cache.js').defaultPath(cfg.home || os.homedir());
+  const topologyCachePath = cfg.topologyCachePath || topologyCache.defaultPath(cfg.home || os.homedir());
   const decksPath = cfg.decksPath || decksStore.defaultDecksPath(cfg.home || os.homedir());
   const proxyReadonly = () => (cfg.readonlyDefault === true || process.env.NEXUSCREW_READONLY === '1');
   function resolveNode(name) {
@@ -292,6 +294,32 @@ function createServer(opts = {}) {
       res.json({ nodeId: view.nodeId, nodes });
     } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
   });
+  // Canonical management inventory: direct hubs/clients plus routed peers.  The
+  // latter are deliberately inspect-only because they have no local nodes.json
+  // record to mutate.  UI and CLI consume the same action matrix.
+  api.get('/peers', async (_req, res) => {
+    try {
+      const st = nodesStore.loadStore(nodesPath);
+      if (!st) return res.json({ nodeId: null, peers: [] });
+      const direct = nodesStore.redactStore(st).nodes;
+      const healths = await nodesHealth.nodesHealth({
+        nodes: st.nodes, home: cfg.home || os.homedir(), fetchImpl: healthFetch, now: Date.now(),
+      });
+      const extras = new Map(direct.map((node, index) => {
+        const health = healths[index] || null;
+        return [node.name, { health, tunnel: nodesHealth.tunnelFromHealth(health) }];
+      }));
+      const topology = await federation.collectLocalTopology({
+        nodesPath, cachePath: topologyCachePath, fetchImpl: healthFetch,
+      });
+      const peers = nodesInventory.buildInventory({
+        direct,
+        topology: topology && Array.isArray(topology.nodes) ? topology.nodes : [],
+        extras,
+      });
+      res.json({ nodeId: st.nodeId, peers });
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
   // Settings API B2 (design §4b(6)): read-only GET + mutanti lista chiusa per il
   // wizard/settings UI. Dietro lo stesso requireToken del router /api; il gate
   // READONLY route-level e la redazione token vivono dentro settingsRoutes.

package/lib/settings/routes.js

@@ -65,6 +65,7 @@ const { publicPeeringRoutes } = require('./public-peering-routes.js');
 const CONFIG_KEYS = new Set(['roles', 'port', 'wizardDone', 'autoUpdate']);
 const ROLE_KEYS = new Set(['client', 'node']);
 const ADD_KEYS = new Set(['name', 'ssh', 'sshPort', 'remotePort', 'localPort', 'keyPath', 'label']);
+const EDIT_KEYS = new Set(['label', 'ssh', 'sshPort', 'autostart', 'visibility', 'selected']);
 
 // Default sensato per il "nome dispositivo" proposto nei form (pairing/invite).
 // NON usa ciecamente hostname: se l'hostname e' vuoto o 'localhost' (tipico di
@@ -186,6 +187,21 @@ function settingsRoutes(deps = {}) {
   });
 
   const validName = (name) => typeof name === 'string' && nodesStore.NODE_NAME_RE.test(name);
+  const applyNodeEdit = (res, name, patch) => {
+    const cap = capture();
+    const out = nodesCmds.nodesEdit({ ...cliOpts(cap), ref: name, patch });
+    if (out.code === 0) return send(res, 200, {
+      saved: true, name: out.name, node: out.node, restarted: out.restarted === true,
+    });
+    const message = lastLine(cap, 'nodes edit fallito');
+    if (out.reason === 'readonly') return send(res, 403, { error: message });
+    if (out.reason === 'unknown-node') return send(res, 404, { error: message });
+    if (out.reason === 'store invalido') {
+      return send(res, out.status || 503, { error: message, ...(out.errorCode ? { code: out.errorCode } : {}) });
+    }
+    const status = out.reason === 'write-or-restart-failed' ? 502 : 400;
+    return send(res, status, { error: message });
+  };
 
   // --- GET / — vista read-only per wizard/settings UI -----------------------
   r.get('/', (_req, res) => {
@@ -459,6 +475,21 @@ function settingsRoutes(deps = {}) {
     } catch (e) { send(res, 500, { error: String(e.message || e) }); }
   });
 
+  // General direct-peer edit endpoint used by both the PWA and headless CLI.
+  // Stable identity fields (name/nodeId/ports/capabilities) are not writable;
+  // nodesEdit applies the direction-aware allowlist and tunnel rollback.
+  r.patch('/nodes/:name', mutGate, (req, res) => {
+    const name = String(req.params.name || '');
+    const body = req.body;
+    if (!validName(name)) return send(res, 400, { error: 'name non valido (^[a-z0-9-]{1,32}$)' });
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+      return send(res, 400, { error: 'body deve essere un oggetto JSON' });
+    }
+    const invalid = Object.keys(body).find((key) => !EDIT_KEYS.has(key));
+    if (invalid) return send(res, 400, { error: `campo non modificabile: "${invalid}"` });
+    return applyNodeEdit(res, name, body);
+  });
+
   // --- POST /nodes/:name/test — non-mutante (POST per coerenza azione) -------
   // NON gated READONLY: e' una probe diagnostica, coerente col `nodes test` CLI.
   r.post('/nodes/:name/test', async (req, res) => {
@@ -530,18 +561,16 @@ function settingsRoutes(deps = {}) {
     let persistedDesired = wasShared;
     const fetchImpl = seams.fetchImpl || fetch;
     const notifyHub = (shared) => notifyHubShare({ node, shared, fetchImpl, timeoutMs: 5000 });
-    const applyLocal = async (shared) => {
-      st = nodesStore.loadStoreStrict(nodesPath);
-      st = nodesStore.updateNode(st, name, { shared });
-      nodesStore.atomicWriteStore(nodesPath, st);
-      persistedDesired = shared;
-      node = nodesStore.getNode(st, name);
-      nodesTunnel.stopTunnel({ home, name });
+    const ensureLocal = async ({ restart = false } = {}) => {
+      if (restart) nodesTunnel.stopTunnel({ home, name });
       const started = nodesTunnel.startForward({
         home, node, localAppPort: runtimePort(),
         spawnImpl: seams.spawnImpl, spawnSyncImpl: seams.spawnSyncImpl,
         sshBin: seams.sshBin, logFd: seams.logFd,
       });
+      // startForward is spec-aware: an exact live argv is idempotent, while a
+      // stale pre-upgrade supervisor whose -L/-R no longer matches nodes.json
+      // is replaced. This is the recovery path for store=false + stale -R.
       if (!started.started && started.reason !== 'already running') {
         throw new Error(started.reason || 'avvio SSH fallito');
       }
@@ -552,12 +581,28 @@ function settingsRoutes(deps = {}) {
       });
       if (!ready || ready.status !== 'healthy') {
         const diagnosis = (seams.readTunnelDiagnostic || nodesTunnel.readTunnelDiagnostic)(home, name, node.remotePort);
-        throw new Error((diagnosis && diagnosis.detail) || (ready && ready.detail) || 'hub non raggiungibile dopo il riavvio SSH');
+        const failure = new Error((diagnosis && diagnosis.detail) || (ready && ready.detail) || 'hub non raggiungibile dopo il riavvio SSH');
+        if (diagnosis && typeof diagnosis.hint === 'string') failure.hint = diagnosis.hint;
+        throw failure;
       }
+      return started;
+    };
+    const applyLocal = async (shared) => {
+      st = nodesStore.loadStoreStrict(nodesPath);
+      st = nodesStore.updateNode(st, name, { shared });
+      nodesStore.atomicWriteStore(nodesPath, st);
+      persistedDesired = shared;
+      node = nodesStore.getNode(st, name);
+      await ensureLocal({ restart: true });
     };
 
     try {
       if (node.shared === body.shared) {
+        // Persisted intent is not proof of the detached process mode. A stale
+        // supervisor can survive an npm upgrade and keep retrying -R even when
+        // the store/UI says private. Re-enter the spec-aware start path before
+        // reconciling the hub, without rewriting nodes.json.
+        await ensureLocal();
         await notifyHub(body.shared);
         return send(res, 200, { name, shared: body.shared, unchanged: true, reconciled: true });
       }
@@ -578,42 +623,33 @@ function settingsRoutes(deps = {}) {
         try { await applyLocal(false); } catch (_) { /* best-effort safe rollback */ }
       }
       const offPersisted = body.shared === false && persistedDesired === false;
+      const redact = (value) => String(value || '').replace(/Bearer\s+\S+/gi, 'Bearer ***');
       return send(res, 502, {
         error: body.shared ? 'Share non attivato'
           : offPersisted ? 'Share disattivato localmente; hub non riconciliato' : 'Share non disattivato',
         ...(offPersisted ? { shared: false, reconcilePending: true } : {}),
-        detail: String(e && e.message || e).replace(/Bearer\s+\S+/gi, 'Bearer ***'),
+        detail: redact(e && e.message || e),
+        ...(e && typeof e.hint === 'string' ? { hint: redact(e.hint) } : {}),
       });
     }
   });
 
   r.patch('/nodes/:name/visibility', mutGate, (req, res) => {
-    try {
-      const name = String(req.params.name || '');
-      const visibility = req.body && req.body.visibility;
-      const selected = (req.body && req.body.selected) || [];
-      if (!validName(name) || !['network', 'relay-only', 'selected'].includes(visibility)) {
-        return send(res, 400, { error: 'visibility non valida' });
-      }
-      let st = nodesStore.loadStoreStrict(nodesPath);
-      st = nodesStore.updateNode(st, name, { visibility, selected: visibility === 'selected' ? selected : [] });
-      nodesStore.atomicWriteStore(nodesPath, st);
-      send(res, 200, { saved: true, name, visibility });
-    } catch (e) { send(res, e.status || 400, { error: String(e.message || e), ...(e.code ? { code: e.code } : {}) }); }
+    const name = String(req.params.name || '');
+    const visibility = req.body && req.body.visibility;
+    const selected = (req.body && req.body.selected) || [];
+    if (!validName(name) || !['network', 'relay-only', 'selected'].includes(visibility)) {
+      return send(res, 400, { error: 'visibility non valida' });
+    }
+    return applyNodeEdit(res, name, { visibility, selected: visibility === 'selected' ? selected : [] });
   });
   // Rinomina la label umana di un nodo SENZA toccare il name (route/URL stabili).
   r.patch('/nodes/:name/label', mutGate, (req, res) => {
-    try {
-      const name = String(req.params.name || '');
-      const label = req.body && req.body.label;
-      if (!validName(name)) return send(res, 400, { error: 'name non valido (^[a-z0-9-]{1,32}$)' });
-      if (!nodesStore.validLabel(label)) return send(res, 400, { error: 'label non valida (max 64 char, niente a capo)' });
-      let st = nodesStore.loadStoreStrict(nodesPath);
-      if (!nodesStore.getNode(st, name)) return send(res, 404, { error: `nodo sconosciuto "${name}"` });
-      st = nodesStore.updateNode(st, name, { label: nodesStore.sanitizeLabel(label, name) });
-      nodesStore.atomicWriteStore(nodesPath, st);
-      send(res, 200, { saved: true, name, label: nodesStore.nodeLabel(nodesStore.getNode(st, name)) });
-    } catch (e) { send(res, e.status || 400, { error: String(e.message || e), ...(e.code ? { code: e.code } : {}) }); }
+    const name = String(req.params.name || '');
+    const label = req.body && req.body.label;
+    if (!validName(name)) return send(res, 400, { error: 'name non valido (^[a-z0-9-]{1,32}$)' });
+    if (!nodesStore.validLabel(label)) return send(res, 400, { error: 'label non valida (max 64 char, niente a capo)' });
+    return applyNodeEdit(res, name, { label });
   });
 
   // Legacy compatibility endpoint: the old node-role/rendezvous flow opened a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.8.20",
+  "version": "0.8.22",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {