ssh-mcp-pro 1.1.5 → 1.2.3

package/docs/development/local-setup.md

@@ -0,0 +1,46 @@
+# Local Setup
+
+The authoritative setup steps are in
+[CONTRIBUTING.md#setup](../../CONTRIBUTING.md#setup) — this page doesn't duplicate them,
+it adds the one-command shortcuts.
+
+## Fastest path
+
+```bash
+git clone https://github.com/oaslananka/ssh-mcp-pro.git
+cd ssh-mcp-pro
+task install   # or: corepack enable && corepack prepare pnpm@11.5.1 --activate && pnpm install --frozen-lockfile
+task verify    # lint + format:check + typecheck + test + build
+```
+
+[Taskfile.yml](../../Taskfile.yml) wraps the same pnpm scripts CONTRIBUTING.md documents
+— use whichever you prefer; there is no behavioral difference between `task lint` and
+`pnpm run lint`.
+
+## What `pnpm run prepare` does
+
+Configures `core.hooksPath=.githooks` so pre-commit/pre-push hooks
+(`pnpm run hook:pre-commit`, `pnpm run hook:pre-push`) run automatically. This runs
+automatically after `pnpm install` via the `prepare` script — you don't need to invoke
+it manually unless hooks stop working.
+
+## Docker-based integration tests
+
+Integration/E2E tests exercise a real SSH fixture via Docker, not a mock:
+
+```bash
+pnpm run docker:ssh-fixture:up
+pnpm run test:integration
+pnpm run docker:ssh-fixture:down
+```
+
+See [docker-compose.yml](../../docker-compose.yml) and
+[Dockerfile.test](../../Dockerfile.test).
+
+## No `.devcontainer` (by design, for now)
+
+This repo doesn't ship a `.devcontainer/`. Given the toolchain is one `pnpm install`
+away from working and Docker is only needed for integration tests, this was assessed as
+optional rather than required — see "Developer experience maturity" in
+[docs/repo-maturity-report.md](../repo-maturity-report.md). Revisit if Windows/macOS
+contributors report toolchain friction that a devcontainer would solve.

package/docs/development/release-process.md

@@ -0,0 +1,31 @@
+# Release Process
+
+## Prepare a version
+
+Release Please v5 prepares Conventional Commit-driven version updates on `main`. A release PR updates `CHANGELOG.md`, package, registry metadata, client readiness metadata and embedded version strings together. Merge a release PR only after the normal protected-branch checks pass.
+
+When an unreleased version reaches `main`, the `Release` workflow preflights the **frozen dependency installation, full quality check, dependency freshness, package build, SBOM, checksums and GitHub artifact attestations** before Release Please creates the tag. It then attaches that exact prebuilt package and SBOM to the GitHub Release and dispatches an immutable-tag GHCR build. Ordinary main pushes without a new version do not repeat the heavy preflight.
+
+## One-click npm publication
+
+**Actions → Release → Run workflow → main → Run workflow** is the **manual npm publish button**. No extra version input, stage job or automatic npm publish on release PR merge is involved.
+
+The `Publish current GitHub Release to npm` job identifies the `package.json` version on `main`, locates its immutable GitHub Release, downloads the already-built `.tgz` and checksum, verifies the tag's source/version, checks SHA-256, package metadata and the GitHub attestation, then calls **`npm publish` directly with GitHub-hosted Actions OIDC**. A version already public on npm is not published twice. After confirming that exact npm version is public, it dispatches the matching MCP Registry publication job. npm Trusted Publisher must authorize `.github/workflows/release.yml` and permit **direct publication**, not stage-only. This is a provider-side prerequisite, not a second GitHub workflow.
+
+GitHub does not override npm account/package security settings. If the npm publisher is configured for stage-only access or another mandatory owner restriction, the direct publish job fails clearly instead of silently staging or bypassing security. Avoid publishing historical versions to work around an npm account restriction; repair the publisher configuration through authorized account settings.
+
+## GHCR and MCP Registry
+
+The release workflow triggers `.github/workflows/docker.yml` with the immutable `ssh-mcp-pro-vX.Y.Z` tag. GHCR must grant this repository's GitHub Actions **Write** access to the existing `ghcr.io/oaslananka/ssh-mcp-pro` package. Package access is managed through **GitHub Packages → Package settings → Manage Actions access**. Docker publishing verifies the release tag and package version before pushing both platform tags.
+
+The MCP Registry job requires an existing GitHub Release and the *same publicly visible npm version*. It skips versions already registered and uses GitHub OIDC. There is no daily staged-publication reconciliation job. The manual npm publish workflow dispatches the MCP Registry publication only after npm confirms the version is public.
+
+## Verify and troubleshoot
+
+- `gh release view ssh-mcp-pro-vX.Y.Z --json assets` — the prepared GitHub Release.
+- `gh run list --workflow release.yml` — release preparation and manual npm publication status.
+- `npm view ssh-mcp-pro@X.Y.Z version` — independently verify actual npm publication.
+- `gh run list --workflow docker.yml` and `gh api users/oaslananka/packages/container/ssh-mcp-pro` — GHCR status.
+- `gh run list --workflow publish-mcp-registry.yml` — MCP Registry publication.
+
+Do not confuse a successful GitHub Release (or npm production environment deployment event) with a successful public npm/GHCR publication. Check the actual registry records before announcing an ecosystem release.

package/docs/development/testing-policy.md

@@ -0,0 +1,47 @@
+# Testing Policy
+
+## Test layers
+
+Defined in [vitest.config.ts](../../vitest.config.ts) as separate projects:
+
+| Project | Location | Run with |
+| --- | --- | --- |
+| Unit | `test/unit/**` | `pnpm test` |
+| Integration | `test/integration/**` | `pnpm run test:integration` |
+| Windows command-path integration | `test/integration/windows-ssh.integration.test.ts` | `pnpm run test:integration:windows` |
+| E2E | `test/e2e/**` | `pnpm run test:e2e` |
+| Performance | `test/perf/**` | `pnpm run test:perf` (baseline: `test:perf:baseline`) |
+
+Integration and E2E projects run sequentially (single worker, no file parallelism) —
+they exercise a real SSH fixture (see `scripts/docker-ssh-fixture.mjs` and
+[docker-compose.yml](../../docker-compose.yml)) and aren't safe to parallelize against
+shared fixture state. Protected CI verifies the Docker fixture before each Linux suite and then checks the generated JUnit report to ensure the env-gated tests executed instead of being silently skipped. Failure runs retain sanitized container state, fixture logs, and JUnit evidence for 14 days.
+
+The `Windows Command-Path Integration` job executes PowerShell-capable command selection and Windows package-manager paths locally on a Windows runner. It does not claim a network connection to a real Windows OpenSSH server.
+
+## Coverage policy
+
+`pnpm run test:coverage` enforces the thresholds in `vitest.config.ts`: 85% branches,
+85% functions, 90% lines, 90% statements repo-wide, with a scoped 75/80/85/85 threshold
+for `src/remote/**` (the remote control-plane surface, which has more integration-only
+paths that are harder to unit-test in isolation). These thresholds are a CI gate, not a
+suggestion — `check:quality`'s downstream `check` script fails the build below them.
+
+## Mutation testing
+
+`pnpm run test:mutation` runs [Stryker](../../stryker.conf.mjs) against specific line
+ranges in the highest-consequence files: `auth.ts`, `policy.ts`, `safety.ts`,
+`config.ts`, `session.ts`, `http-security.ts`, `oauth.ts`, and the `remote/*` control
+plane. Thresholds are 80% mutation score to be considered healthy, 60% as the floor
+(`break: null`, i.e. advisory rather than a hard CI failure today). See
+[docs/testing.md](../testing.md) for the rationale behind the line-range allowlist and
+promotion criteria for adding more files to it.
+
+## What a PR is expected to include
+
+Per [CONTRIBUTING.md](../../CONTRIBUTING.md): new functionality needs accompanying
+tests, and `pnpm run check` (which includes `test:coverage`) must pass before a PR is
+considered ready. There is currently no CI gate that *requires* a human reviewer's
+approval before merge (see the branch-protection gap in
+[docs/repo-maturity-report.md](../repo-maturity-report.md)) — treat the automated gate
+as necessary, not sufficient.

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.