@aliens0006/vmagent 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# vmagent
+
+Lightweight authenticated HTTP command agent for a private server. It uses only Node.js built-ins.
+
+## Install
+
+```bash
+npm install --global @aliens0006/vmagent
+mkdir -p /etc/vmagent
+vmagent init --config /etc/vmagent/config.json
+```
+
+The `init` command generates a unique 256-bit API key and writes the config with mode `0600`. Do not commit or publish that config.
+
+## Run
+
+```bash
+vmagent start --config /etc/vmagent/config.json
+```
+
+Keep the listener on `127.0.0.1` when exposing it through Cloudflare Tunnel. The only authenticated endpoint is `POST /exec`.
+
+```bash
+curl https://vmagent.example.com/health
+curl -X POST https://vmagent.example.com/exec \
+  -H "Authorization: Bearer $VMAGENT_API_KEY" \
+  -H 'content-type: application/json' \
+  -d '{"command":"uname -a"}'
+```
+
+This agent executes arbitrary shell commands as its service user. Use a dedicated non-root account whenever possible and protect the tunnel with Cloudflare Access in addition to the API key.

package/agent.mjs

@@ -0,0 +1,111 @@
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import { appendFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = dirname(fileURLToPath(import.meta.url));
+
+export function loadConfig(path = resolve(root, 'config.json')) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function json(res, status, body) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(body));
+}
+
+function log(config, message) {
+  if (!config.logFile) return;
+  appendFile(config.logFile, `[${new Date().toISOString()}] ${message}\n`).catch(() => {});
+}
+
+function authorized(req, config) {
+  const value = req.headers.authorization;
+  return typeof value === 'string' && value.startsWith('Bearer ') && value.slice(7) === config.apiKey;
+}
+
+function readBody(req, maxBytes) {
+  return new Promise((resolveBody, reject) => {
+    let body = '';
+    req.setEncoding('utf8');
+    req.on('data', chunk => {
+      body += chunk;
+      if (Buffer.byteLength(body) > maxBytes) {
+        reject(Object.assign(new Error('request body too large'), { code: 'BODY_TOO_LARGE' }));
+        req.destroy();
+      }
+    });
+    req.on('end', () => resolveBody(body));
+    req.on('error', reject);
+  });
+}
+
+function runCommand(command, config) {
+  return new Promise(resolveResult => {
+    const started = Date.now();
+    const child = spawn('/bin/sh', ['-c', command], {
+      env: { ...process.env, PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' },
+      detached: true,
+    });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const append = (target, chunk) => {
+      const remaining = config.maxOutput - Buffer.byteLength(target);
+      return remaining > 0 ? target + chunk.toString('utf8').slice(0, remaining) : target;
+    };
+    child.stdout.on('data', chunk => { stdout = append(stdout, chunk); });
+    child.stderr.on('data', chunk => { stderr = append(stderr, chunk); });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try { process.kill(-child.pid, 'SIGTERM'); } catch {}
+    }, config.timeout);
+    child.on('error', error => {
+      clearTimeout(timer);
+      resolveResult({ exitCode: -1, stdout, stderr: error.message, duration: Date.now() - started, error: 'spawn_error' });
+    });
+    child.on('close', code => {
+      clearTimeout(timer);
+      resolveResult({ exitCode: code ?? -1, stdout, stderr, duration: Date.now() - started, error: timedOut ? 'timeout' : null });
+    });
+  });
+}
+
+export function createServer(config) {
+  let active = 0;
+  return http.createServer(async (req, res) => {
+    const path = new URL(req.url, `http://${req.headers.host || 'localhost'}`).pathname;
+    if (req.method === 'GET' && path === '/health') {
+      return json(res, 200, { status: 'ok', uptime: process.uptime() });
+    }
+    if (req.method !== 'POST' || path !== '/exec') return json(res, 404, { error: 'Not found' });
+    if (!authorized(req, config)) return json(res, 401, { error: 'Unauthorized' });
+    if (active >= config.maxConcurrent) return json(res, 429, { error: 'Too many concurrent commands' });
+    active += 1;
+    try {
+      let body;
+      try { body = JSON.parse(await readBody(req, config.maxBody)); } catch (error) {
+        return json(res, error.code === 'BODY_TOO_LARGE' ? 413 : 400, { error: error.code === 'BODY_TOO_LARGE' ? error.message : 'Invalid JSON' });
+      }
+      if (typeof body.command !== 'string' || !body.command.trim()) return json(res, 400, { error: 'command must be a non-empty string' });
+      log(config, `exec command_length=${body.command.length}`);
+      return json(res, 200, await runCommand(body.command, config));
+    } finally {
+      active -= 1;
+    }
+  });
+}
+
+export async function start(configPath) {
+  const config = loadConfig(configPath);
+  if (!/^[a-f0-9]{64}$/.test(config.apiKey)) throw new Error('config.apiKey must be a 64-character hex key');
+  const server = createServer(config);
+  await new Promise((resolveListen, reject) => {
+    server.once('error', reject);
+    server.listen(config.port, config.host, resolveListen);
+  });
+  log(config, `started host=${config.host} port=${config.port}`);
+  return server;
+}

package/cli.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { randomBytes } from 'node:crypto';
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { start } from './agent.mjs';
+
+const root = dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const command = args[0] || 'start';
+const configIndex = args.indexOf('--config');
+const configPath = resolve(configIndex >= 0 ? args[configIndex + 1] : './config.json');
+
+if (command === 'init') {
+  await mkdir(dirname(configPath), { recursive: true });
+  const apiKey = randomBytes(32).toString('hex');
+  const config = { host: '127.0.0.1', port: 3100, apiKey, timeout: 30000, maxOutput: 1048576, maxBody: 1048576, maxConcurrent: 2 };
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  await chmod(configPath, 0o600);
+  console.log(`Created ${configPath}`);
+  console.log(`API key: ${apiKey}`);
+  process.exit(0);
+}
+
+if (command !== 'start') {
+  console.error(`Usage: ${process.argv[1]} [init|start] [--config path]`);
+  process.exit(2);
+}
+
+const server = await start(configPath);
+console.log(`vmagent listening on ${server.address().address}:${server.address().port}`);
+process.on('SIGTERM', () => server.close(() => process.exit(0)));

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@aliens0006/vmagent",
+  "version": "0.1.0",
+  "description": "Lightweight authenticated HTTP command agent for private server automation",
+  "type": "module",
+  "bin": {
+    "vmagent": "cli.mjs"
+  },
+  "files": [
+    "agent.mjs",
+    "cli.mjs",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/agent.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}