@mmmbuto/nexuscrew 0.8.38 → 0.8.40

package/lib/audio/routes.js

@@ -0,0 +1,374 @@
+'use strict';
+// lib/audio/routes.js — route audio locali: /speak, /stop, /capability, /status.
+//
+// Due invarianti reggono tutto il resto.
+//
+// 1) L'origine e' verificata, non dichiarata. `originResolver` e' obbligatorio e
+//    autoritativo: nessun header, campo del body o parametro di query concorre a
+//    stabilire chi sta parlando. Senza un'origine verificabile la richiesta
+//    muore con 401, non con un default permissivo.
+//
+// 2) Ogni decisione di suonare la prende il nodo che possiede l'altoparlante. Se
+//    il target e' remoto questo server non decide per lui: instrada e riporta
+//    l'esito per endpoint cosi' com'e', incluso `unknown`.
+//
+// Il corpo grezzo viene conservato (`req.rawBody`) perche' la firma del bridge
+// copre i BYTE trasmessi: ri-serializzare il JSON per verificarlo produrrebbe
+// una stringa diversa a parita' di significato.
+const express = require('express');
+const { handleSpeak, handleStop, isValidInstance } = require('./speak.js');
+const { describeCapability } = require('./capability.js');
+const { createReceiptStore } = require('./receipt.js');
+const { createSpeakRateLimiter } = require('./rate-limit.js');
+const { createGroupReceiptStore } = require('./group-receipt.js');
+const { createGroupSpeaker } = require('./group-speak.js');
+
+const UTTERANCE_ID_RE = /^[A-Za-z0-9._:-]{8,128}$/;
+const LANG_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,34})$/;
+const VOICE_RE = /^[^\u0000-\u001f\u007f]{1,64}$/;
+const URGENCIES = new Set(['normal', 'high']);
+
+function plainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function onlyKeys(value, allowed) {
+  return plainObject(value) && Object.keys(value).every((key) => allowed.has(key));
+}
+
+function optionalBounded(value, re) {
+  return value === undefined || (typeof value === 'string' && re.test(value));
+}
+
+// Il server non deve diventare tollerante verso campi futuri/non documentati:
+// testo, route o identita' inattesi non vengono mai ignorati in silenzio.
+// `originCell`/`originNode` sono gli unici campi aggiunti dal dispatcher sul
+// percorso federato; il target li ricontrolla nel resolver, non li usa mai
+// come fonte primaria dell'identita'.
+function parseSpeakBody(body, { federated = false } = {}) {
+  const allowed = new Set(['target', 'text', 'lang', 'voice', 'urgency', 'utteranceId']);
+  if (federated) { allowed.add('originCell'); allowed.add('originNode'); }
+  if (!onlyKeys(body, allowed)) return { error: 'invalid-request' };
+  const target = typeof body.target === 'string' ? body.target : '';
+  if (!isValidInstance(target)) return { error: 'invalid-target' };
+  if (typeof body.text !== 'string' || body.text.length < 1 || body.text.length > 320) return { error: 'invalid-text' };
+  if (!optionalBounded(body.lang, LANG_RE) || !optionalBounded(body.voice, VOICE_RE)) return { error: 'invalid-request' };
+  if (body.urgency !== undefined && !URGENCIES.has(body.urgency)) return { error: 'invalid-request' };
+  if (body.utteranceId !== undefined && (typeof body.utteranceId !== 'string' || !UTTERANCE_ID_RE.test(body.utteranceId))) {
+    return { error: 'invalid-utterance' };
+  }
+  return {
+    target, text: body.text,
+    ...(body.lang !== undefined ? { lang: body.lang } : {}),
+    ...(body.voice !== undefined ? { voice: body.voice } : {}),
+    urgency: body.urgency || 'normal',
+    ...(body.utteranceId ? { utteranceId: body.utteranceId } : {}),
+  };
+}
+
+function parseStopBody(body, { federated = false } = {}) {
+  const allowed = new Set(['target', 'utteranceId']);
+  if (federated) { allowed.add('originCell'); allowed.add('originNode'); }
+  if (!onlyKeys(body, allowed)) return { error: 'invalid-request' };
+  const target = typeof body.target === 'string' ? body.target : '';
+  if (!isValidInstance(target)) return { error: 'invalid-target' };
+  if (body.utteranceId !== undefined && (typeof body.utteranceId !== 'string' || !UTTERANCE_ID_RE.test(body.utteranceId))) {
+    return { error: 'invalid-utterance' };
+  }
+  return { target, ...(body.utteranceId ? { utteranceId: body.utteranceId } : {}) };
+}
+
+function parseRemoteStatusBody(body) {
+  if (!onlyKeys(body, new Set(['target', 'utteranceId', 'originCell', 'originNode']))) return { error: 'invalid-request' };
+  if (!isValidInstance(body.target)) return { error: 'invalid-target' };
+  if (typeof body.utteranceId !== 'string' || !UTTERANCE_ID_RE.test(body.utteranceId)) return { error: 'invalid-utterance' };
+  return { target: body.target, utteranceId: body.utteranceId };
+}
+
+function parseGroupSpeakBody(body) {
+  if (!onlyKeys(body, new Set(['group', 'text', 'lang', 'voice', 'urgency', 'utteranceId']))) return { error: 'invalid-request' };
+  if (typeof body.group !== 'string') return { error: 'invalid-group' };
+  if (typeof body.text !== 'string' || body.text.length < 1 || body.text.length > 320) return { error: 'invalid-text' };
+  if (!optionalBounded(body.lang, LANG_RE) || !optionalBounded(body.voice, VOICE_RE)) return { error: 'invalid-request' };
+  if (body.urgency !== undefined && !URGENCIES.has(body.urgency)) return { error: 'invalid-request' };
+  if (body.utteranceId !== undefined && (typeof body.utteranceId !== 'string' || !UTTERANCE_ID_RE.test(body.utteranceId))) {
+    return { error: 'invalid-utterance' };
+  }
+  return {
+    group: body.group, text: body.text, urgency: body.urgency || 'normal',
+    ...(body.lang !== undefined ? { lang: body.lang } : {}),
+    ...(body.voice !== undefined ? { voice: body.voice } : {}),
+    ...(body.utteranceId ? { utteranceId: body.utteranceId } : {}),
+  };
+}
+
+function audioRoutes(deps = {}) {
+  if (!deps.originResolver || typeof deps.originResolver.resolve !== 'function') {
+    throw new Error('audioRoutes: originResolver e obbligatorio (origine verificata)');
+  }
+  const r = express.Router();
+  r.use(express.json({
+    limit: '16kb',
+    verify: (req, _res, buf) => { req.rawBody = Buffer.from(buf); },
+  }));
+
+  const originResolver = deps.originResolver;
+  const receiptStore = deps.receiptStore || createReceiptStore();
+  const rateLimiter = deps.rateLimiter || createSpeakRateLimiter();
+  const readonly = deps.readonly || (() => false);
+  const localNodeId = deps.localNodeId || (() => null);
+  const consent = deps.consent || (() => false);
+  const adapter = deps.adapter || null;
+  const queue = deps.queue || null;
+  const acl = deps.acl || null;
+  const dispatcher = deps.dispatcher || null;
+  const getGroup = deps.getGroup || (() => null);
+  const groupReceipts = deps.groupReceipts || createGroupReceiptStore();
+  const now = deps.now || Date.now;
+
+  const send = (res, code, body) => res.status(code).json(body);
+
+  // Un solo messaggio per ogni fallimento di origine. Distinguere "firma
+  // scaduta" da "nonce riusato" da "cella non attiva" darebbe a chi prova a
+  // forgiare un oracolo gratuito su cosa manca per riuscire.
+  async function originOr401(req, res, opts = {}) {
+    const resolved = await originResolver.resolve(req, opts);
+    if (!resolved || resolved.ok !== true) {
+      send(res, 401, { error: 'origine non verificabile' });
+      return null;
+    }
+    return resolved;
+  }
+
+  function gateDeps(origin, attested) {
+    return {
+      readonly, rateLimiter, queue, localNodeId, consent, now,
+      acl: acl ? acl.allows : null,
+      receipt: (status, o) => receiptStore.record({
+        origin: o.origin, target: o.target, status, reason: o.reason,
+        utteranceId: o.utteranceId, attested,
+      }),
+      updateReceipt: (id, status, reason) => receiptStore.update(id, status, reason),
+      readReceipt: (id, o) => receiptStore.get(o, id),
+      findReceipt: (id, o, target) => receiptStore.find(id, o, target),
+    };
+  }
+
+  function localCapability(target) {
+    const self = localNodeId();
+    if (!self || target !== self) return { status: 'refused', reason: 'invalid-target' };
+    const described = describeCapability({ adapter, consent: consent() === true, nodeId: self });
+    if (described.consent !== true) return { status: 'refused', reason: 'consent' };
+    if (described.installed !== true) return { status: 'refused', reason: 'no-adapter' };
+    if (described.liveness !== 'ready') return { status: 'unknown', reason: 'liveness-unknown' };
+    return { status: 'ready', capability: described };
+  }
+
+  async function capabilityForGroup({ target }) {
+    if (!isValidInstance(target)) return { status: 'refused', reason: 'invalid-target' };
+    if (target === localNodeId()) return localCapability(target);
+    if (!dispatcher || typeof dispatcher.probeCapability !== 'function') return { status: 'unreachable', reason: 'dispatch-unavailable' };
+    return dispatcher.probeCapability(target);
+  }
+
+  async function speakForGroup({ target, origin, utteranceId, text, lang, voice, urgency }) {
+    if (target === localNodeId()) {
+      return handleSpeak({
+        target, text, lang, voice, urgency, utteranceId, origin, trust: 'local-bridge', visited: [],
+      }, gateDeps(origin, false));
+    }
+    if (!dispatcher || typeof dispatcher.dispatch !== 'function') return { status: 'unreachable', reason: 'dispatch-unavailable' };
+    // Un gruppo non e' una scorciatoia attorno al budget `nc_speak`: prima del
+    // dispatch remoto consuma gli stessi tre bucket sul nodo origine. Il target
+    // li applichera' di nuovo in modo indipendente, perche' resta l'autorita'
+    // finale sul proprio altoparlante.
+    const rl = rateLimiter.check({ origin, target, urgency });
+    if (!rl.allowed) return { status: 'refused', reason: 'rate-limit' };
+    return dispatcher.dispatch({
+      resource: '/audio/speak', target, origin,
+      payload: { text, ...(lang ? { lang } : {}), ...(voice ? { voice } : {}), urgency, utteranceId },
+    });
+  }
+
+  async function statusForGroup({ target, origin, utteranceId }) {
+    if (target === localNodeId()) return receiptStore.get(origin, utteranceId) || { status: 'unknown', reason: 'not-found' };
+    if (!dispatcher || typeof dispatcher.dispatch !== 'function') return { status: 'unknown', reason: 'dispatch-unavailable' };
+    return dispatcher.dispatch({ resource: '/audio/speak/status', target, origin, payload: { utteranceId } });
+  }
+
+  async function stopForGroup({ target, origin, utteranceId }) {
+    if (target === localNodeId()) return handleStop({ target, utteranceId, origin }, gateDeps(origin, false));
+    if (!dispatcher || typeof dispatcher.dispatch !== 'function') return { status: 'unknown', reason: 'dispatch-unavailable' };
+    return dispatcher.dispatch({ resource: '/audio/stop', target, origin, payload: { utteranceId } });
+  }
+
+  const groupSpeaker = deps.groupSpeaker || createGroupSpeaker({
+    getGroup, receipts: groupReceipts,
+    capability: capabilityForGroup, speak: speakForGroup,
+    status: statusForGroup, stop: stopForGroup,
+  });
+
+  r.post('/speak', async (req, res) => {
+    const resolved = await originOr401(req, res); if (!resolved) return undefined;
+    const { origin, trust, visited } = resolved;
+    const parsed = parseSpeakBody(req.body, { federated: trust === 'federated' });
+    if (parsed.error) return send(res, 400, { status: 'refused', reason: parsed.error });
+    const { target, utteranceId } = parsed;
+    // Gruppo e speak singolo condividono il namespace dell'utteranceId per
+    // origine. Senza questo gate un id riusato potrebbe far sembrare `spoken`
+    // un endpoint che aveva pronunciato una richiesta precedente, diversa.
+    if (utteranceId && groupReceipts.get(origin, utteranceId)) {
+      return send(res, 422, { status: 'refused', reason: 'utterance-collision' });
+    }
+    // Target remoto: questo nodo non decide e non parla. Instrada sulla
+    // topologia autorizzata e restituisce l'esito del target senza addolcirlo.
+    if (dispatcher && isValidInstance(target) && !dispatcher.isLocal(target)) {
+      if (readonly()) return send(res, 403, { status: 'refused', reason: 'readonly' });
+      const rl = rateLimiter.check({ origin, target, urgency: parsed.urgency });
+      if (!rl.allowed) return send(res, 429, { status: 'refused', reason: 'rate-limit' });
+      const local = receiptStore.record({
+        origin, target, status: 'accepted', utteranceId, attested: trust === 'federated',
+      });
+      const out = await dispatcher.dispatch({
+        resource: '/audio/speak', target, origin,
+        payload: {
+          text: parsed.text, lang: parsed.lang, voice: parsed.voice, urgency: parsed.urgency,
+          utteranceId: local.utteranceId,
+        },
+      });
+      const merged = receiptStore.update(local.utteranceId, out.status, out.reason) || {
+        ...local, status: out.status, ...(out.reason ? { reason: out.reason } : {}),
+      };
+      const code = out.status === 'spoken' || out.status === 'accepted' || out.status === 'unknown' ? 200
+        : out.status === 'unreachable' ? 503 : 422;
+      return send(res, code, merged);
+    }
+
+    const out = handleSpeak({
+      target, text: parsed.text, lang: parsed.lang, voice: parsed.voice, urgency: parsed.urgency,
+      utteranceId, origin, trust, visited,
+    }, gateDeps(origin, trust === 'federated'));
+    const code = out.status === 'spoken' || out.status === 'accepted' || out.status === 'unknown' ? 200
+      : (out.reason === 'invalid-text' || out.reason === 'invalid-target' || out.reason === 'not-local-target') ? 400
+        : out.status === 'unreachable' ? 503 : 422;
+    return send(res, code, out);
+  });
+
+  r.post('/stop', async (req, res) => {
+    const resolved = await originOr401(req, res); if (!resolved) return undefined;
+    const { origin } = resolved;
+    const parsed = parseStopBody(req.body, { federated: resolved.trust === 'federated' });
+    if (parsed.error) return send(res, 400, { status: 'refused', reason: parsed.error });
+    const { target } = parsed;
+    if (dispatcher && isValidInstance(target) && !dispatcher.isLocal(target)) {
+      const out = await dispatcher.dispatch({
+        resource: '/audio/stop', target, origin,
+        payload: { ...(parsed.utteranceId ? { utteranceId: parsed.utteranceId } : {}) },
+      });
+      return send(res, out.status === 'accepted' ? 200 : out.status === 'unreachable' ? 503 : 422, out);
+    }
+    const out = handleStop({ target, utteranceId: parsed.utteranceId, origin }, gateDeps(origin, false));
+    return send(res, out.status === 'accepted' || out.status === 'unknown' ? 200 : 422, out);
+  });
+
+  // Capability del SOLO nodo locale. Non e' una directory: un chiamante non puo'
+  // usare questo endpoint per sondare la capability di un terzo nodo, che va
+  // interrogato sulla propria route federata con la credenziale giusta.
+  r.get('/capability', async (req, res) => {
+    const resolved = await originOr401(req, res, { requireCell: false }); if (!resolved) return undefined;
+    if (resolved.trust === 'federated' && acl && typeof acl.allows === 'function') {
+      const verdict = acl.allows({ trust: resolved.trust, origin: resolved.origin, visited: resolved.visited });
+      if (!verdict || verdict.allowed !== true) return send(res, 403, { error: 'capability non autorizzata' });
+    }
+    if (Object.keys(req.query || {}).some((key) => key !== 'target') || Array.isArray(req.query && req.query.target)) {
+      return send(res, 400, { error: 'query non valida' });
+    }
+    const self = localNodeId();
+    const target = String(req.query.target || self || '');
+    if (!isValidInstance(target)) return send(res, 400, { error: 'target non valido (instanceId 32 hex)' });
+    if (!self || target !== self) return send(res, 403, { error: 'capability descrive solo il nodo locale' });
+    return send(res, 200, describeCapability({ adapter, consent: consent() === true, nodeId: self }));
+  });
+
+  // Status per utteranceId, leggibile SOLO dalla stessa origine (nodo+cella).
+  // Per chiunque altro l'enunciato non esiste: distinguere 404 da 403
+  // permetterebbe di enumerare gli id altrui.
+  r.get('/speak/status/:utteranceId', async (req, res) => {
+    const resolved = await originOr401(req, res); if (!resolved) return undefined;
+    const rc = receiptStore.get(resolved.origin, String(req.params.utteranceId || ''));
+    if (!rc) return send(res, 404, { status: 'unknown', reason: 'not-found' });
+    return send(res, 200, rc);
+  });
+
+  // Status federato: POST e non GET perche' la cella attestata del chiamante
+  // viaggia nel body costruito dal dispatcher. Non e' una API per browser: la
+  // whitelist Hydra e la prova hop rendono il percorso raggiungibile solo da un
+  // origin node gia' autenticato. Il target riapplica l'ACL prima di rivelare
+  // anche il receipt redatto.
+  r.post('/speak/status', async (req, res) => {
+    const resolved = await originOr401(req, res); if (!resolved) return undefined;
+    if (resolved.trust !== 'federated') return send(res, 403, { status: 'refused', reason: 'federated-only' });
+    const parsed = parseRemoteStatusBody(req.body);
+    if (parsed.error) return send(res, 400, { status: 'refused', reason: parsed.error });
+    if (parsed.target !== localNodeId()) return send(res, 403, { status: 'refused', reason: 'not-local-target' });
+    if (acl && typeof acl.allows === 'function') {
+      const verdict = acl.allows({ trust: resolved.trust, origin: resolved.origin, visited: resolved.visited });
+      if (!verdict || verdict.allowed !== true) return send(res, 422, { status: 'refused', reason: 'acl' });
+    }
+    const rc = receiptStore.get(resolved.origin, parsed.utteranceId);
+    if (!rc) return send(res, 404, { status: 'unknown', reason: 'not-found' });
+    return send(res, 200, rc);
+  });
+
+  // I gruppi sono locali all'origine e non fanno parte della whitelist
+  // federata: la loro espansione avviene qui, quindi ogni endpoint riceve un
+  // comando /audio/speak esatto e applica autonomamente consenso/ACL/READONLY.
+  r.post('/groups/speak', async (req, res) => {
+    const resolved = await originOr401(req, res); if (!resolved) return undefined;
+    if (resolved.trust !== 'local-bridge') return send(res, 403, { status: 'refused', reason: 'local-bridge-required' });
+    const parsed = parseGroupSpeakBody(req.body);
+    if (parsed.error) return send(res, 400, { status: 'refused', reason: parsed.error });
+    if (readonly()) return send(res, 422, { status: 'refused', reason: 'readonly' });
+    if (parsed.utteranceId && receiptStore.get(resolved.origin, parsed.utteranceId)) {
+      return send(res, 422, { status: 'refused', reason: 'utterance-collision' });
+    }
+    const out = await groupSpeaker.speakGroup({ origin: resolved.origin, ...parsed });
+    const code = out.status === 'refused' ? 422 : 200;
+    return send(res, code, out);
+  });
+
+  r.get('/groups/status/:utteranceId', async (req, res) => {
+    const resolved = await originOr401(req, res); if (!resolved) return undefined;
+    if (resolved.trust !== 'local-bridge') return send(res, 403, { status: 'refused', reason: 'local-bridge-required' });
+    const utteranceId = String(req.params.utteranceId || '');
+    if (!UTTERANCE_ID_RE.test(utteranceId)) return send(res, 400, { status: 'refused', reason: 'invalid-utterance' });
+    const receipt = groupSpeaker.getStatus({ origin: resolved.origin, utteranceId });
+    if (!receipt) return send(res, 404, { status: 'unknown', reason: 'not-found' });
+    return send(res, 200, receipt);
+  });
+
+  r.post('/groups/stop', async (req, res) => {
+    const resolved = await originOr401(req, res); if (!resolved) return undefined;
+    if (resolved.trust !== 'local-bridge') return send(res, 403, { status: 'refused', reason: 'local-bridge-required' });
+    if (!onlyKeys(req.body, new Set(['utteranceId'])) || typeof req.body.utteranceId !== 'string' || !UTTERANCE_ID_RE.test(req.body.utteranceId)) {
+      return send(res, 400, { status: 'refused', reason: 'invalid-utterance' });
+    }
+    const out = await groupSpeaker.stopGroup({ origin: resolved.origin, utteranceId: req.body.utteranceId });
+    return send(res, out.status === 'refused' ? 422 : 200, out);
+  });
+
+  r.use((err, _req, res, _next) => {
+    if (err && (err.type === 'entity.too.large' || err.status === 413)) {
+      return res.status(413).json({ error: 'body troppo grande' });
+    }
+    if (err instanceof SyntaxError) return res.status(400).json({ error: 'JSON non valido' });
+    return res.status(err.status || 400).json({ error: 'richiesta audio non valida' });
+  });
+
+  return r;
+}
+
+module.exports = {
+  audioRoutes, UTTERANCE_ID_RE, LANG_RE, VOICE_RE,
+  parseSpeakBody, parseStopBody, parseGroupSpeakBody,
+};

package/lib/audio/speak.js

@@ -0,0 +1,125 @@
+'use strict';
+// lib/audio/speak.js — catena di gate LATO TARGET: la decisione di emettere
+// suono la prende il nodo che possiede l'altoparlante, sempre, anche quando la
+// richiesta e' gia' passata da una route federata autorizzata.
+//
+// Ordine dei gate, deliberato:
+//   0. testo valido (1..320)                    — nessun effetto collaterale
+//   1. target esatto e uguale a QUESTO nodo     — un nodo parla solo per se'
+//   2. READONLY                                 — `speak` e' una mutazione: ha
+//      un effetto fisico osservabile, quindi in sola lettura si rifiuta
+//   3. ACL sull'origine
+//   4. consenso audio locale (default OFF)
+//   5. idempotenza per utteranceId              — PRIMA del rate limit, cosi' un
+//      retry identico non consuma budget e non produce una seconda voce
+//   6. rate limit dedicato
+//   7. adapter/coda presenti                    — senza adapter si dice no, non
+//      si finge un `accepted`
+//   8. accodamento
+//
+// I gate 3 e 4 stanno prima dell'idempotenza di proposito: un rifiuto per ACL o
+// consenso deve restare un rifiuto anche al secondo tentativo, non trasformarsi
+// in un receipt riusato.
+const INSTANCE_ID_RE = /^[a-f0-9]{32}$/i;
+const TEXT_MAX = 320;
+
+function isValidInstance(v) {
+  return typeof v === 'string' && INSTANCE_ID_RE.test(v);
+}
+
+// handleSpeak(): ritorna SEMPRE uno stato per endpoint, mai un booleano.
+// `deps.receipt(status, opts)` registra e ritorna il receipt redatto.
+function handleSpeak(input, deps) {
+  const opts = input || {};
+  const d = deps || {};
+  const { target, origin } = opts;
+
+  if (typeof opts.text !== 'string' || opts.text.length < 1 || opts.text.length > TEXT_MAX) {
+    return { status: 'refused', reason: 'invalid-text' };
+  }
+  if (!isValidInstance(target)) return { status: 'refused', reason: 'invalid-target' };
+  // Un target diverso da questo nodo non e' affar suo: il nodo non ritrasmette
+  // e non fa da relay applicativo per la voce di un altro.
+  if (typeof d.localNodeId === 'function' && target !== d.localNodeId()) {
+    return { status: 'refused', reason: 'not-local-target' };
+  }
+  if (typeof d.readonly === 'function' && d.readonly()) {
+    return d.receipt('refused', { reason: 'readonly', target, origin, utteranceId: opts.utteranceId });
+  }
+  if (typeof d.acl === 'function') {
+    const verdict = d.acl({ trust: opts.trust, origin, visited: opts.visited });
+    if (!verdict || verdict.allowed !== true) {
+      // La reason resta generica verso l'esterno: la ragione precisa del rifiuto
+      // descriverebbe la topologia del nodo a chi non e' autorizzato a vederla.
+      return d.receipt('refused', { reason: 'acl', target, origin, utteranceId: opts.utteranceId });
+    }
+  }
+  if (typeof d.consent === 'function' && d.consent() !== true) {
+    return d.receipt('refused', { reason: 'consent', target, origin, utteranceId: opts.utteranceId });
+  }
+  if (opts.utteranceId && typeof d.findReceipt === 'function') {
+    const found = d.findReceipt(opts.utteranceId, origin, target);
+    if (found === 'collision') {
+      const ts = typeof d.now === 'function' ? d.now() : Date.now();
+      return {
+        status: 'refused', reason: 'utterance-collision', utteranceId: opts.utteranceId,
+        origin: { node: origin && origin.node, cell: origin && origin.cell }, target, timestamp: ts,
+      };
+    }
+    if (found) return found;
+  }
+  if (d.rateLimiter) {
+    const rl = d.rateLimiter.check({ origin, target, urgency: opts.urgency });
+    if (!rl.allowed) {
+      return d.receipt('refused', { reason: 'rate-limit', target, origin, utteranceId: opts.utteranceId });
+    }
+  }
+  if (!d.queue || typeof d.queue.enqueue !== 'function') {
+    return d.receipt('refused', { reason: 'no-adapter', target, origin, utteranceId: opts.utteranceId });
+  }
+  // Il receipt nasce PRIMA dell'accodamento: la coda aggiornera' questo stesso
+  // utteranceId quando l'adapter conferma l'avvio, fallisce o va in timeout.
+  const receipt = d.receipt('accepted', { target, origin, utteranceId: opts.utteranceId });
+  const admitted = d.queue.enqueue({
+    utteranceId: receipt.utteranceId,
+    text: opts.text, lang: opts.lang, voice: opts.voice, urgency: opts.urgency,
+  });
+  if (admitted.status !== 'accepted') {
+    return (d.updateReceipt && d.updateReceipt(receipt.utteranceId, admitted.status, admitted.reason))
+      || { ...receipt, status: admitted.status, ...(admitted.reason ? { reason: admitted.reason } : {}) };
+  }
+  // La coda puo' aver gia' concluso in modo sincrono (adapter fake nei test,
+  // fallimento immediato di spawn): si rilegge il receipt invece di riportare
+  // uno stato ormai superato.
+  return (d.readReceipt && d.readReceipt(receipt.utteranceId, origin)) || receipt;
+}
+
+// handleStop(): comando di controllo, non sintesi. Lo stop LOCALE e' sovrano e
+// non dipende dalla rete: un endpoint deve poter tacere anche offline. Uno stop
+// remoto per utteranceId vale solo per gli enunciati del chiamante.
+function handleStop(input, deps) {
+  const opts = input || {};
+  const d = deps || {};
+  const { target, origin } = opts;
+  if (!isValidInstance(target)) return { status: 'refused', reason: 'invalid-target' };
+  if (typeof d.localNodeId === 'function' && target !== d.localNodeId()) {
+    return { status: 'refused', reason: 'not-local-target' };
+  }
+  // READONLY non blocca lo stop: fermare una voce e' sempre permesso. Impedirlo
+  // significherebbe che un nodo in sola lettura non puo' zittirsi.
+  if (opts.utteranceId) {
+    if (typeof d.findReceipt === 'function') {
+      const found = d.findReceipt(opts.utteranceId, origin, target);
+      if (!found || found === 'collision') {
+        return { status: 'unknown', reason: 'utterance-not-found', utteranceId: opts.utteranceId };
+      }
+    }
+    const acted = d.queue && typeof d.queue.stop === 'function' ? d.queue.stop(opts.utteranceId) : false;
+    if (d.updateReceipt && acted) d.updateReceipt(opts.utteranceId, 'refused', 'stopped');
+    return { status: 'accepted', utteranceId: opts.utteranceId, stopped: acted === true };
+  }
+  const acted = d.queue && typeof d.queue.stopAll === 'function' ? d.queue.stopAll() : false;
+  return { status: 'accepted', stopped: acted === true };
+}
+
+module.exports = { handleSpeak, handleStop, isValidInstance, INSTANCE_ID_RE, TEXT_MAX };

package/lib/fleet/managed.js

@@ -60,7 +60,11 @@ const ALIBABA_PI_MODELS = Object.freeze([
 ]);
 
 const CUSTOM_KEYS = ['displayName', 'protocol', 'baseUrl', 'envKey', 'providerId'];
-const MANAGED_KEYS = new Set(['client', 'provider', 'credentialProfile', 'model', 'permissionPolicy', ...CUSTOM_KEYS]);
+const MANAGED_KEYS = new Set(['client', 'provider', 'credentialProfile', 'model', 'permissionPolicy', 'credentialSourcePolicy', ...CUSTOM_KEYS]);
+// Explicit credential source policy. Default 'auto' preserves the legacy
+// resolution order (runtime -> store -> shell -> key files -> legacy) so a
+// pre-WP1 fleet.json migrates no-op: no existing cell changes resolution.
+const CREDENTIAL_SOURCES = Object.freeze(['environment', 'nexuscrew-store', 'auto']);
 const CLIENT_LABELS = Object.freeze({ claude: 'Claude Code', codex: 'Codex', 'codex-vl': 'Codex-VL', pi: 'Pi', agy: 'Agy', shell: 'Shell' });
 const PROVIDER_ID_RE = /^[a-z][a-z0-9_-]{0,31}$/;
 
@@ -167,7 +171,13 @@ function normalizeManagedSpec(value) {
   const permissionPolicy = value.permissionPolicy === undefined ? (profile.client === 'claude' ? 'unsafe' : 'standard') : value.permissionPolicy;
   if (permissionPolicy !== 'standard' && permissionPolicy !== 'unsafe') return null;
   if ((value.client === 'pi' || value.client === 'shell') && permissionPolicy !== 'standard') return null;
+  const credentialSourcePolicy = value.credentialSourcePolicy === undefined ? 'auto' : value.credentialSourcePolicy;
+  if (!CREDENTIAL_SOURCES.includes(credentialSourcePolicy)) return null;
   const out = { client: profile.client, provider: profile.provider, model, permissionPolicy };
+  // 'auto' is the default and stays ABSENT from the normalized spec, so a legacy
+  // fleet.json (no credentialSourcePolicy) migrates truly no-op: no added field,
+  // no change in resolution. Explicit environment|nexuscrew-store are recorded.
+  if (credentialSourcePolicy !== 'auto') out.credentialSourcePolicy = credentialSourcePolicy;
   if (profile.credentialProfile) out.credentialProfile = profile.credentialProfile;
   if (profile.credentialEnv) {
     const envKey = typeof value.envKey === 'string' && value.envKey.trim()
@@ -416,10 +426,20 @@ function credentialSources(cfg, home) {
 function credential(profile, spec, cfg, home) {
   if (profile.auth === 'login' || profile.auth === 'none') return { envKey: profile.auth, value: '', source: profile.auth };
   const envKey = profile.auth === 'dynamic' ? spec.envKey : profile.auth;
+  const policy = spec && CREDENTIAL_SOURCES.includes(spec.credentialSourcePolicy) ? spec.credentialSourcePolicy : 'auto';
   const sources = credentialSources(cfg, home);
   // The fixed shell file is already the user's environment source. Values are
   // consumed only in memory and passed to the selected child; never persisted
   // in fleet.json, service files, API responses or logs.
+  if (policy === 'environment') {
+    if (sources.runtime[envKey]) return { envKey, value: sources.runtime[envKey], source: 'environment' };
+    return { envKey, value: '', source: 'missing' };
+  }
+  if (policy === 'nexuscrew-store') {
+    if (sources.local[envKey]) return { envKey, value: sources.local[envKey], source: 'nexuscrew-store' };
+    return { envKey, value: '', source: 'missing' };
+  }
+  // auto: legacy resolution order (runtime -> store -> shell -> keys -> legacy).
   if (sources.runtime[envKey]) return { envKey, value: sources.runtime[envKey], source: 'environment' };
   if (sources.local[envKey]) return { envKey, value: sources.local[envKey], source: 'local' };
   if (sources.shell[envKey]) return { envKey, value: sources.shell[envKey], source: 'compatibility' };
@@ -430,6 +450,31 @@ function credential(profile, spec, cfg, home) {
   return { envKey, value: '', source: 'missing' };
 }
 
+// The profile's "owned" env set. When the credential source is the local store,
+// the child environment must not inherit any of these from the runtime: the
+// entire set is enumerated and neutralized (unset), never just envKey. For
+// Anthropic-compatible (claude.*) clients the set is the ANTHROPIC_* triple;
+// every other client keeps the single profile envKey.
+function credentialEnvNeutralizeSet(profile) {
+  if (!profile) return [];
+  if (profile.client === 'claude') return ['ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY'];
+  const auth = profile.auth;
+  const envKey = auth && auth !== 'dynamic' && auth !== 'login' && auth !== 'none'
+    ? auth : (profile.defaultEnvKey || '');
+  return envKey ? [envKey] : [];
+}
+
+// Apply nexuscrew-store neutralization to a composed child env: keys of the
+// profile set that carry no NexusCrew-injected value are UNSET (deleted), never
+// left as an empty string. 'auto'/'environment' are unchanged (legacy behavior).
+function applyStoreNeutralization(env, spec, profile) {
+  if (!env || !spec || spec.credentialSourcePolicy !== 'nexuscrew-store') return env;
+  for (const k of credentialEnvNeutralizeSet(profile)) {
+    if (env[k] === undefined || env[k] === '') delete env[k];
+  }
+  return env;
+}
+
 let ollamaCache = { at: 0, models: [] };
 async function discoverOllamaModels(opts = {}) {
   const now = Date.now(); const ttl = opts.ttlMs === undefined ? 30000 : opts.ttlMs;
@@ -527,6 +572,7 @@ function describeManaged(spec, cfg = {}) {
     credentialProfile: normalized.credentialProfile || '', model: normalized.model,
     permissionPolicy: normalized.permissionPolicy, protocol: normalized.protocol || profile.protocol,
     endpoint: normalized.baseUrl || profile.endpoint || '', auth: cred.envKey, authConfigured,
+    credentialSourcePolicy: normalized.credentialSourcePolicy || 'auto',
     credentialSource: authConfigured ? cred.source : 'missing',
     configured, models: [...(profile.models || [])], defaultModel: profile.model || '',
     binary: binary || '', displayName: normalized.displayName || profile.label,
@@ -814,6 +860,10 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     if (cell?.prompt) args.push('--prompt-interactive');
   }
   if (spec.client !== 'shell' && cell?.prompt) args.push(cell.prompt);
+  // nexuscrew-store source: neutralize the profile's env set in the composed
+  // child env (unset, never empty), so the runtime cannot leak credentials that
+  // the local store is meant to own.
+  applyStoreNeutralization(env, spec, profile);
   let command = info.binary;
   if (needsExplicitNode(info.binary, cfg.platform || process.platform, cfg.env || process.env)) {
     command = cfg.nodeExecPath || process.execPath;
@@ -841,10 +891,11 @@ function publicCatalog() {
 module.exports = {
   CATALOG, OLLAMA_CLOUD_MODELS, OLLAMA_CONTEXT, ALIBABA_TOKEN_PLAN_MODELS,
   ALIBABA_CODEX_MODELS, ALIBABA_TOKEN_PLAN_CONTEXT, ALIBABA_PI_MODELS,
-  CLIENT_LABELS, normalizeManagedSpec,
+  CLIENT_LABELS, normalizeManagedSpec, profileFor,
   defaultDefinitions, defaultShellEngine, defaultAgyEngine, describeManaged, describeCatalogCredential, discoverOllamaModels, resolveManagedEngine, needsExplicitNode,
   discoverPiModels, parseEnvFile, parseProviderShellFile, findBinary, publicCatalog, writePiProviderExtension,
   providerKeyPaths, parseProviderKeyFiles, credentialSources, credential,
+  credentialEnvNeutralizeSet, applyStoreNeutralization,
   ensureKimiClaudeConfig, ensureAlibabaClaudeConfig, resolveInteractiveShell,
   shellLoginArgs, shellConfiguredCommandArgs, ENV_KEY_RE,
 };

package/lib/fleet/provider.js

@@ -13,6 +13,12 @@ function disabled(reason) {
 }
 
 async function selectProvider(cfg = {}) {
+  // Seam esplicito per i test: permette di far girare il server REALE con uno
+  // stato Fleet controllato, senza tmux ne' processi. Esiste perche' i confini
+  // che dipendono dalle celle attive (l'origine di Audio Share) vanno provati
+  // sul server vero: un test che inietta le dipendenze nel router non si
+  // accorgerebbe mai di un cablaggio sbagliato.
+  if (cfg.fleetSeam) return { mode: 'seam', reason: 'fleet iniettata (seam di test)', fleet: cfg.fleetSeam };
   if (cfg.fleetEnabled === false) return disabled('fleet disabilitata (fleetEnabled=false)');
   if (cfg.builtinEnabled === false) return disabled('fleet builtin disabilitata (builtinEnabled=false)');
   const fleet = await createBuiltinFleet({ ...cfg, fleetProviderReason: 'NexusCrew builtin fleet' });