Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
'use strict'
const ALLOWED_MODELS_CONFIGMAP_NAME = 'clerum-llm-allowed-models'
const CONTENT_HASH_ANNOTATION = 'clerum.io/content-hash'
const CATALOG_REVISION_ANNOTATION = 'clerum.io/catalog-revision'
const CONNECTION_REVISION_ANNOTATION = 'clerum.io/connection-revision'
const CODEX_CONNECTION_STATUS_ANNOTATION = 'clerum.io/codex-connection-status'
const CODEX_ENABLED_ANNOTATION = 'clerum.io/codex-enabled'
const CODEX_CONNECTIONS_ANNOTATION = 'clerum.io/codex-connections'
const CODEX_CONNECTION_REF_ANNOTATION = 'clerum.io/codex-connection-ref'
const SUBSCRIPTION_CONNECTION_REF_ANNOTATION = 'clerum.io/subscription-connection-ref'
const CODEX_UNASSIGNED_CONNECTION_KEY = 'unassigned'
const CODEX_PROVIDER = 'codex-subscription'
const CODEX_EXECUTE_SCOPE = 'llm:codex:execute'
const CODEX_PROVIDER_PREFIX = `${CODEX_PROVIDER}:`
const GROK_PROVIDER = 'grok-subscription'
const GROK_EXECUTE_SCOPE = 'llm:grok:execute'
const GROK_PROVIDER_PREFIX = `${GROK_PROVIDER}:`
const GROK_ENABLED_ANNOTATION = 'clerum.io/grok-enabled'
const GROK_CONNECTIONS_ANNOTATION = 'clerum.io/grok-connections'
const GROK_CONNECTION_STATUS_ANNOTATION = 'clerum.io/grok-connection-status'
function assignedCodexConnectionKey(value) {
const trimmed = typeof value === 'string' ? value.trim() : ''
return trimmed || CODEX_UNASSIGNED_CONNECTION_KEY
}
function isCodexUnassignedConnectionKey(value) {
return assignedCodexConnectionKey(value) === CODEX_UNASSIGNED_CONNECTION_KEY
}
/**
* Dual-key grant reader. Codex alias is honored only when provider is
* `codex-subscription`. Disagree (both set, unequal) fails closed. A leftover
* Codex alias on any other provider fails closed.
*/
function readSubscriptionConnectionRef(input) {
const provider = input && typeof input.provider === 'string' ? input.provider : ''
const annotations = (input && input.annotations) || {}
const canonical =
typeof annotations[SUBSCRIPTION_CONNECTION_REF_ANNOTATION] === 'string'
? annotations[SUBSCRIPTION_CONNECTION_REF_ANNOTATION].trim()
: ''
const alias =
typeof annotations[CODEX_CONNECTION_REF_ANNOTATION] === 'string'
? annotations[CODEX_CONNECTION_REF_ANNOTATION].trim()
: ''
if (provider === CODEX_PROVIDER) {
if (canonical && alias && canonical !== alias) {
return {
ok: false,
code: 'host_binding_mismatch',
message: 'subscription connection annotations disagree',
}
}
return { ok: true, connectionKey: assignedCodexConnectionKey(canonical || alias) }
}
if (alias) {
return {
ok: false,
code: 'host_binding_mismatch',
message: 'Codex connection annotation is not valid for this oauth-broker provider',
}
}
return { ok: true, connectionKey: assignedCodexConnectionKey(canonical) }
}
function snapshotFromConfigMapError(error) {
return { flagEnabled: false, snapshotError: error }
}
function parseOptionalIntegerAnnotation(annotations, key) {
if (!annotations || !Object.prototype.hasOwnProperty.call(annotations, key)) return null
const parsed = Number(annotations[key])
return Number.isInteger(parsed) ? parsed : 'invalid'
}
function dropCodexModels(enabledModels, staleModels) {
for (const key of [...enabledModels]) {
if (key.startsWith(CODEX_PROVIDER_PREFIX)) {
enabledModels.delete(key)
staleModels.delete(key)
}
}
}
function intersectCodexModels(enabledModels, staleModels, models) {
const allowed = new Set(models.filter(model => typeof model === 'string' && model.trim()))
for (const key of [...enabledModels]) {
if (!key.startsWith(CODEX_PROVIDER_PREFIX)) continue
const model = key.slice(CODEX_PROVIDER_PREFIX.length)
if (!allowed.has(model)) {
enabledModels.delete(key)
staleModels.delete(key)
}
}
}
function parseFlatCatalog(data) {
const enabledModels = new Set()
const staleModels = new Set()
for (const [provider, raw] of Object.entries(data ?? {})) {
let rows
try {
rows = JSON.parse(raw)
} catch {
return { error: 'malformed' }
}
if (!Array.isArray(rows)) return { error: 'malformed' }
for (const row of rows) {
if (row && typeof row.model === 'string' && row.model.trim()) {
const key = `${provider}:${row.model}`
enabledModels.add(key)
if (row.stale === true) staleModels.add(key)
}
}
}
return { enabledModels, staleModels }
}
function parseAllowedModelsSnapshot(cm, connectionKey) {
if (!cm) return snapshotFromConfigMapError('missing')
const annotations = (cm.metadata && cm.metadata.annotations) || {}
const catalog = parseFlatCatalog(cm.data)
if (catalog.error) return snapshotFromConfigMapError('malformed')
const enabledModels = catalog.enabledModels
const staleModels = catalog.staleModels
let catalogRevision = parseOptionalIntegerAnnotation(annotations, CATALOG_REVISION_ANNOTATION)
let connectionRevision = parseOptionalIntegerAnnotation(
annotations,
CONNECTION_REVISION_ANNOTATION
)
if (catalogRevision === 'invalid' || connectionRevision === 'invalid') {
return snapshotFromConfigMapError('malformed')
}
let connectionStatus = annotations[CODEX_CONNECTION_STATUS_ANNOTATION] || null
const assignedKey = assignedCodexConnectionKey(connectionKey)
const rawMap = annotations[CODEX_CONNECTIONS_ANNOTATION]
if (rawMap) {
let parsed
try {
parsed = JSON.parse(rawMap)
} catch {
return snapshotFromConfigMapError('malformed')
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
return snapshotFromConfigMapError('malformed')
}
const assigned = parsed[assignedKey]
// Mapped miss OR models[] omitted: disconnected, empty Codex, no rematch.
if (!assigned || !Array.isArray(assigned.models)) {
connectionStatus = 'disconnected'
dropCodexModels(enabledModels, staleModels)
} else {
connectionStatus = assigned.status || connectionStatus
if (Number.isInteger(assigned.catalogRevision)) {
catalogRevision = assigned.catalogRevision
}
if (Number.isInteger(assigned.connectionRevision)) {
connectionRevision = assigned.connectionRevision
}
intersectCodexModels(enabledModels, staleModels, assigned.models)
}
} else if (assignedKey === CODEX_UNASSIGNED_CONNECTION_KEY) {
// Unassigned never inherits a legacy flat catalog.
connectionStatus = 'disconnected'
dropCodexModels(enabledModels, staleModels)
}
return {
flagEnabled: annotations[CODEX_ENABLED_ANNOTATION] === 'true',
connectionStatus,
catalogContentHash: annotations[CONTENT_HASH_ANNOTATION] ?? null,
catalogRevision,
connectionRevision,
enabledModels,
staleModels,
}
}
function snapshotForAssignedCodexGrant(connectionKey, lastConfigMap, fallback) {
const key = assignedCodexConnectionKey(connectionKey)
if (key === CODEX_UNASSIGNED_CONNECTION_KEY) {
return {
flagEnabled: Boolean(fallback && fallback.flagEnabled),
connectionStatus: 'disconnected',
enabledModels: [],
staleModels: [],
}
}
if (!lastConfigMap) return fallback
return parseAllowedModelsSnapshot(lastConfigMap, key)
}
function collectCodexTargets(spec) {
const targets = []
if (spec && spec.model && spec.model.provider) {
targets.push({
source: 'primary',
provider: spec.model.provider,
model: spec.model.name ?? '',
})
}
for (const row of (spec && spec.allowedModels) || []) {
if (row && row.provider) {
targets.push({ source: 'allowed', provider: row.provider, model: row.model ?? '' })
}
}
for (const row of (spec && spec.llmPolicy && spec.llmPolicy.fallbacks) || []) {
if (row && row.provider) {
targets.push({ source: 'fallback', provider: row.provider, model: row.model ?? '' })
}
}
return targets
}
function freezeProjection(input) {
const driftHashInput = JSON.stringify({
eligibleTargets: input.eligibleTargets,
derivedScopes: input.derivedScopes,
eligibility: input.eligibility,
})
return Object.freeze({ ...input, driftHashInput })
}
function projectCodexExecution(spec, snapshot) {
const targets = collectCodexTargets(spec || {})
const brokerTargets = targets.filter(target => target.provider === CODEX_PROVIDER)
const enabled = new Set(snapshot.enabledModels ?? [])
const stale = new Set(snapshot.staleModels ?? [])
if (snapshot.snapshotError) {
return freezeProjection({
targets,
eligibleTargets: [],
derivedScopes: [],
requiresCodexProxyEgress: false,
catalogContentHash: snapshot.catalogContentHash ?? null,
catalogRevision: snapshot.catalogRevision ?? null,
connectionRevision: snapshot.connectionRevision ?? null,
eligibility: 'uncertain',
reason: `snapshot_${snapshot.snapshotError}`,
})
}
if (!snapshot.flagEnabled) {
return freezeProjection({
targets,
eligibleTargets: [],
derivedScopes: [],
requiresCodexProxyEgress: false,
catalogContentHash: snapshot.catalogContentHash ?? null,
catalogRevision: snapshot.catalogRevision ?? null,
connectionRevision: snapshot.connectionRevision ?? null,
eligibility: 'ineligible',
reason: 'flag_off',
})
}
if (brokerTargets.length === 0) {
return freezeProjection({
targets,
eligibleTargets: [],
derivedScopes: [],
requiresCodexProxyEgress: false,
catalogContentHash: snapshot.catalogContentHash ?? null,
catalogRevision: snapshot.catalogRevision ?? null,
connectionRevision: snapshot.connectionRevision ?? null,
eligibility: 'ineligible',
reason: 'static_only',
})
}
if (snapshot.connectionStatus !== 'connected') {
return freezeProjection({
targets,
eligibleTargets: [],
derivedScopes: [],
requiresCodexProxyEgress: false,
catalogContentHash: snapshot.catalogContentHash ?? null,
catalogRevision: snapshot.catalogRevision ?? null,
connectionRevision: snapshot.connectionRevision ?? null,
eligibility: 'ineligible',
reason: `connection_${snapshot.connectionStatus ?? 'unknown'}`,
})
}
const eligibleTargets = brokerTargets.filter(target => {
if (!target.model.trim()) return false
const key = `${target.provider}:${target.model}`
return enabled.has(key) && !stale.has(key)
})
const eligible = eligibleTargets.length > 0
return freezeProjection({
targets,
eligibleTargets,
derivedScopes: eligible ? [CODEX_EXECUTE_SCOPE] : [],
requiresCodexProxyEgress: eligible,
catalogContentHash: snapshot.catalogContentHash ?? null,
catalogRevision: snapshot.catalogRevision ?? null,
connectionRevision: snapshot.connectionRevision ?? null,
eligibility: eligible ? 'eligible' : 'ineligible',
reason: eligible ? 'eligible' : 'no_eligible_broker_target',
})
}
function toPolicyBinding(cm, connectionKey) {
const key = assignedCodexConnectionKey(connectionKey)
if (!cm || key === CODEX_UNASSIGNED_CONNECTION_KEY) return null
const annotations = (cm.metadata && cm.metadata.annotations) || {}
let catalogRevision = parseOptionalIntegerAnnotation(annotations, CATALOG_REVISION_ANNOTATION)
let credentialRevision = parseOptionalIntegerAnnotation(
annotations,
CONNECTION_REVISION_ANNOTATION
)
const rawMap = annotations[CODEX_CONNECTIONS_ANNOTATION]
if (rawMap) {
let parsed
try {
parsed = JSON.parse(rawMap)
} catch {
return null
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
const assigned = parsed[key]
if (
!assigned ||
!Array.isArray(assigned.models) ||
!Number.isInteger(assigned.catalogRevision) ||
!Number.isInteger(assigned.connectionRevision)
) {
return null
}
return {
catalogRevision: assigned.catalogRevision,
credentialRevision: assigned.connectionRevision,
connectionKey: key,
models: assigned.models.filter(model => typeof model === 'string' && model),
}
}
if (
catalogRevision === null ||
catalogRevision === 'invalid' ||
credentialRevision === null ||
credentialRevision === 'invalid'
) {
return null
}
return { catalogRevision, credentialRevision, connectionKey: key }
}
/**
* Mint an execution policy binding for one (grant, model) pair using the SAME
* eligibility cascade that decides `llm:codex:execute`. It is deliberately a
* caller of `projectCodexExecution` with a synthetic single-target spec, not a
* second copy of the cascade: the invariant
* `binding !== null ⇔ derivedScopes.includes(CODEX_EXECUTE_SCOPE)`
* is what keeps the scope gate and the binding gate from drifting apart.
*
* Always returns an object so the caller can log `reason` (e.g.
* `connection_reauth-required`) without projecting a second time.
*/
function toEligiblePolicyBinding(cm, connectionKey, model) {
const key = assignedCodexConnectionKey(connectionKey)
const trimmedModel = typeof model === 'string' ? model.trim() : ''
if (key === CODEX_UNASSIGNED_CONNECTION_KEY) {
return { binding: null, eligibility: 'ineligible', reason: 'unassigned' }
}
if (!trimmedModel) {
return { binding: null, eligibility: 'ineligible', reason: 'model_missing' }
}
const snapshot = parseAllowedModelsSnapshot(cm, key)
const projection = projectCodexExecution(
{ model: { provider: CODEX_PROVIDER, name: trimmedModel } },
snapshot
)
if (projection.eligibility !== 'eligible') {
return { binding: null, eligibility: projection.eligibility, reason: projection.reason }
}
// Revisions come from the normalized snapshot (assigned.* first, global
// annotations as the legacy shape). The writer always emits both.
if (
!Number.isInteger(snapshot.catalogRevision) ||
!Number.isInteger(snapshot.connectionRevision)
) {
return { binding: null, eligibility: 'ineligible', reason: 'revision_missing' }
}
return {
binding: {
connectionKey: key,
catalogRevision: snapshot.catalogRevision,
credentialRevision: snapshot.connectionRevision,
model: trimmedModel,
},
eligibility: 'eligible',
reason: 'eligible',
}
}
function toEligibleGrokPolicyBinding(cm, connectionKey, model) {
const key = assignedCodexConnectionKey(connectionKey)
const trimmedModel = typeof model === 'string' ? model.trim() : ''
if (key === CODEX_UNASSIGNED_CONNECTION_KEY) {
return { binding: null, eligibility: 'ineligible', reason: 'unassigned' }
}
if (!trimmedModel) {
return { binding: null, eligibility: 'ineligible', reason: 'model_missing' }
}
const snapshot = parseGrokAllowedModelsSnapshot(cm, key)
const projection = projectGrokExecution(
{ model: { provider: GROK_PROVIDER, name: trimmedModel } },
snapshot
)
if (projection.eligibility !== 'eligible') {
return { binding: null, eligibility: projection.eligibility, reason: projection.reason }
}
if (
!Number.isInteger(snapshot.catalogRevision) ||
!Number.isInteger(snapshot.connectionRevision)
) {
return { binding: null, eligibility: 'ineligible', reason: 'revision_missing' }
}
return {
binding: {
connectionKey: key,
catalogRevision: snapshot.catalogRevision,
credentialRevision: snapshot.connectionRevision,
model: trimmedModel,
},
eligibility: 'eligible',
reason: 'eligible',
}
}
function toGrokPolicyBinding(cm, connectionKey) {
const key = assignedCodexConnectionKey(connectionKey)
if (!cm || key === CODEX_UNASSIGNED_CONNECTION_KEY) return null
const annotations = (cm.metadata && cm.metadata.annotations) || {}
const rawMap = annotations[GROK_CONNECTIONS_ANNOTATION]
if (!rawMap) return null
let parsed
try {
parsed = JSON.parse(rawMap)
} catch {
return null
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
const assigned = parsed[key]
if (
!assigned ||
!Array.isArray(assigned.models) ||
!Number.isInteger(assigned.catalogRevision) ||
!Number.isInteger(assigned.connectionRevision)
) {
return null
}
return {
catalogRevision: assigned.catalogRevision,
credentialRevision: assigned.connectionRevision,
connectionKey: key,
models: assigned.models.filter(model => typeof model === 'string' && model),
}
}
function parseGrokAllowedModelsSnapshot(cm, connectionKey) {
if (!cm) return snapshotFromConfigMapError('missing')
const annotations = (cm.metadata && cm.metadata.annotations) || {}
const flagEnabled = annotations[GROK_ENABLED_ANNOTATION] === 'true'
const assignedKey = assignedCodexConnectionKey(connectionKey)
const rawMap = annotations[GROK_CONNECTIONS_ANNOTATION]
if (!rawMap) {
return {
flagEnabled,
connectionStatus: 'disconnected',
enabledModels: [],
staleModels: [],
catalogContentHash: annotations[CONTENT_HASH_ANNOTATION] || null,
}
}
let parsed
try {
parsed = JSON.parse(rawMap)
} catch {
return snapshotFromConfigMapError('malformed')
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
return snapshotFromConfigMapError('malformed')
}
const assigned = parsed[assignedKey]
if (!assigned || !Array.isArray(assigned.models)) {
return {
flagEnabled,
connectionStatus: 'disconnected',
enabledModels: [],
staleModels: [],
catalogContentHash: annotations[CONTENT_HASH_ANNOTATION] || null,
}
}
const enabledModels = assigned.models
.filter(model => typeof model === 'string' && model.trim())
.map(model => `${GROK_PROVIDER_PREFIX}${model}`)
return {
flagEnabled,
connectionStatus: assigned.status || annotations[GROK_CONNECTION_STATUS_ANNOTATION] || null,
catalogRevision: Number.isInteger(assigned.catalogRevision) ? assigned.catalogRevision : null,
connectionRevision: Number.isInteger(assigned.connectionRevision)
? assigned.connectionRevision
: null,
enabledModels,
staleModels: [],
catalogContentHash: annotations[CONTENT_HASH_ANNOTATION] || null,
}
}
function projectGrokExecution(spec, snapshot) {
const targets = collectCodexTargets(spec || {})
const brokerTargets = targets.filter(target => target.provider === GROK_PROVIDER)
const enabled = new Set(snapshot.enabledModels ?? [])
if (snapshot.snapshotError) {
return freezeProjection({
targets,
eligibleTargets: [],
derivedScopes: [],
requiresGrokProxyEgress: false,
catalogContentHash: snapshot.catalogContentHash ?? null,
catalogRevision: snapshot.catalogRevision ?? null,
connectionRevision: snapshot.connectionRevision ?? null,
eligibility: 'uncertain',
reason: `snapshot_${snapshot.snapshotError}`,
})
}
if (!snapshot.flagEnabled) {
return freezeProjection({
targets,
eligibleTargets: [],
derivedScopes: [],
requiresGrokProxyEgress: false,
catalogContentHash: snapshot.catalogContentHash ?? null,
catalogRevision: snapshot.catalogRevision ?? null,
connectionRevision: snapshot.connectionRevision ?? null,
eligibility: 'ineligible',
reason: 'flag_off',
})
}
if (brokerTargets.length === 0) {
return freezeProjection({
targets,
eligibleTargets: [],
derivedScopes: [],
requiresGrokProxyEgress: false,
catalogContentHash: snapshot.catalogContentHash ?? null,
catalogRevision: snapshot.catalogRevision ?? null,
connectionRevision: snapshot.connectionRevision ?? null,
eligibility: 'ineligible',
reason: 'static_only',
})
}
if (snapshot.connectionStatus !== 'connected') {
return freezeProjection({
targets,
eligibleTargets: [],
derivedScopes: [],
requiresGrokProxyEgress: false,
catalogContentHash: snapshot.catalogContentHash ?? null,
catalogRevision: snapshot.catalogRevision ?? null,
connectionRevision: snapshot.connectionRevision ?? null,
eligibility: 'ineligible',
reason: `connection_${snapshot.connectionStatus ?? 'unknown'}`,
})
}
const eligibleTargets = brokerTargets.filter(target => {
if (!target.model.trim()) return false
return enabled.has(`${target.provider}:${target.model}`)
})
const eligible = eligibleTargets.length > 0
return freezeProjection({
targets,
eligibleTargets,
derivedScopes: eligible ? [GROK_EXECUTE_SCOPE] : [],
requiresGrokProxyEgress: eligible,
catalogContentHash: snapshot.catalogContentHash ?? null,
catalogRevision: snapshot.catalogRevision ?? null,
connectionRevision: snapshot.connectionRevision ?? null,
eligibility: eligible ? 'eligible' : 'ineligible',
reason: eligible ? 'eligible' : 'no_eligible_broker_target',
})
}
module.exports = {
ALLOWED_MODELS_CONFIGMAP_NAME,
CONTENT_HASH_ANNOTATION,
CATALOG_REVISION_ANNOTATION,
CONNECTION_REVISION_ANNOTATION,
CODEX_CONNECTION_STATUS_ANNOTATION,
CODEX_ENABLED_ANNOTATION,
CODEX_CONNECTIONS_ANNOTATION,
CODEX_CONNECTION_REF_ANNOTATION,
SUBSCRIPTION_CONNECTION_REF_ANNOTATION,
CODEX_UNASSIGNED_CONNECTION_KEY,
CODEX_PROVIDER,
CODEX_EXECUTE_SCOPE,
GROK_PROVIDER,
GROK_EXECUTE_SCOPE,
GROK_ENABLED_ANNOTATION,
GROK_CONNECTIONS_ANNOTATION,
GROK_CONNECTION_STATUS_ANNOTATION,
assignedCodexConnectionKey,
isCodexUnassignedConnectionKey,
readSubscriptionConnectionRef,
snapshotFromConfigMapError,
parseAllowedModelsSnapshot,
snapshotForAssignedCodexGrant,
collectCodexTargets,
projectCodexExecution,
parseGrokAllowedModelsSnapshot,
projectGrokExecution,
toPolicyBinding,
toGrokPolicyBinding,
toEligibleGrokPolicyBinding,
toEligiblePolicyBinding,
}