@mmmbuto/nexuscrew 0.7.6 → 0.8.0

package/lib/settings/routes.js

@@ -0,0 +1,473 @@
+'use strict';
+// lib/settings/routes.js — Settings API per wizard/settings UI (design §4b(6), B2).
+//
+// Contratto duro:
+//   - read-only: GET /api/settings (roles, firstRun, port, platform, service,
+//     rendezvous redatto, 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):
+//       POST   /config             scrittura config.json ATOMICA (whitelist chiavi)
+//       POST   /token/rotate       riusa rotateToken(); token MAI in risposta (§4b(3))
+//       POST   /nodes              nodes add (riusa lib/nodes/commands.js)
+//       DELETE /nodes/:name        nodes remove
+//       POST   /node-role          node on/off (rendezvous config)
+//       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
+//     config, non up/down/restart dei tunnel):
+//       POST /nodes/:name/test     non-mutante (POST per coerenza azione)
+//       POST /nodes/:name/up|down|restart
+//
+// Invarianti:
+//   - token MAI in risposta: ogni payload passa da deepScrubTokens() (cintura oltre
+//     alla redazione a monte via redactStore); rotateToken() ritorna il nuovo token
+//     ma il valore viene SCARTATO, mai serializzato.
+//   - failure esplicite: {error:'causa precisa'} con status coerente (400 input,
+//     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/node-role
+//     incapsulano le funzioni CLI di lib/nodes/commands.js (log catturato per
+//     estrarre esito/authorized_keys); 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).
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const express = require('express');
+
+const nodesStore = require('../nodes/store.js');
+const nodesCmds = require('../nodes/commands.js');
+const { rotateToken } = require('../auth/token.js');
+const { generateService, installService, installPath: svcInstallPath } = require('../cli/service.js');
+const { detectPlatform, nodeBin, repoRoot, uid } = require('../cli/platform.js');
+const { isServiceRunning, readRoles } = require('../cli/commands.js');
+const { configJsonPath } = require('../config.js');
+const VERSION = require('../../package.json').version;
+
+// Whitelist chiavi scrivibili di config.json via API (lista chiusa dal task B2).
+const CONFIG_KEYS = new Set(['roles', 'port', 'wizardDone']);
+const ROLE_KEYS = new Set(['client', 'node']);
+const ADD_KEYS = new Set(['name', 'ssh', 'remotePort', 'localPort', 'keyPath']);
+const NODE_ROLE_KEYS = new Set(['enabled', 'rendezvousSsh', 'publishedPort', 'keyPath']);
+
+// Cintura §4b(3): rimozione ricorsiva di ogni chiave `token` da QUALUNQUE payload
+// 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) {
+  if (Array.isArray(v)) return v.map(deepScrubTokens);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const [k, val] of Object.entries(v)) {
+      if (k === 'token') continue;
+      out[k] = deepScrubTokens(val);
+    }
+    return out;
+  }
+  return v;
+}
+
+// Cattura il log delle funzioni CLI riusate: serve per estrarre la causa d'errore
+// precisa e la riga authorized_keys (che NON e' un segreto: pubkey con restrict).
+function capture() {
+  const lines = [];
+  return { lines, log: (s) => lines.push(String(s)) };
+}
+
+function lastLine(cap, fallback) {
+  return cap.lines.length ? cap.lines[cap.lines.length - 1] : fallback;
+}
+
+function authorizedKeysLine(cap) {
+  return cap.lines.find((l) => l.startsWith('restrict,')) || null;
+}
+
+// Scrittura ATOMICA di config.json: tmp stessa dir (suffisso random: due write
+// concorrenti nello stesso processo non collidono) -> chmod 0600 -> rename.
+// Stesso pattern hardening di lib/nodes/store.js (no-symlink incluso).
+function atomicWriteConfig(p, obj) {
+  try {
+    if (fs.lstatSync(p).isSymbolicLink()) {
+      throw new Error('refuse to write: config.json target e\' un symlink');
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  const dir = path.dirname(p);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.${path.basename(p)}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify(obj, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, p);
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch (_) { /* cleanup best-effort */ }
+    throw e;
+  }
+}
+
+// config.json corrente come oggetto ({} se assente/illeggibile) + flag esistenza.
+function readConfigFile(p) {
+  try {
+    const obj = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return { exists: true, cfg: (obj && typeof obj === 'object' && !Array.isArray(obj)) ? obj : {} };
+  } catch (_) { return { exists: false, cfg: {} }; }
+}
+
+function settingsRoutes(deps = {}) {
+  const cfg = deps.cfg || {};
+  const seams = cfg.settingsSeams || {};
+  // tokenStore/closeSessions iniettati da server.js per la semantica di invalidazione
+  // live (audit F7 / §4b(3)). Assenti nei test unitari puri su routes -> la rotazione
+  // scrive solo il file (come prima), senza reload in-memory.
+  const tokenStore = deps.tokenStore || null;
+  const closeSessions = deps.closeSessions || null;
+  const home = cfg.home || os.homedir();
+  const configDir = cfg.configDir || path.join(home, '.nexuscrew');
+  // configJsonPath() rispetta NEXUSCREW_CONFIG_FILE (stessa risoluzione di
+  // loadConfig): settings API e server DEVONO leggere/scrivere lo STESSO file —
+  // il fallback home-based divergeva dalla config del server nelle istanze
+  // isolate via env (bug trovato in audit: smoke test che scrivono la config reale).
+  const configPath = cfg.configPath || configJsonPath();
+  const nodesPath = deps.nodesPath || cfg.nodesPath || nodesStore.defaultNodesPath(home);
+  const tokenPath = cfg.tokenPath || path.join(configDir, 'token');
+  const platform = seams.platform || detectPlatform();
+
+  const r = express.Router();
+  r.use(express.json({ limit: '8kb' }));
+
+  const send = (res, status, payload) => res.status(status).json(deepScrubTokens(payload));
+
+  // Gate READONLY route-level (pattern lib/fleet/routes.js): PRIMA di qualunque
+  // dispatch verso le funzioni CLI. Vale per i soli mutanti di config/token/service.
+  const readonly = () => (cfg.readonlyDefault === true || process.env.NEXUSCREW_READONLY === '1');
+  const mutGate = (_req, res, next) => {
+    if (readonly()) return send(res, 403, { error: 'READONLY: mutazione settings bloccata' });
+    next();
+  };
+
+  // Opzioni comuni passate alle funzioni CLI riusate (path espliciti + seam test).
+  const cliOpts = (cap) => ({
+    home, configDir, configPath, nodesPath, log: cap.log,
+    keygen: seams.keygen, execFileImpl: seams.execFileImpl,
+    spawnImpl: seams.spawnImpl, sshBin: seams.sshBin, logFd: seams.logFd,
+    httpProbe: seams.httpProbe, sshVersion: seams.sshVersion,
+    spawnSyncImpl: seams.spawnSyncImpl,
+  });
+
+  const validName = (name) => typeof name === 'string' && nodesStore.NODE_NAME_RE.test(name);
+
+  // --- GET / — vista read-only per wizard/settings UI -----------------------
+  r.get('/', (_req, res) => {
+    try {
+      const { exists, cfg: fileCfg } = readConfigFile(configPath);
+      // firstRun: config.json assente O wizardDone non esplicitamente true
+      // (il wizard persiste wizardDone:true via POST /config a fine setup).
+      const firstRun = !exists || fileCfg.wizardDone !== true;
+      const svcPath = seams.serviceInstallPath || svcInstallPath(platform, home);
+      const service = {
+        installed: fs.existsSync(svcPath),
+        active: isServiceRunning({ platform, execImpl: seams.execImpl, uid: seams.uid, home }),
+      };
+      const out = {
+        roles: readRoles(configPath),
+        firstRun,
+        port: cfg.port,
+        platform,
+        service,
+        version: VERSION,
+      };
+      // rendezvous via redactStore (view sicura §4b(4)): non contiene token, ma
+      // la si prende comunque SOLO dalla vista redatta.
+      const st = nodesStore.loadStore(nodesPath);
+      if (st) {
+        const view = nodesStore.redactStore(st);
+        if (view.rendezvous) out.rendezvous = view.rendezvous;
+      }
+      send(res, 200, out);
+    } catch (e) { send(res, 500, { error: String(e.message || e) }); }
+  });
+
+  // --- POST /config — scrittura atomica, subset whitelisted ------------------
+  r.post('/config', mutGate, (req, res) => {
+    try {
+      const b = req.body;
+      if (!b || typeof b !== 'object' || Array.isArray(b)) {
+        return send(res, 400, { error: 'body deve essere un oggetto JSON' });
+      }
+      for (const k of Object.keys(b)) {
+        if (!CONFIG_KEYS.has(k)) return send(res, 400, { error: `chiave non ammessa: "${k}" (whitelist: roles, port, wizardDone)` });
+      }
+      if (Object.keys(b).length === 0) {
+        return send(res, 400, { error: 'nessuna chiave da scrivere (whitelist: roles, port, wizardDone)' });
+      }
+      if (b.roles !== undefined) {
+        if (!b.roles || typeof b.roles !== 'object' || Array.isArray(b.roles)) {
+          return send(res, 400, { error: 'roles deve essere un oggetto {client?, node?}' });
+        }
+        for (const k of Object.keys(b.roles)) {
+          if (!ROLE_KEYS.has(k)) return send(res, 400, { error: `roles: chiave non ammessa "${k}" (solo client, node)` });
+          if (typeof b.roles[k] !== 'boolean') return send(res, 400, { error: `roles.${k} deve essere boolean` });
+        }
+      }
+      if (b.port !== undefined && !nodesStore.isPort(b.port)) {
+        return send(res, 400, { error: 'port deve essere un intero 1..65535' });
+      }
+      if (b.wizardDone !== undefined && typeof b.wizardDone !== 'boolean') {
+        return send(res, 400, { error: 'wizardDone deve essere boolean' });
+      }
+
+      // merge sul config esistente (preserva le chiavi non gestite qui)
+      const { cfg: current } = readConfigFile(configPath);
+      const next = { ...current };
+      if (b.roles !== undefined) {
+        const prev = (current.roles && typeof current.roles === 'object') ? current.roles : {};
+        next.roles = { client: !!prev.client, node: !!prev.node, ...b.roles };
+      }
+      if (b.port !== undefined) next.port = b.port;
+      if (b.wizardDone !== undefined) next.wizardDone = b.wizardDone;
+      atomicWriteConfig(configPath, next);
+
+      const out = {
+        saved: true,
+        config: { roles: next.roles, port: next.port, wizardDone: next.wizardDone },
+      };
+      // Il server legge la porta SOLO allo startup: il cambio vale al prossimo
+      // restart (contratto dichiarato nella risposta, la UI avvisa).
+      if (b.port !== undefined && b.port !== cfg.port) {
+        out.note = 'la porta cambia al prossimo restart del service';
+      }
+      send(res, 200, out);
+    } catch (e) { send(res, 500, { error: String(e.message || e) }); }
+  });
+
+  // --- 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". Audit F7: 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
+  // 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.
+  r.post('/token/rotate', mutGate, (_req, res) => {
+    try {
+      rotateToken(tokenPath);
+      if (tokenStore && typeof tokenStore.reload === 'function') tokenStore.reload();
+      if (typeof closeSessions === 'function') closeSessions();
+      send(res, 200, {
+        rotated: true,
+        note: 'token ruotato: sessioni attive chiuse, vecchio token invalidato (401) — recupera il nuovo con `nexuscrew url`',
+      });
+    } catch (e) { send(res, 500, { error: String(e.message || e) }); }
+  });
+
+  // --- POST /nodes — nodes add (riusa nodesCmds.nodesAdd) --------------------
+  r.post('/nodes', mutGate, (req, res) => {
+    try {
+      const b = req.body;
+      if (!b || typeof b !== 'object' || Array.isArray(b)) {
+        return send(res, 400, { error: 'body deve essere un oggetto JSON' });
+      }
+      for (const k of Object.keys(b)) {
+        if (!ADD_KEYS.has(k)) return send(res, 400, { error: `chiave non ammessa: "${k}" (schema: name, ssh, remotePort?, localPort?, keyPath?)` });
+      }
+      if (!validName(b.name)) return send(res, 400, { error: 'name non valido (^[a-z0-9-]{1,32}$)' });
+      if (!nodesStore.parseSsh(b.ssh)) return send(res, 400, { error: 'ssh non valido (atteso user@host strict)' });
+      if (b.remotePort !== undefined && !nodesStore.isPort(b.remotePort)) {
+        return send(res, 400, { error: 'remotePort deve essere un intero 1..65535' });
+      }
+      if (b.localPort !== undefined && !nodesStore.isPort(b.localPort)) {
+        return send(res, 400, { error: 'localPort deve essere un intero 1..65535' });
+      }
+      if (b.keyPath !== undefined && !nodesStore.isAbsPath(b.keyPath)) {
+        return send(res, 400, { error: 'keyPath deve essere un path assoluto' });
+      }
+
+      const cap = capture();
+      const out = nodesCmds.nodesAdd({
+        ...cliOpts(cap),
+        name: b.name, ssh: b.ssh,
+        remotePort: b.remotePort, localPort: b.localPort, key: b.keyPath,
+      });
+      if (out.code === 0) {
+        return send(res, 200, {
+          added: true,
+          name: out.name,
+          remotePort: out.remotePort,
+          localPort: out.localPort,
+          // La riga authorized_keys NON e' un segreto: pubkey con restrict/permitopen.
+          authorizedKeys: authorizedKeysLine(cap),
+        });
+      }
+      const msg = lastLine(cap, 'nodes add fallito');
+      if (out.reason === 'readonly') return send(res, 403, { error: msg });
+      if (out.reason === 'add rifiutato') {
+        // duplicato/self-reference = conflitto (409); schema rifiutato = 400.
+        const status = /duplicato|self-reference/.test(msg) ? 409 : 400;
+        return send(res, status, { error: msg });
+      }
+      // store invalido / keygen fallita / write fallita: errore lato server.
+      return send(res, 500, { error: msg });
+    } catch (e) { send(res, 500, { error: String(e.message || e) }); }
+  });
+
+  // --- DELETE /nodes/:name — nodes remove ------------------------------------
+  r.delete('/nodes/:name', mutGate, (req, res) => {
+    try {
+      const name = String(req.params.name || '');
+      if (!validName(name)) return send(res, 400, { error: 'name non valido (^[a-z0-9-]{1,32}$)' });
+      const cap = capture();
+      const out = nodesCmds.nodesRemove({ ...cliOpts(cap), name });
+      if (out.code === 0) return send(res, 200, { removed: true, name, stopped: !!out.stopped });
+      const msg = lastLine(cap, 'nodes remove fallito');
+      if (out.reason === 'readonly') return send(res, 403, { error: msg });
+      const status = /sconosciuto|nessun nodes\.json/.test(msg) ? 404 : 500;
+      send(res, status, { error: msg });
+    } catch (e) { send(res, 500, { error: String(e.message || e) }); }
+  });
+
+  // --- POST /nodes/:name/test — non-mutante (POST per coerenza azione) -------
+  // NON gated READONLY: e' una probe diagnostica, coerente col `nodes test` CLI.
+  r.post('/nodes/:name/test', async (req, res) => {
+    try {
+      const name = String(req.params.name || '');
+      if (!validName(name)) return send(res, 400, { error: 'name non valido (^[a-z0-9-]{1,32}$)' });
+      const cap = capture();
+      const out = await nodesCmds.nodesTest({ ...cliOpts(cap), name });
+      if (out.result === 'unknown-node') return send(res, 404, { error: `nodo sconosciuto "${name}"` });
+      // result distingue: ok | tunnel-down | health-ko | token-missing | token-ko
+      send(res, 200, { ok: out.result === 'ok', result: out.result, detail: lastLine(cap, '') });
+    } catch (e) { send(res, 500, { error: String(e.message || e) }); }
+  });
+
+  // --- POST /nodes/:name/up|down|restart — lifecycle tunnel ------------------
+  // GATE READONLY (audit F6, 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).
+  function lifecycleHandler(action) {
+    return (req, res) => {
+      try {
+        const name = String(req.params.name || '');
+        if (!validName(name)) return send(res, 400, { error: 'name non valido (^[a-z0-9-]{1,32}$)' });
+        const cap = capture();
+        const fn = action === 'up' ? nodesCmds.nodesUp
+          : action === 'down' ? nodesCmds.nodesDown
+            : nodesCmds.nodesRestart;
+        const out = fn({ ...cliOpts(cap), name });
+        if (out.code !== 0) {
+          const msg = lastLine(cap, `nodes ${action} fallito`);
+          const status = /sconosciuto/.test(msg) ? 404 : 500;
+          return send(res, status, { error: msg });
+        }
+        if (action === 'up') return send(res, 200, { name, started: out.started, pid: out.pid });
+        if (action === 'down') return send(res, 200, { name, stopped: out.stopped });
+        return send(res, 200, { name, restarted: true, pid: out.pid });
+      } catch (e) { send(res, 500, { error: String(e.message || e) }); }
+    };
+  }
+  r.post('/nodes/:name/up', mutGate, lifecycleHandler('up'));
+  r.post('/nodes/:name/down', mutGate, lifecycleHandler('down'));
+  r.post('/nodes/:name/restart', mutGate, lifecycleHandler('restart'));
+
+  // --- POST /node-role — node on/off (rendezvous config) ---------------------
+  r.post('/node-role', mutGate, (req, res) => {
+    try {
+      const b = req.body;
+      if (!b || typeof b !== 'object' || Array.isArray(b)) {
+        return send(res, 400, { error: 'body deve essere un oggetto JSON' });
+      }
+      for (const k of Object.keys(b)) {
+        if (!NODE_ROLE_KEYS.has(k)) return send(res, 400, { error: `chiave non ammessa: "${k}" (schema: enabled, rendezvousSsh?, publishedPort?, keyPath?)` });
+      }
+      if (typeof b.enabled !== 'boolean') return send(res, 400, { error: 'enabled deve essere boolean' });
+      if (b.rendezvousSsh !== undefined && !nodesStore.parseSsh(b.rendezvousSsh)) {
+        return send(res, 400, { error: 'rendezvousSsh non valido (atteso user@host strict)' });
+      }
+      if (b.publishedPort !== undefined && !nodesStore.isPort(b.publishedPort)) {
+        return send(res, 400, { error: 'publishedPort deve essere un intero 1..65535' });
+      }
+      if (b.keyPath !== undefined && !nodesStore.isAbsPath(b.keyPath)) {
+        return send(res, 400, { error: 'keyPath deve essere un path assoluto' });
+      }
+
+      const cap = capture();
+      if (b.enabled === false) {
+        const out = nodesCmds.nodeOff({ ...cliOpts(cap) });
+        if (out.code === 0) return send(res, 200, { enabled: false, roles: out.roles });
+        return send(res, 500, { error: lastLine(cap, 'node off fallito') });
+      }
+      const out = nodesCmds.nodeOn({
+        ...cliOpts(cap),
+        rendezvousSsh: b.rendezvousSsh,
+        publishedPort: b.publishedPort,
+        key: b.keyPath,
+        port: cfg.port, // porta nexus locale da esporre = quella del server attivo
+      });
+      if (out.code === 0) {
+        const resp = { enabled: true, roles: out.roles, tunnel: out.tunnel || null };
+        const line = authorizedKeysLine(cap);
+        if (line) resp.authorizedKeys = line; // pubkey con permitlisten: non un segreto
+        return send(res, 200, resp);
+      }
+      const msg = lastLine(cap, 'node on fallito');
+      if (out.reason === 'readonly') return send(res, 403, { error: msg });
+      if (out.reason === 'no rendezvous') return send(res, 400, { error: msg });
+      if (out.reason === 'permitlisten') return send(res, 409, { error: msg });
+      send(res, 500, { error: msg });
+    } catch (e) { send(res, 500, { error: String(e.message || e) }); }
+  });
+
+  // --- POST /service/regenerate — rigenera l'unit service --------------------
+  // Riusa generateService/installService (lib/cli/service.js: escaping per-platform,
+  // no-symlink, tmp+rename atomico). L'execImpl e' un NO-OP che registra i comandi
+  // di attivazione SENZA eseguirli: il contratto B2 vieta il restart automatico
+  // dall'API (la UI avvisa di riavviare a mano).
+  r.post('/service/regenerate', mutGate, (_req, res) => {
+    try {
+      const { cfg: fileCfg } = readConfigFile(configPath);
+      const port = nodesStore.isPort(fileCfg.port) ? fileCfg.port : cfg.port;
+      const ctx = {
+        repoRoot: repoRoot(),
+        nodeBin: nodeBin(),
+        port, home,
+        uid: seams.uid || uid(),
+        installPath: seams.serviceInstallPath,
+      };
+      const content = generateService(platform, ctx);
+      const skipped = [];
+      const noExec = (bin, args) => { skipped.push(`${bin} ${(args || []).join(' ')}`); };
+      const out = installService(platform, content, ctx, { execImpl: noExec });
+      send(res, 200, {
+        regenerated: true,
+        target: out.target,
+        note: 'unit rigenerata; nessun restart automatico — riavvia il service per applicarla',
+        skippedActivation: skipped,
+      });
+    } catch (e) { send(res, 500, { error: String(e.message || e) }); }
+  });
+
+  // Error handler del router: body JSON malformato (express.json) -> 400 con causa;
+  // qualunque altro errore -> status coerente. MAI stack trace in risposta.
+  // eslint-disable-next-line no-unused-vars
+  r.use((err, _req, res, _next) => {
+    if (err && err.type === 'entity.parse.failed') {
+      return send(res, 400, { error: 'body JSON non valido' });
+    }
+    if (err && err.type === 'entity.too.large') {
+      return send(res, 400, { error: 'body troppo grande (limite 8kb)' });
+    }
+    send(res, (err && err.status) || 500, { error: String((err && err.message) || err) });
+  });
+
+  return r;
+}
+
+module.exports = { settingsRoutes, deepScrubTokens };

package/lib/ws/bridge.js

@@ -46,7 +46,12 @@ function bindWs(ws, deps) {
           ['set-option', '-t', `=${msg.session}:`, 'window-size', 'latest'], () => {});
       } catch (_) {}
       pty = openAttach(msg.session, {
-        readonly: msg.readonly ?? defaults.readonlyDefault ?? false,
+        // 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 audit finale: prima il ?? faceva vincere il client.)
+        readonly: defaults.readonlyDefault === true || !!msg.readonly,
         takeSize,
         cols: clamp(msg.cols, 20, 300, 80),
         rows: clamp(msg.rows, 5, 120, 24),
@@ -68,6 +73,10 @@ function bindWs(ws, deps) {
     try { msg = JSON.parse(data.toString()); } catch (_) { return; }
     if (msg.type === 'attach') return fail(1002, 'already attached'); // no 2nd attach
     if (msg.type === 'resize') 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).
+    else if (msg.type === 'focus') { if (msg.on) pty.promote(); else pty.demote(); }
     else if (msg.type === 'input') pty.write(typeof msg.data === 'string' ? msg.data : '');
     else if (msg.type === 'key') pty.write(typeof msg.seq === 'string' ? msg.seq.slice(0, 64) : '');
     else if (msg.type === 'action') runAction(session, msg.name); // nav window/pane server-side

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.7.6",
-  "description": "Faithful browser tmux client \u2014 attach to live sessions over a real PTY, localhost-only, mobile-easy",
+  "version": "0.8.0",
+  "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {
     "nexuscrew": "bin/nexuscrew.js"
@@ -9,6 +9,7 @@
   "files": [
     "bin/",
     "lib/",
+    "skills/",
     "frontend/dist/",
     "frontend/index.html",
     "LICENSE",
@@ -25,9 +26,14 @@
     "@mmmbuto/pty-termux-utils": "^1.1.4",
     "express": "^4.21.0",
     "multer": "^2.2.0",
+    "qrcode-terminal": "^0.12.0",
+    "web-push": "^3.6.7",
     "ws": "^8.18.0"
   },
   "optionalDependencies": {
+    "@lydell/node-pty-darwin-arm64": "^1.2.0-beta.14",
+    "@lydell/node-pty-darwin-x64": "^1.2.0-beta.14",
+    "@lydell/node-pty-linux-arm64": "^1.2.0-beta.12",
     "@lydell/node-pty-linux-x64": "^1.2.0-beta.12",
     "node-pty": "^1.1.0"
   },

package/skills/nexuscrew-agent/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: nexuscrew-agent
+description: Use when an AI agent connected to NexusCrew must notify or ask the human, inspect NexusCrew session/fleet status, read its inbox, deliver a file (report, screenshot, export), send text/input to a tmux session, or recover from tmux send-keys messages that remain unsubmitted or arrive garbled. Prefer the NexusCrew MCP tools nc_notify, nc_ask, nc_status, nc_inbox, and nc_send_file when exposed; use the bundled tmux/file helpers as fallback.
+---
+
+# NexusCrew Agent I/O
+
+Use the [NexusCrew](https://github.com/DioNanos/nexuscrew) MCP bridge for communication with the human and read-only runtime status. Use the bundled helpers for direct tmux messaging or as a compatibility fallback.
+
+## MCP bridge (preferred)
+
+When the client exposes the NexusCrew MCP server, use these tools directly:
+
+| Goal | MCP tool |
+|---|---|
+| Notify the human about a result, blocker, or milestone | `nc_notify` |
+| Ask for a decision without blocking the agent | `nc_ask` |
+| Inspect live tmux sessions and fleet cells | `nc_status` |
+| List files received for the current session | `nc_inbox` |
+| Deliver an absolute file path under the user's home | `nc_send_file` |
+
+Apply these rules:
+
+- Use `nc_notify` for meaningful asynchronous updates, failures requiring attention, and completion. Do not notify for every command or duplicate routine chat commentary.
+- Never include access tokens, credentials, private keys, push subscriptions, or other secrets in a notification, ask, file caption, or tool result.
+- Treat `nc_ask` as non-blocking: it returns an ask ID immediately. Continue safe independent work or wait normally; the human response arrives in the originating tmux session with a `[human reply · ask#<id>]` prefix by default.
+- Use `nc_status` instead of scraping NexusCrew state files. Use `nc_inbox` instead of guessing an inbox path when the tool is available.
+- Pass `nc_send_file` an existing absolute regular-file path below the user's home. Let NexusCrew choose and sanitize the outbox name.
+- Do not treat an MCP notification as a substitute for the final response required by the active client.
+
+The MCP server is the stdio command `nexuscrew mcp` and must be registered in the host AI client. If the `nc_*` tools are not exposed, report that the bridge is not configured in that session and use the fallback flows below where applicable.
+
+## File exchange (inbox / outbox)
+
+Per session, NexusCrew watches `<root>/<session>/{inbox,outbox}` (root = `$NEXUSCREW_FILES_ROOT`, default `~/NexusFiles`):
+
+- **outbox** — files you write here surface in the browser UI with a badge. This is how you deliver a deliverable.
+- **inbox** — files the human sends arrive here. The path reaches you in your prompt either way, but through two different human-side flows: the files-panel upload pastes the bare path straight into your PTY, while the composer **attach button** (paperclip, v0.7.7+) puts the path inside the human's typed message — expect paths mixed with instructions, not always a bare path on its own line. Read the files from the inbox; never overwrite, treat as read-only input.
+
+When `nc_send_file` is unavailable, deliver with the helper (resolves the current tmux session, timestamps, never overwrites):
+
+```bash
+bin/nc-deliver report.pdf chart.png      # → ~/NexusFiles/<session>/outbox/
+```
+
+Don't hand-craft the path from a guessed session name — use `nc-deliver`, or derive the session with `tmux display-message -p '#S'`.
+
+## Sending text to a tmux session
+
+`tmux send-keys 'msg' Enter` is **not** reliable: a TUI's paste-burst detector swallows the Enter and the message just sits in the composer, while exit code is still 0. Use the helper:
+
+```bash
+bin/nc-send <session> "text"              # paste + submit
+bin/nc-send <session> --file prompt.txt   # from a file
+bin/nc-send <session> --no-submit "text"  # leave in composer, no Enter
+```
+
+It does: `load-buffer` → `paste-buffer -p` (bracketed paste) → burst-flush (`C-e`) → `Enter`. **Verify it landed** — never trust the exit code:
+
+```bash
+tmux capture-pane -t <session> -p | tail -8   # see the text / a running state
+```
+
+## Quick reference
+
+| Goal | Do this |
+|---|---|
+| Notify the human | `nc_notify` |
+| Ask the human without blocking | `nc_ask` |
+| Inspect NexusCrew runtime state | `nc_status` |
+| Give the human a file | `nc_send_file` or fallback `nc-deliver <file>...` |
+| Read a file the human sent | `nc_inbox` or fallback to the path in the prompt |
+| Send a prompt/command to a session | `nc-send <session> "text"` |
+| Queue text without running it | `nc-send <session> --no-submit "text"` |
+| Confirm a send worked | `tmux capture-pane -t <session> -p | tail` |
+
+## Common mistakes
+
+- **Trusting `send-keys ... Enter`** → message stuck in composer. Use `nc-send` (bracketed paste + flush).
+- **Not verifying the send** → exit 0 means nothing; always `capture-pane`.
+- **`tmux` aliased/wrapped by the shell** (e.g. an oh-my-zsh plugin) → the nudge silently fails. Helpers resolve the real binary; in ad-hoc commands use `/usr/bin/tmux` or `command tmux`.
+- **Pasting onto a dirty composer** → text concatenates with whatever was there. Clear it first, or the previous line will merge with yours.
+- **Delivering to a guessed session name** → file lands in an orphan folder with no badge. Use `nc-deliver` (it reads the real session).

package/skills/nexuscrew-agent/bin/nc-deliver

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# nc-deliver — deliver files to the human via the NexusCrew outbox (shows a
+# badge in the browser UI). Writes into <root>/<session>/outbox/, where root is
+# $NEXUSCREW_FILES_ROOT (default ~/NexusFiles) and session is the current tmux
+# session. Files are timestamp-prefixed; never overwrites.
+set -euo pipefail
+
+root="${NEXUSCREW_FILES_ROOT:-$HOME/NexusFiles}"
+session="${NEXUSCREW_SESSION:-$(tmux display-message -p '#S' 2>/dev/null || true)}"
+
+[ -n "$session" ] || { echo "nc-deliver: no tmux session (run inside tmux, or set NEXUSCREW_SESSION)" >&2; exit 2; }
+[ "$#" -ge 1 ] || { echo "usage: nc-deliver <file> [file...]" >&2; exit 2; }
+
+dir="$root/$session/outbox"
+mkdir -p "$dir"
+
+for f in "$@"; do
+  [ -f "$f" ] || { echo "nc-deliver: not a file: $f" >&2; exit 1; }
+  dest="$dir/$(date +%Y%m%d-%H%M)_$(basename -- "$f")"
+  i=1; while [ -e "$dest" ]; do dest="$dir/$(date +%Y%m%d-%H%M)_${i}-$(basename -- "$f")"; i=$((i+1)); done
+  cp -- "$f" "$dest"
+  echo "delivered → $dest"
+done