zback 1.0.0 → 1.3.0

package/DISCLOSURE

@@ -0,0 +1,14 @@
+ZBack is an opt-in remote shell administration tool for devices owned or explicitly authorized by the operator. It supports sending a shell command to a local Node.js agent through a WebSocket relay using a private, high-entropy session capability and the Model Context Protocol (MCP).
+
+Security-sensitive functionality:
+- A user manually starts the ZBack command and approves remote shell administration on the first run. The decision is stored in a local user-scoped file; subsequent commands do not require repeated prompts.
+- A background Node.js worker may persist after the invoking terminal detaches. It can be stopped with `zback --stop`.
+- Remote shell commands execute with the operating-system permissions of the account that launched the agent.
+- The worker connects outbound to the configured secure WebSocket endpoint. It does not open an inbound shell listener.
+- The server exposes an MCP endpoint that routes authorized commands to connected workers when the caller presents the private session capability.
+- A randomly generated credential stored with restrictive file permissions stabilizes the session identifier across reconnects. The identifier is a bearer credential and must be kept secret.
+- The operator can inspect activity with `zback`, `zback --status`, `zback --logs`, and rotate the credential with `zback --reset-key` after stopping the agent.
+
+The package has no install-time scripts, no hidden persistence or system service installation, no credential collection, no code obfuscation, and no automatic execution on installation. Remote shell access is a powerful capability and should only be enabled on systems the operator is authorized to manage.
+
+The separately deployed ZBack backend should be exposed via HTTPS/WSS, behind a TLS-terminating reverse proxy. Public access does not imply authorization to use another person's session. Access is controlled by possession of the private session ID.

package/README.md

@@ -1,31 +1,69 @@
-# zback (CLI global)
+# ZBack CLI
 
-Agente CLI para **Node.js 22 o superior**, sin dependencias npm externas. Se conecta a tu backend por WebSocket cifrado, enseña un ID temporal y solicita **autorización presencial para cada comando**.
+ZBack is a deliberately opt-in remote administration agent for systems you own or are authorized to manage. The package uses Node.js 22 or later, has **no third-party runtime dependencies** and runs no installation scripts.
 
-## Instalar
+> **Security:** ZBack grants remote shell access with your local user privileges to anyone who possesses its private session ID. Treat that ID as a password. Do not publish it, paste it in issue reports, or share screenshots containing it. Do not run ZBack as root or as an account with unnecessary permissions.
 
-```bash
-npm install -g .
-zback --help
+## Install and start
+
+```sh
+npm install -g zback@1.2.0
 zback
 ```
 
-Extrae este ZIP antes de ejecutar `npm install -g .` dentro de su directorio.
+On the first run, ZBack explains the remote-shell capability and asks for authorization once. It stores that decision locally, then creates a private agent credential. There are no prompts for each command.
+
+The default server is `wss://zb.soymaycol.icu/ws`. To use your own backend:
+
+```sh
+zback --url wss://your-domain.example/ws
+```
+
+For development only:
+
+```sh
+zback --url ws://127.0.0.1:8787/ws
+```
+
+The client and backend must both be **version 1.2.0** because the connection handshake changed. The backend must be deployed before a remote client can connect.
+
+## Terminal and process lifecycle
 
-Opciones:
+| Command | Behavior |
+| --- | --- |
+| `zback` | Start if needed and attach the terminal to a live event display |
+| `zback --background` | Start the agent without keeping a live terminal display |
+| `zback --status` | Show connection status, process ID and private session ID |
+| `zback --logs` | Display recent connection and command activity |
+| `zback --follow` | Attach to live events from the existing background agent |
+| `zback --stop` | Stop the background agent |
+| `zback --reset-key` | Change the device identity after the agent is stopped |
 
-```bash
-zback --url wss://zb.soymaycol.icu/ws
-zback --cwd /ruta/a/proyecto --timeout 15000 --max-output 32768
-zback --no-reconnect
+`Ctrl+C` while viewing events **detaches the display**, but the agent stays running. Use `zback --stop` to disconnect. The server session ID stays the same over ordinary network reconnections and backend restarts, as long as the private local agent credential remains unchanged.
+
+After a device restart, ZBack does **not** silently install an autostart service. Launch it again when needed. Android/Termux process and battery restrictions can still terminate background tasks; a Node.js program cannot override the operating system's lifecycle.
+
+## Configuration
+
+```sh
+zback --cwd ./workspace --timeout 300000 --max-output 524288
+zback --url wss://your-domain.example/ws --background
 ```
 
-Para pruebas locales: `zback --url ws://127.0.0.1:8787/ws`.
+The client validates TLS on remote connections. Only loopback addresses are allowed for unencrypted `ws://`. Server resource protection and command timeouts are operational safety controls, not per-user paid quotas.
+
+Files are under `~/.local/state/zback` on Linux/Termux and `%LOCALAPPDATA%/zback` on Windows. To use a custom location, set `ZBACK_STATE_DIR`. `agent.key` and the local state files must not be shared. Use `zback --reset-key` to invalidate a previously disclosed session ID.
+
+## MCP
 
-- Escribe `ACEPTO` para iniciar la sesión.
-- Verás un **ID nuevo por cada conexión**. No es una contraseña creada por el usuario, pero funciona como credencial temporal: mantenlo privado.
-- Cuando el MCP pida ejecutar un comando, verás su contenido completo y tendrás que escribir `s` para autorizarlo. Pulsar Enter, responder `n` o agotar el tiempo lo rechaza.
-- Ctrl+C termina la conexión; desconectarse invalida el ID.
-- Conexiones públicas `ws://` sin TLS están bloqueadas.
+The companion backend serves `POST /mcp` with `zback_status` and `zback_execute`. The client prints a **private** session ID for passing to these tools. Only grant your own session ID to trusted applications. MCP clients, LLMs and tools that receive the ID can perform any command your operating-system account can perform.
 
-**Advertencia:** revisar antes de aprobar es fundamental: cualquier comando autorizado se ejecuta con los permisos de tu usuario. El backend no hace que un comando sea confiable.
+## Security disclosure and review
+
+The npm package declares its remote administration capabilities as dual-use software in `contentPolicy` and the root `DISCLOSURE` file. It does not attempt to conceal shell execution, evade security scanning or override npm's decisions. Review the source before running, and follow npm's official manual appeal process if a publication is flagged.
+
+## Tests
+
+```sh
+npm test
+```

package/bin/zback.js

@@ -1,175 +1,219 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { existsSync, realpathSync, statSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readSync, realpathSync, statSync, watchFile, unwatchFile } from 'node:fs';
 import { resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { fileURLToPath } from 'node:url';
+import { connectAgent, execute } from '../src/agent.js';
+import { activeSession, agentKey, consentFile, hasConsent, initStateDir, logFile, readJson, resetKey, sameSession, saveJson, settingsFile, stateFile, alive } from '../src/runtime.js';
 
+const ENTRY = fileURLToPath(import.meta.url);
+const VERSION = '1.2.0';
 const DEFAULT_URL = 'wss://zb.soymaycol.icu/ws';
 
 function help() {
-  console.log(`ZBack 1.0.0 - WebSocket agent (Node.js >=22)
+  console.log(`ZBack ${VERSION} | Authorized remote shell administration
 
-Uso: zback [opciones]
+Usage:
+  zback                     Start the agent and display live events
+  zback --background        Start without attaching the terminal
+  zback --status            Show agent status, PID and private session ID
+  zback --logs              Show recent agent events
+  zback --follow            Follow live events from a running agent
+  zback --stop              Stop the agent
+  zback --reset-key         Rotate local agent identity while stopped
 
-  --url <wss://.../ws>   WebSocket de destino (default: ${DEFAULT_URL})
-  --cwd <directorio>     Directorio desde el cual ejecutar comandos
-  --timeout <ms>        Máximo tiempo de ejecución por comando (1000-300000)
-  --max-output <bytes>  Límite combinado de stdout+stderr (1024-262144)
-  --no-reconnect        Desactivar reconexión automática
-  --help                Mostrar esta ayuda
+Options:
+  --url <wss://.../ws>      Server endpoint (default: ${DEFAULT_URL})
+  --cwd <directory>        Working directory for commands
+  --timeout <ms>           Command timeout (1000-3600000)
+  --max-output <bytes>     Captured output (1024-786432)
+  --no-reconnect           Stop after a connection is lost
+  --help                   Display this help
 
-Se solicita permiso al inicio y cada vez que un comando remoto llega.
-No hay API keys ni ejecución sin confirmación.`);
+ZBack runs shell commands with your account privileges. Initial interactive
+consent is required once, not for every command. Keep the session ID private.
+Ctrl+C detaches the live display; the agent continues running.
+Use --stop to actually disconnect the agent.`);
 }
 
 export function parseArgs(args) {
-  const options = { url: DEFAULT_URL, cwd: process.cwd(), timeout: 30000, maxOutput: 65536, reconnect: true };
-  const set = new Set(['--url', '--cwd', '--timeout', '--max-output']);
+  const options = { url: DEFAULT_URL, cwd: process.cwd(), timeout: 120000, maxOutput: 262144, reconnect: true, background: false };
+  const values = new Set(['--url', '--cwd', '--timeout', '--max-output']);
+  let action = 'start';
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
     if (flag === '--help' || flag === '-h') return { help: true };
+    if (flag === '--worker') return { worker: true };
+    if (['--status', '--stop', '--logs', '--follow', '--reset-key'].includes(flag)) {
+      if (action !== 'start') throw new Error('Choose only one action');
+      action = flag.slice(2);
+      continue;
+    }
+    if (flag === '--background' || flag === '--detach') { options.background = true; continue; }
     if (flag === '--no-reconnect') { options.reconnect = false; continue; }
-    if (!set.has(flag) || i + 1 >= args.length) throw new Error(`Argumento desconocido o incompleto: ${flag}`);
+    if (!values.has(flag) || i + 1 >= args.length) throw new Error(`Unknown or incomplete argument: ${flag}`);
     const value = args[++i];
     if (flag === '--url') options.url = value;
     if (flag === '--cwd') options.cwd = resolve(value);
     if (flag === '--timeout') options.timeout = Number(value);
     if (flag === '--max-output') options.maxOutput = Number(value);
   }
-  if (!Number.isSafeInteger(options.timeout) || options.timeout < 1000 || options.timeout > 300000) throw new Error('--timeout debe estar entre 1000 y 300000 ms');
-  if (!Number.isSafeInteger(options.maxOutput) || options.maxOutput < 1024 || options.maxOutput > 262144) throw new Error('--max-output debe estar entre 1024 y 262144 bytes');
-  if (!existsSync(options.cwd) || !statSync(options.cwd).isDirectory()) throw new Error('--cwd debe ser un directorio existente');
+  if (action !== 'start') return { action };
+  if (!Number.isSafeInteger(options.timeout) || options.timeout < 1000 || options.timeout > 3600000) throw new Error('--timeout must be between 1000 and 3600000 ms');
+  if (!Number.isSafeInteger(options.maxOutput) || options.maxOutput < 1024 || options.maxOutput > 786432) throw new Error('--max-output must be between 1024 and 786432 bytes');
+  if (!existsSync(options.cwd) || !statSync(options.cwd).isDirectory()) throw new Error('--cwd must be an existing directory');
   const url = new URL(options.url);
-  if (url.protocol !== 'wss:' && !(url.protocol === 'ws:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))) {
-    throw new Error('Solo se permite wss:// público o ws:// local. Usa TLS para conexiones remotas.');
-  }
-  if (url.username || url.password || url.search || url.hash || url.pathname !== '/ws') throw new Error('URL inválida: usa una dirección WebSocket terminada en /ws sin credenciales ni parámetros');
-  return options;
+  if (url.protocol !== 'wss:' && !(url.protocol === 'ws:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))) throw new Error('Use wss:// for remote connections or ws:// on localhost');
+  if (url.username || url.password || url.search || url.hash || url.pathname !== '/ws') throw new Error('Expected an endpoint ending in /ws without credentials in the URL');
+  return { ...options, action };
 }
 
-export function execute(command, cwd, timeoutMs, maxOutput) {
-  return new Promise(resolveResult => {
-    let finished = false, timedOut = false, truncated = false;
-    const chunks = { stdout: [], stderr: [] };
-    let collected = 0;
-    let child;
-    try {
-      child = spawn(command, { cwd, shell: true, windowsHide: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
-    } catch (err) {
-      resolveResult({ ok: false, code: null, stdout: '', stderr: String(err.message) });
-      return;
-    }
-    const add = (kind, chunk) => {
-      const remaining = maxOutput - collected;
-      if (remaining <= 0) { truncated = true; return; }
-      if (chunk.length > remaining) truncated = true;
-      const part = chunk.subarray(0, remaining);
-      collected += part.length;
-      chunks[kind].push(part);
-    };
-    child.stdout.on('data', b => add('stdout', b));
-    child.stderr.on('data', b => add('stderr', b));
-    const timer = setTimeout(() => {
-      timedOut = true;
+async function confirmOnce() {
+  if (hasConsent()) return true;
+  if (!stdin.isTTY || !stdout.isTTY) throw new Error('First-run shell authorization requires an interactive terminal');
+  console.log('ZBack permits remote shell commands through a private session credential.');
+  console.log('These commands run as your current user. Do not share your session ID.');
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await rl.question('Authorize remote shell administration on this device? [y/N] ');
+    if (!['y', 'yes'].includes(answer.trim().toLowerCase())) return false;
+    saveJson(consentFile, { approved: true, at: new Date().toISOString() });
+    return true;
+  } finally { rl.close(); }
+}
+
+async function worker() {
+  if (!hasConsent()) throw new Error('Shell access is not authorized. Run zback interactively first');
+  const settings = readJson(settingsFile);
+  if (!settings || !settings.url || !settings.cwd) throw new Error('Missing agent settings');
+  const started = process.env.ZBACK_WORKER_NONCE;
+  if (!started) throw new Error('Worker must be launched through zback');
+  const key = agentKey();
+  const mark = data => {
+    const previous = readJson(stateFile);
+    if (previous && previous.status !== 'stopped' && previous.pid !== process.pid && alive(previous.pid)) return;
+    saveJson(stateFile, { pid: process.pid, started, updated: new Date().toISOString(), ...data });
+  };
+  mark({ status: 'connecting', id: null });
+  try { await connectAgent(settings, mark, key); }
+  finally { if (sameSession(process.pid, started)) mark({ status: 'stopped', id: null }); }
+}
+
+function showStatus() {
+  const state = activeSession();
+  if (!state) { console.log('Status: stopped'); return false; }
+  console.log(`Status: ${state.status}\nPID: ${state.pid}${state.id ? `\nSession ID: ${state.id}` : ''}\nUpdated: ${state.updated || 'unknown'}`);
+  return true;
+}
+
+function recentLog() {
+  if (!existsSync(logFile)) { console.log('No agent logs yet'); return; }
+  const fd = openSync(logFile, 'r');
+  try {
+    const size = statSync(logFile).size;
+    const readSize = Math.min(size, 12000);
+    const buffer = Buffer.alloc(readSize);
+    readSync(fd, buffer, 0, readSize, size - readSize);
+    console.log(buffer.toString('utf8').replace(/^.*?\n/, size > readSize ? '' : '$&').trimEnd());
+  } finally { closeSync(fd); }
+}
+
+async function follow() {
+  if (!stdin.isTTY || !stdout.isTTY) return;
+  console.log('Live agent events. Ctrl+C detaches; the agent stays active.');
+  recentLog();
+  let position = existsSync(logFile) ? statSync(logFile).size : 0;
+  await new Promise(resolve => {
+    const readNew = () => {
       try {
-        if (process.platform === 'win32') spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
-        else process.kill(-child.pid, 'SIGKILL');
-      } catch { try { child.kill('SIGKILL'); } catch {} }
-    }, timeoutMs);
-    const finish = (code, message = '') => {
-      if (finished) return;
-      finished = true;
-      clearTimeout(timer);
-      resolveResult({ ok: code === 0 && !timedOut, code: Number.isInteger(code) ? code : null,
-        stdout: Buffer.concat(chunks.stdout).toString('utf8'),
-        stderr: Buffer.concat(chunks.stderr).toString('utf8') + message,
-        truncated, timedOut });
+        if (!existsSync(logFile)) return;
+        const size = statSync(logFile).size;
+        if (size < position) position = 0;
+        if (size === position) return;
+        const fd = openSync(logFile, 'r');
+        try {
+          const bytes = Math.min(size - position, 512 * 1024);
+          const buffer = Buffer.alloc(bytes);
+          readSync(fd, buffer, 0, bytes, position);
+          position += bytes;
+          stdout.write(buffer.toString('utf8'));
+        } finally { closeSync(fd); }
+      } catch (error) { console.error(`Log monitor: ${error.message}`); }
     };
-    child.once('error', error => finish(null, `\n${error.message}`));
-    child.once('close', code => finish(code));
+    const stop = () => { unwatchFile(logFile, readNew); process.removeListener('SIGINT', stop); process.removeListener('SIGTERM', stop); console.log('\nDetached. Agent continues in the background.'); resolve(); };
+    watchFile(logFile, { interval: 400 }, readNew);
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    readNew();
   });
 }
 
-export async function main(args = process.argv.slice(2)) {
-  let options;
-  try { options = parseArgs(args); }
-  catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 2; return; }
-  if (options.help) return help();
-  if (!stdin.isTTY || !stdout.isTTY) {
-    console.error('Error: se requiere una terminal interactiva para confirmar comandos.');
-    process.exitCode = 2; return;
+async function start(options) {
+  const existing = activeSession();
+  if (existing) {
+    console.log(existing.id ? `Session ID: ${existing.id}` : `ZBack is ${existing.status} (PID ${existing.pid}).`);
+    if (!options.background) await follow();
+    return;
   }
-  console.log('\nZBack - acceso remoto a tu shell');
-  console.log('ADVERTENCIA: ejecutar comandos ajenos puede borrar archivos, modificar el sistema o comprometer información.');
-  console.log('Conéctate solo a tu propio servidor. Revisa cada comando antes de aprobarlo.');
-  console.log(`Servidor: ${options.url}`);
-  console.log(`Directorio: ${options.cwd}`);
-  const rl = createInterface({ input: stdin, output: stdout });
-  const consent = await rl.question('Escribe ACEPTO para habilitar solicitudes remotas: ');
-  if (consent.trim() !== 'ACEPTO') { console.log('Cancelado.'); rl.close(); return; }
-
-  let ws, active = false, stopped = false, retries = 0;
-  let queue = Promise.resolve();
-  const wait = ms => new Promise(resolveWait => setTimeout(resolveWait, ms));
-  const shutdown = () => { stopped = true; try { ws?.close(); } catch {} rl.close(); };
-  process.once('SIGINT', shutdown);
-  process.once('SIGTERM', shutdown);
-
-  while (!stopped) {
-    try {
-      ws = new WebSocket(options.url);
-      await new Promise((accept, reject) => {
-        ws.addEventListener('open', accept, { once: true });
-        ws.addEventListener('error', () => reject(new Error('Conexión fallida')), { once: true });
-      });
-      active = true;
-      retries = 0;
-      console.log('\nConectado. Esperando solicitudes...');
-      const closed = new Promise(resolveClosed => ws.addEventListener('close', resolveClosed, { once: true }));
-      ws.addEventListener('message', event => {
-        let message;
-        try { message = JSON.parse(event.data); } catch { return; }
-        if (message.type === 'welcome') {
-          console.log(`\nID temporal: ${message.id}`);
-          console.log('Comparte el ID solo con el cliente MCP autorizado. No se mostrará en el backend.');
-        }
-        if (message.type === 'command' && typeof message.requestId === 'string') {
-          queue = queue.then(async () => {
-            const command = message.command;
-            if (typeof command !== 'string' || !command.trim() || command.length > 1000 || command.includes('\0')) return;
-            console.log(`\nSolicitud de ejecución recibida:\n  ${JSON.stringify(command)}`);
-            let approval;
-            try {
-              approval = await rl.question('¿Autorizar este comando? [s/N]: ', { signal: AbortSignal.timeout(Math.min(message.approvalTimeoutMs ?? 60000, 300000)) });
-            } catch { approval = ''; }
-            let result;
-            if (approval.trim().toLowerCase() !== 's') {
-              result = { ok: false, rejected: true, code: null, stdout: '', stderr: 'Rechazado por la persona conectada.' };
-              console.log('Comando rechazado.');
-            } else {
-              const timeout = Math.min(options.timeout, Number.isInteger(message.timeoutMs) ? message.timeoutMs : options.timeout);
-              console.log('Ejecutando...');
-              result = await execute(command, options.cwd, timeout, options.maxOutput);
-              console.log(result.ok ? 'Comando completado.' : 'Comando terminado con error o límite.');
-            }
-            if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'result', requestId: message.requestId, ...result }));
-          }).catch(error => console.error(`Error al procesar solicitud: ${error.message}`));
-        }
-      });
-      await closed;
-      console.log('\nDesconectado. El ID anterior ya no es válido.');
-    } catch (error) { console.error(`Conexión: ${error.message}`); }
-    active = false;
-    if (!options.reconnect || stopped) break;
-    const delay = Math.min(30000, 1000 * 2 ** Math.min(retries++, 5));
-    console.log(`Reconectando en ${Math.ceil(delay / 1000)} s...`);
-    await wait(delay);
+  if (!(await confirmOnce())) { console.log('Authorization declined'); return; }
+  initStateDir();
+  agentKey();
+  saveJson(settingsFile, { url: options.url, cwd: options.cwd, timeout: options.timeout, maxOutput: options.maxOutput, reconnect: options.reconnect });
+  const fd = openSync(logFile, 'a', 0o600);
+  const started = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  let child;
+  try {
+    child = spawn(process.execPath, [ENTRY, '--worker'], {
+      detached: true, windowsHide: true,
+      stdio: ['ignore', fd, fd],
+      env: { ...process.env, ZBACK_WORKER_NONCE: started }
+    });
+    child.unref();
+  } finally { closeSync(fd); }
+  if (!child?.pid) throw new Error('Unable to start background agent');
+  let connected = false;
+  for (let i = 0; i < 60; i++) {
+    await new Promise(resolve => setTimeout(resolve, 100));
+    const state = readJson(stateFile);
+    if (state?.pid === child.pid && state.started === started && state.status === 'connected' && state.id) {
+      console.log(`Session ID: ${state.id}`);
+      connected = true;
+      break;
+    }
+    if (!alive(child.pid) || (state?.pid === child.pid && state.status === 'stopped')) throw new Error(`Agent exited unexpectedly. Inspect logs with zback --logs`);
   }
-  shutdown();
+  if (!connected) console.log(`Agent started (PID ${child.pid}). Waiting for backend; use zback --status for current state.`);
+  if (!options.background) await follow();
+}
+
+function stop() {
+  const state = activeSession();
+  if (!state) { console.log('Agent is already stopped'); return; }
+  process.kill(state.pid, 'SIGTERM');
+  console.log(`Stop requested for agent PID ${state.pid}`);
+}
+
+function rotate() {
+  if (activeSession()) throw new Error('Stop the agent using zback --stop before rotating its credential');
+  resetKey();
+  console.log('Agent credential rotated. A new session ID will be assigned when it connects.');
+}
+
+export { execute };
+export async function main(args = process.argv.slice(2)) {
+  try {
+    const options = parseArgs(args);
+    if (options.help) return help();
+    if (options.worker) return worker();
+    if (options.action === 'status') return showStatus();
+    if (options.action === 'stop') return stop();
+    if (options.action === 'logs') return recentLog();
+    if (options.action === 'follow') { showStatus(); return follow(); }
+    if (options.action === 'reset-key') return rotate();
+    return await start(options);
+  } catch (error) { console.error(`ZBack error: ${error.message}`); process.exitCode = 1; }
 }
 
-if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main().catch(error => {
-  console.error(error.message); process.exitCode = 1;
-});
+if (process.argv[1] && realpathSync(process.argv[1]) === ENTRY) main();

package/package.json

@@ -1,10 +1,22 @@
 {
   "name": "zback",
-  "version": "1.0.0",
-  "description": "Consent-based remote shell agent via WebSocket and MCP",
+  "version": "1.3.0",
+  "description": "Opt-in remote shell administration with a persistent WebSocket agent, audit logs and a private session credential",
   "type": "module",
-  "bin": { "zback": "./bin/zback.js" },
-  "engines": { "node": ">=22.0.0" },
-  "scripts": { "test": "node --test" },
-  "license": "MIT"
+  "bin": {
+    "zback": "bin/zback.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "contentPolicy": {
+    "class": "dual-use"
+  },
+  "keywords": ["remote-administration", "websocket", "cli", "mcp", "opt-in"],
+  "files": ["bin/", "src/", "README.md", "DISCLOSURE", "LICENSE"],
+  "license": "MIT",
+  "author": "SoyMaycol"
 }

package/src/agent.js

@@ -0,0 +1,143 @@
+import { spawn } from 'node:child_process';
+
+const children = new Set();
+const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
+const log = message => console.log(`[${new Date().toISOString()}] ${message}`);
+
+function killTree(child) {
+  if (!child?.pid) return;
+  try {
+    if (process.platform === 'win32') {
+      const killer = spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+      killer.unref();
+    } else process.kill(-child.pid, 'SIGKILL');
+  } catch { try { child.kill('SIGKILL'); } catch {} }
+}
+
+export function killRunningCommands() { for (const child of children) killTree(child); }
+
+export function execute(command, cwd, timeoutMs, maxOutput) {
+  return new Promise(resolveResult => {
+    let finished = false, timedOut = false, truncated = false;
+    const chunks = { stdout: [], stderr: [] };
+    let collected = 0;
+    let child;
+    try {
+      child = spawn(command, { cwd, shell: true, windowsHide: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
+      children.add(child);
+    } catch (err) { resolveResult({ ok: false, code: null, stdout: '', stderr: String(err.message) }); return; }
+    const add = (kind, chunk) => {
+      const remaining = maxOutput - collected;
+      if (remaining <= 0) { truncated = true; return; }
+      if (chunk.length > remaining) truncated = true;
+      chunks[kind].push(chunk.subarray(0, remaining));
+      collected += Math.min(chunk.length, remaining);
+    };
+    child.stdout.on('data', b => add('stdout', b));
+    child.stderr.on('data', b => add('stderr', b));
+    const timer = setTimeout(() => { timedOut = true; killTree(child); }, timeoutMs);
+    const finish = (code, message = '') => {
+      if (finished) return;
+      finished = true;
+      children.delete(child);
+      clearTimeout(timer);
+      resolveResult({
+        ok: code === 0 && !timedOut,
+        code: Number.isInteger(code) ? code : null,
+        stdout: Buffer.concat(chunks.stdout).toString('utf8'),
+        stderr: Buffer.concat(chunks.stderr).toString('utf8') + message,
+        truncated, timedOut
+      });
+    };
+    child.once('error', error => finish(null, `\n${error.message}`));
+    child.once('close', code => finish(code));
+  });
+}
+
+export async function connectAgent(options, onState, token) {
+  let stopped = false;
+  let retries = 0;
+  let socket;
+  let cancelDelay;
+  let currentState = '';
+  const update = (status, data = {}) => {
+    onState({ status, ...data });
+    if (currentState !== status) { log(`Agent status: ${status}`); currentState = status; }
+  };
+  const shutdown = () => {
+    stopped = true;
+    if (cancelDelay) cancelDelay();
+    try { socket?.close(1000, 'Agent stopped'); } catch {}
+    killRunningCommands();
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+  try {
+    while (!stopped) {
+      try {
+        update(retries ? 'reconnecting' : 'connecting');
+        const current = new WebSocket(options.url);
+        socket = current;
+        await new Promise((resolve, reject) => {
+          const timer = setTimeout(() => { try { current.close(); } catch {} reject(new Error('Connection timed out')); }, 15000);
+          const success = () => { clearTimeout(timer); resolve(); };
+          const failure = () => { clearTimeout(timer); reject(new Error('Could not reach backend')); };
+          current.addEventListener('open', success, { once: true });
+          current.addEventListener('error', failure, { once: true });
+        });
+        if (stopped) break;
+        current.send(JSON.stringify({ type: 'hello', protocolVersion: 2, token }));
+        await new Promise((resolve, reject) => {
+          let welcomed = false;
+          const timer = setTimeout(() => { try { current.close(); } catch {} reject(new Error('Server handshake timed out')); }, 10000);
+          let queue = Promise.resolve();
+          const messageListener = event => {
+            let message;
+            try { message = JSON.parse(event.data); }
+            catch { log('Ignored invalid server message'); return; }
+            if (message.type === 'welcome' && typeof message.id === 'string') {
+              if (welcomed) return;
+              welcomed = true;
+              clearTimeout(timer);
+              retries = 0;
+              update('connected', { id: message.id });
+              log('Connected and ready for authorized requests');
+              return;
+            }
+            if (!welcomed || message.type !== 'command' || typeof message.requestId !== 'string') return;
+            queue = queue.then(async () => {
+              if (stopped || current.readyState !== WebSocket.OPEN) return;
+              const command = message.command;
+              if (typeof command !== 'string' || !command.trim() || command.length > 4096 || command.includes('\0')) return;
+              const timeout = Math.min(options.timeout, Number.isInteger(message.timeoutMs) && message.timeoutMs > 0 ? message.timeoutMs : options.timeout);
+              log(`Running authorized request ${message.requestId}`);
+              const result = await execute(command, options.cwd, timeout, options.maxOutput);
+              log(`Request ${message.requestId}: ${result.timedOut ? 'timed out' : result.ok ? 'completed' : 'failed'}`);
+              if (current.readyState === WebSocket.OPEN && !stopped) current.send(JSON.stringify({ type: 'result', requestId: message.requestId, ...result }));
+            }).catch(error => log(`Request processing error: ${error.message}`));
+          };
+          current.addEventListener('message', messageListener);
+          current.addEventListener('close', event => {
+            clearTimeout(timer);
+            if (!welcomed) reject(new Error(`Backend rejected connection (WebSocket ${event.code}: ${event.reason || 'no reason'})`));
+            else { log(`Connection closed (${event.code}: ${event.reason || 'connection lost'})`); resolve(); }
+          }, { once: true });
+          current.addEventListener('error', () => { if (!welcomed) { clearTimeout(timer); reject(new Error('WebSocket connection failed')); } }, { once: true });
+        });
+      } catch (error) { if (!stopped) log(`Connection error: ${error.message}`); }
+      killRunningCommands();
+      if (stopped || !options.reconnect) break;
+      update('reconnecting', { id: null });
+      const delay = Math.min(30000, 1000 * 2 ** Math.min(retries++, 5));
+      log(`Retrying connection in ${Math.ceil(delay / 1000)}s`);
+      await new Promise(resolve => {
+        const timer = setTimeout(() => { cancelDelay = null; resolve(); }, delay);
+        cancelDelay = () => { clearTimeout(timer); cancelDelay = null; resolve(); };
+      });
+    }
+  } finally {
+    process.removeListener('SIGINT', shutdown);
+    process.removeListener('SIGTERM', shutdown);
+    update('stopped', { id: null });
+  }
+}

package/src/runtime.js

@@ -0,0 +1,62 @@
+import { randomBytes } from 'node:crypto';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const stateDir = process.env.ZBACK_STATE_DIR || join(process.env.XDG_STATE_HOME || (process.platform === 'win32' ? process.env.LOCALAPPDATA || homedir() : join(homedir(), '.local', 'state')), 'zback');
+export const consentFile = join(stateDir, 'consent.json');
+export const stateFile = join(stateDir, 'session.json');
+export const settingsFile = join(stateDir, 'settings.json');
+export const agentKeyFile = join(stateDir, 'agent.key');
+export const logFile = join(stateDir, 'zback.log');
+
+export function initStateDir() { mkdirSync(stateDir, { recursive: true, mode: 0o700 }); }
+export function readJson(file) { try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; } }
+export function saveJson(file, data) {
+  initStateDir();
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+    renameSync(tmp, file);
+  } finally { try { unlinkSync(tmp); } catch {} }
+}
+export function agentKey() {
+  initStateDir();
+  if (!existsSync(agentKeyFile)) {
+    const key = randomBytes(32).toString('base64url');
+    try {
+      const fd = openSync(agentKeyFile, 'wx', 0o600);
+      try { writeFileSync(fd, key + '\n'); } finally { closeSync(fd); }
+    } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  }
+  const key = readFileSync(agentKeyFile, 'utf8').trim();
+  if (!/^[A-Za-z0-9_-]{43}$/.test(key)) throw new Error('Invalid agent credential file; run zback --reset-key while stopped');
+  return key;
+}
+export function resetKey() {
+  try { unlinkSync(agentKeyFile); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  return agentKey();
+}
+export function hasConsent() { return readJson(consentFile)?.approved === true; }
+export function alive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    if (process.platform === 'linux') {
+      try {
+        if (readFileSync(`/proc/${pid}/stat`, 'utf8').split(') ')[1]?.[0] === 'Z') return false;
+        const cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8');
+        if (!cmd.includes('--worker') || !cmd.includes('zback.js')) return false;
+      } catch {}
+    }
+    return true;
+  } catch (e) { return e.code === 'EPERM'; }
+}
+export function activeSession() {
+  const data = readJson(stateFile);
+  return data && data.status !== 'stopped' && alive(data.pid) ? data : null;
+}
+export function sameSession(pid, started) {
+  const data = readJson(stateFile);
+  return data?.pid === pid && data?.started === started;
+}

package/test/client.test.js

@@ -1,28 +0,0 @@
-import assert from 'node:assert/strict';
-import { test } from 'node:test';
-import { parseArgs, execute } from '../bin/zback.js';
-
-test('default secure endpoint', () => {
-  const args = parseArgs([]);
-  assert.equal(args.url, 'wss://zb.soymaycol.icu/ws');
-  assert.equal(args.reconnect, true);
-});
-
-test('unsafe remote ws URL blocked', () => {
-  assert.throws(() => parseArgs(['--url', 'ws://example.com/ws']), /wss/);
-  assert.equal(parseArgs(['--url', 'ws://127.0.0.1:8787/ws']).timeout, 30000);
-  assert.throws(() => parseArgs(['--timeout', '0']), /timeout/);
-});
-
-test('subprocess respects success and returned output', async () => {
-  const res = await execute('node -p "3*7"', process.cwd(), 5000, 1024);
-  assert.equal(res.ok, true);
-  assert.equal(res.stdout.trim(), '21');
-});
-
-test('subprocess output limit is enforced', async () => {
-  const res = await execute('node -e "process.stdout.write(\'a\'.repeat(2500))"', process.cwd(), 5000, 1024);
-  assert.equal(res.ok, true);
-  assert.equal(res.stdout.length, 1024);
-  assert.equal(res.truncated, true);
-});