Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
12.8 KB
Raw Blame
/**
 * Client for communicating with the Context Mapper service.
 *
 * The Context Mapper provides McpServer CRDs via REST API, so mcp-host
 * doesn't need direct K8s access to McpServer resources.
 */
import { config } from './config'
import { McpServerInfo } from './types'

export interface McpServersResponse {
  servers: McpServerInfo[]
  timestamp: string
}

export interface AuthTokenResponse {
  token: string | null
  credentialRevision: string
}

const DEFAULT_CONTEXT_MAPPER_REQUEST_TIMEOUT_MS = 10_000
const MCP_SERVER_NAME_PATTERN = /^[a-z0-9](?:[-a-z0-9.]*[a-z0-9])?$/

export type ContextMapperRequestKind = 'inventory' | 'credential'

export class ContextMapperRequestError extends Error {
  constructor(
    readonly status: number,
    readonly kind: ContextMapperRequestKind,
    readonly authorizationFailure: boolean
  ) {
    super(
      authorizationFailure
        ? 'HCC caller authority was rejected'
        : `HCC ${kind} request failed with status ${status}`
    )
    this.name = 'ContextMapperRequestError'
  }
}

export class ContextMapperCredentialRevisionError extends Error {
  constructor() {
    super('HCC credential authority changed during retrieval')
    this.name = 'ContextMapperCredentialRevisionError'
  }
}

export function isContextMapperAuthorityRevocation(error: unknown): boolean {
  return (
    error instanceof ContextMapperCredentialRevisionError ||
    (error instanceof ContextMapperRequestError &&
      (error.authorizationFailure || (error.kind === 'credential' && error.status === 404)))
  )
}

/**
 * An inventory 404 means HCC could not resolve the authenticated Host's live
 * Context authority. Unlike a credential 404 (which retires one target), this
 * invalidates the complete locally-published MCP fleet.
 */
export function isContextMapperInventoryAuthorityRevocation(error: unknown): boolean {
  return (
    error instanceof ContextMapperRequestError && error.kind === 'inventory' && error.status === 404
  )
}

export interface ContextMapperAuthentication {
  getAccessToken(): string
  refreshOnUnauthorized(): Promise<void>
  /** Required so every authenticated client has a synchronous revocation hook. */
  onCallerAuthorizationFailure(status: 401 | 403): void
}

export interface ContextMapperClientOptions {
  requestTimeoutMs?: number
  authentication?: ContextMapperAuthentication
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === 'object' && !Array.isArray(value)
}

function decodeMcpServer(value: unknown): McpServerInfo {
  if (!isRecord(value)) throw new Error('HCC inventory response is malformed')
  if ('contextRef' in value || 'auth' in value || 'secretRef' in value || 'secretKey' in value) {
    throw new Error('HCC inventory response contains forbidden authority metadata')
  }
  if (typeof value.name !== 'string' || !MCP_SERVER_NAME_PATTERN.test(value.name)) {
    throw new Error('HCC inventory response contains an invalid server selector')
  }
  if (!isRecord(value.transport)) throw new Error('HCC inventory response is malformed')
  const transportType = value.transport.type
  if (!['sse', 'streamableHttp', 'stdio'].includes(String(transportType))) {
    throw new Error('HCC inventory response contains an invalid transport')
  }
  const transportUrl = value.transport.url
  if (transportUrl !== undefined && typeof transportUrl !== 'string') {
    throw new Error('HCC inventory response contains an invalid transport')
  }
  const transportPort = value.transport.port
  if (
    transportPort !== undefined &&
    (!Number.isSafeInteger(transportPort) ||
      (transportPort as number) < 1 ||
      (transportPort as number) > 65_535)
  ) {
    throw new Error('HCC inventory response contains an invalid transport port')
  }
  if (typeof value.enabled !== 'boolean' || typeof value.authRequired !== 'boolean') {
    throw new Error('HCC inventory response is malformed')
  }
  if (!isRecord(value.status)) throw new Error('HCC inventory response is malformed')
  if (typeof value.status.deployed !== 'boolean' || typeof value.status.ready !== 'boolean') {
    throw new Error('HCC inventory response is malformed')
  }
  if (
    value.credentialRevision !== undefined &&
    (typeof value.credentialRevision !== 'string' || !value.credentialRevision)
  ) {
    throw new Error('HCC inventory response contains an invalid credential revision')
  }
  if (value.authRequired && typeof value.credentialRevision !== 'string') {
    throw new Error('HCC authenticated server is missing its credential revision')
  }
  // authKind is non-secret policy (mini-spec §3.3): an absent value degrades to
  // `static` at dispatch (fail-closed); a present-but-unknown value is rejected,
  // consistent with the strictness of the rest of the decoder. authKind is NOT
  // on the forbidden-metadata denylist, so accepting it leaves that guard intact.
  if (
    value.authKind !== undefined &&
    !['static', 'oauth-user', 'oauth-context'].includes(String(value.authKind))
  ) {
    throw new Error('HCC inventory response contains an invalid authKind')
  }
  // `remote` is non-secret policy (mini-spec 19 §D-6), the sibling of authKind:
  // absent degrades to local (fail-safe default); a present-but-non-boolean value
  // is rejected, consistent with the decoder's strictness. HCC emits it
  // omit-when-false, so a real inventory carries it only for remote servers. Like
  // authKind it is NOT on the forbidden-metadata denylist, so accepting it leaves
  // that guard intact.
  if (value.remote !== undefined && typeof value.remote !== 'boolean') {
    throw new Error('HCC inventory response contains an invalid remote flag')
  }
  // `bearerInBody` is non-secret transport policy (mini-spec 19 §D-8), the sibling
  // of `remote`: absent → header (fail-safe default); present-but-non-boolean is
  // rejected; NOT on the forbidden-metadata denylist, so the guard stays intact.
  if (value.bearerInBody !== undefined && typeof value.bearerInBody !== 'boolean') {
    throw new Error('HCC inventory response contains an invalid bearerInBody flag')
  }

  return {
    name: value.name,
    ...(typeof value.description === 'string' ? { description: value.description } : {}),
    transport: {
      type: transportType as McpServerInfo['transport']['type'],
      ...(typeof transportUrl === 'string' ? { url: transportUrl } : {}),
      ...(typeof transportPort === 'number' ? { port: transportPort } : {}),
    },
    enabled: value.enabled,
    authRequired: value.authRequired,
    ...(typeof value.credentialRevision === 'string'
      ? { credentialRevision: value.credentialRevision }
      : {}),
    ...(typeof value.authKind === 'string'
      ? { authKind: value.authKind as McpServerInfo['authKind'] }
      : {}),
    ...(typeof value.remote === 'boolean' ? { remote: value.remote } : {}),
    ...(typeof value.bearerInBody === 'boolean' ? { bearerInBody: value.bearerInBody } : {}),
    status: {
      deployed: value.status.deployed,
      ready: value.status.ready,
      ...(typeof value.status.authoritative === 'boolean'
        ? { authoritative: value.status.authoritative }
        : {}),
    },
  }
}

function decodeInventoryResponse(value: unknown): McpServersResponse {
  if (!isRecord(value) || !Array.isArray(value.servers) || typeof value.timestamp !== 'string') {
    throw new Error('HCC inventory response is malformed')
  }
  return { servers: value.servers.map(decodeMcpServer), timestamp: value.timestamp }
}

function decodeCredentialResponse(value: unknown): AuthTokenResponse {
  if (!isRecord(value)) throw new Error('HCC credential response is malformed')
  const keys = Object.keys(value).sort()
  if (
    keys.length !== 2 ||
    keys[0] !== 'credentialRevision' ||
    keys[1] !== 'token' ||
    (value.token !== null && typeof value.token !== 'string') ||
    typeof value.credentialRevision !== 'string' ||
    !value.credentialRevision
  ) {
    throw new Error('HCC credential response is malformed')
  }
  return { token: value.token as string | null, credentialRevision: value.credentialRevision }
}

/**
 * Context Mapper client.
 */
export class ContextMapperClient {
  private baseUrl: string
  private requestTimeoutMs: number
  private authentication?: ContextMapperAuthentication

  constructor(
    baseUrl: string,
    options: number | ContextMapperClientOptions = DEFAULT_CONTEXT_MAPPER_REQUEST_TIMEOUT_MS
  ) {
    this.baseUrl = baseUrl.replace(/\/$/, '') // Remove trailing slash
    this.requestTimeoutMs =
      typeof options === 'number'
        ? options
        : (options.requestTimeoutMs ?? DEFAULT_CONTEXT_MAPPER_REQUEST_TIMEOUT_MS)
    this.authentication = typeof options === 'number' ? undefined : options.authentication
  }

  private fetch(input: string, init: RequestInit = {}): Promise<Response> {
    return fetch(input, {
      ...init,
      signal: AbortSignal.timeout(this.requestTimeoutMs),
    })
  }

  private accessToken(kind: ContextMapperRequestKind): string {
    let token = ''
    try {
      token = this.authentication?.getAccessToken().trim() ?? ''
    } catch {
      // Treat an unreadable local credential exactly like an HCC rejection:
      // revoke any already-published fleet before returning to the caller.
    }
    if (!token) {
      this.authentication?.onCallerAuthorizationFailure(401)
      throw new ContextMapperRequestError(401, kind, true)
    }
    return token
  }

  private async protectedFetch(
    path: string,
    kind: ContextMapperRequestKind,
    init: RequestInit = {}
  ): Promise<Response> {
    let retriedAfterRefresh = false
    for (;;) {
      const response = await this.fetch(`${this.baseUrl}${path}`, {
        ...init,
        headers: {
          Accept: 'application/json',
          ...init.headers,
          Authorization: `Bearer ${this.accessToken(kind)}`,
        },
      })

      if (response.status === 401 && !retriedAfterRefresh && this.authentication) {
        retriedAfterRefresh = true
        try {
          await this.authentication.refreshOnUnauthorized()
        } catch {
          this.authentication.onCallerAuthorizationFailure(401)
          throw new ContextMapperRequestError(401, kind, true)
        }
        continue
      }

      if (response.status === 401 || response.status === 403) {
        this.authentication?.onCallerAuthorizationFailure(response.status)
        throw new ContextMapperRequestError(response.status, kind, true)
      }
      if (!response.ok) {
        throw new ContextMapperRequestError(response.status, kind, false)
      }
      return response
    }
  }

  /**
   * Health check.
   */
  async healthCheck(): Promise<boolean> {
    try {
      const response = await this.fetch(`${this.baseUrl}/ready`)
      return response.ok
    } catch {
      console.error('[ContextMapper] Health check failed (reason=transport)')
      return false
    }
  }

  /**
   * List only the McpServers authorized for the authenticated Host. The old
   * global/context-selecting v1 routes are intentionally not represented by
   * this client.
   */
  async listServersForHost(): Promise<McpServerInfo[]> {
    const response = await this.protectedFetch('/api/v2/hosts/self/mcpservers', 'inventory')
    const data = decodeInventoryResponse(await response.json())
    console.log(`[ContextMapper] Received ${data.servers.length} authorized MCP server(s)`)
    return data.servers
  }

  /**
   * Get auth token for an McpServer.
   */
  async getAuthToken(
    serverName: string,
    expectedCredentialRevision?: string
  ): Promise<string | undefined> {
    if (!expectedCredentialRevision) {
      throw new ContextMapperCredentialRevisionError()
    }
    const response = await this.protectedFetch(
      '/api/v2/hosts/self/mcpservers/credential',
      'credential',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ serverName }),
      }
    )
    const data = decodeCredentialResponse(await response.json())
    if (data.credentialRevision !== expectedCredentialRevision) {
      throw new ContextMapperCredentialRevisionError()
    }
    return data.token ?? undefined
  }

  /**
   * Poll for changes to McpServers.
   * Returns only authoritative snapshots. Transport and HTTP failures reject
   * so callers preserve their last known fleet instead of treating an
   * unavailable controller as an authoritative empty inventory.
   */
  async pollServers(): Promise<{ servers: McpServerInfo[]; timestamp: string }> {
    const response = await this.protectedFetch('/api/v2/hosts/self/mcpservers', 'inventory')
    const data = decodeInventoryResponse(await response.json())
    return { servers: data.servers, timestamp: data.timestamp }
  }
}

// Default client instance (configured from environment)
let defaultClient: ContextMapperClient | null = null

export function getContextMapperClient(
  authentication: ContextMapperAuthentication
): ContextMapperClient {
  if (!defaultClient) {
    defaultClient = new ContextMapperClient(config.contextMapperUrl, { authentication })
  }
  return defaultClient
}