Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { config } from '../../config.js'
import type { DbClient } from '../../db.js'
import type { AdministrativeEventSubmitterPrincipalV1 } from '../../middleware/tracingSubmitterAuth.js'
import {
type PendingGovernedEvent,
appendGovernedEventBatchInTransaction,
appendGovernedEventInTransaction,
assertNoClientAuthority,
assertSafeEventPayload,
canonicalPayloadSha256,
normalizeIsoTimestamp,
resolveServiceDependencies,
} from './append.js'
import type {
AdministrativeEventInputV1,
AdministrativeServerBindingV1,
ControlApiLocalAdministrativePrincipalV1,
GovernedAppendResult,
PendingAdministrativeEventEnvelopeV1,
TracingServiceDependencies,
} from './contracts.js'
import {
CONTROL_API_LOCAL_ADMINISTRATIVE_PRINCIPAL_V1,
ControlApiLocalAdministrativeBindingResolver,
type ControlApiLocalAdministrativeContextV1,
} from './controlApiLocalAdministrativeBindingResolver.js'
function permits(values: readonly string[], value: string): boolean {
return values.includes(value)
}
const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
function bindLocalAdministrativeAuthority(
principal: AdministrativeEventSubmitterPrincipalV1 | ControlApiLocalAdministrativePrincipalV1,
binding: AdministrativeServerBindingV1
): AdministrativeServerBindingV1 {
if (principal.kind !== 'control_api_local' || !binding.operatorSub) return binding
return {
...binding,
identityIssuer: binding.identityIssuer ?? config.adminJwtIssuer,
operatorUserId:
binding.operatorUserId ??
(UUID_PATTERN.test(binding.operatorSub) ? binding.operatorSub.toLowerCase() : null),
resourceAud: binding.resourceAud ?? config.adminJwtAudience,
effectiveScopes: binding.effectiveScopes ?? [],
authorizationDecision: binding.authorizationDecision ?? 'allow',
decisionActorSub: binding.decisionActorSub ?? binding.operatorSub,
}
}
export class AdministrativePrincipalBindingInvariantError extends Error {
readonly code = 'administrative_principal_binding_invariant'
constructor(message: string) {
super(message)
this.name = 'AdministrativePrincipalBindingInvariantError'
}
}
function isHccLinkedOutcome(
principal: AdministrativeEventSubmitterPrincipalV1 | ControlApiLocalAdministrativePrincipalV1,
input: AdministrativeEventInputV1
): boolean {
return principal.kind === 'hcc_internal_control' && input.kind === 'linked_outcome'
}
function assertPrincipalBinding(
principal: AdministrativeEventSubmitterPrincipalV1 | ControlApiLocalAdministrativePrincipalV1,
binding: AdministrativeServerBindingV1,
input: AdministrativeEventInputV1
): void {
if (principal.kind === 'hcc_internal_control') {
if (input.kind !== 'linked_outcome') {
throw new AdministrativePrincipalBindingInvariantError(
'hcc_internal_control may submit only linked_outcome administrative events'
)
}
if (!binding.operationId) {
throw new AdministrativePrincipalBindingInvariantError(
'hcc_internal_control linked_outcome requires a server-bound operationId'
)
}
return
}
if (
principal.kind === 'wrc_internal_control' &&
input.kind !== 'service_action' &&
input.kind !== 'linked_outcome'
) {
throw new AdministrativePrincipalBindingInvariantError(
'wrc_internal_control may submit only service_action or linked_outcome administrative events'
)
}
if (input.kind === 'linked_outcome' && !binding.operationId) {
throw new AdministrativePrincipalBindingInvariantError(
'linked_outcome requires a server-bound operationId'
)
}
if (principal.kind === 'control_api_local' && input.kind === 'linked_outcome') {
if (binding.action !== 'host_mutation' || binding.targetType !== 'host') {
throw new AdministrativePrincipalBindingInvariantError(
'control_api_local linked_outcome is limited to Host administrative operations'
)
}
}
}
export class AdministrativeEventService {
private readonly dependencies: Required<TracingServiceDependencies>
constructor(dependencies: TracingServiceDependencies) {
this.dependencies = resolveServiceDependencies(dependencies)
}
async append(
principal: AdministrativeEventSubmitterPrincipalV1 | ControlApiLocalAdministrativePrincipalV1,
binding: AdministrativeServerBindingV1,
input: AdministrativeEventInputV1
): Promise<GovernedAppendResult> {
const event = this.normalize(principal, binding, input)
return this.dependencies.transaction(db => appendGovernedEventInTransaction(db, event))
}
async appendInTransaction(
db: DbClient,
principal: AdministrativeEventSubmitterPrincipalV1 | ControlApiLocalAdministrativePrincipalV1,
binding: AdministrativeServerBindingV1,
input: AdministrativeEventInputV1
): Promise<GovernedAppendResult> {
return appendGovernedEventInTransaction(db, this.normalize(principal, binding, input))
}
async appendManyInTransaction(
db: DbClient,
principal: AdministrativeEventSubmitterPrincipalV1 | ControlApiLocalAdministrativePrincipalV1,
entries: readonly {
binding: AdministrativeServerBindingV1
input: AdministrativeEventInputV1
}[]
): Promise<GovernedAppendResult[]> {
if (entries.length === 0) return []
return appendGovernedEventBatchInTransaction(
db,
entries.map(({ binding, input }) => this.normalize(principal, binding, input)) as [
PendingGovernedEvent<'administrative'>,
...PendingGovernedEvent<'administrative'>[],
]
)
}
/**
* Local callers supply only server-owned mutation context. This method does
* not expose an HTTP binding path or introduce a second persistence route.
*/
async appendControlApiLocalInTransaction(
db: DbClient,
context: ControlApiLocalAdministrativeContextV1,
input: AdministrativeEventInputV1
): Promise<GovernedAppendResult> {
const binding = new ControlApiLocalAdministrativeBindingResolver().resolve(context, input)
if (!binding) {
throw new AdministrativePrincipalBindingInvariantError(
'control_api_local administrative event requires the exact server-owned configuration context'
)
}
return this.appendInTransaction(
db,
CONTROL_API_LOCAL_ADMINISTRATIVE_PRINCIPAL_V1,
binding,
input
)
}
private normalize(
principal: AdministrativeEventSubmitterPrincipalV1 | ControlApiLocalAdministrativePrincipalV1,
binding: AdministrativeServerBindingV1,
input: AdministrativeEventInputV1
): PendingGovernedEvent {
const authoritativeBinding = bindLocalAdministrativeAuthority(principal, binding)
assertNoClientAuthority(input)
assertSafeEventPayload(input.payload)
assertPrincipalBinding(principal, authoritativeBinding, input)
if (!permits(principal.allowedKinds, input.kind)) {
throw new Error(`${principal.kind} cannot submit administrative event kind ${input.kind}`)
}
const occurredAtIso = normalizeIsoTimestamp(input.occurredAt, 'occurredAt')
const ingestedAt = this.dependencies.now().toISOString()
const payload = {
...(input.payload ?? {}),
...(input.reasonCode ? { reason_code: input.reasonCode } : {}),
...(input.sourceStatusRef ? { detail_ref: input.sourceStatusRef } : {}),
}
const canonical = {
family: 'administrative',
sourceService: principal.sourceService,
serviceSub: principal.serviceSub,
sourceKind: principal.kind,
sourceEventId: input.sourceEventId,
// HCC linked outcomes are state facts keyed by operation, generation and
// outcome. HCC holds no stable observation time (it re-observes the
// outcome on every reconcile pass and after every restart), so hashing
// occurredAt turned each re-observation into an idempotency conflict
// (#327). Storage keeps the first occurredAt; reasonCode, sourceStatusRef,
// payload and the server-resolved binding still distinguish a genuinely
// different claim. Every other submitter keeps occurredAt in the hash.
...(isHccLinkedOutcome(principal, input) ? {} : { occurredAt: occurredAtIso }),
kind: input.kind,
reasonCode: input.reasonCode ?? null,
sourceStatusRef: input.sourceStatusRef ?? null,
binding: authoritativeBinding,
payload,
}
const envelope: PendingAdministrativeEventEnvelopeV1<typeof payload> = {
...authoritativeBinding,
eventId: this.dependencies.newEventId(),
schemaVersion: 1,
sourceKind: principal.kind,
sourceService: principal.sourceService,
sourceEventId: input.sourceEventId,
serviceSub: principal.serviceSub,
eventKind: input.kind,
payload,
payloadSha256: canonicalPayloadSha256(canonical),
occurredAt: occurredAtIso,
ingestedAt,
}
return pendingGovernedAdministrativeEventFromEnvelope(envelope)
}
}
export function pendingGovernedAdministrativeEventFromEnvelope<Payload extends object>(
envelope: PendingAdministrativeEventEnvelopeV1<Payload>
): PendingGovernedEvent<'administrative'> {
return {
family: 'administrative',
eventId: envelope.eventId,
schemaVersion: envelope.schemaVersion,
sourceService: envelope.sourceService,
sourceKind: envelope.sourceKind,
sourceEventId: envelope.sourceEventId,
sourceIdentityColumn: 'source_event_id',
occurredAt: envelope.occurredAt,
ingestedAt: envelope.ingestedAt,
payloadSha256: envelope.payloadSha256,
familyColumns: [
{ name: 'event_kind', value: envelope.eventKind },
{ name: 'action', value: envelope.action },
{ name: 'outcome', value: envelope.outcome },
{ name: 'operator_sub', value: envelope.operatorSub },
{ name: 'identity_issuer', value: envelope.identityIssuer ?? null },
{ name: 'operator_user_id', value: envelope.operatorUserId ?? null },
{ name: 'delegated_actor_sub', value: envelope.delegatedActorSub ?? null },
{ name: 'resource_aud', value: envelope.resourceAud ?? null },
{ name: 'effective_scopes', value: [...(envelope.effectiveScopes ?? [])].sort() },
{ name: 'token_exchange_id', value: envelope.tokenExchangeId ?? null },
{ name: 'authorization_decision', value: envelope.authorizationDecision ?? null },
{ name: 'decision_actor_sub', value: envelope.decisionActorSub ?? null },
{ name: 'approval_request_id', value: envelope.approvalRequestId ?? null },
{ name: 'service_sub', value: envelope.serviceSub },
{ name: 'operation_id', value: envelope.operationId },
{ name: 'related_run_id', value: envelope.relatedRunId },
{ name: 'request_id', value: envelope.requestId },
{ name: 'target_type', value: envelope.targetType },
{ name: 'target_ref', value: envelope.targetRef },
{ name: 'target_identity_issuer', value: envelope.targetIdentityIssuer ?? null },
{ name: 'target_human_sub', value: envelope.targetHumanSub ?? null },
{ name: 'target_user_id', value: envelope.targetUserId ?? null },
{ name: 'environment', value: envelope.environment },
{ name: 'team_id', value: envelope.teamId },
{ name: 'namespace', value: envelope.namespace },
{ name: 'source_audit_ref', value: envelope.sourceAuditRef },
{ name: 'payload_metadata', value: JSON.stringify(envelope.payload) },
],
stream: {
environment: envelope.environment,
tenantId: envelope.tenantId,
teamId: envelope.teamId,
runId: envelope.relatedRunId,
operationId: envelope.operationId,
workloadRef: null,
},
}
}