ssh-mcp-pro 1.1.5 → 1.2.1

package/docs/development/api-stability.md

@@ -0,0 +1,44 @@
+# API Stability
+
+This project has never made an explicit stability statement before this document. It's
+written now to describe intent going forward, not to claim a history of enforcement
+that doesn't exist — see [docs/repo-maturity-report.md](../repo-maturity-report.md)
+("API/CLI stability") for the audit that identified this gap.
+
+## What is considered "the public API"
+
+For SemVer purposes, going forward:
+
+1. **MCP tool/resource/prompt schemas** exposed by the `full` profile — names, required
+   parameters, and result shapes. Covered by `test/unit/mcp-contract.test.ts`.
+2. **CLI flags** in `docs/reference/cli.md` (mirrors `src/cli.ts`).
+3. **`SSH_MCP_*` environment variables** and their default values.
+4. **The two published binaries' existence and basic invocation** (`ssh-mcp-pro`,
+   `ssh-mcp-pro-agent`).
+
+## What is explicitly not covered
+
+- Internal module structure under `src/` (anything not re-exported).
+- Exact wording of error messages and log lines.
+- The shape of `SSH_MCP_POLICY_FILE` beyond what's documented — see the config-schema
+  gap noted in the maturity report; this will need its own versioning story before it
+  can be a stability guarantee.
+- Tool profiles *other than* `full` gaining new tools without a version bump — adding a
+  tool to a restricted profile is additive from that profile's consumer's perspective,
+  but is still called out here as unresolved: **Needs human confirmation** on whether
+  profile membership changes should be treated as SemVer-significant.
+
+## What counts as breaking
+
+Per Conventional Commits (`!` / `BREAKING CHANGE:` — see
+[commit-conventions.md](commit-conventions.md)): removing or renaming a tool/flag/env
+var, changing a tool's required parameters, changing a default value that changes
+security posture (e.g. flipping a deny-by-default to allow-by-default), or removing a
+supported Node.js version ahead of its own EOL.
+
+## Current honest caveat
+
+The project is on `1.x` but is 5 days old with zero external consumers on record. This
+policy is aspirational until it's been exercised against a real breaking change and a
+real major version bump — that will be the first real test of whether this document
+holds up in practice.

package/docs/development/coding-standards.md

@@ -0,0 +1,35 @@
+# Coding Standards
+
+This is a reference index, not a new rulebook — every rule below is already enforced by
+a config file or CI job. It exists so "what are the coding standards" has one answer
+instead of requiring a tour of five config files.
+
+| Concern | Enforced by | Command |
+| --- | --- | --- |
+| Formatting | [.prettierrc.json](../../.prettierrc.json), [.editorconfig](../../.editorconfig) | `pnpm run format:check` |
+| Linting | [eslint.config.mjs](../../eslint.config.mjs) | `pnpm run lint` |
+| Type safety | [tsconfig.json](../../tsconfig.json) (`strict` mode) | `pnpm run typecheck` |
+| Module size | [scripts/check-module-size.mjs](../../scripts/check-module-size.mjs) | `pnpm run check:module-size` |
+| Circular dependencies | [.dependency-cruiser.mjs](../../.dependency-cruiser.mjs) | `pnpm run check:circular` |
+| Unused code/exports | [knip.jsonc](../../knip.jsonc) | `pnpm run check:knip` |
+| Commit messages | [.commitlintrc.json](../../.commitlintrc.json) | see [commit-conventions.md](commit-conventions.md) |
+| Documentation prose | [scripts/check-doc-language.mjs](../../scripts/check-doc-language.mjs) | `pnpm run check:doc-language` |
+
+Run everything at once with `pnpm run check:maintainability` (module size + circular
+deps + unused exports) or `pnpm run check:quality` (formatting, lint, typecheck, audit,
+licenses, and more — see [CONTRIBUTING.md](../../CONTRIBUTING.md) for the full gate).
+
+## Security-sensitive code
+
+Files covered by [.github/CODEOWNERS](../../.github/CODEOWNERS) (`src/safety.ts`,
+`src/session.ts`, `src/logging.ts`, `src/tools/`) and the mutation-tested surfaces listed
+in [testing-policy.md](testing-policy.md) receive extra scrutiny. Changes there should
+be justified against [SECURITY_DECISIONS.md](../../SECURITY_DECISIONS.md), not just
+against passing tests.
+
+## Pre-commit / pre-push hooks
+
+[.pre-commit-config.yaml](../../.pre-commit-config.yaml) and the git hooks installed by
+`scripts/setup-git-hooks.mjs` (run automatically via the `prepare` npm script) run a
+subset of the above on staged files before commit, and the full `check:push` gate before
+push. See [CONTRIBUTING.md](../../CONTRIBUTING.md#git-hooks) for details.

package/docs/development/commit-conventions.md

@@ -0,0 +1,35 @@
+# Commit Conventions
+
+ssh-mcp-pro uses [Conventional Commits](https://www.conventionalcommits.org/), enforced
+by [.commitlintrc.json](../../.commitlintrc.json) and
+[scripts/lint-commits.mjs](../../scripts/lint-commits.mjs) (`pnpm run lint:commits`).
+PR titles are additionally linted by
+[scripts/lint-pr-title.mjs](../../scripts/lint-pr-title.mjs) (`pnpm run lint:pr-title`),
+since release-please derives the changelog and version bump from these.
+
+## Format
+
+```
+<type>[optional !][: ]<description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Types in use
+
+`feat`, `fix`, `docs`, `test`, `refactor`, `build`, `ci`, `chore` — see
+[CONTRIBUTING.md](../../CONTRIBUTING.md) for the authoritative list and examples.
+
+## Breaking changes
+
+Mark with `!` after the type (e.g. `feat!:`) or a `BREAKING CHANGE:` footer.
+Release-please uses this to trigger a major version bump and a distinct CHANGELOG
+section — see [docs/development/release-process.md](release-process.md) and
+[MIGRATION.md](../../MIGRATION.md).
+
+## Branch naming
+
+`feature/*`, `fix/*`, `docs/*`, `chore/*` (and project-specific prefixes such as
+`codex/SSH-*`) — see [CONTRIBUTING.md](../../CONTRIBUTING.md) for current conventions.

package/docs/development/dependency-management.md

@@ -0,0 +1,60 @@
+# Dependency Management
+
+## Two update bots, two ecosystems, by design
+
+- **[renovate.json](../../renovate.json)** manages the `npm` ecosystem (production and
+  dev dependencies). Patch/minor devDependency updates automerge; the MCP SDK
+  (`@modelcontextprotocol/sdk`) is explicitly excluded from automerge given how central
+  it is; typescript-eslint packages are grouped.
+- **[.github/dependabot.yml](../../.github/dependabot.yml)** manages the
+  `github-actions` ecosystem only, weekly, capped at 5 open PRs.
+
+npm dependencies are deliberately **not** duplicated into `dependabot.yml` — running two
+bots against the same ecosystem tends to produce competing PRs for the same bump. If
+you're looking for why Dependabot doesn't also open npm PRs, this is why; it's a design
+choice, not an oversight (see the corresponding row in
+[docs/repo-maturity-report.md](../repo-maturity-report.md)).
+
+## Vulnerability response
+
+- `pnpm audit --audit-level moderate` (the `audit` script) runs as part of
+  `check:quality`.
+- The `Dependency Review` job in [ci.yml](../../.github/workflows/ci.yml) is the single
+  canonical dependency review for pull requests. It uses
+  `dependency-review-action` with `fail-on-severity: moderate`, so a newly introduced
+  advisory rated moderate, high, or critical blocks the pull request. A second standalone
+  dependency-review workflow is intentionally not used because duplicate checks can apply
+  contradictory thresholds and create ambiguous merge signals.
+- The same job enforces the repository license allowlist. The allowlist is kept identical
+  to [scripts/check-licenses.mjs](../../scripts/check-licenses.mjs) by a regression test;
+  changing either policy requires a reviewed pull request that updates both surfaces.
+- GitHub Dependabot alerts (vulnerability scanning, distinct from the version-update
+  bot config above) apply automatically on a public GitHub repository. Whether
+  "Dependabot security updates" (automatic fix PRs) is enabled is a repository Settings
+  toggle — see the manual actions list in the maturity report.
+
+### Published artifact verification
+
+`pnpm run audit:packed` installs the generated npm tarball in a clean consumer project
+and audits the resolved production graph without inheriting workspace overrides. Any
+remaining finding must match the machine-readable, time-bounded policy in
+[dependency-audit-exceptions.json](../security/dependency-audit-exceptions.json) and the
+public rationale in [Dependency Audit Exceptions](../security/dependency-audit-exceptions.md).
+Unexpected, expired, or stale exceptions fail the package gate.
+
+## License compliance
+
+[scripts/check-licenses.mjs](../../scripts/check-licenses.mjs) enforces an allowlist
+(MIT, Apache-2.0, BSD-2/3-Clause, BlueOak-1.0.0, CC-\*, ISC, Python-2.0, Unlicense)
+against every resolved dependency, run via `pnpm run licenses:check` as part of
+`check:quality`.
+
+## Freshness (advisory)
+
+`pnpm run check:freshness` (`scripts/check-dependency-freshness.mjs`) compares the
+pinned Node.js floor, pnpm version, and dependency versions against upstream metadata,
+producing `artifacts/dependency-freshness.{json,md}`. It's advisory unless a pinned
+version is unsupported, EOL, deprecated, or vulnerable — see
+[CONTRIBUTING.md](../../CONTRIBUTING.md) for the exact policy and
+[docs/audit/2026-06-05-ecosystem-audit.md](../audit/2026-06-05-ecosystem-audit.md) for
+the most recent full audit.

package/docs/development/deprecation-policy.md

@@ -0,0 +1,29 @@
+# Deprecation Policy
+
+No formal deprecation has ever happened in this project's history (it's 5 days old at
+time of writing), so this document states intent, not a track record — consistent with
+[docs/development/api-stability.md](api-stability.md).
+
+## Policy going forward
+
+1. **Announce before removing.** A deprecated tool, flag, or environment variable is
+   marked as such in `CHANGELOG.md` and, where feasible, the tool/flag continues to
+   function with a warning for at least one minor release before removal.
+2. **Removal is a breaking change.** Per
+   [docs/development/api-stability.md](api-stability.md), actual removal happens in a
+   major version bump, using Conventional Commits' `!`/`BREAKING CHANGE:` convention.
+3. **Security-driven deprecation is the exception.** If a default or feature is found
+   to be actively unsafe (not just superseded), it may be deprecated and disabled faster
+   than the normal window, with the rationale documented in
+   [SECURITY_DECISIONS.md](../../SECURITY_DECISIONS.md) — safety takes priority over the
+   standard notice period.
+4. **`MIGRATION.md` is the landing page** for any deprecation that requires action from
+   users upgrading between versions.
+
+## What this policy does not yet cover
+
+- A specific minimum notice period (e.g. "one minor version" vs. "90 days") — left
+  unspecified until there's a real deprecation to calibrate against.
+- Deprecation of MCP tool schema fields specifically (as opposed to whole tools) — see
+  the open question in [docs/development/api-stability.md](api-stability.md) about
+  whether profile/schema changes are SemVer-significant.

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,57 @@
+# Release Process
+
+## Versioning
+
+Semantic Versioning, automated by [release-please](https://github.com/googleapis/release-please)
+per [release-please-config.json](../../release-please-config.json) (`node` release
+type). Conventional Commit types on `main` (see
+[commit-conventions.md](commit-conventions.md)) drive whether the next release is a
+patch, minor, or major bump.
+
+## How a release happens
+
+1. Conventional commits land on `main`.
+2. The `release` job in [.github/workflows/release.yml](../../.github/workflows/release.yml)
+   runs `googleapis/release-please-action`, which opens or updates a release PR
+   (updating `CHANGELOG.md`, `.release-please-manifest.json`, and the version fields
+   release-please is configured to touch — see `extra-files` in
+   `release-please-config.json`, which includes `mcp.json`, `server.json`, and the MCP
+   registry record).
+3. Merging that PR triggers `release_created`, which runs the `release-assets` job:
+   - `pnpm run check` (full quality gate) must pass.
+   - `pnpm run sbom` generates a CycloneDX SBOM.
+   - The package is packed with `pnpm pack`, and both the tarball and the SBOM get a
+     `sha256sum` checksum file.
+   - `actions/attest-build-provenance` runs twice — once for the package, once for the
+     SBOM — producing verifiable build provenance attestations.
+   - All artifacts (tarball, SBOM, checksums) are attached to the GitHub Release.
+   - npm publish only happens if the repository variable `AUTO_RELEASE_PUBLISH` is
+     `"true"`; otherwise the step is a documented no-op ("npm publishing is disabled by
+     AUTO_RELEASE_PUBLISH").
+
+## Verifying a release artifact
+
+```bash
+sha256sum -c ssh-mcp-pro-<version>.tgz.sha256
+```
+
+For provenance, use [GitHub CLI attestation verification](https://cli.github.com/manual/gh_attestation_verify):
+
+```bash
+gh attestation verify ssh-mcp-pro-<version>.tgz --owner oaslananka
+```
+
+See [docs/security/release-integrity.md](../security/release-integrity.md) for the full
+supply-chain rationale.
+
+## Current status
+
+No release has been published yet (repository created 2026-06-28). Release PR #1
+(`chore(main): release ssh-mcp-pro 1.2.0`) is open and is the first opportunity to
+exercise this pipeline end-to-end — see [ROADMAP.md](../../ROADMAP.md).
+
+## Container images
+
+Published separately by [.github/workflows/docker.yml](../../.github/workflows/docker.yml)
+on tagged releases; see [docs/docker.md](../docker.md) for tag policy and digest-pinned
+usage.

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/>