@mmmbuto/nexuscrew 0.8.58 → 0.9.1

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 = '_';
@@ -151,6 +152,12 @@ function knownResource(resource) {
     || /^\/vl-nodes\/[a-f0-9]{32}(?:\/commands|\/events)?$/.test(resource)
     || resource === '/decks'
     || /^\/decks\/[a-z0-9-]{1,32}$/.test(resource)
+    // Cella ospite Live (0.9.1): un peer designa/legge/rimuove la designazione
+    // SOLO sul nodo che la possiede, mai la propria — stesso gate per-peer del
+    // pannello (isLiveHostResource + liveHostAllowedFor), non l'allowlist
+    // generica: dietro c'e' una scelta dell'operatore del nodo target, non un
+    // dato che ogni peer pairato puo' gia' leggere.
+    || isLiveHostResource(resource)
     || resource === '/topology'
     || resource === '/diagnostics/status'
     || resource === '/diagnostics/logs'
@@ -185,10 +192,47 @@ 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;
+}
+
+// La cella ospite Live copia lo stesso modello, non un altro: chi puo'
+// designare quale cella di QUESTO nodo fa da host Live e' una scelta del nodo
+// che la possiede, non un dato che ogni peer pairato vede gia' — stesso gate
+// per-peer del pannello, stesso default negato. A differenza del pannello (un
+// sottoalbero /panel/<cella>/*, perche' serve HTML/JS/asset), qui l'insieme
+// delle risorse e' chiuso: tre endpoint fissi, non un percorso arbitrario.
+const LIVE_HOST_RESOURCES = new Set(['/live-host', '/live-host/designate', '/live-host/clear']);
+function isLiveHostResource(resource) { return LIVE_HOST_RESOURCES.has(resource); }
+function liveHostAllowedFor(ingress) {
+  if (!ingress) return true;
+  return ingress.liveHostAccess === true;
+}
+
 function allowedResource(resource, method = 'GET') {
+  if (isPanelResource(resource)) return method === 'GET' || method === 'POST';
+  if (resource === '/live-host') return method === 'GET';
+  if (resource === '/live-host/designate' || resource === '/live-host/clear') return 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 +307,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 +343,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;
+}
+
+// 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 }) {
-  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);
+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 +377,14 @@ 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 && isLiveHostResource(parsed.resource) && !liveHostAllowedFor(ingress)) {
+      return res.status(403).json({ error: 'cella ospite live non concessa da questo nodo', reason: 'live-host-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 +392,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 +407,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 +415,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 +1266,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 +1300,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 +1322,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, isLiveHostResource, liveHostAllowedFor, 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,

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,337 @@
+'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) }));
+  }
+
+  // —— Consumo: ticket in query (prima richiesta dell'iframe, monouso — pone
+  // il cookie di visione), cookie (sotto-risorse), Bearer locale (compat: PWA
+  // e probe esistenti). NIENTE emissione qui — nessun corpo semantico, nessun
+  // controllo su chi ha diritto a un ticket NUOVO: quella decisione resta
+  // dov'e' oggi (handleTicketRequest, dietro requireToken sul control plane).
+  // Riusata identica su ENTRAMBE le porte (control plane per compat, porta
+  // pannello per il consumo vero): e' la logica che "si sposta", non si
+  // riscrive due volte.
+  function consumeCore(req, res, next, cellId, provenienza) {
+    const url = String(req.url || '');
+    // 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' }));
+  }
+
+  // Check comune a emissione e consumo: cellId valido + provenienza non sospetta.
+  // Ritorna {cellId, provenienza} o null se ha gia' risposto (404/401).
+  function gate(req, res) {
+    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 null;
+    }
+    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 null;
+    }
+    return { cellId, provenienza };
+  }
+
+  // —— Il middleware STORICO: emissione + consumo nello stesso mount (control
+  // plane, /api/panel). Comportamento INVARIATO — nessuna riga di logica
+  // spostata, solo composta dai due pezzi sopra.
+  function panelAuthMiddleware(req, res, next) {
+    const g = gate(req, res);
+    if (!g) return;
+    const { cellId, provenienza } = g;
+    const url = String(req.url || '');
+    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;
+    }
+    consumeCore(req, res, next, cellId, provenienza);
+  }
+
+  // —— SOLO consumo: per la porta pannello (P0 sicurezza 2026-08-16). Nessuna
+  // emissione qui — quella resta dietro requireToken sul control plane, mai
+  // su una porta che non verifica un token. Un POST .../ticket arrivato qui
+  // (non dovrebbe mai: frameUrl non lo costruisce) cade nel consumo e viene
+  // rifiutato come qualunque richiesta senza ticket/cookie/Bearer validi.
+  function consumeMiddleware(req, res, next) {
+    const g = gate(req, res);
+    if (!g) return;
+    consumeCore(req, res, next, g.cellId, g.provenienza);
+  }
+
+  // —— 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;
+    // Il prefisso varia con la porta: /api/panel sul control plane (compat),
+    // /panel nudo sulla porta pannello dedicata — mai entrambi assieme.
+    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,
+    consumeMiddleware,
+    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,
+};