zback 1.1.1 → 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,40 +1,69 @@
 # ZBack CLI
 
-Global command for Node.js 22+. No npm dependencies, login, API key, or password.
+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.
 
-## 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.0
 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 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
+
+| 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 |
+
+`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.
 
-```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`. 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.
 
-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.0';
 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 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
+
+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 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 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('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('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('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;
@@ -60,38 +85,81 @@ 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;
+    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 });
-  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 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 (!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) {
+    console.log(existing.id ? `Session ID: ${existing.id}` : `ZBack is ${existing.status} (PID ${existing.pid}).`);
+    if (!options.background) await follow();
     return;
   }
-  if (!(await confirmOnce())) { console.log('Permission declined.'); return; }
+  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)}`;
@@ -103,37 +171,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) {
+      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`);
   }
-  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; use zback --status for current state.`);
+  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 +207,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.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"
@@ -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,103 @@ 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 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);
-  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');
+        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(); };
       });
-      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: null });
   }
-  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 (!cmd.includes('--worker') || !cmd.includes('zback.js')) 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);
-});