Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
15.8 KB
Raw Blame
import { apiGet, apiSend } from './api'
import { invalidateReadRequestCache } from './readRequestCache'
import type { SubscriptionCapabilityLoadOptions } from './subscriptionCapabilities'

export const CODEX_SUBSCRIPTION_API_BASE = '/api/v1/admin/llm/providers/codex-subscription'

/** Canonical ChatGPT device verification page. Reject any other href from device/start. */
export const CODEX_DEVICE_VERIFICATION_URI = 'https://auth.openai.com/codex/device'

export type CodexConnectionStatus =
  | 'disconnected'
  | 'connecting'
  | 'connected'
  | 'reauth_required'
  | 'revoked'

export type CodexCatalogStatus = 'never_synced' | 'ready' | 'auth-rejected' | 'unavailable'

export type CodexOAuthIntent = 'connect' | 'reconnect' | 'replace'

export type CodexAssignedHost = { name: string }

export type CodexAssignableHost = {
  name: string
  connectionRef: string
  displayName?: string
  provider?: string
  model?: string
}

export const CODEX_UNASSIGNED_CONNECTION_KEY = 'unassigned'

/** Recipe grant identity. Recipes have no CRD `connectionRef` field. */
export const CODEX_CONNECTION_REF_ANNOTATION = 'clerum.io/codex-connection-ref'

export function isAssignableCodexGrant(
  row: Pick<CodexSubscriptionConnectionView, 'status' | 'catalogStatus'>
): boolean {
  return row.status === 'connected' && row.catalogStatus === 'ready'
}

export type CodexSubscriptionConnectionView = {
  id?: string
  connectionKey: string
  displayName?: string
  defaultModel?: string | null
  status: CodexConnectionStatus
  credentialRevision: number
  catalogRevision: number
  accountFingerprint: string | null
  catalogStatus: CodexCatalogStatus
  catalogSyncedAt: string | null
  lastRefreshAt: string | null
  lastAuthAt: string | null
  refreshLockHeld: boolean
  assignedHosts?: CodexAssignedHost[]
  assignedHostsUnavailable?: boolean
}

export type CodexBrowserStartView = {
  authorizeUrl: string
  state: string
  intent: CodexOAuthIntent
  expiresAt: string
}

export type CodexDeviceStartView = {
  userCode: string
  verificationUri: string
  intervalSeconds: number
  state: string
  intent: CodexOAuthIntent
}

export type CodexDevicePollView =
  | { status: 'pending' | 'slow_down'; intervalSeconds: number; state: string }
  | { status: 'connected'; connection: CodexSubscriptionConnectionView }
  | { status: 'expired' | 'denied' }

export type CodexCatalogSyncView = {
  outcome: string
  added: number
  refreshed: number
  staled: number
  connection: CodexSubscriptionConnectionView | null
}

const FORBIDDEN_KEY =
  /accessToken|refreshToken|deviceCode|authorization|set-cookie|cookie|proxyUrl|proxyURL|accountId|rawAccount|subject/i

function isPlainObject(value: unknown): value is Record<string, unknown> {
  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
}

/**
 * The two subscription brokers share this module's shape validation but not
 * their identity. An operator reading "Codex subscription connection status is
 * invalid" in a Grok dialog is being told the wrong thing about which vendor
 * answered, so every message the user can reach is parameterized by the brand
 * of the endpoint that produced the payload.
 */
export type SubscriptionBrand = 'Codex' | 'Grok'

function assertNoForbiddenKeys(value: unknown, brand: SubscriptionBrand, path = 'root'): void {
  if (Array.isArray(value)) {
    value.forEach((entry, index) => assertNoForbiddenKeys(entry, brand, `${path}[${index}]`))
    return
  }
  if (!isPlainObject(value)) return
  for (const [key, nested] of Object.entries(value)) {
    if (FORBIDDEN_KEY.test(key)) {
      throw new Error(`${brand} subscription payload leaked forbidden field "${key}" at ${path}`)
    }
    assertNoForbiddenKeys(nested, brand, `${path}.${key}`)
  }
}

function pickString(value: unknown): string | null {
  return typeof value === 'string' && value.trim() ? value : null
}

function pickNumber(value: unknown, fallback = 0): number {
  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
}

function pickBool(value: unknown): boolean {
  return value === true
}

export function sanitizeCodexConnection(raw: unknown): CodexSubscriptionConnectionView {
  return sanitizeSubscriptionConnection(raw, 'Codex')
}

export function sanitizeSubscriptionConnection(
  raw: unknown,
  brand: SubscriptionBrand
): CodexSubscriptionConnectionView {
  assertNoForbiddenKeys(raw, brand)
  if (!isPlainObject(raw)) {
    throw new Error(`${brand} subscription connection is not an object`)
  }
  const status = raw.status
  if (
    status !== 'disconnected' &&
    status !== 'connecting' &&
    status !== 'connected' &&
    status !== 'reauth_required' &&
    status !== 'revoked'
  ) {
    throw new Error(`${brand} subscription connection status is invalid`)
  }
  const catalogStatus = raw.catalogStatus
  const safeCatalog: CodexCatalogStatus =
    catalogStatus === 'ready' ||
    catalogStatus === 'auth-rejected' ||
    catalogStatus === 'unavailable' ||
    catalogStatus === 'never_synced'
      ? catalogStatus
      : 'never_synced'
  const connectionKey = typeof raw.connectionKey === 'string' ? raw.connectionKey.trim() : ''
  if (!connectionKey || connectionKey === CODEX_UNASSIGNED_CONNECTION_KEY) {
    throw new Error(`${brand} subscription connection key is invalid`)
  }
  return {
    connectionKey,
    displayName: pickString(raw.displayName) ?? undefined,
    defaultModel: pickString(raw.defaultModel),
    assignedHosts: Array.isArray(raw.assignedHosts)
      ? raw.assignedHosts
          .filter(
            (entry): entry is { name: string } =>
              Boolean(entry) && typeof (entry as { name?: unknown }).name === 'string'
          )
          .map(entry => ({ name: entry.name }))
      : undefined,
    assignedHostsUnavailable: raw.assignedHostsUnavailable === true,
    status,
    credentialRevision: pickNumber(raw.credentialRevision),
    catalogRevision: pickNumber(raw.catalogRevision),
    accountFingerprint: pickString(raw.accountFingerprint),
    catalogStatus: safeCatalog,
    catalogSyncedAt: pickString(raw.catalogSyncedAt),
    lastRefreshAt: pickString(raw.lastRefreshAt),
    lastAuthAt: pickString(raw.lastAuthAt),
    refreshLockHeld: pickBool(raw.refreshLockHeld),
  }
}

export function sanitizeCodexBrowserStart(raw: unknown): CodexBrowserStartView {
  assertNoForbiddenKeys(raw, 'Codex')
  if (!isPlainObject(raw)) throw new Error('Codex browser start is not an object')
  const authorizeUrl = pickString(raw.authorizeUrl)
  const state = pickString(raw.state)
  const expiresAt = pickString(raw.expiresAt)
  const intent = raw.intent
  if (!authorizeUrl || !state || !expiresAt) {
    throw new Error('Codex browser start is incomplete')
  }
  if (!authorizeUrl.startsWith('https://')) {
    throw new Error('Codex browser start authorizeUrl must be https')
  }
  return {
    authorizeUrl,
    state,
    intent: intent === 'reconnect' || intent === 'replace' ? intent : 'connect',
    expiresAt,
  }
}

export function sanitizeCodexDeviceStart(raw: unknown): CodexDeviceStartView {
  assertNoForbiddenKeys(raw, 'Codex')
  if (!isPlainObject(raw)) throw new Error('Codex device start is not an object')
  const userCode = pickString(raw.userCode)
  const verificationUri = pickString(raw.verificationUri)
  const state = pickString(raw.state)
  const intent = raw.intent
  if (!userCode || !verificationUri || !state) {
    throw new Error('Codex device start is incomplete')
  }
  if (verificationUri !== CODEX_DEVICE_VERIFICATION_URI) {
    throw new Error('Codex device start verification URI is not allowed')
  }
  return {
    userCode,
    verificationUri,
    intervalSeconds: Math.max(1, pickNumber(raw.intervalSeconds, 5)),
    state,
    intent: intent === 'reconnect' || intent === 'replace' ? intent : 'connect',
  }
}

export function sanitizeCodexDevicePoll(raw: unknown): CodexDevicePollView {
  assertNoForbiddenKeys(raw, 'Codex')
  if (!isPlainObject(raw)) throw new Error('Codex device poll is not an object')
  if (raw.status === 'connected') {
    return { status: 'connected', connection: sanitizeCodexConnection(raw.connection) }
  }
  if (raw.status === 'expired' || raw.status === 'denied') {
    return { status: raw.status }
  }
  if (raw.status === 'pending' || raw.status === 'slow_down') {
    return {
      status: raw.status,
      intervalSeconds: Math.max(1, pickNumber(raw.intervalSeconds, 5)),
      state: pickString(raw.state) ?? '',
    }
  }
  throw new Error('Codex device poll status is invalid')
}

export function sanitizeCodexCatalogSync(raw: unknown): CodexCatalogSyncView {
  return sanitizeSubscriptionCatalogSync(raw, 'Codex')
}

export function sanitizeSubscriptionCatalogSync(
  raw: unknown,
  brand: SubscriptionBrand
): CodexCatalogSyncView {
  assertNoForbiddenKeys(raw, brand)
  if (!isPlainObject(raw)) throw new Error(`${brand} catalog sync is not an object`)
  return {
    outcome: pickString(raw.outcome) ?? 'unknown',
    added: pickNumber(raw.added),
    refreshed: pickNumber(raw.refreshed),
    staled: pickNumber(raw.staled),
    connection:
      raw.connection == null ? null : sanitizeSubscriptionConnection(raw.connection, brand),
  }
}

function sanitizeAssignableHost(raw: unknown): CodexAssignableHost | null {
  if (!isPlainObject(raw)) return null
  const name = pickString(raw.name)
  const connectionRef = pickString(raw.connectionRef)
  if (!name || !connectionRef) return null
  const provider = pickString(raw.provider)
  const model = pickString(raw.model)
  return {
    name,
    connectionRef,
    displayName: pickString(raw.displayName) ?? name,
    ...(provider ? { provider } : {}),
    ...(model ? { model } : {}),
  }
}

export async function listCodexSubscriptionConnections(
  options: SubscriptionCapabilityLoadOptions = {}
): Promise<CodexSubscriptionConnectionView[]> {
  const fleet = await listCodexSubscriptionFleet(options)
  return fleet.connections
}

export async function listCodexSubscriptionFleet(
  options: SubscriptionCapabilityLoadOptions = {}
): Promise<{
  connections: CodexSubscriptionConnectionView[]
  assignableHosts: CodexAssignableHost[]
  assignableHostsUnavailable: boolean
}> {
  const raw = (await apiGet(
    `${CODEX_SUBSCRIPTION_API_BASE}/connections`,
    {},
    {
      metadataRead: 'subscription-connections',
      refresh: options.refresh,
      signal: options.signal,
    }
  )) as {
    connections?: unknown
    assignableHosts?: unknown
    assignableHostsUnavailable?: unknown
  }
  const connections = Array.isArray(raw.connections)
    ? raw.connections.map(sanitizeCodexConnection)
    : []
  return {
    connections,
    assignableHosts: Array.isArray(raw.assignableHosts)
      ? raw.assignableHosts
          .map(sanitizeAssignableHost)
          .filter((row): row is CodexAssignableHost => Boolean(row))
      : [],
    assignableHostsUnavailable:
      raw.assignableHostsUnavailable === true ||
      connections.some(row => row.assignedHostsUnavailable === true),
  }
}

export async function createCodexSubscriptionConnection(input: {
  displayName: string
  connectionKey?: string
}): Promise<CodexSubscriptionConnectionView> {
  const raw = await apiSend('POST', `${CODEX_SUBSCRIPTION_API_BASE}/connections`, input)
  invalidateReadRequestCache()
  return sanitizeCodexConnection(raw)
}

export async function listCodexConnectionModels(
  connectionKey: string,
  options: SubscriptionCapabilityLoadOptions = {}
): Promise<Array<{ model: string; enabled: boolean; stale: boolean }>> {
  const raw = (await apiGet(
    `${CODEX_SUBSCRIPTION_API_BASE}/connections/${encodeURIComponent(connectionKey)}/models`,
    {},
    {
      metadataRead: 'subscription-model-catalog',
      refresh: options.refresh,
      signal: options.signal,
    }
  )) as { models?: Array<{ model?: string; enabled?: boolean; stale?: boolean }> }
  return Array.isArray(raw.models)
    ? raw.models
        .filter(row => typeof row.model === 'string' && row.model.trim())
        .map(row => ({
          model: String(row.model),
          enabled: row.enabled === true,
          stale: row.stale === true,
        }))
    : []
}

export async function getCodexSubscriptionConnection(
  connectionKey?: string
): Promise<CodexSubscriptionConnectionView> {
  const path = connectionKey
    ? `${CODEX_SUBSCRIPTION_API_BASE}/connections/${encodeURIComponent(connectionKey)}`
    : `${CODEX_SUBSCRIPTION_API_BASE}/connection`
  return sanitizeCodexConnection(await apiGet(path))
}

function keyedPath(connectionKey: string | undefined, action: string): string {
  if (!connectionKey) return `${CODEX_SUBSCRIPTION_API_BASE}/${action}`
  return `${CODEX_SUBSCRIPTION_API_BASE}/connections/${encodeURIComponent(connectionKey)}/${action}`
}

export async function startCodexBrowserConnect(
  intent: CodexOAuthIntent,
  connectionKey?: string
): Promise<CodexBrowserStartView> {
  const raw = await apiSend('POST', keyedPath(connectionKey, 'browser/start'), { intent })
  invalidateReadRequestCache()
  return sanitizeCodexBrowserStart(raw)
}

export async function startCodexDeviceConnect(
  intent: CodexOAuthIntent,
  connectionKey?: string
): Promise<CodexDeviceStartView> {
  const raw = await apiSend('POST', keyedPath(connectionKey, 'device/start'), { intent })
  invalidateReadRequestCache()
  return sanitizeCodexDeviceStart(raw)
}

export async function pollCodexDevice(
  state: string,
  connectionKey?: string
): Promise<CodexDevicePollView> {
  const result = sanitizeCodexDevicePoll(
    await apiGet(keyedPath(connectionKey, 'device/poll'), { state })
  )
  if (result.status === 'connected') invalidateReadRequestCache()
  return result
}

export async function refreshCodexSubscriptionConnection(
  connectionKey?: string
): Promise<CodexSubscriptionConnectionView> {
  const raw = await apiSend('POST', keyedPath(connectionKey, 'refresh'))
  invalidateReadRequestCache()
  return sanitizeCodexConnection(raw)
}

export async function syncCodexSubscriptionCatalog(
  connectionKey?: string
): Promise<CodexCatalogSyncView> {
  const raw = await apiSend('POST', keyedPath(connectionKey, 'catalog/sync'))
  invalidateReadRequestCache()
  return sanitizeCodexCatalogSync(raw)
}

export async function revokeCodexSubscription(
  connectionKey?: string
): Promise<CodexSubscriptionConnectionView> {
  const raw = await apiSend('POST', keyedPath(connectionKey, 'revoke'))
  invalidateReadRequestCache()
  return sanitizeCodexConnection(raw)
}

export async function patchCodexSubscriptionConnection(
  connectionKey: string,
  patch: { displayName?: string; defaultModel?: string | null }
): Promise<CodexSubscriptionConnectionView> {
  const raw = await apiSend(
    'PATCH',
    `${CODEX_SUBSCRIPTION_API_BASE}/connections/${encodeURIComponent(connectionKey)}`,
    patch
  )
  invalidateReadRequestCache()
  return sanitizeCodexConnection(raw)
}

export async function patchCodexCatalogModel(
  connectionKey: string,
  model: string,
  enabled: boolean
): Promise<Array<{ model: string; enabled: boolean; stale: boolean }>> {
  const raw = (await apiSend(
    'PATCH',
    `${CODEX_SUBSCRIPTION_API_BASE}/connections/${encodeURIComponent(connectionKey)}/models/${encodeURIComponent(model)}`,
    { enabled }
  )) as { models?: Array<{ model?: string; enabled?: boolean; stale?: boolean }> }
  invalidateReadRequestCache()
  return Array.isArray(raw.models)
    ? raw.models
        .filter(row => typeof row.model === 'string' && row.model.trim())
        .map(row => ({
          model: String(row.model),
          enabled: row.enabled === true,
          stale: row.stale === true,
        }))
    : []
}

const CODEX_OAUTH_QUERY_PARAM = 'codex_oauth'

export function readCodexOAuthQueryParam(
  searchParams: URLSearchParams | null | undefined
): string | null {
  if (!searchParams) return null
  const value = searchParams.get(CODEX_OAUTH_QUERY_PARAM)
  return value && value.trim() ? value.trim() : null
}

export function isCodexBrowserOAuthUnavailableError(error: unknown): boolean {
  return (
    Boolean(error) &&
    typeof error === 'object' &&
    (error as { code?: unknown }).code === 'browser_oauth_unregistered'
  )
}