ssh-mcp-pro 1.5.0 → 1.6.0

package/docs/adding-a-device.md

@@ -72,12 +72,37 @@ returned token with the installer in Step 2 or the returned npm commands.
 ## Step 2 — Run the bootstrap on the new device
 
 The Linux/Windows bootstrap installs the package, enrolls the machine, and
-registers startup so the agent reconnects after restarts. It needs Node
-22.22+ or 24+. The dashboard-generated command is the shortest path; the
-manual commands below are alternatives if you already have a one-time token.
+registers startup so the agent reconnects after restarts. On Linux/WSL,
+the user-mode installer automatically installs verified **Node 26 LTS** into
+the user's private directory if Node.js/npm is missing or too old. It checks
+the official Node.js release signature and SHA-256 checksum before using the
+binary; no sudo, system-wide Node changes or additional commands are needed.
+System-wide Linux services still require a trusted system-installed Node
+runtime. On Windows, if Node.js is missing, the installer attempts to install
+the official Active LTS through Windows Package Manager (WinGet). The
+dashboard-generated command is the shortest path; the manual commands below
+are alternatives if you already have a one-time token.
 
 ### Linux / WSL
 
+**Same-device browser setup (recommended for Linux/WSL with a browser):**
+
+From the authenticated dashboard's **Add Device** tab, copy the
+**Linux / WSL: Set up with your browser** command and run it in the
+device's own terminal. It installs a verified user-local Node LTS if needed,
+installs the agent and prints an HTTPS approval link. Open that link in a
+browser on the **same device** (including a Windows browser that can reach
+WSL loopback), sign in, choose the initial policy and click **Approve This
+Device**. The one-time enrollment token is handed directly to the agent's
+temporary `127.0.0.1` listener; it is never copied to a chat, terminal
+argument or browser URL. The listener accepts only the control-plane origin
+plus a random one-time link challenge and expires after 10 minutes. Browser
+privacy/localhost network protections must allow the connection. If the
+browser is on another machine, use the existing manual command instead.
+
+For **headless or remote-only devices**, the existing manually generated
+one-time token and installation command remain supported:
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/oaslananka/ssh-mcp-pro/main/scripts/install-agent.sh -o install-agent.sh
 bash install-agent.sh \
@@ -86,20 +111,73 @@ bash install-agent.sh \
   --alias office-pc
 ```
 
-This creates a **user** systemd service and enables linger so it survives
-logout and starts at boot. Pass `--system` (with `sudo`) to install a
-system-wide service instead.
+This creates a **user** systemd service and enables linger. On a normal
+Linux installation, that lets the agent survive logout and start with the
+systemd user manager at boot. **WSL is different:** Microsoft documents that
+systemd services do **not** keep a WSL instance alive. Windows can shut down
+an idle WSL instance even when the service is enabled and `Linger=yes`.
+For an always-on agent on a Windows PC, use the **native Windows installer**
+below instead. Only use WSL as a persistent agent host if you deliberately
+configure and verify its Windows-side startup/lifetime behavior; the Linux
+installer does not silently create a Windows task or disable WSL idling.
+See [Microsoft's WSL systemd documentation](https://learn.microsoft.com/en-us/windows/wsl/systemd).
+
+If enabling linger is denied, the installer reports **incomplete setup**
+instead of claiming success: even on ordinary Linux, the running agent may
+disconnect when the user logs out. Ask an administrator to run
+`sudo loginctl enable-linger <linux-username>`, then verify
+`loginctl show-user <linux-username> -p Linger` reports `Linger=yes`.
+This repair does **not** require a new enrollment token. Pass `--system`
+(with `sudo`) to install a system-wide service instead.
 
 ### Windows (PowerShell)
 
 ```powershell
-irm https://raw.githubusercontent.com/oaslananka/ssh-mcp-pro/main/scripts/install-agent.ps1 -OutFile install-agent.ps1
-./install-agent.ps1 -Server https://your-control-plane.example.com -Token <one-time-token> -Alias office-pc
+Invoke-RestMethod https://raw.githubusercontent.com/oaslananka/ssh-mcp-pro/main/scripts/install-agent.ps1 -OutFile install-agent.ps1
+& ([scriptblock]::Create((Get-Content -LiteralPath ./install-agent.ps1 -Raw))) -Server 'https://your-control-plane.example.com' -Token '<one-time-token>' -Alias 'office-pc'
 ```
 
 This registers a Scheduled Task that runs the agent at logon and restarts it
-on failure. For a fully headless host that must run before any user logs in,
-run the agent under a service manager such as NSSM instead.
+on failure. The dashboard's Windows one-liner is preferred: it downloads from
+your authenticated HTTPS control plane and uses an in-memory script block,
+so no machine-wide PowerShell execution-policy change is needed. The
+installer invokes npm and the agent through their `.cmd` wrappers to avoid
+blocked npm/agent `.ps1` shims. Review the installer source and only use a
+trusted server. If Node.js is missing, WinGet will download and install
+`OpenJS.NodeJS.LTS` from its official `winget` source, potentially prompting
+for Windows administrator approval (UAC). Nothing bypasses that prompt. The
+installer refreshes its own PATH and continues automatically when Node is
+available. If WinGet is unavailable or the user declines installation, the
+script exits with actionable guidance to install Node LTS from
+https://nodejs.org/en/download and rerun the command. An *outdated* Windows Node
+installation is not silently upgraded. On Linux/WSL, the user-scope fallback
+also requires curl, tar, SHA-256 and GPG signature-verification tools; it
+reports missing prerequisites rather than running unverified downloads.
+The Node runtime and npm-installed agent are kept under
+~/.local/share/ssh-mcp-pro/, outside system locations.
+
+### Repair an existing Windows agent task
+
+Earlier Windows installations may still have Task Scheduler's default 72-hour
+process limit even though new installations now set unlimited runtime. If your
+existing agent disconnects after a long uptime, open **administrator PowerShell**
+and approve the normal UAC prompt. Run this **without re-enrolling**:
+
+```powershell
+Invoke-RestMethod https://raw.githubusercontent.com/oaslananka/ssh-mcp-pro/main/scripts/repair-agent-task.ps1 -OutFile repair-agent-task.ps1
+& ([scriptblock]::Create((Get-Content -LiteralPath ./repair-agent-task.ps1 -Raw)))
+```
+
+The repair does not require a new enrollment token, does not reinstall Node or
+npm, and does not restart the running agent. It verifies that the task runs
+`ssh-mcp-pro-agent.cmd run`, then changes only `ExecutionTimeLimit` from
+`PT72H` to `PT0S`. If the task already has unlimited runtime, it succeeds
+without changes. If permissions are insufficient or the task looks unfamiliar,
+it stops and reports an error instead of bypassing UAC or overwriting settings.
+The existing restart-on-failure policy is preserved.
+
+For a fully headless host that must run before any user logs in, run the agent
+under a service manager such as NSSM instead.
 
 ## Step 3 — Verify
 
@@ -114,6 +192,100 @@ enrollment, **not** live connectivity. In the dashboard, open **Enrolled
 Devices** and verify the device reports **Live Online**. The audit log
 should contain `enrollment_token_created` and `agent_connected`.
 
+## Find files after connecting a device
+
+Once a device is **Live Online** with an `operations` or explicitly
+file-read-enabled policy, you can ask your MCP client:
+
+> Find JSON configuration files on my connected device.
+
+The hosted `file_search` tool needs the device alias and a `name_pattern`
+such as `*.json` or `config`. You do not need to know the complete file path.
+It searches the local policy's allowed folders by default, or you can specify
+an allowed `root_path` to narrow the search. Results contain file paths only,
+not file contents; use `file_read` to inspect a selected file afterward.
+
+Searches default to depth 3 and up to 20 matches. At most 2,000 entries,
+128 directories, depth 5 and 50 matches are considered per invocation.
+Hidden files are excluded unless requested. The response marks incomplete
+searches as truncated; narrow the root or pattern for more precise results.
+The agent skips symbolic links and does not search paths denied by its local
+policy. Read-only profiles do not gain file access automatically.
+
+## Find a setting inside a file without knowing its location
+
+When `files.read` is enabled, you can ask your AI client:
+
+> On my connected device, find which configuration file contains
+> `mode=advanced`, and show me where it appears.
+
+The hosted `file_content_search` tool accepts `agent_id_or_alias` and a
+literal `query`. It searches locally allowed folders, returning one matching
+line number and a short snippet **per file**; it never edits files. You can
+optionally restrict the filename with `name_pattern` (e.g. `*.ini`) or an
+allowed `root_path`. The query is plain text, **not a regular expression**,
+and is case-insensitive by default unless `case_sensitive: true` is passed.
+
+One search examines at most 128 files of up to 128 KiB each, traverses at
+most 128 directories and 2,000 entries, and returns at most 50 matches
+(default 20). Depth defaults to 3 (maximum 5). Binary/invalid UTF-8 and
+oversized files are skipped, hidden paths are excluded unless explicitly
+requested, and symbolic links are not followed. A `truncated: true` result
+means the scan or output limit was reached: narrow the filename/root and
+search again. Long files can instead be inspected with paged `file_read`.
+
+The control plane masks the search phrase in stored action metadata.
+Matched snippets are still sent to the authenticated AI client, so avoid
+requesting secrets or credentials unless they are genuinely needed.
+
+## Preview and apply one precise file edit
+
+On an authorized device, clients with **both** `files.read` and
+`files.write` can call `file_replace` instead of overwriting a whole file.
+Give it an existing path, an exact `old_text` snippet and a `new_text` value.
+The default `dry_run: true` returns a short diff and `before_sha256`
+**without changing the file**.
+
+To apply, call the same tool with `dry_run: false` and
+`expected_sha256` equal to the preview's `before_sha256`. It replaces
+**exactly one** occurrence, stages the new content as a temporary file,
+checks the file hash again just before replacing the original, and reports
+`FILE_CONFLICT` if it has changed. Reinspect/repreview after a conflict.
+This is a best-effort optimistic stale-write check, **not** an atomic
+compare-and-swap guarantee against concurrent external writes.
+
+The agent refuses ambiguous/missing matches, non-UTF-8 text, files over
+1 MiB and edits that exceed its output limits. Files outside the local
+allowlist and read-only profiles cannot use this tool. Normal
+`file_write` remains unchanged for full-file edits.
+
+## Follow a long-running command without keeping a terminal open
+
+When the agent's `shell.exec` capability is enabled, you can ask an AI
+client: *"Start the test runner on my enrolled device, show its output, send
+input if it asks, and stop it when I tell you."* The agent exposes four
+tools that operate on a **user-owned process session**:
+
+1. `process_start`: provide `agent_id_or_alias` and `command`, optionally
+   `cwd` and `max_runtime_seconds` (1–600; default 300). Save the returned
+   `process_id`; the command runs on that device, not on the cloud server.
+2. `process_read`: supply the same agent and process ID, plus a `cursor`
+   (start at 0). It returns status, exit code, a bounded list of stdout/stderr
+   chunks, and `next_cursor` for the next read.
+3. `process_input`: send short stdin text or close stdin. Do not type
+   passwords/tokens into shell commands or client conversations.
+4. `process_stop`: terminate the process and its descendants when finished.
+
+Sessions do not survive agent restart, disconnection or permission revocation.
+A device supports up to four simultaneous managed processes; runtime and
+output memory are bounded. When output exceeds the local 64 KiB ring buffer,
+`dropped_before_cursor` indicates earlier content that can no longer be
+retrieved. Finished process results are retained for at most two minutes.
+
+The control plane masks managed command and stdin payloads in durable action
+metadata; the AI client may still receive and display command output. This
+tool does not elevate shell permissions or bypass the local device policy.
+
 ## Changing a policy later
 
 Capabilities are server-authoritative and pushed live to a connected agent —
@@ -144,6 +316,10 @@ restart is required.
   (`systemctl --user status ssh-mcp-pro-agent` on Linux, the Scheduled Task on
   Windows) and that the device can reach the control plane URL over HTTPS.
 - **Enrollment fails with an expired token**: tokens are single-use and
-  short-lived. Create a fresh one and retry.
+  short-lived. An unused, never-connected pending device is removed after its
+  token expires, by the control plane's existing periodic cleanup (once per
+  minute). You can then generate a fresh command with the same alias; if the
+  alias is still reserved, refresh the device list after the next cleanup.
+  Already enrolled or revoked devices and the security audit remain intact.
 - **WebSocket error on start**: confirm Node 22.22+ or 24+, DNS/TLS
   connectivity to the configured server, and that the agent has not been revoked.

package/docs/backup-restore-verification.md

@@ -0,0 +1,45 @@
+# Offline encrypted backup restore verification
+
+Use this **before** authorizing a hosted release or rollback. It does **not**
+change the running service or access live data. Backup existence, filename,
+size or encryption header alone does not prove recoverability.
+
+## Independent recovery host
+
+On an authorized isolated Linux host with Python 3, age and OpenSSL, obtain a
+**separately stored encrypted backup** and its matching age identity using
+your approved secure recovery process. Never paste the identity/private key
+into chat, support requests, CI logs or a Git repository. Store the identity
+as a private file (for example, file permissions 0600).
+
+From a clean repository checkout, run:
+
+~~~bash
+python3 scripts/verify-encrypted-backup.py \
+  --archive /secure/offsite/ssh-mcp-pro-backup.tar.gz.age \
+  --identity /secure/offsite/age-identity.txt
+~~~
+
+Both .tar.age and .tar.gz.age formats are supported. The verifier requires a
+consistent SQLite sshautomator.db including the users, agents and audit_events
+tables, and matching Ed25519 PEM key pairs in control-plane-ed25519.json and
+jwt-ed25519.json. It validates database integrity and foreign keys, and
+validates each signing-key pair using OpenSSL. The archive is **never**
+extracted directly to an embedded path: symbolic links, hardlinks and
+parent-path traversal are rejected.
+
+Success prints a small JSON status without database content or key material.
+Any failure exits nonzero with a generic error code. Plaintext stays only in
+a private temporary directory which is deleted automatically. Live files are
+never overwritten.
+
+**Release acceptance remains incomplete** until the backup is fresh and truly
+offsite, its decryption identity is independently recoverable, and a controlled
+isolated restore proves application startup, signed agent actions, OAuth
+continuity, and rollback. Synthetic fixture tests are not production approval.
+
+Run synthetic tests (no production credentials or data):
+
+~~~bash
+python3 test/unit/backup_restore_verifier_test.py
+~~~

package/docs/coolify.md

@@ -27,3 +27,12 @@ GITHUB_CALLBACK_URL=https://ssh-mcp-pro.oaslananka.dev/oauth/callback/github
 Dashboard login callback URLs additionally use `/auth/callback/google` and `/auth/callback/github`; register both with the relevant OAuth providers. Keep authentication allowlists configured as appropriate. Do not enable anonymous access as a workaround.
 
 Before deployment verify local OAuth login, dashboard and MCP flow. After deployment check health, login callbacks, device connectivity, and persistent state across a controlled restart. Do not run the SSH test fixture service in production.
+
+## Encrypted backup recovery gate
+
+Before changing the hosted image, validate a fresh offsite encrypted SQLite
+and signing-key backup on an independent recovery host. Follow
+[offline backup restore verification](backup-restore-verification.md).
+Passing offline integrity checks alone is **not** production restore or
+rollback acceptance: demonstrate a controlled service startup and signed
+agent/client action before authorizing the release.

package/docs/development/local-setup.md

@@ -9,7 +9,7 @@ it adds the one-command shortcuts.
 ```bash
 git clone https://github.com/oaslananka/ssh-mcp-pro.git
 cd ssh-mcp-pro
-task install   # or: corepack enable && corepack prepare pnpm@11.28.10 --activate && pnpm install --frozen-lockfile
+task install   # or: corepack enable && corepack prepare pnpm@11.28.11 --activate && pnpm install --frozen-lockfile
 task verify    # lint + format:check + typecheck + test + build
 ```
 

package/docs/reference/compatibility.md

@@ -13,7 +13,7 @@ LTS line). This is expected, not an oversight.
 
 ## Package manager
 
-pnpm `11.28.10`, enforced via `packageManager` in `package.json` and `engine-strict=true`.
+pnpm `11.28.11`, enforced via `packageManager` in `package.json` and `engine-strict=true`.
 npm/yarn are not supported installation paths for *developing* this repo (consumers
 installing the published package via npm/npx are unaffected — see
 [README.md#installation](../../README.md#installation)).

package/docs/tutorials/getting-started.md

@@ -10,7 +10,7 @@ and [Reference](../reference/README.md) for the full option set.
 
 You need:
 
-- Node.js `>=22.22.2` (or `>=24.15.0` / `>=26.3.0`) and pnpm `^11.28.10`.
+- Node.js `>=22.22.2` (or `>=24.15.0` / `>=26.3.0`) and pnpm `^11.28.11`.
 - At least one host you can already reach with plain `ssh`, with its key already in
   your `~/.ssh/known_hosts` (this tutorial uses the default `strict` host-key policy —
   see [SECURITY_DECISIONS.md](../../SECURITY_DECISIONS.md) for why).

package/mcp.json

@@ -2,7 +2,7 @@
   "name": "ssh-mcp-pro",
   "display_name": "ssh-mcp-pro",
   "description": "Secure MCP SSH automation server with policy controls, resources, prompts, stdio, and HTTP.",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "author": "Osman Aslan",
   "license": "MIT",
   "runtime": "node",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ssh-mcp-pro",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "mcpName": "io.github.oaslananka/ssh-mcp-pro",
   "description": "Model Context Protocol (MCP) SSH client server for remote automation",
   "type": "module",
@@ -58,7 +58,7 @@
   },
   "engines": {
     "node": ">=22.22.2",
-    "pnpm": "^11.28.10"
+    "pnpm": "^11.28.11"
   },
   "dependencies": {
     "@modelcontextprotocol/node": "^2.1.2",

package/registry/ssh-mcp-pro/mcp.json

@@ -2,7 +2,7 @@
   "name": "ssh-mcp-pro",
   "display_name": "ssh-mcp-pro",
   "description": "Secure MCP SSH automation server with policy controls, resources, prompts, stdio, and HTTP.",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "author": "Osman Aslan",
   "license": "MIT",
   "runtime": "node",

package/server.json

@@ -7,13 +7,13 @@
     "url": "https://github.com/oaslananka/ssh-mcp-pro",
     "source": "github"
   },
-  "version": "1.5.0",
+  "version": "1.6.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "ssh-mcp-pro",
-      "version": "1.5.0",
+      "version": "1.6.0",
       "transport": {
         "type": "stdio"
       }
@@ -22,7 +22,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "ssh-mcp-pro",
-      "version": "1.5.0",
+      "version": "1.6.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "streamable-http",