Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { readFile } from 'node:fs/promises'
import { request as httpRequest } from 'node:http'
import { join } from 'node:path'
// NP-08 access-only runtime observer. This file is streamed into the mcp-host pod.
export const NP08_RUNTIME_ACCESS_ROTATION_WAIT_MS = 35_000
export const NP08_RUNTIME_ACCESS_POLL_MS = 500
export const NP08_RUNTIME_ACCESS_MIN_VALIDITY_SECONDS = 30
const DEFAULT_RUNTIME_AUTH_STATE_DIR = '/var/run/clerum/workflow-auth'
const RUNTIME_AUTH_STATE_FILE = 'approval-auth.json'
const DEFAULT_RUNTIME_PORT = 8080
const LOCAL_RUNTIME_HEALTH_PATH = '/v1/runtime/health'
const MAX_STATE_FILE_BYTES = 128 * 1024
const MAX_HEALTH_BODY_BYTES = 16 * 1024
function delay(ms) {
return new Promise(resolve => setTimeout(resolve, ms))
}
function strictNonEmptyString(value) {
if (typeof value !== 'string' || value.length === 0 || value !== value.trim()) {
return null
}
return value
}
function finiteNumber(value) {
return typeof value === 'number' && Number.isFinite(value) ? value : null
}
function decodeJwtPayload(value) {
if (typeof value !== 'string' || value.length === 0) return null
const parts = value.split('.')
if (parts.length !== 3 || parts[1].length === 0) return null
try {
const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'))
return payload && typeof payload === 'object' && !Array.isArray(payload) ? payload : null
} catch {
return null
}
}
export function decodeRuntimeAccessToken(value) {
const payload = decodeJwtPayload(value)
if (!payload) return null
const hostRefs = Array.isArray(payload.hostRefs) ? payload.hostRefs : []
// HCC runtime authority is a single-Host lineage. Rejecting additional
// refs keeps the persisted candidate's complete binding identical to the
// mounted identity instead of comparing only a privileged first element.
const hostRef = hostRefs.length === 1 ? strictNonEmptyString(hostRefs[0]) : null
const recipeNamespace = strictNonEmptyString(payload.recipeNamespace)
const recipeName = strictNonEmptyString(payload.recipeName)
const exp = finiteNumber(payload.exp)
const iat = finiteNumber(payload.iat)
if (!hostRef || !recipeNamespace || !recipeName) return null
return {
value,
binding: { hostRef, recipeNamespace, recipeName },
exp,
iat,
}
}
function sameBinding(left, right) {
return (
left.hostRef === right.hostRef &&
left.recipeNamespace === right.recipeNamespace &&
left.recipeName === right.recipeName
)
}
function isFresh(candidate, nowMs, minValiditySeconds) {
return (
candidate?.exp !== null &&
candidate.exp > Math.floor(nowMs / 1000) + minValiditySeconds
)
}
function isStrictlyFresher(candidate, baseline) {
if (!sameBinding(candidate.binding, baseline.binding)) return false
if (baseline.iat !== null && (candidate.iat === null || candidate.iat < baseline.iat)) {
return false
}
if (baseline.exp === null) return true
if (candidate.exp === null) return false
if (candidate.exp !== baseline.exp) return candidate.exp > baseline.exp
if (baseline.iat === null) return candidate.iat !== null
return candidate.iat !== null && candidate.iat > baseline.iat
}
async function readPersistedAccessCandidate(stateFilePath, readFileImpl) {
try {
const raw = await readFileImpl(stateFilePath, 'utf8')
if (typeof raw !== 'string' || raw.length > MAX_STATE_FILE_BYTES) return null
const parsed = JSON.parse(raw)
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
return decodeRuntimeAccessToken(parsed.accessToken)
} catch {
// Atomic rotation can briefly race a read. Malformed state never becomes
// an identity source, so the caller retains the mounted access identity.
return null
}
}
export function runtimeAuthStateFilePath(env = process.env) {
const configured = strictNonEmptyString(env.MCP_HOST_RUNTIME_AUTH_STATE_DIR)
return join(configured ?? DEFAULT_RUNTIME_AUTH_STATE_DIR, RUNTIME_AUTH_STATE_FILE)
}
export async function observeFreshRuntimeAccess({
mountedAccessValue,
stateFilePath = runtimeAuthStateFilePath(),
nowMs = Date.now(),
minValiditySeconds = NP08_RUNTIME_ACCESS_MIN_VALIDITY_SECONDS,
readFileImpl = readFile,
}) {
const mounted = decodeRuntimeAccessToken(mountedAccessValue)
if (!mounted) throw new Error('runtime_access_binding_unavailable')
const persisted = await readPersistedAccessCandidate(stateFilePath, readFileImpl)
if (
persisted &&
isFresh(persisted, nowMs, minValiditySeconds) &&
isStrictlyFresher(persisted, mounted)
) {
return { ...persisted, source: 'persisted' }
}
if (isFresh(mounted, nowMs, minValiditySeconds)) {
return { ...mounted, source: 'mounted' }
}
return null
}
export async function waitForFreshRuntimeAccess({
mountedAccessValue,
stateFilePath = runtimeAuthStateFilePath(),
timeoutMs = NP08_RUNTIME_ACCESS_ROTATION_WAIT_MS,
pollIntervalMs = NP08_RUNTIME_ACCESS_POLL_MS,
minValiditySeconds = NP08_RUNTIME_ACCESS_MIN_VALIDITY_SECONDS,
readFileImpl = readFile,
now = Date.now,
sleep = delay,
}) {
const deadline = now() + timeoutMs
while (true) {
const candidate = await observeFreshRuntimeAccess({
mountedAccessValue,
stateFilePath,
nowMs: now(),
minValiditySeconds,
readFileImpl,
})
if (candidate) return candidate
const remainingMs = deadline - now()
if (remainingMs <= 0) throw new Error('runtime_access_fresh_token_timeout')
await sleep(Math.min(pollIntervalMs, remainingMs))
}
}
function responseStatus(result) {
const status = result?.response?.status ?? result?.status
if (!Number.isInteger(status)) throw new Error('runtime_access_request_status_missing')
return status
}
function shouldAdoptObserved(current, observed, nowMs, minValiditySeconds) {
if (!current) return true
if (current.value === observed.value) return true
if (!isFresh(current, nowMs, minValiditySeconds)) return true
return isStrictlyFresher(observed, current)
}
export async function requestWithRuntimeAccess({
mountedAccessValue,
stateFilePath = runtimeAuthStateFilePath(),
currentCandidate = null,
request,
timeoutMs = NP08_RUNTIME_ACCESS_ROTATION_WAIT_MS,
pollIntervalMs = NP08_RUNTIME_ACCESS_POLL_MS,
minValiditySeconds = NP08_RUNTIME_ACCESS_MIN_VALIDITY_SECONDS,
readFileImpl = readFile,
now = Date.now,
sleep = delay,
}) {
if (typeof request !== 'function') throw new Error('runtime_access_request_missing')
const observed = await observeFreshRuntimeAccess({
mountedAccessValue,
stateFilePath,
nowMs: now(),
minValiditySeconds,
readFileImpl,
})
let candidate = currentCandidate
if (observed && shouldAdoptObserved(candidate, observed, now(), minValiditySeconds)) {
candidate = observed
}
if (!candidate || !isFresh(candidate, now(), minValiditySeconds)) {
candidate = await waitForFreshRuntimeAccess({
mountedAccessValue,
stateFilePath,
timeoutMs,
pollIntervalMs,
minValiditySeconds,
readFileImpl,
now,
sleep,
})
}
let result = await request(candidate.value)
if (responseStatus(result) !== 401) {
return { candidate, result, rotatedAfterUnauthorized: false }
}
const deadline = now() + timeoutMs
const attemptedValues = new Set([candidate.value])
while (true) {
const remainingMs = deadline - now()
if (remainingMs <= 0) throw new Error('runtime_access_rotation_timeout')
await sleep(Math.min(pollIntervalMs, remainingMs))
const next = await observeFreshRuntimeAccess({
mountedAccessValue,
stateFilePath,
nowMs: now(),
minValiditySeconds,
readFileImpl,
})
if (
!next ||
attemptedValues.has(next.value) ||
!shouldAdoptObserved(candidate, next, now(), minValiditySeconds)
) {
continue
}
candidate = next
attemptedValues.add(candidate.value)
result = await request(candidate.value)
if (responseStatus(result) !== 401) {
return { candidate, result, rotatedAfterUnauthorized: true }
}
}
}
function timeoutSignal(timeoutMs) {
return typeof globalThis.AbortSignal?.timeout === 'function'
? globalThis.AbortSignal.timeout(timeoutMs)
: undefined
}
function runtimePort(env) {
const raw = strictNonEmptyString(env.CLERUM_SERVER_PORT) ?? String(DEFAULT_RUNTIME_PORT)
if (!/^[1-9][0-9]*$/.test(raw)) throw new Error('mcp_host_runtime_port_invalid')
const value = Number(raw)
if (!Number.isSafeInteger(value) || value > 65_535) {
throw new Error('mcp_host_runtime_port_invalid')
}
return value
}
function contextMapperBaseUrl(env) {
const raw = strictNonEmptyString(env.CLERUM_CONTEXT_MAPPER_URL)
if (!raw) throw new Error('hcc_context_mapper_url_unavailable')
let parsed
try {
parsed = new URL(raw)
} catch {
throw new Error('hcc_context_mapper_url_invalid')
}
if (
(parsed.protocol !== 'http:' && parsed.protocol !== 'https:') ||
parsed.username ||
parsed.password ||
(parsed.pathname !== '/' && parsed.pathname !== '') ||
parsed.search ||
parsed.hash
) {
throw new Error('hcc_context_mapper_url_invalid')
}
return parsed.origin
}
export async function requestLocalRuntimeHealth({
port,
timeoutMs,
requestFactory = httpRequest,
}) {
return new Promise((resolve, reject) => {
let settled = false
let deadline
const finish = (callback, value) => {
if (settled) return
settled = true
clearTimeout(deadline)
callback(value)
}
const request = requestFactory(
{
hostname: '127.0.0.1',
port,
path: LOCAL_RUNTIME_HEALTH_PATH,
method: 'GET',
headers: { accept: 'application/json' },
},
response => {
let bytes = 0
const chunks = []
response.on('data', chunk => {
bytes += chunk.length
if (bytes > MAX_HEALTH_BODY_BYTES) {
request.destroy(new Error('mcp_host_runtime_health_body_too_large'))
return
}
chunks.push(chunk)
})
response.once('end', () => {
let body = null
try {
body = JSON.parse(Buffer.concat(chunks).toString('utf8'))
} catch {
// The caller treats a malformed body as unavailable.
}
finish(resolve, { status: response.statusCode, body })
})
response.once('aborted', () => {
finish(reject, new Error('mcp_host_runtime_health_aborted'))
})
response.once('error', error => finish(reject, error))
}
)
// ClientRequest#setTimeout is an inactivity timeout and can be defeated by
// a peer that drip-feeds bytes. The gate needs a wall-clock deadline for
// the complete local health exchange.
deadline = setTimeout(() => {
request.destroy(new Error('mcp_host_runtime_health_timeout'))
}, timeoutMs)
deadline.unref?.()
request.once('error', error => finish(reject, error))
request.end()
})
}
export async function requireLocalRuntimeHealth({
env = process.env,
requestImpl = requestLocalRuntimeHealth,
timeoutMs = 5_000,
} = {}) {
let result
try {
result = await requestImpl({ port: runtimePort(env), timeoutMs })
} catch {
throw new Error('mcp_host_runtime_health_unavailable')
}
if (result?.status !== 200 || result?.body?.status !== 'ok') {
throw new Error(`mcp_host_runtime_health_unavailable_http_${result?.status ?? 'unknown'}`)
}
}
async function requestJson(fetchImpl, baseUrl, path, init = {}) {
let response
try {
response = await fetchImpl(`${baseUrl}${path}`, {
...init,
redirect: 'error',
signal: timeoutSignal(10_000),
})
} catch {
throw new Error('hcc_request_failed')
}
const text = await response.text()
let body = null
try {
body = JSON.parse(text)
} catch {
body = { nonJson: true }
}
return { response, body }
}
async function assertEventually(label, assertion, timeoutMs = 60_000) {
const deadline = Date.now() + timeoutMs
while (Date.now() < deadline) {
if (await assertion()) return
await delay(1_000)
}
throw new Error(`${label} did not converge`)
}
export async function runDeployedNp08Journey({
env = process.env,
fetchImpl = globalThis.fetch,
} = {}) {
const mountedAccessValue = env.MCP_HOST_RUNTIME_ACCESS_TOKEN
const workflowToken = env.MCP_HOST_WORKFLOW_CONTROL_TOKEN
const serverA = env.NP08_SERVER_A
const serverB = env.NP08_SERVER_B
const serverC = env.NP08_SERVER_C
const expectedSyntheticValue = env.NP08_EXPECTED_SYNTHETIC_VALUE
const hccBaseUrl = contextMapperBaseUrl(env)
if (
!mountedAccessValue ||
!workflowToken ||
!serverA ||
!serverB ||
!serverC ||
!expectedSyntheticValue
) {
throw new Error('runtime_access_environment_unavailable')
}
const stateFilePath = runtimeAuthStateFilePath(env)
let currentCandidate = await waitForFreshRuntimeAccess({
mountedAccessValue,
stateFilePath,
})
console.log(
currentCandidate.source === 'persisted'
? 'PASS runtime access observed from fresher persisted Host state'
: 'PASS runtime access is fresh in the mounted Host identity'
)
let rotationReported = false
async function callAsRuntime(path, init = {}) {
const outcome = await requestWithRuntimeAccess({
mountedAccessValue,
stateFilePath,
currentCandidate,
request: value =>
requestJson(fetchImpl, hccBaseUrl, path, {
...init,
headers: {
...(init.headers ?? {}),
authorization: `Bearer ${value}`,
},
}),
})
currentCandidate = outcome.candidate
if (outcome.rotatedAfterUnauthorized && !rotationReported) {
rotationReported = true
console.log('PASS runtime access advanced after an HCC authorization retry')
}
return outcome.result
}
const credentialPath = '/api/v2/hosts/self/mcpservers/credential'
await assertEventually('same-Context inventory', async () => {
const { response, body } = await callAsRuntime('/api/v2/hosts/self/mcpservers')
if (response.status !== 200 || !Array.isArray(body?.servers)) return false
const names = body.servers.map(server => server?.name)
if (!names.includes(serverA) || names.includes(serverB)) return false
if (
JSON.stringify(body).includes('secretRef') ||
JSON.stringify(body).includes(expectedSyntheticValue)
) {
throw new Error('inventory_exposed_credential_material')
}
return true
})
console.log('PASS same-Context inventory is scoped and metadata-only')
const credentialValueField = 'token'
const positive = await callAsRuntime(credentialPath, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ serverName: serverA }),
})
if (
positive.response.status !== 200 ||
positive.body?.[credentialValueField] !== expectedSyntheticValue ||
typeof positive.body?.credentialRevision !== 'string' ||
positive.body.credentialRevision.length === 0
) {
throw new Error(`same_context_credential_failed_http_${positive.response.status}`)
}
console.log('PASS same-Context credential returned the fenced synthetic value in-memory')
for (const [label, serverName] of [
['cross-Context', serverB],
['unknown', 'np08-e2e-unknown'],
]) {
const denied = await callAsRuntime(credentialPath, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ serverName }),
})
if (
denied.response.status !== 404 ||
JSON.stringify(denied.body) !== '{"error":"not_found"}'
) {
throw new Error(`${label}_credential_not_opaque_404`)
}
if (Object.hasOwn(denied.body ?? {}, credentialValueField)) {
throw new Error(`${label}_credential_response_contained_value`)
}
console.log(`PASS ${label} credential request denied without a credential response`)
}
const noAuth = await callAsRuntime(credentialPath, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ serverName: serverC }),
})
if (noAuth.response.status !== 200 || noAuth.body?.[credentialValueField] !== null) {
throw new Error(`same_context_no_auth_failed_http_${noAuth.response.status}`)
}
console.log('PASS same-Context no-auth server returned an explicit null credential')
const malformedBody = await callAsRuntime(credentialPath, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ serverName: serverA, contextRef: 'caller-supplied-context' }),
})
if (malformedBody.response.status !== 400 || malformedBody.body?.error !== 'bad_request') {
throw new Error('caller_supplied_context_was_accepted')
}
console.log('PASS caller-supplied Context field was rejected')
const bearer = value => ({ authorization: `Bearer ${value}` })
for (const [label, headers] of [
['anonymous', {}],
['workflow-only', bearer(workflowToken)],
['malformed-bearer', bearer('not-a-jwt')],
]) {
const denied = await requestJson(fetchImpl, hccBaseUrl, '/api/v2/hosts/self/mcpservers', { headers })
if (denied.response.status !== 401 || denied.body?.error !== 'unauthorized') {
throw new Error(`${label}_inventory_not_generic_401`)
}
console.log(`PASS ${label} Host inventory request rejected`)
}
for (const path of [
'/api/v1/mcpservers/context/np08-e2e-context-b',
`/api/v1/mcpservers/${serverB}/auth`,
]) {
const retired = await requestJson(fetchImpl, hccBaseUrl, path)
if (retired.response.status !== 410 || retired.body?.error !== 'gone') {
throw new Error('legacy_route_was_not_tombstoned')
}
}
console.log('PASS legacy caller-selected routes are tombstoned')
}
if (process.env.NP08_RUNTIME_ACTION === 'health') {
await requireLocalRuntimeHealth()
console.log('PASS local mcp-host runtime health is ready before fixture mutation')
} else if (process.env.NP08_RUNTIME_ACTION === 'journey') {
await runDeployedNp08Journey()
}