@mmmbuto/nexuscrew 0.8.57 → 0.9.0

package/lib/live-host/routes.js

@@ -0,0 +1,184 @@
+'use strict';
+// lib/live-host/routes.js — route /api/live-host (control plane della designazione).
+//
+// Montate dietro requireToken (come /api/cells, /api/fleet): solo il token del nodo
+// passa. NON sono proxabili via /node/<name>: il blocklist local-only del proxy nega
+// /api/live-host (federazione default-deny — nessuno designa da remoto una cella di
+// questo nodo). La designazione e' quindi un'azione intrinsecamente locale.
+//
+// Invarianti (contratto rev6 §2, §9):
+//   - hostCell unico per nodo, CAS su revision (due designazioni concorrenti non
+//     lasciano due celle rosse).
+//   - API-first: la route e' l'unica autorita'; il frontend riflette la risposta e
+//     su errore resta sullo stato precedente (nessun ottimismo qui — la logica UI
+//     sta nel modulo frontend host-designation.js).
+//   - Cella inattiva PRESERVA la designazione: lo store non cancella mai hostCell per
+//     inattivita; `eligible` e' derivato dal roster al momento del GET.
+//   - readonly => 403 su designate/clear.
+
+const express = require('express');
+const { CELL_ID_RE } = require('./store.js');
+
+// Ricava l'elenco celle LOCALI dal fleet (definizioni, attive e non). Una cella
+// federata non compare qui: e' il check che chiude "designa solo una cella di questo
+// nodo". Ritorna null se il fleet non e' interrogabile (la route decide come gestirlo).
+async function localCells(fleetP) {
+  const fleet = await fleetP;
+  if (!fleet || fleet.available !== true) return null;
+  const statusFn = fleet && (typeof fleet.status === 'function' ? fleet.status : fleet.cellStatus);
+  if (typeof statusFn !== 'function') return null;
+  const st = await statusFn.call(fleet);
+  return Array.isArray(st && st.cells) ? st.cells : [];
+}
+
+function isActive(cell) {
+  return !!(cell && cell.active === true && cell.tmux !== false);
+}
+
+// --- Seam lease↔designazione (2026-08-15, decisione di Dev: grace = false) -----
+//
+// L'idoneita' dell'host designato non e' piu' solo «sessione tmux viva»: con
+// remain-on-exit la sessione sopravvive alla morte del supervisore, e la
+// garanzia «l'host designato e' vivo» la puo' dare SOLO il lease (fetta 2b: il
+// leaseId e' FIRMATO nel proof, quindi lo stato del lease identifica senza
+// ambiguita' chi lo detiene). Regole:
+//   - eligible = attiva AND lease 'live'. In grace NON c'e' garanzia: eligible
+//     false, ma host.lease='grace' dice «recupero in corso» — chi legge
+//     distingue «non idonea perche' morta» da «non idonea perche' in recupero».
+//   - I cinque stati (live|grace|expired|none|unavailable) restano DISTINCTI
+//     fino a chi legge: collassarli e' rifare il difetto a un piano piu' su.
+//   - FALLBACK FAIL-OPEN DICHIARATO: senza fleet.lease (installazione senza
+//     lease) eligible torna tmux-only e host.lease='unavailable'. Non e' «va
+//     bene lo stesso»: e' «la garanzia non e' disponibile qui», detto esplicito
+//     perche' un eligible=true silenzioso verrebbe letto come confermata.
+//   - hostCell resta PRESERVATO in ogni caso (invariante dello store): oscilla
+//     l'idoneita', non la scelta dell'operatore.
+function hostLeaseState(fleet, hostCell) {
+  if (hostCell == null) return null;
+  const lease = fleet && fleet.lease;
+  if (!lease || typeof lease.status !== 'function') return 'unavailable';
+  const st = lease.status(hostCell);
+  return (st && typeof st.state === 'string') ? st.state : 'none';
+}
+
+function eligibleOf(fleet, cell, hostCell) {
+  const leaseState = hostLeaseState(fleet, hostCell);
+  if (leaseState === null) return false; // senza soggetto non c'e' idoneita'
+  if (leaseState === 'unavailable') return isActive(cell); // fail-open dichiarato
+  return isActive(cell) && leaseState === 'live';
+}
+
+function liveHostRoutes({ fleetP, store, readonly = () => false, now = () => Date.now(), bridge = null }) {
+  const r = express.Router();
+
+  // GET /api/live-host — { hostCell, revision, eligible, host: {lease}, at }.
+  // hostCell e revision vengono dallo store (preservato); eligible e' la verita'
+  // COMPOSTA roster+lease (si veda hostLeaseState sopra); host.lease espone lo
+  // stato del lease della cella designata, distinto, perche' chi legge distingue.
+  r.get('/', async (_req, res) => {
+    try {
+      const snap = store.snapshot();
+      let eligible = false;
+      let lease = null;
+      if (snap.hostCell != null) {
+        const fleet = await fleetP.catch(() => null);
+        const cells = await localCells(fleetP).catch(() => []);
+        const cell = Array.isArray(cells) ? cells.find((c) => c && c.cell === snap.hostCell) : null;
+        lease = hostLeaseState(fleet, snap.hostCell);
+        eligible = eligibleOf(fleet, cell, snap.hostCell);
+      }
+      res.json({ hostCell: snap.hostCell, revision: snap.revision, eligible, host: { lease }, at: now() });
+    } catch (e) {
+      res.status(500).json({ error: String(e && e.message || e) });
+    }
+  });
+
+  // POST /api/live-host/designate { cellId, expectedRevision }.
+  // expectedRevision e' OBBLIGATORIO e integer (>=0): nessun CAS permissivo, la UI
+  // legge sempre la revision dal GET prima di scrivere (stato iniziale = 0).
+  // cellId deve appartenere al roster locale (federazione default-deny).
+  r.post('/designate', express.json({ limit: '4kb' }), async (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: designazione cella ospite bloccata' });
+    const body = req.body || {};
+    if (Object.keys(body).some((k) => !['cellId', 'expectedRevision'].includes(k))
+      || typeof body.cellId !== 'string' || !CELL_ID_RE.test(body.cellId)
+      || !(Number.isInteger(body.expectedRevision) && body.expectedRevision >= 0)) {
+      return res.status(400).json({ error: 'designazione non valida' });
+    }
+    try {
+      const fleet = await fleetP.catch(() => null);
+      const cells = await localCells(fleetP);
+      if (cells === null) return res.status(503).json({ error: 'fleet non disponibile, riprova' });
+      const cell = cells.find((c) => c && c.cell === body.cellId);
+      if (!cell) return res.status(404).json({ error: 'cella non appartiene a questo nodo' });
+      const result = await store.compareAndSet(body.expectedRevision, body.cellId);
+      if (!result.ok) return res.status(409).json({
+        error: 'revision superata: rileggi e riprova', revision: result.revision, hostCell: result.hostCell,
+      });
+      res.json({
+        hostCell: result.hostCell, revision: result.revision,
+        eligible: eligibleOf(fleet, cell, result.hostCell),
+        host: { lease: hostLeaseState(fleet, result.hostCell) },
+        at: now(),
+      });
+    } catch (e) {
+      res.status(500).json({ error: String(e && e.message || e) });
+    }
+  });
+
+  // POST /api/live-host/clear { expectedRevision } — rimuove la designazione (CAS).
+  r.post('/clear', express.json({ limit: '4kb' }), async (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: rimozione cella ospite bloccata' });
+    const body = req.body || {};
+    if (Object.keys(body).some((k) => k !== 'expectedRevision')
+      || !(Number.isInteger(body.expectedRevision) && body.expectedRevision >= 0)) {
+      return res.status(400).json({ error: 'rimozione non valida' });
+    }
+    try {
+      const result = await store.compareAndSet(body.expectedRevision, null);
+      if (!result.ok) return res.status(409).json({
+        error: 'revision superata: rileggi e riprova', revision: result.revision, hostCell: result.hostCell,
+      });
+      res.json({ hostCell: null, revision: result.revision, at: now() });
+    } catch (e) {
+      res.status(500).json({ error: String(e && e.message || e) });
+    }
+  });
+
+  // POST /api/live-host/bridge — risolve il puntamento per l'avvio di una Live
+  // (fetta 3). La richiesta NON è parametrizzabile: la designazione è la
+  // condizione (LC3) e nessun chiamante può scegliere il target (MC3.4). Il
+  // ponte risponde sempre 200: i `none` con reason sono esiti legittimi e
+  // distinti (nessuna designazione / cella non idonea / fallback), non errori.
+  // Body opzionale e vuoto: un body con campi è un 400, non viene ignorato.
+  r.post('/bridge', express.json({ limit: '1kb' }), async (req, res) => {
+    const body = req.body || {};
+    if (Object.keys(body).length > 0) return res.status(400).json({ error: 'la risoluzione non accetta parametri' });
+    if (readonly()) return res.json({ mode: 'none', reason: 'readonly', at: now() });
+    if (!bridge) return res.status(503).json({ error: 'ponte Live non configurato su questo nodo' });
+    try {
+      const result = await bridge.resolveForLive();
+      res.json(result);
+    } catch (e) {
+      // Il contratto (MC1.5) vuole che un guasto del ponte non fermi la Live:
+      // anche l'inaspettato collassa in `none` dichiarato, mai un 500.
+      // `bridge-error` e' l'ultima rete: un'eccezione che nessun ramo previsto ha
+      // classificato. Va NOMINATA come le altre, non lasciata fuori dall'elenco
+      // — una causa non dichiarata e' una causa che nessuno cerchera'.
+      res.json({ mode: 'none', reason: 'bridge-error', detail: String(e && e.message || e), at: now() });
+    }
+  });
+
+  // Stesso body-error handling di cellsRoutes: payload troppo grande / JSON invalido.
+  r.use((err, _req, res, _next) => {
+    if (err && (err.type === 'entity.too.large' || err.status === 413)) {
+      return res.status(413).json({ error: 'body troppo grande' });
+    }
+    if (err instanceof SyntaxError) return res.status(400).json({ error: 'JSON non valido' });
+    return res.status(err.status || 400).json({ error: String(err.message || err) });
+  });
+
+  return r;
+}
+
+module.exports = { liveHostRoutes };

package/lib/live-host/store.js

@@ -0,0 +1,96 @@
+'use strict';
+// lib/live-host/store.js — stato della designazione "cella ospite Live" di un nodo.
+//
+// Un solo hostCell per nodo (contratto rev6 §2.2): chiave unica, non una convenzione
+// ripetuta in N punti. Lo stato vive su disco (sopravvive a riavvii di cella e di
+// NexusCrew) e l'aggiornamento e' un CAS su `revision`: due designazioni concorrenti
+// non possono lasciare due celle rosse — il perdente rilegge la revision e rinuncia.
+//
+// La designazione e' PURAMENTE un marker di scelta del nodo. L'eligibilita' (la cella
+// e' anche attiva in questo momento?) e' derivata dal roster Fleet e non si persiste
+// qui: `active` resta `sessions.has(tmuxSession)` (runtime.js), la marcatura non lo
+// tocca. Una cella spenta PRESERVA la designazione — resta hostCell, semplicemente
+// ineligible finche' non torna attiva.
+
+const path = require('node:path');
+const os = require('node:os');
+const { readJsonSafe, atomicWriteJson } = require('../notify/persist.js');
+
+const CELL_ID_RE = /^[A-Za-z0-9._-]{1,32}$/;
+
+// Path del file di stato: override esplicito -> dir del token (~/.nexuscrew) -> home.
+// Stessa convenzione di consentPath/groupsPath, cosi' i test isolano lo stato via
+// cfg.tokenPath senza toccare la home reale.
+function liveHostPath(cfg = {}, home = (cfg.home || os.homedir())) {
+  if (cfg.liveHostPath) return cfg.liveHostPath;
+  if (cfg.tokenPath) return path.join(path.dirname(cfg.tokenPath), 'live-host.json');
+  return path.join(home, '.nexuscrew', 'live-host.json');
+}
+
+// Normalizza il grezzo letto da disco in {revision, hostCell}. Un file assente o
+// garbage (readJsonSafe -> {}) e' lo stato iniziale legittimo {0, null}; un hostCell
+// non-string o fuori formato viene chiuso a null senza promuovere garbage.
+function normalize(raw) {
+  const revision = raw && Number.isInteger(raw.revision) && raw.revision >= 0 ? raw.revision : 0;
+  const hostCell = raw && typeof raw.hostCell === 'string' && CELL_ID_RE.test(raw.hostCell)
+    ? raw.hostCell : null;
+  return { revision, hostCell };
+}
+
+function readLiveHost(filePath) {
+  return normalize(readJsonSafe(filePath));
+}
+
+// createLiveHostStore({filePath, now}) — CAS store.
+//
+// read+compare+write sono sincroni, ma le route sono async e due richieste concorrenti
+// possono entrambe aver letto la stessa revision prima che una delle due scriva. La
+// promise-chain serializza la sezione read-modify-write: nessun await dentro la
+// callback, quindi il check e la scrittura sono una sola transazione atomica rispetto
+// agli altri CAS in volo. Esattamente uno dei due CAS concorrenti avanza la revision.
+function createLiveHostStore({ filePath, now = () => Date.now() } = {}) {
+  if (!filePath || typeof filePath !== 'string') {
+    throw new Error('createLiveHostStore: filePath richiesto');
+  }
+  let chain = Promise.resolve();
+
+  function serialize(fn) {
+    const run = chain.then(fn);
+    // La catena non si rompe mai su un errore di un CAS: un fallimento non deve
+    // bloccare i successivi (un CAS che lancia risolve comunque il run).
+    chain = run.then(() => {}, () => {});
+    return run;
+  }
+
+  // Snapshot read-only corrente (dopo normalizzazione).
+  function snapshot() {
+    return readLiveHost(filePath);
+  }
+
+  // CAS: scrive nextHostCell (stringa valida | null) solo se la revision corrente
+  // coincide con expectedRevision. Ritorna:
+  //   { ok:true, revision:<nuova>, hostCell:<nuovo>, at }
+  //   { ok:false, conflict:true, revision:<corrente>, hostCell:<corrente> }
+  // Fail-closed: expectedRevision deve essere un integer che coincide con la
+  // revision corrente. Uno expected non-integer (es. undefined) NON e' un
+  // lasciapassare: e' un conflitto. Lo stato iniziale e' revision 0 ed e'
+  // conoscibile (la UI lo legge dal GET), quindi non esiste un "primo scrittore
+  // senza revision" legittimo: l'assenza del campo va rifiutata, non tollerata.
+  function compareAndSet(expectedRevision, nextHostCell) {
+    return serialize(() => {
+      const cur = readLiveHost(filePath);
+      if (!Number.isInteger(expectedRevision) || cur.revision !== expectedRevision) {
+        return { ok: false, conflict: true, revision: cur.revision, hostCell: cur.hostCell };
+      }
+      const hostCell = nextHostCell === null ? null
+        : (typeof nextHostCell === 'string' && CELL_ID_RE.test(nextHostCell) ? nextHostCell : null);
+      const revised = { revision: cur.revision + 1, hostCell, updatedAt: now() };
+      atomicWriteJson(filePath, revised);
+      return { ok: true, revision: revised.revision, hostCell: revised.hostCell, at: revised.updatedAt };
+    });
+  }
+
+  return { snapshot, compareAndSet, filePath };
+}
+
+module.exports = { createLiveHostStore, liveHostPath, readLiveHost, normalize, CELL_ID_RE };

package/lib/mcp/tools.js

@@ -863,6 +863,57 @@ const TOOLS = [
       return { receipt };
     },
   },
+  // --- lease Live del child (fetta 2b, contratto rev1 B5) ----------------------
+  // Tre metodi DISTINTI perche' i valori di ritorno non mentono l'uno con l'altro:
+  // solo register puo' rispondere {status:'pending'} (join non ancora tracciato);
+  // refresh su registration viva risponde {status:'live', proof} e non ha stati
+  // pendenti; recovery riprende la STESSA incarnazione con un proof scaduto da
+  // poco. L'authorizer di refresh/recovery e' il proof HMAC firmato dal verifier
+  // per-installazione del server; la cella e' la sessione del chiamante.
+  {
+    name: 'nc_lease_register',
+    description: 'Registra questa cella al lease Live del nodo: crea una registration con incarnationId propria e consegna il primo proof child. Risponde {status:"pending"} se la cella non e\' ancora tracciata dal lease del supervisore: riprova dopo retryAfterMs.',
+    inputSchema: { type: 'object', properties: {} },
+    async handler(_args, ctx) {
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_lease_register', identity.code);
+      return ctx.api('POST', '/api/lease/register', { session });
+    },
+  },
+  {
+    name: 'nc_lease_refresh',
+    description: 'Rinnova la registration child presentando l\'ultimo proof detenuto: risponde {status:"live"} con un proof nuovo. Mai pending: senza registration risponde {status:"no-registration"} (usa nc_lease_register).',
+    inputSchema: {
+      type: 'object',
+      properties: { proof: { type: 'object', description: 'ultimo proof ricevuto (register o refresh precedente), tale e quale' } },
+      required: ['proof'],
+    },
+    async handler(args, ctx) {
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_lease_refresh', identity.code);
+      const proof = args.proof && typeof args.proof === 'object' && !Array.isArray(args.proof)
+        ? args.proof : null;
+      if (!proof) throw new Error('parametro "proof" obbligatorio (oggetto ricevuto da register/refresh)');
+      return ctx.api('POST', '/api/lease/refresh', { session, proof });
+    },
+  },
+  {
+    name: 'nc_lease_recovery',
+    description: 'Riprende la registration child dopo un gap: presenta l\'ultimo proof (accettato anche scaduto da poco) e riceve un proof nuovo con la STESSA incarnazione. Ogni presentazione conta come attempt: oltre il cap serve nc_lease_register.',
+    inputSchema: {
+      type: 'object',
+      properties: { proof: { type: 'object', description: 'ultimo proof detenuto, anche scaduto da poco' } },
+      required: ['proof'],
+    },
+    async handler(args, ctx) {
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_lease_recovery', identity.code);
+      const proof = args.proof && typeof args.proof === 'object' && !Array.isArray(args.proof)
+        ? args.proof : null;
+      if (!proof) throw new Error('parametro "proof" obbligatorio (oggetto ricevuto in precedenza)');
+      return ctx.api('POST', '/api/lease/recovery', { session, proof });
+    },
+  },
 ];
 
 module.exports = {

package/lib/nodes/commands.js

@@ -279,15 +279,22 @@ function nodesEdit(opts) {
   // Lo scope celle vale per QUALUNQUE peer accoppiato, in entrambe le
   // direzioni: riguarda chi accede alle celle di questo nodo, non chi ha
   // aperto il tunnel.
+  // `panelAccess` segue la stessa regola dello scope celle: riguarda chi accede
+  // ai PANNELLI di questo nodo, non chi ha aperto il tunnel — quindi vale in
+  // entrambe le direzioni.
   const allowed = node.direction === 'inbound'
-    ? new Set(['label', 'visibility', 'selected', 'cellVisibility', 'cells'])
-    : new Set(['label', 'ssh', 'sshPort', 'autostart', 'cellVisibility', 'cells']);
+    ? new Set(['label', 'visibility', 'selected', 'cellVisibility', 'cells', 'panelAccess'])
+    : new Set(['label', 'ssh', 'sshPort', 'autostart', 'cellVisibility', 'cells', 'panelAccess']);
   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 (Object.hasOwn(supplied, 'panelAccess') && typeof supplied.panelAccess !== 'boolean') {
+    log('nodes edit: panelAccess vuole un booleano');
+    return { code: 1, reason: 'invalid-panel-access' };
+  }
   if (keys.length === 0) { log('nodes edit: nessuna modifica richiesta'); return { code: 1, reason: 'empty-patch' }; }
   const patch = { ...supplied };
   if (Object.hasOwn(patch, 'label')) {

package/lib/nodes/store.js

@@ -112,6 +112,13 @@ const NODE_KEYS = new Set([
   // Quali CELLE di questo nodo il peer puo' vedere. Distinto da `visibility`,
   // che governa il TRANSITO (attraverso chi passa il traffico) e non l'accesso.
   'cellVisibility', 'cells',
+  // Se questo peer puo' aprire i PANNELLI delle celle di questo nodo. Distinto
+  // da `cellVisibility`, che dice quali celle il peer VEDE: dietro un pannello
+  // c'e' un browser con sessioni gia' autenticate, e un accesso di quel tipo non
+  // si revoca cambiando una chiave. Il resto del modello tratta un peer pairato
+  // come l'operatore stesso; qui no, e di proposito: default NEGATO, si concede
+  // per singolo nodo.
+  'panelAccess',
   // Identita' crittografica del peer — passo 1 del modello di autorita'. Oggi
   // NON governa niente: si osserva e si registra. `keySource` distingue una
   // chiave legata al pairing (nello stesso atto in cui si e' deciso di fidarsi)
@@ -257,6 +264,11 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
     // requests the optional reverse (-R) channel. Old stores therefore migrate
     // safely to private without a schema bump.
     shared: n.shared === undefined ? false : n.shared,
+    // Default negato: un record esistente, scritto quando questo campo non
+    // c'era, NON acquisisce l'accesso ai pannelli per il fatto di essere gia'
+    // pairato. Migrazione silenziosa verso il permesso e' esattamente cio' che
+    // non deve succedere.
+    panelAccess: n.panelAccess === undefined ? false : n.panelAccess,
     visibility: n.visibility || 'network',
   };
   if (!['auto', 'ssh', 'autossh', 'inbound'].includes(out.transport)) return null;
@@ -264,6 +276,7 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
   if (direction === 'outbound' && out.transport === 'inbound') return null;
   if (typeof out.autostart !== 'boolean') return null;
   if (typeof out.shared !== 'boolean') return null;
+  if (typeof out.panelAccess !== 'boolean') return null;
   if (!['network', 'relay-only', 'selected'].includes(out.visibility)) return null;
   if (identityFile) out.identityFile = identityFile;
   // Keep the old public field while reading v1 so old callers/tests and a
@@ -645,6 +658,7 @@ function redactNode(n) {
     transport: n.transport || 'ssh',
     autostart: !!n.autostart,
     shared: n.shared === true,
+    panelAccess: n.panelAccess === true,
     visibility: n.visibility || 'network',
     hasToken: !!n.token, // presenza, non il valore
     paired: !!(n.token && n.acceptToken),

package/lib/nodes/tunnel.js

@@ -568,7 +568,10 @@ function startTunnel(opts) {
   let pid = child && child.pid;
   const cleanupIfOwned = () => {
     const current = pidf.readPidfile(pidPath);
-    if (current && current.pid === pid && current.runId === runId) pidf.removePidfile(pidPath);
+    // allowLive: la garanzia e' il match pid+runId del NOSTRO spawn — il pidfile
+    // e' quello che questa via ha appena scritto per un figlio suo, che in questi
+    // rami d'errore e' stato appena segnato o non e' mai partito.
+    if (current && current.pid === pid && current.runId === runId) pidf.removePidfile(pidPath, { allowLive: true });
     removeStateIfOwned(home, name, { pid, runId });
   };
   if (child && typeof child.on === 'function') {

package/lib/proxy/federation.js

@@ -13,6 +13,7 @@ const {
   sanitizeRequestHeaders, sanitizeResponseHeaders, stripLocalTokenQuery,
 } = require('./node-proxy.js');
 const { signHop, HOP_HEADER } = require('./hop-proof.js');
+const { COOKIE_NAME: PANEL_COOKIE_NAME } = require('./panel-auth.js');
 
 const MAX_HOPS = 4;
 const ROUTE_DELIMITER = '_';
@@ -185,10 +186,32 @@ function knownResource(resource) {
     // significava poter creare a distanza un engine che non si puo' rendere
     // avviabile a distanza — un'asimmetria che rompeva la modifica remota a
     // meta' strada, senza proteggere nulla.
+    || isPanelResource(resource)
     || /^\/fleet\/(status|schema|definitions|credentials\/status|credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-model|remove-model|model-test|define-cell|edit-cell|remove-cell|restore-cells|restore-engines)$/.test(resource);
 }
 
+// Il pannello di una cella e' l'unica risorsa federata con un gate PER-PEER a
+// default negato, e la ragione e' cosa c'e' dietro: un browser con sessioni gia'
+// autenticate. Il resto del modello tratta un peer pairato come l'operatore
+// stesso (docs/SECURITY.md), qui no.
+//
+// Forma: /panel/<cellId>/<path arbitrario>. E' la prima risorsa federata che
+// apre un sottoalbero invece di un endpoint chiuso — un pannello serve HTML, JS
+// e asset suoi — e proprio per questo il gate va valutato PRIMA dell'allowlist:
+// `canTransit` decide chi puo' ATTRAVERSARE questo nodo, non chi puo' aprire un
+// pannello.
+const PANEL_RESOURCE_RE = /^\/panel\/[A-Za-z0-9._-]{1,32}(?:\/.*)?$/;
+function isPanelResource(resource) { return PANEL_RESOURCE_RE.test(resource); }
+
+// `ingress` nullo = richiesta del proprietario di questo nodo (localRouter non
+// lo passa mai): nessun gate. Da un peer, serve il permesso esplicito.
+function panelAllowedFor(ingress) {
+  if (!ingress) return true;
+  return ingress.panelAccess === true;
+}
+
 function allowedResource(resource, method = 'GET') {
+  if (isPanelResource(resource)) return method === 'GET' || method === 'POST';
   if (resource === '/sessions') return method === 'GET' || method === 'POST';
   if (/^\/sessions\/[\w.@%:+-]{1,128}$/.test(resource)) return method === 'DELETE';
   if (/^\/sessions\/[\w.@%:+-]{1,128}\/visibility$/.test(resource)) return method === 'PATCH';
@@ -263,7 +286,34 @@ function allowedQuery(resource, method, rawUrl) {
   return true;
 }
 
-function cleanHeaders(headers, credential, visited = null, hopProof = null) {
+// Il cookie di visione del pannello (`npanel`) e' l'UNICO cookie che attraversa
+// la federazione, e solo sulle panel-resource.
+//
+// Perche' deve passare: le sotto-risorse dentro l'iframe sono URL RELATIVI senza
+// query — il cookie e' l'unico modo che hanno di dire chi sono — e a
+// riconoscerlo e' il nodo PROPRIETARIO, l'unico che lo ha emesso. Senza questo,
+// il pannello remoto serve la pagina e poi nient'altro: un frame che sembra
+// caricato e resta vuoto. (Finche' il Bearer dell'hop apriva tutto il difetto
+// non si vedeva: i test lo attribuivano al cookie, che non arrivava mai.)
+//
+// Perche' SOLO questo: `sanitizeRequestHeaders` toglie l'intero header cookie, e
+// giustamente — i cookie del browser sono della nostra origine e verso un altro
+// nodo non significherebbero nulla. Qui si reintroduce un valore solo, opaco,
+// per-cella e a scadenza breve, che il destinatario ha emesso lui stesso.
+function panelViewCookie(headers) {
+  const raw = headers && (headers.cookie || headers.Cookie);
+  const source = Array.isArray(raw) ? raw.join('; ') : String(raw || '');
+  for (const part of source.split(';')) {
+    const i = part.indexOf('=');
+    if (i <= 0) continue;
+    if (part.slice(0, i).trim() !== PANEL_COOKIE_NAME) continue;
+    const value = part.slice(i + 1).trim();
+    return value ? `${PANEL_COOKIE_NAME}=${value}` : null;
+  }
+  return null;
+}
+
+function cleanHeaders(headers, credential, visited = null, hopProof = null, panelCookie = null) {
   const out = sanitizeRequestHeaders(headers, credential);
   for (const key of Object.keys(out)) {
     if (['x-nexuscrew-route', 'x-nexuscrew-visited', 'x-nexuscrew-hop'].includes(key.toLowerCase())) delete out[key];
@@ -272,12 +322,31 @@ function cleanHeaders(headers, credential, visited = null, hopProof = null) {
   // La prova di hop viene aggiunta DOPO la cancellazione: il canale e' riservato
   // al server, un valore arrivato dal client non sopravvive mai fin qui.
   if (hopProof) out[HOP_HEADER] = hopProof;
+  // Come sopra: dopo lo strip, e mai per risorse che non siano il pannello.
+  if (panelCookie) out.cookie = panelCookie;
   return out;
 }
 
-function proxyHttp(req, res, { port, path, credential, visited = null, hopProof = null }) {
-  const up = http.request({ host: '127.0.0.1', port, method: req.method, path, headers: cleanHeaders(req.headers, credential, visited, hopProof) }, (r) => {
-    res.writeHead(r.statusCode, sanitizeResponseHeaders(r.headers)); r.pipe(res);
+// Riscrittura dei Set-Cookie verso il chiamante locale (il browser della PWA).
+// Il pannello remoto emette il cookie di visione con `Path=/api/panel/<cella>`:
+// quel path e' GIUSTO sul nodo che lo emette, ma il browser ha richiesto
+// `/api/route/<nodi>/_/panel/...` — senza riscrittura il cookie non coprirebbe
+// le sotto-risorse dell'iframe remoto e il frame resterebbe bianco con l'aria
+// di funzionare. Si riscrive SOLO il prefisso `/api` in `/api/route/<nodi>/_`,
+// il resto dell'ambito (per-cella) resta quello deciso dal nodo che lo emette.
+function rewriteSetCookiePath(headers, prefix) {
+  const raw = headers['set-cookie'];
+  if (!raw) return headers;
+  const out = { ...headers };
+  out['set-cookie'] = (Array.isArray(raw) ? raw : [raw])
+    .map((line) => String(line).replace(/([Pp]ath=)\/api\//, `$1${prefix}/`));
+  return out;
+}
+
+function proxyHttp(req, res, { port, path, credential, visited = null, hopProof = null, setCookiePrefix = null, panelCookie = null }) {
+  const up = http.request({ host: '127.0.0.1', port, method: req.method, path, headers: cleanHeaders(req.headers, credential, visited, hopProof, panelCookie) }, (r) => {
+    const headers = setCookiePrefix ? rewriteSetCookiePath(r.headers, setCookiePrefix) : r.headers;
+    res.writeHead(r.statusCode, sanitizeResponseHeaders(headers)); r.pipe(res);
   });
   up.setTimeout(30000, () => up.destroy());
   up.on('error', () => { if (!res.headersSent) res.status(502).json({ error: 'peer non raggiungibile' }); else res.destroy(); });
@@ -287,6 +356,11 @@ function proxyHttp(req, res, { port, path, credential, visited = null, hopProof
 function routeHandler({ nodesPath, localPort, localCredential, ingress = null, readonly = () => false, hopSecret = null }) {
   return (req, res) => {
     const parsed = parseRoute(req.url);
+    // Prima dell'allowlist: un peer senza permesso non deve nemmeno sapere se la
+    // risorsa esiste per una cella o per un'altra.
+    if (parsed && isPanelResource(parsed.resource) && !panelAllowedFor(ingress)) {
+      return res.status(403).json({ error: 'pannello non concesso a questo nodo', reason: 'panel-not-granted' });
+    }
     if (!parsed || !allowedResource(parsed.resource, req.method)
       || !allowedQuery(parsed.resource, req.method, req.url)) return res.status(404).json({ error: 'not found' });
     if (readonly() && readonlyBlocksFederated(parsed.resource, req.method)) return res.status(403).json({ error: 'READONLY: federated mutation blocked' });
@@ -294,6 +368,9 @@ function routeHandler({ nodesPath, localPort, localCredential, ingress = null, r
     if (!st) return res.status(503).json({ error: 'node store unavailable' });
     const visited = controlledVisited(req, ingress, st.nodeId);
     if (!visited) return res.status(409).json({ error: 'federation cycle rejected' });
+    // Vale per l'ultimo hop come per il transito: se si fermasse al primo, una
+    // route a due salti servirebbe la pagina e nessuna delle sue risorse.
+    const panelCookie = isPanelResource(parsed.resource) ? panelViewCookie(req.headers) : null;
     if (parsed.route.length === 0) {
       // Ultimo hop: la richiesta rientra nell'API locale con il Bearer locale e
       // da li' in poi sarebbe indistinguibile da un POST diretto. La prova di
@@ -306,6 +383,7 @@ function routeHandler({ nodesPath, localPort, localCredential, ingress = null, r
         credential: localCredential(),
         visited,
         hopProof: signHop(secret, { method: req.method, path, visited }),
+        panelCookie,
       });
     }
     const next = st && store.getNode(st, parsed.route[0]);
@@ -313,7 +391,14 @@ function routeHandler({ nodesPath, localPort, localCredential, ingress = null, r
     if (!next || !next.token || privateInbound || (ingress && !canTransit(ingress, next))) return res.status(403).json({ error: 'route non consentita' });
     const rest = parsed.route.slice(1);
     const path = `/federation/route/${rest.length ? `${rest.join('/')}/` : ''}${ROUTE_DELIMITER}${parsed.resource}${queryOf(req.url)}`;
-    proxyHttp(req, res, { port: next.localPort, path, credential: next.token, visited });
+    // Verso il browser di questo nodo (ingress nullo) il cookie di visione del
+    // pannello va riscritto col prefisso federato che il browser sta usando:
+    // vedi rewriteSetCookiePath. Da un peer in transito non si tocca — la
+    // riscrittura spetta all'hub dove il browser è collegato.
+    const setCookiePrefix = !ingress && isPanelResource(parsed.resource)
+      ? `/api/route/${parsed.route.join('/')}/${ROUTE_DELIMITER}`
+      : null;
+    proxyHttp(req, res, { port: next.localPort, path, credential: next.token, visited, setCookiePrefix, panelCookie });
   };
 }
 
@@ -1157,19 +1242,26 @@ function localRouter({ nodesPath, localPort, localCredential, readonly, hopSecre
 function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredential, ingress, readonly = () => false, activeSockets = null, hopSecret = null }) {
   if (readonly()) return reject(socket, 403);
   const parsed = parseRoute(req.url.replace(/^\/(?:api\/route|federation\/route)/, ''));
-  if (!parsed || parsed.resource !== '/ws') return reject(socket, 404);
+  // Due percorsi separati: questo NON passa da routeHandler e non ne condivide i
+  // controlli. Un gate scritto solo di la' sarebbe una porta chiusa accanto a una
+  // aperta — e per un pannello la porta aperta e' l'unica che conta, perche' i
+  // frame arrivano da qui.
+  if (!parsed || (parsed.resource !== '/ws' && !isPanelResource(parsed.resource))) return reject(socket, 404);
+  if (isPanelResource(parsed.resource) && !panelAllowedFor(ingress)) return reject(socket, 403);
   const st = store.loadStore(nodesPath);
   if (!st) return reject(socket, 503);
   const visited = controlledVisited(req, ingress, st.nodeId);
   if (!visited) return reject(socket, 409);
-  let port = typeof localPort === 'function' ? localPort() : localPort; let credential = localCredential(); let path = '/ws';
+  let port = typeof localPort === 'function' ? localPort() : localPort; let credential = localCredential();
+  // Ultimo hop: `/ws` entra com'e', il pannello rientra nell'API locale.
+  let path = parsed.resource === '/ws' ? '/ws' : `/api${parsed.resource}`;
   if (parsed.route.length) {
     const next = store.getNode(st, parsed.route[0]);
     const privateInbound = next && next.direction === 'inbound' && next.shared !== true;
     if (!next || !next.token || privateInbound || (ingress && !canTransit(ingress, next))) return reject(socket, 403);
     port = next.localPort; credential = next.token;
     const rest = parsed.route.slice(1);
-    path = `/federation/route/${rest.length ? `${rest.join('/')}/` : ''}${ROUTE_DELIMITER}/ws`;
+    path = `/federation/route/${rest.length ? `${rest.join('/')}/` : ''}${ROUTE_DELIMITER}${parsed.resource}`;
   }
   const up = net.connect({ host: '127.0.0.1', port });
   up.once('connect', () => {
@@ -1184,7 +1276,11 @@ function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredenti
     const hopProof = !parsed.route.length && secret
       ? signHop(secret, { method: req.method || 'GET', path, visited })
       : null;
-    const headers = cleanHeaders(req.headers, credential, visited, hopProof);
+    // Il cookie di visione serve QUI quanto sull'HTTP: la WebSocket del
+    // pannello parte dalla pagina dentro il frame, e senza cookie il frame
+    // carica e resta nero.
+    const panelCookie = isPanelResource(parsed.resource) ? panelViewCookie(req.headers) : null;
+    const headers = cleanHeaders(req.headers, credential, visited, hopProof, panelCookie);
     const lines = [`GET ${path} HTTP/1.1`, `Host: 127.0.0.1:${port}`];
     for (const [k, v] of Object.entries(headers)) lines.push(`${k}: ${Array.isArray(v) ? v.join(', ') : v}`);
     lines.push('Connection: Upgrade', 'Upgrade: websocket', '', '');
@@ -1202,6 +1298,7 @@ function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredenti
 function reject(socket, code) { try { socket.end(`HTTP/1.1 ${code} Error\r\nConnection: close\r\n\r\n`); } catch (_) {} }
 
 module.exports = {
+  isPanelResource, panelAllowedFor, routeHandler,
   MAX_HOPS, ROUTE_DELIMITER, TOPOLOGY_PEER_TIMEOUT_MS, SHARE_NOT_READY_CODE, classifyShareFailure, activeReversePort,
   peerFromToken, peerAllows, canTransit, parseRoute, knownResource, allowedResource, allowedQuery, readonlyBlocksFederated,
   collectTopology, collectTopologyDetailed, collectLocalTopology, peerRouter, localRouter, forwardUpgrade,