Skip to content

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

TypeScript
6.6 KB
Raw Blame
/**
 * Grant-existence client for the hot-revocation poll-sweep (mini-spec 13
 * §4.1/§4.3). Sibling of `brokerTokenProvider.ts` — it reaches the SAME
 * control-api OAuth broker through the SAME workflow-approval gateway, reusing
 * that module's `BrokerTokenProviderDeps` (gateway URL + control JWT accessor +
 * refresh-on-401) and its house fetch timeout WITHOUT editing it. Where the
 * broker MINTS a per-connection token, this only ASKS — a read-only batch
 * `POST /api/v1/mcp-oauth/grants/exists` that returns booleans, never a token.
 *
 * D4 — control-api is the sole authority for the grant: mcp-host asks, never
 * recomputes "connected". The sweep that consumes this evicts a partition ONLY
 * on a definitive `exists:false`; ANY error here THROWS so the caller fails
 * OPEN (conserve every partition — a control-api/gateway blip must not tear down
 * live sessions; the 15-min idle-evict is the backstop, §4.2).
 */
import type { BrokerTokenProviderDeps } from './brokerTokenProvider'
import { DEFAULT_BROKER_FETCH_TIMEOUT_MS } from './brokerTokenProvider'
import type { LiveOAuthPartition } from './manager'

/**
 * One entry of the batch request. Mirrors control-api's `GrantExistsQuery`.
 * `userId` addresses an `oauth-user` grant; `oauth-context` sends neither
 * coordinate (control-api keys the shared grant by the server's authoritative
 * `contextRef`, server-side — mcp-host transports no context identity).
 */
export interface GrantExistsQuery {
  mcpServerName: string
  userId?: string
  contextId?: string
}

/**
 * One entry of the response. control-api ECHOES the query coordinates so the
 * consumer correlates by tuple, not by array position; `exists` is the only
 * new field. Never a token, never the authoritative contextRef, never a key.
 */
export interface GrantExistsResult {
  mcpServerName: string
  userId?: string
  contextId?: string
  exists: boolean
}

/**
 * POST the batch grant-existence query to the gateway and return control-api's
 * `results`. Reuses the broker's refresh-on-401 (an idle pod's control JWT
 * expires; refresh ONCE and retry — bounded to one extra request). THROWS on
 * every failure mode (unconfigured gateway/token, non-200 incl. 403/5xx,
 * malformed body, network/timeout) so the sweep fails OPEN. Never logs or
 * returns a token.
 */
export async function checkGrantExistence(
  deps: BrokerTokenProviderDeps,
  queries: readonly GrantExistsQuery[]
): Promise<GrantExistsResult[]> {
  if (queries.length === 0) return []
  const fetchImpl = deps.fetchImpl ?? fetch
  const timeoutMs = deps.timeoutMs ?? DEFAULT_BROKER_FETCH_TIMEOUT_MS

  const gatewayUrl = deps.gatewayUrl()?.trim()
  if (!gatewayUrl) {
    throw new Error('mcp-oauth grant-existence: gateway URL not configured')
  }
  const controlToken = deps.controlToken()
  if (!controlToken) {
    throw new Error('mcp-oauth grant-existence: control token unavailable')
  }
  const payload = JSON.stringify({ queries })

  const post = async (bearer: string): Promise<Response> =>
    fetchImpl(`${gatewayUrl}/api/v1/mcp-oauth/grants/exists`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${bearer}`,
      },
      body: payload,
      // A hung broker must not stall the eviction tick past its cadence.
      signal: AbortSignal.timeout(timeoutMs),
    })

  let res = await post(controlToken)

  // Same reactive recovery as brokerTokenProvider: the control JWT has a ~10 min
  // TTL and an idle pod reaches control-api with an expired bearer. Refresh ONCE
  // and retry; the "token actually changed" check bounds this to a single extra
  // request, so a refresh that fails cannot loop.
  if (res.status === 401 && deps.refreshControlToken) {
    let rotated: string | undefined
    try {
      await deps.refreshControlToken()
      rotated = deps.controlToken()
    } catch {
      // Fall through with the original 401; the throw below surfaces the failure
      // (and the sweep conserves). The cause is not swallowed silently — the
      // caller logs the thrown error.
    }
    if (rotated && rotated !== controlToken) {
      res = await post(rotated)
    }
  }

  if (res.status !== 200) {
    throw new Error(`mcp-oauth grant-existence returned ${res.status}`)
  }
  const data = (await res.json()) as { results?: unknown }
  if (!Array.isArray(data.results)) {
    throw new Error('mcp-oauth grant-existence returned a malformed body')
  }
  return data.results as GrantExistsResult[]
}

/**
 * Canonical grant-coordinate key — the single source of the convention every
 * grant-existence consumer shares (`oauth-context` carries no userId →
 * normalized to null). Exported because this module is BOTH the producer of the
 * coordinate (`buildGrantExistenceQueries`) and of the echoed response the
 * consumers correlate against, so the probe cache, the revocation sweep, and the
 * eager catalog bootstrap all key on the identical string. A second literal copy
 * of it anywhere would break that correlation silently.
 */
export function grantCoordKey(mcpServerName: string, userId?: string): string {
  return JSON.stringify([mcpServerName, userId ?? null])
}

/**
 * Build the batch query for the live OAuth partitions. Single source of the
 * coordinate convention (D4-adjacent): `oauth-user` sends its `userId`,
 * `oauth-context` sends only `mcpServerName`. Paired with
 * `selectRevokedPartitionKeys`, which reverses the SAME convention.
 */
export function buildGrantExistenceQueries(
  partitions: readonly LiveOAuthPartition[]
): GrantExistsQuery[] {
  return partitions.map(p => {
    const q: GrantExistsQuery = { mcpServerName: p.serverName }
    if (p.userId !== undefined) q.userId = p.userId
    return q
  })
}

/**
 * Correlate the batch results back to partition keys BY COORDINATE (not array
 * position — two per-user partitions of one server must stay distinguishable)
 * and select the keys whose grant is definitively absent. Only a strict
 * `exists === false` selects a key; true, missing, or a malformed entry
 * conserves (fail-closed on definitive revocation, fail-OPEN on everything
 * else). Returns the partition keys the sweep passes to
 * `manager.evictRevokedPartitions`.
 */
export function selectRevokedPartitionKeys(
  partitions: readonly LiveOAuthPartition[],
  results: readonly GrantExistsResult[]
): string[] {
  const byCoord = new Map<string, string>()
  for (const p of partitions) byCoord.set(grantCoordKey(p.serverName, p.userId), p.key)
  const keys: string[] = []
  for (const r of results) {
    if (r.exists !== false) continue
    const key = byCoord.get(grantCoordKey(r.mcpServerName, r.userId))
    if (key) keys.push(key)
  }
  return keys
}