RFC: Graceful Degradation for Multi-Upstream OAuth in vMCP

[tgrunnagle]

Adds an RFC proposing opt-in partial-completion semantics for the
embedded authorization server's multi-upstream OAuth chain in
VirtualMCPServer.

Related issue: stacklok/toolhive#5162

Note: This PR body was updated post-merge to reflect the
RFC's final design after review feedback. See follow-up commits
fde11e0 and 031eda4 on the same branch for the details.

Why

Today the embedded auth server's multi-upstream chain is all-or-nothing:
one upstream IdP outage or one declined consent screen invalidates every
collected token and locks the user out of every backend on the vMCP —
including backends that have nothing to do with the failed upstream.
Operators aggregating backends across multiple SaaS IdPs (e.g. github +
slack + google) see the whole vMCP appear down for what should be a
single-provider problem.

Key design decisions

• Single per-upstream optional flag (default false) on
  UpstreamProviderConfig. Marking any provider optional: true opts
  the deployment into partial completion for that provider; leaving
  every provider at the default reproduces today's all-or-nothing
  behavior exactly. No top-level mode toggle.
• Primary identity provider — already named by
  authzConfig.inline.primaryUpstreamProvider — is always required;
  admission webhook rejects configs that set optional: true on it.
• Chain completion walks every upstream and completes when every
  required upstream has a token; optional upstreams that error or are
  declined are recorded as session-scoped skip rows.
• Skip rows reuse the existing UpstreamTokens storage row. Two
  new scalar fields (Skipped bool, SkippedReason string) on the
  existing row; the UpstreamTokenStorage interface is unchanged. The
  existing InProcessService.GetAllValidTokens / GetValidToken
  filter skip rows out of the live-token map, so identity.UpstreamTokens
  consumers behave exactly as today when no rows are skipped.
• No /authorize restart-all branch. The existing handler already
  mints a fresh SessionID per call, so re-running /authorize is
  structurally a new session — prior session rows age out under their
  existing TTL. Per-upstream retry is explicitly rejected — identity-
  binding hazards outweigh the round-trip savings.
• vMCP filters by skipping unauthorized backend init. vMCP freezes
  the per-session capability set at MCP initialize time, so the
  filter hooks into the pre-init backend filter loop of
  makeBaseSession: backends whose required upstream is missing from
  identity.UpstreamTokens never run initOneBackend at all — no HTTP
  connection, no handshake, no capability listing, no entry into the
  routing table or per-session SDK tool store.
• No new dispatcher gate. Out-of-band revocation between
  initialize and call is already caught by the existing per-request
  identity.UpstreamTokens re-hydration plus each backend auth
  strategy's ErrUpstreamTokenNotFound path.
• Recovery is whole-session. A fresh /authorize produces a new
  JWT with a new tsid; reconnecting to vMCP with the new bearer
  triggers a fresh initialize and re-aggregates capabilities.
• vMCP does not extend the MCP protocol to signal filtered state.

Out of scope

Per-upstream retry, MCP-protocol-level signaling of filtered state,
silent backend dropping on RT expiry, proactive token introspection,
dynamic upstream addition.

Notes for reviewers

• Implementation is sequenced runtime-first → CRD-last so chain-logic
  and filtering can land and be tested before the CRD surface
  solidifies.
• All initial open questions (revocation detection, skip-row TTL,
  metric cardinality, status conditions) were resolved during drafting;
  see the body for the decisions.
• The RFC originated in the toolhive repo via Claude Code (referencing
  source line numbers); file-path references are plain text so they
  remain readable when the RFC is moved to its destination repo.

🤖 Generated with Claude Code

[jhrozek]

very nice thank you