Skip to content

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

TypeScript
12.5 KB
Raw Blame
import * as k8s from '@kubernetes/client-node'

/**
 * Per-Host operator-managed env var management.
 *
 * Two K8s resources per Host:
 *   - ConfigMap `host-<hostRef>-env`         (non-secret values)
 *   - Secret    `host-<hostRef>-env-secret`  (secret values)
 *
 * Resources are created on demand at first write and persist after
 * delete-all. mcp-host ConfigStore watches both via the Kubernetes API
 * and merges them into the runtime env keyspace, so writes here propagate
 * to running pods within ~1 second without restart.
 */

export const RESERVED_PROVIDER_KEYS: ReadonlySet<string> = new Set([
  'OPENAI_API_KEY',
  'CLAUDE_API_KEY',
  'ZAI_API_KEY',
  'BAILIAN_API_KEY',
])

const MAX_KEYS_PER_HOST = 100
const MAX_KEY_NAME_LENGTH = 256
const MAX_NON_SECRET_VALUE_BYTES = 8 * 1024
const MAX_SECRET_VALUE_BYTES = 16 * 1024
const MAX_PAYLOAD_BYTES = 128 * 1024
const KEY_NAME_RE = /^[A-Z][A-Z0-9_]*$/

const SCOPE_LABEL = 'clerum.io/scope'
const HOST_LABEL = 'clerum.io/host'
const MANAGED_BY_LABEL = 'clerum.io/managed-by'

export interface HostEnvEntry {
  key: string
  secret: boolean
  updatedAt?: string
}

export interface HostEnvWriteEntry {
  key: string
  value: string
  secret: boolean
}

export interface HostEnvWriteResult {
  keys: HostEnvEntry[]
  /** Plaintext echo for newly-created/updated secrets in this PUT only. */
  showOnce: Record<string, string>
}

export class HostEnvServiceError extends Error {
  constructor(
    public readonly status: number,
    message: string,
    public readonly hint?: string
  ) {
    super(message)
    this.name = 'HostEnvServiceError'
  }
}

function badRequest(message: string, hint?: string): never {
  throw new HostEnvServiceError(400, message, hint)
}

function isErrorCode(err: unknown, code: number): boolean {
  if (!err || typeof err !== 'object') return false
  const e = err as { code?: number; statusCode?: number; response?: { statusCode?: number } }
  return e.code === code || e.statusCode === code || e.response?.statusCode === code
}

function utcNow(): string {
  return new Date().toISOString()
}

function validateKey(name: string): void {
  if (typeof name !== 'string') badRequest('key must be a string')
  if (name.length === 0 || name.length > MAX_KEY_NAME_LENGTH) {
    badRequest(`key length must be 1-${MAX_KEY_NAME_LENGTH}`)
  }
  if (!KEY_NAME_RE.test(name)) {
    badRequest(
      `Invalid key name "${name}". Must match [A-Z][A-Z0-9_]* (uppercase shell-style env var).`
    )
  }
  if (RESERVED_PROVIDER_KEYS.has(name)) {
    badRequest(
      `"${name}" is a reserved LLM provider-key name`,
      'Manage LLM provider keys via the LLM Secrets tab; do not set them through per-Host env.'
    )
  }
  if (name.startsWith('CLERUM_')) {
    badRequest(
      `"${name}" uses the reserved CLERUM_* prefix`,
      'CLERUM_* is reserved for infrastructure variables injected by HCC. Pick a different prefix.'
    )
  }
}

function utf8ByteLength(s: string): number {
  return Buffer.byteLength(s, 'utf-8')
}

function isUtf8(s: string): boolean {
  // String type already guarantees UTF-16 in memory; reject values that
  // contain the U+FFFD replacement char typical of bad transcodes. Plain
  // ASCII / UTF-8 text passes through cleanly.
  return !/�/.test(s)
}

export class HostEnvService {
  constructor(
    private readonly coreApi: k8s.CoreV1Api,
    private readonly namespace: string
  ) {}

  // ─── Naming helpers ───────────────────────────────────────────────

  private cmName(hostRef: string): string {
    return `host-${hostRef}-env`
  }

  private secretName(hostRef: string): string {
    return `host-${hostRef}-env-secret`
  }

  private commonLabels(hostRef: string): Record<string, string> {
    return {
      [MANAGED_BY_LABEL]: 'control-api',
      [SCOPE_LABEL]: 'host-env',
      [HOST_LABEL]: hostRef,
    }
  }

  // ─── Reads ────────────────────────────────────────────────────────

  /**
   * List names + metadata of all per-Host env vars. Never returns values.
   */
  async list(hostRef: string): Promise<HostEnvEntry[]> {
    const [cm, secret] = await Promise.all([
      this.readCm(hostRef),
      this.readSecret(hostRef),
    ])
    const entries: HostEnvEntry[] = []
    const cmTimestamp =
      cm?.metadata?.annotations?.['clerum.io/last-updated'] ||
      (cm?.metadata?.creationTimestamp ? String(cm.metadata.creationTimestamp) : undefined)
    const secretTimestamp =
      secret?.metadata?.annotations?.['clerum.io/last-updated'] ||
      (secret?.metadata?.creationTimestamp
        ? String(secret.metadata.creationTimestamp)
        : undefined)
    for (const k of Object.keys(cm?.data ?? {})) {
      entries.push({ key: k, secret: false, updatedAt: cmTimestamp })
    }
    for (const k of Object.keys(secret?.data ?? {})) {
      entries.push({ key: k, secret: true, updatedAt: secretTimestamp })
    }
    entries.sort((a, b) => a.key.localeCompare(b.key))
    return entries
  }

  // ─── Writes ───────────────────────────────────────────────────────

  /**
   * Upsert: keys not in the body are left alone (use deleteKey to remove).
   * Validates guardrails; rejects reserved/CLERUM_ names; enforces size
   * limits; refuses overlap between CM and Secret for the same Host.
   * Returns showOnce only for secrets created or updated by this call.
   */
  async putMany(hostRef: string, entries: HostEnvWriteEntry[]): Promise<HostEnvWriteResult> {
    if (!Array.isArray(entries) || entries.length === 0) {
      badRequest('Body must be a non-empty array of {key, value, secret}.')
    }

    // Per-entry validation.
    for (const e of entries) {
      if (!e || typeof e !== 'object') badRequest('Each entry must be an object.')
      validateKey(e.key)
      if (typeof e.value !== 'string') badRequest(`value for "${e.key}" must be a string`)
      if (typeof e.secret !== 'boolean') badRequest(`secret for "${e.key}" must be a boolean`)
      if (!isUtf8(e.value)) badRequest(`value for "${e.key}" must be UTF-8 (no binary)`)
      const max = e.secret ? MAX_SECRET_VALUE_BYTES : MAX_NON_SECRET_VALUE_BYTES
      if (utf8ByteLength(e.value) > max) {
        badRequest(`value for "${e.key}" exceeds ${max / 1024} KB`)
      }
    }

    // Reject duplicate keys within the body itself.
    const seen = new Set<string>()
    for (const e of entries) {
      if (seen.has(e.key)) badRequest(`Duplicate key in body: "${e.key}"`)
      seen.add(e.key)
    }

    // Read current state to merge against.
    const [existingCm, existingSecret] = await Promise.all([
      this.readCm(hostRef),
      this.readSecret(hostRef),
    ])
    const cmData: Record<string, string> = { ...(existingCm?.data ?? {}) }
    const secretRaw: Record<string, string> = { ...(existingSecret?.data ?? {}) }
    // existingSecret data is base64; decode for our cross-resource overlap
    // check and re-encode on write below via stringData (server-side).
    const decodedSecret: Record<string, string> = {}
    for (const [k, v] of Object.entries(secretRaw)) {
      decodedSecret[k] = Buffer.from(v, 'base64').toString('utf-8')
    }

    // Apply incoming writes, ensuring no key spans both kinds for the host.
    const showOnce: Record<string, string> = {}
    for (const e of entries) {
      if (e.secret) {
        if (cmData[e.key] !== undefined) {
          badRequest(
            `"${e.key}" already exists as a non-secret. Delete it first or change its kind.`
          )
        }
        decodedSecret[e.key] = e.value
        showOnce[e.key] = e.value
      } else {
        if (decodedSecret[e.key] !== undefined) {
          badRequest(`"${e.key}" already exists as a secret. Delete it first or change its kind.`)
        }
        cmData[e.key] = e.value
      }
    }

    // Aggregate guardrails.
    const totalKeys = Object.keys(cmData).length + Object.keys(decodedSecret).length
    if (totalKeys > MAX_KEYS_PER_HOST) {
      badRequest(`Per-Host env limit is ${MAX_KEYS_PER_HOST} keys; this write would exceed it.`)
    }
    const cmBytes = Object.values(cmData).reduce((acc, v) => acc + utf8ByteLength(v), 0)
    if (cmBytes > MAX_PAYLOAD_BYTES) {
      badRequest(`ConfigMap payload exceeds ${MAX_PAYLOAD_BYTES / 1024} KB`)
    }
    const secretBytes = Object.values(decodedSecret).reduce((acc, v) => acc + utf8ByteLength(v), 0)
    if (secretBytes > MAX_PAYLOAD_BYTES) {
      badRequest(`Secret payload exceeds ${MAX_PAYLOAD_BYTES / 1024} KB`)
    }

    // Persist. ConfigMap stores plaintext under .data. Secret stores values
    // under .stringData (K8s base64-encodes them server-side).
    const now = utcNow()
    await this.upsertCm(hostRef, cmData, now)
    await this.upsertSecret(hostRef, decodedSecret, now)

    const keys = await this.list(hostRef)
    return { keys, showOnce }
  }

  /**
   * Remove a single key from whichever resource holds it. 404 if absent.
   */
  async deleteKey(hostRef: string, key: string): Promise<void> {
    if (typeof key !== 'string' || !key) badRequest('key path param is required')
    const [cm, secret] = await Promise.all([this.readCm(hostRef), this.readSecret(hostRef)])
    const cmData: Record<string, string> = { ...(cm?.data ?? {}) }
    const secretData: Record<string, string> = { ...(secret?.data ?? {}) }
    let removed = false
    if (cmData[key] !== undefined) {
      delete cmData[key]
      removed = true
      await this.upsertCm(hostRef, cmData, utcNow())
    }
    if (secretData[key] !== undefined) {
      const decoded: Record<string, string> = {}
      for (const [k, v] of Object.entries(secretData)) {
        if (k === key) continue
        decoded[k] = Buffer.from(v, 'base64').toString('utf-8')
      }
      removed = true
      await this.upsertSecret(hostRef, decoded, utcNow())
    }
    if (!removed) {
      throw new HostEnvServiceError(404, `Key "${key}" not found on Host "${hostRef}"`)
    }
  }

  // ─── Internal CM/Secret persistence ──────────────────────────────

  private async readCm(hostRef: string): Promise<k8s.V1ConfigMap | null> {
    try {
      return await this.coreApi.readNamespacedConfigMap({
        namespace: this.namespace,
        name: this.cmName(hostRef),
      })
    } catch (err) {
      if (isErrorCode(err, 404)) return null
      throw err
    }
  }

  private async readSecret(hostRef: string): Promise<k8s.V1Secret | null> {
    try {
      return await this.coreApi.readNamespacedSecret({
        namespace: this.namespace,
        name: this.secretName(hostRef),
      })
    } catch (err) {
      if (isErrorCode(err, 404)) return null
      throw err
    }
  }

  private async upsertCm(
    hostRef: string,
    data: Record<string, string>,
    timestamp: string
  ): Promise<void> {
    const name = this.cmName(hostRef)
    const body: k8s.V1ConfigMap = {
      apiVersion: 'v1',
      kind: 'ConfigMap',
      metadata: {
        name,
        namespace: this.namespace,
        labels: this.commonLabels(hostRef),
        annotations: { 'clerum.io/last-updated': timestamp },
      },
      data,
    }
    try {
      await this.coreApi.createNamespacedConfigMap({ namespace: this.namespace, body })
      return
    } catch (err) {
      if (!isErrorCode(err, 409)) throw err
    }
    const existing = await this.coreApi.readNamespacedConfigMap({
      namespace: this.namespace,
      name,
    })
    body.metadata!.resourceVersion = existing.metadata?.resourceVersion
    await this.coreApi.replaceNamespacedConfigMap({ namespace: this.namespace, name, body })
  }

  private async upsertSecret(
    hostRef: string,
    decodedData: Record<string, string>,
    timestamp: string
  ): Promise<void> {
    const name = this.secretName(hostRef)
    const body: k8s.V1Secret = {
      apiVersion: 'v1',
      kind: 'Secret',
      metadata: {
        name,
        namespace: this.namespace,
        labels: this.commonLabels(hostRef),
        annotations: { 'clerum.io/last-updated': timestamp },
      },
      type: 'Opaque',
      stringData: decodedData,
    }
    try {
      await this.coreApi.createNamespacedSecret({ namespace: this.namespace, body })
      return
    } catch (err) {
      if (!isErrorCode(err, 409)) throw err
    }
    const existing = await this.coreApi.readNamespacedSecret({
      namespace: this.namespace,
      name,
    })
    body.metadata!.resourceVersion = existing.metadata?.resourceVersion
    await this.coreApi.replaceNamespacedSecret({ namespace: this.namespace, name, body })
  }
}