@mmmbuto/nexuscrew 0.8.57 → 0.9.0

package/lib/proxy/node-proxy.js

@@ -32,6 +32,26 @@ const CONNECT_TIMEOUT_MS = 10000;
 // Metodi che mutano stato sul nodo remoto: bloccati sotto NEXUSCREW_READONLY locale.
 const MUTATING = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 
+// Path LOCAL-ONLY: non attraversano MAI la federazione via /node/<name>. La
+// designazione "cella ospite Live" e' un'azione del nodo stesso: nessun peer puo'
+// designare una cella di questo nodo da remoto (federazione default-deny). Il
+// browser parla con /api/live-host solo sul proprio loopback.
+// `/api/panel` e' local-only per la stessa ragione, piu' una sua: dietro c'e' un
+// browser con sessioni gia' autenticate, e un peer pairato non deve poterlo
+// aprire per il solo fatto di essere pairato. L'accesso dai nodi del proprietario
+// passera' dalla via allowlistata della federazione, mai da questo pass-through
+// generico — che inoltra QUALSIASI path non elencato qui.
+// `/api/route` e `/federation/route` sono qui per una ragione che e' costata un
+// audit: l'origine di una richiesta veniva dedotta dal PATH. Su /api/route il
+// gestore assume di parlare col proprietario e non applica gate per-peer; ma un
+// peer poteva farci arrivare quella forma ATTRAVERSO questo stesso pass-through
+// (/node/<A>/api/route/_/panel/<cella>/...), e a quel punto il nodo di
+// destinazione la vedeva come richiesta locale — con il gate del pannello
+// saltato. La catena di inoltro ha gia' un canale suo (/api/route con i suoi
+// hop): passare da qui era un secondo percorso per la stessa cosa, ed e' la
+// forma di difetto che continuiamo a trovare.
+const LOCAL_ONLY_PREFIXES = ['/api/live-host', '/api/panel', '/api/route', '/federation/route'];
+
 // Hop-by-hop (RFC 7230 §6.1) + Proxy-*: mai inoltrati end-to-end.
 const HOP_BY_HOP = new Set([
   'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
@@ -88,6 +108,15 @@ function isTransitiveRest(rest) {
   return false;
 }
 
+// Un path local-only non e' instradabile via /node, neanche in lettura: il proxy lo
+// chiude prima di resolveNode. Controlla raw e decodificato, come isTransitiveRest.
+function isLocalOnly(rest) {
+  const hit = (p) => LOCAL_ONLY_PREFIXES.some((px) => p === px || p.startsWith(`${px}/`));
+  if (hit(rest)) return true;
+  try { if (hit(decodeURIComponent(rest))) return true; } catch (_) { /* malformed: raw basta */ }
+  return false;
+}
+
 // Headers per l'HTTP upstream: strip client-supplied pericolosi, inietta il token
 // del nodo. host lo mette node http.request da host/port (loopback da config).
 function sanitizeRequestHeaders(headers, remoteToken) {
@@ -127,6 +156,9 @@ function createNodeProxy(deps) {
     if (!parsed) return notFound(res);                       // §4b(2)#2 no name
     if (!NODE_NAME_RE.test(parsed.name)) return notFound(res); // §4b(2)#2 strict/traversal
     if (isTransitiveRest(parsed.rest)) return notFound(res);   // §4b(2)#7 no transitive
+    if (isLocalOnly(parsed.rest)) {
+      return res.status(403).json({ error: 'local-only: azione non instradabile via federazione' });
+    }
     const node = resolveNode(parsed.name);
     if (!node) return notFound(res);                           // nome non in config -> 404 secco
     if (readonly() && MUTATING.has(req.method)) {
@@ -242,6 +274,7 @@ function handleNodeUpgrade(ctx) {
   const parsed = splitNodePath(afterNode);
   if (!parsed || !NODE_NAME_RE.test(parsed.name)) return abortUpgrade(socket, 404);
   if (isTransitiveRest(parsed.rest)) return abortUpgrade(socket, 404);
+  if (isLocalOnly(parsed.rest)) return abortUpgrade(socket, 403);
   const node = resolveNode(parsed.name);
   if (!node) return abortUpgrade(socket, 404);
 

package/lib/proxy/panel-auth.js

@@ -0,0 +1,307 @@
+'use strict';
+// lib/proxy/panel-auth.js — l'ingresso al pannello: ticket monouso + cookie di visione.
+//
+// Perche' esiste (misurato, non ipotizzato — vedi la misura dell'iframe che
+// non puo' autenticarsi, 2026-08-15): un `<iframe src>` e' una navigazione del
+// browser e non porta header applicativi. Il proxy del pannello sta dietro
+// requireToken, che accetta solo `Authorization: Bearer`: l'unico
+// consumatore previsto non puo' entrare. E accettare il token in query non
+// basterebbe: la pagina del pannello chiede le proprie risorse con URL
+// relativi, senza query — cadrebbero tutte, e il frame resterebbe bianco.
+//
+// Il disegno, in quattro punti che sono vincoli e non preferenze:
+//
+// 1. IL TICKET NON E' IL TOKEN DEL NODO. Lo chiede la PWA, che e' gia'
+//    autenticata col Bearer; e' opaco, monouso, vive pochi secondi e vale per
+//    UNA cella. Il token del nodo non deve finire nella cronologia del
+//    browser, nei log del proxy o in un Referer.
+// 2. IL TICKET SI CONSUMA ALLA PRIMA RICHIESTA e la risposta imposta un cookie
+//    HttpOnly SameSite Strict con `Path=/api/panel/<cella>` — ESATTAMENTE quel
+//    path, perche' le sotto-risorse relative passino e nient'altro.
+// 3. IL COOKIE NON E' UN'AUTENTICAZIONE DELL'ORIGINE. Il progetto non ne ha
+//    una, e introdurla aprirebbe CSRF su tutte le altre route: qui si verifica
+//    SEMPRE che il cookie sia stato emesso per la cella del path, e lo scope
+//    stretto e' presidiato dai test — un cookie con Path piu' largo o un
+//    ticket riusabile devono FAR FALLIRE un test, non passare inosservati.
+// 4. NIENTE CREDENZIALI VERSO IL PANNELLO: il cookie non viene inoltrato
+//    upstream (lo strip fa' panel-proxy, come l'Authorization), e `Referer`
+//    va tolto dagli header inoltrati insieme agli altri.
+
+// 5. IL BEARER DEL NODO NON VALE SULLA VIA FEDERATA. L'ultimo hop rientra
+//    nell'API locale col Bearer locale e da li' in poi e' indistinguibile
+//    dalla PWA: senza questo confine il contenuto del pannello esce verso
+//    ogni peer con `panelAccess`, senza che nessuno abbia mai preso un
+//    ticket. La prova di hop (lib/proxy/hop-proof.js) e' cio' che distingue
+//    le due provenienze. Chiuso il 2026-08-15; i due casi cattivi stanno in
+//    tests/panel-auth-live.test.js e devono restare l'unico modo di provarlo.
+
+const crypto = require('node:crypto');
+const { CELL_ID_RE } = require('../live-host/store.js');
+const { validPanelUrl } = require('../fleet/definitions.js');
+const { verifyHop, HOP_HEADER } = require('./hop-proof.js');
+
+const VISITED_HEADER = 'x-nexuscrew-visited';
+
+const TICKET_TTL_MS = 30 * 1000;         // "pochi secondi": la vita di un redirect iframe
+const COOKIE_TTL_MS = 60 * 60 * 1000;    // una sessione di visione
+const COOKIE_NAME = 'npanel';
+
+// Ticket e cookie non si confrontano: si CERCANO per chiave in una Map, e il
+// valore e' un segreto casuale da 256 bit. Non c'e' quindi un compare da
+// rendere costante — una funzione che lo promettesse senza avere chiamanti
+// sarebbe una garanzia scritta e mai mantenuta.
+function newSecret() {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+function parseCookieHeader(header) {
+  const out = {};
+  for (const part of String(header || '').split(';')) {
+    const i = part.indexOf('=');
+    if (i <= 0) continue;
+    out[part.slice(0, i).trim()] = part.slice(i + 1).trim();
+  }
+  return out;
+}
+
+// `<cella>` da `/api/panel/<cella>/<rest>` (o `/panel/...` gia' smontato).
+function cellFromPanelPath(url) {
+  const raw = String(url || '');
+  const pathname = raw.slice(0, raw.indexOf('?') === -1 ? raw.length : raw.indexOf('?'));
+  const first = pathname.split('/').filter(Boolean)[0];
+  if (!first) return null;
+  try { return decodeURIComponent(first); } catch (_) { return null; }
+}
+
+function createPanelAuth({
+  verifyToken,                       // (value) => bool, sul token del nodo
+  resolveCellPanel,                  // (cellId) => Promise<panelUrl|null|undefined|''>
+  now = () => Date.now(),
+  ticketTtlMs = TICKET_TTL_MS,
+  cookieTtlMs = COOKIE_TTL_MS,
+  hopSecret = null,                  // () => Buffer|string|null, segreto per-processo
+  log = () => {},
+} = {}) {
+  const tickets = new Map();   // ticket -> { cell, exp }
+  const cookies = new Map();   // cookieToken -> { cell, exp }
+
+  // —— Da dove arriva questa richiesta? La risposta decide se il Bearer del
+  // NODO vale, e non e' una preferenza: e' il confine descritto al punto 5.
+  //
+  // Tre esiti, e il terzo e' fail-closed:
+  //   'locale'   — nessun header di hop: il Bearer vale come e' sempre valso.
+  //   'federata' — hop VERIFICATA: la richiesta e' l'ultimo salto di una route
+  //                federata. Il Bearer qui e' quello che il proxy ha iniettato
+  //                da se', quindi non prova nulla su CHI guarda: per vedere il
+  //                pannello servono il ticket o il cookie emessi da QUESTO nodo.
+  //   'sospetta' — header presente ma non verificabile (segreto assente, catena
+  //                vuota, firma che non torna). Non si indovina: si rifiuta.
+  //
+  // La catena `visited` serve solo a ricostruire il messaggio firmato: qui
+  // interessa RILEVARE il transito, non attribuirne l'origine — quello e' il
+  // mestiere di lib/audio/origin.js, che infatti la valida anche contro il
+  // nodo locale.
+  function hopKind(req) {
+    const headers = (req && req.headers) || {};
+    const proof = headers[HOP_HEADER];
+    if (!proof) return 'locale';
+    const secret = typeof hopSecret === 'function' ? hopSecret() : hopSecret;
+    if (!secret) return 'sospetta';
+    const visited = String(headers[VISITED_HEADER] || '').split(',').filter(Boolean);
+    if (!visited.length) return 'sospetta';
+    // Il path firmato e' quello con cui la richiesta e' ENTRATA nell'API
+    // (`/api/panel/...`), non il resto che il mount di express lascia in
+    // req.url: sotto un `use('/api/panel')` i due differiscono.
+    const path = req.originalUrl || req.url;
+    const ok = verifyHop(secret, { method: req.method || 'GET', path, visited }, proof);
+    return ok ? 'federata' : 'sospetta';
+  }
+
+  function sweep() {
+    const t = now();
+    for (const [k, rec] of tickets) if (rec.exp <= t) tickets.delete(k);
+    for (const [k, rec] of cookies) if (rec.exp <= t) cookies.delete(k);
+  }
+
+  function issueTicket(cellId) {
+    sweep();
+    const ticket = newSecret();
+    tickets.set(ticket, { cell: cellId, exp: now() + ticketTtlMs });
+    return ticket;
+  }
+
+  // Monouso VERO: il biglietto si strappa anche se il controllo fallisce —
+  // scaduto, cella sbagliata o gia' usato sono indistinguibili dal di fuori,
+  // e nessuno dei tre lascia ritentare con lo stesso valore.
+  function consumeTicket(ticket, cellId) {
+    sweep();
+    const rec = tickets.get(ticket);
+    if (!rec) return false;
+    tickets.delete(ticket);
+    return rec.exp > now() && rec.cell === cellId;
+  }
+
+  function issueCookie(cellId) {
+    const value = newSecret();
+    cookies.set(value, { cell: cellId, exp: now() + cookieTtlMs });
+    return value;
+  }
+
+  function verifyCookie(value, cellId) {
+    sweep();
+    const rec = cookies.get(value);
+    return !!rec && rec.exp > now() && rec.cell === cellId;
+  }
+
+  function cookieHeaderValue(cellId, value) {
+    const attrs = [
+      `${COOKIE_NAME}=${value}`,
+      `Path=/api/panel/${encodeURIComponent(cellId)}`,
+      'HttpOnly',
+      'SameSite=Strict',
+      `Max-Age=${Math.floor(cookieTtlMs / 1000)}`,
+    ];
+    return attrs.join('; ');
+  }
+
+  // —— Emissione: POST /api/panel/<cella>/ticket, SOLO per la PWA autenticata.
+  // La cella deve esistere ed avere un pannello valido: nessun ticket per
+  // destinazioni che il proxy rifiuterebbe comunque.
+  async function handleTicketRequest(req, res, cellId) {
+    const bearer = String(req.headers.authorization || '').replace(/^Bearer\s+/i, '');
+    if (!verifyToken(bearer)) {
+      log({ event: 'panel-auth', outcome: 'ticket-denied', reason: 'unauthorized', cell: cellId });
+      res.writeHead(401, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: 'unauthorized' }));
+      return;
+    }
+    let panelUrl;
+    try { panelUrl = await resolveCellPanel(cellId); } catch (_) { panelUrl = null; }
+    if (panelUrl === null || panelUrl === undefined || panelUrl === '' || !validPanelUrl(panelUrl)) {
+      log({ event: 'panel-auth', outcome: 'ticket-denied', reason: 'no-panel', cell: cellId });
+      res.writeHead(404, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: 'pannello non disponibile' }));
+      return;
+    }
+    const ticket = issueTicket(cellId);
+    log({ event: 'panel-auth', outcome: 'ticket-issued', cell: cellId });
+    res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+    res.end(JSON.stringify({ ticket, cell: cellId, expiresInSeconds: Math.floor(ticketTtlMs / 1000) }));
+  }
+
+  // —— Il middleware: decide CHI entra nel proxy, e imposta il cookie quando
+  // e' la prima richiesta dell'iframe (quella col ticket).
+  //
+  // Tre chiavi, in ordine di chi le usa:
+  //   Bearer        — la PWA e le probe esistenti: tutto come prima.
+  //   ?ticket=      — l'iframe al primo ingresso: monouso, consumato ADESSO,
+  //                   e la risposta porta il cookie di visione.
+  //   Cookie        — le sotto-risorse (URL relativi, senza query): il cookie
+  //                   vale solo per la cella del path.
+  function panelAuthMiddleware(req, res, next) {
+    const url = String(req.url || '');
+    const cellId = cellFromPanelPath(url);
+    if (!cellId || !CELL_ID_RE.test(cellId)) {
+      res.writeHead(404, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: 'pannello non trovato' }));
+      return;
+    }
+    const provenienza = hopKind(req);
+    if (provenienza === 'sospetta') {
+      log({ event: 'panel-auth', outcome: 'denied', reason: 'hop-non-verificabile', cell: cellId });
+      res.writeHead(401, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: 'unauthorized' }));
+      return;
+    }
+    const pathname = url.slice(0, url.indexOf('?') === -1 ? url.length : url.indexOf('?'));
+    const tail = pathname.split('/').filter(Boolean).slice(1);
+    // L'emissione del ticket e' l'UNICA operazione con body semantico ed e'
+    // gestita qui, perche' sta prima di ogni requireToken: /panel/<cella>/ticket.
+    if (req.method === 'POST' && tail.length === 1 && tail[0] === 'ticket') {
+      void handleTicketRequest(req, res, cellId);
+      return;
+    }
+
+    // Il ticket ha PRECEDENZA sul Bearer: la richiesta federata dell'iframe
+    // arriva qui con il Bearer dell'hop (il token del nodo, iniettato dalla
+    // via federata) ACCANTO al ticket in query — e deve entrare da iframe,
+    // consumando il ticket e prendendo il cookie, non da PWA. Chi porta un
+    // ticket sta facendo l'ingresso del frame; la PWA non lo mette mai in query.
+    let qTicket = null;
+    const qi = url.indexOf('?');
+    if (qi !== -1) qTicket = new URLSearchParams(url.slice(qi + 1)).get('ticket');
+    if (qTicket) {
+      if (consumeTicket(qTicket, cellId)) {
+        const value = issueCookie(cellId);
+        res.setHeader('set-cookie', cookieHeaderValue(cellId, value));
+        log({ event: 'panel-auth', outcome: 'ticket-consumed', cell: cellId });
+        return next();
+      }
+      log({ event: 'panel-auth', outcome: 'denied', reason: 'ticket-invalid', cell: cellId });
+      res.writeHead(401, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: 'ticket non valido' }));
+      return;
+    }
+
+    // Il Bearer apre il pannello SOLO da locale. Sulla via federata e' il
+    // token che il proxy ha iniettato da se' un istante prima: accettarlo
+    // significherebbe che chiunque raggiunga la route — e la route del
+    // pannello transita prima del requireToken, perche' un iframe non porta
+    // header — si porta via il contenuto. Di la' restano il ticket e il
+    // cookie, che questo nodo ha emesso e sa riconoscere.
+    const bearer = String(req.headers.authorization || '').replace(/^Bearer\s+/i, '');
+    if (provenienza === 'locale' && verifyToken(bearer)) return next();
+
+    const cookieValue = parseCookieHeader(req.headers.cookie)[COOKIE_NAME];
+    if (cookieValue && verifyCookie(cookieValue, cellId)) return next();
+
+    log({
+      event: 'panel-auth', outcome: 'denied', cell: cellId,
+      reason: provenienza === 'federata' ? 'federated-needs-ticket' : 'unauthorized',
+    });
+    res.writeHead(401, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ error: 'unauthorized' }));
+  }
+
+  // —— Auth per l'upgrade WebSocket del pannello. Le WS del pannello partono
+  // dalla pagina dentro il frame e portano il cookie della NOSTRA origine
+  // (same-site): il cookie di visione deve aprirle, altrimenti il pannello
+  // carica l'HTML e resta nero. Il Bearer e il ?token= della PWA restano
+  // validi come prima. Il ticket in query NON si usa qui: il flusso dell'iframe
+  // ha gia' il cookie quando la pagina apre la sua prima socket.
+  //
+  // Lo stesso confine dell'HTTP vale QUI, e va scritto qui: l'upgrade non
+  // passa dal middleware — forwardUpgrade e' un percorso separato — e per un
+  // pannello e' la porta che conta, perche' i frame arrivano da questa.
+  function authorizeUpgrade(req) {
+    const url = String(req.url || '');
+    const provenienza = hopKind(req);
+    if (provenienza === 'sospetta') return false;
+    const bearer = String(req.headers.authorization || '').replace(/^Bearer\s+/i, '');
+    if (provenienza === 'locale' && verifyToken(bearer)) return true;
+    const qi = url.indexOf('?');
+    if (provenienza === 'locale' && qi !== -1
+      && verifyToken(new URLSearchParams(url.slice(qi + 1)).get('token') || '')) return true;
+    const cellId = cellFromPanelPath(url.replace(/^\/api\/panel/, ''));
+    if (!cellId) return false;
+    const cookieValue = parseCookieHeader(req.headers.cookie)[COOKIE_NAME];
+    return !!(cookieValue && verifyCookie(cookieValue, cellId));
+  }
+
+  return {
+    panelAuthMiddleware,
+    authorizeUpgrade,
+    // Per test e diagnostica: verifiche dall'esterno senza passare dal wire.
+    consumeTicketForTest: consumeTicket,
+    verifyCookieForTest: verifyCookie,
+    issueCookieForTest: issueCookie,
+    cookieHeaderValueForTest: cookieHeaderValue,
+  };
+}
+
+module.exports = {
+  createPanelAuth,
+  TICKET_TTL_MS,
+  COOKIE_TTL_MS,
+  COOKIE_NAME,
+};

package/lib/proxy/panel-proxy.js

@@ -0,0 +1,305 @@
+'use strict';
+// lib/proxy/panel-proxy.js — inoltro del pannello di UNA cella locale.
+//
+// Perche' esiste: `panelUrl` e' un endpoint su loopback (es. il desktop in
+// container). L'iframe della PWA risolve `127.0.0.1` sul browser di CHI GUARDA,
+// quindi il pannello di una cella si vede solo stando sulla stessa macchina.
+// Questa route mette il traffico dalla parte giusta del loopback.
+//
+// TRE VINCOLI, che sono il disegno e non dettagli:
+//
+// 1. LA DESTINAZIONE NON ARRIVA MAI DAL CHIAMANTE. Si risolve dal `panelUrl`
+//    della cella indicata, e quella cella deve essere LOCALE. Non e' un
+//    port-forward: un cellId sconosciuto o senza pannello e' un rifiuto, non un
+//    default. Chi chiama sceglie QUALE cella, mai VERSO DOVE.
+//
+// 2. IL TOKEN DI NEXUSCREW NON ESCE DA QUI. Il pannello non e' un nodo della
+//    federazione: e' un servizio terzo che gira accanto. Inoltrargli la nostra
+//    Authorization sarebbe consegnare la credenziale del control plane a un
+//    container. L'header viene rimosso, e l'eventuale 401 del pannello resta
+//    suo — l'autenticazione al contenuto avviene dentro il frame.
+//
+// 3. IL VALIDATORE E' QUELLO, NON UN SECONDO. `validPanelUrl` e' importato da
+//    fleet/definitions.js, la stessa funzione che accetta il campo quando viene
+//    scritto. Riscriverne una copia qui creerebbe due decisioni sullo stesso
+//    fatto, e la seconda divergerebbe: e' il difetto che passiamo le giornate a
+//    chiudere.
+//
+// Certificato self-signed: il container tipico serve HTTPS con un certificato
+// che nessuno ha firmato, e non possiamo installarlo nel trust store della
+// macchina di chi ci ospita. Verso di lui la verifica e' disattivata di
+// proposito, ma SOLO se la destinazione e' loopback — e la condizione viene
+// ricontrollata qui contro la stessa lista che autorizza il campo, non data per
+// scontata dal validatore. Fra noi e una porta della stessa macchina non c'e'
+// un uomo in mezzo da temere; verso qualunque altro host la verifica resta
+// attiva e il collegamento fallisce invece di degradare in silenzio. In cambio, il browser del visualizzatore parla solo con la NOSTRA
+// origine: il frame smette di restare bianco in attesa che qualcuno accetti
+// quel certificato in una scheda separata.
+
+const http = require('node:http');
+const https = require('node:https');
+const { validPanelUrl, PANELURL_LOOPBACK_HOSTS } = require('../fleet/definitions.js');
+const { CELL_ID_RE } = require('../live-host/store.js');
+
+const PANEL_TIMEOUT_MS = 30000;
+
+// Hop-by-hop (RFC 7230 §6.1) + Proxy-*: mai inoltrati end-to-end.
+const HOP_BY_HOP = new Set([
+  'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
+  'te', 'trailer', 'transfer-encoding', 'upgrade',
+]);
+
+// `/api/panel/<cellId>` oppure `/api/panel/<cellId>/<rest...>`.
+function splitPanelPath(url) {
+  const raw = String(url || '');
+  const qIndex = raw.indexOf('?');
+  const pathname = qIndex === -1 ? raw : raw.slice(0, qIndex);
+  const search = qIndex === -1 ? '' : raw.slice(qIndex);
+  const parts = pathname.split('/').filter(Boolean);
+  if (!parts.length) return null;
+  const cellId = decodeURIComponent(parts[0]);
+  const tail = parts.slice(1);
+  // Un `..` verrebbe inoltrato cosi' com'e' e normalizzato dal pannello: non
+  // cambia host ne' porta, ma e' comunque un percorso che il chiamante disegna
+  // dentro il pannello. Si ferma qui, in entrambe le forme in cui puo' arrivare.
+  for (const seg of tail) {
+    const decoded = (() => { try { return decodeURIComponent(seg); } catch (_) { return seg; } })();
+    if (seg === '..' || decoded === '..') return null;
+  }
+  const rest = tail.length ? `/${tail.join('/')}` : '/';
+  return { cellId, rest, search };
+}
+
+// Il token locale puo' viaggiare in query (il browser non puo' mettere header
+// sull'upgrade WebSocket), e cosi' il ticket d'ingresso dell'iframe: nessuno
+// dei due deve proseguire verso il pannello.
+function stripLocalTokenQuery(search) {
+  if (!search) return '';
+  const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
+  params.delete('token');
+  params.delete('ticket');
+  const out = params.toString();
+  return out ? `?${out}` : '';
+}
+
+// Gli stessi header che il proxy verso i nodi non inoltra. Avevo lasciato
+// passare i cookie con la motivazione «sono del pannello»: era **falsa**.
+// Dietro questo proxy l'origine e' la NOSTRA, quindi il browser manda i cookie
+// del nostro dominio — inoltrarli significherebbe consegnare al container la
+// sessione del control plane, esattamente cio' che l'Authorization rimossa
+// doveva impedire. E `x-forwarded-*` da un client sono valori che un pannello
+// potrebbe credere veri. Rilievo di un audit indipendente.
+function isStrippedRequestHeader(key) {
+  if (HOP_BY_HOP.has(key)) return true;
+  if (key === 'authorization' || key === 'cookie' || key === 'host') return true;
+  // `referer` porterebbe il ticket d'ingresso (viaggiava in query sulla prima
+  // richiesta dell'iframe) fino al pannello: al container non deve arrivare
+  // NESSUNA credenziale, nemmeno di seconda mano.
+  if (key === 'referer') return true;
+  if (key.startsWith('proxy-')) return true;
+  if (key === 'forwarded' || key.startsWith('x-forwarded-')) return true;
+  return false;
+}
+
+function forwardHeaders(headers, targetHost) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers || {})) {
+    if (isStrippedRequestHeader(k.toLowerCase())) continue;
+    out[k] = v;
+  }
+  // L'host deve essere quello della destinazione: un pannello che genera
+  // redirect assoluti li costruisce da qui.
+  out.host = targetHost;
+  return out;
+}
+
+function responseHeaders(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers || {})) {
+    if (HOP_BY_HOP.has(k.toLowerCase())) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+// Risolve la destinazione, o dice PERCHE' non si puo'. I motivi restano
+// distinti: «cella sconosciuta», «cella senza pannello» e «pannello non valido»
+// mandano chi indaga in tre posti diversi, e un rifiuto unico li confonderebbe.
+async function resolveTarget(resolveCellPanel, cellId) {
+  if (!CELL_ID_RE.test(cellId)) return { ok: false, reason: 'cell-id-invalid' };
+  let panelUrl;
+  try { panelUrl = await resolveCellPanel(cellId); } catch (_) { return { ok: false, reason: 'fleet-unavailable' }; }
+  if (panelUrl === null) return { ok: false, reason: 'fleet-unavailable' };
+  if (panelUrl === undefined) return { ok: false, reason: 'cell-unknown' };
+  if (panelUrl === '') return { ok: false, reason: 'no-panel' };
+  // Stesso validatore della scrittura: se un valore e' finito nello stato per
+  // un'altra strada, qui viene fermato comunque.
+  if (!validPanelUrl(panelUrl)) return { ok: false, reason: 'panel-url-invalid' };
+  const parsed = new URL(panelUrl);
+  // Guardia in profondita': la verifica TLS viene disattivata SOLO se la
+  // destinazione e' loopback, e questa riga lo ricontrolla contro la stessa
+  // lista che autorizza il campo. Se un giorno il validatore ammettesse un host
+  // remoto, la disattivazione NON lo seguirebbe: si parlerebbe in TLS
+  // verificato, o si fallirebbe — mai in chiaro con un ignoto.
+  const loopback = PANELURL_LOOPBACK_HOSTS.has(parsed.hostname);
+  return {
+    ok: true,
+    loopback,
+    secure: parsed.protocol === 'https:',
+    host: parsed.hostname,
+    port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+    hostHeader: parsed.host,
+    basePath: parsed.pathname.replace(/\/$/, ''),
+  };
+}
+
+function joinPath(basePath, rest) {
+  if (!basePath) return rest;
+  return rest === '/' ? `${basePath}/` : `${basePath}${rest}`;
+}
+
+// Risponde con o senza Express. Il resto del progetto monta le route su un
+// router Express e usa `res.status().json()`, ma questo modulo e' un pezzo di
+// trasporto: farlo dipendere dal framework significa che si rompe appena lo si
+// usa altrove — ed e' successo alla prima prova con un server nudo, mentre la
+// suite mockata non poteva accorgersene perche' il finto offriva `status()`.
+function respond(res, code, body) {
+  const payload = JSON.stringify(body);
+  if (typeof res.status === 'function' && typeof res.json === 'function') {
+    res.status(code).json(body);
+    return;
+  }
+  res.writeHead(code, { 'content-type': 'application/json' });
+  res.end(payload);
+}
+
+function createPanelProxy({ resolveCellPanel, log = () => {}, requestImpl }) {
+  return async function panelProxy(req, res) {
+    const parsed = splitPanelPath(req.url);
+    if (!parsed) {
+      log({ event: 'panel-proxy', outcome: 'rejected', reason: 'no-cell', cell: '' });
+      return respond(res, 404, { error: 'pannello non trovato' });
+    }
+    const target = await resolveTarget(resolveCellPanel, parsed.cellId);
+    if (!target.ok) {
+      log({ event: 'panel-proxy', outcome: 'rejected', reason: target.reason, cell: parsed.cellId });
+      return respond(res, 404, { error: `pannello non disponibile: ${target.reason}` });
+    }
+    const request = requestImpl || (target.secure ? https.request : http.request);
+    const options = {
+      host: target.host,
+      port: target.port,
+      method: req.method,
+      path: `${joinPath(target.basePath, parsed.rest)}${stripLocalTokenQuery(parsed.search)}`,
+      headers: forwardHeaders(req.headers, target.hostHeader),
+      ...(target.secure ? { rejectUnauthorized: !(target.loopback) } : {}),
+    };
+    let upstream;
+    try {
+      upstream = request(options, (up) => {
+        res.writeHead(up.statusCode, responseHeaders(up.headers));
+        up.pipe(res);
+      });
+    } catch (_) {
+      log({ event: 'panel-proxy', outcome: 'error', reason: 'request-failed', cell: parsed.cellId });
+      if (!res.headersSent) respond(res, 502, { error: 'pannello non raggiungibile' });
+      return;
+    }
+    upstream.setTimeout(PANEL_TIMEOUT_MS, () => upstream.destroy(new Error('panel timeout')));
+    upstream.on('error', () => {
+      log({ event: 'panel-proxy', outcome: 'error', reason: 'upstream-error', cell: parsed.cellId });
+      if (!res.headersSent) respond(res, 502, { error: 'pannello non raggiungibile' });
+      else res.destroy();
+    });
+    req.on('aborted', () => upstream.destroy());
+    log({ event: 'panel-proxy', outcome: 'forwarded', cell: parsed.cellId });
+    req.pipe(upstream);
+  };
+}
+
+// Upgrade WebSocket. Un pannello che si apre senza i suoi frame e' nero: un
+// inoltro solo-HTTP darebbe esattamente quello, con l'aria di funzionare.
+//
+// `authorize(req, url)` decide chi apre l'upgrade ed e' il posto del cookie di
+// visione: le WS del pannello partono dalla pagina nel frame, con URL relativi
+// e senza query — portano il cookie, non possono portare altro. Con il solo
+// `verifyToken` (compatibilita' con i test) resta il vecchio contratto:
+// Bearer oppure ?token=.
+function handlePanelUpgrade({ req, socket, head, resolveCellPanel, verifyToken, authorize, log = () => {}, requestImpl }) {
+  // Un upgrade rifiutato deve RISPONDERE prima di chiudere. Chiudere e basta
+  // lascia il client in attesa finche' non decide lui di rinunciare: dal lato
+  // di chi guarda e' un pannello che non arriva mai, indistinguibile da uno
+  // lento. Trovato da una prova con socket veri — la suite mockata non poteva
+  // vederlo, perche' li' nessuno aspettava una risposta.
+  const kill = (code = 400, motivo = 'Bad Request') => {
+    try { socket.end(`HTTP/1.1 ${code} ${motivo}\r\nConnection: close\r\n\r\n`); } catch (_) {}
+    try { socket.destroy(); } catch (_) {}
+  };
+  let url;
+  try { url = new URL(req.url, 'http://127.0.0.1'); } catch (_) { return kill(400, 'Bad Request'); }
+  const allowed = typeof authorize === 'function'
+    ? authorize(req, url)
+    : (() => {
+      const bearer = (req.headers.authorization || '').replace(/^Bearer\s+/i, '');
+      const given = bearer || url.searchParams.get('token') || '';
+      return verifyToken(given);
+    })();
+  if (!allowed) {
+    log({ event: 'panel-proxy', outcome: 'rejected', reason: 'unauthorized', cell: '' });
+    return kill(401, 'Unauthorized');
+  }
+  const parsed = splitPanelPath(req.url.replace(/^\/api\/panel/, ''));
+  if (!parsed) return kill(404, 'Not Found');
+  Promise.resolve(resolveTarget(resolveCellPanel, parsed.cellId)).then((target) => {
+    if (!target.ok) {
+      log({ event: 'panel-proxy', outcome: 'rejected', reason: target.reason, cell: parsed.cellId });
+      return kill(404, 'Not Found');
+    }
+    const request = requestImpl || (target.secure ? https.request : http.request);
+    const headers = forwardHeaders(req.headers, target.hostHeader);
+    headers.connection = 'Upgrade';
+    headers.upgrade = 'websocket';
+    let upstream;
+    try {
+      upstream = request({
+        host: target.host,
+        port: target.port,
+        method: 'GET',
+        path: `${joinPath(target.basePath, parsed.rest)}${stripLocalTokenQuery(parsed.search)}`,
+        headers,
+        ...(target.secure ? { rejectUnauthorized: !(target.loopback) } : {}),
+      });
+    } catch (_) { return kill(502, 'Bad Gateway'); }
+    upstream.on('upgrade', (upRes, upSocket, upHead) => {
+      const lines = [`HTTP/1.1 ${upRes.statusCode} ${upRes.statusMessage}`];
+      for (const [k, v] of Object.entries(upRes.headers)) lines.push(`${k}: ${v}`);
+      try {
+        socket.write(`${lines.join('\r\n')}\r\n\r\n`);
+        if (upHead && upHead.length) socket.write(upHead);
+        if (head && head.length) upSocket.write(head);
+      } catch (_) { return kill(502, 'Bad Gateway'); }
+      log({ event: 'panel-proxy', outcome: 'upgraded', cell: parsed.cellId });
+      upSocket.pipe(socket);
+      socket.pipe(upSocket);
+      const close = () => {
+        try { upSocket.destroy(); } catch (_) {}
+        try { socket.destroy(); } catch (_) {} // qui l'upgrade e' gia' avvenuto: niente risposta HTTP
+      };
+      upSocket.on('error', close); socket.on('error', close);
+      upSocket.on('close', close); socket.on('close', close);
+    });
+    // Il pannello ha risposto senza accettare l'upgrade: non e' un WebSocket,
+    // e fingere il contrario lascerebbe il frame in attesa per sempre.
+    upstream.on('response', () => {
+      log({ event: 'panel-proxy', outcome: 'rejected', reason: 'upgrade-refused', cell: parsed.cellId });
+      kill(502, 'Bad Gateway');
+    });
+    upstream.on('error', () => {
+      log({ event: 'panel-proxy', outcome: 'error', reason: 'upstream-error', cell: parsed.cellId });
+      kill(502, 'Bad Gateway');
+    });
+    upstream.end();
+  }).catch(() => kill(500, 'Internal Server Error'));
+}
+
+module.exports = { createPanelProxy, handlePanelUpgrade, splitPanelPath, resolveTarget };