@mmmbuto/nexuscrew 0.8.39 → 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/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 };

package/lib/server.js

@@ -32,6 +32,17 @@ const nodesInventory = require('./nodes/inventory.js');
 const topologyCache = require('./nodes/topology-cache.js');
 const { createNodeProxy, handleNodeUpgrade } = require('./proxy/node-proxy.js');
 const federation = require('./proxy/federation.js');
+const { audioRoutes } = require('./audio/routes.js');
+const { isConsent: isAudioConsent } = require('./audio/consent.js');
+const { createOriginResolver } = require('./audio/origin.js');
+const { createAudioAcl } = require('./audio/acl.js');
+const { createDispatcher } = require('./audio/dispatch.js');
+const { createSpeakQueue } = require('./audio/queue.js');
+const { createReceiptStore } = require('./audio/receipt.js');
+const audioAdapters = require('./audio/adapters.js');
+const audioGroups = require('./audio/groups.js');
+const { bridgeSecretPath, loadOrCreateBridgeSecret, createNonceCache } = require('./audio/bridge-auth.js');
+const { createHopSecret } = require('./proxy/hop-proof.js');
 const { settingsRoutes, publicPeeringRoutes } = require('./settings/routes.js');
 const decksStore = require('./decks/store.js');
 const { decksRoutes } = require('./decks/routes.js');
@@ -133,6 +144,22 @@ function createServer(opts = {}) {
   const topologyCachePath = cfg.topologyCachePath || topologyCache.defaultPath(cfg.home || os.homedir());
   const decksPath = cfg.decksPath || decksStore.defaultDecksPath(cfg.home || os.homedir());
   const proxyReadonly = () => (cfg.readonlyDefault === true || process.env.NEXUSCREW_READONLY === '1');
+  const audioHome = cfg.home || os.homedir();
+  // Stato audio ancorato alla directory del token (come notifyDir): server,
+  // Settings e bridge MCP devono guardare gli stessi file anche quando un test
+  // isola l'istanza fuori dalla home reale.
+  const audioCfg = {
+    home: audioHome,
+    tokenPath: cfg.tokenPath,
+    audioConsentPath: cfg.audioConsentPath,
+    audioGroupsPath: cfg.audioGroupsPath,
+    audioBridgeSecretPath: cfg.audioBridgeSecretPath || path.join(notifyDir, 'audio-bridge.key'),
+  };
+  // Segreto per-processo della prova di hop federata: vive solo in memoria, non
+  // e' su disco e nessuna API lo espone. Serve a distinguere l'ultimo hop di una
+  // route federata da un POST diretto di chi possiede il token della UI.
+  const hopSecret = createHopSecret();
+  const audioNonceCache = createNonceCache();
   function resolveNode(name) {
     const st = nodesStore.loadStore(nodesPath);
     if (!st) return null;
@@ -299,6 +326,64 @@ function createServer(opts = {}) {
     sessionExists: (name) => sessionExists(cfg.tmuxBin, name),
   }));
   api.use('/fleet', fleetRoutes(fleetP, { ...cfg, diagnostics }));
+  // Audio Share. L'identita' del nodo NON e' un campo di cfg: si legge dal node
+  // store, la stessa fonte usata da /api/cells e /api/peers. Lo stato Fleet e'
+  // asincrono e va atteso: leggerlo come se fosse sincrono lascerebbe la
+  // risoluzione dell'origine sempre vuota e la feature morta senza che un test
+  // sul router se ne accorga.
+  const audioNodeId = () => (nodesStore.loadStore(nodesPath) || {}).nodeId || null;
+  // Seam di test per l'adapter: permette di esercitare il percorso completo
+  // (route -> gate -> coda -> receipt) sul server REALE senza emettere suono.
+  // In produzione resta il probe locale.
+  const audioAdapter = cfg.audioAdapterSeam
+    || audioAdapters.createAdapter(audioAdapters.detectAdapter({ env: cfg.env || process.env }));
+  const audioReceipts = createReceiptStore();
+  const audioQueue = createSpeakQueue({
+    adapter: audioAdapter,
+    // La coda e' l'unica a sapere com'e' finito davvero un enunciato: e' lei ad
+    // aggiornare il receipt da `accepted` a spoken/refused/unknown.
+    onStatus: (utteranceId, status, reason) => { try { audioReceipts.update(utteranceId, status, reason); } catch (_) {} },
+  });
+  api.use('/audio', audioRoutes({
+    readonly: proxyReadonly,
+    localNodeId: audioNodeId,
+    receiptStore: audioReceipts,
+    adapter: audioAdapter,
+    queue: audioQueue,
+    acl: createAudioAcl({ nodesPath }),
+    consent: () => { try { return isAudioConsent(audioCfg, audioHome); } catch (_) { return false; } },
+    originResolver: createOriginResolver({
+      localNodeId: audioNodeId,
+      // Celle Fleet ATTIVE in questo momento, attese davvero.
+      activeCells: async () => {
+        const fleet = await fleetP;
+        if (!fleet || fleet.available !== true || typeof fleet.status !== 'function') return [];
+        const st = await fleet.status();
+        return Array.isArray(st && st.cells) ? st.cells.map((c) => ({
+          cell: c && c.cell, tmuxSession: c && c.tmuxSession,
+          active: c && c.active === true && c.tmux !== false,
+        })) : [];
+      },
+      bridgeSecret: () => { try { return loadOrCreateBridgeSecret(bridgeSecretPath(audioCfg, audioHome)); } catch (_) { return null; } },
+      hopSecret: () => hopSecret,
+      nonceCache: audioNonceCache,
+    }),
+    dispatcher: createDispatcher({
+      localNodeId: audioNodeId,
+      peers: async () => {
+        const st = nodesStore.loadStore(nodesPath);
+        if (!st) return [];
+        const topology = await federation.collectLocalTopology({ nodesPath, cachePath: topologyCachePath, fetchImpl: healthFetch });
+        return nodesInventory.buildInventory({
+          direct: nodesStore.redactStore(st).nodes,
+          topology: topology && Array.isArray(topology.nodes) ? topology.nodes : [],
+        });
+      },
+      localPort: () => (server && server.address() ? server.address().port : cfg.port),
+      localToken: () => tokenHolder.value,
+    }),
+    getGroup: (name) => audioGroups.getGroup(audioCfg, name, audioHome),
+  }));
   api.use('/cells', cellsRoutes({
     fleetP,
     instanceId: () => (nodesStore.loadStore(nodesPath) || {}).nodeId || null,
@@ -359,7 +444,12 @@ function createServer(opts = {}) {
   // Settings API B2 (design §4b(6)): read-only GET + mutanti lista chiusa per il
   // wizard/settings UI. Dietro lo stesso requireToken del router /api; il gate
   // READONLY route-level e la redazione token vivono dentro settingsRoutes.
-  api.use('/settings', settingsRoutes({ cfg, nodesPath, tokenStore, closeSessions, updater, runtimePort }));
+  api.use('/settings', settingsRoutes({
+    cfg, nodesPath, tokenStore, closeSessions, updater, runtimePort,
+    // Stesso adapter/coda dell'API Audio: Settings puo' fare solo la prova
+    // locale a frase fissa e lo stop sovrano, mai una seconda sintesi parallela.
+    audio: { adapter: audioAdapter, queue: audioQueue },
+  }));
   api.use('/diagnostics', diagnosticsRoutes({ diagnostics, readonly: proxyReadonly }));
   api.get('/topology', async (_req, res) => {
     try { res.json(await federation.collectLocalTopology({ nodesPath, cachePath: topologyCachePath })); }
@@ -367,6 +457,7 @@ function createServer(opts = {}) {
   });
   api.use('/route', federation.localRouter({
     nodesPath, localPort: () => (server && server.address() ? server.address().port : cfg.port), localCredential: () => tokenHolder.value, readonly: proxyReadonly,
+    hopSecret: () => hopSecret,
   }));
   api.get('/voice/status', (_req, res) => res.json({ serverSttConfigured: !!cfg.voiceUrl }));
   api.post('/voice/transcribe',
@@ -392,7 +483,7 @@ function createServer(opts = {}) {
   app.use('/api', api);
   app.use('/federation', federation.peerRouter({
     nodesPath, localPort: () => (server && server.address() ? server.address().port : cfg.port), localCredential: () => tokenHolder.value, readonly: proxyReadonly, version: VERSION,
-    fetchImpl: healthFetch,
+    fetchImpl: healthFetch, hopSecret: () => hopSecret,
     roles: () => require('./cli/commands.js').readRoles(cfg.configPath || configJsonPath()),
   }));