Skip to content

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

TypeScript
35.2 KB
Raw Blame
import { createHash, randomBytes } from 'node:crypto'
import type { DbClient } from '../db.js'
import { rootLogger } from '../observability/logger.js'
import { chatgptAccountIdFromJwt } from './chatgptAccountId.js'
import {
  type CodexCatalogOutcome,
  type CodexCatalogTransport,
  rebuildLiveCodexUnionAllowlist,
  syncCodexSubscriptionCatalog,
} from './codexSubscriptionCatalog.js'
import {
  CodexSubscriptionFingerprintConflictError,
  type CodexSubscriptionSafeConnection,
  CodexSubscriptionStaleRevisionError,
  acquireCodexSubscriptionRefreshLock,
  getSafeCodexSubscriptionConnection,
  insertInitialCodexSubscriptionConnection,
  isCodexConnectionKeyConflict,
  loadCodexSubscriptionSecrets,
  markCodexRefreshRejected,
  normalizeCodexConnectionKey,
  persistCodexChatgptAccountId,
  releaseCodexSubscriptionRefreshLock,
  revokeCodexSubscriptionConnection,
  rotateCodexSubscriptionCredentials,
  updateCodexAccessTokenInPlace,
  wasCodexConnectionRevokedSinceOAuthState,
} from './codexSubscriptionConnection.js'
import {
  type CodexSubscriptionOAuthIntent,
  type CodexSubscriptionOAuthSafeState,
  cancelCodexSubscriptionOAuthState,
  consumeCodexSubscriptionOAuthState,
  expireCodexSubscriptionOAuthState,
  insertCodexSubscriptionOAuthState,
  peekPendingCodexSubscriptionOAuthState,
} from './codexSubscriptionOAuthState.js'

const log = rootLogger.child({ module: 'codex-subscription-oauth' })

export const CODEX_OAUTH_AUTHORIZE_URL = 'https://auth.openai.com/oauth/authorize'
export const CODEX_OAUTH_TOKEN_URL = 'https://auth.openai.com/oauth/token'
/** Prefix shared by the Codex CLI device-auth routes. */
export const CODEX_OAUTH_DEVICE_URL = 'https://auth.openai.com/api/accounts/deviceauth'
export const CODEX_OAUTH_DEVICE_USERCODE_URL = `${CODEX_OAUTH_DEVICE_URL}/usercode`
export const CODEX_OAUTH_DEVICE_TOKEN_URL = `${CODEX_OAUTH_DEVICE_URL}/token`
export const CODEX_OAUTH_DEVICE_VERIFICATION_URI = 'https://auth.openai.com/codex/device'
export const CODEX_OAUTH_DEVICE_CALLBACK_URI = 'https://auth.openai.com/deviceauth/callback'
export const CODEX_OAUTH_REVOKE_URL = 'https://auth.openai.com/oauth/revoke'
export const CODEX_OAUTH_SCOPES = ['openid', 'profile', 'email', 'offline_access'] as const
const DEVICE_CODE_TIMEOUT_SECONDS = 15 * 60

const TOKEN_TIMEOUT_MS = 15_000
const REFRESH_LOCK_TTL_MS = 30_000
const REFRESH_LOCK_POLL_MS = 200
const BROWSER_STATE_TTL_MS = 10 * 60_000
const ACCESS_TOKEN_REFRESH_SKEW_MS = 5 * 60_000

function accessTokenIsUsable(secrets: {
  accessToken?: string | null
  accessTokenExpiresAt?: Date | null
}): boolean {
  if (!secrets.accessToken) return false
  return secrets.accessTokenExpiresAt == null || secrets.accessTokenExpiresAt.getTime() > Date.now()
}

function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms))
}

export type CodexOAuthErrorCode =
  | 'disabled'
  | 'not_connected'
  | 'state_replayed'
  | 'state_expired'
  | 'state_cancelled'
  | 'replacement_required'
  | 'stale_revision'
  | 'refresh_in_flight'
  | 'provider_unavailable'
  | 'no_grant'
  | 'invalid_callback'
  | 'browser_oauth_unregistered'
  | 'fingerprint_in_use'
  | 'connection_mismatch'
  | 'reauth_required'

const CODEX_OAUTH_ERROR_CODES: ReadonlySet<CodexOAuthErrorCode> = new Set([
  'disabled',
  'not_connected',
  'state_replayed',
  'state_expired',
  'state_cancelled',
  'replacement_required',
  'stale_revision',
  'refresh_in_flight',
  'provider_unavailable',
  'no_grant',
  'invalid_callback',
  'browser_oauth_unregistered',
  'fingerprint_in_use',
  'connection_mismatch',
  'reauth_required',
])

export function isCodexOAuthErrorCode(value: string): value is CodexOAuthErrorCode {
  return CODEX_OAUTH_ERROR_CODES.has(value as CodexOAuthErrorCode)
}

export class CodexSubscriptionOAuthError extends Error {
  readonly code: CodexOAuthErrorCode
  /**
   * True when the connection row was written before this error was thrown: a
   * refresh token the vendor rejected moves the row to `reauth_required` and
   * only then does the error propagate, so the caller owes a republish.
   */
  readonly persistedConnectionStatus: boolean

  constructor(
    code: CodexOAuthErrorCode,
    message: string,
    opts: { persistedConnectionStatus?: boolean } = {}
  ) {
    super(message)
    this.name = 'CodexSubscriptionOAuthError'
    this.code = code
    this.persistedConnectionStatus = opts.persistedConnectionStatus === true
  }
}

export type CodexOAuthDeps = {
  db: DbClient
  encryptionKey: Buffer
  fetchFn: typeof fetch
  clientId: string
  redirectUri: string
  enabled: boolean
  connectionKey?: string
}

function connectionKeyOf(deps: CodexOAuthDeps): string {
  return normalizeCodexConnectionKey(deps.connectionKey)
}

function completionConnectionKey(deps: CodexOAuthDeps, stateKey: string): string {
  const target = normalizeCodexConnectionKey(stateKey)
  if (deps.connectionKey !== undefined) {
    const requested = normalizeCodexConnectionKey(deps.connectionKey)
    if (requested !== target) {
      log.warn(
        { event: 'codex_oauth_connection_mismatch', requested, target },
        'OAuth completion key does not match the state'
      )
      throw new CodexSubscriptionOAuthError(
        'connection_mismatch',
        'OAuth state is bound to a different connection'
      )
    }
  }
  return target
}

export type CodexBrowserStartResult = {
  authorizeUrl: string
  state: string
  intent: CodexSubscriptionOAuthIntent
  expiresAt: Date
}

export type CodexDeviceStartResult = {
  userCode: string
  verificationUri: string
  verificationUriComplete: string | null
  intervalSeconds: number
  expiresAt: Date
  state: string
  intent: CodexSubscriptionOAuthIntent
}

export type CodexDevicePollResult =
  | { status: 'pending'; intervalSeconds: number; state: CodexSubscriptionOAuthSafeState }
  | { status: 'slow_down'; intervalSeconds: number; state: CodexSubscriptionOAuthSafeState }
  | { status: 'connected'; connection: CodexSubscriptionSafeConnection }
  | { status: 'expired' }
  | { status: 'denied' }

/** Fail-soft catalog fetch after a grant is persisted. Never throws. */
export type CodexCatalogSyncResult =
  | {
      ok: true
      catalogStatus: 'ready'
      added: number
      refreshed: number
      staled: number
      connection: CodexSubscriptionSafeConnection
    }
  | {
      ok: false
      catalogStatus: Extract<CodexCatalogOutcome, 'auth-rejected' | 'unavailable'> | 'never_synced'
      reason: CodexOAuthErrorCode | 'catalog_sync_failed'
      added?: number
      refreshed?: number
      staled?: number
      connection?: CodexSubscriptionSafeConnection | null
      /**
       * The catalog was not synced but the CONNECTION row was written anyway.
       * `catalogStatus` describes the catalog, so it cannot answer "did the row
       * change?" — only this field can.
       */
      persisted?: boolean
    }

function requireEnabled(deps: CodexOAuthDeps): void {
  if (!deps.enabled) {
    throw new CodexSubscriptionOAuthError('disabled', 'Codex subscription is disabled')
  }
}

export async function getCodexSubscriptionConnection(
  deps: CodexOAuthDeps
): Promise<CodexSubscriptionSafeConnection | { connectionKey: string; status: 'disconnected' }> {
  requireEnabled(deps)
  const row = await getSafeCodexSubscriptionConnection(deps.db, connectionKeyOf(deps))
  return row ?? { connectionKey: connectionKeyOf(deps), status: 'disconnected' }
}

export async function startCodexBrowserConnect(
  deps: CodexOAuthDeps,
  intent: CodexSubscriptionOAuthIntent = 'connect'
): Promise<CodexBrowserStartResult> {
  requireEnabled(deps)
  const state = randomBytes(24).toString('base64url')
  const pkceVerifier = randomBytes(32).toString('base64url')
  const expiresAt = new Date(Date.now() + BROWSER_STATE_TTL_MS)
  const safe = await insertCodexSubscriptionOAuthState(deps.db, deps.encryptionKey, {
    state,
    flow: 'browser',
    intent,
    pkceVerifier,
    expiresAt,
    connectionKey: connectionKeyOf(deps),
  })
  const challenge = createHash('sha256').update(pkceVerifier).digest('base64url')
  const url = new URL(CODEX_OAUTH_AUTHORIZE_URL)
  url.searchParams.set('response_type', 'code')
  url.searchParams.set('client_id', deps.clientId)
  url.searchParams.set('redirect_uri', deps.redirectUri)
  url.searchParams.set('scope', CODEX_OAUTH_SCOPES.join(' '))
  url.searchParams.set('state', state)
  url.searchParams.set('code_challenge', challenge)
  url.searchParams.set('code_challenge_method', 'S256')
  log.info({ event: 'codex_oauth_browser_start', intent: safe.intent }, 'browser OAuth start')
  return { authorizeUrl: url.toString(), state, intent: safe.intent, expiresAt: safe.expiresAt }
}

export async function startCodexDeviceConnect(
  deps: CodexOAuthDeps,
  intent: CodexSubscriptionOAuthIntent = 'connect'
): Promise<CodexDeviceStartResult> {
  requireEnabled(deps)
  const started = await postJson(deps, CODEX_OAUTH_DEVICE_USERCODE_URL, {
    client_id: deps.clientId,
  })
  if (!started.ok) {
    throw new CodexSubscriptionOAuthError('provider_unavailable', 'device authorization failed')
  }
  const body = started.body
  const deviceAuthId = requiredString(body.device_auth_id, 'device_auth_id')
  const userCode = requiredString(body.user_code ?? body.usercode, 'user_code')
  const intervalSeconds = parsePositiveNumber(body.interval, 5)
  const expiresAt = parseDeviceExpiry(body)
  const state = randomBytes(24).toString('base64url')
  const safe = await insertCodexSubscriptionOAuthState(deps.db, deps.encryptionKey, {
    state,
    flow: 'device',
    intent,
    deviceCode: encodeDeviceAuthHandle({ deviceAuthId, userCode }),
    expiresAt,
    connectionKey: connectionKeyOf(deps),
  })
  log.info({ event: 'codex_oauth_device_start', intent: safe.intent }, 'device OAuth start')
  return {
    userCode,
    verificationUri: CODEX_OAUTH_DEVICE_VERIFICATION_URI,
    verificationUriComplete: null,
    intervalSeconds,
    expiresAt: safe.expiresAt,
    state,
    intent: safe.intent,
  }
}

export async function handleCodexBrowserCallback(
  deps: CodexOAuthDeps,
  input: { code: string; state: string }
): Promise<CodexSubscriptionSafeConnection> {
  requireEnabled(deps)
  if (!input.code || !input.state) {
    throw new CodexSubscriptionOAuthError('invalid_callback', 'missing code or state')
  }
  const consumed = await consumeCodexSubscriptionOAuthState(
    deps.db,
    deps.encryptionKey,
    input.state
  )
  if (!consumed) {
    throw new CodexSubscriptionOAuthError('state_replayed', 'OAuth state is not reusable')
  }
  if (consumed.safe.flow !== 'browser' || !consumed.pkceVerifier) {
    throw new CodexSubscriptionOAuthError('invalid_callback', 'state is not a browser PKCE flow')
  }
  const token = await exchangeAuthorizationCode(deps, input.code, consumed.pkceVerifier)
  return persistGrantedTokens(
    deps,
    consumed.safe.intent,
    token,
    completionConnectionKey(deps, consumed.safe.connectionKey),
    input.state
  )
}

export async function pollCodexDevice(
  deps: CodexOAuthDeps,
  state: string
): Promise<CodexDevicePollResult> {
  requireEnabled(deps)
  const pending = await peekPendingCodexSubscriptionOAuthState(deps.db, deps.encryptionKey, state)
  if (!pending) {
    throw new CodexSubscriptionOAuthError('state_replayed', 'device state is not pending')
  }
  completionConnectionKey(deps, pending.safe.connectionKey)
  if (pending.safe.expiresAt.getTime() <= Date.now()) {
    await expireCodexSubscriptionOAuthState(deps.db, state)
    return { status: 'expired' }
  }
  const handle = decodeDeviceAuthHandle(pending.deviceCode)
  if (!handle) {
    throw new CodexSubscriptionOAuthError(
      'invalid_callback',
      'device state is missing a device auth handle'
    )
  }
  const tokenResult = await pollDeviceAuthorization(deps, handle)
  if (tokenResult.kind === 'pending') {
    return { status: 'pending', intervalSeconds: tokenResult.intervalSeconds, state: pending.safe }
  }
  if (tokenResult.kind === 'slow_down') {
    return {
      status: 'slow_down',
      intervalSeconds: tokenResult.intervalSeconds,
      state: pending.safe,
    }
  }
  if (tokenResult.kind === 'expired') {
    await expireCodexSubscriptionOAuthState(deps.db, state)
    return { status: 'expired' }
  }
  if (tokenResult.kind === 'denied') {
    await cancelCodexSubscriptionOAuthState(deps.db, state)
    return { status: 'denied' }
  }
  const consumed = await consumeCodexSubscriptionOAuthState(deps.db, deps.encryptionKey, state)
  if (!consumed) {
    throw new CodexSubscriptionOAuthError(
      'state_replayed',
      'device state was consumed concurrently'
    )
  }
  const connection = await persistGrantedTokens(
    deps,
    consumed.safe.intent,
    tokenResult.parsed,
    completionConnectionKey(deps, consumed.safe.connectionKey),
    state
  )
  return { status: 'connected', connection }
}

export async function refreshCodexSubscriptionConnection(
  deps: CodexOAuthDeps
): Promise<CodexSubscriptionSafeConnection> {
  requireEnabled(deps)
  const key = connectionKeyOf(deps)
  const current = await getSafeCodexSubscriptionConnection(deps.db, key)
  if (!current || current.status === 'revoked' || current.status === 'disconnected') {
    throw new CodexSubscriptionOAuthError('not_connected', 'no active Codex subscription')
  }
  const lockToken = randomBytes(16).toString('hex')
  const locked = await acquireCodexSubscriptionRefreshLock(
    deps.db,
    lockToken,
    REFRESH_LOCK_TTL_MS,
    key
  )
  if (!locked) {
    throw new CodexSubscriptionOAuthError('refresh_in_flight', 'another refresh holds the lock')
  }
  try {
    const secrets = await loadCodexSubscriptionSecrets(deps.db, deps.encryptionKey, key)
    if (!secrets)
      throw new CodexSubscriptionOAuthError('no_grant', 'encrypted refresh token missing')
    const token = await exchangeRefreshToken(deps, secrets.refreshToken, {
      expectedRevision: secrets.credentialRevision,
      connectionKey: key,
      lockToken,
    })
    try {
      return await rotateCodexSubscriptionCredentials(
        deps.db,
        deps.encryptionKey,
        secrets.credentialRevision,
        {
          refreshToken: token.refreshToken ?? secrets.refreshToken,
          accessToken: token.accessToken,
          accessTokenExpiresAt: token.expiresAt,
          chatgptAccountId: token.chatgptAccountId,
          accountFingerprint: token.accountFingerprint,
        },
        key
      )
    } catch (err) {
      if (err instanceof CodexSubscriptionStaleRevisionError) {
        throw new CodexSubscriptionOAuthError('stale_revision', 'refresh lost the credential race')
      }
      if (err instanceof CodexSubscriptionFingerprintConflictError) {
        throw new CodexSubscriptionOAuthError(
          'fingerprint_in_use',
          'a live Codex subscription already uses this ChatGPT account'
        )
      }
      throw err
    }
  } finally {
    await releaseCodexSubscriptionRefreshLock(deps.db, lockToken, key)
  }
}

export async function revokeCodexSubscription(
  deps: CodexOAuthDeps
): Promise<CodexSubscriptionSafeConnection | { connectionKey: string; status: 'disconnected' }> {
  requireEnabled(deps)
  const key = connectionKeyOf(deps)
  const secrets = await loadCodexSubscriptionSecrets(deps.db, deps.encryptionKey, key)
  const local = await revokeCodexSubscriptionConnection(deps.db, key)
  await rebuildLiveCodexUnionAllowlist(deps.db)
  if (secrets?.refreshToken) {
    try {
      const revokePayload: Record<string, string> = {
        token_type_hint: 'refresh_token',
        client_id: deps.clientId,
      }
      revokePayload['token'] = secrets.refreshToken
      await postForm(deps, CODEX_OAUTH_REVOKE_URL, revokePayload)
    } catch (err) {
      log.warn({ event: 'codex_oauth_upstream_revoke_failed', err }, 'upstream revoke failed')
    }
  }
  log.info({ event: 'codex_oauth_revoked_local' }, 'local Codex subscription revoked')
  return local ?? { connectionKey: key, status: 'disconnected' }
}

function revokedDuringAuthorizationError(): CodexSubscriptionOAuthError {
  return new CodexSubscriptionOAuthError(
    'state_cancelled',
    'connection was revoked after this authorization started; start a new connection flow'
  )
}

/**
 * A completion lost a write race on its key. If a revoke landed after this
 * flow's state was created, the authorization was invalidated
 * (state_cancelled); otherwise another writer holds the live row
 * (stale_revision, 409).
 */
async function lostKeyRaceError(
  deps: CodexOAuthDeps,
  key: string,
  state: string,
  message: string
): Promise<CodexSubscriptionOAuthError> {
  if (await wasCodexConnectionRevokedSinceOAuthState(deps.db, key, state)) {
    return revokedDuringAuthorizationError()
  }
  return new CodexSubscriptionOAuthError('stale_revision', message)
}

async function persistGrantedTokens(
  deps: CodexOAuthDeps,
  intent: CodexSubscriptionOAuthIntent,
  parsed: ParsedCodexToken,
  connectionKey: string,
  state: string
): Promise<CodexSubscriptionSafeConnection> {
  const key = normalizeCodexConnectionKey(connectionKey)
  // Revoke cancels pending states, but a completion may already have consumed
  // its state when the revoke landed. That authorization predates the revoke
  // and must not recreate the grant; a flow started after the revoke may.
  if (await wasCodexConnectionRevokedSinceOAuthState(deps.db, key, state)) {
    log.warn(
      { event: 'codex_oauth_completion_revoked', connectionKey: key },
      'OAuth completion predates a revoke of its connection'
    )
    throw revokedDuringAuthorizationError()
  }
  const existing = await getSafeCodexSubscriptionConnection(deps.db, key)
  if (existing?.revokedAt || existing?.status === 'revoked') {
    throw new CodexSubscriptionOAuthError(
      'not_connected',
      'revoked grant cannot be reused; create a new connection'
    )
  }
  if (
    existing?.accountFingerprint &&
    existing.accountFingerprint !== parsed.accountFingerprint &&
    intent !== 'replace'
  ) {
    throw new CodexSubscriptionOAuthError(
      'replacement_required',
      'different account requires an explicit replace intent'
    )
  }
  const write = {
    refreshToken: parsed.refreshToken ?? '',
    accessToken: parsed.accessToken,
    accessTokenExpiresAt: parsed.expiresAt,
    chatgptAccountId: parsed.chatgptAccountId,
    accountFingerprint: parsed.accountFingerprint,
    status: 'connected' as const,
  }
  if (!write.refreshToken) {
    throw new CodexSubscriptionOAuthError(
      'provider_unavailable',
      'token response omitted refresh token'
    )
  }
  if (!existing) {
    try {
      const created = await insertInitialCodexSubscriptionConnection(
        deps.db,
        deps.encryptionKey,
        write,
        key
      )
      log.info({ event: 'codex_oauth_persisted', connectionKey: key }, 'Codex grant persisted')
      return created
    } catch (err) {
      if (isCodexConnectionKeyConflict(err)) {
        throw await lostKeyRaceError(deps, key, state, 'a concurrent grant created this connection')
      }
      if (err instanceof CodexSubscriptionFingerprintConflictError) {
        throw new CodexSubscriptionOAuthError(
          'fingerprint_in_use',
          'a live Codex subscription already uses this ChatGPT account'
        )
      }
      throw err
    }
  }
  try {
    const rotated = await rotateCodexSubscriptionCredentials(
      deps.db,
      deps.encryptionKey,
      existing.credentialRevision,
      write,
      key
    )
    log.info({ event: 'codex_oauth_persisted', connectionKey: key }, 'Codex grant persisted')
    return rotated
  } catch (err) {
    if (err instanceof CodexSubscriptionStaleRevisionError) {
      throw await lostKeyRaceError(deps, key, state, 'connection was replaced concurrently')
    }
    if (err instanceof CodexSubscriptionFingerprintConflictError) {
      throw new CodexSubscriptionOAuthError(
        'fingerprint_in_use',
        'a live Codex subscription already uses this ChatGPT account'
      )
    }
    throw err
  }
}

type ParsedCodexToken = {
  accessToken: string
  refreshToken: string | null
  expiresAt: Date | null
  accountFingerprint: string
  chatgptAccountId?: string
}

/**
 * Refresh the ChatGPT access token without bumping credential_revision.
 * Authorize tickets bind that revision; rotating it after issue invalidates them.
 */
export async function ensureFreshCodexAccessToken(deps: CodexOAuthDeps): Promise<void> {
  requireEnabled(deps)
  const key = connectionKeyOf(deps)
  const secrets = await loadCodexSubscriptionSecrets(deps.db, deps.encryptionKey, key)
  if (!secrets) {
    throw new CodexSubscriptionOAuthError('no_grant', 'encrypted refresh token missing')
  }
  let accountId = secrets.chatgptAccountId || chatgptAccountIdFromJwt(secrets.accessToken)
  const expiring =
    secrets.accessTokenExpiresAt != null &&
    secrets.accessTokenExpiresAt.getTime() - Date.now() < ACCESS_TOKEN_REFRESH_SKEW_MS
  if (secrets.accessToken && !expiring && accountId) {
    if (!secrets.chatgptAccountId) {
      await persistCodexChatgptAccountId(deps.db, deps.encryptionKey, accountId, key)
    }
    return
  }

  let lockToken = randomBytes(16).toString('hex')
  let locked = await acquireCodexSubscriptionRefreshLock(
    deps.db,
    lockToken,
    REFRESH_LOCK_TTL_MS,
    key
  )
  if (!locked) {
    // The winner's upstream token exchange takes seconds. A single 400 ms
    // peek loses every concurrent completion at the hourly expiry boundary.
    const deadline = Date.now() + REFRESH_LOCK_TTL_MS
    while (true) {
      await sleep(REFRESH_LOCK_POLL_MS)
      const latest = await loadCodexSubscriptionSecrets(deps.db, deps.encryptionKey, key)
      if (!latest) {
        throw new CodexSubscriptionOAuthError('no_grant', 'encrypted refresh token missing')
      }
      const waitedAccountId = latest.chatgptAccountId || chatgptAccountIdFromJwt(latest.accessToken)
      if (accessTokenIsUsable(latest)) {
        if (waitedAccountId && !latest.chatgptAccountId) {
          await persistCodexChatgptAccountId(deps.db, deps.encryptionKey, waitedAccountId, key)
        }
        return
      }
      if (Date.now() >= deadline) {
        throw new CodexSubscriptionOAuthError('refresh_in_flight', 'another refresh holds the lock')
      }
      lockToken = randomBytes(16).toString('hex')
      locked = await acquireCodexSubscriptionRefreshLock(
        deps.db,
        lockToken,
        REFRESH_LOCK_TTL_MS,
        key
      )
      if (locked) break
    }
  }
  try {
    const latest = await loadCodexSubscriptionSecrets(deps.db, deps.encryptionKey, key)
    if (!latest) {
      throw new CodexSubscriptionOAuthError('no_grant', 'encrypted refresh token missing')
    }
    const token = await exchangeRefreshToken(deps, latest.refreshToken, {
      expectedRevision: latest.credentialRevision,
      connectionKey: key,
      lockToken,
    })
    accountId = token.chatgptAccountId || chatgptAccountIdFromJwt(token.accessToken) || accountId
    await updateCodexAccessTokenInPlace(
      deps.db,
      deps.encryptionKey,
      latest.credentialRevision,
      {
        accessToken: token.accessToken,
        accessTokenExpiresAt: token.expiresAt,
        refreshToken: token.refreshToken,
        chatgptAccountId: accountId,
      },
      key
    )
  } catch (err) {
    if (err instanceof CodexSubscriptionStaleRevisionError) {
      throw new CodexSubscriptionOAuthError(
        'stale_revision',
        'in-place refresh lost the credential race'
      )
    }
    throw err
  } finally {
    await releaseCodexSubscriptionRefreshLock(deps.db, lockToken, key)
  }
}

/**
 * Fail-soft first catalog fetch after OAuth persist. Never throws: a connected
 * grant stays connected when ChatGPT catalog is unavailable.
 */
export async function runCodexCatalogSync(
  deps: CodexOAuthDeps,
  connectionKey: string,
  transport: CodexCatalogTransport
): Promise<CodexCatalogSyncResult> {
  const key = normalizeCodexConnectionKey(connectionKey)
  try {
    const keyed = { ...deps, connectionKey: key }
    await ensureFreshCodexAccessToken(keyed)
    const secrets = await loadCodexSubscriptionSecrets(deps.db, deps.encryptionKey, key)
    if (!secrets?.accessToken) {
      return { ok: false, catalogStatus: 'never_synced', reason: 'no_grant' }
    }
    const synced = await syncCodexSubscriptionCatalog(deps.db, transport, secrets.accessToken, {
      connectionKey: key,
    })
    if (!synced.connection) {
      return { ok: false, catalogStatus: 'never_synced', reason: 'stale_revision' }
    }
    if (synced.outcome !== 'ready') {
      return {
        ok: false,
        catalogStatus: synced.outcome,
        reason: 'catalog_sync_failed',
        added: synced.added,
        refreshed: synced.refreshed,
        staled: synced.staled,
        connection: synced.connection,
      }
    }
    return {
      ok: true,
      catalogStatus: 'ready',
      added: synced.added,
      refreshed: synced.refreshed,
      staled: synced.staled,
      connection: synced.connection,
    }
  } catch (err) {
    log.warn(
      { err, event: 'codex_catalog_auto_sync_failed', connectionKey: key },
      'automatic catalog sync after grant failed'
    )
    const reason: CodexOAuthErrorCode | 'catalog_sync_failed' =
      err instanceof CodexSubscriptionOAuthError ? err.code : 'catalog_sync_failed'
    const persisted =
      err instanceof CodexSubscriptionOAuthError && err.persistedConnectionStatus === true
    return { ok: false, catalogStatus: 'never_synced', reason, persisted }
  }
}

async function exchangeAuthorizationCode(
  deps: CodexOAuthDeps,
  code: string,
  pkceVerifier: string,
  redirectUri = deps.redirectUri
): Promise<ParsedCodexToken> {
  const result = await postForm(deps, CODEX_OAUTH_TOKEN_URL, {
    grant_type: 'authorization_code',
    code,
    redirect_uri: redirectUri,
    client_id: deps.clientId,
    code_verifier: pkceVerifier,
  })
  if (!result.ok) {
    throw new CodexSubscriptionOAuthError(
      'provider_unavailable',
      'authorization code exchange failed'
    )
  }
  return parseTokenResponse(result.body)
}

/**
 * Both callers hold the refresh lock and pass its token and the revision they
 * read under it, so a rejection can be told apart from a refresh that lost a
 * race.
 */
async function exchangeRefreshToken(
  deps: CodexOAuthDeps,
  refreshToken: string,
  fence: { expectedRevision: number; connectionKey: string; lockToken: string }
): Promise<ParsedCodexToken> {
  const result = await postForm(deps, CODEX_OAUTH_TOKEN_URL, {
    grant_type: 'refresh_token',
    refresh_token: refreshToken,
    client_id: deps.clientId,
  })
  if (!result.ok) {
    if (isPermanentRefreshFailure(result.status, readUpstreamErrorCode(result.body))) {
      const latest = await loadCodexSubscriptionSecrets(
        deps.db,
        deps.encryptionKey,
        fence.connectionKey
      )
      const current = await getSafeCodexSubscriptionConnection(deps.db, fence.connectionKey)
      const lockChanged = !current?.refreshLockHeld
      const revisionChanged = latest?.credentialRevision !== fence.expectedRevision
      if (lockChanged || revisionChanged) {
        throw new CodexSubscriptionOAuthError(
          'stale_revision',
          'refresh rejection observed after a lost refresh race'
        )
      }
      const marked = await markCodexRefreshRejected(
        deps.db,
        fence.connectionKey,
        fence.expectedRevision,
        fence.lockToken
      )
      // The fenced UPDATE matched nothing: the grant was revoked or replaced,
      // or another holder took the lock, after the check above, so this is the
      // same lost race and the row was not written.
      if (!marked) {
        throw new CodexSubscriptionOAuthError(
          'stale_revision',
          'refresh rejection observed after the grant changed'
        )
      }
      // The row is now `reauth_required`. The throw below must not read as
      // "nothing happened": the ConfigMap carries this status, so whoever
      // catches this owes a republish.
      throw new CodexSubscriptionOAuthError('reauth_required', 'refresh token was rejected', {
        persistedConnectionStatus: true,
      })
    }
    throw new CodexSubscriptionOAuthError('provider_unavailable', 'refresh token exchange failed')
  }
  return parseTokenResponse(result.body)
}

type CodexDeviceAuthHandle = {
  deviceAuthId: string
  userCode: string
}

function encodeDeviceAuthHandle(handle: CodexDeviceAuthHandle): string {
  return JSON.stringify(handle)
}

function decodeDeviceAuthHandle(value: string | undefined): CodexDeviceAuthHandle | null {
  if (!value) return null
  try {
    const parsed = JSON.parse(value) as { deviceAuthId?: unknown; userCode?: unknown }
    if (
      typeof parsed.deviceAuthId === 'string' &&
      parsed.deviceAuthId.length > 0 &&
      typeof parsed.userCode === 'string' &&
      parsed.userCode.length > 0
    ) {
      return { deviceAuthId: parsed.deviceAuthId, userCode: parsed.userCode }
    }
  } catch {
    return null
  }
  return null
}

const PERMANENT_REFRESH_ERROR_CODES = new Set([
  'refresh_token_expired',
  'refresh_token_reused',
  'refresh_token_invalidated',
])

/**
 * The rule the official Codex client applies (`classify_refresh_token_failure`
 * in openai/codex `codex-rs/login/src/auth/manager.rs`): any 401, one of the
 * refresh-token codes at any status, or a 400 `invalid_grant`, compared
 * case-insensitively. Every other failure is transient.
 */
function isPermanentRefreshFailure(status: number, upstreamCode: string): boolean {
  const code = upstreamCode.toLowerCase()
  return (
    status === 401 ||
    PERMANENT_REFRESH_ERROR_CODES.has(code) ||
    (status === 400 && code === 'invalid_grant')
  )
}

function readUpstreamErrorCode(body: Record<string, unknown>): string {
  const error = body.error
  if (typeof error === 'string') return error
  if (
    error &&
    typeof error === 'object' &&
    typeof (error as { code?: unknown }).code === 'string'
  ) {
    return (error as { code: string }).code
  }
  return ''
}

async function pollDeviceAuthorization(
  deps: CodexOAuthDeps,
  handle: CodexDeviceAuthHandle
): Promise<
  | { kind: 'ok'; parsed: ParsedCodexToken }
  | { kind: 'pending'; intervalSeconds: number }
  | { kind: 'slow_down'; intervalSeconds: number }
  | { kind: 'expired' }
  | { kind: 'denied' }
> {
  const result = await postJson(deps, CODEX_OAUTH_DEVICE_TOKEN_URL, {
    device_auth_id: handle.deviceAuthId,
    user_code: handle.userCode,
  })
  if (result.ok) {
    const authorizationCode = requiredString(result.body.authorization_code, 'authorization_code')
    const codeVerifier = requiredString(result.body.code_verifier, 'code_verifier')
    return {
      kind: 'ok',
      parsed: await exchangeAuthorizationCode(
        deps,
        authorizationCode,
        codeVerifier,
        CODEX_OAUTH_DEVICE_CALLBACK_URI
      ),
    }
  }
  if (result.status === 403 || result.status === 404) {
    return { kind: 'pending', intervalSeconds: parsePositiveNumber(result.body.interval, 5) }
  }
  const error = readUpstreamErrorCode(result.body)
  if (error === 'authorization_pending' || error === 'deviceauth_authorization_pending') {
    return { kind: 'pending', intervalSeconds: parsePositiveNumber(result.body.interval, 5) }
  }
  if (error === 'slow_down') {
    return { kind: 'slow_down', intervalSeconds: parsePositiveNumber(result.body.interval, 10) }
  }
  if (error === 'expired_token' || error === 'deviceauth_expired') return { kind: 'expired' }
  if (error === 'access_denied' || error === 'deviceauth_denied') return { kind: 'denied' }
  throw new CodexSubscriptionOAuthError('provider_unavailable', 'device token poll failed')
}

function parseTokenResponse(body: Record<string, unknown>): ParsedCodexToken {
  const accessToken = requiredString(body.access_token, 'access_token')
  const refreshToken = typeof body.refresh_token === 'string' ? body.refresh_token : null
  const expiresIn = typeof body.expires_in === 'number' ? body.expires_in : null
  const idToken = typeof body.id_token === 'string' ? body.id_token : null
  const subject = subjectFromIdToken(idToken)
  const chatgptAccountId = chatgptAccountIdFromJwt(idToken) || chatgptAccountIdFromJwt(accessToken)
  return {
    accessToken,
    refreshToken,
    expiresAt: expiresIn ? new Date(Date.now() + expiresIn * 1000) : null,
    accountFingerprint: fingerprintAccount(subject),
    ...(chatgptAccountId ? { chatgptAccountId } : {}),
  }
}

function subjectFromIdToken(idToken: string | null): string {
  if (!idToken) {
    throw new CodexSubscriptionOAuthError('invalid_callback', 'token response omitted id_token')
  }
  const parts = idToken.split('.')
  if (parts.length < 2) {
    throw new CodexSubscriptionOAuthError('invalid_callback', 'id_token is malformed')
  }
  try {
    const payload = JSON.parse(Buffer.from(parts[1]!, 'base64url').toString('utf8')) as {
      sub?: unknown
    }
    if (typeof payload.sub !== 'string' || payload.sub.length === 0) {
      throw new Error('missing sub')
    }
    return payload.sub
  } catch {
    throw new CodexSubscriptionOAuthError('invalid_callback', 'id_token subject is unreadable')
  }
}

function fingerprintAccount(subject: string): string {
  return createHash('sha256').update(subject, 'utf8').digest('hex')
}

async function postForm(
  deps: CodexOAuthDeps,
  url: string,
  params: Record<string, string>
): Promise<{ ok: boolean; status: number; body: Record<string, unknown> }> {
  return post(
    deps,
    url,
    'application/x-www-form-urlencoded',
    new URLSearchParams(params).toString()
  )
}

async function postJson(
  deps: CodexOAuthDeps,
  url: string,
  payload: Record<string, string>
): Promise<{ ok: boolean; status: number; body: Record<string, unknown> }> {
  return post(deps, url, 'application/json', JSON.stringify(payload))
}

async function post(
  deps: CodexOAuthDeps,
  url: string,
  contentType: string,
  body: string
): Promise<{ ok: boolean; status: number; body: Record<string, unknown> }> {
  let response: Response
  try {
    response = await deps.fetchFn(url, {
      method: 'POST',
      headers: { 'content-type': contentType, accept: 'application/json' },
      body,
      redirect: 'manual',
      signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
    })
  } catch (err) {
    log.warn({ event: 'codex_oauth_upstream_unreachable', err }, 'Codex OAuth upstream unreachable')
    throw new CodexSubscriptionOAuthError(
      'provider_unavailable',
      'Codex OAuth upstream unreachable'
    )
  }
  if (response.status >= 300 && response.status < 400) {
    log.warn(
      { event: 'codex_oauth_redirect_denied', status: response.status },
      'Codex OAuth upstream returned a redirect'
    )
    throw new CodexSubscriptionOAuthError(
      'provider_unavailable',
      'Codex OAuth upstream returned a redirect'
    )
  }
  const json = (await response.json().catch(() => ({}))) as Record<string, unknown>
  return { ok: response.ok, status: response.status, body: json }
}

function requiredString(value: unknown, field: string): string {
  if (typeof value !== 'string' || value.length === 0) {
    throw new CodexSubscriptionOAuthError('provider_unavailable', `upstream omitted ${field}`)
  }
  return value
}

function parsePositiveNumber(value: unknown, fallback: number): number {
  if (typeof value === 'number' && Number.isFinite(value) && value > 0) return value
  if (typeof value === 'string') {
    const parsed = Number(value.trim())
    if (Number.isFinite(parsed) && parsed > 0) return parsed
  }
  return fallback
}

function parseDeviceExpiry(body: Record<string, unknown>): Date {
  if (typeof body.expires_at === 'string') {
    const parsed = new Date(body.expires_at)
    if (!Number.isNaN(parsed.getTime())) return parsed
  }
  const expiresIn = parsePositiveNumber(body.expires_in, DEVICE_CODE_TIMEOUT_SECONDS)
  return new Date(Date.now() + expiresIn * 1000)
}