remote-access-mcp 2.3.1 → 2.4.0

package/README.fa.md

@@ -24,6 +24,8 @@ ramcp init
 
 ## شروع سریع
 
+روی **سرور** با دامنه:
+
 ```bash
 ramcp init                          # کانفیگ + اولین توکن
 ramcp policy allow /srv/myapp       # چه مسیرهایی رو AI ببینه
@@ -33,6 +35,17 @@ ramcp doctor                        # بررسی سلامت همه‌چیز
 ramcp url                           # URL کانکتور برای چت‌بات
 ```
 
+روی **لپ‌تاپ / دسکتاپ** (بدون دامنه و بدون پورت‌فوروارد):
+
+```bash
+ramcp tunnel
+# → دفعه اول cloudflared رو خودکار دانلود می‌کنه (بدون نیاز به اکانت)
+#   یه URL عمومی https میده مثل https://random-words.trycloudflare.com
+# دستور `ramcp url` توی ترمینال دیگه، لینک زنده کانکتور رو نشون میده.
+```
+
+روی ویندوز، مک و لینوکس یکسانه — PowerShell/cmd روی ویندوز، launchd روی مک، systemd روی لینوکس برای سرویس خودکار.
+
 ## توکن‌های چندگانه — کمترین دسترسی به‌صورت پیش‌فرض
 
 ```bash
@@ -49,6 +62,27 @@ ramcp token add --name deploy --paths /srv/app --scopes filesystem,git,shell --s
 
 فایل‌سیستم (۷)، شل (۳)، سیستم (۳)، HTTP با محافظ SSRF (۳)، گیت با whitelist فعل‌ها (۱)، SQLite تک-دستوره (۲)، لاگ/journalctl (۳)، سرویس‌های systemd (۲)، پکیج‌ها apt/npm (۳)، زمان‌بند (۳)، اسکن امنیتی (۲)، تحلیل پروژه (۲)، پلنینگ + اسنپ‌شات/rollback (۴)، مدیریت پالیسی (۴).
 
+## Fleet: کنترل چند سرور با SSH
+
+گیت‌وی روی یک ماشین می‌مونه؛ ابزارهای remote-capable پارامتر `host` می‌گیرن و از طریق SSH روی ماشین دیگه اجرا میشن. روی سرورهای ریموت هیچ نرم‌افزاری نصب نمیشه — فقط یه SSH server و کلید شما روی گیت‌وی.
+
+```bash
+ramcp fleet add --name web1 --host deploy@10.0.0.5 --tools shell,fs --note "app server"
+ramcp fleet test                 # تست دسترسی همه هاست‌ها
+```
+
+بعد از داخل چت‌بات: «لاگ nginx روی web1 رو ببین» → `journal(unit: "nginx.service", host: "web1")`.
+
+هر هاست allowlist ابزار خودش رو داره (`shell fs logs services packages`) — هاستی که گروهی رو نگرفته با خطای واضح رد میشه، قبل از هر تلاش SSH. نوشتن فایل ریموت از طریق stdin (base64) انجام میشه — بدون فایل موقت. SSH با BatchMode اجرا میشه — هیچ پرامپت پسوردی نیست.
+
+## Webhook و بکاپ
+
+```bash
+ramcp webhook add --url https://hooks.example.com/ramcp --events tool.error
+ramcp config export --out backup.json    # اسنپ‌شات کامل — توکن‌های زنده داره!
+ramcp config import backup.json --merge  # ادغام با حفظ هویت محلی
+```
+
 ## مدل امنیتی
 
 - **فقط loopback** — سرور روی `127.0.0.1` گوش میده

package/README.md

@@ -23,7 +23,14 @@ The server binds to `127.0.0.1` only. You put it behind nginx (with Cloudflare o
 
 ## Install
 
-### One-liner (any Ubuntu/Debian server)
+### Any machine with Node 18+ — Linux, macOS, or Windows
+
+```bash
+npm install -g remote-access-mcp
+ramcp init
+```
+
+### One-liner (Ubuntu/Debian servers)
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AmirAliManzar/remote-access-mcp/main/install.sh | bash
@@ -39,6 +46,8 @@ ramcp init
 
 ## Quick start
 
+On a **server** with a domain:
+
 ```bash
 ramcp init                          # config + first token
 ramcp policy allow /srv/myapp       # what the AI may touch
@@ -48,6 +57,18 @@ ramcp doctor                        # verify everything end-to-end
 ramcp url                           # connector URL for your chatbot
 ```
 
+On a **laptop or desktop** (no domain, no port forwarding):
+
+```bash
+ramcp tunnel
+# → downloads cloudflared on first run (no account needed),
+#   prints a public https URL like https://random-words.trycloudflare.com
+# `ramcp url` in another terminal shows the live connector link.
+```
+
+Works the same on Windows, macOS, and Linux — PowerShell/cmd on Windows,
+launchd on macOS, systemd on Linux for the autostart service.
+
 ## Commands
 
 | Command | Description |
@@ -131,6 +152,39 @@ Endpoint `https://your-domain.com/mcp` + header `Authorization: Bearer <token>`
 
 **Policy** (4) `list_allowed_paths` `allow_path` `deny_path` `shell_enabled` — each token manages only its own sandbox
 
+## Fleet: drive other machines over SSH
+
+The gateway itself stays on one box; every remote-capable tool gains a `host` parameter that routes over SSH. No agent software on the remotes — just an SSH server and your key on the gateway.
+
+```bash
+# on the gateway:
+ramcp fleet add --name web1 --host deploy@10.0.0.5 --tools shell,fs --note "app server"
+ramcp fleet test                 # reachability probe for all hosts
+```
+
+Then from the chatbot: *"read the nginx log on web1"* → `journal(unit: "nginx.service", host: "web1")`.
+
+Each host gets an explicit tool allowlist (`shell fs logs services packages`) — a host that was never granted a group refuses it with a clear error, before any SSH attempt. Remote file writes pipe content over stdin (base64), never temp files. SSH runs with `BatchMode` — no password prompts, ever.
+
+## Webhooks
+
+Get notified when tools run (or fail) — incident bots, Slack relays, anything that accepts a POST:
+
+```bash
+ramcp webhook add --url https://hooks.example.com/ramcp --events tool.error
+ramcp webhook list
+```
+
+Fire-and-forget: a dead endpoint never delays a tool call (5s cap, deduped within 10s).
+
+## Backup & restore
+
+```bash
+ramcp config export --out backup.json     # full snapshot, 0600 perms — contains live tokens!
+ramcp config import backup.json           # replace
+ramcp config import backup.json --merge   # union: keeps local identity, adds new tokens/hosts/hooks
+```
+
 ## Security model
 
 - **Loopback only.** The gateway listens on `127.0.0.1` — unreachable directly from the network.
@@ -164,7 +218,7 @@ cd remote-access-mcp
 npm ci && npm run build && npm test
 ```
 
-42 tests: policy engine, auth matrix, tools-over-MCP integration, full v2 security matrix (scopes, read-only, SSRF, injection, audit chain), CLI lifecycle. CI runs on Node 18/20/22.
+122 tests: policy engine, auth matrix, transport compatibility (stateful, stateless, legacy SSE), cross-platform platform layer, tunnel wiring, CLI lifecycle, crash regressions. CI runs on Node 18/20/22.
 
 ## License
 

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAgyBA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBxD"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAmgCA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BxD"}

package/dist/cli/main.js

@@ -7,7 +7,9 @@ import { fileURLToPath } from 'node:url';
 import { loadConfig, saveConfig, generateToken, newTokenRecord, configPath, configDir, primaryToken, } from '../core/config.js';
 import { resolveReal, TOOL_SCOPES } from '../core/policy.js';
 import { AuditLog } from '../core/audit.js';
-import { platform, isWindows, isMac, isLinux, hasSystemd, platformLabel, } from '../core/platform.js';
+import { fleetProbe, isFleetCapability, FLEET_CAPABILITIES } from '../core/fleet.js';
+import { webhookStats } from '../core/webhooks.js';
+import { platform, isWindows, isMac, isLinux, hasSystemd, platformLabel, readRuntimeState, } from '../core/platform.js';
 import { resolveCloudflared } from '../core/tunnel.js';
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const PKG = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
@@ -56,6 +58,18 @@ Other:
   schedule list [--json]
   scopes                        List available tool groups
 
+Fleet (remote machines over SSH):
+  fleet add --name N --host user@h --tools shell,fs [--port P] [--note T]
+  fleet list | remove N | edit N [--tools …] | test | status
+  (tools accept host: run_command, read_file, write_file, … → run remotely)
+
+Webhooks:
+  webhook add --url https://… [--events tool.error,tool.success]
+  webhook list | off URL | on URL | remove URL
+
+Config:
+  config show | export [--out FILE] | import FILE [--merge]
+
 Options:
   -h, --help                    Show this help
   --json                        Machine-readable output where supported
@@ -66,7 +80,7 @@ function parseArgs(argv) {
     const flags = new Set();
     const values = new Map();
     // Flags that always take a value (so `--paths /a /b` still works positionally)
-    const valueFlags = new Set(['name', 'paths', 'deny', 'scopes', 'rpm', 'expires', 'token', 'host', 'port', 'domain', 'tool', 'since', 'limit']);
+    const valueFlags = new Set(['name', 'paths', 'deny', 'scopes', 'rpm', 'expires', 'token', 'host', 'port', 'domain', 'tool', 'since', 'limit', 'tools', 'url', 'events', 'out', 'note']);
     for (let i = 0; i < rest.length; i++) {
         const a = rest[i];
         if (a.startsWith('--')) {
@@ -203,6 +217,15 @@ async function cmdTunnel(args) {
 function cmdUrl(args) {
     const cfg = loadConfig();
     const t = findToken(cfg, args.sub[0] || args.values.get('token'));
+    // A live tunnel (pid-checked) wins: its URL only exists while that
+    // gateway process runs, and it is the address chatbots must use right now.
+    const rt = readRuntimeState();
+    if (rt?.tunnel_url) {
+        const base = rt.tunnel_url.replace(/\/+$/, '');
+        console.log(`${base}/${t.token}${cfg.mcp_path}`);
+        console.log(`\n(live tunnel — pid ${rt.pid}, since ${rt.started})`);
+        return;
+    }
     const host = cfg.public_host || `${cfg.host}:${cfg.port}`;
     const scheme = cfg.public_host ? 'https' : 'http';
     console.log(`${scheme}://${host}/${t.token}${cfg.mcp_path}`);
@@ -477,6 +500,20 @@ async function cmdDoctor(args) {
     // tunnel readiness
     const cf = resolveCloudflared();
     cf ? ok('tunnel', `cloudflared ready (${cf})`) : warn('tunnel', 'cloudflared not installed yet — `ramcp tunnel` downloads it automatically');
+    // live tunnel state (a running `ramcp tunnel` in another terminal)
+    const rt = readRuntimeState();
+    if (rt?.tunnel_url) {
+        try {
+            const resp = await fetch(`${rt.tunnel_url}/health`, { signal: AbortSignal.timeout(8000) });
+            const body = (await resp.json());
+            body.status === 'ok'
+                ? ok('tunnel-live', `${rt.tunnel_url} (pid ${rt.pid})`)
+                : warn('tunnel-live', `edge answered ${resp.status}`);
+        }
+        catch (e) {
+            warn('tunnel-live', `runtime state says pid ${rt.pid}, but unreachable (${e.message})`);
+        }
+    }
     // public reachability
     if (cfg.public_host) {
         try {
@@ -788,11 +825,14 @@ function uninstallService() {
 // ---------------------------------------------------------------------------
 function cmdStatus() {
     const cfg = loadConfig();
+    const rt = readRuntimeState();
     console.log(`platform:          ${platformLabel()}`);
     console.log(`config:            ${configPath()}`);
     console.log(`${serviceLabel()}:${' '.repeat(Math.max(1, 19 - serviceLabel().length - 1))}${serviceIsInstalled() ? (serviceIsActive() ? 'installed, active' : 'installed, inactive') : 'not installed'}`);
     console.log(`listen:            ${cfg.host}:${cfg.port}${cfg.mcp_path}`);
+    console.log(`gateway process:   ${rt ? `running (pid ${rt.pid})` : 'not running'}`);
     console.log(`public_host:       ${cfg.public_host || '(none — use `ramcp tunnel`)'}`);
+    console.log(`live tunnel:       ${rt?.tunnel_url || '(none)'}`);
     console.log(`tokens:            ${cfg.tokens.length}`);
     console.log(`allowed paths:     ${cfg.tokens.reduce((n, t) => n + t.allowed_paths.length, 0)}`);
     console.log(`audit:             ${cfg.audit.enabled ? 'on' : 'off'}`);
@@ -858,6 +898,237 @@ async function cmdUpgrade(args) {
     }
 }
 // ---------------------------------------------------------------------------
+// fleet — SSH remote machines
+// ---------------------------------------------------------------------------
+function cmdFleet(args) {
+    const cfg = loadConfig();
+    const sub = args.sub[0] || 'list';
+    const hosts = cfg.fleet.hosts;
+    if (sub === 'add') {
+        const name = args.values.get('name') || args.sub[1];
+        const host = args.values.get('host');
+        if (!name || !host) {
+            console.error('Usage: ramcp fleet add --name NAME --host user@hostname [--port N] --tools shell,fs [--note TEXT]');
+            process.exit(1);
+        }
+        if (hosts.some(h => h.name === name)) {
+            console.error(`Host "${name}" already exists (remove it first: ramcp fleet remove ${name})`);
+            process.exit(1);
+        }
+        const tools = splitList(args.values.get('tools'));
+        const bad = tools.filter(t => !isFleetCapability(t));
+        if (bad.length) {
+            console.error(`Unknown tool group(s): ${bad.join(', ')}. Available: ${FLEET_CAPABILITIES.join(', ')}`);
+            process.exit(1);
+        }
+        if (!tools.length) {
+            console.error('Refusing to add a host with no tools — grant at least one of: ' + FLEET_CAPABILITIES.join(', '));
+            process.exit(1);
+        }
+        const rec = {
+            name, host,
+            port: args.values.has('port') ? parseInt(args.values.get('port'), 10) : undefined,
+            tools, note: args.values.get('note'),
+            added: new Date().toISOString(),
+        };
+        hosts.push(rec);
+        saveConfig(cfg);
+        console.log(`✔ fleet host "${name}" added (${host}) with tools: ${tools.join(', ')}`);
+        const probe = fleetProbe(rec).then(r => {
+            console.log(r.ok ? `  SSH check: reachable` : `  SSH check: FAILED — ${r.detail}`);
+            console.log(r.ok ? `  (grant access from a chatbot with the fleet scope or all-tools tokens)` : `  (check: ssh keys loaded? BatchMode disables password prompts)`);
+        });
+        return;
+    }
+    if (sub === 'remove') {
+        const name = args.sub[1];
+        if (!name) {
+            console.error('Usage: ramcp fleet remove NAME');
+            process.exit(1);
+        }
+        const i = hosts.findIndex(h => h.name === name);
+        if (i === -1) {
+            console.error(`No fleet host named "${name}".`);
+            process.exit(1);
+        }
+        hosts.splice(i, 1);
+        saveConfig(cfg);
+        console.log(`✔ removed ${name}`);
+        return;
+    }
+    if (sub === 'edit') {
+        const name = args.sub[1];
+        if (!name) {
+            console.error('Usage: ramcp fleet edit NAME [--tools shell,fs] [--host user@h] [--note T]');
+            process.exit(1);
+        }
+        const h = hosts.find(h => h.name === name);
+        if (!h) {
+            console.error(`No fleet host named "${name}".`);
+            process.exit(1);
+        }
+        if (args.values.has('tools')) {
+            const tools = splitList(args.values.get('tools'));
+            const bad = tools.filter(t => !isFleetCapability(t));
+            if (bad.length) {
+                console.error(`Unknown: ${bad.join(', ')}. Available: ${FLEET_CAPABILITIES.join(', ')}`);
+                process.exit(1);
+            }
+            h.tools = tools;
+        }
+        if (args.values.has('host'))
+            h.host = args.values.get('host');
+        if (args.values.has('port'))
+            h.port = parseInt(args.values.get('port'), 10);
+        if (args.values.has('note'))
+            h.note = args.values.get('note');
+        saveConfig(cfg);
+        console.log(`✔ ${name} updated. tools: ${h.tools.join(',') || '(none)'}`);
+        return;
+    }
+    if (sub === 'test') {
+        (async () => {
+            for (const h of hosts) {
+                const r = await fleetProbe(h);
+                console.log(`${r.ok ? '✔' : '✖'} ${h.name.padEnd(14)} ${h.host}${h.port ? ':' + h.port : ''} ${r.ok ? 'reachable' : 'unreachable — ' + r.detail}`);
+            }
+            if (!hosts.length)
+                console.log('(no fleet hosts)');
+        })();
+        return;
+    }
+    if (sub === 'status') {
+        const { runtime } = { runtime: null };
+        for (const h of hosts) {
+            console.log(`${h.name.padEnd(14)} ${h.host}${h.port ? ':' + h.port : ''}  tools: ${h.tools.join(',')}${h.note ? '  — ' + h.note : ''}`);
+        }
+        if (!hosts.length)
+            console.log('(no fleet hosts — add one with `ramcp fleet add`)');
+        return;
+    }
+    // list / default
+    for (const h of hosts) {
+        console.log(`${h.name.padEnd(14)} ${h.host}${h.port ? ':' + h.port : ''}  tools: ${h.tools.join(',')}${h.note ? '  — ' + h.note : ''}`);
+    }
+    if (!hosts.length)
+        console.log('(no fleet hosts — add one with `ramcp fleet add --name NAME --host user@host --tools shell,fs`)');
+}
+// ---------------------------------------------------------------------------
+// webhook — outbound notifications
+// ---------------------------------------------------------------------------
+function cmdWebhook(args) {
+    const cfg = loadConfig();
+    const sub = args.sub[0] || 'list';
+    if (sub === 'add') {
+        const url = args.values.get('url');
+        if (!url || !/^https?:\/\//.test(url)) {
+            console.error('Usage: ramcp webhook add --url https://… [--events tool.error,tool.success]');
+            process.exit(1);
+        }
+        const events = splitList(args.values.get('events') || 'tool.error');
+        cfg.webhooks.push({ url, events, enabled: true });
+        saveConfig(cfg);
+        console.log(`✔ webhook added: ${url}`);
+        console.log(`  events: ${events.join(', ')}`);
+        console.log(`  (fires fire-and-forget after tool calls; 5s timeout, deduped within 10s)`);
+        return;
+    }
+    if (sub === 'remove') {
+        const i = cfg.webhooks.findIndex(w => w.url === args.sub[1]);
+        if (i === -1) {
+            console.error('No webhook with that URL.');
+            process.exit(1);
+        }
+        cfg.webhooks.splice(i, 1);
+        saveConfig(cfg);
+        console.log('✔ removed');
+        return;
+    }
+    if (sub === 'off' || sub === 'on') {
+        const w = cfg.webhooks.find(w => w.url === args.sub[1]);
+        if (!w) {
+            console.error('No webhook with that URL.');
+            process.exit(1);
+        }
+        w.enabled = sub === 'on';
+        saveConfig(cfg);
+        console.log(`✔ ${w.url} ${w.enabled ? 'enabled' : 'disabled'}`);
+        return;
+    }
+    // list
+    const stats = webhookStats();
+    if (!cfg.webhooks.length) {
+        console.log('(no webhooks — add with `ramcp webhook add --url …`)');
+        return;
+    }
+    for (const w of cfg.webhooks) {
+        console.log(`${w.enabled ? '✔' : '⏸'}  ${w.url}`);
+        console.log(`     events: ${w.events.join(', ')}`);
+    }
+    console.log(`\nsession stats: sent=${stats.sent} failed=${stats.failed}`);
+}
+// ---------------------------------------------------------------------------
+// config — export / import / show
+// ---------------------------------------------------------------------------
+function cmdConfig(args) {
+    const cfg = loadConfig();
+    const sub = args.sub[0] || 'show';
+    if (sub === 'export') {
+        const out = args.values.get('out') || 'ramcp-export.json';
+        const snapshot = JSON.parse(JSON.stringify(cfg));
+        // strip nothing — export is a full backup by design; tokens are the
+        // secrets that make the backup useful. Warn loudly instead.
+        fs.writeFileSync(out, JSON.stringify(snapshot, null, 2), { mode: 0o600 });
+        console.log(`✔ exported ${cfg.tokens.length} token(s), ${(cfg.fleet?.hosts || []).length} fleet host(s), ${(cfg.webhooks || []).length} webhook(s) → ${out}`);
+        console.log('⚠ this file contains live tokens — store it encrypted and delete when done.');
+        return;
+    }
+    if (sub === 'import') {
+        const file = args.sub[1];
+        if (!file) {
+            console.error('Usage: ramcp config import <file> [--merge]');
+            process.exit(1);
+        }
+        let incoming;
+        try {
+            incoming = JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch (e) {
+            console.error(`cannot read ${file}: ${e.message}`);
+            process.exit(1);
+        }
+        if (!Array.isArray(incoming.tokens)) {
+            console.error('not a ramcp export (no tokens array)');
+            process.exit(1);
+        }
+        if (args.flags.has('merge')) {
+            // merge: keep local identity (host/port/domain/paths), union tokens,
+            // add fleet hosts and webhooks that are new.
+            const existingUrls = new Set((cfg.webhooks || []).map(w => w.url));
+            for (const w of incoming.webhooks || [])
+                if (!existingUrls.has(w.url))
+                    cfg.webhooks.push(w);
+            const existingHosts = new Set((cfg.fleet?.hosts || []).map(h => h.name));
+            for (const h of incoming.fleet?.hosts || [])
+                if (!existingHosts.has(h.name))
+                    cfg.fleet.hosts.push(h);
+            for (const t of incoming.tokens)
+                if (!cfg.tokens.some(x => x.token === t.token))
+                    cfg.tokens.push(t);
+            saveConfig(cfg);
+            console.log('✔ merged (local host/port/domain and existing entries preserved)');
+        }
+        else {
+            saveConfig(incoming);
+            console.log(`✔ imported ${incoming.tokens.length} token(s) — replaced existing config`);
+            console.log('(restart the service or reconnect clients to apply)');
+        }
+        return;
+    }
+    // show
+    console.log(JSON.stringify(cfg, null, 2));
+}
+// ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------
 export async function main(argv) {
@@ -906,6 +1177,15 @@ export async function main(argv) {
         case 'upgrade':
             await cmdUpgrade(args);
             break;
+        case 'fleet':
+            cmdFleet(args);
+            break;
+        case 'webhook':
+            cmdWebhook(args);
+            break;
+        case 'config':
+            cmdConfig(args);
+            break;
         case 'version':
             console.log(PKG.version);
             break;