remote-access-mcp 2.4.4 → 3.0.1

package/dist/tools/shell.js

@@ -3,30 +3,8 @@ import { promisify } from 'node:util';
 import { z } from 'zod';
 import { assertToolPermitted } from '../core/policy.js';
 import { shellCommand, childEnv, isWindows } from '../core/platform.js';
-import { sshRun, buildRunCommand } from '../core/fleet.js';
 const exec = promisify(execFile);
 const MAX_OUTPUT = 60_000;
-function fleetHosts(ctx) {
-    return ctx.cfg.fleet?.hosts || [];
-}
-/**
- * Shared optional host parameter — ALWAYS present in the schema.
- *
- * If it were only advertised when a fleet exists, the SDK would silently
- * strip a client's host=<x> argument on a fleet-less gateway and the tool
- * would run the "remote" command LOCALLY on the gateway itself — a silent
- * security downgrade. Keeping the parameter in every schema means the
- * handler always sees it and can refuse with a clear error instead.
- */
-export function hostParam(ctx, names) {
-    const hosts = fleetHosts(ctx);
-    const hint = hosts.length
-        ? `Run on fleet machine${names ? ` (${names})` : ''}: ${hosts.map(h => h.name).join(', ')}. Omit for local.`
-        : 'Reserved for fleet hosts — none configured yet (see `ramcp fleet add`). Ignored locally.';
-    return {
-        host: z.string().optional().describe(hint),
-    };
-}
 // Shell injection surface: we run a shell by design (the tool IS a shell).
 // Guard rails: timeout, output cap, no TTY, cwd policy-checked.
 export function registerShellTools(server, ctx) {
@@ -37,30 +15,16 @@ export function registerShellTools(server, ctx) {
     });
     // ---- run_command -------------------------------------------------------
     server.registerTool('run_command', {
-        description: 'Execute a shell command (bash/sh on POSIX, PowerShell/cmd on Windows; sh on fleet hosts). Requires shell enabled. 120s default timeout.',
+        description: 'Execute a shell command (bash/sh on POSIX, PowerShell/cmd on Windows). Requires shell enabled. 120s default timeout.',
         inputSchema: {
             command: z.string().describe('Command line to run'),
             cwd: z.string().optional().describe('Working directory (policy-checked when local)'),
             timeout_ms: z.number().optional().default(120_000).describe('Timeout in ms (max 600000)'),
-            ...hostParam(ctx),
         },
-    }, async ({ command, cwd, host, timeout_ms }) => {
+    }, async ({ command, cwd, timeout_ms }) => {
         if (!ctx.token.shell_enabled) {
             return { content: [{ type: 'text', text: 'Shell execution is disabled for this token. Enable with `ramcp policy shell on`.' }], isError: true };
         }
-        // Fleet path: per-host allowlist + SSH, no local policy check (the
-        // command does not touch this machine).
-        // If the client names a host but the schema had no fleet to advertise
-        // (empty config), the SDK still may pass the arg through — a silent
-        // LOCAL fallback would run a "remote" command on the gateway itself.
-        if (host && !fleetHosts(ctx).length) {
-            return { content: [{ type: 'text', text: 'No fleet hosts are configured on this gateway. Add one with `ramcp fleet add` before using host parameters.' }], isError: true };
-        }
-        if (host) {
-            const h = (await import('../core/fleet.js')).assertCapability(fleetHosts(ctx), host, 'shell');
-            const { stdout } = await sshRun(h.host, h.port, buildRunCommand(command, undefined, timeout_ms), { timeoutMs: Math.min(timeout_ms, 600_000) });
-            return { content: [{ type: 'text', text: (stdout || '(no output)').slice(0, MAX_OUTPUT) }] };
-        }
         assertToolPermitted({ tool: 'run_command', scopes: ctx.token.scopes, readOnly: ctx.readOnly, policy: policy(), target: cwd });
         const timeout = Math.min(timeout_ms, 600_000);
         const { file, args } = shellCommand(command);
@@ -92,16 +56,9 @@ export function registerShellTools(server, ctx) {
     });
     // ---- process_list ---------------------------------------------------------
     server.registerTool('process_list', {
-        description: 'List running processes with CPU/memory. Local machine, or a fleet host with the shell group.',
-        inputSchema: {
-            ...hostParam(ctx),
-        },
-    }, async ({ host }) => {
-        if (host) {
-            const h = (await import('../core/fleet.js')).assertCapability(fleetHosts(ctx), host, 'shell');
-            const { stdout } = await sshRun(h.host, h.port, "ps axo pid,ppid,user,pcpu,pmem,comm --sort=-pcpu | head -80", { timeoutMs: 30_000 });
-            return { content: [{ type: 'text', text: stdout.slice(0, MAX_OUTPUT) }] };
-        }
+        description: 'List running processes with CPU/memory. Uses ps on POSIX, Get-Process on Windows.',
+        inputSchema: {},
+    }, async () => {
         assertToolPermitted({ tool: 'process_list', scopes: ctx.token.scopes, readOnly: ctx.readOnly });
         try {
             if (isWindows()) {

package/dist/tools/shell.js.map

@@ -1 +1 @@
-{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/tools/shell.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/tools/shell.ts"],"names":[],"mappings":"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"}

package/docs/ai/architecture.md

@@ -0,0 +1,106 @@
+# Architecture
+
+How the gateway is put together, for AI agents (and humans) who need to
+reason about it before changing it.
+
+## Module map
+
+```
+src/
+├── core/                    # framework-free building blocks
+│   ├── config.ts            # RamcpConfig + tokens; loads/migrates config.json
+│   ├── policy.ts            # path sandbox, scope groups, tool permission gate
+│   ├── audit.ts             # JSONL hash-chain audit log + redaction
+│   ├── crypto.ts            # timing-safe token compare
+│   ├── rate-limit.ts        # token-bucket per token
+│   ├── platform.ts          # OS detection, shells, dataDir, runtime state
+│   ├── tunnel.ts            # cloudflared quick-tunnel lifecycle
+│   ├── webhooks.ts          # fire-and-forget event notifications
+│   └── context.ts           # ConfigWatcher (hot-reload) + ToolContext
+├── server/
+│   ├── app.ts               # express app: auth, routes, sessions, MCP wiring
+│   ├── run.ts                # boot: listen, tunnel, runtime state, shutdown
+│   ├── sessions.ts           # stateful MCP session store (Claude dialect)
+│   └── legacy-sse.ts         # 2024-11-05 SSE transport + keepalive
+├── tools/                   # one file per suite, registered per request
+│   ├── filesystem.ts shell.ts system.ts http.ts git.ts sqlite.ts
+│   ├── logs.ts services.ts packages.ts schedule.ts security.ts
+│   ├── project.ts web.ts planning.ts ops.ts policy.ts index.ts
+└── cli/main.ts              # ramcp — all commands
+```
+
+## Request lifecycle (the part that matters most)
+
+One MCP POST travels this path:
+
+```
+nginx ─→ express
+        │  app.all('/<token>/sse') or ('/sse' + Bearer header)
+        ├─ authenticate(presented)                     [core/crypto + config]
+        │    reloads config if mtime changed  (hot-reload)
+        │    timing-safe compare against all tokens
+        ├─ rateLimited(token)?  → 429
+        ├─ normalizeAccept(req)                       [compat: never 406]
+        ├─ session routing:
+        │    Mcp-Session-Id present?
+        │      ├─ known session → its StreamableHTTP transport
+        │      └─ unknown → 404 (client restarts cleanly)
+        │    no session id:
+        │      ├─ initialize → new stateful session (id in response header)
+        │      └─ anything else → stateless throwaway transport
+        ├─ buildServerFor(token)                      [per request!]
+        │    McpServer + registerAllTools(server, ctx)
+        │    every tool handler wrapped: try/catch → audit → webhooks
+        └─ transport.handleRequest → tool executes → response
+```
+
+**Tools are re-registered for every request.** That is what makes policy
+edits (CLI or in-chat `allow_path`) apply on the next request with zero
+restarts. Do not "optimize" this by caching servers across requests — it
+would break hot-reload and per-token isolation.
+
+`ctx: ToolContext` carries `{ cfg, token, readOnly, persist, audit }`.
+The token record is looked up fresh per request, so a revoked token dies
+mid-conversation.
+
+## The three dialects (why server code looks redundant)
+
+| Client | Dialect | First request | Follow-ups |
+|---|---|---|---|
+| ChatGPT, Grok | Streamable, stateless | POST initialize (200 JSON/SSE) | fresh POST per call, ignores session id |
+| Claude (new SDK) | Streamable, stateful | POST initialize → **Mcp-Session-Id header back** | same id on every request; GET opens notification stream |
+| Claude (auto for `/sse` URLs) | Legacy SSE 2024-11-05 | **GET** stream → `event: endpoint` frame | POST to `/<token>/sse/messages?sessionId=…`, replies ride the stream |
+
+GET disambiguation: a GET **with** `Mcp-Session-Id` is a stateful client
+opening its notification stream; **without** it, it's a legacy client
+starting the handshake. Mixing these up sends `event: endpoint` to a
+stateful client, which aborts with `Unknown SSE event: endpoint` — that
+exact bug killed Claude connectors for a full day. Tests pin it
+(`tests/get-dispatch.test.ts`).
+
+## Data & state
+
+| File | Lives in | Written by | Lifetime |
+|---|---|---|---|
+| `config.json` | dataDir per OS | CLI, policy tools | persistent; 0600 |
+| `audit.jsonl` | dataDir | audit wrapper | append-only, hash-chained |
+| `runtime.json` | dataDir | gateway boot | ephemeral — pid-checked, cleared on exit |
+| `schedule.json`, `plans.json`, `snapshots.json`, `snapshots/` | dataDir | tools | persistent |
+
+The tunnel URL **only** ever goes to `runtime.json`. Writing it to config
+would clobber a server's real `public_host` the moment someone ran
+`ramcp tunnel` on it (that happened; ADR-003).
+
+## Cross-platform layer
+
+`core/platform.ts` normalizes: which shell (`bash -lc` / `pwsh` / `cmd.exe`),
+where data lives, how paths compare (case-insensitive on Win/mac),
+`which()`, `hasSystemd()`. Tools call `shellCommand()` instead of hardcoding
+bash — Windows compat lives or dies here.
+
+## Service installers
+
+`ramcp service install` writes a systemd unit (Linux), a launchd plist
+(macOS, per-user, no sudo), or a schtasks entry (Windows, logon trigger).
+The unit points at `dist/server/run.js` under the *global npm* install path —
+`ramcp upgrade` rewrites nothing but must restart the right manager per OS.

package/docs/ai/decisions.md

@@ -0,0 +1,141 @@
+# Decision Records (ADR)
+
+Short, dated records of *why* the code is the way it is. Each one encodes a
+lesson that cost real debugging time. When one of these decisions blocks
+something you're trying to do, don't quietly route around it — write a new
+record superseding the old one.
+
+---
+
+## ADR-001 — Express + per-request McpServer builds
+**Status:** accepted · **Date:** 2026-08-30
+
+The gateway builds a **fresh `McpServer` with all tools re-registered for
+every request** (stateless dialect) or per session (stateful).
+
+Why: (a) policy mutations — CLI, config hot-reload, or in-chat
+`allow_path` — must apply on the *next* request, not after a restart;
+(b) per-request builds bind the calling token's record into the handlers,
+so revocation/rotation takes effect mid-conversation; (c) the MCP SDK
+guidance for our compat matrix is one transport per request anyway.
+
+Cost: registration overhead per request (~1ms measured). Accepted.
+
+---
+
+## ADR-002 — Dual auth: Bearer header *and* token-in-URL
+**Status:** accepted · **Date:** 2026-08-30
+
+ChatGPT custom connectors cannot set custom headers, so the token rides in
+the URL path (`/<token>/mcp`). Everything else uses `Authorization: Bearer`.
+Both resolve through the same timing-safe comparison.
+
+---
+
+## ADR-003 — Tunnel URL lives in runtime.json, never config
+**Status:** accepted · **Date:** 2026-08-31
+
+Quick-tunnel URLs are valid only while the gateway process runs. The first
+implementation persisted the URL into `config.json`'s `public_host` — and
+one test run on the production server **clobbered the real domain**, after
+which `ramcp url` printed a dead trycloudflare URL to the user.
+
+Fix: `runtime.json` = {pid, tunnel_url, host, port, started}, written on
+boot, pid-checked on read (stale → ignored), cleared on exit including
+`process.on('exit')` for Windows service stops. `ramcp url` prefers the
+live tunnel. Pinned by `tests/runtime-state.test.ts`.
+
+---
+
+## ADR-004 — Pure ESM, no require() in src/
+**Status:** accepted · **Date:** 2026-08-31
+
+A `require()` in `src/cli/main.ts` passed the entire test suite (vitest's
+CJS interop tolerates it) and **crash-looped production** within a second
+of every systemd start. Diagnosis needed a boot test that runs the built
+output under plain node — which now exists (`tests/boot.test.ts`) and
+should be the pattern for anything touching startup paths.
+
+---
+
+## ADR-005 — Audit log is JSONL, not better-sqlite3
+**Status:** accepted · **Date:** 2026-08-31
+
+The original audit used better-sqlite3. In the stateless request loop its
+native `Statement` destructor aborted Node with SIGABRT (~8 requests in,
+native stack trace pointing at `Statement::~Statement`). Root cause:
+better-sqlite3's teardown hooks racing the SDK's per-request transports.
+
+The rewrite is a plain append + fsync JSONL file with the same hash chain,
+zero native code in the dependency tree, and a regression test that runs
+30 full stateless cycles with audit writes (`tests/crash-regression.test.ts`).
+sqlite_query/sqlite_schema keep better-sqlite3 for *user* databases (open
+per call, closed in-finally) — that usage never crashed.
+
+---
+
+## ADR-006 — Hermetic tests: build gateway state explicitly
+**Status:** accepted · **Date:** 2026-08-31
+
+Tests that called `buildApp()` without seeding state read the **host's real
+config**. It worked until the production server deployed with
+`mcp_path: /sse` — then 10 tests failed only-when-the-service-was-running.
+All suites now construct explicit `GatewayState` objects (see any
+`tests/*.test.ts` `beforeAll`).
+
+---
+
+## ADR-007 — Fleet mode removed (single machine by design)
+**Status:** accepted · **Date:** 2026-09-01 · **Supersedes:** the v2.4.0 fleet feature
+
+Fleet (SSH to N machines, per-host tool allowlists, 14 remote-capable
+tools, `ramcp fleet` CLI) was fully implemented, tested (including live-SSH
+and fake-ssh suites), published as 2.4.x — and then **removed entirely** in
+3.0.0 by owner decision: the product is one gateway per machine; multi-
+server orchestration is not the problem this project solves.
+
+What the removal kept: webhooks and `config export/import` (independent
+value). What it took with it: `src/core/fleet.ts`, `src/tools/fleet.ts`,
+the `host` parameter on 14 tools, fleet CLI/scopes/config, three test
+files. `ramcp fleet` is now an unknown command (pinned by a test).
+
+---
+
+## ADR-008 — Never omit schema parameters conditionally
+**Status:** accepted · **Date:** 2026-09-01 · **Learned from:** the fleet era
+
+When a tool's schema includes a parameter only under some conditions
+(e.g., `host` only when fleet hosts exist), the MCP SDK **silently strips**
+client arguments that aren't in the current schema. Consequence observed on
+production: a client sending `run_command {command, host: "ghost"}$` to a
+fleet-less gateway had `host` dropped and the **"remote" command executed
+locally on the gateway** — a silent security downgrade, not an error.
+
+Rule: parameters that gate security-relevant behavior stay in the schema
+always; the *handler* refuses with a clear error when the capability is
+absent. (Superseded by ADR-007 removing the host param outright, but the
+rule stands for anything like it.)
+
+---
+
+## ADR-009 — SSE-framed responses by default
+**Status:** accepted · **Date:** 2026-08-31
+
+`enableJsonResponse: true` (plain-JSON replies) works for ChatGPT/Grok but
+Claude's connector read a valid 200 initialize reply and silently
+abandoned the connection. SSE framing (`event: message\ndata: …`,
+`content-type: text/event-stream`) is the reference behavior and the only
+framing observed to satisfy every dialect we've tested. The wire-log proxy
+session that proved this is described in transport-compatibility.md.
+
+---
+
+## ADR-010 — execFile does not support the `input` option
+**Status:** accepted · **Date:** 2026-09-01
+
+`promisify(execFile)({... input})` never closes the child's stdin — the
+call hangs until timeout (fleet's remote file writes hung 5s→timeout every
+time before this was understood; a minimal `bash -c cat` repro confirmed
+it's the API, not our code). Pattern: when stdin must be piped, use
+`spawn()` and end the stream manually. The helper shape lives in git
+history (core/fleet.ts) if ever needed again.

package/docs/ai/security-model.md

@@ -0,0 +1,114 @@
+# Security Model
+
+The gateway hands an AI the keys to a machine. Every design choice below
+exists to make that survivable. Read this before touching anything in the
+auth, policy, or audit paths.
+
+## Threat model, plainly
+
+The token holder is **trusted** (that's you). The threats are:
+1. **Token leakage** → mitigate: no secrets in logs/audit (fingerprints only),
+   tight file perms, rotate in one command.
+2. **The AI itself** going somewhere you didn't intend → mitigate: path
+   sandbox, scope groups, read-only mode, shell opt-in, protected
+   services/packages/processes, SSRF walls.
+3. **A hostile chat platform or MITM** → mitigate: TLS at the edge
+   (Cloudflare/Let's Encrypt), loopback-only bind, timing-safe compares.
+4. **Tampering with history** after an incident → the hash chain.
+
+## Layer 1 — Network
+
+- Binds `127.0.0.1` only. Nothing listens publicly but nginx/Cloudflare.
+- `ramcp tunnel` (laptops) publishes a temporary https URL via cloudflared;
+  the URL dies with the process, is tracked in pid-checked `runtime.json`,
+  and self-verifies reachability before promising anything.
+
+## Layer 2 — Authentication
+
+- Two equivalent forms: `Authorization: Bearer <token>` or the token in the
+  URL path (`/<token>/mcp`) — the latter because ChatGPT connectors cannot
+  set custom headers.
+- Compare is **timing-safe** with a length pre-filter (`core/crypto.ts`).
+- Token records: expiry (ISO date), per-token rate limit (token bucket,
+  burst = rpm/4), revocation is config write + hot reload — a rotated token
+  dies mid-conversation.
+- Sessions (stateful dialect) are **bound to the token fingerprint** that
+  opened them: presenting another token with a stolen session id → 403.
+
+## Layer 3 — Authorization (per token)
+
+`assertToolPermitted()` enforces, in order:
+
+1. **scopes** — empty = every group; else the tool must belong to a listed
+   group. Group map is static in `core/policy.ts` (TOOL_SCOPES).
+2. **read-only** — per-token or global `ramcp policy readonly on` refuses
+   every entry of `MUTATING_TOOLS`.
+3. **path sandbox** — only if the tool passes a `target`:
+
+```
+resolveReal(path)               # realpathSync; for missing paths, the deepest
+                                # existing ancestor is resolved and the
+                                # remainder re-attached → symlink escapes collapse
+  → in denied_paths?  → refuse  # deny always wins, even inside an allowed root
+  → in allowed_paths? → allow
+  → else              → refuse  # empty allow-list denies everything
+```
+
+Path comparison is case-insensitive on Windows/macOS, separators normalized
+(`core/platform.ts`).
+
+**In-chat policy tools can only widen their own token's sandbox** — they
+mutate the calling token's record, never another token's.
+
+## Layer 4 — Tool-level guards
+
+| Guard | Tool(s) | Behavior |
+|---|---|---|
+| Shell opt-in | run_command, kill_process, schedule | refuse unless token `shell_enabled` |
+| Protected pids | kill_process | gateway pid, ppid, PID 1 |
+| SSRF wall | http_request, web_fetch, port_check | 127/8, 10/8, 172.16/12, 192.168/16, 169.254/16 (cloud metadata), 0/8, ::1, fc00::/7, fe80::/10, IPv4-mapped v6, metadata hostnames |
+| Git arg whitelist | git | ~45 known verbs; `--upload-pack`/`--exec=` refused; no `;&|`${}`<>` in args |
+| SQL single-statement | sqlite_query | one statement; ATTACH/DETACH refused (escape the sandbox via another db file) |
+| Unit-name regex | service_*, journal | `[A-Za-z0-9@._-]+` only |
+| Protected units | service_action | ssh/sshd/systemd/networkd/dbus/gateway itself/major Windows services |
+| Protected packages | package_remove | nodejs/npm/nginx/openssh/systemd/remote-access-mcp |
+| Secret masking | secret_scan | matches reported as file:line + type only — never the secret |
+| Secret redaction | environment_inspect | pass/secret/token/key/auth/credential vars → `[MASKED]` |
+| Schedule floor | schedule_command | ≥60s recurrence; one-shot allowed |
+
+## Layer 5 — Accounting
+
+- **Audit log** (`audit.jsonl`): one line per tool invocation — ts, token
+  **fingerprint** (sha256-16, never the secret), tool, redacted args,
+  ok/is_error, duration. Each line's `hash = sha256(prev_hash + fields)` →
+  deleting or editing any line breaks every hash after it.
+  `ramcp audit chain` walks it; exit code 2 on tamper. Args are redacted
+  (`pass|secret|token|key|auth` keys → `[REDACTED]`, values capped at 300ch).
+- **Webhooks** mirror tool.error/tool.success out to URLs you own —
+  fire-and-forget, 5s timeout, identical events deduped within 10s.
+
+## Layer 6 — The audit wrapper itself
+
+`buildServerFor()` monkey-patches `server.registerTool` so **every** handler
+is wrapped: errors are caught and converted to `isError` results (a tool
+crash must never 500 the transport), then audit + webhooks fire. This is
+also the single choke point where a future change would accidentally bypass
+accounting — keep it that way.
+
+## Things we refuse to add (non-negotiable)
+
+- No `require()` in `src/` (pure ESM; one slip crash-looped production).
+- No native modules in the request path (better-sqlite3 SIGABRT'd the
+  stateless loop — audit is plain JSONL now).
+- No dynamic schema omission (the SDK silently drops unknown client args;
+  that once executed a "remote" command locally — ADR-008).
+- No second machine (fleet removed by owner decision — ADR-007).
+
+## If you're adding a tool
+
+Checklist: (1) pick/extend a scope group; (2) decide mutating or read-only
+and add to MUTATING_TOOLS if mutating; (3) accept `path`-style targets →
+pass them as `target:` to the gate; (4) think about injection (quotes,
+metacharacters, second-order effects) and add a guard, not a regex hope;
+(5) never log secrets; the audit wrapper redacts args but your *output* is
+on you.

package/docs/ai/tools-and-cli.md

@@ -0,0 +1,152 @@
+# Tools & CLI Reference
+
+Complete inventory of what the gateway exposes, as of v3.0.0.
+Counts: **44 tools / 17 suites**, **17 CLI commands**.
+
+Every tool handler runs inside the audit wrapper (app.ts): execution is
+timed, arguments redacted, outcome appended to the hash chain, webhooks
+notified. A thrown `PolicyError`/`ScopeError` becomes a normal `isError`
+result — never a 500.
+
+## Permission gate (read this first)
+
+`assertToolPermitted({ tool, scopes, readOnly, policy?, target? })` in
+`core/policy.ts` — three checks, in order:
+
+1. **scopes** — token's `scopes[]` empty = all groups; otherwise tool must
+   be in a listed group (group map in `TOOL_SCOPES`).
+2. **readOnly** — token or global read-only refuses `MUTATING_TOOLS`.
+3. **policy paths** — if `target` given: resolveReal() (symlinks collapsed,
+   deepest existing ancestor for not-yet-existing files) → deny-list wins →
+   must be inside an allow-list entry.
+
+Scope groups: `filesystem shell system http git sqlite policy logs services
+packages schedule security project planning formatting documents ops web`.
+(`ramcp scopes` prints them with member tools.)
+
+## Suites
+
+### filesystem (7) — policy-gated on every path
+| Tool | Notable |
+|---|---|
+| `list_directory` | 2000-entry cap |
+| `read_file` | `offset`/`limit` line windows |
+| `write_file` | mkdir option |
+| `edit_file` | exact-text replace, `all` flag |
+| `delete_path` | rm -rf — destructive, policy-gated |
+| `search_code` | recursive regex, skips .git/node_modules |
+| `file_info` | stat essentials |
+
+### shell (3) — behind token `shell_enabled`
+| Tool | Notable |
+|---|---|
+| `run_command` | platform shell via `shellCommand()`; ≤600s; 60KB output cap; cwd policy-gated |
+| `process_list` | ps (POSIX) / Get-Process (Win) |
+| `kill_process` | refuses gateway pid, ppid, PID 1 |
+
+### system (3)
+`system_info` · `disk_usage` (df / Get-Volume) · `network_interfaces` — all
+cross-platform, no gates (read-only host facts).
+
+### http (3) — SSRF-guarded
+`http_request` · `port_check` · `web_fetch` — loopback/private/link-local
+(169.254.0.0/16 incl. cloud metadata) refused; IPv4-mapped IPv6 too.
+
+### git (1)
+`git` — args validated: verb must match a whitelist (~45 verbs, no
+`upload-pack`/`exec=`), no shell metacharacters in any arg; `repo_path`
+policy-gated.
+
+### sqlite (2) — policy-gated on db_path
+`sqlite_query` — single statement only, ATTACH/DETACH refused, SELECT/WITH/
+PRAGMA/EXPLAIN return rows, others report changes. `sqlite_schema`.
+
+### logs (3) — policy-gated paths
+`tail_logs` (1MB tail read) · `search_logs` (regex + context) · `journal`
+(unit-name regex validated; journalctl / mac `log show` / Get-WinEvent).
+
+### services (2)
+`service_status` · `service_action` — `PROTECTED_UNITS` regex refuses ssh,
+the gateway itself, dbus/networkd/WinDefend etc. Unit names regex-validated.
+
+### packages (3)
+`package_list` / `package_install` / `package_remove` — manager auto-detected
+(apt / brew / winget / choco / npm); `package_remove` refuses
+nodejs/npm/nginx/openssh/systemd/remote-access-mcp.
+
+### schedule (3)
+`schedule_command` (one-shot ISO time or recurring ≥60s; requires shell
+token) · `list_scheduled_tasks` · `cancel_scheduled_task`. File-backed
+(`schedule.json`), a 30s in-process ticker executes them.
+
+### security (2)
+`secret_scan` — 10 credential patterns (keys, AWS, GitHub, Slack, npm,
+bearer, connection-string passwords); **output is masked**, only
+file:line + type. `port_scan_local` — ss / lsof / Get-NetTCPConnection.
+
+### project (2)
+`analyze_project` (files/LOC/manifests/entry points, depth-capped walk) ·
+`project_health_check` (git dirty, README presence, TODO density).
+
+### planning (4)
+`create_task_plan` · `task_status` (mark steps done) · `workspace_snapshot`
+(content-addressed file copies) · `rollback_changes` (atomic restore).
+Snapshot/rollback are in `MUTATING_TOOLS`.
+
+### web (1)
+`web_fetch` — SSRF-guarded public fetch, UA-tagged, size-capped.
+
+### ops (2)
+`environment_inspect` — env vars, secrets masked, long values truncated.
+`nginx_inspect` — read-only; site names regex-validated (no traversal);
+`nginx -T` summary or per-site config.
+
+### policy (4) — token manages only its own sandbox
+`list_allowed_paths` · `allow_path` · `deny_path` · `shell_enabled`. Mutations
+persist via `saveConfig` and hot-reload; they cannot touch other tokens.
+
+## CLI (`ramcp`)
+
+| Command | Subcommands / flags | Notes |
+|---|---|---|
+| `init` | `--paths a,b` | creates config + default token; re-run safe |
+| `start` | `--tunnel --read-only --host --port` | foreground |
+| `tunnel` | — | gateway + public URL; runtime state; self-checks reachability |
+| `url` | `[name]` | live tunnel URL wins, else public_host/local |
+| `token` | `add --name --paths --deny --scopes --shell --read-only --rpm --expires` · `list [--json]` · `show [--full]` · `rotate` · `revoke` | last token can't be revoked |
+| `policy` | `allow <p…>` · `deny <p…>` · `shell on/off` · `scopes <groups|all>` (all `--token`) · `readonly on/off` (global) | multi-path, space-separated |
+| `scopes` | — | group → tools map |
+| `audit` | `--tool --since --limit --json` · `chain` | chain verifies hash chain, exit 2 on tamper |
+| `doctor` | — | platform, config, tokens, gateway, service, tunnel, public, audit |
+| `service` | `install [--domain] [--tunnel] [--dry-run]` · `uninstall` · `logs [-f]` · `status` | systemd / launchd / schtasks by OS |
+| `schedule` | `list [--json]` | |
+| `upgrade` | `--dry-run` | npm self-update + right restart per OS |
+| `status` | — | incl. live runtime state |
+| `version` | — | |
+| `config` | `show` · `export [--out]` · `import FILE [--merge]` | export 0600, contains live tokens; merge preserves local identity |
+| `webhook` | `add --url --events` · `list` · `on/off URL` · `remove URL` | events: `tool.error`, `tool.success`, `*` |
+| ~~`fleet`~~ | — | **removed in v3.0.0** — unknown command now |
+
+### Config file shape (v3)
+
+```jsonc
+{
+  "host": "127.0.0.1", "port": 8765, "public_host": "mcp.example.com",
+  "mcp_path": "/mcp", "mcp_path_aliases": ["/sse"],
+  "log_level": "info",
+  "audit": { "enabled": true, "db_path": "…/audit.jsonl" },
+  "read_only": false,
+  "tunnel": { "provider": "cloudflare", "auto_start": false },
+  "webhooks": [{ "url": "…", "events": ["tool.error"], "enabled": true }],
+  "tokens": [{
+    "id": "…", "name": "default", "token": "…", "created": "ISO",
+    "expires": "ISO?", "scopes": [], "read_only": false,
+    "max_requests_per_minute": 60?, "shell_enabled": true,
+    "allowed_paths": ["…"], "denied_paths": []
+  }]
+}
+```
+
+Env overrides (tests, minimal deploys): `RAMCP_TOKEN RAMCP_HOST RAMCP_PORT
+RAMCP_PUBLIC_HOST RAMCP_SHELL RAMCP_ALLOWED_PATHS RAMCP_DENIED_PATHS`
+(legacy `DANA_*` still honored). `SSH_BIN` existed for fleet tests — gone.