@mmmbuto/nexuscrew 0.9.29 → 0.9.31

package/lib/nodes/commands.js

@@ -19,6 +19,7 @@ const tunnel = require('./tunnel.js');
 const reversePool = require('./reverse-pool.js');
 const topologyCache = require('./topology-cache.js');
 const inventory = require('./inventory.js');
+const accessPresets = require('./access-presets.js');
 const federation = require('../proxy/federation.js');
 const { resolvePaths, DEFAULT_PORT } = require('../cli/url.js');
 
@@ -248,6 +249,63 @@ function nodesList(opts) {
   return { code: 0, nodes, peers: visiblePeers };
 }
 
+// --- Event feed observability -------------------------------------------------
+// Best-effort LOCAL read of the running server's feed diagnostics. The CLI
+// never reads runtime files for this: if the local server is unreachable it
+// says so explicitly instead of reporting zero deliveries.
+// One line for the OS alert relay of that peer: same local diagnostics payload,
+// counters and last reason only. A peer nobody tried to alert stays honest with
+// zeros instead of disappearing.
+function relayLineFor(body, peerNodeId) {
+  const section = (body && body.pushRelay) || {};
+  const own = (section.byOwner && section.byOwner[peerNodeId]) || {};
+  const last = own.lastReason ? ` · ultimo motivo ${own.lastReason}` : '';
+  return `relay:     avvisi OS in coda ${own.queued || 0} · inviati ${own.pushed || 0} · scartati ${own.dropped || 0} · errori ${own.sendFailed || 0}${last}`;
+}
+
+function feedLinesFor(diag, peerNodeId) {
+  if (!diag || diag.ok !== true) {
+    return [`feed:      diagnostica non disponibile (${(diag && diag.reason) || 'sconosciuto'}) — il server locale non risponde`];
+  }
+  const entry = (diag.body && Array.isArray(diag.body.peers) ? diag.body.peers : [])
+    .find((p) => p.nodeId === peerNodeId);
+  if (!entry) return ['feed:      nessuna vista per questo peer'];
+  const enabled = diag.body.enabled === true;
+  const counters = (entry.feed && entry.feed.counters) || {};
+  const lastProblem = (entry.feed && (entry.feed.lastDropReason || entry.feed.lastRejectReason)) || 'none';
+  const grants = entry.grants || {};
+  return [
+    // The kill-switch state is its OWN line: it is the operator's first
+    // question when the feed is silent.
+    `feed:      kill-switch ${enabled ? 'attivo (feed abilitato)' : 'OFF: feed disabilitato'} · revision ${entry.accessRevision} · label ${entry.accessLabel}`,
+    `feed:      grant events=${grants.eventsAccess === true ? 'on' : 'off'} node-events=${grants.nodeEventsAccess === true ? 'on' : 'off'} · scope celle ${grants.cellVisibility || 'none'}${Array.isArray(grants.cells) && grants.cells.length ? ` (${grants.cells.join(', ')})` : ''}`,
+    `feed:      cursore ${(entry.feed && entry.feed.lastCursor) || '-'} · stream ${(entry.feed && entry.feed.streams) || 0} · ultimo mancato: ${lastProblem}`,
+    `feed:      contatori delivered ${(counters.delivered || 0)} · dropped ${(counters.dropped || 0)} · replayed ${(counters.replayed || 0)} · rejected ${(counters.rejected || 0)}`,
+    relayLineFor(diag.body, peerNodeId),
+  ];
+}
+
+async function fetchFeedDiagnostics(opts = {}) {
+  let port = Number(opts.localAppPort) || null;
+  if (!port && opts.configPath) {
+    try { port = Number(JSON.parse(fs.readFileSync(opts.configPath, 'utf8')).port) || null; } catch (_) { port = null; }
+  }
+  let token = '';
+  try { token = fs.readFileSync(opts.tokenPath, 'utf8').trim(); } catch (_) { return { ok: false, reason: 'no-token' }; }
+  if (!port) return { ok: false, reason: 'no-port' };
+  try {
+    // The local diagnostics live under the authenticated API mount: without
+    // the /api prefix the CLI would read the static handler and report the
+    // server as unreachable while it is answering fine.
+    const r = await (opts.fetchImpl || fetch)(`http://127.0.0.1:${port}/api/diagnostics/events`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(1500),
+    });
+    if (!r.ok) return { ok: false, reason: `http-${r.status}` };
+    return { ok: true, body: await r.json() };
+  } catch (_) { return { ok: false, reason: 'unreachable' }; }
+}
+
 function nodesInspect(opts) {
   const log = opts.log || console.log;
   const out = loadPeerInventory(opts);
@@ -273,11 +331,46 @@ function nodesInspect(opts) {
       const cells = Array.isArray(peer.cells) ? peer.cells : [];
       log(`celle:     ${cells.length ? cells.join(', ') : 'nessuna (elenco vuoto)'} (scope: selected)`);
     }
+    // Effective federated access: the label is DERIVED from the grants, and a
+    // record whose grants were never set says so instead of showing a preset
+    // inferred from defaults.
+    if (peer.kind === 'direct') {
+      const view = accessPresets.grantsOf(peer);
+      log(`accesso:   ${view.label}`);
+      log(`grant:     ${ACCESS_GRANT_KEYS.map((key) => `${key}=${view.grants[key] ? 'on' : 'off'}`).join(' ')}`);
+      log(`scope:     celle ${view.grants.cellVisibility}`);
+      for (const line of feedLinesFor(opts.feedDiagnostics, peer.nodeId)) log(line);
+    }
     log(`azioni:    ${Object.keys(peer.actions || {}).filter((key) => peer.actions[key]).join(', ')}`);
   }
   return { code: 0, peer: found.peer };
 }
 
+// --- Federated access grants -------------------------------------------------
+// The grant vector of a peer is set on the node that OWNS the resources, in one
+// validated write. The label (admin/user/nexushost/custom) is derived from the
+// grants; nothing here stores or reads a role.
+const ACCESS_GRANT_KEYS = ['eventsAccess', 'nodeEventsAccess', 'askReplyAccess', 'filesReadAccess', 'peerOperatorAccess'];
+const ACCESS_EDIT_KEYS = new Set(['accessRole', ...ACCESS_GRANT_KEYS]);
+
+const ACCESS_VECTOR_FIELDS = ['cellVisibility', 'cells', 'panelAccess', 'liveHostAccess'];
+
+// The prospective vector of a peer after applying `overrides`. It covers every
+// field the invariants talk about, so a granular edit cannot leave the record
+// in a state the preset validator would refuse (live hosting without the
+// complete admin set being the case that matters).
+function accessVectorFrom(peer, overrides) {
+  const visibility = Object.hasOwn(overrides, 'cellVisibility') ? overrides.cellVisibility : peer.cellVisibility;
+  const vector = { cellVisibility: visibility };
+  const cells = Object.hasOwn(overrides, 'cells') ? overrides.cells : peer.cells;
+  if (visibility === 'selected') vector.cells = Array.isArray(cells) ? cells : [];
+  const all = [...ACCESS_GRANT_KEYS, 'panelAccess', 'liveHostAccess'];
+  for (const key of all) {
+    vector[key] = Object.hasOwn(overrides, key) ? overrides[key] === true : peer[key] === true;
+  }
+  return vector;
+}
+
 function nodesEdit(opts) {
   const log = opts.log || console.log;
   if (isReadonly(opts)) { log('nodes edit: READONLY, mutazione bloccata'); return { code: 1, reason: 'readonly' }; }
@@ -295,9 +388,12 @@ function nodesEdit(opts) {
   // ai PANNELLI di questo nodo, non chi ha aperto il tunnel — quindi vale in
   // entrambe le direzioni. `liveHostAccess` e' identica: riguarda chi puo'
   // designare la cella ospite Live di QUESTO nodo, non chi ha aperto il tunnel.
+  // eventsReceive is the node's OWN choice to import a peer's feed: it is a
+  // local client decision in BOTH directions and never part of the owner's
+  // grant presets.
   const allowed = node.direction === 'inbound'
-    ? new Set(['label', 'visibility', 'selected', 'cellVisibility', 'cells', 'panelAccess', 'liveHostAccess'])
-    : new Set(['label', 'ssh', 'sshPort', 'autostart', 'cellVisibility', 'cells', 'panelAccess', 'liveHostAccess']);
+    ? new Set(['label', 'visibility', 'selected', 'cellVisibility', 'cells', 'panelAccess', 'liveHostAccess', 'accessRole', 'eventsReceive', ...ACCESS_GRANT_KEYS])
+    : new Set(['label', 'ssh', 'sshPort', 'autostart', 'cellVisibility', 'cells', 'panelAccess', 'liveHostAccess', 'accessRole', 'eventsReceive', ...ACCESS_GRANT_KEYS]);
   const keys = Object.keys(supplied);
   const invalid = keys.find((key) => !allowed.has(key));
   if (invalid) {
@@ -308,6 +404,10 @@ function nodesEdit(opts) {
     log('nodes edit: panelAccess vuole un booleano');
     return { code: 1, reason: 'invalid-panel-access' };
   }
+  if (Object.hasOwn(supplied, 'eventsReceive') && typeof supplied.eventsReceive !== 'boolean') {
+    log('nodes edit: eventsReceive vuole un booleano');
+    return { code: 1, reason: 'invalid-events-receive' };
+  }
   if (Object.hasOwn(supplied, 'liveHostAccess') && typeof supplied.liveHostAccess !== 'boolean') {
     log('nodes edit: liveHostAccess vuole un booleano');
     return { code: 1, reason: 'invalid-live-host-access' };
@@ -342,9 +442,73 @@ function nodesEdit(opts) {
   // ricostruisce il nodo da zero.
   if (Object.hasOwn(patch, 'cellVisibility') && patch.cellVisibility !== 'selected') patch.cells = undefined;
 
+  const accessRequested = keys.some((key) => ACCESS_EDIT_KEYS.has(key));
+  const touchesVector = keys.some((key) => ACCESS_VECTOR_FIELDS.includes(key));
+  // A peer whose grants were never configured keeps its historical behaviour
+  // for panel/live flags; once a vector IS configured, every edit of that
+  // vector passes through the same validator and the same single write.
+  const enforceVector = accessRequested || (touchesVector && node.accessConfigured === true);
+  let accessVector = null;
+  if (enforceVector) {
+    const hasRole = Object.hasOwn(supplied, 'accessRole');
+    const granular = ACCESS_GRANT_KEYS.filter((key) => Object.hasOwn(supplied, key));
+    if (hasRole && granular.length > 0) {
+      log('nodes edit: --access-role e i grant granulari non si combinano nella stessa richiesta');
+      return { code: 1, reason: 'preset-and-grants' };
+    }
+    for (const key of granular) {
+      if (typeof supplied[key] !== 'boolean') {
+        log(`nodes edit: ${key} vuole un booleano`);
+        return { code: 1, reason: 'invalid-grant' };
+      }
+    }
+    if (hasRole) {
+      if (typeof supplied.accessRole !== 'string' || !accessPresets.PRESET_NAMES.includes(supplied.accessRole)) {
+        log(`nodes edit: access-role non valido (atteso: ${accessPresets.PRESET_NAMES.join('|')})`);
+        return { code: 1, reason: 'invalid-access-role' };
+      }
+      accessVector = { ...accessPresets.PRESETS[supplied.accessRole] };
+    } else if (!accessRequested && touchesVector) {
+      // Panel/live/scope edit on a configured peer: same vector, same rules.
+      accessVector = accessVectorFrom(node, supplied);
+    } else {
+      // A granular edit only refines a vector that was set explicitly: a peer
+      // whose grants were never configured stays denied, and a partial edit
+      // must not promote it.
+      if (node.accessConfigured !== true) {
+        log('nodes edit: peer non configurato — applica prima un preset (--access-role)');
+        return { code: 1, reason: 'access-not-configured' };
+      }
+      accessVector = accessVectorFrom(node, supplied);
+    }
+    const check = accessPresets.validateGrants(accessVector);
+    if (!check.ok) {
+      log(`nodes edit: concessioni rifiutate — ${check.errors.join('; ')}`);
+      return { code: 1, reason: 'invalid-grants' };
+    }
+    for (const key of [...ACCESS_EDIT_KEYS, ...ACCESS_VECTOR_FIELDS]) delete patch[key];
+  }
+
   let next;
-  try { next = store.updateNode(st, node.name, patch); }
-  catch (e) { log(`nodes edit: ${e.message}`); return { code: 1, reason: 'invalid-patch' }; }
+  if (enforceVector) {
+    // One validated read-modify-write against the policy revision: a concurrent
+    // edit loses the race and rereads instead of overwriting it.
+    const expected = Number.isInteger(opts.expectedRevision) ? opts.expectedRevision : store.accessRevisionOf(st);
+    let res;
+    try {
+      res = store.setPeerAccessGrantsCas({
+        filePath: nodesPath, name: node.name, grants: accessVector, expectedRevision: expected, extraPatch: patch,
+      });
+    } catch (e) { log(`nodes edit: ${e.message}`); return { code: 1, reason: 'invalid-patch' }; }
+    if (!res.ok) {
+      log(`nodes edit: revision delle concessioni superata (attuale ${res.revision}) — rileggi e riprova`);
+      return { code: 1, reason: 'revision-conflict', revision: res.revision };
+    }
+    next = store.loadStoreStrict(nodesPath);
+  } else {
+    try { next = store.updateNode(st, node.name, patch); }
+    catch (e) { log(`nodes edit: ${e.message}`); return { code: 1, reason: 'invalid-patch' }; }
+  }
 
   const transportChanged = node.direction === 'outbound'
     && ['ssh', 'sshPort'].some((key) => Object.hasOwn(patch, key));
@@ -377,6 +541,33 @@ function nodesEdit(opts) {
   return { code: 0, name: node.name, node: edited, restarted: wasUp };
 }
 
+// --- nodes access: read-only inventory --------------------------------------
+// Shows what every peer may currently do on this node, with the revision of
+// the policy. Peers whose grants were never configured are listed as such:
+// they are the ones an explicit migration has to set, and nothing promotes
+// them by name or by age of pairing.
+function nodesAccess(opts = {}) {
+  const log = opts.log || console.log;
+  const { nodesPath } = resolveNodePaths(opts);
+  let st;
+  try { st = store.loadStoreStrict(nodesPath); }
+  catch (e) { log(`nodes access: ${e.message}`); return { code: 1, reason: 'store invalido', status: e.status || 500 }; }
+  const view = store.accessInventory(st);
+  const legacy = view.peers.filter((peer) => !peer.configured);
+  if (opts.json) {
+    log(JSON.stringify({ revision: view.revision, peers: view.peers, unconfigured: legacy.map((p) => p.name) }, null, 2));
+    return { code: 0, ...view, unconfigured: legacy.map((p) => p.name) };
+  }
+  log(`revision concessioni: ${view.revision}`);
+  if (view.peers.length === 0) log('nessun peer diretto');
+  for (const peer of view.peers) {
+    log(`${peer.name}${peer.nodeId ? ` (${peer.nodeId})` : ''}: ${peer.label}`);
+    log(`  ${ACCESS_GRANT_KEYS.map((key) => `${key}=${peer.grants[key] ? 'on' : 'off'}`).join(' ')} · celle ${peer.grants.cellVisibility}`);
+  }
+  if (legacy.length > 0) log(`da configurare esplicitamente (${legacy.length}): ${legacy.map((p) => p.name).join(', ')}`);
+  return { code: 0, ...view, unconfigured: legacy.map((p) => p.name) };
+}
+
 // --- nodes remove ----------------------------------------------------------
 function nodesRemove(opts) {
   const log = opts.log || console.log;
@@ -683,6 +874,9 @@ function nodesSetToken(opts) {
 }
 
 module.exports = {
+  fetchFeedDiagnostics, feedLinesFor,
+
+  nodesAccess, ACCESS_GRANT_KEYS,
   nodesAdd, nodesList, nodesInspect, nodesEdit, nodesRemove, nodesTest, nodesTestAll,
   nodesUp, nodesDown, nodesRestart, nodesSetToken,
   // helper esposti per test/riuso

package/lib/nodes/store.js

@@ -1,8 +1,8 @@
 'use strict';
-// lib/nodes/store.js — nodes.json secret store (design §4, §4b(4)).
+// lib/nodes/store.js — nodes.json secret store.
 //
 // nodes.json e' un SECRET STORE, non config qualunque: contiene i token dei nodi
-// remoti (iniettati dal proxy in B1). Percio' riusa lo stesso hardening di
+// Remoti (iniettati dal proxy in). Percio' riusa lo stesso hardening di
 // lib/fleet/definitions.js e del token file:
 //   - permessi 0600, scrittura atomica (tmp stessa dir + rename), rifiuto symlink
 //   - schema STRICT validato al load: garbage -> errore esplicito, MAI guess
@@ -19,6 +19,7 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const reversePool = require('./reverse-pool.js');
 const identity = require('./identity.js');
+const accessPresets = require('./access-presets.js');
 
 const SCHEMA_VERSION = 3;
 const PREVIOUS_SCHEMA_VERSION = 2;
@@ -28,14 +29,14 @@ const MAX_TOKEN_LEN = 4096;
 const MAX_KEYPATH_LEN = 4096;
 const MAX_SSH_LEN = 320;          // user(<=32) + '@' + host(<=255)
 
-// name: chiave strict usata anche come segmento path/route in B1 -> niente '.',
-// '/', maiuscole. Allineato al contratto §4b(2) (^[a-z0-9-]{1,32}$).
+// name: strict key also used as a path/route segment -> no '.', no '/',
+// no uppercase. Aligned with the strict name contract (^[a-z0-9-]{1,32}$).
 const NODE_NAME_RE = /^[a-z0-9-]{1,32}$/;
 // nodeId: id stabile per-installazione, hex casuale (crypto.randomBytes(16)).
 const NODE_ID_RE = /^[a-f0-9]{16,64}$/;
 // user@host: entrambe le parti argv-safe (no spazi, no leading '-' -> mai
 // interpretabile come opzione ssh). Host: hostname/FQDN/IPv4 (niente ':' -> IPv6
-// va usato via Host alias in ~/.ssh/config, fuori scope B0).
+// Va usato via Host alias in ~/.ssh/config, fuori scope).
 const SSH_USER_RE = /^[A-Za-z0-9._-]{1,32}$/;
 const SSH_HOST_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,254}$/;
 
@@ -112,6 +113,10 @@ const NODE_KEYS = new Set([
   // 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',
+  // eventsReceive: the CLIENT's own local choice to import an owner's feed.
+  // It is NOT a grant the owner sets, it never travels in a preset, and it
+  // only ever decides what THIS node pulls — never what a peer may read here.
+  'eventsReceive',
   // Se questo peer puo' aprire i PANNELLI delle celle di questo nodo. Distinto
   // da `cellVisibility`, che dice quali celle il peer VEDE: dietro un pannello
   // c'e' un browser con sessioni gia' autenticate, e un accesso di quel tipo non
@@ -132,13 +137,25 @@ const NODE_KEYS = new Set([
   // grant potra' pretendere la prima. `keyConflict` conserva una chiave DIVERSA
   // vista dopo il legame, senza sostituire quella legata.
   'publicKey', 'keySource', 'keyBoundAt', 'keyConflict',
-  // P0 stessa-origin, meta' remota: la porta pannello del peer inoltrata sul
+  // Stessa-origin, meta' remota: la porta pannello del peer inoltrata sul
   // NOSTRO loopback (panelLocalPort) e la sua origine remota (panelRemotePort).
   // COPPIA obbligatoria: un -L ha due estremita', mezza coppia e' un forward
   // impossibile, non "meno pannello". Campi assenti = peer accoppiato prima di
   // questa negoziazione: via storica, nessun comportamento nuovo. Le porte non
   // sono segreti (come localPort/remotePort, che stanno qui accanto).
   'panelLocalPort', 'panelRemotePort',
+  // Federated access grants: what this peer may do with the resources this node
+  // OWNS (events, asks, files) beyond cell visibility. Same shape and same rule
+  // as panelAccess/liveHostAccess: default denied, one node at a time. A peer
+  // does not gain them by being paired, and the receiving client's own choice
+  // to receive events is NOT one of them (it is local to that client).
+  'eventsAccess', 'nodeEventsAccess', 'askReplyAccess', 'filesReadAccess', 'peerOperatorAccess',
+  // Whether the grant vector was set EXPLICITLY. Grants alone cannot tell a
+  // legacy record (all defaults denied) from a deliberate vector that happens
+  // to deny everything: without this marker a legacy peer would read as a
+  // coherent "custom" preset instead of "not configured". It is provenance,
+  // not a permission — it grants nothing and handlers never read it as a role.
+  'accessConfigured',
 ]);
 
 // Nome di cella: stessa forma usata da fleet/definitions.js, cells/routes.js e
@@ -248,6 +265,7 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
   const roles = parseRoles(n.roles);
   if (!roles) return null;
   if (n.rolesKnown !== undefined && typeof n.rolesKnown !== 'boolean') return null;
+  if (n.eventsReceive !== undefined && typeof n.eventsReceive !== 'boolean') return null;
   // Before 0.8.9 `roles` was filled with a local default and did not describe
   // the remote peer. Only the explicit marker makes role-based health safe.
   const rolesKnown = n.rolesKnown === true;
@@ -285,6 +303,16 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
     // Stessa regola, stesso motivo: un record senza il campo non acquisisce la
     // designazione live per anzianita' del pairing.
     liveHostAccess: n.liveHostAccess === undefined ? false : n.liveHostAccess,
+    // Le cinque concessioni federate seguono la stessa regola: assenti valgono
+    // NEGATE. Nessuna migrazione silenziosa al load: il vettore va impostato da
+    // un atto esplicito (preset o edit granulare), altrimenti resta negato.
+    eventsReceive: n.eventsReceive === undefined ? false : n.eventsReceive === true,
+    eventsAccess: n.eventsAccess === undefined ? false : n.eventsAccess,
+    nodeEventsAccess: n.nodeEventsAccess === undefined ? false : n.nodeEventsAccess,
+    askReplyAccess: n.askReplyAccess === undefined ? false : n.askReplyAccess,
+    filesReadAccess: n.filesReadAccess === undefined ? false : n.filesReadAccess,
+    peerOperatorAccess: n.peerOperatorAccess === undefined ? false : n.peerOperatorAccess,
+    accessConfigured: n.accessConfigured === true,
     visibility: n.visibility || 'network',
   };
   if (!['auto', 'ssh', 'autossh', 'inbound'].includes(out.transport)) return null;
@@ -294,6 +322,12 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
   if (typeof out.shared !== 'boolean') return null;
   if (typeof out.panelAccess !== 'boolean') return null;
   if (typeof out.liveHostAccess !== 'boolean') return null;
+  if (typeof out.eventsAccess !== 'boolean') return null;
+  if (typeof out.nodeEventsAccess !== 'boolean') return null;
+  if (typeof out.askReplyAccess !== 'boolean') return null;
+  if (typeof out.filesReadAccess !== 'boolean') return null;
+  if (typeof out.peerOperatorAccess !== 'boolean') return null;
+  if (typeof out.accessConfigured !== 'boolean') return null;
   if (!['network', 'relay-only', 'selected'].includes(out.visibility)) return null;
   if (identityFile) out.identityFile = identityFile;
   // Keep the old public field while reading v1 so old callers/tests and a
@@ -303,7 +337,7 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
     if (!isPort(n.reversePort)) return null;
     out.reversePort = n.reversePort;
   }
-  // Coppia pannello (P0 stessa-origin remota): o entrambe le porte o nessuna.
+  // Coppia pannello (stessa-origin remota): o entrambe le porte o nessuna.
   // Una sola meta' non viene indovinata — sarebbe un -L monco. E la porta
   // locale del pannello non puo' stare su quella del control plane: ssh
   // cadrebbe con ExitOnForwardFailure portandosi via il tunnel intero.
@@ -427,7 +461,7 @@ function parseStore(raw) {
 
     if (![SCHEMA_VERSION, PREVIOUS_SCHEMA_VERSION, LEGACY_SCHEMA_VERSION].includes(d.schemaVersion)) return null;
     const rootKeys = d.schemaVersion === SCHEMA_VERSION
-      ? new Set(['schemaVersion', 'nodeId', 'nodes', 'rendezvous', 'reversePoolAnchor', 'reversePoolLedgerInitialized'])
+      ? new Set(['schemaVersion', 'nodeId', 'nodes', 'rendezvous', 'reversePoolAnchor', 'reversePoolLedgerInitialized', 'accessRevision'])
       : new Set(['schemaVersion', 'nodeId', 'nodes', 'rendezvous']);
     if (Object.keys(d).some((key) => !rootKeys.has(key))) return null;
     if (typeof d.nodeId !== 'string' || !NODE_ID_RE.test(d.nodeId)) return null;
@@ -461,6 +495,16 @@ function parseStore(raw) {
 
     const out = { schemaVersion: d.schemaVersion, nodeId: d.nodeId, nodes };
 
+    // Revision of the peer access policy. Absent means 0: a store written
+    // before this field existed is at revision 0 and the first explicit write
+    // advances it to 1. It is kept out of the parsed object when absent so a
+    // plain load never rewrites the file with a field nobody set.
+    if (d.accessRevision !== undefined) {
+      if (d.schemaVersion !== SCHEMA_VERSION) return null;
+      if (!Number.isInteger(d.accessRevision) || d.accessRevision < 0) return null;
+      out.accessRevision = d.accessRevision;
+    }
+
     if (d.rendezvous !== undefined && d.rendezvous !== null) {
       const rdv = parseRendezvous(d.rendezvous);
       if (!rdv) return null;
@@ -647,6 +691,101 @@ function updateNode(store, name, patch) {
   return { ...store, schemaVersion: mutationSchemaVersion(store), nodes };
 }
 
+// --- Concessioni federate: preset, CAS, inventario -------------------------
+
+function accessRevisionOf(store) {
+  return store && Number.isInteger(store.accessRevision) && store.accessRevision >= 0
+    ? store.accessRevision : 0;
+}
+
+// Pure: returns a new store with the peer's grant vector replaced by a
+// validated one. The vector is validated as a whole, so an edit that keeps
+// live hosting while dropping another admin grant is refused here too.
+function setPeerAccessGrants(store, name, grants) {
+  const idx = store.nodes.findIndex((n) => n.name === name);
+  if (idx < 0) throw new Error(`nodo sconosciuto: "${name}"`);
+  const check = accessPresets.validateGrants(grants);
+  if (!check.ok) throw new Error(`concessioni non valide: ${check.errors.join('; ')}`);
+  const next = { ...store.nodes[idx] };
+  next.cellVisibility = grants.cellVisibility;
+  if (grants.cellVisibility === 'selected') next.cells = [...(grants.cells || [])];
+  else delete next.cells;
+  for (const key of accessPresets.BOOLEAN_GRANTS) next[key] = grants[key] === true;
+  next.accessConfigured = true;
+  const nodes = store.nodes.slice();
+  nodes[idx] = next;
+  const out = { ...store, schemaVersion: SCHEMA_VERSION, nodes };
+  out.accessRevision = accessRevisionOf(store) + 1;
+  return out;
+}
+
+// Pure: applies a named preset to one peer.
+function setPeerAccessPreset(store, name, presetName) {
+  const idx = store.nodes.findIndex((n) => n.name === name);
+  if (idx < 0) throw new Error(`nodo sconosciuto: "${name}"`);
+  const applied = accessPresets.applyPreset(store.nodes[idx], presetName);
+  const vector = { cellVisibility: applied.cellVisibility };
+  if (applied.cells !== undefined) vector.cells = applied.cells;
+  for (const key of accessPresets.BOOLEAN_GRANTS) vector[key] = applied[key];
+  return setPeerAccessGrants(store, name, vector);
+}
+
+// Read-only inventory: what every peer is allowed to do on THIS node, with the
+// label derived from the grants. Used by `nodes show`, by the settings view and
+// by the explicit migration: a legacy peer shows up as not configured, never as
+// a preset inferred from defaults.
+function accessInventory(store) {
+  const peers = (store && store.nodes ? store.nodes : []).map((peer) => {
+    const view = accessPresets.grantsOf(peer);
+    return {
+      name: peer.name,
+      nodeId: peer.nodeId || null,
+      direction: peer.direction,
+      configured: view.configured,
+      label: view.label,
+      grants: view.grants,
+    };
+  });
+  return { revision: accessRevisionOf(store), peers };
+}
+
+// Compare-and-set write for the peer access policy: one validated read-modify-
+// write over the store file. `expectedRevision` must be an integer that matches
+// the current revision, otherwise the write is refused and the caller rereads
+// and retries — never a permissive default. The whole path is synchronous, so
+// two callers in this process cannot interleave between the read and the write.
+function setPeerAccessGrantsCas({ filePath, name, grants, expectedRevision, extraPatch }) {
+  const current = loadStoreStrict(filePath);
+  if (!Number.isInteger(expectedRevision) || accessRevisionOf(current) !== expectedRevision) {
+    return { ok: false, conflict: true, revision: accessRevisionOf(current) };
+  }
+  let next = current;
+  if (extraPatch && Object.keys(extraPatch).length > 0) next = updateNode(next, name, extraPatch);
+  next = setPeerAccessGrants(next, name, grants);
+  const written = atomicWriteStore(filePath, next);
+  return {
+    ok: true,
+    name,
+    revision: accessRevisionOf(written),
+    grants: accessPresets.grantsOf(written.nodes.find((n) => n.name === name)).grants,
+    label: accessPresets.grantsOf(written.nodes.find((n) => n.name === name)).label,
+  };
+}
+
+// Same, by preset name.
+function setPeerAccessPresetCas({ filePath, name, presetName, expectedRevision, extraPatch }) {
+  const current = loadStoreStrict(filePath);
+  if (!Number.isInteger(expectedRevision) || accessRevisionOf(current) !== expectedRevision) {
+    return { ok: false, conflict: true, revision: accessRevisionOf(current) };
+  }
+  let next = current;
+  if (extraPatch && Object.keys(extraPatch).length > 0) next = updateNode(next, name, extraPatch);
+  next = setPeerAccessPreset(next, name, presetName);
+  const written = atomicWriteStore(filePath, next);
+  const view = accessPresets.grantsOf(written.nodes.find((n) => n.name === name));
+  return { ok: true, name, revision: accessRevisionOf(written), grants: view.grants, label: view.label };
+}
+
 // The upgrade is explicit: normal legacy pairing remains schema v2 and keeps
 // working with a previous NexusCrew binary.  Enabling rotation is the only
 // path that writes the v3 anchor and therefore requires both peers to support
@@ -691,6 +830,7 @@ function redactNode(n) {
     rolesKnown: n.rolesKnown === true,
     transport: n.transport || 'ssh',
     autostart: !!n.autostart,
+    eventsReceive: n.eventsReceive === true,
     shared: n.shared === true,
     panelAccess: n.panelAccess === true,
     liveHostAccess: n.liveHostAccess === true,
@@ -758,7 +898,7 @@ function hasPairedPeers(store) {
 }
 
 // --- Migrazione esplicita da config.json (guarded, no-op se assente) ---------
-// Se config.json contiene un array `nodes` legacy (vecchio formato pre-B0),
+// Se config.json contiene un array `nodes` legacy (vecchio formato pre-),
 // lo importa in nodes.json. Guarded: no-op se config.json non ha `nodes`, o se
 // nodes.json ha gia' dei nodi (mai overwrite). Strict: un nodo legacy malformato
 // -> throw esplicito (non importa silenziosamente spazzatura).
@@ -885,6 +1025,9 @@ module.exports = {
   defaultNodesPath, loadStore, loadStoreStrict, initStore, atomicWriteStore, loadOrInitStore, emptyStore, newNodeId,
   // mutazioni
   getNode, addNode, removeNode, setNodeToken, updateNode, upgradeToReversePoolSchema, setNodeReversePool,
+  // concessioni federate (preset, CAS, inventario)
+  accessRevisionOf, setPeerAccessGrants, setPeerAccessPreset, accessInventory,
+  setPeerAccessGrantsCas, setPeerAccessPresetCas,
   // redazione
   redactNode, redactStore, hasPairedPeers,
   // migrazione

package/lib/nodes/tunnel.js

@@ -1,5 +1,5 @@
 'use strict';
-// lib/nodes/tunnel.js — SSH tunnel manager (design §4b(1), §7).
+// lib/nodes/tunnel.js — SSH tunnel manager.
 //
 // I processi ssh sono gestiti da un solo supervisor detached, avviato dal
 // lifecycle del servizio o dalle azioni PWA autenticate. argv puro (spawn con
@@ -10,7 +10,7 @@
 //     unit-testabili senza lanciare ssh.
 //   - lifecycle per-tunnel via pidfile (start/stop/restart/state): il processo
 //     ssh e' detached, la sua liveness/porta stabile e' interrogabile da
-//     `status --json` e (in B1) dal proxy. Porta STABILE da nodes.json; una
+// `status --json` e (in) dal proxy. Porta STABILE da nodes.json; una
 //     collisione fa fallire ExitOnForwardFailure -> si segnala, NON si riciclano
 //     porte a caso.
 const fs = require('node:fs');
@@ -21,7 +21,7 @@ const { spawn, spawnSync } = require('node:child_process');
 const pidf = require('../cli/pidfile.js');
 const store = require('./store.js');
 
-// Opzioni SSH comuni ai due template (ordine e valori ESATTI dal design §4b(1)).
+// SSH options shared by both templates (exact order and values).
 const SSH_BASE_OPTS = Object.freeze([
   '-N',
   '-o', 'ExitOnForwardFailure=yes',
@@ -44,7 +44,7 @@ function assertForwardSpec(node) {
   if (node.keyPath !== undefined && !store.isAbsPath(node.keyPath)) throw new Error('tunnel: keyPath non valido');
   if (node.reversePort !== undefined && !store.isPort(node.reversePort)) throw new Error('tunnel: reversePort non valida');
   if (node.localAppPort !== undefined && !store.isPort(node.localAppPort)) throw new Error('tunnel: localAppPort non valida');
-  // Coppia pannello (P0 stessa-origin remota): o entrambe o nessuna, e mai
+  // Coppia pannello (stessa-origin remota): o entrambe o nessuna, e mai
   // sulla porta locale del control plane — il bind conflitto abbatterebbe il
   // tunnel intero con ExitOnForwardFailure.
   if (node.panelLocalPort !== undefined || node.panelRemotePort !== undefined) {
@@ -61,7 +61,7 @@ function assertForwardSpec(node) {
   if (!store.parseSshTarget(node.ssh)) throw new Error('tunnel: target ssh non valido');
 }
 
-// Forward client->nodo (ruolo client). §4b(1):
+// Forward client->node (client role):
 //   ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=30
 //       -o ServerAliveCountMax=3 -o BatchMode=yes -i <key>
 //       -L 127.0.0.1:<locale>:127.0.0.1:<remota> user@host
@@ -108,7 +108,7 @@ function buildReverseArgs(node, { remotePort, targetPort } = {}) {
   ]);
 }
 
-// Backoff esponenziale + jitter (design §7). Deterministico con rng iniettato.
+// Exponential backoff + jitter. Deterministic with an injected rng.
 //   delay = clamp(base * factor^attempt, 0..cap) * (1 +- jitter*(2*rand-1))
 // rng()=0.5 -> jitter nullo (ritorna il valore base clamperato); test deterministici.
 function backoffDelay(attempt, opts = {}) {
@@ -735,7 +735,7 @@ function authorizedKeysLine({ remotePort, panelRemotePort, pub } = {}) {
 // registrato in revisione: `null | stringa` comprimeva stati DIVERSI, e il
 // livello basso componeva frasi su fatti che non conosce — meta' della 0.9.5
 // e' nata li'). Gli esiti sono DATI, senza testo per l'utente: le frasi si
-// compongono al confine UI/log, mai qui. Si aggancia a P4: una chiave cifrata
+// Compongono al confine UI/log, mai qui. Si aggancia a: una chiave cifrata
 // dava `null`, indistinguibile da «file illeggibile», e il pairing ometteva
 // la riga in silenzio.
 //