@mmmbuto/nexuscrew 0.9.28 → 0.9.30

package/lib/server.js

@@ -29,8 +29,10 @@ const { cellsRoutes } = require('./cells/routes.js');
 const { liveHostRoutes } = require('./live-host/routes.js');
 const { createLiveHostStore, liveHostPath } = require('./live-host/store.js');
 const { createLiveBridge } = require('./live-host/bridge.js');
+const { createLiveHostFederation } = require('./live-host/federation.js');
 const { fsRoutes } = require('./fs/routes.js');
 const nodesStore = require('./nodes/store.js');
+const accessPresets = require('./nodes/access-presets.js');
 const nodesTunnel = require('./nodes/tunnel.js');
 const nodesHealth = require('./nodes/health.js');
 const { recordPeerTransition } = require('./nodes/peer-transitions.js');
@@ -66,8 +68,25 @@ const decksStore = require('./decks/store.js');
 const { decksRoutes } = require('./decks/routes.js');
 const { createEventsHub } = require('./notify/events.js');
 const { createPushService } = require('./notify/push.js');
+const { createPushRelay, createPushDedup } = require('./notify/push-relay.js');
 const { createAsksStore } = require('./notify/asks.js');
 const { createNotifier } = require('./notify/notifier.js');
+const { createEventFeed } = require('./notify/event-feed.js');
+const { createEventFeedHistory } = require('./notify/event-feed-history.js');
+const { buildEnvelope } = require('./notify/event-feed-producers.js');
+const { createEventFeedRoutes } = require('./notify/event-feed-routes.js');
+const eventFeedAcl = require('./notify/event-feed-acl.js');
+const { createEventFeedClient } = require('./notify/event-feed-client.js');
+const { createAskReceipts } = require('./notify/ask-receipts.js');
+const { createAskAnswerService } = require('./notify/ask-answer-service.js');
+const { createEventFeedAsksRoutes } = require('./notify/event-feed-asks-routes.js');
+const { createAskRelay } = require('./notify/ask-relay.js');
+const { readFederationEventsEnabled } = require('./config.js');
+
+function sanitizeReplyLabel(raw) {
+  return String(raw === undefined || raw === null ? 'human' : raw)
+    .replace(/[\x00-\x1f\x7f\]]/g, '').slice(0, 32) || 'human';
+}
 const { notifyRoutes } = require('./notify/routes.js');
 const { createNpmUpdater } = require('./update/manager.js');
 const { createDiagnostics } = require('./diagnostics/store.js');
@@ -104,7 +123,7 @@ function createServer(opts = {}) {
   };
   const proxySockets = new Set();
   // wss viene creato piu' sotto; closeSessions lo raggiunge a request-time (mai durante
-  // createServer) per chiudere le sessioni WS attive sulla rotazione token (§4b(3)).
+  // createServer) to close active WS sessions on token rotation.
   let wss = null;
   const ptyGrace = createPtyGraceStore({
     graceMs: cfg.ptyGraceMs,
@@ -144,8 +163,166 @@ function createServer(opts = {}) {
     dir: notifyDir, webpushImpl: cfg.webpushImpl,
     readonly: bridgeReadonly, maxSubs: cfg.pushMaxSubs, lookupImpl: cfg.pushLookupImpl,
   });
+  // OS alerts for IMPORTED notifications: the same push service (endpoint/DNS/
+  // SSRF checks, 404/410 cleanup, READONLY floor) with its OWN queue, its own
+  // alert budget and a durable (owner, eventId) registry — an event already
+  // alerted never rings twice, across a replay or a restart. It is fed only by
+  // the import hub below, so a local emission never takes this path.
+  const pushRelay = createPushRelay({
+    pushDedup: createPushDedup({ filePath: path.join(notifyDir, 'push-relay-dedup.json') }),
+    send: (payload) => pushSvc.sendToAll(payload),
+    log: opts.log || console.log,
+  });
   const asksStore = createAsksStore({ dir: notifyDir });
-  const notifier = createNotifier({ hub: eventsHub, push: pushSvc });
+  // --- Event feed (owner side) -------------------------------------------------
+  // The notifier stays the single emission point; the feed is a SIDE EFFECT of
+  // a local emission, never a separate path. Federated ingress and feed import
+  // call deliverOnly(): local delivery that does NOT re-enter the publisher —
+  // an imported event can never be re-exported, so A→B→A dies by construction.
+  const notifierBase = createNotifier({ hub: eventsHub, push: pushSvc });
+  const feedHistory = createEventFeedHistory({
+    filePath: path.join(notifyDir, 'event-feed-history.json'),
+  });
+  // Kill switch: strict boolean, read FRESH on every use so flipping it in
+  // config.json acts on live streams without a restart.
+  const eventsEnabled = () => readFederationEventsEnabled({ configJsonPath: cfg.configPath, federationEventsEnabled: cfg.federationEventsEnabled });
+  const eventFeed = createEventFeed({
+    log: opts.log || console.log,
+    // A heartbeat is also a revoke checkpoint: grants re-read without events.
+    validatePeer: (peerNodeId) => {
+      if (eventsEnabled() !== true) return false;
+      const st = nodesStore.loadStore(nodesPath);
+      const grants = st ? eventFeedAcl.peerGrants(st, peerNodeId) : null;
+      return !!(grants && grants.configured && grants.eventsAccess === true);
+    },
+  });
+  // Durable receipts + the ONE answer cycle shared by the local route and the
+  // federated ask surface. The closure event flows through the notifier
+  // wrapper so the feed gets a qualified ask-closed envelope.
+  const askReceipts = createAskReceipts({ filePath: path.join(notifyDir, 'ask-receipts.json') });
+  const askAnswerService = createAskAnswerService({
+    asks: asksStore,
+    paste: cfg.pasteSeam || ((session, text) => pasteToSession(cfg.tmuxBin, session, text)),
+    receipts: askReceipts,
+    onClosure: (kind, info) => { try { notifier.emitRaw({ type: kind, id: info.askId }); } catch (_) {} },
+    labelPrefix: sanitizeReplyLabel(cfg && cfg.replyLabel),
+  });
+  const feedSignatures = new Map(); // peerNodeId -> grant signature last seen
+  const apiOwnerId = () => (nodesStore.loadStore(nodesPath) || {}).nodeId || null;
+
+  function publishEnvelopeToPeers(envelope) {
+    if (eventsEnabled() !== true) {
+      eventFeed.invalidateAll('events-disabled');
+      return;
+    }
+    const store = nodesStore.loadStore(nodesPath);
+    if (!store) return;
+    for (const node of store.nodes) {
+      if (!node || node.direction !== 'inbound' || !node.nodeId) continue;
+      const grants = eventFeedAcl.peerGrants(store, node.nodeId);
+      const usable = grants && grants.configured && grants.eventsAccess === true;
+      if (!usable) {
+        // Lost the grants: the view dies BEFORE anything else is served.
+        if (eventFeed.status(node.nodeId)) {
+          eventFeed.invalidatePeer(node.nodeId, 'revoked');
+          eventFeed.disablePeer(node.nodeId);
+          feedSignatures.delete(node.nodeId);
+        }
+        continue;
+      }
+      const seen = feedSignatures.get(node.nodeId);
+      if (seen !== undefined && seen !== grants.signature) {
+        eventFeed.invalidatePeer(node.nodeId, 'grants-changed');
+      }
+      feedSignatures.set(node.nodeId, grants.signature);
+      if (!eventFeedAcl.allowsEnvelope(grants, envelope)) continue;
+      // Per-peer projection BEFORE the ring: a node frame may carry cell
+      // lists, and a hidden cell never reaches the peer's view in any form
+      // (no names, no counts) — node events do not bypass cell visibility.
+      let projected = envelope;
+      if (envelope.scope === 'node' && Array.isArray(envelope.frame && envelope.frame.cells)) {
+        projected = {
+          ...envelope,
+          frame: { ...envelope.frame, cells: eventFeedAcl.projectCells(grants, envelope.frame.cells) },
+        };
+      }
+      try {
+        if (!eventFeed.status(node.nodeId)) eventFeed.enablePeer(node.nodeId);
+        eventFeed.publish(node.nodeId, projected);
+      } catch (_) { /* one peer's budget never blocks the others */ }
+    }
+  }
+
+  // Local emission → envelope + durable history + per-peer publication.
+  function recordAndPublish({ producer, cellId, payload }) {
+    const ownerId = apiOwnerId();
+    if (!ownerId) return null;
+    let envelope;
+    try {
+      envelope = buildEnvelope({ type: producer, payload, ownerId, cellId, now: Date.now });
+    } catch (e) {
+      try { diagnostics.record('warn', 'notify', 'EVENT_FEED_PRODUCER_REFUSED', String(e.message || e), { producer }); } catch (_) {}
+      return null;
+    }
+    try { feedHistory.record(envelope); } catch (_) { /* history degrades, notify still lives */ }
+    publishEnvelopeToPeers(envelope);
+    return envelope;
+  }
+
+  function cellIdForFrame(frame) {
+    try { return cellIdFromTmuxSession(frame && frame.session); } catch (_) { return null; }
+  }
+
+  const notifier = {
+    // Local emission: UI + push + feed. `federated: true` is an INTERNAL flag
+    // of the caller, never a body field — a remote notify cannot ask to be
+    // treated as local.
+    async emit(frame, opts = {}) {
+      const result = await notifierBase.emit(frame);
+      if (opts.federated !== true) {
+        const cellId = cellIdForFrame(frame);
+        recordAndPublish({
+          producer: cellId ? 'notify' : 'notify-node',
+          cellId,
+          payload: { ...frame, ts: Date.now() },
+        });
+      }
+      return result;
+    },
+    // Raw UI frames: ask cards and their closures carry the ask id into the
+    // feed so both sides see the same object.
+    emitRaw(frame) {
+      const out = notifierBase.emitRaw(frame);
+      try {
+        if (frame && frame.type === 'ask' && frame.ask) {
+          const ask = frame.ask;
+          const cellId = cellIdFromTmuxSession(ask.session);
+          if (cellId) {
+            recordAndPublish({
+              producer: 'ask', cellId,
+              payload: { askId: ask.id, revision: ask.revision || 0, question: ask.question, options: ask.options, session: ask.session, ts: Date.now() },
+            });
+          }
+        } else if (frame && (frame.type === 'ask-answered' || frame.type === 'ask-dismissed')) {
+          const all = asksStore.list({ open: false }).concat(asksStore.list({ open: true }));
+          const ask = all.find((a) => a && a.id === frame.id);
+          const cellId = ask ? cellIdFromTmuxSession(ask.session) : null;
+          if (cellId) {
+            recordAndPublish({
+              producer: 'ask-closed', cellId,
+              payload: { askId: frame.id, revision: (ask && ask.revision) || 0, outcome: frame.type === 'ask-dismissed' ? 'dismissed' : 'answered', ts: Date.now() },
+            });
+          }
+        }
+      } catch (_) { /* the local raw frame must not fail because of the feed */ }
+      return out;
+    },
+    // Delivery-only: federated ingress and feed import land here. NO history,
+    // NO publisher — an imported event is never re-exported.
+    async deliverOnly(frame) { return notifierBase.emit(frame); },
+    deliverOnlyRaw(frame) { return notifierBase.emitRaw(frame); },
+    publishState: (producer, payload) => recordAndPublish({ producer, cellId: null, payload }),
+  };
   const diagnostics = opts.diagnostics || createDiagnostics();
   // Contatore cadute WS (rolling 10 min): alimenta i meta dei log di bridge.
   const wsDropCounter = createDropCounter();
@@ -171,7 +348,7 @@ function createServer(opts = {}) {
   const identityOwnerInstanceId = () => (nodesStore.loadStore(nodesPath) || {}).nodeId || null;
   const fleetP = selectProvider({ ...cfg, ensureTmuxProtection, identityOwnerInstanceId }).then((p) => p.fleet);
 
-  // Multi-node (B1): nodes.json e' la fonte dati (B0). Il proxy risolve <name>
+  // Multi-node: nodes.json e' la fonte dati. Il proxy risolve <name>
   // -> {localPort, token} leggendo lo store ad ogni richiesta (fresh: rotazione
   // token / add-remove nodi visibili senza restart). token MAI redatto qui: e'
   // il valore che il proxy inietta upstream, non esce mai verso il browser.
@@ -545,7 +722,7 @@ function createServer(opts = {}) {
   }
 
   const app = express();
-  // CSP frame-ancestors (P0 sicurezza 2026-08-16, rimedio 4 del report): la
+  // CSP frame-ancestors (sicurezza 2026-08-16, rimedio 4 del report): la
   // pagina dell'app non deve poter essere incorporata in un iframe altrui —
   // clickjacking sul control plane. Ortogonale alla porta pannello: quello
   // difende CHI E' NEL FRAME, questo difende l'app dall'ESSERE il frame.
@@ -641,7 +818,7 @@ function createServer(opts = {}) {
       cell: entry.cell, reason: entry.reason, state: entry.outcome,
     }),
   }));
-  // Porta pannello dedicata (P0 sicurezza 2026-08-16): un iframe
+  // Porta pannello dedicata (sicurezza 2026-08-16): un iframe
   // same-origin senza sandbox legge il localStorage del padre — il JS di un
   // pannello ostile puo' prendersi il token e agire come l'operatore. La
   // porta fa parte dell'origin: spostando SOLO il consumo (ticket in query,
@@ -845,8 +1022,8 @@ function createServer(opts = {}) {
     instanceId: apiNodeId,
     identityMode,
   }));
-  // MCP bridge (design §2): /notify, /push/*, /asks — dietro lo stesso Bearer
-  // del router /api; gate READONLY sui mutanti dentro notifyRoutes.
+  // MCP bridge: /notify, /push/*, /asks — behind the same Bearer
+  // of the /api router; READONLY gate on the mutators inside notifyRoutes.
   // Identita' e instradamento condivisi con l'audio: stessa fonte (node store),
   // stesso segreto di hop, stessa inventory. Due modelli di provenienza
   // divergenti sarebbero un bug latente.
@@ -865,8 +1042,9 @@ function createServer(opts = {}) {
     notifier,
     push: pushSvc,
     asks: asksStore,
-    paste: (session, text) => pasteToSession(cfg.tmuxBin, session, text),
-    sessionExists: (name) => sessionExists(cfg.tmuxBin, name),
+    paste: cfg.pasteSeam || ((session, text) => pasteToSession(cfg.tmuxBin, session, text)),
+    // Stesso seam dell'attach: i test non devono parlare con tmux vero.
+    sessionExists: cfg.sessionExistsSeam || ((name) => sessionExists(cfg.tmuxBin, name)),
     fleetP,
     instanceId: apiNodeId,
     identityMode,
@@ -883,16 +1061,156 @@ function createServer(opts = {}) {
       peers: federatedPeers,
       localPort: () => (server && server.address() ? server.address().port : cfg.port),
       localToken: () => tokenHolder.value,
-      // 'no-delivery' (R31-A3): esito legittimo del target — richiesta accettata
+      // 'no-delivery' (-): esito legittimo del target — richiesta accettata
       // ma nessun canale raggiunto (0 UI, 0 push). Senza questa voce forward()
       // lo degraderebbe a 'unknown/unreadable-endpoint-result', nascondendo
       // proprio il silenzio che l'esito esiste per rivelare.
       statuses: new Set(['delivered', 'no-delivery', 'refused', 'unreachable', 'unknown']),
     }),
     federatedRate: createSpeakRateLimiter(),
+    answerService: askAnswerService,
+    receipts: askReceipts,
+  }));
+  // Event feed: the closed SSE/JSON surface, mounted inside the
+  // authenticated API. Its own gate demands a proven federated origin and an
+  // exact two-hop chain — there is no local fallback.
+  api.use('/event-feed/asks', createEventFeedAsksRoutes({
+    nodesPath,
+    localNodeId: federatedNodeId,
+    originResolver: createOriginResolver({
+      localNodeId: federatedNodeId,
+      hopSecret: () => hopSecret,
+    }),
+    eventsEnabled,
+    asks: asksStore,
+    answerService: askAnswerService,
+    receipts: askReceipts,
+    cellForSession: (session) => cellIdFromTmuxSession(session),
+    readonly: proxyReadonly,
   }));
-  api.use('/fleet', fleetRoutes(fleetP, { ...cfg, diagnostics }));
-  // Fetta 2b (D3): superficie child del lease Live via canale nativo del
+  api.use('/event-feed', createEventFeedRoutes({
+    nodesPath,
+    localNodeId: federatedNodeId,
+    originResolver: createOriginResolver({
+      localNodeId: federatedNodeId,
+      hopSecret: () => hopSecret,
+    }),
+    eventFeed,
+    history: feedHistory,
+    asksStore,
+    fleetP,
+    cellForSession: (session) => cellIdFromTmuxSession(session),
+    eventsEnabled,
+  }));
+  // Client-side subscriber: for every outbound peer the
+  // operator flagged eventsReceive, pull the owner's feed (snapshot first),
+  // re-emit imported events LOCALLY with owner attribution. Imports never
+  // touch the notifier wrapper, so a client never re-exports what it imports.
+  // Ask relay (federated asks, client side): the PWA posts here, the relay
+  // resolves the owner from the authorized store and forwards with the peer's
+  // own pair token. Uncertain outcomes are parked, never retried silently.
+  const askRelay = createAskRelay({
+    loadStore: () => nodesStore.loadStore(nodesPath),
+    log: opts.log || console.log,
+  });
+  api.post('/asks-relay', async (req, res) => {
+    try {
+      const b = req.body || {};
+      if (b.action === 'dismiss') {
+        const out = await askRelay.relayDismiss({ ownerId: b.ownerId, askId: b.askId });
+        return res.status(out.ok ? 200 : out.code || 500).json(out.ok ? { dismissed: true } : { error: out.error || 'unknown' });
+      }
+      if (b.action === 'verify') {
+        const out = await askRelay.verifyStatus({ ownerId: b.ownerId, askId: b.askId, requestId: b.requestId });
+        return res.status(out.ok ? 200 : out.code || 500).json(out.ok ? { state: out.state } : { error: out.error || 'unknown', reason: out.reason });
+      }
+      const out = await askRelay.relayAnswer({ ownerId: b.ownerId, askId: b.askId, text: b.text });
+      return res.status(out.ok ? 200 : out.code || 500).json({
+        ...(out.ok ? { status: out.status } : {}),
+        requestId: out.requestId || b.requestId,
+        ...(out.uncertain ? { uncertain: true, reason: out.reason } : {}),
+        ...(!out.ok && !out.uncertain ? { error: out.error, reason: out.reason } : {}),
+      });
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+  // The client re-emits imported events into the local hub (deliverOnly: the
+  // notifier is bypassed on purpose). The alert relay hangs off that same call,
+  // so ONLY an imported notify can ring this device, and never through the
+  // owner-side publisher. READONLY keeps the relay off: its registry is a
+  // durable write.
+  const importHub = {
+    broadcast: (event) => {
+      eventsHub.broadcast(event);
+      if (!bridgeReadonly()) pushRelay.considerImported(event);
+    },
+  };
+  const eventFeedClient = createEventFeedClient({
+    loadStore: () => nodesStore.loadStore(nodesPath),
+    token: () => tokenHolder.value,
+    eventsHub: importHub,
+    log: opts.log || console.log,
+    pollMs: cfg.eventFeedClientPollMs,
+  });
+  eventFeedClient.start();
+  // Local aggregated read for the UI: connected views only, with the cursor
+  // watermark so the first fetch cannot race the live stream. Local
+  // authenticated route, NOT in the federation allowlist.
+  api.get('/feed-state', (_req, res) => {
+    try { res.json(eventFeedClient.state()); }
+    catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+
+  // Local, authenticated observability for the feed (doctor / nodes show feed
+  // it). Deliberately NOT in the federation allowlist: diagnostics stay local.
+  api.get('/diagnostics/events', (_req, res) => {
+    try {
+      // Read-only alert-relay counters for the peers the operator is looking
+      // at: numbers and reasons only — never an endpoint, a subscription or a
+      // key, and nothing here opens a connection anywhere.
+      const relayStatus = pushRelay.status();
+      const pushRelaySection = {
+        global: { ...relayStatus.counters, queued: relayStatus.queued, active: relayStatus.active },
+        byOwner: relayStatus.byOwner,
+      };
+      const store = nodesStore.loadStore(nodesPath);
+      const peers = [];
+      if (store) {
+        for (const node of store.nodes) {
+          if (!node || node.direction !== 'inbound' || !node.nodeId) continue;
+          const grants = eventFeedAcl.peerGrants(store, node.nodeId);
+          peers.push({
+            name: node.name,
+            nodeId: node.nodeId,
+            accessLabel: grants ? grants.label : 'unknown',
+            grants: grants ? {
+              eventsAccess: grants.eventsAccess,
+              nodeEventsAccess: grants.nodeEventsAccess,
+              cellVisibility: grants.cellVisibility,
+              cells: grants.cells,
+              configured: grants.configured,
+            } : null,
+            accessRevision: nodesStore.accessRevisionOf(store),
+            feed: eventFeed.status(node.nodeId),
+          });
+        }
+      }
+      res.json({ enabled: eventsEnabled(), peers, pushRelay: pushRelaySection });
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+  api.use('/fleet', fleetRoutes(fleetP, {
+    ...cfg, diagnostics,
+    // Fleet state changes are events too: the owner resolves the cell and
+    // publishes the normalized delta; grants are applied per peer on publish.
+    onFleetStateChange: (delta) => {
+      try {
+        notifier.publishState('fleet-state', {
+          cells: [{ cell: delta && delta.cell, active: delta && delta.active === true }],
+          ts: Date.now(),
+        });
+      } catch (_) { /* observability must never break the action */ }
+    },
+  }));
+  // Fetta 2b: superficie child del lease Live via canale nativo del
   // bridge (HTTP loopback + Bearer). La cella e' derivata dalla sessione; il
   // proof firmato dal verifier per-installazione autorizza refresh/recovery.
   api.use('/lease', leaseRoutes({
@@ -972,16 +1290,20 @@ function createServer(opts = {}) {
     })),
     readonly: proxyReadonly,
   }));
-  // Cella ospite Live (contratto rev6 §2): hostCell unico per nodo con CAS. Lo store
-  // vive accanto al token (stessa dir isolata nei test); il proxy nega /api/live-host
-  // via /node (local-only), ma la via /api/route la instrada (0.9.1) dietro un
-  // permesso per-peer negato di default (liveHostAccess, v. lib/proxy/federation.js).
+  // Live host cell: one hostCell per node with CAS. The store
+  // lives next to the token (same isolated dir in tests); the proxy refuses
+  // /api/live-host via /node (local-only), but the /api/route path routes it
+  // behind a per-peer permission denied by default (liveHostAccess).
   // Fetta 3: il ponte risolve il puntamento all'avvio di una Live (POST /bridge
   // nello stesso gruppo, stessa auth, stesso local-only). Isolabile da cfg
-  // (rev5 MC0): spento non crea connessioni e la Live resta standard.
+  // (rev5): spento non crea connessioni e la Live resta standard.
+  // One store instance serves both sides of a remote designation: the routes
+  // (owner side) and the forwarder that records the pointer to a peer (client
+  // side). Two instances over the same file would work, one is honest.
+  const liveHostStore = createLiveHostStore({ filePath: liveHostPath(cfg) });
   api.use('/live-host', liveHostRoutes({
     fleetP,
-    store: createLiveHostStore({ filePath: liveHostPath(cfg) }),
+    store: liveHostStore,
     readonly: proxyReadonly,
     bridge: createLiveBridge({
       cfg,
@@ -990,6 +1312,18 @@ function createServer(opts = {}) {
       filesRoot: cfg.filesRoot,
       log: opts.log || console.log,
     }),
+    // Client side: read the owner's state and forward the bridge resolution to
+    // the node the designation points at. Owner side: accept a forwarded
+    // resolution behind the same per-peer gate and the same rate limiting as
+    // the other federated routes.
+    federation: createLiveHostFederation({
+      localNodeId: federatedNodeId,
+      peers: federatedPeers,
+      localPort: () => (server && server.address() ? server.address().port : cfg.port),
+      localToken: () => tokenHolder.value,
+    }),
+    originResolver: createOriginResolver({ localNodeId: federatedNodeId, hopSecret: () => hopSecret }),
+    federatedRate: createSpeakRateLimiter(),
   }));
   // Pannello per-cella: montato con il suo ingresso dedicato (ticket+cookie)
   // PRIMA del requireToken generale — vedi il blocco sopra, dove nascono
@@ -999,7 +1333,7 @@ function createServer(opts = {}) {
   }));
   api.use('/decks', decksRoutes({ cfg, decksPath }));
   api.use('/fs', fsRoutes({ home: os.homedir() }));  // folder-picker del dialog new session
-  // /nodes (read-only, per la settings UI B2): stesso formato di `nodes list --json`
+  // /nodes (read-only, per la settings UI): stesso formato di `nodes list --json`
   // (token SEMPRE redatti via redactStore) + health federato per-nodo. Il campo
   // `tunnel` resta per retro-compatibilita' col frontend (derivato dal health).
   //   health = { transport, auth, reachability, status, detail, managed, at }
@@ -1021,9 +1355,16 @@ function createServer(opts = {}) {
         // (lib/nodes/peer-transitions.js) — nessun probe in piu', nessun
         // record se il peer resta invariato.
         recordPeerTransition(n.name, h, diagnostics);
-        return { ...n, tunnel: nodesHealth.tunnelFromHealth(h), health: h };
+        // Federated access read view: derived label,
+        // configured marker and the effective grant vector. `view.nodes[i]`
+        // is the redacted twin of `st.nodes[i]` (same order, redaction keeps
+        // tokens out), while grants are decisions, not secrets, so they are
+        // derived from the raw record and never contain a credential.
+        return { ...n, tunnel: nodesHealth.tunnelFromHealth(h), health: h, ...accessPresets.accessView(st.nodes[i]) };
       });
-      res.json({ nodeId: view.nodeId, nodes });
+      // Store-root revision of the peer access policy: the CAS value the UI
+      // must send back with every preset write (stale revision -> 409).
+      res.json({ nodeId: view.nodeId, nodes, accessRevision: nodesStore.accessRevisionOf(st) });
     } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
   });
   // Canonical management inventory: direct hubs/clients plus routed peers.  The
@@ -1033,7 +1374,13 @@ function createServer(opts = {}) {
     try {
       const st = nodesStore.loadStore(nodesPath);
       if (!st) return res.json({ nodeId: null, peers: [] });
-      const direct = nodesStore.redactStore(st).nodes;
+      // Same access read view as /api/nodes: the settings UI consumes this
+      // endpoint, so direct peers carry the derived label, the configured
+      // marker and the effective grants here too (the inventory spreads the
+      // record as-is). No duplication: one helper, two endpoints.
+      const direct = nodesStore.redactStore(st).nodes.map(
+        (n, i) => ({ ...n, ...accessPresets.accessView(st.nodes[i]) }),
+      );
       const healths = await nodesHealth.nodesHealth({
         nodes: st.nodes, home: cfg.home || os.homedir(), fetchImpl: healthFetch, now: Date.now(),
         failureThreshold: cfg.nodeHealthFailureThreshold,
@@ -1054,12 +1401,12 @@ function createServer(opts = {}) {
         topology: topology && Array.isArray(topology.nodes) ? topology.nodes : [],
         extras,
       });
-      res.json({ nodeId: st.nodeId, peers });
+      res.json({ nodeId: st.nodeId, peers, accessRevision: nodesStore.accessRevisionOf(st) });
     } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
   });
-  // Settings API B2 (design §4b(6)): read-only GET + mutanti lista chiusa per il
-  // wizard/settings UI. Dietro lo stesso requireToken del router /api; il gate
-  // READONLY route-level e la redazione token vivono dentro settingsRoutes.
+  // Settings API: read-only GET + a closed list of mutators for the
+  // wizard/settings UI. Behind the same requireToken of the /api router; the
+  // route-level READONLY gate and token redaction live inside settingsRoutes.
   api.use('/settings', settingsRoutes({
     cfg, nodesPath, tokenStore, closeSessions, updater, runtimePort,
     // Stesso adapter/coda dell'API Audio: Settings puo' fare solo la prova
@@ -1075,6 +1422,12 @@ function createServer(opts = {}) {
   api.use('/route', federation.localRouter({
     nodesPath, localPort: () => (server && server.address() ? server.address().port : cfg.port), localCredential: () => tokenHolder.value, readonly: proxyReadonly,
     hopSecret: () => hopSecret,
+    // A designation forwarded from here to a peer is recorded by the answer
+    // the peer gives, not by a local guess: see liveHostLedgerCapture.
+    liveHostLedger: {
+      recordRemote: (entry) => liveHostStore.setRemoteDesignation(entry),
+      clearRemote: (ownerId) => liveHostStore.clearForOwner(ownerId),
+    },
   }));
   api.get('/voice/status', (_req, res) => res.json({ serverSttConfigured: !!cfg.voiceUrl }));
   api.post('/voice/transcribe',
@@ -1085,10 +1438,10 @@ function createServer(opts = {}) {
         res.json({ text: out.text || '' });
       } catch (e) { res.status(e.status || 502).json({ error: e.message }); }
     });
-  // SSE eventi UI (notify/ask, MCP bridge §2a): EventSource non puo' settare
-  // header -> il token e' accettato anche in query, SOLO perche' il bind e'
-  // loopback-only (stesso pattern dell'upgrade WS del proxy /node). Montata
-  // PRIMA del router /api (che e' Bearer-only) e sempre sul token live.
+  // SSE UI events (notify/ask, MCP bridge): EventSource cannot set
+  // headers -> the token is accepted in query too, ONLY because the bind is
+  // loopback-only (same pattern as the /node proxy WS upgrade). Mounted
+  // BEFORE the /api router (which is Bearer-only) and always on the live token.
   app.get('/api/events', (req, res) => {
     const given = bearerFrom(req) || String(req.query.token || '');
     if (!verify(tokenHolder.value, given)) {
@@ -1105,16 +1458,16 @@ function createServer(opts = {}) {
     diagnostics,
   }));
 
-  // Reverse-proxy single-origin /node/<name>/… (design §4b(2)). Auth locale PRIMA
-  // di risolvere <name>: requireToken(token) davanti al router, nessuna route
-  // proxy montata prima del middleware auth. Montato PRIMA dello static/catch-all.
+  // Single-origin reverse proxy for /node/<name>/… . Local auth FIRST
+  // before resolving <name>: requireToken(token) in front of the router, no proxy
+  // route mounted before the auth middleware. Mounted BEFORE the static/catch-all.
   app.use('/node', requireToken(tokenStore), createNodeProxy({ resolveNode, readonly: proxyReadonly }));
 
   app.use(express.static(distDir));
-  // Deck multi-finestra (§5b): /deck/<name> serve la STESSA SPA (stesso origin,
-  // stesso token via fragment). <name> e' una chiave strict client-side, mai usata
-  // per costruire path: validazione ^[a-z0-9-]{1,32}$, nome invalido → 404 secco
-  // (niente traversal, niente fallback silenzioso alla SPA su nomi sporchi).
+  // Multi-window deck: /deck/<name> serves the SAME SPA (same origin,
+  // same token via fragment). <name> is a strict client-side key, never used
+  // to build paths: validation ^[a-z0-9-]{1,32}$, invalid name -> hard 404
+  // (no traversal, no silent SPA fallback on dirty names).
   const DECK_NAME_RE = /^[a-z0-9-]{1,32}$/;
   const DECK_OWNER_RE = /^[a-f0-9]{16,64}$/;
   // Cattura TUTTO cio' che sta sotto /deck/ (anche slash/segmenti extra o encoded)
@@ -1238,9 +1591,9 @@ function createServer(opts = {}) {
   wss.on('connection', (ws, req) => {
     ws.isAlive = true;
     ws.on('pong', () => { ws.isAlive = true; });
-    // Preauth via header (B2 attach remoto): quando l'upgrade arriva dal proxy
+    // Preauth via header (attach remoto): quando l'upgrade arriva dal proxy
     // /node/<name> di un hub, il proxy ha gia' iniettato `Authorization: Bearer
-    // <token di QUESTO nodo>` (§4b(2)#3) mentre il frame attach porta il token
+    // of THIS node> while the attach frame carries the token
     // del hub. Un Bearer valido sull'upgrade vale come auth: e' lo STESSO
     // verify dello stesso token locale, solo su un canale diverso. I browser
     // non possono settare header sui WS -> il flusso locale resta identico
@@ -1285,6 +1638,9 @@ function createServer(opts = {}) {
   return {
     app, server, wss, cfg, token: tokenHolder.value, tokenStore, watcher, fleetP, updater, diagnostics,
     panelApp, panelServer, panelServerV6,
+    // Test/observability seam: publish a normalized state event through the
+    // same per-peer projection the local producers use.
+    notify: { publishState: notifier.publishState },
   };
 }
 
@@ -1298,7 +1654,7 @@ function start(opts = {}) {
     if (typeof opts.onListenError === 'function') return opts.onListenError(error);
     throw error;
   };
-  // Porta pannello (P0 sicurezza 2026-08-16): scelta libera con lo STESSO
+  // Porta pannello (sicurezza 2026-08-16): scelta libera con lo STESSO
   // meccanismo di fallback della principale, ma piu' leggero — nessun peer
   // dipende ancora da un valore stabile persistito (a differenza di cfg.port,
   // che i tunnel pairati referenziano), quindi niente scrittura su

package/lib/settings/pairing-coordinator.js

@@ -302,7 +302,7 @@ function createPairHandler(deps) {
       // reversePort resta negoziata per un futuro Share opt-in, ma il builder
       // non emette -R finche' shared non diventa true.
       //
-      // Porta pannello del peer (P0 stessa-origin, meta' remota): se il peer
+      // Porta pannello del peer (stessa-origin, meta' remota): se il peer
       // l'ha annunciata nel join, si riserva una controparte locale e la
       // coppia entra nel record — il supervisor finale inoltrera' entrambe.
       // Nessuna porta disponibile NON fa fallire il pairing: il pannello e