Merge pull request #24 from nestm-dev/codex/mcp-upstream-gaps-alpha7

feat: streaming SSRF transport, bounded capture + catalog digest, runtime snapshot schemas

Author: kauandotnet

.changeset/bounded-capture-catalog-digest.md

@@ -0,0 +1,25 @@
+---
+"@nestm/mcp-conformance": minor
+---
+
+Added bounded hostile-value capture and canonical catalog digests, so hosts stop hand-rolling both
+around the canonicalizer. `canonicalizeMcpConformanceValue` enforces only its own fixed ceilings and
+walks a hostile shape on the way there; `captureMcpConformanceValue(value, limits)` refuses the
+shape instead, copying an untrusted value into deep-frozen, null-prototype JSON data under
+caller-supplied bounds and rejecting proxies, accessor and non-enumerable properties, symbol keys,
+sparse or subclassed arrays, exotic prototypes, cycles, and non-finite numbers.
+`captureMcpToolArguments` layers a bounded argument record on it with predictive byte accounting
+that is cross-checked against the canonicalizer's exact output byte length. Bounds resolve through
+`resolveMcpConformanceCaptureLimits` against `MCP_CONFORMANCE_DEFAULT_CAPTURE_LIMITS` and
+`MCP_CONFORMANCE_HARD_CAPTURE_LIMITS`, and a refusal is an `McpConformanceCaptureError` carrying a
+structural `code` that never quotes the rejected value.
+
+`digestMcpRuntimeCatalog(snapshot, { domain, toolSchemaDomain, limits })` returns one
+`catalogFingerprint` plus a per-tool `schemaDigest` so a management path and a serving path can
+compare the same surface. The snapshot is typed structurally by its `tools`, `resources`,
+`resourceTemplates`, and `prompts` collections, keeping the kernel free of a runtime dependency.
+Discovery order never reaches a digest — each collection sorts on its identity with a canonical-form
+tiebreak — and a repeated identity is refused rather than silently collapsed. `fingerprintMcpConformanceValue`'s
+domain rule now also validates both caller-supplied digest domains, and the new
+`toMcpConformanceFingerprintHex` renders a `sha256:<base64url>` fingerprint as 64 lowercase
+hexadecimal characters for digest columns that check a fixed-width hexadecimal form.

.changeset/conformance-scope-clarification.md

@@ -0,0 +1,24 @@
+---
+"@nestm/mcp-conformance": minor
+---
+
+Scoped the package to what it actually does and dropped the dead CI-regression half. The manifest
+description and keywords now state runtime integrity and safety probing for third-party MCP servers
+instead of conformance testing, and the README opens by disclaiming any relationship to the official
+`@modelcontextprotocol/conformance` spec-compliance suite: this kernel runs bounded, read-only
+probes against a server you do not control and supplies the canonicalization, bounded-capture, and
+catalog-fingerprinting primitives that detect catalog drift and refuse hostile payloads. It asserts
+nothing about the MCP specification.
+
+`compareMcpConformanceReports` and `toMcpConformanceJUnit` are removed with their types
+(`McpConformanceReportComparison`, `McpConformanceComparableReportComparison`,
+`McpConformanceIncomparableReportComparison`, `McpConformanceComparisonVerdict`,
+`McpConformanceCheckChange`), along with the now-unreachable `maxJunitBytes` entry in
+`MCP_CONFORMANCE_DEFAULT_LIMITS` and `MCP_CONFORMANCE_HARD_LIMITS`. Baseline-versus-candidate
+comparison and JUnit projection belong to a release pipeline, not to a runtime integrity kernel, and
+no caller in this repository used either. Plan execution, immutable reports, fingerprints, capture,
+catalog digests, and bounded JSON parsing and serialization are unchanged.
+
+`descriptor.subject` keeps its name — the control-plane API response contract and its web client
+both read it — and now carries a schema doc comment stating what it records: the build of the
+observing client that produced the report, never the observed target, which is `descriptor.target`.

.changeset/runtime-snapshot-schemas.md

@@ -0,0 +1,18 @@
+---
+"@nestm/mcp-manager": minor
+"@nestm/mcp": minor
+---
+
+Publish `MCP_RUNTIME_PHASES` and `MCP_RUNTIME_PROTOCOL_ERAS` as frozen tuples that mirror the
+`McpRuntimePhase` and `McpRuntimeProtocolEra` unions through a compile-time exhaustiveness fence,
+together with `mcpRuntimeStateSnapshotSchema`, `mcpRuntimeProbeSnapshotSchema`, and
+`mcpRuntimeCapabilitiesSnapshotSchema`. The validators implement Standard Schema v1 without adding
+a runtime dependency: they accept exactly what the manager emits, reject unknown properties and
+unpublished phases, eras, or state error codes, and return a frozen normalized snapshot so hosts
+can validate persisted projections on the way back in.
+
+Accept an `McpRuntimeToolCallOptions` object as the fourth `callTool` argument. A positional
+`AbortSignal` stays source compatible as the cancellation-only form, and pinning `toolDefinition`
+threads that exact definition to the managed client runtime so structured output is validated
+against it instead of a cached `tools/list` view. `McpManagerService` from `@nestm/mcp/manager`
+inherits the widened call surface.

.changeset/streaming-guarded-transport.md

@@ -0,0 +1,29 @@
+---
+"@nestm/mcp-auth": minor
+---
+
+Add a transport-grade streaming SSRF-guarded fetch and give the existing guarded transports an
+exact host allowlist and a loopback-http door.
+
+`createStreamingSsrfGuardedFetch` is a complete `FetchLike` — it drops into
+`McpHttpClientTransportDefinition.fetch` with no cast — that keeps the connect-time DNS pinning,
+blocked-range predicate, SNI pinning, and forced `accept-encoding: identity` of
+`createSsrfGuardedFetch` while handing back a live `ReadableStream`, which is what a long-lived
+`text/event-stream` MCP session needs and the buffering fetch structurally cannot serve. Redirects
+are manual by construction and any 3xx is rejected. `maxResponseBytes` (4 MiB) meters ordinary
+bodies as a running total and against a declared `Content-Length`; `text/event-stream` swaps it for
+a per-event `maxSseEventBytes` budget (1 MiB, CR/LF/CRLF framing, reset at each blank line) with no
+total cap, plus an `idleTimeoutMs` gap between bytes. A violation errors the stream and destroys the
+connection. Zero new runtime dependencies — it is built on `node:https`/`node:http` like the
+existing guarded fetch.
+
+`admitMcpHttpEndpoint` and `openGuardedFetch` split admission from the connection so a host can
+reject an endpoint before decrypting the credential it would have sent; the lease replays only the
+answers pinned at admission and confines every request to the admitted origin.
+
+`createSsrfGuardedFetch` and `createNodeDocumentFetcher` gain the shared `allowedHosts` (exact match
+after normalization) and `allowLoopbackHttp` (permits `http:` only to a host whose every resolved
+address is loopback) options; both are fail-closed, so existing callers see no behavior change.
+Also exported: `normalizeGuardedHost`, `isLoopbackAddress`, `McpGuardedHostPolicyOptions`,
+`McpResolvedAddress`, and the `MCP_STREAM_*` fence constants. `McpDocumentFetchFailure` gains a
+`host-not-allowed` reason, which CIMD resolution maps to the existing `host-not-allowed` failure.

.github/workflows/ci.yml

@@ -71,3 +71,21 @@ jobs:
       - run: pnpm run verify:apps
       - run: pnpm --filter "./packages/*" exec publint --strict
       - run: pnpm run verify:attw
+
+  conformance:
+    name: Official MCP conformance suite
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/setup@v2
+        with:
+          install: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      # The fixture imports @nestm/mcp-server through its published export map.
+      - run: pnpm --filter "./packages/*" run build
+      - run: pnpm --filter @nestm/mcp-conformance-harness run conformance

README.md

@@ -14,7 +14,7 @@ The primary use case is an artifact or agent runtime that needs to expose truste
 | `@nestm/mcp-core`          | Framework-neutral operation context, middleware, authorization decisions, and lifecycle observation                                                 | Implemented |
 | `@nestm/mcp-client`        | Named v2 client runtime, strict outbound OAuth, isolated leases, transports, typed requests, managed listening, and middleware                      | Implemented |
 | `@nestm/mcp-manager`       | Framework-neutral bounded ownership and lifecycle for opaque, dynamically resolved MCP client generations                                           | Implemented |
-| `@nestm/mcp-conformance`   | Framework-neutral bounded plan execution, immutable reports, semantic regression comparison, fingerprints, and JSON/JUnit export                    | Alpha       |
+| `@nestm/mcp-conformance`   | Framework-neutral bounded probe execution, immutable reports, hostile-value capture, fingerprints, and catalog-drift digests                        | Alpha       |
 | `@nestm/mcp-server`        | Framework-neutral per-request server runtime, feature registry, web-standard/Node/stdio serving, and OAuth resource-server wrapper                  | Implemented |
 | `@nestm/mcp-apps`          | Stable MCP Apps server metadata, validation, decorator/native fragments, capability advertisement, and direct-server feature composition            | Alpha       |
 | `@nestm/mcp-gateway`       | Tool, prompt, resource, resource-template, and completion projection with policy enforcement and auth-scoped discovery caching                      | Implemented |

apps/control-plane-api/README.md

@@ -89,9 +89,9 @@ digests—not endpoints, credentials, runtime names, raw catalogs or schemas, re
 caught error details.
 
 Dashboard history is operational convenience, not a durable release baseline. Cross-release
-regression checks must persist baseline and candidate JSON/JUnit artifacts outside this process and
-compare reports produced by separate library builds. This API intentionally provides neither
-baseline approval nor durable artifact storage.
+regression checks must persist bounded report JSON outside this process and compare reports produced
+by separate library builds. This API intentionally provides neither baseline approval nor durable
+artifact storage.
 
 The conformance routes share this validation host's loopback/private deployment boundary. They do
 not add caller authentication or make the host safe to expose through a routable bind or public
@@ -116,8 +116,20 @@ limits before broadening that boundary.
 - Conformance requests select only the host-owned passive plan, pin the full run to one managed
   generation lease, enforce time/page/item/schema/concurrency bounds, and never infer permission
   from upstream annotations.
-- This exact-host fetch guard demonstrates the admission seam; an internet-facing product still
-  needs DNS pinning/rebinding protection, response-body limits, authentication, and rate limiting.
+- Outbound MCP transports run on NestM's streaming SSRF-guarded fetch, so this host inherits
+  connect-time DNS pinning, blocked private/link-local ranges, refused redirects, and response
+  fences (a total byte cap for ordinary responses, a per-event cap for SSE) without owning that
+  code. The application supplies only policy: the exact host allowlist and the loopback switch.
+  An internet-facing product still needs authentication, rate limiting, and egress authorization.
+- OAuth discovery, registration, and token requests run on the same package's buffered guarded
+  fetch, which is pinned to HTTPS here because the interactive redirect is a browser navigation.
+  This host adds only its own endpoint policy: a GET may reach the resource origin or an
+  allow-listed authorization host, and a credential-bearing POST must exactly equal the discovered
+  token or registration endpoint.
+- Runtime OAuth credentials are held as revisioned generations behind the client package's
+  credential-store port. Refresh, single-flight coalescing across concurrent 401s, claim/commit
+  fencing, and terminal invalidation belong to that package; this host owns only the projected
+  status, the process-local storage, and the fenced-generation lifecycle.
 
 ## Run
 

apps/control-plane-api/package.json

@@ -30,6 +30,7 @@
 		"@nestjs/platform-fastify": "12.0.0-alpha.5",
 		"@nestjs/swagger": "12.0.0-alpha.2",
 		"@nestm/mcp": "workspace:^",
+		"@nestm/mcp-auth": "workspace:^",
 		"@nestm/mcp-client": "workspace:^",
 		"@nestm/mcp-conformance": "workspace:^",
 		"@nestm/mcp-gateway": "workspace:^",