@mmmbuto/nexuscrew 0.9.28 → 0.9.30

package/lib/fleet/definitions.js

@@ -1,13 +1,13 @@
 'use strict';
-// B4.1 — Definizioni fleet editabili (~/.nexuscrew/fleet.json).
+// Editable fleet definitions (~/.nexuscrew/fleet.json).
 // Modulo PURO: nessun side-effect all'import. Tutto l'I/O vive in
 // loadDefinitions/atomicWrite; parseDefinitions/validateCommandTrust non
 // toccano il filesystem se non per le stat di trust (sincrone, come binTrusted).
 //
 // Principio: fail-closed. Qualunque dato malformato -> null, MAI throw non
-// gestito. Le definizioni contengono comandi arbitrari (design §6), quindi la
-// validazione e' STRICT (garbage -> errore, non guess). Stesso confinamento di
-// lib/fs/routes.js e lib/tmux/lifecycle.js.
+// handled. The definitions carry arbitrary commands, so validation is
+// STRICT (garbage -> error, no guessing). Same confinement as
+// lib/fs/routes.js and lib/tmux/lifecycle.js.
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
@@ -119,7 +119,7 @@ function isTmuxSafeName(name) {
 // Deriva il nome sessione tmux CANONICO di una cella. Puro, iniettivo, reversibile.
 //  - ID senza punto: storico `cloud-<id>` (le sessioni esistenti non vengono
 //    rinominate; il namespace e' tmux-safe perche' l'id stesso non ha punto).
-//  - ID con punto: mapping v2 dot-free (design §3.1.5):
+//  - Dotted IDs: dot-free v2 mapping:
 //      raw    = base64url(UTF-8 id), senza padding '='
 //      n      = lunghezza di raw su due cifre
 //      padded = raw right-padded con '-' fino a 43 caratteri
@@ -469,7 +469,7 @@ function parseCell(c, engineIds, engineMap = new Map(), {
   // cwd (obbligatorio; la risoluzione/confinamento avviene via resolveCwd a runtime)
   if (typeof c.cwd !== 'string' || !c.cwd || c.cwd.length > MAX_CWD_LEN) return null;
 
-  // cwdRel (opzionale canonico, design §4.3): forma portatile home-relative.
+  // cwdRel (optional, canonical): portable home-relative form.
   // Qui si valida solo il FORMATO (stringa canonica): la coerenza cwd<->cwdRel
   // e' un invariante di SCRITTURA (define/edit/restore), non di lettura — così
   // le definizioni legacy (solo cwd) e quelle nuove (cwd+cwdRel) caricano senza
@@ -907,9 +907,9 @@ function validateCommandTrust(command) {
   if (!st.isFile()) return { ok: false, reason: 'non e\' un file regolare (symlink o speciale)' }; // lstat: symlink -> isFile()=false
   if (!(st.mode & 0o100)) return { ok: false, reason: 'non eseguibile dall\'owner' };
   if (st.mode & 0o002) return { ok: false, reason: 'world-writable' };
-  // Owner check (design §9a, da revisione): il command deve appartenere
-  // all'utente del service o a root — un owner terzo potrebbe sostituire
-  // l'eseguibile mantenendo il path "trusted".
+  // Owner check: the command must belong to the service user or root —
+  // a third-party owner could replace the executable while keeping the
+  // path "trusted".
   if (typeof process.getuid === 'function') {
     const uid = process.getuid();
     if (st.uid !== uid && st.uid !== 0) return { ok: false, reason: 'owner non fidato (ne\' utente del service ne\' root)' };
@@ -948,7 +948,7 @@ function resolveCwd(cwd, home, out) {
 }
 
 // ---------------------------------------------------------------------------
-// cwdRel — cwd home-relative PORTATILE (design §4.3 / backup v3).
+// cwdRel — portable home-relative cwd representation.
 // Rappresentazione canonica di una cwd come percorso relativo alla home del
 // device target: '' == la home stessa; 'personal' == <home>/personal.
 // Helper PURI (nessun fs): la normalizzazione e' string-only e fail-closed.

package/lib/fleet/identity-authority.js

@@ -294,7 +294,7 @@ function createIdentityAuthority({
       return { ok: false, reason: 'challenge' };
     }
     const currentTick = Number(now());
-    // R2: il TTL della challenge e' SERVER-OWNED (15s dall'orologio
+    // Il TTL della challenge e' SERVER-OWNED (15s dall'orologio
     // dell'authority), non del chiamante: oltre il cap viene capito, e una
     // challenge con issuedAt nel futuro e' rifiutata (documentato in referto).
     if (Number.isSafeInteger(challenge.issuedAt) && challenge.issuedAt > currentTick) {

package/lib/fleet/launch-broker.js

@@ -77,11 +77,11 @@ function createLaunchBroker(cfg = {}) {
   let closed = false;
   const pending = new Map();
   const ttlMs = Math.max(1000, Number(cfg.launchTokenTtlMs) || 15000);
-  // R3.1.1 (opt-in): se cfg.onLease e' registrato e il payload porta `lease`, la
-  // connessione accettata col nonce one-shot resta APERTA dopo il frame payload e
-  // viene consegnata a onLease(socket, lease) per divenire il canale lease. Senza
-  // onLease o senza lease il comportamento e' invariato (socket.end, one-shot):
-  // le celle non-ospite non sono toccate.
+  // Opt-in: if cfg.onLease is registered and the payload carries `lease`, the
+  // connection accepted with the one-shot nonce stays OPEN after the payload
+  // frame and is handed to onLease(socket, lease) to become the lease channel.
+  // Without onLease or without a lease the behavior is unchanged (socket.end,
+  // one-shot): non-host cells are untouched.
   const onLease = typeof cfg.onLease === 'function' ? cfg.onLease : null;
   const identityMode = cfg.identityMode || 'legacy';
   const identityAuthority = cfg.identityAuthority || null;
@@ -127,12 +127,12 @@ function createLaunchBroker(cfg = {}) {
           // never claim the same payload, even while the first socket drains.
           pending.delete(nonce); clearTimeout(entry.timer);
           if (entry.lease && onLease) {
-            // R3.1.1: la stessa connessione resta APERTA dopo il frame payload.
-            // Disarmiamo il timeout one-shot e rimuoviamo il data handler del nonce:
-            // la socket arriva pulita a onLease, che la dedica al canale lease. Cosi'
-            // un refresh successivo non riparla sul nonce esaurito (il reparse della
-            // riga nonce, con pending vuota, distruggeva la connessione) e non scatta
-            // piu' il timeout idle da 3s pensato per il one-shot.
+            // The same connection stays OPEN after the payload frame.
+            // We disarm the one-shot timeout and remove the nonce data handler:
+            // the socket reaches onLease clean, which dedicates it to the lease
+            // channel: a later refresh never talks to the spent nonce (the reparse
+            // of the nonce line, with an empty pending map, used to destroy the
+            // connection) and the 3s idle timeout meant for the one-shot is gone.
             socket.setTimeout(0);
             socket.removeAllListeners('data');
             // da revisione interna: la lease PRIMA del payload. onLease
@@ -267,8 +267,8 @@ function createLaunchBroker(cfg = {}) {
     try { if (socketPath) fs.unlinkSync(socketPath); } catch (_) {}
   }
 
-  // Revoca esplicita di un nonce pendente (design §3.3): se il respawn-pane
-  // fallisce dopo issue(), il runtime consuma/revoca il ticket subito invece di
+  // Explicit revocation of a pending nonce: if the respawn-pane fails after
+  // issue(), the runtime consumes/revokes the ticket immediately instead of
   // attenderne il TTL. expire() e' gia' no-op su nonce mancante/scaduto.
   return { issue, close, revoke: expire, pendingCount: () => pending.size };
 }

package/lib/fleet/launch.js

@@ -5,7 +5,7 @@
 // del fleet. createBuiltinRuntime() in runtime.js ne fa uso; builtin.js e'
 // ora un facade che re-esporta questi simboli per i test.
 //
-// Sicurezza (design §9a/§9e/§9h) — invariata rispetto a builtin.js:
+// Security model — unchanged versus builtin.js:
 //  - command/args/env NON passano per una shell: execFile + argv diretto
 //    (tmux fa exec del comando, NON sh -c — verificato: ';','|','$' passano
 //    verbatim). Nessun valore passa in argv, `tmux -e`, file temporanei o
@@ -14,8 +14,8 @@
 //    possono toccare PATH/loader-key (parseDefinitions le rifiuta gia' in env).
 //  - promptMode 'send-keys' inietta via `tmux load-buffer` + `paste-buffer -p`
 //    (bracketed paste), NON send-keys grezzo; se il command e' gia' uscito
-//    (sessione morta) NON digita (§9e).
-//  - redactSecrets/sanitizeEarlyDiagnostic (§9h): stderr/stdout dei comandi
+//    (dead session) it does not type.
+//  - redactSecrets/sanitizeEarlyDiagnostic: stderr/stdout of failed tmux
 //    tmux falliti NON devono mai ecoare i segreti delle definizioni.
 const fs = require('node:fs');
 const os = require('node:os');
@@ -26,7 +26,7 @@ const { minimalRuntimeEnv } = require('../runtime/env.js');
 const { codeOf, phaseOf } = require('./causes.js');
 const { isTmuxSafeName, tmuxSessionForCell } = require('./definitions.js');
 
-// Env minimale controllato dal service (design §9a). Allowlist DURA: le definizioni
+// Minimal service-controlled env. HARD allowlist: the definitions
 // non possono toccare PATH/loader-key (parseDefinitions le rifiuta gia' in env);
 // qui NON passiamo MAI l'env del processo per intero. engine.env viene consegnato
 // direttamente al processo figlio dal broker, senza entrare nello stato tmux.
@@ -52,7 +52,7 @@ function tmuxInventoryEnv() {
 }
 
 // httpError(status, msg, data?, cause?) — structured HTTP error. `data` carries
-// arbitrary API detail for the response body; `cause` (T4) is the OPTIONAL
+// Arbitrary API detail for the response body; `cause` is the OPTIONAL
 // bounded failure triple {phase, code} of the up() boundary that failed. The
 // cause is coerced through the closed enum in causes.js (anything not
 // allowlisted degrades to UNKNOWN) and attached as e.fleetCode / e.fleetPhase,
@@ -70,12 +70,12 @@ function httpError(status, msg, data = null, cause = null) {
   return e;
 }
 
-// Marcatore di redazione (design §9h): stderr/stdout dei comandi tmux falliti
+// Redaction marker: stderr/stdout of failed tmux commands
 // NON devono mai ecoare i segreti delle definizioni.
 const REDACTED = '‹redacted›';
 
 // redactSecrets(text, engine, cell) -> string con ogni occorrenza dei segreti
-// delle definizioni sostituita da '‹redacted›'. Segreti coperti (§9h):
+// of the definitions replaced by '‹redacted›'. Covered secrets:
 //  - valori di engine.env           (le CHIAVI restano, i VALUES vengono redatti)
 //  - testo del prompt della cella   (cell.prompt)
 //  - testo del prompt dell'engine   (engine.prompt) se presente
@@ -156,7 +156,7 @@ function boundedTmuxFailure(result) {
     .replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 240) || 'errore tmux';
 }
 
-// Migrazione identita' tmux (design §3.2). Prima costruisce e valida TUTTO il
+// tmux identity migration: the whole plan is built and validated first.
 // piano: nessun rename parte se una sessione legacy normalizzata e' rivendicata
 // da piu celle (es. a.b vs a_b), se legacy+target safe coesistono o se il target
 // non e' tmux-safe. Solo dopo il preflight rinomina via `$N`; qualunque errore e'
@@ -267,7 +267,7 @@ async function migrateLegacyTmuxSessions(tmuxBin, defs, { readonly = false } = {
   };
 }
 
-// Policy caratteri del prompt send-keys (§9e): ammette stampabili + \t \n \r;
+// send-keys prompt character policy: printable + \t \n \r allowed;
 // rifiuta ESC(0x1b) e gli altri byte di controllo (niente marker bracketed-paste
 // iniettabili). parseDefinitions caps solo la lunghezza: questo e' defense-in-depth.
 function promptCharsOk(prompt) {
@@ -293,7 +293,7 @@ function composeClientInvocation(engine, cell) {
     if (val) args.push(engine.model.flag, val);
   }
   // prompt flag-mode: promptFlag + prompt cella, solo se c'e' un prompt effettivo.
-  // SICUREZZA (design §9h): promptMode 'flag' mette il prompt in ARGV -> e' visibile
+  // SECURITY: promptMode 'flag' puts the prompt in ARGV -> it is visible
   // nella process list (ps) / argv della sessione, a differenza di 'send-keys' che lo
   // inietta DOPO via bracketed paste. Va quindi vincolato a prompt NON-segreti.
   if (engine.promptMode === 'flag' && cell.prompt) {
@@ -357,7 +357,7 @@ async function waitStablePane(tmuxBin, target, { env, readyMs }) {
 }
 
 // Risolve il pane id (%N) esatto della sessione, o verifica un %N gia' noto.
-// Contratto submitToSession (R5): output session_name + pane_dead + pane_id,
+// Contratto submitToSession: output session_name + pane_dead + pane_id,
 // parsing ESATTO per campi (mai regex %N libera), session verificata uguale
 // a quella attesa prima di qualunque paste/Enter. Ritorna null se il pane non
 // e' risolvibile, morto, di un'altra sessione o diverso dal %N atteso.
@@ -403,10 +403,10 @@ async function securePaste(tmuxBin, session, text, { env, exec, tmpdir, target,
     const load = await run(tmuxBin, ['load-buffer', '-b', buffer, tmp], { env });
     if (load.err) return { ok: false, stage: 'load', reason: 'buffer non disponibile' };
     loaded = true;
-    // R4: da qui in poi il paste e' stato TENTATO: qualunque throw/rejection
+    // Da qui in poi il paste e' stato TENTATO: qualunque throw/rejection
     // dell'executor e' post-paste (stage 'paste'), mai classificato come
     // pre-paste 'load' — il composer potrebbe contenere testo parziale o
-    // completo e un retry duplicherebbe il prompt (G1).
+    // Completo e un retry duplicherebbe il prompt.
     try {
       const paste = await run(tmuxBin, ['paste-buffer', '-p', '-t', paneId, '-b', buffer], { env });
       if (paste.err) return { ok: false, stage: 'paste', reason: 'paste-buffer failed' };
@@ -423,9 +423,9 @@ async function securePaste(tmuxBin, session, text, { env, exec, tmpdir, target,
 }
 
 // Iniezione prompt send-keys via bracketed paste (contratto legacy per engine
-// custom promptMode 'send-keys': paste SENZA Enter, invariato — 0.8.47 G4).
+// Custom promptMode 'send-keys': paste SENZA Enter, invariato — 0.8.47).
 // Readiness best-effort: se la sessione non e' viva quando paste-iamo (command
-// gia' uscito) NON digita (design §9e). Ritorna {injected, reason}.
+// already exited) does not type. Returns {injected, reason}.
 // Trasporto backportato su securePaste: buffer random, temp wx/0600, pane %N.
 async function injectPrompt(tmuxBin, session, prompt, { env, readyMs = 400, target, engine, cell } = {}) {
   if (!promptCharsOk(prompt)) {

package/lib/fleet/lease-client.js

@@ -2,16 +2,16 @@
 
 // Lease-client lato SUPERVISORE (cell-exec.js).
 //
-// Mantiene la connessione lease iniziale (la stessa del broker one-shot che resta
-// APERTA dopo il payload, R3.1.1), invia refresh a cadenza 20s (R3.2 heartbeat),
-// e su EOF reconnecta all'endpoint stabile (R3.3.2).
+// Keeps the initial lease connection (the same one-shot broker connection that
+// stays OPEN after the payload), sends refreshes every 20s (heartbeat),
+// and on EOF reconnects to the stable endpoint.
 //
-// Fetta 2b (contratto rev1, A2/B1): l'autenticazione del reconnect e' un proof
+// Fetta 2b (contratto rev1, /): l'autenticazione del reconnect e' un proof
 // HMAC firmato dal server col verifier per-installazione — la capability statica
 // della 2a e' revocata. Il proof NON arriva nel payload: il server lo consegna
 // sul canale (frame lease all'attach, ack a ogni refresh) e il supervisore lo
-// detiene in memoria, presentandolo tale e quale al reconnect. R3.1.2 invariato:
-// niente di tutto questo transita mai nell'env del child.
+// held in memory, presented as-is on reconnect. Unchanged:
+// none of this ever transits in the child env.
 //
 // Side effect isolati e iniettabili (seams) per testabilita', come altrove.
 
@@ -33,7 +33,7 @@ function validDaemonChallenge(value) {
   const keys = Object.keys(value);
   if (keys.length !== IDENTITY_CHALLENGE_KEYS.length
     || IDENTITY_CHALLENGE_KEYS.some((key) => !Object.prototype.hasOwnProperty.call(value, key))) return false;
-  // R4: tipi JSON originari, niente coercizioni (Number()/regex su non-stringhe).
+  // Tipi JSON originari, niente coercizioni (Number/regex su non-stringhe).
   const issuedAt = value.issuedAt;
   const expiresAt = value.expiresAt;
   return value.version === 1
@@ -90,13 +90,13 @@ function startLeaseClient(initialSocket, info, seams = {}) {
   let refreshTimer = null;
   let reconnectTimer = null;
   // 2b: ultimo proof consegnato dal server sul canale (attach/refresh). Vive
-  // SOLO in memoria qui: e' effimero per costruzione (B8), non si persiste.
+  // SOLO in memoria qui: e' effimero per costruzione, non si persiste.
   let heldProof = null;
-  // R3.2: bound di grace per i reconnect (eofAt + GRACE_MS). Oltre non si ritenta.
+  // Grace bound for reconnects (eofAt + GRACE_MS). Past it, no more attempts.
   let reconnectDeadline = null;
   const identityPending = new Map();
   const verifyPending = new Map();
-  // R1: una sola transizione di generazione in volo (il supervisore e' sequenziale).
+  // Una sola transizione di generazione in volo (il supervisore e' sequenziale).
   let generationWaiter = null;
 
   function send(obj) {
@@ -150,8 +150,8 @@ function startLeaseClient(initialSocket, info, seams = {}) {
     if (current) { try { current.removeAllListeners('data'); current.removeAllListeners('close'); current.removeAllListeners('end'); } catch (_) {} }
     current = null;
     clearTimer(refreshTimer);
-    // R3.2: la grace parte dall'EOF lato supervisore. I reconnect sono bounded da
-    // eofAt + GRACE_MS: rev13 S3.3 garantisce >=2 tentativi STRETTAMENTE dentro.
+    // The grace starts from the supervisor-side EOF. Reconnects are bounded by
+    // eofAt + GRACE_MS: at least 2 attempts happen STRICTLY inside it.
     reconnectDeadline = now() + L.GRACE_MS;
     armReconnect(0); // primo tentativo subito, poi a cadenza RECONNECT_CADENCE_MS
   }
@@ -160,7 +160,7 @@ function startLeaseClient(initialSocket, info, seams = {}) {
 
   function armReconnect(delay) {
     clearTimer(reconnectTimer);
-    // R3.2: oltre la grace non si ritenta (deny o server muto non vanno in loop).
+    // Past the grace no more attempts (deny or mute server must not loop).
     if (reconnectDeadline != null && now() >= reconnectDeadline) {
       // da revisione interna: la grace e' scaduta senza un reconnect
       // riuscito: la lease e' PERSA per questo supervisore. Prima si desisteva
@@ -182,8 +182,8 @@ function startLeaseClient(initialSocket, info, seams = {}) {
 
   function attemptReconnect() {
     let settled = false;
-    // R3.3.4: generation puo' essere un getter (cell-exec la fa avanzare coi restart)
-    // o un valore; al reconnect presentiamo sempre quella corrente.
+    // The generation may be a getter (cell-exec advances it with restarts)
+    // or a value; on reconnect we always present the current one.
     const curGeneration = typeof info.generation === 'function' ? info.generation() : (info.generation || 0);
     const sock = netImpl.createConnection(info.stablePath, () => {
       // 2b: presentiamo il proof detenuto. Senza proof (nessun ack ricevuto, o
@@ -192,9 +192,9 @@ function startLeaseClient(initialSocket, info, seams = {}) {
       const msg = { type: 'reconnect', generation: curGeneration, ...(heldProof ? { proof: heldProof } : {}) };
       try { sock.write(`${JSON.stringify(msg)}\n`); } catch (_) { try { sock.destroy(); } catch (e) {} }
     });
-    // R3.2: per-attempt timeout. Se il server accetta la connessione ma non risponde
-    // (socket appesa) forziamo la chiusura e ritentiamo: senza questo il client
-    // restava con 1 solo tentativo e 0 timer successivi. Cadence come upper bound.
+    // Per-attempt timeout. If the server accepts the connection but does not
+    // answer (hanging socket) we force-close and retry: without this the client
+    // stayed with 1 attempt and 0 following timers. Cadence as the upper bound.
     const attemptTimer = setTimer(() => {
       if (settled) return;
       settled = true;
@@ -214,8 +214,8 @@ function startLeaseClient(initialSocket, info, seams = {}) {
       if (msg.type === 'lease') {
         settled = true;
         clearTimer(attemptTimer);
-        // R3.3.4: reconnect riuscito, lease nuovo. Il proof consegnato col lease
-        // nuovo diventa quello detenuto; riprende il refresh loop.
+        // Successful reconnect, new lease. The proof delivered with the new
+        // lease becomes the held one; the refresh loop resumes.
         clearTimer(reconnectTimer);
         if (msg.proof && typeof msg.proof === 'object') heldProof = msg.proof;
         current = sock;
@@ -224,8 +224,8 @@ function startLeaseClient(initialSocket, info, seams = {}) {
       } else if (msg.type === 'deny') {
         settled = true;
         clearTimer(attemptTimer);
-        // R3.3.5: rifiutato (proof rifiutato, oltre grace o identity). Riprova a
-        // cadenza: rev13 S3.3 garantisce >=2 tentativi strettamente dentro la grace.
+        // Refused (bad proof, past grace, or identity mismatch). Retry at
+        // cadence: at least 2 attempts happen strictly inside the grace window.
         try { sock.destroy(); } catch (_) {}
         armReconnect(L.RECONNECT_CADENCE_MS);
       }
@@ -373,7 +373,7 @@ function startLeaseClient(initialSocket, info, seams = {}) {
     });
   }
 
-  // R1: annuncia la transizione di generazione sulla connessione viva PRIMA
+  // Annuncia la transizione di generazione sulla connessione viva PRIMA
   // che il supervisore apra il canale identita' della generazione nuova.
   function announceGeneration(generation) {
     if (!Number.isSafeInteger(generation) || generation < 0) {

package/lib/fleet/lease-routes.js

@@ -1,6 +1,6 @@
 'use strict';
 // lib/fleet/lease-routes.js — route /api/lease, superficie child della fetta 2b
-// (contratto rev1: B5 tre metodi distinti + D3 collegamento MCP↔leaseManager).
+// (contract: three distinct methods + the MCP↔leaseManager link).
 //
 // Il bridge MCP di una cella (`nexuscrew mcp`) parla con l'HTTP API locale dietro
 // Bearer (canale nativo del bridge): queste route sono quel collegamento.
@@ -25,7 +25,7 @@ function leaseRoutes({
     fleetP, instanceId, now: () => Date.now(),
     // refresh/recovery hanno gia il proof child come authorizer nel body. Il
     // binding MCP, quando presentato, viene verificato fail-closed; l'assenza
-    // preserva il canale nativo lease (D) che esisteva prima di G3.
+    // Preserva il canale nativo lease (D) che esisteva prima di .
     sharedRequired: false,
   });
 
@@ -51,7 +51,7 @@ function leaseRoutes({
     try {
       const fleet = await fleetP;
       if (!fleet || fleet.available !== true) return res.status(404).json({ error: 'fleet non disponibile' });
-      // D3: il collegamento vive sul provider — senza leaseManager (lease
+      // The link lives vive sul provider — senza leaseManager (lease
       // disattivato) e' 501, non 500: la capability manca, non e' un guasto.
       if (!fleet.lease || typeof fleet.lease.childRegister !== 'function') {
         return res.status(501).json({ error: 'lease non disponibile su questo nodo' });

package/lib/fleet/lease-verifier.js

@@ -1,7 +1,7 @@
 'use strict';
 
 // Verifier per-installazione e proof HMAC del lease Live (fetta 2b, contratto
-// rev1: PREMESSA + B1/B4/B6/B7/B8 + C4/C5).
+// Contract rev1: the premise and the items below.
 //
 // Modello (PREMESSA): la 2a usava un segreto condiviso simmetrico — il
 // supervisore presentava la capability cosi' com'e' e il server la confrontava.
@@ -9,25 +9,25 @@
 // segreto, il supervisore/child presenta un proof firmato con claims ed expiry.
 // Non e' la 2a con un giro in piu': e' un modello di autorizzazione diverso.
 //
-//  - B7: la chiave verifier vive in un file DEDICATO separato 0o600, distinto
+// La chiave verifier vive in un file DEDICATO separato 0o600, distinto
 //    dai token di liveness per-cella e dal segreto del bridge audio. «Un solo
 //    segreto» significa una sola chiave verifier, non un solo file segreto nel
 //    sistema.
-//  - C5: lo stato durevole contiene l'identificativo e l'impronta, MAI il
+// Lo stato durevole contiene l'identificativo e l'impronta, MAI il
 //    segreto — forma gia' usata da vl-node (PendingEnrollment). Il keyId e'
 //    DERIVATO dall'impronta (sha256 della chiave): non esiste uno stato da
 //    tenere sincronizzato con la chiave, e il meta su disco e' diagnostica.
-//  - B4: la codifica canonica e' length-prefixed con proofKind come primo tag.
+// La codifica canonica e' length-prefixed con proofKind come primo tag.
 //    La canonizzazione JSON e' fragile: due serializzatori onesti producono
 //    byte diversi. Il length-prefixing dichiara il confine di ogni campo, non
 //    lo deduce da un separatore.
-//  - B8: expiry = issuedAt + 60s, calcolabile all'emissione. «Ultimo-live+60»
+// Expiry = issuedAt + 60s, calcolabile all'emissione. «Ultimo-live+60»
 //    e' la proprieta' che si vuole, non la formula che si scrive: non e'
 //    calcolabile nel momento in cui il proof va firmato.
-//  - C4: fail-closed sulla verifica. La verifica prova TUTTE le chiavi vive
+// Fail-closed sulla verifica. La verifica prova TUTTE le chiavi vive
 //    (oggi una sola: la rotazione e' sospesa per scelta dichiarata, contratto
-//    C3; la forma e' gia' quella a due chiavi di C2).
-//  - C6: la verifica rende osservabile QUALE chiave ha firmato (keyId), cosi'
+//; la forma e' gia' quella a due chiavi di).
+// La verifica rende osservabile QUALE chiave ha firmato (keyId), cosi'
 //    il momento in cui una chiave subentra resta leggibile dopo il fatto.
 //
 // Disciplina del file segreto: stessa di lib/audio/bridge-auth.js e
@@ -38,7 +38,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 
-// B8: vita di un proof emesso. Il refresh gira ogni 20s (REFRESH_MS): un proof
+// Vita di un proof emesso. Il refresh gira ogni 20s (REFRESH_MS): un proof
 // da 60s lascia sempre al detentore >=2 presentazioni legittime di margine.
 const PROOF_TTL_MS = 60_000;
 
@@ -52,16 +52,16 @@ const KEY_ID_LEN = 16;
 const JTI_RE = /^[a-f0-9]{16,64}$/;
 const SIG_RE = /^[a-f0-9]{64}$/;
 
-// Campi firmati per proofKind, IN ORDINE, proofKind primo (B4). Per kind la
+// Campi firmati per proofKind, IN ORDINE, proofKind primo. Per kind la
 // lista e' fissa e tutti i campi sono obbligatori e non vuoti: campo mancante e
 // campo vuoto non sono distinguibili nella canonica, quindi non esistono campi
-// opzionali. B6: nel kind 'lease' l'identita' del lease e' 'leaseId' — non
+// Opzionali.: nel kind 'lease' l'identita' del lease e' 'leaseId' — non
 // identityKey, che legherebbe il lease all'identita' della cella.
 const KIND_FIELDS = Object.freeze({
   // tupla del supervisore: autorizza il reconnect all'endpoint stabile.
   lease: ['kind', 'cellId', 'launchEpoch', 'leaseId', 'generation', 'jti', 'issuedAt'],
-  // tupla del child: autorizza register/refresh/recovery (B5). incarnationId e'
-  // per-registration (B2), mai globale.
+  // Tupla del child: autorizza register/refresh/recovery. incarnationId e'
+  // Per-registration, mai globale.
   child: ['kind', 'cellId', 'incarnationId', 'jti', 'issuedAt'],
 });
 
@@ -69,7 +69,7 @@ function fingerprintOf(secret) {
   return crypto.createHash('sha256').update(String(secret), 'utf8').digest('hex');
 }
 
-// --- B4: codifica canonica ----------------------------------------------------
+// -: codifica canonica ----------------------------------------------------
 
 // Ogni campo: u32 big-endian della lunghezza in byte UTF-8, poi i byte. Il
 // proofKind e' il primo tag: chiave di dominio della firma (un proof lease non
@@ -91,7 +91,7 @@ function claimsForKind(kind) {
   return fields;
 }
 
-// --- B7/C5: chiave per-installazione ------------------------------------------
+// - : chiave per-installazione ------------------------------------------
 
 // Lettura no-follow (anti-symlink), stessa disciplina del bridge secret.
 function readKeySafe(fsImpl, keyPath) {
@@ -129,8 +129,8 @@ function loadOrCreateVerifier({ dir, fsImpl = fs, log = () => {}, now = Date.now
   try { fsImpl.chmodSync(keyPath, 0o600); } catch (_) {}
   // keyId derivato dall'impronta: la chiave porta con se' la propria identita'.
   const keyId = fingerprintOf(secret).slice(0, KEY_ID_LEN);
-  // C5: il meta persiste id + impronta (MAI il segreto) per diagnostica e
-  // osservabilita' (C6). Best-effort: se e' assente o divergente si riscrive;
+  // Il meta persiste id + impronta (MAI il segreto) per diagnostica e
+  // Osservabilita'. Best-effort: se e' assente o divergente si riscrive;
   // un fallimento di scrittura non invalida la chiave.
   try {
     const meta = { version: 1, keyId, fingerprint: fingerprintOf(secret), createdAt: now() };
@@ -172,11 +172,11 @@ function signProof(verifier, claims, { now = Date.now, jti = null } = {}) {
 
 function isNonEmptyString(v) { return typeof v === 'string' && v.length > 0; }
 
-// Fail-closed (C4): ogni difetto e' un motivo, non un'eccezione. `verifiers` e'
-// la lista delle chiavi vive (oggi una; C2-ready per due). `expect` porta i
+// Fail-closed: ogni difetto e' un motivo, non un'eccezione. `verifiers` e'
+// La lista delle chiavi vive (oggi una; -ready per due). `expect` porta i
 // claims che il chiamante gia' conosce: la firma prova il resto.
 // `graceMs` (default 0) allarga la finestra di accettazione DOPO la scadenza:
-// e' la finestra di recovery del child (B5) — un proof la cui firma e' valida e
+// E' la finestra di recovery del child — un proof la cui firma e' valida e
 // la cui scadenza e' recente NON e' una credenziale rubata riportata in vita, e'
 // un detentore che ha saltato i refresh. Ogni altro check resta invariato.
 function verifyProof(verifiers, candidate, { now = Date.now, expect = {}, graceMs = 0 } = {}) {
@@ -193,7 +193,7 @@ function verifyProof(verifiers, candidate, { now = Date.now, expect = {}, graceM
   const issuedAt = Number(candidate.issuedAt);
   if (!Number.isSafeInteger(issuedAt)) return { ok: false, reason: 'malformed' };
   const expiresAt = Number(candidate.expiresAt);
-  // B8: expiresAt non e' un campo qualunque: deve essere ESATTAMENTE
+  // ExpiresAt non e' un campo qualunque: deve essere ESATTAMENTE
   // issuedAt + PROOF_TTL_MS. Manometterlo non estende la vita del proof.
   if (!Number.isSafeInteger(expiresAt) || expiresAt !== issuedAt + PROOF_TTL_MS) {
     return { ok: false, reason: 'malformed' };
@@ -210,7 +210,7 @@ function verifyProof(verifiers, candidate, { now = Date.now, expect = {}, graceM
   if (expect.launchEpoch !== undefined && candidate.launchEpoch !== expect.launchEpoch) return { ok: false, reason: 'launchEpoch' };
   if (expect.leaseId !== undefined && candidate.leaseId !== expect.leaseId) return { ok: false, reason: 'leaseId' };
   if (expect.incarnationId !== undefined && candidate.incarnationId !== expect.incarnationId) return { ok: false, reason: 'incarnationId' };
-  // Firma contro OGNI chiave viva: la prima che passa vince (C2/C6).
+  // Firma contro OGNI chiave viva: la prima che passa vince (/).
   const canonical = canonicalProofFields(fields.map((f) => candidate[f]));
   for (const v of verifiers) {
     if (!v || typeof v.secret !== 'string') continue;