@mmmbuto/nexuscrew 0.7.7 → 0.8.2

package/lib/proxy/federation.js

@@ -0,0 +1,217 @@
+'use strict';
+
+const http = require('node:http');
+const net = require('node:net');
+const express = require('express');
+const store = require('../nodes/store.js');
+const { bearerFrom } = require('../auth/middleware.js');
+const { safeEqual } = require('../nodes/peering.js');
+const {
+  sanitizeRequestHeaders, sanitizeResponseHeaders, stripLocalTokenQuery,
+} = require('./node-proxy.js');
+
+const MAX_HOPS = 4;
+const ROUTE_DELIMITER = '_';
+
+function peerFromToken(nodesPath, token) {
+  const st = store.loadStore(nodesPath);
+  if (!st || !token) return null;
+  return st.nodes.find((n) => n.acceptToken && safeEqual(n.acceptToken, token)) || null;
+}
+
+function peerAllows(peer, otherId) {
+  if (!peer) return true;
+  if (peer.visibility === 'network') return true;
+  if (peer.visibility === 'relay-only') return false;
+  return Array.isArray(peer.selected) && peer.selected.includes(otherId);
+}
+
+function canTransit(ingress, egress) {
+  if (!ingress || !egress || ingress.name === egress.name) return !ingress;
+  return peerAllows(ingress, egress.nodeId) && peerAllows(egress, ingress.nodeId);
+}
+
+function parseRoute(raw) {
+  const parts = String(raw || '').split('?')[0].split('/').filter(Boolean);
+  const idx = parts.indexOf(ROUTE_DELIMITER);
+  // The delimiter cannot occur in a strict peer name, so the first occurrence
+  // is authoritative. Resource segments may legitimately be "_" (a valid
+  // tmux session name) and must not be mistaken for another boundary.
+  if (idx < 0) return null;
+  const route = parts.slice(0, idx);
+  const resource = `/${parts.slice(idx + 1).join('/')}`;
+  if (route.length > MAX_HOPS || route.some((n) => !store.NODE_NAME_RE.test(n))) return null;
+  if (new Set(route).size !== route.length || !knownResource(resource)) return null;
+  return { route, resource };
+}
+
+function knownResource(resource) {
+  return resource === '/sessions'
+    || /^\/sessions\/[\w.@%:+-]{1,128}$/.test(resource)
+    || resource === '/config'
+    || resource === '/fs/dirs'
+    || resource === '/files'
+    || resource === '/files/download'
+    || resource === '/files/upload'
+    || resource === '/ws';
+}
+
+function allowedResource(resource, method = 'GET') {
+  if (resource === '/sessions') return method === 'GET' || method === 'POST';
+  if (/^\/sessions\/[\w.@%:+-]{1,128}$/.test(resource)) return method === 'DELETE';
+  if (resource === '/config') return method === 'GET';
+  if (resource === '/fs/dirs') return method === 'GET';
+  if (resource === '/files') return method === 'GET' || method === 'DELETE';
+  if (resource === '/files/download') return method === 'GET';
+  if (resource === '/files/upload') return method === 'POST';
+  if (resource === '/ws') return method === 'GET';
+  return false;
+}
+
+function cleanHeaders(headers, credential, visited = 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];
+  }
+  if (Array.isArray(visited) && visited.length) out['x-nexuscrew-visited'] = visited.join(',');
+  return out;
+}
+
+function proxyHttp(req, res, { port, path, credential, visited = null }) {
+  const up = http.request({ host: '127.0.0.1', port, method: req.method, path, headers: cleanHeaders(req.headers, credential, visited) }, (r) => {
+    res.writeHead(r.statusCode, sanitizeResponseHeaders(r.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(); });
+  req.pipe(up);
+}
+
+function routeHandler({ nodesPath, localPort, localCredential, ingress = null, readonly = () => false }) {
+  return (req, res) => {
+    const parsed = parseRoute(req.url);
+    if (!parsed || !allowedResource(parsed.resource, req.method)) return res.status(404).json({ error: 'not found' });
+    if (readonly() && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method)) return res.status(403).json({ error: 'READONLY: federated mutation blocked' });
+    const st = store.loadStore(nodesPath);
+    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' });
+    if (parsed.route.length === 0) {
+      return proxyHttp(req, res, { port: typeof localPort === 'function' ? localPort() : localPort, path: `/api${parsed.resource}${queryOf(req.url)}`, credential: localCredential() });
+    }
+    const next = st && store.getNode(st, parsed.route[0]);
+    if (!next || !next.token || (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 });
+  };
+}
+
+function queryOf(url) {
+  const i = String(url).indexOf('?');
+  return i < 0 ? '' : stripLocalTokenQuery(String(url).slice(i));
+}
+
+function controlledVisited(req, ingress, instanceId) {
+  const raw = ingress ? String(req.headers['x-nexuscrew-visited'] || '') : '';
+  const seen = raw ? raw.split(',').filter(Boolean) : [];
+  if (seen.some((id) => !store.NODE_ID_RE.test(id)) || seen.includes(instanceId) || seen.length > MAX_HOPS) return null;
+  return [...seen, instanceId];
+}
+
+async function collectTopology({ nodesPath, ingress = null, ttl = MAX_HOPS, visited = [], fetchImpl = fetch }) {
+  const st = store.loadStore(nodesPath);
+  if (!st) return { instanceId: null, nodes: [] };
+  const seen = new Set(visited.filter((x) => store.NODE_ID_RE.test(x)));
+  seen.add(st.nodeId);
+  const out = [];
+  for (const n of st.nodes) {
+    if (!n.nodeId || seen.has(n.nodeId) || (ingress && !canTransit(ingress, n))) continue;
+    out.push({ instanceId: n.nodeId, name: n.name, route: [n.name], direct: true });
+    if (ttl <= 1 || !n.token) continue;
+    try {
+      const u = `http://127.0.0.1:${n.localPort}/federation/topology?ttl=${ttl - 1}&visited=${encodeURIComponent([...seen].join(','))}`;
+      const r = await fetchImpl(u, { headers: { authorization: `Bearer ${n.token}` } });
+      const j = await r.json();
+      if (!r.ok || j.instanceId !== n.nodeId || !Array.isArray(j.nodes)) continue;
+      for (const child of j.nodes) {
+        if (!child || !store.NODE_ID_RE.test(child.instanceId) || child.instanceId === n.nodeId || seen.has(child.instanceId)
+          || !store.NODE_NAME_RE.test(child.name)
+          || !Array.isArray(child.route) || child.route.length < 1 || child.route.length >= ttl
+          || child.route.some((x) => !store.NODE_NAME_RE.test(x))
+          || new Set(child.route).size !== child.route.length
+          || child.name !== child.route[child.route.length - 1]
+          || child.route.includes(n.name)) continue;
+        out.push({ instanceId: child.instanceId, name: child.name, route: [n.name, ...child.route], direct: false });
+      }
+    } catch (_) {}
+  }
+  const ids = new Set(); const routes = new Set(); const unique = [];
+  for (const n of out.sort((a, b) => a.route.length - b.route.length)) {
+    const routeKey = n.route.join('/');
+    if (ids.has(n.instanceId) || routes.has(routeKey)) continue;
+    ids.add(n.instanceId); routes.add(routeKey); unique.push(n);
+  }
+  return { instanceId: st.nodeId, nodes: unique };
+}
+
+function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly }) {
+  const r = express.Router();
+  r.use((req, res, next) => {
+    const peer = peerFromToken(nodesPath, bearerFrom(req));
+    if (!peer) return res.status(401).json({ error: 'unauthorized peer' });
+    req.peer = peer; next();
+  });
+  r.get('/topology', async (req, res) => {
+    const ttl = Math.max(0, Math.min(MAX_HOPS, Number(req.query.ttl) || MAX_HOPS));
+    const visited = String(req.query.visited || '').split(',');
+    res.json(await collectTopology({ nodesPath, ingress: req.peer, ttl, visited, fetchImpl }));
+  });
+  r.use('/route', (req, res) => routeHandler({ nodesPath, localPort, localCredential, ingress: req.peer, readonly })(req, res));
+  return r;
+}
+
+function localRouter({ nodesPath, localPort, localCredential, readonly }) {
+  const r = express.Router();
+  r.use((req, res) => routeHandler({ nodesPath, localPort, localCredential, readonly })(req, res));
+  return r;
+}
+
+function forwardUpgrade({ req, socket, head, nodesPath, localPort, localCredential, ingress, readonly = () => false, activeSockets = 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);
+  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';
+  if (parsed.route.length) {
+    const next = store.getNode(st, parsed.route[0]);
+    if (!next || !next.token || (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`;
+  }
+  const up = net.connect({ host: '127.0.0.1', port });
+  up.once('connect', () => {
+    const headers = cleanHeaders(req.headers, credential, parsed.route.length ? visited : null);
+    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', '', '');
+    up.write(lines.join('\r\n')); if (head && head.length) up.write(head);
+    if (activeSockets && typeof activeSockets.add === 'function') {
+      activeSockets.add(socket); activeSockets.add(up);
+      const remove = () => { activeSockets.delete(socket); activeSockets.delete(up); };
+      socket.once('close', remove); up.once('close', remove);
+    }
+    socket.pipe(up); up.pipe(socket);
+  });
+  up.on('error', () => reject(socket, 502)); socket.on('error', () => up.destroy());
+}
+
+function reject(socket, code) { try { socket.end(`HTTP/1.1 ${code} Error\r\nConnection: close\r\n\r\n`); } catch (_) {} }
+
+module.exports = {
+  MAX_HOPS, ROUTE_DELIMITER, peerFromToken, peerAllows, canTransit, parseRoute, knownResource, allowedResource,
+  collectTopology, peerRouter, localRouter, forwardUpgrade,
+};

package/lib/proxy/node-proxy.js

@@ -0,0 +1,305 @@
+'use strict';
+// lib/proxy/node-proxy.js — reverse-proxy single-origin /node/<name> (design §4, §4b(2)).
+//
+// La superficie PIU' security-critical del progetto. Contratti duri (§4b(2)):
+//   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
+//      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
+//      config — mai derivato da input utente/header.
+//   5. Upgrade WS: STESSI check dell'HTTP (auth locale -> name strict -> inject
+//      token remoto). Parita' HTTP/WS.
+//   7. NIENTE proxy transitivo: /node/<a>/node/<b> -> 404 (espone SOLO la root
+//      locale del nodo remoto, mai il suo /node/*).
+//   8. Nodo irraggiungibile -> 502 JSON {error}, mai hang: timeout esplicito.
+//
+// Niente shell, niente http-proxy: proxy manuale con http.request (HTTP) e piping
+// raw socket TCP (upgrade WS). resolveNode/httpRequest/connect iniettabili (test).
+const http = require('node:http');
+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).
+const PROXY_TIMEOUT_MS = 30000;
+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']);
+
+// 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',
+]);
+
+// Header della RICHIESTA client da NON inoltrare upstream: hop-by-hop + i
+// client-supplied che potrebbero (a) impersonare/derivare l'upstream o (b)
+// confondere l'auth remota. Authorization viene RI-iniettato col token del nodo.
+function isStrippedRequestHeader(lk) {
+  if (HOP_BY_HOP.has(lk)) return true;
+  if (lk === 'authorization' || lk === 'cookie' || lk === 'host') return true;
+  if (lk.startsWith('proxy-')) return true;
+  if (lk === 'forwarded' || lk.startsWith('x-forwarded-')) return true;
+  return false;
+}
+
+function connectionOptions(headers) {
+  const names = new Set();
+  for (const [key, value] of Object.entries(headers || {})) {
+    if (key.toLowerCase() !== 'connection') continue;
+    const raw = Array.isArray(value) ? value.join(',') : String(value || '');
+    for (const item of raw.split(',')) {
+      const name = item.trim().toLowerCase();
+      if (/^[!#$%&'*+.^_`|~0-9a-z-]+$/.test(name)) names.add(name);
+    }
+  }
+  return names;
+}
+
+// Divide "/vps/api/x?y=1" -> { name:'vps', rest:'/api/x', search:'?y=1' }.
+// name RAW (non decodificato): validato poi contro l'allowlist strict, cosi'
+// '..', '%2e', nomi lunghi falliscono il regex -> 404. rest/search preservano
+// l'encoding originale e vengono inoltrati verbatim.
+function splitNodePath(afterNode) {
+  const qIdx = afterNode.indexOf('?');
+  const rawPath = qIdx >= 0 ? afterNode.slice(0, qIdx) : afterNode;
+  const search = qIdx >= 0 ? afterNode.slice(qIdx) : '';
+  const trimmed = rawPath.replace(/^\/+/, '');
+  if (!trimmed) return null; // '/node' o '/node/' senza name -> 404
+  const slash = trimmed.indexOf('/');
+  const name = slash >= 0 ? trimmed.slice(0, slash) : trimmed;
+  const rest = slash >= 0 ? trimmed.slice(slash) : '/';
+  return { name, rest, search };
+}
+
+// Proxy transitivo: il path inoltrato NON deve a sua volta essere un /node/*.
+// Controlla sia raw sia decodificato (il remoto normalizza il percent-encoding
+// in fase di routing, quindi '/%6eode/b' vale '/node/b').
+function isTransitiveRest(rest) {
+  const hit = (p) => p === '/node' || p.startsWith('/node/');
+  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) {
+  const out = {};
+  const dynamicHop = connectionOptions(headers);
+  for (const [k, v] of Object.entries(headers || {})) {
+    if (isStrippedRequestHeader(k.toLowerCase()) || dynamicHop.has(k.toLowerCase())) continue;
+    out[k] = v;
+  }
+  if (remoteToken) out.authorization = `Bearer ${remoteToken}`;
+  return out;
+}
+
+// Headers della RISPOSTA verso il browser: strip hop-by-hop (igiene proxy). Il
+// token remoto non viene MAI messo qui dal proxy; il nodo remoto non lo riflette.
+function sanitizeResponseHeaders(headers) {
+  const out = {};
+  const dynamicHop = connectionOptions(headers);
+  for (const [k, v] of Object.entries(headers || {})) {
+    if (HOP_BY_HOP.has(k.toLowerCase()) || dynamicHop.has(k.toLowerCase())) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+function notFound(res) { res.status(404).json({ error: 'not found' }); }
+
+// --- HTTP proxy middleware --------------------------------------------------
+// Montare come: app.use('/node', requireToken(token), createNodeProxy({...}))
+// -> req.url e' gia' il path DOPO /node (es. '/vps/api/x'); l'auth locale e' gia'
+// passata (requireToken davanti). Ordine interno: name strict -> no-transitive ->
+// resolve -> readonly -> proxy.
+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
+    const node = resolveNode(parsed.name);
+    if (!node) return notFound(res);                           // nome non in config -> 404 secco
+    if (readonly() && MUTATING.has(req.method)) {
+      return res.status(403).json({ error: 'READONLY: mutazione verso nodo bloccata' });
+    }
+    proxyHttp(req, res, node, parsed.rest, parsed.search, httpRequest);
+  };
+}
+
+function proxyHttp(req, res, node, rest, search, httpRequest) {
+  const options = {
+    host: '127.0.0.1',                 // §4b(2)#4 upstream SOLO loopback da config
+    port: node.localPort,
+    method: req.method,
+    // parita' col path WS: il token LOCALE eventualmente in query (?token=) non
+    // deve MAI arrivare al nodo remoto — l'auth upstream e' l'Authorization col
+    // token remoto iniettato da sanitizeRequestHeaders.
+    path: `${rest}${stripLocalTokenQuery(search)}`,
+    headers: sanitizeRequestHeaders(req.headers, node.token),
+  };
+  // http.request puo' lanciare in modo SINCRONO (es. header value con char
+  // invalido dal token del nodo) -> senza try/catch diventa un throw non gestito
+  // e Express emette una pagina 500 con lo stack (path interni). Chiudiamo in
+  // 502 JSON come gli altri errori upstream, senza esporre nulla. (fix audit).
+  let upstream;
+  try {
+    upstream = httpRequest(options, (up) => {
+      res.writeHead(up.statusCode, sanitizeResponseHeaders(up.headers));
+      up.pipe(res);
+    });
+  } catch (_) {
+    if (!res.headersSent) res.status(502).json({ error: 'node non raggiungibile' });
+    return;
+  }
+  upstream.setTimeout(PROXY_TIMEOUT_MS, () => upstream.destroy(new Error('upstream timeout')));
+  upstream.on('error', () => {
+    if (!res.headersSent) res.status(502).json({ error: 'node non raggiungibile' });
+    else res.destroy();
+  });
+  req.on('aborted', () => upstream.destroy());
+  req.pipe(upstream);
+}
+
+// --- WebSocket upgrade proxy (raw socket) -----------------------------------
+// Stessi check dell'HTTP, ma l'auth locale va fatta in TESTA (browser non puo'
+// settare Authorization sul WS -> token accettato anche via ?token=<local>).
+// Proxy trasparente a livello TCP: si inoltra la stessa upgrade request (header
+// sanificati + token remoto iniettato) all'upstream loopback e si fa piping raw
+// dei due socket. Nessun doppio handshake: l'Accept lo calcola l'upstream dalla
+// Sec-WebSocket-Key del client, che inoltriamo verbatim.
+function bearerFromUpgrade(req, url) {
+  const h = bearerFrom(req);
+  if (h) return h;
+  try { return url.searchParams.get('token') || ''; } catch (_) { return ''; }
+}
+
+function abortUpgrade(socket, code) {
+  const msg = http.STATUS_CODES[code] || 'Error';
+  try {
+    socket.write(
+      `HTTP/1.1 ${code} ${msg}\r\n` +
+      'Connection: close\r\n' +
+      'Content-Type: text/plain\r\n' +
+      `Content-Length: ${Buffer.byteLength(msg)}\r\n\r\n${msg}`,
+    );
+  } catch (_) { /* socket gia' morto */ }
+  try { socket.destroy(); } catch (_) {}
+}
+
+// Costruisce il blocco header raw dell'upgrade da inoltrare upstream. Preserva i
+// Sec-WebSocket-* e imposta Connection/Upgrade in modo controllato; strippa i
+// client-supplied pericolosi; inietta il token remoto. Rimuove ?token= locale.
+function buildUpgradeRequest(method, rest, search, headers, remoteToken, localPort) {
+  const lines = [];
+  const cleanSearch = stripLocalTokenQuery(search);
+  const clean = sanitizeRequestHeaders(headers, remoteToken);
+  lines.push(`${method} ${rest}${cleanSearch} HTTP/1.1`);
+  lines.push(`Host: 127.0.0.1:${localPort}`);
+  for (const [k, v] of Object.entries(clean)) {
+    const lk = k.toLowerCase();
+    if (lk === 'host' || lk === 'connection' || lk === 'upgrade') continue;
+    const val = Array.isArray(v) ? v.join(', ') : v;
+    lines.push(`${k}: ${val}`);
+  }
+  lines.push('Connection: Upgrade');
+  lines.push('Upgrade: websocket');
+  return `${lines.join('\r\n')}\r\n\r\n`;
+}
+
+function stripLocalTokenQuery(search) {
+  if (!search || search === '?') return '';
+  const sp = new URLSearchParams(search.slice(1));
+  sp.delete('token');
+  const s = sp.toString();
+  return s ? `?${s}` : '';
+}
+
+// handleNodeUpgrade — chiamato dal server.on('upgrade') per i path /node/*.
+// connect(port) -> duplex verso 127.0.0.1:port (default net.connect), seam test.
+function handleNodeUpgrade(ctx) {
+  const {
+    req, socket, head, resolveNode, verifyToken,
+    readonly = () => false, connect = defaultConnect, activeSockets = null,
+  } = ctx;
+  let url;
+  try { url = new URL(req.url, 'http://127.0.0.1'); } catch (_) { return abortUpgrade(socket, 400); }
+
+  // (1) AUTH LOCALE PRIMA DI TUTTO
+  if (!verifyToken(bearerFromUpgrade(req, url))) return abortUpgrade(socket, 401);
+
+  // (2) name strict + (7) no transitive
+  const afterNode = req.url.replace(/^\/node(?=\/|\?|$)/, '');
+  const parsed = splitNodePath(afterNode);
+  if (!parsed || !NODE_NAME_RE.test(parsed.name)) return abortUpgrade(socket, 404);
+  if (isTransitiveRest(parsed.rest)) return abortUpgrade(socket, 404);
+  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.
+  if (readonly()) return abortUpgrade(socket, 403);
+
+  // (3)(4) inject token remoto, upstream SOLO loopback da config
+  let upstream;
+  let settled = false;
+  let fail = (code) => { if (settled) return; settled = true; try { upstream && upstream.destroy(); } catch (_) {} abortUpgrade(socket, code); };
+  try {
+    upstream = connect(node.localPort);   // net.connect puo' lanciare sync su opzioni invalide (port NaN da config)
+  } catch (_) { return fail(502); }       // (parita' error-handling con proxyHttp: 502 JSON-equivalent, no stack)
+
+  const timer = setTimeout(() => fail(502), CONNECT_TIMEOUT_MS);
+  upstream.on('connect', () => {
+    clearTimeout(timer);
+    if (settled) { try { upstream.destroy(); } catch (_) {} return; }
+    // buildUpgradeRequest/write possono lanciare (header invalido). Settle DOPO il
+    // successo dei write: cosi' il catch -> fail(502) e' OPERATIVO (distrugge entrambi
+    // i socket e invia 502) invece di no-op. Prima dell'audit settled veniva messo a
+    // true PRIMA dei write: un throw li' rendeva fail() un no-op e lasciava entrambi i
+    // socket vivi (leak) senza alcun 502 al client (audit F5).
+    try {
+      upstream.write(buildUpgradeRequest(req.method, parsed.rest, parsed.search, req.headers, node.token, node.localPort));
+      if (head && head.length) upstream.write(head);
+    } catch (e) { return fail(502); }
+    settled = true;
+    if (activeSockets && typeof activeSockets.add === 'function') {
+      activeSockets.add(socket);
+      activeSockets.add(upstream);
+      const remove = () => {
+        try { activeSockets.delete(socket); } catch (_) {}
+        try { activeSockets.delete(upstream); } catch (_) {}
+      };
+      if (typeof socket.once === 'function') socket.once('close', remove);
+      if (typeof upstream.once === 'function') upstream.once('close', remove);
+    }
+    socket.on('error', () => { try { upstream.destroy(); } catch (_) {} });
+    upstream.on('error', () => { try { socket.destroy(); } catch (_) {} });
+    socket.pipe(upstream);
+    upstream.pipe(socket);
+  });
+  upstream.on('error', () => { clearTimeout(timer); fail(502); });
+}
+
+function defaultConnect(port) {
+  return net.connect({ host: '127.0.0.1', port });
+}
+
+module.exports = {
+  createNodeProxy,
+  handleNodeUpgrade,
+  // esposti per i test
+  splitNodePath, isTransitiveRest, sanitizeRequestHeaders, sanitizeResponseHeaders,
+  buildUpgradeRequest, stripLocalTokenQuery, isStrippedRequestHeader, connectionOptions, bearerFromUpgrade,
+  MUTATING, HOP_BY_HOP, PROXY_TIMEOUT_MS,
+};

package/lib/pty/attach.js

@@ -1,30 +1,55 @@
 'use strict';
+const { execFile } = require('node:child_process');
+const os = require('node:os');
 const { loadPty } = require('./provider.js');
 
 // Opens `tmux attach` inside a real PTY, non-destructive for other clients.
-// Size model (decisione DAG 2026-07-09, "segue il focus"): la sessione usa
-// `window-size latest` (impostato dal bridge) e i client web NON readonly
-// PARTECIPANO alla geometria — chi è attivo per ultimo comanda. Tornare sul
-// desktop e digitare riporta la sessione grande; il telefono la restringe
-// solo mentre lo usi. I viewer readonly restano ignore-size (mai guidare).
-//   readonly → `-f read-only,ignore-size` (read-only limita anche copy-mode/KeyBar)
+//
+// Size model (emendamento post-audit §5b — deck multi-finestra): la sessione usa
+// `window-size latest` (impostato dal bridge). Un client "possiede" la geometria
+// SOLO se NON è `ignore-size`. I tile grid/deck attaccano `ignore-size` (non
+// contendono la geometria da N finestre/N ResizeObserver); l'owner è il tile col
+// FOCUS, promosso a runtime via `refresh-client -f '!ignore-size'` (demozione col
+// flag `ignore-size`). La single-view / gli attach diretti restano owner di
+// default (takeSize non specificato → drive).
+//   - takeSize esplicito vince sempre (true = owner, false = ignore-size)
+//   - readonly ⇒ SEMPRE ignore-size (un viewer non guida mai)
+//   - readonly → `-f read-only,ignore-size` (read-only limita anche copy-mode/KeyBar)
 function openAttach(session, opts = {}) {
-  const { readonly = false, takeSize = false, cols = 80, rows = 24, tmuxBin = 'tmux' } = opts;
+  const { readonly = false, cols = 80, rows = 24, tmuxBin = 'tmux' } = opts;
+  const drives = opts.takeSize !== undefined
+    ? !!opts.takeSize
+    : (opts.ignoreSize !== undefined ? !opts.ignoreSize : true);
+  const ignoreSize = readonly || !drives;
   const pty = loadPty();
   const args = ['attach-session', '-t', session];
-  if (readonly) args.push('-f', 'read-only,ignore-size');
+  const flags = [];
+  if (readonly) flags.push('read-only');
+  if (ignoreSize) flags.push('ignore-size');
+  if (flags.length) args.push('-f', flags.join(','));
   const term = pty.spawn(tmuxBin, args, {
     name: 'xterm-256color',
     cols, rows,
-    cwd: process.env.HOME,
+    cwd: process.env.HOME || os.homedir(),
     env: process.env,
   });
+  // tty del client tmux (es. /dev/pts/N): identifica QUESTO client per la
+  // promozione/demozione runtime del size-owner via `refresh-client -t <tty>`.
+  const tty = term.ptsName || term._pty || null;
+  const setFlags = (spec) => {
+    if (!tty) return;
+    try { execFile(tmuxBin, ['refresh-client', '-t', tty, '-f', spec], () => {}); } catch (_) {}
+  };
   return {
+    tty,
     write: (data) => term.write(data),
     resize: (c, r) => { try { term.resize(c, r); } catch (_) {} },
     onData: (cb) => term.onData(cb),
     onExit: (cb) => term.onExit(cb),
     kill: () => { try { term.kill(); } catch (_) {} },
+    // Promozione a size-owner (focus). I readonly non guidano MAI la geometria.
+    promote: () => { if (!readonly) setFlags('!ignore-size'); },
+    demote: () => setFlags('ignore-size'),
   };
 }
 module.exports = { openAttach };

package/lib/pty/provider.js

@@ -4,19 +4,34 @@
 // `tmux attach` ESIGE un vero tty: il fallback child_process NON è accettabile qui.
 let _cached = null;
 
+function providerCandidates({ platform = process.platform, arch = process.arch, env = process.env } = {}) {
+  const isTermux = platform === 'android'
+    || (env.PREFIX || '').includes('com.termux');
+  if (isTermux) return ['@mmmbuto/node-pty-android-arm64', 'node-pty'];
+  if (platform === 'darwin') {
+    return arch === 'arm64'
+      ? ['@lydell/node-pty-darwin-arm64', 'node-pty']
+      : ['@lydell/node-pty-darwin-x64', 'node-pty'];
+  }
+  if (platform === 'linux' && arch === 'arm64') {
+    return ['@lydell/node-pty-linux-arm64', 'node-pty'];
+  }
+  return ['@lydell/node-pty-linux-x64', 'node-pty'];
+}
+
 function loadPty() {
   if (_cached) return _cached;
   const isTermux = process.platform === 'android'
     || (process.env.PREFIX || '').includes('com.termux');
-  const candidates = isTermux
-    ? ['@mmmbuto/node-pty-android-arm64', 'node-pty']
-    : ['node-pty', '@lydell/node-pty-linux-x64', '@mmmbuto/node-pty-android-arm64'];
+  const candidates = providerCandidates();
   for (const mod of candidates) {
     try {
       const pty = require(mod);
       // Accept ONLY a provider with a complete PTY API; never child_process.
       if (pty && typeof pty.spawn === 'function') {
-        const t = pty.spawn(process.env.SHELL || '/bin/sh', ['-c', 'true'], { cols: 80, rows: 24 });
+        const fallbackShell = isTermux && process.env.PREFIX
+          ? require('node:path').join(process.env.PREFIX, 'bin', 'sh') : '/bin/sh';
+        const t = pty.spawn(process.env.SHELL || fallbackShell, ['-c', 'true'], { cols: 80, rows: 24 });
         const ok = t && typeof t.write === 'function' && typeof t.onData === 'function'
           && typeof t.resize === 'function' && typeof t.kill === 'function';
         try { t.kill(); } catch (_) {}
@@ -28,6 +43,6 @@ function loadPty() {
       }
     } catch (_) { /* prova il prossimo */ }
   }
-  throw new Error('no real PTY provider available (need node-pty or @mmmbuto/node-pty-android-arm64)');
+  throw new Error('no real PTY provider available (install a platform prebuilt or node-pty build prerequisites)');
 }
-module.exports = { loadPty };
+module.exports = { loadPty, providerCandidates };