@mmmbuto/nexuscrew 0.9.29 → 0.9.30

package/lib/live-host/bridge.js

@@ -19,19 +19,19 @@
 // going to operate on.
 //
 // Invarianti (contratto fetta 3):
-//   - MC1: la designazione si legge con UNA GET su loopback verso
+// La designazione si legge con UNA GET su loopback verso
 //     /api/live-host, autenticata col token del nodo. Nessun accesso diretto
 //     allo store: la route è l'unica verità, `eligible` non si ricalcola.
-//   - MC1.5 / JC3.3: nessuna attesa introdotta. Ogni fase ha il limite
+// Nessuna attesa introdotta. Ogni fase ha il limite
 //     dichiarato cfg.liveBridgeTimeoutMs; oltre quello, o su qualunque
 //     fallimento, la risposta è `none` col motivo: la Live parte senza
 //     puntamento, comportamento standard. Un `none` non è un errore HTTP.
-//   - MC2: il prompt per-cella (LIVE_PROMPT.md accanto ai canonici della
+// Il prompt per-cella (LIVE_PROMPT.md accanto ai canonici della
 //     cella) viaggia su developerInstructions di thread/start e SOSTITUISCE
-//     le developer instructions della config per quella Live (rev4 LC2
-//     emendata da rev5 MC2). La riga che decide è in codex-rs
+// Le developer instructions della config per quella Live (rev4
+// Emendata da rev5). La riga che decide è in codex-rs
 //     core/src/config/mod.rs: `developer_instructions.or(cfg.developer_
-//     instructions)` — l'override Some scarta il valore di config. R2
+// Instructions)` — l'override Some scarta il valore di config.
 //     (verso corretto dopo revisione pre-release): l'identità della
 //     cella designata viaggia SEMPRE come intestazione anteposta al campo,
 //     anche senza prompt. Il campo NON è additivo: una cella senza
@@ -41,18 +41,18 @@
 //     il world state (fragment user, canale separato) e il prompt base.
 //     La via designata per le istruzioni di lavoro della Live è il
 //     LIVE_PROMPT.md della cella: viaggia nello stesso campo.
-//   - MC3: il ponte crea le proprie conversazioni con thread/start e non
+// Il ponte crea le proprie conversazioni con thread/start e non
 //     tocca MAI la thread di una TUI — né turn/start né thread/resume. La sonda
 //     thread/read e' separata e sola lettura: non modifica il thread ponte ne'
 //     quello della TUI. Per questo l'aggancio funziona anche su una cella che
 //     sta già processando un turno: conversazioni separate, nessuna
-//     interruzione (rev1 HC2/rev2 JC4).
-//   - MC3.3: la connessione al socket di controllo è ON-DEMAND (connect →
+// Interruzione (rev1 /rev2).
+// La connessione al socket di controllo è ON-DEMAND (connect →
 //     handshake → thread/start → close), mai permanente: la fuga notifiche
 //     notata in rev5 riguarda i client permanenti.
-//   - MC3.4: il ponte opera SOLO sulla cella designata — non accetta target
-//     dal chiamante, la designazione è la condizione (LC3).
-//   - MC0: isolabile — cfg.liveBridgeEnabled=false e il ponte non si connette
+// Il ponte opera SOLO sulla cella designata — non accetta target
+// Dal chiamante, la designazione è la condizione.
+// Isolabile — cfg.liveBridgeEnabled=false e il ponte non si connette
 //     mai, non fa GET, risponde `none` senza toccare nulla.
 //
 // Protocollo del socket di controllo (misurato sul runtime 2026-08-15):
@@ -61,7 +61,7 @@
 // (senza params). Poi `thread/start` {cwd, developerInstructions?} → response
 // {thread:{id}, cwd}, oppure `thread/read` {threadId, includeTurns:false} per
 // leggere il runtime. Il socket è 0600 dell'utente: il confine è quello
-// (MC1.3), non c'è autenticazione applicativa.
+// Non c'è autenticazione applicativa.
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -174,10 +174,10 @@ function queryThreadStatusOnControlSocket({
   });
 }
 
-// —— Prompt per-cella (rev4 LC2, nome fisso confermato il 2026-08-15) ——
+// — Prompt per-cella (rev4, nome fisso confermato il 2026-08-15) ——
 // Collocazione: filesRoot/<tmuxSession>/LIVE_PROMPT.md — la sessione tmux
 // ESATTA che il roster dichiara per la cella designata, la stessa fonte gia'
-// usata per l'intestazione R2 (identityHeader). NON un prefisso ricostruito a
+// Usata per l'intestazione (identityHeader). NON un prefisso ricostruito a
 // mano: fino al 2026-08-16 questa funzione anteponeva 'cloud-' come default
 // universale quando il cellId non ce l'aveva gia' — su un device che chiama
 // le proprie sessioni con un prefisso diverso il file non veniva MAI trovato,
@@ -194,8 +194,8 @@ function queryThreadStatusOnControlSocket({
 //                                   costruito (mai un prefisso indovinato),
 //                                   quindi non si tenta nemmeno la lettura
 //   applied:false, reason missing       → ENOENT sul path dichiarato: assenza
-//                                   legittima (LC2.3), si procede senza
-//                                   PROMPT (R2: l'intestazione identità
+// Legittima, si procede senza
+// PROMPT: the identity header
 //                                   viaggia comunque). ATTENZIONE: il campo
 //                                   developerInstructions viene comunque
 //                                   inviato per via dell'intestazione, e il
@@ -203,7 +203,7 @@ function queryThreadStatusOnControlSocket({
 //                                   configurazione invece di sommarlo — chi
 //                                   non ha prompt per-cella non riceve le
 //                                   developer instructions globali che
-//                                   riceveva prima (vedi MC2, verificato
+// Riceveva prima (verificato
 //                                   sulla riga che decide)
 //   applied:false, reason unreadable|empty → presente ma inutilizzabile: va
 //                                   dichiarato, mai silenziato
@@ -222,14 +222,14 @@ function readCellPrompt(filesRoot, tmuxSession) {
   return { applied: true, source: 'LIVE_PROMPT.md', text };
 }
 
-// —— Identità della Live (R2, 2026-08-16): la porta il ponte, non il prompt ——
-// Il ponte ha la designazione IN MANO (MC3.4: è la sua condizione di
-// funzionamento) e un prompt può legittimamente mancare (MC2.4): se
+// — Identità della Live (2026-08-16): la porta il ponte, non il prompt ——
+// Il ponte ha la designazione IN MANO: è la sua condizione di
+// Funzionamento) e un prompt può legittimamente mancare: se
 // l'identità dipendesse dal prompt, l'assenza del prompt diventerebbe assenza
 // di identità — è esattamente il difetto visto sul campo (la voce andava a
 // leggere tmux per capire dove si trovava).
 //
-// R30 (v2, 2026-08-19): l'intestazione dice anche COME raggiungere i tool
+// (v2, 2026-08-19): the header also states HOW to reach the tools
 // NexusCrew. Il daemon app-server espone UN solo insieme di server MCP a
 // tutte le Live, con l'ambiente del daemon: nexuscrew è l'unico che prende
 // l'identità dall'ambiente ereditato, quindi i suoi tool con sessione
@@ -353,7 +353,7 @@ function startThreadOnControlSocket({
             title: 'NexusCrew Live Bridge',
             version: bridgeVersion(),
             // Identita della connessione: la sessione gia' risolta della cella
-            // designata (mai env grezzi, mai guess — roster MC3.4). Se assente
+            // Designata (mai env grezzi, mai guess — roster). Se assente
             // il campo SI OMETTE (Option None lato protocollo): il resolver a
             // valle classifica MISSING nominando la causa; sanitizzare qui la
             // duplicherebbe senza guadagno.
@@ -400,7 +400,7 @@ function startThreadOnControlSocket({
         return;
       }
       // Notifiche broadcast e risposte non attese: ignorate (connessione
-      // on-demand, la finestra di esposizione alla fuga MC3.3 è minima).
+      // On-demand, la finestra di esposizione alla fuga è minima).
     });
 
     ws.on('error', (e) => done(Object.assign(new Error(`control socket: ${e.message}`), { code: 'ESOCKET' })));
@@ -426,7 +426,7 @@ function createLiveBridge({
   const threadIdsByCell = new Map();
   const threadStatusCache = new Map();
   const threadStatusInFlight = new Map();
-  // R4: riserve in-process per l'avvio Live. La chiave è la cella host: una
+  // Riserve in-process per l'avvio Live. La chiave è la cella host: una
   // sola start provvisoria per cella alla volta, e il commit ricontrolla la
   // tupla congelata in riserva prima di accettare il thread creato.
   const pendingLiveByCell = new Map();
@@ -435,7 +435,7 @@ function createLiveBridge({
 
   const none = (reason, extra) => ({ mode: 'none', reason, ...(extra || {}), at: now() });
 
-  // MC1: la designazione si legge dalla ROUTE, con il token del nodo, entro
+  // La designazione si legge dalla ROUTE, con il token del nodo, entro
   // il limite dichiarato. retry no, cache no: una lettura per avvio Live.
   async function readDesignation() {
     const ctrl = new AbortController();
@@ -553,7 +553,7 @@ function createLiveBridge({
     if (cell.active !== true) return none('host-cell-inactive');
     if (typeof cell.cwd !== 'string' || !cell.cwd) return none('cell-cwd-unknown');
 
-    // JC2: la modalità è una funzione dell'engine, non una scelta. Nativa solo
+    // La modalità è una funzione dell'engine, non una scelta. Nativa solo
     // su engine codex-vl (il thread ponte vive nell'app-server del fork); per
     // qualunque altro engine la Live lavora ATTRAVERSO la cella e il ponte non
     // ha nulla da creare qui.
@@ -565,7 +565,7 @@ function createLiveBridge({
     if (!engine.startsWith('codex-vl')) {
       const out = {
         mode: 'tmux', cell: snap.hostCell, engine: cell.engine || null, cwd: cell.cwd,
-        // JC5.5: in modalità tmux le regole le applica la cella; nessuna
+        // In modalità tmux le regole le applica la cella; nessuna
         // iniezione da parte del ponte.
         prompt: { applied: false, reason: 'tmux-mode' },
         at: now(),
@@ -574,16 +574,16 @@ function createLiveBridge({
       return out;
     }
 
-    // R2: l'identità viaggia SEMPRE, anteposta al prompt quando c'è. Il campo
+    // L'identità viaggia SEMPRE, anteposta al prompt quando c'è. Il campo
     // non è mai più assente: senza LIVE_PROMPT.md porta la sola intestazione
     // — e poiché il campo SOSTITUISCE le developer instructions della config
-    // (vedi MC2: la .or() in config/mod.rs), quella cella non le riceve più.
+// (see: the .or() in config/mod.rs), that cell no longer receives them.
     const intestazione = identityHeader(snap.hostCell, cell.tmuxSession);
     const developerInstructions = prompt.applied
       ? `${intestazione}\n\n${prompt.text}`
       : intestazione;
 
-    // R4: riserva della tupla e start provvisorio. Finché il commit non
+    // Riserva della tupla e start provvisorio. Finché il commit non
     // ricontrolla la stessa tupla, il thread NON viene accettato: nessun tool
     // può attraversarlo, perché il ponte non ne registra l'id.
     if (pendingLiveByCell.has(snap.hostCell)) return none('reservation-in-flight');
@@ -598,8 +598,8 @@ function createLiveBridge({
         cwd: cell.cwd,
         developerInstructions,
         // Stessa fonte dell'intestazione e del prompt per-cella (roster:
-        // MC3.4). Dichiarata per connessione: batte qualunque ambiente
-        // ereditato, anche quando e' popolato ma stantio (B1-bis).
+        //). Dichiarata per connessione: batte qualunque ambiente
+        // Ereditato, anche quando e' popolato ma stantio (-bis).
         declaredSession: cell.tmuxSession,
         timeoutMs: cfg.liveBridgeTimeoutMs,
         WebSocket,
@@ -612,7 +612,7 @@ function createLiveBridge({
       return none(reason, { cell: snap.hostCell, detail: String(e.message) });
     }
 
-    // R4: commit. La designazione e il lease vengono riletti e confrontati con
+    // Commit. La designazione e il lease vengono riletti e confrontati con
     // la tupla riservata: se qualcosa è cambiato durante lo start, il thread
     // resta scartato (zero dispatch) e l'esito lo dichiara con l'id scartato.
     let commitSnap;
@@ -649,9 +649,9 @@ function createLiveBridge({
     };
     threadIdsByCell.set(snap.hostCell, started.threadId);
     threadStatusCache.delete(snap.hostCell);
-    // LC1.4: il puntamento è visibile lato nostro — log con cella, thread e
+    // Il puntamento è visibile lato nostro — log con cella, thread e
     // prompt applicato. È il "dirottamento dichiarato" del contratto. Il
-    // campo SOSTITUISCE le developer instructions della config (MC2, la
+    // Campo SOSTITUISCE le developer instructions della config (la
     // .or() in config/mod.rs): il log lo dichiara, perché chi lo legge sappia
     // cosa quella Live NON riceve.
     log(`[live-bridge] Live puntata su ${snap.hostCell}: thread ${started.threadId} (cwd ${started.cwd}, identità nell'intestazione, prompt ${prompt.applied ? 'per-cella applicato' : `non applicato (${promptEcho.reason})`}, sostituisce le developer instructions di config)`);

package/lib/live-host/routes.js

@@ -10,7 +10,7 @@
 // chiede. Senza quel permesso il peer riceve un rifiuto che nomina la causa
 // (`live-host-not-granted`), non un silenzio.
 //
-// Invarianti (contratto rev6 §2, §9):
+// Invariants (host-cell designation contract):
 //   - hostCell unico per nodo, CAS su revision (due designazioni concorrenti non
 //     lasciano due celle rosse).
 //   - API-first: la route e' l'unica autorita'; il frontend riflette la risposta e
@@ -336,7 +336,7 @@ function liveHostRoutes({ fleetP, store, readonly = () => false, now = () => Dat
       const result = await bridge.resolveForLive();
       res.json(result);
     } catch (e) {
-      // Il contratto (MC1.5) vuole che un guasto del ponte non fermi la Live:
+      // Il contratto vuole che un guasto del ponte non fermi la Live:
       // anche l'inaspettato collassa in `none` dichiarato, mai un 500.
       // `bridge-error` e' l'ultima rete: un'eccezione che nessun ramo previsto ha
       // classificato. Va NOMINATA come le altre, non lasciata fuori dall'elenco

package/lib/live-host/store.js

@@ -1,10 +1,10 @@
 'use strict';
 // lib/live-host/store.js — stato della designazione "cella ospite Live" di un nodo.
 //
-// Un solo hostCell per nodo (contratto rev6 §2.2): chiave unica, non una convenzione
-// ripetuta in N punti. Lo stato vive su disco (sopravvive a riavvii di cella e di
-// NexusCrew) e l'aggiornamento e' un CAS su `revision`: due designazioni concorrenti
-// non possono lasciare due celle rosse — il perdente rilegge la revision e rinuncia.
+// One hostCell per node (unique key, not a repeated convention):
+// the state lives on disk (survives cell and NexusCrew restarts) and the
+// update is a CAS on `revision`: two concurrent designations cannot leave
+// two red cells — the loser re-reads the revision and gives up.
 //
 // La designazione e' PURAMENTE un marker di scelta del nodo. L'eligibilita' (la cella
 // e' anche attiva in questo momento?) e' derivata dal roster Fleet e non si persiste

package/lib/mcp/server.js

@@ -81,12 +81,12 @@ function companionInstructions() {
 }
 
 // --- identita' cella mittente ------------------------------------------------
-// Ordine delle sorgenti (design §1, INVARIATO): $TMUX presente -> tmux
-// display-message (nome sessione reale); se fallisce/invalida -> fallback env
-// NEXUSCREW_MCP_SESSION; altrimenti null. I tool che RICHIEDONO la sessione
-// restano fail-closed. execFile argv diretto: mai shell.
+// Source order (UNCHANGED): $TMUX present -> tmux display-message (real
+// session name); if it fails/is invalid -> env fallback NEXUSCREW_MCP_SESSION;
+// otherwise null. The tools that REQUIRE the session stay fail-closed.
+// execFile direct argv: never a shell.
 //
-// P0: il nome da tmux si chiede con `-t $TMUX_PANE` — target esplicito al
+// Il nome da tmux si chiede con `-t $TMUX_PANE` — target esplicito al
 // PANE del chiamante, deterministico e indipendente dall'environ ereditato.
 // Senza `-t` il CLI tmux risolve il pane dall'ENVIRON DEL PROCESSO FIGLIO:
 // se quel pane è vivo risponde correttamente, ma se è morto (environ stale,
@@ -95,7 +95,7 @@ function companionInstructions() {
 // Comportamento misurato su tmux 3.4 con `-t`: pane morto -> rc=0 e stdout
 // VUOTO (non un errore): il vuoto è il segnale dello stantio.
 //
-// `resolveIdentity` rende OSSERVABILE la sorgente della risoluzione (P0):
+// `resolveIdentity` rende OSSERVABILE la sorgente della risoluzione:
 // ritorna { session, source, code, envPresence, requiredEnvVars, remediation }
 // senza cambiare la precedenza e senza esporre valori/segreti. `resolveSession`
 // resta il wrapper pubblico Promise<string|null> invariato (compatibilita').
@@ -174,13 +174,13 @@ function resolveIdentity({ env, tmuxBin, execFileImpl }) {
     session: null, source: 'missing', code: codeWhenMissing(),
     envPresence, requiredEnvVars: IDENTITY_ALL_REQUIRED_ENV_VARS, remediation: IDENTITY_REMEDIATION,
   });
-  // P0: pane stantio o non verificabile -> NON attribuire. source 'stale-pane'
+  // Pane stantio o non verificabile -> NON attribuire. source 'stale-pane'
   // nomina il problema; code STALE_PANE (tools.js).
   const stalePane = () => ({
     session: null, source: 'stale-pane', code: IDENTITY_CODE.STALE_PANE,
     envPresence, requiredEnvVars: IDENTITY_ALL_REQUIRED_ENV_VARS, remediation: IDENTITY_REMEDIATION,
   });
-  // P0/R2: tmux e fallback env dicono sessioni DIVERSE entrambe valide:
+  // : tmux e fallback env dicono sessioni DIVERSE entrambe valide:
   // identità ambigua -> NON attribuire (nemmeno il fallback: è parte del
   // conflitto). Il code nomina il mismatch, che INVALID non direbbe.
   const sessionMismatch = () => ({
@@ -190,7 +190,7 @@ function resolveIdentity({ env, tmuxBin, execFileImpl }) {
 
   return new Promise((resolve) => {
     // Precedenza preservata: prima il fallback env valido, poi l'esito negativo
-    // dato (`missing` storico o `stalePane` P0).
+    // Dato (`missing` storico o `stalePane`).
     const settle = (otherwise) => {
       const fb = tryFallback();
       resolve(typeof fb === 'string' ? ok(fb, 'NEXUSCREW_MCP_SESSION') : otherwise());
@@ -217,13 +217,13 @@ function resolveIdentity({ env, tmuxBin, execFileImpl }) {
         // rc=0 e stdout VUOTO. Il vuoto è il segnale dello stantio.
         if (!name) return settle(stalePane);
         if (isValidSession(name)) {
-          // R2: se il fallback env è valido ma dice un'altra sessione, le due
+          // Se il fallback env è valido ma dice un'altra sessione, le due
           // fonti si contraddicono -> ambiguo, non si attribuisce.
           const fb = tryFallback();
           if (typeof fb === 'string' && fb !== name) return resolve(sessionMismatch());
           return resolve(ok(name, 'tmux'));
         }
-        // nome non vuoto ma invalido: precedenza preservata, come da design §1.
+        // non-empty but invalid name: precedence preserved, by design.
         settle(missing);
       });
     } catch (_) {
@@ -618,9 +618,9 @@ function startMcp(opts = {}) {
 
 module.exports = {
   createMcpServer, startMcp, resolveSession, resolveIdentity, normalizeIdentityContext, TOOLS,
-  // V-69: il ramo vl di resolveManagedEngine compone le istruzioni companion
-  // nel file di prompt per-cella — vl non ha client MCP, questo e' l'unica
-  // superficie attraverso cui il testo lo raggiunge.
+  // The vl branch of resolveManagedEngine composes the companion instructions
+  // into the per-cell prompt file — vl has no MCP client, this is the only
+  // surface through which the text reaches it.
   companionInstructions,
   PROTOCOL_FALLBACK, HTTP_TIMEOUT_MS, HTTP_TIMEOUT_CODE, HTTP_UNREACHABLE_CODE, transportError,
   IDENTITY_CONTEXT_MISSING, IDENTITY_CONTEXT_UNVERIFIED, IDENTITY_CONTEXT_FROM_MISMATCH,

package/lib/mcp/tools.js

@@ -30,7 +30,7 @@ function argString(args, key, { required = false, max = 4096 } = {}) {
   return v;
 }
 
-// Codici stabili di identita' MCP (contratto P0). Valori EXACT, non sensibili,
+// Codici stabili di identita' MCP (contratto). Valori EXACT, non sensibili,
 // usati sia nella diagnostica read-only (`nc_identity`) sia nel messaggio umano
 // dei tool identity-gated (isError=true preservato dal server). Non espongono
 // valori/env/sessioni: solo la categoria del problema.
@@ -38,10 +38,10 @@ const IDENTITY_CODE = Object.freeze({
   OK: 'OK',
   MISSING: 'NEXUSCREW_MCP_IDENTITY_MISSING',
   INVALID: 'NEXUSCREW_MCP_IDENTITY_INVALID',
-  // P0: il pane del chiamante non esiste più (o TMUX_PANE è assente/malformato):
+  // Il pane del chiamante non esiste più (o TMUX_PANE è assente/malformato):
   // l'identità non viene attribuita via tmux.
   STALE_PANE: 'NEXUSCREW_MCP_IDENTITY_STALE_PANE',
-  // P0/R2: tmux e NEXUSCREW_MCP_SESSION sono entrambi validi ma dicono sessioni
+  // : tmux e NEXUSCREW_MCP_SESSION sono entrambi validi ma dicono sessioni
   // diverse: identità ambigua, non si attribuisce nessuna delle due.
   SESSION_MISMATCH: 'NEXUSCREW_MCP_IDENTITY_SESSION_MISMATCH',
   // una fonte verified (NEXUSCREW_VERIFIED_*) presente ma non
@@ -303,7 +303,7 @@ function vlOwnerPath(owner, leaf = '') {
 }
 
 // --- definizione tool (prefisso nc_ anti-collisione) ---------------------------
-// annotations.readOnlyHint:true sui tool che non mutano nulla (§1).
+// annotations.readOnlyHint:true on the tools that mutate nothing.
 const TOOLS = [
   {
     name: 'nc_notify',
@@ -920,7 +920,7 @@ const TOOLS = [
       return { receipt };
     },
   },
-  // --- lease Live del child (fetta 2b, contratto rev1 B5) ----------------------
+  // -- lease Live del child (fetta 2b, contratto rev1) ----------------------
   // Tre metodi DISTINTI perche' i valori di ritorno non mentono l'uno con l'altro:
   // solo register puo' rispondere {status:'pending'} (join non ancora tracciato);
   // refresh su registration viva risponde {status:'live', proof} e non ha stati

package/lib/nodes/access-presets.js

@@ -0,0 +1,258 @@
+'use strict';
+
+// Access presets for paired peers.
+//
+// A preset is a vector of grants written in ONE validated write on the node
+// that owns the resources. There is no persistent `role` field: the label
+// (`admin`, `user`, `nexushost`, `custom`, `unconfigured`) is DERIVED from the
+// effective grants, and request handlers check grants, never the label.
+//
+// The owner node decides what a peer may do with its own resources. A grant
+// that is missing or malformed is denied, and a record written before these
+// fields existed stays denied until an explicit migration sets them: being
+// paired is not, by itself, a permission.
+
+const MAX_CELLS = 128;
+const CELL_ID_RE = /^[A-Za-z0-9._-]{1,32}$/;
+
+const CELL_VISIBILITY = Object.freeze(['all', 'selected', 'none']);
+
+// Grants owned by the local node towards one peer.
+const BOOLEAN_GRANTS = Object.freeze([
+  'eventsAccess',
+  'nodeEventsAccess',
+  'askReplyAccess',
+  'filesReadAccess',
+  'liveHostAccess',
+  'panelAccess',
+  'peerOperatorAccess',
+]);
+
+// `eventsReceive` is the receiving client's local choice, so it is excluded
+// from every preset: applying a preset never toggles who receives events.
+const EXCLUDED_GRANTS = Object.freeze(['eventsReceive']);
+
+const GRANT_FIELDS = Object.freeze(['cellVisibility', 'cells', ...BOOLEAN_GRANTS]);
+
+// Provenance marker of an explicitly configured vector. It is not a grant and
+// never a role: it only separates "set on purpose" from "defaulted".
+const CONFIGURED_MARKER = 'accessConfigured';
+
+const ADMIN_GRANTS = Object.freeze({
+  cellVisibility: 'all',
+  eventsAccess: true,
+  nodeEventsAccess: true,
+  askReplyAccess: true,
+  filesReadAccess: true,
+  liveHostAccess: true,
+  panelAccess: true,
+  peerOperatorAccess: true,
+});
+
+const USER_GRANTS = Object.freeze({
+  cellVisibility: 'all',
+  eventsAccess: true,
+  nodeEventsAccess: true,
+  askReplyAccess: false,
+  filesReadAccess: true,
+  liveHostAccess: false,
+  panelAccess: false,
+  peerOperatorAccess: false,
+});
+
+const NEXUSHOST_GRANTS = Object.freeze({
+  cellVisibility: 'none',
+  eventsAccess: false,
+  nodeEventsAccess: false,
+  askReplyAccess: false,
+  filesReadAccess: false,
+  liveHostAccess: false,
+  panelAccess: false,
+  peerOperatorAccess: false,
+});
+
+const PRESETS = Object.freeze({
+  admin: ADMIN_GRANTS,
+  user: USER_GRANTS,
+  nexushost: NEXUSHOST_GRANTS,
+});
+
+const PRESET_NAMES = Object.freeze(Object.keys(PRESETS));
+
+// Every grant denied: what an unknown peer gets.
+const DENIED_GRANTS = Object.freeze({
+  cellVisibility: 'none',
+  ...Object.fromEntries(BOOLEAN_GRANTS.map((k) => [k, false])),
+});
+
+function isPlainObject(v) {
+  return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+
+function isCellId(v) {
+  return typeof v === 'string' && CELL_ID_RE.test(v);
+}
+
+// The admin vector is all-or-nothing: live hosting is an administrative act
+// on the owner's own host, so it is granted only together with the complete
+// admin set. A granular edit that keeps live hosting while dropping any other
+// admin grant is refused.
+function isCompleteAdminVector(g) {
+  if (!isPlainObject(g)) return false;
+  if (g.cellVisibility !== 'all') return false;
+  if (Array.isArray(g.cells) && g.cells.length !== 0) return false;
+  return BOOLEAN_GRANTS.every((k) => g[k] === true);
+}
+
+// Validates a grant vector. Returns { ok, errors }: `ok` means the vector is
+// complete and coherent, so a label may be derived from it. A vector that is
+// not ok is DENIED by callers; it is never completed with defaults.
+function validateGrants(input) {
+  const errors = [];
+  if (!isPlainObject(input)) {
+    return { ok: false, errors: ['grants must be an object'] };
+  }
+  for (const key of Object.keys(input)) {
+    if (key === 'role') {
+      errors.push('role is not a grant: the label is derived from the grants');
+    } else if (EXCLUDED_GRANTS.includes(key)) {
+      errors.push(`${key} is a local client choice and is not part of a preset`);
+    } else if (!GRANT_FIELDS.includes(key)) {
+      errors.push(`unknown grant field: ${key}`);
+    }
+  }
+
+  if (!CELL_VISIBILITY.includes(input.cellVisibility)) {
+    errors.push('cellVisibility must be one of all|selected|none');
+  }
+
+  let cells = [];
+  if (input.cells !== undefined) {
+    if (!Array.isArray(input.cells)) {
+      errors.push('cells must be an array');
+    } else if (input.cells.length > MAX_CELLS) {
+      errors.push(`cells must hold at most ${MAX_CELLS} entries`);
+    } else if (!input.cells.every(isCellId)) {
+      errors.push('cells entries must be cell names');
+    } else if (new Set(input.cells).size !== input.cells.length) {
+      errors.push('cells must not repeat an entry');
+    } else {
+      cells = input.cells;
+    }
+  }
+  if (input.cellVisibility === 'selected' && cells.length === 0) {
+    errors.push('cellVisibility selected needs at least one cell');
+  }
+  if ((input.cellVisibility === 'all' || input.cellVisibility === 'none') && cells.length > 0) {
+    errors.push('cells are allowed only with cellVisibility selected');
+  }
+
+  for (const key of BOOLEAN_GRANTS) {
+    if (!(key in input)) errors.push(`missing grant: ${key}`);
+    else if (typeof input[key] !== 'boolean') errors.push(`grant must be a boolean: ${key}`);
+  }
+
+  if (input.liveHostAccess === true && !isCompleteAdminVector(input)) {
+    errors.push('liveHostAccess requires the complete admin grant set');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+// A record is configured only when its grant vector is complete and coherent.
+// Records written before these fields existed, or damaged ones, are denied.
+function isConfigured(input) {
+  return validateGrants(input).ok;
+}
+
+function sameBooleans(a, b) {
+  return BOOLEAN_GRANTS.every((k) => a[k] === b[k]);
+}
+
+// Derives the label from the effective grants. `custom` means a coherent
+// vector that matches no preset; `unconfigured` means the vector is not
+// complete, so no preset may be inferred from it.
+function deriveLabel(input) {
+  if (!isConfigured(input)) return 'unconfigured';
+  if (sameBooleans(input, ADMIN_GRANTS) && input.cellVisibility === 'all') return 'admin';
+  if (sameBooleans(input, NEXUSHOST_GRANTS) && input.cellVisibility === 'none') return 'nexushost';
+  // The owner may narrow the visible cells of a user peer without granting
+  // anything new, so any of the three visibility values still reads `user`.
+  if (sameBooleans(input, USER_GRANTS) && CELL_VISIBILITY.includes(input.cellVisibility)) return 'user';
+  return 'custom';
+}
+
+// Returns a copy of the peer record with the grants of the named preset.
+// The input is never mutated; `role` is dropped, because it is not a field
+// that this model persists.
+function applyPreset(peer, name) {
+  if (!isPlainObject(peer)) throw new Error('peer must be an object');
+  if (!Object.prototype.hasOwnProperty.call(PRESETS, name)) {
+    throw new Error(`unknown preset: ${name}`);
+  }
+  const out = { ...peer };
+  delete out.role;
+  const preset = PRESETS[name];
+  // Applying a preset IS the explicit act: the record is marked as configured
+  // so a legacy peer with defaulted (denied) grants is never mistaken for a
+  // deliberate vector that denies everything.
+  out.accessConfigured = true;
+  out.cellVisibility = preset.cellVisibility;
+  if (preset.cellVisibility === 'selected') out.cells = [...(preset.cells || [])];
+  else delete out.cells;
+  for (const key of BOOLEAN_GRANTS) out[key] = preset[key];
+  return out;
+}
+
+// Extracts the grant vector from a peer record. An unconfigured record yields
+// every grant denied.
+function grantsOf(peer) {
+  if (!isPlainObject(peer)) return { configured: false, label: 'unconfigured', grants: { ...DENIED_GRANTS } };
+  const grants = {};
+  grants.cellVisibility = peer.cellVisibility;
+  if (peer.cells !== undefined) grants.cells = peer.cells;
+  for (const key of BOOLEAN_GRANTS) grants[key] = peer[key];
+  // A record is configured only when its vector is coherent AND the vector was
+  // set explicitly. Grants alone cannot tell a legacy record (everything
+  // defaulted to denied) from a deliberate vector that denies everything.
+  const configured = peer.accessConfigured === true && isConfigured(grants);
+  return {
+    configured,
+    label: configured ? deriveLabel(grants) : 'unconfigured',
+    grants: configured ? grants : { ...DENIED_GRANTS },
+  };
+}
+
+
+// Read view of ONE peer for listing endpoints and the settings UI: the
+// derived label, the configured marker and the EFFECTIVE grant vector. The
+// vector is flat and always complete (denied for records that are not
+// configured), so a caller never has to guess defaults and no token or
+// secret is ever included: grants are decisions, not credentials.
+function accessView(peer) {
+  const view = grantsOf(peer);
+  const access = { cellVisibility: view.grants.cellVisibility };
+  for (const key of BOOLEAN_GRANTS) access[key] = view.grants[key] === true;
+  return { accessLabel: view.label, accessConfigured: view.configured, access };
+}
+
+module.exports = {
+  ADMIN_GRANTS,
+  BOOLEAN_GRANTS,
+  CELL_VISIBILITY,
+  CONFIGURED_MARKER,
+  DENIED_GRANTS,
+  EXCLUDED_GRANTS,
+  GRANT_FIELDS,
+  NEXUSHOST_GRANTS,
+  PRESETS,
+  PRESET_NAMES,
+  USER_GRANTS,
+  accessView,
+  applyPreset,
+  deriveLabel,
+  grantsOf,
+  isCompleteAdminVector,
+  isConfigured,
+  validateGrants,
+};