ssh-mcp-pro 1.1.4 → 1.2.1

package/docs/explanation/architecture.md

@@ -0,0 +1,44 @@
+# Explanation: Architecture
+
+This page is explanation-oriented (the "why"), per
+[Diátaxis](https://diataxis.fr/explanation/). For the authoritative system diagram,
+component breakdown, and ADRs, see [ARCHITECTURE.md](../../ARCHITECTURE.md) — this page
+doesn't duplicate that content, it frames it.
+
+## Why an MCP server for SSH, specifically
+
+Model Context Protocol gives an LLM client a structured, typed set of tools instead of
+free-form shell access. ssh-mcp-pro's core design bet is that "give the model SSH" is
+unsafe as a primitive, but "give the model a curated set of SSH-backed tools, each with
+its own policy check" is a workable middle ground between "no remote access" and
+"unrestricted remote shell." That bet is why the codebase has a dedicated `policy`/
+`safety` layer sitting between tool dispatch and the SSH session, rather than tools
+calling `node-ssh` directly.
+
+## Why defaults are deny-by-default
+
+Every default documented in [SECURITY_DECISIONS.md](../../SECURITY_DECISIONS.md) —
+strict host-key verification, no root login, no raw `sudo`, no destructive commands or
+filesystem operations — exists because the honest threat model for this project is "an
+LLM-driven client with SSH credentials, potentially acting on ambiguous or adversarial
+instructions." See [docs/security/threat-model.md](../security/threat-model.md) for the
+full reasoning. Architecturally, this means the safety checks live close to the tool
+registry (so no tool can bypass them by construction), not scattered per-tool.
+
+## Why there's a separate "remote control plane"
+
+`src/remote/*` and the `ssh-mcp-pro-agent` binary exist because not every deployment
+wants the MCP server itself reachable from the public internet. The control plane lets
+an operator run a broker that mediates access, so the SSH-capable server can stay on a
+private network while remote clients (ChatGPT connectors, Claude connectors) talk to the
+broker instead. See [docs/remote-mcp-hardening.md](../remote-mcp-hardening.md) for the
+operational guide and [ARCHITECTURE.md](../../ARCHITECTURE.md) for where this sits in
+the request flow.
+
+## Why tool profiles exist
+
+`SSH_MCP_TOOL_PROFILE` (`full`, `remote-safe`, `chatgpt`, `claude`,
+`remote-readonly`, `remote-broker`) exists because "expose every tool" is the right
+default for a trusted local stdio client, but the wrong default for a remote connector
+serving a broader audience. Profiles are an allowlist, not a denylist, so adding a new
+profile can never accidentally widen an existing one's exposure.

package/docs/how-to/README.md

@@ -0,0 +1,14 @@
+# How-to Guides
+
+How-to guides are goal-oriented: they assume you already know the basics (see the
+[tutorial](../tutorials/getting-started.md) if not) and get you to a specific outcome.
+Organized per the [Diátaxis](https://diataxis.fr/how-to-guides/) model.
+
+- [How to run ssh-mcp-pro with Docker](../docker.md)
+- [How to onboard a remote device / agent](../adding-a-device.md)
+- [How to harden a public/remote MCP deployment](../remote-mcp-hardening.md)
+- [How to set the SSH host-key and policy defaults](configure-ssh-policy.md)
+
+If something's actually broken rather than a task you're trying to accomplish, see
+[Troubleshooting](../troubleshooting.md) instead. If you're looking for exhaustive
+option listings instead of a task, see [Reference](../reference/README.md).

package/docs/how-to/configure-ssh-policy.md

@@ -0,0 +1,50 @@
+# How to configure the SSH policy
+
+This guide walks through the most common policy adjustments. Every setting here is one
+row in the [environment variable reference](../../README.md#configuration) — this guide
+just groups them by task.
+
+## Loosen host-key checking for a lab environment
+
+By default `SSH_MCP_HOST_KEY_POLICY=strict`, which requires every host to already be in
+`SSH_MCP_KNOWN_HOSTS_PATH`. For a throwaway lab environment where you accept the risk:
+
+```bash
+export SSH_MCP_HOST_KEY_POLICY=accept-new
+```
+
+Do not set this to `insecure` outside of a fully isolated test environment — see
+[SECURITY_DECISIONS.md](../../SECURITY_DECISIONS.md) for why `strict` is the default.
+
+## Allow a specific destructive operation
+
+Destructive commands and filesystem operations (like `fs_rmrf`) are denied by default.
+To allow them for a specific deployment:
+
+```bash
+export SSH_MCP_ALLOW_DESTRUCTIVE_COMMANDS=true
+export SSH_MCP_ALLOW_DESTRUCTIVE_FS=true
+```
+
+Prefer narrowing scope with `SSH_MCP_COMMAND_ALLOW`/`SSH_MCP_COMMAND_DENY` and
+`SSH_MCP_PATH_ALLOW_PREFIXES`/`SSH_MCP_PATH_DENY_PREFIXES` instead of a blanket allow,
+where possible.
+
+## Restrict which hosts can be targeted at all
+
+```bash
+export SSH_MCP_ALLOWED_HOSTS="bastion.example.com,10.0.0.0/8"
+```
+
+## Use a policy file instead of many environment variables
+
+```bash
+export SSH_MCP_POLICY_FILE=/etc/ssh-mcp-pro/policy.json
+export SSH_MCP_POLICY_MODE=enforce
+```
+
+Set `SSH_MCP_POLICY_MODE=explain` first in a non-production environment to see what the
+policy *would* block without actually enforcing it, before flipping to `enforce`.
+
+See [docs/security/input-validation.md](../security/input-validation.md) for how these
+allow/deny lists are evaluated.

package/docs/openssf-evidence.md

@@ -0,0 +1,75 @@
+# OpenSSF Best Practices — Evidence
+
+Self-assessment against the [OpenSSF Best Practices Passing criteria](https://www.bestpractices.dev/en/criteria/0),
+current as of 2026-07-03. This is a repo-side evidence log, not an official OpenSSF
+artifact — the actual badge is issued by submitting these answers at
+[bestpractices.dev](https://www.bestpractices.dev/). See `.bestpractices.json` for the
+same answers in a structured tracking form used to prepare that submission.
+
+Status legend: `Met` / `Partially met` / `Unmet` / `N/A`, matching the badge site's own
+vocabulary.
+
+## Basics
+
+| Criterion | Status | Evidence |
+| --- | --- | --- |
+| Project has a public repository with a version-controlled history | Met | github.com/oaslananka/ssh-mcp-pro |
+| Project uses a common distributed version control system (Git) | Met | Git |
+| Project has FLOSS license | Met | `LICENSE` (MIT), `REUSE.toml` |
+| License is OSI-approved | Met | MIT |
+| Documentation: basic description of purpose | Met | README.md intro |
+| Documentation: how to obtain/provide feedback and contribute | Met | CONTRIBUTING.md, SUPPORT.md |
+| Interim versions/releases are identifiable | Met | Conventional Commits + release-please tagging (pending first tag — see gap analysis) |
+
+## Change control
+
+| Criterion | Status | Evidence |
+| --- | --- | --- |
+| Public version-controlled source repository | Met | GitHub |
+| Repository tracks changes with commit-level granularity | Met | Git history |
+| Releases have version numbers following a documented convention | Met | SemVer via release-please |
+| Project has release notes for each new major/minor release | Partially met | `CHANGELOG.md` follows Keep a Changelog; no release has actually been cut yet to verify end-to-end |
+
+## Reporting
+
+| Criterion | Status | Evidence |
+| --- | --- | --- |
+| Project has a process for reporting bugs | Met | Issue templates, `.github/ISSUE_TEMPLATE/config.yml` |
+| Project has a documented vulnerability reporting process | Met | `SECURITY.md` — private advisories, 7-day SLA |
+| Project acknowledges vulnerability reports within a reasonable time | Unmet (no data) | No vulnerability report has been received yet to measure against the documented SLA |
+
+## Quality
+
+| Criterion | Status | Evidence |
+| --- | --- | --- |
+| Project uses at least one automated test suite | Met | Vitest: unit, integration, e2e, perf projects |
+| Project has FLOSS automated test suite invoked on all commits/PRs | Met | `ci.yml` |
+| New functionality has accompanying tests (documented expectation) | Met | `CONTRIBUTING.md` PR checklist requires it |
+| Project has a general policy for test coverage | Met | `vitest.config.ts` enforces 85–90% thresholds |
+| Project uses continuous integration | Met | `ci.yml` on push/PR/schedule |
+| Project has at least one static analysis tool applied | Met | CodeQL, ESLint, mutation testing (Stryker) |
+| All medium/high-severity static analysis findings are addressed | Met (2026-07-03) | All 8 CodeQL alerts closed: 1 fixed in code, 7 dismissed with rationale re-verified against current code — see `SECURITY_DECISIONS.md`. (Separately, Trivy container-image scanning added the same day found 50+ new findings against the built Docker image, mostly in the base image's bundled tooling rather than this project's source — tracked as an open item in `docs/repo-maturity-report.md`, not part of this specific criterion, which concerns source static analysis) |
+
+## Security
+
+| Criterion | Status | Evidence |
+| --- | --- | --- |
+| Project has a documented security architecture / defaults | Met | SECURITY_DECISIONS.md, README "Security Defaults" |
+| Cryptographic functions use public, well-reviewed protocols | Met | `jose` for JWT/OAuth verification (per `package.json` deps); no bespoke crypto identified |
+| Secrets are not stored in the repository | Met (best-effort) | GitHub secret scanning + push protection enabled; `gitleaks.yml` added by this PR for defense-in-depth history scanning |
+| Delivery mechanisms protect against MITM | Met | npm publish over registry.npmjs.org HTTPS with npm provenance; container images pinned by digest per `docs/docker.md` |
+
+## Analysis
+
+| Criterion | Status | Evidence |
+| --- | --- | --- |
+| Static analysis applied to any language used | Met | CodeQL (JS/TS query pack) |
+| Dynamic analysis applied | Partially met | Mutation testing (Stryker) exercises runtime behavior of security-critical code paths; no fuzzing harness exists, and none is currently believed necessary (see repo-maturity-report.md, "Fuzzing: Not applicable") |
+
+## Bottom line
+
+As of 2026-07-03, the CodeQL blocker has been resolved. The remaining blocker is
+"cut a first release," already tracked in [ROADMAP.md](../ROADMAP.md), plus triaging
+the new Trivy container-image findings noted above. Nothing in this evidence log claims
+Silver or Gold; see [docs/openssf-gap-analysis.md](openssf-gap-analysis.md) for why
+those are out of reach right now.

package/docs/openssf-gap-analysis.md

@@ -0,0 +1,63 @@
+# OpenSSF Gap Analysis
+
+This document separates what's achievable now (Passing) from what genuinely requires
+organizational change (Silver, Gold), so that neither this audit nor future readers
+overclaim.
+
+## Passing — achievable now
+
+See [docs/openssf-evidence.md](openssf-evidence.md) for the full criterion table.
+
+~~Seven open CodeQL alerts (one High) with no fully-current documented disposition.~~
+**Resolved 2026-07-03** — see `SECURITY_DECISIONS.md`.
+
+The remaining concrete blocker: no release has been cut yet, so "release notes exist
+for each release" is unverified in practice even though the mechanism (release-please +
+CHANGELOG) is implemented. Tracked in [ROADMAP.md](../ROADMAP.md) and as a recommended
+issue in [docs/repo-maturity-report.md](repo-maturity-report.md).
+
+A new, unrelated item surfaced the same day: Trivy container-image scanning (added
+after this document was first written) found 50+ open findings against the built
+Docker image — see "Package publishing maturity" in
+[docs/repo-maturity-report.md](repo-maturity-report.md). This doesn't block Passing
+(that criterion concerns source static analysis, not container base-image CVEs) but is
+worth tracking as its own item.
+
+## Silver — not yet achievable
+
+OpenSSF Best Practices Silver adds requirements this project cannot honestly claim yet,
+specifically:
+
+- **Two or more unassociated significant contributors.** Current bus factor is 1
+  (single collaborator, `oaslananka`). Silver requires evidence of contribution from
+  people not all affiliated with the same entity.
+- **A documented process for reviewing and responding to bug reports within a
+  well-defined window, evidenced by actual history.** The process is documented
+  (`SECURITY.md`, `SUPPORT.md`), but there is no report history yet to evidence it.
+- **Basic floor for cryptographic practices is fully documented** (partially met —
+  `SECURITY_DECISIONS.md` covers several defaults but doesn't exhaustively enumerate
+  every cryptographic operation in the codebase).
+
+**What would need to change:** a second active contributor with merged, substantive
+PRs; at least one real vulnerability report handled end-to-end; and a pass over
+`SECURITY_DECISIONS.md` to make the cryptographic inventory exhaustive.
+
+## Gold — explicitly out of scope for a claim today
+
+Per the audit's own instructions, Gold is only evaluated as a gap list when its
+preconditions are absent — and they are absent here:
+
+| Gold precondition | Current state |
+| --- | --- |
+| Multiple active maintainers | 1 (see MAINTAINERS.md) |
+| Independent contributor/reviewer | 0 non-bot PRs have ever been opened |
+| Regular human PR review | 0 human-reviewed PRs to date |
+| Branch protection | Not applied on GitHub (ruleset JSON exists but unapplied) |
+| Sustainable governance | Solo-maintainer model, honestly documented in GOVERNANCE.md, not yet a multi-party governance structure |
+| High test coverage sustained over time | Coverage thresholds exist (85–90%) but "sustained over time" needs release/version history that doesn't exist yet (repo is 5 days old) |
+| Repeatable/reproducible release process | Implemented (SBOM, checksums, provenance) but never executed — zero releases published |
+
+**This is a gap list, not a target with a date.** None of these should be worked toward
+by editing files; they require either time (release/contribution history accruing
+naturally) or a maintainer decision (branch protection, recruiting a co-maintainer).
+Revisit this analysis after the "Silver" preconditions above are met.

package/docs/openssf-proposal-links.md

@@ -0,0 +1,37 @@
+# OpenSSF Proposal Links
+
+Reference links for acting on the findings in
+[docs/repo-maturity-report.md](repo-maturity-report.md) and
+[docs/openssf-gap-analysis.md](openssf-gap-analysis.md). These are pointers to where a
+maintainer takes the next action, not automated submissions — no badge or scorecard
+submission has been made on the project's behalf by this audit.
+
+## OpenSSF Best Practices badge
+
+- Self-assessment form (submit once the CodeQL/first-release gaps in
+  `docs/openssf-gap-analysis.md` close): <https://www.bestpractices.dev/en/projects/new>
+- Full criteria reference used for this audit: <https://www.bestpractices.dev/en/criteria/0>
+- `.bestpractices.json` in the repo root tracks current self-assessment answers to make
+  filling out the form above mechanical.
+
+## OpenSSF Scorecard
+
+- Public checks reference: <https://github.com/ossf/scorecard/blob/main/docs/checks.md>
+- Scorecard viewer for this repo (once `publish_results` is re-enabled or a manual run
+  is published): <https://securityscorecards.dev/viewer/?uri=github.com/oaslananka/ssh-mcp-pro>
+- `ossf/scorecard-action` documentation for the `publish_results` requirements that are
+  currently blocking automatic publication: <https://github.com/ossf/scorecard-action#authenticated-workflow>
+
+## GitHub repository configuration referenced by this audit
+
+- Branch protection settings: `https://github.com/oaslananka/ssh-mcp-pro/settings/branches`
+- Rulesets (to import `.github/rulesets/main-protection.json`):
+  `https://github.com/oaslananka/ssh-mcp-pro/settings/rules`
+- Security & analysis settings (private vulnerability reporting, Dependabot security
+  updates): `https://github.com/oaslananka/ssh-mcp-pro/settings/security_analysis`
+- Code scanning alerts: `https://github.com/oaslananka/ssh-mcp-pro/security/code-scanning`
+
+## CHAOSS
+
+- Metrics reference used for the Community maturity section:
+  <https://chaoss.community/metrics/>

package/docs/professionalization-plan.md

@@ -0,0 +1,81 @@
+# Professionalization Plan
+
+A phased plan synthesizing [docs/repo-maturity-report.md](repo-maturity-report.md)'s
+"Safe refactor opportunities," "High-risk refactor opportunities," and "Recommended
+issues" into an ordered sequence. This is a plan, not a commitment with dates — see
+[ROADMAP.md](../ROADMAP.md) for the roadmap framing of the same underlying gaps.
+
+## Phase 0 — Done (this audit)
+
+Documentation, governance, and evidence gaps that required no maintainer decision and
+no behavior change: `CODE_OF_CONDUCT.md`, `GOVERNANCE.md`, `MAINTAINERS.md`,
+`ROADMAP.md`, OpenSSF evidence/gap-analysis docs, Diátaxis documentation structure,
+development-process docs, security docs, and the `gitleaks.yml` workflow.
+
+## Phase 1 — Maintainer decisions, no code change
+
+Status as of 2026-07-03:
+
+1. Apply branch protection on `main` (import the existing ruleset or configure
+   equivalently). **Still open.**
+2. ~~Confirm private vulnerability reporting is enabled.~~ **Done** — confirmed
+   already enabled via API.
+3. ~~Decide on the Dependabot security-updates toggle.~~ **Done** — enabled, along
+   with Dependabot vulnerability alerts.
+4. Merge or re-trigger release-please PR #1 to ship the first release. **Still open**
+   — deliberately left for the maintainer; triggers a real publish action.
+5. Register the repo/workflow as an npm trusted publisher on npmjs.com (the workflow
+   side is already implemented; this is the registry-side counterpart). **Still open**
+   — an npmjs.com-side action outside the repo.
+
+**Why this order:** branch protection and the first release are the two remaining
+changes that would flip the most `Missing`/`Partial` rows in the maturity report to
+`Passed` — they have outsized leverage relative to effort.
+
+## Phase 2 — Low-risk CI additions
+
+Status as of 2026-07-03:
+
+1. ~~Container image vulnerability scanning (Trivy or Grype) in `docker.yml`.~~
+   **Done** — Trivy added, advisory-only. It found real findings: see the new Phase 3
+   item below.
+2. Hadolint for Dockerfile linting. **Still open.**
+3. ~~`publint` as an advisory (non-blocking) npm packaging check.~~ **Done** — added,
+   passes cleanly against the built package.
+
+## Phase 3 — Security follow-through
+
+Status as of 2026-07-03:
+
+1. ~~Fix CodeQL alert #1 (High: clear-text logging in `scripts/start-chatgpt-http.mjs`).~~
+   **Done.**
+2. ~~Review and record disposition for the remaining 7 CodeQL alerts.~~ **Done** — all
+   dismissed via the code-scanning API with rationale re-verified against current code;
+   written up in `SECURITY_DECISIONS.md`.
+3. Re-evaluate Scorecard `publish_results: false` — either fix the blocking
+   `env:`/`defaults:` patterns across workflows, or adjust the README badge. **Still
+   open** — investigated; relocating those blocks across all 7 workflows risks
+   silently breaking the Windows Integration job's shell default, which can't be
+   verified without a live Windows Actions run.
+4. **New: triage the Trivy container-image backlog.** Adding Trivy in item 1 above
+   surfaced 50+ open findings against the built image — mostly the Alpine base image's
+   OpenSSL packages and npm/corepack's own bundled dependencies, not this project's own
+   code. Options: rebuild on a newer/slimmer base image, prune build tooling from the
+   final layer, or accept and document the current baseline explicitly.
+
+## Phase 4 — Community growth (not schedulable)
+
+1. Land a first externally-authored, human-reviewed pull request.
+2. Reconsider a second maintainer once Phase 4.1 has happened more than once — see
+   [GOVERNANCE.md](../GOVERNANCE.md#path-to-adding-maintainers).
+3. Revisit OpenSSF Silver readiness once Phase 4.1–4.2 give real evidence to point to.
+
+## What's explicitly not in this plan
+
+- No plan to pursue OpenSSF Gold/foundation-grade on any timeline — see
+  [docs/openssf-gap-analysis.md](openssf-gap-analysis.md) for why that's an
+  organizational precondition problem, not a checklist.
+- No plan to add PyPI, Go, or Rust packaging — none of those ecosystems are used by
+  this project.
+- No plan to add a `.devcontainer` — assessed as optional given the toolchain is
+  already a single `pnpm install` away from working.

package/docs/reference/README.md

@@ -0,0 +1,21 @@
+# Reference
+
+Reference material is information-oriented: precise, exhaustive where practical, and
+organized for lookup rather than reading start-to-finish. This index follows the
+[Diátaxis](https://diataxis.fr/reference/) definition of "reference."
+
+- [Environment variables](../../README.md#configuration) — the canonical
+  `SSH_MCP_*` configuration table lives in the README so it stays next to the
+  install/quickstart instructions; this reference doesn't duplicate it.
+- [Tool profiles](../../README.md#tool-profiles) — which tools/resources/prompts each
+  connector profile (`full`, `remote-safe`, `chatgpt`, `claude`, `remote-readonly`,
+  `remote-broker`) exposes.
+- [CLI reference](cli.md) — `ssh-mcp-pro` and `ssh-mcp-pro-agent` command-line flags.
+- [Configuration reference](configuration.md) — the `SSH_MCP_*` table grouped by
+  concern, pointing back to the canonical table in the README.
+- [Compatibility reference](compatibility.md) — supported Node.js/pnpm/OS/container
+  platforms and MCP transport/client compatibility.
+- [MCP metadata](../../mcp.json) and [server metadata](../../server.json) — machine-readable
+  capability and registry declarations.
+- [Security defaults](../../SECURITY_DECISIONS.md) — the exact default-deny behaviors and
+  why each exists.

package/docs/reference/cli.md

@@ -0,0 +1,41 @@
+# CLI Reference
+
+ssh-mcp-pro installs two binaries (see `bin` in [package.json](../../package.json)):
+
+- `ssh-mcp-pro` — the MCP server itself.
+- `ssh-mcp-pro-agent` — the remote control-plane agent (see
+  [docs/remote-mcp-hardening.md](../remote-mcp-hardening.md)).
+
+## `ssh-mcp-pro`
+
+Source of truth: [src/cli.ts](../../src/cli.ts).
+
+| Flag / subcommand | Effect |
+| --- | --- |
+| (no args) | Starts the server over stdio transport (default) |
+| `stdio` | Explicitly selects stdio transport |
+| `http` | Selects the Streamable HTTP transport |
+| `agent [...]` | Delegates all remaining arguments to the agent CLI (see below); consumes the rest of `argv` |
+| `--help`, `-h` | Print help and exit |
+| `--version`, `-v` | Print version and exit |
+| `--stdio` | Forces stdio transport |
+| `--transport=stdio` \| `--transport=http` | Explicit transport selection |
+| `--host <value>` | HTTP bind host (overrides `SSH_MCP_HTTP_HOST`) |
+| `--port <value>` | HTTP bind port (overrides `SSH_MCP_HTTP_PORT`) |
+| `--bearer-token-file <path>` | Bearer token file for HTTP auth (overrides `SSH_MCP_HTTP_BEARER_TOKEN_FILE`) |
+| `--enable-legacy-sse` | Enables legacy SSE compatibility (overrides `SSH_MCP_ENABLE_LEGACY_SSE`) |
+| `--tool-profile <name>` | Selects a tool exposure profile (overrides `SSH_MCP_TOOL_PROFILE`) — see [Tool Profiles](../../README.md#tool-profiles) |
+| `--connector-credential-provider <name>` | Selects a connector credential provider (overrides `SSH_MCP_CONNECTOR_CREDENTIAL_PROVIDER`) |
+| `--no-stdio` | Unsupported/internal flag; do not rely on it |
+
+Unknown flags are ignored rather than rejected, so that MCP clients invoking the binary
+with extra arguments don't break the server.
+
+## `ssh-mcp-pro-agent`
+
+Delegates directly to `src/remote/agent-cli.ts` via `argv` passthrough. See
+[docs/remote-mcp-hardening.md](../remote-mcp-hardening.md) and
+[docs/adding-a-device.md](../adding-a-device.md) for the documented agent workflows —
+this reference intentionally doesn't restate flags that aren't yet enumerated in one
+place in the source, to avoid documenting something that could drift silently from the
+implementation.

package/docs/reference/compatibility.md

@@ -0,0 +1,46 @@
+# Compatibility Reference
+
+## Node.js
+
+| Requirement | Value | Source |
+| --- | --- | --- |
+| Minimum supported range | `>=22.22.2 \|\| >=24.15.0 \|\| >=26.3.0` | `package.json` `engines.node` |
+| CI matrix | Node 22, 24, 26 (`Unit Tests (Node 22/24/26)`) | `.github/workflows/ci.yml` |
+| Local development / release builds | Node 24.15.0 / 26.3.0 | `CONTRIBUTING.md`, `release.yml` |
+
+Note the gap between 22.22.2 and 24.15.0: Node 23.x is not supported (it was never an
+LTS line). This is expected, not an oversight.
+
+## Package manager
+
+pnpm `11.28.5`, 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)).
+
+## Operating systems
+
+| OS | Status | Evidence |
+| --- | --- | --- |
+| Linux | Passed | Primary CI target; SSH fixture-based integration/E2E tests |
+| Windows command paths | Passed | Dedicated `test:integration:windows` project on `windows-2022`; the `Windows Command-Path Integration` job validates local PowerShell and package-manager dispatch, not a real Windows OpenSSH server |
+| macOS | Needs human confirmation | Listed as a supported platform in `mcp.json` (`platforms: [linux, macos, windows]`) but no macOS-specific CI job was found — likely covered incidentally by the cross-platform Node.js/SSH code paths, not by a dedicated test |
+
+## Container platforms
+
+`linux/amd64`, `linux/arm64` — built and verified in `docker.yml` via Buildx + QEMU.
+
+## MCP transport compatibility
+
+| Transport | Status |
+| --- | --- |
+| stdio | Passed — default, used by all documented client configs |
+| Streamable HTTP | Passed — `http`/`--transport=http`, with the non-loopback safety gate described in [SECURITY_DECISIONS.md](../../SECURITY_DECISIONS.md) |
+| Legacy SSE | Partial — available behind `SSH_MCP_ENABLE_LEGACY_SSE` for compatibility, not the recommended path |
+
+## MCP client compatibility
+
+Documented configs exist for a generic stdio client, VS Code, and Claude Desktop (see
+[README.md#quickstart](../../README.md#quickstart)) plus connector-shaped profiles for
+ChatGPT and Claude remote connectors (`chatgpt`, `claude` tool profiles). See
+[Tool Profiles](../../README.md#tool-profiles) for exactly what each profile exposes.

package/docs/reference/configuration.md

@@ -0,0 +1,72 @@
+# Configuration Reference
+
+The canonical, exhaustive `SSH_MCP_*` table lives in
+[README.md#configuration](../../README.md#configuration) and isn't duplicated here — a
+second copy of a 40+ row table would drift out of sync with the first. This page groups
+that table by concern, for when you know *what kind* of setting you need but not its
+exact name.
+
+## Session and resource limits
+
+`SSH_MCP_MAX_SESSIONS`, `SSH_MCP_SESSION_TTL`, `SSH_MCP_COMMAND_TIMEOUT`,
+`SSH_MCP_MAX_COMMAND_OUTPUT_BYTES`, `SSH_MCP_MAX_STREAM_CHUNKS`, `SSH_MCP_MAX_FILE_SIZE`,
+`SSH_MCP_MAX_FILE_WRITE_BYTES`, `SSH_MCP_MAX_TRANSFER_BYTES`.
+
+## SSH security policy
+
+`SSH_MCP_HOST_KEY_POLICY`, `SSH_MCP_KNOWN_HOSTS_PATH`, `SSH_MCP_ALLOW_ROOT_LOGIN`,
+`SSH_MCP_ALLOWED_CIPHERS`, `SSH_MCP_ALLOW_RAW_SUDO`, `SSH_MCP_ALLOW_DESTRUCTIVE_COMMANDS`,
+`SSH_MCP_ALLOW_DESTRUCTIVE_FS`, `SSH_MCP_ALLOWED_HOSTS`, `SSH_MCP_COMMAND_ALLOW`,
+`SSH_MCP_COMMAND_DENY`, `SSH_MCP_PATH_ALLOW_PREFIXES`, `SSH_MCP_PATH_DENY_PREFIXES`. See
+[docs/how-to/configure-ssh-policy.md](../how-to/configure-ssh-policy.md) for task-based
+guidance and [docs/security/threat-model.md](../security/threat-model.md) for why these
+defaults exist.
+
+## Local transfer and tunnel policy
+
+`SSH_MCP_LOCAL_PATH_ALLOW_PREFIXES`, `SSH_MCP_LOCAL_PATH_DENY_PREFIXES`,
+`SSH_MCP_TUNNEL_ALLOW_BIND_HOSTS`, `SSH_MCP_TUNNEL_DENY_BIND_HOSTS`,
+`SSH_MCP_TUNNEL_ALLOW_REMOTE_HOSTS`, `SSH_MCP_TUNNEL_DENY_REMOTE_HOSTS`,
+`SSH_MCP_TUNNEL_ALLOW_PORTS`, `SSH_MCP_TUNNEL_DENY_PORTS`.
+
+## Policy engine
+
+`SSH_MCP_POLICY_FILE`, `SSH_MCP_POLICY_MODE` — a JSON policy file plus enforce/explain
+mode, for centralizing the settings above instead of many separate environment
+variables. No config-schema version field currently exists for the policy file (see
+[docs/development/api-stability.md](../development/api-stability.md)).
+
+## HTTP transport
+
+`SSH_MCP_HTTP_HOST`, `SSH_MCP_HTTP_PORT`, `SSH_MCP_HTTP_ALLOWED_ORIGINS`,
+`SSH_MCP_HTTP_BEARER_TOKEN_FILE`, `SSH_MCP_ENABLE_LEGACY_SSE`,
+`SSH_MCP_HTTP_MAX_REQUEST_BODY_BYTES`, `SSH_MCP_HTTP_MAX_SESSIONS`,
+`SSH_MCP_HTTP_SESSION_IDLE_TTL_MS`, `SSH_MCP_HTTP_PUBLIC_URL`,
+`SSH_MCP_HTTP_TRUST_PROXY`. See [docs/remote-mcp-hardening.md](../remote-mcp-hardening.md).
+
+## OAuth (HTTP auth mode)
+
+`SSH_MCP_HTTP_AUTH_MODE`, `SSH_MCP_OAUTH_ISSUER`, `SSH_MCP_OAUTH_AUDIENCE`,
+`SSH_MCP_OAUTH_JWKS_URL`, `SSH_MCP_OAUTH_RESOURCE`, `SSH_MCP_OAUTH_REQUIRED_SCOPES`,
+`SSH_MCP_OAUTH_ALLOWED_ALGORITHMS`.
+
+## Remote agent WebSocket boundary
+
+`AGENT_WS_PATH`, `AGENT_WS_HELLO_TIMEOUT_MS`, `AGENT_WS_HEARTBEAT_INTERVAL_MS`,
+`AGENT_WS_IDLE_TIMEOUT_MS`, `AGENT_WS_MAX_CONNECTIONS`,
+`AGENT_WS_MAX_CONNECTIONS_PER_AGENT`, `MAX_ACTION_TIMEOUT_SECONDS`,
+`MAX_OUTPUT_BYTES`. The idle timeout is normalized to at least two heartbeat intervals.
+See [docs/remote-mcp-hardening.md](../remote-mcp-hardening.md) for operational guidance.
+
+## Tool exposure and connectors
+
+`SSH_MCP_TOOL_PROFILE` / `SSH_MCP_CONNECTOR_PROFILE`,
+`SSH_MCP_CONNECTOR_CREDENTIAL_PROVIDER`, `SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND`,
+`SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND_ARGS`,
+`SSH_MCP_CONNECTOR_CREDENTIAL_COMMAND_TIMEOUT_MS`,
+`SSH_MCP_CONNECTOR_DEFAULT_USERNAME`, `SSH_MCP_REMOTE_AGENT_MCP_PASSTHROUGH`. See
+[Tool Profiles](../../README.md#tool-profiles) for what each profile exposes.
+
+## Misc
+
+`SSH_MCP_DEBUG`, `SSH_MCP_RATE_LIMIT*` (global and per-session rate limiting).

package/docs/remote-mcp-hardening.md

@@ -0,0 +1,59 @@
+# Remote MCP hardening
+
+Use this checklist before exposing `ssh-mcp-pro` through a public Streamable HTTP MCP endpoint.
+
+## Streamable HTTP session resilience
+
+- Keep `SSH_MCP_HTTP_SESSION_IDLE_TTL_MS` low enough for connector workloads that may abandon sessions without sending HTTP `DELETE`. A practical production value for ChatGPT/Cloudflare deployments is `300000`.
+- Raise `SSH_MCP_HTTP_MAX_SESSIONS` above the expected burst of connector initializations. A practical production value for ChatGPT/Cloudflare deployments is `100`.
+- The HTTP session registry cleans expired sessions before opening a new session. If capacity is still full, it evicts the oldest idle session with reason `capacity-evict-oldest` instead of returning a persistent 503 that can surface as an upstream 502.
+- Watch logs for `HTTP MCP session removed`, `idle-timeout`, and `capacity-evict-oldest` to confirm cleanup is happening.
+
+## Remote agent WebSocket lifecycle
+
+- Keep `AGENT_WS_HELLO_TIMEOUT_MS` short enough that unauthenticated sockets cannot remain open indefinitely. The default is `10000` milliseconds.
+- `AGENT_WS_MAX_CONNECTIONS` bounds all accepted agent WebSockets, including connections still waiting for `agent.hello`. The default is `128`.
+- `AGENT_WS_MAX_CONNECTIONS_PER_AGENT` bounds active and replacement candidates for one enrolled agent. The default is `2`, which permits one live connection and one authenticated replacement attempt.
+- `AGENT_WS_HEARTBEAT_INTERVAL_MS` defaults to `30000`. The server sends protocol pings and treats pong or text traffic as activity.
+- `AGENT_WS_IDLE_TIMEOUT_MS` defaults to `90000` and is normalized to at least two heartbeat intervals. Idle connections close cleanly and are forcibly terminated if the close handshake does not complete.
+- The `/readyz` response reports `agent_connections_open` and `agent_connections_unauthenticated`. Audit events record global/per-agent capacity rejection, hello timeout, idle timeout, replacement, and safe numeric close codes.
+- Keep WebSocket compression disabled at the public boundary. Agent messages are text-only and capped at 1 MiB.
+
+## OAuth and token verification
+
+- Prefer OAuth mode for public endpoints.
+- Configure `SSH_MCP_OAUTH_ISSUER`, `SSH_MCP_OAUTH_JWKS_URL`, and either `SSH_MCP_OAUTH_AUDIENCE` or `SSH_MCP_OAUTH_RESOURCE` explicitly.
+- Use `SSH_MCP_OAUTH_ALLOWED_ALGORITHMS` to pin accepted JWT algorithms when your authorization server has a stable signing policy.
+- Keep `SSH_MCP_OAUTH_REQUIRED_SCOPES` narrow and environment-specific.
+- Confirm unauthorized `/mcp` requests return `401` with `WWW-Authenticate` metadata discovery headers.
+
+## Connector routing
+
+- Keep `SSH_MCP_REMOTE_AGENT_MCP_PASSTHROUGH` disabled by default.
+- Enable it only during a controlled remote-agent routing migration where `/mcp` must bypass the remote control plane and reach the Streamable HTTP MCP handler.
+- Remove the switch again after the routing migration is complete.
+
+## Tool exposure
+
+- Prefer `remote-safe`, `remote-readonly`, or `remote-broker` profiles for public connectors.
+- Require a host allowlist for public endpoints.
+- Keep credential entry in chat disabled; use the credential broker or SSH agent instead.
+- Keep destructive filesystem and command policies disabled unless the environment has an explicit change-control process.
+
+## Packaging and repository hygiene
+
+- Never commit local bearer tokens, private keys, or generated credential files.
+- Keep local credential directories ignored by Git.
+- Run the full push gate before merging changes that affect remote connector behavior:
+
+```bash
+pnpm run format:check
+pnpm run lint
+pnpm run typecheck
+pnpm test
+pnpm run build
+pnpm run audit
+pnpm run validate:mcp-metadata
+pnpm run validate:chatgpt-app
+pnpm run validate:claude-connector
+```