zback 0.0.0-stage → 1.1.1

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,40 @@
-# Temporary Holding Version
+# ZBack CLI
 
-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.
+Global command for Node.js 22+. No npm dependencies, login, API key, or password.
+
+## Install
+
+```bash
+npm install -g .
+zback
+```
+
+The first time, ZBack asks exactly once for permission to access **your own shell**. Answer `y` to run it as a detached background process. When connected, it prints:
+
+```
+Okay, here's your session ID "..."
+```
+
+Closing the terminal does not normally stop the agent. Later calls to `zback` show its current session ID without requesting permission again. To view the connection state or terminate the worker:
+
+```bash
+zback --status
+zback --stop
+```
+
+Advanced options at first launch (or after stopping it):
+
+```bash
+zback --url wss://zb.soymaycol.icu/ws --cwd /path/to/project
+zback --timeout 120000 --max-output 131072
+```
+
+Local development: `zback --url ws://127.0.0.1:8787/ws`.
+
+The agent automatically reconnects, potentially receiving a **new session ID**; check `zback --status` if the previous ID stops working. There are no per-command approvals after initial permission. The session ID grants anyone who possesses it remote shell access for the lifetime of that session; **keep it private**. TLS (`wss://`) is required remotely.
+
+Status, consent, and log files are stored in the OS user state directory (`~/.local/state/zback` on most Linux systems or `%LOCALAPPDATA%/zback` on Windows). They are local and not published by the backend. Optionally set `ZBACK_STATE_DIR` to change this location.
+
+Closing a terminal normally leaves the detached worker running. Force-stopping an Android app, battery restrictions, shutdown or network loss may still terminate or interrupt it; this CLI does not auto-start itself on device boot.
+
+Test with `npm test`.

package/bin/zback.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { openSync } 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 { existsSync, statSync } from 'node:fs';
+import { connectAgent, execute } from '../src/agent.js';
+import { activeSession, alive, consentFile, hasConsent, initStateDir, logFile, readJson, sameSession, saveJson, settingsFile, stateFile } from '../src/runtime.js';
+
+const ENTRY = fileURLToPath(import.meta.url);
+const DEFAULT_URL = 'wss://zb.soymaycol.icu/ws';
+
+function help() {
+  console.log(`ZBack 1.1.0\n\nUsage: zback [options]\n\n  --url <wss://.../ws>   WebSocket endpoint (default: ${DEFAULT_URL})\n  --cwd <directory>     Directory for shell commands\n  --timeout <ms>        Command timeout (1000-300000)\n  --max-output <bytes>  Maximum command output (1024-262144)\n  --no-reconnect        Disable automatic reconnection\n  --status              Show background agent status and session ID\n  --stop                Stop background agent\n  --help                Display help\n\nThe first launch asks for shell access permission only once.\nThe agent runs in the background until stopped.`);
+}
+
+export function parseArgs(args) {
+  const options = { url: DEFAULT_URL, cwd: process.cwd(), timeout: 30000, maxOutput: 65536, reconnect: true };
+  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 (flag === '--status' || flag === '--stop') {
+      if (action !== 'start') throw new Error('Specify one action');
+      action = flag.slice(2);
+      continue;
+    }
+    if (flag === '--no-reconnect') { options.reconnect = false; continue; }
+    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 (action !== 'start') return { action };
+  if (!Number.isSafeInteger(options.timeout) || options.timeout < 1000 || options.timeout > 300000) throw new Error('--timeout must be between 1000 and 300000 ms');
+  if (!Number.isSafeInteger(options.maxOutput) || options.maxOutput < 1024 || options.maxOutput > 262144) throw new Error('--max-output must be between 1024 and 262144 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('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 a WebSocket URL ending in /ws');
+  return { ...options, action };
+}
+
+async function confirmOnce() {
+  if (hasConsent()) return true;
+  if (!stdin.isTTY || !stdout.isTTY) throw new Error('An interactive terminal is required for initial permission.');
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await rl.question('This module accesses your shell. Do you allow it to use your shell? Permission will not be requested again. [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('Permission has not been granted. 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('Not a valid ZBack background worker');
+  const mark = data => {
+    const current = readJson(stateFile);
+    if (current && current.status !== 'stopped' && current.pid !== process.pid && alive(current.pid)) return;
+    saveJson(stateFile, { pid: process.pid, started, updated: new Date().toISOString(), ...data });
+  };
+  mark({ status: 'connecting', id: null });
+  const hardStop = () => {
+    if (sameSession(process.pid, started)) mark({ status: 'stopped', id: null });
+    setTimeout(() => process.exit(0), 150).unref();
+  };
+  process.once('SIGTERM', hardStop);
+  process.once('SIGINT', hardStop);
+  try { await connectAgent(settings, mark); }
+  finally {
+    if (sameSession(process.pid, started)) mark({ status: 'stopped', id: null });
+  }
+}
+
+async function start(options) {
+  const running = activeSession();
+  if (running) {
+    console.log(running.id ? `Okay, here's your session ID "${running.id}"` : `ZBack is ${running.status}.`);
+    console.log('Use zback --status to inspect the agent or zback --stop to stop it.');
+    return;
+  }
+  if (!(await confirmOnce())) { console.log('Permission declined.'); return; }
+  initStateDir();
+  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 {
+    const { closeSync } = await import('node:fs');
+    closeSync(fd);
+  }
+  if (!child?.pid) throw new Error('Could not launch background process');
+  for (let i = 0; i < 80; i++) {
+    await new Promise(r => setTimeout(r, 100));
+    const state = readJson(stateFile);
+    if (state?.pid === child.pid && state.started === started && state.id && state.status === 'connected') {
+      console.log(`Okay, here's your session ID "${state.id}"`);
+      return;
+    }
+    if (!alive(child.pid) || (state?.pid === child.pid && state.status === 'stopped')) {
+      throw new Error(`Background process exited. See ${logFile}`);
+    }
+  }
+  console.log(`Background agent started (PID ${child.pid}); waiting for the server.`);
+  console.log('Use zback --status to see the session ID once connected.');
+}
+
+function status() {
+  const state = activeSession();
+  if (!state) return console.log('ZBack is stopped.');
+  console.log(`Status: ${state.status}\nPID: ${state.pid}${state.id ? `\nSession ID: ${state.id}` : ''}`);
+}
+
+function stop() {
+  const state = activeSession();
+  if (!state) return console.log('ZBack is not running.');
+  process.kill(state.pid, 'SIGTERM');
+  console.log('ZBack stop requested.');
+}
+
+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 status();
+    if (options.action === 'stop') return stop();
+    return await start(options);
+  } catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 1; }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === ENTRY) main();

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "zback",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.1",
+  "description": "Background WebSocket shell agent with one-time local consent",
+  "type": "module",
+  "bin": {
+    "zback": "bin/zback.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "license": "MIT"
+}

package/src/agent.js

@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process';
+
+const children = new Set();
+const wait = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+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;
+      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; 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) {
+  let stopped = false, retries = 0, socket;
+  const shutdown = () => { stopped = true; try { socket?.close(); } catch {} killRunningCommands(); };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+  while (!stopped) {
+    try {
+      socket = new WebSocket(options.url);
+      await new Promise((resolve, reject) => {
+        socket.addEventListener('open', resolve, { once: true });
+        socket.addEventListener('error', () => reject(new Error('Connection failed')), { once: true });
+      });
+      if (stopped) break;
+      retries = 0;
+      onState({ status: 'connected', id: null });
+      let queue = Promise.resolve();
+      socket.addEventListener('message', event => {
+        let message;
+        try { message = JSON.parse(event.data); } catch { return; }
+        if (message.type === 'welcome' && typeof message.id === 'string') {
+          onState({ status: 'connected', id: message.id });
+          console.log(`[zback] Connected; session ${message.id}`);
+        }
+        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;
+            const timeout = Math.min(options.timeout, Number.isInteger(message.timeoutMs) && message.timeoutMs > 0 ? message.timeoutMs : options.timeout);
+            console.log(`[zback] Executing request ${message.requestId}`);
+            const result = await execute(command, options.cwd, timeout, options.maxOutput);
+            if (socket.readyState === WebSocket.OPEN && !stopped) socket.send(JSON.stringify({ type: 'result', requestId: message.requestId, ...result }));
+          }).catch(error => console.error(`[zback] Request failed: ${error.message}`));
+        }
+      });
+      await new Promise(resolve => socket.addEventListener('close', resolve, { once: true }));
+    } catch (error) { if (!stopped) console.error(`[zback] ${error.message}`); }
+    if (stopped || !options.reconnect) break;
+    onState({ status: 'reconnecting', id: null });
+    await wait(Math.min(30000, 1000 * 2 ** Math.min(retries++, 5)));
+  }
+  onState({ status: 'stopped', id: null });
+}

package/src/runtime.js

@@ -0,0 +1,39 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, 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 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}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+}
+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; } 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;
+}
+export function hasState() { return existsSync(stateFile); }

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);
+});