Skip to content

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

TypeScript
16.7 KB
Raw Blame
import type { DbClient } from '../db.js'
import type { PinnedTransport } from '../http/pinnedFetch.js'
import type { DnsResolver } from '../http/validateMcpServerSpec.js'
import { remoteWireForProfile } from './asProfiles.js'
import {
  type OAuthClientDecl,
  RecipeNotFoundError,
  type RecipeReader,
  type RecipeWithOAuthClients,
  SecretNotFoundError,
  type SecretReader,
  postRemoteTokenForm,
  resolveRemoteClientCredential,
} from './callback.js'
import {
  type ParsedTokenResponse,
  buildAdapterFromConfig,
  buildRemoteRefreshRequest,
  getOAuthProviderAdapter,
  isKnownOAuthProvider,
  parseRemoteTokenResponse,
} from './providers.js'
import {
  type OAuthGrantKey,
  getOAuthGrant,
  refreshOAuthGrantTokens,
  resolveOwnerKind,
} from './store.js'

/**
 * Fetch the current access token for a grant (user or service), refreshing on
 * demand using the stored refresh token. Refresh tokens never leave
 * control-api; only the freshly-minted access token is returned.
 *
 * Callers: the cookie-authed `POST /sandbox-ui/oauth/token` endpoint for `user`
 * grants (spec §9.9), and the broker route `POST /api/v1/recipe-oauth/token`
 * for `service` grants (Path B, spec §10).
 *
 * CONCURRENCY GUARD-RAIL: this is the UNLOCKED refresh engine. It must only be
 * called (a) with a `deps.db` that already holds this grant's row lock inside an
 * open transaction — the proactive cron and {@link getAccessTokenReactive} do
 * exactly this — or (b) via {@link getAccessTokenReactive}, which takes the row
 * lock for you. A direct reactive call on a loose pool client re-opens the
 * double-spend hole (two POSTs with the same rotating refresh token → the AS kills
 * the grant). Reactive callers use {@link getAccessTokenReactive}, never this.
 */

/**
 * Reactive refresh buffer (Br): a stored access token is treated as stale, and
 * refreshed on demand, once it is within this window of expiry. The default when
 * a caller passes no `refreshBufferMs`. Exported so the proactive buffer (Bp) can
 * be validated `Bp > Br` at config load (mini-spec L §3) against the SAME source
 * of truth the reactive path uses — never a re-typed literal.
 */
export const REACTIVE_REFRESH_BUFFER_MS = 60_000

/**
 * A stored access token is "stale" — due for refresh — once it sits within
 * `refreshBufferMs` of expiry. A grant with no known expiry (`accessTokenExpiresAt`
 * absent) is never stale: there is nothing to refresh against. Single source of
 * truth for the staleness rule (regla D4): both the reactive fast-path
 * ({@link getAccessTokenReactive}) and the engine ({@link getAccessToken}) call
 * this, so they can never disagree on what "stale" means.
 */
export function isAccessTokenStale(
  grant: { accessTokenExpiresAt?: Date },
  refreshBufferMs: number
): boolean {
  if (!grant.accessTokenExpiresAt) return false
  return grant.accessTokenExpiresAt.getTime() - refreshBufferMs <= Date.now()
}

export type GetAccessTokenInput = OAuthGrantKey & {
  /**
   * Require a background-consented grant (per-user broker, SEC-5). Parametrized,
   * NOT pinned to `true`: the recipe background broker passes `true`; the
   * interactive mcp-host live-session path (U1) passes `false` (there IS a live
   * session). Honored for `user` and `shared` grants; ignored for `service`.
   */
  requireBackground?: boolean
}

export interface GetAccessTokenDeps {
  db: DbClient
  recipeReader: RecipeReader
  secretReader: SecretReader
  fetchFn: typeof fetch
  encryptionKey: Buffer
  /** How long before expiry we consider the token "stale" and refresh. Default 60s. */
  refreshBufferMs?: number
  /** Token-exchange timeout. Default 15s. */
  refreshTimeoutMs?: number
  /**
   * Remote lane only: injectable DNS resolver + pinned transport for the
   * IP-pinned refresh POST (DEC-17). Production leaves both undefined (real
   * resolve + `node:https`); the baked lane never touches them (keeps `fetchFn`).
   */
  resolveDns?: DnsResolver
  pinnedTransport?: PinnedTransport
}

export type GetAccessTokenResult =
  | { kind: 'ok'; accessToken: string; expiresAt?: Date }
  | { kind: 'no_grant' }
  | { kind: 'recipe_not_found' }
  | { kind: 'unknown_oauth_client' }
  | { kind: 'unsupported_provider'; provider: string }
  | { kind: 'secret_missing'; secret: string }
  | { kind: 'refresh_failed'; status?: number; detail: string }

export async function getAccessToken(
  input: GetAccessTokenInput,
  deps: GetAccessTokenDeps
): Promise<GetAccessTokenResult> {
  const grant = await getOAuthGrant(deps.db, deps.encryptionKey, input)
  if (!grant) return { kind: 'no_grant' }

  const refreshBufferMs = deps.refreshBufferMs ?? REACTIVE_REFRESH_BUFFER_MS
  if (!isAccessTokenStale(grant, refreshBufferMs)) {
    return { kind: 'ok', accessToken: grant.accessToken, expiresAt: grant.accessTokenExpiresAt }
  }

  // Stale → need refresh. Without a refresh token we surface no_grant so the
  // caller treats it as "needs reauth"; the user re-clicks Connect.
  if (!grant.refreshToken) return { kind: 'no_grant' }

  // Resolve recipe + secrets + provider for the refresh exchange.
  let recipe: RecipeWithOAuthClients | null
  try {
    recipe = await deps.recipeReader.read(input.recipeName, input.recipeNamespace)
  } catch (err) {
    if (err instanceof RecipeNotFoundError) return { kind: 'recipe_not_found' }
    throw err
  }
  if (!recipe) return { kind: 'recipe_not_found' }

  // A grant sealed with another installation's uid is inert: the owner was
  // uninstalled and a same-name server now exists. Refreshing it would spend the
  // old refresh token against the new installation's client (and, for DCR, a
  // rejected POST would be misread as the new client being invalid). The fenced
  // reader above cannot catch this when the key came from the row itself (the
  // proactive sweep) or when the CR was replaced after the caller read it.
  const ownerCrUid = recipe.metadata?.uid
  if (grant.crUid !== undefined && grant.crUid !== ownerCrUid) return { kind: 'no_grant' }

  const decl = recipe.spec?.oauthClients?.find(c => c.id === input.oauthClientId)
  if (!decl) return { kind: 'unknown_oauth_client' }

  // Only pods without install identity wrote unsealed rows, and those only spoke
  // the baked lane. The owner CR is re-read here, after the caller built the key,
  // so it may now be another lane or provider; refreshing would send the legacy
  // refresh token to an endpoint nobody consented to. Same rule as the store's
  // reader fence, applied to the CR as it is now.
  if (resolveOwnerKind(input) === 'mcpserver' && grant.crUid === undefined) {
    if (decl.remote || decl.generic || decl.provider !== grant.provider) {
      return { kind: 'no_grant' }
    }
  }

  // Remote lane (`source:'remote'`): discovery-derived refresh over the IP-pinned
  // transport (DEC-17), public token client, credentials per `secretSource`. The
  // baked provider-adapter path is below (unchanged).
  if (decl.remote) {
    // no-refresh derived from pinned metadata (D-8, fail-closed): the AS never
    // advertised `refresh_token`, so treat as "needs reauth" rather than POST a
    // refresh — surfaces `connect_required` in mcp-host. Derived from the flag,
    // NOT heuristically from token presence.
    if (!decl.remote.supportsRefresh) return { kind: 'no_grant' }
    return refreshRemoteGrant(grant.refreshToken, decl, ownerCrUid, input, deps)
  }

  // Generic self-hosted lane (`source:'generic'`, DEC-28): same fail-closed
  // no-refresh gate (D-8) and IP-pinned refresh POST (DEC-17) as the remote lane,
  // but the request is composed from the CR knobs (`buildAdapterFromConfig`).
  if (decl.generic) {
    if (!decl.generic.supportsRefresh) return { kind: 'no_grant' }
    return refreshGenericGrant(grant.refreshToken, decl, ownerCrUid, input, deps)
  }

  if (!isKnownOAuthProvider(decl.provider)) {
    return { kind: 'unsupported_provider', provider: decl.provider }
  }

  // Baked/recipe lane: clientIdRef always present (only remote omits it).
  if (!decl.clientIdRef) {
    return { kind: 'secret_missing', secret: `${decl.id}/client_id` }
  }
  const clientIdRef = decl.clientIdRef

  let clientIdSecret: Record<string, string>
  try {
    clientIdSecret = await deps.secretReader.read(clientIdRef.name, input.recipeNamespace)
  } catch (err) {
    if (err instanceof SecretNotFoundError) {
      return { kind: 'secret_missing', secret: clientIdRef.name }
    }
    throw err
  }
  const clientId = clientIdSecret[clientIdRef.key]
  if (!clientId) {
    return { kind: 'secret_missing', secret: `${clientIdRef.name}/${clientIdRef.key}` }
  }

  // Public client (E-19.2): no clientSecretRef ⇒ refresh without a client_secret.
  // When a ref is present the confidential path is unchanged.
  let clientSecret: string | undefined
  if (decl.clientSecretRef) {
    let clientSecretSecret: Record<string, string>
    try {
      clientSecretSecret = await deps.secretReader.read(
        decl.clientSecretRef.name,
        input.recipeNamespace
      )
    } catch (err) {
      if (err instanceof SecretNotFoundError) {
        return { kind: 'secret_missing', secret: decl.clientSecretRef.name }
      }
      throw err
    }
    clientSecret = clientSecretSecret[decl.clientSecretRef.key]
    if (!clientSecret) {
      return {
        kind: 'secret_missing',
        secret: `${decl.clientSecretRef.name}/${decl.clientSecretRef.key}`,
      }
    }
  }

  const adapter = getOAuthProviderAdapter(decl.provider)
  let refreshRequest: ReturnType<typeof adapter.buildRefreshRequest>
  try {
    refreshRequest = adapter.buildRefreshRequest({
      refreshToken: grant.refreshToken,
      clientId,
      clientSecret,
    })
  } catch (err) {
    return { kind: 'refresh_failed', detail: (err as Error).message }
  }

  let parsed: ParsedTokenResponse
  try {
    const response = await deps.fetchFn(refreshRequest.url, {
      method: refreshRequest.method,
      headers: refreshRequest.headers,
      body: refreshRequest.body,
      signal: AbortSignal.timeout(deps.refreshTimeoutMs ?? 15_000),
    })
    if (!response.ok) {
      const body = (await response.text().catch(() => '')).slice(0, 2000)
      return { kind: 'refresh_failed', status: response.status, detail: body }
    }
    parsed = adapter.parseTokenResponse(await response.json())
  } catch (err) {
    return { kind: 'refresh_failed', detail: (err as Error).message }
  }

  // Some providers omit refresh_token on refresh — keep the previous one.
  // Persist via `refreshOAuthGrantTokens` (UPDATE by key), NOT an upsert. The
  // grant row was read above, but a concurrent disconnect (DELETE) can land
  // between that read and this write; an `INSERT … ON CONFLICT` would RESURRECT
  // the deleted grant with fresh tokens (R1-B1), whereas an UPDATE touches 0
  // rows once the row is gone. Spread `...input` so the grant key
  // (grantKind + owner/identifiers) targets the SAME row verbatim; for `shared`
  // the UPDATE never rewrites `bootstrapped_by_user_id` or the shared identity.
  const refreshed = await refreshOAuthGrantTokens(deps.db, deps.encryptionKey, {
    ...input,
    provider: decl.provider,
    accessToken: parsed.accessToken,
    refreshToken: parsed.refreshToken ?? grant.refreshToken,
    accessTokenExpiresInSec: parsed.expiresIn,
  })
  // 0 rows ⇒ the grant was deleted during the refresh window. Surface it as
  // "needs reauth" (no_grant) rather than return a token for a revoked grant —
  // and crucially do NOT recreate the row.
  if (!refreshed.updated) return { kind: 'no_grant' }

  const expiresAt =
    typeof parsed.expiresIn === 'number'
      ? new Date(Date.now() + parsed.expiresIn * 1000)
      : undefined
  return { kind: 'ok', accessToken: parsed.accessToken, expiresAt }
}

/**
 * Remote-lane refresh (`source:'remote'`, `supportsRefresh:true`). Public token
 * client, credentials per `secretSource`, IP-pinned POST to the discovery-derived
 * token endpoint (DEC-17). Persists via the SAME `refreshOAuthGrantTokens` UPDATE
 * (never resurrects a concurrently-deleted grant). `refreshToken` is already
 * narrowed non-null by the caller.
 */
async function refreshRemoteGrant(
  refreshToken: string,
  decl: OAuthClientDecl,
  ownerCrUid: string | undefined,
  input: GetAccessTokenInput,
  deps: GetAccessTokenDeps
): Promise<GetAccessTokenResult> {
  const remote = decl.remote
  if (!remote) return { kind: 'no_grant' }
  const credResult = await resolveRemoteClientCredential(
    decl,
    input.recipeNamespace,
    { name: input.recipeName, crUid: ownerCrUid },
    {
      db: deps.db,
      encryptionKey: deps.encryptionKey,
      secretReader: deps.secretReader,
    }
  )
  if (!credResult.ok) return { kind: 'secret_missing', secret: credResult.secret }

  const refreshRequest = buildRemoteRefreshRequest(
    remote.tokenEndpoint,
    {
      refreshToken,
      clientId: credResult.cred.clientId,
      clientSecret: credResult.cred.clientSecret,
    },
    remote.resource,
    // Entra's refresh token is valid for every consented API, so without `scope` the
    // refreshed token's audience would not be pinned to this server.
    remoteWireForProfile(remote.asProfile).scopeOnTokenRequests ? decl.scopes : undefined
  )
  const posted = await postRemoteTokenForm(
    remote.tokenEndpoint,
    'spec.oauth.tokenEndpoint',
    refreshRequest,
    {
      resolveDns: deps.resolveDns,
      pinnedTransport: deps.pinnedTransport,
      timeoutMs: deps.refreshTimeoutMs,
    }
  )
  if (!posted.ok) return { kind: 'refresh_failed', status: posted.status, detail: posted.detail }

  let parsed: ParsedTokenResponse
  try {
    parsed = parseRemoteTokenResponse(JSON.parse(posted.bodyText))
  } catch (err) {
    return { kind: 'refresh_failed', detail: (err as Error).message }
  }

  const refreshed = await refreshOAuthGrantTokens(deps.db, deps.encryptionKey, {
    ...input,
    provider: 'remote',
    accessToken: parsed.accessToken,
    refreshToken: parsed.refreshToken ?? refreshToken,
    accessTokenExpiresInSec: parsed.expiresIn,
  })
  if (!refreshed.updated) return { kind: 'no_grant' }

  const expiresAt =
    typeof parsed.expiresIn === 'number'
      ? new Date(Date.now() + parsed.expiresIn * 1000)
      : undefined
  return { kind: 'ok', accessToken: parsed.accessToken, expiresAt }
}

/**
 * Generic-lane refresh (`source:'generic'`, `supportsRefresh:true`, DEC-28). The
 * refresh request is composed from the CR knobs (`buildAdapterFromConfig`),
 * credentials come from `secretSource` (public/k8s-secret), and the POST is
 * IP-pinned to the pinned `refreshEndpoint` (defaulting to `tokenEndpoint`,
 * DEC-17). Persists via the SAME `refreshOAuthGrantTokens` UPDATE (never
 * resurrects a concurrently-deleted grant). `refreshToken` is already narrowed
 * non-null by the caller.
 */
async function refreshGenericGrant(
  refreshToken: string,
  decl: OAuthClientDecl,
  ownerCrUid: string | undefined,
  input: GetAccessTokenInput,
  deps: GetAccessTokenDeps
): Promise<GetAccessTokenResult> {
  const generic = decl.generic
  if (!generic) return { kind: 'no_grant' }
  const credResult = await resolveRemoteClientCredential(
    decl,
    input.recipeNamespace,
    { name: input.recipeName, crUid: ownerCrUid },
    {
      db: deps.db,
      encryptionKey: deps.encryptionKey,
      secretReader: deps.secretReader,
    }
  )
  if (!credResult.ok) return { kind: 'secret_missing', secret: credResult.secret }

  const adapter = buildAdapterFromConfig(generic)
  let refreshRequest: ReturnType<typeof adapter.buildRefreshRequest>
  try {
    // The build can throw (tokenAuthMethod=basic without a secret); wrap it into a
    // typed fail-closed result rather than an opaque 500 (symmetric with baked).
    refreshRequest = adapter.buildRefreshRequest({
      refreshToken,
      clientId: credResult.cred.clientId,
      clientSecret: credResult.cred.clientSecret,
    })
  } catch (err) {
    return { kind: 'refresh_failed', detail: (err as Error).message }
  }

  const posted = await postRemoteTokenForm(
    refreshRequest.url,
    'spec.oauth.refreshEndpoint',
    refreshRequest,
    {
      resolveDns: deps.resolveDns,
      pinnedTransport: deps.pinnedTransport,
      timeoutMs: deps.refreshTimeoutMs,
    }
  )
  if (!posted.ok) return { kind: 'refresh_failed', status: posted.status, detail: posted.detail }

  let parsed: ParsedTokenResponse
  try {
    parsed = adapter.parseTokenResponse(JSON.parse(posted.bodyText))
  } catch (err) {
    return { kind: 'refresh_failed', detail: (err as Error).message }
  }

  const refreshed = await refreshOAuthGrantTokens(deps.db, deps.encryptionKey, {
    ...input,
    provider: 'generic',
    accessToken: parsed.accessToken,
    refreshToken: parsed.refreshToken ?? refreshToken,
    accessTokenExpiresInSec: parsed.expiresIn,
  })
  if (!refreshed.updated) return { kind: 'no_grant' }

  const expiresAt =
    typeof parsed.expiresIn === 'number'
      ? new Date(Date.now() + parsed.expiresIn * 1000)
      : undefined
  return { kind: 'ok', accessToken: parsed.accessToken, expiresAt }
}