@mmmbuto/nexuscrew 0.9.28 → 0.9.30

package/lib/settings/routes.js

@@ -1,21 +1,21 @@
 'use strict';
-// lib/settings/routes.js — Settings API per wizard/settings UI (design §4b(6), B2).
+// lib/settings/routes.js — Settings API for the wizard/settings UI.
 //
 // Contratto duro:
 //   - read-only: GET /api/settings (roles, firstRun, port, platform, service,
 //     version).
-//   - mutanti (LISTA CHIUSA §4b(6)), tutti dietro requireToken (montati sotto il
-//     router /api gia' autenticato) + gate READONLY route-level (pattern
-//     lib/fleet/routes.js, 403 esplicito):
+//   - mutators (CLOSED LIST), all behind requireToken (mounted under the
+//     already-authenticated /api router) + route-level READONLY gate
+//     (lib/fleet/routes.js pattern, explicit 403):
 //       POST   /config             scrittura config.json ATOMICA (whitelist chiavi)
-//       POST   /token/rotate       riusa rotateToken(); token MAI in risposta (§4b(3))
+//       POST   /token/rotate       reuses rotateToken(); token NEVER in the response
 //       POST   /nodes              nodes add (riusa lib/nodes/commands.js)
 //       DELETE /nodes/:name        nodes remove
 //       PATCH  /nodes/:name/share publish/revoke the local node on its hub
 //       POST   /node-role          retired compatibility endpoint (410)
 //       POST   /service/regenerate rigenera unit service (NO restart automatico)
 //   - NON gate READONLY (lifecycle di PROCESSO, non mutazione di config — decisione
-//     B0 documentata in lib/nodes/commands.js: READONLY blocca le mutazioni di
+// Documentata in lib/nodes/commands.js: READONLY blocca le mutazioni di
 //     config, non up/down/restart dei tunnel):
 //       POST /nodes/:name/test     non-mutante (POST per coerenza azione)
 //       POST /nodes/:name/up|down|restart
@@ -28,15 +28,15 @@
 //     403 readonly, 404 nodo, 409 conflitto, 500 con messaggio). Niente stack trace.
 //   - validazione input strict fail-closed: schema chiuso per ogni body, garbage
 //     -> 400 con causa, mai guess.
-//   - NIENTE reimplementazione della logica B0: i mutanti nodes incapsulano le
+// NIENTE reimplementazione della logica: i mutanti nodes incapsulano le
 //     funzioni CLI di lib/nodes/commands.js (log catturato per estrarre l'esito);
 //     config.json scritto col pattern atomico
 //     tmp+rename di lib/nodes/store.js.
 //
 // Nota lifecycle: i tunnel avviati da /nodes/:name/up sono spawn DETACHED+unref
 // con pidfile (lib/nodes/tunnel.js): non restano figli dell'handler HTTP; il
-// commento B0 "mai spawn dalla superficie web" e' superato per B2 da questo
-// contratto esplicito (§4b(6): "restart processi tunnel" e' mutazione ammessa).
+// Commento "mai spawn dalla superficie web" e' superato per da questo
+// explicit contract ("restart tunnel processes" is an allowed mutation).
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
@@ -69,11 +69,17 @@ const { scrubError } = require('../update/core.js');
 const { createPairHandler } = require('./pairing-coordinator.js');
 const { publicPeeringRoutes } = require('./public-peering-routes.js');
 
-// Whitelist chiavi scrivibili di config.json via API (lista chiusa dal task B2).
+// Whitelist chiavi scrivibili di config.json via API (lista chiusa dal task).
 const CONFIG_KEYS = new Set(['roles', 'port', 'wizardDone', 'autoUpdate', 'alternateScreen']);
 const ROLE_KEYS = new Set(['client', 'node']);
 const ADD_KEYS = new Set(['name', 'ssh', 'sshPort', 'remotePort', 'localPort', 'keyPath', 'label']);
-const EDIT_KEYS = new Set(['label', 'ssh', 'sshPort', 'autostart', 'visibility', 'selected', 'cellVisibility', 'cells']);
+const EDIT_KEYS = new Set([
+  'label', 'ssh', 'sshPort', 'autostart', 'visibility', 'selected', 'cellVisibility', 'cells',
+  // Federated access: `accessRole` applies a preset, the granular keys refine an
+  // explicitly set vector, and `accessRevision` makes the write a compare-and-set.
+  // A `role` key is NOT here: a declared role is refused instead of being stored.
+  'accessRole', 'accessRevision', 'eventsAccess', 'nodeEventsAccess', 'askReplyAccess', 'filesReadAccess', 'peerOperatorAccess',
+]);
 const LOCAL_AUDIO_TEST_TEXT = 'NexusCrew audio test.';
 
 // Default sensato per il "nome dispositivo" proposto nei form (pairing/invite).
@@ -86,7 +92,7 @@ function defaultDeviceName(hostname = os.hostname()) {
   return h.slice(0, nodesStore.LABEL_MAX);
 }
 
-// Cintura §4b(3): rimozione ricorsiva di ogni chiave `token` da QUALUNQUE payload
+// Belt: recursive removal of every `token` key from ANY response
 // di risposta (la vista redatta espone hasToken, mai il valore). Difesa in
 // profondita' oltre a redactStore: anche un bug a monte non fa uscire il segreto.
 function deepScrubTokens(v) {
@@ -204,9 +210,9 @@ function settingsRoutes(deps = {}) {
   });
 
   const validName = (name) => typeof name === 'string' && nodesStore.NODE_NAME_RE.test(name);
-  const applyNodeEdit = (res, name, patch) => {
+  const applyNodeEdit = (res, name, patch, extra = {}) => {
     const cap = capture();
-    const out = nodesCmds.nodesEdit({ ...cliOpts(cap), ref: name, patch });
+    const out = nodesCmds.nodesEdit({ ...cliOpts(cap), ref: name, patch, ...extra });
     if (out.code === 0) return send(res, 200, {
       saved: true, name: out.name, node: out.node, restarted: out.restarted === true,
     });
@@ -216,6 +222,9 @@ function settingsRoutes(deps = {}) {
     if (out.reason === 'store invalido') {
       return send(res, out.status || 503, { error: message, ...(out.errorCode ? { code: out.errorCode } : {}) });
     }
+    if (out.reason === 'revision-conflict') {
+      return send(res, 409, { error: message, revision: out.revision });
+    }
     const status = out.reason === 'write-or-restart-failed' ? 502 : 400;
     return send(res, status, { error: message });
   };
@@ -359,10 +368,10 @@ function settingsRoutes(deps = {}) {
   });
 
   // --- POST /token/rotate — atomico + reload live + chiusura WS; token MAI in risposta
-  // Contratto §4b(3): "scrittura atomica del token file + chiusura delle sessioni
-  // WS/API attive locali + reload credenziali proxy". Da revisione: prima questa route
-  // scriveva solo il file, e il server teneva il VECCHIO token in memoria -> restava
-  // accettato fino al restart manuale. Ora: (1) scrittura atomica, (2) reload live
+  // Contract: "atomic write of the token file + closing of the active local
+  // WS/API sessions + proxy credential reload". From review: before, this route
+  // only wrote the file, and the server kept the OLD token in memory -> it stayed
+  // accepted until a manual restart. Now: (1) atomic write, (2) live reload
   // dell'holder in memoria (requireToken/verify vedono il nuovo), (3) chiusura delle
   // sessioni WS long-lived (autenticate solo all'upgrade). Il nuovo token NON trapela
   // mai: rotateToken() lo ritorna ma il valore viene SCARTATO, e reload() non lo espone.
@@ -527,7 +536,11 @@ function settingsRoutes(deps = {}) {
     }
     const invalid = Object.keys(body).find((key) => !EDIT_KEYS.has(key));
     if (invalid) return send(res, 400, { error: `campo non modificabile: "${invalid}"` });
-    return applyNodeEdit(res, name, body);
+    if (Object.hasOwn(body, 'accessRevision') && !Number.isInteger(body.accessRevision)) {
+      return send(res, 400, { error: 'accessRevision vuole un intero' });
+    }
+    const { accessRevision, ...patch } = body;
+    return applyNodeEdit(res, name, patch, { expectedRevision: accessRevision });
   });
 
   // --- POST /nodes/:name/test — non-mutante (POST per coerenza azione) -------
@@ -548,11 +561,11 @@ function settingsRoutes(deps = {}) {
   });
 
   // --- POST /nodes/:name/up|down|restart — lifecycle tunnel ------------------
-  // GATE READONLY (da revisione, contract §4b(6): "restart processi tunnel" e' tra i
-  // mutanti della lista chiusa e NEXUSCREW_READONLY blocca TUTTI i mutanti). Prima
-  // questi endpoint erano esplicitamente NON gated ("decisione B0") — ma cio'
-  // contradiceva il contratto duro §4b(6): up/down/restart mutano processi e vanno
-  // bloccati in READONLY. /nodes/:name/test resta NON gated (probe diagnostica).
+  // READONLY gate (tunnel process restart is among the mutators of the
+  // closed list and NEXUSCREW_READONLY blocks ALL of them). Before, these
+  // Endpoints were explicitly NOT gated (" decision") — but that contradicted
+  // the hard contract: up/down/restart mutate processes and must be blocked
+  // in READONLY. /nodes/:name/test stays NOT gated (diagnostic probe).
   function lifecycleHandler(action) {
     return (req, res) => {
       try {
@@ -771,10 +784,10 @@ function settingsRoutes(deps = {}) {
         await notifyHub(true);
         return send(res, 200, { name, shared: true });
       }
-      // OFF e' fail-safe e crash-durevole (design piano §3.2): persist desired
-      // false -> revoke autenticata sul canale -L ancora vivo -> restart locale
-      // senza -R. MAI restart-before-revoke: il -L e' il canale stesso della
-      // revoca, e un crash prima dell'ACK non puo' mai ripubblicare da intent
+      // OFF is fail-safe and crash-durable: persist desired
+      // false -> authenticated revoke on the still-live -L channel -> local restart
+      // without -R. NEVER restart-before-revoke: the -L is the very channel of
+      // the revocation, and a crash before the ACK can never republish by intent.
       // stale (il file dice gia' false; il boot riparte -L only + reconcile).
       // 1) persist desired false (snapshot dei soli campi gia' validati).
       st = nodesStore.loadStoreStrict(nodesPath);
@@ -928,7 +941,7 @@ function settingsRoutes(deps = {}) {
       return send(res, 400, { error: 'body non valido: attesi targets e mode' });
     }
     try { return send(res, 200, { group: audioGroups.saveGroup(audioCfg, String(req.params.name || ''), body, home) }); }
-    // R31-A4: il catch nudo raccontava QUALUNQUE errore come «gruppo non
+    // : il catch nudo raccontava QUALUNQUE errore come «gruppo non
     // valido» (400): un EACCES/ENOSPC sulla scrittura di audio-groups.json
     // finiva letto come colpa del nome. La validazione arriva dal modulo con
     // status 400 + code chiuso; tutto il resto — scrittura fallita compresa —
@@ -941,7 +954,7 @@ function settingsRoutes(deps = {}) {
       const removed = audioGroups.removeGroup(audioCfg, String(req.params.name || ''), home);
       return removed ? send(res, 200, { removed: true }) : send(res, 404, { error: 'gruppo audio non trovato' });
     } catch (e) {
-      // R31-A4: come PUT sopra — vedi il commento lì.
+      // : come PUT sopra — vedi il commento lì.
       return send(res, e.status || 500, { error: scrubError(e), ...(e.code ? { code: e.code } : {}) });
     }
   });
@@ -987,7 +1000,7 @@ function settingsRoutes(deps = {}) {
   // --- POST /service/regenerate — rigenera l'unit service --------------------
   // Riusa generateService/installService (lib/cli/service.js: escaping per-platform,
   // no-symlink, tmp+rename atomico). activate:false registra il piano di attivazione
-  // SENZA eseguirlo: il contratto B2 vieta il restart automatico dall'API
+  // SENZA eseguirlo: il contratto vieta il restart automatico dall'API
   // (la UI avvisa di riavviare a mano).
   r.post('/service/regenerate', mutGate, (_req, res) => {
     try {
@@ -1003,7 +1016,7 @@ function settingsRoutes(deps = {}) {
         uid: seams.uid || uid(),
         installPath: seams.serviceInstallPath,
       };
-      // 1-bis (R23): come in init — il path del boot si risolve alla
+      // 1-bis: come in init — il path del boot si risolve alla
       // scrittura e cio' che non ha alias stabile torna DICHIARATO. Le
       // warnings sono DATI nella risposta, non testo composto qui.
       const svcBoot = resolveBootPaths({

package/lib/update/manager.js

@@ -100,7 +100,7 @@ function createNpmUpdater(opts = {}) {
       supported, enabled, current: currentVersion,
       phase: state.phase || 'idle', latest: state.latest || '',
       available: state.available === true && isNewer(state.latest, currentVersion),
-      // R31: `idle` di DEFAULT (stato mai scritto) e `idle` DOPO un check
+      // `idle` di DEFAULT (stato mai scritto) e `idle` DOPO un check
       // senza novita' coincidono — e la UI narrava «aggiornato» in entrambi.
       // `checked` deriva da lastCheckedAt, che viene scritto a OGNI check
       // (riuscito o fallito): chi legge distingue «mai controllato» (ignoranza)

package/lib/update/runner.js

@@ -19,7 +19,7 @@ const {
 // `nexuscrew init` — resta puntata a un binario che non esiste più, con exit
 // 78 EX_CONFIG e le celle boot:true mute (misurato sul campo 2026-08-18).
 //
-// Il criterio R23 resta intatto («alias stabile che realpath allo stesso
+// Il criterio resta intatto («alias stabile che realpath allo stesso
 // file», verificato alla SCRITTURA, mai a ogni avvio) con una estensione
 // dichiarata per il caso del runner: il processo dell'update può girare con
 // un node già unlinkato su disco, e in quel caso si sceglie il primo percorso

package/lib/voice/transcribe.js

@@ -1,6 +1,6 @@
 'use strict';
 // Voice STT proxy (graceful). voiceUrl null => non configurato: 503 pulito, non 502.
-// Web Speech nel browser resta indipendente da questo proxy (split model M5).
+// Web Speech nel browser resta indipendente da questo proxy (split model).
 const fs = require('node:fs');
 
 function loadVoiceToken(cfg) {

package/lib/ws/bridge.js

@@ -242,8 +242,8 @@ function bindWs(ws, deps) {
         // readonlyDefault del server e' un PAVIMENTO, non un default: se il server
         // e' READONLY nessun client puo' declassarlo (msg.readonly:false non deve
         // vincere). Il client puo' solo AGGIUNGERE restrizione (attach read-only
-        // su un server read-write). Contratto design §4b(6): READONLY blocca anche
-        // le scritture PTY. (fix da revisione finale: prima il ?? faceva vincere il client.)
+        // on a read-write server). Design contract: READONLY also blocks
+        // PTY writes. (final-review fix: before, the ?? let the client win.)
         readonly: defaults.readonlyDefault === true || !!msg.readonly,
         takeSize,
         cols: clamp(msg.cols, 20, 300, 80),
@@ -289,7 +289,7 @@ function bindWs(ws, deps) {
     if (msg.type === 'resize') record.pty.resize(clamp(msg.cols, 20, 300, 80), clamp(msg.rows, 5, 120, 24));
     // focus: il tile che prende il focus diventa size-owner (promote); perdendolo
     // torna ignore-size (demote). Cosi' N deck/tile sulla stessa sessione NON si
-    // contendono la geometria: comanda solo chi ha il focus (§5b size policy).
+    // contend for geometry: only the focused tile commands it (size policy).
     else if (msg.type === 'focus') { if (msg.on) record.pty.promote(); else record.pty.demote(); }
     else if (msg.type === 'input' && !record.readonly) record.pty.write(typeof msg.data === 'string' ? msg.data : '');
     else if (msg.type === 'key' && !record.readonly) record.pty.write(typeof msg.seq === 'string' ? msg.seq.slice(0, 64) : '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.9.28",
+  "version": "0.9.30",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {

package/skills/live/SKILL.md

@@ -33,6 +33,18 @@ read from the roster and the designated cell's lease state
 (`live`/`grace`/`expired`/`none`/`unavailable`) — a designated-but-not-eligible
 host is a distinct, readable state, not an error to explain away.
 
+## The rule is per node — and the cell may live on another node
+
+One host cell **per node** is the rule, and it keeps holding when the designated
+cell belongs to a peer: the node serving the page keeps the pointer locally
+(`ownerId` plus the owner's own `revision`, and `remote: true` on `GET`) and
+forwards the bridge resolution to the owner instead of resolving it locally.
+The caller still chooses nothing — the designation is the choice, and it can now
+point off-node. An unreachable owner, or a peer that was never granted
+`liveHostAccess`, is a **named** outcome (`live-host-owner-unreachable`,
+`live-host-not-granted`), never a silent fallback to a local cell. `clear`
+removes the pointer on both sides.
+
 ## Command the node that owns the cell, not the one serving the page
 
 This is the point of the feature: **the request must reach the node whose