@mmmbuto/nexuscrew 0.9.28 → 0.9.30

package/lib/notify/routes.js

@@ -1,5 +1,5 @@
 'use strict';
-// Route del MCP bridge (design §2): notify, web-push, asks. Montate dentro il
+// Routes of the MCP bridge: notify, web-push, asks. Mounted inside the
 // router /api gia' dietro requireToken (server.js) — qui restano solo:
 //   - READONLY come FLOOR (da revisione): sono gated 403 TUTTI i mutanti — answer
 //     (scrittura PTY via paste), push subscribe/unsubscribe (push.json) e la
@@ -18,6 +18,7 @@
 // Il paste della risposta riusa ESATTAMENTE pasteToSession (bracketed literal,
 // niente Invio, control char rifiutati): qui si sanifica il testo PRIMA.
 const express = require('express');
+const { createAskAnswerService } = require('./ask-answer-service.js');
 const { isValidSession } = require('../files/store.js');
 const { normalizeNotificationLang } = require('./language.js');
 const { HOP_HEADER } = require('../proxy/hop-proof.js');
@@ -110,7 +111,16 @@ function notifyRoutes({
   // apre per omissione.
   localNodeId = () => null, originResolver = null, acl = null, dispatcher = null,
   federatedRate = null,
+  answerService = null, receipts = null,
 }) {
+  // The shared answer cycle is built from the local deps when the caller does
+  // not inject one: the local route and the federated surface must never drift
+  // into two different implementations.
+  const askService = answerService || createAskAnswerService({
+    asks, paste,
+    labelPrefix: replyLabel(cfg),
+    onClosure: (kind, info) => { try { notifier.emitRaw({ type: kind, id: info.askId }); } catch (_) {} },
+  });
   const r = express.Router();
   const json = express.json({ limit: '16kb' });
   const bindingGuard = createIdentityBindingGuard({
@@ -196,7 +206,9 @@ function notifyRoutes({
             return res.status(429).json({ status: 'refused', reason: `rate-${quota.bucket}` });
           }
         }
-        const delivered = await notifier.emit({
+        // Delivery ONLY: a federated notify is delivered to this node's UI
+        // and never re-enters the event publisher (no loop, no re-export).
+        const delivered = await notifier.deliverOnly({
           title: b.title.trim(), body: b.body, urgency: b.urgency, lang,
           // Il mittente NON e' `b.session`: quel campo lo dichiara il chiamante.
           // Qui vale solo cio' che la catena ha provato, piu' la cella che il
@@ -204,7 +216,7 @@ function notifyRoutes({
           originNode: resolved.origin.node,
           originCell: resolved.origin.cell,
         });
-        // R31-A3: lo status e' DERIVATO dai conteggi, non dichiarato a parte.
+        // : lo status e' DERIVATO dai conteggi, non dichiarato a parte.
         // `emit` e' best-effort — push fallito → 0, `ui` conta i write SSE
         // riusciti — e il dispatcher propaga SOLO l'etichetta (i conteggi
         // muoiono in forward(), rilievo da revisione): per la cella mittente e'
@@ -304,6 +316,7 @@ function notifyRoutes({
         urgency: 'high',
         session: ask.session,
         lang: 'it',
+        askId: ask.id,
         url: `/#ask=${ask.id}`,
       });
       res.status(201).json({ id: ask.id });
@@ -326,9 +339,12 @@ function notifyRoutes({
       const ask = asks.get(id);
       const binding = await guardBinding(req, ask && ask.session);
       if (binding instanceof Error) return bindingRejected(res, binding);
-      const out = asks.dismiss(id);
+      // Same service as the federated path: one authoritative state, so the
+      // pending/unknown constraint cannot be bypassed from here.
+      const out = askService.dismiss(id);
       if (!out.ok) {
         if (out.reason === 'unknown') return res.status(404).json({ error: 'ask inesistente' });
+        if (out.reason === 'delivery-unknown-block') return res.status(409).json({ error: out.error, reason: out.reason });
         if (out.reason === 'answering') return res.status(409).json({ error: 'risposta in corso: non si scarta un ask in answering' });
         return res.status(500).json({ error: 'dismiss non riuscito' });
       }
@@ -348,7 +364,7 @@ function notifyRoutes({
       // Validazione del testo PRIMA del claim: nessun claim da rilasciare su 400.
       const raw = req.body && req.body.text;
       if (typeof raw !== 'string') return res.status(400).json({ error: 'text deve essere una stringa' });
-      // R27: oltre il tetto si RIFIUTA, non si tronca. I due tetti vicini in casa
+      // Oltre il tetto si RIFIUTA, non si tronca. I due tetti vicini in casa
       // (title/body della notifica, nc_send_cell) rifiutano da sempre; qui invece
       // la textarea non ha limite, la route troncava a MAX_ANSWER e rispondeva
       // {answered:true}: l'operatore incollava una config e la cella riceveva la
@@ -358,7 +374,7 @@ function notifyRoutes({
       // La lunghezza misurata ENTRA nel messaggio: la route la conosce, e senza
       // di essa chi ha incollato 12000 caratteri sa che c'e' un tetto ma non di
       // quanto deve tagliare. Dirti che hai sbagliato senza dirti di quanto e'
-      // la stessa meta' di difetto che R27 corregge altrove.
+      // La stessa meta' di difetto che corregge altrove.
       if (sanitized.length > MAX_ANSWER) {
         return res.status(400).json({ error: `text troppo lungo: ${sanitized.length} caratteri, il massimo e' ${MAX_ANSWER}` });
       }
@@ -367,25 +383,48 @@ function notifyRoutes({
       const ask = asks.get(id);
       const binding = await guardBinding(req, ask && ask.session);
       if (binding instanceof Error) return bindingRejected(res, binding);
-      const claim = asks.claim(id);
-      if (!claim.ok) {
-        if (claim.reason === 'unknown') return res.status(404).json({ error: 'ask inesistente' });
-        if (claim.reason === 'dismissed') return res.status(409).json({ error: 'ask gia\' scartato (dismissed)' });
-        if (claim.reason === 'answering') return res.status(409).json({ error: 'risposta gia\' in corso da un\'altra richiesta' });
-        return res.status(409).json({ error: 'ask gia\' risposto' });
+      // ONE answer cycle for local and federated: the service owns the
+      // claim -> paste -> commit flow AND the delivery-unknown lock. The
+      // closure event is emitted by the service, not here.
+      const out = await askService.answerLocal({ askId: id, text });
+      if (!out.ok) return res.status(out.code || 500).json({ error: out.error });
+      res.json({ answered: true, id });
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+
+  // Explicit reconciliation: local and authenticated only, NEVER
+  // federata (la route non e' in allowlist). Decide l'esito dei tentativi
+  // delivery-unknown e sblocca l'ask; CAS facoltativa sulla revisione.
+  r.post('/asks/:id/reconcile', mutGate, json, (req, res) => {
+    try {
+      const id = String(req.params.id || '');
+      const ask = asks.get(id);
+      if (!ask) return res.status(404).json({ error: 'ask inesistente' });
+      const body = req.body || {};
+      const decision = body.decision;
+      if (decision !== 'mark-delivered' && decision !== 'allow-new-attempt') {
+        return res.status(400).json({ error: 'decision deve essere mark-delivered|allow-new-attempt' });
       }
-      let pasted = false;
-      try {
-        pasted = await paste(claim.ask.session, `[${replyLabel(cfg)} reply · ask#${id}] ${text}`);
-      } catch (_) { pasted = false; }
-      if (!pasted) {
-        asks.release(id); // rollback: l'ask resta open e contendibile
-        return res.status(502).json({ error: `paste fallito: sessione "${claim.ask.session}" non raggiungibile` });
+      const out = askService.reconcile({ askId: id, decision, expectedRevision: body.expectedRevision });
+      if (!out.ok) {
+        if (out.reason === 'revision-required' || out.reason === 'bad-decision') {
+          return res.status(400).json({ error: out.error, reason: out.reason });
+        }
+        if (out.reason === 'revision-conflict') return res.status(409).json({ error: out.error, reason: out.reason });
+        if (out.reason === 'unknown') return res.status(404).json({ error: out.error, reason: out.reason });
+        if (out.reason === 'persist-failed') {
+          return res.status(500).json({ error: 'reconcile non persistito: ask ancora bloccato', reason: out.reason });
+        }
+        // Il servizio dichiara il proprio codice: il rifiuto di una
+        // riconciliazione su un paste VIVO (answering) o senza alcun esito
+        // incerto da riconciliare (nothing-to-reconcile, generation-changed)
+        // e' una decisione dell'operatore rifiutata, non un errore interno.
+        if (out.code === 409) {
+          return res.status(409).json({ error: out.error, reason: out.reason });
+        }
+        return res.status(500).json({ error: out.error || 'reconcile non riuscito', reason: out.reason });
       }
-      asks.commit(id, text);
-      // Le altre UI aperte tolgono la card/badge senza aspettare il poll.
-      notifier.emitRaw({ type: 'ask-answered', id });
-      res.json({ answered: true, id });
+      res.json({ reconciled: true, askId: id, decision, attempts: out.changed, revision: out.revision });
     } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
   });
 

package/lib/proxy/federation.js

@@ -5,6 +5,7 @@ const net = require('node:net');
 const express = require('express');
 const store = require('../nodes/store.js');
 const topologyCache = require('../nodes/topology-cache.js');
+const { allowedByClass, classifyResource } = require('./resource-acl.js');
 const reverseRotation = require('../nodes/reverse-rotation.js');
 const { bearerFrom } = require('../auth/middleware.js');
 const { safeEqual } = require('../nodes/peering.js');
@@ -176,8 +177,8 @@ function knownResource(resource) {
     || resource === '/ws'
     // Un avviso all'operatore attraversa la federazione con la stessa spina
     // dorsale dell'audio: origine provata dalla catena `visited`, ACL del
-    // target, budget dedicato. NON e' la coda di NC-NEXT-07 (§5 del modello di
-    // autorita'): quella differisce un'esecuzione, questo mostra del testo e
+    // target, dedicated budget. It is NOT the authority-model queue: that one
+    // defers an execution, this one shows text and executes nothing.
     // non esegue nulla. `/audio/speak` esce da un altoparlante in una stanza
     // fisica ed e' gia' federato: una notifica e' meno invasiva di cosi'.
     || resource === '/notify'
@@ -192,6 +193,15 @@ 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.
+    // Event feed: a closed GET surface inside the authenticated API.
+    // The handler demands a proven last hop on top of the class gate — the
+    // allowlist only admits the resources exist at all.
+    || resource === '/event-feed'
+    || resource === '/event-feed/snapshot'
+    // Federated ask write-back: answer, dismiss, attempt status.
+    || /^\/event-feed\/asks\/[a-f0-9]{8}(?:\/answer|\/requests\/[0-9a-f-]{16,64})?$/.test(resource)
+    || /^\/event-feed\/[A-Za-z0-9._-]{1,32}$/.test(resource)
+    || /^\/event-feed\/node\/[a-f0-9]{32}$/.test(resource)
     || 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);
 }
@@ -221,18 +231,31 @@ function panelAllowedFor(ingress) {
 // 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']);
+// delle risorse e' chiuso: quattro endpoint fissi, non un percorso arbitrario.
+const LIVE_HOST_RESOURCES = new Set(['/live-host', '/live-host/designate', '/live-host/clear', '/live-host/bridge']);
 function isLiveHostResource(resource) { return LIVE_HOST_RESOURCES.has(resource); }
 function liveHostAllowedFor(ingress) {
   if (!ingress) return true;
   return ingress.liveHostAccess === true;
 }
 
+// One decision, used by BOTH federated entry points: the HTTP relay and the
+// WebSocket upgrade. A resource whose class is unknown, or whose grants the
+// owner has not conceded, is refused before anything is dispatched.
+function classGateCheck(resource, method, ingress) {
+  const cls = classifyResource(resource, method);
+  if (!cls) return { ok: false, status: 404, reason: 'resource-not-classified' };
+  if (!allowedByClass(cls, ingress)) return { ok: false, status: 403, reason: `grant-required:${cls}` };
+  return { ok: true, className: cls };
+}
+
 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';
+  // The bridge resolution travels to the owner without parameters: the
+  // designation picks the target, so a forwarded call cannot add one.
+  if (resource === '/live-host/bridge') 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';
@@ -270,6 +293,13 @@ function allowedResource(resource, method = 'GET') {
   // Notify: solo POST. `/events`, `/asks` e `/push/*` restano NON federati —
   // SSE non puo' autenticarsi col Bearer e un ask ha un canale di ritorno che
   // e' un paste nel tmux locale, quindi non attraverserebbe comunque.
+  // Event feed: GET only, no mutation, no upgrade.
+  if (resource === '/event-feed' || resource === '/event-feed/snapshot') return method === 'GET';
+  if (/^\/event-feed\/[A-Za-z0-9._-]{1,32}$/.test(resource)) return method === 'GET';
+  if (/^\/event-feed\/node\/[a-f0-9]{32}$/.test(resource)) return method === 'GET';
+  if (/^\/event-feed\/asks\/[a-f0-9]{8}\/answer$/.test(resource)) return method === 'POST';
+  if (/^\/event-feed\/asks\/[a-f0-9]{8}$/.test(resource)) return method === 'DELETE';
+  if (/^\/event-feed\/asks\/[a-f0-9]{8}\/requests\/[0-9a-f-]{16,64}$/.test(resource)) return method === 'GET';
   if (resource === '/notify') return method === 'POST';
   // Audio: only capability read, speak and stop are exposed through Hydra.
   // audio.consent is a LOCAL mutation and MUST stay unreachable federated.
@@ -290,7 +320,27 @@ function readonlyBlocksFederated(resource, method) {
   return resource !== '/audio/speak/status' && resource !== '/audio/stop';
 }
 
+const EVENT_FEED_CURSOR_RE = /^[0-9]{1,12}:[0-9]{1,12}$/;
+
 function allowedQuery(resource, method, rawUrl) {
+  // The event feed has a CLOSED query surface: only `after=<epoch>:<seq>` on
+  // the SSE stream, nothing at all on the snapshot. A token in a query is
+  // refused on these paths whatever it looks like.
+  if (resource === '/event-feed' || resource === '/event-feed/snapshot'
+    || /^\/event-feed\/[A-Za-z0-9._-]{1,32}$/.test(resource)
+    || /^\/event-feed\/node\/[a-f0-9]{32}$/.test(resource)) {
+    const index = String(rawUrl || '').indexOf('?');
+    if (index < 0) return true;
+    const params = new URLSearchParams(String(rawUrl).slice(index + 1));
+    const keys = [...params.keys()];
+    if (keys.some((k) => !/^[A-Za-z0-9_]+$/.test(k))) return false;
+    if (params.has('token') || params.has('access_token')) return false;
+    if (resource !== '/event-feed') return keys.length === 0;
+    if (params.getAll('after').length > 1) return false;
+    if (keys.length === 0) return true;
+    if (keys.length !== 1 || !params.has('after')) return false;
+    return EVENT_FEED_CURSOR_RE.test(params.get('after') || '');
+  }
   if (!resource.startsWith('/diagnostics/')) return true;
   const index = String(rawUrl || '').indexOf('?');
   if (index < 0) return true;
@@ -364,17 +414,57 @@ function rewriteSetCookiePath(headers, prefix) {
   return out;
 }
 
-function proxyHttp(req, res, { port, path, credential, visited = null, hopProof = null, setCookiePrefix = null, panelCookie = null }) {
+// What this node records when a designation is created or removed on a PEER
+// through it: `ownerId` is the peer the forward went to, and the revision is
+// the owner's own, taken from its 2xx answer — never a local guess, because the
+// owner is the one that decides. A non-2xx answer, or a body without
+// `{hostCell, revision}`, records nothing: an absent pointer is honest, an
+// invented one is not.
+function liveHostLedgerCapture({ ledger, ownerId, resource }) {
+  return (status, text) => {
+    if (!ledger || !(status >= 200 && status < 300)) return;
+    if (resource === '/live-host/clear') {
+      if (typeof ledger.clearRemote === 'function') ledger.clearRemote(ownerId);
+      return;
+    }
+    let body = null;
+    try { body = JSON.parse(String(text || '')); } catch (_) { return; }
+    if (!body || typeof body.hostCell !== 'string' || !Number.isInteger(body.revision)) return;
+    if (typeof ledger.recordRemote === 'function') {
+      ledger.recordRemote({ ownerId, hostCell: body.hostCell, revision: body.revision });
+    }
+  };
+}
+
+function proxyHttp(req, res, { port, path, credential, visited = null, hopProof = null, setCookiePrefix = null, panelCookie = null, capture = null }) {
+  // A body a local middleware has already read is no longer in the stream: the
+  // headers would announce bytes that nothing sends, and the peer would wait for
+  // a body that never arrives. Say it at once, with a name, instead of letting
+  // the forward sit until the upstream timeout expires.
+  if (Number(req.headers['content-length'] || 0) > 0 && req.readableEnded) {
+    return res.status(502).json({ error: 'request body already read by a local middleware', reason: 'federation-body-consumed' });
+  }
   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);
+    if (!capture) { res.writeHead(r.statusCode, sanitizeResponseHeaders(headers)); r.pipe(res); return; }
+    // Buffered only where a capture asks for it (the two live-host mutations):
+    // the owner's answer carries the revision that has to be recorded.
+    const chunks = [];
+    r.on('data', (chunk) => chunks.push(chunk));
+    r.on('end', () => {
+      const body = Buffer.concat(chunks);
+      try { capture(r.statusCode, body.toString('utf8')); } catch (_) { /* the ledger never breaks the forward */ }
+      if (res.writableEnded) return;
+      res.writeHead(r.statusCode, sanitizeResponseHeaders(headers));
+      res.end(body);
+    });
   });
   up.setTimeout(30000, () => up.destroy());
-  up.on('error', () => { if (!res.headersSent) res.status(502).json({ error: 'peer non raggiungibile' }); else res.destroy(); });
+  up.on('error', () => { if (!res.headersSent) res.status(502).json({ error: 'peer non raggiungibile', reason: 'federation-peer-unreachable' }); else res.destroy(); });
   req.pipe(up);
 }
 
-function routeHandler({ nodesPath, localPort, localCredential, ingress = null, readonly = () => false, hopSecret = null }) {
+function routeHandler({ nodesPath, localPort, localCredential, ingress = null, readonly = () => false, hopSecret = null, liveHostLedger = null }) {
   return (req, res) => {
     const parsed = parseRoute(req.url);
     // Prima dell'allowlist: un peer senza permesso non deve nemmeno sapere se la
@@ -385,6 +475,20 @@ function routeHandler({ nodesPath, localPort, localCredential, ingress = null, r
     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' });
     }
+    // Class gate, before the dispatch: every federated resource belongs to a
+    // class, and the class decides which grants the owner must have conceded.
+    // A resource that is allowlisted but not classified is DENIED — a new route
+    // must not reach a limited peer by accident — and the coverage test fails
+    // when the allowlist grows without the classification.
+    if (parsed && allowedResource(parsed.resource, req.method)) {
+      const gate = classGateCheck(parsed.resource, req.method, ingress);
+      if (!gate.ok) {
+        return res.status(gate.status).json({
+          error: gate.status === 404 ? 'not found' : 'risorsa non concessa a questo nodo',
+          reason: gate.reason,
+        });
+      }
+    }
     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' });
@@ -422,7 +526,13 @@ function routeHandler({ nodesPath, localPort, localCredential, ingress = null, r
     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 });
+    // A designation forwarded from here lands on the owner: what this node ends
+    // up pointing at is decided THERE, so the pointer is recorded from the
+    // owner's answer (liveHostLedgerCapture) and not from a local guess.
+    const capture = liveHostLedger && (parsed.resource === '/live-host/designate' || parsed.resource === '/live-host/clear')
+      ? liveHostLedgerCapture({ ledger: liveHostLedger, ownerId: next.nodeId, resource: parsed.resource })
+      : null;
+    proxyHttp(req, res, { port: next.localPort, path, credential: next.token, visited, setCookiePrefix, panelCookie, capture });
   };
 }
 
@@ -748,7 +858,7 @@ async function reconcilePeerShare(opts = {}) {
   throw lastError || new Error('riconciliazione Share fallita');
 }
 
-// Runner di riconciliazione Share OFF al boot (design piano §3.2.8). Per-peer,
+// Share-off reconciliation runner at boot.
 // no-overlap (un solo runner attivo per nome), al massimo tre round per processo,
 // backoff nominato 0/1000/5000 ms (iniettabile). Re-read dello stato desiderato
 // (nodes.json) prima di ogni round: abort se non e' piu' shared:false (es. il peer
@@ -995,7 +1105,11 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
   r.get('/health', (_req, res) => {
     const st = store.loadStore(nodesPath);
     const advertisedRoles = typeof roles === 'function' ? roles() : null;
+    // eventFeedV1: the peer checks this capability BEFORE subscribing to the
+    // event feed. An older node reports no capability and the client marks the
+    // feed unsupported instead of retrying forever.
     res.json({ ok: true, instanceId: (st && st.nodeId) || null, version, readonly: !!readonly(),
+      eventFeedV1: true,
       ...(advertisedRoles ? { roles: advertisedRoles } : {}) });
   });
   // Il client puo' verificare SOLO la reverse port che il pairing gli ha
@@ -1257,9 +1371,9 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
   return r;
 }
 
-function localRouter({ nodesPath, localPort, localCredential, readonly, hopSecret = null }) {
+function localRouter({ nodesPath, localPort, localCredential, readonly, hopSecret = null, liveHostLedger = null }) {
   const r = express.Router();
-  r.use((req, res) => routeHandler({ nodesPath, localPort, localCredential, readonly, hopSecret })(req, res));
+  r.use((req, res) => routeHandler({ nodesPath, localPort, localCredential, readonly, hopSecret, liveHostLedger })(req, res));
   return r;
 }
 
@@ -1272,6 +1386,12 @@ function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredenti
   // 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);
+  // The same class decision as the HTTP relay: an upgrade is an entry point too,
+  // and a limited peer must not reach an operator-class channel through it.
+  {
+    const gate = classGateCheck(parsed.resource, 'GET', ingress);
+    if (!gate.ok) return reject(socket, gate.status === 404 ? 404 : 403);
+  }
   const st = store.loadStore(nodesPath);
   if (!st) return reject(socket, 503);
   const visited = controlledVisited(req, ingress, st.nodeId);

package/lib/proxy/node-proxy.js

@@ -1,13 +1,13 @@
 'use strict';
-// lib/proxy/node-proxy.js — reverse-proxy single-origin /node/<name> (design §4, §4b(2)).
+// lib/proxy/node-proxy.js — single-origin reverse proxy for /node/<name>.
 //
-// La superficie PIU' security-critical del progetto. Contratti duri (§4b(2)):
+// The MOST security-critical surface of the project. Hard contracts:
 //   1. Il token LOCALE (Bearer) si verifica PRIMA di risolvere <name>. Il router
 //      HTTP e' montato DIETRO requireToken; l'upgrade WS verifica il token in testa
 //      a handleNodeUpgrade, prima di qualunque parsing/resolve.
 //   2. <name> = chiave strict di nodes.json (^[a-z0-9-]{1,32}$), MAI usata per
 //      costruire path/URL filesystem; nome non in config -> 404 secco.
-//   3. Il token del nodo remoto lo inietta SOLO il proxy (da nodes.json via B0); il
+// 3. Il token del nodo remoto lo inietta SOLO il proxy (da nodes.json via); il
 //      browser non lo vede MAI. Header hop-by-hop e Authorization/cookie/host/
 //      x-forwarded/proxy-* client-supplied STRIPPATI, mai inoltrati upstream.
 //   4. Upstream consentito: ESCLUSIVAMENTE 127.0.0.1:<localPort> del tunnel da
@@ -25,7 +25,7 @@ const net = require('node:net');
 const { NODE_NAME_RE } = require('../nodes/store.js');
 const { bearerFrom } = require('../auth/middleware.js');
 
-// Timeout upstream: irraggiungibile/lento -> 502, mai spinner infinito (§8).
+// Upstream timeouts: unreachable/slow -> 502, never an endless spinner.
 const PROXY_TIMEOUT_MS = 30000;
 const CONNECT_TIMEOUT_MS = 10000;
 
@@ -52,7 +52,7 @@ const MUTATING = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 // 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.
+// Hop-by-hop (RFC 7230 section 6.1) + Proxy-*: never forwarded end-to-end.
 const HOP_BY_HOP = new Set([
   'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
   'te', 'trailer', 'transfer-encoding', 'upgrade',
@@ -153,9 +153,9 @@ function createNodeProxy(deps) {
   const { resolveNode, readonly = () => false, httpRequest = http.request } = deps;
   return function nodeProxy(req, res) {
     const parsed = splitNodePath(req.url);
-    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 (!parsed) return notFound(res);                       // no name
+    if (!NODE_NAME_RE.test(parsed.name)) return notFound(res); // strict/traversal
+    if (isTransitiveRest(parsed.rest)) return notFound(res);   // no transitive rest
     if (isLocalOnly(parsed.rest)) {
       return res.status(403).json({ error: 'local-only: azione non instradabile via federazione' });
     }
@@ -170,7 +170,7 @@ function createNodeProxy(deps) {
 
 function proxyHttp(req, res, node, rest, search, httpRequest) {
   const options = {
-    host: '127.0.0.1',                 // §4b(2)#4 upstream SOLO loopback da config
+    host: '127.0.0.1',                 // upstream loopback ONLY, from config
     port: node.localPort,
     method: req.method,
     // parita' col path WS: il token LOCALE eventualmente in query (?token=) non
@@ -278,10 +278,10 @@ function handleNodeUpgrade(ctx) {
   const node = resolveNode(parsed.name);
   if (!node) return abortUpgrade(socket, 404);
 
-  // §9d: in READONLY locale il WS proxy si nega in toto — il piping raw non puo'
-  // applicare un readonly frame-level e un attach WS e' un canale di scrittura
-  // (PTY remoto). Il nodo remoto applica il PROPRIO READONLY ai suoi client;
-  // qui vale quello locale, come per i metodi HTTP mutanti.
+  // In local READONLY the WS proxy refuses wholesale — raw piping cannot
+  // apply a frame-level readonly and a WS attach is a write channel (remote
+  // PTY). The remote node applies ITS OWN READONLY to its clients;
+  // here the local one rules, as for mutating HTTP methods.
   if (readonly()) return abortUpgrade(socket, 403);
 
   // (3)(4) inject token remoto, upstream SOLO loopback da config

package/lib/proxy/panel-auth.js

@@ -17,7 +17,7 @@
 //    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=ESATTAMENTE il mount da cui la
-//    richiesta e' entrata + la cella (R22, 2026-08-17): `/api/panel/<cella>`
+// Richiesta e' entrata + la cella (2026-08-17): `/api/panel/<cella>`
 //    sul control plane, `/panel/<cella>` sulla porta pannello dedicata — MAI
 //    una costante unica, perche' i due mount servono path diversi e un cookie
 //    scritto per l'uno non verrebbe mai mandato dal browser sotto l'altro
@@ -159,7 +159,7 @@ function createPanelAuth({
     return !!rec && rec.exp > now() && rec.cell === cellId;
   }
 
-  // R22: il Path deve valere per il mount da cui la richiesta e' ENTRATA, non
+  // Il Path deve valere per il mount da cui la richiesta e' ENTRATA, non
   // per una costante. Whitelist stretta invece di un default permissivo — un
   // prefisso non riconosciuto rifiuta (vedi mountPrefixOf) invece di produrre
   // un cookie con uno scope che nessuno ha verificato.
@@ -237,7 +237,7 @@ function createPanelAuth({
     const qi = url.indexOf('?');
     if (qi !== -1) qTicket = new URLSearchParams(url.slice(qi + 1)).get('ticket');
     if (qTicket) {
-      // R22: il mount si verifica PRIMA di toccare il ticket — un mount non
+      // Il mount si verifica PRIMA di toccare il ticket — un mount non
       // riconosciuto non deve bruciare un ticket monouso per un errore che
       // non dipende da chi lo presenta.
       const mountPrefix = mountPrefixOf(req);
@@ -318,7 +318,7 @@ function createPanelAuth({
     consumeCore(req, res, next, cellId, provenienza);
   }
 
-  // —— SOLO consumo: per la porta pannello (P0 sicurezza 2026-08-16). Nessuna
+  // — SOLO consumo: per la porta pannello (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

package/lib/proxy/panel-proxy.js

@@ -43,7 +43,7 @@ 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.
+// Hop-by-hop (RFC 7230 section 6.1) + Proxy-*: never forwarded end-to-end.
 const HOP_BY_HOP = new Set([
   'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
   'te', 'trailer', 'transfer-encoding', 'upgrade',
@@ -295,7 +295,7 @@ function handlePanelUpgrade({ req, socket, head, resolveCellPanel, verifyToken,
     return kill(401, 'Unauthorized');
   }
   // Il prefisso varia con la porta: /api/panel sul control plane (compat),
-  // /panel nudo sulla porta pannello dedicata (P0 sicurezza 2026-08-16).
+  // /panel nudo sulla porta pannello dedicata (sicurezza 2026-08-16).
   const parsed = splitPanelPath(req.url.replace(/^\/(?:api\/)?panel/, ''));
   if (!parsed) return kill(404, 'Not Found');
   Promise.resolve(resolveTarget(resolveCellPanel, parsed.cellId)).then((target) => {