Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
feat(control-api): probe MCP transport in remote discover + install
Diego Zacarias94afe0254554
diff --git a/control-api/package-lock.json b/control-api/package-lock.jsonindex 865f6235f..0a4fd7424 100644--- a/control-api/package-lock.json+++ b/control-api/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-control-api",- "version": "0.1.646",+ "version": "0.1.647","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-control-api",- "version": "0.1.646",+ "version": "0.1.647","dependencies": {"@clerum/display-field": "file:../packages/display-field","@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",diff --git a/control-api/package.json b/control-api/package.jsonindex 5817feb3f..731cc8961 100644--- a/control-api/package.json+++ b/control-api/package.json@@ -1,6 +1,6 @@{"name": "clerum-control-api",- "version": "0.1.646",+ "version": "0.1.647","description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets","main": "dist/main.js","engines": {diff --git a/control-api/src/http/pinnedFetch.ts b/control-api/src/http/pinnedFetch.tsindex 45c7a0585..83efff8d6 100644--- a/control-api/src/http/pinnedFetch.ts+++ b/control-api/src/http/pinnedFetch.ts@@ -49,6 +49,13 @@ export interface PinnedTransportInput {maxBodyBytes: number/** Present only for method === 'POST' (form body); C4 exchange adoption. */body?: string+ /**+ * When false, resolve on the response HEADERS and discard the body without waiting+ * for `end`. Needed to probe an MCP `initialize` whose 200 is a `text/event-stream`+ * that may never close: reading only status+headers avoids hanging until the+ * timeout. Defaults to true (read the full body). Test transports ignore it.+ */+ readBody?: boolean}export interface PinnedRawResponse {@@ -85,6 +92,12 @@ export interface PinnedFetchOptions {transport?: PinnedTransporttimeoutMs?: numbermaxBodyBytes?: number+ /**+ * When false, the transport resolves on the response headers and discards the body+ * (see {@link PinnedTransportInput.readBody}). The returned `bodyText` is empty.+ * Defaults to true.+ */+ readBody?: boolean}function errMessage(e: unknown): string {@@ -143,6 +156,23 @@ const defaultPinnedTransport: PinnedTransport = input =>signal: input.signal,},res => {+ // Header-only mode: resolve on the response headers and tear the socket down+ // immediately, without waiting for `end`. An MCP `initialize` 200 is a+ // `text/event-stream` that may stay open indefinitely; reading the body would+ // hang the request until the timeout.+ if (input.readBody === false) {+ resolve({+ status: res.statusCode ?? 0,+ headers: res.headers,+ bodyText: '',+ })+ // Swallow a late stream 'error' emitted after we tore the socket down:+ // without a listener it would throw as an unhandled stream error.+ res.on('error', () => {})+ res.destroy()+ req.destroy()+ return+ }const chunks: Buffer[] = []let total = 0let capped = false@@ -208,6 +238,7 @@ export async function pinnedFetch(lookup: pinnedLookup(resolved.addresses),signal,maxBodyBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,+ readBody: options.readBody ?? true,...(options.body !== undefined ? { body: options.body } : {}),})} catch (e) {diff --git a/control-api/src/oauth/discovery.ts b/control-api/src/oauth/discovery.tsindex 33d85cbca..38e0a9c6b 100644--- a/control-api/src/oauth/discovery.ts+++ b/control-api/src/oauth/discovery.ts@@ -279,7 +279,7 @@ async function guardedFetch(* invariant: validation runs BEFORE every fetch, and a URL the kernel rejects is* never fetched.*/-async function guardedFetchJson(+export async function guardedFetchJson(url: string,field: string,deps: DiscoveryDeps@@ -362,7 +362,7 @@ function isRecord(v: unknown): v is Record<string, unknown> {}/** Path with any trailing slashes stripped (so `/mcp/` and `/mcp` compare equal). */-function trimmedPath(url: URL): string {+export function trimmedPath(url: URL): string {return url.pathname.replace(/\/+$/, '')}diff --git a/control-api/src/oauth/mcpTransportProbe.ts b/control-api/src/oauth/mcpTransportProbe.tsnew file mode 100644index 000000000..51e1eb7e3--- /dev/null+++ b/control-api/src/oauth/mcpTransportProbe.ts@@ -0,0 +1,273 @@+import { type PinnedFetchError, pinnedFetch } from '../http/pinnedFetch.js'+import { rootLogger } from '../observability/logger.js'+import { type DiscoveryDeps, guardedFetchJson, trimmedPath } from './discovery.js'++/**+ * MCP transport probe for the remote OAuth carril (issue 26-09-25, mini-spec D3).+ *+ * The remote wizard's Detect + install saga validate the per-path OAuth metadata+ * chain (RFC 9728 → 8414) but never touch the MCP TRANSPORT. A URL whose OAuth+ * metadata answers on `/mcp` but whose MCP `initialize` there 404s (Vercel serves MCP+ * at the root `/`) passes Detect + install and only fails at mcp-host's first+ * `initialize`. This module closes that gap: a tokenless `POST initialize` through the+ * SAME IP-pinned fetch the carril uses ({@link pinnedFetch}, spec §4 kernel + pin per+ * hop), classified against the decision table, blocking install ONLY when the path is+ * provably dead (404/405). Ambiguity never blocks — the probe vetoes only what it can+ * prove dead, and warns otherwise.+ *+ * Shared by Detect and install (D4 — one rule, one implementation). The `initialize`+ * 200 is a `text/event-stream` that may not close, so the probe reads HEADERS ONLY+ * (`readBody:false`) and tears the socket down at the headers.+ */++/** Version advertised in the probe's `clientInfo`; cosmetic — the body is never read back. */+const PROBE_CLIENT_VERSION: string = (() => {+ try {+ // CommonJS build: read the service version at runtime without a static (rootDir-+ // bound) JSON import. The value only decorates the probe's clientInfo.+ return (require('../../package.json') as { version?: string }).version ?? '0.0.0'+ } catch {+ return '0.0.0'+ }+})()++/** MCP protocol version mcp-host's StreamableHTTP client sends on `initialize`. */+const PROBE_PROTOCOL_VERSION = '2025-11-25'++/** 8s: an `initialize` that neither answers nor resets by then is treated as inconclusive. */+export const PROBE_TIMEOUT_MS = 8_000++export type TransportProbeOutcome =+ | { status: 'alive'; probedUrl: string; httpStatus: number; challenge: boolean }+ | { status: 'dead'; probedUrl: string; httpStatus: 404 | 405; suggestedBaseUrl?: string }+ | {+ status: 'inconclusive'+ probedUrl: string+ reason:+ | 'timeout'+ | 'transport_failed'+ | 'redirect'+ | 'unexpected_status'+ | 'content_encoding_rejected'+ | 'kernel_rejected'+ httpStatus?: number+ detail: string+ }++/**+ * Build the tokenless JSON-RPC `initialize` body the probe POSTs — the exact method ++ * params shape mcp-host's StreamableHTTP client sends, so a server that answers a real+ * `initialize` answers this one identically.+ */+export function buildInitializeProbeBody(): string {+ return JSON.stringify({+ jsonrpc: '2.0',+ id: 0,+ method: 'initialize',+ params: {+ protocolVersion: PROBE_PROTOCOL_VERSION,+ capabilities: {},+ clientInfo: { name: 'clerum-control-api-probe', version: PROBE_CLIENT_VERSION },+ },+ })+}++function isRedirectStatus(status: number): boolean {+ return status === 301 || status === 302 || status === 303 || status === 307 || status === 308+}++/**+ * Classify a tokenless `POST initialize` response (mini-spec D3 decision table). PURE.+ *+ * - 200/202 → alive (path accepts `initialize`).+ * - 401 → alive; `challenge` true iff a `www-authenticate` header is present (RFC 9728+ * compliant transport asking for a token — the exact case the issue must NOT break).+ * - 403 → alive (transport exists; treated as an auth signal).+ * - 404/405 → dead (path has no MCP).+ * - 3xx → inconclusive/redirect (the pin never follows; mcp-host's undici does at+ * runtime, so a redirect must not block).+ * - any other 4xx / 5xx → inconclusive/unexpected_status (something processed the POST,+ * or the server is down ≠ wrong URL — fail-open on the SIGNAL, never on security).+ */+export function classifyInitializeResponse(+ status: number,+ headers: Record<string, string | string[] | undefined>+):+ | { status: 'alive'; challenge: boolean }+ | { status: 'dead' }+ | { status: 'inconclusive'; reason: 'redirect' | 'unexpected_status' } {+ if (status === 200 || status === 202) return { status: 'alive', challenge: false }+ if (status === 401) {+ return { status: 'alive', challenge: headers['www-authenticate'] !== undefined }+ }+ if (status === 403) return { status: 'alive', challenge: false }+ if (status === 404 || status === 405) return { status: 'dead' }+ if (isRedirectStatus(status)) return { status: 'inconclusive', reason: 'redirect' }+ return { status: 'inconclusive', reason: 'unexpected_status' }+}++/** Map a {@link PinnedFetchError} onto the probe's inconclusive reasons (never blocks). */+function inconclusiveFromPinnedError(+ probedUrl: string,+ error: PinnedFetchError+): Extract<TransportProbeOutcome, { status: 'inconclusive' }> {+ switch (error.kind) {+ case 'kernel_rejected':+ return {+ status: 'inconclusive',+ probedUrl,+ reason: 'kernel_rejected',+ detail: `ssrf kernel rejected ${error.field}`,+ }+ case 'transport_failed': {+ // AbortSignal.timeout rejects with an abort/timeout message; keep them distinct.+ const reason = /timeout|aborted|abort/i.test(error.detail) ? 'timeout' : 'transport_failed'+ return { status: 'inconclusive', probedUrl, reason, detail: error.detail }+ }+ case 'content_encoding_rejected':+ return {+ status: 'inconclusive',+ probedUrl,+ reason: 'content_encoding_rejected',+ detail: `content-encoding ${error.encoding}`,+ }+ }+}++function isRecord(v: unknown): v is Record<string, unknown> {+ return typeof v === 'object' && v !== null && !Array.isArray(v)+}++/**+ * Canonical-URL suggestion (mini-spec §"Algoritmo de sugerencia"), only run when the+ * typed path probed DEAD and is not already the root. Bounded to +1 GET + 1 POST and+ * never suggests a URL it did not verify alive.+ *+ * Candidate = the root PRM's `resource` when it is a same-origin string that differs in+ * path from what was typed (Vercel: `https://mcp.vercel.com/`), else `${origin}/`. The+ * candidate is then re-probed through the same classifier; only an `alive` candidate is+ * suggested. The PRM GET goes through {@link guardedFetchJson} (kernel-guarded + pinned,+ * redirects re-pinned per hop).+ */+async function suggestCanonicalBaseUrl(+ baseUrl: string,+ deps: DiscoveryDeps+): Promise<string | undefined> {+ let typed: URL+ try {+ typed = new URL(baseUrl)+ } catch {+ return undefined+ }+ const origin = typed.origin+ const prmRootUrl = `${origin}/.well-known/oauth-protected-resource`++ let candidate = `${origin}/`+ const fetched = await guardedFetchJson(prmRootUrl, 'prmUrl', deps)+ if (fetched.ok && isRecord(fetched.json) && typeof fetched.json.resource === 'string') {+ try {+ const resourceUrl = new URL(fetched.json.resource)+ if (resourceUrl.origin === origin && trimmedPath(resourceUrl) !== trimmedPath(typed)) {+ candidate = fetched.json.resource+ }+ } catch {+ // Non-URL resource → keep the `${origin}/` fallback.+ }+ }++ const candidateOutcome = await probeMcpTransport(candidate, deps, { suggest: false })+ return candidateOutcome.status === 'alive' ? candidate : undefined+}++/**+ * Probe the MCP transport at `baseUrl` with a tokenless `POST initialize` through the+ * IP-pinned fetch, classify it, and (when dead and `suggest` is not false) look for the+ * canonical URL. Never throws — a kernel/transport failure is a non-blocking+ * `inconclusive`. `opts.suggest` is false on the recursive candidate probe so the+ * suggestion search cannot recurse.+ */+export async function probeMcpTransport(+ baseUrl: string,+ deps: DiscoveryDeps,+ opts: { suggest?: boolean } = {}+): Promise<TransportProbeOutcome> {+ const log = (deps.logger ?? rootLogger).child({ module: 'mcp-transport-probe' })++ const body = buildInitializeProbeBody()+ const fetched = await pinnedFetch(baseUrl, 'baseUrl', {+ method: 'POST',+ headers: {+ 'content-type': 'application/json',+ accept: 'application/json, text/event-stream',+ 'content-length': String(Buffer.byteLength(body)),+ },+ body,+ readBody: false,+ timeoutMs: PROBE_TIMEOUT_MS,+ resolveDns: deps.resolveDns,+ transport: deps.transport,+ })++ let outcome: TransportProbeOutcome+ if (!fetched.ok) {+ outcome = inconclusiveFromPinnedError(baseUrl, fetched.error)+ if (fetched.error.kind === 'kernel_rejected') {+ // Practically impossible (the caller validated the same URL moments earlier);+ // log it because a probe hitting the kernel is a signal worth seeing. Names only.+ log.warn(+ { event: 'remote_transport_probe_kernel_rejected', field: fetched.error.field },+ 'mcp transport probe rejected by ssrf kernel'+ )+ }+ } else {+ const classified = classifyInitializeResponse(fetched.response.status, fetched.response.headers)+ if (classified.status === 'alive') {+ outcome = {+ status: 'alive',+ probedUrl: baseUrl,+ httpStatus: fetched.response.status,+ challenge: classified.challenge,+ }+ } else if (classified.status === 'dead') {+ const httpStatus = fetched.response.status as 404 | 405+ let suggestedBaseUrl: string | undefined+ if (opts.suggest !== false) {+ let pathname = '/'+ try {+ pathname = new URL(baseUrl).pathname+ } catch {+ pathname = '/'+ }+ if (pathname !== '/') {+ suggestedBaseUrl = await suggestCanonicalBaseUrl(baseUrl, deps)+ }+ }+ outcome = {+ status: 'dead',+ probedUrl: baseUrl,+ httpStatus,+ ...(suggestedBaseUrl ? { suggestedBaseUrl } : {}),+ }+ } else {+ outcome = {+ status: 'inconclusive',+ probedUrl: baseUrl,+ reason: classified.reason,+ httpStatus: fetched.response.status,+ detail: `HTTP ${fetched.response.status}`,+ }+ }+ }++ log.info(+ {+ event: 'remote_transport_probe',+ status: outcome.status,+ httpStatus: 'httpStatus' in outcome ? outcome.httpStatus : undefined,+ reason: outcome.status === 'inconclusive' ? outcome.reason : undefined,+ hasSuggestion: outcome.status === 'dead' ? Boolean(outcome.suggestedBaseUrl) : undefined,+ },+ 'mcp transport probe'+ )+ return outcome+}diff --git a/control-api/src/routes/admin/__tests__/remoteMcpDiscoverErrorMapping.test.ts b/control-api/src/routes/admin/__tests__/remoteMcpDiscoverErrorMapping.test.tsindex 8633824a9..1d52d37fb 100644--- a/control-api/src/routes/admin/__tests__/remoteMcpDiscoverErrorMapping.test.ts+++ b/control-api/src/routes/admin/__tests__/remoteMcpDiscoverErrorMapping.test.ts@@ -48,6 +48,14 @@ function buildApp(discover: ReturnType<typeof fetchFailedDiscover>) {// Inject a fixed encryption key so router construction never touches config.encryptionKey: Buffer.alloc(32),discover: discover as any,+ // Hygiene: the `fetch_failed` case returns before the transport probe, but stub it+ // anyway so the router never reaches the real (networked) probe.+ probe: (async () => ({+ status: 'inconclusive',+ probedUrl: BASE_URL,+ reason: 'transport_failed',+ detail: 'stub',+ })) as any,}))return appdiff --git a/control-api/src/routes/admin/remoteMcp.ts b/control-api/src/routes/admin/remoteMcp.tsindex 1a327c27b..bd1903930 100644--- a/control-api/src/routes/admin/remoteMcp.ts+++ b/control-api/src/routes/admin/remoteMcp.ts@@ -25,6 +25,7 @@ import {upsertDynamicClient,} from '../../oauth/dynamicClientStore.js'import { deriveOAuthEncryptionKey } from '../../oauth/encryption.js'+import { probeMcpTransport } from '../../oauth/mcpTransportProbe.js'import { rootLogger } from '../../observability/logger.js'import { K8sNotFoundError } from '../../services/resourceService.js'import type { SecretSnapshot } from '../../services/secretRepository.js'@@ -38,12 +39,14 @@ import { normalizeConfiguredOrigin } from '../external/oauthCallback.js'* authenticated the caller as a control-ui admin):** POST /admin/mcp-servers/remote/discover — dry-run: kernel-guard the URL, run- * RFC 9728→8414 discovery, return the "Detected" prefill for the C5 wizard. No- * writes.+ * RFC 9728→8414 discovery, probe the MCP transport (a tokenless `initialize`), and+ * return the "Detected" prefill + `transport` verdict for the C5 wizard. No writes.* POST /admin/mcp-servers/remote — transactional install saga: re-run- * discovery server-side (D-4: discover only at install, then pin), create the- * Secret (confidential only) + McpServer CR + attach to the Context, with- * compensating rollback that preserves the original error.+ * discovery server-side (D-4: discover only at install, then pin), probe the MCP+ * transport as a hard gate (a provably-dead 404/405 path is a 400+ * `transport_unreachable` BEFORE any AS mint or K8s write), then create the Secret+ * (confidential only) + McpServer CR + attach to the Context, with compensating+ * rollback that preserves the original error.** The written `spec.oauth` remote shape is the C3 CRD contract (see* {@link buildRemoteOAuthSpec}). It is NOT admissible by the current CRD — C3@@ -251,6 +254,12 @@ export interface AdminRemoteMcpDeps {* it to drive a specific `DiscoveryOutcome` (e.g. a `fetch_failed`) with no network.*/discover?: typeof discoverRemoteOAuth+ /**+ * Injectable MCP transport probe (test seam only). Production leaves it undefined and+ * the real {@link probeMcpTransport} (real IP-pinned POST `initialize`) is used; tests+ * inject one derived from the real producer to drive a specific probe outcome offline.+ */+ probe?: typeof probeMcpTransport}export function createAdminRemoteMcpRouter(@@ -262,6 +271,7 @@ export function createAdminRemoteMcpRouter(const encryptionKey = deps.encryptionKey ?? deriveOAuthEncryptionKey(config.oauthEncryptionKey)const dcrDeps: DcrDeps = deps.dcr ?? { logger: log }const discover = deps.discover ?? discoverRemoteOAuth+ const probe = deps.probe ?? probeMcpTransport// ── POST /admin/mcp-servers/remote/discover — dry-run, no writes ──────────router.post(@@ -293,7 +303,24 @@ export function createAdminRemoteMcpRouter(}const r = outcome.result++ // Probe the MCP transport (issue 26-09-25): OAuth metadata alone can resolve on a+ // path whose `initialize` 404s (Vercel serves MCP at `/`). Detect surfaces this+ // early (+ a canonical-URL suggestion) without blocking the dry-run.+ const transport = await probe(baseUrl, { logger: log })+ if (transport.status === 'dead') {+ log.warn(+ {+ event: 'remote_discover_transport_unreachable',+ httpStatus: transport.httpStatus,+ hasSuggestion: Boolean(transport.suggestedBaseUrl),+ },+ 'remote discover: MCP transport unreachable at the typed path'+ )+ }+res.status(200).json({+ transport,detected: {registrationMode: r.registrationMode,// DCR is available in C2. Echo the resolved client mode (derived from the@@ -402,6 +429,45 @@ export function createAdminRemoteMcpRouter(return}+ // Hard gate (issue 26-09-25): probe the MCP transport BEFORE any AS mint or K8s+ // write. A provably-dead path (404/405 `initialize`) means the operator typed a+ // URL that passes OAuth discovery but has no MCP transport — install would only+ // fail later at mcp-host. `inconclusive` never blocks (fail-open on the signal).+ const transportProbe = await probe(body.baseUrl, { logger: log })+ if (transportProbe.status === 'dead') {+ log.warn(+ {+ event: 'remote_install_transport_unreachable',+ serverName: body.serverName,+ httpStatus: transportProbe.httpStatus,+ hasSuggestion: Boolean(transportProbe.suggestedBaseUrl),+ },+ 'remote install blocked: MCP transport unreachable at the typed path'+ )+ res.status(400).json({+ error: 'transport_unreachable',+ detail: {+ probedUrl: transportProbe.probedUrl,+ httpStatus: transportProbe.httpStatus,+ ...(transportProbe.suggestedBaseUrl+ ? { suggestedBaseUrl: transportProbe.suggestedBaseUrl }+ : {}),+ },+ })+ return+ }+ if (transportProbe.status === 'inconclusive') {+ log.warn(+ {+ event: 'remote_install_transport_inconclusive',+ serverName: body.serverName,+ reason: transportProbe.reason,+ httpStatus: transportProbe.httpStatus,+ },+ 'remote install: MCP transport probe inconclusive, continuing'+ )+ }+// Client mode: pre-registered/CIMD are fixed by the mode; DCR derives it from// the AS auth methods (public iff `none`, else confidential) — NOT the body.const clientMode: 'public' | 'confidential' =diff --git a/control-api/test/fixtures/remoteOAuthDiscovery.ts b/control-api/test/fixtures/remoteOAuthDiscovery.tsindex d24571aa3..7985c5172 100644--- a/control-api/test/fixtures/remoteOAuthDiscovery.ts+++ b/control-api/test/fixtures/remoteOAuthDiscovery.ts@@ -18,8 +18,14 @@* GET https://mcp.canva.com/mcp → 401 www-authenticate: Bearer realm="OAuth", resource_metadata="https://mcp.canva.com/.well-known/oauth-protected-resource/mcp", error="invalid_token", …* (POST initialize returns the identical header on all four.)*+ * Transport probe (sondeo POST en vivo 2026-09-25): the tokenless `POST initialize` of+ * the four CIMD pilots returns 401 with the same Bearer challenge (transport alive,+ * token required); Vercel's `/mcp` returns 404 (dead) while `/` returns 200+ * `text/event-stream`. Those bytes back the `VERCEL_PILOT` + the `initialize` table+ * below — derived from the real producer, not hand-invented.+ ** Provenance: scratchpad/c1-fixtures-provenance.md (sondeo en vivo 2026-09-20,- * sección "EVIDENCIA GET").+ * sección "EVIDENCIA GET") + the 2026-09-25 POST probe.*/import type { DbClient } from '../../src/db.js'import type { PinnedTransport } from '../../src/http/pinnedFetch.js'@@ -65,10 +71,23 @@ export interface PilotFixture {/** MCP server URL discovery is entered with. */mcpUrl: stringprm: { url: string; json: string }+ /**+ * The ROOT PRM (`/.well-known/oauth-protected-resource`, no path suffix) when the+ * server serves a distinct one — the source of the transport probe's canonical-URL+ * suggestion (Vercel: root PRM `resource` is `https://mcp.vercel.com/`).+ */+ prmRoot?: { url: string; json: string }/** Additional well-known/PRM URLs the server 404s on (for candidate fallback). */prmNotFound?: string[]/** WWW-Authenticate header the 401 probe of `mcpUrl` returns, if any. */wwwAuthenticate?: string+ /**+ * Per-URL response of the tokenless `POST initialize` transport probe, keyed by the+ * exact URL POSTed (the typed MCP URL and any canonical candidate). Vercel: `/mcp` →+ * 404, `/` → 200 event-stream. The 4 CIMD pilots omit this — the transport defaults+ * their POST to the real 401 challenge (transport alive, token required).+ */+ initialize?: Record<string, { status: number; headers: Record<string, string> }>as: { url: string; json: string }}@@ -130,6 +149,59 @@ export const PILOTS: Record<'notion' | 'linear' | 'sentry' | 'canva', PilotFixtu},}+// ─── Vercel (DCR, NOT CIMD) — transport probe repro (sondeo en vivo 2026-09-25) ──+//+// The exact bytes Vercel returned on 2026-09-25. Vercel serves OAuth metadata+// PER-PATH (both root and `/mcp` PRM answer 200) but its MCP transport lives at the+// ROOT `/`: POST `initialize` to `/mcp` → 404 (Next.js 404 page), to `/` → 200+// `text/event-stream`. This is the exact URL-resolution gap the probe closes. Vercel's+// AS omits `none` from `token_endpoint_auth_methods_supported` → mode `dcr`.+//+// PROVENANCE (curl, 2026-09-25):+// GET https://mcp.vercel.com/.well-known/oauth-protected-resource → 200 (root, resource `/`)+// GET https://mcp.vercel.com/.well-known/oauth-protected-resource/mcp → 200 (path, resource `/mcp`)+// GET https://vercel.com/.well-known/oauth-authorization-server → 200+// POST initialize https://mcp.vercel.com/mcp → 404 text/html; https://mcp.vercel.com/ → 200 text/event-stream++/** Root PRM: resource is the canonical root `https://mcp.vercel.com/`. */+export const VERCEL_PRM_ROOT_JSON =+ '{"resource":"https://mcp.vercel.com/","authorization_servers":["https://vercel.com"],"scopes_supported":["openid"],"resource_name":"Vercel MCP","resource_documentation":"https://vercel.com/docs/mcp/vercel-mcp","organization_name":"Vercel","organization_uri":"https://vercel.com","description":"Vercel\'s official MCP server — Vercel platform tools, deployment management, and documentation for AI assistants.","logo_uri":"https://mcp.vercel.com/icons/vercel-light.svg"}'+/** Path-suffixed PRM: resource echoes the typed `/mcp` path (what fooled Detect). */+export const VERCEL_PRM_MCP_JSON =+ '{"resource":"https://mcp.vercel.com/mcp","authorization_servers":["https://vercel.com"],"scopes_supported":["openid"],"resource_name":"Vercel MCP","resource_documentation":"https://vercel.com/docs/mcp/vercel-mcp","organization_name":"Vercel","organization_uri":"https://vercel.com","description":"Vercel\'s official MCP server — Vercel platform tools, deployment management, and documentation for AI assistants.","logo_uri":"https://mcp.vercel.com/icons/vercel-light.svg"}'+export const VERCEL_AS_JSON =+ '{"issuer":"https://vercel.com","jwks_uri":"https://vercel.com/.well-known/jwks","subject_types_supported":["public"],"response_types_supported":["code"],"response_modes_supported":["web_message.opener"],"claims_supported":["sub","aud","exp","iat","iss","jti","nbf","nonce","preferred_username","email","picture"],"id_token_signing_alg_values_supported":["RS256"],"scopes_supported":["openid","email","profile","offline_access"],"authorization_endpoint":"https://vercel.com/oauth/authorize","device_authorization_endpoint":"https://api.vercel.com/login/oauth/device-authorization","token_endpoint":"https://api.vercel.com/login/oauth/token","revocation_endpoint":"https://api.vercel.com/login/oauth/token/revoke","userinfo_endpoint":"https://api.vercel.com/login/oauth/userinfo","code_challenge_methods_supported":["S256"],"token_endpoint_auth_methods_supported":["client_secret_basic","client_secret_post","client_secret_jwt","private_key_jwt"],"grant_types_supported":["authorization_code","client_credentials","refresh_token","urn:ietf:params:oauth:grant-type:device_code"],"registration_endpoint":"https://api.vercel.com/login/oauth/register"}'++/**+ * Vercel pilot — DCR (not CIMD), kept OUT of the `PILOTS` record so the CIMD discovery+ * loop (`oauth.discovery.test.ts`) is untouched. Discovery resolves through the+ * path-suffixed PRM (`resource: …/mcp`), while the transport probe finds `/mcp` dead+ * (404) and suggests the root `/` from the root PRM's `resource`.+ */+export const VERCEL_PILOT: PilotFixture = {+ name: 'vercel',+ mcpUrl: 'https://mcp.vercel.com/mcp',+ prm: {+ url: 'https://mcp.vercel.com/.well-known/oauth-protected-resource/mcp',+ json: VERCEL_PRM_MCP_JSON,+ },+ prmRoot: {+ url: 'https://mcp.vercel.com/.well-known/oauth-protected-resource',+ json: VERCEL_PRM_ROOT_JSON,+ },+ as: {+ url: 'https://vercel.com/.well-known/oauth-authorization-server',+ json: VERCEL_AS_JSON,+ },+ initialize: {+ 'https://mcp.vercel.com/mcp': {+ status: 404,+ headers: { 'content-type': 'text/html; charset=utf-8' },+ },+ 'https://mcp.vercel.com/': { status: 200, headers: { 'content-type': 'text/event-stream' } },+ },+}+/*** Build a {@link PinnedTransport}-shaped mock from a pilot fixture: a 401 (with* WWW-Authenticate) on the MCP probe when the fixture has a hint, 200+JSON on the@@ -365,14 +437,37 @@ export function makeInMemoryDynamicClientsDb(): {return { db, rows }}+/**+ * The real POST `initialize` 401 challenge the four CIMD pilots emit (Notion/Canva/+ * Linear/Sentry, sondeo 2026-09-25): a Bearer challenge = transport ALIVE, token+ * required. Only presence matters to the probe's `challenge` classification.+ */+const CIMD_INITIALIZE_CHALLENGE = 'Bearer realm="OAuth", error="invalid_token"'+export function makeDiscoveryTransport(pilot: PilotFixture): PinnedTransport {const jsonByUrl = new Map<string, string>([[pilot.prm.url, pilot.prm.json],[pilot.as.url, pilot.as.json],+ ...(pilot.prmRoot ? ([[pilot.prmRoot.url, pilot.prmRoot.json]] as [string, string][]) : []),])const notFound = new Set(pilot.prmNotFound ?? [])- return async ({ url }) => {- // MCP probe → 401 with the challenge header when the fixture has one.+ return async ({ url, method }) => {+ // POST → the transport probe (tokenless `initialize`). Per-URL `initialize` table+ // first (Vercel `/mcp`→404, `/`→200); otherwise the typed MCP URL defaults to the+ // real 401 challenge shape (transport alive). Method is undefined-safe.+ if (method === 'POST') {+ const probe = pilot.initialize?.[url]+ if (probe) return { status: probe.status, headers: probe.headers, bodyText: '' }+ if (url === pilot.mcpUrl) {+ return {+ status: 401,+ headers: { 'www-authenticate': pilot.wwwAuthenticate ?? CIMD_INITIALIZE_CHALLENGE },+ bodyText: '',+ }+ }+ return { status: 404, headers: { 'content-type': 'text/html' }, bodyText: 'not found' }+ }+ // GET (discovery): MCP probe → 401 with the challenge header when the fixture has one.if (url === pilot.mcpUrl) {if (pilot.wwwAuthenticate) {return { status: 401, headers: { 'www-authenticate': pilot.wwwAuthenticate }, bodyText: '' }diff --git a/control-api/test/oauth.mcpTransportProbe.test.ts b/control-api/test/oauth.mcpTransportProbe.test.tsnew file mode 100644index 000000000..4fcc6d492--- /dev/null+++ b/control-api/test/oauth.mcpTransportProbe.test.ts@@ -0,0 +1,191 @@+import { describe, expect, it, vi } from 'vitest'+import type { PinnedTransport } from '../src/http/pinnedFetch.js'+import { classifyInitializeResponse, probeMcpTransport } from '../src/oauth/mcpTransportProbe.js'+import { PILOTS, VERCEL_PILOT, makeDiscoveryTransport } from './fixtures/remoteOAuthDiscovery.js'++/**+ * MCP transport probe (issue 26-09-25, mini-spec D3). Fixtures are the real 2026-09-25+ * POST `initialize` bytes (T1). `classifyInitializeResponse` is exercised per decision-+ * table row (T5); `probeMcpTransport` is driven through the injected pinned transport+ * + `resolveDns`, so the pin and kernel run with zero real network.+ */+const PUBLIC_IP = '93.184.216.34'+const publicDns = () => vi.fn(async () => [PUBLIC_IP])++/** Record every hop the pinned transport receives, then delegate to the fixture base. */+function recordingTransport(base: PinnedTransport): {+ transport: PinnedTransport+ calls: Array<{+ url: string+ method?: string+ headers: Record<string, string>+ body?: string+ readBody?: boolean+ }>+} {+ const calls: Array<{+ url: string+ method?: string+ headers: Record<string, string>+ body?: string+ readBody?: boolean+ }> = []+ const transport: PinnedTransport = async input => {+ calls.push({+ url: input.url,+ method: input.method,+ headers: input.headers,+ body: input.body,+ readBody: input.readBody,+ })+ return base(input)+ }+ return { transport, calls }+}++describe('classifyInitializeResponse — decision table (T5, one per row)', () => {+ it('200 → alive, no challenge', () => {+ expect(classifyInitializeResponse(200, {})).toEqual({ status: 'alive', challenge: false })+ })+ it('202 → alive, no challenge', () => {+ expect(classifyInitializeResponse(202, {})).toEqual({ status: 'alive', challenge: false })+ })+ it('401 with www-authenticate → alive, challenge true', () => {+ expect(classifyInitializeResponse(401, { 'www-authenticate': 'Bearer realm="OAuth"' })).toEqual(+ {+ status: 'alive',+ challenge: true,+ }+ )+ })+ it('401 without www-authenticate → alive, challenge false', () => {+ expect(classifyInitializeResponse(401, {})).toEqual({ status: 'alive', challenge: false })+ })+ it('403 → alive, no challenge', () => {+ expect(classifyInitializeResponse(403, {})).toEqual({ status: 'alive', challenge: false })+ })+ it('404 → dead', () => {+ expect(classifyInitializeResponse(404, {})).toEqual({ status: 'dead' })+ })+ it('405 → dead', () => {+ expect(classifyInitializeResponse(405, {})).toEqual({ status: 'dead' })+ })+ it('302 (3xx) → inconclusive/redirect', () => {+ expect(classifyInitializeResponse(302, {})).toEqual({+ status: 'inconclusive',+ reason: 'redirect',+ })+ })+ it('400 (other 4xx) → inconclusive/unexpected_status', () => {+ expect(classifyInitializeResponse(400, {})).toEqual({+ status: 'inconclusive',+ reason: 'unexpected_status',+ })+ })+ it('500 (5xx) → inconclusive/unexpected_status', () => {+ expect(classifyInitializeResponse(500, {})).toEqual({+ status: 'inconclusive',+ reason: 'unexpected_status',+ })+ })+})++describe('probeMcpTransport — Vercel /mcp is dead, suggests the root (repro)', () => {+ it('POSTs a tokenless initialize, classifies dead, and suggests the canonical root', async () => {+ const { transport, calls } = recordingTransport(makeDiscoveryTransport(VERCEL_PILOT))+ const resolveDns = publicDns()++ const outcome = await probeMcpTransport(VERCEL_PILOT.mcpUrl, { transport, resolveDns })++ // Dead at the typed path, with the canonical-root suggestion derived from the root PRM.+ expect(outcome).toEqual({+ status: 'dead',+ probedUrl: 'https://mcp.vercel.com/mcp',+ httpStatus: 404,+ suggestedBaseUrl: 'https://mcp.vercel.com/',+ })++ // The transport saw exactly: POST /mcp, GET root PRM, POST / (the candidate probe).+ expect(calls.map(c => c.url)).toEqual([+ 'https://mcp.vercel.com/mcp',+ 'https://mcp.vercel.com/.well-known/oauth-protected-resource',+ 'https://mcp.vercel.com/',+ ])++ // The initial probe: POST, correct Accept, header-only, a real `initialize` body.+ const initial = calls[0]+ expect(initial.method).toBe('POST')+ expect(initial.headers.accept).toBe('application/json, text/event-stream')+ expect(initial.headers['content-type']).toBe('application/json')+ expect(initial.readBody).toBe(false)+ const parsedBody = JSON.parse(initial.body ?? '{}')+ expect(parsedBody.method).toBe('initialize')+ expect(parsedBody.params.clientInfo.name).toBe('clerum-control-api-probe')++ // The candidate probe is a POST too.+ expect(calls[2].method).toBe('POST')+ })+})++describe('probeMcpTransport — the four CIMD pilots are alive with a challenge', () => {+ for (const key of ['notion', 'linear', 'sentry', 'canva'] as const) {+ it(`${key}: 401 initialize → alive, challenge true`, async () => {+ const pilot = PILOTS[key]+ const outcome = await probeMcpTransport(pilot.mcpUrl, {+ transport: makeDiscoveryTransport(pilot),+ resolveDns: publicDns(),+ })+ expect(outcome.status).toBe('alive')+ if (outcome.status !== 'alive') return+ expect(outcome.challenge).toBe(true)+ expect(outcome.httpStatus).toBe(401)+ })+ }+})++describe('probeMcpTransport — IP pin', () => {+ it('resolves DNS and pins the socket to the validated IP', async () => {+ const resolveDns = vi.fn(async () => [PUBLIC_IP])+ const connectedIps: string[] = []+ const base = makeDiscoveryTransport(PILOTS.notion)+ const transport: PinnedTransport = async input => {+ await new Promise<void>(resolve => {+ input.lookup(+ new URL(input.url).hostname,+ { all: true } as never,+ ((_err: Error | null, addrs: string | Array<{ address: string }>) => {+ const list = Array.isArray(addrs) ? addrs : [{ address: addrs as string }]+ list.forEach(a => connectedIps.push(a.address))+ resolve()+ }) as never+ )+ })+ return base(input)+ }++ const outcome = await probeMcpTransport(PILOTS.notion.mcpUrl, { transport, resolveDns })+ expect(outcome.status).toBe('alive')+ expect(resolveDns).toHaveBeenCalled()+ expect(connectedIps.length).toBeGreaterThan(0)+ connectedIps.forEach(ip => expect(ip).toBe(PUBLIC_IP))+ })+})++describe('probeMcpTransport — SSRF kernel', () => {+ it('a host resolving to a metadata IP is rejected before the transport is called', async () => {+ const transport = vi.fn<PinnedTransport>(async () => ({+ status: 200,+ headers: {},+ bodyText: '',+ }))+ const outcome = await probeMcpTransport('https://mcp.notion.com/mcp', {+ transport,+ resolveDns: async () => ['169.254.169.254'],+ })+ expect(outcome.status).toBe('inconclusive')+ if (outcome.status !== 'inconclusive') return+ expect(outcome.reason).toBe('kernel_rejected')+ // Fail-closed: nothing was fetched.+ expect(transport).not.toHaveBeenCalled()+ })+})diff --git a/control-api/test/routes.adminRemoteMcp.test.ts b/control-api/test/routes.adminRemoteMcp.test.tsindex a73899fa7..5a2d6d2d6 100644--- a/control-api/test/routes.adminRemoteMcp.test.ts+++ b/control-api/test/routes.adminRemoteMcp.test.ts@@ -2,6 +2,7 @@ import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'viteimport express from 'express'import request from 'supertest'import { config } from '../src/config.js'+import type { PinnedTransport } from '../src/http/pinnedFetch.js'import type { K8sGateway } from '../src/k8s.js'import {type DiscoveryOutcome,@@ -9,6 +10,7 @@ import {discoverRemoteOAuth,} from '../src/oauth/discovery.js'import { decryptOAuthSecret, deriveOAuthEncryptionKey } from '../src/oauth/encryption.js'+import { probeMcpTransport } from '../src/oauth/mcpTransportProbe.js'import {type AdminRemoteMcpDeps,createAdminRemoteMcpRouter,@@ -23,6 +25,7 @@ import {DCR_VERCEL_DOWNGRADE_REGISTRATION_JSON,DCR_VERCEL_DOWNGRADE_REGISTRATION_RESPONSE,PILOTS,+ VERCEL_PILOT,dcrPilot,makeDcrTransport,makeDiscoveryTransport,@@ -52,10 +55,36 @@ vi.mock('../src/oauth/discovery.js', async importActual => {const NS = config.mcpServersNamespace // 'mcp-server'-function makeApp(gateway: MockGateway) {+// F1 collateral: the router now probes the MCP transport in BOTH discover and install.+// Every app injects a `probe` derived from the REAL producer (`probeMcpTransport` bound+// to a fixture transport) — never a hand-stubbed outcome — so no test escapes to the+// network. `GENERIC_ALIVE_TRANSPORT` mirrors the real pilots: a tokenless POST+// `initialize` answers 401 with a Bearer challenge (transport alive, token required).+const PROBE_DNS = async () => ['93.184.216.34']+const GENERIC_ALIVE_TRANSPORT: PinnedTransport = async ({ method }) =>+ method === 'POST'+ ? { status: 401, headers: { 'www-authenticate': 'Bearer realm="OAuth"' }, bodyText: '' }+ : { status: 404, headers: {}, bodyText: '' }++/** Bind the real `probeMcpTransport` to a fixture transport + offline DNS (T1). */+function boundProbe(transport: PinnedTransport): typeof probeMcpTransport {+ return (baseUrl, deps, opts) =>+ probeMcpTransport(baseUrl, { ...deps, transport, resolveDns: PROBE_DNS }, opts)+}+const genericProbe = boundProbe(GENERIC_ALIVE_TRANSPORT)+/** Vercel: POST `/mcp` → 404 (dead), POST `/` → 200, root PRM → suggested `/`. */+const vercelProbe = boundProbe(makeDiscoveryTransport(VERCEL_PILOT))+/** A 5xx POST → inconclusive/unexpected_status (must NOT block install). */+const inconclusiveProbe = boundProbe(async () => ({ status: 503, headers: {}, bodyText: '' }))++// Real Vercel DiscoveryResult, derived from the real producer (T1): the actual+// discovery client run against the 2026-09-25 Vercel probe fixtures.+let vercelResult: DiscoveryResult++function makeApp(gateway: MockGateway, probe: typeof probeMcpTransport = genericProbe) {const app = express()app.use(express.json())- app.use(createAdminRemoteMcpRouter(gateway as unknown as K8sGateway))+ app.use(createAdminRemoteMcpRouter(gateway as unknown as K8sGateway, { probe }))app.use((err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {res.status(500).json({ error: err instanceof Error ? err.message : 'unknown' })@@ -88,6 +117,14 @@ beforeAll(async () => {})if (!outcome.ok) throw new Error(`fixture discovery failed: ${outcome.error.kind}`)notionResult = outcome.result++ const vercelOutcome = await actual.discoverRemoteOAuth(VERCEL_PILOT.mcpUrl, {+ transport: makeDiscoveryTransport(VERCEL_PILOT),+ resolveDns: async () => ['93.184.216.34'],+ })+ if (!vercelOutcome.ok)+ throw new Error(`vercel fixture discovery failed: ${vercelOutcome.error.kind}`)+ vercelResult = vercelOutcome.result})beforeEach(() => {@@ -148,6 +185,36 @@ describe('POST /admin/mcp-servers/remote/discover (dry-run)', () => {expect(res.status).toBe(400)expect(res.body.error).toBe('discovery_failed')})++ // Repro (issue 26-09-25): OAuth discovery resolves on Vercel's `/mcp` path, but the+ // MCP transport there is dead (404). Detect must surface a `dead` verdict + the+ // canonical-root suggestion WITHOUT changing the OAuth `detected` block.+ it('Vercel /mcp: discovery ok but the transport probe reports dead + suggests the root → 200', async () => {+ mockDiscovery(vercelResult)+ const res = await request(makeApp(gatewayWithContext(), vercelProbe))+ .post('/admin/mcp-servers/remote/discover')+ .send({ baseUrl: 'https://mcp.vercel.com/mcp' })+ expect(res.status).toBe(200)+ // OAuth `detected` is unchanged: the path-suffixed PRM resource is what fooled Detect.+ expect(res.body.detected.resource).toBe('https://mcp.vercel.com/mcp')+ // The new sibling: transport probe verdict.+ expect(res.body.transport).toEqual({+ status: 'dead',+ probedUrl: 'https://mcp.vercel.com/mcp',+ httpStatus: 404,+ suggestedBaseUrl: 'https://mcp.vercel.com/',+ })+ })++ it('Notion /mcp: transport probe reports alive with a challenge → 200', async () => {+ mockDiscovery(notionResult)+ const res = await request(makeApp(gatewayWithContext()))+ .post('/admin/mcp-servers/remote/discover')+ .send({ baseUrl: 'https://mcp.notion.com/mcp' })+ expect(res.status).toBe(200)+ expect(res.body.transport.status).toBe('alive')+ expect(res.body.transport.challenge).toBe(true)+ })})describe('POST /admin/mcp-servers/remote (install saga)', () => {@@ -441,6 +508,67 @@ describe('POST /admin/mcp-servers/remote (install saga)', () => {})expect(res.status).toBe(400)})++ // Repro (issue 26-09-25, T3+T4): a Vercel `/mcp` install passes OAuth discovery (mode+ // dcr) but the transport there is dead (404). The hard gate must return 400+ // `transport_unreachable` BEFORE minting any AS client or writing K8s — observable:+ // no DCR POST, no CR, Context allowlist untouched.+ it('Vercel /mcp install (dcr): transport probe dead → 400 transport_unreachable, nothing minted or written', async () => {+ mockDiscovery(vercelResult)+ const { db } = makeInMemoryDynamicClientsDb()+ const { transport: dcrTransport, calls } = makeDcrTransport({+ responseJson: JSON.stringify(DCR_PUBLIC_REGISTRATION_RESPONSE),+ })+ const gw = gatewayWithContext('ctx-a')+ const app = express()+ app.use(express.json())+ app.use(+ createAdminRemoteMcpRouter(gw as unknown as K8sGateway, {+ db,+ dcr: { transport: dcrTransport, resolveDns: PROBE_DNS },+ probe: vercelProbe,+ })+ )+ const res = await request(app).post('/admin/mcp-servers/remote').send({+ serverName: 'vercel-remote',+ contextRef: 'ctx-a',+ baseUrl: 'https://mcp.vercel.com/mcp',+ mode: 'dcr',+ })+ expect(res.status).toBe(400)+ expect(res.body.error).toBe('transport_unreachable')+ expect(res.body.detail).toMatchObject({+ probedUrl: 'https://mcp.vercel.com/mcp',+ httpStatus: 404,+ suggestedBaseUrl: 'https://mcp.vercel.com/',+ })+ // No AS client minted (the DCR POST never fired).+ expect(calls).toHaveLength(0)+ // No CR written.+ await expect(gw.getResource('mcpservers', 'vercel-remote', NS)).rejects.toThrow()+ // Context allowlist untouched.+ const ctx = (await gw.getResource('contexts', 'ctx-a', NS)) as {+ spec: { mcpServers?: string[] }+ }+ expect(ctx.spec.mcpServers ?? []).not.toContain('vercel-remote')+ })++ // An inconclusive probe (5xx) must NOT block: the install proceeds to 201.+ it('install proceeds to 201 when the transport probe is inconclusive (5xx)', async () => {+ mockDiscovery(notionResult)+ const gw = gatewayWithContext('ctx-a')+ const res = await request(makeApp(gw, inconclusiveProbe))+ .post('/admin/mcp-servers/remote')+ .send({+ serverName: 'inconclusive-remote',+ contextRef: 'ctx-a',+ baseUrl: 'https://mcp.notion.com/mcp',+ mode: 'cimd',+ })+ expect(res.status).toBe(201)+ // The CR was written despite the inconclusive probe.+ await expect(gw.getResource('mcpservers', 'inconclusive-remote', NS)).resolves.toBeTruthy()+ })})// ─── C2: DCR install saga (spec 02 C2, DEC-18/DEC-19) ───────────────────────@@ -488,7 +616,11 @@ describe('POST /admin/mcp-servers/remote — DCR install saga (C2)', () => {function makeAppWithDeps(gateway: MockGateway, deps: AdminRemoteMcpDeps) {const app = express()app.use(express.json())- app.use(createAdminRemoteMcpRouter(gateway as unknown as K8sGateway, deps))+ // Inject the generic-alive probe by default (F1 collateral: DCR installs baseUrl+ // mcp.notion.com/mcp, which probes alive); a test may override via `deps.probe`.+ app.use(+ createAdminRemoteMcpRouter(gateway as unknown as K8sGateway, { probe: genericProbe, ...deps })+ )app.use((err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {res.status(500).json({ error: err instanceof Error ? err.message : 'unknown' })