zback 1.1.1 → 1.3.1

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.
+- The agent runs in the foreground by default and stops on Ctrl+C. An explicitly requested background worker may persist after the terminal detaches and 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,40 +1,69 @@
 # ZBack CLI
 
-Global command for Node.js 22+. No npm dependencies, login, API key, or password.
+ZBack is an 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.
 
-## Install
+> **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 .
+## Install and start
+
+```sh
+npm install -g zback@1.2.1
 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:
+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.
 
-```
-Okay, here's your session ID "..."
+The default server is `wss://zb.soymaycol.icu/ws`. To use your own backend:
+
+```sh
+zback --url wss://your-domain.example/ws
 ```
 
-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:
+For development only:
 
-```bash
-zback --status
-zback --stop
+```sh
+zback --url ws://127.0.0.1:8787/ws
 ```
 
-Advanced options at first launch (or after stopping it):
+The client requires **backend 1.2.0 or later**. The client rejects older servers rather than accepting unstable legacy session IDs. Deploy the updated backend before connecting a remote client.
+
+## Terminal and process lifecycle
+
+| Command | Behavior |
+| --- | --- |
+| `zback` | Keep the agent in the foreground; display the session ID, MCP endpoint and live activity |
+| `zback --background` | Explicitly start a detached agent |
+| `zback --status` | Show connection status, process ID and private session ID |
+| `zback --logs` | Display recent connection and command activity |
+| `zback --follow` | Watch new events from an existing background agent without replaying old logs |
+| `zback --stop` | Stop the background agent |
+| `zback --reset-key` | Change the device identity after the agent is stopped |
+
+`Ctrl+C` in the default foreground mode **stops the agent**. In background mode, `Ctrl+C` detaches the log display only. Use `zback --stop` to disconnect a background agent. Before upgrading from version 1.1.x or an earlier running version, stop its existing background worker with `zback --stop`. The server session ID stays the same over ordinary network reconnections and backend restarts, as long as the private local agent credential remains unchanged.
 
-```bash
-zback --url wss://zb.soymaycol.icu/ws --cwd /path/to/project
-zback --timeout 120000 --max-output 131072
+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
 ```
 
-Local development: `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.
 
-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.
+## MCP
 
-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.
+The companion backend serves `POST /mcp` with `zback_status` and `zback_execute`. On connection, the client displays the MCP endpoint and a **private** session ID, which is supplied as the `id` argument to either tool. 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.
 
-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.
+## Security disclosure and review
 
-Test with `npm test`.
+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,34 +1,57 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { openSync } 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 { 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';
+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.1';
 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.`);
+  console.log(`ZBack ${VERSION} | Authorized remote shell administration
+
+Usage:
+  zback                     Start in the foreground and display live events
+  zback --background        Run as a background agent
+  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
+
+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
+
+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 stops a foreground agent. Background mode must be requested explicitly.
+Use --stop to disconnect a background agent.`);
 }
 
 export function parseArgs(args) {
-  const options = { url: DEFAULT_URL, cwd: process.cwd(), timeout: 30000, maxOutput: 65536, reconnect: true };
+  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 (flag === '--status' || flag === '--stop') {
-      if (action !== 'start') throw new Error('Specify one action');
+    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 (!values.has(flag) || i + 1 >= args.length) throw new Error(`Unknown or incomplete argument: ${flag}`);
     const value = args[++i];
@@ -38,21 +61,23 @@ export function parseArgs(args) {
     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 (!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('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');
+  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 };
 }
 
 async function confirmOnce() {
   if (hasConsent()) return true;
-  if (!stdin.isTTY || !stdout.isTTY) throw new Error('An interactive terminal is required for initial permission.');
+  if (!stdin.isTTY || !stdout.isTTY) throw new Error('First-run shell authorization requires an interactive terminal');
+  console.log('This module grants remote shell access to anyone holding your private session ID.');
+  console.log('Commands run with your user permissions. Keep the session ID private.');
   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] ');
+    const answer = await rl.question('Do you allow remote access to your shell? This is asked only once. [y/N] ');
     if (!['y', 'yes'].includes(answer.trim().toLowerCase())) return false;
     saveJson(consentFile, { approved: true, at: new Date().toISOString() });
     return true;
@@ -60,39 +85,125 @@ async function confirmOnce() {
 }
 
 async function worker() {
-  if (!hasConsent()) throw new Error('Permission has not been granted. Run zback interactively first.');
+  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('Not a valid ZBack background worker');
+  if (!started) throw new Error('Worker must be launched through zback');
+  const key = agentKey();
   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 });
+    const previous = readJson(stateFile);
+    if (previous && previous.status !== 'stopped' && previous.pid !== process.pid && alive(previous.pid)) return;
+    saveJson(stateFile, { pid: process.pid, started, version: VERSION, 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 });
-  }
+  try { await connectAgent(settings, mark, key); }
+  finally { if (sameSession(process.pid, started)) mark({ status: 'stopped', id: null }); }
+}
+
+function mcpEndpoint(url) {
+  const endpoint = new URL(url);
+  endpoint.protocol = endpoint.protocol === 'wss:' ? 'https:' : 'http:';
+  endpoint.pathname = '/mcp';
+  return endpoint.toString();
+}
+
+function showConnection(id, url) {
+  console.log(`Session ID: ${id}`);
+  console.log(`MCP endpoint: ${mcpEndpoint(url)}`);
+  console.log('MCP tools: zback_status, zback_execute (provide the ID as the id argument)');
+  console.log('Keep the session ID private; it grants remote shell access.');
+}
+
+function showStatus() {
+  const state = activeSession();
+  if (!state) { console.log('Status: stopped'); return false; }
+  console.log(`Status: ${state.status}\nPID: ${state.pid}\nUpdated: ${state.updated || 'unknown'}`);
+  if (state.id) showConnection(state.id, readJson(settingsFile)?.url || DEFAULT_URL);
+  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('Monitoring background agent. Ctrl+C closes this view; the agent stays active.');
+  let position = existsSync(logFile) ? statSync(logFile).size : 0;
+  await new Promise(resolve => {
+    const readNew = () => {
+      try {
+        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}`); }
+    };
+    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();
+  });
 }
 
 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.');
+  const existing = activeSession();
+  if (existing) {
+    if (existing.version !== VERSION) {
+      console.error('An older ZBack agent is still running. Run zback --stop, then zback to start this version.');
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`Agent already running (${existing.status}, PID ${existing.pid}).`);
+    if (existing.id) showConnection(existing.id, readJson(settingsFile)?.url || DEFAULT_URL);
+    if (!options.background) await follow();
     return;
   }
-  if (!(await confirmOnce())) { console.log('Permission declined.'); return; }
+  if (!(await confirmOnce())) { console.log('Authorization declined'); return; }
   initStateDir();
+  const key = agentKey();
   saveJson(settingsFile, { url: options.url, cwd: options.cwd, timeout: options.timeout, maxOutput: options.maxOutput, reconnect: options.reconnect });
+  if (!options.background) {
+    const started = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    let lastId = null;
+    let previousStatus = null;
+    const mark = data => {
+      saveJson(stateFile, { pid: process.pid, started, version: VERSION, updated: new Date().toISOString(), ...data });
+      if (data.status === 'connected') {
+        if (data.id !== lastId) {
+          console.log('Connected.');
+          showConnection(data.id, options.url);
+          console.log('Monitoring requests and connection errors. Press Ctrl+C to disconnect.');
+          lastId = data.id;
+        } else if (previousStatus !== 'connected') console.log('Connection restored.');
+      } else if (data.status === 'reconnecting' && previousStatus !== 'reconnecting') console.error('Connection lost. Attempting to reconnect...');
+      else if (data.status === 'stopped' && previousStatus !== 'stopped' && lastId) console.log('Disconnected.');
+      previousStatus = data.status;
+    };
+    console.log(`Connecting to ${options.url}...`);
+    mark({ status: 'connecting', id: null });
+    try { await connectAgent(options, mark, key); }
+    finally { if (sameSession(process.pid, started)) saveJson(stateFile, { pid: process.pid, started, version: VERSION, status: 'stopped', id: lastId, updated: new Date().toISOString() }); }
+    return;
+  }
   const fd = openSync(logFile, 'a', 0o600);
   const started = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
   let child;
@@ -103,37 +214,34 @@ async function start(options) {
       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));
+  } 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.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}`);
+    if (state?.pid === child.pid && state.started === started && state.status === 'connected' && state.id) {
+      showConnection(state.id, options.url);
+      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`);
   }
-  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}` : ''}`);
+  if (!connected) console.log(`Agent started (PID ${child.pid}). Waiting for backend; run zback --status to inspect.`);
+  if (!options.background) await follow();
 }
 
 function stop() {
   const state = activeSession();
-  if (!state) return console.log('ZBack is not running.');
+  if (!state) { console.log('Agent is already stopped'); return; }
   process.kill(state.pid, 'SIGTERM');
-  console.log('ZBack stop requested.');
+  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 };
@@ -142,10 +250,13 @@ export async function main(args = process.argv.slice(2)) {
     const options = parseArgs(args);
     if (options.help) return help();
     if (options.worker) return worker();
-    if (options.action === 'status') return status();
+    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(`Error: ${error.message}`); process.exitCode = 1; }
+  } catch (error) { console.error(`ZBack error: ${error.message}`); process.exitCode = 1; }
 }
 
-if (process.argv[1] && resolve(process.argv[1]) === ENTRY) main();
+if (process.argv[1] && realpathSync(process.argv[1]) === ENTRY) main();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zback",
-  "version": "1.1.1",
-  "description": "Background WebSocket shell agent with one-time local consent",
+  "version": "1.3.1",
+  "description": "Opt-in foreground remote shell administration with a persistent WebSocket agent and private session credential",
   "type": "module",
   "bin": {
     "zback": "bin/zback.js"
@@ -12,5 +12,11 @@
   "scripts": {
     "test": "node --test"
   },
-  "license": "MIT"
+  "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

@@ -2,6 +2,7 @@ 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;
@@ -24,17 +25,13 @@ export function execute(command, cwd, timeoutMs, maxOutput) {
     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;
-    }
+    } 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);
+      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));
@@ -44,55 +41,112 @@ export function execute(command, cwd, timeoutMs, maxOutput) {
       finished = true;
       children.delete(child);
       clearTimeout(timer);
-      resolveResult({ ok: code === 0 && !timedOut, code: Number.isInteger(code) ? code : null,
+      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 });
+        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(); };
+export async function connectAgent(options, onState, token) {
+  let stopped = false;
+  let retries = 0;
+  let socket;
+  let cancelDelay;
+  let lastId = null;
+  let lastError = null;
+  const update = (status, data = {}) => onState({ status, ...data });
+  const shutdown = () => {
+    stopped = true;
+    if (cancelDelay) cancelDelay();
+    try { socket?.close(1000, 'Agent stopped'); } 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}`));
-        }
+  try {
+    while (!stopped) {
+      try {
+        update(retries ? 'reconnecting' : 'connecting', { id: lastId });
+        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') {
+              if (welcomed) return;
+              if (message.protocolVersion !== 2 || typeof message.id !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(message.id)) {
+                clearTimeout(timer);
+                current.close(1000, 'Incompatible protocol');
+                const mismatch = new Error('Incompatible backend. Deploy ZBack backend 1.2.0 or later; this server issues legacy session IDs.');
+                mismatch.code = 'INCOMPATIBLE_BACKEND';
+                reject(mismatch);
+                return;
+              }
+              welcomed = true;
+              clearTimeout(timer);
+              retries = 0;
+              lastId = message.id;
+              lastError = null;
+              update('connected', { id: message.id });
+              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 { if (!stopped) 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 && error.code === 'INCOMPATIBLE_BACKEND') throw error;
+        if (!stopped && error.message !== lastError) { log(`Connection error: ${error.message}`); lastError = error.message; }
+      }
+      killRunningCommands();
+      if (stopped || !options.reconnect) break;
+      update('reconnecting', { id: lastId });
+      const delay = Math.min(30000, 1000 * 2 ** Math.min(retries++, 5));
+      await new Promise(resolve => {
+        const timer = setTimeout(() => { cancelDelay = null; resolve(); }, delay);
+        cancelDelay = () => { clearTimeout(timer); cancelDelay = null; resolve(); };
       });
-      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)));
+    }
+  } finally {
+    process.removeListener('SIGINT', shutdown);
+    process.removeListener('SIGTERM', shutdown);
+    update('stopped', { id: lastId });
   }
-  onState({ status: 'stopped', id: null });
 }

package/src/runtime.js

@@ -1,4 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+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';
 
@@ -6,15 +7,35 @@ export const stateDir = process.env.ZBACK_STATE_DIR || join(process.env.XDG_STAT
 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}.tmp`;
-  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
-  renameSync(tmp, file);
+  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) {
@@ -22,11 +43,14 @@ export function alive(pid) {
   try {
     process.kill(pid, 0);
     if (process.platform === 'linux') {
-      try { if (readFileSync(`/proc/${pid}/stat`, 'utf8').split(') ')[1]?.[0] === 'Z') return false; } catch {}
+      try {
+        if (readFileSync(`/proc/${pid}/stat`, 'utf8').split(') ')[1]?.[0] === 'Z') return false;
+        const cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8');
+        if (!/(?:^|[\x00/\\])zback(?:\.js)?(?:\x00|$)/.test(cmd)) return false;
+      } catch {}
     }
     return true;
-  }
-  catch (e) { return e.code === 'EPERM'; }
+  } catch (e) { return e.code === 'EPERM'; }
 }
 export function activeSession() {
   const data = readJson(stateFile);
@@ -36,4 +60,3 @@ 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

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