Skip to content

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

TypeScript
37.6 KB
Raw Blame
/**
 * Configuration settings loaded from environment variables.
 */
import { DEFAULT_ALLOWED_PLUGIN_IMAGE_PREFIXES } from '@clerum/image-policy'
import { parseK8sApiCidrs, parseNodeLocalDnsCidr } from './k8sApiCidrs'
import { ContextCRD, McpServerCRD } from './types'

export const DEFAULT_EGRESS_PROXY_IMAGE = 'clerum/nginx-egress-proxy:0.1.0'
export interface Config {
  // Dev mode - if true, reads servers from env var instead of K8s
  devMode: boolean

  // Server port
  port: number

  // Kubernetes namespace where MCP servers and Context CRDs live
  namespace: string

  // Kubernetes namespace where control-plane gateway services live
  controlPlaneNamespace: string

  // Kubernetes namespace where mcp-host pods run (used for NetworkPolicy generation)
  hostNamespace: string

  // Kubernetes namespace and service port where gfsc runs.
  gfsNamespace: string
  gfscPort: number

  // Kubernetes namespace where rpc-proxy runs (for L2 egress NetworkPolicy generation)
  rpcProxyNamespace: string

  // Kubernetes namespace where per-Host channel-reader Deployments live
  channelsNamespace: string

  // Kubernetes namespace where LlmHook image workloads (guardrail hook pods)
  // live and where the LlmHook CRDs are watched.
  llmHooksNamespace: string

  // Periodic LlmHook fullReconcile interval (seconds). Drives the reference-
  // counted orphan sweep (guardrails phase-4 §3) and readiness convergence when
  // a watch drops events. 0 disables.
  llmHookResyncIntervalSec: number

  // Container image used for per-Host channel-reader Deployments
  channelReaderImage: string

  // imagePullPolicy applied to per-Host channel-reader Deployments
  channelReaderImagePullPolicy: string

  // Internal handoff port exposed by per-Host channel-reader Services.
  channelReaderHandoffPort: number

  // Dev mode: MCP servers from CLERUM_MCP_SERVERS JSON
  devMcpServers: McpServerCRD[]

  // Dev mode: Contexts from CLERUM_CONTEXTS JSON
  devContexts: ContextCRD[]

  // Dev mode: Auth tokens from CLERUM_MCP_AUTH JSON (serverName -> token)
  devAuthTokens: Map<string, string>

  // Egress proxy image for remote MCP servers
  egressProxyImage: string

  // stdio-bridge sidecar image for managed stdio MCP servers
  stdioBridgeImage: string

  // Default resource limits for the stdio-bridge sidecar
  stdioBridgeResources: {
    requests: { memory: string; cpu: string }
    limits: { memory: string; cpu: string }
  }

  // Runtime namespaces where L0 deny-all + L1 infrastructure policies apply
  runtimeNamespaces: string[]

  // Subset of `runtimeNamespaces` that get only deny-all + DNS egress —
  // explicitly NOT allow-hcc-api or allow-k8s-api. Lets us opt out namespaces
  // whose pods aren't K8s clients and don't consume the HCC discovery API.
  minimalInfraNamespaces: string[]

  // K8s API server CIDRs for allow-k8s-api-egress-* policies. Empty = fall
  // back to KUBERNETES_SERVICE_HOST. Validated fail-closed at module load.
  k8sApiCidrs: string[]

  // DNS infrastructure CIDR for GKE NodeLocal DNSCache / kube-dns. When set,
  // allow-dns-egress-* policies append an ipBlock egress rule on port 53 so
  // pod DNS can reach the target cluster's kube-dns Service IP under Calico.
  // Empty (default) -> no extra rule, behavior unchanged.
  nodeLocalDnsCidr: string

  // Host runtime reconciliation defaults
  hostImage: string
  hostImagePullPolicy: 'Always' | 'IfNotPresent' | 'Never'
  // Pull policy override for STATELESS host pods (Stage 6, W5). Empty =
  // inherit hostImagePullPolicy. The configured policy is always applied.
  // IfNotPresent on a mutable image reference (no @sha256: digest, tag not
  // sha-<gitsha>) is only reported: a once-per-(host,image) warning and the
  // advisory StatelessPullPolicyRejected=True condition. Always is not
  // enforced — see resolveStatelessImagePullPolicy.
  statelessImagePullPolicy: '' | 'Always' | 'IfNotPresent' | 'Never'
  mcpServerImagePullPolicy: 'Always' | 'IfNotPresent' | 'Never'
  hostImagePullSecretName: string
  hostPort: number
  hostConfigMapName: string
  hostServiceAccountName: string
  hostWorkspaceStorageClassName: string
  hostWorkspaceStorageSize: string
  hostWorkspacePath: string
  hostResources: {
    requests: { memory: string; cpu: string }
    limits: { memory: string; cpu: string }
  }

  // Desktop image and resource defaults (used when Host CRD has spec.desktop)
  desktopImage: string
  desktopPort: number
  desktopResources: {
    requests: { memory: string; cpu: string }
    limits: { memory: string; cpu: string }
  }

  // Service token for desktop API endpoints (empty = skip auth, e.g. dev mode)
  desktopApiToken: string

  // workspace-files-controller (per-SharedFileSystem) reconciliation defaults
  wfcImage: string
  wfcImagePullPolicy: 'Always' | 'IfNotPresent' | 'Never'
  wfcImagePullSecretName: string
  wfcPort: number
  wfcInitImage: string
  wfcResources: {
    requests: { memory: string; cpu: string }
    limits: { memory: string; cpu: string }
  }
  /** ConfigMap that exposes the JWT public key the wfc uses to verify browsing JWTs. */
  wfcJwtPublicKeyConfigMapName: string
  wfcJwtPublicKeyConfigMapKey: string
  /** WSF_MAX_* limits forwarded to the wfc container as env. */
  wfcMaxUploadBytes: number
  wfcMaxListEntries: number
  wfcMaxPathDepth: number

  // Cluster-internal control-api base URL — HCC calls this directly (NOT via
  // the public workflow-approval-gateway) to issue mcpHost runtime tokens for the
  // mcp-host pods it provisions. Provisioner issuance is direct;
  // runtime traffic from mcp-host pods still flows through the gateway.
  controlApiBaseUrl: string
  governedTracingEnabled: boolean

  // HS256 secret used by HCC to sign per-request InternalControl JWTs
  // for control-api token issuance.
  internalControlJwtHccHmacSecret: string

  // Namespace HCC targets when asking control-api to issue the shared
  // 1st-party mcp-host credentials.
  hccTargetNamespace: string

  // Control API RS256 verifier contract for Host-scoped MCP API routes.
  mcpHostJwtPublicKey: string
  mcpHostJwtIssuer: string
  mcpHostJwtMaxTtlSeconds: number
  mcpHostApiRateLimitPerMinute: number

  // URL of the nginx gateway that mediates mcp-host → control-api traffic.
  // Injected into mcp-host pods as MCP_HOST_GATEWAY_URL. Per the architecture
  // diagram this is the "nginx (only /mcp-host)" allowlist-proxy.
  mcpHostGatewayUrl: string

  // Periodic Host fullReconcile interval (seconds). Guards against silent
  // event drops on long K8s watch disconnects. 0 disables.
  hostResyncIntervalSec: number

  // Periodic NetworkPolicy convergence interval (seconds). Re-enters the
  // coordinated single-flight pass (not a naked fullReconcile) so a dropped
  // watch cannot leave stale allows. Default 0 disables the interval; startup
  // still runs one convergence pass. Non-canonical values fail loud at load.
  // Set via CONTEXT_MAPPER_NETPOL_RESYNC_SEC.
  netPolResyncIntervalSec: number

  // Periodic L0/L1 defaults-only interval (seconds). Re-applies
  // ensureDefaultPolicies without entering a fleet fullReconcile. Default 0
  // disables the interval. Non-canonical values fail loud at load. Set via
  // CONTEXT_MAPPER_NETPOL_DEFAULTS_RESYNC_SEC.
  netPolDefaultsResyncIntervalSec: number

  // Absolute orphan-delete cap for a NetworkPolicy fullReconcile sweep.
  // Candidates strictly above this count refuse deletes and increment the
  // cap metric; the pass still certifies. 0 refuses every orphan delete.
  // Negative values fail loud at load. Set via
  // CONTEXT_MAPPER_NETPOL_ORPHAN_DELETE_CAP.
  netPolOrphanDeleteCap: number

  // Percent orphan-delete cap against the listed managed fleet. Candidates
  // strictly above this fraction are refused. Inert on a tiny inventory
  // where percent*fleet < 1. Values above 100 never fire. Set via
  // CONTEXT_MAPPER_NETPOL_ORPHAN_DELETE_CAP_PERCENT.
  netPolOrphanDeleteCapPercent: number

  // Per-request deadline for finite Kubernetes calls on the serialized Host
  // convergence path. Watches keep their independent long-lived lifecycle.
  hostK8sRequestTimeoutMs: number

  // Bounded cross-Host concurrency for a full/lifecycle Host fleet pass. Urgent
  // per-Host events (ADDED/MODIFIED/DELETED/wake) are admitted outside this
  // budget. Integer 1..8, default 2 (see parseHostFullReconcileConcurrency).
  hostFullReconcileConcurrency: number

  // Render the `workspace-layout-merge` init on every Host (see
  // parseWorkspaceLayoutMerge). Default true.
  workspaceLayoutMerge: boolean

  // Periodic SharedFileSystem fullReconcile interval (seconds). The SFS watch
  // fires only on SFS CRD changes, not on PVC binding / wfc pod readiness, so
  // this drives truthful-status auto-recovery (#592): a SharedFileSystem stuck
  // in Initializing/Degraded converges to Ready once the volume binds. 0 disables.
  sfsResyncIntervalSec: number

  // Periodic GlobalFileSystem fullReconcile interval (seconds). Same rationale as
  // SFS: the gfs watch fires only on the CRD changing, not on the gfsc writer
  // Deployment becoming Available — so a GlobalFileSystem reported Initializing
  // converges to Ready (and its root-directory seed runs) once the writer is up.
  // 0 disables.
  gfsResyncIntervalSec: number

  // How long before refresh expiry HCC should refresh the bootstrap
  // credential Secret for future pod starts. This does not by itself roll
  // healthy running pods.
  mcpHostBootstrapRefreshBeforeSec: number

  // Rotate the mcp-host bootstrap runtime-token Secret when the refresh
  // token's REAL expiry (the JWT `exp` claim, decoded without signature
  // verification) is closer than this many seconds. Set via
  // CONTEXT_MAPPER_RUNTIME_TOKEN_ROTATE_BEFORE_S; default 24h (86400).
  // Bounded at decision time to half the token's observed lifetime so
  // short-lived dev/test tokens cannot rotate on every reconcile.
  runtimeTokenRotateBeforeSec: number

  // Periodic external-egress DNS resync interval (seconds). Re-resolves
  // McpServer.spec.egressBindings so DNS changes and failures converge without
  // requiring a watch event. 0 disables. Must sit below externalEgressOverlapSec
  // so accumulated IPs never expire between refreshes (issue #299).
  externalEgressResyncIntervalSec: number

  // Deadline for one DNS resolution attempt. A silent resolver cannot block
  // safety convergence indefinitely.
  externalEgressDnsResolveTimeoutMs: number

  // Grace kept after a DNS TTL before an accumulated /32 may expire (seconds).
  // The sliding window that fixes #299: entries live for TTL + overlap, so a
  // provider that rotates a single A record still resolves through the union of
  // recently-live IPs. Set via HCC_EXTERNAL_EGRESS_OVERLAP_SEC.
  externalEgressOverlapSec: number

  // Minimum sane refresh interval (seconds); guards against a hot-loop resync.
  // Set via HCC_EXTERNAL_EGRESS_REFRESH_FLOOR_SEC.
  externalEgressRefreshFloorSec: number

  // Per-FQDN accumulated-entry cap. On overflow the core evicts the
  // least-recently-observed IP (never rejects the policy). Set via
  // HCC_EXTERNAL_EGRESS_MAX_ENTRIES.
  externalEgressMaxEntries: number

  // Plugin image-host allowlist (Phase 2.3). Trusted raw-image prefixes for
  // local-mode McpServer images. Audit mode (default) logs would-be denials
  // without blocking; enforce mode blocks the workload build.
  allowedPluginImagePrefixes: string[]
  enforcePluginImageAllowlist: boolean

  // ─── Stateless heartbeat + D8 idle gate (Stage 3) ─────────────────────
  // Idle window before a stateless Host is drain-eligible (minutes).
  statelessIdleMinutes: number
  // Platform floor for the idle window: effective T_idle = max(idle, floor).
  statelessIdleFloorMinutes: number
  // Grace after a drain:true verdict before suspending without a drained report.
  statelessDrainGraceMs: number
  // Max pod uptime ceiling — an older pod drains regardless of activity (hours).
  statelessMaxUptimeHours: number
  // Cadence of HCC's control-api heartbeat poll (ms). mcp-host heartbeats
  // are ingested by control-api's /mcp-host facade (Host JWT verified there);
  // HCC only CONSUMES them via the InternalControl feed
  // (GET /api/v1/auth/mcp-host/heartbeats) — it never verifies Host JWTs.
  heartbeatPollMs: number
}

function getEnv(key: string, defaultValue?: string): string | undefined {
  return process.env[key] ?? defaultValue
}

function getEnvInt(key: string, defaultValue: number): number {
  const value = process.env[key]
  if (!value) return defaultValue
  const parsed = parseInt(value, 10)
  return isNaN(parsed) ? defaultValue : parsed
}

/** Reject negative orphan-delete caps. 0 is a valid never-delete kill-switch. */
function requireNonNegativeEnvInt(key: string, value: number): number {
  if (!Number.isSafeInteger(value) || value < 0) {
    throw new Error(`${key} must be a non-negative integer, got '${process.env[key] ?? ''}'`)
  }
  return value
}

/**
 * Unsigned base-10 integer, including 0. Rejects the parseInt coercions
 * (`2e1`→2, `10.9`→10, `12abc`→12) that getEnvInt would swallow.
 */
function requireCanonicalNonNegativeEnvInt(key: string, defaultValue: number): number {
  const raw = process.env[key]
  if (raw === undefined || raw === '') return defaultValue
  if (!/^\d+$/.test(raw)) {
    throw new Error(`${key} must be an unsigned base-10 integer, got '${raw}'`)
  }
  const parsed = Number(raw)
  return requireNonNegativeEnvInt(key, parsed)
}

export function parseExternalEgressDnsTimeoutMs(raw: string | undefined): number {
  if (raw === undefined || raw.trim() === '') return 5_000
  const parsed = Number(raw)
  if (!Number.isSafeInteger(parsed) || parsed <= 0 || parsed > 2_147_483_647) {
    throw new Error(
      `HCC_EXTERNAL_EGRESS_DNS_TIMEOUT_MS must be a positive integer no greater than 2147483647, got '${raw}'`
    )
  }
  return parsed
}

/**
 * Loud integer env parser for the external-egress knobs (audit R1-L1). Unlike
 * getEnvInt (parseInt), this rejects non-canonical values instead of silently
 * coercing them: '60.5'->60 or '60abc'->60 would pass getEnvInt AND the
 * range invariant (which re-checks the already-truncated value), letting an
 * in-range typo through quietly. Canonical unsigned base-10 only; empty -> default.
 */
function getExternalEgressEnvInt(key: string, defaultValue: number): number {
  const raw = process.env[key]
  if (raw === undefined || raw === '') return defaultValue
  if (!/^\d+$/.test(raw)) {
    throw new Error(`${key} must be an unsigned base-10 integer (seconds), got '${raw}'`)
  }
  const parsed = Number(raw)
  if (!Number.isSafeInteger(parsed)) {
    throw new Error(`${key} is out of the safe integer range, got '${raw}'`)
  }
  return parsed
}

/**
 * CONTEXT_MAPPER_HEARTBEAT_POLL_MS — cadence of HCC's control-api heartbeat
 * poll. Fails config load loudly on a non-positive-integer value: a silent
 * default over garbage would hide a typo'd cadence in production.
 */
export function parseHeartbeatPollMs(raw: string | undefined): number {
  if (raw === undefined || raw.trim() === '') return 10_000
  const parsed = Number(raw)
  if (!Number.isInteger(parsed) || parsed <= 0) {
    throw new Error(
      `CONTEXT_MAPPER_HEARTBEAT_POLL_MS must be a positive integer (milliseconds), got '${raw}'`
    )
  }
  return parsed
}

export function parseHostK8sRequestTimeoutMs(raw: string | undefined): number {
  if (raw === undefined) return 30_000
  const parsed = Number(raw)
  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
    throw new Error(
      `HCC_HOST_K8S_REQUEST_TIMEOUT_MS must be a positive integer (milliseconds), got '${raw}'`
    )
  }
  return parsed
}

/**
 * HCC_HOST_FULL_RECONCILE_CONCURRENCY — bounded cross-Host concurrency for a
 * full/lifecycle Host fleet pass. Urgent per-Host events are admitted OUTSIDE
 * this budget, so a low default optimizes for Kubernetes API stability rather
 * than convergence speed. Integer 1..8 (1 = diagnostic serial mode), default 2.
 * Fails config load loudly on garbage: a silent default over a typo'd value
 * would mask an operator's intended concurrency in production.
 */
export function parseHostFullReconcileConcurrency(raw: string | undefined): number {
  if (raw === undefined || raw.trim() === '') return 2
  const parsed = Number(raw)
  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 8) {
    throw new Error(
      `HCC_HOST_FULL_RECONCILE_CONCURRENCY must be an integer from 1 through 8, got '${raw}'`
    )
  }
  return parsed
}

/**
 * CONTEXT_MAPPER_WORKSPACE_LAYOUT_MERGE — whether Host Deployments render the
 * `workspace-layout-merge` init that moves a PVC split by the earlier stateless
 * layout back to the root layout. The merge is needed once per Host; a cluster
 * turns it off once every Host has started with it. Unset or empty means true,
 * so a deploy that ships this HCC merges without an overlay change. Only the
 * exact strings 'true' and 'false' are accepted: a typo read as false would
 * start split Hosts on an empty database without any error.
 */
export function parseWorkspaceLayoutMerge(raw: string | undefined): boolean {
  if (raw === undefined || raw === '') return true
  if (raw === 'true') return true
  if (raw === 'false') return false
  throw new Error(`CONTEXT_MAPPER_WORKSPACE_LAYOUT_MERGE must be 'true' or 'false', got '${raw}'`)
}

export function validateRemovedStatelessCommunicationChannelPolicy(raw: string | undefined): void {
  if (raw === undefined || raw.trim() === '') return
  throw new Error(
    "CLERUM_STATELESS_COMMUNICATION_CHANNEL_POLICY is no longer supported; CommunicationChannel-connected Hosts are always kept active until channel wake/redrive is implemented (got '" +
      raw +
      "')"
  )
}

function getEnvBool(key: string, defaultValue: boolean): boolean {
  const value = process.env[key]
  if (!value) return defaultValue
  return value.toLowerCase() === 'true' || value === '1'
}

/**
 * Parse CLERUM_MCP_SERVERS JSON for dev mode.
 * Format: [{"name": "...", "spec": {"contextRef": "...", "transport": {...}}}]
 */
function parseDevMcpServers(): McpServerCRD[] {
  const serversJson = process.env.CLERUM_MCP_SERVERS
  if (!serversJson) {
    return []
  }

  try {
    const parsed = JSON.parse(serversJson) as McpServerCRD[]
    console.log(`[Config] Parsed ${parsed.length} dev MCP server(s) from CLERUM_MCP_SERVERS`)
    for (const server of parsed) {
      console.log(`[Config]   - ${server.name}: ${server.spec.transport?.url || 'no url'}`)
    }
    return parsed
  } catch (error) {
    console.error('[Config] Failed to parse CLERUM_MCP_SERVERS:', error)
    return []
  }
}

/**
 * Parse CLERUM_CONTEXTS JSON for dev mode.
 * Format: [{"name": "ctx1", "spec": {"contextId": "ctx1", "mcpServers": ["server-a"]}}]
 */
function parseDevContexts(): ContextCRD[] {
  const contextsJson = process.env.CLERUM_CONTEXTS
  if (!contextsJson) {
    return []
  }

  try {
    const parsed = JSON.parse(contextsJson) as ContextCRD[]
    console.log(`[Config] Parsed ${parsed.length} dev Context(s) from CLERUM_CONTEXTS`)
    for (const ctx of parsed) {
      console.log(`[Config]   - ${ctx.name}: mcpServers=[${ctx.spec.mcpServers.join(', ')}]`)
    }
    return parsed
  } catch (error) {
    console.error('[Config] Failed to parse CLERUM_CONTEXTS:', error)
    return []
  }
}

/**
 * Parse CLERUM_MCP_AUTH JSON for dev mode.
 * Format: {"serverName": "token", ...}
 */
function parseDevAuthTokens(): Map<string, string> {
  const authJson = process.env.CLERUM_MCP_AUTH
  if (!authJson) {
    return new Map()
  }

  try {
    const parsed = JSON.parse(authJson) as Record<string, string>
    const tokens = new Map<string, string>()
    for (const [name, token] of Object.entries(parsed)) {
      tokens.set(name, token)
      console.log(`[Config]   - Auth token configured for: ${name}`)
    }
    return tokens
  } catch (error) {
    console.error('[Config] Failed to parse CLERUM_MCP_AUTH:', error)
    return new Map()
  }
}

const devMode = getEnvBool('CLERUM_DEV_MODE', false)

validateRemovedStatelessCommunicationChannelPolicy(
  getEnv('CLERUM_STATELESS_COMMUNICATION_CHANNEL_POLICY')
)

/**
 * Enforce the external-egress sliding-window invariant (issue #299):
 *   refreshFloor >= 1, overlap > 0, maxEntries >= 1, and when the periodic
 *   resync is enabled (interval > 0): floor <= interval <= overlap/2.
 * The interval MUST stay at or below HALF the overlap so an accumulated /32 is
 * refreshed before it can expire (the renewal-write window is only overlap/2
 * wide); otherwise a gap reopens and the pod loses egress on the next rotation.
 * Fails loud at startup rather than degrading silently.
 */
// Upper bounds (audit M-C, port of commit 3f968956). The one-hour cadence
// ceiling keeps every timer far below Node's signed-32-bit setTimeout limit
// (2^31-1 ms ≈ 24.8 days) — an unbounded seconds value multiplied to ms would
// overflow and Node clamps it to 1ms, turning the self-rescheduling resync into
// a back-to-back DNS hot loop. The entry ceiling is a coarse COUNT alarm cap
// matching WRC (1300); the real bound on the annotation size is the core's
// byte-aware eviction (MAX_ANNOTATION_BYTES in network-policy-core), which trims
// long-FQDN sets well before this count is reached (R1-M5 — the previous 4096
// claim of "matches WRC" was false; WRC is 1300 and 4096 never bounds bytes).
const MAX_EXTERNAL_EGRESS_CADENCE_SEC = 60 * 60
const MAX_EXTERNAL_EGRESS_MAX_ENTRIES = 1300

export function validateExternalEgressResyncInvariant(cfg: {
  externalEgressResyncIntervalSec: number
  externalEgressOverlapSec: number
  externalEgressRefreshFloorSec: number
  externalEgressMaxEntries: number
}): void {
  const interval = cfg.externalEgressResyncIntervalSec
  const overlap = cfg.externalEgressOverlapSec
  const floor = cfg.externalEgressRefreshFloorSec
  const max = cfg.externalEgressMaxEntries

  if (!Number.isInteger(overlap) || overlap <= 0 || overlap > MAX_EXTERNAL_EGRESS_CADENCE_SEC) {
    throw new Error(
      `HCC_EXTERNAL_EGRESS_OVERLAP_SEC must be an integer between 1 and ` +
        `${MAX_EXTERNAL_EGRESS_CADENCE_SEC} (seconds), got '${overlap}'`
    )
  }
  if (!Number.isInteger(floor) || floor < 1 || floor > MAX_EXTERNAL_EGRESS_CADENCE_SEC) {
    throw new Error(
      `HCC_EXTERNAL_EGRESS_REFRESH_FLOOR_SEC must be an integer between 1 and ` +
        `${MAX_EXTERNAL_EGRESS_CADENCE_SEC} (seconds), got '${floor}'`
    )
  }
  if (!Number.isInteger(max) || max < 1 || max > MAX_EXTERNAL_EGRESS_MAX_ENTRIES) {
    throw new Error(
      `HCC_EXTERNAL_EGRESS_MAX_ENTRIES must be an integer between 1 and ` +
        `${MAX_EXTERNAL_EGRESS_MAX_ENTRIES}, got '${max}'`
    )
  }
  // A negative interval is a typo, not "disabled" — reject it loudly so it can't
  // silently reinstate the #299 drift bug (audit F4). 0 = explicitly disabled.
  // The upper cap (M-C) prevents a signed-32-bit setTimeout overflow.
  if (!Number.isInteger(interval) || interval < 0 || interval > MAX_EXTERNAL_EGRESS_CADENCE_SEC) {
    throw new Error(
      `HCC_EXTERNAL_EGRESS_RESYNC_SEC must be an integer between 0 and ` +
        `${MAX_EXTERNAL_EGRESS_CADENCE_SEC} (0 disables), got '${interval}'`
    )
  }
  // interval 0 disables periodic resync; only enforce ordering when enabled.
  if (interval > 0) {
    if (interval < floor) {
      throw new Error(
        `HCC_EXTERNAL_EGRESS_RESYNC_SEC (${interval}) must be >= the refresh floor (${floor})`
      )
    }
    // Audit L2: the renewal-write window is only overlap/2 wide, so the interval
    // must be <= overlap/2 (not just < overlap) — otherwise the persisted window
    // can lapse between refreshes and a rotated-away IP is pruned with grace ~=
    // interval instead of TTL+overlap.
    if (interval * 2 > overlap) {
      throw new Error(
        `HCC_EXTERNAL_EGRESS_RESYNC_SEC (${interval}) must be <= half the overlap window ` +
          `(${overlap}/2 = ${overlap / 2}) so the persisted window never lapses between refreshes (issue #299)`
      )
    }
  }
}

export const config: Config = {
  devMode,

  // Server port
  port: getEnvInt('CONTEXT_MAPPER_PORT', 8081),

  // Kubernetes namespace (where MCP servers run)
  namespace: getEnv('CONTEXT_MAPPER_NAMESPACE', 'mcp-server')!,

  // Kubernetes namespace where host-context-controller API gateway runs
  controlPlaneNamespace: getEnv('CONTEXT_MAPPER_CONTROL_PLANE_NAMESPACE', 'control-plane')!,

  // Host namespace (where mcp-host pods run — for NetworkPolicy generation)
  hostNamespace: getEnv('CONTEXT_MAPPER_HOST_NAMESPACE', 'mcp-host')!,

  // Global File System controller namespace and service port.
  gfsNamespace: getEnv('CONTEXT_MAPPER_GFS_NAMESPACE', 'gfs')!,
  gfscPort: getEnvInt('CONTEXT_MAPPER_GFSC_PORT', 8087),

  // rpc-proxy namespace
  rpcProxyNamespace: getEnv('CONTEXT_MAPPER_RPC_PROXY_NAMESPACE', 'rpc-proxy')!,

  // Per-Host channel-reader Deployments namespace
  channelsNamespace: getEnv('CONTEXT_MAPPER_CHANNELS_NAMESPACE', 'channels')!,

  // LlmHook image-workload / CRD-watch namespace (guardrails phase-4).
  llmHooksNamespace: getEnv('CONTEXT_MAPPER_LLM_HOOKS_NAMESPACE', 'llm-hooks')!,

  // Periodic LlmHook resync (default 5 min, matching hostResyncIntervalSec).
  llmHookResyncIntervalSec: getEnvInt('CONTEXT_MAPPER_LLM_HOOK_RESYNC_SEC', 300),

  // Per-Host channel-reader Deployment image (matches deploy/base/channels/channel-reader.yaml)
  channelReaderImage: getEnv('CONTEXT_MAPPER_CHANNEL_READER_IMAGE', 'clerum/channel-reader:0.9.5')!,

  // imagePullPolicy for per-Host channel-reader Deployments. Default 'Always'
  // matches production (pull from registry). Minikube overlay sets
  // 'IfNotPresent' to use locally-loaded images.
  channelReaderImagePullPolicy: getEnv(
    'CONTEXT_MAPPER_CHANNEL_READER_IMAGE_PULL_POLICY',
    'Always'
  )!,
  channelReaderHandoffPort: getEnvInt('CONTEXT_MAPPER_CHANNEL_READER_HANDOFF_PORT', 8099),

  // Egress proxy image for remote MCP servers (nginx-based, per-server proxy)
  egressProxyImage: getEnv('CONTEXT_MAPPER_EGRESS_PROXY_IMAGE', DEFAULT_EGRESS_PROXY_IMAGE)!,

  // stdio-bridge sidecar image
  stdioBridgeImage: getEnv(
    'CONTEXT_MAPPER_STDIO_BRIDGE_IMAGE',
    'us-central1-docker.pkg.dev/your-gcp-project/clerum/stdio-bridge:0.1.0'
  )!,

  // stdio-bridge sidecar resource defaults
  stdioBridgeResources: {
    requests: {
      memory: getEnv('CONTEXT_MAPPER_STDIO_BRIDGE_REQUEST_MEMORY', '32Mi')!,
      cpu: getEnv('CONTEXT_MAPPER_STDIO_BRIDGE_REQUEST_CPU', '50m')!,
    },
    limits: {
      memory: getEnv('CONTEXT_MAPPER_STDIO_BRIDGE_LIMIT_MEMORY', '128Mi')!,
      cpu: getEnv('CONTEXT_MAPPER_STDIO_BRIDGE_LIMIT_CPU', '200m')!,
    },
  },

  // Runtime namespaces where L0 deny-all + L1 infrastructure policies apply.
  //
  // llm-hooks is deliberately NOT listed: this list is a package deal, and its
  // L1 pass grants namespace-wide DNS (`ensureDnsEgress` uses podSelector: {})
  // plus HCC-gateway egress to every pod carrying clerum.io/managed-by — which
  // hook pod templates do. That would hand a pure `/v1` responder the implicit
  // DNS N5 forbids. The llm-hooks baseline is static instead
  // (deploy/base/llm-hooks/networkpolicies.yaml: deny-all ingress + egress),
  // with per-pod-key ingress and scoped CoreDNS emitted by LlmHookReconciler
  // only for hooks that declare egressBindings.
  runtimeNamespaces: getEnv(
    'CONTEXT_MAPPER_RUNTIME_NAMESPACES',
    'mcp-server,mcp-host,sandbox-recipes,rpc-proxy'
  )!.split(','),

  // DNS infrastructure CIDR for GKE NodeLocal DNSCache / kube-dns. Empty
  // (default) keeps only the kube-system selector. Validated fail-closed as a
  // single IPv4 /32 because GKE requires KUBE_DNS_SVC_CLUSTER_IP/32.
  nodeLocalDnsCidr: parseNodeLocalDnsCidr(getEnv('CONTEXT_MAPPER_NODELOCAL_DNS_CIDR')),

  // Subset of runtime namespaces that get only the minimal infrastructure
  // egress (deny-all + DNS) — and explicitly NOT allow-hcc-api or
  // allow-k8s-api. Use this for namespaces whose pods are not K8s clients
  // and don't consume the HCC discovery API (e.g. third-party UI workloads
  // that only need to serve HTTP back to a single ingress source).
  // Empty by default → all runtime namespaces get the full infra set.
  minimalInfraNamespaces: getEnv('CONTEXT_MAPPER_MINIMAL_INFRA_NAMESPACES', '')!
    .split(',')
    .map(s => s.trim())
    .filter(s => s.length > 0),

  // Validated at module load — a malformed/over-broad value crashes startup
  // rather than programming a permissive allow-k8s-api-egress NetworkPolicy.
  k8sApiCidrs: parseK8sApiCidrs(getEnv('CONTEXT_MAPPER_K8S_API_CIDRS')),

  // Dev mode MCP servers
  devMcpServers: devMode ? parseDevMcpServers() : [],

  // Dev mode contexts
  devContexts: devMode ? parseDevContexts() : [],

  // Dev mode auth tokens
  devAuthTokens: devMode ? parseDevAuthTokens() : new Map(),

  // Host runtime defaults
  hostImage: getEnv(
    'CONTEXT_MAPPER_HOST_IMAGE',
    'us-central1-docker.pkg.dev/your-gcp-project/clerum/mcp-host:0.6.0'
  )!,
  hostImagePullPolicy: getEnv('CONTEXT_MAPPER_HOST_IMAGE_PULL_POLICY', 'Always') as
    'Always' | 'IfNotPresent' | 'Never',
  statelessImagePullPolicy: getEnv('CONTEXT_MAPPER_STATELESS_IMAGE_PULL_POLICY', '') as
    '' | 'Always' | 'IfNotPresent' | 'Never',
  mcpServerImagePullPolicy: getEnv('CONTEXT_MAPPER_MCPSERVER_IMAGE_PULL_POLICY', 'IfNotPresent') as
    'Always' | 'IfNotPresent' | 'Never',
  hostImagePullSecretName: getEnv('CONTEXT_MAPPER_HOST_IMAGE_PULL_SECRET', 'clerum')!,
  hostPort: getEnvInt('CONTEXT_MAPPER_HOST_PORT', 8080),
  hostConfigMapName: getEnv('CONTEXT_MAPPER_HOST_CONFIGMAP_NAME', 'mcp-host-config')!,
  hostServiceAccountName: getEnv('CONTEXT_MAPPER_HOST_SERVICE_ACCOUNT', 'mcp-host')!,
  hostWorkspaceStorageClassName: getEnv(
    'CONTEXT_MAPPER_HOST_WORKSPACE_STORAGE_CLASS',
    'do-block-storage-retain'
  )!,
  hostWorkspaceStorageSize: getEnv('CONTEXT_MAPPER_HOST_WORKSPACE_SIZE', '10Gi')!,
  hostWorkspacePath: getEnv('CONTEXT_MAPPER_HOST_WORKSPACE_PATH', '/workspace')!,
  hostResources: {
    requests: {
      memory: getEnv('CONTEXT_MAPPER_HOST_RESOURCES_REQUEST_MEMORY', '128Mi')!,
      cpu: getEnv('CONTEXT_MAPPER_HOST_RESOURCES_REQUEST_CPU', '100m')!,
    },
    limits: {
      memory: getEnv('CONTEXT_MAPPER_HOST_RESOURCES_LIMIT_MEMORY', '512Mi')!,
      cpu: getEnv('CONTEXT_MAPPER_HOST_RESOURCES_LIMIT_CPU', '500m')!,
    },
  },

  // Desktop image and resource defaults
  desktopImage: getEnv('CONTEXT_MAPPER_DESKTOP_IMAGE', 'clerum/mcp-host-desktop:latest')!,
  desktopPort: getEnvInt('CONTEXT_MAPPER_DESKTOP_PORT', 3000),
  desktopResources: {
    requests: {
      memory: getEnv('CONTEXT_MAPPER_DESKTOP_RESOURCES_REQUEST_MEMORY', '256Mi')!,
      cpu: getEnv('CONTEXT_MAPPER_DESKTOP_RESOURCES_REQUEST_CPU', '250m')!,
    },
    limits: {
      memory: getEnv('CONTEXT_MAPPER_DESKTOP_RESOURCES_LIMIT_MEMORY', '4Gi')!,
      cpu: getEnv('CONTEXT_MAPPER_DESKTOP_RESOURCES_LIMIT_CPU', '1')!,
    },
  },

  // Service token for desktop API endpoints (empty = skip auth for dev mode)
  desktopApiToken: getEnv('CONTEXT_MAPPER_DESKTOP_API_TOKEN', '')!,

  // workspace-files-controller (per-SharedFileSystem) reconciliation defaults
  wfcImage: getEnv(
    'CONTEXT_MAPPER_WFC_IMAGE',
    'us-central1-docker.pkg.dev/your-gcp-project/clerum/workspace-files-controller:0.1.0'
  )!,
  wfcImagePullPolicy: getEnv('CONTEXT_MAPPER_WFC_IMAGE_PULL_POLICY', 'IfNotPresent') as
    'Always' | 'IfNotPresent' | 'Never',
  wfcImagePullSecretName: getEnv('CONTEXT_MAPPER_WFC_IMAGE_PULL_SECRET', 'clerum')!,
  wfcPort: getEnvInt('CONTEXT_MAPPER_WFC_PORT', 8086),
  wfcInitImage: getEnv('CONTEXT_MAPPER_WFC_INIT_IMAGE', 'busybox:1.36')!,
  wfcResources: {
    requests: {
      memory: getEnv('CONTEXT_MAPPER_WFC_RESOURCES_REQUEST_MEMORY', '64Mi')!,
      cpu: getEnv('CONTEXT_MAPPER_WFC_RESOURCES_REQUEST_CPU', '50m')!,
    },
    limits: {
      memory: getEnv('CONTEXT_MAPPER_WFC_RESOURCES_LIMIT_MEMORY', '128Mi')!,
      cpu: getEnv('CONTEXT_MAPPER_WFC_RESOURCES_LIMIT_CPU', '200m')!,
    },
  },
  wfcJwtPublicKeyConfigMapName: getEnv('CONTEXT_MAPPER_WFC_JWT_PUBLIC_KEY_CM', 'mcp-host-config')!,
  wfcJwtPublicKeyConfigMapKey: getEnv(
    'CONTEXT_MAPPER_WFC_JWT_PUBLIC_KEY_CM_KEY',
    'CLERUM_AUTH_JWT_PUBLIC_KEY'
  )!,
  wfcMaxUploadBytes: getEnvInt('CONTEXT_MAPPER_WFC_MAX_UPLOAD_BYTES', 100 * 1024 * 1024),
  wfcMaxListEntries: getEnvInt('CONTEXT_MAPPER_WFC_MAX_LIST_ENTRIES', 5000),
  wfcMaxPathDepth: getEnvInt('CONTEXT_MAPPER_WFC_MAX_PATH_DEPTH', 32),

  // Cluster-internal control-api endpoint (issuance is direct, NOT via gateway)
  controlApiBaseUrl: getEnv(
    'CONTROL_API_BASE_URL',
    'http://control-api.control-plane.svc.cluster.local:8090'
  )!,
  governedTracingEnabled: getEnvBool('GOVERNED_TRACING_ENABLED', true),

  // HCC signs InternalControl JWTs for direct control-api issuance calls.
  internalControlJwtHccHmacSecret: getEnv('INTERNAL_CONTROL_JWT_HCC_HMAC_SECRET', '')!,

  // HCC provisions the shared 1st-party mcp-host credentials by default.
  hccTargetNamespace: getEnv('HCC_TARGET_NAMESPACE')?.trim() || 'mcp-host',

  mcpHostJwtPublicKey: getEnv('HCC_MCP_HOST_JWT_PUBLIC_KEY', '')!,
  mcpHostJwtIssuer: getEnv('HCC_MCP_HOST_JWT_ISSUER', 'control-api')!,
  mcpHostJwtMaxTtlSeconds: Math.max(1, getEnvInt('HCC_MCP_HOST_JWT_MAX_TTL_SECONDS', 600)),
  mcpHostApiRateLimitPerMinute: Math.max(
    1,
    getEnvInt('HCC_MCP_HOST_API_RATE_LIMIT_PER_MINUTE', 120)
  ),

  // URL of the nginx gateway that mediates mcp-host → control-api traffic.
  // Injected into mcp-host pods as MCP_HOST_GATEWAY_URL. Per the architecture
  // diagram this is the "nginx (only /mcp-host)" allowlist-proxy.
  mcpHostGatewayUrl: getEnv(
    'MCP_HOST_GATEWAY_URL',
    'http://nginx-workflow-approval-gateway.control-plane.svc.cluster.local:8092'
  )!,

  // Periodic Host resync (default 5 min). 0 disables watches-only self-heal
  // for runtime-auth degraded mcp-host pods; use only for diagnostic runs.
  hostResyncIntervalSec: getEnvInt('CONTEXT_MAPPER_HOST_RESYNC_SEC', 300),

  // Periodic NetworkPolicy resync. Default 0 (disabled): startup still
  // converges once; the interval is opt-in so a bad cache cannot periodically
  // sweep. Unset or 0 → no interval.
  netPolResyncIntervalSec: requireCanonicalNonNegativeEnvInt('CONTEXT_MAPPER_NETPOL_RESYNC_SEC', 0),
  // Periodic L0/L1 defaults-only tick (#488). Default 0 (disabled): start()
  // still applies defaults once as a bootstrap barrier. The interval is
  // opt-in and is not shipped in deploy/base. Unset or 0 → no interval.
  netPolDefaultsResyncIntervalSec: requireCanonicalNonNegativeEnvInt(
    'CONTEXT_MAPPER_NETPOL_DEFAULTS_RESYNC_SEC',
    0
  ),
  // Mass-delete guard for the namespace-wide orphan sweep. Thresholds are
  // strict `>`: exactly N candidates still delete; N+1 refuses deletes and
  // still certifies.
  netPolOrphanDeleteCap: requireCanonicalNonNegativeEnvInt(
    'CONTEXT_MAPPER_NETPOL_ORPHAN_DELETE_CAP',
    10
  ),
  netPolOrphanDeleteCapPercent: requireCanonicalNonNegativeEnvInt(
    'CONTEXT_MAPPER_NETPOL_ORPHAN_DELETE_CAP_PERCENT',
    20
  ),

  // Every finite Kubernetes request that can hold Host convergence gets its
  // own deadline. Watch streams are intentionally excluded.
  hostK8sRequestTimeoutMs: parseHostK8sRequestTimeoutMs(getEnv('HCC_HOST_K8S_REQUEST_TIMEOUT_MS')),
  hostFullReconcileConcurrency: parseHostFullReconcileConcurrency(
    getEnv('HCC_HOST_FULL_RECONCILE_CONCURRENCY')
  ),
  workspaceLayoutMerge: parseWorkspaceLayoutMerge(
    process.env.CONTEXT_MAPPER_WORKSPACE_LAYOUT_MERGE
  ),

  // Periodic SharedFileSystem resync (default 60s). Re-evaluates PVC bind + wfc
  // readiness so a transient Initializing/Degraded converges to Ready (#592).
  sfsResyncIntervalSec: getEnvInt('CONTEXT_MAPPER_SFS_RESYNC_SEC', 60),
  gfsResyncIntervalSec: getEnvInt('CONTEXT_MAPPER_GFS_RESYNC_SEC', 60),

  // Bootstrap runtime credential refresh margin. The reconciler bounds this
  // against hostResyncIntervalSec and the issuer-provided refresh TTL.
  mcpHostBootstrapRefreshBeforeSec: getEnvInt(
    'HCC_MCP_HOST_RUNTIME_BOOTSTRAP_REFRESH_BEFORE_SEC',
    900
  ),

  // Refresh-token near-expiry rotation window (default 24h). Documented in
  // the ClerumConfig interface above.
  runtimeTokenRotateBeforeSec: getEnvInt('CONTEXT_MAPPER_RUNTIME_TOKEN_ROTATE_BEFORE_S', 86_400),

  // Periodic external-egress DNS resync. Lowered from the legacy 5 min to 60s so
  // it sits below the 300s overlap window: accumulated IPs are refreshed before
  // they expire, closing the #299 rotation gap. 0 disables (reintroduces the
  // stale-snapshot risk; only for operators who explicitly opt out).
  externalEgressResyncIntervalSec: getExternalEgressEnvInt('HCC_EXTERNAL_EGRESS_RESYNC_SEC', 60),
  externalEgressDnsResolveTimeoutMs: parseExternalEgressDnsTimeoutMs(
    getEnv('HCC_EXTERNAL_EGRESS_DNS_TIMEOUT_MS')
  ),
  externalEgressOverlapSec: getExternalEgressEnvInt('HCC_EXTERNAL_EGRESS_OVERLAP_SEC', 300),
  externalEgressRefreshFloorSec: getExternalEgressEnvInt(
    'HCC_EXTERNAL_EGRESS_REFRESH_FLOOR_SEC',
    5
  ),
  externalEgressMaxEntries: getExternalEgressEnvInt('HCC_EXTERNAL_EGRESS_MAX_ENTRIES', 128),

  // Plugin image-host allowlist (Phase 2.3). Permissive default = current
  // fleet hosts + registry.evenfire.ai; enforce defaults to false (audit mode).
  allowedPluginImagePrefixes: getEnv(
    'CONTEXT_MAPPER_ALLOWED_IMAGE_PREFIXES',
    [...DEFAULT_ALLOWED_PLUGIN_IMAGE_PREFIXES].join(',')
  )!
    .split(',')
    .map(s => s.trim())
    .filter(s => s.length > 0),
  enforcePluginImageAllowlist: getEnvBool('CONTEXT_MAPPER_ENFORCE_IMAGE_ALLOWLIST', false),

  // Stateless heartbeat + D8 idle gate (Stage 3).
  statelessIdleMinutes: getEnvInt('CONTEXT_MAPPER_STATELESS_IDLE_MINUTES', 30),
  statelessIdleFloorMinutes: getEnvInt('CONTEXT_MAPPER_STATELESS_IDLE_FLOOR_MINUTES', 15),
  statelessDrainGraceMs: getEnvInt('CONTEXT_MAPPER_STATELESS_DRAIN_GRACE_MS', 60000),
  statelessMaxUptimeHours: getEnvInt('CONTEXT_MAPPER_STATELESS_MAX_UPTIME_HOURS', 72),
  heartbeatPollMs: parseHeartbeatPollMs(getEnv('CONTEXT_MAPPER_HEARTBEAT_POLL_MS')),
}

// Fail loud at import time if the external-egress sliding-window knobs are
// inconsistent (issue #299) — a silent misconfig would reopen the rotation gap.
validateExternalEgressResyncInvariant(config)