Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import {
CATALOG_ORIGIN,
COMPLETIONS_ORIGIN,
TRANSPORT_PROTOCOL_VERSION,
} from '@clerum/grok-provider-attempt-contract'
import { config } from '../config.js'
import { type DbClient, pool, withTransaction } from '../db.js'
import { deriveOAuthEncryptionKey } from '../oauth/encryption.js'
import { rootLogger } from '../observability/logger.js'
import { llmAllowlistConfigMapWriteFailuresTotal } from '../observability/metrics.js'
import { verifyGrokExecutionTicket } from './grokProviderAttemptTicket.js'
import {
getSafeGrokSubscriptionConnectionById,
loadGrokSubscriptionSecrets,
} from './grokSubscriptionConnection.js'
import { GrokSubscriptionOAuthError, ensureFreshGrokAccessToken } from './grokSubscriptionOAuth.js'
import {
type AllowedModelsConfigMapMaterializer,
publishAllowedModelsConfigMapAfterGrantChange,
} from './llmAllowedModelsConfigMap.js'
import { GROK_MAX_STREAM_DURATION_MS } from './llmProviderAttemptEnvelope.js'
import { opaqueAttemptReceipt } from './llmProviderAttemptRedemption.js'
import {
loadLlmProviderAttempt,
lockLlmProviderAttemptTicket,
markLlmProviderAttemptTicketRedeemed,
peekLlmProviderAttemptTicket,
} from './llmProviderAttemptStore.js'
const log = rootLogger.child({ module: 'grok-provider-attempt-redemption' })
export const GROK_COMPLETIONS_ORIGIN = COMPLETIONS_ORIGIN
export const GROK_CATALOG_ORIGIN = CATALOG_ORIGIN
export const GROK_TRANSPORT_PROTOCOL = TRANSPORT_PROTOCOL_VERSION
export { GROK_MAX_STREAM_DURATION_MS }
export type GrokProviderAttemptRedeemErrorCode =
| 'disabled'
| 'ticket_invalid'
| 'ticket_replayed'
| 'ticket_expired'
| 'request_hash_mismatch'
| 'connection_unavailable'
| 'no_grant'
| 'provider_unavailable'
export class GrokProviderAttemptRedeemError extends Error {
constructor(
readonly code: GrokProviderAttemptRedeemErrorCode,
message: string
) {
super(message)
this.name = 'GrokProviderAttemptRedeemError'
}
}
export type RedeemGrokAttemptSuccess = {
accessToken: string
transport: {
protocolVersion: typeof GROK_TRANSPORT_PROTOCOL
completionsOrigin: typeof GROK_COMPLETIONS_ORIGIN
catalogOrigin: typeof GROK_CATALOG_ORIGIN
operation: 'completion_stream' | 'completion_cancel' | 'connection_test'
servedModel: string
maxStreamDurationMs: number
}
expiryClass: 'short_lived' | 'upstream_managed'
attemptReceipt: string
}
export type RedeemGrokAttemptInput = {
executionTicket: string
requestHash: string
model?: string
hostRef?: string
operation?: 'completion_stream' | 'completion_cancel' | 'connection_test'
}
export type RedeemGrokAttemptDeps = {
enabled: boolean
db: DbClient
withTransaction: typeof withTransaction
loadSecrets: typeof loadGrokSubscriptionSecrets
getConnectionById: typeof getSafeGrokSubscriptionConnectionById
encryptionKey: Buffer
ensureFreshAccessToken?: (connectionKey?: string) => Promise<void>
/** Republishes the runtime allowlist ConfigMap after a grant change. */
publishAllowlist: () => Promise<void>
}
export const productionGrokRedeemDeps = (
materializer: AllowedModelsConfigMapMaterializer
): RedeemGrokAttemptDeps => ({
enabled: config.grokSubscriptionEnabled,
db: pool,
withTransaction,
loadSecrets: loadGrokSubscriptionSecrets,
getConnectionById: getSafeGrokSubscriptionConnectionById,
encryptionKey: deriveOAuthEncryptionKey(config.oauthEncryptionKey),
ensureFreshAccessToken: connectionKey =>
ensureFreshGrokAccessToken({
db: { query: (text, values) => pool.query(text, values) },
encryptionKey: deriveOAuthEncryptionKey(config.oauthEncryptionKey),
fetchFn: fetch,
clientId: config.grokOAuthClientId,
enabled: config.grokSubscriptionEnabled,
connectionKey: connectionKey ?? '',
}),
publishAllowlist: async () => {
await publishAllowedModelsConfigMapAfterGrantChange(materializer)
},
})
/**
* A refresh failure that persisted a connection status (a rejected refresh
* token marks the row reauth_required) changed what the runtime ConfigMap
* must say about the grant, so it is published before the redemption fails,
* as the refresh and catalog-sync routes do. A failed publish is counted and
* logged exactly as those routes count and log it; the redemption then
* fails with its own code, because the proxy contract has no code for an
* unwritten ConfigMap.
*/
async function publishAfterPersistedRefreshFailure(deps: RedeemGrokAttemptDeps): Promise<void> {
try {
await deps.publishAllowlist()
} catch (err) {
llmAllowlistConfigMapWriteFailuresTotal.inc({ phase: 'mutation' })
log.error(
{ err, event: 'grok_allowed_models_cm_write_failed' },
'Grok refresh failure persisted a connection status but the runtime ConfigMap was not updated'
)
}
}
export async function redeemGrokProviderAttempt(
input: RedeemGrokAttemptInput,
deps: RedeemGrokAttemptDeps
): Promise<RedeemGrokAttemptSuccess> {
if (!deps.enabled) {
throw new GrokProviderAttemptRedeemError('disabled', 'Grok subscription is disabled')
}
const claims = verifyGrokExecutionTicket(input.executionTicket)
if (!claims) {
throw new GrokProviderAttemptRedeemError('ticket_invalid', 'execution ticket is invalid')
}
if (claims.provider !== 'grok-subscription') {
throw new GrokProviderAttemptRedeemError(
'ticket_invalid',
'ticket provider is not grok-subscription'
)
}
if (claims.requestHash !== input.requestHash) {
throw new GrokProviderAttemptRedeemError(
'request_hash_mismatch',
'requestHash does not match the ticket'
)
}
if (input.model && input.model !== claims.model) {
throw new GrokProviderAttemptRedeemError('ticket_invalid', 'model does not match the ticket')
}
if (input.hostRef && input.hostRef !== claims.hostRef) {
throw new GrokProviderAttemptRedeemError('ticket_invalid', 'hostRef does not match the ticket')
}
const previewTicket = await peekLlmProviderAttemptTicket(deps.db, claims.jti)
if (!previewTicket) {
throw new GrokProviderAttemptRedeemError('ticket_invalid', 'execution ticket is not registered')
}
if (previewTicket.status !== 'issued') {
throw new GrokProviderAttemptRedeemError('ticket_replayed', 'execution ticket already used')
}
const previewAttempt = await loadLlmProviderAttempt(deps.db, previewTicket.providerAttemptId)
if (
!previewAttempt ||
previewAttempt.provider !== 'grok-subscription' ||
previewAttempt.connectionId !== claims.connectionId
) {
throw new GrokProviderAttemptRedeemError(
'ticket_invalid',
'ticket provider or connectionId does not match the attempt'
)
}
if (deps.ensureFreshAccessToken) {
const assigned = await deps.getConnectionById(deps.db, claims.connectionId)
if (!assigned) {
// The attempt's connection row is gone; never hand an empty key to the
// refresh path (it would surface as an unmapped 500).
throw new GrokProviderAttemptRedeemError(
'connection_unavailable',
'Grok subscription connection is not usable'
)
}
try {
await deps.ensureFreshAccessToken(assigned.connectionKey)
} catch (err) {
if (err instanceof GrokSubscriptionOAuthError) {
if (err.persistedConnectionStatus === true) {
await publishAfterPersistedRefreshFailure(deps)
}
throw new GrokProviderAttemptRedeemError(
err.code === 'no_grant' || err.code === 'not_connected' || err.code === 'reauth_required'
? 'no_grant'
: err.code === 'provider_unavailable'
? 'provider_unavailable'
: 'connection_unavailable',
'Grok access token could not be refreshed'
)
}
throw err
}
}
return deps.withTransaction(async tx => {
const ticket = await lockLlmProviderAttemptTicket(tx, claims.jti)
if (!ticket) {
throw new GrokProviderAttemptRedeemError(
'ticket_invalid',
'execution ticket is not registered'
)
}
if (ticket.status !== 'issued') {
throw new GrokProviderAttemptRedeemError('ticket_replayed', 'execution ticket already used')
}
if (ticket.expiresAt.getTime() <= Date.now()) {
throw new GrokProviderAttemptRedeemError('ticket_expired', 'execution ticket expired')
}
const attempt = await loadLlmProviderAttempt(tx, ticket.providerAttemptId)
if (!attempt || attempt.status !== 'authorized') {
throw new GrokProviderAttemptRedeemError(
'ticket_invalid',
'provider attempt is not redeemable'
)
}
if (attempt.provider !== 'grok-subscription' || attempt.connectionId !== claims.connectionId) {
throw new GrokProviderAttemptRedeemError(
'ticket_invalid',
'ticket provider or connectionId does not match the attempt'
)
}
if (
attempt.requestHash !== claims.requestHash ||
attempt.model !== claims.model ||
attempt.hostRef !== claims.hostRef ||
attempt.invocationId !== claims.invocationId ||
attempt.attemptGeneration !== claims.attemptGeneration ||
attempt.policyHash !== claims.policyHash ||
attempt.policyRevision !== claims.policyRevision ||
attempt.budgetReservationId !== claims.budgetReservationId ||
attempt.connectionRevision !== claims.connectionRevision
) {
throw new GrokProviderAttemptRedeemError(
'no_grant',
'ticket bindings no longer match the attempt'
)
}
if (!attempt.connectionId) {
throw new GrokProviderAttemptRedeemError(
'connection_unavailable',
'Grok attempt is missing a connection binding'
)
}
const connection = await getSafeGrokSubscriptionConnectionById(tx, attempt.connectionId)
if (
!connection ||
connection.status !== 'connected' ||
connection.revokedAt ||
connection.credentialRevision !== attempt.connectionRevision ||
connection.id !== attempt.connectionId
) {
throw new GrokProviderAttemptRedeemError(
'connection_unavailable',
'Grok subscription connection is not usable'
)
}
const redeemed = await markLlmProviderAttemptTicketRedeemed(tx, claims.jti)
if (!redeemed) {
throw new GrokProviderAttemptRedeemError('ticket_replayed', 'execution ticket already used')
}
const secrets = await deps.loadSecrets(tx, deps.encryptionKey, connection.connectionKey)
if (!secrets?.accessToken) {
throw new GrokProviderAttemptRedeemError(
'connection_unavailable',
'no usable access token is available'
)
}
const expiryClass =
secrets.accessTokenExpiresAt &&
secrets.accessTokenExpiresAt.getTime() - Date.now() < 3_600_000
? 'short_lived'
: 'upstream_managed'
log.info(
{ event: 'grok_attempt_redeemed', providerAttemptId: attempt.id },
'redeemed Grok execution ticket'
)
return {
accessToken: secrets.accessToken,
transport: {
protocolVersion: GROK_TRANSPORT_PROTOCOL,
completionsOrigin: GROK_COMPLETIONS_ORIGIN,
catalogOrigin: GROK_CATALOG_ORIGIN,
operation: input.operation ?? 'completion_stream',
servedModel: attempt.model,
maxStreamDurationMs: GROK_MAX_STREAM_DURATION_MS,
},
expiryClass,
attemptReceipt: opaqueAttemptReceipt({
jti: claims.jti,
providerAttemptId: attempt.id,
requestHash: attempt.requestHash,
}),
}
})
}