Skip to content

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

TypeScript
27.4 KB
Raw Blame
/**
 * Shared reader for an OAuth McpServer's `spec.oauth` declaration.
 *
 * The grant-scope / oauthClientId / contextRef derivation is a security-relevant
 * rule (it decides WHICH grant coordinate governs a server). It is consumed by
 * three seams that must never drift apart (D4):
 *   - the token broker (`routes/mcpOauth.ts`) — the LLM/tool-call rail;
 *   - the rpc-proxy grant-presence gate (`services/access/mcpInvocable.ts`);
 *   - the grant-existence sweep (`routes/mcpOauth.ts`, mini-spec 13) — the
 *     hot-revocation poll.
 * All read the SAME fields the SAME way and derive the SAME `oauth_grants` key
 * (`buildMcpServerGrantKey`), so the rule lives here once.
 */
import { rootLogger } from '../observability/logger.js'
import {
  detectAsProfile,
  isAsProfileId,
  profileHasResourceScope,
  profileScopeViolation,
  remoteWireForProfile,
  withProfileScopes,
} from './asProfiles.js'
import type {
  GenericClientRouting,
  OAuthClientDecl,
  RemoteClientRouting,
  ServerOAuthSecretSource,
} from './callback.js'
import { isCimdClientId } from './cimdIdentity.js'
import { checkAsEndpointsSameSite } from './discovery.js'
import { MAX_EXTRA_AUTHORIZE_PARAMS, MAX_EXTRA_AUTHORIZE_PARAM_VALUE_LEN } from './genericKnobs.js'
import { remoteCallbackVariant } from './remoteCallback.js'
import type { OAuthGrantKey } from './store.js'

const log = rootLogger.child({ module: 'mcp-server-oauth-spec' })

export interface McpServerOAuthDecl {
  id?: unknown
  provider?: unknown
  clientIdRef?: { name?: unknown; key?: unknown }
  clientSecretRef?: { name?: unknown; key?: unknown }
  scopes?: unknown
  backgroundAccess?: unknown
  grantScope?: unknown
  // Remote MCP-OAuth lane (`source:'remote'`, C1.5/C2/C3). Untrusted CR data →
  // every field is validated before use; a malformed remote block fails closed.
  source?: unknown
  clientMode?: unknown
  authorizationEndpoint?: unknown
  tokenEndpoint?: unknown
  registrationEndpoint?: unknown
  issuer?: unknown
  resource?: unknown
  bearerInBody?: unknown
  supportsRefresh?: unknown
  issForCallback?: unknown
  asProfile?: unknown
  // Generic self-hosted lane (`source:'generic'`, DEC-28). Untrusted CR data →
  // every field is validated before use; a malformed generic block fails closed.
  refreshEndpoint?: unknown
  tokenRequestFormat?: unknown
  tokenAuthMethod?: unknown
  scopeSeparator?: unknown
  sendScope?: unknown
  usePkce?: unknown
  includeResponseType?: unknown
  extraAuthorizeParams?: unknown
}

/** Minimal structural shape needed to resolve a server's OAuth grant coordinate. */
export interface McpServerOAuthSpecInput {
  metadata?: { uid?: unknown; name?: unknown }
  spec?: {
    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
    remote?: { baseUrl?: unknown }
  }
}

export type GrantScope = 'user' | 'context'

export interface ResolvedServerOAuth {
  oauthClientId: string
  grantScope: GrantScope
  /** Authoritative Context of the server (spec.contextRef); undefined if absent. */
  contextRef?: string
  /**
   * metadata.uid of the CR this resolution was read from — the installation
   * identity grant reads are fenced by. Undefined when the object carried none.
   */
  crUid?: string
  /**
   * The CR's `spec.oauth.provider`, present only on the baked lane. It lets the
   * store serve an unsealed (legacy) grant written by a pod without install
   * identity, and only one of this same provider.
   */
  legacyProvider?: string
}

/**
 * OAuth lane of a McpServer. `unknown` is a `source` value no reader recognises;
 * callers that need a decl keep treating it as baked, but it never qualifies for
 * legacy (unsealed) grants.
 */
export type McpServerOAuthLane = 'baked' | 'remote' | 'generic' | 'unknown'

/**
 * The single lane classifier for `spec.oauth.source`: absent (undefined/null) ⇒
 * baked; the literals `'remote'`/`'generic'`; any other value (including `''`) ⇒
 * unknown.
 */
export function readOAuthLane(oauth: McpServerOAuthDecl): McpServerOAuthLane {
  const source = oauth.source
  if (source === undefined || source === null) return 'baked'
  if (source === 'remote' || source === 'generic') return source
  return 'unknown'
}

/**
 * The apiserver's `metadata.uid` of a McpServer, or undefined when absent or not
 * a non-empty string. Never defaulted: an unknown identity must not match a
 * sealed grant.
 */
export function readCrUid(server: McpServerOAuthSpecInput): string | undefined {
  const uid = server.metadata?.uid
  return typeof uid === 'string' && uid.length > 0 ? uid : undefined
}

/**
 * Derive `{ oauthClientId, grantScope, contextRef, crUid }` from a McpServer's
 * `spec.oauth`. Returns null when the server carries no usable OAuth id, so
 * callers fail closed. `grantScope` defaults to `'user'` for anything other
 * than the explicit `'context'` sentinel (U1: immutable per server, CEL-guarded).
 */
export function resolveServerOAuth(server: McpServerOAuthSpecInput): ResolvedServerOAuth | null {
  const oauth = server.spec?.oauth
  if (!oauth || typeof oauth.id !== 'string' || oauth.id.length === 0) return null
  const grantScope: GrantScope = oauth.grantScope === 'context' ? 'context' : 'user'
  const contextRef =
    typeof server.spec?.contextRef === 'string' && server.spec.contextRef.length > 0
      ? server.spec.contextRef
      : undefined
  const legacyProvider =
    readOAuthLane(oauth) === 'baked' &&
    typeof oauth.provider === 'string' &&
    oauth.provider.length > 0
      ? oauth.provider
      : undefined
  return {
    oauthClientId: oauth.id,
    grantScope,
    contextRef,
    crUid: readCrUid(server),
    ...(legacyProvider ? { legacyProvider } : {}),
  }
}

/** The coordinates the caller supplies to derive an mcp-server grant key. */
export interface McpServerGrantKeyCoords {
  /** McpServer name — reinterpreted as the grant owner's `recipeName`. */
  mcpServerName: string
  /** The mcp-servers namespace — the grant owner's `recipeNamespace`. */
  mcpServersNamespace: string
  /**
   * End-user identity, for `grantScope='user'` servers only. IGNORED for
   * `context` servers, which key by the server's AUTHORITATIVE `contextRef`
   * (server-side), never by any caller-supplied context value.
   */
  userId?: string
}

/**
 * Derive the `oauth_grants` key for an OAuth McpServer by flavor — the SINGLE
 * key derivation shared by the token mint, the rpc-proxy grant-presence gate,
 * the grant-existence sweep, and the end-user disconnect endpoint
 * (`internal/oauth.ts`) — delete (D4: one authority, no drift). Returns null when
 * the coordinate the flavor needs is absent, so every caller decides fail-open
 * vs fail-closed for itself:
 *   - `user`    → needs a non-empty `userId`; null otherwise.
 *   - `context` → keys by the server's AUTHORITATIVE `contextRef` (server-side,
 *                 NEVER a body value); null when the server carries none.
 *
 * It intentionally does NOT read the token or touch the DB — it only maps a
 * resolved OAuth declaration + coordinates to a key.
 *
 * A missing `crUid` never yields null: the key is still built and the store
 * treats an mcp-server key without a uid as matching no row. Returning null here
 * would push the grant-existence sweep into its fail-open branch (`exists:true`),
 * so a revoked token cached in mcp-host would never be evicted.
 */
export function buildMcpServerGrantKey(
  resolved: ResolvedServerOAuth,
  coords: McpServerGrantKeyCoords
): OAuthGrantKey | null {
  if (resolved.grantScope === 'context') {
    // Shared identity is keyed by the server's authoritative Context, decoupled
    // from any caller-supplied userId/contextId (no body-trust).
    if (!resolved.contextRef) return null
    return {
      grantKind: 'shared',
      ownerKind: 'mcpserver',
      recipeNamespace: coords.mcpServersNamespace,
      recipeName: coords.mcpServerName,
      contextId: resolved.contextRef,
      oauthClientId: resolved.oauthClientId,
      crUid: resolved.crUid,
      ...(resolved.legacyProvider ? { legacyProvider: resolved.legacyProvider } : {}),
    }
  }
  if (typeof coords.userId !== 'string' || coords.userId.length === 0) return null
  return {
    grantKind: 'user',
    ownerKind: 'mcpserver',
    recipeNamespace: coords.mcpServersNamespace,
    recipeName: coords.mcpServerName,
    userId: coords.userId,
    oauthClientId: resolved.oauthClientId,
    crUid: resolved.crUid,
    ...(resolved.legacyProvider ? { legacyProvider: resolved.legacyProvider } : {}),
  }
}

/**
 * The `spec.oauth` declaration in the `oauthClients[]`-compatible shape the
 * consent flow (U5: authorize-URL mint + callback) consumes, plus the grant
 * routing. Structurally assignable to `OAuthClientDecl` (`oauth/callback.ts`) so
 * the same broker/refresh machinery stays owner-agnostic.
 */
export interface ResolvedServerOAuthSubject {
  /**
   * The `oauthClients[]`-compatible client decl. For BAKED (no `source`) it is
   * byte-identical to the confidential-K8s shape (id/provider + both refs). For
   * REMOTE (`source:'remote'`) it carries `remote` routing + a `secretSource`
   * discriminator and OMITS `clientSecretRef`/`clientIdRef` unless the mode is
   * pre-registered-confidential (`k8s-secret`).
   */
  decl: OAuthClientDecl
  grantScope: GrantScope
  /** Authoritative Context (spec.contextRef); undefined if absent. */
  contextRef?: string
  /** metadata.uid of the CR this subject was read from; undefined if absent. */
  crUid?: string
}

export type RemoteOAuthSpecIncoherence =
  | 'public_client_with_secret_refs'
  | 'bearer_in_body'
  | 'cimd_without_issuer_binding'
  | 'as_endpoints_cross_site'
  | 'as_profile_issuer_mismatch'
  | 'scope_audience_mismatch'

/**
 * A remote `spec.oauth` the admission rules reject but that reached the apiserver
 * anyway (CRD applied after the object, or a write that bypassed validation, e.g. by
 * kubectl/GitOps). The phase using it refuses it with this specific error instead of
 * degrading to a generic failure: the CRD-mirror reasons (`public_client_with_secret_refs`,
 * `bearer_in_body`, `as_profile_issuer_mismatch`) and the profile's scope audience
 * (`scope_audience_mismatch`) in consent and token issuance alike; the per-server callback
 * reasons (`cimd_without_issuer_binding`, `as_endpoints_cross_site`) only in consent
 * (authorize-URL minting and the callback), so grants already obtained keep serving.
 */
export class RemoteOAuthSpecIncoherentError extends Error {
  readonly code = 'remote_oauth_spec_incoherent'
  constructor(readonly reason: RemoteOAuthSpecIncoherence) {
    super(`remote spec.oauth is incoherent: ${reason}`)
    this.name = 'RemoteOAuthSpecIncoherentError'
  }
}

/**
 * Where a remote server's `spec.oauth` is being used:
 *   - `consent` — authorize-URL minting and the OAuth callback, where a new code is
 *                 issued and redeemed;
 *   - `token`   — serving and refreshing a grant already obtained (user-token, the
 *                 reactive refresh and the proactive cron).
 * Required at every call site, with no default, so no reader silently picks a phase.
 */
export type RemoteOAuthCoherencePhase = 'consent' | 'token'

function remoteOAuthSpecIncoherence(
  oauth: McpServerOAuthDecl,
  baseUrl: unknown,
  phase: RemoteOAuthCoherencePhase
): RemoteOAuthSpecIncoherence | null {
  if (
    oauth.clientMode === 'public' &&
    (oauth.clientIdRef != null || oauth.clientSecretRef != null)
  ) {
    return 'public_client_with_secret_refs'
  }
  if (oauth.bearerInBody === true) return 'bearer_in_body'
  // A profile stops sending RFC 8707 `resource`, so it is only honoured on the issuer it
  // is recognised from; anywhere else it would strip the audience binding of another AS.
  if (
    oauth.asProfile !== undefined &&
    (!isAsProfileId(oauth.asProfile) ||
      typeof oauth.issuer !== 'string' ||
      detectAsProfile(oauth.issuer)?.id !== oauth.asProfile)
  ) {
    return 'as_profile_issuer_mismatch'
  }
  // The converse: the install always pins the profile its issuer is recognised from, so
  // a tenant issuer without one was written outside it, typically by an apiserver whose
  // CRD predates the field and pruned it. On the generic wire that issuer either rejects
  // the exchange or picks the audience from the browser's scopes.
  if (
    oauth.asProfile === undefined &&
    typeof oauth.issuer === 'string' &&
    detectAsProfile(oauth.issuer) !== null
  ) {
    return 'as_profile_issuer_mismatch'
  }
  // Without `resource` the scopes alone pick the token's audience, and the scopes or the
  // base URL can be edited after the install (API or kubectl). The hard audience rules
  // are therefore re-checked against the base URL in force now: a known API's GUID scope
  // off its own host is refused. GUID scopes of an API the platform does not know pass:
  // writing the CR is the operator's confirmation.
  if (oauth.asProfile === 'entra-v2') {
    const scopes = withProfileScopes(normalizeScopes(oauth.scopes) ?? [], 'entra-v2')
    if (
      typeof baseUrl !== 'string' ||
      !URL.canParse(baseUrl) ||
      profileScopeViolation('entra-v2', baseUrl, scopes) !== null ||
      !profileHasResourceScope('entra-v2', baseUrl, scopes)
    ) {
      return 'scope_audience_mismatch'
    }
  }
  // The per-server rules defend the authorization response (which AS minted a code, and
  // where it is redeemed). A grant already obtained is sealed to this CR's uid and its
  // endpoints are immutable, so a refresh only ever returns to the token endpoint that
  // issued it: blocking it would strand existing grants without closing any mix-up.
  if (phase === 'consent' && remoteCallbackVariant(oauth) === 'per-server') {
    // The CIMD document lists only the shared callback, so its client can never be
    // bound to one server's redirect URI; without `iss` nothing else ties its codes to
    // this server.
    if (isCimdClientId(oauth.id)) return 'cimd_without_issuer_binding'
    if (!asEndpointsOnIssuerSite(oauth)) return 'as_endpoints_cross_site'
  }
  return null
}

/**
 * The install-time same-site rule, re-applied to the endpoints pinned on a per-server
 * CR. The install already enforces it, but a CR written straight to the apiserver
 * skips the install, and without `iss` a token endpoint off the issuer's site would
 * redeem our codes. An endpoint that is not a string is left to the routing reader,
 * which fails closed on it; a missing issuer fails here, since per-server consent
 * cannot be anchored without one.
 */
function asEndpointsOnIssuerSite(oauth: McpServerOAuthDecl): boolean {
  const optional = (value: unknown): string | undefined =>
    typeof value === 'string' && value.length > 0 ? value : undefined
  const authorization = optional(oauth.authorizationEndpoint)
  const token = optional(oauth.tokenEndpoint)
  if (authorization === undefined || token === undefined) return true
  const registration = optional(oauth.registrationEndpoint)
  return checkAsEndpointsSameSite({
    issuer: typeof oauth.issuer === 'string' ? oauth.issuer : '',
    authorization,
    token,
    ...(registration ? { registration } : {}),
  }).ok
}

/**
 * Runtime mirror of the remote-carril coherence rules of the McpServer CRD
 * (REMOTE-SECRET-PAIRING for `public`, REMOTE-BEARER-HEADER, AS-PROFILE-ISSUER), of the
 * install's profile pinning (a recognised issuer always carries its profile; the CRD does
 * not require it, and an older CRD prunes the field), of the install's
 * scope-audience rules for an authorization-server profile, and of the install's
 * per-server callback rules (no CIMD client and same-site AS endpoints when the AS
 * does not return `iss`, which the CRD cannot express). Throws
 * {@link RemoteOAuthSpecIncoherentError} for a remote server whose shape no
 * install path produces; a no-op for every other lane. The CRD mirrors apply in both
 * phases; the per-server callback rules only in `consent` (see
 * {@link RemoteOAuthCoherencePhase}).
 *
 * Deliberately NOT applied by {@link resolveServerOAuth}: that coordinate backs
 * revoke and the grant-existence sweep, and an incoherent server must still be
 * disconnectable and must not push the sweep into its fail-open branch.
 */
export function assertRemoteOAuthSpecCoherent(
  server: McpServerOAuthSpecInput,
  phase: RemoteOAuthCoherencePhase
): void {
  const oauth = server.spec?.oauth
  if (!oauth || readOAuthLane(oauth) !== 'remote') return
  const reason = remoteOAuthSpecIncoherence(oauth, server.spec?.remote?.baseUrl, phase)
  if (!reason) return
  const name = server.metadata?.name
  log.warn(
    {
      event: 'remote_oauth_spec_incoherent',
      mcpServerName: typeof name === 'string' ? name : undefined,
      reason,
      phase,
    },
    'remote mcp-server oauth spec is incoherent; refusing it in this phase'
  )
  throw new RemoteOAuthSpecIncoherentError(reason)
}

/** Extract + type-validate the remote routing block from an untrusted `spec.oauth`. */
function extractRemoteRouting(oauth: McpServerOAuthDecl): RemoteClientRouting | null {
  const clientMode = oauth.clientMode
  if (clientMode !== 'public' && clientMode !== 'confidential') return null
  const authorizationEndpoint = oauth.authorizationEndpoint
  const tokenEndpoint = oauth.tokenEndpoint
  if (typeof authorizationEndpoint !== 'string' || authorizationEndpoint.length === 0) return null
  if (typeof tokenEndpoint !== 'string' || tokenEndpoint.length === 0) return null
  const asProfile = isAsProfileId(oauth.asProfile) ? oauth.asProfile : undefined
  // The CR keeps the PRM's `resource` for audit even when the profile does not send it.
  const resource =
    remoteWireForProfile(asProfile).sendResource &&
    typeof oauth.resource === 'string' &&
    oauth.resource.length > 0
      ? oauth.resource
      : undefined
  const issForCallback =
    typeof oauth.issForCallback === 'string' && oauth.issForCallback.length > 0
      ? oauth.issForCallback
      : undefined
  const issuer =
    typeof oauth.issuer === 'string' && oauth.issuer.length > 0 ? oauth.issuer : undefined
  return {
    authorizationEndpoint,
    tokenEndpoint,
    resource,
    clientMode,
    bearerInBody: oauth.bearerInBody === true,
    supportsRefresh: oauth.supportsRefresh === true,
    issForCallback,
    ...(issuer ? { issuer } : {}),
    ...(asProfile ? { asProfile } : {}),
  }
}

/** Read a nested `{name,key}` ref, returning null unless BOTH are non-empty strings. */
function readRef(
  ref: { name?: unknown; key?: unknown } | undefined
): { name: string; key: string } | null {
  if (!ref || typeof ref.name !== 'string' || typeof ref.key !== 'string') return null
  return { name: ref.name, key: ref.key }
}

/**
 * Classify a remote client's secret source (DEC-18): refs present ⇒ K8s Secret
 * (pre-registered confidential); no refs + confidential ⇒ encrypted DCR store;
 * no refs + public ⇒ no secret. `public` with refs never reaches here:
 * {@link assertRemoteOAuthSpecCoherent} rejects it first.
 */
function resolveRemoteSecretSource(
  oauth: McpServerOAuthDecl,
  clientMode: 'public' | 'confidential'
): ServerOAuthSecretSource {
  const clientIdRef = readRef(oauth.clientIdRef)
  const clientSecretRef = readRef(oauth.clientSecretRef)
  if (clientIdRef && clientSecretRef) {
    return { kind: 'k8s-secret', clientIdRef, clientSecretRef }
  }
  return clientMode === 'confidential' ? { kind: 'dcr-store' } : { kind: 'public' }
}

/**
 * Read the optional `extraAuthorizeParams` map, keeping only string-valued keys and
 * enforcing the same bounds as the install-side schema (genericKnobs). A CR can be
 * written straight to the apiserver, bypassing admission, so the runtime reader is
 * the last gate before these land in the authorize URL: over-long values are dropped
 * (never truncated or forwarded) and the map is capped at MAX_EXTRA_AUTHORIZE_PARAMS.
 */
function extractExtraAuthorizeParams(raw: unknown): Record<string, string> | undefined {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined
  const out: Record<string, string> = {}
  for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
    if (typeof v !== 'string' || v.length > MAX_EXTRA_AUTHORIZE_PARAM_VALUE_LEN) continue
    out[k] = v
    if (Object.keys(out).length >= MAX_EXTRA_AUTHORIZE_PARAMS) break
  }
  return Object.keys(out).length > 0 ? out : undefined
}

/**
 * Extract + type-validate the generic routing block from an untrusted `spec.oauth`
 * (DEC-28). The three wire enums (`tokenRequestFormat`/`tokenAuthMethod`/
 * `scopeSeparator`) fail closed to null when malformed; the booleans read as
 * `=== true` (absent ⇒ false), mirroring the remote block's boolean handling.
 */
function extractGenericRouting(oauth: McpServerOAuthDecl): GenericClientRouting | null {
  const authorizationEndpoint = oauth.authorizationEndpoint
  const tokenEndpoint = oauth.tokenEndpoint
  if (typeof authorizationEndpoint !== 'string' || authorizationEndpoint.length === 0) return null
  if (typeof tokenEndpoint !== 'string' || tokenEndpoint.length === 0) return null
  const tokenRequestFormat = oauth.tokenRequestFormat
  if (tokenRequestFormat !== 'form' && tokenRequestFormat !== 'json') return null
  const tokenAuthMethod = oauth.tokenAuthMethod
  if (tokenAuthMethod !== 'body' && tokenAuthMethod !== 'basic') return null
  const scopeSeparator = oauth.scopeSeparator
  if (scopeSeparator !== 'space' && scopeSeparator !== 'comma') return null
  const refreshEndpoint =
    typeof oauth.refreshEndpoint === 'string' && oauth.refreshEndpoint.length > 0
      ? oauth.refreshEndpoint
      : undefined
  const resource =
    typeof oauth.resource === 'string' && oauth.resource.length > 0 ? oauth.resource : undefined
  return {
    authorizationEndpoint,
    tokenEndpoint,
    refreshEndpoint,
    resource,
    tokenRequestFormat,
    tokenAuthMethod,
    scopeSeparator,
    sendScope: oauth.sendScope === true,
    usePkce: oauth.usePkce === true,
    includeResponseType: oauth.includeResponseType === true,
    supportsRefresh: oauth.supportsRefresh === true,
    extraAuthorizeParams: extractExtraAuthorizeParams(oauth.extraAuthorizeParams),
  }
}

/**
 * Classify a generic client's secret source (DEC-28): NEITHER ref ⇒ public (no
 * secret; `client_id` IS `oauth.id`); BOTH refs ⇒ k8s-secret (reuse the shared
 * shape). Exactly one ref is a half-declared config ⇒ null (fail closed), never
 * silently treated as public.
 */
function resolveGenericSecretSource(oauth: McpServerOAuthDecl): ServerOAuthSecretSource | null {
  const clientIdRef = readRef(oauth.clientIdRef)
  const clientSecretRef = readRef(oauth.clientSecretRef)
  if (clientIdRef && clientSecretRef) {
    return { kind: 'k8s-secret', clientIdRef, clientSecretRef }
  }
  if (clientIdRef || clientSecretRef) return null
  return { kind: 'public' }
}

function normalizeScopes(scopes: unknown): string[] | undefined {
  return Array.isArray(scopes)
    ? scopes.filter((s): s is string => typeof s === 'string')
    : undefined
}

/**
 * Resolve a McpServer's full OAuth subject (decl + grant routing) for the U5
 * consent flow. Returns null when the server carries no usable OAuth
 * declaration (missing id/provider/clientIdRef/clientSecretRef) so callers fail
 * closed. Throws {@link RemoteOAuthSpecIncoherentError} for a remote server whose
 * shape the runtime cannot honor (see {@link assertRemoteOAuthSpecCoherent}).
 * Same field-reading rule as {@link resolveServerOAuth} — kept here so the
 * authorize-URL minter and the callback never drift (D4).
 *
 * Two lanes (C4/DEC-23), keyed uniformly by `oauth.id` (the install backfills it
 * for every remote mode, so the grant coordinate is uniform):
 *   - BAKED (no `source`): behaves EXACTLY as before — confidential-K8s, both
 *     refs required, `provider` required; returns the same decl shape. A public
 *     baked mcp-server is still not representable, so nothing reachable changes.
 *   - REMOTE (`source:'remote'`): `provider` is NOT required (no baked adapter);
 *     the decl carries `remote` routing + a `secretSource` discriminator and
 *     drops `clientSecretRef`/`clientIdRef` unless the mode is
 *     pre-registered-confidential. Stays PURE/synchronous — the caller reads the
 *     secret (K8s Secret or `getDynamicClient`) per `secretSource`.
 */
export function resolveServerOAuthSubject(
  server: McpServerOAuthSpecInput,
  phase: RemoteOAuthCoherencePhase
): ResolvedServerOAuthSubject | null {
  const oauth = server.spec?.oauth
  if (!oauth || typeof oauth.id !== 'string' || oauth.id.length === 0) return null
  const grantScope: GrantScope = oauth.grantScope === 'context' ? 'context' : 'user'
  const contextRef =
    typeof server.spec?.contextRef === 'string' && server.spec.contextRef.length > 0
      ? server.spec.contextRef
      : undefined
  const crUid = readCrUid(server)
  const lane = readOAuthLane(oauth)

  // ─── Remote lane (`source:'remote'`) ─────────────────────────────────────
  if (lane === 'remote') {
    assertRemoteOAuthSpecCoherent(server, phase)
    const remote = extractRemoteRouting(oauth)
    if (!remote) return null
    const secretSource = resolveRemoteSecretSource(oauth, remote.clientMode)
    const decl: OAuthClientDecl = {
      id: oauth.id,
      // No baked provider on the remote lane; exchange/refresh/authorize branch on
      // `remote` before any provider-adapter lookup. `'remote'` is the persisted /
      // displayed label.
      provider: 'remote',
      // With a profile the required scopes ride every authorize and refresh, even when
      // the CR (edited after the install) dropped them.
      scopes: withProfileScopes(normalizeScopes(oauth.scopes) ?? [], remote.asProfile),
      backgroundAccess: oauth.backgroundAccess === true,
      remote,
      secretSource,
    }
    if (secretSource.kind === 'k8s-secret') {
      decl.clientIdRef = secretSource.clientIdRef
      decl.clientSecretRef = secretSource.clientSecretRef
    }
    return { decl, grantScope, contextRef, crUid }
  }

  // ─── Generic self-hosted lane (`source:'generic'`, DEC-28) ────────────────
  if (lane === 'generic') {
    const generic = extractGenericRouting(oauth)
    if (!generic) return null
    const secretSource = resolveGenericSecretSource(oauth)
    if (!secretSource) return null
    const decl: OAuthClientDecl = {
      id: oauth.id,
      // No baked provider on the generic lane; exchange/refresh/authorize branch on
      // `generic` before any provider-adapter lookup. `'generic'` is the persisted /
      // displayed label only — it NEVER reaches ADAPTERS/KNOWN_OAUTH_PROVIDERS.
      provider: 'generic',
      scopes: normalizeScopes(oauth.scopes),
      backgroundAccess: oauth.backgroundAccess === true,
      generic,
      secretSource,
    }
    if (secretSource.kind === 'k8s-secret') {
      decl.clientIdRef = secretSource.clientIdRef
      decl.clientSecretRef = secretSource.clientSecretRef
    }
    return { decl, grantScope, contextRef, crUid }
  }

  // ─── Baked lane (byte-identical to before) ───────────────────────────────
  if (typeof oauth.provider !== 'string' || oauth.provider.length === 0) return null
  const clientIdRef = readRef(oauth.clientIdRef)
  const clientSecretRef = readRef(oauth.clientSecretRef)
  if (!clientIdRef || !clientSecretRef) return null
  return {
    decl: {
      id: oauth.id,
      provider: oauth.provider,
      clientIdRef,
      clientSecretRef,
      scopes: normalizeScopes(oauth.scopes),
      backgroundAccess: oauth.backgroundAccess === true,
    },
    grantScope,
    contextRef,
    crUid,
  }
}