Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
feat(control-api): authorize Codex provider attempts
Alfredo Lopezea5b3203c78f
diff --git a/control-api/src/routes/mcp-host/index.ts b/control-api/src/routes/mcp-host/index.tsindex ee063eeb1..4327dc3d7 100644--- a/control-api/src/routes/mcp-host/index.ts+++ b/control-api/src/routes/mcp-host/index.ts@@ -2,6 +2,7 @@ import { Router } from 'express'import { K8sGateway } from '../../k8s.js'import type { DirectRunAttributionBindingService } from '../../services/tracing/directRunAttributionBindingService.js'import { createMcpHostHostsHeartbeatRoutes } from './hosts-heartbeat.routes.js'+import { createMcpHostLlmProviderAttemptRoutes } from './llmProviderAttempts.routes.js'import { createMcpHostPluginWorkloadSdkRoutes } from './plugin-workload-sdk.routes.js'import { createMcpHostRenewalRoutes } from './renewal/index.js'import { createUserApprovalRequestsRoutes } from './user-approval-requests.routes.js'@@ -16,6 +17,7 @@ export function createMcpHostRoutes(router.use(createUserApprovalRequestsRoutes(gateway, directRunAttributionBindingService))router.use(createMcpHostWorkflowRoutes(gateway))router.use(createMcpHostPluginWorkloadSdkRoutes())+ router.use(createMcpHostLlmProviderAttemptRoutes())router.use(createMcpHostHostsHeartbeatRoutes(gateway))return router}diff --git a/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts b/control-api/src/routes/mcp-host/llmProviderAttempts.routes.tsnew file mode 100644index 000000000..abc037e05--- /dev/null+++ b/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts@@ -0,0 +1,57 @@+import { type Request, type Response, Router } from 'express'+import { asyncHandler } from '../../http/asyncHandler.js'+import { requireMcpHostJwt } from '../../middleware/mcpHostJwtAuth.js'+import { rootLogger } from '../../observability/logger.js'+import {+ LlmProviderAttemptAuthorizeError,+ authorizeLlmProviderAttempt,+} from '../../services/llmProviderAttemptAuthorizer.js'++const log = rootLogger.child({ module: 'mcp-host-llm-provider-attempts' })++const ERROR_STATUS: Record<string, number> = {+ disabled: 404,+ insufficient_scope: 403,+ no_grant: 403,+ model_not_allowed: 403,+ budget_denied: 403,+ connection_unavailable: 503,+ host_binding_mismatch: 403,+ unknown_field: 400,+ invalid_request: 400,+ stale_generation: 409,+ idempotency_conflict: 409,+ provider_unavailable: 503,+}++function sendAuthorizeError(res: Response, err: unknown): void {+ if (err instanceof LlmProviderAttemptAuthorizeError) {+ const status = ERROR_STATUS[err.code] ?? 400+ log.warn({ event: 'codex_attempt_authorize_denied', code: err.code }, err.message)+ res.status(status).json({ error: err.code })+ return+ }+ throw err+}++export function createMcpHostLlmProviderAttemptRoutes(): Router {+ const router = Router()+ router.post(+ '/mcp-host/llm/provider-attempts/authorize',+ requireMcpHostJwt,+ asyncHandler(async (req: Request, res: Response) => {+ const claims = req.mcpHostJwt+ if (!claims) {+ res.status(401).json({ error: 'Unauthorized' })+ return+ }+ try {+ const result = await authorizeLlmProviderAttempt(claims, req.body)+ res.status(200).json(result)+ } catch (err) {+ sendAuthorizeError(res, err)+ }+ })+ )+ return router+}diff --git a/control-api/src/services/budgets/check.ts b/control-api/src/services/budgets/check.tsindex e2b1ca4ab..cd15359e1 100644--- a/control-api/src/services/budgets/check.ts+++ b/control-api/src/services/budgets/check.ts@@ -30,6 +30,7 @@ import { type TokenBudget, listBudgets, toNumber } from './definitions.js'import { type BudgetScopeDimension, scopeMatches } from './dimensions.js'import {type ReservationConnector,+ type ReservationTxClient,releaseReservation,reserveInDangerZone,} from './reservations.js'@@ -94,6 +95,13 @@ export type BudgetCheckMatched = {enforcement: string}+export type BudgetCheckOptions = {+ /** Codex attempts may only consume token budgets; a matching cost cap denies. */+ requiredUnit?: 'tokens'+ /** When set, danger-zone reservations join this already-open transaction. */+ transactionClient?: ReservationTxClient+}+export type BudgetCheckResult = {allowed: booleanreason?: string@@ -210,7 +218,8 @@ function normalize(value: string | null | undefined): string | null {export async function evaluateBudgetCheck(req: BudgetCheckRequest,db: DbClient = pool,- connector: ReservationConnector = pool+ connector: ReservationConnector = pool,+ options: BudgetCheckOptions = {}): Promise<BudgetCheckResult> {// 1. Resolve identity — team_id binding (SECURITY, §4.1).//@@ -308,6 +317,13 @@ export async function evaluateBudgetCheck(const unpricedByKey = new Map<string, UnpricedModel>()for (const budget of matching) {+ if (options.requiredUnit === 'tokens' && budget.unit !== 'tokens') {+ if (budget.enforcement === 'block' && budget.unit === 'cost') {+ allowed = false+ if (!reason) reason = 'cost_unit_rejected'+ }+ continue+ }let spent: numberlet remaining: numbertry {@@ -398,7 +414,8 @@ export async function evaluateBudgetCheck(// above and bound to claims.hostRefs[0] by the route's claim-binding.hostRef: dimensions.host_ref ?? null,},- connector+ connector,+ options.transactionClient)if (r.decision === 'deny') {// effective_remaining (incl. concurrent pending) < min_start → thediff --git a/control-api/src/services/budgets/reservations.ts b/control-api/src/services/budgets/reservations.tsindex 049b4c252..3155a879c 100644--- a/control-api/src/services/budgets/reservations.ts+++ b/control-api/src/services/budgets/reservations.ts@@ -36,9 +36,9 @@ import { toNumber } from './definitions.js'export const BUDGET_RESERVATION_TTL_SECONDS = config.budgetReservationTtlSeconds/** Minimal transaction client shape — pg's PoolClient satisfies it. */-type ReservationTxClient = {+export type ReservationTxClient = {query: (text: string, values?: unknown[]) => Promise<{ rows: unknown[]; rowCount: number | null }>- release: () => void+ release?: () => void}/** Minimal connector shape — pg's Pool satisfies it. */@@ -86,66 +86,22 @@ export type DangerZoneReserveResult =*/export async function reserveInDangerZone(input: DangerZoneReserveInput,- connector: ReservationConnector = pool+ connector: ReservationConnector = pool,+ existingClient?: ReservationTxClient): Promise<DangerZoneReserveResult> {+ if (existingClient) {+ return decideDangerZoneReservation(existingClient, input)+ }+const client = await connector.connect()let inTransaction = falsetry {await client.query('BEGIN')inTransaction = true-- // Serialize concurrent checks of THIS budget. xact-scoped: auto-released on- // COMMIT/ROLLBACK. hashtext(uuid::text) → int4, implicitly widened to the- // bigint single-arg overload of pg_advisory_xact_lock.- await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [input.budgetId])-- // Exclude THIS task's own still-active reservation from the pending sum. A- // retried check of the same in-flight task (same task_ref) would otherwise- // count its previous reservation as a concurrent competitor and over-deny.- // Only excludable when we have a task_ref to identify "self": with a null- // task_ref we cannot tell our own row from another anonymous task's, so we- // must NOT exclude (excluding all null-task rows would under-count → over-- // allow). `IS DISTINCT FROM` handles the null-safe comparison.- const pendingParams: unknown[] = [input.budgetId]- let selfExclusion = ''- if (input.taskRef) {- pendingParams.push(input.taskRef)- selfExclusion = ' AND task_ref IS DISTINCT FROM $2'- }- const pendingRes = await client.query(- `SELECT COALESCE(SUM(est_amount), 0) AS pending- FROM budget_pending_reservations- WHERE budget_id = $1 AND expires_at > NOW()${selfExclusion}`,- pendingParams- )- const pending = toNumber((pendingRes.rows[0] as { pending?: unknown } | undefined)?.pending)- const effectiveRemaining = input.limit - input.spent - pending-- if (effectiveRemaining < input.minStart) {- // Another in-flight task already consumed the headroom — deny without- // reserving. COMMIT (no writes) releases the advisory lock.- await client.query('COMMIT')- inTransaction = false- return { decision: 'deny' }- }-- const insertRes = await client.query(- `INSERT INTO budget_pending_reservations (budget_id, est_amount, task_ref, host_ref, expires_at)- VALUES ($1, $2, $3, $4, NOW() + ($5::int * INTERVAL '1 second'))- RETURNING id`,- [- input.budgetId,- input.estAmount,- input.taskRef,- input.hostRef,- BUDGET_RESERVATION_TTL_SECONDS,- ]- )+ const result = await decideDangerZoneReservation(client, input)await client.query('COMMIT')inTransaction = false-- const reservationId = String((insertRes.rows[0] as { id: unknown }).id)- return { decision: 'allow', reservationId }+ return result} catch (err) {if (inTransaction) {try {@@ -156,10 +112,60 @@ export async function reserveInDangerZone(}throw err} finally {- client.release()+ client.release?.()}}+async function decideDangerZoneReservation(+ client: ReservationTxClient,+ input: DangerZoneReserveInput+): Promise<DangerZoneReserveResult> {+ await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [input.budgetId])++ const pendingParams: unknown[] = [input.budgetId]+ let selfExclusion = ''+ if (input.taskRef) {+ pendingParams.push(input.taskRef)+ selfExclusion = ' AND task_ref IS DISTINCT FROM $2'+ }+ const pendingRes = await client.query(+ `SELECT COALESCE(SUM(est_amount), 0) AS pending+ FROM budget_pending_reservations+ WHERE budget_id = $1 AND expires_at > NOW()${selfExclusion}`,+ pendingParams+ )+ const pending = toNumber((pendingRes.rows[0] as { pending?: unknown } | undefined)?.pending)+ const effectiveRemaining = input.limit - input.spent - pending++ if (effectiveRemaining < input.minStart) {+ return { decision: 'deny' }+ }++ const insertRes = await client.query(+ `INSERT INTO budget_pending_reservations (budget_id, est_amount, task_ref, host_ref, expires_at)+ VALUES ($1, $2, $3, $4, NOW() + ($5::int * INTERVAL '1 second'))+ RETURNING id`,+ [input.budgetId, input.estAmount, input.taskRef, input.hostRef, BUDGET_RESERVATION_TTL_SECONDS]+ )+ const reservationId = String((insertRes.rows[0] as { id: unknown }).id)+ return { decision: 'allow', reservationId }+}++export async function getActiveReservation(+ db: { query: ReservationTxClient['query'] },+ input: { reservationId: string; hostRef: string }+): Promise<{ id: string } | null> {+ const result = await db.query(+ `SELECT id::text AS id+ FROM budget_pending_reservations+ WHERE id = $1 AND host_ref = $2 AND expires_at > NOW()+ LIMIT 1`,+ [input.reservationId, input.hostRef]+ )+ const row = result.rows[0] as { id?: unknown } | undefined+ return row?.id ? { id: String(row.id) } : null+}+export type ReleaseReservationInput = {reservationId?: string | nulltaskRef?: string | nulldiff --git a/control-api/src/services/llmProviderAttemptAuthorizer.ts b/control-api/src/services/llmProviderAttemptAuthorizer.tsnew file mode 100644index 000000000..964448d7b--- /dev/null+++ b/control-api/src/services/llmProviderAttemptAuthorizer.ts@@ -0,0 +1,407 @@+import { createHash } from 'node:crypto'+import {+ LIMITS,+ hashCodexCompletionRequestV1,+ parseCodexCompletionRequestV1,+} from '@clerum/llm-provider-attempt-contract'+import { config } from '../config.js'+import { type DbClient, pool, withTransaction } from '../db.js'+import { rootLogger } from '../observability/logger.js'+import type { McpHostAccessClaims } from '../utils/auth/mcpHostJwtToken.js'+import { isPlainObject } from '../utils/isPlainObject.js'+import { stableStringify } from '../utils/stableStringify.js'+import { evaluateBudgetCheck } from './budgets/check.js'+import { getActiveReservation } from './budgets/reservations.js'+import { getSafeCodexSubscriptionConnection } from './codexSubscriptionConnection.js'+import { getModelAllowlistState } from './llmAllowedModels.js'+import {+ getMaxLlmProviderAttemptGeneration,+ insertLlmProviderAttempt,+} from './llmProviderAttemptStore.js'+import { issueRegisteredCodexExecutionTicket } from './llmProviderAttemptTicket.js'++const log = rootLogger.child({ module: 'llm-provider-attempt-authorizer' })+const CODEX_EXECUTE_SCOPE = 'llm:codex:execute'+const PROVIDER = 'codex-subscription' as const++const AUTHORIZE_BODY_KEYS = new Set([+ 'request',+ 'invocationId',+ 'attemptGeneration',+ 'providerAttemptIndex',+ 'policyRevision',+ 'policyHash',+ 'requestHash',+ 'budgetReservationId',+ 'hostRef',+ 'recipeNamespace',+ 'recipeName',+ 'userId',+])++export type LlmProviderAttemptAuthorizeErrorCode =+ | 'disabled'+ | 'insufficient_scope'+ | 'no_grant'+ | 'model_not_allowed'+ | 'budget_denied'+ | 'connection_unavailable'+ | 'host_binding_mismatch'+ | 'unknown_field'+ | 'invalid_request'+ | 'stale_generation'+ | 'idempotency_conflict'+ | 'provider_unavailable'++export class LlmProviderAttemptAuthorizeError extends Error {+ constructor(+ readonly code: LlmProviderAttemptAuthorizeErrorCode,+ message: string+ ) {+ super(message)+ this.name = 'LlmProviderAttemptAuthorizeError'+ }+}++export type AuthorizeAttemptSuccess = {+ providerAttemptId: string+ requestHash: string+ executionTicket: string+ expiresAt: string+}++export type LlmProviderAttemptAuthorizerDeps = {+ enabled: boolean+ db: DbClient+ withTransaction: typeof withTransaction+ getConnection: typeof getSafeCodexSubscriptionConnection+ getModelState: typeof getModelAllowlistState+ evaluateBudget: typeof evaluateBudgetCheck+ getActiveReservation: typeof getActiveReservation+ getMaxGeneration: typeof getMaxLlmProviderAttemptGeneration+ insertAttempt: typeof insertLlmProviderAttempt+ issueTicket: typeof issueRegisteredCodexExecutionTicket+}++const defaultDeps = (): LlmProviderAttemptAuthorizerDeps => ({+ enabled: config.codexSubscriptionEnabled,+ db: { query: (text, values) => pool.query(text, values) },+ withTransaction,+ getConnection: getSafeCodexSubscriptionConnection,+ getModelState: getModelAllowlistState,+ evaluateBudget: evaluateBudgetCheck,+ getActiveReservation,+ getMaxGeneration: getMaxLlmProviderAttemptGeneration,+ insertAttempt: insertLlmProviderAttempt,+ issueTicket: issueRegisteredCodexExecutionTicket,+})++export function computeCodexPolicyHash(input: {+ model: string+ catalogRevision: number+ credentialRevision: number+}): string {+ return createHash('sha256')+ .update(+ stableStringify({+ catalogRevision: input.catalogRevision,+ credentialRevision: input.credentialRevision,+ model: input.model,+ provider: PROVIDER,+ })+ )+ .digest('hex')+}++function firstUnknownKey(body: Record<string, unknown>): string | null {+ for (const key of Object.keys(body)) {+ if (!AUTHORIZE_BODY_KEYS.has(key)) return key+ }+ return null+}++function resolveCaller(claims: McpHostAccessClaims): {+ callerKind: 'host' | 'recipe'+ hostRef: string+ recipeNamespace: string | null+ recipeName: string | null+} {+ const hostRef = claims.hostRefs[0]?.trim()+ if (!hostRef) {+ throw new LlmProviderAttemptAuthorizeError(+ 'insufficient_scope',+ 'mcp-host JWT missing canonical hostRefs[0] caller binding'+ )+ }+ const isRecipe = hostRef.includes('/')+ return {+ callerKind: isRecipe ? 'recipe' : 'host',+ hostRef,+ recipeNamespace: isRecipe ? claims.recipeNamespace : null,+ recipeName: isRecipe ? claims.recipeName : null,+ }+}++function assertClaimBinding(body: Record<string, unknown>, claims: McpHostAccessClaims): void {+ const caller = resolveCaller(claims)+ if (typeof body.hostRef === 'string' && body.hostRef.trim() !== caller.hostRef) {+ throw new LlmProviderAttemptAuthorizeError(+ 'host_binding_mismatch',+ 'body hostRef does not match the token caller'+ )+ }+ if (+ typeof body.recipeNamespace === 'string' &&+ body.recipeNamespace.trim() !== claims.recipeNamespace+ ) {+ throw new LlmProviderAttemptAuthorizeError(+ 'host_binding_mismatch',+ 'body recipeNamespace does not match the token caller'+ )+ }+ if (typeof body.recipeName === 'string' && body.recipeName.trim() !== claims.recipeName) {+ throw new LlmProviderAttemptAuthorizeError(+ 'host_binding_mismatch',+ 'body recipeName does not match the token caller'+ )+ }+ if (typeof body.userId === 'string' && body.userId.trim() !== claims.sub) {+ throw new LlmProviderAttemptAuthorizeError(+ 'host_binding_mismatch',+ 'body userId does not match the token caller'+ )+ }+}++export async function authorizeLlmProviderAttempt(+ claims: McpHostAccessClaims,+ body: unknown,+ deps: LlmProviderAttemptAuthorizerDeps = defaultDeps()+): Promise<AuthorizeAttemptSuccess> {+ if (!deps.enabled) {+ throw new LlmProviderAttemptAuthorizeError('disabled', 'Codex subscription is disabled')+ }+ if (!claims.workflowControlScopes.includes(CODEX_EXECUTE_SCOPE)) {+ throw new LlmProviderAttemptAuthorizeError(+ 'insufficient_scope',+ 'mcp-host JWT lacks the llm:codex:execute scope'+ )+ }+ if (!isPlainObject(body)) {+ throw new LlmProviderAttemptAuthorizeError('invalid_request', 'body must be an object')+ }+ const serialized = JSON.stringify(body)+ if (Buffer.byteLength(serialized, 'utf8') > LIMITS.maxRequestBodyBytes) {+ throw new LlmProviderAttemptAuthorizeError('invalid_request', 'request body exceeds the limit')+ }+ const unknown = firstUnknownKey(body)+ if (unknown) {+ throw new LlmProviderAttemptAuthorizeError('unknown_field', `unknown field '${unknown}'`)+ }++ const caller = resolveCaller(claims)+ assertClaimBinding(body, claims)++ const parsed = parseCodexCompletionRequestV1(body.request)+ if (!parsed.ok) {+ throw new LlmProviderAttemptAuthorizeError('invalid_request', parsed.message)+ }+ const request = parsed.value+ if (request.provider !== PROVIDER) {+ throw new LlmProviderAttemptAuthorizeError(+ 'model_not_allowed',+ 'provider must be codex-subscription'+ )+ }++ const invocationId = typeof body.invocationId === 'string' ? body.invocationId.trim() : ''+ const attemptGeneration =+ typeof body.attemptGeneration === 'number' ? body.attemptGeneration : NaN+ const providerAttemptIndex =+ typeof body.providerAttemptIndex === 'number' ? body.providerAttemptIndex : 1+ const policyRevision = typeof body.policyRevision === 'number' ? body.policyRevision : NaN+ const policyHash = typeof body.policyHash === 'string' ? body.policyHash : ''+ if (!invocationId || !Number.isInteger(attemptGeneration) || attemptGeneration < 1) {+ throw new LlmProviderAttemptAuthorizeError(+ 'invalid_request',+ 'invocationId and attemptGeneration are required'+ )+ }+ if (!Number.isInteger(providerAttemptIndex) || providerAttemptIndex < 1) {+ throw new LlmProviderAttemptAuthorizeError(+ 'invalid_request',+ 'providerAttemptIndex must be a positive integer'+ )+ }+ if (+ !Number.isInteger(policyRevision) ||+ policyRevision < 1 ||+ !/^[a-f0-9]{64}$/.test(policyHash)+ ) {+ throw new LlmProviderAttemptAuthorizeError(+ 'invalid_request',+ 'policyRevision and policyHash are required'+ )+ }++ const requestHash = hashCodexCompletionRequestV1(request)+ if (typeof body.requestHash === 'string' && body.requestHash !== requestHash) {+ throw new LlmProviderAttemptAuthorizeError(+ 'invalid_request',+ 'requestHash does not match the canonical request'+ )+ }++ return deps.withTransaction(async tx => {+ const db: DbClient = tx+ const connection = await deps.getConnection(db)+ if (+ !connection ||+ connection.status !== 'connected' ||+ connection.revokedAt ||+ connection.catalogStatus === 'auth-rejected'+ ) {+ throw new LlmProviderAttemptAuthorizeError(+ 'connection_unavailable',+ 'Codex subscription connection is not usable'+ )+ }+ if (connection.catalogStatus === 'unavailable' || connection.catalogStatus === 'never_synced') {+ throw new LlmProviderAttemptAuthorizeError(+ 'connection_unavailable',+ 'Codex subscription catalog is not ready'+ )+ }++ const modelState = await deps.getModelState(PROVIDER, request.model, db)+ if (!modelState || !modelState.enabled || modelState.stale) {+ throw new LlmProviderAttemptAuthorizeError(+ 'model_not_allowed',+ 'model is disabled, stale, or absent from the Codex catalog'+ )+ }++ const expectedPolicyHash = computeCodexPolicyHash({+ model: request.model,+ catalogRevision: connection.catalogRevision,+ credentialRevision: connection.credentialRevision,+ })+ if (policyRevision !== connection.catalogRevision || policyHash !== expectedPolicyHash) {+ throw new LlmProviderAttemptAuthorizeError(+ 'no_grant',+ 'policy revision or hash does not match the current Codex catalog'+ )+ }++ const maxGeneration = await deps.getMaxGeneration(db, invocationId)+ if (attemptGeneration < maxGeneration) {+ throw new LlmProviderAttemptAuthorizeError(+ 'stale_generation',+ 'attemptGeneration is older than the recorded invocation'+ )+ }++ const presentedReservationId =+ typeof body.budgetReservationId === 'string' ? body.budgetReservationId.trim() : ''+ if (presentedReservationId) {+ const active = await deps.getActiveReservation(db, {+ reservationId: presentedReservationId,+ hostRef: caller.hostRef,+ })+ if (!active) {+ throw new LlmProviderAttemptAuthorizeError(+ 'budget_denied',+ 'budget reservation is missing or expired'+ )+ }+ }++ const budget = await deps.evaluateBudget(+ {+ host_ref: caller.hostRef,+ context_ref: null,+ team_id: null,+ user_id: null,+ provider: PROVIDER,+ model: request.model,+ llm_secret_name: null,+ source_kind: caller.callerKind === 'recipe' ? 'workflow' : 'channel',+ recipe_name: caller.recipeName,+ cron_job_id: null,+ task_ref: invocationId,+ },+ db,+ { connect: async () => tx as never },+ { requiredUnit: 'tokens', transactionClient: tx }+ )+ if (!budget.allowed) {+ throw new LlmProviderAttemptAuthorizeError(+ 'budget_denied',+ budget.reason === 'cost_unit_rejected'+ ? 'Codex attempts reject cost-unit budgets'+ : 'token budget denied this attempt'+ )+ }++ const budgetReservationId =+ budget.reservationIds?.[0] ?? (presentedReservationId || 'unbudgeted')++ try {+ const attempt = await deps.insertAttempt(db, {+ callerKind: caller.callerKind,+ hostRef: caller.hostRef,+ recipeNamespace: caller.recipeNamespace,+ recipeName: caller.recipeName,+ invocationId,+ attemptGeneration,+ providerAttemptIndex,+ model: request.model,+ requestHash,+ policyRevision,+ policyHash,+ budgetReservationId,+ connectionRevision: connection.credentialRevision,+ })+ const issued = await deps.issueTicket(db, {+ sub: claims.sub,+ hostRef: caller.hostRef,+ recipeNamespace: caller.recipeNamespace ?? undefined,+ recipeName: caller.recipeName ?? undefined,+ invocationId,+ attemptGeneration,+ providerAttemptId: attempt.id,+ providerAttemptIndex,+ model: request.model,+ requestHash,+ policyRevision,+ policyHash,+ budgetReservationId,+ connectionRevision: connection.credentialRevision,+ })+ log.info(+ {+ event: 'codex_attempt_authorized',+ providerAttemptId: attempt.id,+ hostRef: caller.hostRef,+ model: request.model,+ },+ 'authorized Codex provider attempt'+ )+ return {+ providerAttemptId: attempt.id,+ requestHash,+ executionTicket: issued.executionTicket,+ expiresAt: issued.expiresAt.toISOString(),+ }+ } catch (err) {+ const code = (err as { code?: string }).code+ if (code === '23505') {+ throw new LlmProviderAttemptAuthorizeError(+ 'idempotency_conflict',+ 'an attempt with this invocation binding already exists'+ )+ }+ throw err+ }+ })+}diff --git a/control-api/src/services/llmProviderAttemptStore.ts b/control-api/src/services/llmProviderAttemptStore.tsindex 9c0a3fadb..42cd76daa 100644--- a/control-api/src/services/llmProviderAttemptStore.ts+++ b/control-api/src/services/llmProviderAttemptStore.ts@@ -166,3 +166,16 @@ export async function registerLlmProviderAttemptTicket([input.jti, input.providerAttemptId, input.expiresAt])}++export async function getMaxLlmProviderAttemptGeneration(+ db: DbClient,+ invocationId: string+): Promise<number> {+ const result = await db.query(+ `SELECT COALESCE(MAX(attempt_generation), 0) AS max_generation+ FROM llm_provider_attempts+ WHERE invocation_id = $1`,+ [invocationId]+ )+ return Number((result.rows[0] as { max_generation?: unknown } | undefined)?.max_generation ?? 0)+}diff --git a/control-api/src/utils/auth/mcpHostJwtToken.ts b/control-api/src/utils/auth/mcpHostJwtToken.tsindex e3f28922a..12bfb61b3 100644--- a/control-api/src/utils/auth/mcpHostJwtToken.ts+++ b/control-api/src/utils/auth/mcpHostJwtToken.ts@@ -173,6 +173,9 @@ export const ALL_MCP_HOST_CONTROL_SCOPES = [// (status.pluginWorkloadSdk) declares the SDK; SDK routes reject access// tokens without it via scope_denied.'plugin-workload-sdk',+ // Derive-only Codex execution. HCC/WRC may request this after projecting an+ // eligible broker target. Never add it to user-declarable Host/Recipe CRD fields.+ 'llm:codex:execute',] as constexport type McpHostControlScope = (typeof ALL_MCP_HOST_CONTROL_SCOPES)[number]diff --git a/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts b/control-api/test/routes.mcp-host.llmProviderAttempts.test.tsnew file mode 100644index 000000000..4f5c70825--- /dev/null+++ b/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts@@ -0,0 +1,110 @@+import { beforeEach, describe, expect, it, vi } from 'vitest'+import express from 'express'+import request from 'supertest'+import { createMcpHostLlmProviderAttemptRoutes } from '../src/routes/mcp-host/llmProviderAttempts.routes.js'+import { LlmProviderAttemptAuthorizeError } from '../src/services/llmProviderAttemptAuthorizer.js'+import * as authorizer from '../src/services/llmProviderAttemptAuthorizer.js'+import * as mcpHostJwt from '../src/utils/auth/mcpHostJwtToken.js'++vi.mock('../src/services/llmProviderAttemptAuthorizer.js', async () => {+ const actual = await vi.importActual<+ typeof import('../src/services/llmProviderAttemptAuthorizer.js')+ >('../src/services/llmProviderAttemptAuthorizer.js')+ return {+ ...actual,+ authorizeLlmProviderAttempt: vi.fn(),+ }+})++const NS = 'default'+const HOST = 'research-host'++function buildApp() {+ const app = express()+ app.use(express.json({ limit: '1mb' }))+ const api = express.Router()+ api.use(createMcpHostLlmProviderAttemptRoutes())+ app.use('/api/v1', api)+ return app+}++function token(scopes: mcpHostJwt.McpHostControlScope[] = ['llm:codex:execute']) {+ return mcpHostJwt.issueMcpHostAccessJwt(NS, HOST, [HOST], {+ workflowControlScopes: scopes,+ }).token+}++describe('POST /api/v1/mcp-host/llm/provider-attempts/authorize', () => {+ beforeEach(() => {+ vi.mocked(authorizer.authorizeLlmProviderAttempt).mockReset()+ })++ it('returns 401 for a missing or invalid JWT', async () => {+ const app = buildApp()+ const missing = await request(app)+ .post('/api/v1/mcp-host/llm/provider-attempts/authorize')+ .send({ request: {} })+ expect(missing.status).toBe(401)+ const invalid = await request(app)+ .post('/api/v1/mcp-host/llm/provider-attempts/authorize')+ .set('Authorization', 'Bearer not-a-jwt')+ .send({ request: {} })+ expect(invalid.status).toBe(401)+ expect(authorizer.authorizeLlmProviderAttempt).not.toHaveBeenCalled()+ })++ it('maps authorizer taxonomy without collapsing it into 500', async () => {+ const app = buildApp()+ vi.mocked(authorizer.authorizeLlmProviderAttempt).mockRejectedValueOnce(+ new LlmProviderAttemptAuthorizeError('disabled', 'off')+ )+ const disabled = await request(app)+ .post('/api/v1/mcp-host/llm/provider-attempts/authorize')+ .set('Authorization', `Bearer ${token()}`)+ .send({ request: {} })+ expect(disabled.status).toBe(404)+ expect(disabled.body).toEqual({ error: 'disabled' })++ vi.mocked(authorizer.authorizeLlmProviderAttempt).mockRejectedValueOnce(+ new LlmProviderAttemptAuthorizeError('insufficient_scope', 'no scope')+ )+ const scope = await request(app)+ .post('/api/v1/mcp-host/llm/provider-attempts/authorize')+ .set('Authorization', `Bearer ${token()}`)+ .send({ request: {} })+ expect(scope.status).toBe(403)+ expect(scope.body).toEqual({ error: 'insufficient_scope' })++ vi.mocked(authorizer.authorizeLlmProviderAttempt).mockRejectedValueOnce(+ new LlmProviderAttemptAuthorizeError('budget_denied', 'tokens')+ )+ const budget = await request(app)+ .post('/api/v1/mcp-host/llm/provider-attempts/authorize')+ .set('Authorization', `Bearer ${token()}`)+ .send({ request: {} })+ expect(budget.status).toBe(403)+ expect(budget.body).toEqual({ error: 'budget_denied' })+ })++ it('returns the authorize contract without leaking tokens', async () => {+ const app = buildApp()+ vi.mocked(authorizer.authorizeLlmProviderAttempt).mockResolvedValueOnce({+ providerAttemptId: '33333333-3333-4333-8333-333333333333',+ requestHash: 'a'.repeat(64),+ executionTicket: 'ticket.jwt',+ expiresAt: '2026-08-20T12:00:00.000Z',+ })+ const res = await request(app)+ .post('/api/v1/mcp-host/llm/provider-attempts/authorize')+ .set('Authorization', `Bearer ${token()}`)+ .send({ request: { schemaVersion: 'codex-completion-request.v1' } })+ expect(res.status).toBe(200)+ expect(res.body).toEqual({+ providerAttemptId: '33333333-3333-4333-8333-333333333333',+ requestHash: 'a'.repeat(64),+ executionTicket: 'ticket.jwt',+ expiresAt: '2026-08-20T12:00:00.000Z',+ })+ expect(JSON.stringify(res.body)).not.toMatch(/refresh|access_token|Authorization/i)+ })+})diff --git a/control-api/test/services.llmProviderAttemptAuthorization.realPostgres.integration.test.ts b/control-api/test/services.llmProviderAttemptAuthorization.realPostgres.integration.test.tsnew file mode 100644index 000000000..6eabaf7d5--- /dev/null+++ b/control-api/test/services.llmProviderAttemptAuthorization.realPostgres.integration.test.ts@@ -0,0 +1,217 @@+import { afterAll, beforeAll, describe, expect, it } from 'vitest'+import { randomBytes, randomUUID } from 'node:crypto'+import { Pool } from 'pg'+import { initDb } from '../src/db.js'+import { deriveOAuthEncryptionKey } from '../src/oauth/encryption.js'+import { evaluateBudgetCheck } from '../src/services/budgets/check.js'+import { getActiveReservation } from '../src/services/budgets/reservations.js'+import {+ getSafeCodexSubscriptionConnection,+ insertInitialCodexSubscriptionConnection,+ recordCodexCatalogOutcome,+} from '../src/services/codexSubscriptionConnection.js'+import { getModelAllowlistState } from '../src/services/llmAllowedModels.js'+import {+ type LlmProviderAttemptAuthorizerDeps,+ authorizeLlmProviderAttempt,+ computeCodexPolicyHash,+} from '../src/services/llmProviderAttemptAuthorizer.js'+import {+ getMaxLlmProviderAttemptGeneration,+ insertLlmProviderAttempt,+} from '../src/services/llmProviderAttemptStore.js'+import { issueRegisteredCodexExecutionTicket } from '../src/services/llmProviderAttemptTicket.js'+import type { McpHostAccessClaims } from '../src/utils/auth/mcpHostJwtToken.js'++const adminUrl = process.env.CONTROL_API_REAL_PG_ADMIN_URL+const describeRealPostgres = adminUrl ? describe : describe.skip+const KEY = deriveOAuthEncryptionKey('ab'.repeat(32))++function databaseUrl(baseUrl: string, database: string): string {+ const url = new URL(baseUrl)+ url.pathname = `/${database}`+ return url.toString()+}++function quoteIdent(value: string): string {+ return `"${value.replace(/"/g, '""')}"`+}++const REQUEST = {+ schemaVersion: 'codex-completion-request.v1' as const,+ requestId: 'req-pg-1',+ idempotencyKey: 'idem-pg-1',+ provider: 'codex-subscription' as const,+ model: 'gpt-5.1',+ messages: [{ role: 'user' as const, content: 'hello from postgres' }],+}++function claims(): McpHostAccessClaims {+ return {+ sub: 'default/research-host',+ recipeNamespace: 'default',+ recipeName: 'research-host',+ hostRefs: ['research-host'],+ scope: 'workflow:approval:request',+ workflowControlScopes: ['llm:codex:execute'],+ iss: 'control-api',+ aud: 'workflow-approvals',+ jti: randomUUID(),+ exp: Math.floor(Date.now() / 1000) + 60,+ }+}++describeRealPostgres('Codex provider-attempt authorization on real PostgreSQL', () => {+ const database = `llm_attempt_authz_${randomBytes(6).toString('hex')}`+ const connectionString = databaseUrl(+ adminUrl ?? 'postgresql://[email protected]/postgres',+ database+ )+ let adminPool: Pool+ let pool: Pool++ function dbClient() {+ return { query: (text: string, values?: unknown[]) => pool.query(text, values) }+ }++ function testDeps(+ overrides: Partial<LlmProviderAttemptAuthorizerDeps> = {}+ ): LlmProviderAttemptAuthorizerDeps {+ const db = dbClient()+ return {+ enabled: true,+ db,+ withTransaction: async work => {+ const client = await pool.connect()+ try {+ await client.query('BEGIN')+ const result = await work(client as never)+ await client.query('COMMIT')+ return result+ } catch (error) {+ try {+ await client.query('ROLLBACK')+ } catch {+ // keep the original error+ }+ throw error+ } finally {+ client.release()+ }+ },+ getConnection: getSafeCodexSubscriptionConnection,+ getModelState: getModelAllowlistState,+ evaluateBudget: evaluateBudgetCheck,+ getActiveReservation,+ getMaxGeneration: getMaxLlmProviderAttemptGeneration,+ insertAttempt: insertLlmProviderAttempt,+ issueTicket: issueRegisteredCodexExecutionTicket,+ ...overrides,+ }+ }++ beforeAll(async () => {+ adminPool = new Pool({ connectionString: adminUrl })+ await adminPool.query(`CREATE DATABASE ${quoteIdent(database)}`)+ pool = new Pool({ connectionString })+ await initDb({ connect: () => pool.connect() })+ await insertInitialCodexSubscriptionConnection(pool, KEY, {+ refreshToken: 'refresh-authz',+ accountFingerprint: 'fp-authz',+ })+ await recordCodexCatalogOutcome(pool, {+ catalogStatus: 'ready',+ expectedCredentialRevision: 1,+ expectedCatalogRevision: 0,+ })+ await pool.query(+ `INSERT INTO llm_allowed_models (provider, model, enabled, source, stale)+ VALUES ('codex-subscription', 'gpt-5.1', true, 'discovery', false)`+ )+ }, 60_000)++ afterAll(async () => {+ await pool?.end()+ if (adminPool) {+ await adminPool+ .query(`DROP DATABASE IF EXISTS ${quoteIdent(database)}`)+ .catch(() => undefined)+ await adminPool.end()+ }+ })++ it('lets only one concurrent authorization win for the same invocation binding', async () => {+ const current = await getSafeCodexSubscriptionConnection(pool)+ expect(current?.status).toBe('connected')+ const payload = {+ request: REQUEST,+ invocationId: `invocation-${randomUUID()}`,+ attemptGeneration: 1,+ providerAttemptIndex: 1,+ policyRevision: current!.catalogRevision,+ policyHash: computeCodexPolicyHash({+ model: REQUEST.model,+ catalogRevision: current!.catalogRevision,+ credentialRevision: current!.credentialRevision,+ }),+ }+ const deps = testDeps()+ const [first, second] = await Promise.allSettled([+ authorizeLlmProviderAttempt(claims(), payload, deps),+ authorizeLlmProviderAttempt(claims(), payload, deps),+ ])+ const wins = [first, second].filter(result => result.status === 'fulfilled')+ const losses = [first, second].filter(result => result.status === 'rejected')+ expect(wins).toHaveLength(1)+ expect(losses).toHaveLength(1)+ if (losses[0]?.status === 'rejected') {+ expect((losses[0].reason as { code?: string }).code).toBe('idempotency_conflict')+ }++ const count = await pool.query<{ count: string }>(+ `SELECT COUNT(*)::text AS count+ FROM llm_provider_attempts+ WHERE invocation_id = $1`,+ [payload.invocationId]+ )+ expect(count.rows[0]?.count).toBe('1')+ expect(JSON.stringify(wins[0])).not.toContain('hello from postgres')+ })++ it('rolls budget reservation, attempt, and ticket back together when ticket issue fails', async () => {+ const current = await getSafeCodexSubscriptionConnection(pool)+ const invocationId = `invocation-rollback-${randomUUID()}`+ const payload = {+ request: { ...REQUEST, requestId: 'req-pg-2', idempotencyKey: 'idem-pg-2' },+ invocationId,+ attemptGeneration: 1,+ providerAttemptIndex: 1,+ policyRevision: current!.catalogRevision,+ policyHash: computeCodexPolicyHash({+ model: REQUEST.model,+ catalogRevision: current!.catalogRevision,+ credentialRevision: current!.credentialRevision,+ }),+ }++ await expect(+ authorizeLlmProviderAttempt(+ claims(),+ payload,+ testDeps({+ issueTicket: async () => {+ throw new Error('ticket registration failed')+ },+ })+ )+ ).rejects.toThrow(/ticket registration failed/)++ const leftover = await pool.query<{ count: string }>(+ `SELECT COUNT(*)::text AS count+ FROM llm_provider_attempts+ WHERE invocation_id = $1`,+ [invocationId]+ )+ expect(leftover.rows[0]?.count).toBe('0')+ })+})diff --git a/control-api/test/services.llmProviderAttemptAuthorizer.test.ts b/control-api/test/services.llmProviderAttemptAuthorizer.test.tsnew file mode 100644index 000000000..bd7103cf7--- /dev/null+++ b/control-api/test/services.llmProviderAttemptAuthorizer.test.ts@@ -0,0 +1,234 @@+import { beforeEach, describe, expect, it, vi } from 'vitest'+import { hashCodexCompletionRequestV1 } from '@clerum/llm-provider-attempt-contract'+import {+ LlmProviderAttemptAuthorizeError,+ type LlmProviderAttemptAuthorizerDeps,+ authorizeLlmProviderAttempt,+ computeCodexPolicyHash,+} from '../src/services/llmProviderAttemptAuthorizer.js'+import type { McpHostAccessClaims } from '../src/utils/auth/mcpHostJwtToken.js'++const REQUEST = {+ schemaVersion: 'codex-completion-request.v1' as const,+ requestId: 'req-001',+ idempotencyKey: 'idem-001',+ provider: 'codex-subscription' as const,+ model: 'gpt-5.1',+ messages: [{ role: 'user' as const, content: 'hello' }],+}++function claims(overrides: Partial<McpHostAccessClaims> = {}): McpHostAccessClaims {+ return {+ sub: 'default/research-host',+ recipeNamespace: 'default',+ recipeName: 'research-host',+ hostRefs: ['research-host'],+ scope: 'workflow:approval:request',+ workflowControlScopes: ['llm:codex:execute'],+ iss: 'control-api',+ aud: 'workflow-approvals',+ jti: 'jti-1',+ exp: Math.floor(Date.now() / 1000) + 60,+ ...overrides,+ }+}++function connection(overrides: Record<string, unknown> = {}) {+ return {+ connectionKey: 'deployment-default',+ status: 'connected',+ credentialRevision: 3,+ catalogRevision: 4,+ accountFingerprint: 'fp',+ catalogStatus: 'ready',+ catalogSyncedAt: new Date(),+ lastRefreshAt: null,+ lastAuthAt: new Date(),+ refreshLockHeld: false,+ revokedAt: null,+ createdAt: new Date(),+ updatedAt: new Date(),+ ...overrides,+ }+}++function body(overrides: Record<string, unknown> = {}) {+ const policyHash = computeCodexPolicyHash({+ model: REQUEST.model,+ catalogRevision: 4,+ credentialRevision: 3,+ })+ return {+ request: REQUEST,+ invocationId: 'invocation-1',+ attemptGeneration: 1,+ providerAttemptIndex: 1,+ policyRevision: 4,+ policyHash,+ ...overrides,+ }+}++function deps(+ overrides: Partial<LlmProviderAttemptAuthorizerDeps> = {}+): LlmProviderAttemptAuthorizerDeps {+ const db = { query: vi.fn() }+ return {+ enabled: true,+ db,+ withTransaction: async work => work(db as never),+ getConnection: vi.fn().mockResolvedValue(connection()),+ getModelState: vi.fn().mockResolvedValue({ enabled: true, stale: false }),+ evaluateBudget: vi.fn().mockResolvedValue({ allowed: true, reservationIds: ['res-1'] }),+ getActiveReservation: vi.fn().mockResolvedValue({ id: 'res-1' }),+ getMaxGeneration: vi.fn().mockResolvedValue(0),+ insertAttempt: vi.fn().mockResolvedValue({+ id: '33333333-3333-4333-8333-333333333333',+ hostRef: 'research-host',+ }),+ issueTicket: vi.fn().mockResolvedValue({+ executionTicket: 'ticket.jwt',+ expiresAt: new Date('2026-08-20T12:00:00.000Z'),+ claims: { jti: 'jti-ticket' },+ }),+ ...overrides,+ }+}++describe('authorizeLlmProviderAttempt', () => {+ let current: LlmProviderAttemptAuthorizerDeps++ beforeEach(() => {+ current = deps()+ })++ it('authorizes a bound attempt and returns a ticket without persisting messages', async () => {+ const result = await authorizeLlmProviderAttempt(claims(), body(), current)+ expect(result).toMatchObject({+ providerAttemptId: '33333333-3333-4333-8333-333333333333',+ executionTicket: 'ticket.jwt',+ requestHash: hashCodexCompletionRequestV1(REQUEST),+ })+ expect(current.insertAttempt).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({+ hostRef: 'research-host',+ model: 'gpt-5.1',+ requestHash: result.requestHash,+ budgetReservationId: 'res-1',+ })+ )+ const persisted = vi.mocked(current.insertAttempt).mock.calls[0]?.[1]+ expect(JSON.stringify(persisted)).not.toContain('hello')+ expect(JSON.stringify(result)).not.toMatch(/sk-|refresh|Authorization/i)+ })++ it('uses claims.hostRefs[0] even when the body carries a different hostRef', async () => {+ await expect(+ authorizeLlmProviderAttempt(claims(), body({ hostRef: 'forged-host' }), current)+ ).rejects.toMatchObject({ code: 'host_binding_mismatch' })+ expect(current.insertAttempt).not.toHaveBeenCalled()+ })++ it('rejects a token without llm:codex:execute as insufficient_scope', async () => {+ await expect(+ authorizeLlmProviderAttempt(claims({ workflowControlScopes: [] }), body(), current)+ ).rejects.toMatchObject({ code: 'insufficient_scope' })+ })++ it('rejects a missing hostRefs[0] binding', async () => {+ await expect(+ authorizeLlmProviderAttempt(claims({ hostRefs: [] }), body(), {+ ...current,+ enabled: true,+ })+ ).rejects.toBeInstanceOf(LlmProviderAttemptAuthorizeError)+ })++ it('rejects unknown fields', async () => {+ await expect(+ authorizeLlmProviderAttempt(claims(), body({ extra: true }), current)+ ).rejects.toMatchObject({ code: 'unknown_field' })+ })++ it('rejects a stale requestHash', async () => {+ await expect(+ authorizeLlmProviderAttempt(claims(), body({ requestHash: 'a'.repeat(64) }), current)+ ).rejects.toMatchObject({ code: 'invalid_request' })+ })++ it('rejects disconnected and reauth connections as connection_unavailable', async () => {+ vi.mocked(current.getConnection).mockResolvedValueOnce(+ connection({ status: 'disconnected' }) as never+ )+ await expect(authorizeLlmProviderAttempt(claims(), body(), current)).rejects.toMatchObject({+ code: 'connection_unavailable',+ })+ vi.mocked(current.getConnection).mockResolvedValueOnce(+ connection({ status: 'reauth_required' }) as never+ )+ await expect(authorizeLlmProviderAttempt(claims(), body(), current)).rejects.toMatchObject({+ code: 'connection_unavailable',+ })+ })++ it('rejects a disabled or stale Codex model as model_not_allowed', async () => {+ vi.mocked(current.getModelState).mockResolvedValueOnce({ enabled: false, stale: false })+ await expect(authorizeLlmProviderAttempt(claims(), body(), current)).rejects.toMatchObject({+ code: 'model_not_allowed',+ })+ vi.mocked(current.getModelState).mockResolvedValueOnce({ enabled: true, stale: true })+ await expect(authorizeLlmProviderAttempt(claims(), body(), current)).rejects.toMatchObject({+ code: 'model_not_allowed',+ })+ })++ it('rejects an old policy revision/hash as no_grant', async () => {+ await expect(+ authorizeLlmProviderAttempt(claims(), body({ policyRevision: 1 }), current)+ ).rejects.toMatchObject({ code: 'no_grant' })+ })++ it('rejects a cost-unit budget as budget_denied', async () => {+ vi.mocked(current.evaluateBudget).mockResolvedValueOnce({+ allowed: false,+ reason: 'cost_unit_rejected',+ })+ await expect(authorizeLlmProviderAttempt(claims(), body(), current)).rejects.toMatchObject({+ code: 'budget_denied',+ })+ })++ it('rejects an expired presented reservation as budget_denied', async () => {+ vi.mocked(current.getActiveReservation).mockResolvedValueOnce(null)+ await expect(+ authorizeLlmProviderAttempt(claims(), body({ budgetReservationId: 'stale-res' }), current)+ ).rejects.toMatchObject({ code: 'budget_denied' })+ })++ it('rejects an older invocation generation', async () => {+ vi.mocked(current.getMaxGeneration).mockResolvedValueOnce(3)+ await expect(authorizeLlmProviderAttempt(claims(), body(), current)).rejects.toMatchObject({+ code: 'stale_generation',+ })+ })++ it('rejects a non-Codex provider as model_not_allowed', async () => {+ await expect(+ authorizeLlmProviderAttempt(+ claims(),+ body({+ request: { ...REQUEST, provider: 'openai' },+ }),+ current+ )+ ).rejects.toMatchObject({ code: 'invalid_request' })+ })++ it('is disabled when the feature flag is off', async () => {+ await expect(+ authorizeLlmProviderAttempt(claims(), body(), { ...current, enabled: false })+ ).rejects.toMatchObject({ code: 'disabled' })+ expect(current.insertAttempt).not.toHaveBeenCalled()+ })+})