Skip to content

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

TypeScript
6.2 KB
Raw Blame
import { config } from './config'
import { GFS_HOST_SCOPES } from './gfsHostPolicy'
import { makeExpectedHostGfsSubject } from './gfsHostSubject'
import { signInternalControlJwt } from './utils/internalControlSigner'

/**
 * HCC 1st-party host gfs token minting (spec community.md §Subjects, plan
 * P3-S02). HCC asks control-api (the sole gfs token minter) for a host token and
 * mounts it on the Host's mcp-host pod.
 *
 * The Host's trusted Kubernetes namespace/name is the durable GFS principal.
 * For example, the `mcp-host/chatllm` Host receives
 * `host:1st:mcp-host/chatllm`; another Host is never authorized through the
 * same binding, and HCC validates that control-api returns that exact subject
 * before exposing the credential to Kubernetes. The token ceiling permits the
 * Control UI's supported Host operations, read and write; resource grants
 * still decide which concrete resources the Host may access.
 */

export interface GfsHostToken {
  token: string
  expiresInSeconds: number
  subject: string
}

/** Dependencies, injectable so the mint is unit-tested without a live control-api. */
export interface GfsHostBindingDeps {
  controlApiBaseUrl?: string
  /** Signs an HCC InternalControl JWT (iss=hcc). */
  signToken?: () => string
  fetchFn?: typeof fetch
}

export interface GfsFirstPartyHostRef {
  name: string
  namespace: string
}

export const GFS_HOST_TOKEN_REQUEST_TIMEOUT_MS = 10_000
export const GFS_HOST_TOKEN_REQUEST_TIMEOUT_CODE = 'HCC_GFS_HOST_TOKEN_REQUEST_TIMEOUT'
// Single source of truth: the capability ceiling shared with the reconciler's
// drift metadata. Managed agents are never granted anything beyond read+write.
const GFS_HOST_TOKEN_SCOPES = GFS_HOST_SCOPES

function validateIssuedTokenClaims(
  token: unknown,
  expectedSubject: string
): asserts token is string {
  if (typeof token !== 'string') {
    throw new Error('gfs host token is not a JWT')
  }

  const segments = token.split('.')
  if (segments.length !== 3 || segments.some(segment => !/^[A-Za-z0-9_-]+$/.test(segment))) {
    throw new Error('gfs host token is not a JWT')
  }

  let claims: unknown
  try {
    claims = JSON.parse(Buffer.from(segments[1], 'base64url').toString('utf8'))
  } catch {
    throw new Error('gfs host token has a malformed JWT payload')
  }

  if (typeof claims !== 'object' || claims === null || Array.isArray(claims)) {
    throw new Error('gfs host token has a malformed JWT payload')
  }

  const payload = claims as Record<string, unknown>
  if (payload.sub !== expectedSubject) {
    throw new Error(
      `gfs host token claim subject mismatch: expected ${expectedSubject}, received ${String(payload.sub)}`
    )
  }

  // Compare as a set: the ceiling is exactly these scopes, but a benign
  // ordering change in control-api's scope handling must not brick every
  // Host reconcile fleet-wide.
  const scopes = payload.scopes
  if (
    !Array.isArray(scopes) ||
    scopes.length !== GFS_HOST_TOKEN_SCOPES.length ||
    !GFS_HOST_TOKEN_SCOPES.every(scope => scopes.includes(scope))
  ) {
    throw new Error(
      `gfs host token claim scopes mismatch: expected ${JSON.stringify(GFS_HOST_TOKEN_SCOPES)}`
    )
  }
}

export class GfsHostTokenMintTimeoutError extends Error {
  readonly code = GFS_HOST_TOKEN_REQUEST_TIMEOUT_CODE

  constructor(
    readonly timeoutMs: number,
    options?: { cause?: unknown }
  ) {
    super(
      `gfs host token mint exceeded its ${timeoutMs}ms deadline`,
      options?.cause === undefined ? undefined : { cause: options.cause }
    )
    this.name = 'GfsHostTokenMintTimeoutError'
  }
}

export class GfsHostTokenValidationError extends Error {
  constructor(message: string) {
    super(message)
    this.name = 'GfsHostTokenValidationError'
  }
}

/**
 * Mint a 1st-party host gfs token via control-api's provisioner route. Fails
 * loud on any non-2xx — a host without a working gfs token must surface, never
 * silently degrade.
 */
export async function mintHostGfsToken(
  host: GfsFirstPartyHostRef,
  deps: GfsHostBindingDeps = {}
): Promise<GfsHostToken> {
  const expectedSubject = makeExpectedHostGfsSubject(host.namespace, host.name)
  if (!expectedSubject) {
    throw new Error('gfs host token mint requires a trusted Kubernetes namespace and name')
  }
  const baseUrl = deps.controlApiBaseUrl ?? config.controlApiBaseUrl
  const sign = deps.signToken ?? signInternalControlJwt
  const doFetch = deps.fetchFn ?? fetch
  const url = `${baseUrl}/api/v1/auth/gfs/${encodeURIComponent(host.name)}/tokens`
  const timeoutError = new GfsHostTokenMintTimeoutError(GFS_HOST_TOKEN_REQUEST_TIMEOUT_MS)
  const controller = new AbortController()
  const timer = setTimeout(() => controller.abort(timeoutError), GFS_HOST_TOKEN_REQUEST_TIMEOUT_MS)
  timer.unref?.()

  try {
    const response = await doFetch(url, {
      method: 'POST',
      headers: {
        'content-type': 'application/json',
        Authorization: `Bearer ${sign()}`,
      },
      body: JSON.stringify({
        namespace: host.namespace,
        scopes: [...GFS_HOST_TOKEN_SCOPES],
      }),
      signal: controller.signal,
    })
    if (controller.signal.aborted) throw timeoutError
    if (!response.ok) {
      throw new Error(`gfs host token mint failed: HTTP ${response.status}`)
    }
    const body = (await response.json()) as Partial<GfsHostToken>
    if (controller.signal.aborted) throw timeoutError
    if (
      typeof body.token !== 'string' ||
      body.token.length === 0 ||
      !Number.isSafeInteger(body.expiresInSeconds) ||
      (body.expiresInSeconds ?? 0) <= 0 ||
      typeof body.subject !== 'string'
    ) {
      throw new GfsHostTokenValidationError('gfs host token mint returned a malformed response')
    }
    if (body.subject !== expectedSubject) {
      throw new GfsHostTokenValidationError(
        `gfs host token subject mismatch: expected ${expectedSubject}, received ${body.subject}`
      )
    }
    validateIssuedTokenClaims(body.token, expectedSubject)
    return body as GfsHostToken
  } catch (error) {
    if (error instanceof GfsHostTokenMintTimeoutError) throw error
    if (controller.signal.aborted) {
      throw new GfsHostTokenMintTimeoutError(GFS_HOST_TOKEN_REQUEST_TIMEOUT_MS, {
        cause: error,
      })
    }
    throw error
  } finally {
    clearTimeout(timer)
  }
}