zback 1.3.0 → 1.3.1

package/DISCLOSURE

@@ -2,7 +2,7 @@ ZBack is an opt-in remote shell administration tool for devices owned or explici
 
 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`.
+- 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.

package/README.md

@@ -1,13 +1,13 @@
 # ZBack CLI
 
-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.
+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.
 
 > **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.
 
 ## Install and start
 
 ```sh
-npm install -g zback@1.2.0
+npm install -g zback@1.2.1
 zback
 ```
 
@@ -25,21 +25,21 @@ For development only:
 zback --url ws://127.0.0.1:8787/ws
 ```
 
-The client and backend must both be **version 1.2.0** because the connection handshake changed. The backend must be deployed before a remote client can connect.
+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` | Start if needed and attach the terminal to a live event display |
-| `zback --background` | Start the agent without keeping a live terminal display |
+| `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` | Attach to live events from the existing background agent |
+| `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` 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.
+`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.
 
 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.
 
@@ -56,7 +56,7 @@ Files are under `~/.local/state/zback` on Linux/Termux and `%LOCALAPPDATA%/zback
 
 ## MCP
 
-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.
+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.
 
 ## Security disclosure and review
 

package/bin/zback.js

@@ -9,15 +9,15 @@ import { connectAgent, execute } from '../src/agent.js';
 import { activeSession, agentKey, consentFile, hasConsent, initStateDir, logFile, readJson, resetKey, sameSession, saveJson, settingsFile, stateFile, alive } from '../src/runtime.js';
 
 const ENTRY = fileURLToPath(import.meta.url);
-const VERSION = '1.2.0';
+const VERSION = '1.2.1';
 const DEFAULT_URL = 'wss://zb.soymaycol.icu/ws';
 
 function help() {
   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                     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
@@ -34,8 +34,8 @@ Options:
 
 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.`);
+Ctrl+C stops a foreground agent. Background mode must be requested explicitly.
+Use --stop to disconnect a background agent.`);
 }
 
 export function parseArgs(args) {
@@ -73,11 +73,11 @@ export function parseArgs(args) {
 async function confirmOnce() {
   if (hasConsent()) return true;
   if (!stdin.isTTY || !stdout.isTTY) throw new Error('First-run shell authorization requires an interactive terminal');
-  console.log('ZBack permits remote shell commands through a private session credential.');
-  console.log('These commands run as your current user. Do not share your session ID.');
+  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('Authorize remote shell administration on this device? [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;
@@ -94,17 +94,32 @@ async function worker() {
   const mark = data => {
     const previous = readJson(stateFile);
     if (previous && previous.status !== 'stopped' && previous.pid !== process.pid && alive(previous.pid)) return;
-    saveJson(stateFile, { pid: process.pid, started, updated: new Date().toISOString(), ...data });
+    saveJson(stateFile, { pid: process.pid, started, version: VERSION, updated: new Date().toISOString(), ...data });
   };
   mark({ status: 'connecting', id: null });
   try { await connectAgent(settings, mark, key); }
   finally { if (sameSession(process.pid, started)) mark({ status: 'stopped', id: null }); }
 }
 
+function 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}${state.id ? `\nSession ID: ${state.id}` : ''}\nUpdated: ${state.updated || 'unknown'}`);
+  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;
 }
 
@@ -122,8 +137,7 @@ function recentLog() {
 
 async function follow() {
   if (!stdin.isTTY || !stdout.isTTY) return;
-  console.log('Live agent events. Ctrl+C detaches; the agent stays active.');
-  recentLog();
+  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 = () => {
@@ -153,14 +167,43 @@ async function follow() {
 async function start(options) {
   const existing = activeSession();
   if (existing) {
-    console.log(existing.id ? `Session ID: ${existing.id}` : `ZBack is ${existing.status} (PID ${existing.pid}).`);
+    if (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('Authorization declined'); return; }
   initStateDir();
-  agentKey();
+  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;
@@ -178,13 +221,13 @@ async function start(options) {
     await new Promise(resolve => setTimeout(resolve, 100));
     const state = readJson(stateFile);
     if (state?.pid === child.pid && state.started === started && state.status === 'connected' && state.id) {
-      console.log(`Session ID: ${state.id}`);
+      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`);
   }
-  if (!connected) console.log(`Agent started (PID ${child.pid}). Waiting for backend; use zback --status for current state.`);
+  if (!connected) console.log(`Agent started (PID ${child.pid}). Waiting for backend; run zback --status to inspect.`);
   if (!options.background) await follow();
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zback",
-  "version": "1.3.0",
-  "description": "Opt-in remote shell administration with a persistent WebSocket agent, audit logs and a private session credential",
+  "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"

package/src/agent.js

@@ -59,11 +59,9 @@ export async function connectAgent(options, onState, token) {
   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; }
-  };
+  let lastId = null;
+  let lastError = null;
+  const update = (status, data = {}) => onState({ status, ...data });
   const shutdown = () => {
     stopped = true;
     if (cancelDelay) cancelDelay();
@@ -75,7 +73,7 @@ export async function connectAgent(options, onState, token) {
   try {
     while (!stopped) {
       try {
-        update(retries ? 'reconnecting' : 'connecting');
+        update(retries ? 'reconnecting' : 'connecting', { id: lastId });
         const current = new WebSocket(options.url);
         socket = current;
         await new Promise((resolve, reject) => {
@@ -95,13 +93,22 @@ export async function connectAgent(options, onState, token) {
             let message;
             try { message = JSON.parse(event.data); }
             catch { log('Ignored invalid server message'); return; }
-            if (message.type === 'welcome' && typeof message.id === 'string') {
+            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 });
-              log('Connected and ready for authorized requests');
               return;
             }
             if (!welcomed || message.type !== 'command' || typeof message.requestId !== 'string') return;
@@ -120,16 +127,18 @@ export async function connectAgent(options, onState, token) {
           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(); }
+            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) log(`Connection error: ${error.message}`); }
+      } 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: null });
+      update('reconnecting', { id: lastId });
       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(); };
@@ -138,6 +147,6 @@ export async function connectAgent(options, onState, token) {
   } finally {
     process.removeListener('SIGINT', shutdown);
     process.removeListener('SIGTERM', shutdown);
-    update('stopped', { id: null });
+    update('stopped', { id: lastId });
   }
 }

package/src/runtime.js

@@ -46,7 +46,7 @@ export function alive(pid) {
       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;
+        if (!/(?:^|[\x00/\\])zback(?:\.js)?(?:\x00|$)/.test(cmd)) return false;
       } catch {}
     }
     return true;