ssh-mcp-pro 1.0.0

package/AGENTS.md

@@ -0,0 +1,127 @@
+# AGENTS.md - ssh-mcp-pro
+
+Guidance for AI agents using `ssh-mcp-pro` v2.
+
+## Quick Start
+
+```json
+{
+  "name": "ssh-mcp-pro",
+  "command": "ssh-mcp-pro",
+  "type": "stdio"
+}
+```
+
+## Secure Defaults
+
+- Host-key verification is strict by default.
+- Root SSH login is denied unless policy allows it.
+- Raw `proc_sudo` is denied unless policy allows it.
+- Destructive commands and filesystem operations are policy-controlled.
+- Use `policyMode: "explain"` before mutations when you need a plan or user confirmation.
+
+## Recommended Workflow
+
+1. `ssh_list_configured_hosts` to discover aliases when useful.
+2. `ssh_open_session` with `hostKeyPolicy: "strict"` or `expectedHostKeySha256`.
+3. `os_detect` to learn platform capabilities.
+4. Read `ssh-mcp-pro://policy/effective` before privileged or destructive work.
+5. Use task tools: `fs_*`, `proc_exec`, `ensure_*`, `file_*`, `tunnel_*`.
+6. `ssh_close_session` when work is complete.
+
+## Explain Mode
+
+Use explain mode when a request may mutate a remote host, change files, start or
+stop services, install packages, open tunnels, or require user approval before
+execution. Explain mode is a planning and policy-preview path; it is not a
+permission bypass and it does not execute the requested mutation.
+
+Use `policyMode: "explain"` when you need a non-mutating preview from normal SSH
+tools. For example, `ssh_open_session` with `policyMode: "explain"` returns a
+connection plan with `wouldConnect` instead of opening a live SSH connection.
+Write, transfer, process, ensure, and tunnel tools that honor the session policy
+mode return explain-only plans instead of performing the change.
+
+Use `policyMode: "enforce"` only after the plan has been reviewed, the target
+host and path are correct, strict host-key verification is active, and the
+effective policy allows the concrete operation. Enforce mode is the default mode
+for actual work.
+
+Connector clients can use `ssh_policy_explain` before opening sessions or
+running task tools. It evaluates an optional `hostAlias`, action class, command,
+and path against policy, returns `executed: false`, includes the policy
+decision, and marks non-inspection requests as requiring explicit user
+confirmation.
+
+Connector clients can use `ssh_mutation_plan` for remote changes that should be
+planned without execution. It accepts `hostAlias`, `goal`, and an optional
+category such as `package`, `service`, `file`, `command`, `tunnel`, or `other`.
+The result includes `executed: false`, a policy decision, prerequisites that
+must be true before execution, and operations that remain disallowed in remote
+connector profiles.
+
+Use the `plan-mutation` prompt when the user asks for a risky remote change and
+you need the agent to produce a concise, reviewable plan first. The prompt
+directs the agent to use explain mode or policy resources and to call out sudo
+needs, destructive operations, path policy, rollback, commands, and files that
+would change.
+
+Concrete explain-to-enforce sequence:
+
+1. `ssh_list_configured_hosts` to choose an allowed alias.
+2. `ssh_policy_explain` with `hostAlias`, `action: "mutation"`, and the
+   proposed command or path.
+3. `ssh_mutation_plan` with `hostAlias`, `goal`, and the closest category.
+4. `ssh_open_session` with `policyMode: "explain"` and strict host-key
+   verification to confirm the connection plan.
+5. Review the policy decision, target host, target path, rollback, and exact
+   tool payload with the user or supervising workflow.
+6. `ssh_open_session` again with `policyMode: "enforce"` only after approval.
+7. Run the narrow task tool, such as `ensure_package`, `ensure_service`,
+   `fs_write`, `patch_apply`, or `proc_exec`.
+8. Verify the result with read-only inspection and then `ssh_close_session`.
+
+## Tool Guidance
+
+| Tool | Use |
+|------|-----|
+| `ssh_open_session` | Open a persistent SSH connection. Reuse one session per host per task. |
+| `proc_exec` | Run non-interactive commands. Destructive patterns may be denied. |
+| `proc_sudo` | Raw sudo only when policy explicitly permits it. Prefer `ensure_*`. |
+| `proc_exec_stream` | Long-running commands or output that should stream. |
+| `fs_read` | Text-focused reads with size limits. Use `file_download` for large files. |
+| `fs_write` | Write text data. Policy may deny protected paths. |
+| `fs_rmrf` | Destructive delete. Use explain mode and confirm before invoking. |
+| `file_upload` / `file_download` | SFTP transfers with checksum verification. |
+| `ensure_package` | Idempotent package install/remove. |
+| `ensure_service` | Idempotent service state changes where supported. |
+| `ensure_lines_in_file` | Idempotent line management. |
+| `patch_apply` | Apply unified diffs with dry-run behavior. |
+| `tunnel_*` | Real SSH local/remote forwarding. Close tunnels when finished. |
+
+## Resources
+
+- `ssh-mcp-pro://sessions/active`
+- `ssh-mcp-pro://metrics/json`
+- `ssh-mcp-pro://metrics/prometheus`
+- `ssh-mcp-pro://ssh-config/hosts`
+- `ssh-mcp-pro://policy/effective`
+- `ssh-mcp-pro://audit/recent`
+- `ssh-mcp-pro://capabilities/support-matrix`
+
+## Prompts
+
+- `safe-connect`
+- `inspect-host-capabilities`
+- `plan-mutation`
+- `managed-config-change`
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Opening a new session for every tool call | Reuse the existing `sessionId`. |
+| Disabling host-key checks for production | Populate `known_hosts` or pin `expectedHostKeySha256`. |
+| Using raw `proc_sudo` for package/service work | Prefer `ensure_package` or `ensure_service`. |
+| Reading huge files with `fs_read` | Use `file_download`. |
+| Treating BusyBox/dropbear as full Linux | Check `sftpAvailable` and support matrix first. |

package/ARCHITECTURE.md

@@ -0,0 +1,145 @@
+# Architecture
+
+ssh-mcp-pro is organized around a small dependency-injected application container, an MCP server boundary, policy-aware tool providers, and SSH-backed services.
+
+## System Diagram
+
+```mermaid
+flowchart LR
+  Client[MCP client] --> Transport[stdio or Streamable HTTP transport]
+  Transport --> Server[SSHMCPServer]
+  Server --> Registry[ToolRegistry]
+  Registry --> Providers[Tool providers]
+  Providers --> Services[Session, process, filesystem, transfer, ensure, tunnel services]
+  Services --> SessionManager[SessionManager]
+  SessionManager --> SSH[node-ssh / ssh2]
+  Providers --> Policy[PolicyEngine.check]
+  Policy --> Audit[AuditLog]
+  Policy --> Metrics[MetricsCollector]
+```
+
+Core request flow:
+
+1. `SSHMCPServer` registers MCP tool, resource, and prompt handlers.
+2. `ToolRegistry` resolves aliases and filters tools by connector profile.
+3. Tool providers validate arguments and call services.
+4. Services ask `PolicyEngine` before privileged or destructive work.
+5. Policy decisions are recorded through `AuditLog` and `MetricsCollector`.
+6. `SessionManager` owns SSH connection lifecycle and delegates to `node-ssh`, which uses `ssh2` underneath.
+
+## Dependency Injection
+
+`AppContainer` is the runtime dependency graph. It contains `ConfigManager`, `RateLimiter`, `MetricsCollector`, `AuditLog`, `PolicyEngine`, `SessionManager`, and `TunnelService`.
+
+`createContainer()` builds the production graph from environment-backed `ConfigManager` settings. It enables the normal rate limiter behavior and wires session-close cleanup to tunnel cleanup.
+
+`createTestContainer()` builds the same shape for tests while allowing targeted overrides. It disables blocking rate-limit behavior and uses shorter session defaults so unit tests can replace only the dependency they are exercising.
+
+## MCP Server And Tool Registry
+
+`SSHMCPServer` wraps the MCP SDK `Server`. It exposes tools, resources, and prompts over stdio by default and can be connected to another transport through `connect()`.
+
+Tool calls pass through a global sliding-window rate limit first. Calls whose arguments include a top-level `sessionId` then pass through a second configurable `session:<id>` window so one busy SSH session cannot exhaust the entire server budget.
+
+Streamable HTTP responses also include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers derived from the current global limiter usage so HTTP clients can observe budget state before a hard rate-limit error.
+
+`ToolRegistry` owns provider registration and dispatch. It supports compatibility aliases such as `ssh.openSession` -> `ssh_open_session`, filters tool exposure through the configured tool profile, and converts thrown project errors into typed `ToolErrorResponse` MCP error results with `structuredContent.error`, `code`, and `message`. Successful tool handlers must return either a JSON object or an explicit MCP `CallToolResult` with non-null `structuredContent`; every listed tool has a concrete `outputSchema` that describes the successful structured response shape exposed to clients.
+
+## Policy Engine
+
+The policy path is:
+
+```text
+MCP tool call -> provider argument validation -> PolicyEngine.check() -> allow, deny, or explain -> AuditLog record -> service action
+```
+
+Default policy denies root login, raw sudo, destructive commands, and destructive filesystem operations. In `explain` mode, providers can surface the policy decision without mutating remote state.
+
+## Remote Control Plane
+
+The remote control plane provides Streamable HTTP MCP access and a no-custody outbound agent model.
+
+- `server-http.ts` hosts the HTTP MCP endpoint and enforces bearer or OAuth authorization.
+- `remote/control-plane.ts` implements control-plane HTTP routes, OAuth 2.0 PKCE, GitHub identity exchange, protected resource metadata, agent enrollment, and WebSocket agent communication.
+- `remote/websocket.ts` handles the persistent outbound agent channel.
+- `RemoteStore` persists users, OAuth clients, authorization codes, remote agents, enrollment tokens, and audit events in SQLite.
+- `remote/mcp-tools.ts` exposes administrative remote-agent tools behind control-plane scopes.
+
+OAuth uses PKCE for browser-based authorization and validates access tokens before protected MCP operations. Enrollment tokens are one-time secrets stored only as hashes.
+
+## Persistence
+
+`RemoteStore` currently uses `node:sqlite` through `DatabaseSync`. The project pins Node.js versions that include this module. In Node 24.15.0, `node:sqlite` is still a Stability 1.2 release-candidate API, so the contingency path is to introduce `better-sqlite3` 11.x as a maintained native fallback before widening the runtime matrix or if `node:sqlite` becomes unavailable.
+
+## ADR-001: Use `node:sqlite` For RemoteStore
+
+Status: accepted.
+
+Context: The remote control plane needs a small local database for OAuth clients, authorization codes, users, agents, enrollment tokens, and audit events.
+
+Decision: Use `node:sqlite` instead of adding `better-sqlite3` immediately.
+
+Rationale:
+
+- Avoids native bindings in the default install path.
+- Keeps the package installable through the pinned Node.js runtime without postinstall compilation.
+- Fits the local control-plane storage model.
+- The release-candidate status is acceptable because `engines.node` pins versions known to expose `node:sqlite`.
+
+Consequence: If Node removes or materially changes `node:sqlite`, the fallback is `better-sqlite3` 11.x with an explicit migration issue and CI coverage on the affected Node versions.
+
+## ADR-002: Use An In-Process Rate Limiter
+
+Status: accepted.
+
+Context: stdio deployments should not require Redis or another external service.
+
+Decision: Use the in-process `RateLimiter` sliding-window log.
+
+Rationale:
+
+- Keeps local stdio usage dependency-free.
+- Gives deterministic unit-test behavior.
+- Limits accidental global and per-session tool-call bursts without requiring network infrastructure.
+
+Consequence: Multi-instance HTTP deployments need an external rate-limiting layer at the reverse proxy or platform edge if they require global limits.
+
+## ADR-003: `better-sqlite3` Fallback For RemoteStore
+
+Status: contingency.
+
+Context: `node:sqlite` is the default storage adapter. Startup now validates that the current Node.js build exposes a constructable `DatabaseSync` before opening the control-plane database. If that check fails on a supported deployment target, the maintained native fallback is `better-sqlite3`.
+
+Decision: Keep `node:sqlite` as the default and document a direct fallback patch that can be applied if a pinned Node.js build removes or materially changes the API.
+
+Fallback steps:
+
+1. Install the fallback dependency:
+
+   ```bash
+   pnpm add better-sqlite3@^11.0.0
+   ```
+
+2. Replace the `createRequire`-based `node:sqlite` loader in `src/remote/store.ts` with:
+
+   ```typescript
+   import Database from "better-sqlite3";
+   ```
+
+3. Replace the `DatabaseSync` constructor call with:
+
+   ```typescript
+   this.db = new Database(filePath);
+   ```
+
+4. Keep the existing `prepare().get()`, `prepare().run()`, and `exec()` call sites. The `better-sqlite3` synchronous API supports the same access pattern used by `RemoteStore`.
+
+5. Run the full verification chain on the affected Node.js versions before widening the runtime matrix:
+
+   ```bash
+   pnpm run typecheck
+   pnpm test
+   pnpm run check
+   ```
+
+Consequence: The default install remains native-dependency-free. The fallback path is documented with copy-paste steps, but adopting it must be accompanied by a dependency review, lockfile update, CI coverage, and release notes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Osman Aslan (oaslananka)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSES/MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Osman Aslan (oaslananka)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,14 @@
+# Migration Guide
+
+## 1.x
+
+Version `1.0.0` is the initial public baseline for this repository. There are no earlier published package versions with a supported automated migration path.
+
+When upgrading within `1.x`, preserve these compatibility expectations:
+
+- Node.js must satisfy `^22.22.2 || ^24.15.0`.
+- pnpm must satisfy `^11.0.9`.
+- Existing stdio MCP client configs can continue to launch `ssh-mcp-pro` with no arguments.
+- HTTP deployments should keep explicit authentication, allowed origins, host allowlists, strict host-key verification, and a remote-safe tool profile.
+
+Future breaking changes should add a new section with required config, policy, or data migration steps before release.

package/README.md

@@ -0,0 +1,175 @@
+[![npm version](https://img.shields.io/npm/v/ssh-mcp-pro.svg)](https://www.npmjs.com/package/ssh-mcp-pro)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/oaslananka/ssh-mcp-pro/actions/workflows/ci.yml/badge.svg)](https://github.com/oaslananka/ssh-mcp-pro/actions/workflows/ci.yml)
+
+# ssh-mcp-pro
+
+ssh-mcp-pro is a secure Model Context Protocol (MCP) server for SSH automation. It lets MCP-capable clients open SSH sessions, inspect hosts, run guarded commands, manage files, transfer artifacts, create tunnels, and perform idempotent package or service work through policy-controlled tools.
+
+## Prerequisites
+
+- Node.js `>=22.22.2` or `>=24.15.0`
+- pnpm `>=11.0.9`
+- SSH access to the target hosts
+- Docker, only for local integration tests and container image builds
+
+## Installation
+
+Install globally with pnpm:
+
+```bash
+pnpm add --global ssh-mcp-pro
+ssh-mcp-pro --version
+```
+
+Run without a global install:
+
+```bash
+npx ssh-mcp-pro
+```
+
+For pnpm-only environments, use:
+
+```bash
+pnpm dlx ssh-mcp-pro
+```
+
+## Quickstart
+
+Generic stdio MCP config:
+
+```json
+{
+  "name": "ssh-mcp-pro",
+  "command": "ssh-mcp-pro",
+  "type": "stdio"
+}
+```
+
+VS Code settings style:
+
+```json
+{
+  "mcp.servers": {
+    "ssh-mcp-pro": {
+      "type": "stdio",
+      "command": "ssh-mcp-pro",
+      "args": []
+    }
+  }
+}
+```
+
+Claude Desktop style:
+
+```json
+{
+  "mcpServers": {
+    "ssh-mcp-pro": {
+      "command": "ssh-mcp-pro",
+      "args": []
+    }
+  }
+}
+```
+
+After registration, start with discovery and a strict host-key policy:
+
+```text
+List configured SSH hosts, open a session to bastion.example.com as deploy with hostKeyPolicy=strict, then run os_detect.
+```
+
+## Configuration
+
+All `SSH_MCP_*` environment variables parsed by `src/config.ts` are listed below. Comma-separated settings also accept newline-separated values.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SSH_MCP_MAX_SESSIONS` | `20` | Maximum concurrent SSH sessions. |
+| `SSH_MCP_SESSION_TTL` | `900000` | Session time-to-live in milliseconds. |
+| `SSH_MCP_COMMAND_TIMEOUT` | `30000` | Default remote command timeout in milliseconds. |
+| `SSH_MCP_MAX_COMMAND_OUTPUT_BYTES` | `1048576` | Maximum buffered stdout/stderr bytes per command result. |
+| `SSH_MCP_MAX_STREAM_CHUNKS` | `4096` | Maximum retained streaming chunks. |
+| `SSH_MCP_MAX_FILE_SIZE` | `10485760` | Maximum bytes returned by text-focused file reads. |
+| `SSH_MCP_MAX_FILE_WRITE_BYTES` | `10485760` | Maximum accepted write payload before buffering. |
+| `SSH_MCP_MAX_TRANSFER_BYTES` | `52428800` | Maximum upload or download transfer size. |
+| `SSH_MCP_DEBUG` | `false` | Enables debug-oriented configuration behavior. |
+| `SSH_MCP_RATE_LIMIT` | `true` | Enables the global MCP request rate limiter. |
+| `SSH_MCP_RATE_LIMIT_MAX` | `100` | Maximum requests per rate-limit window. |
+| `SSH_MCP_RATE_LIMIT_PER_SESSION` | `true` | Enables per-session MCP request rate limiting when tool arguments include `sessionId`. |
+| `SSH_MCP_RATE_LIMIT_PER_SESSION_MAX` | `50` | Maximum requests per SSH session per rate-limit window. |
+| `SSH_MCP_RATE_LIMIT_PER_SESSION_WINDOW_MS` | `60000` | Per-session rate-limit window in milliseconds. |
+| `SSH_MCP_RATE_LIMIT_WINDOW_MS` | `60000` | Rate-limit window in milliseconds. |
+| `SSH_MCP_STRICT_HOST_KEY` | unset | Legacy boolean alias for strict vs insecure host-key checking. |
+| `SSH_MCP_HOST_KEY_POLICY` | `strict` | Host-key mode: `strict`, `accept-new`, or `insecure`. |
+| `SSH_MCP_KNOWN_HOSTS_PATH` | `~/.ssh/known_hosts` | Known hosts file used for strict host-key verification. |
+| `SSH_MCP_ALLOW_ROOT_LOGIN` | `false` | Allows SSH login as root and mirrors into policy. |
+| `SSH_MCP_ALLOWED_CIPHERS` | empty | Optional SSH cipher allowlist. |
+| `SSH_MCP_POLICY_FILE` | unset | JSON file containing partial policy overrides. |
+| `SSH_MCP_POLICY_MODE` | `enforce` | Policy decision mode: `enforce` or `explain`. |
+| `SSH_MCP_ALLOW_RAW_SUDO` | `false` | Allows raw `proc_sudo`; prefer `ensure_*` tools. |
+| `SSH_MCP_ALLOW_DESTRUCTIVE_COMMANDS` | `false` | Allows commands matching destructive command policy. |
+| `SSH_MCP_ALLOW_DESTRUCTIVE_FS` | `false` | Allows destructive filesystem operations such as `fs_rmrf`. |
+| `SSH_MCP_ALLOWED_HOSTS` | empty | Host allowlist for policy and remote connector safety checks. |
+| `SSH_MCP_COMMAND_ALLOW` | empty | Command allow patterns. |
+| `SSH_MCP_COMMAND_DENY` | empty | Command deny patterns. |
+| `SSH_MCP_PATH_ALLOW_PREFIXES` | `/tmp,/var/tmp,/home,/Users` | Remote path prefixes allowed by filesystem policy. |
+| `SSH_MCP_PATH_DENY_PREFIXES` | `/etc/sudoers,/etc/shadow,/etc/passwd,/boot,/dev,/proc` | Remote path prefixes denied by filesystem policy. |
+| `SSH_MCP_LOCAL_PATH_ALLOW_PREFIXES` | OS temp directory | Local paths allowed for transfer operations. |
+| `SSH_MCP_LOCAL_PATH_DENY_PREFIXES` | empty | Local paths denied for transfer operations. |
+| `SSH_MCP_TUNNEL_ALLOW_BIND_HOSTS` | `127.0.0.1,localhost,::1` | Local bind hosts allowed for tunnels. |
+| `SSH_MCP_TUNNEL_DENY_BIND_HOSTS` | `0.0.0.0,::` | Local bind hosts denied for tunnels. |
+| `SSH_MCP_TUNNEL_ALLOW_REMOTE_HOSTS` | empty | Optional remote tunnel target host allowlist. |
+| `SSH_MCP_TUNNEL_DENY_REMOTE_HOSTS` | empty | Optional remote tunnel target host denylist. |
+| `SSH_MCP_TUNNEL_ALLOW_PORTS` | empty | Optional tunnel port allowlist. |
+| `SSH_MCP_TUNNEL_DENY_PORTS` | empty | Optional tunnel port denylist. |
+| `SSH_MCP_HTTP_HOST` | `127.0.0.1` | Streamable HTTP bind host. |
+| `SSH_MCP_HTTP_PORT` | `3000` | Streamable HTTP bind port. |
+| `SSH_MCP_HTTP_ALLOWED_ORIGINS` | `http://127.0.0.1,http://localhost` | Browser origins allowed for HTTP clients. |
+| `SSH_MCP_HTTP_BEARER_TOKEN_FILE` | unset | Bearer token file for HTTP transport. Required for non-loopback bearer deployments. |
+| `SSH_MCP_ENABLE_LEGACY_SSE` | `false` | Enables legacy SSE compatibility. |
+| `SSH_MCP_HTTP_MAX_REQUEST_BODY_BYTES` | `1048576` | Maximum HTTP request body size. |
+| `SSH_MCP_HTTP_MAX_SESSIONS` | `20` | Maximum HTTP MCP sessions. |
+| `SSH_MCP_HTTP_SESSION_IDLE_TTL_MS` | `900000` | HTTP MCP session idle timeout in milliseconds. |
+| `SSH_MCP_HTTP_PUBLIC_URL` | unset | Stable public HTTPS MCP URL for protected resource metadata. |
+| `SSH_MCP_HTTP_TRUST_PROXY` | `false` | Trust reverse proxy forwarded headers. |
+| `SSH_MCP_TOOL_PROFILE` | `full` | Active tool exposure profile. |
+| `SSH_MCP_CONNECTOR_PROFILE` | `full` | Alias for `SSH_MCP_TOOL_PROFILE`. |
+| `SSH_MCP_CONNECTOR_CREDENTIAL_PROVIDER` | `none` | Credential provider: `none`, `agent`, or `command`. |
+| `SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND` | unset | External credential command when provider is `command`. |
+| `SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND_ARGS` | empty | Arguments passed to the external credential command. |
+| `SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND_TIMEOUT_MS` | `5000` | Credential command timeout in milliseconds. |
+| `SSH_MCP_CONNECTOR_DEFAULT_USERNAME` | unset | Default username for connector broker flows. |
+| `SSH_MCP_HTTP_AUTH_MODE` | `bearer` | HTTP auth mode: `bearer` or `oauth`. |
+| `SSH_MCP_OAUTH_ISSUER` | unset | Expected OAuth issuer. |
+| `SSH_MCP_OAUTH_AUDIENCE` | unset | Expected OAuth audience. |
+| `SSH_MCP_OAUTH_JWKS_URL` | unset | OAuth JWKS URL. |
+| `SSH_MCP_OAUTH_RESOURCE` | unset | OAuth protected resource identifier. |
+| `SSH_MCP_OAUTH_REQUIRED_SCOPES` | `ssh-mcp-pro.read` | Required OAuth scopes. |
+
+The parser also accepts non-`SSH_MCP_*` compatibility aliases `PORT`, `KNOWN_HOSTS_PATH`, and `STRICT_HOST_KEY_CHECKING`.
+
+## Tool Profiles
+
+`full` exposes every registered tool, resource, and prompt. Every other profile uses an explicit per-profile allowset. `chatgpt` and `claude` currently expose the same baseline connector tools as `remote-safe`, with empty client-specific extension sets reserved for future additions.
+
+| Profile | Exposed tools | Exposed resources | Exposed prompts |
+| --- | --- | --- | --- |
+| `full` | All SSH, process, filesystem, transfer, ensure, tunnel, connector, and system tools. | All runtime resources. | All prompts. |
+| `remote-safe` | `connector_status`, `ssh_hosts_list`, `ssh_policy_explain`, `ssh_host_inspect`, `ssh_mutation_plan`. | `ssh-mcp-pro://capabilities/support-matrix`. | `inspect-host-capabilities`, `plan-mutation`. |
+| `chatgpt` | Baseline remote connector tools plus an empty ChatGPT extension set. | Same remote connector subset as `remote-safe`. | Same remote connector subset as `remote-safe`. |
+| `claude` | Baseline remote connector tools plus an empty Claude extension set. | Same remote connector subset as `remote-safe`. | Same remote connector subset as `remote-safe`. |
+| `remote-readonly` | Same remote connector subset as `remote-safe`. | Same remote connector subset as `remote-safe`. | Same remote connector subset as `remote-safe`. |
+| `remote-broker` | Same remote connector subset as `remote-safe`. | Same remote connector subset as `remote-safe`. | Same remote connector subset as `remote-safe`. |
+
+## Security Defaults
+
+ssh-mcp-pro starts with strict SSH host-key verification, denies root login, denies raw sudo, blocks destructive commands and filesystem operations unless policy allows them, and refuses non-loopback HTTP startup unless authentication, origins, public HTTPS URL, strict host-key verification, a remote-safe tool profile, and host allowlists are configured. See [SECURITY.md](SECURITY.md) for vulnerability reporting and [SECURITY_DECISIONS.md](SECURITY_DECISIONS.md) for the design rationale behind these defaults.
+
+## More Documentation
+
+- [INSTALL.md](INSTALL.md) covers full client setup and troubleshooting.
+- [AGENTS.md](AGENTS.md) describes agent-facing operational guidance.
+- [examples/README.md](examples/README.md) contains workflow examples.
+- [ARCHITECTURE.md](ARCHITECTURE.md) explains the major subsystems and ADRs.
+- [REGISTRY_SUBMISSION.md](REGISTRY_SUBMISSION.md) tracks MCP Registry submission readiness.

package/REGISTRY_SUBMISSION.md

@@ -0,0 +1,38 @@
+# MCP Registry Submission
+
+Published server name:
+
+```text
+io.github.oaslananka/ssh-mcp-pro
+```
+
+Package identifier:
+
+```text
+ssh-mcp-pro
+```
+
+## Checklist
+
+- [x] `server.json` uses the `io.github.oaslananka/ssh-mcp-pro` namespace.
+- [x] `mcp.json` and `registry/ssh-mcp-pro/mcp.json` match `package.json` name, version, and entrypoint.
+- [x] Package metadata declares stdio transport and Node runtime.
+- [x] Package metadata declares Linux, macOS, and Windows platforms.
+- [x] Tool, resource, and prompt capabilities are declared.
+- [x] `validate:mcp-metadata` checks local metadata consistency without requiring build artifacts.
+- [ ] A versioned package has been published to npm.
+- [ ] The MCP Registry latest record resolves for `io.github.oaslananka/ssh-mcp-pro`.
+- [ ] Registry submission has been verified after the first published release.
+
+## Local Validation
+
+```bash
+pnpm run validate:mcp-metadata
+pnpm run sync-version -- --check
+pnpm run build
+pnpm pack --dry-run
+```
+
+## Notes
+
+The registry workflow validates local metadata and accepts a missing public registry record before the first release. After npm publication, the workflow should confirm that the latest registry record resolves to `io.github.oaslananka/ssh-mcp-pro`.

package/SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Security support |
+| --- | --- |
+| `1.x` | Supported. The current major version receives security fixes. |
+| `<1.0.0` | Not supported. |
+
+## Reporting a Vulnerability
+
+Report suspected vulnerabilities through GitHub's private security advisory form:
+
+https://github.com/oaslananka/ssh-mcp-pro/security/advisories/new
+
+Do not open a public issue for credential handling bugs, authorization bypasses, command execution escapes, policy bypasses, host-key verification problems, token validation issues, or vulnerabilities that expose SSH session data.
+
+## Response SLA
+
+Maintainers aim to acknowledge a valid report within 7 days. The acknowledgment should confirm receipt, request any missing reproduction details, and identify the next expected update window.
+
+## Coordinated Disclosure
+
+Security fixes are coordinated privately until a patch is available. Public disclosure should happen after the patched release is published, release notes are available, and affected users have a practical upgrade path.
+
+## Scope
+
+In scope:
+
+- Authentication or authorization bypasses in the stdio, HTTP, OAuth, or remote agent surfaces.
+- Policy bypasses that allow denied commands, root login, raw sudo, filesystem mutation, transfers, or tunnels.
+- Secret leakage through logs, audit records, MCP responses, package artifacts, or container images.
+- Host-key verification failures that silently weaken strict mode.
+- Remote control-plane vulnerabilities in enrollment, token validation, OAuth PKCE, or WebSocket agent handling.
+
+Out of scope:
+
+- Vulnerabilities in `node-ssh`, `ssh2`, `jose`, Node.js, OpenSSH, Docker, or operating system packages that are not exploitable through this project's exposed behavior.
+- Findings that require disabling documented secure defaults.
+- Denial-of-service reports based only on local resource exhaustion in a trusted development environment.

package/SECURITY_DECISIONS.md

@@ -0,0 +1,59 @@
+# Security Decisions
+
+This document records security-relevant defaults that affect SSH sessions, remote command execution, HTTP transport, and registry readiness.
+
+## Strict Host-Key Verification
+
+`SSH_MCP_HOST_KEY_POLICY` defaults to `strict`, using `~/.ssh/known_hosts` unless `SSH_MCP_KNOWN_HOSTS_PATH` is set. This prevents silent trust-on-first-use in production paths.
+
+Non-loopback HTTP startup is refused unless host-key verification remains strict. The HTTP transport can be exposed to browsers or hosted clients, so allowing `insecure` there would combine remote reachability with unverifiable SSH host identity.
+
+## Non-Loopback HTTP Restrictions
+
+For non-loopback HTTP bindings, startup requires:
+
+- Bearer authentication or configured OAuth.
+- Explicit allowed origins.
+- A stable HTTPS public URL.
+- A remote-safe tool profile.
+- A non-empty host allowlist.
+- Strict SSH host-key verification.
+
+These checks prevent accidentally exposing the full local SSH automation surface on a public interface.
+
+## Root Login And Raw Sudo
+
+Root login is denied by default through both security config and policy config. Raw `proc_sudo` is denied by default because it can bypass higher-level idempotent package and service helpers.
+
+Operators who need privileged work should prefer `ensure_package`, `ensure_service`, `ensure_lines_in_file`, or `patch_apply`, with `SSH_MCP_POLICY_MODE=explain` before mutation when reviewing the plan.
+
+## Destructive Commands And Filesystem Operations
+
+Destructive command execution and destructive filesystem operations are denied by default. Policy allowlists, path prefixes, and explicit destructive toggles are required before tools such as `fs_rmrf` can remove remote paths.
+
+## Audit Redaction
+
+`AuditLog` stores policy decisions and selected action metadata. Before retention, it calls `redactSensitiveData()` and `redactErrorMessage()` so fields matching password, private key, passphrase, sudo password, secret, token, credential, auth, API key, bearer, and PEM patterns are redacted.
+
+## Audit Buffer Size
+
+The in-memory audit buffer keeps 500 events by default. This bounded size avoids unbounded memory growth in stdio and local HTTP deployments while retaining recent security-relevant decisions for inspection. Deployments with compliance retention requirements should export or persist audit events; OTLP log persistence is tracked separately from this baseline.
+
+## Token Comparison
+
+Bearer token comparison uses SHA-256 digests and `timingSafeEqual` through `constantTimeTokenEquals()`. Remote enrollment token validation also compares fixed-length hashes with `timingSafeEqual`. This avoids leaking token equality information through variable-time string comparison.
+
+## CodeQL Agent Bootstrap Findings
+
+CodeQL alerts #2, #4, #5, and #6 are documented false positives for the remote agent bootstrap flow. They are tracked by CodeQL as `js/http-to-file-access` / `js/file-access-to-http` because the agent writes enrollment data to its local config file and later uses that config to connect to the control plane.
+
+The flow is intentional:
+
+- `ssh-mcp-pro-agent enroll` requires an explicit `--server` URL and one-time enrollment token from the operator.
+- Enrollment writes only to `SSHAUTOMATOR_AGENT_CONFIG` or `~/.sshautomator/agent.json` with file mode `0600`.
+- Server response fields are validated with `requireString()` and `parseAgentPolicy()` before persistence.
+- The agent private key is generated locally and is not received from the network.
+- `ssh-mcp-pro-agent run` connects only to the enrolled `websocketUrl` from that config and sends signed agent envelopes to the configured control plane.
+- The private key remains local; outbound payloads contain signed metadata, policy-limited capabilities, and policy-controlled action results.
+
+These findings are dismissed individually with a false-positive rationale. No broad CodeQL suppression is used.

package/dist/agent-bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=agent-bin.d.ts.map

package/dist/agent-bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-bin.d.ts","sourceRoot":"","sources":["../src/agent-bin.ts"],"names":[],"mappings":""}

package/dist/agent-bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runAgentCli } from "./remote/agent-cli.js";
+runAgentCli(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=agent-bin.js.map