Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import {
LIMITS as GROK_LIMITS,
buildGrokProxyEnvelope,
computeGrokPolicyHash,
requestBodyLimitBytes as grokRequestBodyLimitBytes,
hashGrokCompletionRequest,
measureNonImageAuthorizeBytes as measureGrokNonImageAuthorizeBytes,
parseGrokCompletionRequest,
} from '@clerum/grok-provider-attempt-contract'
import {
ENVELOPE_ALLOWANCE_BYTES,
LIMITS,
buildCodexProxyEnvelope,
computeCodexPolicyHash,
hashCodexCompletionRequest,
isBoundedId,
measureNonImageAuthorizeBytes,
parseCodexCompletionRequest,
requestBodyLimitBytes,
} 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 { evaluateBudgetCheck } from './budgets/check.js'
import { getActiveReservation } from './budgets/reservations.js'
import { getCodexCatalogModelState } from './codexSubscriptionCatalog.js'
import {
CODEX_UNASSIGNED_CONNECTION_KEY,
getSafeCodexSubscriptionConnection,
isCodexUnassignedConnectionKey,
} from './codexSubscriptionConnection.js'
import { issueRegisteredGrokExecutionTicket } from './grokProviderAttemptTicket.js'
import { getGrokCatalogModelState } from './grokSubscriptionCatalog.js'
import {
GROK_RESERVED_DEPLOYMENT_DEFAULT_KEY,
GROK_UNASSIGNED_CONNECTION_KEY,
getSafeGrokSubscriptionConnection,
isGrokUnassignedConnectionKey,
} from './grokSubscriptionConnection.js'
import {
CODEX_ATTEMPT_RESERVATION_TTL_SECONDS,
GROK_ATTEMPT_RESERVATION_TTL_SECONDS,
} from './llmProviderAttemptEnvelope.js'
import {
getMaxLlmProviderAttemptGeneration,
insertLlmProviderAttempt,
} from './llmProviderAttemptStore.js'
import { issueRegisteredCodexExecutionTicket } from './llmProviderAttemptTicket.js'
import {
getPluginWorkloadSdkProviderAttemptForUpdate,
lockPluginWorkloadSdkRecipe,
pluginWorkloadSdkSpendOutcomeExists,
promoteReservedOauthBrokerProviderAttempt,
} from './pluginWorkloadSdkDb.js'
import {
attestLiveBrokerTarget,
attestRequestedBrokerProvider,
readSubscriptionConnectionRef,
} from './subscriptionGrantIdentity.js'
const log = rootLogger.child({ module: 'llm-provider-attempt-authorizer' })
const CODEX_EXECUTE_SCOPE = 'llm:codex:execute'
const GROK_EXECUTE_SCOPE = 'llm:grok:execute'
const PROVIDER = 'codex-subscription' as const
const GROK_PROVIDER = 'grok-subscription' as const
const AUTHORIZE_BODY_KEYS = new Set([
'request',
'invocationId',
'attemptGeneration',
'providerAttemptIndex',
'policyRevision',
'policyHash',
'requestHash',
'budgetReservationId',
'hostRef',
'recipeNamespace',
'recipeName',
'userId',
'pluginWorkloadSdkProviderAttemptId',
'targetRef',
])
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
export type LlmProviderAttemptAuthorizeErrorCode =
| 'disabled'
| 'insufficient_scope'
| 'no_grant'
| 'model_not_allowed'
| 'budget_denied'
| 'connection_unavailable'
| 'unassigned_connection'
| 'host_binding_mismatch'
| 'unknown_field'
| 'invalid_request'
| 'payload_too_large'
| 'stale_generation'
| 'idempotency_conflict'
| 'provider_unavailable'
| 'authorize_timeout'
| 'authorize_aborted'
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
signal?: AbortSignal
db: DbClient
withTransaction: typeof withTransaction
getConnection: typeof getSafeCodexSubscriptionConnection
getModelState: typeof getCodexCatalogModelState
/**
* Live oauth-broker targets on the Host/recipe. Required: a missing
* assignment must not fall back to `request.provider` (that made D6 a no-op).
*/
resolveAssignment: (
hostRef: string,
signal?: AbortSignal
) => Promise<{
liveBrokerProviders: string[]
liveConnectionRef: string
annotations?: Record<string, string>
}>
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: getCodexCatalogModelState,
resolveAssignment: async () => ({
liveBrokerProviders: [],
liveConnectionRef: CODEX_UNASSIGNED_CONNECTION_KEY,
}),
evaluateBudget: evaluateBudgetCheck,
getActiveReservation,
getMaxGeneration: getMaxLlmProviderAttemptGeneration,
insertAttempt: insertLlmProviderAttempt,
issueTicket: issueRegisteredCodexExecutionTicket,
})
export { computeCodexPolicyHash }
// body > request > messages[] > message > toolCalls[] > call > arguments: the
// deepest free-form tree the contracts accept sits six containers below the
// body root, and may itself nest maxNestingDepth containers.
const MAX_AUTHORIZE_BODY_DEPTH = Math.max(LIMITS.maxNestingDepth, GROK_LIMITS.maxNestingDepth) + 6
/**
* #731 — room for the authorize envelope around the contract-capped `request`:
* ids, revisions, hashes and recipe names, a few hundred bytes in practice.
* The whole-body check bounds serialization cost before parsing; the request
* itself is held to maxRequestBodyBytes by the contract parser, so a request
* at the cap is never refused for its envelope. The gateway's
* client_max_body_size on this route is the larger of the cap plus this
* allowance and the V2 visual envelope (#660). The contract owns the value,
* shared with both proxies and mcp-host; the Grok contract exports the same
* one.
*/
export const AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES = ENVELOPE_ALLOWANCE_BYTES
/**
* Reject an over-deep body before anything serializes it, including direct
* service calls that do not pass through the route's raw-body scan. Iterative,
* so attacker-controlled nesting cannot turn a refusal into a RangeError/500.
*/
function assertBodyNestingWithinLimit(body: Record<string, unknown>): void {
const stack: Array<[unknown, number]> = [[body, 1]]
while (stack.length > 0) {
const [node, depth] = stack.pop()!
if (depth > MAX_AUTHORIZE_BODY_DEPTH) {
throw new LlmProviderAttemptAuthorizeError(
'invalid_request',
'request body exceeds the maximum nesting depth'
)
}
const children = Array.isArray(node) ? node : Object.values(node as Record<string, unknown>)
for (const child of children) {
if (child !== null && typeof child === 'object') stack.push([child, depth + 1])
}
}
}
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'
)
}
}
function peekRequestedProvider(body: Record<string, unknown>): string {
if (!isPlainObject(body.request)) return ''
return typeof body.request.provider === 'string' ? body.request.provider : ''
}
async function authorizeGrokProviderAttempt(
claims: McpHostAccessClaims,
body: Record<string, unknown>,
resolvedDeps: LlmProviderAttemptAuthorizerDeps
): Promise<AuthorizeAttemptSuccess> {
if (!config.grokSubscriptionEnabled) {
throw new LlmProviderAttemptAuthorizeError('disabled', 'Grok subscription is disabled')
}
if (!claims.workflowControlScopes.includes(GROK_EXECUTE_SCOPE)) {
throw new LlmProviderAttemptAuthorizeError(
'insufficient_scope',
'mcp-host JWT lacks the llm:grok:execute scope'
)
}
assertBodyNestingWithinLimit(body)
const serialized = JSON.stringify(body)
// Same budgets as the Codex path (#784): the larger of the non-image cap plus
// the envelope allowance and the V2 visual envelope bounds the whole body;
// the wrapper outside image data stays on the non-image cap.
const wholeBodyLimit = Math.max(
grokRequestBodyLimitBytes(body.request),
GROK_LIMITS.maxRequestBodyBytes + AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES
)
if (Buffer.byteLength(serialized, 'utf8') > wholeBodyLimit) {
throw new LlmProviderAttemptAuthorizeError(
'payload_too_large',
'request body exceeds the limit'
)
}
if (
measureGrokNonImageAuthorizeBytes(body) >
GROK_LIMITS.maxRequestBodyBytes + AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES
) {
throw new LlmProviderAttemptAuthorizeError(
'payload_too_large',
'authorize wrapper exceeds the non-image limit'
)
}
const unknown = firstUnknownKey(body)
if (unknown) {
throw new LlmProviderAttemptAuthorizeError('unknown_field', `unknown field '${unknown}'`)
}
const caller = resolveCaller(claims)
assertClaimBinding(body, claims)
const parsed = parseGrokCompletionRequest(body.request)
if (!parsed.ok) {
// `kind: 'size'` is 413: the byte budgets and the container, member and
// element bounds. Every other refusal is 400, including the image count
// (`kind: 'count'`) and the message, tool-call, depth and range bounds
// (no kind).
throw new LlmProviderAttemptAuthorizeError(
parsed.code === 'limit' && parsed.kind === 'size' ? 'payload_too_large' : 'invalid_request',
parsed.message
)
}
const request = parsed.value
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 = hashGrokCompletionRequest(request)
if (typeof body.requestHash === 'string' && body.requestHash !== requestHash) {
throw new LlmProviderAttemptAuthorizeError(
'invalid_request',
'requestHash does not match the canonical request'
)
}
const assignment = await resolvedDeps
.resolveAssignment(caller.hostRef, resolvedDeps.signal)
.catch(error => {
resolvedDeps.signal?.throwIfAborted()
throw error
})
resolvedDeps.signal?.throwIfAborted()
const liveTarget = attestLiveBrokerTarget({
requestedProvider: GROK_PROVIDER,
liveBrokerProviders: assignment.liveBrokerProviders,
})
if (!liveTarget.ok) {
throw new LlmProviderAttemptAuthorizeError(liveTarget.code, liveTarget.message)
}
let resolvedConnectionRef = assignment.liveConnectionRef
if (assignment.annotations) {
const read = readSubscriptionConnectionRef({
provider: GROK_PROVIDER,
annotations: assignment.annotations,
})
if (!read.ok) {
throw new LlmProviderAttemptAuthorizeError(read.code, read.message)
}
resolvedConnectionRef = read.connectionKey
}
const attested = attestRequestedBrokerProvider({
requestedProvider: GROK_PROVIDER,
liveBrokerProviders: assignment.liveBrokerProviders,
liveConnectionRef: resolvedConnectionRef,
})
if (!attested.ok) {
throw new LlmProviderAttemptAuthorizeError(attested.code, attested.message)
}
const connectionKey = attested.connectionKey
if (
isGrokUnassignedConnectionKey(connectionKey) ||
connectionKey === GROK_UNASSIGNED_CONNECTION_KEY ||
connectionKey === GROK_RESERVED_DEPLOYMENT_DEFAULT_KEY
) {
throw new LlmProviderAttemptAuthorizeError(
'unassigned_connection',
'Host has no Grok subscription assigned'
)
}
return resolvedDeps.withTransaction(
async tx => {
resolvedDeps.signal?.throwIfAborted()
const db: DbClient = tx
const connection = await getSafeGrokSubscriptionConnection(db, connectionKey)
if (
!connection ||
connection.revokedAt ||
connection.status === 'revoked' ||
connection.status === 'reauth_required' ||
connection.catalogStatus === 'auth-rejected'
) {
throw new LlmProviderAttemptAuthorizeError(
'no_grant',
'Grok subscription grant is missing, revoked, or requires re-authentication'
)
}
if (
connection.status !== 'connected' ||
connection.catalogStatus === 'unavailable' ||
connection.catalogStatus === 'never_synced'
) {
throw new LlmProviderAttemptAuthorizeError(
'connection_unavailable',
'Grok subscription catalog is not ready'
)
}
const modelState = await getGrokCatalogModelState(db, connection.id, request.model)
if (!modelState || !modelState.enabled || modelState.stale) {
throw new LlmProviderAttemptAuthorizeError(
'model_not_allowed',
'model is disabled, stale, or absent from the Grok catalog'
)
}
const expectedPolicyHash = computeGrokPolicyHash({
model: request.model,
catalogRevision: connection.catalogRevision,
credentialRevision: connection.credentialRevision,
connectionKey: connection.connectionKey,
})
if (policyRevision !== connection.catalogRevision || policyHash !== expectedPolicyHash) {
throw new LlmProviderAttemptAuthorizeError(
'no_grant',
'policy revision or hash does not match the current Grok catalog'
)
}
const maxGeneration = await resolvedDeps.getMaxGeneration(db, invocationId)
if (attemptGeneration < maxGeneration) {
throw new LlmProviderAttemptAuthorizeError(
'stale_generation',
'attemptGeneration is older than the recorded invocation'
)
}
const pluginWorkloadSdkProviderAttemptId =
typeof body.pluginWorkloadSdkProviderAttemptId === 'string'
? body.pluginWorkloadSdkProviderAttemptId.trim()
: ''
let sdkLinkRecipe: { namespace: string; name: string } | null = null
if (pluginWorkloadSdkProviderAttemptId) {
if (!UUID_RE.test(pluginWorkloadSdkProviderAttemptId)) {
throw new LlmProviderAttemptAuthorizeError(
'invalid_request',
'pluginWorkloadSdkProviderAttemptId must be a UUID'
)
}
if (caller.callerKind === 'host') {
throw new LlmProviderAttemptAuthorizeError(
'no_grant',
'host Grok chat cannot bind a Plugin Workload SDK provider attempt'
)
}
if (!caller.recipeNamespace || !caller.recipeName) {
throw new LlmProviderAttemptAuthorizeError(
'no_grant',
'pluginWorkloadSdkProviderAttemptId does not match the reserved SDK attempt'
)
}
sdkLinkRecipe = { namespace: caller.recipeNamespace, name: caller.recipeName }
}
if (sdkLinkRecipe) {
await lockPluginWorkloadSdkRecipe(db, sdkLinkRecipe.namespace, sdkLinkRecipe.name)
}
const presentedReservationId =
typeof body.budgetReservationId === 'string' ? body.budgetReservationId.trim() : ''
let budgetReservationId = presentedReservationId || 'unbudgeted'
if (presentedReservationId) {
const active = await resolvedDeps.getActiveReservation(db, {
reservationId: presentedReservationId,
hostRef: caller.hostRef,
})
if (!active) {
throw new LlmProviderAttemptAuthorizeError(
'budget_denied',
'budget reservation is missing or expired'
)
}
} else {
const budget = await resolvedDeps.evaluateBudget(
{
host_ref: caller.hostRef,
context_ref: null,
team_id: null,
user_id: null,
provider: GROK_PROVIDER,
model: request.model,
llm_secret_name: null,
source_kind: 'channel',
recipe_name: caller.recipeName,
cron_job_id: null,
task_ref: `${invocationId}:${attemptGeneration}:${providerAttemptIndex}`,
},
db,
{ connect: async () => tx as never },
{
requiredUnit: 'tokens',
transactionClient: tx,
reservationTtlSeconds: GROK_ATTEMPT_RESERVATION_TTL_SECONDS,
}
)
if (!budget.allowed) {
throw new LlmProviderAttemptAuthorizeError(
'budget_denied',
'token budget denied this attempt'
)
}
budgetReservationId = budget.reservationIds?.[0] ?? 'unbudgeted'
}
const presentedTargetRef = typeof body.targetRef === 'string' ? body.targetRef.trim() : ''
let reservedSdkAttemptToPromote: {
id: string
invocationId: string
recipeNamespace: string
recipeName: string
attemptGeneration: number
attemptIndex: number
model: string
targetRef: string
} | null = null
if (pluginWorkloadSdkProviderAttemptId) {
const sdkAttempt = await getPluginWorkloadSdkProviderAttemptForUpdate(
pluginWorkloadSdkProviderAttemptId,
db
)
const spendExists = sdkAttempt
? await pluginWorkloadSdkSpendOutcomeExists(sdkAttempt.id, db)
: false
if (
!sdkAttempt ||
spendExists ||
sdkAttempt.invocationId !== invocationId ||
sdkAttempt.attemptGeneration !== attemptGeneration ||
sdkAttempt.attemptIndex !== providerAttemptIndex ||
sdkAttempt.recipeNamespace !== caller.recipeNamespace ||
sdkAttempt.recipeName !== caller.recipeName ||
sdkAttempt.provider !== GROK_PROVIDER ||
sdkAttempt.model !== request.model ||
!sdkAttempt.targetRef.trim() ||
(presentedTargetRef !== '' && presentedTargetRef !== sdkAttempt.targetRef) ||
!['reserved', 'in_progress'].includes(sdkAttempt.status)
) {
throw new LlmProviderAttemptAuthorizeError(
'no_grant',
'pluginWorkloadSdkProviderAttemptId does not match the reserved SDK attempt'
)
}
if (sdkAttempt.status === 'reserved') {
reservedSdkAttemptToPromote = {
id: sdkAttempt.id,
invocationId: sdkAttempt.invocationId,
recipeNamespace: sdkAttempt.recipeNamespace,
recipeName: sdkAttempt.recipeName,
attemptGeneration: sdkAttempt.attemptGeneration,
attemptIndex: sdkAttempt.attemptIndex,
model: sdkAttempt.model,
targetRef: sdkAttempt.targetRef,
}
}
}
try {
const attempt = await resolvedDeps.insertAttempt(db, {
callerKind: caller.callerKind,
hostRef: caller.hostRef,
recipeNamespace: caller.recipeNamespace,
recipeName: caller.recipeName,
invocationId,
attemptGeneration,
providerAttemptIndex,
provider: GROK_PROVIDER,
model: request.model,
requestHash,
policyRevision,
policyHash,
budgetReservationId,
connectionRevision: connection.credentialRevision,
connectionId: connection.id,
...(pluginWorkloadSdkProviderAttemptId ? { pluginWorkloadSdkProviderAttemptId } : {}),
})
if (reservedSdkAttemptToPromote) {
const promoted = await promoteReservedOauthBrokerProviderAttempt(
{ ...reservedSdkAttemptToPromote, provider: GROK_PROVIDER },
db
)
if (!promoted) {
throw new LlmProviderAttemptAuthorizeError(
'no_grant',
'pluginWorkloadSdkProviderAttemptId is no longer reserved for Grok authorize'
)
}
}
const issued = await issueRegisteredGrokExecutionTicket(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,
connectionId: connection.id,
})
if (request.schemaVersion === 'grok-completion-request.v2') {
// Measure the exact proxy envelope while the attempt, ticket and any
// new reservation are still transactional, as the Codex path does.
const envelope = buildGrokProxyEnvelope({
executionTicket: issued.executionTicket,
requestHash,
request,
})
if (!envelope.ok) {
throw new LlmProviderAttemptAuthorizeError(
envelope.code === 'limit' && envelope.kind === 'size'
? 'payload_too_large'
: 'invalid_request',
envelope.message
)
}
}
log.info(
{
event: 'grok_attempt_authorized',
providerAttemptId: attempt.id,
hostRef: caller.hostRef,
model: request.model,
},
'authorized Grok 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
}
},
undefined,
{ signal: resolvedDeps.signal }
)
}
export async function authorizeLlmProviderAttempt(
claims: McpHostAccessClaims,
body: unknown,
deps: LlmProviderAttemptAuthorizerDeps | Partial<LlmProviderAttemptAuthorizerDeps> = defaultDeps()
): Promise<AuthorizeAttemptSuccess> {
const resolvedDeps: LlmProviderAttemptAuthorizerDeps = { ...defaultDeps(), ...deps }
resolvedDeps.signal?.throwIfAborted()
if (!isPlainObject(body)) {
throw new LlmProviderAttemptAuthorizeError('invalid_request', 'body must be an object')
}
if (peekRequestedProvider(body) === GROK_PROVIDER) {
return authorizeGrokProviderAttempt(claims, body, resolvedDeps)
}
if (!resolvedDeps.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'
)
}
assertBodyNestingWithinLimit(body)
const serialized = JSON.stringify(body)
// The larger of the two budgets wins, as on the gateway's client_max_body_size:
// the non-image cap plus the envelope allowance (#731), or the V2 visual
// envelope (#660). The contract parser below still holds `request` itself to
// its own schema's cap.
const wholeBodyLimit = Math.max(
requestBodyLimitBytes(body.request),
LIMITS.maxRequestBodyBytes + AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES
)
if (Buffer.byteLength(serialized, 'utf8') > wholeBodyLimit) {
throw new LlmProviderAttemptAuthorizeError(
'payload_too_large',
'request body exceeds the limit'
)
}
if (
measureNonImageAuthorizeBytes(body) >
LIMITS.maxRequestBodyBytes + AUTHORIZE_ENVELOPE_ALLOWANCE_BYTES
) {
throw new LlmProviderAttemptAuthorizeError(
'payload_too_large',
'authorize wrapper exceeds the non-image limit'
)
}
const unknown = firstUnknownKey(body)
if (unknown) {
throw new LlmProviderAttemptAuthorizeError('unknown_field', `unknown field '${unknown}'`)
}
const caller = resolveCaller(claims)
assertClaimBinding(body, claims)
const parsed = parseCodexCompletionRequest(body.request)
if (!parsed.ok) {
// `kind: 'size'` is 413: the byte budgets, the image geometry and the
// container, member and element bounds. `range`, `count` and `depth`
// stay 400.
throw new LlmProviderAttemptAuthorizeError(
parsed.code === 'limit' && parsed.kind === 'size' ? 'payload_too_large' : '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 (!isBoundedId(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 = hashCodexCompletionRequest(request)
if (typeof body.requestHash === 'string' && body.requestHash !== requestHash) {
throw new LlmProviderAttemptAuthorizeError(
'invalid_request',
'requestHash does not match the canonical request'
)
}
const assignment = await resolvedDeps
.resolveAssignment(caller.hostRef, resolvedDeps.signal)
.catch(error => {
resolvedDeps.signal?.throwIfAborted()
throw error
})
resolvedDeps.signal?.throwIfAborted()
const liveTarget = attestLiveBrokerTarget({
requestedProvider: request.provider,
liveBrokerProviders: assignment.liveBrokerProviders,
})
if (!liveTarget.ok) {
throw new LlmProviderAttemptAuthorizeError(liveTarget.code, liveTarget.message)
}
let resolvedConnectionRef = assignment.liveConnectionRef
if (assignment.annotations) {
const read = readSubscriptionConnectionRef({
provider: request.provider,
annotations: assignment.annotations,
})
if (!read.ok) {
throw new LlmProviderAttemptAuthorizeError(read.code, read.message)
}
resolvedConnectionRef = read.connectionKey
}
const attested = attestRequestedBrokerProvider({
requestedProvider: request.provider,
liveBrokerProviders: assignment.liveBrokerProviders,
liveConnectionRef: resolvedConnectionRef,
})
if (!attested.ok) {
throw new LlmProviderAttemptAuthorizeError(attested.code, attested.message)
}
const connectionKey = attested.connectionKey
if (isCodexUnassignedConnectionKey(connectionKey)) {
throw new LlmProviderAttemptAuthorizeError(
'unassigned_connection',
'Host has no ChatGPT subscription assigned'
)
}
return resolvedDeps.withTransaction(
async tx => {
resolvedDeps.signal?.throwIfAborted()
const db: DbClient = tx
const connection = await resolvedDeps.getConnection(db, connectionKey)
// Terminal grant failures must not look like a retryable proxy outage.
// Missing, revoked, and auth-rejected rows require a new grant or
// operator re-auth — failover onto another provider is the wrong recovery.
if (
!connection ||
connection.revokedAt ||
connection.status === 'revoked' ||
connection.status === 'reauth_required' ||
connection.catalogStatus === 'auth-rejected'
) {
throw new LlmProviderAttemptAuthorizeError(
'no_grant',
'Codex subscription grant is missing, revoked, or requires re-authentication'
)
}
if (
connection.status !== 'connected' ||
connection.catalogStatus === 'unavailable' ||
connection.catalogStatus === 'never_synced'
) {
throw new LlmProviderAttemptAuthorizeError(
'connection_unavailable',
'Codex subscription catalog is not ready'
)
}
const modelState = await resolvedDeps.getModelState(db, connection.id, request.model)
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,
connectionKey: connection.connectionKey,
})
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 resolvedDeps.getMaxGeneration(db, invocationId)
if (attemptGeneration < maxGeneration) {
throw new LlmProviderAttemptAuthorizeError(
'stale_generation',
'attemptGeneration is older than the recorded invocation'
)
}
const pluginWorkloadSdkProviderAttemptId =
typeof body.pluginWorkloadSdkProviderAttemptId === 'string'
? body.pluginWorkloadSdkProviderAttemptId.trim()
: ''
let sdkLinkRecipe: { namespace: string; name: string } | null = null
if (pluginWorkloadSdkProviderAttemptId) {
if (!UUID_RE.test(pluginWorkloadSdkProviderAttemptId)) {
throw new LlmProviderAttemptAuthorizeError(
'invalid_request',
'pluginWorkloadSdkProviderAttemptId must be a UUID'
)
}
if (caller.callerKind === 'host') {
throw new LlmProviderAttemptAuthorizeError(
'no_grant',
'host Codex chat cannot bind a Plugin Workload SDK provider attempt'
)
}
if (!caller.recipeNamespace || !caller.recipeName) {
throw new LlmProviderAttemptAuthorizeError(
'no_grant',
'pluginWorkloadSdkProviderAttemptId does not match the reserved SDK attempt'
)
}
sdkLinkRecipe = { namespace: caller.recipeNamespace, name: caller.recipeName }
}
// Recipe authorize and promptBridge finalize share this advisory. Take it
// before budget reservation work so concurrent Codex + fallback cannot
// deadlock (budget rows then advisory vs advisory then spend/invocation).
//
// Only an SDK-linked authorize goes on to take plugin_workload_sdk_*
// rows FOR UPDATE, which is the order finalize follows after this advisory.
// The workflow lane touches neither, so taking it for every recipe caller
// serialized that lane per recipe for no ordering benefit.
if (sdkLinkRecipe) {
await lockPluginWorkloadSdkRecipe(db, sdkLinkRecipe.namespace, sdkLinkRecipe.name)
}
const presentedReservationId =
typeof body.budgetReservationId === 'string' ? body.budgetReservationId.trim() : ''
let budgetReservationId = presentedReservationId || 'unbudgeted'
if (presentedReservationId) {
const active = await resolvedDeps.getActiveReservation(db, {
reservationId: presentedReservationId,
hostRef: caller.hostRef,
})
if (!active) {
throw new LlmProviderAttemptAuthorizeError(
'budget_denied',
'budget reservation is missing or expired'
)
}
} else {
const budget = await resolvedDeps.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: 'channel',
recipe_name: caller.recipeName,
cron_job_id: null,
task_ref: `${invocationId}:${attemptGeneration}:${providerAttemptIndex}`,
},
db,
{ connect: async () => tx as never },
{
requiredUnit: 'tokens',
transactionClient: tx,
reservationTtlSeconds: CODEX_ATTEMPT_RESERVATION_TTL_SECONDS,
}
)
if (!budget.allowed) {
throw new LlmProviderAttemptAuthorizeError(
'budget_denied',
budget.reason === 'cost_unit_rejected'
? 'Codex attempts reject cost-unit budgets'
: 'token budget denied this attempt'
)
}
budgetReservationId = budget.reservationIds?.[0] ?? 'unbudgeted'
}
const presentedTargetRef = typeof body.targetRef === 'string' ? body.targetRef.trim() : ''
if (presentedTargetRef !== '' && !isBoundedId(presentedTargetRef)) {
throw new LlmProviderAttemptAuthorizeError('invalid_request', 'targetRef is invalid')
}
let reservedSdkAttemptToPromote: {
id: string
invocationId: string
recipeNamespace: string
recipeName: string
attemptGeneration: number
attemptIndex: number
model: string
targetRef: string
} | null = null
if (pluginWorkloadSdkProviderAttemptId) {
const sdkAttempt = await getPluginWorkloadSdkProviderAttemptForUpdate(
pluginWorkloadSdkProviderAttemptId,
db
)
const spendExists = sdkAttempt
? await pluginWorkloadSdkSpendOutcomeExists(sdkAttempt.id, db)
: false
if (
!sdkAttempt ||
spendExists ||
sdkAttempt.invocationId !== invocationId ||
sdkAttempt.attemptGeneration !== attemptGeneration ||
sdkAttempt.attemptIndex !== providerAttemptIndex ||
sdkAttempt.recipeNamespace !== caller.recipeNamespace ||
sdkAttempt.recipeName !== caller.recipeName ||
sdkAttempt.provider !== PROVIDER ||
sdkAttempt.model !== request.model ||
!sdkAttempt.targetRef.trim() ||
(presentedTargetRef !== '' && presentedTargetRef !== sdkAttempt.targetRef) ||
!['reserved', 'in_progress'].includes(sdkAttempt.status)
) {
throw new LlmProviderAttemptAuthorizeError(
'no_grant',
'pluginWorkloadSdkProviderAttemptId does not match the reserved SDK attempt'
)
}
if (sdkAttempt.status === 'reserved') {
reservedSdkAttemptToPromote = {
id: sdkAttempt.id,
invocationId: sdkAttempt.invocationId,
recipeNamespace: sdkAttempt.recipeNamespace,
recipeName: sdkAttempt.recipeName,
attemptGeneration: sdkAttempt.attemptGeneration,
attemptIndex: sdkAttempt.attemptIndex,
model: sdkAttempt.model,
targetRef: sdkAttempt.targetRef,
}
}
}
try {
const attempt = await resolvedDeps.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,
connectionId: connection.id,
...(pluginWorkloadSdkProviderAttemptId ? { pluginWorkloadSdkProviderAttemptId } : {}),
})
if (reservedSdkAttemptToPromote) {
const promoted = await promoteReservedOauthBrokerProviderAttempt(
{ ...reservedSdkAttemptToPromote, provider: PROVIDER },
db
)
if (!promoted) {
throw new LlmProviderAttemptAuthorizeError(
'no_grant',
'pluginWorkloadSdkProviderAttemptId is no longer reserved for Codex authorize'
)
}
log.info(
{
event: 'sdk_oauth_attempt_promoted',
pluginWorkloadSdkProviderAttemptId: reservedSdkAttemptToPromote.id,
providerAttemptId: attempt.id,
credentialJtiPresent: false,
},
'promoted reserved SDK oauth attempt after Codex authorize-link'
)
}
const issued = await resolvedDeps.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,
connectionId: connection.id,
})
if (request.schemaVersion === 'codex-completion-request.v2') {
// Measure the exact proxy envelope while the attempt, ticket and any
// new reservation are still transactional. Pre-redeem failures cannot
// use the ordinary receipt-based finalizer.
const envelope = buildCodexProxyEnvelope({
executionTicket: issued.executionTicket,
requestHash,
request,
})
if (!envelope.ok) {
throw new LlmProviderAttemptAuthorizeError(
envelope.code === 'limit' && envelope.kind === 'size'
? 'payload_too_large'
: 'invalid_request',
envelope.message
)
}
}
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
}
},
undefined,
{ signal: resolvedDeps.signal }
)
}