@brrew/projectbridge 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# ProjectBridge Remote CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ProjectBridge is proprietary software. All rights are reserved; npm publication makes the package installable but does not grant permission to copy, modify, redistribute, or create derivative works except where separately authorized by the copyright holder.
+
+## Install and run
+
+```sh
+npx --yes @brrew/projectbridge@latest remote
+```
+
+To keep the host online after the terminal closes and start it automatically in future user sessions, run:
+
+```sh
+npx --yes @brrew/projectbridge@latest install-service
+```
+
+Remove only the persistent startup entry (the enrollment credential is retained):
+
+```sh
+npx --yes @brrew/projectbridge@latest uninstall-service
+```
+
+Check for and install the latest npm release into the managed runtime:
+
+```sh
+npx --yes @brrew/projectbridge@latest update
+```
+
+The CLI requests a short-lived pairing, waits for you to confirm the matching hostname and one-time code in the ProjectBridge dashboard. A separate browser confirmation is no longer required. After approval, it stores a device credential in a user-private configuration directory, sends authenticated heartbeats, polls for host tasks, and returns bounded task results. The agent checks for a newer npm release on startup and every six hours while running. The optional persistent install uses the native per-user startup manager: systemd user service on Linux, LaunchAgent on macOS, or a logon scheduled task on Windows. When online, it checks npm for newer releases every six hours and restarts onto an update automatically. Updates are fetched through npm's registry TLS and package integrity verification.
+
+## Requirements
+
+- Node.js 20+
+- HTTPS access to the ProjectBridge server
+- The user must be signed in to the ProjectBridge dashboard to confirm the browser pairing and approve the host
+
+Set `PROJECTBRIDGE_SERVER` to use a different server. Set `PROJECTBRIDGE_CONFIG` to override the local config path.
+
+## Current limitations
+
+This is an early remote host-management release. It supports authenticated host inspection, validated service control, process termination with explicit dashboard confirmation, and read-only artifact verification (SHA-256, ZIP/TAR/GZIP integrity, and macOS DMG checks). Arbitrary shell execution and remote filesystem modification remain disabled. Linux persistence depends on the user systemd bus being available; whether the agent runs while logged out depends on the host's user-service/linger configuration.

package/bin/projectbridge.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { setTimeout: sleep } = require('node:timers/promises');
+const lifecycle = require('../lib/lifecycle');
+
+const VERSION = '0.3.0';
+const DEFAULT_SERVER = (process.env.PROJECTBRIDGE_SERVER || 'https://projectbridge.brrew.us').replace(/\/$/, '');
+const UA = 'ProjectBridge-Remote/' + VERSION + ' (+https://projectbridge.brrew.us)';
+const READ_ONLY_TOOLS = new Set(['system.info', 'memory.info', 'process.list', 'disk.list', 'network.interfaces', 'network.connections', 'service.list', 'artifact.verify']);
+const CONTROLLED_TOOLS = new Set(['service.control', 'process.terminate']);
+
+function configPath() {
+  if (process.env.PROJECTBRIDGE_CONFIG) return path.resolve(process.env.PROJECTBRIDGE_CONFIG);
+  if (process.platform === 'win32') return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'ProjectBridge', 'remote.json');
+  return path.join(os.homedir(), '.config', 'projectbridge', 'remote.json');
+}
+function hostInfo() {
+  return { hostname: os.hostname().slice(0,160), platform: process.platform === 'darwin' ? 'macOS' : process.platform === 'win32' ? 'Windows' : 'Linux',
+    os_version: os.version().slice(0,160), architecture: os.arch().slice(0,80), agent_version: VERSION };
+}
+async function request(base, route, body, credential) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 12000);
+  try {
+    const headers = { 'User-Agent': UA, 'Accept': 'application/json' };
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    if (credential) headers.Authorization = 'Bearer ' + credential;
+    const response = await fetch(new URL(route, base), { method: body === undefined ? 'GET' : 'POST', headers,
+      body: body === undefined ? undefined : JSON.stringify(body), signal: controller.signal, redirect: 'error' });
+    const text = await response.text();
+    let data;
+    try { data = JSON.parse(text); } catch { throw new Error('Server returned non-JSON (HTTP ' + response.status + ').'); }
+    if (!response.ok) throw new Error('ProjectBridge HTTP ' + response.status + ': ' + String(data.error || data.message || 'request failed'));
+    if (data.ok === false || data.error) throw new Error(String(data.error || 'ProjectBridge request failed'));
+    return data;
+  } finally { clearTimeout(timer); }
+}
+async function saveConfig(config) {
+  const file = configPath();
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  await fs.writeFile(file, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  if (process.platform !== 'win32') { await fs.chmod(path.dirname(file), 0o700); await fs.chmod(file, 0o600); }
+  return file;
+}
+async function enroll(base) {
+  console.log('Requesting a temporary ProjectBridge pairing…');
+  const start = await request(base, '/api/enroll/start', hostInfo());
+  const pairing = start.result;
+  if (!pairing?.pairing_id || !pairing?.code || !pairing?.poll_token) throw new Error('Enrollment response was incomplete.');
+  console.log('\nPairing code: ' + pairing.code);
+  console.log('This code expires in about ' + (pairing.expires_in || 300) + ' seconds.');
+  console.log('Open the ProjectBridge dashboard, go to Activity → Pending device approvals, verify this host and code, then click Confirm & connect.');
+  console.log('No separate browser confirmation is required. Keep this terminal open until the dashboard approves the host.');
+  const deadline = Date.now() + Math.min(300, Math.max(30, Number(pairing.expires_in) || 300)) * 1000;
+  while (Date.now() < deadline) {
+    await sleep(4000);
+    const poll = await request(base, '/api/enroll/status', { pairing_id: pairing.pairing_id, code: pairing.code, poll_token: pairing.poll_token });
+    const result = poll.result;
+    if (result?.status === 'expired') throw new Error('Pairing expired. Run the command again to get a new code.');
+    if (result?.status === 'enrolled' && typeof result.credential === 'string' && result.credential.length >= 32) {
+      const file = await saveConfig({ server_url: base, device_credential: result.credential, heartbeat_interval_seconds: 30, agent_version: VERSION });
+      console.log('Host enrolled as ' + result.device_id + '. Protected config saved to ' + file);
+      return result.credential;
+    }
+    const states = [];
+    if (result?.dashboard_approved) states.push('dashboard approved; finishing connection');
+    console.log('Waiting for both confirmations' + (states.length ? ' (' + states.join(', ') + ')' : '') + '…');
+  }
+  throw new Error('Pairing timed out. No credential was saved.');
+}
+async function collect(tool, args={}) {
+  if (!READ_ONLY_TOOLS.has(tool) && !CONTROLLED_TOOLS.has(tool)) throw new Error('Operation is not in the host-operation allowlist.');
+  if (tool==='artifact.verify') return verifyArtifact(args);
+  if (tool==='service.control') return serviceControl(args);
+  if (tool==='process.terminate') return terminateProcess(args);
+  if (tool==='system.info') return {hostname:os.hostname(),platform:hostInfo().platform,os_version:os.version(),architecture:os.arch(),cpu_count:os.cpus().length,uptime_seconds:Math.floor(os.uptime()),total_memory_bytes:os.totalmem(),free_memory_bytes:os.freemem(),agent_version:VERSION};
+  if (tool==='memory.info') return {total_bytes:os.totalmem(),free_bytes:os.freemem(),used_bytes:os.totalmem()-os.freemem(),used_percent:Math.round((os.totalmem()-os.freemem())/os.totalmem()*1000)/10};
+  let argv;
+  if (tool==='process.list') {
+    if(process.platform==='win32') argv=['powershell.exe','-NoProfile','-NonInteractive','-Command','Get-Process | Sort-Object CPU -Descending | Select-Object -First 100 Id,ProcessName,CPU,WorkingSet64 | ConvertTo-Json -Compress'];
+    else if(process.platform==='darwin') argv=['ps','-Ao','pid=,comm=,pcpu=,rss='];
+    else argv=['ps','-eo','pid=,comm=,pcpu=,rss=','--sort=-pcpu'];
+  } else if(tool==='disk.list') {
+    if(process.platform==='win32') argv=['powershell.exe','-NoProfile','-NonInteractive','-Command','Get-CimInstance Win32_LogicalDisk | Select-Object DeviceID,VolumeName,FileSystem,Size,FreeSpace | ConvertTo-Json -Compress'];
+    else argv=['df','-Pk'];
+  } else if(tool==='network.interfaces') {
+    if(process.platform==='win32') argv=['powershell.exe','-NoProfile','-NonInteractive','-Command','Get-NetIPConfiguration | Select-Object InterfaceAlias,InterfaceIndex,IPv4Address,IPv6Address | ConvertTo-Json -Compress'];
+    else if(process.platform==='darwin') argv=['ifconfig'];
+    else argv=['ip','-brief','address'];
+  } else if(tool==='network.connections') {
+    if(process.platform==='win32') argv=['powershell.exe','-NoProfile','-NonInteractive','-Command','Get-NetTCPConnection | Select-Object -First 200 State,LocalAddress,LocalPort,RemoteAddress,RemotePort,OwningProcess | ConvertTo-Json -Compress'];
+    else if(process.platform==='darwin') argv=['netstat','-an'];
+    else if(await commandExists('ss')) argv=['ss','-tunap'];
+    else argv=['netstat','-tunap'];
+  } else {
+    if(process.platform==='win32') argv=['powershell.exe','-NoProfile','-NonInteractive','-Command','Get-Service | Sort-Object Name | Select-Object -First 200 Name,DisplayName,Status,StartType | ConvertTo-Json -Compress'];
+    else if(process.platform==='darwin') argv=['launchctl','list'];
+    else argv=['systemctl','list-units','--type=service','--all','--no-legend','--no-pager','--plain'];
+  }
+  const r=await runLocal(argv);
+  if(r.exit_code!==0) throw new Error((r.stderr||('Local utility exited '+r.exit_code)).trim().slice(0,500));
+  if(process.platform==='win32') { try { return JSON.parse(r.stdout||'[]'); } catch { throw new Error('Could not parse local system utility output.'); } }
+  return {format:'text',output:r.stdout.slice(-16000)};
+}
+async function verifyArtifact(args) {
+  const allowed=new Set(['path','expected_sha256']);
+  if(!args||typeof args.path!=='string'||!path.isAbsolute(args.path)||args.path.length>1024||args.path.includes('\0')||Object.keys(args).some(k=>!allowed.has(k))) throw new Error('Provide an absolute artifact path and optional expected_sha256.');
+  if(args.expected_sha256&&!/^[a-fA-F0-9]{64}$/.test(args.expected_sha256))throw new Error('expected_sha256 must be 64 hexadecimal characters.');
+  const file=await fs.realpath(args.path);
+  const st=await fs.stat(file);
+  if(!st.isFile())throw new Error('Artifact path must point to a regular file.');
+  if(st.size>20*1024*1024*1024)throw new Error('Artifact exceeds the 20 GiB verification limit.');
+  const ext=path.extname(file).toLowerCase();
+  const supported=new Set(['.zip','.dmg','.appimage','.deb','.exe','.msi','.tar','.tgz','.gz','.bz2','.xz']);
+  if(!supported.has(ext))throw new Error('Unsupported artifact extension. Supported: '+[...supported].join(', '));
+  const crypto=require('node:crypto');
+  const hash=crypto.createHash('sha256');
+  const stream=require('node:fs').createReadStream(file);
+  for await (const chunk of stream) hash.update(chunk);
+  const sha256=hash.digest('hex');
+  const result={path:file,name:path.basename(file),size_bytes:st.size,sha256,expected_sha256:args.expected_sha256||null,checksum_match:args.expected_sha256?sha256.toLowerCase()===args.expected_sha256.toLowerCase():null,integrity_check:args.expected_sha256&&sha256.toLowerCase()===args.expected_sha256.toLowerCase()?'sha256-match':'hash-only',verified:Boolean(args.expected_sha256&&sha256.toLowerCase()===args.expected_sha256.toLowerCase()),checks:[]};
+  if(args.expected_sha256&&!result.checksum_match){result.checks.push({name:'sha256',ok:false,expected:args.expected_sha256.toLowerCase(),actual:sha256});return result;}
+  if(ext==='.zip'){
+    if(process.platform==='win32'){
+      if(!await commandExists('7z.exe')){result.checks.push({name:'7z-test',ok:false,reason:'Requires 7-Zip (7z.exe) on Windows'});return result;}
+      const r=await runLocal(['7z.exe','t',file],180000);
+      if(r.exit_code!==0)throw new Error((r.stderr||r.stdout||'ZIP integrity verification failed').slice(-2000));
+      result.integrity_check='7z-test';result.verified=true;result.checks.push({name:'7z-test',ok:true,output:r.stdout.slice(-2000)});
+    } else {
+      if(!await commandExists('unzip')){result.checks.push({name:'zip-test',ok:false,reason:'unzip utility unavailable'});return result;}
+      const r=await runLocal(['unzip','-t',file],180000);
+      if(r.exit_code!==0)throw new Error((r.stderr||r.stdout||'ZIP integrity verification failed').slice(-2000));
+      result.integrity_check='zip-test';result.verified=true;result.checks.push({name:'zip-test',ok:true,output:r.stdout.slice(-2000)});
+    }
+  } else if(ext==='.dmg'){
+    if(process.platform!=='darwin'){result.checks.push({name:'hdiutil-verify',ok:false,reason:'Requires macOS; SHA-256 only on this host'});return result;}
+    const r=await runLocal(['hdiutil','verify',file],180000);
+    if(r.exit_code!==0)throw new Error((r.stderr||r.stdout||'Disk image verification failed').slice(-2000));
+    result.integrity_check='hdiutil-verify';result.verified=true;result.checks.push({name:'hdiutil-verify',ok:true,output:r.stdout.slice(-4000)});
+  } else if(['.gz','.tgz'].includes(ext)){
+    if(!await commandExists('gzip'))throw new Error('gzip verification utility is unavailable on this host.');
+    const r=await runLocal(['gzip','-t',file],180000);
+    if(r.exit_code!==0)throw new Error((r.stderr||'gzip integrity verification failed').slice(-1000));
+    result.integrity_check='gzip-test';result.verified=true;result.checks.push({name:'gzip-test',ok:true});
+    if((ext==='.tgz'||file.toLowerCase().endsWith('.tar.gz'))&&await commandExists('tar')){const t=await runLocal(['tar','-tzf',file],180000);if(t.exit_code!==0)throw new Error((t.stderr||'TAR entry validation failed').slice(-1000));result.checks.push({name:'tar-list',ok:true,entries:t.stdout.split(/\r?\n/).filter(Boolean).length});}
+  } else if(ext==='.tar'){
+    if(!await commandExists('tar'))throw new Error('tar verification utility is unavailable on this host.');
+    const r=await runLocal(['tar','-tf',file],180000);
+    if(r.exit_code!==0)throw new Error((r.stderr||'tar archive validation failed').slice(-1000));
+    result.integrity_check='tar-list';result.verified=true;result.checks.push({name:'tar-list',ok:true,entries:r.stdout.split(/\r?\n/).filter(Boolean).length});
+  } else if(['.bz2','.xz'].includes(ext)){
+    const utility=ext==='.bz2'?'bzip2':'xz';
+    if(!await commandExists(utility)){result.checks.push({name:utility+'-test',ok:false,reason:utility+' utility unavailable'});return result;}
+    const r=await runLocal([utility,'-t',file],180000);
+    if(r.exit_code!==0)throw new Error((r.stderr||utility+' integrity verification failed').slice(-1000));
+    result.integrity_check=utility+'-test';result.verified=true;result.checks.push({name:utility+'-test',ok:true});
+    if(file.toLowerCase().endsWith('.tar.bz2')||file.toLowerCase().endsWith('.tar.xz')){if(!await commandExists('tar')){result.checks.push({name:'tar-list',ok:false,reason:'tar utility unavailable'});result.verified=false;}else{const t=await runLocal(['tar','-tf',file],180000);if(t.exit_code!==0)throw new Error((t.stderr||'TAR entry validation failed').slice(-1000));result.checks.push({name:'tar-list',ok:true,entries:t.stdout.split(/\r?\n/).filter(Boolean).length});}}
+  } else if(ext==='.deb'&&process.platform==='linux'&&await commandExists('dpkg-deb')){
+    const r=await runLocal(['dpkg-deb','--info',file],60000);
+    if(r.exit_code!==0)throw new Error((r.stderr||'Debian package validation failed').slice(-1000));
+    result.integrity_check='dpkg-deb-info';result.verified=true;result.checks.push({name:'dpkg-deb-info',ok:true,output:r.stdout.slice(-2000)});
+  }
+  return result;
+}
+async function terminateProcess(args) {
+  const pid=args?.pid;
+  if(!Number.isSafeInteger(pid)||pid<5||pid>2147483647||Object.keys(args).some(k=>k!=='pid')) throw new Error('Invalid process termination request.');
+  if(pid===process.pid||pid===process.ppid) throw new Error('Refusing to terminate the ProjectBridge agent or its parent process.');
+  if(process.platform==='win32') {
+    const r=await runLocal(['taskkill.exe','/PID',String(pid),'/T'],15000);
+    if(r.exit_code!==0)throw new Error((r.stderr||r.stdout||'Windows process termination failed').slice(0,500));
+    return {pid,signal:'terminate',status:'requested',output:r.stdout.slice(-2000)};
+  }
+  try { process.kill(pid,'SIGTERM'); return {pid,signal:'SIGTERM',status:'requested'}; }
+  catch(e) { throw new Error('Could not terminate process '+pid+': '+String(e.message||e).slice(0,300)); }
+}
+async function serviceControl(args) {
+  const name=args?.name, operation=args?.operation;
+  if(typeof name!=='string'||!/^[A-Za-z0-9_.@-]{1,128}$/.test(name)||!['start','stop','restart'].includes(operation)||Object.keys(args).some(k=>!['name','operation'].includes(k))) throw new Error('Invalid service control request.');
+  if(process.platform==='win32') {
+    const payload=Buffer.from(JSON.stringify({name,operation}),'utf8').toString('base64');
+    const script="$ErrorActionPreference='Stop';$d=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('"+payload+"'))|ConvertFrom-Json;switch($d.operation){'start'{Start-Service -Name $d.name -ErrorAction Stop};'stop'{Stop-Service -Name $d.name -ErrorAction Stop};'restart'{Restart-Service -Name $d.name -ErrorAction Stop}};Get-Service -Name $d.name|Select-Object Name,Status|ConvertTo-Json -Compress";
+    const encoded=Buffer.from(script,'utf16le').toString('base64');
+    const r=await runLocal(['powershell.exe','-NoLogo','-NoProfile','-NonInteractive','-EncodedCommand',encoded],45000);
+    if(r.exit_code!==0)throw new Error((r.stderr||'Windows service operation failed').slice(0,500));
+    try{return JSON.parse(r.stdout||'{}')}catch{return {output:r.stdout.slice(-2000)}};
+  }
+  if(process.platform!=='linux') throw new Error('Remote service control is currently supported on Windows and Linux only.');
+  const r=await runLocal(['systemctl',operation,name],45000);
+  if(r.exit_code!==0)throw new Error((r.stderr||'Service operation failed').slice(0,500));
+  return {name,operation,status:'requested',stdout:r.stdout.slice(-2000)};
+}
+async function commandExists(name) { const dirs=(process.env.PATH||'').split(path.delimiter); for(const dir of dirs){try{await fs.access(path.join(dir,name));return true}catch{}} return false; }
+async function runLocal(argv,timeoutMs) { return runLocalImpl(argv,timeoutMs); }
+async function runLocalImpl(argv,timeoutMs=12000) {
+  return new Promise((resolve,reject)=>{
+    const child=spawn(argv[0],argv.slice(1),{stdio:['ignore','pipe','pipe'],windowsHide:true});let stdout='',stderr='',closed=false;
+    const timer=setTimeout(()=>child.kill(),timeoutMs);
+    child.stdout.on('data',b=>stdout=(stdout+b.toString()).slice(-50000));
+    child.stderr.on('data',b=>stderr=(stderr+b.toString()).slice(-8000));
+    child.on('error',e=>{if(closed)return;closed=true;clearTimeout(timer);reject(new Error('Required local utility unavailable: '+e.message))});
+    child.on('close',(code)=>{if(closed)return;closed=true;clearTimeout(timer);resolve({exit_code:code??-1,stdout,stderr})});
+  });
+}
+async function handleTask(base,credential,task) {
+  if(!task || typeof task.id!=='string' || (!READ_ONLY_TOOLS.has(task.tool)&&!CONTROLLED_TOOLS.has(task.tool))) throw new Error('Server supplied an unsupported task; refusing to execute it.');
+  const started_at=new Date().toISOString();
+  try { const result=await collect(task.tool,task.args||{}); await request(base,'/api/commander/tasks/result',{task_id:task.id,status:'completed',result,started_at,finished_at:new Date().toISOString()},credential); console.log(new Date().toISOString()+' Completed host task '+task.tool+'.'); }
+  catch(e) { await request(base,'/api/commander/tasks/result',{task_id:task.id,status:'failed',error:String(e.message||e).slice(0,500),started_at,finished_at:new Date().toISOString()},credential); console.error('Task '+task.tool+' failed: '+String(e.message||e).slice(0,250)); }
+}
+async function remote() {
+  if (Number(process.versions.node.split('.')[0]) < 20) throw new Error('Node.js 20 or newer is required.');
+  let base=DEFAULT_SERVER,credential,file=configPath();
+  try { const c=JSON.parse(await fs.readFile(file,'utf8'));if(c.server_url)base=String(c.server_url).replace(/\/$/,'');if(typeof c.device_credential==='string'&&c.device_credential.length>=32)credential=c.device_credential; }
+  catch(e){
+    if(e.code!=='ENOENT')throw new Error('Could not read ProjectBridge config: '+e.message);
+    if(process.platform==='win32') {
+      const legacy=path.join(process.env.ProgramData||'C:\\ProgramData','ProjectBridge','remote.json');
+      try { const c=JSON.parse(await fs.readFile(legacy,'utf8')); if(c.server_url)base=String(c.server_url).replace(/\/$/,''); if(typeof c.device_credential==='string'&&c.device_credential.length>=32){credential=c.device_credential;await saveConfig(c);console.log('Migrated the existing host credential to the per-user config directory.');} }
+      catch(oldError){if(oldError.code!=='ENOENT')throw new Error('Could not read legacy ProjectBridge config: '+oldError.message)}
+    }
+  }
+  const url=new URL(base);
+  if(url.protocol!=='https:'&&!(url.protocol==='http:'&&['localhost','127.0.0.1'].includes(url.hostname)))throw new Error('HTTPS is required except for localhost testing.');
+  if(!credential)credential=await enroll(base);
+  console.log('ProjectBridge remote agent is connected. Read-only inspection and confirmed service controls are enabled; arbitrary shell execution and remote file writes are disabled.');
+  let delay=2,lastHeartbeat=0,lastUpdateCheck=0;
+  while(true){
+    try{
+      if(Date.now()-lastUpdateCheck>=6*60*60*1000){
+        lastUpdateCheck=Date.now();
+        try {
+          const update=await lifecycle.updateRuntime();
+          if(update.updated){
+            console.log('ProjectBridge updated from '+update.current+' to '+update.latest+'. Restarting the agent to load the new version.');
+            if(process.env.PROJECTBRIDGE_MANAGED==='1') process.exit(75);
+            const child=spawn(process.execPath,[lifecycle.runtimeEntry(),'remote'],{stdio:'inherit',env:process.env,windowsHide:true});
+            child.on('error',e=>console.error('Could not restart updated agent: '+e.message));
+            await new Promise(resolve=>child.once('spawn',resolve));
+            process.exit(0);
+          }
+        } catch(e) { console.error('Automatic update check failed; current agent remains active: '+String(e.message||e).slice(0,300)); }
+      }
+      if(Date.now()-lastHeartbeat>=30000){
+        const hb=await request(base,'/api/commander/heartbeat',{metadata:hostInfo()},credential);
+        if(!hb.result?.device_id)throw new Error('Heartbeat response was incomplete.');
+        lastHeartbeat=Date.now();
+      }
+      const poll=await request(base,'/api/commander/tasks/poll',{metadata:hostInfo()},credential);
+      if(poll.result?.task)await handleTask(base,credential,poll.result.task);
+      delay=2;
+    }catch(e){console.error('Connection unavailable: '+String(e.message||e).slice(0,300)+'. Retrying in '+delay+'s.');delay=Math.min(60,delay*2)}
+    await sleep(delay*1000);
+  }
+}
+async function ensureEnrollment(){
+  const file=configPath();
+  try { const c=JSON.parse(await fs.readFile(file,'utf8')); if(typeof c.device_credential==='string'&&c.device_credential.length>=32)return; }
+  catch(e){if(e.code!=='ENOENT')throw e;}
+  if(process.platform==='win32') {
+    const legacy=path.join(process.env.ProgramData||'C:\\ProgramData','ProjectBridge','remote.json');
+    try { const c=JSON.parse(await fs.readFile(legacy,'utf8')); if(typeof c.device_credential==='string'&&c.device_credential.length>=32){await saveConfig(c);return;} }
+    catch(e){if(e.code!=='ENOENT')throw e;}
+  }
+  await enroll(DEFAULT_SERVER);
+}
+async function main(){
+  const command=process.argv[2];
+  if(command==='remote')return remote();
+  if(command==='install-service') { await ensureEnrollment(); const r=await lifecycle.installService(); console.log('ProjectBridge persistence enabled for this user on '+r.platform+'.'); console.log('Runtime: '+lifecycle.runtimeDir()); return; }
+  if(command==='uninstall-service') { const r=await lifecycle.uninstallService(); console.log('Persistent startup removed for '+r.platform+'. The enrollment credential was kept.'); return; }
+  if(command==='update') { const r=await lifecycle.updateRuntime(); console.log(r.updated?'Updated ProjectBridge runtime to '+r.latest+'.':'ProjectBridge runtime is current ('+r.latest+').'); return; }
+  if(command==='--help'||command==='-h'||command==='help'||!command){
+    console.log('ProjectBridge Remote '+VERSION+'\n\nUsage: npx --yes @brrew/projectbridge@latest <command>\n\nCommands:\n  remote            Enroll or connect this host in the foreground\n  install-service   Install per-user persistent startup and automatic updates\n  uninstall-service Remove persistent startup (keeps enrollment)\n  update            Check npm latest and update the managed runtime\n  help              Show this help\n\nAutomatic updates check npm latest every six hours while online. Updates use npm registry TLS and package integrity verification. Arbitrary shell execution and remote file writes remain disabled.');
+    return;
+  }
+  throw new Error('Unknown command: '+command+'. Run with --help.');
+}
+if(require.main===module) main().catch(e=>{console.error('ProjectBridge: '+e.message);process.exitCode=1});
+module.exports={collect,READ_ONLY_TOOLS,CONTROLLED_TOOLS,serviceControl,terminateProcess,verifyArtifact,VERSION};

package/lib/lifecycle.js

@@ -0,0 +1,120 @@
+'use strict';
+const fs = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const PACKAGE = '@brrew/projectbridge';
+const SERVICE = 'ProjectBridgeRemote';
+const SOURCE_DIR = path.resolve(__dirname, '..');
+function versionParts(value) { const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(String(value || '')); return m ? [Number(m[1]), Number(m[2]), Number(m[3]), m[4] || ''] : null; }
+function isNewer(a, b) { const x = versionParts(a), y = versionParts(b); if (!x || !y) return false; for (let i = 0; i < 3; i++) { if (x[i] !== y[i]) return x[i] > y[i]; } return !x[3] && !!y[3] ? true : !!x[3] && !y[3] ? false : false; }
+function runtimeDir() {
+  const root = process.platform === 'win32' ? (process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local')) : (process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share'));
+  return path.join(root, 'projectbridge', 'runtime');
+}
+function runtimeEntry() { return path.join(runtimeDir(), 'node_modules', '@brrew', 'projectbridge', 'bin', 'projectbridge.js'); }
+function npmCommand() { return path.join(path.dirname(process.execPath), process.platform === 'win32' ? 'npm.cmd' : 'npm'); }
+function run(command, args, timeoutMs = 120000) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { windowsHide: true, shell: process.platform === 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '', stderr = '';
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+    child.stdout.on('data', b => stdout = (stdout + b.toString()).slice(-12000));
+    child.stderr.on('data', b => stderr = (stderr + b.toString()).slice(-6000));
+    child.on('error', e => { clearTimeout(timer); reject(new Error('Could not start ' + command + ': ' + e.message)); });
+    child.on('close', code => { clearTimeout(timer); resolve({ code: code ?? -1, stdout, stderr }); });
+  });
+}
+async function installedVersion() {
+  try { return JSON.parse(await fs.readFile(path.join(runtimeDir(), 'node_modules', '@brrew', 'projectbridge', 'package.json'), 'utf8')).version; }
+  catch { return null; }
+}
+async function latestVersion() {
+  const r = await run(npmCommand(), ['view', PACKAGE, 'dist-tags.latest'], 30000);
+  if (r.code !== 0) throw new Error(('Could not check npm latest version: ' + r.stderr).trim().slice(0, 500));
+  const version = r.stdout.trim();
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) throw new Error('npm returned an invalid latest version.');
+  return version;
+}
+async function installPackage(spec) {
+  await fs.mkdir(runtimeDir(), { recursive: true });
+  const r = await run(npmCommand(), ['install', '--prefix', runtimeDir(), '--no-audit', '--no-fund', '--ignore-scripts', spec], 180000);
+  if (r.code !== 0) throw new Error(('npm install failed: ' + r.stderr).trim().slice(0, 700));
+}
+async function updateRuntime() {
+  const latest = await latestVersion();
+  let current = await installedVersion();
+  if (!current) { await installPackage(SOURCE_DIR); current = await installedVersion(); }
+  const sourcePackage = JSON.parse(await fs.readFile(path.join(SOURCE_DIR, 'package.json'), 'utf8'));
+  if (isNewer(sourcePackage.version, current)) { await installPackage(SOURCE_DIR); current = await installedVersion(); }
+  if (isNewer(latest, current)) { await installPackage(PACKAGE + '@' + latest); }
+  const installed = await installedVersion();
+  if (!installed) throw new Error('Runtime package was not installed.');
+  return { updated: installed !== current, current, latest: installed, available: latest };
+}
+async function writePrivate(file, contents) {
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  await fs.writeFile(file, contents, { mode: 0o600 });
+  if (process.platform !== 'win32') await fs.chmod(file, 0o600);
+}
+async function installService() {
+  const updated = await updateRuntime();
+  const entry = runtimeEntry();
+  await fs.access(entry);
+  if (process.platform === 'linux') {
+    const unit = path.join(os.homedir(), '.config', 'systemd', 'user', 'projectbridge.service');
+    const content = '[Unit]\nDescription=ProjectBridge Remote Host Agent\nAfter=network-online.target\n\n[Service]\nType=simple\nExecStart=' + process.execPath + ' ' + entry + ' remote\nRestart=always\nRestartSec=5\nEnvironment=PROJECTBRIDGE_MANAGED=1\n\n[Install]\nWantedBy=default.target\n';
+    await writePrivate(unit, content);
+    const reload = await run('systemctl', ['--user', 'daemon-reload'], 20000);
+    if (reload.code !== 0) throw new Error(('Could not reload systemd user services: ' + reload.stderr).trim().slice(0, 500));
+    const enable = await run('systemctl', ['--user', 'enable', '--now', 'projectbridge.service'], 30000);
+    if (enable.code !== 0) throw new Error(('Could not enable user service: ' + enable.stderr).trim().slice(0, 500) + '. Check that the systemd user bus is available.');
+    return { platform: 'linux', service: unit, updated };
+  }
+  if (process.platform === 'darwin') {
+    const file = path.join(os.homedir(), 'Library', 'LaunchAgents', 'us.brrew.projectbridge.remote.plist');
+    const esc = s => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    const plist = '<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>us.brrew.projectbridge.remote</string><key>ProgramArguments</key><array><string>' + esc(process.execPath) + '</string><string>' + esc(entry) + '</string><string>remote</string></array><key>RunAtLoad</key><true/><key>KeepAlive</key><true/><key>EnvironmentVariables</key><dict><key>PROJECTBRIDGE_MANAGED</key><string>1</string></dict></dict></plist>\n';
+    await writePrivate(file, plist);
+    const uid = process.getuid ? process.getuid() : '';
+    await run('launchctl', ['bootout', 'gui/' + uid + '/us.brrew.projectbridge.remote'], 15000);
+    const load = await run('launchctl', ['bootstrap', 'gui/' + uid, file], 20000);
+    if (load.code !== 0) throw new Error(('Could not load LaunchAgent: ' + load.stderr).trim().slice(0, 500));
+    return { platform: 'darwin', service: file, updated };
+  }
+  if (process.platform === 'win32') {
+    const dir = path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'ProjectBridge');
+    const script = path.join(dir, 'run-agent.ps1');
+    const content = "$ErrorActionPreference = 'Continue'\n$env:PROJECTBRIDGE_MANAGED = '1'\n$node = '" + process.execPath.replace(/'/g, "''") + "'\n$entry = '" + entry.replace(/'/g, "''") + "'\nwhile ($true) { & $node $entry remote; Start-Sleep -Seconds 5 }\n";
+    await writePrivate(script, content);
+    const task = await run('schtasks.exe', ['/Create', '/F', '/SC', 'ONLOGON', '/TN', SERVICE, '/TR', 'powershell.exe -NoProfile -ExecutionPolicy Bypass -File "' + script + '"'], 30000);
+    if (task.code !== 0) throw new Error(('Could not create per-user logon task: ' + task.stderr + task.stdout).trim().slice(0, 700));
+    await run('schtasks.exe', ['/Run', '/TN', SERVICE], 15000);
+    return { platform: 'win32', service: SERVICE, script, updated };
+  }
+  throw new Error('Persistent installation is supported on Windows, macOS, and Linux only.');
+}
+async function uninstallService() {
+  if (process.platform === 'linux') {
+    await run('systemctl', ['--user', 'disable', '--now', 'projectbridge.service'], 20000);
+    await fs.rm(path.join(os.homedir(), '.config', 'systemd', 'user', 'projectbridge.service'), { force: true });
+    await run('systemctl', ['--user', 'daemon-reload'], 20000);
+    return { removed: true, platform: 'linux' };
+  }
+  if (process.platform === 'darwin') {
+    const file = path.join(os.homedir(), 'Library', 'LaunchAgents', 'us.brrew.projectbridge.remote.plist');
+    const uid = process.getuid ? process.getuid() : '';
+    await run('launchctl', ['bootout', 'gui/' + uid + '/us.brrew.projectbridge.remote'], 15000);
+    await fs.rm(file, { force: true });
+    return { removed: true, platform: 'darwin' };
+  }
+  if (process.platform === 'win32') {
+    await run('schtasks.exe', ['/End', '/TN', SERVICE], 10000);
+    const r = await run('schtasks.exe', ['/Delete', '/F', '/TN', SERVICE], 15000);
+    await fs.rm(path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'ProjectBridge', 'run-agent.ps1'), { force: true });
+    if (r.code !== 0 && !/cannot find|does not exist/i.test(r.stderr + r.stdout)) throw new Error('Could not remove scheduled task: ' + (r.stderr + r.stdout).slice(0, 500));
+    return { removed: true, platform: 'win32' };
+  }
+  throw new Error('Unsupported platform.');
+}
+module.exports = { runtimeDir, runtimeEntry, installedVersion, latestVersion, updateRuntime, installService, uninstallService, isNewer }

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@brrew/projectbridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "ProjectBridge remote host agent CLI",
+  "license": "UNLICENSED",
+  "type": "commonjs",
+  "bin": {
+    "projectbridge": "bin/projectbridge.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}