@mmmbuto/nexuscrew 0.8.38 → 0.8.40

package/lib/mcp/server.js

@@ -20,10 +20,12 @@
 const readline = require('node:readline');
 const crypto = require('node:crypto');
 const os = require('node:os');
+const path = require('node:path');
 const { execFile } = require('node:child_process');
 const { loadConfig } = require('../config.js');
 const { readTokenSafe } = require('../auth/token.js');
 const { isValidSession } = require('../files/store.js');
+const { loadOrCreateBridgeSecret, signedHeaders } = require('../audio/bridge-auth.js');
 const VERSION = require('../../package.json').version;
 const MCP_COMPANIONS = require('../../mcp-companions.json');
 const { TOOLS, IDENTITY_CODE, IDENTITY_REMEDIATION } = require('./tools.js');
@@ -162,17 +164,39 @@ function createMcpServer(opts = {}) {
     throw new Error('token NexusCrew non leggibile: il server e\' inizializzato? (nexuscrew init)');
   }
 
-  async function api(method, apiPath, body) {
+  // Segreto del bridge: file 0600 accanto al token, distinto dal token stesso.
+  // Serve dove il Bearer non basta — Audio Share — perche' il Bearer prova solo
+  // "qualcuno in loopback ce l'ha", non "questa e' la cella X".
+  const bridgeKeyPath = () => cfg.audioBridgeSecretPath || path.join(path.dirname(cfg.tokenPath), 'audio-bridge.key');
+
+  // `opts.signedSession` attiva la firma HMAC del bridge: copre metodo, path,
+  // sessione, timestamp, nonce e i BYTE del body effettivamente inviati. Per
+  // questo il payload viene serializzato UNA volta sola e riusato: firmare un
+  // JSON e spedirne un altro, anche solo con un ordine di chiavi diverso,
+  // produrrebbe una firma valida per un corpo che il server non vede mai.
+  async function api(method, apiPath, body, opts = {}) {
     const token = readToken();
+    const payload = body !== undefined ? JSON.stringify(body) : undefined;
+    let signed = {};
+    if (opts.signedSession) {
+      try {
+        signed = signedHeaders(loadOrCreateBridgeSecret(bridgeKeyPath()), {
+          method, path: apiPath, session: opts.signedSession, rawBody: payload === undefined ? '' : payload,
+        });
+      } catch (_) {
+        throw new Error('segreto bridge audio non leggibile: il server e\' inizializzato? (nexuscrew init)');
+      }
+    }
     let r;
     try {
       r = await fetchImpl(`${baseUrl}${apiPath}`, {
         method,
         headers: {
           authorization: `Bearer ${token}`,
-          ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+          ...signed,
+          ...(payload !== undefined ? { 'content-type': 'application/json' } : {}),
         },
-        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        ...(payload !== undefined ? { body: payload } : {}),
         signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
       });
     } catch (e) {

package/lib/mcp/tools.js

@@ -496,6 +496,148 @@ const TOOLS = [
       return out;
     },
   },
+  {
+    name: 'nc_speak',
+    description: 'Speak un utterance audio verso un nodo target (exact instanceId). Ritorna un receipt caller-scoped con status per-endpoint (refused|unreachable|accepted|spoken|unknown) e attribution; MAI text/lang/voice o aggregate success. L\'origin genera un utteranceId immutabile se omesso.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'exact target node instanceId (32 hex)' },
+        text: { type: 'string', description: 'utterance text (bounded)' },
+        lang: { type: 'string', description: 'BCP-47 lang hint (optional)' },
+        voice: { type: 'string', description: 'voice id hint (optional)' },
+        urgency: { type: 'string', enum: ['normal', 'high'], description: 'high urgency non bypassa i rate limit' },
+        utteranceId: { type: 'string', description: 'immutable id (generato se omesso)' },
+      },
+      required: ['target', 'text'],
+    },
+    async handler(args, ctx) {
+      const target = argString(args, 'target', { required: true, max: 32 });
+      const text = argString(args, 'text', { required: true, max: 320 });
+      const lang = argString(args, 'lang', { max: 35 });
+      const voice = argString(args, 'voice', { max: 64 });
+      if (args.urgency !== undefined && args.urgency !== 'normal' && args.urgency !== 'high') {
+        throw new Error('urgency deve essere "normal" o "high"');
+      }
+      const urgency = args.urgency === 'high' ? 'high' : 'normal';
+      const utteranceId = argString(args, 'utteranceId', { max: 128 });
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_speak', identity.code);
+      // La sessione NON viaggia nel body: sarebbe una dichiarazione, e una
+      // dichiarazione e' falsificabile da chiunque abbia il token della UI.
+      // Viaggia dentro la firma HMAC del bridge, che il server verifica prima di
+      // attribuire l'enunciato a una cella.
+      const payload = { target, text, urgency, ...(lang ? { lang } : {}), ...(voice ? { voice } : {}), ...(utteranceId ? { utteranceId } : {}) };
+      const receipt = await ctx.api('POST', '/api/audio/speak', payload, { signedSession: session });
+      return { receipt };
+    },
+  },
+  {
+    name: 'nc_speak_status',
+    description: 'Interroga lo status di uno speak per utteranceId (read-only). Ritorna il receipt caller-scoped redacted (status/reason/attribution); MAI text/lang/voice/secret.',
+    inputSchema: {
+      type: 'object',
+      properties: { utteranceId: { type: 'string', description: 'utterance id da interrogare' } },
+      required: ['utteranceId'],
+    },
+    annotations: { readOnlyHint: true },
+    async handler(args, ctx) {
+      const utteranceId = argString(args, 'utteranceId', { required: true, max: 128 });
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_speak_status', identity.code);
+      const receipt = await ctx.api('GET', `/api/audio/speak/status/${encodeURIComponent(utteranceId)}`, undefined, { signedSession: session });
+      return { receipt };
+    },
+  },
+  {
+    name: 'nc_speak_stop',
+    description: 'Ferma un enunciato su un nodo target. Con utteranceId ferma quello specifico (solo se e\' del chiamante), senza utteranceId ferma tutto sul target. Lo stop locale del nodo resta sovrano e non dipende da questa chiamata.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'exact target node instanceId (32 hex)' },
+        utteranceId: { type: 'string', description: 'enunciato da fermare; omesso = tutti gli enunciati del target' },
+      },
+      required: ['target'],
+    },
+    async handler(args, ctx) {
+      const target = argString(args, 'target', { required: true, max: 32 });
+      const utteranceId = argString(args, 'utteranceId', { max: 128 });
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_speak_stop', identity.code);
+      const receipt = await ctx.api('POST', '/api/audio/stop', {
+        target, ...(utteranceId ? { utteranceId } : {}),
+      }, { signedSession: session });
+      return { receipt };
+    },
+  },
+  {
+    name: 'nc_speak_group',
+    description: 'Speak verso un gruppo audio locale nominato. Il gruppo espande solo instanceId esatti: primary-failover prova un endpoint alla volta, fanout e esplicito. Ritorna subito un receipt per endpoint; usa nc_speak_group_status per gli aggiornamenti. Un gruppo non concede consenso e non aggira liveness/ACL del target.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        group: { type: 'string', description: 'nome del gruppo audio locale (a-z, 0-9, trattini)' },
+        text: { type: 'string', description: 'utterance text (bounded)' },
+        lang: { type: 'string', description: 'BCP-47 lang hint (optional)' },
+        voice: { type: 'string', description: 'voice id hint (optional)' },
+        urgency: { type: 'string', enum: ['normal', 'high'], description: 'high urgency non bypassa i rate limit' },
+        utteranceId: { type: 'string', description: 'immutable id (generato se omesso)' },
+      },
+      required: ['group', 'text'],
+    },
+    async handler(args, ctx) {
+      const group = argString(args, 'group', { required: true, max: 32 });
+      const text = argString(args, 'text', { required: true, max: 320 });
+      const lang = argString(args, 'lang', { max: 35 });
+      const voice = argString(args, 'voice', { max: 64 });
+      if (args.urgency !== undefined && args.urgency !== 'normal' && args.urgency !== 'high') {
+        throw new Error('urgency deve essere "normal" o "high"');
+      }
+      const urgency = args.urgency === 'high' ? 'high' : 'normal';
+      const utteranceId = argString(args, 'utteranceId', { max: 128 });
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_speak_group', identity.code);
+      const receipt = await ctx.api('POST', '/api/audio/groups/speak', {
+        group, text, urgency,
+        ...(lang ? { lang } : {}), ...(voice ? { voice } : {}), ...(utteranceId ? { utteranceId } : {}),
+      }, { signedSession: session });
+      return { receipt };
+    },
+  },
+  {
+    name: 'nc_speak_group_status',
+    description: 'Interroga lo status per-endpoint di un gruppo audio (read-only). Il receipt e caller-scoped e non contiene testo, lingua, voce o successi aggregati.',
+    inputSchema: {
+      type: 'object',
+      properties: { utteranceId: { type: 'string', description: 'utterance id del gruppo' } },
+      required: ['utteranceId'],
+    },
+    annotations: { readOnlyHint: true },
+    async handler(args, ctx) {
+      const utteranceId = argString(args, 'utteranceId', { required: true, max: 128 });
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_speak_group_status', identity.code);
+      const receipt = await ctx.api('GET', `/api/audio/groups/status/${encodeURIComponent(utteranceId)}`, undefined, { signedSession: session });
+      return { receipt };
+    },
+  },
+  {
+    name: 'nc_speak_group_stop',
+    description: 'Ferma un gruppo audio per utteranceId: blocca i candidati non ancora tentati e invia Stop a ogni endpoint gia ammesso. Lo Stop locale del nodo resta sovrano anche offline.',
+    inputSchema: {
+      type: 'object',
+      properties: { utteranceId: { type: 'string', description: 'utterance id del gruppo da fermare' } },
+      required: ['utteranceId'],
+    },
+    async handler(args, ctx) {
+      const utteranceId = argString(args, 'utteranceId', { required: true, max: 128 });
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_speak_group_stop', identity.code);
+      const receipt = await ctx.api('POST', '/api/audio/groups/stop', { utteranceId }, { signedSession: session });
+      return { receipt };
+    },
+  },
 ];
 
 module.exports = {

package/lib/nodes/commands.js

@@ -416,36 +416,46 @@ async function nodesTest(opts) {
     return { code: 1, result: 'tunnel-down', diagnostic };
   }
 
-  const httpProbe = opts.httpProbe || defaultHttpProbe;
-  const base = `http://127.0.0.1:${node.localPort}`;
-
-  // health: GET / non autenticato -> 2xx significa "server remoto raggiungibile via tunnel".
-  let health;
-  try { health = await httpProbe(`${base}/`, {}); }
-  catch (e) { health = { ok: false, error: e && e.message }; }
-  if (!health || !health.ok) {
-    const diagnostic = tunnel.diagnoseTunnel(home, node);
-    const realCause = diagnostic.code !== 'transport-ready' ? diagnostic.detail : ((health && health.error) || 'server HTTP non raggiungibile');
-    log(`nodes test [${name}]: HEALTH KO — ${realCause}${diagnostic.hint ? ` · ${diagnostic.hint}` : ''}`);
-    return { code: 1, result: 'health-ko', diagnostic: diagnostic.code === 'transport-ready'
-      ? { stage: 'http', code: 'peer-http-unreachable', detail: realCause, hint: 'verifica la porta NexusCrew contenuta nel link' }
-      : diagnostic };
-  }
-
-  // token: GET /api/config con Bearer del nodo -> 200 ok, 401 token KO.
   if (!node.token) {
     log(`nodes test [${name}]: ASSOCIAZIONE INCOMPLETA — rimuovi il nodo e ripeti il pairing dalla PWA`);
     return { code: 1, result: 'token-missing' };
   }
-  let authed;
-  try { authed = await httpProbe(`${base}/api/config`, { authorization: `Bearer ${node.token}` }); }
-  catch (e) { authed = { ok: false, error: e && e.message }; }
-  if (authed && authed.status === 200) {
-    log(`nodes test [${name}]: OK — tunnel up, health ok, token valido`);
-    return { code: 0, result: 'ok' };
+
+  // The per-peer token is a federation credential accepted by the remote
+  // peer's acceptToken. It is deliberately NOT the remote browser/UI token,
+  // so probing /api/config with it always returns a misleading 401. Use the
+  // same authenticated, identity-bound health endpoint as the live topology.
+  const probe = opts.federationProbe || federation.probeHealth;
+  let health;
+  try {
+    health = await probe({
+      port: node.localPort, token: node.token, expectedInstanceId: node.nodeId || null,
+      fetchImpl: opts.fetchImpl, timeoutMs: opts.timeoutMs,
+    });
+  } catch (_) {
+    health = {
+      transport: 'down', auth: 'unknown', reachability: 'unknown',
+      status: 'down', detail: 'peer non raggiungibile',
+    };
+  }
+  if (health && health.status === 'healthy') {
+    log(`nodes test [${name}]: OK — tunnel e federation autenticati`);
+    return { code: 0, result: 'ok', health };
   }
-  log(`nodes test [${name}]: CREDENZIALE KO — il pairing non e' piu' valido (status ${(authed && authed.status) || '?'}); ripeti il pairing dalla PWA`);
-  return { code: 1, result: 'token-ko' };
+  if (health && health.auth === 'failed') {
+    log(`nodes test [${name}]: CREDENZIALE KO — ${health.detail || 'federation 401'}; ripeti il pairing dalla PWA`);
+    return { code: 1, result: 'token-ko', health };
+  }
+  const diagnostic = tunnel.diagnoseTunnel(home, node);
+  const detail = (health && health.detail)
+    || (diagnostic.code !== 'transport-ready' ? diagnostic.detail : 'peer federation non raggiungibile');
+  log(`nodes test [${name}]: HEALTH KO — ${detail}${diagnostic.hint ? ` · ${diagnostic.hint}` : ''}`);
+  return {
+    code: 1, result: 'health-ko', health,
+    diagnostic: diagnostic.code === 'transport-ready'
+      ? { stage: 'http', code: 'peer-federation-unreachable', detail, hint: 'verifica il tunnel e la porta NexusCrew contenuta nel link' }
+      : diagnostic,
+  };
 }
 
 // probe HTTP di default (fetch built-in, Node >=18). Ritorna {ok, status}.

package/lib/nodes/tunnel-supervisor.js

@@ -21,6 +21,17 @@ const ownershipGraceMs = Number.isFinite(ownershipGraceRaw) && ownershipGraceRaw
 const reverseFailureMaxRaw = Number(process.env.NEXUSCREW_TUNNEL_REVERSE_FAILURE_MAX || 8);
 const reverseFailureMax = Number.isInteger(reverseFailureMaxRaw) && reverseFailureMaxRaw >= 1
   ? Math.min(reverseFailureMaxRaw, 32) : 8;
+// Once the initial reverse-forward budget is exhausted the supervisor does NOT
+// die: it stays "degraded" and retries at the fixed production cadence of 60s,
+// so a transient reverse listener on the hub (e.g. a mobile reconnect) heals on
+// its own without an OFF/ON.  A short cadence is a test-only seam, never a
+// production runtime override: otherwise a bad environment value could recreate
+// the retry storm that this breaker is meant to prevent.
+const steadyRetryTestMode = process.env.NEXUSCREW_TUNNEL_TEST_MODE === '1';
+const steadyRetryMsRaw = Number(steadyRetryTestMode ? (process.env.NEXUSCREW_TUNNEL_STEADY_RETRY_MS || 60000) : 60000);
+const steadyRetryMinMs = steadyRetryTestMode ? 1 : 60000;
+const steadyRetryMs = Number.isFinite(steadyRetryMsRaw) && steadyRetryMsRaw >= steadyRetryMinMs
+  ? Math.min(steadyRetryMsRaw, 120000) : 60000;
 if (!sshBin || !statePath || !pidPath || !runId) process.exit(2);
 
 let child = null;
@@ -92,6 +103,7 @@ function probeForward(expectedChild) {
     if (stopping || child !== expectedChild || !child || child.exitCode != null) return;
     if (ready) {
       attempt = 0;
+      reverseFailures = 0;
       logEvent(`forward ready stableMs=${stableMs}`);
       if (!writeState('transport-ready', { sshPid: child.pid, stableMs, probe: 'tcp-forward' })) stop();
       return;
@@ -137,14 +149,28 @@ function scheduleRetry(detail) {
   retryTimer = setTimeout(run, delayMs);
 }
 
-function terminalFailure(diagnosis) {
+// Bounded, attributable degraded state. The supervisor stays alive, advertises
+// the reverse failure class plus the negotiated reversePort and the honest
+// remote-listener attribution (unknown without hub privilege), then retries on
+// a fixed cadence. It never exits on a reverse-forward failure: the tunnel
+// self-heals when the channel frees up.
+function enterDegraded(diagnosis) {
+  if (stopping) return finish();
   const safe = diagnosis || { code: 'reverse-forward-failed', detail: 'canale inverso non disponibile' };
-  logEvent(`ssh terminal failure code=${safe.code} attempts=${reverseFailures}`);
-  writeState('failed', {
+  if (reverseFailures > reverseFailureMax) reverseFailures = reverseFailureMax;
+  // `ownsGeneration()` only proves that THIS local supervisor owns its pidfile;
+  // it cannot identify the process holding a listener on the hub.  Never turn
+  // local pidfile ownership into a false remote-listener attribution.
+  const ownership = 'unknown';
+  logEvent(`ssh degraded code=${safe.code} reversePort=${reversePort || 'none'} ownership=${ownership} failures=${reverseFailures} steadyRetryMs=${steadyRetryMs}`);
+  if (!writeState('degraded', {
     code: safe.code, detail: safe.detail,
-    ...(safe.hint ? { hint: safe.hint } : {}), terminal: true,
-  });
-  process.exit(0);
+    ...(safe.hint ? { hint: safe.hint } : {}),
+    reversePort, ownership, steadyRetryMs, terminal: false,
+  })) return stop();
+  // Keep the backoff counter honest for observers; the degraded retry is fixed.
+  if (attempt < reverseFailureMax) attempt = reverseFailureMax;
+  retryTimer = setTimeout(run, steadyRetryMs);
 }
 
 function run() {
@@ -176,7 +202,7 @@ function run() {
     const reverseFailure = diagnosis && ['reverse-forward-bind', 'reverse-forward-failed'].includes(diagnosis.code);
     if (reverseFailure) {
       reverseFailures += 1;
-      if (reverseFailures >= reverseFailureMax) return terminalFailure(diagnosis);
+      if (reverseFailures >= reverseFailureMax) return enterDegraded(diagnosis);
     } else {
       reverseFailures = 0;
     }

package/lib/nodes/tunnel.js

@@ -290,6 +290,19 @@ function readTunnelState(home, name) {
       const owned = state.supervisorPid === meta.pid && (!meta.runId || state.runId === meta.runId);
       if (!owned) return { status: 'down', pid: meta.pid, since: meta.startTs || null, reason: 'starting' };
       if (state.status === 'failed' && state.terminal === true) return terminalState();
+      if (state.status === 'degraded') {
+        return {
+          status: 'down', phase: 'degraded', reason: 'degraded', pid: meta.pid, since: meta.startTs || null,
+          ...(typeof state.code === 'string' ? { code: state.code } : {}),
+          ...(typeof state.detail === 'string' ? { detail: state.detail } : {}),
+          ...(typeof state.hint === 'string' ? { hint: state.hint } : {}),
+          ...(Number.isInteger(state.reversePort) ? { reversePort: state.reversePort } : {}),
+          ...(typeof state.ownership === 'string' ? { ownership: state.ownership } : {}),
+          ...(Number.isInteger(state.attempt) ? { attempt: state.attempt } : {}),
+          ...(Number.isFinite(state.steadyRetryMs) ? { retryInMs: state.steadyRetryMs } : {}),
+          ...(transport ? { transport } : {}),
+        };
+      }
       if (state.status === 'transport-ready' || state.status === 'up') {
         return { status: 'up', phase: 'transport-ready', pid: meta.pid, since: meta.startTs || null,
           ...(Number.isInteger(state.attempt) ? { attempt: state.attempt } : {}), ...(transport ? { transport } : {}) };
@@ -330,6 +343,14 @@ function diagnoseTunnel(home, node, state = null) {
       detail: `connessione SSH in retry${Number.isInteger(current.attempt) ? ` (tentativo ${current.attempt + 1})` : ''}`,
       hint: 'usa Test connessione per vedere la causa; verifica target SSH, chiave e porta' };
   }
+  if (current.reason === 'degraded' || current.phase === 'degraded') {
+    return {
+      stage: 'ssh', code: current.code || 'reverse-forward-failed', status: 'down', phase: 'degraded',
+      detail: current.detail || 'canale inverso non disponibile, retry fisso in corso',
+      hint: current.hint || 'il tunnel resta attivo e riprovera automaticamente; verifica il listener reverse sul hub',
+      ...(Number.isInteger(current.reversePort) ? { reversePort: current.reversePort } : {}),
+    };
+  }
   if (current.reason === 'failed' || current.phase === 'failed') {
     return {
       stage: 'ssh', code: current.code || 'ssh-terminal-failure', status: 'down', phase: 'failed',

package/lib/proxy/federation.js

@@ -10,6 +10,7 @@ const { safeEqual } = require('../nodes/peering.js');
 const {
   sanitizeRequestHeaders, sanitizeResponseHeaders, stripLocalTokenQuery,
 } = require('./node-proxy.js');
+const { signHop, HOP_HEADER } = require('./hop-proof.js');
 
 const MAX_HOPS = 4;
 const ROUTE_DELIMITER = '_';
@@ -71,6 +72,10 @@ function knownResource(resource) {
     // Hydra: the rest of /settings stays unreachable.
     || resource === '/settings/peering/invite'
     || resource === '/ws'
+    || resource === '/audio/capability'
+    || resource === '/audio/speak'
+    || resource === '/audio/speak/status'
+    || resource === '/audio/stop'
     || /^\/fleet\/(status|schema|definitions|credentials\/status|credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-cell|edit-cell|remove-cell|restore-cells|restore-engines)$/.test(resource);
 }
 
@@ -97,9 +102,25 @@ function allowedResource(resource, method = 'GET') {
   if (resource === '/ws') return method === 'GET';
   if (/^\/fleet\/(status|schema|definitions|credentials\/status)$/.test(resource)) return method === 'GET';
   if (/^\/fleet\/(credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-cell|edit-cell|remove-cell|restore-cells|restore-engines)$/.test(resource)) 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.
+  if (resource === '/audio/capability') return method === 'GET';
+  if (resource === '/audio/speak') return method === 'POST';
+  if (resource === '/audio/speak/status') return method === 'POST';
+  if (resource === '/audio/stop') return method === 'POST';
   return false;
 }
 
+// READONLY blocca ogni mutazione che crea o modifica stato, con due eccezioni
+// audio deliberate: interrogare lo status federato usa POST soltanto per
+// trasportare l'attestazione della cella, e Stop e' un'azione di sicurezza che
+// deve poter zittire un endpoint anche quando quel nodo e' READONLY. Speak
+// resta naturalmente bloccato.
+function readonlyBlocksFederated(resource, method) {
+  if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) return false;
+  return resource !== '/audio/speak/status' && resource !== '/audio/stop';
+}
+
 function allowedQuery(resource, method, rawUrl) {
   if (!resource.startsWith('/diagnostics/')) return true;
   const index = String(rawUrl || '').indexOf('?');
@@ -117,17 +138,20 @@ function allowedQuery(resource, method, rawUrl) {
   return true;
 }
 
-function cleanHeaders(headers, credential, visited = null) {
+function cleanHeaders(headers, credential, visited = null, hopProof = 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(',');
+  // 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;
   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) => {
+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);
   });
   up.setTimeout(30000, () => up.destroy());
@@ -135,22 +159,28 @@ function proxyHttp(req, res, { port, path, credential, visited = null }) {
   req.pipe(up);
 }
 
-function routeHandler({ nodesPath, localPort, localCredential, ingress = null, readonly = () => false }) {
+function routeHandler({ nodesPath, localPort, localCredential, ingress = null, readonly = () => false, hopSecret = null }) {
   return (req, res) => {
     const parsed = parseRoute(req.url);
     if (!parsed || !allowedResource(parsed.resource, req.method)
       || !allowedQuery(parsed.resource, req.method, req.url)) 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' });
+    if (readonly() && readonlyBlocksFederated(parsed.resource, 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) {
+      // 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
+      // hop e' cio' che la distingue, ed e' legata a metodo, path e catena.
+      const path = `/api${parsed.resource}${queryOf(req.url)}`;
+      const secret = typeof hopSecret === 'function' ? hopSecret() : hopSecret;
       return proxyHttp(req, res, {
         port: typeof localPort === 'function' ? localPort() : localPort,
-        path: `/api${parsed.resource}${queryOf(req.url)}`,
+        path,
         credential: localCredential(),
         visited,
+        hopProof: signHop(secret, { method: req.method, path, visited }),
       });
     }
     const next = st && store.getNode(st, parsed.route[0]);
@@ -514,7 +544,7 @@ async function collectLocalTopology({
   return { instanceId: live.instanceId, nodes };
 }
 
-function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly = () => false, version = null, roles = null }) {
+function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly = () => false, version = null, roles = null, hopSecret = null }) {
   const r = express.Router();
   r.use((req, res, next) => {
     const peer = peerFromToken(nodesPath, bearerFrom(req));
@@ -576,13 +606,13 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
       return res.status(e.status || 500).json({ error: String(e && e.message || e), ...(e.code ? { code: e.code } : {}) });
     }
   });
-  r.use('/route', (req, res) => routeHandler({ nodesPath, localPort, localCredential, ingress: req.peer, readonly })(req, res));
+  r.use('/route', (req, res) => routeHandler({ nodesPath, localPort, localCredential, ingress: req.peer, readonly, hopSecret })(req, res));
   return r;
 }
 
-function localRouter({ nodesPath, localPort, localCredential, readonly }) {
+function localRouter({ nodesPath, localPort, localCredential, readonly, hopSecret = null }) {
   const r = express.Router();
-  r.use((req, res) => routeHandler({ nodesPath, localPort, localCredential, readonly })(req, res));
+  r.use((req, res) => routeHandler({ nodesPath, localPort, localCredential, readonly, hopSecret })(req, res));
   return r;
 }
 
@@ -624,7 +654,7 @@ function reject(socket, code) { try { socket.end(`HTTP/1.1 ${code} Error\r\nConn
 
 module.exports = {
   MAX_HOPS, ROUTE_DELIMITER, TOPOLOGY_PEER_TIMEOUT_MS,
-  peerFromToken, peerAllows, canTransit, parseRoute, knownResource, allowedResource, allowedQuery,
+  peerFromToken, peerAllows, canTransit, parseRoute, knownResource, allowedResource, allowedQuery, readonlyBlocksFederated,
   collectTopology, collectTopologyDetailed, collectLocalTopology, peerRouter, localRouter, forwardUpgrade,
   probeHealth, waitForHealthyPeer, notifyHubShare, reconcilePeerShare, runShareRevokeBoot,
 };

package/lib/proxy/hop-proof.js

@@ -0,0 +1,50 @@
+'use strict';
+// lib/proxy/hop-proof.js — prova che una richiesta arrivata su /api e' l'ULTIMO
+// hop di una route federata generata da QUESTO processo, non un POST diretto di
+// un client locale che ha semplicemente scritto gli header a mano.
+//
+// Perche' serve. `controlledVisited()` lega gia' `x-nexuscrew-visited` al peer
+// autenticato dal suo acceptToken, ma l'ultimo hop entra in `/api/<resource>`
+// con il Bearer LOCALE: a quel punto l'handler non distingue piu' un inbound
+// federato da una richiesta diretta di chiunque possieda il token della UI.
+// `cleanHeaders()` cancella gia' `x-nexuscrew-{route,visited,hop}` da ogni
+// header in ingresso, quindi il canale e' riservato: basta renderlo non
+// riproducibile. La firma usa un segreto casuale per-processo, mai su disco,
+// mai esposto da un'API: un client locale non puo' calcolarla.
+//
+// Il payload firmato include metodo e path oltre alla catena visited, cosi' una
+// prova non e' trasportabile su un'altra risorsa o su un altro verbo.
+const crypto = require('node:crypto');
+
+const HOP_HEADER = 'x-nexuscrew-hop';
+const PREFIX = 'NEXUSCREW-HOP-V1';
+
+function createHopSecret() {
+  return crypto.randomBytes(32);
+}
+
+function canonicalHop({ method, path: reqPath, visited }) {
+  const chain = Array.isArray(visited) ? visited.join(',') : String(visited || '');
+  return `${PREFIX}\n${String(method || '').toUpperCase()}\n${String(reqPath || '')}\n${chain}`;
+}
+
+// signHop(): hex HMAC-SHA256. Ritorna null senza segreto, cosi' un server che
+// non ha inizializzato la prova non emette un header vuoto interpretabile.
+function signHop(secret, parts) {
+  if (!secret) return null;
+  return crypto.createHmac('sha256', secret).update(canonicalHop(parts)).digest('hex');
+}
+
+// verifyHop(): confronto timing-safe. Fail-closed su qualunque anomalia
+// (segreto assente, header assente, lunghezza diversa, hex non valido).
+function verifyHop(secret, parts, proof) {
+  if (!secret || typeof proof !== 'string' || !/^[a-f0-9]{64}$/i.test(proof)) return false;
+  const expected = signHop(secret, parts);
+  if (!expected) return false;
+  const a = Buffer.from(expected, 'hex');
+  const b = Buffer.from(proof.toLowerCase(), 'hex');
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+
+module.exports = { createHopSecret, signHop, verifyHop, canonicalHop, HOP_HEADER };