Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* 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,
}
}