Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* HTTP REST API server for Context Mapper.
*/
import * as http from 'http'
import { config } from './config'
import { HostReconciler } from './hostReconciler'
import { McpServerProvider } from './k8sClient'
import { hccLogger } from './logger'
import {
McpApiAuthenticationError,
McpApiAuthenticator,
type VerifiedMcpHostPrincipal,
} from './mcpApiAuthentication'
import {
McpAuthorizationError,
McpAuthorizationService,
toPublicMcpTransport,
} from './mcpAuthorization'
import { mcpHostApiRequestsTotal, registry } from './metrics'
import {
type ReadinessInventoryDetail,
type ReadinessReason,
probeReadinessReasonsFromDetail,
readinessReasonsFromDetail,
} from './readinessGate'
import { McpServersResponse } from './types'
const readinessLog = hccLogger.child({ module: 'readiness' })
const MCP_SELECTOR_RE = /^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$/
const MCP_REQUEST_BODY_LIMIT = 1024
const mcpApiLog = hccLogger.child({ module: 'mcp-host-api' })
type McpHostApiAction = 'inventory' | 'credential'
type RateLimitEntry = { windowStartMs: number; count: number }
/** Per-Host, per-action fixed-window limiter applied only after JWT validation. */
export class McpHostApiRateLimiter {
private readonly entries = new Map<string, RateLimitEntry>()
constructor(
private readonly maxPerMinute: number,
private readonly now: () => number = Date.now
) {}
consume(
hostUid: string,
action: McpHostApiAction
): { allowed: true } | { allowed: false; retryAfterSeconds: number } {
const nowMs = this.now()
const key = `${hostUid}\u0000${action}`
const existing = this.entries.get(key)
if (!existing || nowMs - existing.windowStartMs >= 60_000) {
this.entries.set(key, { windowStartMs: nowMs, count: 1 })
this.prune(nowMs)
return { allowed: true }
}
if (existing.count >= this.maxPerMinute) {
return {
allowed: false,
retryAfterSeconds: Math.max(
1,
Math.ceil((60_000 - (nowMs - existing.windowStartMs)) / 1000)
),
}
}
existing.count += 1
return { allowed: true }
}
private prune(nowMs: number): void {
if (this.entries.size <= 10_000) return
for (const [key, entry] of this.entries) {
if (nowMs - entry.windowStartMs >= 60_000) this.entries.delete(key)
}
while (this.entries.size > 10_000) {
const oldest = this.entries.keys().next()
if (oldest.done) break
this.entries.delete(oldest.value)
}
}
}
type ReadinessLane = 'probe' | 'request'
type ReadinessState =
| { ready: true; status: 'ready' }
| {
ready: false
status: 'starting' | 'degraded'
message: string
reasons?: ReadinessReason[]
}
export class ContextMapperServer {
private server: http.Server | null = null
private provider: McpServerProvider
private port: number
private hostReconciler: HostReconciler | null
private hasDesktopFn: ((hostRef: string) => boolean) | null
private mcpAuthenticator: McpApiAuthenticator | null
private mcpAuthorization: McpAuthorizationService | null
private mcpRateLimiter: McpHostApiRateLimiter
private providerAuthoritativeFn: () => boolean
private hostAuthoritativeFn: () => boolean
private readinessDetailFn: (() => ReadinessInventoryDetail) | undefined
private probeAuthoritativeFn: (() => boolean) | undefined
private ready = false
private lastReadinessTransitionKey = ''
private lastProbeReadinessTransitionKey = ''
constructor(
provider: McpServerProvider,
port: number = config.port,
hostReconciler?: HostReconciler,
hasDesktopFn?: (hostRef: string) => boolean,
// Fails closed. Per-request data endpoints assert that no stale allow is
// live, and a caller that omits this gate gets no type error, so the
// default must withhold authority rather than grant it.
providerAuthoritativeFn: () => boolean = () => false,
// Desktop status needs ONLY Host inventory authority, not the full
// readiness inventory. Fails closed like providerAuthoritativeFn: a caller
// that omits it gets a 503 on desktop rather than a wrong 200 'inactive'.
hostAuthoritativeFn: () => boolean = () => false,
mcpAuthenticator?: McpApiAuthenticator,
mcpAuthorization?: McpAuthorizationService,
readinessDetailFn?: () => ReadinessInventoryDetail,
// Optional kubelet /ready gate. When omitted, /ready falls back to
// providerAuthoritativeFn (6-clause) so omitting this argument can never
// weaken readiness. Production wires resolveProbeAuthoritativeFn so the
// probe ignores phase-2 certification.
probeAuthoritativeFn?: () => boolean
) {
this.provider = provider
this.port = port
this.hostReconciler = hostReconciler ?? null
this.hasDesktopFn = hasDesktopFn ?? null
this.mcpAuthenticator = mcpAuthenticator ?? null
this.mcpAuthorization = mcpAuthorization ?? null
this.mcpRateLimiter = new McpHostApiRateLimiter(config.mcpHostApiRateLimitPerMinute)
this.providerAuthoritativeFn = providerAuthoritativeFn
this.hostAuthoritativeFn = hostAuthoritativeFn
this.readinessDetailFn = readinessDetailFn
this.probeAuthoritativeFn = probeAuthoritativeFn
}
/**
* Host inventory authority, fail-closed on error — the desktop route's only
* authority gate. Same shape as the provider check in getReadinessState().
*/
private safeHostAuthoritative(): boolean {
try {
return this.hostAuthoritativeFn()
} catch (err) {
readinessLog.error('host authority check failed', { err })
return false
}
}
/**
* Mark the server as ready once the provider warm-up has completed.
*/
setReady(ready: boolean): void {
this.ready = ready
}
private collectLaneReasons(lane: ReadinessLane): ReadinessReason[] | undefined {
if (!this.readinessDetailFn) return undefined
try {
const detail = this.readinessDetailFn()
return lane === 'probe'
? probeReadinessReasonsFromDetail(detail)
: readinessReasonsFromDetail(detail)
} catch (err) {
readinessLog.error(
lane === 'probe' ? 'probe readiness detail check failed' : 'readiness detail check failed',
{ err, lane }
)
return undefined
}
}
private emitReadinessTransition(state: ReadinessState, lane: ReadinessLane): void {
const keyHolder =
lane === 'probe' ? 'lastProbeReadinessTransitionKey' : 'lastReadinessTransitionKey'
const reasons = !state.ready ? (state.reasons ?? []) : []
const key = `${state.ready}:${state.status}:${reasons.join(',')}`
if (key === this[keyHolder]) return
this[keyHolder] = key
if (state.ready) {
readinessLog.info('readiness became ready', { lane })
return
}
readinessLog.warn('readiness not ready', { lane, status: state.status, reasons })
}
private evaluateAuthoritativeLane(
lane: ReadinessLane,
authoritativeFn: () => boolean
): ReadinessState {
if (!this.ready) {
const starting: ReadinessState = {
ready: false,
status: 'starting',
message: 'Context mapper is still starting',
}
this.emitReadinessTransition(starting, lane)
return starting
}
try {
if (authoritativeFn()) {
const ready: ReadinessState = { ready: true, status: 'ready' }
this.emitReadinessTransition(ready, lane)
return ready
}
} catch (err) {
readinessLog.error(
lane === 'probe'
? 'probe authority readiness check failed'
: 'provider authority readiness check failed',
{ err, lane }
)
}
const degraded: ReadinessState = {
ready: false,
status: 'degraded',
message:
lane === 'probe'
? 'Context mapper watch inventory is not fresh'
: 'Context mapper provider inventory is not authoritative',
reasons: this.collectLaneReasons(lane),
}
this.emitReadinessTransition(degraded, lane)
return degraded
}
private getReadinessState(): ReadinessState {
return this.evaluateAuthoritativeLane('request', this.providerAuthoritativeFn)
}
/**
* Kubelet /ready state. When probeAuthoritativeFn is omitted, fall back to
* the 6-clause provider gate so omitting the 10th constructor argument
* cannot weaken readiness.
*/
private getProbeReadinessState(): ReadinessState {
if (this.probeAuthoritativeFn === undefined) {
return this.getReadinessState()
}
return this.evaluateAuthoritativeLane('probe', this.probeAuthoritativeFn)
}
private async handleRequest(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
const url = new URL(req.url || '/', `http://localhost:${this.port}`)
const isLegacyHostSelectedMcpRoute =
url.pathname.startsWith('/api/v1/mcpservers/context/') ||
(url.pathname.startsWith('/api/v1/mcpservers/') && url.pathname.endsWith('/auth'))
const isProtectedMcpRoute =
url.pathname.startsWith('/api/v2/hosts/self/mcpservers') || isLegacyHostSelectedMcpRoute
// The Host credential surface is service-to-service and deliberately has
// no browser wildcard CORS grant. Preserve the historical public CORS
// behavior only for unrelated/legacy endpoints.
if (!isProtectedMcpRoute) {
res.setHeader('Access-Control-Allow-Origin', '*')
res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS')
res.setHeader('Access-Control-Allow-Headers', 'Content-Type')
}
// Retire caller-selected Context/credential routes at the application
// boundary for every method, including preflight, and independently of
// readiness. This remains a defense if a caller bypasses the gateway.
if (isLegacyHostSelectedMcpRoute) {
this.sendProtectedJson(res, 410, { error: 'gone' })
return
}
if (req.method === 'OPTIONS') {
res.writeHead(204)
res.end()
return
}
// Root path - API information
if (req.method === 'GET' && url.pathname === '/') {
this.handleRoot(res)
return
}
// Health check
if (req.method === 'GET' && url.pathname === '/health') {
const readiness = this.getReadinessState()
this.sendJson(res, 200, {
status: 'ok',
ready: readiness.ready,
})
return
}
// Readiness check — watch freshness only when a probe gate is wired.
if (req.method === 'GET' && url.pathname === '/ready') {
const readiness = this.getProbeReadinessState()
const body: { status: string; ready: boolean; reasons?: ReadinessReason[] } = {
status: readiness.status,
ready: readiness.ready,
}
if (!readiness.ready && readiness.reasons && readiness.reasons.length > 0) {
body.reasons = readiness.reasons
}
this.sendJson(res, readiness.ready ? 200 : 503, body)
return
}
// Prometheus metrics
if (req.method === 'GET' && url.pathname === '/metrics') {
const metrics = await registry.metrics()
res.writeHead(200, { 'Content-Type': registry.contentType })
res.end(metrics)
return
}
// Desktop status: Host inventory is the ONLY authority this route needs, so
// it is gated here — ABOVE the blanket readiness gate — on Host authority
// alone. A degraded McpServer/Context lane must NOT 503 desktop, and a
// degraded Host lane must 503 it (never answer 200 'inactive' from a stale
// cache). See the E3 design note's endpoint→authority matrix.
if (req.method === 'GET' && url.pathname.startsWith('/api/v1/desktop/')) {
if (!this.ready || !this.safeHostAuthoritative()) {
this.sendJson(res, 503, {
error: 'Service Unavailable',
message: 'Host inventory is not authoritative',
})
return
}
if (!this.checkDesktopAuth(req, res)) return
const hostRef = url.pathname.replace('/api/v1/desktop/', '')
await this.handleDesktopStatus(res, hostRef)
return
}
const readiness = this.getReadinessState()
if (!readiness.ready) {
// NP-08: protected MCP routes get an opaque, uniform authorization error
// instead of the generic readiness message, preserving the caller-binding
// contract even while the authority inventory is still warming up.
if (isProtectedMcpRoute) {
this.sendProtectedJson(res, 503, { error: 'authorization_unavailable' })
return
}
this.sendJson(res, 503, {
error: 'Service Unavailable',
message: readiness.message,
})
return
}
if (url.pathname === '/api/v2/hosts/self/mcpservers') {
if (req.method === 'GET') {
await this.handleHostMcpServers(req, res)
} else {
this.sendProtectedJson(res, 405, { error: 'method_not_allowed' }, { Allow: 'GET' })
}
return
}
if (url.pathname === '/api/v2/hosts/self/mcpservers/credential') {
if (req.method === 'POST') {
await this.handleHostMcpCredential(req, res)
} else {
this.sendProtectedJson(res, 405, { error: 'method_not_allowed' }, { Allow: 'POST' })
}
return
}
// List all McpServers (temporary PR 2 compatibility residual).
if (req.method === 'GET' && url.pathname === '/api/v1/mcpservers') {
await this.handleListAll(req, res, url)
return
}
// Desktop status is handled above (Host-authority-gated, ABOVE the readiness
// gate). The v1 caller-selected Context/credential routes are retired at the
// application boundary (410) earlier in this handler; NP-08 removed their
// handlers, so no route block belongs here.
// 404
if (isProtectedMcpRoute) {
this.sendProtectedJson(res, 404, { error: 'not_found' })
return
}
this.sendJson(res, 404, { error: 'Not Found', message: 'Endpoint not found' })
}
/**
* Verify the desktop API token from the Authorization header.
* Skips check when desktopApiToken is empty (dev mode).
*/
private checkDesktopAuth(req: http.IncomingMessage, res: http.ServerResponse): boolean {
const token = config.desktopApiToken
if (!token) return true // skip auth in dev mode
const authHeader = req.headers.authorization
if (!authHeader || authHeader !== `Bearer ${token}`) {
this.sendJson(res, 401, {
error: 'Unauthorized',
message: 'Invalid or missing service token',
})
return false
}
return true
}
private authenticateMcpHost(
req: http.IncomingMessage,
res: http.ServerResponse,
action: McpHostApiAction
): VerifiedMcpHostPrincipal | null {
if (!this.mcpAuthenticator || !this.mcpAuthorization) {
mcpApiLog.error('MCP authorization authority unavailable', {
reason: 'verifier_not_configured',
})
mcpHostApiRequestsTotal.inc({ action, outcome: 'error', reason: 'unconfigured' }, 1)
this.sendProtectedJson(res, 503, { error: 'authorization_unavailable' })
return null
}
try {
return this.mcpAuthenticator.authenticate(req.headers, req.rawHeaders)
} catch (error) {
const reason =
error instanceof McpApiAuthenticationError ? 'invalid_bearer' : 'verifier_error'
mcpApiLog.info('MCP request denied', { reason })
mcpHostApiRequestsTotal.inc({ action, outcome: 'denied', reason }, 1)
this.sendProtectedJson(
res,
401,
{ error: 'unauthorized' },
{ 'WWW-Authenticate': 'Bearer realm="host-context-controller"' }
)
return null
}
}
private async handleHostMcpServers(
req: http.IncomingMessage,
res: http.ServerResponse
): Promise<void> {
const principal = this.authenticateMcpHost(req, res, 'inventory')
if (!principal || !this.mcpAuthorization) return
if (!this.enforceMcpRateLimit(principal, 'inventory', res)) return
try {
const servers = await this.mcpAuthorization.listServers(principal)
mcpHostApiRequestsTotal.inc({ action: 'inventory', outcome: 'success', reason: 'ok' }, 1)
this.sendProtectedJson(res, 200, { servers, timestamp: new Date().toISOString() })
} catch (error) {
this.sendMcpAuthorizationError(res, error, 'inventory')
}
}
private async handleHostMcpCredential(
req: http.IncomingMessage,
res: http.ServerResponse
): Promise<void> {
const principal = this.authenticateMcpHost(req, res, 'credential')
if (!principal || !this.mcpAuthorization) return
if (!this.enforceMcpRateLimit(principal, 'credential', res)) return
const contentType = String(req.headers['content-type'] ?? '')
.split(';', 1)[0]
.trim()
if (contentType !== 'application/json') {
this.sendProtectedJson(res, 415, { error: 'unsupported_media_type' })
return
}
let body: unknown
try {
body = await this.readBoundedJsonBody(req)
} catch (error) {
const status = error instanceof Error && error.message === 'body_too_large' ? 413 : 400
this.sendProtectedJson(res, status, {
error: status === 413 ? 'payload_too_large' : 'bad_request',
})
return
}
const bodyKeys =
body && typeof body === 'object' && !Array.isArray(body) ? Object.keys(body) : []
const serverName =
bodyKeys.length === 1 && bodyKeys[0] === 'serverName'
? (body as { serverName?: unknown }).serverName
: undefined
if (
typeof serverName !== 'string' ||
serverName.length > 253 ||
serverName.trim() !== serverName ||
!MCP_SELECTOR_RE.test(serverName)
) {
this.sendProtectedJson(res, 400, { error: 'bad_request' })
return
}
try {
const credential = await this.mcpAuthorization.getCredential(principal, serverName)
mcpHostApiRequestsTotal.inc({ action: 'credential', outcome: 'success', reason: 'ok' }, 1)
this.sendProtectedJson(res, 200, credential)
} catch (error) {
this.sendMcpAuthorizationError(res, error, 'credential')
}
}
private async readBoundedJsonBody(req: http.IncomingMessage): Promise<unknown> {
const declared = Number(req.headers['content-length'] ?? 0)
if (Number.isFinite(declared) && declared > MCP_REQUEST_BODY_LIMIT) {
throw new Error('body_too_large')
}
const chunks: Buffer[] = []
let size = 0
for await (const chunk of req) {
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
size += buffer.length
if (size > MCP_REQUEST_BODY_LIMIT) throw new Error('body_too_large')
chunks.push(buffer)
}
if (size === 0) throw new Error('invalid_json')
return JSON.parse(Buffer.concat(chunks).toString('utf8'))
}
private sendMcpAuthorizationError(
res: http.ServerResponse,
error: unknown,
action: McpHostApiAction
): void {
const code = error instanceof McpAuthorizationError ? error.code : 'authorization_unavailable'
mcpApiLog.info('MCP request denied', { action, reason: code })
mcpHostApiRequestsTotal.inc({ action, outcome: 'denied', reason: code }, 1)
if (code === 'unauthorized') {
this.sendProtectedJson(
res,
401,
{ error: 'unauthorized' },
{ 'WWW-Authenticate': 'Bearer realm="host-context-controller"' }
)
return
}
if (code === 'not_found') {
this.sendProtectedJson(res, 404, { error: 'not_found' })
return
}
if (code === 'credential_unavailable') {
this.sendProtectedJson(res, 503, { error: 'credential_unavailable' })
return
}
this.sendProtectedJson(res, 503, { error: 'authorization_unavailable' })
}
private enforceMcpRateLimit(
principal: VerifiedMcpHostPrincipal,
action: McpHostApiAction,
res: http.ServerResponse
): boolean {
const result = this.mcpRateLimiter.consume(principal.hostUid, action)
if (result.allowed) return true
mcpApiLog.info('MCP request denied', { action, reason: 'rate_limited' })
mcpHostApiRequestsTotal.inc({ action, outcome: 'denied', reason: 'rate_limited' }, 1)
this.sendProtectedJson(
res,
429,
{ error: 'rate_limited' },
{ 'Retry-After': String(result.retryAfterSeconds) }
)
return false
}
private sendProtectedJson(
res: http.ServerResponse,
status: number,
data: unknown,
headers: Record<string, string> = {}
): void {
res.writeHead(status, {
'Content-Type': 'application/json',
'Cache-Control': 'no-store, private',
Pragma: 'no-cache',
'X-Content-Type-Options': 'nosniff',
...headers,
})
res.end(JSON.stringify(data))
}
/**
* Start the server.
*/
start(): Promise<void> {
return new Promise((resolve, reject) => {
this.server = http.createServer((req, res) => {
this.handleRequest(req, res).catch(err => {
console.error('[Server] Request handler failed:', err)
if (!res.headersSent) {
this.sendJson(res, 500, {
error: 'Internal Server Error',
message: 'Unhandled server error',
})
} else {
res.end()
}
})
})
this.server.on('error', err => {
console.error('[Server] Error:', err)
reject(err)
})
this.server.listen(this.port, () => {
console.log(`[Server] Context Mapper listening on port ${this.port}`)
console.log(`[Server] Endpoints:`)
console.log(`[Server] GET / - API information`)
console.log(`[Server] GET /health - Health check`)
console.log(`[Server] GET /ready - Readiness check`)
console.log(`[Server] GET /api/v1/mcpservers - List all McpServers`)
console.log(`[Server] GET /api/v2/hosts/self/mcpservers - Host-scoped MCP inventory`)
console.log(
`[Server] POST /api/v2/hosts/self/mcpservers/credential - Host-scoped MCP credential`
)
console.log(`[Server] GET /api/v1/desktop/:hostRef - Desktop status`)
resolve()
})
})
}
/**
* Handle GET / - Root endpoint with API information
*/
private handleRoot(res: http.ServerResponse): void {
const info = {
name: 'Context Mapper',
description:
'Kubernetes operator and REST API service for McpServer CRDs. ' +
'In production, it watches McpServer CRDs and automatically manages Deployments, ' +
'Services, and validates secrets for each MCP server. It also provides a REST API ' +
'for mcp-host to discover available MCP servers. ' +
'In dev mode, it reads server configurations from environment variables.',
version: '1.0.0',
mode: config.devMode ? 'development' : 'production',
endpoints: {
'GET /': 'This information page',
'GET /health': "Health check endpoint - returns { status: 'ok', ready: boolean }",
'GET /ready':
'Readiness endpoint - returns 200 after warm-up while watch inventory is fresh',
'GET /api/v1/mcpservers': 'List all McpServer resources',
'GET /api/v2/hosts/self/mcpservers': 'List MCP servers for the authenticated Host',
'POST /api/v2/hosts/self/mcpservers/credential':
'Get an authorized credential for the authenticated Host',
},
examples: {
listAll: `curl http://localhost:${this.port}/api/v1/mcpservers`,
},
stats: {
totalServers: this.provider.getAllServerInfos().length,
},
}
this.sendJson(res, 200, info)
}
/**
* Handle GET /api/v1/mcpservers
*/
private async handleListAll(
req: http.IncomingMessage,
res: http.ServerResponse,
url: URL
): Promise<void> {
console.log(`[Server] GET /api/v1/mcpservers`)
const servers = this.provider.getAllServerInfos().map(server => ({
name: server.name,
contextRef: server.contextRef,
transport: toPublicMcpTransport(server.transport),
enabled: server.enabled,
status: {
deployed: server.status.deployed,
ready: server.status.ready,
},
}))
const response: McpServersResponse = {
servers,
contextRef: '*',
timestamp: new Date().toISOString(),
}
this.sendProtectedJson(res, 200, response)
}
/**
* Send JSON response.
*/
private sendJson(res: http.ServerResponse, status: number, data: unknown): void {
res.writeHead(status, { 'Content-Type': 'application/json' })
res.end(JSON.stringify(data))
}
/**
* Handle GET /api/v1/desktop/:hostRef — Desktop status
*/
private async handleDesktopStatus(res: http.ServerResponse, hostRef: string): Promise<void> {
if (!hostRef) {
this.sendJson(res, 400, { error: 'Bad Request', message: 'hostRef is required' })
return
}
if (!this.hostReconciler) {
this.sendJson(res, 200, { status: 'inactive', message: 'Host reconciler not available' })
return
}
// Verify the host actually has spec.desktop enabled
if (this.hasDesktopFn && !this.hasDesktopFn(hostRef)) {
this.sendJson(res, 200, {
status: 'inactive',
hostRef,
message: 'Host does not have desktop enabled',
})
return
}
const status = this.hostReconciler.getStatus(hostRef)
if (status.deployed && status.ready) {
this.sendJson(res, 200, { status: 'running', hostRef })
} else {
this.sendJson(res, 200, { status: 'inactive', hostRef, message: status.message })
}
}
/**
* Stop the server.
*/
stop(): Promise<void> {
this.ready = false
const activeServer = this.server
this.server = null
return new Promise(resolve => {
if (activeServer) {
activeServer.close(() => {
console.log('[Server] Context Mapper stopped')
resolve()
})
} else {
resolve()
}
})
}
}