Production-readiness audit: security/resilience fixes, coverage tools, template-inheritance guidance

.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  # npm dependency updates (the published package + dev toolchain).
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    open-pull-requests-limit: 10
+    groups:
+      dev-dependencies:
+        dependency-type: 'development'
+
+  # Keep GitHub Actions pinned versions current.
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    open-pull-requests-limit: 5

.github/workflows/ci.yml

@@ -63,6 +63,11 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - name: Dependency audit (advisory)
+        # Surfaces known-vulnerable dependencies. Advisory for now (does not fail
+        # the build); promote to a hard gate once the tree is clean.
+        run: bun audit --audit-level=high || true
+
       - name: Format check
         run: bun run format:check
 
@@ -78,8 +83,8 @@ jobs:
       - name: Verify API truth
         run: bun run verify:truth
 
-      - name: Test
-        run: bun run test
+      - name: Test (with coverage gate)
+        run: bun run test:coverage
 
       - name: Scenario suite
         run: bun run test:scenarios

.nvmrc

@@ -0,0 +1 @@
+22

CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Thanks for contributing to `@evertrust/stream-mcp`.
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) 1.x (the project's package manager and test runner) or
+  Node.js >= 22.19.
+- Access to an Evertrust Stream 2.1 instance for the optional live/E2E tiers.
+
+See [docs/development.md](docs/development.md) for the full development guide
+(architecture, the route-truth check, and the test tiers).
+
+## Workflow
+
+1. Branch off `main`.
+2. Make your change with a test. The project uses test-driven development; new
+   behavior needs unit tests and, where it touches the wire contract, a note in
+   `docs/audit/<domain>.md`.
+3. Run the full local gate before opening a PR:
+
+   ```bash
+   bun run validate:ci
+   ```
+
+   This runs format, lint, typecheck, build, the API route-truth check, the unit
+   suite, and the deterministic scenario suite.
+4. Open a PR. CI re-runs the gate and (when QA secrets are available) a read-only
+   E2E smoke test.
+
+## Conventional commits
+
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
+(`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `ci:`, `perf:`).
+Releases are automated by semantic-release from the commit history, so the type
+and scope matter.
+
+## Code style
+
+- TypeScript, ESM, strict mode. Prefer many small, focused modules.
+- Immutable data: return new objects rather than mutating inputs.
+- Never log or return secret material; route reads that may carry secrets through
+  the redaction helpers.
+- Every interpolated path segment must be URL-encoded (`encodePathSegment`).
+
+## Security
+
+Please report vulnerabilities privately - see [SECURITY.md](SECURITY.md).

README.md

@@ -12,7 +12,7 @@ Most MCP servers hand an LLM a list of tools and leave it to figure out the doma
 
 ## Features
 
-- **153 tools across 13 domains**, each annotated with a safety tier (`read-only`, `idempotent`, `additive`, `destructive`) surfaced as MCP tool annotations.
+- **157 tools across 13 domains**, each annotated with a safety tier (`read-only`, `idempotent`, `additive`, `destructive`) surfaced as MCP tool annotations.
 - **Knowledge catalog**: 15 topic URIs (with auto-generated section URIs for the longer guides) plus `search_docs` / `get_doc` tools.
 - **Two authentication modes**: local account (API headers) and mutual TLS (PEM or PKCS#12). No OIDC.
 - **Query languages**: SCQL (Stream Certificates Query Language) for certificate search/aggregate and SEQL (Stream Events Query Language) for the audit log, documented in `stream://knowledge/query-languages`.
@@ -25,14 +25,14 @@ Tool counts per domain:
 
 | Domain                          | Tools | Highlights                                                                 |
 | ------------------------------- | ----: | ------------------------------------------------------------------------- |
-| Access control & identity       |    27 | roles, local identities, identity providers, credentials, `whoami`        |
+| Access control & identity       |    28 | roles, local identities, identity providers, credentials, `whoami`        |
 | System management               |    19 | config, HTTP proxies, queues, license, dictionaries, AsciiDoc export      |
-| OpenSSH (SSH module)            |    19 | SSH CAs, templates, certificate search/enroll/revoke, KRLs                 |
+| OpenSSH (SSH module)            |    20 | SSH CAs, templates, certificate search/enroll/revoke, KRLs                 |
 | Timestamping (TSA)             |    16 | TSA authorities, signers (+ CSR), NTP clients                             |
 | Utilities & decoders            |    14 | X.509/CSR/CRL/PKCS#12/OpenSSH decoders, trust chains, EKUs                 |
 | X.509 certificate authorities   |    12 | create-from-scratch, import, CSR, issue, enhance, migrate, CRL upload      |
 | Cryptographic storage           |    12 | keystores (software/PKCS#11/AWS/Azure/GCP), keys, HSM introspection        |
-| Revocation (CRL & OCSP)        |    10 | CRL info, OCSP signers (+ CSR), assign-signer-to-CA                        |
+| Revocation (CRL & OCSP)        |    12 | CRL info + published CRL/AIA fetch, OCSP signers (+ CSR), assign-to-CA     |
 | X.509 certificates & lifecycle  |     6 | SCQL search/aggregate, enroll, revoke, requestable templates              |
 | Triggers & notifications        |     6 | email / REST notifications, expiration triggers, dry-run test             |
 | X.509 certificate templates     |     5 | issuance-profile CRUD                                                      |
@@ -43,7 +43,7 @@ Full per-tool table with safety tiers in [docs/tools-reference.md](docs/tools-re
 
 ## Prerequisites
 
-- [Bun](https://bun.sh/) 1.x+ (recommended) or Node.js >= 24.10
+- [Bun](https://bun.sh/) 1.x+ (recommended) or Node.js >= 22.19
 - An Evertrust Stream 2.1 instance
 - A local account (username/password) or a client certificate for that instance
 
@@ -69,6 +69,13 @@ bun run build
 node dist/index.js
 ```
 
+### Option 3 - prebuilt standalone binary
+
+Each GitHub release attaches self-contained binaries (no Node/Bun required) for
+Linux (x64/arm64), macOS (x64/arm64), and Windows (x64). Download the one for
+your platform from the [Releases](https://github.com/evertrust/stream-mcp/releases)
+page, make it executable, and run it directly.
+
 The server speaks MCP over **stdio** - it is normally launched by an MCP client rather than run by hand (see [MCP client setup](#mcp-client-setup)).
 
 ## Configuration
@@ -180,7 +187,7 @@ See [docs/authentication.md](docs/authentication.md) for the full step-by-step g
 
 ## Tool catalog overview
 
-The 153 tools are grouped into 13 domains. Each tool ships with explicit guidance for smaller models and clearly distinguishes mandatory from optional inputs. The table above lists per-domain counts; [docs/tools-reference.md](docs/tools-reference.md) has the full per-tool table with safety tiers and one-line descriptions.
+The 157 tools are grouped into 13 domains. Each tool ships with explicit guidance for smaller models and clearly distinguishes mandatory from optional inputs. The table above lists per-domain counts; [docs/tools-reference.md](docs/tools-reference.md) has the full per-tool table with safety tiers and one-line descriptions.
 
 Knowledge resources are exposed at `stream://knowledge/*` URIs. See [docs/knowledge-resources.md](docs/knowledge-resources.md) for the full catalog.
 
@@ -292,9 +299,8 @@ Create a local account for a new operator and return its one-time password.
 ## What is not supported
 
 - **OIDC sign-in for the MCP server** - only local-account and mTLS auth are supported (OIDC providers can be *managed* as configuration objects, but not used to authenticate the MCP itself).
-- **Protocol responder traffic** - the OCSP (`/ocsp`), TSA (`/tsa`), CRL and AIA distribution endpoints are wire-protocol services; this MCP manages their *configuration* (signers, CAs, CRLs), not the responder traffic.
+- **Protocol responder traffic** - the OCSP (`/ocsp`) and TSA (`/tsa`) endpoints are wire-protocol services; this MCP manages their *configuration* (signers, CAs), not the responder traffic. The published CRL / AIA / KRL artifacts can be *fetched* read-only (`get_published_crl` / `get_published_aia` / `get_published_krl`) for inspection.
 - **Deleting issued certificates** - Stream exposes no API to delete an issued certificate; revocation is the terminal state.
-- **Standalone binaries** - run from npm (`bunx`/`npx`) or from source.
 
 ## Contributing
 
@@ -322,7 +328,7 @@ For local setup, project layout, architecture, how to add a tool, and the full t
 | [Installation](docs/installation.md)                | Install methods, configuration, troubleshooting                   |
 | [Authentication](docs/authentication.md)            | Local-account and mTLS modes with environment-variable reference  |
 | [Client setup](docs/client-setup.md)                | Claude Desktop, Claude Code, Cursor, Codex, MCP Inspector         |
-| [Tool reference](docs/tools-reference.md)           | All 153 tools by domain with safety tiers                         |
+| [Tool reference](docs/tools-reference.md)           | All 157 tools by domain with safety tiers                         |
 | [Knowledge resources](docs/knowledge-resources.md)  | `stream://knowledge/*` catalog and the `search_docs` / `get_doc` tools |
 | [Development](docs/development.md)                   | Dev setup, architecture, tests, contributing                      |
 

SECURITY.md

@@ -0,0 +1,46 @@
+# Security Policy
+
+`@evertrust/stream-mcp` is an MCP server that operates a PKI control plane
+(certificate authorities, OCSP/TSA signers, keystores, RBAC). Security issues
+are taken seriously.
+
+## Reporting a vulnerability
+
+**Do not open a public issue for a security vulnerability.**
+
+Please report it privately using GitHub's
+[private vulnerability reporting](https://github.com/evertrust/stream-mcp/security/advisories/new)
+("Report a vulnerability" under the repository's *Security* tab). If you cannot
+use that channel, contact the Evertrust security team through the channels
+listed at <https://www.evertrust.io>.
+
+Please include:
+
+- a description of the issue and its impact,
+- the affected version(s) and configuration (auth mode, Stream version),
+- reproduction steps or a proof of concept.
+
+We aim to acknowledge a report within a few business days and will coordinate a
+fix and disclosure timeline with you.
+
+## Scope
+
+This policy covers the MCP server in this repository. Vulnerabilities in the
+Evertrust Stream backend itself should be reported through Evertrust's product
+security channel.
+
+In-scope examples: secret leakage through tool output or logs, SSRF via outbound
+trigger URLs, path traversal in API routing, TLS-verification bypass, or any way
+to make the server perform an unintended privileged operation.
+
+## Supported versions
+
+The server targets **Evertrust Stream 2.1**. Only the latest published release
+of this package receives security fixes.
+
+## Handling of secrets
+
+The server never logs request headers, bodies, or tool arguments. Private keys,
+PKCS#12 material, PINs, and credential secrets are write-only and redacted from
+tool output. If you observe secret material reaching tool output or logs, treat
+it as a security issue and report it privately.