@mmmbuto/nexuscrew 0.8.52-rc.9 → 0.8.53

package/lib/mcp/tools.js

@@ -48,6 +48,52 @@ const IDENTITY_REMEDIATION =
   + 'oppure assicurati che il client MCP inoltri il contesto tmux al processo child: nessun valore '
   + 'viene copiato nella CLI o nel file di configurazione.';
 
+// Perche' una ricerca fallita non e' una sola cosa.
+//
+// Il messaggio storico era «cella destinataria non trovata nella rete
+// autorizzata» per OGNI fallimento. Chi lo leggeva andava a controllare la
+// directory e le autorizzazioni — cioe' i due posti dove il difetto non era.
+// Il caso reale: un instanceId RIBATTUTO invece che copiato da `nc_cells`, con
+// un carattere perso. `NODE_ID_RE` accetta 16-64 esadecimali, quindi un id
+// troncato passa la validazione, e da li' in poi ogni indizio puntava altrove.
+// Il costo e' stato un'indagine su un canale che funzionava.
+//
+// Le tre risposte sono distinte perche' portano a tre azioni distinte:
+// correggere l'id, accendere il nodo, correggere il nome della cella.
+function cellLookupFailure(directory, targetRef) {
+  const cells = Array.isArray(directory.cells) ? directory.cells : [];
+  if (cells.some((cell) => cell.instanceId === targetRef.instanceId)) {
+    return `cella "${targetRef.cell}" non trovata sul nodo ${targetRef.instanceId}`;
+  }
+  const down = (Array.isArray(directory.unavailable) ? directory.unavailable : [])
+    .find((owner) => owner.instanceId === targetRef.instanceId);
+  // Il nodo esiste ed e' autorizzato: e' irraggiungibile adesso. Dirlo evita di
+  // cercare un errore di configurazione al posto di un dispositivo spento.
+  if (down) return `nodo ${targetRef.instanceId} non raggiungibile (${down.failure}): le sue celle non sono in elenco`;
+  // «rete autorizzata» resta fuori di proposito: e' la formula che faceva
+  // leggere un id sbagliato come un problema di permessi.
+  return `nessun nodo con instanceId ${targetRef.instanceId} fra quelli noti a questo hub`
+    + ' — copia l\'id esatto da nc_cells invece di ribatterlo';
+}
+
+// La stessa lezione sull'altra directory. `VL_TARGET_RE` accetta anch'esso
+// 16-64 esadecimali per l'owner, quindi un id ribattuto e troncato arriva fino
+// alla ricerca esattamente come per le celle — e il messaggio unico nominava il
+// micro-device e l'autorizzazione, tacendo sull'owner.
+function vlLookupFailure(directory, { instanceId, nodeId = null }) {
+  const owners = Array.isArray(directory.owners) ? directory.owners : [];
+  // Se l'owner c'e', allora manca davvero il device: e' l'unico caso in cui il
+  // soggetto giusto e' il micro-device.
+  if (nodeId && owners.some((owner) => owner.instanceId === instanceId)) {
+    return `micro-device VL-${nodeId} non trovato sull'owner ${instanceId}`;
+  }
+  const down = (Array.isArray(directory.unavailable) ? directory.unavailable : [])
+    .find((owner) => owner.instanceId === instanceId);
+  if (down) return `owner ${instanceId} non raggiungibile (${down.failure}): la sua directory VL non e' in elenco`;
+  return `nessun owner con instanceId ${instanceId} fra quelli noti a questo hub`
+    + ' — copia l\'id esatto da nc_vl_nodes invece di ribatterlo';
+}
+
 function requireSession(session, tool, code = IDENTITY_CODE.MISSING) {
   if (session) return session;
   const stableCode = code === IDENTITY_CODE.INVALID ? IDENTITY_CODE.INVALID : IDENTITY_CODE.MISSING;
@@ -237,6 +283,10 @@ const TOOLS = [
           type: 'string',
           description: 'lingua opzionale del testo: it, en, es o locale BCP-47 equivalente (es. it-IT)',
         },
+        target: {
+          type: 'string',
+          description: 'instanceId ESATTO del nodo su cui sta l\'operatore, per avvisarlo quando non e\' su questo nodo. Ottienilo da nc_cells/nc_status; niente wildcard. Omesso = questo nodo.',
+        },
       },
       required: ['title'],
     },
@@ -245,6 +295,10 @@ const TOOLS = [
       const body = argString(args, 'body', { max: 2000 });
       const urgency = argString(args, 'urgency', { max: 16 });
       const rawLang = argString(args, 'lang', { max: 35 });
+      const target = argString(args, 'target', { max: 64 });
+      if (target !== undefined && !/^[a-f0-9]{32}$/i.test(target)) {
+        throw new Error('target deve essere un instanceId di nodo (32 hex)');
+      }
       if (urgency !== undefined && urgency !== 'normal' && urgency !== 'high') {
         throw new Error('urgency deve essere "normal" o "high"');
       }
@@ -258,9 +312,18 @@ const TOOLS = [
         ...(body ? { body } : {}),
         ...(urgency ? { urgency } : {}),
         ...(lang ? { lang } : {}),
+        ...(target ? { target } : {}),
       };
       if (session) payload.session = session;
       const j = await ctx.api('POST', '/api/notify', payload);
+      // Con un target remoto l'esito e' quello del nodo che ha consegnato:
+      // `delivered` da solo direbbe "0 tentativi qui", che e' vero e inutile.
+      // Restituirlo cosi' evita di far leggere un successo dove c'e' un rifiuto.
+      // Nessun conteggio: il dispatcher non lo propaga, e un ramo che non puo'
+      // mai essere vero e' codice morto travestito da informazione
+      // (rilievo R1 di DevAuditor su rc.14). Se un giorno servira' il dettaglio,
+      // va fatto propagare da forward(), non dedotto qui.
+      if (target) return { status: j.status, ...(j.reason ? { reason: j.reason } : {}) };
       return { delivered: j.delivered };
     },
   },
@@ -472,7 +535,7 @@ const TOOLS = [
         || ttlSeconds < 30 || ttlSeconds > 3600) throw new Error('ownerId o ttlSeconds non valido');
       const directory = await readVlDirectory(ctx);
       const owner = directory.owners.find((item) => item.instanceId === ownerId);
-      if (!owner) throw new Error('owner VL non disponibile nella rete autorizzata');
+      if (!owner) throw new Error(vlLookupFailure(directory, { instanceId: ownerId }));
       const apiPath = vlOwnerPath(owner, 'invite');
       if (!apiPath) throw new Error('route owner VL non valida');
       const result = await ctx.api('POST', apiPath, { label, ttlSeconds });
@@ -500,7 +563,7 @@ const TOOLS = [
         || JSON.stringify(commandArgs).length > 4096) throw new Error('target o args VL non validi');
       const directory = await readVlDirectory(ctx);
       const node = directory.nodes.find((item) => item.id === target.id);
-      if (!node) throw new Error('micro-device VL non trovato nella rete autorizzata');
+      if (!node) throw new Error(vlLookupFailure(directory, target));
       if (!node.canManage || !node.online) throw new Error('micro-device VL offline; nessun comando accodato');
       const apiPath = vlOwnerPath(node, `${target.nodeId}/commands`);
       if (!apiPath) throw new Error('route micro-device VL non valida');
@@ -523,7 +586,7 @@ const TOOLS = [
       if (!target) throw new Error('target VL non valido');
       const directory = await readVlDirectory(ctx);
       const node = directory.nodes.find((item) => item.id === target.id);
-      if (!node) throw new Error('micro-device VL non trovato nella rete autorizzata');
+      if (!node) throw new Error(vlLookupFailure(directory, target));
       const apiPath = vlOwnerPath(node, target.nodeId);
       if (!apiPath) throw new Error('route micro-device VL non valida');
       await ctx.api('DELETE', apiPath);
@@ -604,7 +667,7 @@ const TOOLS = [
       if (!sender) throw new Error('nc_send_cell: la sessione chiamante non e\' una cella Fleet attiva locale');
       const target = directory.cells.find((cell) => cell.instanceId === targetRef.instanceId
         && cell.cell === targetRef.cell);
-      if (!target) throw new Error('cella destinataria non trovata nella rete autorizzata');
+      if (!target) throw new Error(cellLookupFailure(directory, targetRef));
       if (!target.canReceive) throw new Error('cella destinataria non attiva; nessun messaggio accodato');
       const apiPath = target.route === 'local'
         ? '/api/cells/send' : routePath(target.route.split('/'), 'cells/send');

package/lib/nodes/commands.js

@@ -252,6 +252,15 @@ function nodesInspect(opts) {
     log(`tipo:      ${peer.kind} · ${peer.relation}`);
     log(`route:     ${peer.route.join(' -> ')}`);
     if (peer.tunnel) log(`status:    ${peer.tunnel.status}`);
+    // Uno scope celle ristretto e' una limitazione che l'operatore ha imposto
+    // e che poi non vede piu' da nessuna parte: si dimentica, e il giorno che
+    // un peer "non trova" una cella la causa e' invisibile. Il caso `all` non
+    // si stampa: e' il default, e una riga per dire "nessun limite" e' rumore.
+    if (peer.cellVisibility === 'none') log('celle:     nessuna (scope: none)');
+    else if (peer.cellVisibility === 'selected') {
+      const cells = Array.isArray(peer.cells) ? peer.cells : [];
+      log(`celle:     ${cells.length ? cells.join(', ') : 'nessuna (elenco vuoto)'} (scope: selected)`);
+    }
     log(`azioni:    ${Object.keys(peer.actions || {}).filter((key) => peer.actions[key]).join(', ')}`);
   }
   return { code: 0, peer: found.peer };
@@ -267,9 +276,12 @@ function nodesEdit(opts) {
   const node = resolveStoredNode(st, opts.ref || opts.name);
   if (!node) { log(`nodes edit: nodo sconosciuto "${opts.ref || opts.name || ''}"`); return { code: 1, reason: 'unknown-node' }; }
   const supplied = opts.patch && typeof opts.patch === 'object' ? opts.patch : {};
+  // Lo scope celle vale per QUALUNQUE peer accoppiato, in entrambe le
+  // direzioni: riguarda chi accede alle celle di questo nodo, non chi ha
+  // aperto il tunnel.
   const allowed = node.direction === 'inbound'
-    ? new Set(['label', 'visibility', 'selected'])
-    : new Set(['label', 'ssh', 'sshPort', 'autostart']);
+    ? new Set(['label', 'visibility', 'selected', 'cellVisibility', 'cells'])
+    : new Set(['label', 'ssh', 'sshPort', 'autostart', 'cellVisibility', 'cells']);
   const keys = Object.keys(supplied);
   const invalid = keys.find((key) => !allowed.has(key));
   if (invalid) {
@@ -298,6 +310,13 @@ function nodesEdit(opts) {
     log('nodes edit: visibility non valida'); return { code: 1, reason: 'invalid-visibility' };
   }
   if (patch.visibility !== 'selected') delete patch.selected;
+  // Stessa simmetria per lo scope celle. `delete` non basterebbe: updateNode
+  // fonde patch e nodo esistente, quindi le celle concesse prima
+  // sopravviverebbero alla modalita' che le revoca — e tornerebbero buone al
+  // primo ritorno a `selected`, concedendo in silenzio cio' che l'operatore
+  // credeva di aver tolto. `undefined` invece le fa sparire, perche' parseNode
+  // ricostruisce il nodo da zero.
+  if (Object.hasOwn(patch, 'cellVisibility') && patch.cellVisibility !== 'selected') patch.cells = undefined;
 
   let next;
   try { next = store.updateNode(st, node.name, patch); }
@@ -475,6 +494,70 @@ async function nodesTest(opts) {
   };
 }
 
+// `nodes test` senza riferimento: prova TUTTI i peer diretti e chiude con le
+// incoerenze.
+//
+// Nasce da un caso reale: tre peer su quattro risultavano "Share enabled" e uno
+// solo aveva davvero il canale inverso attivo. La diagnosi c'era gia' —
+// `nodes test <nodo>` distingue OK, KO e passivo con precisione — ma andava
+// lanciata un nodo alla volta, sapendo gia' di doverlo fare. Uno stato che
+// mostra il DESIDERIO ("Share enabled") accanto a nessuna verifica non e' una
+// bugia del codice: e' una domanda che nessuno pensa di fare.
+//
+// Il valore non e' l'elenco, che si otteneva anche prima: e' l'ultima riga.
+async function nodesTestAll(opts) {
+  const log = opts.log || console.log;
+  const { nodesPath } = resolveNodePaths(opts);
+  const st = store.loadStore(nodesPath);
+  const nodes = st && Array.isArray(st.nodes) ? st.nodes : [];
+  if (!nodes.length) {
+    log('nodes test: nessun nodo configurato');
+    return { code: 0, results: [] };
+  }
+  // In parallelo: un peer irraggiungibile consuma il proprio timeout, e in
+  // sequenza quattro nodi spenti farebbero sembrare rotto il comando.
+  const results = await Promise.all(nodes.map(async (node) => {
+    const lines = [];
+    let outcome;
+    try {
+      outcome = await nodesTest({ ...opts, ref: node.name, log: (line) => lines.push(String(line)) });
+    } catch (e) {
+      outcome = { code: 1, result: 'errore', detail: String(e && e.message || e) };
+    }
+    return {
+      name: node.name,
+      shared: node.shared === true,
+      result: outcome.result || 'sconosciuto',
+      line: lines.length ? lines[lines.length - 1] : `nodes test [${node.name}]: esito non riportato`,
+    };
+  }));
+  for (const entry of results) log(entry.line);
+
+  // L'incoerenza che conta: dichiarato condiviso, canale non verificabile.
+  // Non e' per forza un difetto — un dispositivo spento finisce qui — ma e'
+  // esattamente cio' che lo stato mostrato non dice.
+  const declaredNotProven = results.filter((entry) => entry.shared && entry.result !== 'ok');
+  if (declaredNotProven.length) {
+    log('');
+    log(`nodes test: ${declaredNotProven.length} nodo/i risultano condivisi ma il canale inverso non risponde: ${declaredNotProven.map((entry) => entry.name).join(', ')}`);
+    // La riga esiste per essere letta da chi ha il problema. Dice DOVE
+    // guardare (qui, sull'hub), COSA deve esserci (le porte del pool di quel
+    // dispositivo) e la parola da cercare (permitlisten).
+    //
+    // La concessione sta sull'HUB, non sul dispositivo: il dispositivo CHIEDE
+    // il bind reverse, ma e' lo sshd di questa macchina a concederlo o negarlo
+    // in base alla riga di `authorized_keys` che porta la sua chiave. Mandare
+    // l'operatore a cercare sul dispositivo sarebbe peggio di una riga vaga —
+    // lo si manderebbe dalla parte sbagliata, che e' esattamente il modo in cui
+    // questo difetto e' rimasto aperto per giorni.
+    log('nodes test: "Share attivo" e\' lo stato desiderato, non una verifica. Un dispositivo spento finisce qui; se e\' acceso, il bind inverso viene rifiutato prima di salire: su QUESTO hub, la chiave di quel dispositivo in ~/.ssh/authorized_keys deve concedere le porte del suo pool (opzione SSH permitlisten).');
+  }
+  // Esito 0 anche con incoerenze: questo comando RIFERISCE, non giudica. Un
+  // codice diverso da zero farebbe fallire ogni script che lo usa per stampare
+  // lo stato, e un dispositivo spento non e' un errore dell'installazione.
+  return { code: 0, results, declaredNotProven: declaredNotProven.map((entry) => entry.name) };
+}
+
 // probe HTTP di default (fetch built-in, Node >=18). Ritorna {ok, status}.
 async function defaultHttpProbe(url, headers) {
   const res = await fetch(url, { headers, redirect: 'manual' });
@@ -576,7 +659,7 @@ function nodesSetToken(opts) {
 }
 
 module.exports = {
-  nodesAdd, nodesList, nodesInspect, nodesEdit, nodesRemove, nodesTest,
+  nodesAdd, nodesList, nodesInspect, nodesEdit, nodesRemove, nodesTest, nodesTestAll,
   nodesUp, nodesDown, nodesRestart, nodesSetToken,
   // helper esposti per test/riuso
   assignLocalPort, bindLocalPort, reserveLocalPort, defaultKeyPath, ensureKey, readSecretToken,

package/lib/nodes/identity.js

@@ -0,0 +1,232 @@
+'use strict';
+// lib/nodes/identity.js — la chiave di questo nodo, e cosa sappiamo delle altrui.
+//
+// Primo passo del modello di autorita' per-nodo, e il piu' modesto: «chiavi per
+// nodo e directory delle pubbliche, nessun effetto sui permessi». Quella
+// clausola e' un vincolo, non una nota: qui si OSSERVA e si REGISTRA, non si
+// concede e non si nega. Nessuna via cambia comportamento perche' una chiave
+// c'e' o non c'e'.
+//
+// PERCHE' UN PASSO CHE NON CAMBIA NULLA VALE COMUNQUE. Tutto il modello poggia
+// su una proprieta' sola: che `holderKey` identifichi davvero un titolare. Se
+// l'identita' di un peer potesse cambiare in silenzio, i grant dei passi 3-5
+// sarebbero legati a un nome che chiunque puo' prendersi, e nessuna firma
+// varrebbe niente. Quella proprieta' si guadagna adesso, osservando presto e a
+// lungo, o non si guadagna piu': una chiave legata oggi ha una storia domani.
+//
+// LA REGOLA: una chiave gia' legata NON viene mai sovrascritta. La prima
+// osservazione lega (TOFU), una successiva diversa e' un CONFLITTO che si
+// registra e si mostra. Sovrascrivere sarebbe comodo — il peer ha reinstallato,
+// ha rigenerato, e' tutto normale — ed e' esattamente il comportamento che
+// rende l'identita' inutile: chi sa rispondere a un probe diventerebbe il peer.
+//
+// STATO REALE, perche' non si creda piu' di cio' che c'e': OGGI IL PAIRING E'
+// L'UNICO SCRITTORE di chiavi, e scrive inline in `/pair/confirm` e nel
+// coordinatore. `observePeerKey` NON HA CHIAMANTI: e' la primitiva del primo
+// percorso che imparera' una chiave FUORI dal pairing, e arriva con lui. Fino
+// ad allora nessuna chiave puo' essere sovrascritta perche' non esiste un
+// secondo scrittore — la proprieta' regge per assenza, non per controllo, e la
+// differenza va detta invece che lasciata credere.
+//
+// Rilievo dell'audit indipendente: una funzione provata e senza chiamanti e' il
+// segnale piu' forte che una garanzia esista, ed e' il piu' facile da dare per
+// sbaglio.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+// Ed25519 grezza: 32 byte, in base64url. Lunghezza fissa, niente PEM sul filo,
+// niente ambiguita' di codifica fra due implementazioni.
+const PUBLIC_KEY_RE = /^[A-Za-z0-9_-]{43}$/;
+const KEY_BASENAME = 'node-key.json';
+const KEY_SCHEMA_VERSION = 1;
+
+function keyPathFor(home) {
+  return path.join(home, '.nexuscrew', KEY_BASENAME);
+}
+
+// La chiave vive accanto a nodes.json, non accanto alla home: chi ha gia' un
+// `nodesPath` — le route, il coordinatore di pairing, ogni test con una home
+// finta — non deve ricostruire una home da cui e' gia' derivato. Derivare due
+// volte lo stesso percorso da due basi diverse e' il modo in cui un test passa
+// su un file e la produzione ne usa un altro.
+function keyPathNextTo(nodesPath) {
+  return path.join(path.dirname(nodesPath), KEY_BASENAME);
+}
+
+// La privata sta in un file SUO, non dentro nodes.json. Non e' pignoleria:
+// nodes.json viene letto dalla redazione, dal backup, da `nodes inspect` e
+// dalle viste condivise. Tenerla fuori per COSTRUZIONE vale piu' di ricordarsi
+// di redigerla in cinque punti — dimenticarne uno la pubblicherebbe, e una
+// privata pubblicata una volta e' bruciata per sempre.
+function readKeyFile(p) {
+  let st;
+  try {
+    st = fs.lstatSync(p);
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+  // Un symlink qui e' un modo per farci scrivere altrove o per farci leggere
+  // una chiave che non e' la nostra. Stessa disciplina di atomicWriteStore.
+  if (st.isSymbolicLink()) throw new Error('node-key.json e\' un symlink: rifiuto di usarlo');
+  if (!st.isFile()) throw new Error('node-key.json non e\' un file regolare');
+  // Se il file e' leggibile da gruppo o altri, la chiave e' gia' potenzialmente
+  // fuori. Non la si usa fingendo che vada bene, e non la si "ripara" in
+  // silenzio: un chmod nostro nasconderebbe che qualcuno l'ha letta.
+  if ((st.mode & 0o077) !== 0) {
+    throw new Error(`node-key.json ha permessi ${(st.mode & 0o777).toString(8)}: `
+      + 'la chiave privata e\' leggibile oltre il proprietario, va rigenerata a mano');
+  }
+  // UN FILE CHE ESISTE MA NON E' USABILE FA RUMORE, NON SI SOSTITUISCE.
+  // La prima stesura tornava `null` per uno schema sbagliato — cioe' «genera
+  // pure una chiave nuova» — e LANCIAVA su un JSON corrotto, perche' il parse
+  // stava fuori dal try. Due esiti opposti per due modi di essere illeggibile,
+  // e quello comodo era il piu' pericoloso: rigenerare cambia l'identita' di
+  // questo nodo, e ogni peer che aveva legato la vecchia si ritrova per sempre
+  // con una chiave che non corrisponde. Meglio fermarsi e farlo sapere.
+  // Rilievo dell'audit indipendente; risolto nel verso opposto a quello
+  // proposto, perche' la coerenza va cercata sul ramo sicuro.
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (e) {
+    throw new Error(`node-key.json illeggibile (${e.message}): `
+      + 'non lo sostituisco da solo, perche\' rigenerare cambierebbe l\'identita\' di questo nodo');
+  }
+  const rotto = !parsed || typeof parsed !== 'object' || Array.isArray(parsed)
+    || parsed.schemaVersion !== KEY_SCHEMA_VERSION
+    || typeof parsed.privateKeyPem !== 'string' || !parsed.privateKeyPem.includes('PRIVATE KEY');
+  if (rotto) {
+    throw new Error('node-key.json non ha la forma attesa: '
+      + 'non lo sostituisco da solo, perche\' rigenerare cambierebbe l\'identita\' di questo nodo');
+  }
+  return parsed;
+}
+
+// La pubblica si DERIVA dalla privata a ogni caricamento, e non si conserva
+// accanto. Due copie della stessa cosa possono divergere, e una pubblica che
+// non corrisponde alla privata e' un'identita' che firma e non verifica —
+// il genere di guasto che si scopre solo quando serve.
+function publicKeyFromPrivate(privateKey) {
+  const jwk = crypto.createPublicKey(privateKey).export({ format: 'jwk' });
+  if (!jwk || jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || typeof jwk.x !== 'string') {
+    throw new Error('chiave del nodo non Ed25519');
+  }
+  return jwk.x;
+}
+
+function writeKeyFile(p, privateKeyPem) {
+  const dir = path.dirname(p);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.${KEY_BASENAME}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify({
+      schemaVersion: KEY_SCHEMA_VERSION,
+      privateKeyPem,
+    }, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600); // 0600 a prescindere da umask
+    fs.renameSync(tmp, p);
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch (_) { /* best-effort */ }
+    throw e;
+  }
+}
+
+// ensureNodeKey: idempotente. La prima chiamata genera, le successive leggono.
+// `created` distingue i due casi per chi vuole registrarlo una volta sola.
+// `afterWriteSeam` e' un seam di prova, come `sessionExistsSeam` e `fleetSeam`
+// altrove: viene chiamato subito dopo la scrittura e serve a far accadere la
+// corsa in modo deterministico. Senza, il test della corsa e' verde per
+// costruzione — il file esiste gia' e il percorso di CREAZIONE non viene mai
+// eseguito. L'ho scoperto perche' il controllo negativo non falliva.
+function ensureNodeKey({ home, keyPath, afterWriteSeam } = {}) {
+  const p = keyPath || keyPathFor(home);
+  const existing = readKeyFile(p);
+  if (existing) {
+    const privateKey = crypto.createPrivateKey(existing.privateKeyPem);
+    return { publicKey: publicKeyFromPrivate(privateKey), privateKey, path: p, created: false };
+  }
+  const { privateKey } = crypto.generateKeyPairSync('ed25519');
+  const pem = privateKey.export({ format: 'pem', type: 'pkcs8' }).toString();
+  writeKeyFile(p, pem);
+  if (typeof afterWriteSeam === 'function') afterWriteSeam(p);
+
+  // SI RILEGGE DAL DISCO invece di restituire la chiave appena generata, e non
+  // e' pignoleria: due processi che partono insieme sulla PRIMA creazione
+  // vedono entrambi il file assente, generano due chiavi diverse e i due rename
+  // si sovrascrivono. Chi perde la corsa restituirebbe in memoria una chiave
+  // che sul disco non esiste piu' — e se nel frattempo l'ha mandata a un peer
+  // dentro un pairing, quel peer lega un'identita' che non potremo mai
+  // dimostrare: da li' in poi ogni nostra chiave gli risulta un conflitto, per
+  // sempre, ed e' esattamente il guasto che questo modulo esiste per impedire.
+  // Rileggendo, i due processi convergono su chi ha vinto il rename.
+  const suDisco = readKeyFile(p);
+  const effettiva = suDisco ? crypto.createPrivateKey(suDisco.privateKeyPem) : privateKey;
+  return { publicKey: publicKeyFromPrivate(effettiva), privateKey: effettiva, path: p, created: true };
+}
+
+function isPublicKey(value) {
+  return typeof value === 'string' && PUBLIC_KEY_RE.test(value);
+}
+
+// observePeerKey — il cuore del passo, ed e' quattro righe di logica e un
+// invariante. Torna un nodo NUOVO (non muta l'ingresso) e l'esito osservato.
+//
+//   'bound'     la prima volta: si lega e si registra COME e QUANDO
+//   'unchanged' la chiave e' quella di prima
+//   'conflict'  e' arrivata una chiave DIVERSA. Non si sovrascrive nulla.
+//
+// `source` ('pairing' | 'peer-assertion') non e' decorazione: al passo 3 un
+// grant potra' pretendere una chiave legata AL PAIRING, cioe' nello stesso atto
+// in cui l'operatore ha deciso di fidarsi, e non una arrivata dopo su un canale
+// che il peer stesso controlla. Se non lo registriamo adesso, quella
+// distinzione non e' piu' ricostruibile.
+function observePeerKey(node, { publicKey, source = 'peer-assertion', now = Date.now() } = {}) {
+  if (!isPublicKey(publicKey)) return { node, outcome: 'invalid' };
+  if (!node.publicKey) {
+    return {
+      node: { ...node, publicKey, keySource: source, keyBoundAt: new Date(now).toISOString() },
+      outcome: 'bound',
+    };
+  }
+  if (node.publicKey === publicKey) {
+    // Una chiave gia' legata al pairing non viene "promossa" ne' declassata da
+    // un'osservazione successiva: la provenienza e' quella del legame, non
+    // dell'ultima volta che l'abbiamo rivista.
+    return { node, outcome: 'unchanged' };
+  }
+  // Conflitto. Si conserva il primo legame e si registra cosa e' arrivato,
+  // perche' l'operatore possa decidere: un peer reinstallato e una sostituzione
+  // di identita' hanno la stessa forma sul filo, e a distinguerli non e' il
+  // codice ma chi sa cosa e' successo a quel dispositivo.
+  return {
+    node: { ...node, keyConflict: { seen: publicKey, at: new Date(now).toISOString(), source } },
+    outcome: 'conflict',
+  };
+}
+
+// La directory: cosa questo nodo sa delle identita' altrui. Sola lettura,
+// nessun segreto — le pubbliche sono pubbliche, ed e' il punto.
+function publicKeyDirectory(store) {
+  const nodes = store && Array.isArray(store.nodes) ? store.nodes : [];
+  return nodes.map((node) => ({
+    name: node.name,
+    instanceId: node.nodeId || null,
+    publicKey: node.publicKey || null,
+    source: node.publicKey ? (node.keySource || 'peer-assertion') : null,
+    boundAt: node.keyBoundAt || null,
+    conflict: node.keyConflict || null,
+  }));
+}
+
+module.exports = {
+  ensureNodeKey,
+  observePeerKey,
+  publicKeyDirectory,
+  publicKeyFromPrivate,
+  isPublicKey,
+  keyPathFor,
+  keyPathNextTo,
+  PUBLIC_KEY_RE,
+};

package/lib/nodes/store.js

@@ -18,6 +18,7 @@ const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const reversePool = require('./reverse-pool.js');
+const identity = require('./identity.js');
 
 const SCHEMA_VERSION = 3;
 const PREVIOUS_SCHEMA_VERSION = 2;
@@ -108,8 +109,27 @@ const NODE_KEYS = new Set([
   'name', 'ssh', 'sshPort', 'remotePort', 'localPort', 'keyPath', 'identityFile',
   'roles', 'rolesKnown', 'token', 'acceptToken', 'nodeId', 'transport', 'autostart', 'visibility', 'selected',
   'direction', 'reversePort', 'shared', 'label', 'reversePool',
+  // Quali CELLE di questo nodo il peer puo' vedere. Distinto da `visibility`,
+  // che governa il TRANSITO (attraverso chi passa il traffico) e non l'accesso.
+  'cellVisibility', 'cells',
+  // Identita' crittografica del peer — passo 1 del modello di autorita'. Oggi
+  // NON governa niente: si osserva e si registra. `keySource` distingue una
+  // chiave legata al pairing (nello stesso atto in cui si e' deciso di fidarsi)
+  // da una arrivata dopo su un canale che il peer controlla; al passo 3 un
+  // grant potra' pretendere la prima. `keyConflict` conserva una chiave DIVERSA
+  // vista dopo il legame, senza sostituire quella legata.
+  'publicKey', 'keySource', 'keyBoundAt', 'keyConflict',
 ]);
 
+// Nome di cella: stessa forma usata da fleet/definitions.js, cells/routes.js e
+// mcp/cells.js. E' `cell` la chiave del permesso — unica nel nodo e immutabile —
+// non `tmuxSession`, che e' derivata e ammette override non canonici.
+const CELL_ID_RE = /^[A-Za-z0-9._-]{1,32}$/;
+const MAX_CELLS = 128;
+
+// Un conflitto di chiave e' un record chiuso: cosa e' arrivato, quando, da dove.
+const KEY_CONFLICT_KEYS = new Set(['seen', 'at', 'source']);
+
 const REVERSE_POOL_SLOT_STATES = new Set(['active', 'ready', 'reserved', 'draining', 'quarantined', 'retired']);
 const REVERSE_POOL_VERIFICATIONS = new Set(['verified', 'unverifiable', 'missing', 'invalidated']);
 const REVERSE_POOL_PHASES = new Set(['active', 'prepared', 'switched', 'abandoned']);
@@ -265,6 +285,28 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
     if (selected.some((id) => typeof id !== 'string' || !NODE_ID_RE.test(id))) return null;
     out.selected = selected;
   }
+  // Scope celle. Il default e' `all` quando il campo e' ASSENTE: un default
+  // fail-closed renderebbe muta l'intera flotta al primo aggiornamento, senza
+  // che nessuno abbia deciso nulla. Restringere deve restare un atto esplicito.
+  // `selected` con lista vuota significa invece "nessuna cella", ed e' proprio
+  // per distinguerlo da "campo assente" che la modalita' e' un campo a parte.
+  if (n.cellVisibility !== undefined) {
+    if (!['all', 'none', 'selected'].includes(n.cellVisibility)) return null;
+    out.cellVisibility = n.cellVisibility;
+  } else {
+    out.cellVisibility = 'all';
+  }
+  if (n.cells !== undefined) {
+    // Elencare celle senza dichiarare la modalita' e' ambiguo: l'elenco
+    // sembrerebbe un permesso mentre non lo e'. Meglio rifiutare che indovinare.
+    if (out.cellVisibility !== 'selected') return null;
+    if (!Array.isArray(n.cells) || n.cells.length > MAX_CELLS) return null;
+    const cells = [...new Set(n.cells)];
+    if (cells.some((id) => typeof id !== 'string' || !CELL_ID_RE.test(id))) return null;
+    out.cells = cells;
+  } else if (out.cellVisibility === 'selected') {
+    out.cells = [];
+  }
   // Campo opzionale per compatibilita' con gli store 0.8.0: se assente, ssh
   // continua a usare la porta risolta da ~/.ssh/config o il default OpenSSH.
   if (n.sshPort !== undefined) out.sshPort = n.sshPort;
@@ -280,6 +322,38 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
     if (typeof n.nodeId !== 'string' || !NODE_ID_RE.test(n.nodeId)) return null;
     out.nodeId = n.nodeId;
   }
+  // Identita' del peer. Schema chiuso come il resto: una chiave malformata e'
+  // un record rifiutato, non una chiave "quasi buona" che qualcuno confrontera'
+  // piu' tardi credendola valida.
+  if (n.publicKey !== undefined) {
+    if (!identity.isPublicKey(n.publicKey)) return null;
+    out.publicKey = n.publicKey;
+  }
+  if (n.keySource !== undefined) {
+    // Solo due provenienze, perche' e' la distinzione che serve al passo 3.
+    // Un terzo valore inventato passerebbe i confronti e non significherebbe
+    // niente.
+    if (n.keySource !== 'pairing' && n.keySource !== 'peer-assertion') return null;
+    if (out.publicKey === undefined) return null; // provenienza senza chiave: incoerente
+    out.keySource = n.keySource;
+  }
+  if (n.keyBoundAt !== undefined) {
+    if (typeof n.keyBoundAt !== 'string' || Number.isNaN(Date.parse(n.keyBoundAt))) return null;
+    if (out.publicKey === undefined) return null;
+    out.keyBoundAt = n.keyBoundAt;
+  }
+  if (n.keyConflict !== undefined) {
+    const c = n.keyConflict;
+    if (!c || typeof c !== 'object' || Array.isArray(c)) return null;
+    for (const k of Object.keys(c)) { if (!KEY_CONFLICT_KEYS.has(k)) return null; }
+    if (!identity.isPublicKey(c.seen)) return null;
+    if (typeof c.at !== 'string' || Number.isNaN(Date.parse(c.at))) return null;
+    if (c.source !== 'pairing' && c.source !== 'peer-assertion') return null;
+    // Un conflitto senza chiave legata non e' un conflitto: e' la prima
+    // osservazione, e va scritta come tale.
+    if (out.publicKey === undefined) return null;
+    out.keyConflict = { seen: c.seen, at: c.at, source: c.source };
+  }
   if (label) out.label = label;
   return out;
 }
@@ -577,8 +651,23 @@ function redactNode(n) {
   };
   if (n.identityFile || n.keyPath) out.hasIdentity = true;
   if (n.visibility === 'selected') out.selected = [...(n.selected || [])];
+  // Lo scope celle non e' un segreto: e' una decisione dell'operatore e va
+  // mostrata, come `selected`. La Settings UI deve poterla leggere per dirla.
+  out.cellVisibility = n.cellVisibility || 'all';
+  if (out.cellVisibility === 'selected') out.cells = [...(n.cells || [])];
   if (n.sshPort !== undefined) out.sshPort = n.sshPort;
   if (n.nodeId) out.nodeId = n.nodeId;
+  // La pubblica di un peer NON e' un segreto: e' quella la cosa che va
+  // confrontata, e nasconderla renderebbe impossibile accorgersi di un
+  // conflitto guardando. Il conflitto viaggia con lei per la stessa ragione:
+  // se si vede la chiave ma non che ne e' arrivata un'altra, la vista
+  // rassicura invece di informare.
+  if (n.publicKey) {
+    out.publicKey = n.publicKey;
+    out.keySource = n.keySource || 'peer-assertion';
+    if (n.keyBoundAt) out.keyBoundAt = n.keyBoundAt;
+    if (n.keyConflict) out.keyConflict = { ...n.keyConflict };
+  }
   if (n.reversePool) {
     out.reversePool = {
       base: n.reversePool.base,

package/lib/notify/notifier.js

@@ -13,6 +13,13 @@ function createNotifier({ hub, push }) {
       urgency: frame.urgency === 'high' ? 'high' : 'normal',
       ...(frame.session ? { session: String(frame.session) } : {}),
       ...(frame.lang ? { lang: String(frame.lang) } : {}),
+      // Provenienza federata. `originNode` e' VERIFICATO (catena visited
+      // costruita dal server); `originCell` e' soltanto ATTESTATO dal nodo di
+      // origine, che l'ha verificata da se'. La differenza va fino alla UI: chi
+      // guarda deve poter distinguere cio' che e' provato da cio' che e'
+      // dichiarato, altrimenti il mittente diventa un campo di phishing.
+      ...(frame.originNode ? { originNode: String(frame.originNode) } : {}),
+      ...(frame.originCell ? { originCell: String(frame.originCell) } : {}),
       ts: Date.now(),
     });
     let pushed = 0;