@mmmbuto/nexuscrew 0.8.39 → 0.8.40

package/lib/audio/dispatch.js

@@ -0,0 +1,154 @@
+'use strict';
+// lib/audio/dispatch.js — instradamento lato ORIGINE verso un target esatto.
+//
+// Regole non negoziabili:
+//   * il target e' un instanceId di nodo, esatto. Niente wildcard, niente "tutti",
+//     niente broadcast: se il chiamante non sa chi deve parlare, non parla nessuno;
+//   * la risoluzione avviene sulla topologia LIVE autorizzata di questo server
+//     (peer diretti + peer instradati realmente noti), non su un nome fornito dal
+//     chiamante e non su una cache arbitraria;
+//   * l'inoltro riusa la route federata esistente, quindi passa da `canTransit`,
+//     dalla whitelist delle risorse e da `controlledVisited`: la provenienza la
+//     costruisce il server, il chiamante non puo' iniettarla;
+//   * nessun esito ambiguo diventa un successo. Timeout, 5xx, corpo non
+//     interpretabile e stati sconosciuti restano `unreachable` o `unknown`.
+const { resolvePeer } = require('../nodes/inventory.js');
+
+const DISPATCH_TIMEOUT_MS = 8000;
+const PER_ENDPOINT_STATUS = new Set(['refused', 'unreachable', 'accepted', 'spoken', 'unknown']);
+const INSTANCE_ID_RE = /^[a-f0-9]{32}$/i;
+
+function createDispatcher(opts = {}) {
+  const localNodeId = opts.localNodeId || (() => null);
+  const peers = opts.peers || (async () => []);
+  const localPort = opts.localPort || (() => 0);
+  const localToken = opts.localToken || (() => '');
+  const fetchImpl = opts.fetchImpl || fetch;
+  const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : DISPATCH_TIMEOUT_MS;
+
+  function isLocal(target) {
+    const self = localNodeId();
+    return !!self && target === self;
+  }
+
+  // resolveRoute(): ritorna la catena di nomi peer verso il target, oppure il
+  // motivo per cui non e' raggiungibile. Un target che non compare nella
+  // topologia autorizzata NON e' un errore del chiamante da spiegare in
+  // dettaglio: e' semplicemente irraggiungibile da qui.
+  async function resolveRoute(target) {
+    if (!INSTANCE_ID_RE.test(String(target || ''))) return { error: 'invalid-target' };
+    let list;
+    try { list = await peers(); } catch (_) { return { error: 'topology-unavailable' }; }
+    if (!Array.isArray(list) || !list.length) return { error: 'unknown-target' };
+    // Risoluzione per instanceId soltanto: risolvere per nome permetterebbe a un
+    // chiamante di colpire un nodo diverso da quello che intendeva se due
+    // installazioni condividono un'etichetta.
+    const found = resolvePeer(list.filter((p) => p && (p.nodeId || p.instanceId)), String(target));
+    if (found.error || !found.peer) return { error: 'unknown-target' };
+    const route = Array.isArray(found.peer.route) ? found.peer.route.filter(Boolean) : [];
+    if (!route.length) return { error: 'unknown-target' };
+    return { route, peer: found.peer };
+  }
+
+  // forward(): POST interno verso la propria route federata. Usa il Bearer
+  // locale perche' il destinatario del primo hop e' questo stesso server, che
+  // poi applica peering, ACL e whitelist come per qualunque altro inoltro.
+  async function forward(resource, route, body) {
+    const port = localPort();
+    const token = localToken();
+    if (!port || !token) return { status: 'unreachable', reason: 'local-transport-unavailable' };
+    const url = `http://127.0.0.1:${port}/api/route/${route.join('/')}/_${resource}`;
+    let res;
+    try {
+      res = await fetchImpl(url, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (_) {
+      // Timeout o transport giu': mai un successo, mai uno stato inventato.
+      return { status: 'unreachable', reason: 'transport' };
+    }
+    let payload = null;
+    try { payload = await res.json(); } catch (_) { payload = null; }
+    // 404 del lookup receipt NON e' una route negata: il target ha risposto
+    // intenzionalmente `unknown/not-found` al caller gia' autenticato. Tenerlo
+    // distinto permette al failover di reagire all'assenza di ack senza
+    // scambiare il risultato per un ACL deny.
+    if (resource === '/audio/speak/status' && res.status === 404
+      && payload && payload.status === 'unknown') {
+      return { status: 'unknown', reason: payload.reason || 'not-found', httpStatus: res.status };
+    }
+    if (res.status === 403 || res.status === 404 || res.status === 409) {
+      return { status: 'refused', reason: 'route-denied', httpStatus: res.status };
+    }
+    if (res.status >= 500) return { status: 'unreachable', reason: 'peer-error', httpStatus: res.status };
+    if (!payload || typeof payload !== 'object' || !PER_ENDPOINT_STATUS.has(payload.status)) {
+      // Il peer ha risposto qualcosa che non e' un esito per endpoint: non si
+      // indovina. `unknown` e' esattamente questo caso.
+      return { status: 'unknown', reason: 'unreadable-endpoint-result', httpStatus: res.status };
+    }
+    return {
+      status: payload.status,
+      ...(payload.reason ? { reason: String(payload.reason).slice(0, 64) } : {}),
+      httpStatus: res.status,
+    };
+  }
+
+  // La capability e' una GET federata separata dalla sintesi. Il target decide
+  // se e' pronto e consenziente prima che un gruppo lo consideri eleggibile;
+  // unknown/non-200 non diventano mai "ready". La route federata ricostruisce
+  // l'origine-node dalla catena visited, quindi non serve (ne' si accetta) una
+  // cella dichiarata in query.
+  async function probeCapability(target) {
+    const resolved = await resolveRoute(target);
+    if (resolved.error === 'invalid-target') return { status: 'refused', reason: 'invalid-target' };
+    if (resolved.error) return { status: 'unreachable', reason: resolved.error };
+    const port = localPort(); const token = localToken();
+    if (!port || !token) return { status: 'unreachable', reason: 'local-transport-unavailable' };
+    const url = `http://127.0.0.1:${port}/api/route/${resolved.route.join('/')}/_/audio/capability?target=${encodeURIComponent(target)}`;
+    let res;
+    try {
+      res = await fetchImpl(url, {
+        method: 'GET', headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (_) { return { status: 'unreachable', reason: 'transport' }; }
+    let body = null;
+    try { body = await res.json(); } catch (_) { body = null; }
+    if (res.status === 401) return { status: 'unreachable', reason: 'auth-failed' };
+    if (res.status === 403 || res.status === 404 || res.status === 409) return { status: 'refused', reason: 'route-denied' };
+    if (res.status >= 500) return { status: 'unreachable', reason: 'peer-error' };
+    if (!body || body.nodeId !== target || typeof body.installed !== 'boolean'
+      || typeof body.consent !== 'boolean' || !['ready', 'unknown', 'unavailable'].includes(body.liveness)) {
+      return { status: 'unknown', reason: 'capability-unreadable' };
+    }
+    if (body.consent !== true) return { status: 'refused', reason: 'consent' };
+    if (body.installed !== true || body.liveness !== 'ready') return { status: 'refused', reason: 'no-adapter' };
+    return { status: 'ready', capability: body };
+  }
+
+  return {
+    isLocal,
+    resolveRoute,
+    probeCapability,
+    // dispatch(): unico ingresso per un target remoto.
+    async dispatch({ resource, target, origin, payload }) {
+      const resolved = await resolveRoute(target);
+      if (resolved.error === 'invalid-target') return { status: 'refused', reason: 'invalid-target' };
+      if (resolved.error) return { status: 'unreachable', reason: resolved.error };
+      return forward(resource, resolved.route, {
+        ...payload,
+        target,
+        // Attestazione della cella di origine. Il NODO di origine lo ricostruisce
+        // il destinatario dalla catena `visited`; questo campo serve solo perche'
+        // possa registrare *quale cella* quel nodo dichiara. La differenza fra
+        // verificato e attestato viaggia fino al receipt.
+        originCell: origin && origin.cell,
+        originNode: origin && origin.node,
+      });
+    },
+  };
+}
+
+module.exports = { createDispatcher, DISPATCH_TIMEOUT_MS, PER_ENDPOINT_STATUS };

package/lib/audio/group-receipt.js

@@ -0,0 +1,119 @@
+'use strict';
+// lib/audio/group-receipt.js — receipt bounded di un gruppo Audio Share.
+//
+// Il receipt resta dell'origine nodo+cella e conserva SOLO la mappa endpoint
+// redatta. Non contiene testo, lingua, voce, route, path o un booleano di
+// successo aggregato: un gruppo puo' avere un endpoint spoken e un altro
+// unreachable senza che un `ok:true` nasconda il dettaglio.
+const crypto = require('node:crypto');
+const { callerKey, STATUS, CAP, TTL_MS } = require('./receipt.js');
+
+function createGroupReceiptStore({ now = Date.now } = {}) {
+  const byId = new Map();
+  const expired = (entry, at) => at - entry.timestamp > TTL_MS;
+  const cleanup = (at) => {
+    for (const [id, entry] of byId) if (expired(entry, at)) byId.delete(id);
+  };
+  const redact = (entry) => ({
+    utteranceId: entry.utteranceId,
+    origin: { node: entry.origin.node, cell: entry.origin.cell },
+    group: entry.group,
+    mode: entry.mode,
+    timestamp: entry.timestamp,
+    endpoints: entry.endpoints.map((endpoint) => ({
+      target: endpoint.target,
+      status: endpoint.status,
+      ...(endpoint.reason ? { reason: endpoint.reason } : {}),
+    })),
+  });
+  const find = (origin, utteranceId) => {
+    const key = callerKey(origin);
+    const entry = byId.get(utteranceId);
+    if (!key || !entry) return null;
+    if (expired(entry, now())) { byId.delete(utteranceId); return null; }
+    return entry.caller === key ? entry : null;
+  };
+
+  function begin({ origin, group, mode, targets, utteranceId } = {}) {
+    const caller = callerKey(origin);
+    if (!caller) throw new Error('group receipt: origin mancante');
+    if (typeof group !== 'string' || !group) throw new Error('group receipt: gruppo mancante');
+    if (!Array.isArray(targets) || !targets.length) throw new Error('group receipt: target mancanti');
+    const id = typeof utteranceId === 'string' && utteranceId ? utteranceId : crypto.randomUUID();
+    const existing = byId.get(id);
+    if (existing && !expired(existing, now())) {
+      const same = existing.caller === caller && existing.group === group && existing.mode === mode
+        && existing.endpoints.map((endpoint) => endpoint.target).join(',') === targets.join(',');
+      if (!same) throw new Error('utteranceId collision');
+      return { created: false, receipt: redact(existing) };
+    }
+    const timestamp = now();
+    cleanup(timestamp);
+    const entry = {
+      utteranceId: id, caller, origin: { node: origin.node, cell: origin.cell }, group, mode,
+      timestamp,
+      endpoints: targets.map((target) => ({ target, status: 'unknown', reason: 'not-attempted', admitted: false })),
+    };
+    byId.set(id, entry);
+    if (byId.size > CAP) {
+      const oldest = [...byId.entries()].sort((a, b) => a[1].timestamp - b[1].timestamp);
+      while (byId.size > CAP && oldest.length) byId.delete(oldest.shift()[0]);
+    }
+    return { created: true, receipt: redact(entry) };
+  }
+
+  function update(origin, utteranceId, target, status, reason, admitted = false) {
+    if (!STATUS.includes(status)) throw new Error('group receipt: status non valida');
+    const entry = find(origin, utteranceId);
+    if (!entry) return null;
+    // Uno Stop locale prevale sull'orchestratore asincrono: un completamento
+    // tardivo non puo' riaprire un endpoint gia' cancellato e farlo parlare.
+    if (entry.stopped === true) return redact(entry);
+    const endpoint = entry.endpoints.find((value) => value.target === target);
+    if (!endpoint) return null;
+    endpoint.status = status;
+    endpoint.admitted = endpoint.admitted || admitted === true;
+    if (reason) endpoint.reason = String(reason).slice(0, 64);
+    else delete endpoint.reason;
+    return redact(entry);
+  }
+
+  function get(origin, utteranceId) {
+    const entry = find(origin, utteranceId);
+    return entry ? redact(entry) : null;
+  }
+
+  function admittedTargets(origin, utteranceId) {
+    const entry = find(origin, utteranceId);
+    return entry ? entry.endpoints.filter((endpoint) => endpoint.admitted).map((endpoint) => endpoint.target) : [];
+  }
+
+  // Segna la richiesta di stop prima di contattare gli endpoint. Gli endpoint
+  // non ancora tentati diventano `refused/stopped`; quelli gia' ammessi
+  // conservano l'ultimo stato noto, perche' un POST remoto accettato non prova
+  // ancora che la voce sia gia' cessata. La coda locale e il suo stop sovrano
+  // restano l'autorita' finale su quel dettaglio.
+  function stop(origin, utteranceId) {
+    const entry = find(origin, utteranceId);
+    if (!entry) return null;
+    entry.stopped = true;
+    for (const endpoint of entry.endpoints) {
+      if (!endpoint.admitted && endpoint.status === 'unknown' && endpoint.reason === 'not-attempted') {
+        endpoint.status = 'refused'; endpoint.reason = 'stopped';
+      }
+    }
+    return redact(entry);
+  }
+
+  function isStopped(origin, utteranceId) {
+    const entry = find(origin, utteranceId);
+    return !!(entry && entry.stopped === true);
+  }
+
+  return {
+    begin, update, get, admittedTargets, stop, isStopped,
+    count: () => { cleanup(now()); return byId.size; },
+  };
+}
+
+module.exports = { createGroupReceiptStore };

package/lib/audio/group-speak.js

@@ -0,0 +1,146 @@
+'use strict';
+// lib/audio/group-speak.js — orchestrazione origin-side di gruppi nominati.
+//
+// Il gruppo NON e' un'autorizzazione: espande una lista locale di instanceId e
+// interroga ogni nodo. Primary/failover e' sequenziale; fanout e' esplicito e
+// parallelo. Ogni esito resta per-endpoint, inclusi gli endpoint non tentati.
+const { TEXT_MAX } = require('./speak.js');
+const { validName, MODES } = require('./groups.js');
+const { callerKey } = require('./receipt.js');
+// Duplicato intenzionale del contratto di routes: importare routes qui
+// creerebbe un ciclo (routes monta il group speaker) e renderebbe la regex
+// `undefined` durante il caricamento CommonJS.
+const UTTERANCE_ID_RE = /^[A-Za-z0-9._:-]{8,128}$/;
+
+const ACK_TIMEOUT_MS = 5000;
+const POLL_INTERVAL_MS = 250;
+
+function validText(text) { return typeof text === 'string' && text.length >= 1 && text.length <= TEXT_MAX; }
+
+function createGroupSpeaker(deps = {}) {
+  const getGroup = deps.getGroup || (() => null);
+  const receipts = deps.receipts;
+  const capability = deps.capability || (async () => ({ status: 'unreachable', reason: 'capability-unavailable' }));
+  const speak = deps.speak || (async () => ({ status: 'unreachable', reason: 'dispatch-unavailable' }));
+  const status = deps.status || (async () => ({ status: 'unknown', reason: 'status-unavailable' }));
+  const stop = deps.stop || (async () => ({ status: 'unknown', reason: 'stop-unavailable' }));
+  const now = deps.now || Date.now;
+  const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const ackTimeoutMs = Number.isFinite(deps.ackTimeoutMs) ? deps.ackTimeoutMs : ACK_TIMEOUT_MS;
+  const pollIntervalMs = Number.isFinite(deps.pollIntervalMs) ? deps.pollIntervalMs : POLL_INTERVAL_MS;
+  const running = new Set();
+
+  if (!receipts || typeof receipts.begin !== 'function') throw new Error('group speaker: receipt store obbligatorio');
+
+  async function awaitStart({ target, origin, utteranceId }) {
+    const deadline = now() + ackTimeoutMs;
+    while (now() < deadline) {
+      await sleep(Math.max(1, Math.min(pollIntervalMs, deadline - now())));
+      const current = await status({ target, origin, utteranceId });
+      if (!current || typeof current.status !== 'string') return { status: 'unknown', reason: 'status-unreadable' };
+      if (current.status !== 'accepted') return current;
+    }
+    return { status: 'unknown', reason: 'ack-timeout' };
+  }
+
+  async function runEndpoint({ target, origin, utteranceId, text, lang, voice, urgency, onAdmitted = null }) {
+    if (receipts.isStopped(origin, utteranceId)) return { status: 'refused', reason: 'stopped', admitted: false };
+    const cap = await capability({ target, origin });
+    if (!cap || cap.status !== 'ready') {
+      return {
+        status: cap && ['refused', 'unreachable', 'unknown'].includes(cap.status) ? cap.status : 'unknown',
+        ...(cap && cap.reason ? { reason: cap.reason } : { reason: 'capability-unavailable' }),
+        admitted: false,
+      };
+    }
+    if (receipts.isStopped(origin, utteranceId)) return { status: 'refused', reason: 'stopped', admitted: false };
+    const initial = await speak({ target, origin, utteranceId, text, lang, voice, urgency });
+    if (!initial || typeof initial.status !== 'string') return { status: 'unknown', reason: 'speak-unreadable', admitted: false };
+    if (initial.status !== 'accepted') {
+      // Anche uno `spoken` sincrono e' gia' ammesso: registra prima questo
+      // fatto minimo cosi' uno Stop concorrente non perde una finestra di un
+      // microtask fra la risposta dell'adapter e l'update finale del receipt.
+      if (initial.status === 'spoken' && typeof onAdmitted === 'function') onAdmitted();
+      return { status: initial.status, reason: initial.reason, admitted: initial.status === 'spoken' };
+    }
+    // L'endpoint ha ammesso l'enunciato: registrarlo PRIMA di aspettare l'ack
+    // permette a Stop di raggiungerlo anche se il polling resta appeso. Non e'
+    // ancora `spoken`, quindi il receipt non promette udibilita'.
+    if (typeof onAdmitted === 'function') onAdmitted();
+    const final = await awaitStart({ target, origin, utteranceId });
+    return { status: final.status, reason: final.reason, admitted: true };
+  }
+
+  function runKey(origin, utteranceId) { return `${callerKey(origin) || ''}\u0000${utteranceId}`; }
+
+  async function orchestrate({ origin, spec, utteranceId, text, lang, voice, urgency }) {
+    const one = async (target) => {
+      if (receipts.isStopped(origin, utteranceId)) return { status: 'refused', reason: 'stopped', admitted: false };
+      let result;
+      try {
+        result = await runEndpoint({
+          target, origin, utteranceId, text, lang, voice, urgency,
+          onAdmitted: () => receipts.update(origin, utteranceId, target, 'accepted', undefined, true),
+        });
+      }
+      catch (_) { result = { status: 'unknown', reason: 'endpoint-error', admitted: false }; }
+      receipts.update(origin, utteranceId, target, result.status, result.reason, result.admitted);
+      return result;
+    };
+    if (spec.mode === 'fanout') {
+      await Promise.all(spec.targets.map(one));
+      return;
+    }
+    for (const target of spec.targets) {
+      if (receipts.isStopped(origin, utteranceId)) return;
+      const result = await one(target);
+      if (result.status === 'spoken') return;
+    }
+  }
+
+  async function speakGroup({ origin, group, text, lang = '', voice = '', urgency = 'normal', utteranceId } = {}) {
+    if (!validName(group)) return { status: 'refused', reason: 'invalid-group' };
+    if (!validText(text)) return { status: 'refused', reason: 'invalid-text' };
+    if (utteranceId && !UTTERANCE_ID_RE.test(utteranceId)) return { status: 'refused', reason: 'invalid-utterance' };
+    const spec = getGroup(group);
+    if (!spec || !Array.isArray(spec.targets) || !MODES.includes(spec.mode)) return { status: 'refused', reason: 'unknown-group' };
+    let begun;
+    try { begun = receipts.begin({ origin, group, mode: spec.mode, targets: spec.targets, utteranceId }); }
+    catch (_) { return { status: 'refused', reason: 'utterance-collision' }; }
+    if (!begun.created) return begun.receipt; // retry idempotente: non risuona
+    const id = begun.receipt.utteranceId;
+    const key = runKey(origin, id);
+    // Il comando non aspetta fino a 8 × 5s: conserva subito un receipt
+    // interrogabile e completa in background. In questo modo la semantica
+    // resta asincrona come `nc_speak`; `not-attempted` non e' un falso esito,
+    // indica precisamente che il candidato non e' ancora stato provato.
+    running.add(key);
+    Promise.resolve().then(() => orchestrate({ origin, spec, utteranceId: id, text, lang, voice, urgency }))
+      .catch(() => {})
+      .finally(() => running.delete(key));
+    return begun.receipt;
+  }
+
+  async function stopGroup({ origin, utteranceId } = {}) {
+    if (!utteranceId || !UTTERANCE_ID_RE.test(utteranceId)) return { status: 'refused', reason: 'invalid-utterance' };
+    const existing = receipts.get(origin, utteranceId);
+    if (!existing) return { status: 'unknown', reason: 'not-found', utteranceId };
+    // Stop prima la pipeline locale: i candidati non ancora tentati non devono
+    // partire mentre la rete sta ricevendo gli stop degli endpoint gia' ammessi.
+    const admitted = receipts.admittedTargets(origin, utteranceId);
+    receipts.stop(origin, utteranceId);
+    await Promise.all(admitted.map(async (target) => {
+      try { await stop({ target, origin, utteranceId }); } catch (_) { /* receipt resta ultimo stato onesto */ }
+    }));
+    return receipts.get(origin, utteranceId);
+  }
+
+  return {
+    speakGroup, stopGroup,
+    getStatus: ({ origin, utteranceId }) => receipts.get(origin, utteranceId),
+    // Solo seam di test/diagnostica locale: non e' esposto dalle route.
+    isRunning: ({ origin, utteranceId }) => running.has(runKey(origin, utteranceId)),
+  };
+}
+
+module.exports = { createGroupSpeaker, ACK_TIMEOUT_MS, POLL_INTERVAL_MS };

package/lib/audio/groups.js

@@ -0,0 +1,121 @@
+'use strict';
+// lib/audio/groups.js — gruppi audio LOCALI dell'origine.
+//
+// Un gruppo e' solo una preferenza di consegna: non pubblica un nodo, non
+// modifica Share/visibility e non concede consenso audio. Ogni endpoint della
+// lista viene comunque rivalutato dal proprio nodo quando riceve speak.
+// Tenerlo in un file distinto da audio.json preserva lo schema chiuso del
+// consenso ({audio:{consent}}) e impedisce che una nuova preferenza allenti un
+// confine fisico gia' esistente.
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+const SCHEMA_VERSION = 1;
+const GROUP_NAME_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const NODE_ID_RE = /^[a-f0-9]{32}$/i;
+const MODES = Object.freeze(['primary-failover', 'fanout']);
+const MAX_TARGETS = 8;
+
+function groupsPath(cfg = {}, home = (cfg && cfg.home) || os.homedir()) {
+  if (cfg.audioGroupsPath) return cfg.audioGroupsPath;
+  if (cfg.tokenPath) return path.join(path.dirname(cfg.tokenPath), 'audio-groups.json');
+  return path.join(home, '.nexuscrew', 'audio-groups.json');
+}
+
+function emptyGroups() { return { schemaVersion: SCHEMA_VERSION, groups: {} }; }
+
+function validName(name) { return typeof name === 'string' && GROUP_NAME_RE.test(name); }
+
+function normalizeSpec(spec) {
+  if (!spec || typeof spec !== 'object' || Array.isArray(spec)) return null;
+  if (Object.keys(spec).some((key) => !['targets', 'mode'].includes(key))) return null;
+  if (!Array.isArray(spec.targets) || spec.targets.length < 1 || spec.targets.length > MAX_TARGETS) return null;
+  if (!MODES.includes(spec.mode)) return null;
+  const targets = spec.targets.map((value) => String(value || '').toLowerCase());
+  if (targets.some((value) => !NODE_ID_RE.test(value))) return null;
+  if (new Set(targets).size !== targets.length) return null;
+  return { targets, mode: spec.mode };
+}
+
+function normalizeStore(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw) || raw.schemaVersion !== SCHEMA_VERSION) return emptyGroups();
+  if (!raw.groups || typeof raw.groups !== 'object' || Array.isArray(raw.groups)) return emptyGroups();
+  const groups = {};
+  for (const [name, spec] of Object.entries(raw.groups)) {
+    const normalized = validName(name) ? normalizeSpec(spec) : null;
+    if (!normalized) return emptyGroups(); // configurazione corrotta = nessun gruppo, mai guess
+    groups[name] = normalized;
+  }
+  return { schemaVersion: SCHEMA_VERSION, groups };
+}
+
+function readGroups(cfg = {}, home = (cfg && cfg.home) || os.homedir()) {
+  try {
+    const file = groupsPath(cfg, home);
+    // Una preferenza audio non deve diventare un lettore di file arbitrari: un
+    // symlink viene trattato come configurazione assente sia in lettura sia in
+    // scrittura. In particolare non restituiamo mai il contenuto del target.
+    if (fs.lstatSync(file).isSymbolicLink()) return emptyGroups();
+    return normalizeStore(JSON.parse(fs.readFileSync(file, 'utf8')));
+  }
+  catch (_) { return emptyGroups(); }
+}
+
+function atomicWrite(file, data) {
+  try {
+    if (fs.lstatSync(file).isSymbolicLink()) throw new Error('refusing symlink audio groups path');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify(data)}\n`, { flag: 'wx', mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw err;
+  }
+}
+
+function listGroups(cfg = {}, home) {
+  const store = readGroups(cfg, home);
+  return Object.entries(store.groups)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, spec]) => ({ name, targets: [...spec.targets], mode: spec.mode }));
+}
+
+function getGroup(cfg = {}, name, home) {
+  if (!validName(name)) return null;
+  const spec = readGroups(cfg, home).groups[name];
+  return spec ? { name, targets: [...spec.targets], mode: spec.mode } : null;
+}
+
+function saveGroup(cfg = {}, name, spec, home) {
+  if (!validName(name)) throw new Error('nome gruppo audio non valido');
+  const normalized = normalizeSpec(spec);
+  if (!normalized) throw new Error('gruppo audio non valido');
+  const store = readGroups(cfg, home);
+  store.groups[name] = normalized;
+  atomicWrite(groupsPath(cfg, home), store);
+  return { name, targets: [...normalized.targets], mode: normalized.mode };
+}
+
+function removeGroup(cfg = {}, name, home) {
+  if (!validName(name)) throw new Error('nome gruppo audio non valido');
+  const store = readGroups(cfg, home);
+  if (!Object.prototype.hasOwnProperty.call(store.groups, name)) return false;
+  delete store.groups[name];
+  atomicWrite(groupsPath(cfg, home), store);
+  return true;
+}
+
+module.exports = {
+  SCHEMA_VERSION, GROUP_NAME_RE, NODE_ID_RE, MODES, MAX_TARGETS,
+  groupsPath, emptyGroups, validName, normalizeSpec, readGroups, listGroups,
+  getGroup, saveGroup, removeGroup,
+};

package/lib/audio/origin.js

@@ -0,0 +1,128 @@
+'use strict';
+// lib/audio/origin.js — risoluzione dell'ORIGINE di una richiesta audio.
+//
+// L'origine non e' un campo del body: e' il risultato di una verifica. Esistono
+// esattamente due modi legittimi di presentarsi, e nient'altro e' accettato.
+//
+//   1. locale via bridge MCP — la richiesta porta la firma HMAC del segreto di
+//      bridge (lib/audio/bridge-auth.js) e dichiara una sessione tmux che deve
+//      risultare una cella Fleet ATTIVA in questo momento. Lo stato Fleet e'
+//      asincrono: va atteso, non letto da un oggetto che sembra sincrono.
+//      Origine = { node: nodeId locale, cell: id logico della cella }.
+//
+//   2. federata — la richiesta e' l'ultimo hop di una route federata, provato
+//      dall'header di hop firmato dal segreto per-processo (lib/proxy/hop-proof)
+//      piu' la catena `visited` che il proxy costruisce lato server. Origine
+//      node = `visited[0]`, cioe' il nodo che ha aperto la catena, MAI un campo
+//      del body.
+//
+// Confine dichiarato, non nascosto: il nodo di origine e' verificato end-to-end
+// (catena visited legata ai token di peering); la CELLA di origine remota e'
+// invece *attestata* dal nodo di origine, che l'ha verificata localmente col
+// bridge. Un proprietario di nodo puo' mentire su quale delle proprie celle ha
+// parlato. Questo limite e' inerente al modello di fiducia fra nodi e va
+// registrato come tale, non spacciato per autenticazione.
+//
+// Il Bearer — della UI o di federation — non concorre MAI a stabilire l'origine.
+const { verifyRequest, SESSION_HEADER } = require('./bridge-auth.js');
+const { verifyHop, HOP_HEADER } = require('../proxy/hop-proof.js');
+
+const NODE_ID_RE = /^[a-f0-9]{16,64}$/;
+const CELL_ID_RE = /^[A-Za-z0-9._-]{1,32}$/;
+
+function validNode(v) { return typeof v === 'string' && NODE_ID_RE.test(v); }
+function validCell(v) { return typeof v === 'string' && CELL_ID_RE.test(v); }
+
+// Catena visited gia' costruita dal server (controlledVisited). Qui si verifica
+// solo la forma e la coerenza con il nodo locale: la prova di provenienza e'
+// l'header di hop, non questa stringa.
+function parseVisitedChain(raw, localNodeId) {
+  const ids = String(raw || '').split(',').filter(Boolean);
+  if (!ids.length || ids.length > 8) return null;
+  if (ids.some((id) => !validNode(id))) return null;
+  if (new Set(ids).size !== ids.length) return null;
+  if (ids.at(-1) !== localNodeId) return null;
+  return ids;
+}
+
+// createOriginResolver(): deps esplicite, nessun accesso globale.
+//   localNodeId()  -> string|null   nodeId REALE del nodo (dal node store)
+//   activeCells()  -> Promise<[{cell, tmuxSession, active}]>  stato Fleet atteso
+//   bridgeSecret() -> string|null   segreto del bridge (file 0600)
+//   hopSecret()    -> Buffer|null   segreto per-processo della prova di hop
+function createOriginResolver(deps = {}) {
+  const localNodeId = deps.localNodeId || (() => null);
+  const activeCells = deps.activeCells || (async () => []);
+  const bridgeSecret = deps.bridgeSecret || (() => null);
+  const hopSecret = deps.hopSecret || (() => null);
+  const nonceCache = deps.nonceCache || null;
+  const now = deps.now || Date.now;
+
+  async function resolve(req, opts = {}) {
+    // Capability e' una lettura per-nodo: un hop federato prova gia' il nodo
+    // origine, ma non porta una cella nel body di una GET. Speak/status/stop
+    // mantengono invece requireCell=true per scope receipt/rate/attribution.
+    const requireCell = opts.requireCell !== false;
+    const self = localNodeId();
+    // Senza identita' di nodo non si puo' ne' attribuire ne' verificare nulla:
+    // fail-closed invece di inventare un nodeId vuoto.
+    if (!validNode(self)) return { ok: false, reason: 'no-node-identity' };
+
+    const headers = req.headers || {};
+    const hopProof = headers[HOP_HEADER];
+    if (hopProof) {
+      const visited = parseVisitedChain(headers['x-nexuscrew-visited'], self);
+      if (!visited) return { ok: false, reason: 'bad-visited' };
+      const okHop = verifyHop(hopSecret(), {
+        method: req.method, path: req.originalUrl || req.url, visited,
+      }, hopProof);
+      if (!okHop) return { ok: false, reason: 'bad-hop' };
+      const originNode = visited[0];
+      // Un hop la cui catena inizia col nodo locale non e' un inbound federato:
+      // e' un giro su se stessi, e l'origine locale ha il suo percorso.
+      if (originNode === self) return { ok: false, reason: 'self-hop' };
+      const body = req.body || {};
+      const attested = body.originCell;
+      if (requireCell && !validCell(attested)) return { ok: false, reason: 'bad-attested-cell' };
+      if (!requireCell && attested !== undefined && !validCell(attested)) return { ok: false, reason: 'bad-attested-cell' };
+      // Coerenza: se il body dichiara anche un nodo, deve combaciare con la
+      // catena controllata dal server. In caso di conflitto vince visited e la
+      // richiesta viene rifiutata, non "corretta" in silenzio.
+      if (body.originNode !== undefined && body.originNode !== originNode) {
+        return { ok: false, reason: 'origin-mismatch' };
+      }
+      return {
+        ok: true,
+        origin: { node: originNode, ...(validCell(attested) ? { cell: attested } : {}) },
+        trust: 'federated', visited,
+      };
+    }
+
+    // Percorso locale: serve la firma del bridge. Nessun fallback sul body.
+    const verified = verifyRequest({
+      secret: bridgeSecret(),
+      method: req.method,
+      path: req.originalUrl || req.url,
+      headers,
+      rawBody: req.rawBody,
+      nonceCache,
+      now,
+    });
+    if (!verified.ok) return { ok: false, reason: verified.reason };
+    const session = headers[SESSION_HEADER];
+    let cells;
+    try {
+      cells = await activeCells();
+    } catch (_) {
+      return { ok: false, reason: 'fleet-unavailable' };
+    }
+    if (!Array.isArray(cells)) return { ok: false, reason: 'fleet-unavailable' };
+    const match = cells.find((c) => c && c.tmuxSession === session && c.active === true);
+    if (!match || !validCell(match.cell)) return { ok: false, reason: 'cell-not-active' };
+    return { ok: true, origin: { node: self, cell: match.cell }, trust: 'local-bridge' };
+  }
+
+  return { resolve };
+}
+
+module.exports = { createOriginResolver, parseVisitedChain, NODE_ID_RE, CELL_ID_RE };