Skip to content

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

TypeScript
28.8 KB
Raw Blame
import { createHash, randomBytes } from 'node:crypto'
import type { DbClient } from '../db.js'
import { rootLogger } from '../observability/logger.js'
import {
  type GrokCatalogOutcome,
  type GrokCatalogTransport,
  type GrokTransactionRunner,
  defaultGrokTransactionRunner,
  rebuildLiveGrokUnionAllowlist,
  syncGrokSubscriptionCatalog,
} from './grokSubscriptionCatalog.js'
import {
  GrokSubscriptionConnectionKeyConflictError,
  GrokSubscriptionFingerprintConflictError,
  type GrokSubscriptionSafeConnection,
  GrokSubscriptionStaleRevisionError,
  acquireGrokSubscriptionRefreshLock,
  assertGrokConnectionKey,
  getGrokSubscriptionConnectionIncludingRevoked,
  getSafeGrokSubscriptionConnection,
  insertInitialGrokSubscriptionConnection,
  loadGrokSubscriptionSecrets,
  markGrokRefreshSubjectMismatch,
  persistGrokRefreshCiphertextFirst,
  releaseGrokSubscriptionRefreshLock,
  revokeGrokSubscriptionConnection,
  rotateGrokSubscriptionCredentials,
  updateGrokAccessTokenInPlace,
} from './grokSubscriptionConnection.js'
import {
  type GrokSubscriptionOAuthIntent,
  type GrokSubscriptionOAuthSafeState,
  cancelGrokSubscriptionOAuthState,
  consumeGrokSubscriptionOAuthState,
  expireGrokSubscriptionOAuthState,
  insertGrokSubscriptionOAuthState,
  peekPendingGrokSubscriptionOAuthState,
} from './grokSubscriptionOAuthState.js'

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

export const GROK_OAUTH_DEVICE_URL = 'https://auth.x.ai/oauth2/device/code'
export const GROK_OAUTH_TOKEN_URL = 'https://auth.x.ai/oauth2/token'
export const GROK_OAUTH_REVOKE_URL = 'https://auth.x.ai/oauth2/revoke'
export const GROK_OAUTH_DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code'
/**
 * Exact hosts allowed for the user-facing device verification page. The live
 * xAI device endpoint returns https://accounts.x.ai/oauth2/device (probed
 * 2026-09-18); auth.x.ai stays allowed for the OAuth endpoints' own origin.
 */
export const GROK_OAUTH_VERIFICATION_HOSTS: readonly string[] = ['auth.x.ai', 'accounts.x.ai']
export const GROK_OAUTH_SCOPES = [
  'openid',
  'profile',
  'email',
  'offline_access',
  'grok-cli:access',
  'api:access',
  'conversations:read',
  'conversations:write',
] 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 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 GrokOAuthErrorCode =
  | 'disabled'
  | 'not_connected'
  | 'state_replayed'
  | 'state_expired'
  | 'state_cancelled'
  | 'replacement_required'
  | 'stale_revision'
  | 'refresh_in_flight'
  | 'provider_unavailable'
  | 'no_grant'
  | 'invalid_callback'
  | 'fingerprint_in_use'
  | 'connection_mismatch'
  | 'reauth_required'

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

export function isGrokOAuthErrorCode(value: string): value is GrokOAuthErrorCode {
  return GROK_OAUTH_ERROR_CODES.has(value as GrokOAuthErrorCode)
}

export class GrokSubscriptionOAuthError extends Error {
  readonly code: GrokOAuthErrorCode

  /**
   * True when this throw FOLLOWS a write to the connection row, so the caller
   * must treat the connection as changed even though the operation failed. A
   * rejected refresh token is the case that matters: the row is moved to
   * `reauth_required` and only then does the error propagate, so the runtime
   * snapshot is stale until it is republished.
   */
  readonly persistedConnectionStatus: boolean

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

export type GrokOAuthDeps = {
  db: DbClient
  encryptionKey: Buffer
  fetchFn: typeof fetch
  clientId: string
  enabled: boolean
  connectionKey: string
  /** Transaction runner bound to `db`'s pool; defaults to the Control API pool. */
  withTransaction?: GrokTransactionRunner
}

function connectionKeyOf(deps: GrokOAuthDeps): string {
  return assertGrokConnectionKey(deps.connectionKey)
}

function completionConnectionKey(deps: GrokOAuthDeps, stateKey: string): string {
  const target = assertGrokConnectionKey(stateKey)
  const requested = connectionKeyOf(deps)
  if (requested !== target) {
    log.warn(
      { event: 'grok_oauth_connection_mismatch', requested, target },
      'OAuth completion key does not match the state'
    )
    throw new GrokSubscriptionOAuthError(
      'connection_mismatch',
      'OAuth state is bound to a different connection'
    )
  }
  return target
}

function requireEnabled(deps: GrokOAuthDeps): void {
  if (!deps.enabled) {
    throw new GrokSubscriptionOAuthError('disabled', 'Grok subscription is disabled')
  }
}

function revokedKeyError(): GrokSubscriptionOAuthError {
  return new GrokSubscriptionOAuthError(
    'not_connected',
    'revoked grant cannot be reused; create a new connection'
  )
}

function isRevoked(connection: GrokSubscriptionSafeConnection | null | undefined): boolean {
  return Boolean(connection?.revokedAt || connection?.status === 'revoked')
}

/** Revocation is terminal per key: no OAuth work may start or finish on a tombstone. */
async function assertKeyNotRevoked(deps: GrokOAuthDeps, key: string): Promise<void> {
  if (isRevoked(await getGrokSubscriptionConnectionIncludingRevoked(deps.db, key))) {
    throw revokedKeyError()
  }
}

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

export type GrokDevicePollResult =
  | {
      status: 'pending' | 'slow_down'
      intervalSeconds: number
      state: GrokSubscriptionOAuthSafeState
    }
  | { status: 'expired' | 'denied' }
  | { status: 'connected'; connection: GrokSubscriptionSafeConnection }

export type GrokCatalogSyncResult =
  | { ok: true; catalogStatus: 'ready'; connection: GrokSubscriptionSafeConnection }
  | {
      ok: false
      catalogStatus: GrokCatalogOutcome | 'never_synced'
      reason?: GrokOAuthErrorCode | 'catalog_sync_failed' | 'stale_revision' | 'no_grant'
      /**
       * 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
    }

export async function getGrokSubscriptionConnection(
  deps: GrokOAuthDeps
): Promise<GrokSubscriptionSafeConnection | { connectionKey: string; status: 'disconnected' }> {
  requireEnabled(deps)
  const row = await getSafeGrokSubscriptionConnection(deps.db, connectionKeyOf(deps))
  return row ?? { connectionKey: connectionKeyOf(deps), status: 'disconnected' }
}

export async function startGrokDeviceConnect(
  deps: GrokOAuthDeps,
  intent: GrokSubscriptionOAuthIntent = 'connect'
): Promise<GrokDeviceStartResult> {
  requireEnabled(deps)
  const connectionKey = connectionKeyOf(deps)
  await assertKeyNotRevoked(deps, connectionKey)
  const started = await postForm(deps, GROK_OAUTH_DEVICE_URL, {
    client_id: deps.clientId,
    scope: GROK_OAUTH_SCOPES.join(' '),
  })
  if (!started.ok) {
    throw new GrokSubscriptionOAuthError('provider_unavailable', 'device authorization failed')
  }
  const body = started.body
  const deviceCode = requiredString(body.device_code, 'device_code')
  const userCode = requiredString(body.user_code, 'user_code')
  const verificationUri = assertVerificationUri(
    typeof body.verification_uri === 'string' ? body.verification_uri : ''
  )
  const verificationUriComplete =
    typeof body.verification_uri_complete === 'string' && body.verification_uri_complete
      ? assertVerificationUri(body.verification_uri_complete)
      : null
  const intervalSeconds = parsePositiveNumber(body.interval, 5)
  const expiresAt = parseDeviceExpiry(body)
  const state = randomBytes(24).toString('base64url')
  const safe = await insertGrokSubscriptionOAuthState(deps.db, deps.encryptionKey, {
    state,
    intent,
    deviceCode,
    expiresAt,
    connectionKey,
  })
  log.info({ event: 'grok_oauth_device_start', intent: safe.intent }, 'device OAuth start')
  return {
    userCode,
    verificationUri,
    verificationUriComplete,
    intervalSeconds,
    expiresAt: safe.expiresAt,
    state,
    intent: safe.intent,
  }
}

export async function pollGrokDevice(
  deps: GrokOAuthDeps,
  state: string
): Promise<GrokDevicePollResult> {
  requireEnabled(deps)
  await assertKeyNotRevoked(deps, connectionKeyOf(deps))
  const pending = await peekPendingGrokSubscriptionOAuthState(deps.db, deps.encryptionKey, state)
  if (!pending) {
    throw new GrokSubscriptionOAuthError('state_replayed', 'device state is not pending')
  }
  completionConnectionKey(deps, pending.safe.connectionKey)
  if (pending.safe.expiresAt.getTime() <= Date.now()) {
    await expireGrokSubscriptionOAuthState(deps.db, state)
    return { status: 'expired' }
  }
  if (!pending.deviceCode) {
    throw new GrokSubscriptionOAuthError(
      'invalid_callback',
      'device state is missing a device code'
    )
  }
  const tokenResult = await pollDeviceAuthorization(deps, pending.deviceCode)
  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 expireGrokSubscriptionOAuthState(deps.db, state)
    return { status: 'expired' }
  }
  if (tokenResult.kind === 'denied') {
    await cancelGrokSubscriptionOAuthState(deps.db, state)
    return { status: 'denied' }
  }
  const consumed = await consumeGrokSubscriptionOAuthState(deps.db, deps.encryptionKey, state)
  if (!consumed) {
    throw new GrokSubscriptionOAuthError('state_replayed', 'device state was consumed concurrently')
  }
  const connection = await persistGrantedTokens(
    deps,
    consumed.safe.intent,
    tokenResult.parsed,
    completionConnectionKey(deps, consumed.safe.connectionKey)
  )
  return { status: 'connected', connection }
}

export async function refreshGrokSubscriptionConnection(
  deps: GrokOAuthDeps
): Promise<GrokSubscriptionSafeConnection> {
  requireEnabled(deps)
  const key = connectionKeyOf(deps)
  const current = await getSafeGrokSubscriptionConnection(deps.db, key)
  if (!current || current.status === 'revoked' || current.status === 'disconnected') {
    throw new GrokSubscriptionOAuthError('not_connected', 'no active Grok subscription')
  }
  const lockToken = randomBytes(16).toString('hex')
  const locked = await acquireGrokSubscriptionRefreshLock(
    deps.db,
    lockToken,
    REFRESH_LOCK_TTL_MS,
    key
  )
  if (!locked) {
    throw new GrokSubscriptionOAuthError('refresh_in_flight', 'another refresh holds the lock')
  }
  try {
    return await rotateLockedRefresh(deps, key, lockToken)
  } finally {
    await releaseGrokSubscriptionRefreshLock(deps.db, lockToken, key)
  }
}

export async function revokeGrokSubscription(
  deps: GrokOAuthDeps
): Promise<GrokSubscriptionSafeConnection | { connectionKey: string; status: 'disconnected' }> {
  requireEnabled(deps)
  const key = connectionKeyOf(deps)
  const secrets = await loadGrokSubscriptionSecrets(deps.db, deps.encryptionKey, key)
  const runInTransaction = deps.withTransaction ?? defaultGrokTransactionRunner
  const local = await runInTransaction(async tx => {
    const revoked = await revokeGrokSubscriptionConnection(tx, key)
    await rebuildLiveGrokUnionAllowlist(tx)
    return revoked
  })
  if (secrets?.refreshToken) {
    try {
      await postForm(deps, GROK_OAUTH_REVOKE_URL, {
        token_type_hint: 'refresh_token',
        client_id: deps.clientId,
        token: secrets.refreshToken,
      })
    } catch (err) {
      log.warn({ event: 'grok_oauth_upstream_revoke_failed', err }, 'upstream revoke failed')
    }
  }
  log.info({ event: 'grok_oauth_revoked_local' }, 'local Grok subscription revoked')
  return local ?? { connectionKey: key, status: 'disconnected' }
}

export async function ensureFreshGrokAccessToken(deps: GrokOAuthDeps): Promise<void> {
  requireEnabled(deps)
  const key = connectionKeyOf(deps)
  const secrets = await loadGrokSubscriptionSecrets(deps.db, deps.encryptionKey, key)
  if (!secrets) {
    throw new GrokSubscriptionOAuthError('no_grant', 'encrypted refresh token missing')
  }
  const expiring =
    secrets.accessTokenExpiresAt != null &&
    secrets.accessTokenExpiresAt.getTime() - Date.now() < ACCESS_TOKEN_REFRESH_SKEW_MS
  if (secrets.accessToken && !expiring) return

  let lockToken = randomBytes(16).toString('hex')
  let locked = await acquireGrokSubscriptionRefreshLock(
    deps.db,
    lockToken,
    REFRESH_LOCK_TTL_MS,
    key
  )
  if (!locked) {
    const deadline = Date.now() + REFRESH_LOCK_TTL_MS
    while (true) {
      await sleep(REFRESH_LOCK_POLL_MS)
      const latest = await loadGrokSubscriptionSecrets(deps.db, deps.encryptionKey, key)
      if (!latest) {
        throw new GrokSubscriptionOAuthError('no_grant', 'encrypted refresh token missing')
      }
      if (accessTokenIsUsable(latest)) return
      if (Date.now() >= deadline) {
        throw new GrokSubscriptionOAuthError('refresh_in_flight', 'another refresh holds the lock')
      }
      lockToken = randomBytes(16).toString('hex')
      locked = await acquireGrokSubscriptionRefreshLock(
        deps.db,
        lockToken,
        REFRESH_LOCK_TTL_MS,
        key
      )
      if (locked) break
    }
  }
  try {
    await rotateLockedRefresh(deps, key, lockToken)
  } finally {
    await releaseGrokSubscriptionRefreshLock(deps.db, lockToken, key)
  }
}

export async function runGrokCatalogSync(
  deps: GrokOAuthDeps,
  connectionKey: string,
  transport: GrokCatalogTransport
): Promise<GrokCatalogSyncResult> {
  const key = assertGrokConnectionKey(connectionKey)
  try {
    const keyed = { ...deps, connectionKey: key }
    await ensureFreshGrokAccessToken(keyed)
    const secrets = await loadGrokSubscriptionSecrets(deps.db, deps.encryptionKey, key)
    if (!secrets?.accessToken) {
      return { ok: false, catalogStatus: 'never_synced', reason: 'no_grant' }
    }
    const synced = await syncGrokSubscriptionCatalog(
      deps.db,
      transport,
      secrets.accessToken,
      { connectionKey: key },
      { withTransaction: deps.withTransaction }
    )
    if (!synced.connection) {
      return { ok: false, catalogStatus: 'never_synced', reason: 'stale_revision' }
    }
    if (synced.outcome !== 'ready') {
      return { ok: false, catalogStatus: synced.outcome }
    }
    return { ok: true, catalogStatus: 'ready', connection: synced.connection }
  } catch (err) {
    log.warn(
      { err, event: 'grok_catalog_auto_sync_failed', connectionKey: key },
      'automatic catalog sync after grant failed'
    )
    const reason: GrokOAuthErrorCode | 'catalog_sync_failed' =
      err instanceof GrokSubscriptionOAuthError ? err.code : 'catalog_sync_failed'
    const persisted =
      err instanceof GrokSubscriptionOAuthError && err.persistedConnectionStatus === true
    return { ok: false, catalogStatus: 'never_synced', reason, persisted }
  }
}

async function rotateLockedRefresh(
  deps: GrokOAuthDeps,
  key: string,
  lockToken: string
): Promise<GrokSubscriptionSafeConnection> {
  const secrets = await loadGrokSubscriptionSecrets(deps.db, deps.encryptionKey, key)
  if (!secrets) {
    throw new GrokSubscriptionOAuthError('no_grant', 'encrypted refresh token missing')
  }
  const current = await getSafeGrokSubscriptionConnection(deps.db, key)
  const observedRevision = secrets.credentialRevision
  const pair = await exchangeRefreshToken(deps, secrets.refreshToken, {
    expectedRevision: observedRevision,
    lockToken,
    connectionKey: key,
  })
  try {
    const persisted = await persistGrokRefreshCiphertextFirst(deps.db, deps.encryptionKey, {
      connectionKey: key,
      expectedRevision: observedRevision,
      lockToken,
      refreshToken: pair.refreshToken,
    })
    let subject: string
    try {
      subject = subjectFromTokens(pair.idToken, pair.accessToken)
    } catch (err) {
      const marked = await markGrokRefreshSubjectMismatch(
        deps.db,
        key,
        persisted.credentialRevision
      )
      if (marked) return marked
      throw err
    }
    const accountFingerprint = fingerprintAccount(subject)
    if (
      current?.accountFingerprint &&
      accountFingerprint &&
      current.accountFingerprint !== accountFingerprint
    ) {
      const marked = await markGrokRefreshSubjectMismatch(
        deps.db,
        key,
        persisted.credentialRevision
      )
      return marked ?? { ...persisted, status: 'reauth_required' }
    }
    return updateGrokAccessTokenInPlace(
      deps.db,
      deps.encryptionKey,
      persisted.credentialRevision,
      {
        accessToken: pair.accessToken,
        accessTokenExpiresAt: pair.expiresAt,
      },
      key,
      lockToken
    )
  } catch (err) {
    if (err instanceof GrokSubscriptionStaleRevisionError) {
      throw new GrokSubscriptionOAuthError('stale_revision', 'refresh lost the credential race')
    }
    throw err
  }
}

async function persistGrantedTokens(
  deps: GrokOAuthDeps,
  intent: GrokSubscriptionOAuthIntent,
  parsed: ParsedGrokToken,
  connectionKey: string
): Promise<GrokSubscriptionSafeConnection> {
  const key = assertGrokConnectionKey(connectionKey)
  // Tombstone-aware: a key revoked after this flow started must not be revived.
  const existing = await getGrokSubscriptionConnectionIncludingRevoked(deps.db, key)
  if (isRevoked(existing)) throw revokedKeyError()
  if (
    existing?.accountFingerprint &&
    existing.accountFingerprint !== parsed.accountFingerprint &&
    intent !== 'replace'
  ) {
    throw new GrokSubscriptionOAuthError(
      'replacement_required',
      'different account requires an explicit replace intent'
    )
  }
  const write = {
    refreshToken: parsed.refreshToken,
    accessToken: parsed.accessToken,
    accessTokenExpiresAt: parsed.expiresAt,
    accountFingerprint: parsed.accountFingerprint,
    status: 'connected' as const,
  }
  if (!existing) {
    try {
      const created = await insertInitialGrokSubscriptionConnection(
        deps.db,
        deps.encryptionKey,
        write,
        key
      )
      log.info({ event: 'grok_oauth_persisted', connectionKey: key }, 'Grok grant persisted')
      return created
    } catch (err) {
      if (err instanceof GrokSubscriptionConnectionKeyConflictError) {
        throw await lostKeyRaceError(deps, key, 'a concurrent grant created this connection')
      }
      if (err instanceof GrokSubscriptionFingerprintConflictError) {
        throw new GrokSubscriptionOAuthError(
          'fingerprint_in_use',
          'a live Grok subscription already uses this account'
        )
      }
      throw err
    }
  }
  try {
    const rotated = await rotateGrokSubscriptionCredentials(
      deps.db,
      deps.encryptionKey,
      existing.credentialRevision,
      write,
      key
    )
    log.info({ event: 'grok_oauth_persisted', connectionKey: key }, 'Grok grant persisted')
    return rotated
  } catch (err) {
    if (err instanceof GrokSubscriptionStaleRevisionError) {
      throw await lostKeyRaceError(deps, key, 'connection was replaced concurrently')
    }
    if (err instanceof GrokSubscriptionFingerprintConflictError) {
      throw new GrokSubscriptionOAuthError(
        'fingerprint_in_use',
        'a live Grok subscription already uses this account'
      )
    }
    throw err
  }
}

/**
 * A completion lost a write race on its key. If the winner was a revoke, the
 * key is a terminal tombstone (not_connected); otherwise another writer holds
 * the live row (stale_revision, 409).
 */
async function lostKeyRaceError(
  deps: GrokOAuthDeps,
  key: string,
  message: string
): Promise<GrokSubscriptionOAuthError> {
  const latest = await getGrokSubscriptionConnectionIncludingRevoked(deps.db, key)
  if (isRevoked(latest)) return revokedKeyError()
  return new GrokSubscriptionOAuthError('stale_revision', message)
}

type GrokTokenPair = {
  accessToken: string
  refreshToken: string
  expiresAt: Date | null
  idToken: string | null
}

type ParsedGrokToken = GrokTokenPair & {
  accountFingerprint: string
}

async function pollDeviceAuthorization(
  deps: GrokOAuthDeps,
  deviceCode: string
): Promise<
  | { kind: 'ok'; parsed: ParsedGrokToken }
  | { kind: 'pending'; intervalSeconds: number }
  | { kind: 'slow_down'; intervalSeconds: number }
  | { kind: 'expired' }
  | { kind: 'denied' }
> {
  const result = await postForm(deps, GROK_OAUTH_TOKEN_URL, {
    grant_type: GROK_OAUTH_DEVICE_GRANT,
    device_code: deviceCode,
    client_id: deps.clientId,
  })
  if (result.ok) {
    return { kind: 'ok', parsed: parseTokenResponse(result.body, { requireRefresh: true }) }
  }
  const error = readUpstreamErrorCode(result.body)
  if (error === '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') return { kind: 'expired' }
  if (error === 'access_denied') return { kind: 'denied' }
  if (result.status === 403) {
    throw new GrokSubscriptionOAuthError(
      'provider_unavailable',
      'device token poll was entitlement-denied'
    )
  }
  throw new GrokSubscriptionOAuthError('provider_unavailable', 'device token poll failed')
}

async function exchangeRefreshToken(
  deps: GrokOAuthDeps,
  refreshToken: string,
  fence: { expectedRevision: number; lockToken: string; connectionKey: string }
): Promise<GrokTokenPair> {
  const result = await postForm(deps, GROK_OAUTH_TOKEN_URL, {
    grant_type: 'refresh_token',
    refresh_token: refreshToken,
    client_id: deps.clientId,
  })
  if (result.status === 402 || result.status === 403) {
    throw new GrokSubscriptionOAuthError('provider_unavailable', 'refresh was entitlement-denied')
  }
  if (!result.ok) {
    const error = readUpstreamErrorCode(result.body)
    if ((result.status === 400 || result.status === 401) && error === 'invalid_grant') {
      const latest = await loadGrokSubscriptionSecrets(
        deps.db,
        deps.encryptionKey,
        fence.connectionKey
      )
      const current = await getSafeGrokSubscriptionConnection(deps.db, fence.connectionKey)
      const lockChanged = !current?.refreshLockHeld
      const revisionChanged = latest?.credentialRevision !== fence.expectedRevision
      if (lockChanged || revisionChanged) {
        throw new GrokSubscriptionOAuthError(
          'stale_revision',
          'invalid_grant observed after a lost refresh race'
        )
      }
      await markGrokRefreshSubjectMismatch(deps.db, fence.connectionKey, fence.expectedRevision)
      // 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 GrokSubscriptionOAuthError('reauth_required', 'refresh token was rejected', {
        persistedConnectionStatus: true,
      })
    }
    throw new GrokSubscriptionOAuthError('provider_unavailable', 'refresh token exchange failed')
  }
  return readGrokTokenPair(result.body, { requireRefresh: true })
}

function readGrokTokenPair(
  body: Record<string, unknown>,
  opts: { requireRefresh: boolean }
): GrokTokenPair {
  const accessToken = requiredString(body.access_token, 'access_token')
  const refreshToken = typeof body.refresh_token === 'string' ? body.refresh_token : ''
  if (opts.requireRefresh && !refreshToken) {
    throw new GrokSubscriptionOAuthError(
      'provider_unavailable',
      'token response omitted refresh_token'
    )
  }
  const expiresIn = typeof body.expires_in === 'number' ? body.expires_in : null
  const idToken = typeof body.id_token === 'string' ? body.id_token : null
  return {
    accessToken,
    refreshToken,
    expiresAt: expiresIn ? new Date(Date.now() + expiresIn * 1000) : null,
    idToken,
  }
}

function parseTokenResponse(
  body: Record<string, unknown>,
  opts: { requireRefresh: boolean }
): ParsedGrokToken {
  const pair = readGrokTokenPair(body, opts)
  return {
    ...pair,
    accountFingerprint: fingerprintAccount(subjectFromTokens(pair.idToken, pair.accessToken)),
  }
}

function subjectFromTokens(idToken: string | null, accessToken: string): string {
  const fromId = subjectFromJwt(idToken)
  if (fromId) return fromId
  const fromAccess = subjectFromJwt(accessToken)
  if (fromAccess) return fromAccess
  throw new GrokSubscriptionOAuthError('invalid_callback', 'token response omitted a subject')
}

function subjectFromJwt(token: string | null): string | null {
  if (!token) return null
  const parts = token.split('.')
  if (parts.length < 2) return null
  try {
    const payload = JSON.parse(Buffer.from(parts[1]!, 'base64url').toString('utf8')) as {
      sub?: unknown
    }
    if (typeof payload.sub === 'string' && payload.sub.length > 0) return payload.sub
  } catch {
    return null
  }
  return null
}

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

function assertVerificationUri(value: string): string {
  let parsed: URL
  try {
    parsed = new URL(value)
  } catch {
    throw new GrokSubscriptionOAuthError(
      'provider_unavailable',
      'device verification URI is invalid'
    )
  }
  if (parsed.protocol !== 'https:' || !GROK_OAUTH_VERIFICATION_HOSTS.includes(parsed.hostname)) {
    throw new GrokSubscriptionOAuthError(
      'provider_unavailable',
      'device verification URI origin is not frozen'
    )
  }
  return parsed.toString()
}

async function postForm(
  deps: GrokOAuthDeps,
  url: string,
  params: Record<string, string>
): Promise<{ ok: boolean; status: number; body: Record<string, unknown> }> {
  return post(deps, url, new URLSearchParams(params).toString())
}

async function post(
  deps: GrokOAuthDeps,
  url: 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': 'application/x-www-form-urlencoded',
        accept: 'application/json',
      },
      body,
      redirect: 'manual',
      signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
    })
  } catch (err) {
    log.warn({ event: 'grok_oauth_upstream_unreachable', err }, 'Grok OAuth upstream unreachable')
    throw new GrokSubscriptionOAuthError('provider_unavailable', 'Grok OAuth upstream unreachable')
  }
  if (response.status >= 300 && response.status < 400) {
    log.warn(
      { event: 'grok_oauth_redirect_denied', status: response.status },
      'Grok OAuth upstream returned a redirect'
    )
    throw new GrokSubscriptionOAuthError(
      'provider_unavailable',
      'Grok 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) return value
  throw new GrokSubscriptionOAuthError('provider_unavailable', `upstream omitted ${field}`)
}

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 ''
}

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)
}