@mmmbuto/nexuscrew 0.8.12 → 0.8.14

package/lib/fleet/builtin.js

@@ -13,8 +13,9 @@
 //    exec del comando, NON sh -c — verificato: ';','|','$' passano verbatim).
 //  - env: il builtin lancia con un env MINIMALE controllato dal service (allowlist
 //    dura); engine.env — gia' ripulito dalle loader-key da parseDefinitions —
-//    raggiunge la sessione SOLO via `tmux -e` (chiavi validate). PATH lo controlla
-//    il service, mai la definizione.
+//    raggiunge il client solo tramite un broker AF_UNIX privato e monouso. Nessun
+//    valore passa in argv, `tmux -e`, file temporanei o ambiente globale tmux.
+//    PATH lo controlla il service, mai la definizione.
 //  - READONLY (cfg.readonlyDefault===true | NEXUSCREW_READONLY=1) blocca ogni
 //    mutazione fleet e ogni up (§9d): passano solo status/schema/capabilities.
 //  - promptMode 'send-keys' inietta via `tmux load-buffer` + `paste-buffer -p`
@@ -31,29 +32,22 @@ const {
 const {
   publicCatalog, describeManaged, resolveManagedEngine, discoverOllamaModels, discoverPiModels,
 } = require('./managed.js');
+const { validEnvKey } = require('./env-key.js');
+const { setCredential, removeCredential } = require('./credentials.js');
+const { createLaunchBroker } = require('./launch-broker.js');
+const { MINIMAL_ENV_KEYS, minimalRuntimeEnv } = require('../runtime/env.js');
 
 const STATUS_TTL_MS = 2000;
 
 // Env minimale controllato dal service (design §9a). Allowlist DURA: le definizioni
 // non possono toccare PATH/loader-key (parseDefinitions le rifiuta gia' in env);
-// qui NON passiamo MAI l'env del processo per intero. engine.env va in session via -e.
+// 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.
 // Nota: se un server tmux e' gia' in esecuzione (avviato fuori dal service), i comandi
 // ereditano l'env di quel server; la garanzia dura resta: le definizioni non possono
 // iniettare loader-key, e engine.env arriva al pane SOLO tramite chiavi validate.
-const MINIMAL_ENV_KEYS = [
-  'PATH', 'HOME', 'SHELL', 'TERM', 'LANG', 'LANGUAGE',
-  'LC_ALL', 'LC_CTYPE', 'USER', 'LOGNAME',
-  'XDG_RUNTIME_DIR', 'DBUS_SESSION_BUS_ADDRESS',
-];
 function minimalEnv() {
-  const env = {};
-  for (const k of MINIMAL_ENV_KEYS) {
-    if (process.env[k] !== undefined && process.env[k] !== '') env[k] = process.env[k];
-  }
-  if (!env.PATH) env.PATH = '/usr/local/bin:/usr/bin:/bin';
-  if (!env.HOME) env.HOME = os.homedir();
-  if (!env.TERM) env.TERM = 'xterm-256color';
-  return env;
+  return minimalRuntimeEnv(process.env, { home: os.homedir() });
 }
 
 function httpError(status, msg, data = null) { const e = new Error(msg); e.status = status; if (data) e.data = data; return e; }
@@ -88,6 +82,32 @@ function redactSecrets(text, engine, cell) {
   return out;
 }
 
+const MAX_EARLY_DIAGNOSTIC = 1200;
+
+function sanitizeEarlyDiagnostic(text, engine, cell, home) {
+  let out = redactSecrets(String(text || ''), engine, cell);
+  // ANSI CSI/OSC e byte di controllo non devono arrivare nell'errore JSON/UI.
+  out = out.replace(/\x1b\][^\x07]*(?:\x07|$)/g, '')
+    .replace(/\x1b\[[0-?]*[ -\/]*[@-~]/g, '');
+  let clean = '';
+  for (let i = 0; i < out.length; i += 1) {
+    const code = out.charCodeAt(i);
+    if (code === 9 || code === 10 || code === 13 || (code >= 32 && code !== 127)) clean += out[i];
+  }
+  out = clean;
+  if (typeof home === 'string' && home) out = out.split(home).join('~');
+  out = out
+    .replace(/\bBearer\s+\S+/gi, `Bearer ${REDACTED}`)
+    .replace(/\b([A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|AUTH)[A-Z0-9_]*)(\s*[:=]\s*)\S+/g,
+      (_m, key, sep) => `${key}${sep}${REDACTED}`)
+    .replace(/\b(?:sk|fw|fpk|hf|zai)-[A-Za-z0-9._-]{8,}\b/gi, REDACTED);
+  const lines = out.split(/\r?\n/).map((line) => line.trimEnd())
+    .filter((line) => line.trim() && !/^Pane is dead \(status /i.test(line.trim()));
+  out = lines.join('\n').trim();
+  if (out.length > MAX_EARLY_DIAGNOSTIC) out = `…${out.slice(-(MAX_EARLY_DIAGNOSTIC - 1))}`;
+  return out;
+}
+
 // Esecutore tmux: argv diretto (MAI shell). Risolve sempre {err,stdout,stderr,code}
 // cosi' il chiamante distingue "sessione assente" (code!==0 atteso) da errori reali.
 function tmuxExec(tmuxBin, args, { env, timeoutMs = 10000 } = {}) {
@@ -115,16 +135,12 @@ function promptCharsOk(prompt) {
 }
 
 // ---------------------------------------------------------------------------
-// composeLaunchArgv({tmuxSession, realCwd, engine, cell}) -> argv per new-session
-// PURA + testabile. No shell: command e args sono argv diretto. model/prompt sono
-// aggiunti solo se c'e' un VALORE effettivo (override cella || default engine).
+// Build the direct child invocation separately from tmux. This lets the secure
+// launch broker carry the complete child argv and environment in memory while
+// tmux receives only the broker helper path and a one-time nonce.
 // ---------------------------------------------------------------------------
-function composeLaunchArgv({ tmuxSession, realCwd, engine, cell }) {
-  const args = ['new-session', '-d', '-s', tmuxSession, '-c', realCwd];
-  // engine.env -> env di sessione via -e (chiavi gia' validate, no loader-key)
-  for (const [k, v] of Object.entries(engine.env || {})) args.push('-e', `${k}=${v}`);
-  // command + args: argv diretto (tmux exec, NON sh -c)
-  args.push(engine.command, ...(engine.args || []));
+function composeClientInvocation(engine, cell) {
+  const args = [...(engine.args || [])];
   // model: flag + (override cella || valore engine), solo se c'e' un valore
   if (engine.model) {
     const val = (cell.model != null && cell.model !== '') ? cell.model : engine.model.value;
@@ -137,7 +153,15 @@ function composeLaunchArgv({ tmuxSession, realCwd, engine, cell }) {
   if (engine.promptMode === 'flag' && cell.prompt) {
     args.push(engine.promptFlag, cell.prompt);
   }
-  return args;
+  return { command: engine.command, args };
+}
+
+// composeLaunchArgv({tmuxSession, realCwd, engine, cell}) -> argv per new-session
+// PURA + testabile. Provider values are deliberately absent: no `tmux -e`, no
+// environment value and no broker payload ever appears in the tmux client argv.
+function composeLaunchArgv({ tmuxSession, realCwd, engine, cell }) {
+  const child = composeClientInvocation(engine, cell);
+  return ['new-session', '-d', '-s', tmuxSession, '-c', realCwd, child.command, ...child.args];
 }
 
 // Poll has-session entro readyMs (no delay fisso cieco). Ritorna true se la sessione
@@ -152,6 +176,25 @@ async function waitAlive(tmuxBin, session, { env, readyMs }) {
   }
 }
 
+async function waitStablePane(tmuxBin, target, { env, readyMs }) {
+  const deadline = Date.now() + Math.max(0, readyMs | 0);
+  for (;;) {
+    const state = await tmuxExec(tmuxBin,
+      ['display-message', '-p', '-t', target, '#{pane_dead}\t#{pane_dead_status}\t#{pane_id}'],
+      { env, timeoutMs: 2000 });
+    if (state.err) return { alive: false, status: null, target: null };
+    const [dead, rawStatus, paneId] = state.stdout.trim().split('\t');
+    if (!/^%[0-9]+$/.test(paneId || '')) return { alive: false, status: null, target: null };
+    if (dead === '1') {
+      const status = /^-?[0-9]+$/.test(rawStatus || '') ? Number(rawStatus) : null;
+      return { alive: false, status, target: paneId };
+    }
+    if (dead !== '0') return { alive: false, status: null, target: null };
+    if (Date.now() >= deadline) return { alive: true, status: null, target: paneId };
+    await sleep(60);
+  }
+}
+
 // Iniezione prompt send-keys via bracketed paste (come skills/.../nc-send):
 // load-buffer del prompt in un buffer nominato + paste-buffer -p (bracketed),
 // poi cleanup. Readiness best-effort: se la sessione non e' viva quando paste-iamo
@@ -242,6 +285,7 @@ async function createBuiltinFleet(cfg = {}) {
   const defsPath = cfg.fleetDefsPath || path.join(home, '.nexuscrew', 'fleet.json');
   const tmuxBin = cfg.tmuxBin || process.env.TMUX_BIN || 'tmux';
   const readonly = () => (cfg.readonlyDefault === true || process.env.NEXUSCREW_READONLY === '1');
+  const launchBroker = cfg.launchBroker || createLaunchBroker({ ...cfg, home });
 
   // Bootstrap: fleet.json valido? garbage -> unavailable (fail-closed, design §7)
   const boot = loadDefinitions(defsPath);
@@ -257,12 +301,14 @@ async function createBuiltinFleet(cfg = {}) {
   function findEngine(defs, id) { return defs.engines.find((e) => e.id === id) || null; }
 
   async function refreshSessions() {
-    const r = await tmuxExec(tmuxBin, ['list-sessions', '-F', '#{session_name}'], { env: minimalEnv() });
+    const r = await tmuxExec(tmuxBin, ['list-sessions', '-F', '#{session_name}\t#{session_windows}'], { env: minimalEnv() });
     if (r.err) return new Set();            // nessun server / nessuna sessione
     const set = new Set();
     for (const line of r.stdout.split('\n')) {
-      const n = line.trim();
-      if (n) set.add(n);
+      const [rawName, rawWindows] = line.split('\t');
+      const n = String(rawName || '').trim();
+      const windows = rawWindows === undefined ? 1 : Number(rawWindows);
+      if (n && Number.isFinite(windows) && windows > 0) set.add(n);
     }
     return set;
   }
@@ -356,12 +402,32 @@ async function createBuiltinFleet(cfg = {}) {
     const realCwd = resolveCwd(cell.cwd, home);
     if (!realCwd) throw httpError(400, `cwd non valida (deve esistere sotto la home): ${cell.cwd}`);
 
-    // (4)+(5) argv diretto (no shell), env minimale + engine.env via -e.
+    // (4)+(5) argv diretto (no shell). Environment-bearing launches go
+    // through a private, one-shot Unix-socket broker so credentials never
+    // appear in `ps`, tmux argv, tmux global/session env or a temporary file.
     // '-P -F #{pane_id}': tmux stampa il pane id della sessione appena creata,
     // cosi' l'iniezione del prompt bersaglia ESATTAMENTE quel pane (audit impl
     // #5: elimina la race di riuso del nome sessione tra waitAlive e paste).
-    const argv = composeLaunchArgv({ tmuxSession: cell.tmuxSession, realCwd, engine: launchEngine, cell });
+    let tmuxLaunchEngine = launchEngine;
+    if (Object.keys(launchEngine.env || {}).length) {
+      const child = composeClientInvocation(launchEngine, cell);
+      const ticket = await launchBroker.issue({
+        command: child.command,
+        args: child.args,
+        env: { ...minimalEnv(), ...launchEngine.env },
+      });
+      tmuxLaunchEngine = {
+        command: process.execPath,
+        args: [path.join(__dirname, 'cell-exec.js'), '--socket', ticket.socketPath, '--nonce', ticket.nonce],
+        env: {}, promptMode: 'managed-argv',
+      };
+    }
+    const argv = composeLaunchArgv({ tmuxSession: cell.tmuxSession, realCwd, engine: tmuxLaunchEngine, cell });
     argv.splice(2, 0, '-P', '-F', '#{pane_id}');
+    // Mantieni il pane morto solo durante la finestra di readiness: permette di
+    // catturare un errore reale del client senza lasciare una sessione fantasma.
+    // Il separatore e' interpretato da tmux (execFile argv diretto), non da shell.
+    argv.push(';', 'set-option', '-w', '-t', `=${cell.tmuxSession}:`, 'remain-on-exit', 'on');
     const launch = await tmuxExec(tmuxBin, argv, { env: minimalEnv() });
     if (launch.err) {
       // Redazione (§9h): lo stderr di tmux puo' ecoare argv/env del comando lanciato.
@@ -376,17 +442,34 @@ async function createBuiltinFleet(cfg = {}) {
     // this readiness gate the PWA reported success and then showed nothing.
     // Always verify liveness, including cells without a system prompt.
     const readyMs = cfg.launchReadyMs != null ? cfg.launchReadyMs : 500;
-    const alive = await waitAlive(tmuxBin, cell.tmuxSession, { env: minimalEnv(), readyMs });
-    if (!alive) {
+    const paneId = launch.stdout.trim().split('\n')[0] || '';
+    const readiness = paneId.startsWith('%')
+      ? await waitStablePane(tmuxBin, paneId, { env: minimalEnv(), readyMs })
+      : { alive: await waitAlive(tmuxBin, cell.tmuxSession, { env: minimalEnv(), readyMs }), status: null, target: null };
+    if (!readiness.alive) {
+      let diagnostic = '';
+      if (readiness.target) {
+        const captured = await tmuxExec(tmuxBin,
+          ['capture-pane', '-p', '-S', '-80', '-t', readiness.target], { env: minimalEnv(), timeoutMs: 2000 });
+        if (!captured.err) diagnostic = sanitizeEarlyDiagnostic(captured.stdout, launchEngine, cell, home);
+      }
+      // remain-on-exit era soltanto diagnostico: nessun pane morto deve restare
+      // nella Fleet o nella lista tmux dopo aver raccolto l'errore.
+      await tmuxExec(tmuxBin, ['kill-session', '-t', `=${cell.tmuxSession}`], { env: minimalEnv(), timeoutMs: 2000 });
       cache = { ...cache, at: 0 };
-      throw httpError(500, `client ${launchEngine.command} terminato subito: verifica login, provider, modello e argomenti dell'engine`);
+      const client = path.basename(launchEngine.clientBinary || launchEngine.command || 'client');
+      const status = Number.isInteger(readiness.status) ? ` (exit ${readiness.status})` : '';
+      throw httpError(500, `client ${client} terminato subito${status}: ${diagnostic || 'verifica login, provider, modello e argomenti dell\'engine'}`);
+    }
+    if (readiness.target) {
+      await tmuxExec(tmuxBin,
+        ['set-option', '-w', '-t', readiness.target, 'remain-on-exit', 'off'], { env: minimalEnv(), timeoutMs: 2000 });
     }
 
     // (6) prompt send-keys: bracketed-paste best-effort, target = pane id esatto
     // (fallback al nome sessione con match esatto '=' se tmux non ha stampato l'id).
     let prompt = null;
     if (launchEngine.promptMode === 'send-keys' && cell.prompt) {
-      const paneId = launch.stdout.trim().split('\n')[0] || '';
       const target = paneId.startsWith('%') ? paneId : `=${cell.tmuxSession}`;
       prompt = await injectPrompt(tmuxBin, cell.tmuxSession, cell.prompt, {
         env: minimalEnv(),
@@ -605,6 +688,68 @@ async function createBuiltinFleet(cfg = {}) {
         .filter((cell) => cell && sessions.has(cell.tmuxSession)).map((cell) => cell.id),
     };
   }
+
+  // Ripristino engine separato e atomico. Il formato portatile non accetta mai
+  // `env` values: per un engine custom nuovo parte da env vuoto; in overwrite
+  // conserva gli eventuali valori write-only già configurati sul target.
+  async function restoreEngines(engines, opts = {}) {
+    if (readonly()) throw httpError(403, 'READONLY: restore-engines bloccato');
+    if (!Array.isArray(engines) || engines.length < 1 || engines.length > 24) {
+      throw httpError(400, 'engines deve contenere 1..24 definizioni');
+    }
+    const allowed = new Set(['id', 'label', 'rc', 'managed', 'command', 'args', 'envKeys', 'model', 'promptMode', 'promptFlag']);
+    const seen = new Set();
+    for (const engine of engines) {
+      if (!engine || typeof engine !== 'object' || Array.isArray(engine)) throw httpError(400, 'definizione engine non valida');
+      for (const key of Object.keys(engine)) if (!allowed.has(key)) throw httpError(400, `campo engine backup non ammesso: ${key}`);
+      if (typeof engine.id !== 'string' || seen.has(engine.id)) throw httpError(400, `id engine duplicato o mancante: ${engine.id || '?'}`);
+      if (engine.managed && engine.envKeys !== undefined) throw httpError(400, `envKeys non ammesso per engine managed: ${engine.id}`);
+      if (!engine.managed && (!Array.isArray(engine.envKeys)
+        || engine.envKeys.length > 32
+        || engine.envKeys.some((key) => typeof key !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(key))
+        || new Set(engine.envKeys).size !== engine.envKeys.length)) {
+        throw httpError(400, `envKeys non valido per engine: ${engine.id}`);
+      }
+      if (!engine.managed && Array.isArray(engine.args) && engine.args.some((arg) => {
+        const text = String(arg || '');
+        return /(?:bearer\s+|authorization\s*[:=]|(?:api[_-]?key|secret|token)\s*[:=])/i.test(text)
+          || /^-{1,2}(?:api[-_]?key|access[-_]?key|auth(?:orization)?[-_]?token|token|secret|password|credential)(?:$|=)/i.test(text)
+          || /\b(?:sk|fw|fpk|hf|zai)[-_][A-Za-z0-9._-]{8,}\b/i.test(text)
+          || /https?:\/\/[^\s/@:]+:[^\s/@]+@/i.test(text);
+      })) {
+        throw httpError(400, `argomento potenzialmente segreto non ammesso per engine: ${engine.id}`);
+      }
+      seen.add(engine.id);
+    }
+    const defs = reloadDefs();
+    const conflicts = engines.filter((engine) => !!findEngine(defs, engine.id)).map((engine) => engine.id);
+    if (conflicts.length && opts.overwrite !== true) {
+      throw httpError(409, `engine già esistenti: ${conflicts.join(', ')}`, { code: 'engine-conflicts', conflicts });
+    }
+    const sessions = await refreshSessions();
+    const affected = defs.cells.filter((cell) => conflicts.includes(cell.engine) && sessions.has(cell.tmuxSession)).map((cell) => cell.id);
+    await mutate(defs, (draft) => {
+      for (const portable of engines) {
+        const index = draft.engines.findIndex((current) => current.id === portable.id);
+        const current = index >= 0 ? draft.engines[index] : null;
+        const next = { ...portable };
+        if (!next.managed) {
+          const keys = next.envKeys;
+          delete next.envKeys;
+          next.env = Object.fromEntries(keys.map((key) => [key,
+            current && !current.managed && Object.prototype.hasOwnProperty.call(current.env || {}, key)
+              ? current.env[key] : '',
+          ]));
+        }
+        if (index >= 0) draft.engines[index] = next; else draft.engines.push(next);
+      }
+    });
+    return {
+      ok: true, count: engines.length,
+      created: engines.filter((engine) => !conflicts.includes(engine.id)).map((engine) => engine.id),
+      replaced: conflicts, needsRestart: affected,
+    };
+  }
   async function removeCell(id, opts = {}) {
     if (readonly()) throw httpError(403, 'READONLY: remove-cell bloccato');
     let defs = reloadDefs();
@@ -694,10 +839,64 @@ async function createBuiltinFleet(cfg = {}) {
         ...(c.permissionPolicies ? { permissionPolicies: { ...c.permissionPolicies } } : {}),
       })),
       managedCatalog: publicCatalog(),
-      managedConfig: { providerSecretsPath: cfg.providerSecretsPath || path.join(home, '.nexuscrew', 'providers.env') },
+      managedConfig: {
+        providerSecretsPath: cfg.providerSecretsPath || path.join(home, '.nexuscrew', 'providers.env'),
+        providerShellPath: cfg.providerShellPath || path.join(home, '.config', 'ai-shell', 'providers.zsh'),
+        providerKeysPath: cfg.providerKeysPath || path.join(home, '.config', 'keys', 'ai.env'),
+        providerSecurePath: cfg.providerSecurePath || path.join(home, '.config', 'secure', '.env'),
+        localCredentialStore: true,
+      },
     };
   }
 
+  function credentialRequirements() {
+    const defs = reloadDefs(); const map = new Map();
+    for (const engine of defs.engines) {
+      if (!engine.managed) continue;
+      const info = describeManaged(engine.managed, { ...cfg, home });
+      const envKey = info.auth;
+      if (!validEnvKey(envKey) || envKey === 'login' || envKey === 'none') continue;
+      const current = map.get(envKey) || {
+        envKey, configured: false, source: 'missing', engines: [], activeCells: [],
+      };
+      current.configured ||= info.authConfigured === true;
+      if (info.credentialSource && info.credentialSource !== 'missing') current.source = info.credentialSource;
+      current.engines.push(engine.id);
+      map.set(envKey, current);
+    }
+    return { defs, map };
+  }
+
+  async function credentialStatus() {
+    const { defs, map } = credentialRequirements();
+    const sessions = await refreshSessions();
+    for (const entry of map.values()) {
+      entry.engines.sort();
+      entry.activeCells = defs.cells
+        .filter((cell) => entry.engines.includes(cell.engine) && sessions.has(cell.tmuxSession))
+        .map((cell) => cell.id).sort();
+    }
+    return { credentials: [...map.values()].sort((a, b) => a.envKey.localeCompare(b.envKey)) };
+  }
+
+  async function setLocalCredential(envKey, value) {
+    if (readonly()) throw httpError(403, 'READONLY: credential write blocked');
+    const { map } = credentialRequirements();
+    if (!map.has(envKey)) throw httpError(400, 'credential key is not required by a configured engine');
+    try { setCredential({ ...cfg, home }, envKey, value, home); }
+    catch (error) { throw httpError(400, error.message); }
+    return credentialStatus();
+  }
+
+  async function removeLocalCredential(envKey) {
+    if (readonly()) throw httpError(403, 'READONLY: credential removal blocked');
+    const { map } = credentialRequirements();
+    if (!map.has(envKey)) throw httpError(400, 'credential key is not required by a configured engine');
+    try { removeCredential({ ...cfg, home }, envKey, home); }
+    catch (error) { throw httpError(400, error.message); }
+    return credentialStatus();
+  }
+
   // Scrive il draft mutato; atomicWrite valida PRIMA (fail-closed). Su input
   // invalido: backup predecessore + throw -> httpError(400) (mai garbage).
   async function mutate(defs, mutator) {
@@ -768,24 +967,30 @@ async function createBuiltinFleet(cfg = {}) {
   }
 
   function capabilities() {
-    return ['status', 'up', 'down', 'restart', 'engine', 'boot', 'define', 'edit', 'remove', 'import', 'restore', 'schema', 'definitions'];
+    return ['status', 'up', 'down', 'restart', 'engine', 'boot', 'define', 'edit', 'remove', 'import', 'restore', 'schema', 'definitions', 'credentials'];
   }
 
+  async function close() { await launchBroker.close(); }
+
   return {
     available: true,
     provider: 'builtin',
     status, up, down, restart, engine: setEngine, boot: setBoot, isCellSession,
     defineEngine, editEngine, removeEngine,
-    defineCell, editCell, removeCell, importCell, restoreCells,
+    defineCell, editCell, removeCell, importCell, restoreCells, restoreEngines,
     schema, definitions, capabilities,
+    credentialStatus, setLocalCredential, removeLocalCredential, close,
   };
 }
 
 module.exports = {
   createBuiltinFleet,
   composeLaunchArgv,
+  composeClientInvocation,
   minimalEnv,
   promptCharsOk,
   redactSecrets,
+  sanitizeEarlyDiagnostic,
+  waitStablePane,
   MINIMAL_ENV_KEYS,
 };

package/lib/fleet/cell-exec.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+'use strict';
+
+// Tiny launch helper. It receives only a local socket path and a random,
+// single-use nonce in argv. Provider values arrive over the private Unix
+// socket, stay in memory and are passed directly to the child process.
+const net = require('node:net');
+const { spawn } = require('node:child_process');
+const { MAX_PAYLOAD } = require('./launch-broker.js');
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 2) {
+    if (argv[i] === '--socket') out.socketPath = argv[i + 1];
+    else if (argv[i] === '--nonce') out.nonce = argv[i + 1];
+    else return null;
+  }
+  if (typeof out.socketPath !== 'string' || !out.socketPath
+    || typeof out.nonce !== 'string' || !/^[a-f0-9]{64}$/.test(out.nonce)) return null;
+  return out;
+}
+
+function validPayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return false;
+  if (typeof payload.command !== 'string' || !payload.command || !Array.isArray(payload.args)) return false;
+  if (!payload.env || typeof payload.env !== 'object' || Array.isArray(payload.env)) return false;
+  return payload.args.every((v) => typeof v === 'string')
+    && Object.entries(payload.env).every(([k, v]) => /^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(k) && typeof v === 'string');
+}
+
+function receivePayload(socketPath, nonce, timeoutMs = 5000) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let data = Buffer.alloc(0); let expected = null; let done = false;
+    const finish = (error, payload) => {
+      if (done) return; done = true; socket.destroy();
+      if (error) reject(error); else resolve(payload);
+    };
+    socket.setTimeout(timeoutMs, () => finish(new Error('launch broker timed out')));
+    socket.once('connect', () => socket.write(`${JSON.stringify({ nonce })}\n`));
+    socket.on('data', (chunk) => {
+      data = Buffer.concat([data, chunk]);
+      if (expected === null && data.length >= 4) {
+        expected = data.readUInt32BE(0); data = data.subarray(4);
+        if (!expected || expected > MAX_PAYLOAD) return finish(new Error('invalid launch payload length'));
+      }
+      if (expected !== null && data.length >= expected) {
+        try {
+          const payload = JSON.parse(data.subarray(0, expected).toString('utf8'));
+          if (!validPayload(payload)) return finish(new Error('invalid launch payload'));
+          finish(null, payload);
+        } catch (error) { finish(error); }
+      }
+    });
+    socket.once('error', (error) => finish(error));
+    socket.once('end', () => { if (!done) finish(new Error('launch broker closed early')); });
+  });
+}
+
+async function main(argv = process.argv.slice(2), seams = {}) {
+  const parsed = parseArgs(argv);
+  if (!parsed) throw new Error('usage: cell-exec --socket <path> --nonce <hex>');
+  const payload = await (seams.receivePayload || receivePayload)(parsed.socketPath, parsed.nonce);
+  const spawnImpl = seams.spawn || spawn;
+  const child = spawnImpl(payload.command, payload.args, { env: payload.env, stdio: 'inherit' });
+  for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) {
+    process.once(signal, () => { try { child.kill(signal); } catch (_) {} });
+  }
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code, signal) => resolve(signal ? 128 : (code == null ? 1 : code)));
+  });
+}
+
+if (require.main === module) {
+  main().then((code) => { process.exitCode = code; }).catch((error) => {
+    process.stderr.write(`nexuscrew cell launch failed: ${error.message}\n`); process.exitCode = 1;
+  });
+}
+
+module.exports = { parseArgs, validPayload, receivePayload, main };

package/lib/fleet/credentials.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { validEnvKey } = require('./env-key.js');
+
+const SCHEMA_VERSION = 1;
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_VALUE_BYTES = 16 * 1024;
+
+function credentialsPath(cfg = {}, home = cfg.home || os.homedir()) {
+  return cfg.credentialsPath || process.env.NEXUSCREW_CREDENTIALS_FILE
+    || path.join(home, '.nexuscrew', 'credentials.json');
+}
+
+function ownedByCurrentUser(st) {
+  return typeof process.getuid !== 'function' || st.uid === process.getuid();
+}
+
+function safePrivateDir(dir, { create = false } = {}) {
+  let st;
+  try { st = fs.lstatSync(dir); }
+  catch (error) {
+    if (error.code !== 'ENOENT' || !create) throw error;
+    fs.mkdirSync(dir, { recursive: false, mode: 0o700 });
+    st = fs.lstatSync(dir);
+  }
+  if (!st.isSymbolicLink() && st.isDirectory() && ownedByCurrentUser(st) && (st.mode & 0o077) && create) {
+    fs.chmodSync(dir, 0o700); st = fs.lstatSync(dir);
+  }
+  if (st.isSymbolicLink() || !st.isDirectory() || !ownedByCurrentUser(st) || (st.mode & 0o077)) {
+    throw new Error('unsafe credential directory (must be user-owned mode 0700, not a symlink)');
+  }
+  return st;
+}
+
+function normalizeCredentials(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('invalid credential store');
+  if (raw.schemaVersion !== SCHEMA_VERSION || !raw.credentials
+    || typeof raw.credentials !== 'object' || Array.isArray(raw.credentials)) {
+    throw new Error('invalid credential store schema');
+  }
+  const credentials = {};
+  for (const [key, value] of Object.entries(raw.credentials)) {
+    if (!validEnvKey(key) || typeof value !== 'string' || !value
+      || Buffer.byteLength(value) > MAX_VALUE_BYTES || /[\x00\r\n]/.test(value)) {
+      throw new Error('invalid credential store entry');
+    }
+    credentials[key] = value;
+  }
+  return credentials;
+}
+
+function readCredentialStore(cfg = {}, home = cfg.home || os.homedir()) {
+  const file = credentialsPath(cfg, home);
+  try {
+    const parent = path.dirname(file);
+    safePrivateDir(parent);
+    const st = fs.lstatSync(file);
+    if (st.isSymbolicLink() || !st.isFile() || !ownedByCurrentUser(st)
+      || (st.mode & 0o077) || st.size > MAX_FILE_BYTES) {
+      throw new Error('unsafe credential store (must be user-owned mode 0600, not a symlink)');
+    }
+    return normalizeCredentials(JSON.parse(fs.readFileSync(file, 'utf8')));
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw error;
+  }
+}
+
+function validateCredential(key, value) {
+  if (!validEnvKey(key)) throw new Error('invalid credential environment key');
+  if (typeof value !== 'string' || !value || Buffer.byteLength(value) > MAX_VALUE_BYTES
+    || /[\x00\r\n]/.test(value)) {
+    throw new Error('credential must be 1-16384 bytes without control line breaks');
+  }
+}
+
+function atomicWriteStore(file, credentials) {
+  const dir = path.dirname(file);
+  safePrivateDir(dir, { create: true });
+  try {
+    const existing = fs.lstatSync(file);
+    if (existing.isSymbolicLink() || !existing.isFile() || !ownedByCurrentUser(existing)
+      || (existing.mode & 0o077)) throw new Error('unsafe existing credential store');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const body = `${JSON.stringify({ schemaVersion: SCHEMA_VERSION, credentials }, null, 2)}\n`;
+  if (Buffer.byteLength(body) > MAX_FILE_BYTES) throw new Error('credential store is too large');
+  const tmp = path.join(dir, `.credentials.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`);
+  let fd;
+  try {
+    fd = fs.openSync(tmp, 'wx', 0o600);
+    fs.writeFileSync(fd, body, 'utf8');
+    fs.fsyncSync(fd);
+    fs.closeSync(fd); fd = undefined;
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, file);
+    // Best effort directory fsync: supported on Linux/macOS, harmlessly
+    // skipped on filesystems that do not permit opening directories.
+    try {
+      const dfd = fs.openSync(dir, 'r');
+      try { fs.fsyncSync(dfd); } finally { fs.closeSync(dfd); }
+    } catch (_) {}
+  } finally {
+    if (fd !== undefined) { try { fs.closeSync(fd); } catch (_) {} }
+    try { fs.unlinkSync(tmp); } catch (_) {}
+  }
+}
+
+function setCredential(cfg, key, value, home = cfg.home || os.homedir()) {
+  validateCredential(key, value);
+  safePrivateDir(path.dirname(credentialsPath(cfg, home)), { create: true });
+  const current = readCredentialStore(cfg, home);
+  atomicWriteStore(credentialsPath(cfg, home), { ...current, [key]: value });
+}
+
+function removeCredential(cfg, key, home = cfg.home || os.homedir()) {
+  if (!validEnvKey(key)) throw new Error('invalid credential environment key');
+  safePrivateDir(path.dirname(credentialsPath(cfg, home)), { create: true });
+  const current = readCredentialStore(cfg, home);
+  if (!Object.prototype.hasOwnProperty.call(current, key)) return false;
+  delete current[key];
+  atomicWriteStore(credentialsPath(cfg, home), current);
+  return true;
+}
+
+module.exports = {
+  SCHEMA_VERSION, MAX_FILE_BYTES, MAX_VALUE_BYTES,
+  credentialsPath, readCredentialStore, setCredential, removeCredential,
+  safePrivateDir, validateCredential,
+};

package/lib/fleet/env-key.js

@@ -0,0 +1,12 @@
+'use strict';
+
+// Shared by managed providers, the local credential store and the HTTP API.
+// Mixed-case names are valid POSIX environment keys and are intentionally
+// preserved for custom providers.
+const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+
+function validEnvKey(value) {
+  return typeof value === 'string' && ENV_KEY_RE.test(value);
+}
+
+module.exports = { ENV_KEY_RE, validEnvKey };