zback 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZBack contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# zback (CLI global)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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**.
+
+## Instalar
+
+```bash
+npm install -g .
+zback --help
+zback
+```
+
+Extrae este ZIP antes de ejecutar `npm install -g .` dentro de su directorio.
+
+Opciones:
+
+```bash
+zback --url wss://zb.soymaycol.icu/ws
+zback --cwd /ruta/a/proyecto --timeout 15000 --max-output 32768
+zback --no-reconnect
+```
+
+Para pruebas locales: `zback --url ws://127.0.0.1:8787/ws`.
+
+- 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.
+
+**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.

package/bin/zback.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { existsSync, realpathSync, statSync } 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';
+
+const DEFAULT_URL = 'wss://zb.soymaycol.icu/ws';
+
+function help() {
+  console.log(`ZBack 1.0.0 - WebSocket agent (Node.js >=22)
+
+Uso: zback [opciones]
+
+  --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
+
+Se solicita permiso al inicio y cada vez que un comando remoto llega.
+No hay API keys ni ejecución sin confirmación.`);
+}
+
+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']);
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    if (flag === '--help' || flag === '-h') return { help: true };
+    if (flag === '--no-reconnect') { options.reconnect = false; continue; }
+    if (!set.has(flag) || i + 1 >= args.length) throw new Error(`Argumento desconocido o incompleto: ${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');
+  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;
+}
+
+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;
+      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 });
+    };
+    child.once('error', error => finish(null, `\n${error.message}`));
+    child.once('close', code => finish(code));
+  });
+}
+
+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;
+  }
+  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);
+  }
+  shutdown();
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main().catch(error => {
+  console.error(error.message); process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "zback",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Consent-based remote shell agent via WebSocket and MCP",
+  "type": "module",
+  "bin": { "zback": "./bin/zback.js" },
+  "engines": { "node": ">=22.0.0" },
+  "scripts": { "test": "node --test" },
+  "license": "MIT"
+}

package/test/client.test.js

@@ -0,0 +1,28 @@
+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);
+});