Skip to content

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

TypeScript
34.4 KB
Raw Blame
import { type NextFunction, type Request, type Response, Router } from 'express'
import { config } from '../config.js'
import { pool } from '../db.js'
import type { DbClient } from '../db.js'
import { K8sGateway } from '../k8s.js'
import { rateLimitMiddleware } from '../middleware/rateLimitMiddleware.js'
import {
  type OwnerDeclReader,
  RecipeNotFoundError,
  type RecipeWithOAuthClients,
  SecretNotFoundError,
  type SecretReader,
} from '../oauth/callback.js'
import { deriveOAuthEncryptionKey } from '../oauth/encryption.js'
import { integrationNotConfigured, isSecretNotFound } from '../oauth/integrationNotConfigured.js'
import {
  type McpServerOAuthDecl,
  RemoteOAuthSpecIncoherentError,
  assertRemoteOAuthSpecCoherent,
  buildMcpServerGrantKey,
  readCrUid,
  readOAuthLane,
  resolveServerOAuth,
  resolveServerOAuthSubject,
} from '../oauth/mcpServerOAuthSpec.js'
import { getAccessTokenReactive } from '../oauth/reactiveTokenHelper.js'
import { type OAuthGrantKey, oauthGrantExists } from '../oauth/store.js'
import { type Logger, rootLogger } from '../observability/logger.js'
import { mcpOauthBrokerDeniedTotal } from '../observability/metrics.js'
import {
  type ResolvedHostBinding,
  checkBrokerCallerLineage,
  hasContextIdMismatch,
  hostAccessForUser,
  isCanonicalUuid,
  isLive,
  isValidK8sName,
  resolveBrokerHostBinding,
} from '../services/access/brokerHostBinding.js'
import { isK8sResourceNotFound } from '../services/access/mcpInvocable.js'
import { K8sNotFoundError } from '../services/resourceService.js'
import {
  type McpHostControlClaims,
  mcpHostRateLimitBucketKey,
  verifyMcpHostControlJwt,
} from '../utils/auth/mcpHostJwtToken.js'
import { extractBearerToken } from '../utils/extractBearerToken.js'

/**
 * OAuth mcp-server broker route (U1, spec §U1).
 *
 * `POST /api/v1/mcp-oauth/user-token` — mcp-host exchanges its EXISTING
 * control JWT (host-bound, `typ:'service'`, RS256, rotated with the runtime
 * Secret) for a fresh per-connection provider access token, so the LLM can call
 * an OAuth mcp-server tool with `Authorization: Bearer <token>`. Refresh tokens
 * and the encryption key never leave control-api (invariant §1.1.2).
 *
 * Gate: the control JWT + scope `oauth:user-token`. No new static credential
 * and no new broker-token minting infra (the híbrido design, §U1).
 *
 * Binding: the body only names the mcp-server and, for per-user servers, the
 * end user. Everything else comes from the authenticated caller:
 *   - The control JWT must belong to a host-context-controller Host
 *     (`hostRefs[0]` + `host_uid`), and that Host must be live with the same
 *     uid, so a token cannot outlive or be replayed against a recreated Host.
 *   - The Context is the Host's `spec.contextRef`, never a body field: a
 *     caller cannot name another Context to obtain its shared token.
 *   - The mcp-server must be in that Context's allowlist (exact match, as
 *     host-context-controller applies it), enabled and live. Anything else
 *     answers the same 404 as a missing server, read before the CR is fetched,
 *     so the broker is no existence oracle across Contexts.
 *   - A per-user token requires the body `userId` to be an active user who
 *     enters this Host (directly or through an active team). The `userId`
 *     itself is still asserted by mcp-host, not proven by a signature here.
 *   - `oauthClientId` is derived from the McpServer's `spec.oauth.id`, NEVER
 *     from the request body.
 *
 * Flavor dispatch — read from the server's `spec.oauth.grantScope`:
 *   - `user`    → grant key `(server, userId)`   — per-user identity.
 *   - `context` → grant key `(server, contextRef)` — shared identity.
 * Both branches ship in v1; the `context` branch is governed/exercised by U6.
 */

export interface McpServerResource {
  metadata?: { name?: string; namespace?: string; uid?: string; deletionTimestamp?: unknown }
  spec?: {
    enabled?: unknown
    auth?: { type?: unknown }
    oauth?: McpServerOAuthDecl
    // `spec.contextRef` is REQUIRED + singular on the CRD ("the context this
    // server belongs to", mcpserver.yaml). It is the AUTHORITATIVE Context of a
    // context-identity server — the shared grant coordinate — never the body.
    contextRef?: unknown
  }
}

/**
 * The owner metadata the refresh engine reads. `uid` is the installation identity
 * a grant was sealed with; it is kept only when it is a non-empty string, so a
 * malformed value can never equal a sealed grant's uid.
 */
function ownerMetadata(server: McpServerResource): RecipeWithOAuthClients['metadata'] {
  const md = server.metadata
  if (!md) return undefined
  const uid = readCrUid(server)
  return { name: md.name, namespace: md.namespace, ...(uid ? { uid } : {}) }
}

/**
 * Normalize a McpServer's single `spec.oauth` object into the
 * `{ spec: { oauthClients: [decl] } }` shape the owner-agnostic broker +
 * refresh path (`getAccessToken`) already consume. Returns null when the server
 * is not an OAuth server (no `spec.oauth`), so callers fail closed.
 */
export function normalizeMcpServerOwnerDecl(
  server: McpServerResource
): RecipeWithOAuthClients | null {
  const oauth = server.spec?.oauth
  if (!oauth) return null
  const lane = readOAuthLane(oauth)
  // Remote lane (`source:'remote'`): delegate to the SHARED subject resolver so the
  // refresh reader reads the remote client (public / DCR / pre-registered)
  // IDENTICALLY to the mint + callback (D4 — no drift). The remote decl carries the
  // pinned routing + secretSource that `getAccessToken` branches on.
  if (lane === 'remote') {
    const resolved = resolveServerOAuthSubject(server, 'token')
    if (!resolved) return null
    return { metadata: ownerMetadata(server), spec: { oauthClients: [resolved.decl] } }
  }
  // Generic self-hosted lane (`source:'generic'`, DEC-28): delegate to the SAME
  // subject resolver (D4 — no drift with mint + callback) so the refresh reader
  // gets the pinned `generic` routing + secretSource that `getAccessToken`
  // branches on.
  if (lane === 'generic') {
    const resolved = resolveServerOAuthSubject(server, 'token')
    if (!resolved) return null
    return { metadata: ownerMetadata(server), spec: { oauthClients: [resolved.decl] } }
  }
  // Baked lane (unchanged; a public baked client is tolerated per E-19.2).
  if (typeof oauth.id !== 'string' || typeof oauth.provider !== 'string') return null
  const clientIdRef = oauth.clientIdRef
  if (!clientIdRef || typeof clientIdRef.name !== 'string' || typeof clientIdRef.key !== 'string') {
    return null
  }
  // clientSecretRef is optional (E-19.2, public client): ABSENT (null/undefined)
  // ⇒ public client (decl carries `clientSecretRef: undefined`); PRESENT-but-
  // malformed stays fail-closed (null) — a half-declared secret ref is a config
  // error, not a public client. `!= null` (not `!== undefined`) so a JSON-null
  // ref from the untrusted CR is treated as absent, never dereferenced.
  const clientSecretRef = oauth.clientSecretRef
  let normalizedSecretRef: { name: string; key: string } | undefined
  if (clientSecretRef != null) {
    if (typeof clientSecretRef.name !== 'string' || typeof clientSecretRef.key !== 'string') {
      return null
    }
    normalizedSecretRef = { name: clientSecretRef.name, key: clientSecretRef.key }
  }
  return {
    metadata: ownerMetadata(server),
    spec: {
      oauthClients: [
        {
          id: oauth.id,
          provider: oauth.provider,
          clientIdRef: { name: clientIdRef.name, key: clientIdRef.key },
          clientSecretRef: normalizedSecretRef,
          scopes: Array.isArray(oauth.scopes)
            ? oauth.scopes.filter((s): s is string => typeof s === 'string')
            : undefined,
          backgroundAccess: oauth.backgroundAccess === true,
        },
      ],
    },
  }
}

type BrokerDenialReason =
  | 'lineage'
  | 'unauthenticated'
  | 'host_not_bound'
  | 'server_not_found'
  | 'context_ref_mismatch'
  | 'no_grant'
  | 'unavailable'

// Fixed bodies: denials must not vary with what was found, and a 503 never
// forwards the apiserver or DB error (an RBAC 403 from Kubernetes would
// otherwise reach the client through the shared error handler).
const HOST_NOT_BOUND = { error: 'host_not_bound' }
const SERVER_NOT_FOUND = { error: 'server_not_found' }
const STATE_UNAVAILABLE = { error: 'host_state_unavailable' }
const NO_GRANT = { error: 'no_grant' }

// Upper bound on the grant-existence batch. mcp-host caps its per-user OAuth
// partitions at OAUTH_USER_PARTITION_MAX=500, so one sweep never legitimately
// exceeds that; 1000 is generous headroom that still rejects an abusive payload.
const MAX_EXISTS_BATCH = 1000

/** One entry of a `POST /mcp-oauth/grants/exists` request. */
export interface GrantExistsQuery {
  mcpServerName: string
  /** End-user identity, for `grantScope='user'` servers. */
  userId?: string
  /**
   * Accepted for API fidelity but NEVER used to key a lookup — `context`
   * servers key by the server's authoritative `contextRef` (server-side). A
   * lying value therefore cannot change the answer (no body-trust).
   */
  contextId?: string
}

/**
 * One entry of the response. It ECHOES the query's coordinates so the consumer
 * (the mcp-host sweep) correlates by the tuple `(mcpServerName, userId)` /
 * `(mcpServerName, contextId)` rather than by array position — two per-user
 * partitions of the SAME server (different `userId`) must stay distinguishable.
 * `userId`/`contextId` are echoed exactly as the caller sent them: values the
 * caller itself supplied, so echoing them leaks nothing (confirmed in review).
 * Never a token, never the server's authoritative contextRef, never a key.
 */
export interface GrantExistsResult {
  mcpServerName: string
  userId?: string
  contextId?: string
  exists: boolean
}

/**
 * The coordinates of one untrusted batch entry, echoed back exactly as they
 * arrived so the consumer correlates by tuple. A non-string `mcpServerName`
 * cannot address a server and echoes as ''.
 */
function parseGrantExistsEntry(raw: unknown): GrantExistsQuery {
  const entry = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
  const parsed: GrantExistsQuery = {
    mcpServerName: typeof entry.mcpServerName === 'string' ? entry.mcpServerName : '',
  }
  if (typeof entry.userId === 'string') parsed.userId = entry.userId
  if (typeof entry.contextId === 'string') parsed.contextId = entry.contextId
  return parsed
}

function echoGrantExistsEntry(entry: GrantExistsQuery, exists: boolean): GrantExistsResult {
  return { ...entry, exists }
}

export interface GrantExistenceDeps {
  db: DbClient
  gateway: Pick<K8sGateway, 'getResource'>
  /** The calling Host, already resolved live: every entry is judged against it. */
  binding: ResolvedHostBinding
  mcpServersNamespace: string
  log?: Logger
}

type BrokerRoute = 'user_token' | 'grants_exists'

function recordBrokerDenial(
  log: Logger,
  route: BrokerRoute,
  reason: BrokerDenialReason,
  context: Record<string, unknown>,
  level: 'warn' | 'debug' = 'warn'
): void {
  mcpOauthBrokerDeniedTotal.inc({ reason, route }, 1)
  log[level](
    { event: 'mcp_oauth_broker_denied', reason, route, ...context },
    'mcp oauth broker denied'
  )
}

/** What one mcp-server contributes to every entry that names it in a batch. */
type ServerVerdict =
  | { kind: 'deny'; reason: 'server_not_found' | 'context_ref_mismatch' }
  // Cannot be decided now, or nothing to evict: keep the partition. `cause` is
  // set only for a transient read failure, which is reported per entry.
  | { kind: 'error'; cause?: { err: unknown } }
  | { kind: 'resolved'; resolved: NonNullable<ReturnType<typeof resolveServerOAuth>> }

/**
 * Batch grant-existence resolver for the hot-revocation sweep, bound to the
 * calling Host (`deps.binding`). Each entry gets the `user-token` rules, but a
 * definitive denial answers `exists:false` (mcp-host evicts the partition) and
 * anything transient or undecidable answers `exists:true` (mcp-host keeps it):
 * an apiserver or DB blip must never disconnect a user.
 *
 *   - outside the Host Context's allowlist (exact match), being deleted or
 *     disabled → false; outside the allowlist the CR is never read;
 *   - allowlisted but the CR is gone → true: an uninstall in flight is not
 *     this sweep's to evict (the uninstall itself purges grants);
 *   - read error, not an OAuth server, a per-user entry without userId → true;
 *   - context-scope owned by another Context or without one → false;
 *   - per-user: non-UUID userId or a user who cannot enter the Host → false,
 *     a DB error checking that → true;
 *   - otherwise the store decides (`oauthGrantExists`, never the token).
 *
 * Strictly 1:1 and in order with the input, each result echoing its entry's
 * coordinates; a malformed entry gets a fail-open placeholder in its slot.
 * Every mcp-server is read once and every userId's Host access queried once
 * per batch; denials are logged and counted once per (reason, mcp-server).
 */
export async function resolveBatchGrantExistence(
  deps: GrantExistenceDeps,
  queries: readonly unknown[]
): Promise<GrantExistsResult[]> {
  const log = deps.log ?? rootLogger
  const { binding } = deps
  const results: GrantExistsResult[] = []

  type Denial = {
    reason: BrokerDenialReason
    mcpServerName: string
    entries: number
    warn: boolean
    detail: Record<string, unknown>
  }
  const denials = new Map<string, Denial>()
  // Called once per affected entry; the first call's detail (stage, err) is kept.
  const noteDenial = (
    reason: BrokerDenialReason,
    mcpServerName: string,
    opts: { warn?: boolean; detail?: Record<string, unknown> } = {}
  ) => {
    const warn = opts.warn ?? true
    const key = `${reason}\u0000${mcpServerName}`
    const seen = denials.get(key)
    if (seen) {
      seen.entries += 1
      seen.warn ||= warn
    } else {
      denials.set(key, { reason, mcpServerName, entries: 1, warn, detail: opts.detail ?? {} })
    }
  }

  const serverVerdicts = new Map<string, ServerVerdict>()
  const serverVerdict = async (name: string): Promise<ServerVerdict> => {
    const memo = serverVerdicts.get(name)
    if (memo) return memo
    const verdict = await readServerVerdict(name)
    serverVerdicts.set(name, verdict)
    return verdict
  }
  const readServerVerdict = async (name: string): Promise<ServerVerdict> => {
    if (!binding.allowlist.includes(name)) return { kind: 'deny', reason: 'server_not_found' }
    let server: McpServerResource
    try {
      server = (await deps.gateway.getResource(
        'mcpservers',
        name,
        deps.mcpServersNamespace
      )) as McpServerResource
    } catch (err) {
      if (isK8sResourceNotFound(err)) {
        log.warn(
          { mcpServerName: name },
          'grant-existence: allowlisted server not found; fail-open'
        )
        return { kind: 'error' }
      }
      return { kind: 'error', cause: { err } }
    }
    if (!server || !isLive(server.metadata) || server.spec?.enabled === false) {
      return { kind: 'deny', reason: 'server_not_found' }
    }
    const resolved = resolveServerOAuth(server)
    if (server.spec?.auth?.type !== 'oauth' || !resolved) {
      log.warn(
        { mcpServerName: name },
        'grant-existence: server not resolvable as oauth; fail-open'
      )
      return { kind: 'error' }
    }
    if (resolved.grantScope === 'context' && resolved.contextRef !== binding.contextName) {
      return { kind: 'deny', reason: 'context_ref_mismatch' }
    }
    return { kind: 'resolved', resolved }
  }

  type Access = { kind: 'allowed' } | { kind: 'denied' } | { kind: 'error'; err: unknown }
  const userAccess = new Map<string, Access>()
  const accessFor = async (userId: string): Promise<Access> => {
    const memo = userAccess.get(userId)
    if (memo) return memo
    let access: Access
    try {
      access = { kind: await hostAccessForUser(deps.db, userId, binding.hostName) }
    } catch (err) {
      access = { kind: 'error', err }
    }
    userAccess.set(userId, access)
    return access
  }

  for (const raw of queries) {
    const entry = parseGrantExistsEntry(raw)
    const { mcpServerName, userId } = entry
    const echo = (exists: boolean) => echoGrantExistsEntry(entry, exists)

    if (!mcpServerName || !isValidK8sName(mcpServerName)) {
      log.warn({ mcpServerName }, 'grant-existence: malformed query entry; fail-open (exists:true)')
      results.push(echo(true))
      continue
    }

    const verdict = await serverVerdict(mcpServerName)
    if (verdict.kind === 'deny') {
      noteDenial(verdict.reason, mcpServerName)
      results.push(echo(false))
      continue
    }
    if (verdict.kind === 'error') {
      if (verdict.cause) {
        noteDenial('unavailable', mcpServerName, {
          detail: { stage: 'mcp_server', err: verdict.cause.err },
        })
      }
      results.push(echo(true))
      continue
    }
    const { resolved } = verdict

    if (resolved.grantScope === 'user') {
      if (!userId) {
        results.push(echo(true))
        continue
      }
      if (!isCanonicalUuid(userId)) {
        // Channel senders reach here on every sweep by design: debug only.
        noteDenial('no_grant', mcpServerName, { warn: false })
        results.push(echo(false))
        continue
      }
      const access = await accessFor(userId)
      if (access.kind === 'error') {
        noteDenial('unavailable', mcpServerName, {
          detail: { stage: 'user_access', err: access.err },
        })
        results.push(echo(true))
        continue
      }
      if (access.kind === 'denied') {
        noteDenial('no_grant', mcpServerName)
        results.push(echo(false))
        continue
      }
    }

    const key = buildMcpServerGrantKey(resolved, {
      mcpServerName,
      mcpServersNamespace: deps.mcpServersNamespace,
      userId,
    })
    if (!key) {
      // Unreachable: a context server without contextRef was denied above and a
      // per-user entry without userId answered already. Keep the partition.
      results.push(echo(true))
      continue
    }
    try {
      results.push(echo(await oauthGrantExists(deps.db, key)))
    } catch (err) {
      log.warn({ err, mcpServerName }, 'grant-existence check failed; fail-open (exists:true)')
      results.push(echo(true))
    }
  }

  for (const { reason, mcpServerName, entries, warn, detail } of denials.values()) {
    recordBrokerDenial(
      log,
      'grants_exists',
      reason,
      { host: binding.hostName, mcpServerName, entries, ...detail },
      warn ? 'warn' : 'debug'
    )
  }
  return results
}

export function createMcpOauthRouter(gateway: K8sGateway): Router {
  const router = Router()
  const encryptionKey = deriveOAuthEncryptionKey(config.oauthEncryptionKey)

  // OwnerDeclReader for McpServers: reads the CR from the mcp-servers namespace
  // and normalizes `spec.oauth` → oauthClients shape. Used by getAccessToken on
  // the refresh path so it stays owner-agnostic.
  const ownerDeclReader: OwnerDeclReader = {
    async read(name): Promise<RecipeWithOAuthClients | null> {
      try {
        const server = (await gateway.getResource(
          'mcpservers',
          name,
          config.mcpServersNamespace
        )) as McpServerResource
        return normalizeMcpServerOwnerDecl(server)
      } catch (err) {
        if (err instanceof K8sNotFoundError) {
          throw new RecipeNotFoundError(`mcpserver ${config.mcpServersNamespace}/${name} not found`)
        }
        throw err
      }
    },
  }

  // Secrets (client_id / client_secret) live in the mcp-servers namespace, NOT
  // the sandbox-recipes namespace.
  const secretReader: SecretReader = {
    async read(name, namespace): Promise<Record<string, string>> {
      try {
        const raw = (await gateway.getSecret(name, namespace)) as { data?: Record<string, string> }
        const decoded: Record<string, string> = {}
        for (const [k, v] of Object.entries(raw.data ?? {})) {
          decoded[k] = Buffer.from(v, 'base64').toString('utf8')
        }
        return decoded
      } catch (err) {
        if (isSecretNotFound(err)) {
          throw new SecretNotFoundError(`secret ${namespace}/${name} not found`)
        }
        throw err
      }
    },
  }

  // Verify the mcp-host control JWT and stash the claims so the rate limiter can
  // key off the caller before the handler runs.
  function requireControlCaller(req: Request, res: Response, next: NextFunction): void {
    const bearer = extractBearerToken(req)
    if (!bearer || bearer.length > 4096) {
      res.status(401).json({ error: 'Unauthorized' })
      return
    }
    const claims = verifyMcpHostControlJwt(bearer)
    if (!claims) {
      res.status(401).json({ error: 'Unauthorized' })
      return
    }
    res.locals.mcpHostControl = claims
    next()
  }

  // Fail-closed kill-switch (finding R1-H1). While the OAuth mcp-server broker
  // is disabled the endpoint must look ABSENT — a 404 before any auth or token
  // work, not a 403 — so it cannot serve provider tokens in production until the
  // U4 mcp-host runtime lands. Read at request time so the flag is honored
  // without a restart in tests; default is OFF (config.mcpOauthBrokerEnabled).
  function requireBrokerEnabled(_req: Request, res: Response, next: NextFunction): void {
    if (!config.mcpOauthBrokerEnabled) {
      res.status(404).json({ error: 'not_found' })
      return
    }
    next()
  }

  router.post(
    '/mcp-oauth/user-token',
    requireBrokerEnabled,
    requireControlCaller,
    rateLimitMiddleware({
      bucketType: 'mcp_oauth_broker',
      maxPerMinute: config.oauthBrokerRlPerMin,
      getBucketKey: req => {
        const claims = req.res?.locals?.mcpHostControl as McpHostControlClaims | undefined
        // Standalone 1st-party hosts all share sub=<hostsNamespace>/standalone,
        // so keying by sub would collapse every standalone host into one bucket.
        // The verified principal keys standalone hosts by hostRefs[0] instead,
        // keeping each host isolated.
        return (
          mcpHostRateLimitBucketKey('mcp-oauth', claims, 'mcp-oauth:unknown') ?? 'mcp-oauth:unknown'
        )
      },
      onBackendUnavailable: 'process-memory',
    }),
    async (req, res, next) => {
      const claims = res.locals.mcpHostControl as McpHostControlClaims | undefined
      // Scope gate: the control JWT must carry `oauth:user-token`.
      if (!claims || !claims.scopes.includes('oauth:user-token')) {
        return res.status(403).json({ error: 'insufficient_scope' })
      }
      const log = req.log ?? rootLogger
      const deny = (
        reason: BrokerDenialReason,
        status: number,
        body: Record<string, string>,
        context: Record<string, unknown> = {},
        level: 'warn' | 'debug' = 'warn'
      ) => {
        recordBrokerDenial(log, 'user_token', reason, context, level)
        return res.status(status).json(body)
      }

      const lineage = checkBrokerCallerLineage(claims, config)
      if (lineage.kind === 'lineage') {
        return deny('lineage', 403, HOST_NOT_BOUND, { sub: claims.sub })
      }
      if (lineage.kind === 'unauthenticated') {
        return deny('unauthenticated', 401, { error: 'Unauthorized' }, { host: claims.hostRefs[0] })
      }
      const hostName = lineage.hostName

      try {
        const body = (req.body ?? {}) as {
          mcpServerName?: unknown
          userId?: unknown
        }
        const mcpServerName = body.mcpServerName
        const userId = body.userId
        if (typeof mcpServerName !== 'string' || !isValidK8sName(mcpServerName)) {
          return res.status(400).json({ error: 'invalid_request' })
        }
        const where = { host: hostName, mcpServerName }

        const binding = await resolveBrokerHostBinding(gateway, hostName, lineage.hostUid, config)
        if (binding.kind === 'denied') return deny('host_not_bound', 403, HOST_NOT_BOUND, where)
        if (binding.kind === 'unavailable') {
          return deny('unavailable', 503, STATE_UNAVAILABLE, {
            ...where,
            stage: 'host_binding',
            err: binding.cause,
          })
        }
        // Debug, not warn: the broker never keys on spec.contextId, and this
        // fires on every mint for every Host of the Context.
        if (hasContextIdMismatch(binding.ctx)) {
          log.debug(
            { event: 'context_id_mismatch', host: hostName, context: binding.ctx.metadata?.name },
            'context spec.contextId differs from its name'
          )
        }

        // Allowlist before the CR read: a server outside this Host's Context
        // must cost the same as one that does not exist.
        if (!binding.allowlist.includes(mcpServerName)) {
          return deny('server_not_found', 404, SERVER_NOT_FOUND, where)
        }
        let server: McpServerResource
        try {
          server = (await gateway.getResource(
            'mcpservers',
            mcpServerName,
            config.mcpServersNamespace
          )) as McpServerResource
        } catch (err) {
          if (isK8sResourceNotFound(err)) {
            return deny('server_not_found', 404, SERVER_NOT_FOUND, where)
          }
          return deny('unavailable', 503, STATE_UNAVAILABLE, {
            ...where,
            stage: 'mcp_server',
            err,
          })
        }
        if (!server || !isLive(server.metadata) || server.spec?.enabled === false) {
          return deny('server_not_found', 404, SERVER_NOT_FOUND, where)
        }

        const authType = server.spec?.auth?.type
        const resolved = resolveServerOAuth(server)
        if (authType !== 'oauth' || !resolved) {
          return res.status(400).json({ error: 'not_oauth_server' })
        }

        // Context-scope: the server's owner must be this Host's Context. Checked
        // before remote coherence so a foreign owner gets the uniform 404, not
        // a 409 that would reveal its spec. Any body `contextId` is ignored.
        if (resolved.grantScope === 'context' && resolved.contextRef !== binding.contextName) {
          return deny('context_ref_mismatch', 404, SERVER_NOT_FOUND, where)
        }

        // Checked up front, not only through the refresh reader: a still-fresh
        // access token is served without ever reading the owner declaration.
        assertRemoteOAuthSpecCoherent(server, 'token')

        // Bifurcate by grantScope read from the server. The KEY comes from the
        // shared derivation (`buildMcpServerGrantKey`, D4) so the mint, the
        // rpc-proxy grant-presence gate and the grant-existence sweep never
        // drift.
        let userForKey: string | undefined
        if (resolved.grantScope === 'user') {
          if (typeof userId !== 'string' || userId.length === 0) {
            return res.status(400).json({ error: 'invalid_request' })
          }
          // A user who cannot enter this Host looks exactly like one who never
          // connected the server.
          let access: 'allowed' | 'denied'
          try {
            access = await hostAccessForUser(pool, userId, hostName)
          } catch (err) {
            return deny('unavailable', 503, STATE_UNAVAILABLE, {
              ...where,
              stage: 'user_access',
              err,
            })
          }
          if (access === 'denied') {
            // Channel senders (Slack, email, Telegram ids) are not users.id and
            // reach here on every mint by design; only an entitled-looking id
            // that cannot enter the Host is worth a warning.
            return isCanonicalUuid(userId)
              ? deny('no_grant', 404, NO_GRANT, { ...where, cause: 'no_host_access' })
              : deny('no_grant', 404, NO_GRANT, { ...where, cause: 'non_uuid_user_id' }, 'debug')
          }
          userForKey = userId
        }
        const key: OAuthGrantKey | null = buildMcpServerGrantKey(resolved, {
          mcpServerName,
          mcpServersNamespace: config.mcpServersNamespace,
          userId: userForKey,
        })
        if (!key) {
          // Unreachable: the guards above already rejected the null cases (a
          // context server without contextRef never equals the Host's Context).
          // Fail closed defensively rather than mint against a malformed key.
          return res.status(400).json({ error: 'invalid_request' })
        }

        // Interactive live-session path — a human session is present, so
        // background consent is NOT required here (requireBackground: false).
        const result = await getAccessTokenReactive(
          { ...key, requireBackground: false },
          {
            db: { query: (text, values) => pool.query(text, values) },
            recipeReader: ownerDeclReader,
            secretReader,
            fetchFn: (input, init) => fetch(input, init),
            encryptionKey,
          }
        )

        const audit = (outcome: string) =>
          req.log?.info(
            {
              event: 'mcp_oauth_user_token_issued',
              mcpServerName,
              grantScope: resolved.grantScope,
              oauthClientId: resolved.oauthClientId,
              outcome,
            },
            'mcp oauth user token issued'
          )

        switch (result.kind) {
          case 'ok':
            audit('ok')
            return res.status(200).json({
              token: result.accessToken,
              expiresAt: result.expiresAt?.toISOString() ?? null,
            })
          case 'no_grant':
            audit('no_grant')
            return res.status(404).json({ error: 'no_grant' })
          case 'recipe_not_found':
            audit('server_not_found')
            return res.status(404).json({ error: 'server_not_found' })
          case 'unknown_oauth_client':
            audit('unknown_oauth_client')
            return res.status(400).json({ error: 'unknown_oauth_client' })
          case 'unsupported_provider':
            audit('unsupported_provider')
            return res
              .status(400)
              .json({ error: 'unsupported_provider', provider: result.provider })
          case 'secret_missing':
            audit('integration_not_configured')
            return res
              .status(503)
              .json(integrationNotConfigured(resolved.oauthClientId, result.secret))
          case 'refresh_failed':
            audit('refresh_failed')
            return res
              .status(502)
              .json({ error: 'refresh_failed', status: result.status, detail: result.detail })
        }
      } catch (err) {
        if (err instanceof RemoteOAuthSpecIncoherentError) {
          return res.status(409).json({ error: err.code, reason: err.reason })
        }
        next(err)
      }
    }
  )

  // Batch grant-existence sweep. mcp-host asks, in the cadence
  // of the poll it already runs, whether its live OAuth partitions still have a
  // grant, and evicts the ones answered with a strict `exists:false`. Same
  // kill-switch, caller gate, rate-limit bucket and scope as user-token, and the
  // same Host binding. mcp-host treats ANY non-200 as "keep everything", so
  // only caller-level failures (scope, lineage, a token to renew) are errors:
  // a Host that no longer binds answers 200 with every entry false, and a
  // binding that cannot be read answers 200 with every entry true. Returns only
  // `{ mcpServerName, userId?, contextId?, exists }` — never a token or a key.
  router.post(
    '/mcp-oauth/grants/exists',
    requireBrokerEnabled,
    requireControlCaller,
    rateLimitMiddleware({
      bucketType: 'mcp_oauth_broker',
      maxPerMinute: config.oauthBrokerRlPerMin,
      getBucketKey: req => {
        const claims = req.res?.locals?.mcpHostControl as McpHostControlClaims | undefined
        // Standalone 1st-party hosts all share sub=<hostsNamespace>/standalone,
        // so keying by sub would collapse every standalone host into one bucket.
        // The verified principal keys standalone hosts by hostRefs[0] instead,
        // keeping each host isolated.
        return (
          mcpHostRateLimitBucketKey('mcp-oauth', claims, 'mcp-oauth:unknown') ?? 'mcp-oauth:unknown'
        )
      },
      onBackendUnavailable: 'process-memory',
    }),
    async (req, res, next) => {
      const claims = res.locals.mcpHostControl as McpHostControlClaims | undefined
      if (!claims || !claims.scopes.includes('oauth:user-token')) {
        return res.status(403).json({ error: 'insufficient_scope' })
      }
      const log = req.log ?? rootLogger

      // wrc tokens never call this endpoint; a 403 is harmless. A token
      // without host_uid gets 401 so mcp-host renews it.
      const lineage = checkBrokerCallerLineage(claims, config)
      if (lineage.kind === 'lineage') {
        recordBrokerDenial(log, 'grants_exists', 'lineage', { sub: claims.sub })
        return res.status(403).json(HOST_NOT_BOUND)
      }
      if (lineage.kind === 'unauthenticated') {
        recordBrokerDenial(log, 'grants_exists', 'unauthenticated', { host: claims.hostRefs[0] })
        return res.status(401).json({ error: 'Unauthorized' })
      }
      const hostName = lineage.hostName

      const body = (req.body ?? {}) as { queries?: unknown }
      if (!Array.isArray(body.queries)) {
        return res.status(400).json({ error: 'invalid_request' })
      }
      if (body.queries.length > MAX_EXISTS_BATCH) {
        return res.status(400).json({ error: 'batch_too_large' })
      }
      const queries: unknown[] = body.queries
      if (queries.length === 0) return res.status(200).json({ results: [] })
      const everyEntry = (exists: boolean) => ({
        results: queries.map(raw => echoGrantExistsEntry(parseGrantExistsEntry(raw), exists)),
      })

      try {
        const binding = await resolveBrokerHostBinding(gateway, hostName, lineage.hostUid, config)
        if (binding.kind === 'denied') {
          mcpOauthBrokerDeniedTotal.inc({ reason: 'host_not_bound', route: 'grants_exists' }, 1)
          log.warn(
            { event: 'broker_batch_denied', host: hostName, entries: queries.length },
            'grant-existence batch denied: Host not bound'
          )
          return res.status(200).json(everyEntry(false))
        }
        if (binding.kind === 'unavailable') {
          recordBrokerDenial(log, 'grants_exists', 'unavailable', {
            host: hostName,
            stage: 'host_binding',
            err: binding.cause,
          })
          return res.status(200).json(everyEntry(true))
        }
        const results = await resolveBatchGrantExistence(
          {
            db: { query: (text, values) => pool.query(text, values) },
            gateway,
            binding,
            mcpServersNamespace: config.mcpServersNamespace,
            log,
          },
          queries
        )
        return res.status(200).json({ results })
      } catch (err) {
        next(err)
      }
    }
  )

  return router
}