Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import type { DbClient } from '../db.js'
import type { PinnedTransport } from '../http/pinnedFetch.js'
import { pinnedFetch } from '../http/pinnedFetch.js'
import type { DnsResolver } from '../http/validateMcpServerSpec.js'
import { rootLogger } from '../observability/logger.js'
import { type AsProfileId, remoteWireForProfile } from './asProfiles.js'
import { getDynamicClient } from './dynamicClientStore.js'
import {
type RemoteOAuthSpecIncoherence,
RemoteOAuthSpecIncoherentError,
} from './mcpServerOAuthSpec.js'
import { buildPerServerRedirectUri, resolvePerServerRegistration } from './perServerRegistration.js'
import { deriveCodeVerifier } from './pkce.js'
import {
type GenericAdapterConfig,
type OAuthProvider,
type ParsedTokenResponse,
buildAdapterFromConfig,
buildRemoteTokenRequest,
getOAuthProviderAdapter,
isKnownOAuthProvider,
parseRemoteTokenResponse,
} from './providers.js'
import {
InvalidRemoteRedirectUriInputError,
REMOTE_CALLBACK_CLIENT_SEGMENT,
buildRemoteRedirectUri,
remoteCallbackVariant,
} from './remoteCallback.js'
import type { OAuthMcpStateClaims } from './state.js'
import { signOAuthState, verifyOAuthStateSignature } from './state.js'
import { bootstrapSharedOAuthGrant, setUserGrantBackground, upsertOAuthGrant } from './store.js'
// Reserved last URL segment of the shared remote OAuth callback. Defined in
// `remoteCallback.ts` (the single redirect-URI builder); re-exported for the existing
// importers of this module.
export { REMOTE_CALLBACK_CLIENT_SEGMENT }
const log = rootLogger.child({ module: 'oauth-callback' })
/**
* Discriminator for WHERE an mcp-server's OAuth client credentials live
* (DEC-18). Present only on a `source:'remote'` subject; baked/recipe decls read
* their K8s Secret via `clientIdRef`/`clientSecretRef` directly and carry none.
* - `k8s-secret` → pre-registered confidential: read the named Secret.
* - `dcr-store` → DCR-confidential: read the encrypted `dynamic_clients` row.
* - `public` → CIMD/DCR-public: no secret; `client_id` IS `oauth.id`.
*/
export type ServerOAuthSecretSource =
| {
kind: 'k8s-secret'
clientIdRef: { name: string; key: string }
clientSecretRef: { name: string; key: string }
}
| { kind: 'dcr-store' }
| { kind: 'public' }
/**
* Remote MCP-OAuth routing pinned on the CR at install (C1.5/C2/C3). Present only
* for a `source:'remote'` client; drives the discovery-derived exchange/refresh/
* authorize instead of a baked provider adapter. All endpoints are attacker-
* controlled (discovery-derived) ⇒ every fetch through them is IP-pinned (DEC-17).
*/
export interface RemoteClientRouting {
authorizationEndpoint: string
tokenEndpoint: string
/** RFC 8707 resource indicator; absent when the authorization-server profile does not send it. */
resource?: string
clientMode: 'public' | 'confidential'
/** D-8: token in the body vs Authorization header (mcp-host concern; carried for parity). */
bearerInBody: boolean
/** D-8: fail-closed — false ⇒ NEVER attempt a refresh. */
supportsRefresh: boolean
/** RFC 9207 issuer to validate the callback `iss` against, when advertised. */
issForCallback?: string
/**
* The pinned AS issuer. Without RFC 9207 an AS may still send `iss`; when it does,
* it must match this value rather than being ignored.
*/
issuer?: string
/** Closed authorization-server profile pinned on the CR; drives the wire (asProfiles.ts). */
asProfile?: AsProfileId
}
/**
* Generic self-hosted OAuth routing pinned on the CR (`source:'generic'`, DEC-28).
* Present only for a `source:'generic'` client; drives a KNOB-configured
* exchange/refresh/authorize via `buildAdapterFromConfig` instead of a baked
* provider adapter. Like the remote lane, the operator-supplied endpoints are
* attacker-influenced ⇒ every token/refresh POST is IP-pinned (DEC-17). Extends
* the pure wire knobs (`GenericAdapterConfig`, single source of truth in
* providers.ts) with the fail-closed `supportsRefresh` flag (D-8).
*/
export interface GenericClientRouting extends GenericAdapterConfig {
/** D-8: fail-closed — false ⇒ NEVER attempt a refresh. */
supportsRefresh: boolean
}
/**
* End-to-end handler for the auth-code OAuth callback. Independent of Express
* so we can unit-test it with stubs for K8s + DB + fetch. The route handler
* (`routes/external/oauthCallback.ts`) is a thin parse-params + delegate.
*
* Spec §9.9 / Decision 20.
*/
export interface OAuthClientDecl {
id: string
provider: string
/**
* Confidential-client id reference. Optional (C4/DEC-23): a remote PUBLIC or
* DCR client has no K8s ref — its `client_id` is `oauth.id` (`decl.id`) or the
* encrypted `dynamic_clients` row. Baked/recipe decls always carry it; the
* baked paths guard fail-closed if it is somehow absent (unreachable there).
*/
clientIdRef?: { name: string; key: string }
/**
* Confidential-client secret reference. Optional (E-19.2): a PUBLIC OAuth
* client declares no secret, so the callback reads only the client_id Secret
* and the token POST omits `client_secret`. When present, the confidential
* path is byte-identical to before.
*/
clientSecretRef?: { name: string; key: string }
scopes?: string[]
/**
* Path B — when true, this client may be connected as a recipe-scoped
* `service` grant for background workloads. The CRD OpenAPI field + admission
* validation land in phase 3; this reader type tolerates its absence (a
* recipe predating the field reads as `undefined` → fail closed).
*/
backgroundAccess?: boolean
/**
* Remote MCP-OAuth routing (`source:'remote'`). Present ⇒ the discovery-derived
* lane: exchange/refresh/authorize use the pinned endpoints + `secretSource`
* instead of a baked provider adapter. Absent ⇒ baked/recipe (byte-identical).
*/
remote?: RemoteClientRouting
/**
* Generic self-hosted OAuth routing (`source:'generic'`, DEC-28). Present ⇒ the
* knob-configured lane: exchange/refresh/authorize use the pinned endpoints +
* `buildAdapterFromConfig` + `secretSource` instead of a baked provider adapter.
* Mutually exclusive with `remote`. Absent ⇒ baked/recipe (byte-identical).
*/
generic?: GenericClientRouting
/**
* Where the remote/generic client credentials live (DEC-18). Present alongside
* `remote` or `generic`; absent ⇒ the legacy K8s `clientIdRef`/`clientSecretRef`
* path. For the generic lane it is `public` (no refs) or `k8s-secret` (both refs).
*/
secretSource?: ServerOAuthSecretSource
}
export interface RecipeWithOAuthClients {
/** `uid` is set for an McpServer owner: the installation its grants are sealed with. */
metadata?: { name?: string; namespace?: string; uid?: string }
spec?: { oauthClients?: OAuthClientDecl[] }
}
export interface SecretReader {
/**
* Read a Kubernetes Secret in the given namespace, returning a map of
* key → plaintext value. Caller handles 404s by mapping to a thrown
* `SecretNotFoundError`.
*/
read(name: string, namespace: string): Promise<Record<string, string>>
}
export interface RecipeReader {
read(name: string, namespace: string): Promise<RecipeWithOAuthClients | null>
}
/**
* Structural alias of {@link RecipeReader} for the generalized owner model (U1).
*
* An owner declaration reader resolves a grant owner — a WorkflowRecipe, or an
* OAuth McpServer — to the same `{ spec: { oauthClients: [...] } }` shape the
* broker + refresh path already consume. The McpServer variant normalizes its
* single `spec.oauth` object into a one-element `oauthClients` array so the
* downstream code (`getAccessToken`) stays owner-agnostic. It is deliberately a
* plain alias (single method `read(name, namespace)`) so it can be injected
* per-router with a minimal blast radius — `tokenHelper.ts` and `state.ts` are
* untouched. (Generalizing `OAuthStateClaims` is U5, not here.)
*/
export type OwnerDeclReader = RecipeReader
/**
* An OAuth McpServer subject, resolved for the U5 callback / authorize-URL
* paths. Unlike {@link OwnerDeclReader} (which flattens a server to the
* owner-agnostic `oauthClients` shape for the refresh path), this carries the
* extra routing the consent flow needs:
* - `namespace` — the mcp-servers namespace the server + its Secrets live in;
* also the grant owner coordinate. Kept on the subject so the pure callback
* never imports config.
* - `grantScope` — `'user'` → per-user grant `(server, userId)`;
* `'context'` → shared grant `(server, contextRef)` (U6 governance).
* - `contextRef` — the AUTHORITATIVE Context (`spec.contextRef`), the shared
* grant coordinate. NEVER taken from the state or a body param.
*/
export interface McpServerOAuthSubject {
namespace: string
decl: OAuthClientDecl
grantScope: 'user' | 'context'
contextRef?: string
/**
* metadata.uid of the McpServer CR the subject was read from. The callback seals
* the grant it writes with it and fences the DCR credential read by it; the
* authorize-url mint carries it too but never persists a grant. Absent only when
* the CR carried no uid.
*/
crUid?: string
}
export interface McpServerOAuthReader {
/**
* Resolve an OAuth McpServer by name from the mcp-servers namespace. Returns
* null when the server does not exist or is not a usable OAuth server, so
* callers fail closed. May throw {@link RecipeNotFoundError} for a hard 404, or
* {@link RemoteOAuthSpecIncoherentError} for a remote spec the runtime cannot honor.
*/
read(mcpServerName: string): Promise<McpServerOAuthSubject | null>
}
export class SecretNotFoundError extends Error {}
export class RecipeNotFoundError extends Error {}
/**
* Which callback URL the provider redirected to. Decided by the route from the path
* shape alone; the handler then checks it against the signed state and the CR.
*
* - `client` — `/oauth-callback/<oauthClientId>` (recipe, baked, generic).
* - `remote-shared` — `/oauth-callback/remote`: every remote server whose AS
* returns RFC 9207 `iss`, which is what binds the code there.
* - `remote-per-server` — `/oauth-callback/remote/<serverName>[/<installNonce>]`: a
* remote server whose AS does not return `iss`, where the URI
* itself is the binding. Both segments are already validated.
*
* The remote kinds carry an origin, not a URI: the redirect URI replayed on the token
* exchange is rebuilt from the signed state and the CR once they have been checked,
* never from the request path.
*/
export type CallbackTarget =
| {
kind: 'client'
id: string
/** Public URL registered for this client; replayed on the token POST. */
redirectUri: string
}
| {
kind: 'remote-shared'
/** Origin of the shared callback (the configured base URL, else the request Host). */
origin: string
}
| {
kind: 'remote-per-server'
serverName: string
installNonce?: string
/** The configured public origin; null when none is configured (fails closed). */
origin: string | null
}
export interface CallbackInput {
target: CallbackTarget
/** OAuth `code` query parameter from the provider redirect. */
code: string
/** Signed state value (we re-verify before doing anything). */
state: string
/**
* RFC 9207 `iss` exactly as parsed from the query (`req.query.iss`): a string, an
* array when repeated, an object for bracket syntax, or undefined. Kept raw because
* the two remote variants read it differently: the shared callback treats anything
* but a string as absent, while the per-server callback rejects a malformed value
* instead of letting it pass as "no iss". Ignored on the `client` target.
*/
iss?: unknown
}
export interface CallbackDeps {
db: DbClient
recipeReader: RecipeReader
secretReader: SecretReader
/**
* Resolver for OAuth McpServer subjects (U5). Required to process an
* mcp-subject state; when absent, an mcp state fails closed
* (`server_not_found`). Recipe callbacks never touch it.
*/
mcpServerReader?: McpServerOAuthReader
/**
* Resolve the Contexts a user is a member of (via `user_contexts`). Required
* ONLY for the shared-identity mcp bootstrap (`grantScope='context'`): a
* shared grant plants a team credential for everyone in the Context, so the
* consenting user MUST be a member first. Injected so the pure callback stays
* testable; the route wires the real `getUserContexts`. When absent on a
* shared-context path, that path fails closed (`context_membership_denied`).
* The per-user path never touches it: its access check is
* `userServerAccessReader`.
*/
userContextsReader?: (userId: string) => Promise<{ contextIds: string[] }>
/**
* Whether some Context the user reaches (directly, or through an agent
* assigned to them) still enables the server through its `spec.mcpServers`
* allowlist. Required ONLY for the per-user mcp path
* (`grantScope='user'`), re-checked before the code exchange so a user who
* lost that access after the authorize URL was minted cannot finish creating
* a grant. The route wires the same rule the authorize-URL mint applies. When
* absent on a per-user path, that path fails closed
* (`context_membership_denied`). The shared-context path never touches it.
*/
userServerAccessReader?: (userId: string, mcpServerName: string) => Promise<boolean>
/**
* Injectable for tests; defaults to globalThis.fetch in production wiring.
* BAKED lane ONLY — the remote lane (`source:'remote'`) never uses it (DEC-17):
* its endpoint is discovery-derived, so it goes through the IP-pinned
* `pinnedFetch` to close the DNS-rebinding TOCTOU (H2).
*/
fetchFn: typeof fetch
/** HMAC secret used to sign / verify state. */
stateSecret: string
/** AES-256-GCM key used to encrypt refresh tokens at rest. */
encryptionKey: Buffer
/** Optional override for token-exchange request timeout. Default 15s. */
tokenRequestTimeoutMs?: number
/**
* Remote lane only: injectable DNS resolver + pinned transport for
* `pinnedFetch`. Production leaves both undefined (real resolve + real
* `node:https`); tests inject to assert `connectedIP === validatedIP`.
*/
resolveDns?: DnsResolver
pinnedTransport?: PinnedTransport
}
/**
* Provider label persisted / displayed. `'remote'` for the discovery-derived lane,
* `'generic'` for the knob-configured self-hosted lane (DEC-28).
*/
export type GrantProviderLabel = OAuthProvider | 'remote' | 'generic'
export type CallbackResult =
| {
kind: 'ok'
provider: GrantProviderLabel
userId: string
grantKind: 'user' | 'service'
/** Whether the user explicitly requested background access in this flow. */
backgroundRequested: boolean
/**
* Whether background access was successfully enabled — true only when
* `backgroundRequested` is true AND the provider returned a refresh token.
* When false and backgroundRequested is true, the user reconnected but the
* provider did not issue a refresh token, so background access could not be
* established.
*/
backgroundEnabled: boolean
/**
* Subject that consented. Absent (undefined) for the recipe subject — the
* recipe deep-link is FROZEN and carries no `source`. Set to `'mcp'` for an
* OAuth McpServer subject so the route appends `&source=mcp` to the return
* deep-link (U5).
*/
source?: 'mcp'
/**
* The consented mcp-server's name — present only on the `source:'mcp'`
* path. Comes from the signed state (authoritative), never a body param.
* The route forwards it into the deep-link (`&mcpServerName=…`) so the
* desktop can correlate which suspended task to resume under concurrent
* suspensions.
*/
mcpServerName?: string
}
| { kind: 'invalid_state'; reason: string }
/**
* RFC 9207 authorization-server mix-up defence: the callback `iss` did not
* match the AS issuer pinned on the remote server (`issForCallback`), or was
* absent when one was advertised. Fail closed BEFORE the single-use code is
* exchanged. No value fields — the issuer strings are NEVER echoed back.
*/
| { kind: 'issuer_mismatch' }
/**
* RFC 9207 mix-up defence, absence case: a remote subject reached the SHARED
* remote callback but no issuer was pinned at install (`issForCallback` absent),
* so the callback cannot attribute the code to an authorization server. Fail
* closed BEFORE the single-use code is exchanged. No value fields.
*/
| { kind: 'issuer_binding_required' }
/**
* A per-server remote callback with no usable configured public origin: its redirect
* URI cannot be rebuilt byte-for-byte, so the code is not exchanged.
*/
| { kind: 'callback_base_url_unconfigured' }
| { kind: 'unknown_oauth_client' }
| { kind: 'recipe_not_found' }
/** mcp subject: the McpServer named in the signed state does not exist / is not OAuth. */
| { kind: 'server_not_found' }
/**
* mcp subject with `grantScope='context'` but no authoritative `spec.contextRef`
* — the shared grant coordinate is unresolvable, so there is nothing safe to
* persist. Fail closed (mini-spec 05 §2).
*/
| { kind: 'server_missing_context' }
/**
* mcp subject whose consenting (signed) user lacks access, by flavor:
* - `grantScope='context'`: not a member of the server's `spec.contextRef`
* (a shared grant lends a Context-wide credential);
* - `grantScope='user'`: no Context the user reaches (directly or through an
* assigned agent) still lists the server in its `spec.mcpServers` allowlist.
* Also returned when the reader for that flavor is not wired. Fail closed →
* 403, no code exchange, no persist.
*/
| { kind: 'context_membership_denied' }
/**
* mcp subject whose remote `spec.oauth` the runtime cannot honor (public client
* with secret refs, or bearerInBody). Fail closed BEFORE the code is exchanged.
*/
| { kind: 'remote_oauth_spec_incoherent'; reason: RemoteOAuthSpecIncoherence }
| { kind: 'secret_missing'; secret: string }
| { kind: 'unsupported_provider'; provider: string }
| { kind: 'provider_token_exchange_failed'; status: number; body: string }
| { kind: 'provider_response_invalid'; detail: string }
const BINDING_MISMATCH = { kind: 'invalid_state', reason: 'binding_mismatch' } as const
/**
* Run the full callback flow. Pure relative to its `CallbackDeps` so tests
* inject stub readers / fetch / db.
*/
export async function handleOAuthCallback(
input: CallbackInput,
deps: CallbackDeps
): Promise<CallbackResult> {
// ─── 1. Verify state signature, recover binding from the claims ───────
// The callback URL no longer carries the subject coordinates — they are
// recovered from the signed, unforgeable state. Whatever the URL does carry is
// cross-checked against the claims: the subject identity itself needs no such
// check (the HMAC guarantees it), but the URL is where the AS delivered the code,
// and on the per-server remote callback that location IS the mix-up defence.
const verified = verifyOAuthStateSignature(deps.stateSecret, input.state)
if (verified.kind !== 'ok') {
return { kind: 'invalid_state', reason: verified.kind }
}
const claims = verified.claims
const target = input.target
if (claims.subjectKind === 'mcp') {
// `/oauth-callback/<id>`: the segment must be the signed client id.
if (target.kind === 'client' && claims.oauthClientId !== target.id) return BINDING_MISMATCH
// `/remote/<serverName>/…`: a code delivered to one server's URI must never be
// attributed to another, and this is decided before the CR the state names is even
// read — an AS that redirects to `a` with `b`'s state learns nothing about `b`.
if (target.kind === 'remote-per-server' && claims.mcpServerName !== target.serverName) {
return BINDING_MISMATCH
}
return handleMcpOAuthCallback(claims, input, deps)
}
// Recipe subject. The per-server URI only exists for remote mcp servers. A recipe
// client may legitimately be named `remote` (operator-authored id), so the shared
// path keeps the segment==id rule for it, over the same bytes it always used.
let recipeRedirectUri: string
let segmentId: string
if (target.kind === 'client') {
segmentId = target.id
recipeRedirectUri = target.redirectUri
} else if (target.kind === 'remote-shared') {
segmentId = REMOTE_CALLBACK_CLIENT_SEGMENT
recipeRedirectUri = buildRemoteRedirectUri({ origin: target.origin, variant: 'shared' })
} else {
return BINDING_MISMATCH
}
if (claims.oauthClientId !== segmentId) return BINDING_MISMATCH
const recipeNamespace = claims.recipeNamespace
const recipeName = claims.recipeName
const oauthClientId = claims.oauthClientId
const userId = claims.userId
// `grantKind` comes ONLY from the signed state — the admin connect route is
// the sole minter of `service` states (SEC-1). For `service`, `userId` is the
// initiating admin: used for audit, never written to the grant.
const grantKind = claims.grantKind
// ─── 2. Look up the OAuthClientDef on the recipe ──────────────────────
let recipe: RecipeWithOAuthClients | null
try {
recipe = await deps.recipeReader.read(recipeName, recipeNamespace)
} catch (err) {
if (err instanceof RecipeNotFoundError) return { kind: 'recipe_not_found' }
throw err
}
if (!recipe) return { kind: 'recipe_not_found' }
const clientDecl = recipe.spec?.oauthClients?.find(c => c.id === oauthClientId)
if (!clientDecl) return { kind: 'unknown_oauth_client' }
// ─── 3-4. Read secrets + exchange code ────────────────────────────────
const exchanged = await exchangeAuthCode(
clientDecl,
recipeNamespace,
undefined,
{ code: input.code, state: input.state, redirectUri: recipeRedirectUri },
deps
)
if (exchanged.kind !== 'ok') return exchanged
const { provider, parsed } = exchanged
// ─── 5. Encrypt + persist ─────────────────────────────────────────────
// A `service` grant is recipe-owned: no `userId` column. A `user` grant
// belongs to the connecting end-user.
const backgroundRequested = claims.background
let backgroundEnabled = false
if (grantKind === 'service') {
await upsertOAuthGrant(deps.db, deps.encryptionKey, {
grantKind: 'service',
recipeNamespace: recipeNamespace,
recipeName: recipeName,
oauthClientId: oauthClientId,
provider,
accessToken: parsed.accessToken,
refreshToken: parsed.refreshToken,
accessTokenExpiresInSec: parsed.expiresIn,
})
} else {
await upsertOAuthGrant(deps.db, deps.encryptionKey, {
grantKind: 'user',
recipeNamespace: recipeNamespace,
recipeName: recipeName,
userId,
oauthClientId: oauthClientId,
provider,
accessToken: parsed.accessToken,
refreshToken: parsed.refreshToken,
accessTokenExpiresInSec: parsed.expiresIn,
})
// Background consent: only enable when the provider actually returned a
// refresh token — without one the broker could not sustain access. A plain
// (non-background) connect never touches the flag, so re-connecting does
// not silently revoke a prior background grant.
//
// NOTE — the reverse direction is also intentional: an interactive
// (non-background) reconnect intentionally preserves any existing
// background=true grant. The only downgrade paths are an explicit
// user-initiated revoke (DELETE /external/oauth/grants/…) or an admin
// force-revoke — both delete the row entirely.
if (backgroundRequested && parsed.refreshToken) {
await setUserGrantBackground(
deps.db,
{
recipeNamespace: recipeNamespace,
recipeName: recipeName,
userId,
oauthClientId: oauthClientId,
},
true
)
backgroundEnabled = true
}
}
return { kind: 'ok', provider, userId, grantKind, backgroundRequested, backgroundEnabled }
}
/**
* mcp-subject callback (U5). The signed state binds the initiating `userId` and
* the `mcpServerName`; the server's OAuth declaration + grant-scope routing are
* recovered fresh from the CR (authoritative), NOT from the state or any body.
*
* Access is re-checked BEFORE the code exchange, by flavor:
* - `grantScope='user'` → some Context the signed user reaches (directly or
* through an assigned agent) must still allowlist the server
* (`userServerAccessReader`); `spec.contextRef` is not consulted.
* - `grantScope='context'` → the signed user must be a member of the server's
* `spec.contextRef` (`userContextsReader`).
*
* Persistence connects to the U1 store primitives (no reimplementation):
* - `grantScope='user'` → `upsertOAuthGrant` `(mcpserver, ns, name, userId)`.
* - `grantScope='context'` → `bootstrapSharedOAuthGrant` `(mcpserver, ns, name,
* spec.contextRef)`, bootstrapper = the signed `userId` (first-consent wins;
* U6 governance). The Context comes from the AUTHORITATIVE `spec.contextRef`,
* never the state — so no context field is (or needs to be) bound into the
* mcp state.
*/
async function handleMcpOAuthCallback(
claims: OAuthMcpStateClaims,
input: CallbackInput,
deps: CallbackDeps
): Promise<CallbackResult> {
// Fail closed: an mcp state cannot be processed without an mcp reader wired.
if (!deps.mcpServerReader) return { kind: 'server_not_found' }
let subject: McpServerOAuthSubject | null
try {
subject = await deps.mcpServerReader.read(claims.mcpServerName)
} catch (err) {
if (err instanceof RecipeNotFoundError) return { kind: 'server_not_found' }
if (err instanceof RemoteOAuthSpecIncoherentError) {
return { kind: 'remote_oauth_spec_incoherent', reason: err.reason }
}
throw err
}
if (!subject) return { kind: 'server_not_found' }
// Defence in depth: the resolved server's declared oauthClient must match the
// client id bound in the signed state. Checked against `claims.oauthClientId`
// because on the remote callbacks the URL carries no client id at all.
if (subject.decl.id !== claims.oauthClientId) return BINDING_MISMATCH
// The callback URL must be the one this server's lane registers, in both
// directions: remote servers only ever register a remote URI, and the remote
// URIs waive the segment==id rule on the strength of checks (issuer, per-server
// binding) that only exist for remote servers. A baked/generic server that owns
// the reserved id, or a remote server reached through `/oauth-callback/<id>`,
// fails closed instead of leaving the AS's own redirect_uri comparison — which
// the generic lane cannot rely on — as the only binding.
const target = input.target
const remote = subject.decl.remote
const reachedOnRemoteUri = target.kind !== 'client'
if (reachedOnRemoteUri !== Boolean(remote)) return BINDING_MISMATCH
let redirectUri: string
if (target.kind === 'client') {
redirectUri = target.redirectUri
} else if (target.kind === 'remote-shared') {
const rejected = checkSharedCallbackIssuer(remote as RemoteClientRouting, input.iss)
if (rejected) return rejected
redirectUri = buildRemoteRedirectUri({ origin: target.origin, variant: 'shared' })
} else {
const perServer = await checkPerServerCallback(
subject,
claims.mcpServerName,
target,
input.iss,
deps.db
)
if (perServer.kind !== 'ok') return perServer
redirectUri = perServer.redirectUri
}
// ─── Access guards run BEFORE the token exchange (R3-L1) ──────────────────
// These guards depend only on the signed claims + the resolved subject
// (`subject.contextRef`, `claims.userId`, `claims.mcpServerName`) and the
// injected readers — never on the token. Running them first means a user who
// lost access during the ~600s mint→callback window fails here instead of
// first driving `exchangeAuthCode`, which burns the single-use auth-code
// against the provider and yields a real token only to discard it at a 403.
// The mint is still the primary gate; this re-check closes the window between
// the two. Persistence (below) stays after the exchange.
//
// `contextRef` is set iff this is a context-scoped grant that passed the
// membership guard; the persistence dispatch below keys off it (non-undefined
// ⇒ shared bootstrap), which also re-narrows it to `string` without a `!`.
let contextRef: string | undefined
if (subject.grantScope === 'context') {
// Shared identity — the coordinate is the server's authoritative contextRef.
// Without it there is nothing safe to key the grant on: fail closed.
if (!subject.contextRef) return { kind: 'server_missing_context' }
// Defence in depth: a shared grant lends a team-wide credential to every
// member of the Context, so the consenting (signed) user must be a member
// of that Context before we let them bootstrap it. Fail closed when the
// membership reader is unwired or the user is not a member — NEVER persist.
if (!deps.userContextsReader) return { kind: 'context_membership_denied' }
const { contextIds } = await deps.userContextsReader(claims.userId)
if (!contextIds.includes(subject.contextRef)) {
return { kind: 'context_membership_denied' }
}
contextRef = subject.contextRef
} else {
// Per-user identity — the grant serves every Context that enables the
// server, so access is "some Context the user reaches still allowlists
// it", the same rule the mint applied. Fail closed when the reader is
// unwired.
if (!deps.userServerAccessReader) return { kind: 'context_membership_denied' }
const enabled = await deps.userServerAccessReader(claims.userId, claims.mcpServerName)
if (!enabled) return { kind: 'context_membership_denied' }
}
const exchanged = await exchangeAuthCode(
subject.decl,
subject.namespace,
{ name: claims.mcpServerName, crUid: subject.crUid },
{ code: input.code, state: input.state, redirectUri },
deps
)
if (exchanged.kind !== 'ok') return exchanged
const { provider, parsed } = exchanged
if (contextRef !== undefined) {
// Context-scoped grant, membership already verified above.
await bootstrapSharedOAuthGrant(deps.db, deps.encryptionKey, {
ownerKind: 'mcpserver',
recipeNamespace: subject.namespace,
recipeName: claims.mcpServerName,
contextId: contextRef,
// Grant coordinate = the resolved client id (`oauth.id`), NEVER the URL: the
// remote callbacks carry no client id in it. `subject.decl.id ===
// claims.oauthClientId` (checked above), and it matches what the token broker
// keys by (`resolveServerOAuth`, D4).
oauthClientId: subject.decl.id,
// Bootstrapper = the signed initiator. Audit-only, first-wins on conflict.
bootstrappedByUserId: claims.userId,
provider,
accessToken: parsed.accessToken,
refreshToken: parsed.refreshToken,
accessTokenExpiresInSec: parsed.expiresIn,
// Seal to this installation so a same-name reinstall's teardown never purges it.
crUid: subject.crUid,
})
} else {
await upsertOAuthGrant(deps.db, deps.encryptionKey, {
grantKind: 'user',
ownerKind: 'mcpserver',
recipeNamespace: subject.namespace,
recipeName: claims.mcpServerName,
userId: claims.userId,
// See the shared-grant branch: coordinate is `oauth.id`, not the URL segment.
oauthClientId: subject.decl.id,
provider,
accessToken: parsed.accessToken,
refreshToken: parsed.refreshToken,
accessTokenExpiresInSec: parsed.expiresIn,
// Seal to this installation so a same-name reinstall's teardown never purges it.
crUid: subject.crUid,
})
}
return {
kind: 'ok',
provider,
userId: claims.userId,
grantKind: claims.grantKind,
// mcp interactive consent never captures background; the broker resolves
// tokens JIT against a live session.
backgroundRequested: false,
backgroundEnabled: false,
source: 'mcp',
// Authoritative — from the signed state, never a body param. Lets the
// desktop correlate which suspended task to resume.
mcpServerName: claims.mcpServerName,
}
}
/**
* RFC 9207 check of the shared remote callback. The shared URI carries no per-server
* binding, so `iss` is the only thing that attributes a code to the AS that minted it:
* pinned at discovery (`issForCallback`) and required to match exactly, before the
* single-use code is exchanged.
*
* Fails closed when the server pinned no issuer. The shared callback serves every
* remote server, so whether the check runs must not depend on the resolved AS's own
* metadata: a malicious installed AS that omitted `iss` could otherwise relay the user
* to an honest AS sharing this redirect/state/PKCE and have the honest code attributed
* to itself. Such a server belongs on its per-server URI instead.
*/
function checkSharedCallbackIssuer(
remote: RemoteClientRouting,
rawIss: unknown
): { kind: 'issuer_binding_required' } | { kind: 'issuer_mismatch' } | null {
const expectedIss = remote.issForCallback
if (typeof expectedIss !== 'string' || expectedIss.length === 0) {
return { kind: 'issuer_binding_required' }
}
// Anything but a string (repeated or bracketed parameter) reads as absent, and
// absent never matches a pinned issuer.
const iss = typeof rawIss === 'string' ? rawIss : undefined
return iss === expectedIss ? null : { kind: 'issuer_mismatch' }
}
type PerServerCheckResult =
| { kind: 'ok'; redirectUri: string }
| { kind: 'invalid_state'; reason: 'binding_mismatch' }
| { kind: 'issuer_mismatch' }
| { kind: 'callback_base_url_unconfigured' }
/**
* Checks of the per-server remote callback (`/remote/<serverName>[/<installNonce>]`),
* for an AS that does not return RFC 9207 `iss`. The server name was already matched
* to the signed state before the CR was read; here:
*
* 1. the CR must use the per-server variant — a server whose AS returns `iss` is
* bound by it on the shared callback and must never be reachable here;
* 2. the URI must be the one this installation registered: for DCR, the nonce of the
* row bound to this CR; for pre-registered, no nonce (the mode comes from the CR);
* 3. an `iss` the AS sends anyway must be the pinned issuer — but it cannot be
* required, which is why this variant exists;
* 4. the redirect URI for the exchange is rebuilt from the signed server name and the
* stored registration, not from the request path.
*/
async function checkPerServerCallback(
subject: McpServerOAuthSubject,
serverName: string,
target: Extract<CallbackTarget, { kind: 'remote-per-server' }>,
rawIss: unknown,
db: DbClient
): Promise<PerServerCheckResult> {
const remote = subject.decl.remote as RemoteClientRouting
if (remoteCallbackVariant(remote) !== 'per-server') return BINDING_MISMATCH
const registration = await resolvePerServerRegistration(db, subject, serverName)
if (!registration) return BINDING_MISMATCH
const expectedNonce = registration.mode === 'dcr' ? registration.installNonce : undefined
if (target.installNonce !== expectedNonce) return BINDING_MISMATCH
const issRejection = perServerIssRejection(rawIss, remote.issuer)
if (issRejection) {
// Only the server and the reason: the query also carries `code` and `state`,
// which the log redaction does not cover.
log.warn({ serverName, reason: issRejection }, 'per-server oauth callback iss rejected')
return { kind: 'issuer_mismatch' }
}
if (target.origin === null) return { kind: 'callback_base_url_unconfigured' }
try {
return {
kind: 'ok',
redirectUri: buildPerServerRedirectUri(target.origin, serverName, registration),
}
} catch (err) {
if (err instanceof InvalidRemoteRedirectUriInputError) {
return { kind: 'callback_base_url_unconfigured' }
}
throw err
}
}
/**
* Validate an `iss` the AS sent on a per-server callback. Absent is fine; a present
* value must be a single non-empty string equal to the pinned issuer. A repeated,
* bracketed or empty parameter is rejected rather than read as absent, so an attacker
* who can append to the query cannot turn a wrong issuer into "no issuer".
*/
function perServerIssRejection(
rawIss: unknown,
pinnedIssuer: string | undefined
): 'iss_malformed' | 'iss_mismatch' | null {
if (rawIss === undefined) return null
if (typeof rawIss !== 'string' || rawIss.length === 0) return 'iss_malformed'
return rawIss === pinnedIssuer ? null : 'iss_mismatch'
}
/** The authorization-code grant a callback redeems, with the redirect URI to replay. */
interface AuthCodeGrant {
code: string
state: string
redirectUri: string
}
type ExchangeAuthCodeResult =
| { kind: 'ok'; provider: GrantProviderLabel; parsed: ParsedTokenResponse }
| { kind: 'unknown_oauth_client' }
| { kind: 'secret_missing'; secret: string }
| { kind: 'unsupported_provider'; provider: string }
| { kind: 'provider_token_exchange_failed'; status: number; body: string }
| { kind: 'provider_response_invalid'; detail: string }
/**
* Read the (clientId, clientSecret) Secrets for a declaration, then exchange the
* auth code with the provider. Shared verbatim by the recipe and mcp callbacks
* so the token-exchange rule lives once (D4). The recipe path's observable
* result kinds and ordering are unchanged.
*/
async function exchangeAuthCode(
decl: OAuthClientDecl,
secretNamespace: string,
/** mcp-server owner (dynamic-client coordinate + installation); undefined for the recipe lane. */
owner: RemoteCredentialOwner | undefined,
grant: AuthCodeGrant,
deps: CallbackDeps
): Promise<ExchangeAuthCodeResult> {
// Remote lane (`source:'remote'`): discovery-derived endpoint ⇒ IP-pinned POST
// (DEC-17), public token client, credentials per `secretSource`. Byte-identical
// baked path is below (unchanged).
if (decl.remote) {
return exchangeRemoteAuthCode(decl, secretNamespace, owner, grant, deps)
}
// Generic self-hosted lane (`source:'generic'`): knob-configured request over
// the same IP-pinned POST (DEC-17). Credentials per `secretSource` (public or
// k8s-secret). Baked path is below (unchanged).
if (decl.generic) {
return exchangeGenericAuthCode(decl, secretNamespace, owner, grant, deps)
}
// Baked/recipe lane. clientIdRef is always present here (remote is the only
// decl that omits it); guard fail-closed rather than dereference undefined.
if (!decl.clientIdRef) {
return { kind: 'secret_missing', secret: `${decl.id}/client_id` }
}
const clientIdRef = decl.clientIdRef
let clientIdSecret: Record<string, string>
try {
clientIdSecret = await deps.secretReader.read(clientIdRef.name, secretNamespace)
} catch (err) {
if (err instanceof SecretNotFoundError) {
return { kind: 'secret_missing', secret: clientIdRef.name }
}
throw err
}
const clientId = clientIdSecret[clientIdRef.key]
if (!clientId) {
return { kind: 'secret_missing', secret: `${clientIdRef.name}/${clientIdRef.key}` }
}
// Public client (E-19.2): no clientSecretRef ⇒ skip the second Secret read and
// exchange without a client_secret. When a ref is present the confidential
// path is unchanged (same read, same fail-closed on missing Secret/key).
let clientSecret: string | undefined
if (decl.clientSecretRef) {
let clientSecretSecret: Record<string, string>
try {
clientSecretSecret = await deps.secretReader.read(decl.clientSecretRef.name, secretNamespace)
} catch (err) {
if (err instanceof SecretNotFoundError) {
return { kind: 'secret_missing', secret: decl.clientSecretRef.name }
}
throw err
}
clientSecret = clientSecretSecret[decl.clientSecretRef.key]
if (!clientSecret) {
return {
kind: 'secret_missing',
secret: `${decl.clientSecretRef.name}/${decl.clientSecretRef.key}`,
}
}
}
const provider = decl.provider
if (!isKnownOAuthProvider(provider)) {
return { kind: 'unsupported_provider', provider }
}
const adapter = getOAuthProviderAdapter(provider)
// PKCE (DEC-1): re-derive the verifier from the EXACT round-tripped state
// string — the same signed value the authorize URL derived its challenge from.
const codeVerifier = adapter.usesPkce
? deriveCodeVerifier(deps.stateSecret, grant.state)
: undefined
try {
// Build INSIDE the try: a confidential-only baked adapter (notion/monday/
// clickup) throws when handed a public (secret-less) decl. Keeping the build
// inside the catch turns that into a typed `provider_response_invalid` (fail
// closed, no token) instead of an opaque 500 — symmetric with tokenHelper's
// wrapped `buildRefreshRequest`.
const tokenRequest = adapter.buildTokenRequest({
code: grant.code,
clientId,
clientSecret,
redirectUri: grant.redirectUri,
codeVerifier,
})
const response = await deps.fetchFn(tokenRequest.url, {
method: tokenRequest.method,
headers: tokenRequest.headers,
body: tokenRequest.body,
signal: AbortSignal.timeout(deps.tokenRequestTimeoutMs ?? 15_000),
})
if (!response.ok) {
const body = await safeReadText(response)
return { kind: 'provider_token_exchange_failed', status: response.status, body }
}
const responseJson = await response.json()
return { kind: 'ok', provider, parsed: adapter.parseTokenResponse(responseJson) }
} catch (err) {
return { kind: 'provider_response_invalid', detail: (err as Error).message }
}
}
/**
* Remote-lane auth-code exchange (`source:'remote'`). Discovery-derived token
* endpoint ⇒ IP-pinned POST (DEC-17, closes the H2 DNS-rebinding TOCTOU). Public
* token client with credentials resolved per `secretSource`. Always PKCE S256.
*/
async function exchangeRemoteAuthCode(
decl: OAuthClientDecl,
secretNamespace: string,
owner: RemoteCredentialOwner | undefined,
grant: AuthCodeGrant,
deps: CallbackDeps
): Promise<ExchangeAuthCodeResult> {
// `decl.remote` presence is the branch guard in the caller.
const remote = decl.remote as RemoteClientRouting
const credResult = await resolveRemoteClientCredential(decl, secretNamespace, owner, deps)
if (!credResult.ok) return { kind: 'secret_missing', secret: credResult.secret }
// PKCE (DEC-1 / §6 #3): the remote lane is ALWAYS S256 — re-derive the verifier
// from the exact round-tripped state, same as the baked PKCE adapters.
const codeVerifier = deriveCodeVerifier(deps.stateSecret, grant.state)
const tokenRequest = buildRemoteTokenRequest(
remote.tokenEndpoint,
{
code: grant.code,
clientId: credResult.cred.clientId,
clientSecret: credResult.cred.clientSecret,
redirectUri: grant.redirectUri,
codeVerifier,
},
remote.resource,
// The authorize request's `scope` travels through the browser and can be edited;
// without `scope` on the redemption Entra issues the token for whatever that leg
// asked for, so the CR's scopes are what pin the audience here.
remoteWireForProfile(remote.asProfile).scopeOnTokenRequests ? decl.scopes : undefined
)
const posted = await postRemoteTokenForm(
remote.tokenEndpoint,
'spec.oauth.tokenEndpoint',
tokenRequest,
{
resolveDns: deps.resolveDns,
pinnedTransport: deps.pinnedTransport,
timeoutMs: deps.tokenRequestTimeoutMs,
}
)
if (!posted.ok) {
if (typeof posted.status === 'number') {
return { kind: 'provider_token_exchange_failed', status: posted.status, body: posted.detail }
}
return { kind: 'provider_response_invalid', detail: posted.detail }
}
try {
return {
kind: 'ok',
provider: 'remote',
parsed: parseRemoteTokenResponse(JSON.parse(posted.bodyText)),
}
} catch (err) {
return { kind: 'provider_response_invalid', detail: (err as Error).message }
}
}
/**
* Generic-lane auth-code exchange (`source:'generic'`, DEC-28). Operator-pinned
* token endpoint ⇒ IP-pinned POST (DEC-17). The request is composed from the CR
* knobs via `buildAdapterFromConfig`; credentials come from `secretSource`
* (public ⇒ no `client_secret`; k8s-secret ⇒ both read from the named Secret).
* PKCE is gated on the `usePkce` knob.
*/
async function exchangeGenericAuthCode(
decl: OAuthClientDecl,
secretNamespace: string,
owner: RemoteCredentialOwner | undefined,
grant: AuthCodeGrant,
deps: CallbackDeps
): Promise<ExchangeAuthCodeResult> {
// `decl.generic` presence is the branch guard in the caller.
const generic = decl.generic as GenericClientRouting
const credResult = await resolveRemoteClientCredential(decl, secretNamespace, owner, deps)
if (!credResult.ok) return { kind: 'secret_missing', secret: credResult.secret }
const adapter = buildAdapterFromConfig(generic)
// PKCE gated on the knob: re-derive the verifier from the exact round-tripped
// state (the authorize URL derived its challenge from the same value).
const codeVerifier = generic.usePkce
? deriveCodeVerifier(deps.stateSecret, grant.state)
: undefined
let tokenRequest: ReturnType<typeof adapter.buildTokenRequest>
try {
// The build can throw (e.g. tokenAuthMethod=basic on a secret-less client) —
// turn that into a typed fail-closed result, never an opaque 500.
tokenRequest = adapter.buildTokenRequest({
code: grant.code,
clientId: credResult.cred.clientId,
clientSecret: credResult.cred.clientSecret,
redirectUri: grant.redirectUri,
codeVerifier,
})
} catch (err) {
return { kind: 'provider_response_invalid', detail: (err as Error).message }
}
const posted = await postRemoteTokenForm(
tokenRequest.url,
'spec.oauth.tokenEndpoint',
tokenRequest,
{
resolveDns: deps.resolveDns,
pinnedTransport: deps.pinnedTransport,
timeoutMs: deps.tokenRequestTimeoutMs,
}
)
if (!posted.ok) {
if (typeof posted.status === 'number') {
return { kind: 'provider_token_exchange_failed', status: posted.status, body: posted.detail }
}
return { kind: 'provider_response_invalid', detail: posted.detail }
}
try {
return {
kind: 'ok',
provider: 'generic',
parsed: adapter.parseTokenResponse(JSON.parse(posted.bodyText)),
}
} catch (err) {
return { kind: 'provider_response_invalid', detail: (err as Error).message }
}
}
/** Resolved remote client credentials for a token/refresh POST. */
export interface RemoteClientCredential {
clientId: string
/** Absent for a public client. */
clientSecret?: string
}
export type RemoteCredentialResult =
| { ok: true; cred: RemoteClientCredential }
| { ok: false; secret: string }
/** The McpServer whose `dynamic_clients` row holds a DCR client's credentials. */
export interface RemoteCredentialOwner {
/** McpServer name — the `dynamic_clients` coordinate. */
name: string
/** metadata.uid of the live CR; undefined when the reader saw none. */
crUid: string | undefined
}
/**
* Resolve the remote client's `(clientId, clientSecret)` from the `secretSource`
* discriminator (DEC-18) — the SINGLE place the three remote secret sources are
* read, shared by the exchange (here) and the refresh (`tokenHelper.ts`) so the
* two never drift (D4). Never logs or returns secret material on the error path
* (names only). `owner` locates the `dynamic_clients` row (DCR only).
*
* A DCR row is used only when it is not yet bound (`cr_uid` NULL — pending
* between the CR create and the bind, or legacy) or bound to `owner.crUid`. A row
* bound to another uid belongs to a gone installation of the same name and is
* treated as absent. The check lives here rather than in `getDynamicClient`
* because the install saga must still see every row to classify and reclaim it.
*/
export async function resolveRemoteClientCredential(
decl: OAuthClientDecl,
secretNamespace: string,
owner: RemoteCredentialOwner | undefined,
deps: { db: DbClient; encryptionKey: Buffer; secretReader: SecretReader }
): Promise<RemoteCredentialResult> {
const source = decl.secretSource
// A remote decl always carries a secretSource; fail closed if it somehow does not.
if (!source) return { ok: false, secret: `${decl.id}/secret_source_missing` }
if (source.kind === 'public') {
// CIMD/DCR-public: the public client_id IS `oauth.id`; no secret.
return { ok: true, cred: { clientId: decl.id } }
}
if (source.kind === 'dcr-store') {
if (!owner) return { ok: false, secret: `dynamic_clients/${decl.id}` }
const row = await getDynamicClient(deps.db, deps.encryptionKey, {
serverNamespace: secretNamespace,
serverName: owner.name,
})
if (!row || (row.crUid !== undefined && row.crUid !== owner.crUid)) {
return { ok: false, secret: `dynamic_clients/${owner.name}` }
}
if (!row.clientSecret) {
return { ok: false, secret: `dynamic_clients/${owner.name}/client_secret` }
}
return { ok: true, cred: { clientId: row.clientId, clientSecret: row.clientSecret } }
}
// k8s-secret: pre-registered confidential — read both keys from the named Secret.
const { clientIdRef, clientSecretRef } = source
let idSecret: Record<string, string>
try {
idSecret = await deps.secretReader.read(clientIdRef.name, secretNamespace)
} catch (err) {
if (err instanceof SecretNotFoundError) return { ok: false, secret: clientIdRef.name }
throw err
}
const clientId = idSecret[clientIdRef.key]
if (!clientId) return { ok: false, secret: `${clientIdRef.name}/${clientIdRef.key}` }
let secSecret: Record<string, string>
try {
secSecret = await deps.secretReader.read(clientSecretRef.name, secretNamespace)
} catch (err) {
if (err instanceof SecretNotFoundError) return { ok: false, secret: clientSecretRef.name }
throw err
}
const clientSecret = secSecret[clientSecretRef.key]
if (!clientSecret) return { ok: false, secret: `${clientSecretRef.name}/${clientSecretRef.key}` }
return { ok: true, cred: { clientId, clientSecret } }
}
export type RemotePostResult =
| { ok: true; bodyText: string }
| { ok: false; status?: number; detail: string }
/**
* POST a token/refresh request to a discovery-derived (remote) or operator-pinned
* (generic) endpoint through the IP-pinned `pinnedFetch` (DEC-17). Body-agnostic:
* the builder owns the `content-type` (`application/x-www-form-urlencoded` for the
* remote/baked and generic form path, `application/json` for a generic
* `tokenRequestFormat:'json'` server); this helper only adds `content-length` (the
* pinned `node:https` transport needs an explicit length rather than chunked) from
* `Buffer.byteLength` of the builder's body. Any pin-level
* failure (kernel-rejected, transport, non-identity encoding) is a fail-closed
* `ok:false` with a NAME-only detail — never secret material. Shared by exchange
* + refresh (D4).
*/
export async function postRemoteTokenForm(
url: string,
field: string,
tokenRequest: { headers: Record<string, string>; body: string },
deps: { resolveDns?: DnsResolver; pinnedTransport?: PinnedTransport; timeoutMs?: number }
): Promise<RemotePostResult> {
const headers = {
...tokenRequest.headers,
'content-length': String(Buffer.byteLength(tokenRequest.body)),
}
const result = await pinnedFetch(url, field, {
method: 'POST',
headers,
body: tokenRequest.body,
resolveDns: deps.resolveDns,
transport: deps.pinnedTransport,
timeoutMs: deps.timeoutMs ?? 15_000,
})
if (!result.ok) return { ok: false, detail: result.error.kind }
const { status, bodyText } = result.response
if (status < 200 || status >= 300) return { ok: false, status, detail: bodyText.slice(0, 2000) }
return { ok: true, bodyText }
}
// ─── helpers ──────────────────────────────────────────────────────────────
async function safeReadText(response: Response): Promise<string> {
try {
return (await response.text()).slice(0, 2000)
} catch {
return ''
}
}
// Re-export for the route layer's convenience.
export { signOAuthState }