Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* McpServer CRD Spec Validation — API-layer early feedback.
*
* Purpose: UX safety net + defense-in-depth. The HCC reconciler applies
* sanitizeCrdSpec() as a silent backstop; this module gives the operator
* immediate 422 feedback before the CRD reaches K8s.
*
* This is NOT a security boundary — the admin already has full cluster access.
* It prevents accidental misconfiguration (copy-paste errors, typos) and
* provides consistent "platform decides deployment" semantics at the earliest
* possible layer.
*/
import { lookup } from 'node:dns/promises'
import { classifyPluginImage } from '@clerum/image-policy'
import {
WORKFLOW_RECIPE_DEFAULT_ALLOWED_CAPABILITIES,
isWorkflowRecipeDefaultAllowedCapability,
} from '@clerum/workflow-recipe-capability-policy'
export interface ValidationError {
field: string
message: string
}
interface McpServerSpec {
imagePullPolicy?: string
security?: {
runAsUser?: number
addCapabilities?: string[]
}
env?: Array<{ name: string; value?: string; valueFrom?: unknown }>
resources?: {
limits?: { cpu?: string; memory?: string }
requests?: { cpu?: string; memory?: string }
}
image?: unknown
transport?: unknown
remote?: unknown
egressBindings?: unknown
}
interface EgressBinding {
egressClass?: unknown
dns?: unknown
cidr?: unknown
port?: unknown
protocol?: unknown
}
export type DnsResolver = (hostname: string) => Promise<string[]>
const FORBIDDEN_ENV = new Set([
'LD_PRELOAD',
'LD_LIBRARY_PATH',
'PATH',
'NODE_OPTIONS',
'PYTHONPATH',
'JAVA_TOOL_OPTIONS',
'KUBECONFIG',
'KUBERNETES_SERVICE_HOST',
'KUBERNETES_SERVICE_PORT',
])
const MAX_CPU_MILLICORES = 4000
const MAX_MEM_MIB = 8192
const MAX_EGRESS_BINDINGS = 20
const BLOCKED_EGRESS_CIDRS = [
'0.0.0.0/8',
'10.0.0.0/8',
'100.64.0.0/10',
'127.0.0.0/8',
'169.254.0.0/16',
'172.16.0.0/12',
'192.0.0.0/24',
'192.0.2.0/24',
'192.31.196.0/24',
'192.52.193.0/24',
'192.88.99.0/24',
'192.168.0.0/16',
'192.175.48.0/24',
'198.18.0.0/15',
'198.51.100.0/24',
'203.0.113.0/24',
'224.0.0.0/4',
'240.0.0.0/4',
]
function isPlainObject(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
function ipv4ToInt(ip: string): number | null {
const parts = ip.split('.')
if (
parts.length !== 4 ||
parts.some(part => {
if (!/^\d+$/.test(part)) return true
const parsed = Number(part)
return !Number.isInteger(parsed) || parsed < 0 || parsed > 255
})
) {
return null
}
return parts.reduce((acc, part) => ((acc << 8) + Number(part)) >>> 0, 0)
}
function cidrRange(cidr: string): { start: number; end: number; canonical: boolean } | null {
const match = cidr.match(/^(\d+(?:\.\d+){3})\/(\d{1,2})$/)
if (!match) return null
const base = ipv4ToInt(match[1])
const prefix = Number(match[2])
if (base === null || !Number.isInteger(prefix) || prefix < 0 || prefix > 32) return null
const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0
const start = (base & mask) >>> 0
const size = 2 ** (32 - prefix)
return { start, end: (start + size - 1) >>> 0, canonical: base === start }
}
function cidrOverlaps(left: string, right: string): boolean {
const a = cidrRange(left)
const b = cidrRange(right)
if (!a || !b) return false
return a.start <= b.end && b.start <= a.end
}
function isPublicDnsHostname(hostname: string): boolean {
if (hostname !== hostname.trim()) return false
if (hostname !== hostname.toLowerCase()) return false
if (hostname.includes('*') || hostname.includes('/') || hostname.includes(':')) return false
if (ipv4ToInt(hostname) !== null) return false
if (!hostname.includes('.')) return false
if (
hostname === 'localhost' ||
hostname === 'metadata.goog' ||
hostname === 'kubernetes.default' ||
hostname.endsWith('.localhost') ||
hostname.endsWith('.local') ||
hostname.endsWith('.internal') ||
hostname.endsWith('.svc') ||
hostname.endsWith('.svc.cluster.local') ||
hostname.endsWith('.cluster.local')
) {
return false
}
return hostname.split('.').every(label => /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/.test(label))
}
function validatePublicCidr(cidr: string): string | null {
const range = cidrRange(cidr)
if (!range) return 'cidr must be valid IPv4 CIDR notation'
if (!range.canonical) return 'cidr must use canonical network CIDR notation'
if (BLOCKED_EGRESS_CIDRS.some(blocked => cidrOverlaps(cidr, blocked))) {
return 'cidr must not overlap private, metadata, link-local, documentation, multicast, or reserved IPv4 ranges'
}
return null
}
async function defaultDnsResolver(hostname: string): Promise<string[]> {
const answers = await lookup(hostname, { family: 4, all: true, verbatim: true })
return answers.map(answer => answer.address)
}
/**
* From a set of resolved addresses, return the ones that must be treated as
* BLOCKED: a non-IPv4 answer (cannot be range-checked, so fail closed) or an
* IPv4 that overlaps a private/metadata/link-local/multicast/reserved/internal
* range. Shared (D4) by the egress preflight and {@link validateOAuthEndpointUrl}
* so both classify resolved IPs by the exact same rule.
*/
function filterBlockedIpv4(addresses: string[]): string[] {
return addresses.filter(address => {
if (ipv4ToInt(address) === null) return true
return validatePublicCidr(`${address}/32`) !== null
})
}
/** Parse a Kubernetes resource quantity like "4000m" or "8Gi" into a number. */
function parseCpuMillicores(val: string): number | null {
if (val.endsWith('m')) return parseInt(val, 10)
const asNum = parseFloat(val)
if (isNaN(asNum)) return null
return Math.round(asNum * 1000)
}
function parseMemoryMiB(val: string): number | null {
if (val.endsWith('Gi')) return parseInt(val, 10) * 1024
if (val.endsWith('Mi')) return parseInt(val, 10)
if (val.endsWith('Ki')) return Math.round(parseInt(val, 10) / 1024)
const asNum = parseFloat(val)
if (isNaN(asNum)) return null
return Math.round(asNum / (1024 * 1024))
}
export interface ImageAllowlistOptions {
allowedImagePrefixes?: string[]
enforceImageAllowlist?: boolean
}
/**
* Validate an McpServer CRD spec at the API layer.
* Returns an array of validation errors (empty = valid).
*/
export function validateMcpServerSpec(
spec: Record<string, unknown>,
options: ImageAllowlistOptions = {}
): ValidationError[] {
const errors: ValidationError[] = []
const s = spec as McpServerSpec
// ── imagePullPolicy: platform decides, not the CRD author ──
if (s.imagePullPolicy !== undefined) {
errors.push({
field: 'spec.imagePullPolicy',
message:
'imagePullPolicy is platform-controlled and cannot be set via the API. The HCC reconciler assigns it automatically.',
})
}
// ── Security: root UID prevention ──
if (s.security?.runAsUser !== undefined) {
if (s.security.runAsUser < 1) {
errors.push({
field: 'spec.security.runAsUser',
message: `runAsUser must be >= 1 (got ${s.security.runAsUser}). Root (UID 0) is not allowed.`,
})
}
}
// ── Security: Linux capabilities ──
if (s.security?.addCapabilities) {
const rejected = s.security.addCapabilities.filter(
cap => !isWorkflowRecipeDefaultAllowedCapability(cap)
)
if (rejected.length > 0) {
errors.push({
field: 'spec.security.addCapabilities',
message: `Capabilities not in the default-allowed set: ${rejected.join(', ')}. Allowed: ${WORKFLOW_RECIPE_DEFAULT_ALLOWED_CAPABILITIES.join(', ')}.`,
})
}
}
// ── Env vars: block dangerous names ──
if (s.env && Array.isArray(s.env)) {
const blocked = s.env
.filter(e => FORBIDDEN_ENV.has((e.name ?? '').toUpperCase()))
.map(e => e.name)
if (blocked.length > 0) {
errors.push({
field: 'spec.env',
message: `Dangerous env vars not allowed: ${blocked.join(', ')}. These can compromise the container runtime.`,
})
}
}
// ── Resources: clamp to platform limits ──
if (s.resources?.limits) {
if (s.resources.limits.cpu) {
const cpu = parseCpuMillicores(s.resources.limits.cpu)
if (cpu !== null && cpu > MAX_CPU_MILLICORES) {
errors.push({
field: 'spec.resources.limits.cpu',
message: `CPU limit exceeds platform maximum (${s.resources.limits.cpu} > ${MAX_CPU_MILLICORES}m).`,
})
}
}
if (s.resources.limits.memory) {
const mem = parseMemoryMiB(s.resources.limits.memory)
if (mem !== null && mem > MAX_MEM_MIB) {
errors.push({
field: 'spec.resources.limits.memory',
message: `Memory limit exceeds platform maximum (${s.resources.limits.memory} > 8Gi).`,
})
}
}
}
// ── External egress: mirror CRD shape for early operator feedback ──
if (s.egressBindings !== undefined) {
if (!Array.isArray(s.egressBindings)) {
errors.push({
field: 'spec.egressBindings',
message: 'egressBindings must be an array',
})
} else {
if (s.egressBindings.length > MAX_EGRESS_BINDINGS) {
errors.push({
field: 'spec.egressBindings',
message: `egressBindings must contain at most ${MAX_EGRESS_BINDINGS} items`,
})
}
s.egressBindings.forEach((rawBinding, index) => {
const field = `spec.egressBindings[${index}]`
if (!isPlainObject(rawBinding)) {
errors.push({ field, message: 'egress binding must be an object' })
return
}
const binding = rawBinding as EgressBinding
const egressClass = binding.egressClass ?? 'exact-host'
if (egressClass !== 'exact-host' && egressClass !== 'public-web') {
errors.push({
field: `${field}.egressClass`,
message: 'egressClass must be exact-host or public-web',
})
return
}
if (egressClass === 'public-web') {
if (
binding.dns !== undefined ||
binding.cidr !== undefined ||
binding.port !== undefined ||
binding.protocol !== undefined
) {
errors.push({
field,
message: 'public-web egressBindings must not declare dns, cidr, port, or protocol',
})
}
return
}
const hasDns = typeof binding.dns === 'string' && binding.dns.trim().length > 0
const hasCidr = typeof binding.cidr === 'string' && binding.cidr.trim().length > 0
if (hasDns === hasCidr) {
errors.push({
field,
message: 'exact-host egressBindings must declare exactly one of dns or cidr',
})
}
if (hasDns) {
const dns = (binding.dns as string).trim()
if (!isPublicDnsHostname(dns)) {
errors.push({
field: `${field}.dns`,
message: 'dns must be a public DNS hostname',
})
}
}
if (hasCidr) {
const cidr = (binding.cidr as string).trim()
const cidrError = validatePublicCidr(cidr)
if (cidrError) {
errors.push({
field: `${field}.cidr`,
message: cidrError,
})
}
}
if (
typeof binding.port !== 'number' ||
!Number.isInteger(binding.port) ||
binding.port < 1 ||
binding.port > 65535
) {
errors.push({
field: `${field}.port`,
message: 'port must be an integer between 1 and 65535',
})
}
if (
binding.protocol !== undefined &&
binding.protocol !== 'TCP' &&
binding.protocol !== 'UDP'
) {
errors.push({ field: `${field}.protocol`, message: 'protocol must be TCP or UDP' })
}
})
}
}
if (
s.remote !== undefined &&
(!Array.isArray(s.egressBindings) || s.egressBindings.length === 0)
) {
errors.push({
field: 'spec.egressBindings',
message: 'remote MCP servers must declare at least one egressBinding',
})
}
// ── Plugin image-host allowlist (2.3) — local-mode only, enforce → 422 ──
if (
options.enforceImageAllowlist === true &&
s.remote === undefined &&
typeof s.image === 'string' &&
s.image.trim().length > 0
) {
const decision = classifyPluginImage(s.image, {
allowedPrefixes: options.allowedImagePrefixes ?? [],
rejectLatest: false,
})
if (!decision.ok) {
errors.push({
field: 'spec.image',
message: `Image "${s.image}" is not permitted by the plugin image allowlist (${decision.reason}).`,
})
}
}
return errors
}
export async function validateMcpServerSpecPreflight(
spec: Record<string, unknown>,
options: { resolveDns?: DnsResolver } & ImageAllowlistOptions = {}
): Promise<ValidationError[]> {
const errors = validateMcpServerSpec(spec, {
allowedImagePrefixes: options.allowedImagePrefixes,
enforceImageAllowlist: options.enforceImageAllowlist,
})
const s = spec as McpServerSpec
if (!Array.isArray(s.egressBindings)) return errors
const resolveDns = options.resolveDns ?? defaultDnsResolver
const hostFields = new Map<string, string[]>()
s.egressBindings.forEach((rawBinding, index) => {
if (!isPlainObject(rawBinding)) return
const binding = rawBinding as EgressBinding
const egressClass = binding.egressClass ?? 'exact-host'
if (egressClass !== 'exact-host' || typeof binding.dns !== 'string') return
const dns = binding.dns.trim()
if (!isPublicDnsHostname(dns)) return
const fields = hostFields.get(dns) ?? []
fields.push(`spec.egressBindings[${index}].dns`)
hostFields.set(dns, fields)
})
await Promise.all(
[...hostFields.entries()].map(async ([dns, fields]) => {
try {
const addresses = Array.from(new Set(await resolveDns(dns)))
if (addresses.length === 0) {
fields.forEach(field =>
errors.push({ field, message: `dns "${dns}" did not resolve to an IPv4 A record` })
)
return
}
const blocked = filterBlockedIpv4(addresses)
if (blocked.length > 0) {
fields.forEach(field =>
errors.push({
field,
message:
`dns "${dns}" resolved to blocked IPv4 address(es): ${blocked.join(', ')}. ` +
'Exact-host egress must not resolve to private, metadata, link-local, multicast, reserved, or internal ranges.',
})
)
}
} catch (error) {
fields.forEach(field =>
errors.push({
field,
message: `dns "${dns}" could not be resolved: ${
error instanceof Error ? error.message : String(error)
}`,
})
)
}
})
)
return errors
}
/**
* Kernel core: validate an OAuth endpoint URL (spec 19 §4) AND return the resolved
* IPv4 addresses. scheme https + public host + resolve→non-blocked IPs, reusing
* isPublicDnsHostname/filterBlockedIpv4. `resolveDns` is injectable ⇒ testable in
* Vitest without a cluster.
*
* This is the single source of truth for the rule: both {@link validateOAuthEndpointUrl}
* (thin wrapper discarding the addresses) and {@link resolveValidatedOAuthEndpoint}
* (the pin, which CONSUMES the addresses so the socket connects to the exact IPs the
* validator resolved — closing the TOCTOU/DNS-rebinding window, H2) call it. The two
* MUST never drift, so the resolve+filter logic lives here once.
*
* `addresses` is the deduplicated set of resolved IPv4 addresses. When `errors` is
* empty it is guaranteed non-empty and all non-blocked (public) — the pin candidates.
*/
async function validateAndResolveOAuthEndpoint(
rawUrl: string,
field: string,
options: { resolveDns?: DnsResolver } = {}
): Promise<{ errors: ValidationError[]; addresses: string[] }> {
let url: URL
try {
url = new URL(rawUrl)
} catch {
return { errors: [{ field, message: 'must be a valid absolute URL' }], addresses: [] }
}
const errors: ValidationError[] = []
if (url.protocol !== 'https:') {
errors.push({ field, message: 'must use https' })
}
const host = url.hostname
if (!isPublicDnsHostname(host)) {
// Same rule as the egress preflight: only syntactically-public hosts are
// resolved. An internal/literal/malformed host is rejected without a DNS
// lookup (never resolve to probe internal names).
errors.push({ field, message: 'host must be a public DNS hostname' })
return { errors, addresses: [] }
}
const resolveDns = options.resolveDns ?? defaultDnsResolver
let addresses: string[] = []
try {
addresses = Array.from(new Set(await resolveDns(host)))
if (addresses.length === 0) {
errors.push({ field, message: `host "${host}" did not resolve to an IPv4 A record` })
} else {
const blocked = filterBlockedIpv4(addresses)
if (blocked.length > 0) {
errors.push({
field,
message:
`host "${host}" resolved to blocked IPv4 address(es): ${blocked.join(', ')}. ` +
'OAuth endpoints must not resolve to private, metadata, link-local, multicast, reserved, or internal ranges.',
})
}
}
} catch (error) {
errors.push({
field,
message: `host "${host}" could not be resolved: ${
error instanceof Error ? error.message : String(error)
}`,
})
}
return { errors, addresses }
}
/**
* Kernel de política sobre una URL de endpoint OAuth (spec 19 §4): scheme https +
* host público + resolve→IP no bloqueada. `resolveDns` inyectable ⇒ testeable en
* Vitest sin cluster. Devuelve [] si válida. Seam compartido para el carril
* self-hosted 'generic' (S3-B2) y el remoto (spec 02).
*/
export async function validateOAuthEndpointUrl(
rawUrl: string,
field: string,
options: { resolveDns?: DnsResolver } = {}
): Promise<ValidationError[]> {
const { errors } = await validateAndResolveOAuthEndpoint(rawUrl, field, options)
return errors
}
/**
* Same rule as {@link validateOAuthEndpointUrl}, but on success RETURNS the resolved
* IPv4 addresses so a caller can PIN the socket to those exact IPs (spec 02 §4,
* H2 DNS-rebinding/TOCTOU). The addresses are the deduplicated, all-public set the
* validator resolved; a pinned fetch feeds them to its `lookup` so the connection
* cannot re-resolve to a private/metadata host between validation and connect.
*
* Fail-closed: any validation error (bad scheme, non-public host, blocked/empty
* resolution) yields `{ ok: false, errors }` and no addresses.
*/
export async function resolveValidatedOAuthEndpoint(
rawUrl: string,
field: string,
options: { resolveDns?: DnsResolver } = {}
): Promise<{ ok: true; addresses: string[] } | { ok: false; errors: ValidationError[] }> {
const { errors, addresses } = await validateAndResolveOAuthEndpoint(rawUrl, field, options)
if (errors.length > 0) return { ok: false, errors }
return { ok: true, addresses }
}
export async function validateEgressBindingsPreflight(
egressBindings: unknown,
fieldPrefix = 'spec.egressBindings',
options: { resolveDns?: DnsResolver; allowCidr?: boolean } = {}
): Promise<ValidationError[]> {
const errors = await validateMcpServerSpecPreflight({ egressBindings }, options)
if (options.allowCidr === false && Array.isArray(egressBindings)) {
egressBindings.forEach((rawBinding, index) => {
if (!isPlainObject(rawBinding)) return
const binding = rawBinding as EgressBinding
if (binding.cidr !== undefined) {
errors.push({
field: `spec.egressBindings[${index}].cidr`,
message: 'cidr is not supported on this egress surface; use dns exact-host or public-web',
})
}
})
}
return errors.map(error => ({
...error,
field: error.field.replace(/^spec\.egressBindings/, fieldPrefix),
}))
}