Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* Guardrail hook resolution (spec §8.2) — turns the admin-authored
* `Host.spec.guardrails.hooks` references (`{id, digest}` grouped by phase) into
* runtime `HookDescriptor`s the LLM-lane engine can call.
*
* For each unique referenced hook id we read its LlmHook CR (llm-hooks
* namespace) and derive:
* - endpoint — image target: the digest-dedup Service DNS the controller
* deploys (`llmhook-<podKey>.<ns>.svc`); service target: the
* referenced Service DNS; remote target: the external baseUrl.
* - path / capabilities / failMode / order from the CR spec.
* - lifecyclePoints — the INTERSECTION of the CR's declared points and the
* Host phase keys the hook is referenced under, so a hook runs
* only where the Host admin placed it (removing it from one
* phase stops it there even if the CR still declares it).
*
* The pod-key derivation MUST byte-match host-context-controller's
* `computePodKey` (llmHookReconciler.ts) or the Service DNS won't resolve.
*
* `getLlmHook` is injected so this is unit-testable without a cluster.
*/
import { createHash } from 'crypto'
import type { GuardrailsConfig } from './core/guardrails/config'
import type { HookDescriptor, LifecyclePoint } from './core/guardrails/hooks/types'
import type { Capability } from './core/guardrails/types'
import type { LlmHookCR } from './k8sClient'
import { logger } from './logger'
/** Host phase key (CRD/Host naming) → engine lifecycle point. */
const PHASE_TO_POINT: Record<string, LifecyclePoint> = {
preCall: 'pre_call',
moderate: 'moderate',
postCallSuccess: 'post_call',
onError: 'on_error',
preToolUse: 'pre_tool_use',
postToolUse: 'post_tool_use',
}
const KNOWN_CAPABILITIES: readonly string[] = [
'may_deny',
'may_rewrite',
'may_substitute_result',
'may_add_context',
]
interface HookRef {
id?: string
digest?: string
}
type ImageTarget = NonNullable<NonNullable<LlmHookCR['spec']>['target']>['image']
export interface ResolveHookDeps {
getLlmHook: (name: string) => Promise<LlmHookCR | null>
llmHooksNamespace: string
}
interface CollectedRef {
/** First digest seen for this id across phases. */
digest: string | undefined
/** Engine lifecycle points this id is referenced under on the Host. */
points: Set<LifecyclePoint>
}
/**
* Unique referenced hook ids (across all phases) → the first digest seen for
* each, plus the set of Host phases (as engine points) the id appears under.
* Unknown phase keys contribute no point.
*/
function collectRefs(guardrails: GuardrailsConfig | undefined): Map<string, CollectedRef> {
const out = new Map<string, CollectedRef>()
const hooks = guardrails?.hooks as Record<string, unknown> | undefined
if (!hooks) return out
for (const phase of Object.keys(hooks)) {
const refs = hooks[phase]
if (!Array.isArray(refs)) continue
const point = PHASE_TO_POINT[phase] as LifecyclePoint | undefined
for (const r of refs as HookRef[]) {
if (!r || typeof r.id !== 'string') continue
let entry = out.get(r.id)
if (!entry) {
entry = { digest: r.digest, points: new Set() }
out.set(r.id, entry)
}
if (point) entry.points.add(point)
}
}
return out
}
/** Order-independent egress canonicalization — mirrors HCC `normalizeEgressBindings`. */
function normalizeEgressBindings(
bindings: NonNullable<ImageTarget>['egressBindings']
): Array<{ cidr: string | null; toFQDN: string | null; ports: number[] }> {
return (bindings ?? [])
.map(b => ({
cidr: b.cidr ?? null,
toFQDN: b.toFQDN ?? null,
ports: [...(b.ports ?? [])].sort((a, z) => a - z),
}))
.sort((a, z) => JSON.stringify(a).localeCompare(JSON.stringify(z)))
}
/** MUST byte-match host-context-controller `computePodKey` (key order matters). */
function computePodKey(img: NonNullable<ImageTarget>): string {
const canonical = {
imageRef: img.ref,
port: img.port,
envSecret: img.envSecret ?? '',
egressBindings: normalizeEgressBindings(img.egressBindings),
addCapabilities: [...(img.security?.addCapabilities ?? [])].sort(),
}
return createHash('sha256').update(JSON.stringify(canonical)).digest('hex').slice(0, 16)
}
type ResolvedEndpoint = { endpoint: string; kind: 'image' | 'service' | 'remote' }
function endpointFor(cr: LlmHookCR, ns: string): ResolvedEndpoint | null {
const t = cr.spec?.target
const img = t?.image
if (img?.ref && img.port) {
const podKey = computePodKey(img)
return {
endpoint: `http://llmhook-${podKey}.${ns}.svc.cluster.local:${img.port}`,
kind: 'image',
}
}
const svc = t?.service
if (svc?.name && svc.namespace && svc.port) {
return {
endpoint: `http://${svc.name}.${svc.namespace}.svc.cluster.local:${svc.port}`,
kind: 'service',
}
}
if (t?.remote?.baseUrl) return { endpoint: t.remote.baseUrl, kind: 'remote' }
return null
}
/**
* §1.2 path-collision loser: two co-located hooks (same pod key) declaring the
* same `spec.path` share one handler, so a loser dialed at that path would
* inherit the winner's admin-granted capabilities. The host-context-controller
* flags losers with a `Ready=False / reason=DuplicatePath` condition ("fail
* closed"), but nothing enforced it — the resolver only ever read
* `observedDigest`. Honor the condition here.
*/
function isDuplicatePathLoser(cr: LlmHookCR): boolean {
const conditions = (
cr.status as
{ conditions?: Array<{ type?: string; status?: string; reason?: string }> } | undefined
)?.conditions
return (
Array.isArray(conditions) &&
conditions.some(
c => c?.type === 'Ready' && c?.status === 'False' && c?.reason === 'DuplicatePath'
)
)
}
/**
* Resolve every referenced hook into a `HookDescriptor`. Dangling refs, targets
* with no resolvable endpoint, and (for image hooks) digest mismatches are
* skipped with a warning rather than failing the whole boot.
*/
export async function resolveGuardrailHookDescriptors(
guardrails: GuardrailsConfig | undefined,
deps: ResolveHookDeps
): Promise<HookDescriptor[]> {
const refs = collectRefs(guardrails)
const out: HookDescriptor[] = []
for (const [id, ref] of refs) {
const refDigest = ref.digest
let cr: LlmHookCR | null
try {
cr = await deps.getLlmHook(id)
} catch (err) {
logger.error(
{ hookId: id, error: err instanceof Error ? err.message : String(err) },
'[Guardrails] failed reading LlmHook'
)
continue
}
if (!cr) continue // dangling reference → skip
const ep = endpointFor(cr, deps.llmHooksNamespace)
if (!ep) {
logger.warn({ hookId: id }, '[Guardrails] LlmHook has no resolvable target; skipping')
continue
}
const declared = (cr.spec?.lifecyclePoints ?? [])
.map(p => PHASE_TO_POINT[p])
.filter((p): p is LifecyclePoint => !!p)
if (declared.length === 0) {
logger.warn(
{ hookId: id },
'[Guardrails] LlmHook declares no known lifecycle points; skipping'
)
continue
}
// Run the hook only at the phases the Host references it under (§8.2): the
// Host phase key is the admin's placement, the CR's points are what the hook
// supports. A Host phase the hook does not declare is ignored.
const points = declared.filter(p => ref.points.has(p))
if (points.length === 0) {
logger.warn(
{ hookId: id, declared, referenced: [...ref.points] },
'[Guardrails] LlmHook is not referenced under any phase it declares; skipping'
)
continue
}
const capabilities = (cr.spec?.capabilities ?? []).filter((c): c is Capability =>
KNOWN_CAPABILITIES.includes(c)
)
const path = cr.spec?.path ?? '/'
const failMode: 'open' | 'closed' = cr.spec?.failMode === 'open' ? 'open' : 'closed'
// Content projection selector (§8.4/§8.7). Only an explicit `metadata` makes a
// pre_call hook content-free; anything else (incl. absent) receives content.
const contentAccess: 'metadata' | 'content' | undefined =
cr.spec?.contentAccess === 'metadata'
? 'metadata'
: cr.spec?.contentAccess === 'content'
? 'content'
: undefined
const order = typeof cr.spec?.order === 'number' ? cr.spec.order : 100
// §8.6 circuit-breaker policy (CRD defaults: strict / 5 / 30000). `strict`
// preserves the always-dial behavior; `breaker` is honored at runtime only
// for advisory (non-may_deny) hooks (RemoteLlmHook.breakerEngaged).
const ou = cr.spec?.onUnavailable
const onUnavailable = {
mode: ou?.mode === 'breaker' ? ('breaker' as const) : ('strict' as const),
failureThreshold:
typeof ou?.failureThreshold === 'number' && ou.failureThreshold >= 1
? ou.failureThreshold
: 5,
cooldownMs: typeof ou?.cooldownMs === 'number' && ou.cooldownMs >= 0 ? ou.cooldownMs : 30000,
}
// `remote` targets are dialed over the public internet → SSRF-guarded
// transport (private/metadata-range reject + DNS-pin). image/service targets
// resolve to cluster-private IPs and must bypass that guard.
const external = ep.kind === 'remote'
// Digest binding (§8.2): an image hook whose reconciled digest no longer
// matches the admin-pinned reference is not the reviewed image. Rather than
// drop it (fail-OPEN), QUARANTINE it — the descriptor still loads but every
// /v1 call short-circuits to unavailable, so a `may_deny` (fail-closed) hook
// DENIES and an advisory hook contributes nothing (§8.6/N11). Never a silent
// allow for a deny-authoritative hook whose integrity check failed.
const digestMismatch =
ep.kind === 'image' &&
!!refDigest &&
!!cr.status?.observedDigest &&
refDigest !== cr.status.observedDigest
// A path-collision loser is fail-closed the same way: quarantine it so its
// /v1 calls short-circuit to unavailable (may_deny → deny; advisory →
// nothing) instead of hitting the co-located winner's handler and inheriting
// its capabilities.
const duplicatePathLoser = isDuplicatePathLoser(cr)
const quarantined = digestMismatch || duplicatePathLoser
if (digestMismatch) {
logger.warn(
{ hookId: id, refDigest, observedDigest: cr.status?.observedDigest },
'[Guardrails] LlmHook digest mismatch; quarantining (fail-closed for may_deny)'
)
}
if (duplicatePathLoser) {
logger.warn(
{ hookId: id },
'[Guardrails] LlmHook is a DuplicatePath collision loser (Ready=False); quarantining (fail-closed for may_deny)'
)
}
out.push({
id,
endpoint: ep.endpoint,
path,
lifecyclePoints: points,
capabilities,
failMode,
onUnavailable,
order,
external,
...(contentAccess ? { contentAccess } : {}),
...(quarantined ? { quarantined: true } : {}),
})
logger.info(
{
hookId: id,
endpointKind: ep.kind,
path,
points,
capabilities,
failMode,
external,
...(quarantined
? { quarantined: duplicatePathLoser ? 'duplicate-path' : 'digest-mismatch' }
: {}),
},
'[Guardrails] resolved hook'
)
}
return out
}
/**
* Merge resolved descriptors into a guardrails config for the agent. Preserves
* any inline `hookDescriptors` (dev/E2E via CLERUM_GUARDRAILS_CONFIG) and the
* rest of the block; returns undefined only when there is nothing to apply.
*/
export function withResolvedHookDescriptors(
guardrails: GuardrailsConfig | undefined,
resolved: HookDescriptor[]
): GuardrailsConfig | undefined {
if (!guardrails && resolved.length === 0) return undefined
const inline = guardrails?.hookDescriptors ?? []
const hookDescriptors = [...inline, ...resolved]
return { ...(guardrails ?? {}), hookDescriptors }
}